Archon Dev

archon-dev

Development workflow — research, plan, build, review, ship.

Current State

• Branch: !git branch --show-current 2>/dev/null || echo "not in git repo"
• Artifacts: !ls .claude/archon/ 2>/dev/null || echo "none yet"
• Active plans: !ls .claude/archon/plans/*.plan.md 2>/dev/null | head -5 || echo "none"

---

Routing

Read `$ARGUMENTS` and determine which cookbook to load.

If the user explicitly names a cookbook (e.g., "plan", "implement"), use that. Otherwise, match intent from keywords:

If ambiguous: Ask the user which cookbook to use.

After routing: Read the matched cookbook file and follow its instructions exactly.

---

Workflow Chains

Cookbooks feed into each other. After completing one, suggest the next:

research ──► investigate ──► prd ──► plan ──► implement ──► commit ──► pr
                              ▲                    │
             debug ───────────┘      review ◄──────┘
                 │
                 ▼
               issue ──► plan (if feature) or debug (if bug)

---

Artifact Directory

All artifacts go to .claude/archon/. Create subdirectories as needed on first use.

.claude/archon/
├── prds/              # Product requirement documents
├── plans/             # Implementation plans
│   └── completed/     # Archived after implementation
├── reports/           # Implementation reports
├── issues/            # GitHub issue investigations
│   └── completed/
├── reviews/           # PR review reports
├── debug/             # Root cause analysis
└── research/          # Research findings

---

Project Detection

Do NOT hardcode project-specific commands. Detect dynamically:

• Package manager: Check for bun.lockb → bun, pnpm-lock.yaml → pnpm, yarn.lock → yarn, else npm
• Validation command: Check package.json scripts for validate, check, or verify
• Test command: Check for test script in package.json
• Conventions: Read CLAUDE.md for project-specific rules

---

Rules

1. Evidence-based: Every claim about the codebase must reference file:line 2. No speculation: If uncertain, investigate first 3. Fail fast: Surface errors immediately, never swallow them 4. Respect CLAUDE.md: Project conventions override cookbook defaults 5. No AI attribution: Never add "Generated with Claude" or "Co-Authored-By: Claude" to commits or PRs

Commit Cookbook

Analyze changes and create well-structured commits. Supports natural language file targeting. Acts on git directly — no artifact file.

Input: $ARGUMENTS — optional target description and/or commit message hint, or omit for auto-analysis.

---

Phase 1: ANALYZE — Understand What Changed

Run in parallel: 1. git status — see all modified and untracked files 2. git diff — see unstaged changes 3. git diff --staged — see already-staged changes 4. git log --oneline -5 — see recent commit style

CHECKPOINT: Changes understood before proceeding.

---

Phase 2: TARGET — Determine What to Stage

If $ARGUMENTS contains a target description, interpret it:

Safety checks (automatic, no user prompt needed):

• .env or credentials files → NEVER stage, skip silently
• Large binaries → skip and note in output
• Generated files → include if they're part of the build

---

Phase 3: CLASSIFY — Determine Commit Type

Based on the changes, classify:

---

Phase 4: GROUP — Split if Needed

If changes span multiple unrelated concerns, split into multiple commits.

For each logical group:

• Which files belong together
• What type of change it is
• Commit message for that group

---

Phase 5: DRAFT — Write Commit Message

Follow conventional commit format:

{type}({scope}): {concise description}

{Optional body explaining WHY, not WHAT — the diff shows what changed}

Rules from CLAUDE.md:

• No "Generated with Claude Code" footer
• No "Co-Authored-By: Claude"
• No robot emoji
• Write as if a human wrote it
• Focus on WHY, not WHAT
• Keep subject line under 72 characters

If $ARGUMENTS contains a message hint, use it as the basis.

---

Phase 6: EXECUTE — Stage and Commit

1. Stage specific files (NEVER use git add -A or git add . unless targeting all changes) 2. Create the commit using a HEREDOC for the message:

git add {file1} {file2} {file3}
git commit -m "$(cat <<'EOF'
{commit message}
EOF
)"

3. Verify with git status after commit

If committing multiple groups, repeat for each group in logical order.

---

Done

Report:

• Commit hash(es) created
• Files committed
• Suggest next step: /archon-dev pr to create a pull request

Examples

/archon-dev commit                          # All changes
/archon-dev commit typescript files         # *.ts only
/archon-dev commit except package-lock      # Exclude specific
/archon-dev commit only the new files       # Untracked only
/archon-dev commit staged                   # Already-staged only
/archon-dev commit the auth refactor        # Context-based targeting

Debug Cookbook

Systematic root cause analysis using hypothesis testing and evidence chains. No guessing — every claim requires proof.

Input: $ARGUMENTS — error description, GitHub issue number (#123), stack trace, or symptom. Optional: --quick for surface scan.

---

Phase 1: CLASSIFY — Parse Input

1.1 Determine Input Type

1.2 Determine Mode

• --quick flag present → Surface scan (2-3 Whys, skip git history)
• No flag → Deep analysis (full 5 Whys, git history required)

1.3 Restate the Symptom

Parse the input and restate the symptom in one clear sentence. What is actually failing?

Document:

• What's happening (the symptom)
• What's expected (the desired behavior)
• When it started (if known)
• Reproduction steps (if available)

CHECKPOINT: Input classified. Mode determined (quick/deep). Symptom clearly restated.

---

Phase 2: HYPOTHESIZE — Form Theories

2.1 Generate Hypotheses

Based on the symptom, generate 2-4 hypotheses:

2.2 Rank and Select

Start with the most probable hypothesis. If evidence refutes it, pivot to the next one.

CHECKPOINT: 2-4 hypotheses generated and ranked.

---

Phase 3: REPRODUCE — Verify the Problem

Attempt to reproduce before diving into analysis:

1. Check tests: Are there failing tests that demonstrate the issue? 2. Read the code: Trace the code path described in the symptom 3. Run commands: If safe, run the reproduction steps 4. Check logs: Look for relevant error output

If you can reproduce it, document exactly how. If you can't, note what you tried.

---

Phase 4: INVESTIGATE — The 5 Whys

Execute the 5 Whys protocol for your leading hypothesis:

WHY 1: Why does [symptom] occur?
→ Because [intermediate cause A]
→ Evidence: `file.ts:123` — {code snippet proving this}

WHY 2: Why does [intermediate cause A] happen?
→ Because [intermediate cause B]
→ Evidence: `file.ts:456` — {proof}

WHY 3: Why does [intermediate cause B] happen?
→ Because [intermediate cause C]
→ Evidence: `file.ts:789` — {proof}

WHY 4: Why does [intermediate cause C] happen?
→ Because [intermediate cause D]
→ Evidence: {proof}

WHY 5: Why does [intermediate cause D] happen?
→ Because [ROOT CAUSE]
→ Evidence: `source.ts:101` — {exact problematic code}

Quick mode: Stop at 2-3 Whys. Deep mode: Full 5 Whys required.

Evidence Standards (STRICT)

Investigation Techniques

For tracing complex code paths, launch a codebase-analyst agent:

Analyze the implementation around: [suspected area / error location]

TRACE:
1. How data flows through the affected code path
2. Entry points that lead to the failure
3. State changes and side effects along the way
4. Contracts between components in the chain

Document what exists with precise file:line references. No suggestions.

For code issues:

• Grep for error messages, function names
• Read full context around suspicious code
• Check git blame for when/why code was written
• Run the suspicious code with edge case inputs

For runtime issues:

• Check environment/config differences
• Look for initialization order dependencies
• Search for race conditions

For "it worked before" issues:

git log --oneline -20
git diff HEAD~10 [suspicious files]

Rules:

• Stop when you hit code you can change
• Every "because" MUST have evidence
• If evidence refutes a hypothesis, pivot to the next one
• If you hit a dead end, backtrack and try alternative branches

---

Phase 5: VALIDATE — Confirm Root Cause

5.1 Three Tests

If any test fails → root cause is incomplete. Go deeper or broader.

5.2 Git History (Deep Mode Required)

git log --oneline -10 -- [affected files]
git blame [affected file] | grep -A2 -B2 [line number]

Document:

• When was the problematic code introduced?
• What commit/PR added it?
• Type: regression / original bug / long-standing

5.3 Rule Out Alternatives (Deep Mode)

CHECKPOINT: All three tests pass. Git history documented (deep mode). Alternatives ruled out.

---

Phase 6: FIX OPTIONS — Identify Approaches

For each fix option, document:

Option 1: {title} (Recommended)

What to change: {specific files and modifications} Complexity: LOW / MEDIUM / HIGH Risk: {what could go wrong}

```{language} // Current (problematic): {simplified example}

// Required (fixed): {simplified example}

### Option 2: {title}

**What to change**: {specific files and modifications}
**Complexity**: LOW / MEDIUM / HIGH
**Risk**: {what could go wrong}

**Recommendation**: {which option and why}

Provide at least 2 options when possible.

---

## Phase 7: WRITE — Save Artifact

**If from a GitHub issue**: Save to `.claude/archon/issues/issue-{number}.md`
**Otherwise**: Save to `.claude/archon/debug/{date}-{slug}.md`

Create the directory if it doesn't exist.

### Artifact Template

Root Cause Analysis

Issue: {description or #number} Root Cause: {one-line actual cause} Date: {YYYY-MM-DD} Branch: {current branch} Severity: Critical / High / Medium / Low Confidence: High / Medium / Low — {reasoning} Mode: Quick / Deep

---

Symptom

{What's happening — observable behavior}

Reproduction

{Steps to reproduce, or "Could not reproduce — {what was tried}"}

Hypotheses

Evidence Chain

WHY: {symptom} ↓ BECAUSE: {cause} Evidence: file.ts:123 — {code snippet}

WHY: {cause} ↓ BECAUSE: {deeper cause} Evidence: file.ts:456 — {code snippet}

↓ ROOT CAUSE: {the fixable thing} Evidence: source.ts:789 — {problematic code}

Validation

Git History

• Introduced: {commit hash} — {message} — {date}
• Author: {who}
• Recent changes: {yes/no, when}
• Type: regression / original bug / long-standing

Affected Files

Fix Options

Option 1: {title} (Recommended)

Changes: {specific files and modifications} Complexity: LOW / MEDIUM / HIGH Risk: {what could go wrong}

Option 2: {title}

Changes: {specific files and modifications} Complexity: LOW / MEDIUM / HIGH Risk: {what could go wrong}

Recommendation

{Which option and why}

Verification

1. {Test to run} 2. {Expected outcome} 3. {How to reproduce original issue to confirm fix}

---

## Phase 8: REPORT — Present and Suggest Next Step

Summarize:
- Root cause in one sentence
- Severity and confidence
- Recommended fix approach

Link to the artifact.

**Next steps**:
- For complex fixes: `/archon-dev plan` (create a plan from the RCA)
- For simple fixes: `/archon-dev implement` (implement directly)
- For GitHub issues: Consider posting the RCA as a comment with `gh issue comment`

Implement Cookbook

Execute a plan file step by step with validation gates. No auto-retry — failures are surfaced to the user.

Input: $ARGUMENTS — path to a .plan.md file, or omit to auto-detect the latest plan. Optional: --base <branch> to override base branch.

---

Phase 0: DETECT — Project Environment

0.1 Identify Package Manager

Store the detected runner — use it for all subsequent commands.

0.2 Detect Base Branch

1. Check arguments: If $ARGUMENTS contains --base <branch>, extract that value 2. Auto-detect from remote:

   git symbolic-ref refs/remotes/origin/HEAD 2>/dev/null | sed 's@^refs/remotes/origin/@@'

3. Fallback:

   git remote show origin 2>/dev/null | grep 'HEAD branch' | awk '{print $NF}'

4. Last resort: main

Store as `{base-branch}` — use for ALL branch comparisons. Never hardcode main or master.

0.3 Identify Validation Scripts

Check package.json for available scripts: type-check, lint, lint:fix, test, build, validate.

Use the plan's "Validation Commands" section — it specifies exact commands for this project.

CHECKPOINT: Runner detected. Base branch determined. Validation scripts identified.

---

Phase 1: LOAD — Read the Plan

1. If path provided: Read the plan file at $ARGUMENTS 2. If no path: Look for the most recent .plan.md in .claude/archon/plans/ (excluding completed/) 3. If no plans found: Tell the user and suggest /archon-dev plan

Parse the plan and extract:

• Mandatory Reading list
• Step-by-Step Tasks list
• Validation Commands
• Acceptance Criteria

CHECKPOINT: Plan loaded and understood.

---

Phase 2: PREFLIGHT — Verify Readiness

2.1 Read Mandatory Reading

Read every P0 and P1 file listed in the plan. Verify that "Patterns to Mirror" code snippets are still accurate.

If patterns have drifted from what the plan describes, note the discrepancy and adapt. Do NOT blindly follow stale patterns.

2.2 Check Git State

git branch --show-current
git status --porcelain
git worktree list

2.3 Sync with Remote

git fetch origin
git pull --rebase origin {base-branch} 2>/dev/null || true

CHECKPOINT: All mandatory reading complete. Patterns verified. Branch is clean and synced.

---

Phase 3: EXECUTE — Work Through Tasks

For each task in the plan, sequentially:

1. Read the target file(s) before making changes 2. Read the MIRROR reference from the task and actually mirror it 3. Make the changes described in the task 4. Run incremental validation — at minimum, type-check after each task 5. If validation fails: Fix immediately before moving to the next task 6. If stuck after 2 fix attempts: Stop and present the issue to the user — do NOT guess

Rules:

• Follow the plan's task order (dependencies matter)
• If a task is unclear, re-read the plan context rather than improvising
• Track which tasks are complete as you go

Deviation Handling: If you must deviate from the plan:

• Note WHAT changed
• Note WHY it changed
• Continue with the deviation documented

---

Phase 4: VALIDATE — Full Validation Gate

After ALL tasks are complete, run the full validation suite from the plan:

1. Level 1: Type check 2. Level 2: Lint (run lint:fix first if available, then lint) 3. Level 3: Unit tests 4. Level 4: Full validation (if available, e.g., bun run validate) 5. Level 5: Database validation (if schema changes) 6. Level 6: Manual verification (if specified in plan)

If failures exist: Fix them and re-run the failing validation level. Repeat until all pass.

Do NOT auto-loop indefinitely. If the same failure persists after 2 fix attempts, stop and ask the user.

---

Phase 5: REPORT — Write Implementation Report

Save to .claude/archon/reports/{slug}-report.md using the plan's slug.

Create the directory if it doesn't exist.

Artifact Template

# Implementation Report

**Plan**: `{path to plan file}`
**Branch**: {current branch}
**Date**: {YYYY-MM-DD}
**Status**: COMPLETE / PARTIAL

---

## Summary

{What was done — 2-3 sentences}

## Assessment vs Reality

| Metric | Predicted | Actual | Reasoning |
|--------|-----------|--------|-----------|
| Complexity | {from plan} | {actual} | {why it matched or differed} |
| Confidence | {from plan} | {actual} | {e.g., "root cause was correct" or "had to pivot"} |

**If implementation deviated from the plan:**
- {What changed and why}

## Tasks Completed

| # | Task | Status |
|---|------|--------|
| 1 | {task description} | Done |
| 2 | {task description} | Done |
| 3 | {task description} | Skipped — {reason} |

## Validation Results

| Check | Result | Details |
|-------|--------|---------|
| Type check | PASS/FAIL | {notes} |
| Lint | PASS/FAIL | {notes} |
| Unit tests | PASS/FAIL | {X passed, Y failed} |
| Full validation | PASS/FAIL | {notes} |

## Files Changed

| File | Action | Lines Changed |
|------|--------|---------------|
| `{path}` | Created | +{N} |
| `{path}` | Modified | +{N}, -{M} |

## Tests Written

| Test File | Test Cases |
|-----------|-----------|
| `{path}` | {list of test functions} |

## Deviations from Plan

{List any deviations with rationale, or "None"}

## Issues Encountered

{List any problems and how they were resolved, or "None"}

## Open Items

{Anything left undone — "None" if fully complete}

---

Phase 6: ARCHIVE — Move Plan to Completed

mkdir -p .claude/archon/plans/completed
mv {plan-path} .claude/archon/plans/completed/

Update Source PRD (if applicable)

Check if the plan was generated from a PRD (look for "Source PRD:" in plan or matching filename):

1. Read the PRD file 2. Update the phase status from in-progress to complete 3. Save the PRD

---

Phase 7: REPORT — Present and Suggest Next Step

Summarize the implementation:

• Tasks completed vs total
• Validation status
• Assessment vs reality (did complexity/confidence match?)
• Any deviations or issues

Link to the report artifact.

If from PRD, show progress:

### PRD Progress
**PRD**: `{prd-file-path}`
**Phase Completed**: #{number} - {phase name}
**Next Phase**: {next pending phase, or "All phases complete!"}
To continue: `/archon-dev plan {prd-path}`

Next steps:

• To commit: /archon-dev commit
• To create PR: /archon-dev pr
• To review: /archon-dev review

Investigate Cookbook

Strategic research combining external knowledge with codebase feasibility. Answers "what should we do?" questions by researching options, comparing approaches, and assessing how they'd fit into the existing codebase.

Input: $ARGUMENTS — a question, technology choice, or approach to evaluate.

Use this cookbook when the question goes beyond "how does our code work" into:

• Library/tool evaluation: "Should we use X or Y?"
• Approach research: "What's the best way to add WebSocket support?"
• Feasibility assessment: "Can we migrate from SQLite to Turso?"
• Prior art: "How do other projects handle rate limiting?"
• Integration planning: "What would it take to add OpenTelemetry?"

For pure codebase questions ("how does X work?"), use the research cookbook instead.

---

Phase 1: FRAME — Define the Question

Parse $ARGUMENTS and classify:

Restate the question clearly:

QUESTION: {restated question}
TYPE: {Compare / Explore / Feasibility / Prior Art}
DECISION NEEDED: {what the user needs to decide after reading this}

CHECKPOINT: Question framed. Decision point identified.

---

Phase 2: DISCOVER — Parallel Research

Launch 2-3 agents in parallel:

Agent 1: Web Researcher (web-researcher)

Always launch. Write a detailed prompt:

Research: {the question}

FIND:
1. Current best practices and recommended approaches
2. Comparison of options (if applicable) with pros/cons
3. Official documentation for relevant libraries (match versions if known)
4. Known gotchas, performance characteristics, maintenance status
5. Real-world usage examples and case studies

Return findings with direct links to specific doc sections (not homepages).
Flag anything that's version-sensitive or recently changed.

Agent 2: Codebase Explorer (Explore)

Always launch. Write a detailed prompt:

Find everything in our codebase relevant to: {the question}

LOCATE:
1. Existing infrastructure that relates to this decision
2. Current patterns and conventions we'd need to align with
3. Dependencies already in use that overlap or conflict
4. Configuration, types, and integration points that would be affected

Return file:line references and actual code snippets.

Agent 3: Codebase Analyst (codebase-analyst)

Launch for feasibility/integration questions. Write a detailed prompt:

Analyze how {the topic} would integrate with our existing architecture.

TRACE:
1. Entry points where new code would connect
2. Data flow through affected components
3. Contracts and interfaces that constrain the approach
4. Side effects and state that would be impacted

Document what exists with file:line references. No suggestions — just map the landscape.

---

Phase 3: ASSESS — Evaluate Fit

After agents return, assess each option against the codebase:

For each option/approach:

Codebase Alignment

• Does it match our existing patterns? Which ones?
• Does it conflict with anything? What would need to change?
• What dependencies does it share with or add to our stack?

Integration Effort

• What files would need to change?
• How invasive is the change? (surface-level adapter vs deep refactor)
• Can it be adopted incrementally or is it all-or-nothing?

Trade-offs

---

Phase 4: RECOMMEND — Form Opinion

Unlike the research cookbook, this cookbook SHOULD form an opinion.

State a clear recommendation with reasoning:

RECOMMENDATION: {Option/approach}
CONFIDENCE: {High/Medium/Low}
REASONING: {2-3 sentences — why this over alternatives, grounded in codebase evidence}

If no clear winner exists, say so and explain what additional information would tip the decision.

---

Phase 5: WRITE — Save Artifact

Save to .claude/archon/research/{date}-{slug}.md.

Create the directory if it doesn't exist.

Artifact Template

---
date: {ISO timestamp}
topic: "{Question}"
type: {compare / explore / feasibility / prior-art}
tags: [investigate, {relevant topics}]
status: complete
recommendation: "{short recommendation}"
---

# Investigation: {Question}

## Decision Needed

{What the user needs to decide after reading this}

## Summary

{3-4 sentence overview of findings and recommendation}

## Current State

{What exists in our codebase today that's relevant — with file:line refs}

## Research Findings

### {Option/Approach A}

**What it is**: {brief description}
**Source**: {links to docs, articles}

**Pros**:
- {pro with evidence}

**Cons**:
- {con with evidence}

**Codebase fit**: {how it aligns with our patterns — file:line refs}

### {Option/Approach B}

...

## Comparison

| Dimension | {Option A} | {Option B} |
|-----------|-----------|-----------|
| Codebase fit | {assessment} | {assessment} |
| Integration effort | {LOW/MED/HIGH} | {LOW/MED/HIGH} |
| Learning curve | {assessment} | {assessment} |
| Maintenance outlook | {assessment} | {assessment} |

## Integration Analysis

{How the recommended approach would connect to existing code}

**Affected areas**:

| File/Area | Impact | Notes |
|-----------|--------|-------|
| `{path}` | {what changes} | {details} |

**Constraints**:
- {architectural constraint from codebase}
- {dependency constraint}

## Recommendation

**{Option/Approach}** — Confidence: {High/Medium/Low}

{Why this option, grounded in both external research and codebase evidence.
What makes it the best fit for THIS project specifically.}

## Next Steps

{Concrete actions to move forward with the recommendation}

## Open Questions

- {Anything that could change the recommendation}

---

Phase 6: REPORT — Present to User

Summarize:

• The question and what was researched
• Top 2-3 findings from external research
• How options fit (or don't) with the codebase
• Clear recommendation with confidence level

Link to the artifact.

Next steps:

• To write requirements: /archon-dev prd {recommended approach}
• To plan implementation: /archon-dev plan {recommended approach}
• For deeper codebase context: /archon-dev research {specific component}

Issue Cookbook

Create well-structured GitHub issues from conversation context. Classifies bug vs feature, finds the right template, validates with a subagent, and submits via gh.

Input: $ARGUMENTS — description of the bug or feature, or omit to use recent conversation context.

---

Phase 1: CLASSIFY — Bug or Feature?

1.1 Determine Issue Type

Analyze $ARGUMENTS and recent conversation context:

1.2 Extract Key Details

From the conversation context, gather:

For bugs:

• What broke (symptom)
• Steps that triggered it (repro)
• Expected vs actual behavior
• Error messages or stack traces
• Which platform/workflow was involved

For features:

• The problem being solved
• Who it affects
• Proposed solution (if discussed)

CHECKPOINT: Issue type determined. Key details extracted from conversation.

---

Phase 2: DISCOVER — Find Template and Context

2.1 Find Issue Template

ls .github/ISSUE_TEMPLATE/ 2>/dev/null

Read the matching template. If no template found, scan .github/ subfolders. If still none, use a sensible default format.

2.2 Gather Codebase Context

Launch a subagent to gather evidence relevant to the issue:

For bugs — Validate and locate:

• Search for the error message or symptom in the codebase
• Identify the file(s) and function(s) involved
• Check recent git history for related changes: git log --oneline -20 --all -- {relevant paths}
• Determine the package and module scope
• Note any related open issues: gh issue list --search "{keywords}" --limit 5

For features — Find integration points:

• Identify which package(s) would be affected
• Find the interfaces or modules the feature would touch
• Check for existing partial implementations or TODOs
• Note any related open issues: gh issue list --search "{keywords}" --limit 5

CHECKPOINT: Template loaded. Codebase context gathered. No duplicate issues found.

---

Phase 3: DRAFT — Fill the Template

Fill every section of the template using the extracted details and subagent findings.

Bug Report Sections

Feature Request Sections

Draft Rules

• Write clearly and concisely — an engineer who wasn't in this conversation should understand the issue
• Include file:line references from subagent findings where relevant
• Don't speculate about root cause in bug reports — state symptoms and evidence
• For features, be specific about what "done" looks like

CHECKPOINT: All template sections filled. Issue is self-contained and actionable.

---

Phase 4: REVIEW — Validate the Draft

Present the full draft to the user before submitting:

## Issue Preview ({bug|feature})

**Title**: {title}

{full issue body}

---

Ready to submit? (Y/n)

If the user requests changes, revise and re-present.

---

Phase 5: SUBMIT — Create the Issue

5.1 Determine Labels

Based on classification and scope:

# Bug
gh issue create --label "bug" --label "{package-scope}" ...

# Feature
gh issue create --label "enhancement" --label "{package-scope}" ...

5.2 Create the Issue

gh issue create \
  --title "{title}" \
  --label "{labels}" \
  --body "$(cat <<'EOF'
{filled template body}
EOF
)"

5.3 Verify

gh issue view --json number,url,title,labels

---

Phase 6: REPORT — Summary

## Issue Created

**Issue**: #{number}
**URL**: {url}
**Title**: {title}
**Type**: {bug|feature}
**Labels**: {labels}

### Context Gathered

- Package: {package}
- Module: {module}
- Related issues: {links or "None"}

### Next Steps

- {For bugs}: `/archon-dev debug #{number}` to investigate
- {For features}: `/archon-dev prd` to write requirements, or `/archon-dev plan` to design

---

Examples

/archon-dev issue                              # Use recent conversation context
/archon-dev report this to gh                  # Same — infer from context
/archon-dev log this bug in github             # Bug from context
/archon-dev create a feature request for X     # Feature with description
/archon-dev gh issue: streaming breaks on large responses  # Bug with description

Plan Cookbook

Detailed implementation plans with codebase intelligence. The most critical cookbook — plans drive everything downstream. Creates a context-rich document that enables one-pass implementation success.

Input: $ARGUMENTS — path to PRD, feature description, or GitHub issue number.

Core Principle: PLAN ONLY — no code written. Codebase first, research second. Solutions must fit existing patterns before introducing new ones.

---

Phase 0: DETECT — Input Type Resolution

If PRD File Detected:

1. Read the PRD file 2. Parse the Implementation Phases table — find rows with Status: pending 3. Check dependencies — only select phases whose dependencies are complete 4. Select the next actionable phase — first pending phase with all dependencies complete 5. Report selection to user:

   PRD: {prd file path}
   Selected Phase: #{number} - {name}

   {If parallel phases available:}
   Note: Phase {X} can also run in parallel (in separate worktree).

   Proceeding with Phase #{number}...

If Free-form or Issue:

Proceed directly to Phase 1.

CHECKPOINT: Input type determined. If PRD: next phase selected and dependencies verified.

---

Phase 1: PARSE — Feature Understanding

1. If file path: Read it as the source document 2. If GitHub issue: Fetch with gh issue view {number} 3. If description: Use it directly 4. Always read CLAUDE.md for project conventions, architecture, and constraints

Extract:

• Core problem being solved
• User value and business impact
• Feature type: NEW_CAPABILITY | ENHANCEMENT | REFACTOR | BUG_FIX
• Complexity: LOW | MEDIUM | HIGH
• Affected systems list

Formulate user story:

As a {user type}
I want to {action/goal}
So that {benefit/value}

GATE: If requirements are AMBIGUOUS, STOP and ASK user for clarification before proceeding.

---

Phase 2: EXPLORE — Deep Codebase Intelligence

Launch 2-3 agents in parallel using the Agent tool:

Agent 1: Codebase Explorer (Explore)

Always launch. Write a detailed prompt asking it to find:

• Similar features already implemented with file:line references
• Naming conventions with actual examples
• Error handling and logging patterns
• Type definitions and test patterns
• Configuration and dependencies

Request actual code snippets — these become the "Patterns to Mirror" section.

Agent 2: Codebase Analyst (codebase-analyst)

Always launch. Write a detailed prompt asking it to:

• Map the blast radius — all files that would need to change
• Trace data flow through related components
• Identify entry points and integration contracts
• Document side effects and state changes

Agent 3: Web Researcher (web-researcher)

Launch only if the feature involves external libraries or APIs. Ask for version-specific docs (matching package.json versions), known gotchas, migration notes.

Merge Agent Results

Combine findings into a unified discovery table:

CHECKPOINT: Both agents completed. At least 3 similar implementations found. Code snippets are actual (copy-pasted, not invented).

---

Phase 3: RESEARCH — External Documentation

ONLY AFTER Phase 2 — solutions must fit existing codebase patterns first.

If web researcher was launched, format findings:

- [Library Docs v{version}](https://url#specific-section)
  - KEY_INSIGHT: {what we learned}
  - APPLIES_TO: {which task/file}
  - GOTCHA: {pitfall and how to avoid}

CHECKPOINT: URLs include specific section anchors. Versions match package.json.

---

Phase 4: DESIGN — UX Transformation

Create ASCII diagrams showing user experience before and after:

╔════════════════════════════════════════════════╗
║                  BEFORE STATE                  ║
╠════════════════════════════════════════════════╣
║   USER_FLOW: [current step-by-step]            ║
║   PAIN_POINT: [what's missing or broken]       ║
║   DATA_FLOW: [how data moves currently]        ║
╚════════════════════════════════════════════════╝

╔════════════════════════════════════════════════╗
║                  AFTER STATE                   ║
╠════════════════════════════════════════════════╣
║   USER_FLOW: [new step-by-step]                ║
║   VALUE_ADD: [what user gains]                 ║
║   DATA_FLOW: [how data moves after]            ║
╚════════════════════════════════════════════════╝

Document interaction changes:

CHECKPOINT: Before state is accurate. After state shows all new capabilities.

---

Phase 5: ARCHITECT — Strategic Design

For complex features with multiple integration points, optionally launch a second codebase-analyst agent to trace architecture around specific integration points from Phase 2.

Analyze deeply:

• ARCHITECTURE_FIT: How does this integrate with existing architecture?
• EXECUTION_ORDER: What must happen first → second → third?
• FAILURE_MODES: Edge cases, race conditions, error scenarios?
• SECURITY: Attack vectors? Data exposure? Auth/authz?

Decide and document:

APPROACH_CHOSEN: [description]
RATIONALE: [why this over alternatives — reference codebase patterns]

ALTERNATIVES_REJECTED:
- [Alternative 1]: Rejected because [reason]
- [Alternative 2]: Rejected because [reason]

NOT_BUILDING (explicit scope limits):
- [Item 1 — out of scope and why]
- [Item 2 — out of scope and why]

---

Phase 6: VALIDATE — Check Completeness

Before saving, verify:

• [ ] Every file in "Files to Change" actually exists (for UPDATE/DELETE) or parent directory exists (for CREATE)
• [ ] Every pattern cited in "Patterns to Mirror" matches the actual codebase
• [ ] Every task has a clear validation step
• [ ] Acceptance criteria are testable, not vague
• [ ] No circular dependencies between tasks

NO_PRIOR_KNOWLEDGE_TEST: Could an agent unfamiliar with this codebase implement using ONLY the plan? If not, add more context.

---

Phase 7: WRITE — Save Artifact

Save to .claude/archon/plans/{slug}.plan.md where {slug} is a kebab-case feature name.

Create the directory if it doesn't exist.

Artifact Template

# Feature: {Title}

## Summary

{1-2 sentences: what changes and why}

## User Story

As {role}
I want {goal}
So that {benefit}

## Problem Statement

{What's wrong today, with evidence — file:line references}

## Solution Statement

{Numbered list of concrete changes}

1. {change 1}
2. {change 2}
3. {change 3}

## Metadata

| Field | Value |
|-------|-------|
| Type | NEW_CAPABILITY / ENHANCEMENT / REFACTOR / BUG_FIX |
| Complexity | LOW / MEDIUM / HIGH |
| Systems Affected | {packages, modules, or areas} |
| Dependencies | {what must exist first} |
| Estimated Tasks | {number} |
| Confidence | {1-10}/10 — {rationale for one-pass implementation success} |

---

## UX Design

### Before State

{ASCII diagram — current user experience with data flows}

### After State

{ASCII diagram — new user experience with data flows}

### Interaction Changes

| Location | Before | After | User Impact |
|----------|--------|-------|-------------|
| {path/component} | {old behavior} | {new behavior} | {what changes for user} |

---

## NOT Building (Scope Limits)

- {Item 1 — explicitly out of scope and why}
- {Item 2 — explicitly out of scope and why}

---

## Mandatory Reading

**The implementation agent MUST read these files before starting any task.**

| Priority | File | Lines | Why Read This |
|----------|------|-------|---------------|
| P0 | `{path}` | {range} | {reason — e.g., "Pattern to MIRROR exactly"} |
| P1 | `{path}` | {range} | {reason — e.g., "Types to IMPORT"} |
| P2 | `{path}` | {range} | {reason — e.g., "Tests to EXTEND"} |

**External Documentation:**

| Source | Section | Why Needed |
|--------|---------|------------|
| [Lib Docs v{version}](url#anchor) | {section name} | {specific reason} |

## Patterns to Mirror

**Copy these patterns from the existing codebase.**

**{PATTERN_NAME}:**
\`\`\`{language}
// SOURCE: {file}:{lines}
{actual code snippet from the codebase}
\`\`\`

## Files to Change

| File | Action | Justification |
|------|--------|---------------|
| `{path}` | CREATE | {why} |
| `{path}` | UPDATE | {why} |
| `{path}` | DELETE | {why} |

---

## Step-by-Step Tasks

Execute in order. Each task is atomic and independently verifiable.

### Task 1: {ACTION} `{file path}`

**Action**: CREATE / UPDATE / DELETE
**Details**: {Exact changes with code snippets where helpful}
**Mirror**: `{source file}:{lines}` — follow this pattern
**Imports**: {specific imports needed}
**Gotcha**: {known issue to avoid}
**Validate**: `{specific command to verify this task}`

### Task 2: {ACTION} `{file path}`

...

---

## Testing Strategy

### Tests to Write

| Test File | Test Cases | Validates |
|-----------|-----------|-----------|
| `{path}` | {cases} | {what} |

### Edge Cases Checklist

- [ ] {edge case 1}
- [ ] {edge case 2}
- [ ] {feature-specific edge case}

---

## Validation Commands

**Detect project runner**:
- `bun.lockb` → bun
- `pnpm-lock.yaml` → pnpm
- `yarn.lock` → yarn
- else → npm

**Levels:**

1. **Type check**: `{runner} run type-check`
2. **Lint**: `{runner} run lint`
3. **Unit tests**: `{runner} run test` (or specific test file)
4. **Full validation**: `{runner} run validate` (if available)
5. **Database validation**: {if schema changes — verify tables, indexes}
6. **Manual verification**: {specific curl, CLI, or browser commands}

## Acceptance Criteria

- [ ] {criterion 1 — specific and testable}
- [ ] {criterion 2}
- [ ] All validation commands pass
- [ ] No regressions in existing tests

## Risks

| Risk | Likelihood | Impact | Mitigation |
|------|------------|--------|------------|
| {risk} | Low/Med/High | Low/Med/High | {specific mitigation} |

---

Phase 8: REPORT — Present and Suggest Next Step

Summarize the plan:

## Plan Created

**File**: `.claude/archon/plans/{slug}.plan.md`

{If from PRD:}
**Source PRD**: `{prd-file-path}`
**Phase**: #{number} - {phase name}

**Summary**: {2-3 sentence feature overview}
**Complexity**: {LOW/MEDIUM/HIGH} — {rationale}
**Confidence**: {1-10}/10 for one-pass implementation

**Scope**:
- {N} files to CREATE
- {M} files to UPDATE
- {K} total tasks

**Key Patterns**: {top 2-3 from codebase with file:line}
**UX**: BEFORE: {one-line} → AFTER: {one-line}
**Risks**: {primary risk}: {mitigation}

{If parallel phases available:}
**Parallel Opportunity**: Phase {X} can run concurrently in a separate worktree.

**Next Step**: `/archon-dev implement .claude/archon/plans/{slug}.plan.md`

If input was from a PRD file, also update the PRD: 1. Change the phase's Status from pending to in-progress 2. Add the plan file path to the Plan column

PR Cookbook

Create well-structured pull requests. Detects PR templates, auto-detects base branch, and links related artifacts. The PR itself is the artifact — no file written.

Input: $ARGUMENTS — optional PR title hint, --base <branch> override, --draft for draft PR, or omit for auto-detection.

---

Phase 0: DETECT — Base Branch

1. Check arguments: If $ARGUMENTS contains --base <branch>, extract that value 2. Auto-detect from remote:

   git symbolic-ref refs/remotes/origin/HEAD 2>/dev/null | sed 's@^refs/remotes/origin/@@'

3. Fallback:

   git remote show origin 2>/dev/null | grep 'HEAD branch' | awk '{print $NF}'

4. Last resort: main

Store as `{base-branch}` — use for ALL comparisons. Never hardcode main or master.

---

Phase 1: VALIDATE — Check Prerequisites

1.1 Verify Git State

git branch --show-current
git status --short
git log origin/{base-branch}..HEAD --oneline

1.2 Check for Existing PR

gh pr list --head $(git branch --show-current) --json number,url

If PR exists:

PR already exists for this branch: {url}
Use `gh pr view` to see details or `gh pr edit` to modify.

CHECKPOINT: Not on base branch. Working directory is clean. Has commits. No existing PR.

---

Phase 2: DISCOVER — Gather Context

2.1 Check for PR Template

ls -la .github/PULL_REQUEST_TEMPLATE.md 2>/dev/null
ls -la .github/pull_request_template.md 2>/dev/null
ls -la .github/PULL_REQUEST_TEMPLATE/ 2>/dev/null

If not found yet scan the .gothub folder and subfolders to make sure its not there before you move on

If template found: Read it and use as the PR body structure. If multiple templates: Use the default or ask user which to use. If no template: Use default format (see Phase 4).

2.2 Analyze Commits

git log origin/{base-branch}..HEAD --pretty=format:"- %s"
git log origin/{base-branch}..HEAD --pretty=format:"%h %s%n%b" --no-merges

2.3 Analyze Changed Files

git diff --stat origin/{base-branch}..HEAD
git diff --name-only origin/{base-branch}..HEAD

2.4 Gather Related Artifacts

Check .claude/archon/ for artifacts related to this work:

ls .claude/archon/plans/completed/ 2>/dev/null
ls .claude/archon/reports/ 2>/dev/null
ls .claude/archon/prds/ 2>/dev/null
ls .claude/archon/issues/ 2>/dev/null

Match artifacts to the current branch/work by filename and dates.

2.5 Determine PR Title

• If single commit: Use commit message as title
• If multiple commits: Summarize the change in imperative mood
• Format: {type}({scope}): {description} (under 70 characters)

If $ARGUMENTS provides a title hint, use it.

2.6 Extract Issue References

From commit messages, find patterns like Fixes #123, Closes #123, Relates to #123, #123.

CHECKPOINT: Template located (or none). Commits analyzed. Changed files listed. Title determined.

---

Phase 3: PUSH — Ensure Branch is Remote

git push -u origin HEAD

If push fails:

• Check for remote branch conflicts
• May need --force-with-lease if rebased (warn user first)

---

Phase 4: CREATE — Build and Submit PR

If Template Exists

Read the template and fill in each section based on commits, changes, and artifacts.

If No Template — Use Default Format

gh pr create \
  --title "{title}" \
  --base "{base-branch}" \
  {--draft if requested} \
  --body "$(cat <<'EOF'
## Summary

{1-2 sentence description of what this PR accomplishes}

## Changes

{List of commit summaries}
- {commit 1}
- {commit 2}

## Context

{Link to plan/PRD/issue if they exist. Otherwise, brief motivation.}

## Files Changed

{Count} files changed

<details>
<summary>File list</summary>

{list of changed files}

</details>

## Test Plan

- [ ] {validation step 1}
- [ ] {validation step 2}
- [ ] {validation step 3}

## Related Issues

{Any linked issues from commit messages, or "None"}
EOF
)"

Rules from CLAUDE.md:

• No "Generated with Claude Code" in description
• No AI attribution anywhere
• Write as if a human wrote it

---

Phase 5: VERIFY — Confirm PR Created

gh pr view --json number,url,title,state
gh pr checks 2>/dev/null

---

Phase 6: REPORT — Present to User

## Pull Request Created

**PR**: #{number}
**URL**: {url}
**Title**: {title}
**Base**: {base-branch} <- {current-branch}

### Summary

{Brief description}

### Changes

- {N} commits
- {M} files changed

### Related Artifacts

- Plan: `{path}` (or "None")
- Report: `{path}` (or "None")

### Checks

{Status of CI checks, or "Pending"}

### Next Steps

- Wait for CI checks to pass
- Request review: `gh pr edit --add-reviewer @username`
- Self-review first: `/archon-dev review {pr-number}`

---

Handling Edge Cases

Branch has diverged from base

git fetch origin
git rebase origin/{base-branch}
git push --force-with-lease

Warn the user before force-pushing.

PR template has required sections

Parse template for required sections (often marked with <!-- required -->). Ensure all are filled. Warn if any appear incomplete.

Draft PR requested

If --draft in $ARGUMENTS or user asks for draft:

gh pr create --draft --title "{title}" --base "{base-branch}" --body "{body}"

Suggest: /archon-dev review {pr-number} to self-review before requesting human review.

PRD Cookbook

Problem-first, hypothesis-driven product requirements. Interactive multi-round interview that focuses on WHAT and WHY, not HOW.

Input: $ARGUMENTS — feature idea, problem description, or path to research artifact.

---

Process Overview

INITIATE → FOUNDATION (questions) → GROUNDING (research) → DEEP DIVE (questions) → FEASIBILITY (research) → DECISIONS (questions) → GENERATE

Each question set builds on previous answers. Grounding phases validate assumptions with agents.

---

Phase 1: INITIATE — Confirm Understanding

If no input provided, ask:

What do you want to build?

Describe the product, feature, or capability in a few sentences.

If input provided, confirm understanding by restating:

I understand you want to build: {restated understanding}

Is this correct, or should I adjust my understanding?

If input references a research artifact, read it first and extract context.

GATE: Wait for user response before proceeding.

---

Phase 2: FOUNDATION — Problem Discovery

Present all questions at once (user can answer together):

Foundation Questions:

>

1. Who has this problem? Be specific — not just "users" but what type of person/role?

2. What problem are they facing? Describe the observable pain, not the assumed need.

3. Why can't they solve it today? What alternatives exist and why do they fail?

4. Why now? What changed that makes this worth building?

5. How will you know if you solved it? What would success look like?

GATE: Wait for user responses before proceeding.

---

Phase 3: GROUNDING — Market & Context Research

After foundation answers, launch research agents:

Web Researcher (web-researcher)

Research the market context for: {product/feature idea}

FIND:
1. Similar products/features in the market
2. How competitors solve this problem
3. Common patterns and anti-patterns
4. Recent trends or changes in this space

Return findings with direct links, key insights, and any gaps.

Codebase Explorer (Explore) — if codebase exists

Find existing functionality relevant to: {product/feature idea}

LOCATE:
1. Related existing functionality
2. Patterns that could be leveraged
3. Technical constraints or opportunities

Return file locations, code patterns, and conventions observed.

Summarize findings to user:

What I found:

- {Market insight 1}

- {Competitor approach}

- {Relevant codebase pattern, if applicable}

>

Does this change or refine your thinking?

GATE: Brief pause for user input (can be "continue" or adjustments).

---

Phase 4: DEEP DIVE — Vision & Users

Vision & Users:

>

1. Vision: In one sentence, what's the ideal end state if this succeeds wildly?

2. Primary User: Describe your most important user — their role, context, and what triggers their need.

3. Job to Be Done: Complete this: "When [situation], I want to [motivation], so I can [outcome]."

4. Non-Users: Who is explicitly NOT the target? Who should we ignore?

5. Constraints: What limitations exist? (time, budget, technical, regulatory)

GATE: Wait for user responses before proceeding.

---

Phase 5: FEASIBILITY — Technical Assessment

Launch two agents in parallel if codebase exists:

Codebase Explorer (Explore)

Assess technical feasibility for: {product/feature}

LOCATE:
1. Existing infrastructure we can leverage
2. Similar patterns already implemented
3. Integration points and dependencies

Return file locations, code patterns, and conventions.

Codebase Analyst (codebase-analyst)

Analyze technical constraints for: {product/feature}

TRACE:
1. How existing related features are implemented end-to-end
2. Data flow through potential integration points
3. Architectural patterns and boundaries

Document what exists with precise file:line references. No suggestions.

Summarize to user:

Technical Context:

- Feasibility: {HIGH/MEDIUM/LOW} because {reason}

- Can leverage: {existing patterns/infrastructure}

- Key technical risk: {main concern}

>

Any technical constraints I should know about?

GATE: Brief pause for user input.

---

Phase 6: DECISIONS — Scope & Approach

Scope & Approach:

>

1. MVP Definition: What's the absolute minimum to test if this works?

2. Must Have vs Nice to Have: What 2-3 things MUST be in v1? What can wait?

3. Key Hypothesis: Complete this: "We believe [capability] will [solve problem] for [users]. We'll know we're right when [measurable outcome]."

4. Out of Scope: What are you explicitly NOT building (even if users ask)?

5. Open Questions: What uncertainties could change the approach?

GATE: Wait for user responses before generating.

---

Phase 7: GENERATE — Write PRD

Save to .claude/archon/prds/{slug}.prd.md where {slug} is a kebab-case feature name.

Create the directory if it doesn't exist.

Artifact Template

# {Feature Name}

## Problem Statement

{2-3 sentences: Who has what problem, and what's the cost of not solving it?}

## Evidence

- {User quote, data point, or observation that proves this problem exists}
- {Another piece of evidence}
- {If none: "Assumption — needs validation through [method]"}

## Proposed Solution

{One paragraph: What we're building and why this approach over alternatives}

## Key Hypothesis

We believe {capability} will {solve problem} for {users}.
We'll know we're right when {measurable outcome}.

## What We're NOT Building

- {Out of scope item 1} — {why}
- {Out of scope item 2} — {why}

## Success Metrics

| Metric | Target | How Measured |
|--------|--------|--------------|
| {Primary metric} | {Specific number} | {Method} |
| {Secondary metric} | {Specific number} | {Method} |

## Open Questions

- [ ] {Unresolved question 1}
- [ ] {Unresolved question 2}

---

## Users & Context

**Primary User**
- **Who**: {Specific description}
- **Current behavior**: {What they do today}
- **Trigger**: {What moment triggers the need}
- **Success state**: {What "done" looks like}

**Job to Be Done**
When {situation}, I want to {motivation}, so I can {outcome}.

**Non-Users**
{Who this is NOT for and why}

---

## Solution Detail

### Core Capabilities (MoSCoW)

| Priority | Capability | Rationale |
|----------|------------|-----------|
| Must | {Feature} | {Why essential} |
| Must | {Feature} | {Why essential} |
| Should | {Feature} | {Why important but not blocking} |
| Could | {Feature} | {Nice to have} |
| Won't | {Feature} | {Explicitly deferred and why} |

### MVP Scope

{What's the minimum to validate the hypothesis}

### User Flow

{Critical path — shortest journey to value}

---

## Technical Approach

**Feasibility**: {HIGH/MEDIUM/LOW}

**Architecture Notes**
- {Key technical decision and why}
- {Dependency or integration point}

**Technical Risks**

| Risk | Likelihood | Mitigation |
|------|------------|------------|
| {Risk} | {H/M/L} | {How to handle} |

---

## Implementation Phases

<!--
  STATUS: pending | in-progress | complete
  PARALLEL: phases that can run concurrently (e.g., "with 3" or "-")
  DEPENDS: phases that must complete first (e.g., "1, 2" or "-")
-->

| # | Phase | Description | Status | Parallel | Depends | Plan |
|---|-------|-------------|--------|----------|---------|------|
| 1 | {Phase name} | {What this phase delivers} | pending | - | - | - |
| 2 | {Phase name} | {What this phase delivers} | pending | - | 1 | - |
| 3 | {Phase name} | {What this phase delivers} | pending | with 4 | 2 | - |
| 4 | {Phase name} | {What this phase delivers} | pending | with 3 | 2 | - |

### Phase Details

**Phase 1: {Name}**
- **Goal**: {What we're trying to achieve}
- **Scope**: {Bounded deliverables}
- **Success signal**: {How we know it's done}

{Continue for each phase...}

### Parallelism Notes

{Explain which phases can run concurrently and why}

---

## Decisions Log

| Decision | Choice | Alternatives | Rationale |
|----------|--------|--------------|-----------|
| {Decision} | {Choice} | {Options considered} | {Why this one} |

---

## Research Summary

**Market Context**
{Key findings from market research}

**Technical Context**
{Key findings from technical exploration}

---

Phase 8: REPORT — Present and Suggest Next Step

Summarize the PRD in 3-5 bullet points. Link to the artifact.

Present validation status:

Next step: /archon-dev plan .claude/archon/prds/{slug}.prd.md

Research Cookbook

Pure codebase cartography. Documents what IS, not what SHOULD BE. Answer questions about the codebase with evidence.

Input: $ARGUMENTS — a question about the codebase. Optional: --follow-up (append to existing research).

This cookbook is for codebase questions only. For strategic research involving external docs, library comparisons, or feasibility analysis, use the investigate cookbook instead.

---

CRITICAL: Documentarian Only

• DO NOT suggest improvements or changes
• DO NOT propose future enhancements or critique implementations
• ONLY describe what exists, where it exists, how it works, and how components interact

Every claim must have a file:line reference. No speculation.

---

Phase 1: PARSE — Understand the Question

1.1 Read Mentioned Files

If the user mentions specific files, read them FULLY first before any decomposition.

1.2 Classify the Query

1.3 Determine Scope

• Identify specific components, patterns, or concepts to investigate
• Note --follow-up flag for appending to existing research

CHECKPOINT: Query classified, scope identified.

---

Phase 2: DECOMPOSE — Break into Research Areas

Break the query into 2-5 composable research areas:

RESEARCH QUESTION: {user's question}

AREAS:
1. {Area} → Agent: {which agent}
2. {Area} → Agent: {which agent}
3. {Area} → Agent: {which agent}

Select agents based on query classification. Run in parallel when searching different areas.

---

Phase 3: EXPLORE — Deploy Parallel Agents

Launch agents in parallel using the Agent tool. Write detailed, specific prompts for each.

Agent: Codebase Explorer (Explore)

Use for Where/What/Pattern queries. Ask it to find all relevant code locations — files, functions, types, tests. Request file:line references and actual code snippets.

Agent: Codebase Analyst (codebase-analyst)

Use for How/What queries. Ask it to trace data flow, map dependencies, identify entry points, and document how components interact. Request file:line references.

Wait for ALL agents to complete before proceeding.

---

Phase 4: SYNTHESIZE — Merge Findings

1. Deduplicate — Remove overlapping findings across agents 2. Connect — Link findings across different components 3. Answer — Map findings back to the original question 4. Identify gaps — Note areas that couldn't be fully documented 5. Verify key claims — Read the most critical files yourself to confirm

---

Phase 5: WRITE — Create Artifact

Handle Follow-ups

If --follow-up and an existing research file on this topic exists in .claude/archon/research/: 1. Read the existing file 2. Append a ## Follow-up: {date} section 3. Update frontmatter last_updated

New Research

Save to .claude/archon/research/{date}-{slug}.md.

Create the directory if it doesn't exist.

Artifact Template

---
date: {ISO timestamp}
git_commit: {short hash}
branch: {branch name}
topic: "{Question/Topic}"
tags: [research, {relevant-component-names}]
status: complete
last_updated: {YYYY-MM-DD}
---

# Research: {topic}

## Question

{The original research question}

## Summary

{2-3 sentence answer — describe what exists, not what should change}

## Detailed Findings

### {Finding Area 1}

**Location**: `{file}:{lines}`

{What exists and how it works}

### {Finding Area 2}

...

## Architecture

{Current patterns, conventions, and design. ASCII diagram if helpful.}

## Code References

| File | Lines | Description |
|------|-------|-------------|
| `{path}` | {range} | {what's there} |

## Open Questions

- {Areas that need further investigation}

---

Phase 6: REPORT — Present to User

Summarize key findings in 3-5 bullet points with file:line references. Link to the artifact.

Next steps:

• To dig deeper: /archon-dev research --follow-up {topic}
• For strategic/external research: /archon-dev investigate {topic}
• To write requirements: /archon-dev prd {topic}

Review Cookbook

Structured code review for PRs or local changes. Deploys parallel review agents for thorough coverage.

Input: $ARGUMENTS — PR number, PR URL, branch name, or omit for local uncommitted changes. Optional: --approve, --request-changes.

---

Phase 1: SCOPE — Determine What to Review

1.1 Parse Input

1.2 Get PR Metadata (if PR)

gh pr view {NUMBER} --json number,title,body,author,headRefName,baseRefName,state,additions,deletions,changedFiles,files
gh pr diff {NUMBER}
gh pr diff {NUMBER} --name-only

1.3 Validate PR State

1.4 Checkout PR Branch (if PR)

gh pr checkout {NUMBER}

CHECKPOINT: Diff obtained. Scope understood. PR state is reviewable.

---

Phase 2: CONTEXT — Read Project Standards

2.1 Read CLAUDE.md

Extract key constraints: type safety, code style, testing requirements, architecture patterns.

2.2 Find Implementation Artifacts

Check .claude/archon/ for artifacts related to this work:

ls .claude/archon/reports/ 2>/dev/null
ls .claude/archon/plans/completed/ 2>/dev/null
ls .claude/archon/issues/ 2>/dev/null
ls .claude/archon/debug/ 2>/dev/null

If implementation report exists: 1. Read the report and referenced plan 2. Note documented deviations — these are INTENTIONAL, not issues 3. Only flag undocumented deviations

If no implementation report: Note in review that no report was found.

2.3 Read Affected Files

Read the full files being changed (not just the diff) — context matters. Check for related test files.

CHECKPOINT: Project rules understood. Implementation artifacts located. Changed files read.

---

Phase 3: REVIEW — Deploy Parallel Agents

Launch 2-4 review agents in parallel using the Agent tool:

Agent 1: Correctness & Logic (code-reviewer)

Always launch. Write a detailed prompt describing the specific changes, files affected, and what to look for. Ask it to check correctness, logic bugs, edge cases, error handling, and adherence to CLAUDE.md conventions.

Agent 2: Silent Failures & Error Handling (silent-failure-hunter)

Always launch. Write a detailed prompt describing the changed files. Ask it to hunt for swallowed errors, inappropriate fallbacks, missing error propagation.

Agent 3: Test Coverage (pr-test-analyzer)

Launch if code changes (not just docs/config). Describe what functionality changed and ask it to evaluate behavioral coverage gaps.

Agent 4: Simplification (code-simplifier)

Launch if changes are substantial (>100 lines). Describe the changed code and ask for simplification opportunities that preserve exact functionality.

---

Phase 4: SYNTHESIZE — Merge and Prioritize

After all agents return:

1. Deduplicate findings across agents 2. Check against implementation report — documented deviations are intentional, not issues 3. Categorize by severity:

• Critical (must fix): Bugs, security issues, data loss risks
• High (should fix): Logic errors, missing error handling, type safety violations
• Medium (consider): Pattern inconsistencies, undocumented deviations, missing edge cases
• Low (nit): Style preferences, minor optimizations

4. Verify top findings yourself — read the actual code to confirm

---

Phase 5: VALIDATE — Run Automated Checks

Detect project runner and run validation:

# Type checking
{runner} run type-check

# Linting
{runner} run lint

# Tests
{runner} run test

# Full validation (if available)
{runner} run validate

Capture pass/fail status, error count, and specific failures for each.

---

Phase 6: DECIDE — Form Recommendation

APPROVE if:

• No critical or high issues
• All validation passes
• Code follows patterns
• Changes match PR intent

REQUEST CHANGES if:

• High priority issues exist
• Validation fails but is fixable
• Missing tests for new functionality

BLOCK if:

• Critical security or data issues
• Fundamental approach is wrong
• Breaking changes without migration

---

Phase 7: WRITE — Save Review Artifact

Save to .claude/archon/reviews/{date}-pr-{number}.md (or {date}-{slug}.md for local changes).

Create the directory if it doesn't exist.

Artifact Template

# Code Review

**Target**: PR #{number} / local changes on {branch}
**Date**: {YYYY-MM-DD}
**Files Reviewed**: {count}
**Verdict**: APPROVE / REQUEST_CHANGES / BLOCK

---

## Summary

{2-3 sentence overall assessment}

## Implementation Context

| Artifact | Path |
|----------|------|
| Implementation Report | `{path}` or "Not found" |
| Original Plan | `{path}` or "Not found" |
| Documented Deviations | {count} or "N/A" |

---

## Critical Issues

### {issue title}
**File**: `{path}:{line}`
**Problem**: {description}
**Fix**: {suggested fix}

## High Priority

### {issue title}
**File**: `{path}:{line}`
**Problem**: {description}
**Suggestion**: {suggested improvement}

## Medium Priority

...

## Low Priority / Nits

...

---

## Validation Results

| Check | Status | Details |
|-------|--------|---------|
| Type Check | {PASS/FAIL} | {notes} |
| Lint | {PASS/WARN} | {count} warnings |
| Tests | {PASS/FAIL} | {count} passed |
| Full validation | {PASS/FAIL} | {notes} |

## Pattern Compliance

- [{x}] Follows existing code structure
- [{x}] Type safety maintained
- [{x}] Naming conventions followed
- [{x}] Tests added for new code
- [{x}] Documentation updated

## What's Good

{Positive observations — what was done well}

## Recommendation

**{APPROVE/REQUEST CHANGES/BLOCK}**

{Clear explanation and what needs to happen next}

---

Phase 8: PUBLISH — Post to GitHub (if PR)

# Determine review action based on recommendation and flags
# If --approve AND no critical/high issues:
gh pr review {NUMBER} --approve --body-file .claude/archon/reviews/{filename}.md

# If --request-changes OR high issues:
gh pr review {NUMBER} --request-changes --body-file .claude/archon/reviews/{filename}.md

# Otherwise just comment:
gh pr comment {NUMBER} --body-file .claude/archon/reviews/{filename}.md

If reviewing a PR, ask the user whether to post findings as a PR comment before posting.

---

Phase 9: REPORT — Present to User

Summarize the review:

• Verdict (approve/request changes/block)
• Count of issues by severity
• Top 3 most important findings
• Validation results

Link to the artifact. If PR, include the PR comment URL.

Suggest: /archon-dev review {pr-number} to self-review before requesting human review.