# 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
├── tasks/            # All work items — unified lifecycle
│   ├── _index.csv    # Generated cache for fast grep (id,title,type,status,priority,deps,pr,updated)
│   └── NNN/          # Task directory (sequential ID: 001, 002, ...)
│       ├── spec.md   # Single file: frontmatter + context + ACs + plan + questions + history
│       ├── reports/   # qa.md, review.md, acceptance.md (written by review agents)
│       └── subtasks/  # Architect-created work units, assigned by team-lead
│           └── NN/
│               └── spec.md  # Subtask: frontmatter (parent, status, assigned, deps) + what/tests/files + history
├── sessions/         # Work sessions (cross-task)
│   ├── _index.csv    # Session index (id,date,agent,tasks,status,summary)
│   └── NNN/
│       ├── plan.md   # Intent — written BEFORE work starts
│       └── log.md    # Reality — written during and after work
├── evolution/        # Evolution log + overlays (see EVOLUTION.md)
│   ├── LOG.md        # Append-only findings journal (write-only)
│   ├── KERNEL.md     # Kernel overlay — pipeline-level rules (read by all agents)
│   └── agents/       # Per-agent overlays
│       └── <agent>.md
└── memory/           # Shared project memory
    ├── CONTEXT.md    # Project state, entities, architecture
    ├── DECISIONS.md  # Append-only decision log
    ├── VOCABULARY.md # Domain terms and definitions
    └── HISTORY.md    # Legacy session index (migrating to sessions/_index.csv)
```

## Task Statuses

```
idea → ready → planned → plan-approved → in_progress → review → done | blocked
                                              ↑            |
                                              └── reject ──┘
```

- `idea` — raw thought, no acceptance criteria yet
- `ready` — spec written, user approved, waiting for architect
- `planned` — ## Plan section written in spec.md, waiting for architect-reviewer
- `plan-approved` — plan reviewed and approved, team-lead can implement
- `in_progress` — draft PR open, internal pipeline running (direction → code → QA → acceptance). CI does NOT trigger
- `review` — acceptance PASS, PR marked ready for review, CI triggers, waiting for user
- `done` — user approved and merged
- `blocked` — waiting on question answer or dependency

**Reject flow:** user rejects PR → PR back to draft → status `in_progress` → team-lead fixes → acceptance re-verifies → PR ready for review again → status `review`

## Sessions

A **session** is one episodic work unit — one sitting, one goal. Sessions can span multiple tasks.

### Structure

```
.ievo/sessions/
├── _index.csv    # id,date,agent,tasks,status,summary
└── 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. Recovery document.
- **`log.md`** — what was actually built, artifacts created/modified, commits, errors.

### Session statuses

```
planned → in_progress → completed
```

### 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.
- **Record experience in real time**: when something is learned — a mistake, a discovery, a pattern — append it immediately to `.ievo/EXP.md`. Don't wait for session end (session may never end cleanly). Write as it happens. This is raw experience — unprocessed, unfiltered. Format:
  ```
  ## YYYY-MM-DD: <short title>
  - **What worked:** <pattern/approach that proved effective — and WHY>
  - **What didn't:** <approach that failed or caused rework — and WHY>
  - **Discovered:** <new insight, tool, convention worth remembering>
  - **For next time:** <concrete action to take in similar situations>
  ```
  Not every entry needs all four fields — write what's relevant.

## Cross-Linking

### Sessions → Tasks (strong, required)

`log.md` MUST list tasks worked on:

```markdown
## What was done
- Tasks: 001 (spec → ready), 002 (arch written), 003 (idea captured)
- Decisions: D-007, D-008
- Commits: abc1234, def5678
```

Experience is logged in real time to `.ievo/EXP.md`, not in session logs.

### Tasks → Sessions (weak, via frontmatter)

`spec.md` frontmatter has `created_session: "NNN"` — optional link to originating session.

