devflow-kit 1.8.3 → 2.0.1

package/src/assets/commands/explore.mds

@@ -0,0 +1,150 @@
+---
+description: Explore codebase with structured analysis and optional feature knowledge creation
+output-dir: dist/commands
+---
+@import { knowledge_writeback } from "./_partials/_knowledge.mds"
+@import { decisions_load } from "./_partials/_decisions.mds"
+
+# Explore Command
+
+Explore a codebase area by spawning parallel agents for flow tracing, dependency mapping, and pattern analysis. Findings are synthesized into structured output with file:line references, with optional feature knowledge created as a byproduct.
+
+## Usage
+
+```
+/explore "how does the auth system work"
+/explore "trace the request lifecycle from API to database"
+/explore "what patterns does the payments module use"
+```
+
+## Input
+
+`$ARGUMENTS` contains whatever follows `/explore`:
+- Area description: "how does the auth system work"
+- Flow question: "trace the request lifecycle"
+- Empty: use conversation context
+
+## Phases
+
+### Phase 1: Load Decisions (Orchestrator-Local)
+
+**Produces:** DECISIONS_CONTEXT
+
+{decisions_load()}
+
+The orchestrator uses `DECISIONS_CONTEXT` locally when framing exploration — prior decisions and pitfalls suggest specific areas to investigate. Follow `devflow:apply-decisions` to Read full entry bodies on demand. **Do NOT pass `DECISIONS_CONTEXT` to Explore sub-agents** — decisions context stays in the orchestrator, not in the investigation workers.
+
+**No up-front feature knowledge load** — explore investigation workers read code directly to avoid confirmation bias. Feature knowledge is only created as a write-back at the end, after exploration is complete.
+
+### Phase 2: Orient
+
+**Produces:** ORIENT_OUTPUT
+
+Spawn `Agent(subagent_type="Skim")` to get codebase overview relevant to the exploration question:
+
+- File structure and module boundaries in the target area
+- Entry points and key abstractions
+- Related patterns and conventions
+
+### Phase 3: Explore
+
+**Produces:** EXPLORE_OUTPUT
+**Requires:** ORIENT_OUTPUT
+
+Based on Skim agent findings, spawn 2-3 `Agent(subagent_type="Explore")` agents **in a single message** (parallel execution):
+
+- **Flow explorer**: Trace the primary call chain end-to-end — entry point through to side effects
+- **Dependency explorer**: Map imports, shared types, module boundaries, and integration points
+- **Pattern explorer**: Identify recurring patterns, conventions, and architectural decisions in the area
+
+Adjust explorer focus based on the specific exploration question.
+
+### Phase 4: Synthesize
+
+**Produces:** MERGED_FINDINGS
+**Requires:** EXPLORE_OUTPUT
+
+Spawn `Agent(subagent_type="Synthesize")` in `exploration` mode with combined findings:
+
+- Merge overlapping discoveries from parallel explorers
+- Resolve any contradictions between explorer findings
+- Organize into the Output format below
+
+### Phase 5: Present
+
+**Requires:** MERGED_FINDINGS
+
+Main session reviews synthesis for:
+
+- **Gaps**: Areas the explorers missed or couldn't reach
+- **Surprises**: Unexpected patterns, hidden dependencies, non-obvious design choices
+- **Depth**: Areas where the user might want to drill deeper
+
+Present findings to user. Use AskUserQuestion to offer focused follow-up exploration.
+
+### Phase 6: Suggest Feature Knowledge Creation (Conditional)
+
+**Requires:** MERGED_FINDINGS, DECISIONS_CONTEXT
+**Produces:** FEATURE_KNOWLEDGE_STATUS (created | skipped)
+
+1. Check if matching feature knowledge already exists by reading `\{worktree\}/.devflow/features/index.md` (or globbing frontmatter if absent). If covered → skip
+2. Use AskUserQuestion: "No feature knowledge exists for \{explored area\}. Create one to capture these patterns?"
+3. If user declines → set FEATURE_KNOWLEDGE_STATUS = skipped
+4. If user accepts: proceed with write-back below.
+
+{knowledge_writeback()}
+
+Set FEATURE_KNOWLEDGE_STATUS = created (if agent spawned) or skipped.
+
+**Failure handling**: Non-blocking. If Knowledge agent fails, log and continue.
+
+## Worktree Support
+
+If the orchestrator receives a `WORKTREE_PATH` context (e.g., from multi-worktree workflows), pass it through to all spawned agents. Each agent's "Worktree Support" section handles path resolution.
+
+## Output
+
+Structured exploration findings with concrete code references:
+
+- Scope (what was explored and boundaries)
+- Architecture Map (modules, layers, key abstractions with file:line)
+- Flow Trace (call chain from entry to exit with file:line at each step)
+- Integration Points (module boundaries, shared types, external dependencies)
+- Patterns (recurring conventions, design decisions observed)
+- Key Insights (non-obvious findings, surprises, potential concerns)
+
+## Architecture
+
+```
+/explore (orchestrator)
+│
+├─ Phase 1: Load Decisions (Orchestrator-Local)
+│
+├─ Phase 2: Orient
+│  └─ Skim agent (codebase overview)
+│
+├─ Phase 3: Parallel exploration
+│  └─ 2-3 Explore agents (flow, dependency, pattern) in single message
+│
+├─ Phase 4: Synthesize
+│  └─ Synthesize agent aggregates findings in exploration mode
+│
+├─ Phase 5: Present findings with drill-down offer
+│
+└─ Phase 6: Suggest feature knowledge creation (conditional)
+   └─ Knowledge agent write-back (if user accepts and no existing feature knowledge)
+```
+
+## Principles
+
+1. **Structure over browsing** - Every claim must cite file:line references
+2. **Parallel execution** - All explorers run simultaneously for speed
+3. **Knowledge-informed** - Prior decisions guide where to look; NO pre-loaded feature knowledge in sub-agents (avoids confirmation bias)
+4. **User-driven depth** - Present findings, then offer drill-down into specific areas
+
+## Error Handling
+
+- If Skim agent returns no relevant files: report "No files found matching exploration scope"
+- If all explorers error: report partial findings from any that succeeded, note gaps
+- If an explorer errors: continue with remaining results, note the gap
+- If feature knowledge creation fails: log failure, report exploration results normally

package/src/assets/commands/implement.mds

@@ -0,0 +1,496 @@
+---
+description: Execute a single task through implementation, quality gates, and PR creation - accepts plan documents, issues, or task descriptions
+output-dir: dist/commands
+---
+@import { knowledge_load, knowledge_writeback } from "./_partials/_knowledge.mds"
+@import { decisions_load } from "./_partials/_decisions.mds"
+@import { compliance_gate } from "./_partials/_compliance.mds"
+
+# 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.
+
+{compliance_gate()}
+
+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)`.
+
+{decisions_load()}
+
+Pass to Code agent (Phase 2) and Scrutinize agent (Phase 5).
+
+{knowledge_load()}
+
+### 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.
+
+{knowledge_writeback()}
+
+## 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.