# iEvo Pipeline Context

> Auto-generated by `ievo init`. Auto-updated when CLI version changes.
> Do not edit manually — changes will be overwritten.

## Directory Structure

```
.ievo/
├── version           # CLI version that last updated this project
├── IEVO.md           # This file — pipeline context overlay
├── config.yaml       # Project settings
├── backlog/          # Raw ideas (IDEA-xxx) and research proposals (PROP-xxx)
├── spec/             # Requirements (REQ-xxx), questions (Q-xxx), changes (CR-xxx)
│   ├── SPEC_INDEX.md # Registry of all specs + statuses
│   ├── PRIORITY.md   # Selection algorithm
│   ├── requirements/ # REQ-NNN-<slug>.md
│   ├── questions/    # Q-NNN-<slug>.md, Q-NNN-arch.md (escalations)
│   └── changes/      # CR-NNN-<slug>.md
├── plans/            # Implementation plans (PLAN-REQ-xxx)
├── reports/          # Verification results
│   ├── review/       # REVIEW-REQ-xxx.md (code review)
│   ├── qa/           # QA-REQ-xxx.md (QA testing)
│   ├── acceptance/   # ACC-REQ-xxx.md, ACC-REQ-xxx-rN.md (revisions)
│   ├── tech-lead/    # AUDIT-YYYY-MM-DD.md (infrastructure audits)
│   └── defrag/       # DEFRAG-YYYY-MM-DD.md
├── evolution/        # Per-agent local evolution overlays
│   └── <agent>.md    # Project-specific rules learned by each agent
└── memory/           # Shared project memory
    ├── CONTEXT.md    # Project state, entities, architecture
    ├── DECISIONS.md  # Append-only decision log
    ├── VOCABULARY.md # Domain terms and definitions
    ├── HISTORY.md    # Session index with statuses
    └── sessions/     # Per-session plan + log
        └── NNN/
            ├── plan.md
            └── log.md
```

## Document Lifecycle

```
Session starts → memory/sessions/NNN/plan.md (intent, goals, scope)
  │
  │  Idea → backlog/IDEA-xxx.md
  │    ↓ (Sprint planning — human selects)
  │  Spec Writer → spec/requirements/REQ-xxx.md
  │    ↓ (ambiguity?)
  │    → spec/questions/Q-xxx.md (blocks REQ until resolved)
  │    ↓
  │  Architect → plans/PLAN-REQ-xxx.md
  │    ↓ (plan broken?)
  │  Coder → spec/questions/Q-xxx-arch.md (escalation to Architect)
  │    ↓
  │  Coder → src/ + tests/
  │    ↓
  │  Code Reviewer → reports/review/REVIEW-REQ-xxx.md
  │    ↓ NEEDS CHANGES → Coder fixes → re-review
  │    ↓ PASS
  │  QA → reports/qa/QA-REQ-xxx.md (+ additional tests)
  │    ↓ BUGS FOUND → Q-file → Coder fixes → re-QA
  │    ↓ PASS
  │  Acceptance → reports/acceptance/ACC-REQ-xxx.md
  │    ↓ FAIL → Coder fixes → ACC-REQ-xxx-r2.md (revision)
  │    ↓ PASS → status = implemented
  │    ↓
  │  Docs → docs/, README.md, CLAUDE.md
  │
Session ends → memory/sessions/NNN/log.md (reality, artifacts, commits)
            → memory/HISTORY.md updated
```

## Requirement Statuses

```
draft → ready → in-progress → review → implemented | blocked | removed
```

- `draft` — has ambiguities, not ready for implementation
- `ready` — fully specified, agent can pick it up
- `blocked` — agent found ambiguities, questions filed
- `in-progress` — agent is currently implementing
- `review` — implementation complete, in code review / QA / acceptance pipeline
- `implemented` — all acceptance criteria met, all tests passing
- `removed` — deleted via Change Request

## Sessions

A **session** is one episodic work unit — one sitting, one goal. Sessions wrap pipeline work and track what happened.

### Structure

```
memory/sessions/NNN/
├── plan.md   # Intent — written BEFORE work starts
└── log.md    # Reality — written during and after work
```

