diff --git a/.archon/commands/defaults/archon-create-plan.md b/.archon/commands/defaults/archon-create-plan.md index 979756c252..3c826831d1 100644 --- a/.archon/commands/defaults/archon-create-plan.md +++ b/.archon/commands/defaults/archon-create-plan.md @@ -36,6 +36,31 @@ Transform "$ARGUMENTS" into a battle-tested implementation plan through systemat | Free-form text | Description | Use directly as feature input | | Empty/blank | Error | STOP - require input | +### 0.1a If the input is a GitHub issue: comments outrank the body + +Fetch the issue **with its comments**, and treat them as authoritative: + +```bash +gh issue view {number} --json title,body,labels,comments,state,url,author +``` + +- **Read every comment before planning.** A later maintainer comment supersedes + the body wherever they disagree — the body is the opening position, not the + specification. +- **A comment stating a decision IS the specification.** If one settles a shape, + a field list, an interface, or an explicit "do X, not Y", plan that. Do not + re-derive the choice from the body and do not compromise between them. +- **Follow linked issues.** When the body or a comment points at another issue + (`#1234` or a URL) for a decision or contract, fetch that issue and its + comments too. One level of following is enough. +- **If the body and a decision conflict, record which you followed** in the plan. + A silent choice is the failure mode here. + +On 2026-08-03 a run planned from an issue body while a maintainer comment on that +same issue — already present in the fetched input — specified a different design. +The resulting PR was discarded. The data was there; nothing said it outranked the +body. + ### 0.2 If PRD File Detected 1. **Read the PRD file** diff --git a/.archon/commands/defaults/archon-investigate-issue.md b/.archon/commands/defaults/archon-investigate-issue.md index 2d3f88cdd5..ab29d62467 100644 --- a/.archon/commands/defaults/archon-investigate-issue.md +++ b/.archon/commands/defaults/archon-investigate-issue.md @@ -49,6 +49,32 @@ gh issue view {number} --json title,body,labels,comments,state,url,author - Parse as problem description - Note: No GitHub posting (artifact only) +### 1.2a Comments outrank the body, and linked issues are part of the input + +An issue body describes a problem as first understood. Comments are where it gets +**decided**. Treat them with that authority: + +- **Read every comment before planning anything.** A later maintainer comment + supersedes the body wherever the two disagree — the body is the opening + position, not the specification. +- **A comment stating a decision IS the specification.** If one settles a shape, + a field list, an interface, or an explicit "do X, not Y", implement that. Do + not re-derive the choice from the body and do not average the two. +- **Follow linked issues.** When the body or a comment points at another issue + (`#1234`, or a full URL) for a decision, design, or contract, fetch it and read + its comments too: + ```bash + gh issue view 1234 --json title,body,comments,state,url + ``` + One level of following is enough — do not spider the whole graph. +- **If the body and a decision conflict, say so in your investigation artifact** + and state which you followed. A silent choice is the failure mode here. + +This is not hypothetical. On 2026-08-03 a run implemented an issue's body while a +maintainer comment on that same issue — fetched, present in the input, posted 16 +seconds before the run started — specified a different shape entirely. The PR was +discarded. The data was there; nothing said it outranked the body. + ### 1.3 Classify Issue Type | Type | Indicators | diff --git a/.archon/workflows/experimental/archon-fix-github-issue-experimental.yaml b/.archon/workflows/experimental/archon-fix-github-issue-experimental.yaml index d08bff378a..1116f1c949 100644 --- a/.archon/workflows/experimental/archon-fix-github-issue-experimental.yaml +++ b/.archon/workflows/experimental/archon-fix-github-issue-experimental.yaml @@ -39,10 +39,41 @@ description: | 8. Simplifies changed code (implements fixes directly, not just reports) 9. Reports results back to the GitHub issue with follow-up suggestions -provider: claude -model: sonnet +# Provider-agnostic: no `provider:` here, so every node inherits the install +# default (`defaultAssistant` / `assistants.*` in .archon/config.yaml). Models are +# tier keywords, not literal ids, so the same DAG runs on whatever the install has +# configured for small/medium/large. +model: medium nodes: + # ═══════════════════════════════════════════════════════════════ + # PHASE 0: PREP WORKTREE + # ═══════════════════════════════════════════════════════════════ + # A fresh worktree has no installed dependencies, so type-check and tests + # fail before reaching project code. Root node with no depends_on, so it runs + # in parallel with the classify/plan phase and costs no wall-clock — only + # `implement` waits on it. Kept deliberately minimal; add context only if it + # actually fails on a real project. + + - id: prep-worktree + prompt: | + Install this project's dependencies so builds, type-checks and tests can run + in this fresh worktree. + + Follow this order: + + 1. Locate the package-manager markers actually present in the repo — lockfiles + and manifests. Decide from evidence, never from convention. + 2. Read the manifest head to confirm the manager and any pinned version. + 3. Verify that manager responds to a version check before relying on it. + 4. Install using the manager's locked mode — the variant that reproduces the + lockfile exactly and fails rather than updating it. The install must not + modify the lockfile. + 5. Report one line: the manager you detected, and whether the install succeeded. + + Bound every read; never print a whole file. + model: small + # ═══════════════════════════════════════════════════════════════ # PHASE 1: FETCH & CLASSIFY # ═══════════════════════════════════════════════════════════════ @@ -58,6 +89,7 @@ nodes: - If the message is ambiguous (e.g., "fix the SQLite timestamp bug"), use `gh issue list` to search for matching issues and pick the best match. CRITICAL: Your final output must be ONLY the bare number with no quotes, no markdown, no explanation. Example correct output: 709 + model: small - id: fetch-issue bash: | @@ -79,6 +111,15 @@ nodes: $fetch-issue.output + ## Operator Request + + The message that started this run, verbatim. It is often just an issue reference, + but it may add constraints, corrections, or context the issue body lacks — e.g. + naming the real type, flagging that external research is needed, or narrowing + scope. Weigh it alongside the issue, and where the two conflict, prefer this. + + $ARGUMENTS + ## Type | Type | Indicators | @@ -112,8 +153,7 @@ nodes: Provide reasoning that covers all three decisions. depends_on: [fetch-issue] - model: haiku - allowed_tools: [] + model: small output_format: type: object properties: @@ -221,6 +261,7 @@ nodes: - id: investigate command: archon-investigate-issue + output_type: investigation depends_on: [classify, web-research] when: "$classify.output.issue_type == 'bug'" # Allow web-research to be skipped (needs_external_research == 'false') without blocking @@ -229,6 +270,7 @@ nodes: - id: plan command: archon-create-plan + output_type: plan depends_on: [classify, web-research] when: "$classify.output.issue_type != 'bug'" # Allow web-research to be skipped (needs_external_research == 'false') without blocking @@ -258,9 +300,50 @@ nodes: - id: implement command: archon-fix-issue - depends_on: [bridge-artifacts] + output_type: implementation + depends_on: [bridge-artifacts, prep-worktree] context: fresh - model: opus[1m] + model: large + + # Hard stop when `implement` produced nothing. + # + # `implement` can decline to change anything — a blocked precondition, an unclear + # plan — and still report success, so the run continued through create-pr and the + # whole review fleet on an empty diff, then reported `completed`. Nine nodes ran + # after the work had already failed. This asks the only question that matters + # deterministically: is there a change to review? + # + # Exiting non-zero fails the node, and therefore the run, before any reviewer or + # PR node spends anything. A run with nothing to show should fail, not go green. + # `.archon/` is excluded deliberately. Archon copies the operator's workflow and + # command edits into every run worktree — that is the feature that lets a workflow + # be iterated on before it is committed — so those files are present BEFORE + # `implement` runs and are not its output. A first version of this guard counted + # them and passed three consecutive runs on an empty implementation, which is the + # exact failure it exists to catch. + # + # Only the working tree is inspected: `implement` leaves its changes uncommitted + # (committing is `create-pr`'s job). If that ever stops being true this guard fails + # a run that did have work — visible and annoying — rather than passing one that + # did not, which is silent. That is the safe direction for it to be wrong in. + - id: assert-implemented + bash: | + base=$BASE_BRANCH + tracked=$(git diff --name-only HEAD -- ':(exclude).archon' | head -1) + untracked=$(git ls-files --others --exclude-standard -- ':(exclude).archon' | head -1) + if commits=$(git rev-list --count "origin/$base..HEAD" 2>/dev/null); then :; else commits=unknown; fi + + if [ -n "$tracked" ] || [ -n "$untracked" ]; then + git --no-pager diff --stat HEAD -- ':(exclude).archon' | tail -1 + elif [ "$commits" = "unknown" ]; then + echo "WARNING: cannot compare against origin/$base — not failing on an unknown" + elif [ "$commits" != "0" ]; then + echo "$commits commit(s) ahead of origin/$base" + else + echo "implement produced neither a commit nor a working-tree change outside .archon/ — failing before the review phase" >&2 + exit 1 + fi + depends_on: [implement] # ═══════════════════════════════════════════════════════════════ # PHASE 5: VALIDATE @@ -268,7 +351,8 @@ nodes: - id: validate command: archon-validate - depends_on: [implement] + output_type: validation + depends_on: [assert-implemented] context: fresh # ═══════════════════════════════════════════════════════════════ @@ -322,9 +406,37 @@ nodes: # PHASE 7: REVIEW # ═══════════════════════════════════════════════════════════════ + # Deterministic PR-number capture. + # + # create-pr asks the MODEL to run `gh pr view --json number` and echo the result + # into $ARTIFACTS_DIR/.pr-number. Being a prompt instruction, it is advisory: on + # 2026-08-03, across four parallel runs, it wrote the ISSUE number twice + # (c77ed1bc -> 2323, 500fa086 -> 2279), skipped the file entirely once + # (3b03cb58), and was correct once. review-scope then resolved a PR that does not + # exist, correctly refused to fabricate a scope.md, and review-classify declined + # every specialist for lack of evidence — while the run still reported success. + # Three of four PRs got one generalist reviewer instead of the intended set. + # + # This has no judgment content and its silent failure guts the entire review + # phase, so it belongs in a node that cannot decline to fire rather than in a + # prompt. Failing here stops the run instead of yielding a green under-reviewed + # pass. (Workflow constitution: the reliability carve-out, not a style rule.) + - id: capture-pr-number + bash: | + pr=$(gh pr view --json number --jq .number 2>/dev/null || true) + if ! printf '%s' "$pr" | grep -qE '^[0-9]+$'; then + echo "capture-pr-number: no PR resolves for the current branch." >&2 + echo "The review phase would be scoped against nothing and would still report success." >&2 + exit 1 + fi + printf '%s' "$pr" > "$ARTIFACTS_DIR/.pr-number" + gh pr view --json url --jq .url > "$ARTIFACTS_DIR/.pr-url" 2>/dev/null || true + echo "{\"pr_number\":\"$pr\"}" + depends_on: [create-pr] + - id: review-scope command: archon-pr-review-scope - depends_on: [create-pr] + depends_on: [capture-pr-number] context: fresh - id: review-classify @@ -350,8 +462,7 @@ nodes: Provide your reasoning for each decision. depends_on: [review-scope] - model: haiku - allowed_tools: [] + model: small context: fresh output_format: type: object @@ -387,31 +498,62 @@ nodes: depends_on: [review-classify] context: fresh - # Reviewer gates: run when review-classify flags them AND the scope is non-small, - # OR when smoke-validate found the issue claims unreliable (fallback to full review). - # Expression form: A && B || A && C (the condition evaluator has no parens; && binds tighter than ||) + # All four conditional reviewers share one extra-scrutiny term: + # run_ AND (scope is non-small OR the issue's claims did not hold up) + # `when:` has no parentheses by design, so expressing that inline forced + # `A && B || A && C` — four near-identical ~180-char conditions differing only in + # the agent flag. Computing the shared term ONCE here keeps it deterministic + # (script computes, YAML coordinates) and leaves each gate two short comparisons. + # + # Substitutions are injected already shell-quoted, so they are assigned unquoted + # and then quoted normally as locals. + - id: review-gate + bash: | + scope=$classify.output.scope + claims_blob=$smoke-validate.output + # Fail-safe: only SUPPRESS the extra reviewers when the scope is small AND + # the smoke validator positively confirmed the issue's claims. Anything else + # — non-small scope, claims refuted, or smoke-validate producing nothing at + # all (timeout, failure) — biases toward MORE review, never less. + # + # Reads the whole output and greps rather than `$smoke-validate.output.claims_accurate`: + # strict field access fails this node when the producer emitted no JSON, and a + # failed gate silently skips every conditional reviewer downstream. Observed on + # run 7f392748: smoke-validate timed out, this node failed, and the review phase + # quietly dropped from two specialists to one while still reporting success. + if [ "$scope" = "small" ] && printf '%s' "$claims_blob" | grep -q '"claims_accurate"[[:space:]]*:[[:space:]]*"\?true'; then + echo '{"extra_review":"false"}' + else + echo '{"extra_review":"true"}' + fi + depends_on: [review-classify, smoke-validate] + # Run even when smoke-validate failed — that case must reach the fail-safe + # branch above, not skip this node and take the reviewers down with it. + trigger_rule: all_done + + # Reviewer gates: the agent's own flag AND the shared extra-scrutiny term. - id: error-handling command: archon-error-handling-agent - depends_on: [review-classify] - when: "$review-classify.output.run_error_handling == 'true' && $classify.output.scope != 'small' || $review-classify.output.run_error_handling == 'true' && $smoke-validate.output.claims_accurate == 'false'" + depends_on: [review-classify, review-gate] + when: "$review-classify.output.run_error_handling == 'true' && $review-gate.output.extra_review == 'true'" context: fresh - id: test-coverage command: archon-test-coverage-agent - depends_on: [review-classify] - when: "$review-classify.output.run_test_coverage == 'true' && $classify.output.scope != 'small' || $review-classify.output.run_test_coverage == 'true' && $smoke-validate.output.claims_accurate == 'false'" + depends_on: [review-classify, review-gate] + when: "$review-classify.output.run_test_coverage == 'true' && $review-gate.output.extra_review == 'true'" context: fresh - id: comment-quality command: archon-comment-quality-agent - depends_on: [review-classify] - when: "$review-classify.output.run_comment_quality == 'true' && $classify.output.scope != 'small' || $review-classify.output.run_comment_quality == 'true' && $smoke-validate.output.claims_accurate == 'false'" + depends_on: [review-classify, review-gate] + when: "$review-classify.output.run_comment_quality == 'true' && $review-gate.output.extra_review == 'true'" context: fresh - id: docs-impact command: archon-docs-impact-agent - depends_on: [review-classify] - when: "$review-classify.output.run_docs_impact == 'true' && $classify.output.scope != 'small' || $review-classify.output.run_docs_impact == 'true' && $smoke-validate.output.claims_accurate == 'false'" + depends_on: [review-classify, review-gate] + when: "$review-classify.output.run_docs_impact == 'true' && $review-gate.output.extra_review == 'true'" context: fresh # ═══════════════════════════════════════════════════════════════ @@ -420,8 +562,14 @@ nodes: - id: synthesize command: archon-synthesize-review + output_type: review-synthesis depends_on: [code-review, error-handling, test-coverage, comment-quality, docs-impact] - trigger_rule: one_success + # all_done, not one_success: synthesize only once EVERY reviewer is terminal. + # one_success would let a synthesis stand on a subset if the reviewers ever land + # in different layers, and it reports that partial view as if it were the whole + # review. all_done also still fires when reviewers were skipped by design (the + # common case — the classifier only asks for the relevant specialists). + trigger_rule: all_done context: fresh - id: self-fix @@ -444,5 +592,6 @@ nodes: - id: report command: archon-issue-completion-report + output_type: completion-report depends_on: [simplify] context: fresh diff --git a/packages/workflows/src/defaults/bundled-defaults.generated.ts b/packages/workflows/src/defaults/bundled-defaults.generated.ts index d58518d625..0a3df9fe52 100644 --- a/packages/workflows/src/defaults/bundled-defaults.generated.ts +++ b/packages/workflows/src/defaults/bundled-defaults.generated.ts @@ -20,7 +20,7 @@ export const BUNDLED_COMMANDS: Record = { "archon-code-review-agent": "---\ndescription: Review code quality, CLAUDE.md compliance, and detect bugs\nargument-hint: (none - reads from scope artifact)\n---\n\n# Code Review Agent\n\n---\n\n## Your Mission\n\nReview the PR for code quality, CLAUDE.md compliance, patterns, and bugs. Produce a structured artifact with findings, fix suggestions with multiple options, and reasoning.\n\n**Output artifact**: `$ARTIFACTS_DIR/review/code-review-findings.md`\n\n---\n\n## Phase 1: LOAD - Get Context\n\n### 1.1 Get PR Number from Registry\n\n```bash\nPR_NUMBER=$(cat $ARTIFACTS_DIR/.pr-number)\n```\n\n### 1.2 Read Scope\n\n```bash\ncat $ARTIFACTS_DIR/review/scope.md\n```\n\nNote:\n- Changed files list\n- CLAUDE.md rules to check\n- Focus areas\n\n**CRITICAL**: Check for \"NOT Building (Scope Limits)\" section. Items listed there are **intentionally excluded** - do NOT flag them as bugs or missing features!\n\n### 1.3 Get PR Diff\n\n```bash\ngh pr diff {number}\n```\n\n### 1.4 Read CLAUDE.md\n\n```bash\ncat CLAUDE.md\n```\n\nNote all coding standards, patterns, and rules.\n\n**PHASE_1_CHECKPOINT:**\n- [ ] PR number identified\n- [ ] Scope loaded\n- [ ] Diff available\n- [ ] CLAUDE.md rules noted\n\n---\n\n## Phase 2: ANALYZE - Review Code\n\n### 2.1 Check CLAUDE.md Compliance\n\nFor each changed file, verify:\n- Import patterns match project style\n- Naming conventions followed\n- Error handling patterns correct\n- Type annotations complete\n- Testing patterns followed\n\n### 2.2 Detect Bugs\n\nLook for:\n- Logic errors\n- Null/undefined handling issues\n- Race conditions\n- Memory leaks\n- Security vulnerabilities\n- Off-by-one errors\n- Missing error handling\n\n### 2.3 Check Code Quality\n\nEvaluate:\n- Code duplication\n- Function complexity\n- Proper abstractions\n- Clear naming\n- Appropriate comments\n\n### 2.4 Pattern Matching\n\nFor each issue found, search codebase for correct patterns:\n\n```bash\n# Find similar patterns in codebase\ngrep -r \"pattern\" src/ --include=\"*.ts\" | head -5\n```\n\n### 2.5 Check for Primitive Duplication\n\nFor each new interface, class, type alias, or utility module introduced in the diff:\n\n1. Search for similar existing abstractions:\n\n```bash\n# Replace {Name} with the new abstraction's name\ngrep -r \"interface {Name}\\|class {Name}\\|type {Name}\" packages/ --include=\"*.ts\" | head -10\n```\n\n2. Flag if the new abstraction duplicates or closely overlaps an existing one.\n3. Flag if a new utility function reimplements logic already available in a shared package.\n4. Note findings in the CLAUDE.md Compliance section with verdict: **EXTENDS** (extends existing primitive) or **DUPLICATE** (redundant with existing) or **NEW** (genuinely new, no existing primitive).\n\n**PHASE_2_CHECKPOINT:**\n- [ ] CLAUDE.md compliance checked\n- [ ] Bugs identified\n- [ ] Quality issues noted\n- [ ] Patterns found for fixes\n- [ ] Primitive duplication checked\n\n---\n\n## Phase 3: GENERATE - Create Artifact\n\nWrite to `$ARTIFACTS_DIR/review/code-review-findings.md`:\n\n```markdown\n# Code Review Findings: PR #{number}\n\n**Reviewer**: code-review-agent\n**Date**: {ISO timestamp}\n**Files Reviewed**: {count}\n\n---\n\n## Summary\n\n{2-3 sentence overview of code quality and main concerns}\n\n**Verdict**: {APPROVE | REQUEST_CHANGES | NEEDS_DISCUSSION}\n\n---\n\n## Findings\n\n### Finding 1: {Descriptive Title}\n\n**Severity**: CRITICAL | HIGH | MEDIUM | LOW\n**Category**: bug | style | performance | security | pattern-violation\n**Location**: `{file}:{line}`\n\n**Issue**:\n{Clear description of what's wrong}\n\n**Evidence**:\n```typescript\n// Current code at {file}:{line}\n{problematic code snippet}\n```\n\n**Why This Matters**:\n{Explain the impact - what could go wrong, why it violates standards}\n\n---\n\n#### Fix Suggestions\n\n| Option | Approach | Pros | Cons |\n|--------|----------|------|------|\n| A | {approach description} | {benefits} | {drawbacks} |\n| B | {alternative approach} | {benefits} | {drawbacks} |\n\n**Recommended**: Option {A/B}\n\n**Reasoning**:\n{Explain why this option is preferred, referencing:\n- Codebase patterns\n- CLAUDE.md rules\n- Best practices\n- Specific project context}\n\n**Recommended Fix**:\n```typescript\n// Suggested fix\n{corrected code}\n```\n\n**Codebase Pattern Reference**:\n```typescript\n// SOURCE: {file}:{lines}\n// This pattern shows how similar code is handled elsewhere\n{existing code from codebase}\n```\n\n---\n\n### Finding 2: {Title}\n\n{Same structure...}\n\n---\n\n## Statistics\n\n| Severity | Count | Auto-fixable |\n|----------|-------|--------------|\n| CRITICAL | {n} | {n} |\n| HIGH | {n} | {n} |\n| MEDIUM | {n} | {n} |\n| LOW | {n} | {n} |\n\n---\n\n## CLAUDE.md Compliance\n\n| Rule | Status | Notes |\n|------|--------|-------|\n| {rule from CLAUDE.md} | PASS/FAIL | {details} |\n| ... | ... | ... |\n\n---\n\n## Patterns Referenced\n\n| File | Lines | Pattern |\n|------|-------|---------|\n| `src/example.ts` | 42-50 | {what this pattern demonstrates} |\n| ... | ... | ... |\n\n---\n\n## Positive Observations\n\n{List things done well - good patterns, clean code, etc.}\n\n---\n\n## Metadata\n\n- **Agent**: code-review-agent\n- **Timestamp**: {ISO timestamp}\n- **Artifact**: `$ARTIFACTS_DIR/review/code-review-findings.md`\n```\n\n**PHASE_3_CHECKPOINT:**\n- [ ] Artifact file created\n- [ ] All findings have severity and location\n- [ ] Fix options provided with reasoning\n- [ ] Codebase patterns referenced\n\n---\n\n## Phase 4: VALIDATE - Check Artifact\n\n### 4.1 Verify File Exists\n\n```bash\ncat $ARTIFACTS_DIR/review/code-review-findings.md | head -20\n```\n\n### 4.2 Check Structure\n\nVerify artifact contains:\n- Summary with verdict\n- At least findings section (even if empty)\n- Statistics table\n- CLAUDE.md compliance table\n\n**PHASE_4_CHECKPOINT:**\n- [ ] Artifact file exists\n- [ ] Structure is complete\n- [ ] No placeholder text remaining\n\n---\n\n## Success Criteria\n\n- **CONTEXT_LOADED**: Scope and diff read successfully\n- **ANALYSIS_COMPLETE**: All changed files reviewed\n- **ARTIFACT_CREATED**: Findings file written\n- **PATTERNS_INCLUDED**: Each finding references codebase patterns\n- **OPTIONS_PROVIDED**: Multiple fix options where applicable\n", "archon-comment-quality-agent": "---\ndescription: Review code comments for accuracy, completeness, and maintainability\nargument-hint: (none - reads from scope artifact)\n---\n\n# Comment Quality Agent\n\n---\n\n## Your Mission\n\nAnalyze code comments for accuracy against actual code, identify comment rot, check documentation completeness, and ensure comments aid long-term maintainability. Produce a structured artifact with findings and recommendations.\n\n**Output artifact**: `$ARTIFACTS_DIR/review/comment-quality-findings.md`\n\n---\n\n## Phase 1: LOAD - Get Context\n\n### 1.1 Get PR Number from Registry\n\n```bash\nPR_NUMBER=$(cat $ARTIFACTS_DIR/.pr-number)\n```\n\n### 1.2 Read Scope\n\n```bash\ncat $ARTIFACTS_DIR/review/scope.md\n```\n\n**CRITICAL**: Check for \"NOT Building (Scope Limits)\" section. Items listed there are **intentionally excluded** - do NOT flag them as missing documentation or comment issues!\n\n### 1.3 Get PR Diff\n\n```bash\ngh pr diff {number}\n```\n\nFocus on:\n- New comments added\n- Comments near modified code\n- JSDoc/docstrings added or changed\n\n**PHASE_1_CHECKPOINT:**\n- [ ] PR number identified\n- [ ] Changed files with comments identified\n- [ ] Diff available\n\n---\n\n## Phase 2: ANALYZE - Review Comments\n\n### 2.1 Check Comment Accuracy\n\nFor each comment in changed code:\n- Does the comment accurately describe what the code does?\n- Is the comment up-to-date with the implementation?\n- Are parameter descriptions correct?\n- Are return value descriptions accurate?\n- Are edge cases documented correctly?\n\n### 2.2 Identify Comment Rot\n\nLook for:\n- Comments that describe old behavior\n- TODO/FIXME that should have been addressed\n- Outdated references (old file names, removed functions)\n- Comments that contradict the code\n\n### 2.3 Check Documentation Completeness\n\nEvaluate:\n- Are complex functions properly documented?\n- Are public APIs documented?\n- Are non-obvious algorithms explained?\n- Are magic numbers/constants explained?\n- Are important decisions documented?\n\n### 2.4 Assess Maintainability\n\nConsider:\n- Will future developers understand the \"why\"?\n- Are there redundant comments (just restating code)?\n- Is the signal-to-noise ratio good?\n- Are comments in the right places?\n\n**PHASE_2_CHECKPOINT:**\n- [ ] Comment accuracy verified\n- [ ] Comment rot identified\n- [ ] Completeness gaps found\n- [ ] Maintainability assessed\n\n---\n\n## Phase 3: GENERATE - Create Artifact\n\nWrite to `$ARTIFACTS_DIR/review/comment-quality-findings.md`:\n\n```markdown\n# Comment Quality Findings: PR #{number}\n\n**Reviewer**: comment-quality-agent\n**Date**: {ISO timestamp}\n**Comments Reviewed**: {count}\n\n---\n\n## Summary\n\n{2-3 sentence overview of comment quality}\n\n**Verdict**: {APPROVE | REQUEST_CHANGES | NEEDS_DISCUSSION}\n\n---\n\n## Findings\n\n### Finding 1: {Descriptive Title}\n\n**Severity**: CRITICAL | HIGH | MEDIUM | LOW\n**Category**: inaccurate | outdated | missing | redundant | misleading\n**Location**: `{file}:{line}`\n\n**Issue**:\n{Clear description of the comment problem}\n\n**Current Comment**:\n```typescript\n// {the problematic comment}\n{code the comment describes}\n```\n\n**Actual Code Behavior**:\n{What the code actually does vs what comment says}\n\n**Impact**:\n{How this could mislead future developers}\n\n---\n\n#### Fix Suggestions\n\n| Option | Approach | Pros | Cons |\n|--------|----------|------|------|\n| A | {update comment} | {benefits} | {drawbacks} |\n| B | {remove comment} | {benefits} | {drawbacks} |\n| C | {expand comment} | {benefits} | {drawbacks} |\n\n**Recommended**: Option {X}\n\n**Reasoning**:\n{Why this option:\n- Matches documentation standards\n- Provides value without being redundant\n- Will remain accurate over time}\n\n**Recommended Fix**:\n```typescript\n/**\n * {corrected/improved comment}\n *\n * @param {type} param - {accurate description}\n * @returns {type} - {accurate description}\n */\n{code}\n```\n\n**Good Comment Pattern**:\n```typescript\n// SOURCE: {file}:{lines}\n// Example of good documentation in this codebase\n{existing well-documented code}\n```\n\n---\n\n### Finding 2: {Title}\n\n{Same structure...}\n\n---\n\n## Comment Audit\n\n| Location | Type | Accurate | Up-to-date | Useful | Verdict |\n|----------|------|----------|------------|--------|---------|\n| `file:line` | JSDoc | YES/NO | YES/NO | YES/NO | GOOD/UPDATE/REMOVE |\n| ... | ... | ... | ... | ... | ... |\n\n---\n\n## Statistics\n\n| Severity | Count | Auto-fixable |\n|----------|-------|--------------|\n| CRITICAL | {n} | {n} |\n| HIGH | {n} | {n} |\n| MEDIUM | {n} | {n} |\n| LOW | {n} | {n} |\n\n---\n\n## Documentation Gaps\n\n| Code Area | What's Missing | Priority |\n|-----------|----------------|----------|\n| `function xyz()` | Parameter docs, return type | HIGH |\n| `class Abc` | Class purpose, usage example | MEDIUM |\n| ... | ... | ... |\n\n---\n\n## Comment Rot Found\n\n| Location | Comment Says | Code Does | Age |\n|----------|--------------|-----------|-----|\n| `file:line` | \"{old description}\" | {actual behavior} | {when introduced} |\n| ... | ... | ... | ... |\n\n---\n\n## Positive Observations\n\n{Well-documented code, helpful comments, good explanations}\n\n---\n\n## Metadata\n\n- **Agent**: comment-quality-agent\n- **Timestamp**: {ISO timestamp}\n- **Artifact**: `$ARTIFACTS_DIR/review/comment-quality-findings.md`\n```\n\n**PHASE_3_CHECKPOINT:**\n- [ ] Artifact file created\n- [ ] Comment accuracy verified\n- [ ] Comment rot documented\n- [ ] Documentation gaps listed\n\n---\n\n## Success Criteria\n\n- **COMMENTS_AUDITED**: All comments in changed code reviewed\n- **ACCURACY_CHECKED**: Comments verified against actual code\n- **ROT_IDENTIFIED**: Outdated comments found\n- **GAPS_DOCUMENTED**: Missing documentation noted\n", "archon-confirm-plan": "---\ndescription: Verify plan research is still valid - check patterns exist, code hasn't drifted\nargument-hint: (no arguments - reads from workflow artifacts)\n---\n\n# Confirm Plan Research\n\n**Workflow ID**: $WORKFLOW_ID\n\n---\n\n## Your Mission\n\nVerify that the plan's research is still valid before implementation begins.\n\nPlans can become stale:\n- Files may have been renamed or moved\n- Code patterns may have changed\n- APIs may have been updated\n\n**This step does NOT implement anything** - it only validates the plan is still accurate.\n\n---\n\n## Phase 1: LOAD - Read Context Artifact\n\n### 1.1 Load Plan Context\n\n```bash\ncat $ARTIFACTS_DIR/plan-context.md\n```\n\nIf not found, STOP with error:\n```\n❌ Plan context not found at $ARTIFACTS_DIR/plan-context.md\n\nRun archon-plan-setup first.\n```\n\n### 1.2 Extract Verification Targets\n\nFrom the context, identify:\n\n1. **Patterns to Mirror** - Files and line ranges to verify\n2. **Files to Change** - Files that will be created/updated\n3. **Validation Commands** - Commands that should work\n\n**PHASE_1_CHECKPOINT:**\n\n- [ ] Context artifact loaded\n- [ ] Patterns to verify extracted\n- [ ] Files to change identified\n\n---\n\n## Phase 2: VERIFY - Check Patterns Exist\n\n### 2.1 Verify Pattern Files\n\nFor each file in \"Patterns to Mirror\":\n\n1. Check if file exists:\n ```bash\n test -f {file-path} && echo \"EXISTS\" || echo \"MISSING\"\n ```\n\n2. If exists, read the referenced lines:\n ```bash\n sed -n '{start},{end}p' {file-path}\n ```\n\n3. Compare with what the plan expected (if plan included code snippets)\n\n### 2.2 Document Findings\n\nFor each pattern file:\n\n| File | Status | Notes |\n|------|--------|-------|\n| `src/adapters/telegram.ts` | ✅ EXISTS | Lines 11-23 match expected pattern |\n| `src/types/index.ts` | ✅ EXISTS | Interface still present |\n| `src/old-file.ts` | ❌ MISSING | File was renamed/deleted |\n| `src/changed.ts` | ⚠️ DRIFTED | Code structure changed significantly |\n\n### 2.3 Severity Assessment\n\n| Finding | Severity | Action |\n|---------|----------|--------|\n| File exists, code matches | ✅ OK | Proceed |\n| File exists, minor differences | ⚠️ WARNING | Note in artifact, proceed with caution |\n| File exists, major drift | 🟠 CONCERN | Flag for review, may need plan update |\n| File missing | ❌ BLOCKER | Stop, plan needs revision |\n\n**PHASE_2_CHECKPOINT:**\n\n- [ ] All pattern files checked\n- [ ] Findings documented\n- [ ] Severity assessed\n\n---\n\n## Phase 3: VERIFY - Check Target Locations\n\n### 3.1 Check Files to Create\n\nFor each file marked CREATE:\n\n1. Verify it doesn't already exist (would be unexpected):\n ```bash\n test -f {file-path} && echo \"ALREADY EXISTS\" || echo \"OK - will create\"\n ```\n\n2. Verify parent directory exists or can be created:\n ```bash\n dirname {file-path} | xargs test -d && echo \"DIR EXISTS\" || echo \"DIR WILL BE CREATED\"\n ```\n\n### 3.2 Check Files to Update\n\nFor each file marked UPDATE:\n\n1. Verify it exists:\n ```bash\n test -f {file-path} && echo \"EXISTS\" || echo \"MISSING\"\n ```\n\n2. If the plan references specific lines/functions, verify they exist\n\n**PHASE_3_CHECKPOINT:**\n\n- [ ] CREATE targets verified (don't exist yet)\n- [ ] UPDATE targets verified (do exist)\n\n---\n\n## Phase 4: VERIFY - Check Validation Commands\n\n### 4.1 Dry Run Validation Commands\n\nTest that the validation commands work (without expecting them to pass):\n\n```bash\n# Check type-check command exists\nbun run type-check --help 2>/dev/null || echo \"type-check not available\"\n\n# Check lint command exists\nbun run lint --help 2>/dev/null || echo \"lint not available\"\n\n# Check test command exists\nbun test --help 2>/dev/null || echo \"test not available\"\n```\n\n### 4.2 Document Command Availability\n\n| Command | Status |\n|---------|--------|\n| `bun run type-check` | ✅ Available |\n| `bun run lint` | ✅ Available |\n| `bun test` | ✅ Available |\n| `bun run build` | ✅ Available |\n\n**PHASE_4_CHECKPOINT:**\n\n- [ ] Validation commands tested\n- [ ] All required commands available\n\n---\n\n## Phase 5: ARTIFACT - Write Confirmation\n\n### 5.1 Write Confirmation Artifact\n\nWrite to `$ARTIFACTS_DIR/plan-confirmation.md`:\n\n```markdown\n# Plan Confirmation\n\n**Generated**: {YYYY-MM-DD HH:MM}\n**Workflow ID**: $WORKFLOW_ID\n**Status**: {CONFIRMED | WARNINGS | BLOCKED}\n\n---\n\n## Pattern Verification\n\n| Pattern | File | Status | Notes |\n|---------|------|--------|-------|\n| Constructor pattern | `src/adapters/telegram.ts:11-23` | ✅ | Matches expected |\n| Interface definition | `src/types/index.ts:49-74` | ✅ | Present |\n| ... | ... | ... | ... |\n\n**Pattern Summary**: {X} of {Y} patterns verified\n\n---\n\n## Target Files\n\n### Files to Create\n\n| File | Status |\n|------|--------|\n| `src/new-file.ts` | ✅ Does not exist (ready to create) |\n\n### Files to Update\n\n| File | Status |\n|------|--------|\n| `src/existing.ts` | ✅ Exists |\n\n---\n\n## Validation Commands\n\n| Command | Available |\n|---------|-----------|\n| `bun run type-check` | ✅ |\n| `bun run lint` | ✅ |\n| `bun test` | ✅ |\n| `bun run build` | ✅ |\n\n---\n\n## Issues Found\n\n{If no issues:}\nNo issues found. Plan research is valid.\n\n{If issues:}\n### Warnings\n\n- **{file}**: {description of drift or concern}\n\n### Blockers\n\n- **{file}**: {description of missing file or critical issue}\n\n---\n\n## Recommendation\n\n{One of:}\n- ✅ **PROCEED**: Plan research is valid, continue to implementation\n- ⚠️ **PROCEED WITH CAUTION**: Minor drift detected, implementation may need adjustments\n- ❌ **STOP**: Critical issues found, plan needs revision\n\n---\n\n## Next Step\n\n{If PROCEED or PROCEED WITH CAUTION:}\nContinue to `archon-implement-tasks` to execute the plan.\n\n{If STOP:}\nRevise the plan to address blockers, then re-run `archon-plan-setup`.\n```\n\n**PHASE_5_CHECKPOINT:**\n\n- [ ] Confirmation artifact written\n- [ ] Status clearly indicated\n- [ ] Issues documented\n\n---\n\n## Phase 6: OUTPUT - Report to User\n\n### If Confirmed (no blockers):\n\n```markdown\n## Plan Confirmed ✅\n\n**Workflow ID**: `$WORKFLOW_ID`\n**Status**: Ready for implementation\n\n### Verification Summary\n\n| Check | Result |\n|-------|--------|\n| Pattern files | ✅ {X}/{Y} verified |\n| Target files | ✅ Ready |\n| Validation commands | ✅ Available |\n\n{If warnings:}\n### Warnings\n\n- {warning 1}\n- {warning 2}\n\nThese are minor and shouldn't block implementation.\n\n### Artifact\n\nConfirmation written to: `$ARTIFACTS_DIR/plan-confirmation.md`\n\n### Next Step\n\nProceed to `archon-implement-tasks` to execute the plan.\n```\n\n### If Blocked:\n\n```markdown\n## Plan Blocked ❌\n\n**Workflow ID**: `$WORKFLOW_ID`\n**Status**: Cannot proceed\n\n### Blockers Found\n\n1. **{file}**: {description}\n2. **{file}**: {description}\n\n### Required Action\n\nThe plan references files or patterns that no longer exist. Options:\n\n1. **Update the plan** to reflect current codebase state\n2. **Restore missing files** if they were accidentally deleted\n3. **Re-run planning** with `/archon-plan` to generate a fresh plan\n\n### Artifact\n\nDetails written to: `$ARTIFACTS_DIR/plan-confirmation.md`\n```\n\n---\n\n## Success Criteria\n\n- **PATTERNS_VERIFIED**: All pattern files exist and are reasonably similar\n- **TARGETS_VALID**: CREATE files don't exist, UPDATE files do exist\n- **COMMANDS_AVAILABLE**: Validation commands can be run\n- **ARTIFACT_WRITTEN**: Confirmation artifact created with clear status\n", - "archon-create-plan": "---\ndescription: Create comprehensive feature implementation plan with codebase analysis and research\nargument-hint: \n---\n\n# Create Implementation Plan\n\n**Input**: $ARGUMENTS\n**Workflow ID**: $WORKFLOW_ID\n\n---\n\n## Your Mission\n\nTransform \"$ARGUMENTS\" into a battle-tested implementation plan through systematic codebase exploration, pattern extraction, and strategic research.\n\n**Core Principle**: PLAN ONLY - no code written. Create a context-rich document that enables one-pass implementation success.\n\n**Execution Order**: CODEBASE FIRST, RESEARCH SECOND. Solutions must fit existing patterns before introducing new ones.\n\n**Agent Strategy**: Use Task tool with subagent_type=\"Explore\" for codebase intelligence gathering. This ensures thorough pattern discovery before any external research.\n\n**Output**: `$ARTIFACTS_DIR/plan.md`\n\n---\n\n## Phase 0: DETECT - Input Type Resolution\n\n### 0.1 Determine Input Type\n\n| Input Pattern | Type | Action |\n|---------------|------|--------|\n| Ends with `.prd.md` | PRD file | Parse PRD, select next phase |\n| Ends with `.md` and contains \"Implementation Phases\" | PRD file | Parse PRD, select next phase |\n| File path that exists | Document | Read and extract feature description |\n| Free-form text | Description | Use directly as feature input |\n| Empty/blank | Error | STOP - require input |\n\n### 0.2 If PRD File Detected\n\n1. **Read the PRD file**\n2. **Parse the Implementation Phases table** - find rows with `Status: pending`\n3. **Check dependencies** - only select phases whose dependencies are `complete`\n4. **Select the next actionable phase:**\n - First pending phase with all dependencies complete\n - If multiple candidates with same dependencies, note parallelism opportunity\n\n5. **Extract phase context:**\n ```\n PHASE: {phase number and name}\n GOAL: {from phase details}\n SCOPE: {from phase details}\n SUCCESS SIGNAL: {from phase details}\n PRD CONTEXT: {problem statement, user, hypothesis from PRD}\n ```\n\n6. **Report selection to user:**\n ```\n PRD: {prd file path}\n Selected Phase: #{number} - {name}\n\n {If parallel phases available:}\n Note: Phase {X} can also run in parallel (in separate worktree).\n\n Proceeding with Phase #{number}...\n ```\n\n### 0.3 If Free-form Description\n\nProceed directly to Phase 1 with the input as feature description.\n\n**PHASE_0_CHECKPOINT:**\n\n- [ ] Input type determined\n- [ ] If PRD: next phase selected and dependencies verified\n- [ ] Feature description ready for Phase 1\n\n---\n\n## Phase 1: PARSE - Feature Understanding\n\n### 1.1 Discover Project Structure\n\n**CRITICAL**: Do NOT assume `src/` exists. Discover actual structure:\n\n```bash\n# List root contents\nls -la\n\n# Find main source directories\nls -la */ 2>/dev/null | head -50\n\n# Identify project type from config files\ncat package.json 2>/dev/null | head -20\ncat pyproject.toml 2>/dev/null | head -20\ncat Cargo.toml 2>/dev/null | head -20\ncat go.mod 2>/dev/null | head -20\n```\n\nCommon alternatives to `src/`:\n- `app/` (Next.js, Rails, Laravel)\n- `lib/` (Ruby gems, Elixir)\n- `packages/` (monorepos)\n- `cmd/`, `internal/`, `pkg/` (Go)\n- Root-level source files (Python, scripts)\n\n### 1.2 Read CLAUDE.md\n\n```bash\ncat CLAUDE.md\n```\n\nNote all coding standards, patterns, and rules that apply to this codebase.\n\n### 1.3 Extract from Input\n\n- Core problem being solved\n- User value and business impact\n- Feature type: NEW_CAPABILITY | ENHANCEMENT | REFACTOR | BUG_FIX\n- Complexity: LOW | MEDIUM | HIGH\n- Affected systems list\n\n### 1.4 Formulate User Story\n\n```\nAs a \nI want to \nSo that \n```\n\n**PHASE_1_CHECKPOINT:**\n\n- [ ] Project structure discovered\n- [ ] CLAUDE.md rules noted\n- [ ] Problem statement is specific and testable\n- [ ] User story follows correct format\n- [ ] Complexity assessment has rationale\n- [ ] Affected systems identified\n\n**GATE**: If requirements are AMBIGUOUS → STOP and ASK user for clarification before proceeding.\n\n---\n\n## Phase 2: EXPLORE - Codebase Intelligence\n\n**CRITICAL: Use Task tool with subagent_type=\"Explore\" with thoroughness=\"very thorough\"**\n\n### 2.1 Launch Explore Agent\n\n```\nExplore the codebase to find patterns, conventions, and integration points\nrelevant to implementing: [feature description].\n\nDISCOVER:\n1. Similar implementations - find analogous features with file:line references\n2. Naming conventions - extract actual examples of function/class/file naming\n3. Error handling patterns - how errors are created, thrown, caught\n4. Logging patterns - logger usage, message formats\n5. Type definitions - relevant interfaces and types\n6. Test patterns - test file structure, assertion styles\n7. Integration points - where new code connects to existing\n8. Dependencies - relevant libraries already in use\n\nReturn ACTUAL code snippets from codebase, not generic examples.\n```\n\n### 2.2 Document Discoveries\n\n**Format in table:**\n\n| Category | File:Lines | Pattern Description | Code Snippet |\n|----------|------------|---------------------|--------------|\n| NAMING | `src/features/X/service.ts:10-15` | camelCase functions | `export function createThing()` |\n| ERRORS | `src/features/X/errors.ts:5-20` | Custom error classes | `class ThingNotFoundError` |\n| LOGGING | `src/core/logging/index.ts:1-10` | getLogger pattern | `const logger = getLogger(\"domain\")` |\n| TESTS | `src/features/X/tests/service.test.ts:1-30` | describe/it blocks | `describe(\"service\", () => {` |\n| TYPES | `src/features/X/models.ts:1-20` | Type inference | `type Thing = typeof things.$inferSelect` |\n\n**PHASE_2_CHECKPOINT:**\n\n- [ ] Explore agent launched and completed successfully\n- [ ] At least 3 similar implementations found with file:line refs\n- [ ] Code snippets are ACTUAL (copy-pasted from codebase, not invented)\n- [ ] Integration points mapped with specific file paths\n- [ ] Dependencies cataloged with versions from package.json\n\n---\n\n## Phase 3: RESEARCH - External Documentation\n\n**ONLY AFTER Phase 2 is complete** - solutions must fit existing codebase patterns first.\n\n### 3.1 Search for Documentation\n\nUse WebSearch tool for:\n- Official documentation for involved libraries (match versions from package.json)\n- Known gotchas, breaking changes, deprecations\n- Security considerations and best practices\n- Performance optimization patterns\n\n### 3.2 Format References\n\n```markdown\n- [Library Docs v{version}](https://url#specific-section)\n - KEY_INSIGHT: {what we learned that affects implementation}\n - APPLIES_TO: {which task/file this affects}\n - GOTCHA: {potential pitfall and how to avoid}\n```\n\n**PHASE_3_CHECKPOINT:**\n\n- [ ] Documentation versions match package.json\n- [ ] URLs include specific section anchors (not just homepage)\n- [ ] Gotchas documented with mitigation strategies\n- [ ] No conflicting patterns between external docs and existing codebase\n\n---\n\n## Phase 4: DESIGN - UX Transformation\n\n### 4.1 Create ASCII Diagrams\n\n**Before State:**\n\n```\n╔═══════════════════════════════════════════════════════════════════════════════╗\n║ BEFORE STATE ║\n╠═══════════════════════════════════════════════════════════════════════════════╣\n║ ║\n║ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ ║\n║ │ Screen/ │ ──────► │ Action │ ──────► │ Result │ ║\n║ │ Component │ │ Current │ │ Current │ ║\n║ └─────────────┘ └─────────────┘ └─────────────┘ ║\n║ ║\n║ USER_FLOW: [describe current step-by-step experience] ║\n║ PAIN_POINT: [what's missing, broken, or inefficient] ║\n║ DATA_FLOW: [how data moves through the system currently] ║\n║ ║\n╚═══════════════════════════════════════════════════════════════════════════════╝\n```\n\n**After State:**\n\n```\n╔═══════════════════════════════════════════════════════════════════════════════╗\n║ AFTER STATE ║\n╠═══════════════════════════════════════════════════════════════════════════════╣\n║ ║\n║ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ ║\n║ │ Screen/ │ ──────► │ Action │ ──────► │ Result │ ║\n║ │ Component │ │ NEW │ │ NEW │ ║\n║ └─────────────┘ └─────────────┘ └─────────────┘ ║\n║ │ ║\n║ ▼ ║\n║ ┌─────────────┐ ║\n║ │ NEW_FEATURE │ ◄── [new capability added] ║\n║ └─────────────┘ ║\n║ ║\n║ USER_FLOW: [describe new step-by-step experience] ║\n║ VALUE_ADD: [what user gains from this change] ║\n║ DATA_FLOW: [how data moves through the system after] ║\n║ ║\n╚═══════════════════════════════════════════════════════════════════════════════╝\n```\n\n### 4.2 Document Interaction Changes\n\n| Location | Before | After | User_Action | Impact |\n|----------|--------|-------|-------------|--------|\n| `/route` | State A | State B | Click X | Can now Y |\n| `Component.tsx` | Missing feature | Has feature | Input Z | Gets result W |\n\n**PHASE_4_CHECKPOINT:**\n\n- [ ] Before state accurately reflects current system behavior\n- [ ] After state shows ALL new capabilities\n- [ ] Data flows are traceable from input to output\n- [ ] User value is explicit and measurable\n\n---\n\n## Phase 5: ARCHITECT - Strategic Design\n\n### 5.0 Primitives Inventory\n\nBefore designing the solution, audit existing building blocks:\n\n1. **What primitives already exist?** List the core abstractions in the codebase\n related to this feature — with file:line references from the Explore agent output.\n2. **Are they complete?** Do the existing primitives cover this use case, or do they\n have gaps that require extension?\n3. **Extend before adding** — can we extend an existing primitive rather than creating\n a new one? Prefer `implements ExistingInterface` over `interface NewInterface`.\n4. **Minimum primitive surface** — if new primitives ARE needed, what's the smallest\n addition that enables this feature and remains useful to future callers?\n5. **Dependency chain** — what must exist first? What does this feature unlock downstream?\n\n| Primitive | File:Lines | Complete? | Role in Feature |\n|-----------|-----------|-----------|----------------|\n| {name} | `path/to/file.ts:10-30` | Yes/Partial/No | {how it's used or extended} |\n\n### 5.1 Deep Analysis\n\nConsider (use extended thinking if needed):\n\n- **ARCHITECTURE_FIT**: How does this integrate with the existing architecture?\n- **EXECUTION_ORDER**: What must happen first → second → third?\n- **FAILURE_MODES**: Edge cases, race conditions, error scenarios?\n- **PERFORMANCE**: Will this scale? Database queries optimized?\n- **SECURITY**: Attack vectors? Data exposure risks? Auth/authz?\n- **MAINTAINABILITY**: Will future devs understand this code?\n\n### 5.2 Document Decisions\n\n```markdown\nAPPROACH_CHOSEN: [description]\nRATIONALE: [why this over alternatives - reference codebase patterns]\n\nALTERNATIVES_REJECTED:\n- [Alternative 1]: Rejected because [specific reason]\n- [Alternative 2]: Rejected because [specific reason]\n\nNOT_BUILDING (explicit scope limits):\n- [Item 1 - explicitly out of scope and why]\n- [Item 2 - explicitly out of scope and why]\n```\n\n**PHASE_5_CHECKPOINT:**\n\n- [ ] Approach aligns with existing architecture and patterns\n- [ ] Dependencies ordered correctly (types → repository → service → routes)\n- [ ] Edge cases identified with specific mitigation strategies\n- [ ] Scope boundaries are explicit and justified\n\n---\n\n## Phase 6: GENERATE - Write Plan File\n\n### 6.1 Create Artifact Directory\n\n```bash\n```\n\n### 6.2 Write Plan\n\nWrite to `$ARTIFACTS_DIR/plan.md`:\n\n```markdown\n# Feature: {Feature Name}\n\n## Summary\n\n{One paragraph: What we're building and high-level approach}\n\n## User Story\n\nAs a {user type}\nI want to {action}\nSo that {benefit}\n\n## Problem Statement\n\n{Specific problem this solves - must be testable}\n\n## Solution Statement\n\n{How we're solving it - architecture overview}\n\n## Metadata\n\n| Field | Value |\n|-------|-------|\n| Type | NEW_CAPABILITY / ENHANCEMENT / REFACTOR / BUG_FIX |\n| Complexity | LOW / MEDIUM / HIGH |\n| Systems Affected | {comma-separated list} |\n| Dependencies | {external libs/services with versions} |\n| Estimated Tasks | {count} |\n\n---\n\n## UX Design\n\n### Before State\n\n{ASCII diagram - current user experience with data flows}\n\n### After State\n\n{ASCII diagram - new user experience with data flows}\n\n### Interaction Changes\n\n| Location | Before | After | User Impact |\n|----------|--------|-------|-------------|\n| {path/component} | {old behavior} | {new behavior} | {what changes for user} |\n\n---\n\n## Mandatory Reading\n\n**CRITICAL: Implementation agent MUST read these files before starting any task:**\n\n| Priority | File | Lines | Why Read This |\n|----------|------|-------|---------------|\n| P0 | `path/to/critical.ts` | 10-50 | Pattern to MIRROR exactly |\n| P1 | `path/to/types.ts` | 1-30 | Types to IMPORT |\n| P2 | `path/to/test.ts` | all | Test pattern to FOLLOW |\n\n**External Documentation:**\n\n| Source | Section | Why Needed |\n|--------|---------|------------|\n| [Lib Docs v{version}](url#anchor) | {section name} | {specific reason} |\n\n---\n\n## Patterns to Mirror\n\n**NAMING_CONVENTION:**\n```typescript\n// SOURCE: {file:lines}\n// COPY THIS PATTERN:\n{actual code snippet from codebase}\n```\n\n**ERROR_HANDLING:**\n```typescript\n// SOURCE: {file:lines}\n// COPY THIS PATTERN:\n{actual code snippet from codebase}\n```\n\n**LOGGING_PATTERN:**\n```typescript\n// SOURCE: {file:lines}\n// COPY THIS PATTERN:\n{actual code snippet from codebase}\n```\n\n**TEST_STRUCTURE:**\n```typescript\n// SOURCE: {file:lines}\n// COPY THIS PATTERN:\n{actual code snippet from codebase}\n```\n\n---\n\n## Files to Change\n\n| File | Action | Justification |\n|------|--------|---------------|\n| `src/features/new/models.ts` | CREATE | Type definitions |\n| `src/features/new/service.ts` | CREATE | Business logic |\n| `src/existing/index.ts` | UPDATE | Add integration |\n\n---\n\n## NOT Building (Scope Limits)\n\nExplicit exclusions to prevent scope creep:\n\n- {Item 1 - explicitly out of scope and why}\n- {Item 2 - explicitly out of scope and why}\n\n---\n\n## Step-by-Step Tasks\n\nExecute in order. Each task is atomic and independently verifiable.\n\n### Task 1: {CREATE/UPDATE} `{file path}`\n\n- **ACTION**: {CREATE new file / UPDATE existing file}\n- **IMPLEMENT**: {specific what to implement}\n- **MIRROR**: `{source-file:lines}` - follow this pattern exactly\n- **IMPORTS**: `{specific imports needed}`\n- **GOTCHA**: {known issue to avoid}\n- **VALIDATE**: `{validation-command}` - must pass before next task\n\n### Task 2: {CREATE/UPDATE} `{file path}`\n\n{... repeat for each task ...}\n\n---\n\n## Testing Strategy\n\n### Unit Tests to Write\n\n| Test File | Test Cases | Validates |\n|-----------|------------|-----------|\n| `src/features/new/tests/service.test.ts` | CRUD ops, edge cases | Business logic |\n\n### Edge Cases Checklist\n\n- [ ] Empty string inputs\n- [ ] Missing required fields\n- [ ] Unauthorized access attempts\n- [ ] Not found scenarios\n- [ ] {feature-specific edge case}\n\n---\n\n## Validation Commands\n\n### Level 1: STATIC_ANALYSIS\n\n```bash\n{runner} run type-check && {runner} run lint\n```\n\n**EXPECT**: Exit 0, no errors or warnings\n\n### Level 2: UNIT_TESTS\n\n```bash\n{runner} test {path/to/feature/tests}\n```\n\n**EXPECT**: All tests pass\n\n### Level 3: FULL_SUITE\n\n```bash\n{runner} run validate\n```\n\n**EXPECT**: All tests pass, build succeeds\n\n---\n\n## Acceptance Criteria\n\n- [ ] All specified functionality implemented per user story\n- [ ] Level 1-3 validation commands pass with exit 0\n- [ ] Code mirrors existing patterns exactly (naming, structure, logging)\n- [ ] No regressions in existing tests\n- [ ] UX matches \"After State\" diagram\n\n---\n\n## Completion Checklist\n\n- [ ] All tasks completed in dependency order\n- [ ] Each task validated immediately after completion\n- [ ] All acceptance criteria met\n\n---\n\n## Risks and Mitigations\n\n| Risk | Likelihood | Impact | Mitigation |\n|------|------------|--------|------------|\n| {Risk description} | LOW/MED/HIGH | LOW/MED/HIGH | {Specific prevention/handling strategy} |\n\n---\n\n## Notes\n\n{Additional context, design decisions, trade-offs, future considerations}\n```\n\n### 6.3 If Input Was PRD\n\nAlso update the PRD file:\n1. Change the phase's Status from `pending` to `in-progress`\n2. Add the plan file path to the PRP Plan column\n\n**PHASE_6_CHECKPOINT:**\n\n- [ ] Plan file written to `$ARTIFACTS_DIR/plan.md`\n- [ ] All sections populated with actual codebase data\n- [ ] If PRD: source file updated\n\n---\n\n## Phase 7: VERIFY - Plan Quality Check\n\n### 7.1 Context Completeness\n\n- [ ] All patterns from Explore agent documented with file:line references\n- [ ] External docs versioned to match package.json\n- [ ] Integration points mapped with specific file paths\n- [ ] Gotchas captured with mitigation strategies\n- [ ] Every task has at least one executable validation command\n\n### 7.2 Implementation Readiness\n\n- [ ] Tasks ordered by dependency (can execute top-to-bottom)\n- [ ] Each task is atomic and independently testable\n- [ ] No placeholders - all content is specific and actionable\n- [ ] Pattern references include actual code snippets (copy-pasted, not invented)\n\n### 7.3 Pattern Faithfulness\n\n- [ ] Every new file mirrors existing codebase style exactly\n- [ ] No unnecessary abstractions introduced\n- [ ] Naming follows discovered conventions\n- [ ] Error/logging patterns match existing\n- [ ] Test structure matches existing tests\n\n### 7.4 No Prior Knowledge Test\n\n**Could an agent unfamiliar with this codebase implement using ONLY the plan?**\n\nIf NO → add missing context to plan.\n\n**PHASE_7_CHECKPOINT:**\n\n- [ ] All verification checks pass\n- [ ] Plan is self-contained\n\n---\n\n## Phase 8: OUTPUT - Report to User\n\n```markdown\n## Plan Created\n\n**File**: `$ARTIFACTS_DIR/plan.md`\n**Workflow ID**: `$WORKFLOW_ID`\n\n{If from PRD:}\n**Source PRD**: `{prd-file-path}`\n**Phase**: #{number} - {phase name}\n**PRD Updated**: Status set to `in-progress`, plan linked\n\n{If parallel phases available:}\n**Parallel Opportunity**: Phase {X} can run concurrently in a separate worktree.\n\n---\n\n### Summary\n\n{2-3 sentence feature overview}\n\n### Metadata\n\n| Field | Value |\n|-------|-------|\n| Complexity | {LOW/MEDIUM/HIGH} |\n| Files to CREATE | {N} |\n| Files to UPDATE | {M} |\n| Total Tasks | {K} |\n\n### Key Patterns Discovered\n\n- {Pattern 1 from Explore agent with file:line}\n- {Pattern 2 from Explore agent with file:line}\n- {Pattern 3 from Explore agent with file:line}\n\n### External Research\n\n- {Key doc 1 with version}\n- {Key doc 2 with version}\n\n### UX Transformation\n\n- **BEFORE**: {one-line current state}\n- **AFTER**: {one-line new state}\n\n### Risks\n\n- {Primary risk}: {mitigation}\n\n### Confidence Score\n\n**{1-10}/10** for one-pass implementation success\n\n{Rationale for score}\n\n---\n\n### Next Step\n\nPlan ready. Proceeding to implementation setup.\n```\n\n---\n\n## Success Criteria\n\n- **CONTEXT_COMPLETE**: All patterns, gotchas, integration points documented from actual codebase via Explore agent\n- **IMPLEMENTATION_READY**: Tasks executable top-to-bottom without questions, research, or clarification\n- **PATTERN_FAITHFUL**: Every new file mirrors existing codebase style exactly\n- **VALIDATION_DEFINED**: Every task has executable verification command\n- **UX_DOCUMENTED**: Before/After transformation is visually clear with data flows\n- **ONE_PASS_TARGET**: Confidence score 8+ indicates high likelihood of first-attempt success\n- **ARTIFACT_WRITTEN**: Plan saved to `$ARTIFACTS_DIR/plan.md`\n", + "archon-create-plan": "---\ndescription: Create comprehensive feature implementation plan with codebase analysis and research\nargument-hint: \n---\n\n# Create Implementation Plan\n\n**Input**: $ARGUMENTS\n**Workflow ID**: $WORKFLOW_ID\n\n---\n\n## Your Mission\n\nTransform \"$ARGUMENTS\" into a battle-tested implementation plan through systematic codebase exploration, pattern extraction, and strategic research.\n\n**Core Principle**: PLAN ONLY - no code written. Create a context-rich document that enables one-pass implementation success.\n\n**Execution Order**: CODEBASE FIRST, RESEARCH SECOND. Solutions must fit existing patterns before introducing new ones.\n\n**Agent Strategy**: Use Task tool with subagent_type=\"Explore\" for codebase intelligence gathering. This ensures thorough pattern discovery before any external research.\n\n**Output**: `$ARTIFACTS_DIR/plan.md`\n\n---\n\n## Phase 0: DETECT - Input Type Resolution\n\n### 0.1 Determine Input Type\n\n| Input Pattern | Type | Action |\n|---------------|------|--------|\n| Ends with `.prd.md` | PRD file | Parse PRD, select next phase |\n| Ends with `.md` and contains \"Implementation Phases\" | PRD file | Parse PRD, select next phase |\n| File path that exists | Document | Read and extract feature description |\n| Free-form text | Description | Use directly as feature input |\n| Empty/blank | Error | STOP - require input |\n\n### 0.1a If the input is a GitHub issue: comments outrank the body\n\nFetch the issue **with its comments**, and treat them as authoritative:\n\n```bash\ngh issue view {number} --json title,body,labels,comments,state,url,author\n```\n\n- **Read every comment before planning.** A later maintainer comment supersedes\n the body wherever they disagree — the body is the opening position, not the\n specification.\n- **A comment stating a decision IS the specification.** If one settles a shape,\n a field list, an interface, or an explicit \"do X, not Y\", plan that. Do not\n re-derive the choice from the body and do not compromise between them.\n- **Follow linked issues.** When the body or a comment points at another issue\n (`#1234` or a URL) for a decision or contract, fetch that issue and its\n comments too. One level of following is enough.\n- **If the body and a decision conflict, record which you followed** in the plan.\n A silent choice is the failure mode here.\n\nOn 2026-08-03 a run planned from an issue body while a maintainer comment on that\nsame issue — already present in the fetched input — specified a different design.\nThe resulting PR was discarded. The data was there; nothing said it outranked the\nbody.\n\n### 0.2 If PRD File Detected\n\n1. **Read the PRD file**\n2. **Parse the Implementation Phases table** - find rows with `Status: pending`\n3. **Check dependencies** - only select phases whose dependencies are `complete`\n4. **Select the next actionable phase:**\n - First pending phase with all dependencies complete\n - If multiple candidates with same dependencies, note parallelism opportunity\n\n5. **Extract phase context:**\n ```\n PHASE: {phase number and name}\n GOAL: {from phase details}\n SCOPE: {from phase details}\n SUCCESS SIGNAL: {from phase details}\n PRD CONTEXT: {problem statement, user, hypothesis from PRD}\n ```\n\n6. **Report selection to user:**\n ```\n PRD: {prd file path}\n Selected Phase: #{number} - {name}\n\n {If parallel phases available:}\n Note: Phase {X} can also run in parallel (in separate worktree).\n\n Proceeding with Phase #{number}...\n ```\n\n### 0.3 If Free-form Description\n\nProceed directly to Phase 1 with the input as feature description.\n\n**PHASE_0_CHECKPOINT:**\n\n- [ ] Input type determined\n- [ ] If PRD: next phase selected and dependencies verified\n- [ ] Feature description ready for Phase 1\n\n---\n\n## Phase 1: PARSE - Feature Understanding\n\n### 1.1 Discover Project Structure\n\n**CRITICAL**: Do NOT assume `src/` exists. Discover actual structure:\n\n```bash\n# List root contents\nls -la\n\n# Find main source directories\nls -la */ 2>/dev/null | head -50\n\n# Identify project type from config files\ncat package.json 2>/dev/null | head -20\ncat pyproject.toml 2>/dev/null | head -20\ncat Cargo.toml 2>/dev/null | head -20\ncat go.mod 2>/dev/null | head -20\n```\n\nCommon alternatives to `src/`:\n- `app/` (Next.js, Rails, Laravel)\n- `lib/` (Ruby gems, Elixir)\n- `packages/` (monorepos)\n- `cmd/`, `internal/`, `pkg/` (Go)\n- Root-level source files (Python, scripts)\n\n### 1.2 Read CLAUDE.md\n\n```bash\ncat CLAUDE.md\n```\n\nNote all coding standards, patterns, and rules that apply to this codebase.\n\n### 1.3 Extract from Input\n\n- Core problem being solved\n- User value and business impact\n- Feature type: NEW_CAPABILITY | ENHANCEMENT | REFACTOR | BUG_FIX\n- Complexity: LOW | MEDIUM | HIGH\n- Affected systems list\n\n### 1.4 Formulate User Story\n\n```\nAs a \nI want to \nSo that \n```\n\n**PHASE_1_CHECKPOINT:**\n\n- [ ] Project structure discovered\n- [ ] CLAUDE.md rules noted\n- [ ] Problem statement is specific and testable\n- [ ] User story follows correct format\n- [ ] Complexity assessment has rationale\n- [ ] Affected systems identified\n\n**GATE**: If requirements are AMBIGUOUS → STOP and ASK user for clarification before proceeding.\n\n---\n\n## Phase 2: EXPLORE - Codebase Intelligence\n\n**CRITICAL: Use Task tool with subagent_type=\"Explore\" with thoroughness=\"very thorough\"**\n\n### 2.1 Launch Explore Agent\n\n```\nExplore the codebase to find patterns, conventions, and integration points\nrelevant to implementing: [feature description].\n\nDISCOVER:\n1. Similar implementations - find analogous features with file:line references\n2. Naming conventions - extract actual examples of function/class/file naming\n3. Error handling patterns - how errors are created, thrown, caught\n4. Logging patterns - logger usage, message formats\n5. Type definitions - relevant interfaces and types\n6. Test patterns - test file structure, assertion styles\n7. Integration points - where new code connects to existing\n8. Dependencies - relevant libraries already in use\n\nReturn ACTUAL code snippets from codebase, not generic examples.\n```\n\n### 2.2 Document Discoveries\n\n**Format in table:**\n\n| Category | File:Lines | Pattern Description | Code Snippet |\n|----------|------------|---------------------|--------------|\n| NAMING | `src/features/X/service.ts:10-15` | camelCase functions | `export function createThing()` |\n| ERRORS | `src/features/X/errors.ts:5-20` | Custom error classes | `class ThingNotFoundError` |\n| LOGGING | `src/core/logging/index.ts:1-10` | getLogger pattern | `const logger = getLogger(\"domain\")` |\n| TESTS | `src/features/X/tests/service.test.ts:1-30` | describe/it blocks | `describe(\"service\", () => {` |\n| TYPES | `src/features/X/models.ts:1-20` | Type inference | `type Thing = typeof things.$inferSelect` |\n\n**PHASE_2_CHECKPOINT:**\n\n- [ ] Explore agent launched and completed successfully\n- [ ] At least 3 similar implementations found with file:line refs\n- [ ] Code snippets are ACTUAL (copy-pasted from codebase, not invented)\n- [ ] Integration points mapped with specific file paths\n- [ ] Dependencies cataloged with versions from package.json\n\n---\n\n## Phase 3: RESEARCH - External Documentation\n\n**ONLY AFTER Phase 2 is complete** - solutions must fit existing codebase patterns first.\n\n### 3.1 Search for Documentation\n\nUse WebSearch tool for:\n- Official documentation for involved libraries (match versions from package.json)\n- Known gotchas, breaking changes, deprecations\n- Security considerations and best practices\n- Performance optimization patterns\n\n### 3.2 Format References\n\n```markdown\n- [Library Docs v{version}](https://url#specific-section)\n - KEY_INSIGHT: {what we learned that affects implementation}\n - APPLIES_TO: {which task/file this affects}\n - GOTCHA: {potential pitfall and how to avoid}\n```\n\n**PHASE_3_CHECKPOINT:**\n\n- [ ] Documentation versions match package.json\n- [ ] URLs include specific section anchors (not just homepage)\n- [ ] Gotchas documented with mitigation strategies\n- [ ] No conflicting patterns between external docs and existing codebase\n\n---\n\n## Phase 4: DESIGN - UX Transformation\n\n### 4.1 Create ASCII Diagrams\n\n**Before State:**\n\n```\n╔═══════════════════════════════════════════════════════════════════════════════╗\n║ BEFORE STATE ║\n╠═══════════════════════════════════════════════════════════════════════════════╣\n║ ║\n║ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ ║\n║ │ Screen/ │ ──────► │ Action │ ──────► │ Result │ ║\n║ │ Component │ │ Current │ │ Current │ ║\n║ └─────────────┘ └─────────────┘ └─────────────┘ ║\n║ ║\n║ USER_FLOW: [describe current step-by-step experience] ║\n║ PAIN_POINT: [what's missing, broken, or inefficient] ║\n║ DATA_FLOW: [how data moves through the system currently] ║\n║ ║\n╚═══════════════════════════════════════════════════════════════════════════════╝\n```\n\n**After State:**\n\n```\n╔═══════════════════════════════════════════════════════════════════════════════╗\n║ AFTER STATE ║\n╠═══════════════════════════════════════════════════════════════════════════════╣\n║ ║\n║ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ ║\n║ │ Screen/ │ ──────► │ Action │ ──────► │ Result │ ║\n║ │ Component │ │ NEW │ │ NEW │ ║\n║ └─────────────┘ └─────────────┘ └─────────────┘ ║\n║ │ ║\n║ ▼ ║\n║ ┌─────────────┐ ║\n║ │ NEW_FEATURE │ ◄── [new capability added] ║\n║ └─────────────┘ ║\n║ ║\n║ USER_FLOW: [describe new step-by-step experience] ║\n║ VALUE_ADD: [what user gains from this change] ║\n║ DATA_FLOW: [how data moves through the system after] ║\n║ ║\n╚═══════════════════════════════════════════════════════════════════════════════╝\n```\n\n### 4.2 Document Interaction Changes\n\n| Location | Before | After | User_Action | Impact |\n|----------|--------|-------|-------------|--------|\n| `/route` | State A | State B | Click X | Can now Y |\n| `Component.tsx` | Missing feature | Has feature | Input Z | Gets result W |\n\n**PHASE_4_CHECKPOINT:**\n\n- [ ] Before state accurately reflects current system behavior\n- [ ] After state shows ALL new capabilities\n- [ ] Data flows are traceable from input to output\n- [ ] User value is explicit and measurable\n\n---\n\n## Phase 5: ARCHITECT - Strategic Design\n\n### 5.0 Primitives Inventory\n\nBefore designing the solution, audit existing building blocks:\n\n1. **What primitives already exist?** List the core abstractions in the codebase\n related to this feature — with file:line references from the Explore agent output.\n2. **Are they complete?** Do the existing primitives cover this use case, or do they\n have gaps that require extension?\n3. **Extend before adding** — can we extend an existing primitive rather than creating\n a new one? Prefer `implements ExistingInterface` over `interface NewInterface`.\n4. **Minimum primitive surface** — if new primitives ARE needed, what's the smallest\n addition that enables this feature and remains useful to future callers?\n5. **Dependency chain** — what must exist first? What does this feature unlock downstream?\n\n| Primitive | File:Lines | Complete? | Role in Feature |\n|-----------|-----------|-----------|----------------|\n| {name} | `path/to/file.ts:10-30` | Yes/Partial/No | {how it's used or extended} |\n\n### 5.1 Deep Analysis\n\nConsider (use extended thinking if needed):\n\n- **ARCHITECTURE_FIT**: How does this integrate with the existing architecture?\n- **EXECUTION_ORDER**: What must happen first → second → third?\n- **FAILURE_MODES**: Edge cases, race conditions, error scenarios?\n- **PERFORMANCE**: Will this scale? Database queries optimized?\n- **SECURITY**: Attack vectors? Data exposure risks? Auth/authz?\n- **MAINTAINABILITY**: Will future devs understand this code?\n\n### 5.2 Document Decisions\n\n```markdown\nAPPROACH_CHOSEN: [description]\nRATIONALE: [why this over alternatives - reference codebase patterns]\n\nALTERNATIVES_REJECTED:\n- [Alternative 1]: Rejected because [specific reason]\n- [Alternative 2]: Rejected because [specific reason]\n\nNOT_BUILDING (explicit scope limits):\n- [Item 1 - explicitly out of scope and why]\n- [Item 2 - explicitly out of scope and why]\n```\n\n**PHASE_5_CHECKPOINT:**\n\n- [ ] Approach aligns with existing architecture and patterns\n- [ ] Dependencies ordered correctly (types → repository → service → routes)\n- [ ] Edge cases identified with specific mitigation strategies\n- [ ] Scope boundaries are explicit and justified\n\n---\n\n## Phase 6: GENERATE - Write Plan File\n\n### 6.1 Create Artifact Directory\n\n```bash\n```\n\n### 6.2 Write Plan\n\nWrite to `$ARTIFACTS_DIR/plan.md`:\n\n```markdown\n# Feature: {Feature Name}\n\n## Summary\n\n{One paragraph: What we're building and high-level approach}\n\n## User Story\n\nAs a {user type}\nI want to {action}\nSo that {benefit}\n\n## Problem Statement\n\n{Specific problem this solves - must be testable}\n\n## Solution Statement\n\n{How we're solving it - architecture overview}\n\n## Metadata\n\n| Field | Value |\n|-------|-------|\n| Type | NEW_CAPABILITY / ENHANCEMENT / REFACTOR / BUG_FIX |\n| Complexity | LOW / MEDIUM / HIGH |\n| Systems Affected | {comma-separated list} |\n| Dependencies | {external libs/services with versions} |\n| Estimated Tasks | {count} |\n\n---\n\n## UX Design\n\n### Before State\n\n{ASCII diagram - current user experience with data flows}\n\n### After State\n\n{ASCII diagram - new user experience with data flows}\n\n### Interaction Changes\n\n| Location | Before | After | User Impact |\n|----------|--------|-------|-------------|\n| {path/component} | {old behavior} | {new behavior} | {what changes for user} |\n\n---\n\n## Mandatory Reading\n\n**CRITICAL: Implementation agent MUST read these files before starting any task:**\n\n| Priority | File | Lines | Why Read This |\n|----------|------|-------|---------------|\n| P0 | `path/to/critical.ts` | 10-50 | Pattern to MIRROR exactly |\n| P1 | `path/to/types.ts` | 1-30 | Types to IMPORT |\n| P2 | `path/to/test.ts` | all | Test pattern to FOLLOW |\n\n**External Documentation:**\n\n| Source | Section | Why Needed |\n|--------|---------|------------|\n| [Lib Docs v{version}](url#anchor) | {section name} | {specific reason} |\n\n---\n\n## Patterns to Mirror\n\n**NAMING_CONVENTION:**\n```typescript\n// SOURCE: {file:lines}\n// COPY THIS PATTERN:\n{actual code snippet from codebase}\n```\n\n**ERROR_HANDLING:**\n```typescript\n// SOURCE: {file:lines}\n// COPY THIS PATTERN:\n{actual code snippet from codebase}\n```\n\n**LOGGING_PATTERN:**\n```typescript\n// SOURCE: {file:lines}\n// COPY THIS PATTERN:\n{actual code snippet from codebase}\n```\n\n**TEST_STRUCTURE:**\n```typescript\n// SOURCE: {file:lines}\n// COPY THIS PATTERN:\n{actual code snippet from codebase}\n```\n\n---\n\n## Files to Change\n\n| File | Action | Justification |\n|------|--------|---------------|\n| `src/features/new/models.ts` | CREATE | Type definitions |\n| `src/features/new/service.ts` | CREATE | Business logic |\n| `src/existing/index.ts` | UPDATE | Add integration |\n\n---\n\n## NOT Building (Scope Limits)\n\nExplicit exclusions to prevent scope creep:\n\n- {Item 1 - explicitly out of scope and why}\n- {Item 2 - explicitly out of scope and why}\n\n---\n\n## Step-by-Step Tasks\n\nExecute in order. Each task is atomic and independently verifiable.\n\n### Task 1: {CREATE/UPDATE} `{file path}`\n\n- **ACTION**: {CREATE new file / UPDATE existing file}\n- **IMPLEMENT**: {specific what to implement}\n- **MIRROR**: `{source-file:lines}` - follow this pattern exactly\n- **IMPORTS**: `{specific imports needed}`\n- **GOTCHA**: {known issue to avoid}\n- **VALIDATE**: `{validation-command}` - must pass before next task\n\n### Task 2: {CREATE/UPDATE} `{file path}`\n\n{... repeat for each task ...}\n\n---\n\n## Testing Strategy\n\n### Unit Tests to Write\n\n| Test File | Test Cases | Validates |\n|-----------|------------|-----------|\n| `src/features/new/tests/service.test.ts` | CRUD ops, edge cases | Business logic |\n\n### Edge Cases Checklist\n\n- [ ] Empty string inputs\n- [ ] Missing required fields\n- [ ] Unauthorized access attempts\n- [ ] Not found scenarios\n- [ ] {feature-specific edge case}\n\n---\n\n## Validation Commands\n\n### Level 1: STATIC_ANALYSIS\n\n```bash\n{runner} run type-check && {runner} run lint\n```\n\n**EXPECT**: Exit 0, no errors or warnings\n\n### Level 2: UNIT_TESTS\n\n```bash\n{runner} test {path/to/feature/tests}\n```\n\n**EXPECT**: All tests pass\n\n### Level 3: FULL_SUITE\n\n```bash\n{runner} run validate\n```\n\n**EXPECT**: All tests pass, build succeeds\n\n---\n\n## Acceptance Criteria\n\n- [ ] All specified functionality implemented per user story\n- [ ] Level 1-3 validation commands pass with exit 0\n- [ ] Code mirrors existing patterns exactly (naming, structure, logging)\n- [ ] No regressions in existing tests\n- [ ] UX matches \"After State\" diagram\n\n---\n\n## Completion Checklist\n\n- [ ] All tasks completed in dependency order\n- [ ] Each task validated immediately after completion\n- [ ] All acceptance criteria met\n\n---\n\n## Risks and Mitigations\n\n| Risk | Likelihood | Impact | Mitigation |\n|------|------------|--------|------------|\n| {Risk description} | LOW/MED/HIGH | LOW/MED/HIGH | {Specific prevention/handling strategy} |\n\n---\n\n## Notes\n\n{Additional context, design decisions, trade-offs, future considerations}\n```\n\n### 6.3 If Input Was PRD\n\nAlso update the PRD file:\n1. Change the phase's Status from `pending` to `in-progress`\n2. Add the plan file path to the PRP Plan column\n\n**PHASE_6_CHECKPOINT:**\n\n- [ ] Plan file written to `$ARTIFACTS_DIR/plan.md`\n- [ ] All sections populated with actual codebase data\n- [ ] If PRD: source file updated\n\n---\n\n## Phase 7: VERIFY - Plan Quality Check\n\n### 7.1 Context Completeness\n\n- [ ] All patterns from Explore agent documented with file:line references\n- [ ] External docs versioned to match package.json\n- [ ] Integration points mapped with specific file paths\n- [ ] Gotchas captured with mitigation strategies\n- [ ] Every task has at least one executable validation command\n\n### 7.2 Implementation Readiness\n\n- [ ] Tasks ordered by dependency (can execute top-to-bottom)\n- [ ] Each task is atomic and independently testable\n- [ ] No placeholders - all content is specific and actionable\n- [ ] Pattern references include actual code snippets (copy-pasted, not invented)\n\n### 7.3 Pattern Faithfulness\n\n- [ ] Every new file mirrors existing codebase style exactly\n- [ ] No unnecessary abstractions introduced\n- [ ] Naming follows discovered conventions\n- [ ] Error/logging patterns match existing\n- [ ] Test structure matches existing tests\n\n### 7.4 No Prior Knowledge Test\n\n**Could an agent unfamiliar with this codebase implement using ONLY the plan?**\n\nIf NO → add missing context to plan.\n\n**PHASE_7_CHECKPOINT:**\n\n- [ ] All verification checks pass\n- [ ] Plan is self-contained\n\n---\n\n## Phase 8: OUTPUT - Report to User\n\n```markdown\n## Plan Created\n\n**File**: `$ARTIFACTS_DIR/plan.md`\n**Workflow ID**: `$WORKFLOW_ID`\n\n{If from PRD:}\n**Source PRD**: `{prd-file-path}`\n**Phase**: #{number} - {phase name}\n**PRD Updated**: Status set to `in-progress`, plan linked\n\n{If parallel phases available:}\n**Parallel Opportunity**: Phase {X} can run concurrently in a separate worktree.\n\n---\n\n### Summary\n\n{2-3 sentence feature overview}\n\n### Metadata\n\n| Field | Value |\n|-------|-------|\n| Complexity | {LOW/MEDIUM/HIGH} |\n| Files to CREATE | {N} |\n| Files to UPDATE | {M} |\n| Total Tasks | {K} |\n\n### Key Patterns Discovered\n\n- {Pattern 1 from Explore agent with file:line}\n- {Pattern 2 from Explore agent with file:line}\n- {Pattern 3 from Explore agent with file:line}\n\n### External Research\n\n- {Key doc 1 with version}\n- {Key doc 2 with version}\n\n### UX Transformation\n\n- **BEFORE**: {one-line current state}\n- **AFTER**: {one-line new state}\n\n### Risks\n\n- {Primary risk}: {mitigation}\n\n### Confidence Score\n\n**{1-10}/10** for one-pass implementation success\n\n{Rationale for score}\n\n---\n\n### Next Step\n\nPlan ready. Proceeding to implementation setup.\n```\n\n---\n\n## Success Criteria\n\n- **CONTEXT_COMPLETE**: All patterns, gotchas, integration points documented from actual codebase via Explore agent\n- **IMPLEMENTATION_READY**: Tasks executable top-to-bottom without questions, research, or clarification\n- **PATTERN_FAITHFUL**: Every new file mirrors existing codebase style exactly\n- **VALIDATION_DEFINED**: Every task has executable verification command\n- **UX_DOCUMENTED**: Before/After transformation is visually clear with data flows\n- **ONE_PASS_TARGET**: Confidence score 8+ indicates high likelihood of first-attempt success\n- **ARTIFACT_WRITTEN**: Plan saved to `$ARTIFACTS_DIR/plan.md`\n", "archon-create-pr": "---\ndescription: Create a PR from current branch with implementation context\nargument-hint: [base-branch] (default: auto-detected from config or repo)\n---\n\n# Create Pull Request\n\n**Base branch override**: $ARGUMENTS\n**Default base branch**: $BASE_BRANCH\n\n> If a base branch was provided as argument above, use it for `--base`. Otherwise use the default base branch.\n\n---\n\n## Pre-flight: Check for Existing PRs\n\nExtract the issue number from the current branch name or context (e.g., `fix/issue-580` → `580`).\n\n```bash\nBRANCH=$(git branch --show-current)\nISSUE_NUM=$(echo \"$BRANCH\" | grep -oE '[0-9]+' | tail -1)\n# Pin all gh pr commands to the origin remote — in a fork clone, gh otherwise\n# targets the upstream parent repo. Re-run this line in every new shell.\nORIGIN_REPO=$(git remote get-url origin | sed -E 's#^.*[:/]([^/]+/[^/]+)$#\\1#; s#\\.git$##')\n```\n\nIf an issue number was found, search for open PRs that already reference it:\n\n```bash\ngh pr list \\\n --repo \"$ORIGIN_REPO\" \\\n --search \"Fixes #${ISSUE_NUM} OR Closes #${ISSUE_NUM}\" \\\n --state open \\\n --json number,url,headRefName\n```\n\n**If a matching PR is returned**: stop here, report the existing PR URL, and do **not** proceed to Phase 2 or Phase 3.\n\n```\nExisting PR found for issue #${ISSUE_NUM}: [url]\nSkipping PR creation.\n```\n\n**If no match is found** (or no issue number could be extracted): continue to Phase 1.\n\n---\n\n## Phase 1: Gather Context\n\n### 1.1 Check Git State\n\n```bash\ngit branch --show-current\ngit status --short\ngit log origin/$BASE_BRANCH..HEAD --oneline\n```\n\n### 1.2 Check for Implementation Report\n\nLook for the most recent implementation report:\n\n```bash\nls -t $ARTIFACTS_DIR/../reports/*-report.md 2>/dev/null | head -1\n```\n\nIf found, read it to extract:\n- Summary of what was implemented\n- Files changed\n- Validation results\n- Any deviations from plan\n\n### 1.3 Get Commit Summary\n\n```bash\ngit log origin/$BASE_BRANCH..HEAD --pretty=format:\"- %s\"\n```\n\n---\n\n## Phase 2: Prepare Branch\n\n### 2.1 Ensure All Changes Committed\n\nIf uncommitted changes exist:\n\n```bash\ngit status --porcelain\n```\n\n**If dirty**:\n\n1. Stage **only** the source files that are part of this change — never `git add -A`, `git add .`, or `git add -u`. List them by name:\n ```bash\n git add path/to/file1 path/to/file2 ...\n git status --porcelain # verify nothing else is staged\n ```\n2. **Never stage** scratch / review / PR-body artifacts, even if they show up in `git status`:\n - `.pr-body.md`, `pr-body.md`, `*.scratch.md`, `*.tmp.md`\n - `review/`, `*-report.md` at the repo root\n - Anything under `$ARTIFACTS_DIR`\n3. Commit: `git commit -m \"Final changes before PR\"`\n\n### 2.2 Push Branch\n\n```bash\ngit push -u origin HEAD\n```\n\n---\n\n## Phase 3: Create PR\n\n### 3.1 Check for PR Template\n\nLook for the project's PR template at `.github/pull_request_template.md`, `.github/PULL_REQUEST_TEMPLATE.md`, or `docs/PULL_REQUEST_TEMPLATE.md`. Read whichever one exists.\n\n**If template found**: Use it as the structure, fill in **every section** with details from the implementation report and commits. Don't skip sections or leave placeholders.\n\n**If no template**, use this format:\n\n```markdown\n## Summary\n\n[Brief description from implementation report or commits]\n\n## Changes\n\n[List from implementation report \"Files Changed\" section, or from commits]\n- file1.ts - description\n- file2.ts - description\n\n## Validation\n\n[From implementation report \"Validation Results\" section]\n- [x] Type check passes\n- [x] Lint passes\n- [x] Tests pass\n- [x] Build succeeds\n\n## Testing Notes\n\n[Any manual testing done or integration test results]\n\n---\n\n[If from a GitHub issue, add: Closes #XXX]\n```\n\n### 3.2 Determine PR Title\n\n**Title**: Concise, imperative mood\n- From implementation report summary, OR\n- From commit messages\n\n### 3.3 Create the PR\n\n```bash\n# Write body to file to avoid shell escaping\ncat > $ARTIFACTS_DIR/pr-body.md <<'EOF'\n[body from above]\nEOF\n\n# Fork-safe target: without --repo, gh opens the PR against the upstream parent\nORIGIN_REPO=$(git remote get-url origin | sed -E 's#^.*[:/]([^/]+/[^/]+)$#\\1#; s#\\.git$##')\n\ngh pr create \\\n --repo \"$ORIGIN_REPO\" \\\n --title \"[title]\" \\\n --body-file $ARTIFACTS_DIR/pr-body.md \\\n --base $BASE_BRANCH\n```\n\nOr if the content is simple:\n\n```bash\ngh pr create --repo \"$ORIGIN_REPO\" --fill --base $BASE_BRANCH\n```\n\nAfter creating the PR, capture its identifiers for downstream steps. Only write artifacts if PR creation succeeded — never persist stale data from a pre-existing PR:\n\n```bash\n# After creating the PR, capture and persist the PR number for downstream steps\n# IMPORTANT: Only write artifacts after confirmed successful PR creation\nORIGIN_REPO=$(git remote get-url origin | sed -E 's#^.*[:/]([^/]+/[^/]+)$#\\1#; s#\\.git$##')\nif gh pr view --repo \"$ORIGIN_REPO\" --json number,url -q '.number,.url' > /dev/null 2>&1; then\n PR_NUMBER=$(gh pr view --repo \"$ORIGIN_REPO\" --json number -q '.number')\n PR_URL=$(gh pr view --repo \"$ORIGIN_REPO\" --json url -q '.url')\n echo \"$PR_NUMBER\" > \"$ARTIFACTS_DIR/.pr-number\"\n echo \"$PR_URL\" > \"$ARTIFACTS_DIR/.pr-url\"\nelse\n echo \"WARNING: Could not confirm PR creation; skipping .pr-number/.pr-url artifacts\"\nfi\n```\n\n---\n\n## Phase 4: Output\n\nReport the result:\n\n```markdown\n## PR Created\n\n**URL**: [PR URL]\n**Branch**: [branch-name] → [base-branch]\n**Title**: [PR title]\n\n### Summary\n[Brief summary of what the PR contains]\n\n### Next Steps\n1. Request review if needed\n2. Address any CI failures\n3. Merge when approved\n```\n\n---\n\n## Error Handling\n\n### No Commits to Push\n\n```\nNo commits between origin/$BASE_BRANCH and HEAD.\nNothing to create a PR for.\n```\n\n### Branch Already Has PR\n\n```bash\nORIGIN_REPO=$(git remote get-url origin | sed -E 's#^.*[:/]([^/]+/[^/]+)$#\\1#; s#\\.git$##')\ngh pr view --repo \"$ORIGIN_REPO\" --web\n```\n\nOpens the existing PR instead of creating a duplicate.\n\n### Push Fails\n\n1. Check if branch exists remotely: `git ls-remote --heads origin [branch]`\n2. If conflicts: `git pull --rebase origin $BASE_BRANCH` then retry push\n3. If permission issues: Check GitHub access\n", "archon-docs-impact-agent": "---\ndescription: Check if PR changes require documentation updates (CLAUDE.md, docs/, agents)\nargument-hint: (none - reads from scope artifact)\n---\n\n# Documentation Impact Agent\n\n---\n\n## Your Mission\n\nAnalyze if the PR changes require updates to project documentation: CLAUDE.md, docs/ folder, agent definitions, or other documentation. Produce a structured artifact with recommendations.\n\n**Output artifact**: `$ARTIFACTS_DIR/review/docs-impact-findings.md`\n\n---\n\n## Phase 1: LOAD - Get Context\n\n### 1.1 Get PR Number from Registry\n\n```bash\nPR_NUMBER=$(cat $ARTIFACTS_DIR/.pr-number)\n```\n\n### 1.2 Read Scope\n\n```bash\ncat $ARTIFACTS_DIR/review/scope.md\n```\n\n**CRITICAL**: Check for \"NOT Building (Scope Limits)\" section. Items listed there are **intentionally excluded** - do NOT flag them as missing documentation needs!\n\n### 1.3 Get PR Diff\n\n```bash\ngh pr diff {number}\n```\n\n### 1.4 Read Current Documentation\n\n```bash\n# Read CLAUDE.md\ncat CLAUDE.md\n\n# List docs folder\nls -la $DOCS_DIR\n\n# List agent definitions\nls -la .claude/agents/ 2>/dev/null || true\nls -la .archon/commands/ 2>/dev/null || true\n```\n\n**PHASE_1_CHECKPOINT:**\n- [ ] PR number identified\n- [ ] Changes understood\n- [ ] Current docs read\n\n---\n\n## Phase 2: ANALYZE - Check Documentation Impact\n\n### 2.1 CLAUDE.md Impact\n\nCheck if changes affect documented:\n- Commands or slash commands\n- Workflows\n- Development setup\n- Environment variables\n- Database schema\n- API endpoints\n- Testing instructions\n- Code patterns/standards\n\n### 2.2 docs/ Folder Impact\n\nCheck if changes affect:\n- Architecture documentation\n- Getting started guide\n- Configuration documentation\n- API documentation\n- Deployment instructions\n\n### 2.3 Agent/Command Definitions\n\nCheck if changes affect:\n- Agent capabilities\n- Command arguments\n- Workflow steps\n- Tool usage patterns\n\n### 2.4 README Impact\n\nCheck if changes affect:\n- Feature list\n- Installation instructions\n- Usage examples\n- Configuration options\n\n**PHASE_2_CHECKPOINT:**\n- [ ] CLAUDE.md impact assessed\n- [ ] docs/ impact assessed\n- [ ] Agent definitions checked\n- [ ] README checked\n\n---\n\n## Phase 3: GENERATE - Create Artifact\n\nWrite to `$ARTIFACTS_DIR/review/docs-impact-findings.md`:\n\n```markdown\n# Documentation Impact Findings: PR #{number}\n\n**Reviewer**: docs-impact-agent\n**Date**: {ISO timestamp}\n**Docs Checked**: CLAUDE.md, docs/, agents, README\n\n---\n\n## Summary\n\n{2-3 sentence overview of documentation impact}\n\n**Verdict**: {NO_CHANGES_NEEDED | UPDATES_REQUIRED | CRITICAL_UPDATES}\n\n---\n\n## Impact Assessment\n\n| Document | Impact | Required Update |\n|----------|--------|-----------------|\n| CLAUDE.md | NONE/LOW/HIGH | {description or \"None\"} |\n| $DOCS_DIR/architecture.md | NONE/LOW/HIGH | {description or \"None\"} |\n| $DOCS_DIR/configuration.md | NONE/LOW/HIGH | {description or \"None\"} |\n| README.md | NONE/LOW/HIGH | {description or \"None\"} |\n| .claude/agents/*.md | NONE/LOW/HIGH | {description or \"None\"} |\n| .archon/commands/*.md | NONE/LOW/HIGH | {description or \"None\"} |\n\n---\n\n## Findings\n\n### Finding 1: {Descriptive Title}\n\n**Severity**: CRITICAL | HIGH | MEDIUM | LOW\n**Category**: missing-docs | outdated-docs | incomplete-docs | misleading-docs\n**Document**: `{file path}`\n**PR Change**: `{source file}:{line}` - {what changed}\n\n**Issue**:\n{Clear description of why docs need updating}\n\n**Current Documentation**:\n```markdown\n{current text in docs}\n```\n\n**Code Change**:\n```typescript\n// What changed in the PR\n{new code that docs don't reflect}\n```\n\n**Impact if Not Updated**:\n{What happens if docs aren't updated - user confusion, wrong setup, etc.}\n\n---\n\n#### Update Suggestions\n\n| Option | Approach | Scope | Effort |\n|--------|----------|-------|--------|\n| A | {minimal update} | {what it covers} | LOW |\n| B | {comprehensive update} | {what it covers} | MED/HIGH |\n\n**Recommended**: Option {X}\n\n**Reasoning**:\n{Why this update approach:\n- Keeps docs accurate\n- Matches existing documentation style\n- Appropriate level of detail}\n\n**Suggested Documentation Update**:\n```markdown\n{what the docs should say after update}\n```\n\n**Documentation Style Reference**:\n```markdown\n# SOURCE: {doc file}\n# How similar features are documented\n{existing documentation pattern}\n```\n\n---\n\n### Finding 2: {Title}\n\n{Same structure...}\n\n---\n\n## CLAUDE.md Sections to Update\n\n| Section | Current | Needed Update |\n|---------|---------|---------------|\n| {section name} | {current text summary} | {what to add/change} |\n| ... | ... | ... |\n\n---\n\n## Statistics\n\n| Severity | Count | Documents Affected |\n|----------|-------|-------------------|\n| CRITICAL | {n} | {list} |\n| HIGH | {n} | {list} |\n| MEDIUM | {n} | {list} |\n| LOW | {n} | {list} |\n\n---\n\n## New Documentation Needed\n\n| Topic | Suggested Location | Priority |\n|-------|-------------------|----------|\n| {new feature/change} | {where to document} | HIGH/MED/LOW |\n| ... | ... | ... |\n\n---\n\n## Positive Observations\n\n{Documentation already updated in PR, good inline docs, etc.}\n\n---\n\n## Metadata\n\n- **Agent**: docs-impact-agent\n- **Timestamp**: {ISO timestamp}\n- **Artifact**: `$ARTIFACTS_DIR/review/docs-impact-findings.md`\n```\n\n**PHASE_3_CHECKPOINT:**\n- [ ] Artifact file created\n- [ ] All docs checked\n- [ ] Update suggestions provided\n- [ ] Existing doc style referenced\n\n---\n\n## Success Criteria\n\n- **DOCS_ANALYZED**: All relevant docs checked\n- **IMPACT_ASSESSED**: Each doc rated for impact\n- **UPDATES_SPECIFIED**: Clear update suggestions\n- **STYLE_MATCHED**: Suggestions match existing doc style\n", "archon-error-handling-agent": "---\ndescription: Review error handling for silent failures, inadequate catch blocks, and poor fallbacks\nargument-hint: (none - reads from scope artifact)\n---\n\n# Error Handling Agent\n\n---\n\n## Your Mission\n\nHunt for silent failures, inadequate error handling, broad catch blocks, and inappropriate fallback behavior. Produce a structured artifact with findings, fix suggestions with options, and reasoning.\n\n**Output artifact**: `$ARTIFACTS_DIR/review/error-handling-findings.md`\n\n---\n\n## Phase 1: LOAD - Get Context\n\n### 1.1 Get PR Number from Registry\n\n```bash\nPR_NUMBER=$(cat $ARTIFACTS_DIR/.pr-number)\n```\n\n### 1.2 Read Scope\n\n```bash\ncat $ARTIFACTS_DIR/review/scope.md\n```\n\n**CRITICAL**: Check for \"NOT Building (Scope Limits)\" section. Items listed there are **intentionally excluded** - do NOT flag them as bugs or missing features!\n\n### 1.3 Get PR Diff\n\n```bash\ngh pr diff {number}\n```\n\n### 1.4 Read CLAUDE.md Error Handling Rules\n\n```bash\ncat CLAUDE.md | grep -A 20 -i \"error\"\n```\n\n**PHASE_1_CHECKPOINT:**\n- [ ] PR number identified\n- [ ] Scope loaded\n- [ ] Diff available\n\n---\n\n## Phase 2: ANALYZE - Hunt for Issues\n\n### 2.1 Find All Error Handling Code\n\nSearch for:\n- `try { ... } catch` blocks\n- `.catch(` handlers\n- `|| fallback` patterns\n- `?? defaultValue` patterns\n- `?.` optional chaining that might hide errors\n- Error event handlers\n- Conditional error state handling\n\n### 2.2 Scrutinize Each Handler\n\nFor every error handling location, evaluate:\n\n**Logging Quality:**\n- Is error logged with appropriate severity?\n- Does log include sufficient context?\n- Would this help debugging in 6 months?\n\n**User Feedback:**\n- Does user receive actionable feedback?\n- Is the error message specific and helpful?\n- Are technical details appropriately hidden/shown?\n\n**Catch Block Specificity:**\n- Does it catch only expected error types?\n- Could it accidentally suppress unrelated errors?\n- Should it be multiple catch blocks?\n\n**Fallback Behavior:**\n- Is fallback explicitly documented/intended?\n- Does fallback mask the underlying problem?\n- Is user aware they're seeing fallback behavior?\n\n### 2.3 Find Codebase Error Patterns\n\n```bash\n# Find error handling patterns in codebase\ngrep -r \"catch\" src/ --include=\"*.ts\" -A 3 | head -30\ngrep -r \"console.error\" src/ --include=\"*.ts\" -B 2 -A 2 | head -30\n```\n\n**PHASE_2_CHECKPOINT:**\n- [ ] All error handlers identified\n- [ ] Each handler evaluated\n- [ ] Codebase patterns found\n\n---\n\n## Phase 3: GENERATE - Create Artifact\n\nWrite to `$ARTIFACTS_DIR/review/error-handling-findings.md`:\n\n```markdown\n# Error Handling Findings: PR #{number}\n\n**Reviewer**: error-handling-agent\n**Date**: {ISO timestamp}\n**Error Handlers Reviewed**: {count}\n\n---\n\n## Summary\n\n{2-3 sentence overview of error handling quality}\n\n**Verdict**: {APPROVE | REQUEST_CHANGES | NEEDS_DISCUSSION}\n\n---\n\n## Findings\n\n### Finding 1: {Descriptive Title}\n\n**Severity**: CRITICAL | HIGH | MEDIUM | LOW\n**Category**: silent-failure | broad-catch | missing-logging | poor-user-feedback | unsafe-fallback\n**Location**: `{file}:{line}`\n\n**Issue**:\n{Clear description of the error handling problem}\n\n**Evidence**:\n```typescript\n// Current error handling at {file}:{line}\n{problematic code}\n```\n\n**Hidden Errors**:\nThis catch block could silently hide:\n- {Error type 1}: {scenario when it occurs}\n- {Error type 2}: {scenario when it occurs}\n- {Error type 3}: {scenario when it occurs}\n\n**User Impact**:\n{What happens to the user when this error occurs? Why is it bad?}\n\n---\n\n#### Fix Suggestions\n\n| Option | Approach | Pros | Cons |\n|--------|----------|------|------|\n| A | {e.g., Add specific error types} | {benefits} | {drawbacks} |\n| B | {e.g., Add logging + user message} | {benefits} | {drawbacks} |\n| C | {e.g., Propagate error instead} | {benefits} | {drawbacks} |\n\n**Recommended**: Option {X}\n\n**Reasoning**:\n{Explain why this option is preferred:\n- Aligns with project error handling patterns\n- Provides better debugging experience\n- Gives users actionable feedback\n- Follows CLAUDE.md rules}\n\n**Recommended Fix**:\n```typescript\n// Improved error handling\n{corrected code with proper logging, specific catches, user feedback}\n```\n\n**Codebase Pattern Reference**:\n```typescript\n// SOURCE: {file}:{lines}\n// This is how similar errors are handled elsewhere\n{existing error handling pattern from codebase}\n```\n\n---\n\n### Finding 2: {Title}\n\n{Same structure...}\n\n---\n\n## Error Handler Audit\n\n| Location | Type | Logging | User Feedback | Specificity | Verdict |\n|----------|------|---------|---------------|-------------|---------|\n| `file:line` | try-catch | GOOD/BAD | GOOD/BAD | GOOD/BAD | PASS/FAIL |\n| ... | ... | ... | ... | ... | ... |\n\n---\n\n## Statistics\n\n| Severity | Count | Auto-fixable |\n|----------|-------|--------------|\n| CRITICAL | {n} | {n} |\n| HIGH | {n} | {n} |\n| MEDIUM | {n} | {n} |\n| LOW | {n} | {n} |\n\n---\n\n## Silent Failure Risk Assessment\n\n| Risk | Likelihood | Impact | Mitigation |\n|------|------------|--------|------------|\n| {potential silent failure} | HIGH/MED/LOW | {user impact} | {fix needed} |\n| ... | ... | ... | ... |\n\n---\n\n## Patterns Referenced\n\n| File | Lines | Pattern |\n|------|-------|---------|\n| `src/example.ts` | 42-50 | {error handling pattern} |\n| ... | ... | ... |\n\n---\n\n## Positive Observations\n\n{Error handling done well, good patterns, proper logging}\n\n---\n\n## Metadata\n\n- **Agent**: error-handling-agent\n- **Timestamp**: {ISO timestamp}\n- **Artifact**: `$ARTIFACTS_DIR/review/error-handling-findings.md`\n```\n\n**PHASE_3_CHECKPOINT:**\n- [ ] Artifact file created\n- [ ] All error handlers audited\n- [ ] Hidden errors listed for each finding\n- [ ] Fix options with reasoning provided\n\n---\n\n## Success Criteria\n\n- **ERROR_HANDLERS_FOUND**: All try/catch, .catch, fallbacks identified\n- **EACH_HANDLER_AUDITED**: Logging, feedback, specificity evaluated\n- **HIDDEN_ERRORS_LISTED**: Each finding lists what could be hidden\n- **ARTIFACT_CREATED**: Findings file written with complete structure\n", @@ -30,7 +30,7 @@ export const BUNDLED_COMMANDS: Record = { "archon-implement-review-fixes": "---\ndescription: Implement CRITICAL and HIGH fixes from review, add tests, report remaining issues\nargument-hint: (none - reads from consolidated review artifact)\n---\n\n# Implement Review Fixes\n\n---\n\n## IMPORTANT: Output Behavior\n\n**Your output will be posted as a GitHub comment.** Keep your working output minimal:\n- Do NOT narrate each step (\"Now I'll read the file...\", \"Let me check...\")\n- Do NOT output verbose progress updates\n- Only output the final structured report at the end\n- Use the TodoWrite tool to track progress silently\n\n---\n\n## Your Mission\n\nRead the consolidated review artifact and implement all CRITICAL and HIGH priority fixes. Add tests for fixed code if missing. Commit and push changes. Report what was fixed, what wasn't (and why), and suggest follow-up issues for remaining items.\n\n**Output artifact**: `$ARTIFACTS_DIR/review/fix-report.md`\n**Git action**: Commit AND push fixes to the PR branch\n**GitHub action**: Post fix report comment\n\n---\n\n## Phase 1: LOAD - Get Fix List\n\n### 1.1 Get PR Number from Registry\n\n```bash\nPR_NUMBER=$(cat $ARTIFACTS_DIR/.pr-number)\n\n# Get the PR's head branch name\nHEAD_BRANCH=$(gh pr view $PR_NUMBER --json headRefName --jq '.headRefName')\necho \"PR: $PR_NUMBER, Branch: $HEAD_BRANCH\"\n```\n\n### 1.2 Checkout the PR Branch\n\n**CRITICAL: Work on the PR's actual branch, not a new branch.**\n\n```bash\n# Fetch and checkout the PR's branch\ngit fetch origin $HEAD_BRANCH\ngit checkout $HEAD_BRANCH\ngit pull origin $HEAD_BRANCH\n```\n\n### 1.3 Read Consolidated Review\n\n```bash\ncat $ARTIFACTS_DIR/review/consolidated-review.md\n```\n\nExtract:\n- All CRITICAL issues with fixes\n- All HIGH issues with fixes\n- MEDIUM issues (for reporting)\n- LOW issues (for reporting)\n\n### 1.4 Read Individual Artifacts for Details\n\nIf consolidated doesn't have full fix code, read original artifacts:\n\n```bash\ncat $ARTIFACTS_DIR/review/code-review-findings.md\ncat $ARTIFACTS_DIR/review/error-handling-findings.md\ncat $ARTIFACTS_DIR/review/test-coverage-findings.md\ncat $ARTIFACTS_DIR/review/docs-impact-findings.md\n```\n\n### 1.5 Check Current Git State\n\n```bash\ngit status --porcelain\ngit branch --show-current\n```\n\nVerify you are on the correct PR branch (should be `$HEAD_BRANCH`).\n\n**PHASE_1_CHECKPOINT:**\n- [ ] PR number identified\n- [ ] On the correct PR branch (NOT base branch, NOT a new branch)\n- [ ] Consolidated review loaded\n- [ ] CRITICAL/HIGH issues extracted\n\n---\n\n## Phase 2: IMPLEMENT - Apply Fixes\n\n### 2.1 For Each CRITICAL Issue\n\n1. **Read the file**\n2. **Apply the recommended fix**\n3. **Verify fix compiles**: `bun run type-check`\n4. **Track**: Note what was changed\n\n### 2.2 For Each HIGH Issue\n\nSame process as CRITICAL.\n\n### 2.3 For Test Coverage Gaps\n\nIf test-coverage-agent identified missing tests for fixed code:\n\n1. **Create/update test file**\n2. **Add tests for the fix**\n3. **Verify tests pass**: `bun test {file}`\n\n### 2.4 Handle Unfixable Issues\n\nIf a fix cannot be applied:\n- **Conflict**: Code has changed since review\n- **Complex**: Requires architectural changes\n- **Unclear**: Recommendation is ambiguous\n- **Risk**: Fix might break other things\n\nDocument the reason clearly.\n\n**PHASE_2_CHECKPOINT:**\n- [ ] All CRITICAL fixes attempted\n- [ ] All HIGH fixes attempted\n- [ ] Tests added for fixes\n- [ ] Unfixable issues documented\n\n---\n\n## Phase 3: VALIDATE - Verify Fixes\n\n### 3.1 Type Check\n\n```bash\nbun run type-check\n```\n\nMust pass. If not, fix type errors.\n\n### 3.2 Lint\n\n```bash\nbun run lint\n```\n\nFix any lint errors introduced.\n\n### 3.3 Run Tests\n\n```bash\nbun test\n```\n\nAll tests must pass. If new tests fail, fix them.\n\n### 3.4 Build Check\n\n```bash\nbun run build\n```\n\nMust succeed.\n\n**PHASE_3_CHECKPOINT:**\n- [ ] Type check passes\n- [ ] Lint passes\n- [ ] All tests pass\n- [ ] Build succeeds\n\n---\n\n## Phase 4: COMMIT AND PUSH - Save and Push Changes\n\n### 4.1 Stage Changes\n\nStage **only** the files you actually edited while applying review fixes — never `git add -A`, `git add .`, or `git add -u`. List them by name:\n\n```bash\ngit add path/to/file1 path/to/file2 ...\ngit status --porcelain # verify nothing scratch/review/PR-body is staged\n```\n\n**Never stage**:\n\n- `.pr-body.md`, `pr-body.md`, `*.scratch.md`, `*.tmp.md`\n- `review/`, `*-report.md` at the repo root\n- Anything under `$ARTIFACTS_DIR` (review artifacts live here, not in the worktree)\n\n### 4.2 Commit\n\n```bash\ngit commit -m \"fix: Address review findings (CRITICAL/HIGH)\n\nFixes applied:\n- {brief list of fixes}\n\nTests added:\n- {list of new tests if any}\n\nSkipped (see review artifacts):\n- {brief list of unfixable if any}\n\nReview artifacts: $ARTIFACTS_DIR/review/\"\n```\n\n### 4.3 Push to PR Branch\n\n**Push the fixes to the PR branch so they appear in the PR.**\n\n```bash\ngit push origin $HEAD_BRANCH\n```\n\nIf push fails due to divergence:\n```bash\ngit pull --rebase origin $HEAD_BRANCH\ngit push origin $HEAD_BRANCH\n```\n\n**PHASE_4_CHECKPOINT:**\n- [ ] Changes committed\n- [ ] Changes pushed to PR branch\n- [ ] PR now shows the fixes\n\n---\n\n## Phase 5: GENERATE - Create Fix Report\n\nWrite to `$ARTIFACTS_DIR/review/fix-report.md`:\n\n```markdown\n# Fix Report: PR #{number}\n\n**Date**: {ISO timestamp}\n**Status**: {COMPLETE | PARTIAL}\n**Branch**: {HEAD_BRANCH}\n\n---\n\n## Summary\n\n{2-3 sentence overview of fixes applied}\n\n---\n\n## Fixes Applied\n\n### CRITICAL Fixes ({n}/{total})\n\n| Issue | Location | Status | Details |\n|-------|----------|--------|---------|\n| {title} | `file:line` | ✅ FIXED | {what was done} |\n| {title} | `file:line` | ❌ SKIPPED | {why} |\n\n---\n\n### HIGH Fixes ({n}/{total})\n\n| Issue | Location | Status | Details |\n|-------|----------|--------|---------|\n| {title} | `file:line` | ✅ FIXED | {what was done} |\n\n---\n\n## Tests Added\n\n| Test File | Test Cases | For Issue |\n|-----------|------------|-----------|\n| `src/x.test.ts` | `it('should...')` | {issue title} |\n\n---\n\n## Not Fixed (Requires Manual Action)\n\n### {Issue Title}\n\n**Severity**: {CRITICAL/HIGH}\n**Location**: `{file}:{line}`\n**Reason Not Fixed**: {reason}\n\n**Suggested Action**:\n{What the user should do}\n\n---\n\n## MEDIUM Issues (User Decision Required)\n\n| Issue | Location | Options |\n|-------|----------|---------|\n| {title} | `file:line` | Fix now / Create issue / Skip |\n\n---\n\n## LOW Issues (For Consideration)\n\n| Issue | Location | Suggestion |\n|-------|----------|------------|\n| {title} | `file:line` | {brief suggestion} |\n\n---\n\n## Suggested Follow-up Issues\n\n| Issue Title | Priority | Related Finding |\n|-------------|----------|-----------------|\n| \"{title}\" | P{1/2/3} | {which finding} |\n\n---\n\n## Validation Results\n\n| Check | Status |\n|-------|--------|\n| Type check | ✅ |\n| Lint | ✅ |\n| Tests | ✅ ({n} passed) |\n| Build | ✅ |\n\n---\n\n## Git Status\n\n- **Branch**: {HEAD_BRANCH}\n- **Commit**: {commit-hash}\n- **Pushed**: ✅ Yes\n```\n\n**PHASE_5_CHECKPOINT:**\n- [ ] Fix report created\n- [ ] All fixes documented\n\n---\n\n## Phase 6: POST - GitHub Comment\n\n### 6.1 Post Fix Report\n\n```bash\ngh pr comment {number} --body \"$(cat <<'EOF'\n# ⚡ Auto-Fix Report\n\n**Status**: {COMPLETE | PARTIAL}\n**Pushed**: ✅ Changes pushed to PR\n\n---\n\n## Fixes Applied\n\n| Severity | Fixed | Skipped |\n|----------|-------|---------|\n| 🔴 CRITICAL | {n} | {n} |\n| 🟠 HIGH | {n} | {n} |\n\n### What Was Fixed\n\n{For each fix:}\n- ✅ **{title}** (`{file}:{line}`) - {brief description}\n\n### Tests Added\n\n{If any:}\n- `{test-file}`: {n} new test cases\n\n---\n\n## ❌ Not Fixed (Manual Action Required)\n\n{If any:}\n- **{title}** (`{file}`) - {reason}\n\n---\n\n## 🟡 MEDIUM Issues (Your Decision)\n\n{If any:}\n| Issue | Options |\n|-------|---------|\n| {title} | Fix now / Create issue / Skip |\n\n---\n\n## 📋 Suggested Follow-up Issues\n\n{If any items should become issues:}\n1. **{Issue Title}** (P{1/2/3}) - {brief description}\n\n---\n\n## Validation\n\n✅ Type check | ✅ Lint | ✅ Tests | ✅ Build\n\n---\n\n*Auto-fixed by Archon comprehensive-pr-review workflow*\n*Fixes pushed to branch `{HEAD_BRANCH}`*\nEOF\n)\"\n```\n\n**PHASE_6_CHECKPOINT:**\n- [ ] GitHub comment posted\n\n---\n\n## Phase 7: OUTPUT - Final Report\n\nOutput only this summary (keep it brief):\n\n```markdown\n## ✅ Fix Implementation Complete\n\n**PR**: #{number}\n**Branch**: {HEAD_BRANCH}\n**Status**: {COMPLETE | PARTIAL}\n\n| Severity | Fixed |\n|----------|-------|\n| CRITICAL | {n}/{total} |\n| HIGH | {n}/{total} |\n\n**Validation**: ✅ All checks pass\n**Pushed**: ✅ Changes pushed to PR\n\nSee fix report: `$ARTIFACTS_DIR/review/fix-report.md`\n```\n\n---\n\n## Error Handling\n\n### Type Check Fails After Fix\n\n1. Review the error\n2. Adjust the fix\n3. Re-run type check\n4. If still failing, mark as \"Not Fixed\" with reason\n\n### Tests Fail\n\n1. Check if fix caused the failure\n2. Either: fix the implementation, or fix the test\n3. If unclear, mark as \"Not Fixed\" for manual review\n\n### Push Fails\n\n1. Pull with rebase: `git pull --rebase origin $HEAD_BRANCH`\n2. Resolve any conflicts\n3. Push again\n\n---\n\n## Success Criteria\n\n- **ON_CORRECT_BRANCH**: Working on PR's head branch, not base branch or new branch\n- **CRITICAL_ADDRESSED**: All CRITICAL issues attempted\n- **HIGH_ADDRESSED**: All HIGH issues attempted\n- **VALIDATION_PASSED**: Type check, lint, tests, build all pass\n- **COMMITTED_AND_PUSHED**: Changes committed AND pushed to PR branch\n- **REPORTED**: Fix report artifact and GitHub comment created\n", "archon-implement-tasks": "---\ndescription: Execute plan tasks with type-checking after each change\nargument-hint: (no arguments - reads from workflow artifacts)\n---\n\n# Implement Tasks\n\n**Workflow ID**: $WORKFLOW_ID\n\n---\n\n## Your Mission\n\nExecute each task from the plan, validating after every change.\n\n**Core Philosophy**:\n- Type-check after EVERY file change\n- Fix issues immediately before moving on\n- Document any deviations from the plan\n\n**This step assumes setup is complete** - branch exists, PR is created, plan is confirmed.\n\n---\n\n## Phase 1: LOAD - Read Context\n\n### 1.1 Load Plan Context\n\n```bash\ncat $ARTIFACTS_DIR/plan-context.md\n```\n\nExtract:\n- Files to change (CREATE/UPDATE list)\n- Validation commands (especially type-check)\n- Patterns to mirror\n\n### 1.2 Load Plan Confirmation\n\n```bash\ncat $ARTIFACTS_DIR/plan-confirmation.md\n```\n\nCheck:\n- Status is CONFIRMED or PROCEED WITH CAUTION\n- Note any warnings to handle during implementation\n\n### 1.3 Load Original Plan\n\nThe plan source path is in `plan-context.md`. Read the full plan for detailed task instructions:\n\n```bash\ncat {plan-source-path}\n```\n\n### 1.4 Identify Package Manager\n\n```bash\ntest -f bun.lockb && echo \"bun\" || \\\ntest -f pnpm-lock.yaml && echo \"pnpm\" || \\\ntest -f yarn.lock && echo \"yarn\" || \\\ntest -f package-lock.json && echo \"npm\" || \\\necho \"unknown\"\n```\n\nStore the runner for validation commands.\n\n**PHASE_1_CHECKPOINT:**\n\n- [ ] Plan context loaded\n- [ ] Confirmation status verified\n- [ ] Original plan loaded\n- [ ] Package manager identified\n\n---\n\n## Phase 2: EXECUTE - Implement Each Task\n\n**For each task in the plan's \"Tasks\" or \"Step-by-Step Tasks\" section:**\n\n### 2.1 Read Task Context\n\nBefore implementing each task:\n\n1. **Read the MIRROR file** referenced in the task\n2. **Understand the pattern** to follow\n3. **Note any GOTCHA warnings**\n4. **Check IMPORTS** needed\n\n### 2.2 Implement the Task\n\nMake the change as specified:\n\n- **CREATE**: Write new file following the pattern\n- **UPDATE**: Modify existing file as described\n- **Follow patterns exactly** - match style, naming, structure\n\n### 2.3 Type-Check Immediately\n\n**After EVERY file change:**\n\n```bash\n{runner} run type-check\n```\n\n**If type-check fails:**\n\n1. Read the error message carefully\n2. Fix the type issue\n3. Re-run type-check\n4. Only proceed when passing\n\n**Do NOT accumulate errors** - fix each one before moving to the next task.\n\n### 2.4 Track Progress\n\nLog each task as completed:\n\n```\nTask 1: CREATE src/features/x/models.ts ✅\nTask 2: CREATE src/features/x/service.ts ✅\nTask 3: UPDATE src/routes/index.ts ✅\n```\n\n### 2.5 Handle Deviations\n\nIf you must deviate from the plan:\n\n1. **Document WHAT** changed\n2. **Document WHY** it changed\n3. **Continue** with the deviation noted\n\nCommon reasons for deviation:\n- Pattern file has changed since plan was created\n- Missing import discovered\n- Type incompatibility requires different approach\n- Better solution discovered during implementation\n\n**PHASE_2_CHECKPOINT (per task):**\n\n- [ ] Task implemented\n- [ ] Type-check passes\n- [ ] Progress logged\n- [ ] Deviations documented (if any)\n\n---\n\n## Phase 3: TESTS - Write Required Tests\n\n### 3.1 Test Requirements\n\nEvery new function/feature needs at least one test:\n\n- **New file created** → Create corresponding test file\n- **New function added** → Add test for that function\n- **Behavior changed** → Update existing tests\n\n### 3.2 Follow Test Patterns\n\nFind existing test files to mirror:\n\n```bash\nfind . -name \"*.test.ts\" -type f | head -5\n```\n\nRead a relevant test file to understand the project's test patterns.\n\n### 3.3 Write Tests\n\nFor each new/changed file, write tests that cover:\n\n1. **Happy path** - Normal expected behavior\n2. **Edge cases** - Boundary conditions from the plan\n3. **Error cases** - What happens with bad input\n\n### 3.4 Run Tests\n\n```bash\n{runner} test\n```\n\n**If tests fail:**\n\n1. Determine: bug in implementation or bug in test?\n2. Fix the actual issue (usually implementation)\n3. Re-run tests\n4. Repeat until green\n\n**PHASE_3_CHECKPOINT:**\n\n- [ ] Tests written for new code\n- [ ] All tests pass\n\n---\n\n## Phase 4: ARTIFACT - Write Implementation Progress\n\n### 4.1 Write Progress Artifact\n\nWrite to `$ARTIFACTS_DIR/implementation.md`:\n\n```markdown\n# Implementation Progress\n\n**Generated**: {YYYY-MM-DD HH:MM}\n**Workflow ID**: $WORKFLOW_ID\n**Status**: {COMPLETE | IN_PROGRESS | BLOCKED}\n\n---\n\n## Tasks Completed\n\n| # | Task | File | Status | Notes |\n|---|------|------|--------|-------|\n| 1 | {description} | `src/x.ts` | ✅ | |\n| 2 | {description} | `src/y.ts` | ✅ | |\n| 3 | {description} | `src/z.ts` | ✅ | Minor deviation - see below |\n\n**Progress**: {X} of {Y} tasks completed\n\n---\n\n## Files Changed\n\n| File | Action | Lines |\n|------|--------|-------|\n| `src/new-file.ts` | CREATE | +{N} |\n| `src/existing.ts` | UPDATE | +{N}/-{M} |\n\n---\n\n## Tests Written\n\n| Test File | Test Cases |\n|-----------|------------|\n| `src/x.test.ts` | `should do X`, `should handle Y` |\n| `src/y.test.ts` | `creates correctly`, `validates input` |\n\n---\n\n## Deviations from Plan\n\n{If none:}\nNo deviations. Implementation matched the plan exactly.\n\n{If any:}\n### Deviation 1: {brief title}\n\n**Task**: {which task}\n**Expected**: {what plan said}\n**Actual**: {what was done}\n**Reason**: {why the change was necessary}\n\n---\n\n## Type-Check Status\n\n- [x] Passes after all changes\n\n---\n\n## Test Status\n\n- [x] All tests pass\n- Tests added: {N}\n- Tests modified: {M}\n\n---\n\n## Issues Encountered\n\n{If none:}\nNo issues encountered.\n\n{If any:}\n### Issue 1: {title}\n\n**Problem**: {description}\n**Resolution**: {how it was fixed}\n\n---\n\n## Next Step\n\nContinue to `archon-validate` for full validation suite.\n```\n\n**PHASE_4_CHECKPOINT:**\n\n- [ ] Implementation artifact written\n- [ ] All tasks documented\n- [ ] Deviations noted\n- [ ] Test status recorded\n\n---\n\n## Phase 5: OUTPUT - Report Progress\n\n```markdown\n## Implementation Complete\n\n**Workflow ID**: `$WORKFLOW_ID`\n**Status**: ✅ All tasks executed\n\n### Progress Summary\n\n| Metric | Count |\n|--------|-------|\n| Tasks completed | {X}/{Y} |\n| Files created | {N} |\n| Files updated | {M} |\n| Tests written | {K} |\n\n### Type-Check\n\n✅ Passes\n\n### Tests\n\n✅ All pass ({N} tests)\n\n{If deviations:}\n### Deviations\n\n{count} deviation(s) from plan documented in artifact.\n\n### Artifact\n\nProgress written to: `$ARTIFACTS_DIR/implementation.md`\n\n### Next Step\n\nProceed to `archon-validate` for full validation (lint, build, integration tests).\n```\n\n---\n\n## Error Handling\n\n### Type-Check Fails\n\nDo NOT proceed to next task. Fix the issue:\n\n1. Read the error carefully\n2. Identify the file and line\n3. Fix the type issue\n4. Re-run type-check\n5. Only continue when green\n\n### Test Fails\n\n1. Read the failure output\n2. Identify: implementation bug or test bug?\n3. Fix the root cause\n4. Re-run tests\n\n### Pattern File Changed\n\nIf a pattern file has changed since the plan was created:\n\n1. Read the current version\n2. Adapt the implementation to match current patterns\n3. Document as a deviation\n4. Continue\n\n### Task Unclear\n\nIf a task description is ambiguous:\n\n1. Check the plan's context sections for clarity\n2. Look at the MIRROR file for guidance\n3. Make a reasonable decision\n4. Document the interpretation as a deviation\n\n---\n\n## Success Criteria\n\n- **TASKS_COMPLETE**: All tasks from plan executed\n- **TYPES_PASS**: Type-check passes after all changes\n- **TESTS_WRITTEN**: New code has tests\n- **TESTS_PASS**: All tests green\n- **DEVIATIONS_DOCUMENTED**: Any plan deviations noted\n- **ARTIFACT_WRITTEN**: Implementation progress artifact created\n", "archon-implement": "---\ndescription: Execute an implementation plan with rigorous validation loops\nargument-hint: \n---\n\n# Implement Plan\n\n**Plan**: $ARGUMENTS\n\n---\n\n## Your Mission\n\nExecute the plan end-to-end with rigorous self-validation. You are autonomous.\n\n**Core Philosophy**: Validation loops catch mistakes early. Run checks after every change. Fix issues immediately. The goal is a working implementation, not just code that exists.\n\n**Golden Rule**: If a validation fails, fix it before moving on. Never accumulate broken state.\n\n---\n\n## Phase 0: DETECT - Project Environment\n\n### 0.1 Identify Package Manager\n\nCheck for these files to determine the project's toolchain:\n\n| File Found | Package Manager | Runner |\n|------------|-----------------|--------|\n| `bun.lockb` | bun | `bun` / `bun run` |\n| `pnpm-lock.yaml` | pnpm | `pnpm` / `pnpm run` |\n| `yarn.lock` | yarn | `yarn` / `yarn run` |\n| `package-lock.json` | npm | `npm run` |\n| `pyproject.toml` | uv/pip | `uv run` / `python` |\n| `Cargo.toml` | cargo | `cargo` |\n| `go.mod` | go | `go` |\n\n**Store the detected runner** - use it for all subsequent commands.\n\n### 0.2 Identify Validation Scripts\n\nCheck `package.json` (or equivalent) for available scripts:\n- Type checking: `type-check`, `typecheck`, `tsc`\n- Linting: `lint`, `lint:fix`\n- Testing: `test`, `test:unit`, `test:integration`\n- Building: `build`, `compile`\n\n**Use the plan's \"Validation Commands\" section** - it should specify exact commands for this project.\n\n---\n\n## Phase 1: LOAD - Read the Plan\n\n### 1.1 Load Plan File\n\n```bash\ncat $ARGUMENTS\n```\n\nIf `$ARGUMENTS` is a GitHub issue URL or number (e.g., `#123`), fetch the issue body which contains the plan.\n\n### 1.2 Extract Key Sections\n\nLocate and understand:\n\n- **Summary** - What we're building\n- **Patterns to Mirror** - Code to copy from\n- **Files to Change** - CREATE/UPDATE list\n- **Step-by-Step Tasks** - Implementation order\n- **Validation Commands** - How to verify (USE THESE, not hardcoded commands)\n- **Acceptance Criteria** - Definition of done\n\n### 1.3 Validate Plan Exists\n\n**If plan not found:**\n\n```\nError: Plan not found at $ARGUMENTS\n\nProvide a valid plan path or GitHub issue containing the plan.\n```\n\n**PHASE_1_CHECKPOINT:**\n\n- [ ] Plan file loaded\n- [ ] Key sections identified\n- [ ] Tasks list extracted\n\n---\n\n## Phase 2: PREPARE - Git State\n\n### 2.1 Check Current State\n\n```bash\n# What branch are we on?\ngit branch --show-current\n\n# Are we in a worktree?\ngit rev-parse --show-toplevel\ngit worktree list\n\n# Is working directory clean?\ngit status --porcelain\n```\n\n### 2.2 Branch Decision\n\n```text\n┌─ IN WORKTREE?\n│ └─ YES → Use current branch AS-IS. Do NOT switch branches. Do NOT create\n│ new branches. The isolation system has already set up the correct\n│ branch; any deviation operates on the wrong code.\n│ Log: \"Using worktree at {path} on branch {branch}\"\n│\n├─ ON $BASE_BRANCH? (main, master, or configured base branch)\n│ └─ Q: Working directory clean?\n│ ├─ YES → Create branch: git checkout -b feature/{plan-slug}\n│ │ (only applies outside a worktree — e.g., manual CLI usage)\n│ └─ NO → STOP: \"Stash or commit changes first\"\n│\n├─ ON OTHER BRANCH?\n│ └─ Use it AS-IS. Do NOT switch to another branch (e.g., one shown by\n│ `git branch` but not currently checked out).\n│ Log: \"Using existing branch {name}\"\n│\n└─ DIRTY STATE?\n └─ STOP: \"Stash or commit changes first\"\n```\n\n### 2.3 Sync with Remote\n\n```bash\ngit fetch origin\ngit pull --rebase origin $BASE_BRANCH 2>/dev/null || true\n```\n\n**PHASE_2_CHECKPOINT:**\n\n- [ ] On correct branch (not $BASE_BRANCH with uncommitted work)\n- [ ] Working directory ready\n- [ ] Up to date with remote\n\n---\n\n## Phase 3: EXECUTE - Implement Tasks\n\n**For each task in the plan's Step-by-Step Tasks section:**\n\n### 3.1 Read Context\n\n1. Read the **MIRROR** file reference from the task\n2. Understand the pattern to follow\n3. Read any **IMPORTS** specified\n\n### 3.2 Implement\n\n1. Make the change exactly as specified\n2. Follow the pattern from MIRROR reference\n3. Handle any **GOTCHA** warnings\n\n### 3.3 Validate Immediately\n\n**After EVERY file change, run the type-check command from the plan's Validation Commands section.**\n\nCommon patterns:\n- `{runner} run type-check` (JS/TS projects)\n- `mypy .` (Python)\n- `cargo check` (Rust)\n- `go build ./...` (Go)\n\n**If types fail:**\n\n1. Read the error\n2. Fix the issue\n3. Re-run type-check\n4. Only proceed when passing\n\n### 3.4 Track Progress\n\nLog each task as you complete it:\n\n```\nTask 1: CREATE src/features/x/models.ts ✅\nTask 2: CREATE src/features/x/service.ts ✅\nTask 3: UPDATE src/routes/index.ts ✅\n```\n\n**Deviation Handling:**\nIf you must deviate from the plan:\n\n- Note WHAT changed\n- Note WHY it changed\n- Continue with the deviation documented\n\n**PHASE_3_CHECKPOINT:**\n\n- [ ] All tasks executed in order\n- [ ] Each task passed type-check\n- [ ] Deviations documented\n\n---\n\n## Phase 4: VALIDATE - Full Verification\n\n### 4.1 Static Analysis\n\n**Run the type-check and lint commands from the plan's Validation Commands section.**\n\nCommon patterns:\n- JS/TS: `{runner} run type-check && {runner} run lint`\n- Python: `ruff check . && mypy .`\n- Rust: `cargo check && cargo clippy`\n- Go: `go vet ./...`\n\n**Must pass with zero errors.**\n\nIf lint errors:\n\n1. Run the lint fix command (e.g., `{runner} run lint:fix`, `ruff check --fix .`)\n2. Re-check\n3. Manual fix remaining issues\n\n### 4.2 Unit Tests\n\n**You MUST write or update tests for new code.** This is not optional.\n\n**Test requirements:**\n\n1. Every new function/feature needs at least one test\n2. Edge cases identified in the plan need tests\n3. Update existing tests if behavior changed\n\n**Write tests**, then run the test command from the plan.\n\nCommon patterns:\n- JS/TS: `{runner} test` or `{runner} run test`\n- Python: `pytest` or `uv run pytest`\n- Rust: `cargo test`\n- Go: `go test ./...`\n\n**If tests fail:**\n\n1. Read failure output\n2. Determine: bug in implementation or bug in test?\n3. Fix the actual issue\n4. Re-run tests\n5. Repeat until green\n\n### 4.3 Build Check\n\n**Run the build command from the plan's Validation Commands section.**\n\nCommon patterns:\n- JS/TS: `{runner} run build`\n- Python: N/A (interpreted) or `uv build`\n- Rust: `cargo build --release`\n- Go: `go build ./...`\n\n**Must complete without errors.**\n\n### 4.4 Integration Testing (if applicable)\n\n**If the plan involves API/server changes, use the integration test commands from the plan.**\n\nExample pattern:\n```bash\n# Start server in background (command varies by project)\n{runner} run dev &\nSERVER_PID=$!\nsleep 3\n\n# Test endpoints (adjust URL/port per project config)\ncurl -s http://localhost:{port}/health | jq\n\n# Stop server\nkill $SERVER_PID\n```\n\n### 4.5 Edge Case Testing\n\nRun any edge case tests specified in the plan.\n\n**PHASE_4_CHECKPOINT:**\n\n- [ ] Type-check passes (command from plan)\n- [ ] Lint passes (0 errors)\n- [ ] Tests pass (all green)\n- [ ] Build succeeds\n- [ ] Integration tests pass (if applicable)\n\n---\n\n## Phase 5: REPORT - Create Implementation Report\n\n### 5.1 Create Report Directory\n\n```bash\nmkdir -p $ARTIFACTS_DIR/../reports\n```\n\n### 5.2 Generate Report\n\n**Path**: `$ARTIFACTS_DIR/../reports/{plan-name}-report.md`\n\n```markdown\n# Implementation Report\n\n**Plan**: `$ARGUMENTS`\n**Source Issue**: #{number} (if applicable)\n**Branch**: `{branch-name}`\n**Date**: {YYYY-MM-DD}\n**Status**: {COMPLETE | PARTIAL}\n\n---\n\n## Summary\n\n{Brief description of what was implemented}\n\n---\n\n## Assessment vs Reality\n\nCompare the original plan's assessment with what actually happened:\n\n| Metric | Predicted | Actual | Reasoning |\n| ---------- | ----------- | -------- | ------------------------------------------------------------------------------ |\n| Complexity | {from plan} | {actual} | {Why it matched or differed - e.g., \"discovered additional integration point\"} |\n| Confidence | {from plan} | {actual} | {e.g., \"root cause was correct\" or \"had to pivot because X\"} |\n\n**If implementation deviated from the plan, explain why:**\n\n- {What changed and why - based on what you discovered during implementation}\n\n---\n\n## Tasks Completed\n\n| # | Task | File | Status |\n| --- | ------------------ | ---------- | ------ |\n| 1 | {task description} | `src/x.ts` | ✅ |\n| 2 | {task description} | `src/y.ts` | ✅ |\n\n---\n\n## Validation Results\n\n| Check | Result | Details |\n| ----------- | ------ | --------------------- |\n| Type check | ✅ | No errors |\n| Lint | ✅ | 0 errors, N warnings |\n| Unit tests | ✅ | X passed, 0 failed |\n| Build | ✅ | Compiled successfully |\n| Integration | ✅/⏭️ | {result or \"N/A\"} |\n\n---\n\n## Files Changed\n\n| File | Action | Lines |\n| ---------- | ------ | --------- |\n| `src/x.ts` | CREATE | +{N} |\n| `src/y.ts` | UPDATE | +{N}/-{M} |\n\n---\n\n## Deviations from Plan\n\n{List any deviations with rationale, or \"None\"}\n\n---\n\n## Issues Encountered\n\n{List any issues and how they were resolved, or \"None\"}\n\n---\n\n## Tests Written\n\n| Test File | Test Cases |\n| --------------- | ------------------------ |\n| `src/x.test.ts` | {list of test functions} |\n\n---\n\n## Next Steps\n\n- [ ] Review implementation\n- [ ] Create PR (next step in workflow)\n- [ ] Merge when approved\n```\n\n### 5.3 Archive Plan\n\n```bash\nmkdir -p $ARTIFACTS_DIR/../plans/completed\ncp $ARGUMENTS $ARTIFACTS_DIR/../plans/completed/ 2>/dev/null || true\n```\n\n**PHASE_5_CHECKPOINT:**\n\n- [ ] Report created at `$ARTIFACTS_DIR/../reports/`\n- [ ] Plan copied to completed folder (if local file)\n\n---\n\n## Phase 6: OUTPUT - Report to User\n\n```markdown\n## Implementation Complete\n\n**Plan**: `$ARGUMENTS`\n**Source Issue**: #{number} (if applicable)\n**Branch**: `{branch-name}`\n**Status**: ✅ Complete\n\n### Validation Summary\n\n| Check | Result |\n| ---------- | --------------- |\n| Type check | ✅ |\n| Lint | ✅ |\n| Tests | ✅ ({N} passed) |\n| Build | ✅ |\n\n### Files Changed\n\n- {N} files created\n- {M} files updated\n- {K} tests written\n\n### Deviations\n\n{If none: \"Implementation matched the plan.\"}\n{If any: Brief summary of what changed and why}\n\n### Artifacts\n\n- Report: `$ARTIFACTS_DIR/../reports/{name}-report.md`\n\n### Next Steps\n\n1. Review the report (especially if deviations noted)\n2. Create PR (next workflow step)\n3. Merge when approved\n```\n\n---\n\n## Handling Failures\n\n### Type Check Fails\n\n1. Read error message carefully\n2. Fix the type issue\n3. Re-run the type-check command\n4. Don't proceed until passing\n\n### Tests Fail\n\n1. Identify which test failed\n2. Determine: implementation bug or test bug?\n3. Fix the root cause (usually implementation)\n4. Re-run tests\n5. Repeat until green\n\n### Lint Fails\n\n1. Run the lint fix command for auto-fixable issues\n2. Manually fix remaining issues\n3. Re-run lint\n4. Proceed when clean\n\n### Build Fails\n\n1. Usually a type or import issue\n2. Check the error output\n3. Fix and re-run\n\n### Integration Test Fails\n\n1. Check if server started correctly\n2. Verify endpoint exists\n3. Check request format\n4. Fix implementation and retry\n\n---\n\n## Success Criteria\n\n- **TASKS_COMPLETE**: All plan tasks executed\n- **TYPES_PASS**: Type-check command exits 0\n- **LINT_PASS**: Lint command exits 0 (warnings OK)\n- **TESTS_PASS**: Test command all green\n- **BUILD_PASS**: Build command succeeds\n- **REPORT_CREATED**: Implementation report exists\n", - "archon-investigate-issue": "---\ndescription: Investigate a GitHub issue or problem - analyze codebase, create plan, post to GitHub\nargument-hint: \n---\n\n# Investigate Issue\n\n**Input**: $ARGUMENTS\n\n---\n\n## Your Mission\n\nInvestigate the issue/problem and produce a comprehensive implementation plan that:\n\n1. Can be executed by `/implement-issue`\n2. Is posted as a GitHub comment (if GH issue provided)\n3. Captures all context needed for one-pass implementation\n\n**Golden Rule**: The artifact you produce IS the specification. The implementing agent should be able to work from it without asking questions.\n\n---\n\n## Phase 1: PARSE - Understand Input\n\n### 1.1 Determine Input Type\n\n**Check the input format:**\n\n- Looks like a number (`123`, `#123`) → GitHub issue number\n- Starts with `http` → GitHub URL (extract issue number)\n- Anything else → Free-form description\n\n```bash\n# If GitHub issue, fetch it:\ngh issue view {number} --json title,body,labels,comments,state,url,author\n```\n\n### 1.2 Extract Context\n\n**If GitHub issue:**\n- Title: What's the reported problem?\n- Body: Details, reproduction steps, expected vs actual\n- Labels: bug? enhancement? documentation?\n- Comments: Additional context from discussion\n- State: Is it still open?\n\n**If free-form:**\n- Parse as problem description\n- Note: No GitHub posting (artifact only)\n\n### 1.3 Classify Issue Type\n\n| Type | Indicators |\n|------|------------|\n| BUG | \"broken\", \"error\", \"crash\", \"doesn't work\", stack trace |\n| ENHANCEMENT | \"add\", \"support\", \"feature\", \"would be nice\" |\n| REFACTOR | \"clean up\", \"improve\", \"simplify\", \"reorganize\" |\n| CHORE | \"update\", \"upgrade\", \"maintenance\", \"dependency\" |\n| DOCUMENTATION | \"docs\", \"readme\", \"clarify\", \"example\" |\n\n### 1.4 Assess Severity/Priority, Complexity, and Confidence\n\nEach assessment requires a **one-sentence reasoning** explaining WHY you chose that value. This reasoning must be based on concrete findings from your investigation (codebase exploration, git history, integration analysis).\n\n**For BUG issues - Severity:**\n\n| Severity | Criteria |\n|----------|----------|\n| CRITICAL | System down, data loss, security vulnerability, no workaround |\n| HIGH | Major feature broken, significant user impact, difficult workaround |\n| MEDIUM | Feature partially broken, moderate impact, workaround exists |\n| LOW | Minor issue, cosmetic, edge case, easy workaround |\n\n**For ENHANCEMENT/REFACTOR/CHORE/DOCUMENTATION - Priority:**\n\n| Priority | Criteria |\n|----------|----------|\n| HIGH | Blocking other work, frequently requested, high user value |\n| MEDIUM | Important but not urgent, moderate user value |\n| LOW | Nice to have, low urgency, minimal user impact |\n\n**Complexity** (based on codebase findings):\n\n| Complexity | Criteria |\n|------------|----------|\n| HIGH | 5+ files, multiple integration points, architectural changes, high risk |\n| MEDIUM | 2-4 files, some integration points, moderate risk |\n| LOW | 1-2 files, isolated change, low risk |\n\n**Confidence** (based on evidence quality):\n\n| Confidence | Criteria |\n|------------|----------|\n| HIGH | Clear root cause, strong evidence, well-understood code path |\n| MEDIUM | Likely root cause, some assumptions, partially understood |\n| LOW | Uncertain root cause, limited evidence, many unknowns |\n\n**PHASE_1_CHECKPOINT:**\n- [ ] Input type identified (GH issue or free-form)\n- [ ] Issue content extracted\n- [ ] Type classified\n- [ ] Severity (bug) or Priority (other) assessed with reasoning\n- [ ] Complexity assessed with reasoning (after Phase 2)\n- [ ] Confidence assessed with reasoning (after Phase 3)\n- [ ] If GH issue: confirmed it's open and not already has PR\n\n---\n\n## Phase 2: EXPLORE - Codebase Intelligence\n\n### 2.1 Search for Relevant Code\n\nUse Task tool with subagent_type=\"Explore\":\n\n```\nExplore the codebase to understand the issue:\n\nISSUE: {title/description}\n\nDISCOVER:\n1. Files directly related to this functionality\n2. How the current implementation works\n3. Integration points - what calls this, what it calls\n4. Similar patterns elsewhere to mirror\n5. Existing test patterns for this area\n6. Error handling patterns used\n\nReturn:\n- File paths with specific line numbers\n- Actual code snippets (not summaries)\n- Dependencies and data flow\n```\n\n### 2.2 Document Findings\n\n| Area | File:Lines | Notes |\n|------|-----------|-------|\n| Core logic | `src/x.ts:10-50` | Main function affected |\n| Callers | `src/y.ts:20-30` | Uses the core function |\n| Types | `src/types/x.ts:5-15` | Relevant interfaces |\n| Tests | `src/x.test.ts:1-100` | Existing test patterns |\n| Similar | `src/z.ts:40-60` | Pattern to mirror |\n\n**PHASE_2_CHECKPOINT:**\n- [ ] Explore agent completed successfully\n- [ ] Core files identified with line numbers\n- [ ] Integration points mapped\n- [ ] Similar patterns found to mirror\n- [ ] Test patterns documented\n\n---\n\n## Phase 3: ANALYZE - Form Approach\n\n### 3.0 First-Principles Analysis\n\nBefore diving into bug analysis or enhancement scoping, identify the primitive:\n\n1. **What primitive is involved?** What is the core abstraction this bug/feature touches?\n (e.g., the condition evaluator, the approval system, the isolation provider)\n2. **Is the primitive sound?** Does the existing design handle this case, or is the\n primitive itself incomplete or missing a case?\n3. **Root cause vs symptom** — are we fixing where the error manifests, or where it\n originates? Trace the data flow back to the source.\n4. **What's the minimal change?** What is the smallest edit that fixes the root cause?\n Avoid adding new abstractions when extending existing ones works.\n5. **What does this unlock?** If we add/change a primitive, what other improvements\n become possible?\n\n| Primitive | File:Lines | Sound? | Notes |\n|-----------|-----------|--------|-------|\n| {abstraction name} | `src/x.ts:10-30` | Yes/No/Partial | {if incomplete: what's missing} |\n\n### 3.1 For BUG Issues - Root Cause Analysis\n\nApply the 5 Whys:\n\n```\nWHY 1: Why does [symptom] occur?\n→ Because [cause A]\n→ Evidence: `file.ts:123` - {code snippet}\n\nWHY 2: Why does [cause A] happen?\n→ Because [cause B]\n→ Evidence: {proof}\n\n... continue until you reach fixable code ...\n\nROOT CAUSE: [the specific code/logic to change]\nEvidence: `source.ts:456` - {the problematic code}\n```\n\n**Check git history:**\n```bash\ngit log --oneline -10 -- {affected-file}\ngit blame -L {start},{end} {affected-file}\n```\n\n### 3.2 For ENHANCEMENT/REFACTOR Issues\n\n**Identify:**\n- What needs to be added/changed?\n- Where does it integrate?\n- What are the scope boundaries?\n- What should NOT be changed?\n\n### 3.3 For All Issues\n\n**Determine:**\n- Files to CREATE (new files)\n- Files to UPDATE (existing files)\n- Files to DELETE (if any)\n- Dependencies and order of changes\n- Edge cases and risks\n- Validation strategy\n\n**PHASE_3_CHECKPOINT:**\n- [ ] Root cause identified (for bugs) OR change rationale clear (for enhancements)\n- [ ] All affected files listed with specific changes\n- [ ] Scope boundaries defined (what NOT to change)\n- [ ] Risks and edge cases identified\n- [ ] Validation approach defined\n\n---\n\n## Phase 4: GENERATE - Create Artifact\n\n### 4.1 Artifact Path\n\n```bash\n```\n\n**Path:** `$ARTIFACTS_DIR/investigation.md`\n\nThis unified path allows review agents to find the artifact regardless of workflow type.\n\n### 4.2 Artifact Template\n\nWrite this structure to the artifact file.\n\n**Note on Severity vs Priority:**\n- Use **Severity** for BUG type (CRITICAL, HIGH, MEDIUM, LOW)\n- Use **Priority** for all other types (HIGH, MEDIUM, LOW)\n\n**Important:** Each assessment must include a one-sentence reasoning based on your investigation findings.\n\n```markdown\n# Investigation: {Title}\n\n**Issue**: #{number} ({url})\n**Type**: {BUG|ENHANCEMENT|REFACTOR|CHORE|DOCUMENTATION}\n**Investigated**: {ISO timestamp}\n\n### Assessment\n\n| Metric | Value | Reasoning |\n|--------|-------|-----------|\n| Severity | {CRITICAL\\|HIGH\\|MEDIUM\\|LOW} | {Why this severity? Based on user impact, workarounds, scope of failure} |\n| Complexity | {LOW\\|MEDIUM\\|HIGH} | {Why this complexity? Based on files affected, integration points, risk} |\n| Confidence | {HIGH\\|MEDIUM\\|LOW} | {Why this confidence? Based on evidence quality, unknowns, assumptions} |\n\n\n\n---\n\n## Problem Statement\n\n{Clear 2-3 sentence description of what's wrong or what's needed}\n\n---\n\n## Analysis\n\n### Root Cause / Change Rationale\n\n{For BUG: The 5 Whys chain with evidence}\n{For ENHANCEMENT: Why this change and what it enables}\n\n### Evidence Chain\n\nWHY: {symptom}\n↓ BECAUSE: {cause 1}\n Evidence: `file.ts:123` - `{code snippet}`\n\n↓ BECAUSE: {cause 2}\n Evidence: `file.ts:456` - `{code snippet}`\n\n↓ ROOT CAUSE: {the fixable thing}\n Evidence: `file.ts:789` - `{problematic code}`\n\n### Affected Files\n\n| File | Lines | Action | Description |\n|------|-------|--------|-------------|\n| `src/x.ts` | 45-60 | UPDATE | {what changes} |\n| `src/x.test.ts` | NEW | CREATE | {test to add} |\n\n### Integration Points\n\n- `src/y.ts:20` calls this function\n- `src/z.ts:30` depends on this behavior\n- {other dependencies}\n\n### Git History\n\n- **Introduced**: {commit} - {date} - \"{message}\"\n- **Last modified**: {commit} - {date}\n- **Implication**: {regression? original bug? long-standing?}\n\n---\n\n## Implementation Plan\n\n### Step 1: {First change description}\n\n**File**: `src/x.ts`\n**Lines**: 45-60\n**Action**: UPDATE\n\n**Current code:**\n```typescript\n// Line 45-50\n{actual current code}\n```\n\n**Required change:**\n```typescript\n// What it should become\n{the fix/change}\n```\n\n**Why**: {brief rationale}\n\n---\n\n### Step 2: {Second change description}\n\n{Same structure...}\n\n---\n\n### Step N: Add/Update Tests\n\n**File**: `src/x.test.ts`\n**Action**: {CREATE|UPDATE}\n\n**Test cases to add:**\n```typescript\ndescribe('{feature}', () => {\n it('should {expected behavior}', () => {\n // Test the fix\n });\n\n it('should handle {edge case}', () => {\n // Test edge case\n });\n});\n```\n\n---\n\n## Patterns to Follow\n\n**From codebase - mirror these exactly:**\n\n```typescript\n// SOURCE: src/similar.ts:20-30\n// Pattern for {what this demonstrates}\n{actual code snippet from codebase}\n```\n\n---\n\n## Edge Cases & Risks\n\n| Risk/Edge Case | Mitigation |\n|----------------|------------|\n| {risk 1} | {how to handle} |\n| {edge case} | {how to handle} |\n\n---\n\n## Validation\n\n### Automated Checks\n\n```bash\nbun run type-check\nbun test {relevant-pattern}\nbun run lint\n```\n\n### Manual Verification\n\n1. {Step to verify the fix/feature works}\n2. {Step to verify no regression}\n\n---\n\n## Scope Boundaries\n\n**IN SCOPE:**\n- {what we're changing}\n\n**OUT OF SCOPE (do not touch):**\n- {what to leave alone}\n- {future improvements to defer}\n\n---\n\n## Metadata\n\n- **Investigated by**: Claude\n- **Timestamp**: {ISO timestamp}\n- **Artifact**: `$ARTIFACTS_DIR/investigation.md`\n```\n\n**PHASE_4_CHECKPOINT:**\n- [ ] Artifact file created\n- [ ] All sections filled with specific content\n- [ ] Code snippets are actual (not invented)\n- [ ] Steps are actionable without clarification\n\n---\n\n## Phase 5: POST - GitHub Comment\n\n**Only if input was a GitHub issue (not free-form):**\n\nFormat the artifact for GitHub and post:\n\n```bash\ngh issue comment {number} --body \"$(cat <<'EOF'\n## 🔍 Investigation: {Title}\n\n**Type**: `{TYPE}`\n\n### Assessment\n\n| Metric | Value | Reasoning |\n|--------|-------|-----------|\n| {Severity or Priority} | `{VALUE}` | {one-sentence why} |\n| Complexity | `{COMPLEXITY}` | {one-sentence why} |\n| Confidence | `{CONFIDENCE}` | {one-sentence why} |\n\n---\n\n### Problem Statement\n\n{problem statement from artifact}\n\n---\n\n### Root Cause Analysis\n\n{evidence chain, formatted for GitHub}\n\n---\n\n### Implementation Plan\n\n| Step | File | Change |\n|------|------|--------|\n| 1 | `src/x.ts:45` | {description} |\n| 2 | `src/x.test.ts` | Add test for {case} |\n\n
\n📋 Detailed Implementation Steps\n\n{detailed steps from artifact}\n\n
\n\n---\n\n### Validation\n\n```bash\nbun run type-check && bun test {pattern} && bun run lint\n```\n\n---\n\n### Next Step\n\nTo implement: `/implement-issue {number}`\n\n---\n*Investigated by Claude • {timestamp}*\nEOF\n)\"\n```\n\n**PHASE_5_CHECKPOINT:**\n- [ ] Comment posted to GitHub (if GH issue)\n- [ ] Formatting renders correctly\n\n---\n\n## Phase 6: REPORT - Output to User\n\n```markdown\n## Investigation Complete\n\n**Issue**: #{number} - {title}\n**Type**: {BUG|ENHANCEMENT|REFACTOR|...}\n\n### Assessment\n\n| Metric | Value | Reasoning |\n|--------|-------|-----------|\n| {Severity or Priority} | {value} | {why - based on investigation} |\n| Complexity | {LOW\\|MEDIUM\\|HIGH} | {why - based on files/integration/risk} |\n| Confidence | {HIGH\\|MEDIUM\\|LOW} | {why - based on evidence/unknowns} |\n\n### Key Findings\n\n- **Root Cause**: {one-line summary}\n- **Files Affected**: {count} files\n- **Estimated Changes**: {brief scope}\n\n### Files to Modify\n\n| File | Action |\n|------|--------|\n| `src/x.ts` | UPDATE |\n| `src/x.test.ts` | CREATE |\n\n### Artifact\n\n📄 `$ARTIFACTS_DIR/investigation.md`\n\n### GitHub\n\n{✅ Posted to issue | ⏭️ Skipped (free-form input)}\n\n### Next Step\n\nRun `/implement-issue {number}` to execute the plan.\n```\n\n---\n\n## Handling Edge Cases\n\n### Issue is already closed\n- Report: \"Issue #{number} is already closed\"\n- Still create artifact if user wants analysis\n\n### Issue already has linked PR\n- Warn: \"PR #{pr} already addresses this issue\"\n- Ask if user wants to continue anyway\n\n### Can't determine root cause\n- Document what you found\n- Set confidence to LOW\n- Note uncertainty in artifact\n- Proceed with best hypothesis\n\n### Very large scope\n- Suggest breaking into smaller issues\n- Focus on core problem first\n- Note deferred items in \"Out of Scope\"\n\n---\n\n## Success Criteria\n\n- **ARTIFACT_COMPLETE**: All sections filled with specific, actionable content\n- **EVIDENCE_BASED**: Every claim has file:line reference or proof\n- **IMPLEMENTABLE**: Another agent can execute without questions\n- **GITHUB_POSTED**: Comment visible on issue (if GH issue)\n- **COMMITTED**: Artifact saved in git\n", + "archon-investigate-issue": "---\ndescription: Investigate a GitHub issue or problem - analyze codebase, create plan, post to GitHub\nargument-hint: \n---\n\n# Investigate Issue\n\n**Input**: $ARGUMENTS\n\n---\n\n## Your Mission\n\nInvestigate the issue/problem and produce a comprehensive implementation plan that:\n\n1. Can be executed by `/implement-issue`\n2. Is posted as a GitHub comment (if GH issue provided)\n3. Captures all context needed for one-pass implementation\n\n**Golden Rule**: The artifact you produce IS the specification. The implementing agent should be able to work from it without asking questions.\n\n---\n\n## Phase 1: PARSE - Understand Input\n\n### 1.1 Determine Input Type\n\n**Check the input format:**\n\n- Looks like a number (`123`, `#123`) → GitHub issue number\n- Starts with `http` → GitHub URL (extract issue number)\n- Anything else → Free-form description\n\n```bash\n# If GitHub issue, fetch it:\ngh issue view {number} --json title,body,labels,comments,state,url,author\n```\n\n### 1.2 Extract Context\n\n**If GitHub issue:**\n- Title: What's the reported problem?\n- Body: Details, reproduction steps, expected vs actual\n- Labels: bug? enhancement? documentation?\n- Comments: Additional context from discussion\n- State: Is it still open?\n\n**If free-form:**\n- Parse as problem description\n- Note: No GitHub posting (artifact only)\n\n### 1.2a Comments outrank the body, and linked issues are part of the input\n\nAn issue body describes a problem as first understood. Comments are where it gets\n**decided**. Treat them with that authority:\n\n- **Read every comment before planning anything.** A later maintainer comment\n supersedes the body wherever the two disagree — the body is the opening\n position, not the specification.\n- **A comment stating a decision IS the specification.** If one settles a shape,\n a field list, an interface, or an explicit \"do X, not Y\", implement that. Do\n not re-derive the choice from the body and do not average the two.\n- **Follow linked issues.** When the body or a comment points at another issue\n (`#1234`, or a full URL) for a decision, design, or contract, fetch it and read\n its comments too:\n ```bash\n gh issue view 1234 --json title,body,comments,state,url\n ```\n One level of following is enough — do not spider the whole graph.\n- **If the body and a decision conflict, say so in your investigation artifact**\n and state which you followed. A silent choice is the failure mode here.\n\nThis is not hypothetical. On 2026-08-03 a run implemented an issue's body while a\nmaintainer comment on that same issue — fetched, present in the input, posted 16\nseconds before the run started — specified a different shape entirely. The PR was\ndiscarded. The data was there; nothing said it outranked the body.\n\n### 1.3 Classify Issue Type\n\n| Type | Indicators |\n|------|------------|\n| BUG | \"broken\", \"error\", \"crash\", \"doesn't work\", stack trace |\n| ENHANCEMENT | \"add\", \"support\", \"feature\", \"would be nice\" |\n| REFACTOR | \"clean up\", \"improve\", \"simplify\", \"reorganize\" |\n| CHORE | \"update\", \"upgrade\", \"maintenance\", \"dependency\" |\n| DOCUMENTATION | \"docs\", \"readme\", \"clarify\", \"example\" |\n\n### 1.4 Assess Severity/Priority, Complexity, and Confidence\n\nEach assessment requires a **one-sentence reasoning** explaining WHY you chose that value. This reasoning must be based on concrete findings from your investigation (codebase exploration, git history, integration analysis).\n\n**For BUG issues - Severity:**\n\n| Severity | Criteria |\n|----------|----------|\n| CRITICAL | System down, data loss, security vulnerability, no workaround |\n| HIGH | Major feature broken, significant user impact, difficult workaround |\n| MEDIUM | Feature partially broken, moderate impact, workaround exists |\n| LOW | Minor issue, cosmetic, edge case, easy workaround |\n\n**For ENHANCEMENT/REFACTOR/CHORE/DOCUMENTATION - Priority:**\n\n| Priority | Criteria |\n|----------|----------|\n| HIGH | Blocking other work, frequently requested, high user value |\n| MEDIUM | Important but not urgent, moderate user value |\n| LOW | Nice to have, low urgency, minimal user impact |\n\n**Complexity** (based on codebase findings):\n\n| Complexity | Criteria |\n|------------|----------|\n| HIGH | 5+ files, multiple integration points, architectural changes, high risk |\n| MEDIUM | 2-4 files, some integration points, moderate risk |\n| LOW | 1-2 files, isolated change, low risk |\n\n**Confidence** (based on evidence quality):\n\n| Confidence | Criteria |\n|------------|----------|\n| HIGH | Clear root cause, strong evidence, well-understood code path |\n| MEDIUM | Likely root cause, some assumptions, partially understood |\n| LOW | Uncertain root cause, limited evidence, many unknowns |\n\n**PHASE_1_CHECKPOINT:**\n- [ ] Input type identified (GH issue or free-form)\n- [ ] Issue content extracted\n- [ ] Type classified\n- [ ] Severity (bug) or Priority (other) assessed with reasoning\n- [ ] Complexity assessed with reasoning (after Phase 2)\n- [ ] Confidence assessed with reasoning (after Phase 3)\n- [ ] If GH issue: confirmed it's open and not already has PR\n\n---\n\n## Phase 2: EXPLORE - Codebase Intelligence\n\n### 2.1 Search for Relevant Code\n\nUse Task tool with subagent_type=\"Explore\":\n\n```\nExplore the codebase to understand the issue:\n\nISSUE: {title/description}\n\nDISCOVER:\n1. Files directly related to this functionality\n2. How the current implementation works\n3. Integration points - what calls this, what it calls\n4. Similar patterns elsewhere to mirror\n5. Existing test patterns for this area\n6. Error handling patterns used\n\nReturn:\n- File paths with specific line numbers\n- Actual code snippets (not summaries)\n- Dependencies and data flow\n```\n\n### 2.2 Document Findings\n\n| Area | File:Lines | Notes |\n|------|-----------|-------|\n| Core logic | `src/x.ts:10-50` | Main function affected |\n| Callers | `src/y.ts:20-30` | Uses the core function |\n| Types | `src/types/x.ts:5-15` | Relevant interfaces |\n| Tests | `src/x.test.ts:1-100` | Existing test patterns |\n| Similar | `src/z.ts:40-60` | Pattern to mirror |\n\n**PHASE_2_CHECKPOINT:**\n- [ ] Explore agent completed successfully\n- [ ] Core files identified with line numbers\n- [ ] Integration points mapped\n- [ ] Similar patterns found to mirror\n- [ ] Test patterns documented\n\n---\n\n## Phase 3: ANALYZE - Form Approach\n\n### 3.0 First-Principles Analysis\n\nBefore diving into bug analysis or enhancement scoping, identify the primitive:\n\n1. **What primitive is involved?** What is the core abstraction this bug/feature touches?\n (e.g., the condition evaluator, the approval system, the isolation provider)\n2. **Is the primitive sound?** Does the existing design handle this case, or is the\n primitive itself incomplete or missing a case?\n3. **Root cause vs symptom** — are we fixing where the error manifests, or where it\n originates? Trace the data flow back to the source.\n4. **What's the minimal change?** What is the smallest edit that fixes the root cause?\n Avoid adding new abstractions when extending existing ones works.\n5. **What does this unlock?** If we add/change a primitive, what other improvements\n become possible?\n\n| Primitive | File:Lines | Sound? | Notes |\n|-----------|-----------|--------|-------|\n| {abstraction name} | `src/x.ts:10-30` | Yes/No/Partial | {if incomplete: what's missing} |\n\n### 3.1 For BUG Issues - Root Cause Analysis\n\nApply the 5 Whys:\n\n```\nWHY 1: Why does [symptom] occur?\n→ Because [cause A]\n→ Evidence: `file.ts:123` - {code snippet}\n\nWHY 2: Why does [cause A] happen?\n→ Because [cause B]\n→ Evidence: {proof}\n\n... continue until you reach fixable code ...\n\nROOT CAUSE: [the specific code/logic to change]\nEvidence: `source.ts:456` - {the problematic code}\n```\n\n**Check git history:**\n```bash\ngit log --oneline -10 -- {affected-file}\ngit blame -L {start},{end} {affected-file}\n```\n\n### 3.2 For ENHANCEMENT/REFACTOR Issues\n\n**Identify:**\n- What needs to be added/changed?\n- Where does it integrate?\n- What are the scope boundaries?\n- What should NOT be changed?\n\n### 3.3 For All Issues\n\n**Determine:**\n- Files to CREATE (new files)\n- Files to UPDATE (existing files)\n- Files to DELETE (if any)\n- Dependencies and order of changes\n- Edge cases and risks\n- Validation strategy\n\n**PHASE_3_CHECKPOINT:**\n- [ ] Root cause identified (for bugs) OR change rationale clear (for enhancements)\n- [ ] All affected files listed with specific changes\n- [ ] Scope boundaries defined (what NOT to change)\n- [ ] Risks and edge cases identified\n- [ ] Validation approach defined\n\n---\n\n## Phase 4: GENERATE - Create Artifact\n\n### 4.1 Artifact Path\n\n```bash\n```\n\n**Path:** `$ARTIFACTS_DIR/investigation.md`\n\nThis unified path allows review agents to find the artifact regardless of workflow type.\n\n### 4.2 Artifact Template\n\nWrite this structure to the artifact file.\n\n**Note on Severity vs Priority:**\n- Use **Severity** for BUG type (CRITICAL, HIGH, MEDIUM, LOW)\n- Use **Priority** for all other types (HIGH, MEDIUM, LOW)\n\n**Important:** Each assessment must include a one-sentence reasoning based on your investigation findings.\n\n```markdown\n# Investigation: {Title}\n\n**Issue**: #{number} ({url})\n**Type**: {BUG|ENHANCEMENT|REFACTOR|CHORE|DOCUMENTATION}\n**Investigated**: {ISO timestamp}\n\n### Assessment\n\n| Metric | Value | Reasoning |\n|--------|-------|-----------|\n| Severity | {CRITICAL\\|HIGH\\|MEDIUM\\|LOW} | {Why this severity? Based on user impact, workarounds, scope of failure} |\n| Complexity | {LOW\\|MEDIUM\\|HIGH} | {Why this complexity? Based on files affected, integration points, risk} |\n| Confidence | {HIGH\\|MEDIUM\\|LOW} | {Why this confidence? Based on evidence quality, unknowns, assumptions} |\n\n\n\n---\n\n## Problem Statement\n\n{Clear 2-3 sentence description of what's wrong or what's needed}\n\n---\n\n## Analysis\n\n### Root Cause / Change Rationale\n\n{For BUG: The 5 Whys chain with evidence}\n{For ENHANCEMENT: Why this change and what it enables}\n\n### Evidence Chain\n\nWHY: {symptom}\n↓ BECAUSE: {cause 1}\n Evidence: `file.ts:123` - `{code snippet}`\n\n↓ BECAUSE: {cause 2}\n Evidence: `file.ts:456` - `{code snippet}`\n\n↓ ROOT CAUSE: {the fixable thing}\n Evidence: `file.ts:789` - `{problematic code}`\n\n### Affected Files\n\n| File | Lines | Action | Description |\n|------|-------|--------|-------------|\n| `src/x.ts` | 45-60 | UPDATE | {what changes} |\n| `src/x.test.ts` | NEW | CREATE | {test to add} |\n\n### Integration Points\n\n- `src/y.ts:20` calls this function\n- `src/z.ts:30` depends on this behavior\n- {other dependencies}\n\n### Git History\n\n- **Introduced**: {commit} - {date} - \"{message}\"\n- **Last modified**: {commit} - {date}\n- **Implication**: {regression? original bug? long-standing?}\n\n---\n\n## Implementation Plan\n\n### Step 1: {First change description}\n\n**File**: `src/x.ts`\n**Lines**: 45-60\n**Action**: UPDATE\n\n**Current code:**\n```typescript\n// Line 45-50\n{actual current code}\n```\n\n**Required change:**\n```typescript\n// What it should become\n{the fix/change}\n```\n\n**Why**: {brief rationale}\n\n---\n\n### Step 2: {Second change description}\n\n{Same structure...}\n\n---\n\n### Step N: Add/Update Tests\n\n**File**: `src/x.test.ts`\n**Action**: {CREATE|UPDATE}\n\n**Test cases to add:**\n```typescript\ndescribe('{feature}', () => {\n it('should {expected behavior}', () => {\n // Test the fix\n });\n\n it('should handle {edge case}', () => {\n // Test edge case\n });\n});\n```\n\n---\n\n## Patterns to Follow\n\n**From codebase - mirror these exactly:**\n\n```typescript\n// SOURCE: src/similar.ts:20-30\n// Pattern for {what this demonstrates}\n{actual code snippet from codebase}\n```\n\n---\n\n## Edge Cases & Risks\n\n| Risk/Edge Case | Mitigation |\n|----------------|------------|\n| {risk 1} | {how to handle} |\n| {edge case} | {how to handle} |\n\n---\n\n## Validation\n\n### Automated Checks\n\n```bash\nbun run type-check\nbun test {relevant-pattern}\nbun run lint\n```\n\n### Manual Verification\n\n1. {Step to verify the fix/feature works}\n2. {Step to verify no regression}\n\n---\n\n## Scope Boundaries\n\n**IN SCOPE:**\n- {what we're changing}\n\n**OUT OF SCOPE (do not touch):**\n- {what to leave alone}\n- {future improvements to defer}\n\n---\n\n## Metadata\n\n- **Investigated by**: Claude\n- **Timestamp**: {ISO timestamp}\n- **Artifact**: `$ARTIFACTS_DIR/investigation.md`\n```\n\n**PHASE_4_CHECKPOINT:**\n- [ ] Artifact file created\n- [ ] All sections filled with specific content\n- [ ] Code snippets are actual (not invented)\n- [ ] Steps are actionable without clarification\n\n---\n\n## Phase 5: POST - GitHub Comment\n\n**Only if input was a GitHub issue (not free-form):**\n\nFormat the artifact for GitHub and post:\n\n```bash\ngh issue comment {number} --body \"$(cat <<'EOF'\n## 🔍 Investigation: {Title}\n\n**Type**: `{TYPE}`\n\n### Assessment\n\n| Metric | Value | Reasoning |\n|--------|-------|-----------|\n| {Severity or Priority} | `{VALUE}` | {one-sentence why} |\n| Complexity | `{COMPLEXITY}` | {one-sentence why} |\n| Confidence | `{CONFIDENCE}` | {one-sentence why} |\n\n---\n\n### Problem Statement\n\n{problem statement from artifact}\n\n---\n\n### Root Cause Analysis\n\n{evidence chain, formatted for GitHub}\n\n---\n\n### Implementation Plan\n\n| Step | File | Change |\n|------|------|--------|\n| 1 | `src/x.ts:45` | {description} |\n| 2 | `src/x.test.ts` | Add test for {case} |\n\n
\n📋 Detailed Implementation Steps\n\n{detailed steps from artifact}\n\n
\n\n---\n\n### Validation\n\n```bash\nbun run type-check && bun test {pattern} && bun run lint\n```\n\n---\n\n### Next Step\n\nTo implement: `/implement-issue {number}`\n\n---\n*Investigated by Claude • {timestamp}*\nEOF\n)\"\n```\n\n**PHASE_5_CHECKPOINT:**\n- [ ] Comment posted to GitHub (if GH issue)\n- [ ] Formatting renders correctly\n\n---\n\n## Phase 6: REPORT - Output to User\n\n```markdown\n## Investigation Complete\n\n**Issue**: #{number} - {title}\n**Type**: {BUG|ENHANCEMENT|REFACTOR|...}\n\n### Assessment\n\n| Metric | Value | Reasoning |\n|--------|-------|-----------|\n| {Severity or Priority} | {value} | {why - based on investigation} |\n| Complexity | {LOW\\|MEDIUM\\|HIGH} | {why - based on files/integration/risk} |\n| Confidence | {HIGH\\|MEDIUM\\|LOW} | {why - based on evidence/unknowns} |\n\n### Key Findings\n\n- **Root Cause**: {one-line summary}\n- **Files Affected**: {count} files\n- **Estimated Changes**: {brief scope}\n\n### Files to Modify\n\n| File | Action |\n|------|--------|\n| `src/x.ts` | UPDATE |\n| `src/x.test.ts` | CREATE |\n\n### Artifact\n\n📄 `$ARTIFACTS_DIR/investigation.md`\n\n### GitHub\n\n{✅ Posted to issue | ⏭️ Skipped (free-form input)}\n\n### Next Step\n\nRun `/implement-issue {number}` to execute the plan.\n```\n\n---\n\n## Handling Edge Cases\n\n### Issue is already closed\n- Report: \"Issue #{number} is already closed\"\n- Still create artifact if user wants analysis\n\n### Issue already has linked PR\n- Warn: \"PR #{pr} already addresses this issue\"\n- Ask if user wants to continue anyway\n\n### Can't determine root cause\n- Document what you found\n- Set confidence to LOW\n- Note uncertainty in artifact\n- Proceed with best hypothesis\n\n### Very large scope\n- Suggest breaking into smaller issues\n- Focus on core problem first\n- Note deferred items in \"Out of Scope\"\n\n---\n\n## Success Criteria\n\n- **ARTIFACT_COMPLETE**: All sections filled with specific, actionable content\n- **EVIDENCE_BASED**: Every claim has file:line reference or proof\n- **IMPLEMENTABLE**: Another agent can execute without questions\n- **GITHUB_POSTED**: Comment visible on issue (if GH issue)\n- **COMMITTED**: Artifact saved in git\n", "archon-issue-completion-report": "---\ndescription: Post completion report to GitHub issue with results, unaddressed items, and follow-up suggestions\nargument-hint: (none - reads from workflow artifacts)\n---\n\n# Issue Completion Report\n\n**Input**: $ARGUMENTS\n**Workflow ID**: $WORKFLOW_ID\n\n---\n\n## Your Mission\n\nCompile all workflow artifacts into a final report and post it to the original GitHub issue. Summarize what was done, what wasn't addressed (and why), and suggest follow-up issues if needed.\n\n**GitHub action**: Post completion report as a comment on the original issue\n**Output artifact**: `$ARTIFACTS_DIR/completion-report.md`\n\n---\n\n## Phase 1: LOAD — Gather All Artifacts\n\n### 1.1 Get Issue Number\n\nExtract issue number from `$ARGUMENTS`:\n\n```bash\n# $ARGUMENTS should be the issue number or URL\necho \"$ARGUMENTS\"\n```\n\n### 1.2 Get PR Info\n\n```bash\nPR_NUMBER=$(cat $ARTIFACTS_DIR/.pr-number 2>/dev/null || echo \"unknown\")\nPR_URL=$(cat $ARTIFACTS_DIR/.pr-url 2>/dev/null || echo \"unknown\")\necho \"PR: $PR_NUMBER ($PR_URL)\"\n```\n\n### 1.3 Read All Available Artifacts\n\nCheck for and read each artifact that may exist:\n\n```bash\n# Investigation/Plan\ncat $ARTIFACTS_DIR/investigation.md 2>/dev/null\ncat $ARTIFACTS_DIR/plan.md 2>/dev/null\n\n# Implementation\ncat $ARTIFACTS_DIR/implementation.md 2>/dev/null\n\n# Web research\ncat $ARTIFACTS_DIR/web-research.md 2>/dev/null\n\n# Validation\ncat $ARTIFACTS_DIR/validation.md 2>/dev/null\n\n# Review artifacts\nls $ARTIFACTS_DIR/review/ 2>/dev/null\ncat $ARTIFACTS_DIR/review/consolidated-review.md 2>/dev/null\ncat $ARTIFACTS_DIR/review/fix-report.md 2>/dev/null\n```\n\n### 1.4 Get Git Info\n\n```bash\ngit branch --show-current\ngit log --oneline -5\n```\n\n**PHASE_1_CHECKPOINT:**\n\n- [ ] Issue number identified\n- [ ] PR info loaded\n- [ ] All available artifacts read\n- [ ] Git state captured\n\n---\n\n## Phase 2: COMPILE — Build Report\n\n### 2.1 Summarize What Was Done\n\nFrom the artifacts, compile:\n\n- **Classification**: What type of issue (bug/feature/etc)\n- **Investigation/Plan**: Key findings and approach\n- **Implementation**: What was changed, files modified\n- **Validation**: Test results, lint, type-check\n- **Review**: What was reviewed, findings count\n- **Self-fix**: What review findings were fixed\n\n### 2.2 Identify Unaddressed Items\n\nFrom the fix report and consolidated review:\n\n- Findings that were SKIPPED (with reasons)\n- Findings that were BLOCKED (with reasons)\n- MEDIUM/LOW findings not auto-fixed\n- Any validation issues that persisted\n\n### 2.3 Suggest Follow-up Issues\n\nFor each unaddressed item, determine if it warrants a follow-up issue:\n\n| Item | Warrants Issue? | Why |\n|------|----------------|-----|\n| {skipped finding} | YES/NO | {reason} |\n\n**PHASE_2_CHECKPOINT:**\n\n- [ ] Summary compiled\n- [ ] Unaddressed items identified\n- [ ] Follow-up suggestions prepared\n\n---\n\n## Phase 3: GENERATE — Write Artifact\n\nWrite to `$ARTIFACTS_DIR/completion-report.md`:\n\n```markdown\n# Completion Report: Issue $ARGUMENTS\n\n**Date**: {ISO timestamp}\n**Workflow ID**: $WORKFLOW_ID\n**PR**: #{pr-number} ({pr-url})\n\n---\n\n## Summary\n\n{3-5 sentence overview of the entire workflow execution}\n\n---\n\n## Classification\n\n| Field | Value |\n|-------|-------|\n| Type | {bug/feature/enhancement/...} |\n| Complexity | {LOW/MEDIUM/HIGH} |\n| Confidence | {HIGH/MEDIUM/LOW} |\n\n---\n\n## What Was Done\n\n### Investigation/Planning\n\n{Brief summary of root cause or plan}\n\n### Implementation\n\n| File | Action | Description |\n|------|--------|-------------|\n| `{file}` | {CREATE/UPDATE} | {what changed} |\n\n### Validation\n\n| Check | Result |\n|-------|--------|\n| Type check | ✅ / ❌ |\n| Lint | ✅ / ❌ |\n| Tests | ✅ ({n} passed) / ❌ |\n\n### Review & Self-Fix\n\n- **Findings**: {n} total from review agents\n- **Fixed**: {n} (including tests, docs, simplification)\n- **Skipped**: {n}\n- **Blocked**: {n}\n\n---\n\n## Unaddressed Items\n\n{If none: \"All findings were addressed.\"}\n\n### Skipped\n\n| Finding | Severity | Reason |\n|---------|----------|--------|\n| {title} | {sev} | {reason} |\n\n### Blocked\n\n| Finding | Severity | Reason |\n|---------|----------|--------|\n| {title} | {sev} | {reason} |\n\n---\n\n## Suggested Follow-up Issues\n\n| Title | Priority | Description |\n|-------|----------|-------------|\n| \"{title}\" | {P1/P2/P3} | {brief description} |\n\n*(none)* if everything was addressed\n\n---\n\n## Artifacts\n\n| Artifact | Path |\n|----------|------|\n| Investigation/Plan | `$ARTIFACTS_DIR/{investigation or plan}.md` |\n| Web Research | `$ARTIFACTS_DIR/web-research.md` |\n| Implementation | `$ARTIFACTS_DIR/implementation.md` |\n| Consolidated Review | `$ARTIFACTS_DIR/review/consolidated-review.md` |\n| Fix Report | `$ARTIFACTS_DIR/review/fix-report.md` |\n```\n\n**PHASE_3_CHECKPOINT:**\n\n- [ ] Completion report written\n\n---\n\n## Phase 4: POST — GitHub Issue Comment\n\nPost to the original GitHub issue:\n\n```bash\nISSUE_NUMBER=$(echo \"$ARGUMENTS\" | grep -oE '[0-9]+')\n\ngh issue comment $ISSUE_NUMBER --body \"$(cat <<'EOF'\n## ✅ Issue Resolution Report\n\n**PR**: #{pr-number} ({pr-url})\n**Status**: COMPLETE\n\n---\n\n### Summary\n\n{Brief overview of what was done to resolve this issue}\n\n---\n\n### Changes Made\n\n| File | Change |\n|------|--------|\n| `{file}` | {description} |\n\n---\n\n### Validation\n\n✅ Type check | ✅ Lint | ✅ Tests ({n} passed)\n\n---\n\n### Review & Self-Fix\n\n- **{n}** review findings addressed\n- **{n}** tests added\n- **{n}** docs updated\n- **{n}** code simplifications applied\n\n---\n\n### Unaddressed Items\n\n{If none: \"All review findings were addressed in the PR.\"}\n\n{If any:}\n\n| Finding | Severity | Reason |\n|---------|----------|--------|\n| {title} | {sev} | {why not addressed} |\n\n---\n\n### Suggested Follow-up Issues\n\n{If any:}\n\n1. **{Issue Title}** ({priority}) — {brief description}\n\n{If none: \"No follow-up issues needed.\"}\n\n---\n\n*Resolved by Archon workflow `$WORKFLOW_ID`*\nEOF\n)\"\n```\n\n**PHASE_4_CHECKPOINT:**\n\n- [ ] GitHub comment posted to issue\n\n---\n\n## Phase 5: OUTPUT — Final Summary\n\n```markdown\n## Issue Resolution Complete\n\n**Issue**: $ARGUMENTS\n**PR**: #{pr-number}\n**Workflow**: $WORKFLOW_ID\n\n### Results\n\n- Implementation: ✅\n- Validation: ✅\n- Review: ✅\n- Self-fix: ✅\n\n### Unaddressed: {n} items\n### Follow-up issues suggested: {n}\n\n### Artifacts\n\n- Completion report: `$ARTIFACTS_DIR/completion-report.md`\n- GitHub comment: Posted to issue\n\n### Next Steps\n\n1. Review the PR: #{pr-number}\n2. Create suggested follow-up issues if agreed\n3. Merge when ready\n```\n\n---\n\n## Success Criteria\n\n- **ALL_ARTIFACTS_READ**: All workflow artifacts loaded and parsed\n- **REPORT_COMPILED**: Comprehensive completion report written\n- **GITHUB_POSTED**: Comment posted to original issue\n- **UNADDRESSED_DOCUMENTED**: Clear reasons for anything not fixed\n- **FOLLOWUPS_SUGGESTED**: Actionable follow-up issues recommended where appropriate\n", "archon-plan-setup": "---\ndescription: Setup for plan execution - read plan, ensure branch ready, write context artifact\nargument-hint: \n---\n\n# Plan Setup\n\n**Plan**: $ARGUMENTS\n**Workflow ID**: $WORKFLOW_ID\n\n---\n\n## Your Mission\n\nPrepare everything needed for plan implementation:\n1. Read and parse the plan (including scope limits)\n2. Ensure we're on the correct branch\n3. Write a comprehensive context artifact for subsequent steps\n\n**This step does NOT implement anything** - it only sets up the environment.\n**This step does NOT create a PR** - that happens in `archon-finalize-pr` after implementation.\n\n---\n\n## Phase 1: LOAD - Read the Plan\n\n### 1.1 Locate Plan File\n\n**Check in order:**\n\n1. **If `$ARGUMENTS` provided**: Use that path\n2. **If plan already in workflow artifacts**: Use `$ARTIFACTS_DIR/plan.md`\n\n```bash\n# Check if plan was created by archon-create-plan in this workflow\nif [ -f \"$ARTIFACTS_DIR/plan.md\" ]; then\n PLAN_PATH=\"$ARTIFACTS_DIR/plan.md\"\n echo \"Using plan from workflow: $PLAN_PATH\"\nelif [ -n \"$ARGUMENTS\" ] && [ -f \"$ARGUMENTS\" ]; then\n PLAN_PATH=\"$ARGUMENTS\"\n echo \"Using plan from arguments: $PLAN_PATH\"\nelse\n echo \"ERROR: No plan found\"\n exit 1\nfi\n```\n\n### 1.2 Load Plan File\n\nRead the plan file:\n\n```bash\ncat $PLAN_PATH\n```\n\nIf `$ARGUMENTS` is a GitHub issue URL or number (e.g., `#123`), fetch the issue body instead.\n\n### 1.3 Extract Key Information\n\nFrom the plan, identify and extract:\n\n| Field | Where to Find | Example |\n|-------|---------------|---------|\n| **Title** | First `#` heading or \"Summary\" section | \"Discord Platform Adapter\" |\n| **Summary** | \"Summary\" or \"Feature Description\" section | 1-2 sentence overview |\n| **Files to Change** | \"Files to Change\" or \"Tasks\" section | List of CREATE/UPDATE files |\n| **Validation Commands** | \"Validation Commands\" or \"Validation Strategy\" | `bun run type-check`, etc. |\n| **Acceptance Criteria** | \"Acceptance Criteria\" section | Checklist items |\n| **NOT Building (Scope Limits)** | \"NOT Building\", \"Scope Limits\", or \"Out of Scope\" section | Explicit exclusions |\n\n**CRITICAL**: The \"NOT Building\" section defines what is **intentionally excluded** from scope. This MUST be captured and passed to review agents so they don't flag intentional exclusions as bugs.\n\n### 1.4 Derive Branch Name\n\nCreate a branch name from the plan title:\n\n```\nfeature/{slug}\n```\n\nWhere `{slug}` is the title lowercased, spaces replaced with hyphens, max 50 chars.\n\nExamples:\n- \"Discord Platform Adapter\" → `feature/discord-platform-adapter`\n- \"ESLint/Prettier Integration\" → `feature/eslint-prettier-integration`\n\n**PHASE_1_CHECKPOINT:**\n\n- [ ] Plan file loaded and readable\n- [ ] Key information extracted\n- [ ] Branch name derived\n\n---\n\n## Phase 2: PREPARE - Git State\n\n### 2.1 Check Current State\n\n```bash\ngit branch --show-current\ngit status --porcelain\ngit remote get-url origin\n```\n\n### 2.2 Determine Repository Info\n\nExtract owner/repo from the remote URL for PR creation:\n\n```bash\ngh repo view --json nameWithOwner -q .nameWithOwner\n```\n\n### 2.3 Branch Decision\n\nEvaluate in order (first matching case wins):\n\n```text\n┌─ IN WORKTREE?\n│ └─ YES → Use current branch AS-IS. Do NOT switch branches. Do NOT create\n│ new branches. The isolation system has already set up the correct\n│ branch; any deviation operates on the wrong code.\n│ Log: \"Using worktree branch: {name}\"\n│\n├─ ON $BASE_BRANCH? (main, master, or configured base branch)\n│ └─ Q: Working directory clean?\n│ ├─ YES → Create and checkout: `git checkout -b {branch-name}`\n│ │ (only applies outside a worktree — e.g., manual CLI usage)\n│ └─ NO → STOP: \"Uncommitted changes on $BASE_BRANCH. Stash or commit first.\"\n│\n└─ ON OTHER BRANCH?\n └─ Q: Does it match the expected branch for this plan?\n ├─ YES → Use it, log \"Using existing branch: {name}\"\n └─ NO → STOP: \"On branch {X}, expected {Y}. Switch branches or adjust plan.\"\n```\n\n### 2.4 Sync with Remote\n\n```bash\ngit fetch origin\ngit rebase origin/$BASE_BRANCH || git merge origin/$BASE_BRANCH\n```\n\nIf conflicts occur, STOP with error: \"Merge conflicts with $BASE_BRANCH. Resolve manually.\"\n\n### 2.5 Push Branch (if commits exist)\n\nIf there are commits on the branch:\n```bash\ngit push -u origin HEAD\n```\n\nIf no commits yet (fresh branch), skip push - it will happen after implementation.\n\n**PHASE_2_CHECKPOINT:**\n\n- [ ] On correct branch\n- [ ] No uncommitted changes\n- [ ] Up to date with base branch\n\n---\n\n## Phase 3: ARTIFACT - Write Context File\n\n### 3.1 Create Artifact Directory\n\n```bash\n```\n\n### 3.2 Write Context Artifact\n\nWrite to `$ARTIFACTS_DIR/plan-context.md`:\n\n```markdown\n# Plan Context\n\n**Generated**: {YYYY-MM-DD HH:MM}\n**Workflow ID**: $WORKFLOW_ID\n**Plan Source**: $ARGUMENTS\n\n---\n\n## Branch\n\n| Field | Value |\n|-------|-------|\n| **Branch** | {branch-name} |\n| **Base** | {base-branch} |\n\n---\n\n## Plan Summary\n\n**Title**: {extracted-title}\n\n**Overview**: {1-2 sentence summary from plan}\n\n---\n\n## Files to Change\n\n{Copy the \"Files to Change\" table from the plan, or list extracted files}\n\n| File | Action |\n|------|--------|\n| `src/example.ts` | CREATE |\n| `src/other.ts` | UPDATE |\n\n---\n\n## NOT Building (Scope Limits)\n\n**CRITICAL FOR REVIEWERS**: These items are **intentionally excluded** from scope. Do NOT flag them as bugs or missing features.\n\n{Copy from plan's \"NOT Building\", \"Scope Limits\", or \"Out of Scope\" section}\n\n- {Explicit exclusion 1 with rationale}\n- {Explicit exclusion 2 with rationale}\n\n{If no explicit exclusions in plan: \"No explicit scope limits defined in plan.\"}\n\n---\n\n## Validation Commands\n\n{Copy from plan's \"Validation Commands\" section}\n\n```bash\nbun run type-check\nbun run lint\nbun test\nbun run build\n```\n\n---\n\n## Acceptance Criteria\n\n{Copy from plan's \"Acceptance Criteria\" section}\n\n- [ ] Criterion 1\n- [ ] Criterion 2\n- [ ] ...\n\n---\n\n## Patterns to Mirror\n\n{Copy key file references from plan's \"Patterns to Mirror\" section}\n\n| Pattern | Source File | Lines |\n|---------|-------------|-------|\n| {pattern-name} | `src/example.ts` | 10-50 |\n\n---\n\n## Next Steps\n\n1. `archon-confirm-plan` - Verify patterns still exist\n2. `archon-implement-tasks` - Execute the plan\n3. `archon-validate` - Run full validation\n4. `archon-finalize-pr` - Create PR and mark ready\n```\n\n**PHASE_3_CHECKPOINT:**\n\n- [ ] Artifact directory created\n- [ ] `plan-context.md` written with all sections\n- [ ] \"NOT Building\" section captured (even if empty)\n\n---\n\n## Phase 4: OUTPUT - Report to User\n\n```markdown\n## Plan Setup Complete\n\n**Plan**: `$ARGUMENTS`\n**Workflow ID**: `$WORKFLOW_ID`\n\n### Branch\n\n| Field | Value |\n|-------|-------|\n| Branch | `{branch-name}` |\n| Base | `{base-branch}` |\n\n### Plan Summary\n\n**{plan-title}**\n\n{1-2 sentence overview}\n\n### Scope\n\n- {N} files to create\n- {M} files to update\n- {K} explicit exclusions captured\n\n### Artifact\n\nContext written to: `$ARTIFACTS_DIR/plan-context.md`\n\n### Next Step\n\nProceed to `archon-confirm-plan` to verify the plan's research is still valid.\n```\n\n---\n\n## Error Handling\n\n### Plan File Not Found\n\n```\n❌ Plan not found: $ARGUMENTS\n\nVerify the path exists and try again.\n```\n\n### Uncommitted Changes on Base Branch\n\n```\n❌ Uncommitted changes on base branch\n\nOptions:\n1. Stash changes: `git stash`\n2. Commit changes: `git add . && git commit -m \"WIP\"`\n3. Discard changes: `git checkout .`\n\nThen retry.\n```\n\n### Merge Conflicts\n\n```\n❌ Merge conflicts with $BASE_BRANCH\n\nResolve conflicts manually:\n1. `git status` to see conflicts\n2. Edit conflicting files\n3. `git add `\n4. `git rebase --continue`\n\nThen retry.\n```\n\n---\n\n## Success Criteria\n\n- **PLAN_LOADED**: Plan file read and parsed\n- **SCOPE_LIMITS_CAPTURED**: \"NOT Building\" section extracted (even if empty)\n- **BRANCH_READY**: On correct branch, synced with base branch\n- **ARTIFACT_WRITTEN**: `plan-context.md` contains all required sections including scope limits\n", "archon-post-review-to-pr": "---\ndescription: Post code review findings as a comment on the PR\nargument-hint: (none - reads from artifacts)\n---\n\n# Post Review to PR\n\n---\n\n## Your Mission\n\nRead the code review findings artifact and post a formatted summary as a comment on the PR.\n\n---\n\n## Phase 1: LOAD - Get Context\n\n### 1.1 Get PR Number\n\n```bash\nPR_NUMBER=$(cat $ARTIFACTS_DIR/.pr-number)\n```\n\n**If not found:**\n```\n❌ No PR number found at $ARTIFACTS_DIR/.pr-number\nCannot post review without a PR number.\n```\n\n### 1.2 Read Review Findings\n\n```bash\ncat $ARTIFACTS_DIR/review/code-review-findings.md\n```\n\n**If not found:**\n```\n❌ No review findings found at $ARTIFACTS_DIR/review/code-review-findings.md\nRun code review first.\n```\n\n**PHASE_1_CHECKPOINT:**\n- [ ] PR number loaded\n- [ ] Review findings loaded\n\n---\n\n## Phase 2: FORMAT - Build PR Comment\n\n### 2.1 Extract Key Information\n\nFrom the review findings, extract:\n- **Verdict**: APPROVE / REQUEST_CHANGES / NEEDS_DISCUSSION\n- **Summary**: 2-3 sentence overview\n- **Findings**: All findings with severity and location\n- **Statistics**: Finding counts by severity\n\n### 2.2 Build Comment Body\n\nFormat the review as a GitHub-friendly comment:\n\n```markdown\n## 🔍 Code Review\n\n**Verdict**: {APPROVE ✅ | REQUEST_CHANGES ❌ | NEEDS_DISCUSSION 💬}\n\n{Summary from findings}\n\n---\n\n### Findings\n\n{For each finding:}\n\n#### {severity emoji} {title}\n\n**Severity**: {CRITICAL|HIGH|MEDIUM|LOW} · **Category**: {category} · **Location**: `{file}:{line}`\n\n{Issue description}\n\n
\nSuggested Fix\n\n```typescript\n{recommended fix code}\n```\n\n**Why**: {reasoning}\n\n
\n\n---\n\n{End of findings}\n\n### Summary\n\n| Severity | Count |\n|----------|-------|\n| 🔴 Critical | {n} |\n| 🟠 High | {n} |\n| 🟡 Medium | {n} |\n| 🔵 Low | {n} |\n\n{If positive observations exist:}\n\n### What's Done Well\n\n{Positive observations from review}\n\n---\n\n*Automated code review*\n```\n\n**Severity emojis:**\n- CRITICAL → 🔴\n- HIGH → 🟠\n- MEDIUM → 🟡\n- LOW → 🔵\n\n**PHASE_2_CHECKPOINT:**\n- [ ] Comment body formatted\n- [ ] All findings included\n- [ ] Statistics table present\n\n---\n\n## Phase 3: POST - Comment on PR\n\n### 3.1 Post the Comment\n\n```bash\ngh pr comment {PR_NUMBER} --body \"$(cat <<'EOF'\n{formatted comment body}\nEOF\n)\"\n```\n\n### 3.2 Verify\n\n```bash\n# Check the comment was posted\ngh pr view {PR_NUMBER} --comments --json comments --jq '.comments | length'\n```\n\n**PHASE_3_CHECKPOINT:**\n- [ ] Comment posted to PR\n- [ ] Verified comment exists\n\n---\n\n## Phase 4: OUTPUT - Report to User\n\n```markdown\n## Review Posted to PR\n\n**PR**: #{PR_NUMBER}\n**Verdict**: {verdict}\n**Findings**: {total count} ({critical} critical, {high} high, {medium} medium, {low} low)\n\nReview comment has been posted to the pull request.\n```\n\n---\n\n## Error Handling\n\n### PR not found\n- Verify PR number is correct\n- Check if PR is still open\n- Report error to user\n\n### Comment fails to post\n- Check GitHub authentication\n- Try with shorter body if too large\n- Report error with details\n\n### No findings\n- Post a clean review comment: \"No issues found. LGTM!\"\n\n---\n\n## Success Criteria\n\n- **FINDINGS_LOADED**: Review artifact read successfully\n- **COMMENT_FORMATTED**: PR comment built with all findings\n- **COMMENT_POSTED**: Comment visible on the PR\n",