devflow-kit 1.8.3 → 2.0.0

package/dist/commands/implement.md

@@ -0,0 +1,590 @@
+---
+description: Execute a single task through implementation, quality gates, and PR creation - accepts plan documents, issues, or task descriptions
+---
+# Implement Command
+
+Orchestrate a single task through implementation by spawning specialized agents. The orchestrator only spawns agents and passes context - all work is done by agents.
+
+## Usage
+
+```
+/implement <task description>
+/implement #42                                     (GitHub issue number)
+/implement .devflow/docs/design/42-jwt-auth.2026-04-07_1430.md  (plan document from /plan)
+/implement                                         (use conversation context)
+```
+
+## Input
+
+`$ARGUMENTS` contains whatever follows `/implement`:
+- Plan document path: `.devflow/docs/design/42-jwt-auth.2026-04-07_1430.md` (path to an existing `.md` file)
+- GitHub issue: `#42`
+- Task description: "implement JWT auth"
+- Empty: use conversation context
+
+> **Tip**: For best results, run `/plan` first to produce a design artifact, then pass it to `/implement`.
+
+## Phases
+
+### Re-validation Continuation Path
+
+When the user explicitly asks to re-validate, re-check, or re-run quality gates after making their own changes:
+
+1. **Branch safety check**: If on a protected branch (main, master, develop, etc.), run Phase 1 to create/switch to a work branch. If already on a work branch, skip Phase 1.
+2. **Skip Phase 2** — no Code agent needed, user already made changes.
+3. **Detect FILES_CHANGED**: `git diff --name-only {base_branch}...HEAD`
+4. **Run Phases 3-8** — full quality gate pipeline on detected changes.
+5. **Proceed to Phase 10** (Create PR) / **Phase 11** (Report).
+
+If the user prompt does NOT match re-validation, proceed with the full pipeline below.
+
+### Phase 1: Setup
+
+**Produces:** TASK_ID, BASE_BRANCH, EXECUTION_PLAN, DECISIONS_CONTEXT, FEATURE_KNOWLEDGE, PR_DESCRIPTION_GUIDANCE, ISSUE_NUMBER
+
+**Load Companion Skills** — Load via Skill tool: `devflow:test-driven-development`, `devflow:patterns`, `devflow:dependency-research`. If a skill fails to load, continue without it.
+
+Record the current branch name as `BASE_BRANCH` - this will be the PR target.
+
+**Resolve `COMPLIANCE_SKILL_INSTALLED` once per run:** Check whether `~/.claude/skills/devflow:compliance/SKILL.md` exists (one file-existence check, read-only, silent). Set `COMPLIANCE_SKILL_INSTALLED = true` if the file exists, `false` otherwise.
+
+Spawn Git agent to set up task environment. The Git agent derives the branch name automatically from the issue or task description:
+
+```
+Agent(subagent_type="Git"):
+"OPERATION: setup-task
+BASE_BRANCH: {current branch name}
+ISSUE_INPUT: {issue number if $ARGUMENTS starts with #, otherwise omit}
+TASK_DESCRIPTION: {task description from $ARGUMENTS if not an issue number or .md path, otherwise omit}
+COMPLIANCE: {enabled if COMPLIANCE_SKILL_INSTALLED, otherwise (none)}
+PLAN_ARTIFACT_PATH: {path to plan document if $ARGUMENTS ends in .md, otherwise (none)}
+Derive branch name from issue or description, create feature branch, and fetch issue if specified.
+Return the branch setup summary."
+```
+
+**Capture from Git agent output** (used throughout flow):
+- `TASK_ID`: The branch name created by Git agent (use as TASK_ID for rest of flow)
+- `BASE_BRANCH`: Branch this feature was created from (for PR target)
+- `ISSUE_NUMBER`: GitHub issue number (if provided or created by the issue-first gate in step 1c)
+- `ISSUE_CONTENT`: Full issue body including description (if provided)
+- `ACCEPTANCE_CRITERIA`: Extracted acceptance criteria from issue (if provided)
+
+**Plan Document Handling** (when $ARGUMENTS is a path ending in `.md`):
+1. Read the plan document from the path provided
+2. Extract from YAML frontmatter: `execution-strategy`, `context-risk`, `issue` number
+3. Extract from body: Subtask Breakdown, Implementation Plan, Patterns to Follow, Acceptance Criteria
+4. If `issue` field present in frontmatter: pass to Git agent as ISSUE_INPUT
+5. Use extracted content as EXECUTION_PLAN for the Code agent phase (replaces exploration/planning output)
+6. Captured values override defaults from Git agent where present
+7. Extract `## PR Description Guidance` section (if present) → set `PR_DESCRIPTION_GUIDANCE` to its full content. If section not found, set `PR_DESCRIPTION_GUIDANCE` to `(none)`.
+
+If `PR_DESCRIPTION_GUIDANCE` was not set above (non-plan paths: issue input or task description), set it to `(none)`.
+
+### Load DECISIONS_CONTEXT
+
+Resolve the worktree root using the `devflow:worktree-support` algorithm (use WORKTREE_PATH if provided, otherwise cwd). All paths below are relative to `{worktree}`.
+
+**Step 1 — Read the pre-rendered index:**
+
+Attempt to read `{worktree}/.devflow/learning/index.md`.
+
+- If the file exists and contains non-empty content: use that content as `DECISIONS_CONTEXT`.
+- If the file is absent or empty: set `DECISIONS_CONTEXT` to `(none)`.
+
+**No subprocess, no `.cjs` script.** This is a single direct file read — the index is written at render time by `render-decisions.cjs` alongside `decisions.md`/`pitfalls.md`.
+
+**Step 2 — Apply decisions using `devflow:apply-decisions`:**
+
+When `DECISIONS_CONTEXT` is not `(none)`, follow `devflow:apply-decisions` to scan the index, identify plausibly-relevant entries, Read full entry bodies on demand, and cite verbatim IDs in downstream agent prompts and reasoning.
+
+Pass to Code agent (Phase 2) and Scrutinize agent (Phase 5).
+
+### Load Feature Knowledge
+
+Resolve the worktree root using the `devflow:worktree-support` algorithm (use WORKTREE_PATH if provided, otherwise cwd). All paths below are relative to `{worktree}`.
+
+**Step 1 — Read the index cache:**
+
+Attempt to read `{worktree}/.devflow/features/index.md`. Each line follows the format:
+
+```
+- **{slug}** — {areas} — {Use-when description}
+```
+
+If `index.md` exists and contains at least one entry line, use it for relevance matching.
+
+**Step 2 — Fallback: glob frontmatter (if `index.md` is absent or empty):**
+
+Glob `{worktree}/.devflow/features/*/KNOWLEDGE.md`. For each file found, read only its YAML frontmatter block (between the opening and closing `---` delimiters). The frontmatter fields `name`, `description`, and `directories` are the authoritative relevance surface — `index.md` is only a cache.
+
+**Step 3 — Pick relevant KBs:**
+
+Match the current task area and description against each index line (or frontmatter `description` + `directories` on fallback). Select entries whose documented area overlaps the current task. This is a relevance judgment — prefer specificity over breadth.
+
+**Step 4 — Read selected KBs:**
+
+For each selected entry, read `{worktree}/.devflow/features/{slug}/KNOWLEDGE.md` in full. When the KB content contradicts the current code you observe, **trust the code** — the code is the freshness mechanism; the KB may lag behind.
+
+**Step 5 — Set FEATURE_KNOWLEDGE:**
+
+Concatenate the selected KNOWLEDGE.md files under slug headers:
+
+```
+--- Feature knowledge: {slug} ---
+{full KNOWLEDGE.md content}
+```
+
+If no KBs exist, no KBs are relevant, or `.devflow/features/` is absent, set `FEATURE_KNOWLEDGE` to `(none)`.
+
+**No subprocess, no git calls, no `.cjs` script.** This entire step is direct file reads — 1 index read (or N frontmatter reads on fallback), bounded by KB count.
+
+### Phase 2: Implement
+
+**Produces:** CODE_AGENT_OUTPUT, FILES_CHANGED
+**Requires:** TASK_ID, BASE_BRANCH, EXECUTION_PLAN, PR_DESCRIPTION_GUIDANCE
+
+Based on Setup context (plan document, issue body, or conversation context), use the three-strategy framework:
+
+**Strategy Selection**:
+- If plan document provided: use `execution-strategy` from frontmatter (default: SINGLE_CODE_AGENT if absent)
+- Otherwise: default to SINGLE_CODE_AGENT unless task description signals high complexity
+
+| Strategy | When | Frequency |
+|----------|------|-----------|
+| **SINGLE_CODE_AGENT** | Default. Coherent A→Z implementation | ~80% |
+| **SEQUENTIAL_CODE_AGENTS** | Context overflow risk, layered dependencies | ~15% |
+| **PARALLEL_CODE_AGENTS** | True artifact independence (rare) | ~5% |
+
+---
+
+**SINGLE_CODE_AGENT** (default):
+
+```
+Agent(subagent_type="Code"):
+"TASK_ID: {task-id}
+TASK_DESCRIPTION: {description}
+BASE_BRANCH: {base branch}
+EXECUTION_PLAN: {full plan from setup context}
+PATTERNS: {patterns from plan document or empty}
+CREATE_PR: true
+DOMAIN: {detected domain or 'fullstack'}
+FEATURE_KNOWLEDGE: {feature_knowledge}
+DECISIONS_CONTEXT: {decisions_context}
+PR_DESCRIPTION_GUIDANCE: {pr_description_guidance}
+ISSUE_NUMBER: {issue number or (none)}"
+```
+
+---
+
+**SEQUENTIAL_CODE_AGENTS** (for HIGH/CRITICAL context risk):
+
+Spawn Code agents one at a time, passing handoff summaries between phases:
+
+**Phase 1 Code agent:**
+```
+Agent(subagent_type="Code"):
+"TASK_ID: {task-id}
+TASK_DESCRIPTION: {phase 1 description}
+BASE_BRANCH: {base branch}
+EXECUTION_PLAN: {phase 1 steps}
+PATTERNS: {patterns from plan document or empty}
+CREATE_PR: false
+DOMAIN: {phase 1 domain, e.g., 'backend'}
+FEATURE_KNOWLEDGE: {feature_knowledge}
+DECISIONS_CONTEXT: {decisions_context}
+PR_DESCRIPTION_GUIDANCE: {pr_description_guidance}
+ISSUE_NUMBER: {issue number or (none)}
+HANDOFF_REQUIRED: true
+HANDOFF_FILE: .devflow/docs/handoff-{branch_slug}.md"
+```
+
+**Phase 2+ Code agents** (after prior phase completes):
+```
+Agent(subagent_type="Code"):
+"TASK_ID: {task-id}
+TASK_DESCRIPTION: {phase N description}
+BASE_BRANCH: {base branch}
+EXECUTION_PLAN: {phase N steps}
+PATTERNS: {patterns from plan document or empty}
+CREATE_PR: {true if last phase, false otherwise}
+DOMAIN: {phase N domain, e.g., 'frontend'}
+PRIOR_PHASE_SUMMARY: {summary from previous Code agent}
+FILES_FROM_PRIOR_PHASE: {list of files created}
+FEATURE_KNOWLEDGE: {feature_knowledge}
+DECISIONS_CONTEXT: {decisions_context}
+PR_DESCRIPTION_GUIDANCE: {pr_description_guidance}
+ISSUE_NUMBER: {issue number or (none)}
+HANDOFF_REQUIRED: {true if not last phase}
+HANDOFF_FILE: .devflow/docs/handoff-{branch_slug}.md"
+```
+
+**Handoff Protocol**: Each sequential Code agent receives the prior Code agent's implementation summary via PRIOR_PHASE_SUMMARY and FILES_FROM_PRIOR_PHASE. The Code agent's built-in branch orientation step handles git log scanning, file reading, and pattern discovery automatically. After each Code agent with HANDOFF_REQUIRED=true completes, write its phase summary to `.devflow/docs/handoff-{branch_slug}.md` using the Write tool (survives context compaction). Delete `.devflow/docs/handoff-{branch_slug}.md` after the final Code agent completes (cleanup).
+
+---
+
+**PARALLEL_CODE_AGENTS** (rare - truly independent artifacts):
+
+Spawn multiple Code agents **in a single message**, each with independent subtask:
+
+```
+Agent(subagent_type="Code"):  # Code agent 1
+"TASK_ID: {task-id}-part1
+TASK_DESCRIPTION: {independent subtask 1}
+BASE_BRANCH: {base branch}
+EXECUTION_PLAN: {subtask 1 steps}
+PATTERNS: {patterns}
+CREATE_PR: false
+DOMAIN: {subtask 1 domain}
+FEATURE_KNOWLEDGE: {feature_knowledge}
+DECISIONS_CONTEXT: {decisions_context}
+PR_DESCRIPTION_GUIDANCE: {pr_description_guidance}
+ISSUE_NUMBER: {issue number or (none)}"
+
+Agent(subagent_type="Code"):  # Code agent 2 (same message)
+"TASK_ID: {task-id}-part2
+TASK_DESCRIPTION: {independent subtask 2}
+BASE_BRANCH: {base branch}
+EXECUTION_PLAN: {subtask 2 steps}
+PATTERNS: {patterns}
+CREATE_PR: false
+DOMAIN: {subtask 2 domain}
+FEATURE_KNOWLEDGE: {feature_knowledge}
+DECISIONS_CONTEXT: {decisions_context}
+PR_DESCRIPTION_GUIDANCE: {pr_description_guidance}
+ISSUE_NUMBER: {issue number or (none)}"
+```
+
+**Independence criteria** (all must be true for PARALLEL_CODE_AGENTS):
+- No shared contracts or interfaces
+- No integration points between subtasks
+- Different files/modules with no imports between them
+- Each subtask is self-contained
+
+### Phase 3: Validate
+
+**Produces:** VALIDATION_RESULT
+**Requires:** FILES_CHANGED
+
+After Code agent completes, spawn Validate agent to verify correctness:
+
+```
+Agent(subagent_type="Validate", model="haiku"):
+"FILES_CHANGED: {list of files from Code agent output}
+VALIDATION_SCOPE: full
+Run build, typecheck, lint, test. Report pass/fail with failure details."
+```
+
+**If FAIL:**
+1. Extract failure details from Validate agent output
+2. Increment `validation_retry_count`
+3. If `validation_retry_count <= 2`:
+   - Spawn Code agent with fix context:
+   ```
+   Agent(subagent_type="Code"):
+   "TASK_ID: {task-id}
+   TASK_DESCRIPTION: Fix validation failures
+   OPERATION: validation-fix
+   VALIDATION_FAILURES: {parsed failures from Validate agent}
+   SCOPE: Fix only the listed failures, no other changes
+   CREATE_PR: false
+   ISSUE_NUMBER: {issue number or (none)}"
+   ```
+   - Loop back to Phase 3 (re-validate)
+4. If `validation_retry_count > 2`: Report failures to user and halt
+
+**If PASS:** Continue to Phase 4
+
+### Phase 4: Simplify
+
+**Produces:** SIMPLIFY_OUTPUT
+**Requires:** FILES_CHANGED
+
+After validation passes, spawn Simplify agent to polish the code:
+
+```
+Agent(subagent_type="Simplify"):
+"Simplify recently implemented code
+Task: {task description}
+FILES_CHANGED: {list of files from Code agent output}
+Focus on code modified by Code agent, apply project standards, enhance clarity"
+```
+
+### Phase 5: Self-Review
+
+**Produces:** SCRUTINIZE_OUTPUT
+**Requires:** FILES_CHANGED
+
+After Simplify agent completes, spawn Scrutinize agent as final quality gate:
+
+```
+Agent(subagent_type="Scrutinize"):
+"TASK_DESCRIPTION: {task description}
+FILES_CHANGED: {list of files from Code agent output}
+DECISIONS_CONTEXT: {decisions_context}
+FEATURE_KNOWLEDGE: {feature_knowledge}
+Evaluate 9 pillars, fix P0/P1 issues, report status"
+```
+
+If Scrutinize agent returns BLOCKED, report to user and halt.
+
+### Phase 6: Re-Validate (if Scrutinize agent made changes)
+
+**Produces:** REVALIDATION_RESULT
+**Requires:** SCRUTINIZE_OUTPUT
+
+If Scrutinize agent made code changes (status: FIXED), spawn Validate agent to verify:
+
+```
+Agent(subagent_type="Validate", model="haiku"):
+"FILES_CHANGED: {files modified by Scrutinize agent}
+VALIDATION_SCOPE: changed-only
+Verify Scrutinize agent's fixes didn't break anything."
+```
+
+**If FAIL:** Report to user - Scrutinize agent broke tests, needs manual intervention.
+
+**If PASS:** Continue to Phase 7
+
+### Phase 7: Alignment Check
+
+**Produces:** ALIGNMENT_RESULT
+**Requires:** FILES_CHANGED, EXECUTION_PLAN
+
+After Scrutinize agent passes (and re-validation if needed), spawn Evaluate agent to validate alignment:
+
+```
+Agent(subagent_type="Evaluate"):
+"ORIGINAL_REQUEST: {task description or issue content}
+EXECUTION_PLAN: {execution plan from Phase 1}
+FILES_CHANGED: {list of files from Code agent output}
+ACCEPTANCE_CRITERIA: {extracted criteria if available}
+FEATURE_KNOWLEDGE: {feature_knowledge}
+Validate alignment with request and plan. Report ALIGNED or MISALIGNED with details."
+```
+
+**If ALIGNED:** Continue to Phase 8
+
+**If MISALIGNED:**
+1. Extract misalignment details from Evaluate agent output
+2. Increment `alignment_fix_count`
+3. If `alignment_fix_count <= 2`:
+   - Spawn Code agent to fix misalignments:
+   ```
+   Agent(subagent_type="Code"):
+   "TASK_ID: {task-id}
+   TASK_DESCRIPTION: Fix alignment issues
+   OPERATION: alignment-fix
+   MISALIGNMENTS: {structured misalignments from Evaluate agent}
+   SCOPE: Fix only the listed misalignments, no other changes
+   CREATE_PR: false
+   ISSUE_NUMBER: {issue number or (none)}"
+   ```
+   - Spawn Validate agent to verify fix didn't break tests:
+   ```
+   Agent(subagent_type="Validate", model="haiku"):
+   "FILES_CHANGED: {files modified by fix Code agent}
+   VALIDATION_SCOPE: changed-only"
+   ```
+   - If Validate agent FAIL: Report to user
+   - If Validate agent PASS: Loop back to Phase 7 (re-check alignment)
+4. If `alignment_fix_count > 2`: Report misalignments to user for decision
+
+### Phase 8: QA Testing
+
+**Produces:** QA_RESULT
+**Requires:** FILES_CHANGED, EXECUTION_PLAN
+
+After Evaluate agent passes, spawn Test agent for scenario-based acceptance testing:
+
+```
+Agent(subagent_type="Test"):
+"ORIGINAL_REQUEST: {task description or issue content}
+EXECUTION_PLAN: {execution plan from Phase 1}
+FILES_CHANGED: {list of files from Code agent output}
+ACCEPTANCE_CRITERIA: {extracted criteria if available}
+Design and execute scenario-based acceptance tests. Report PASS or FAIL with evidence."
+```
+
+**If PASS:** Continue to Phase 9
+
+**If FAIL:**
+1. Extract failure details from Test agent output
+2. Increment `qa_retry_count`
+3. If `qa_retry_count <= 2`:
+   - Spawn Code agent to fix QA failures:
+   ```
+   Agent(subagent_type="Code"):
+   "TASK_ID: {task-id}
+   TASK_DESCRIPTION: Fix QA test failures
+   OPERATION: qa-fix
+   QA_FAILURES: {structured failures from Test agent}
+   SCOPE: Fix only the listed failures, no other changes
+   CREATE_PR: false
+   ISSUE_NUMBER: {issue number or (none)}"
+   ```
+   - Spawn Validate agent to verify fix didn't break tests:
+   ```
+   Agent(subagent_type="Validate", model="haiku"):
+   "FILES_CHANGED: {files modified by fix Code agent}
+   VALIDATION_SCOPE: changed-only"
+   ```
+   - If Validate agent FAIL: Report to user
+   - If Validate agent PASS: Loop back to Phase 8 (re-run Test agent)
+4. If `qa_retry_count > 2`: Report QA failures to user for decision
+
+### Phase 9: CI Status Gate
+
+**Produces:** CI_STATUS
+**Requires:** PR_URL, FILES_CHANGED
+
+Strategy-conditional: run for **SINGLE_CODE_AGENT** (PR exists from Phase 2), skip for **SEQUENTIAL_CODE_AGENTS** / **PARALLEL_CODE_AGENTS** (PR not yet created).
+
+<!-- PATTERN: ci-status-gate -->
+1. Spawn `Agent(subagent_type="Git")` with `OPERATION: check-ci-status` and `PR_NUMBER` from PR_URL.
+2. **If PASSING** → proceed to Phase 10.
+3. **If NO_PR or NO_CI** → skip: "No PR/CI configured, skipping CI validation." Proceed to Phase 10.
+4. **If PENDING** → poll every 60 seconds (global budget, see step 6). Re-spawn Git agent each poll. If PASSING → proceed. If still PENDING after budget exhausted → report "CI still running — verify manually before merging" and proceed.
+5. **If FAILING** → report failing checks. Spawn `Agent(subagent_type="Code")` to fix CI failures based on check names and failure context. After fix, push and re-check. Max 2 fix attempts. If still failing → report failures and proceed.
+6. **Total budget**: max 10 polls and max 2 fix attempts across all check/fix cycles combined. If budget exhausted, report current status and proceed.
+<!-- /PATTERN: ci-status-gate -->
+
+### Phase 10: Create PR
+
+**Produces:** PR_URL
+**Requires:** BASE_BRANCH, TASK_ID
+
+**For SEQUENTIAL_CODE_AGENTS or PARALLEL_CODE_AGENTS**: The last sequential Code agent (with CREATE_PR: true) handles PR creation. For parallel Code agents, create unified PR using `devflow:git` skill patterns. Push branch and run `gh pr create` with comprehensive description, targeting `BASE_BRANCH`.
+
+If `PR_DESCRIPTION_GUIDANCE` is not `(none)`, use it to compose the PR body (see Code agent Responsibility 7 for field-to-section mapping).
+
+When `ISSUE_NUMBER` is known, ensure the PR body includes a `## Related Issues` section with `Closes #{ISSUE_NUMBER}`.
+
+**For SINGLE_CODE_AGENT**: PR is created by the Code agent (CREATE_PR: true) — the Code agent's Responsibility 7 handles Related Issues inclusion when ISSUE_NUMBER is provided.
+
+### Phase 11: Report
+
+**Requires:** VALIDATION_RESULT, ALIGNMENT_RESULT, QA_RESULT, PR_URL
+
+Display completion summary with phase status, PR info, and next steps.
+
+If any Git agent output emitted `TRACEABILITY: DEGRADED ({reason})` lines during the run, surface them verbatim in the report under a `### Traceability` subsection so the user can act on them.
+
+### Feature Knowledge Write-Back (Conditional)
+
+Resolve the worktree root using the `devflow:worktree-support` algorithm (use WORKTREE_PATH if provided, otherwise cwd). All paths below are relative to `{worktree}`.
+
+**Step 1 — Check the opt-out gate:**
+
+Read `{worktree}/.devflow/config.json`. If the `knowledge` field is `false`, skip write-back entirely — the user has disabled it.
+
+If `.devflow/config.json` does not exist, proceed (default is enabled).
+
+**Step 2 — Evaluate whether write-back is warranted:**
+
+Only proceed if **at least one** of these is true:
+- This workflow changed files in a directory that is documented by an existing feature knowledge base (a documented area changed).
+- This workflow surfaced durable, cross-cutting knowledge about a codebase area that would help future agents working in the same area — patterns, anti-patterns, integration points, gotchas not visible from a single file read.
+
+**Never spawn unconditionally.** If neither condition is met, skip write-back silently.
+
+**Step 3 — Spawn the Knowledge agent:**
+
+Spawn `Agent(subagent_type="Knowledge")` with the following context:
+
+```
+"WORKTREE_PATH: {worktree root}
+FEATURE_SLUG: {slug derived from primary changed directory, kebab-case}
+FEATURE_NAME: {human-readable name}
+DIRECTORIES: {list of primary directories touched by this workflow}
+FILES_CHANGED: {list of files changed}
+DECISIONS_CONTEXT: {DECISIONS_CONTEXT if available, else (none)}
+
+Load the devflow:feature-knowledge skill and follow its authoring process.
+
+Write the knowledge base to:
+  {worktree}/.devflow/features/{slug}/KNOWLEDGE.md
+
+Then update the index cache by performing a read-modify-write on:
+  {worktree}/.devflow/features/index.md
+
+Index line format: `- **{slug}** — {areas} — {Use-when description}`
+
+If the line for this slug already exists in index.md, replace it. If it does not exist, append it. If index.md does not exist, create it with just this line.
+
+The frontmatter in KNOWLEDGE.md is the source of truth — index.md is only a cache. Write the two files directly — no intermediate result JSON files, no external scripts.
+
+After writing, commit the two files to the current worktree branch yourself by running git via your Bash tool (do not use a script). Stage ONLY .devflow/features/index.md and .devflow/features/{slug}/KNOWLEDGE.md, then commit just those paths with a docs(knowledge): message. Do NOT push, do NOT force, do NOT stage anything else. Follow your Commit Protocol — it is non-blocking, so if any git step fails, report KB_COMMIT and finish normally."
+```
+
+**Failure handling**: Non-blocking. If the Knowledge agent fails, log the failure and continue — the workflow outcome is not affected by write-back success.
+
+## Architecture
+
+```
+/implement (orchestrator - spawns agents only)
+│
+├─ Re-validation Path (when user says "re-validate"/"re-check"/"re-run gates")
+│  └─ Branch safety → skip Phase 2 → detect FILES_CHANGED → Phases 3-8 → Phase 10-11
+│
+├─ Phase 1: Setup
+│  └─ Git agent (operation: setup-task) - creates feature branch, fetches issue
+│  └─ Plan document parsing (if .md path provided) - extracts execution plan, strategy
+│
+├─ Phase 2: Implement (3-strategy framework)
+│  ├─ SINGLE_CODE_AGENT (80%): One Code agent, full plan, CREATE_PR: true
+│  ├─ SEQUENTIAL_CODE_AGENTS (15%): N Code agents with handoff summaries
+│  └─ PARALLEL_CODE_AGENTS (5%): N Code agents in single message (rare)
+│
+├─ Phase 3: Validate
+│  └─ Validate agent (build, typecheck, lint, test)
+│  └─ If FAIL: Code agent fix loop (max 2 retries) → re-validate
+│
+├─ Phase 4: Simplify
+│  └─ Simplify agent (refines code clarity and consistency)
+│
+├─ Phase 5: Self-Review
+│  └─ Scrutinize agent (final quality gate, fixes P0/P1)
+│
+├─ Phase 6: Re-Validate (if Scrutinize agent made changes)
+│  └─ Validate agent (verify Scrutinize agent fixes)
+│
+├─ Phase 7: Alignment Check
+│  └─ Evaluate agent (validates alignment - reports only, no fixes)
+│  └─ If MISALIGNED: Code agent fix loop (max 2 iterations) → Validate agent → re-check
+│
+├─ Phase 8: QA Testing
+│  └─ Test agent (scenario-based acceptance tests)
+│  └─ If FAIL: Code agent fix loop (max 2 retries) → Validate agent → re-test
+│
+├─ Phase 9: CI Status Gate (SINGLE_CODE_AGENT only)
+│  └─ Git agent (check-ci-status) → poll/fix cycle (10 polls + 2 fix budget)
+│
+├─ Phase 10: Create PR (if needed)
+│  └─ SINGLE_CODE_AGENT: handled by Code agent
+│  └─ SEQUENTIAL: handled by last Code agent
+│  └─ PARALLEL: orchestrator creates unified PR
+│
+├─ Phase 11: Report
+│
+└─ Feature Knowledge Write-Back (Conditional)
+   └─ Knowledge agent (if documented area changed AND knowledge enabled)
+```
+
+## Principles
+
+1. **Orchestration only** - Command spawns agents, never does work itself
+2. **Plan-first** - Plan documents from `/plan` skip exploration/planning overhead entirely
+3. **Coherence-first** - Single Code agent produces more consistent code (default ~80% of tasks)
+4. **Agent ownership** - Each agent owns its output completely
+5. **Clean handoffs** - Each phase passes structured data to next; sequential Code agents pass implementation summaries
+6. **Honest reporting** - Display agent outputs directly
+7. **Simplification pass** - Code refined for clarity before PR
+8. **Strict delegation** - Never perform agent work in main session. "Spawn X" means call Agent tool with X, not do X's work yourself
+9. **Validate agent owns validation** - Never run `npm test`, `npm run build`, or similar in main session; always delegate to Validate agent
+10. **Code agent owns fixes** - Never implement fixes in main session; spawn Code agent for validation failures and alignment fixes
+11. **Loop limits** - Max 2 validation retries, max 2 alignment fix iterations before escalating to user
+12. **CI awareness** - CI status is checked before merge for SINGLE_CODE_AGENT strategy
+
+## Error Handling
+
+If any agent fails, report the phase, agent type, and error. Offer options: retry phase, investigate systematically, or escalate to user.