- **`plan.md`** — goals, phases, decisions to make, files to create/modify. This is the recovery document — if a session crashes mid-work, the plan enables another agent to continue.
- **`log.md`** — what was actually built, artifacts created/modified, commits, errors encountered, pending items. Updated incrementally as work progresses.

### Session statuses

```
planned → in_progress → completed
```

### HISTORY.md format

`memory/HISTORY.md` is the lightweight index of all sessions:

```markdown
| # | Date | Topic | Status | Key outcome |
|---|------|-------|--------|-------------|
| [001](sessions/001/) | 2026-02-28 | Project bootstrap | completed | Architecture decided, first 3 REQs |
| [002](sessions/002/) | 2026-03-01 | Auth implementation | in_progress | REQ-001 through REQ-005 |
```

### Rules

- **Plan first**: write `plan.md` BEFORE starting implementation. No plan = no recovery if context is lost.
- **Incremental updates**: update `plan.md` and `log.md` after each phase completes — don't wait until session end.
- **Sequential numbering**: 001, 002, 003... Never skip numbers.
- **One session = one goal**: if the goal shifts significantly, start a new session.

## Cross-Linking

How documents reference each other across the `.ievo/` structure.

### Sessions → Artifacts (strong, required)

`log.md` MUST list all artifacts created or modified during the session:

```markdown
## What was done
- Created: REQ-001, REQ-002, REQ-003
- Approved: PLAN-REQ-001
- Passed: ACC-REQ-001
- Decisions: D-007, D-008
- Commits: abc1234, def5678
```

### Artifacts → Sessions (weak, optional)

REQ, PLAN, and ACC files do NOT require session references. Artifacts are autonomous — they survive across multiple sessions and can be referenced independently. An optional `Created in: Session NNN` note is fine but never required.

### DECISIONS.md — the cross-session decision log

Decisions are referenced by ID (`D-NNN`) from any document:

```markdown
## D-007: Use PostgreSQL for persistence
**Date:** 2026-02-28
**Session:** 001
**Context:** Evaluated SQLite vs PostgreSQL vs MongoDB
**Decision:** PostgreSQL — team expertise, ACID guarantees
**Affects:** REQ-003, REQ-004
```

Decisions persist across sessions. When an agent needs to know WHY something was decided, it reads DECISIONS.md — not old session logs.

### Summary

| Direction | Strength | Example |
|-----------|----------|---------|
| Session → Artifacts | **Strong** | `log.md` lists REQ-001, PLAN-REQ-001, ACC-REQ-001 |
| Artifacts → Sessions | Weak | Optional "Created in Session 001" metadata |
| Any doc → Decisions | **Strong** | "Per D-007, we use PostgreSQL" |
| HISTORY.md → Sessions | **Strong** | Links to `sessions/NNN/` directories |

## Evolution Overlay

Each agent accumulates project-specific lessons in `.ievo/evolution/<agent>.md`. These files are **local to the project** — they survive agent updates from the marketplace.

### How it works

```
Agent makes a mistake → /evo skill → logs lesson to .ievo/evolution/<agent>.md
Evolution agent picks it up → creates issue in ievo-ai/curator (evolution_log label)
Curator/Eva review → if valuable, update agent in marketplace
```

### File format

```markdown
# Evolution: <agent-name>

## YYYY-MM-DD: <brief title>

**Type:** <spec-error|plan-error|code-error|test-error|process-error>
**What happened:** <1-2 sentences>
**Root cause:** <why it happened>
**Lesson:** <actionable rule to prevent recurrence>
```

### Rules

- **Overlay, not override.** Evolution files ADD rules — they never contradict the agent's base instructions.
- **Project-specific only.** Generic lessons go to the curator (via Evolution agent issues). Only rules that apply specifically to THIS project belong here.
- **Append-only.** Never delete entries — they are the learning history.
- **Survives updates.** When HR agent updates an agent from marketplace, evolution overlays are preserved.

## Naming Conventions