### 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:** tasks 003, 004
```

### Summary

| Direction | Strength | Example |
|-----------|----------|---------|
| Session → Tasks | **Strong** | `log.md` lists tasks worked on |
| Tasks → Sessions | Weak | `created_session` in frontmatter |
| Any doc → Decisions | **Strong** | "Per D-007, we use PostgreSQL" |
| `_index.csv` → Tasks | **Strong** | Generated from `spec.md` frontmatter |

## Evolution Overlay

Project-specific lessons accumulate in `.ievo/evolution/` and are loaded as context at each session start. The evolution system has three components:

- **`LOG.md`** — append-only findings journal written by the Evolution agent. Write-only: agents do not load this as context.
- **`KERNEL.md`** — kernel overlay for pipeline-level lessons (naming conventions, document lifecycle, cross-agent coordination). Read by all agents at session start.
- **`agents/<agent>.md`** — per-agent overlay for agent-specific lessons. Read by that agent at session start.

```
Finding in agent behavior        → LOG.md + agents/<agent>.md
Finding in pipeline conventions  → LOG.md + KERNEL.md
All findings                     → curator GitHub issue
```

Read `EVOLUTION.md` for full convention — entry formats, routing rules, context loading template.

## Naming Conventions

| Type | Pattern | Location |
|------|---------|----------|
| Task (all-in-one) | `spec.md` | `.ievo/tasks/NNN/` |
| Subtask (all-in-one) | `spec.md` | `.ievo/tasks/NNN/subtasks/NN/` |
| QA report | `qa.md` | `.ievo/tasks/NNN/reports/` |
| Code review | `review.md` | `.ievo/tasks/NNN/reports/` |
| Acceptance report | `acceptance.md` | `.ievo/tasks/NNN/reports/` |
| Acceptance revision | `acceptance-rN.md` | `.ievo/tasks/NNN/reports/` |
| Task index | `_index.csv` | `.ievo/tasks/` |
| Session plan | `plan.md` | `.ievo/sessions/NNN/` |
| Session log | `log.md` | `.ievo/sessions/NNN/` |
| Session index | `_index.csv` | `.ievo/sessions/` |
| Decision | `D-NNN` (entry in file) | `.ievo/memory/DECISIONS.md` |
| Experience log | `EXP.md` | `.ievo/` |
| Evolution log | `LOG.md` | `.ievo/evolution/` |
| Kernel overlay | `KERNEL.md` | `.ievo/evolution/` |
| Agent overlay | `<agent>.md` | `.ievo/evolution/agents/` |

## Instincts

Core behaviors hardwired into every session. Not rules — reflexes. No agent references, no role names. These apply to everything the kernel touches.

- **Challenge first, execute second.** Before acting on any input — try to break it. What's wrong? What's missing? What contradicts what you already know? Input that survives scrutiny is worth executing. Input that doesn't must be returned with questions. Accepting flawed input and producing perfect output from it is a failure.
- **Curious mind.** Research the domain before making any design decision. How do established projects solve this? What are the conventions? What packages exist? Use WebSearch, read docs, study real examples. 5 minutes of research costs nothing. Replanning after a preventable flaw costs everything.
- **Ecosystem awareness.** Before proposing any command, flag, pattern, or tool — check how it's already done in this ecosystem (other repos in the same org, standard toolchain). If the answer already exists, don't reinvent it. If a name collides with standard tooling, reject it. One action — reading the closest analog — catches most design flaws.
- **Healthy self-criticism.** Question your own output before presenting it. "Is this actually right? Did I check, or did I assume?" Not paralysis — a quick sanity pass. Catch your own mistakes before someone else does. But don't spiral — one honest review is enough.
- **Seek consensus, not compliance.** Do not blindly agree with the user. If the user's direction seems wrong — say so, explain why, propose an alternative. The goal is the best outcome, not the fastest "yes". Push back respectfully, find consensus. A "yes" that leads to a bad design is worse than a constructive disagreement.
- **Hold everyone accountable.** Agents forget, skip steps, take shortcuts, and produce sloppy output. This is their nature. Don't trust — verify. When reviewing anyone's output, assume something was missed. Check that rules were followed, that evolution overlays were read, that previous feedback was applied. If something was supposed to change and didn't — call it out immediately. A gentle reminder costs nothing; undetected sloppiness compounds into disasters.
- **Best practices by default.** Always use established best practices — don't wait to be asked. When writing code, designing systems, or making decisions — apply industry standards and proven patterns. When a best practice is missing in the project — proactively propose adopting it. The goal is not just "working" but "working well". A solution that ignores known best practices is a solution that creates future debt.
- **Flag tech debt on sight.** When reading code for any reason — planning, reviewing, implementing — and you see something wrong (hardcoded templates, wrong project layout, missing abstractions, copy-paste) — don't ignore it just because it's "not in scope". Create a task immediately: `type: refactor`, `status: ready`, with concrete description of what's wrong and what to do. Not an idea — a task with clear scope. Technical debt that nobody writes down grows silently until it's unmanageable. Fixing now is always cheaper than fixing later.
- **Never stop learning.** Treat every session as a chance to get better. Actively seek new information — better tools, newer patterns, smarter approaches. When something fails, extract the lesson. When something works, understand why. Evolution is not a phase — it's the default state. A system that stops learning starts decaying.

## Pipeline Rules

- **Language**: Communicate with the user in their language. All artifacts (specs, plans, reports, code, comments, documentation) are written in English
- **15-minute rule**: decompose every task to ≤15 minutes of 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 → fix → re-verify. No shortcuts
- **Escalate when reality doesn't match plan**: if implementation reveals the plan doesn't fit the actual code — STOP, return to planning with specific issues. The one who sees real code must push back on the one who designed from spec. Write issues to `## Questions` in spec.md
- **Docs live in repo**: each repo maintains a `docs/` directory for architecture, guides, and reference
- **Evolution gates**: observe every pipeline transition (post-spec, post-plan, post-implementation, post-acceptance)
- **Atomic REQs**: each requirement has 3-7 testable acceptance criteria
- **Priority scoring**: `score = (priority_weight×3) + (blocking_count×2) + (dependency_met×1) - (complexity×0.5) - (open_questions×5)`. Weights: critical=10, high=7, medium=5, low=3. Rules: CRs before REQs → filter `ready` + deps `implemented` → score → tiebreak by lower REQ number
- **Commit authorship**: all agent commits use `Co-Authored-By: iEVO <agent-name> <noreply@ievo.ai>` — never use the default Claude Code footer (`Co-Authored-By: Claude ...`)
- **PR branding**: every PR description ends with `🧬 Evolved with [iEVO](https://github.com/ievo-ai)` — replaces the default `🤖 Generated with Claude Code` footer
- **Merge strategy**: always use merge commit (`gh pr merge --merge --delete-branch`), never squash. Squash hides per-subtask commits and authorship. Each subtask commit = traceable unit of work. `--delete-branch` cleans up the remote branch after merge — no stale branches
- **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`

## Best Practices

Proven practices derived from real sessions — apply these by default.

> New practices discovered during sessions go to `.ievo/evolution/KERNEL.md`, not here. See `EVOLUTION.md` for the full evolution convention.

### Requirements & Backlog

- **Discussion starts as idea**: every new requirement begins as a task with `status: idea` via `/idea`, never directly as a ready spec. The spec.md is a living document — it grows through research, interview, and architect assessment until spec-writer promotes it to `ready` with user approval.
- **Always record WHY**: every decision made during discussion must be logged with context — what options were considered, why this one was chosen, who decided. Log to IDEA file or `.ievo/memory/DECISIONS.md`. Without a decision log, context is lost within days and no one remembers why things were done a certain way.
- **Backlog revival requires full context reload**: when an idea returns from backlog after weeks, always load its discussion log and run a context refresh — what has changed since then, is the original approach still valid?
- **New requirements during discussion → new task**: if a new requirement emerges during spec elicitation, capture it as a separate task (`/idea`) immediately. Do not graft it onto the current task's scope without explicit user approval.

### Research

- **Verify before trusting research findings**: always check that GitHub repos, star counts, and project names found in research are real. Researchers can hallucinate project names. Apply the "can I open this URL?" test. Flag unverified items with `⚠️ TODO: verify`.
- **Study adjacent ecosystems**: before building something, check if OpenClaw, IronClaw, Lobster, or similar projects already solved it. Reference implementations save months.
- **Persist research findings in `.ievo/research/`**: raw research output belongs in `.ievo/research/YYYY-MM-DD-<topic>.md`, not in task specs or session logs. Task specs reference research files — they don't contain raw findings. Update `INDEX.md` in `.ievo/research/` after every new research file. Format: `findings / comparing A vs B and why / conclusion / final decision and why`.

### Pipeline Design

- **Deterministic engine over LLM routing**: pipeline stage transitions must be driven by a deterministic workflow engine (YAML state machine), not by LLMs deciding what to do next. LLMs are unreliable routers — they misinterpret iteration counts and forget to signal transitions.
- **Hard gates between stages**: every pipeline stage has explicit entry conditions and exit artifacts. The next stage agent checks entry conditions before starting. No stage can claim completion without producing its required artifact.
- **Judge/gate agent is non-bypassable**: the judge that promotes a REQ from draft to ready cannot be skipped. If a stage's artifact is missing or invalid, the pipeline stops — it does not proceed with assumptions.

### Security

- **LLM sees credential names, never values**: inject only the list of available credential names into agent context. Actual values are resolved by the security layer at tool execution time and never appear in LLM reasoning.
- **LiteLLM proxy for API keys**: run a LiteLLM proxy on the host. Docker containers receive a fake API key + proxy base URL. The proxy adds real auth headers. Even `echo $ANTHROPIC_API_KEY` in the container returns a useless placeholder.
- **Shell wrapper over PTY bridge for credential injection**: replace `/bin/bash` inside Docker with `ievo-bash`. Intercept credential references at shell execution level — not at PTY stream level. PTY bridge fails during model thinking phases; shell wrapper fires on every actual tool execution regardless of model state.
- **Scan tool output for leaks**: PostToolUse hook (or shell wrapper post-exec) scans every tool output for credential patterns before returning it to the LLM.

### PR Review Methodology

All agents that review PR changes follow this protocol:

1. **Get changed files locally** — never use `gh pr diff` (GitHub has a 20 000-line limit):
   ```bash
   git fetch origin <branch>
   git diff main...<branch> --name-only
   ```

2. **Read each changed file by size**:
   - File < 300 lines → read the full file (`Read` tool)
   - File ≥ 300 lines → `git diff -U40 main...<branch> -- <file>` (40 lines context each side)

3. **Group files by module** before reviewing — understand the structure before diving into individual files

4. **Never review a raw diff alone** — a diff without surrounding context hides intent. When a single line changed, read at least the enclosing function.

### Agent & App Design

- **One agent, one responsibility**: each agent has exactly one job. Do not combine review, verification, and acceptance into one agent — split them. When an agent's description requires "and", it is two agents. Single-responsibility agents are independently replaceable, testable, and evolvable.
- **Apps > agents for end-to-end workflows**: when a use case requires multiple agents working together, package them as an iEvo App (agents + pipeline + MCP) rather than shipping loose agents. Users get a working system, not parts to wire manually.
- **One pipeline engine, many providers**: pipeline YAML is provider-agnostic. The same workflow runs whether agents execute on Claude, Codex, Ollama, or a mix. Provider selection lives in UAF agent config, not in pipeline logic.
- **Native CLI passthrough**: never replace the native provider CLI (Claude Code, Codex). Wrap it transparently via PTY bridge. Users keep full native access; iEvo adds orchestration on top.