| Type | Pattern | Location |
|------|---------|----------|
| Requirement | `REQ-NNN-<slug>.md` | `.ievo/spec/requirements/` |
| Question | `Q-NNN-<slug>.md` | `.ievo/spec/questions/` |
| Escalation | `Q-NNN-arch.md` | `.ievo/spec/questions/` |
| Change Request | `CR-NNN-<slug>.md` | `.ievo/spec/changes/` |
| Plan | `PLAN-REQ-NNN.md` | `.ievo/plans/` |
| Acceptance Report | `ACC-REQ-NNN.md` | `.ievo/reports/acceptance/` |
| Revision | `ACC-REQ-NNN-rN.md` | `.ievo/reports/acceptance/` |
| Code Review | `REVIEW-REQ-NNN.md` | `.ievo/reports/review/` |
| QA Report | `QA-REQ-NNN.md` | `.ievo/reports/qa/` |
| Tech Lead Audit | `AUDIT-YYYY-MM-DD.md` | `.ievo/reports/tech-lead/` |
| Defrag Report | `DEFRAG-YYYY-MM-DD.md` | `.ievo/reports/defrag/` |
| Idea | `IDEA-NNN-<slug>.md` | `.ievo/backlog/` |
| Proposal | `PROP-NNN-<slug>.md` | `.ievo/backlog/` |
| Session plan | `plan.md` | `.ievo/memory/sessions/NNN/` |
| Session log | `log.md` | `.ievo/memory/sessions/NNN/` |
| Session index | `HISTORY.md` | `.ievo/memory/` |
| Decision | `D-NNN` (entry in file) | `.ievo/memory/DECISIONS.md` |
| Evolution overlay | `<agent>.md` | `.ievo/evolution/` |

## Pipeline Rules

- **15-minute rule**: Architect decomposes every task to ≤15 minutes of agent work
- **Sprint = agreed REQs**: human approves what enters sprint. Scope is frozen once agreed
- **Backlog = pre-spec**: raw ideas and proposals, not yet refined into requirements
- **Acceptance loop**: FAIL → Coder fixes → Acceptance re-verifies. No shortcuts
- **Coder escalation**: plan broken → `Q-xxx-arch.md` → Architect revises plan
- **Evolution gates**: Evolution agent observes every pipeline transition (post-spec, post-plan, post-implementation, post-acceptance)
- **Atomic REQs**: each requirement has 3-7 testable acceptance criteria
- **Priority scoring**: see `PRIORITY.md` for formula. Agents auto-select highest-value task
- **Commit authorship**: all agent commits use `Co-Authored-By: iEVO <agent-name> <noreply@ievo.ai>` — never use the default Claude Code footer
- **Three-layer separation**: `CLAUDE.md` = project context (tech stack, architecture). `.ievo/IEVO.md` = pipeline conventions. `agents/*.md` = agent rules. NEVER write pipeline rules or evolution lessons to `CLAUDE.md` — they belong in agent `.md` files or `.ievo/evolution/`

## Agent Pipeline

```
Backlog → Spec Writer → [Evolution] → Sprint → Architect → [Evolution]
  → Coder → [Evolution] → Code Reviewer → QA → Acceptance → [Evolution] → Docs → Done

Tech Lead — runs post-init, periodically, or on demand (infrastructure audits)
```

### Agent Discovery

Your project has pipeline agents installed in `.claude/agents/`. To see available agents:

```bash
ls .claude/agents/*.md
```

Read each agent's `.md` file to understand its role, tools, and when to delegate to it. **Always delegate pipeline tasks to the appropriate agent** instead of doing everything yourself:

| Task | Agent |
|------|-------|
| Break down features into requirements | `spec-writer` |
| Create implementation plans | `architect` |
| Write code and tests | `coder` |
| Review code quality (docstrings, types, patterns) | `code-reviewer` |
| Write additional test scenarios (edge cases, E2E) | `qa` |
| Verify acceptance criteria | `acceptance` |
| Update documentation | `docs` |
| Manage project tooling & CI | `tech-lead` |
| Log lessons from mistakes | `evolution` |
| Research external tools/APIs | `researcher` |
| Audit consistency across pipeline | `defrag` |
| Manage agent team | `hr` |

Agent-specific instructions are in each agent's `.md` file.
