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:
| Intent | Keywords | Cookbook |
|---|---|---|
| Codebase questions, document what exists | "research", "how does", "what is", "where is", "trace", "find" | cookbooks/research.md |
| Strategic research, library eval, feasibility | "investigate", "should we", "can we", "compare", "evaluate", "feasibility", "best way to", "best approach" | cookbooks/investigate.md |
| Write product requirements | "prd", "requirements", "spec", "product requirement" | cookbooks/prd.md |
| Create implementation plan | "plan", "design", "architect", "write a plan" | cookbooks/plan.md |
| Execute an existing plan | "implement", "execute", "build", "code this", path to .plan.md | cookbooks/implement.md |
| Review code or PR | "review", "review PR", "code review", "review changes" | cookbooks/review.md |
| Debug or root cause analysis | "debug", "rca", "root cause", "why is", "broken", "failing" | cookbooks/debug.md |
| Commit changes | "commit", "save changes", "stage" | cookbooks/commit.md |
| Create pull request | "pr", "pull request", "create pr", "open pr" | cookbooks/pr.md |
| Report to GitHub | "issue", "report to gh", "log in github", "file a bug", "feature request", "create issue", "gh issue" | cookbooks/issue.md |
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 findingsProject 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.jsonscripts forvalidate,check, orverify - Test command: Check for
testscript inpackage.json - Conventions: Read CLAUDE.md for project-specific rules
Rules
- Evidence-based: Every claim about the codebase must reference
file:line - No speculation: If uncertain, investigate first
- Fail fast: Surface errors immediately, never swallow them
- Respect CLAUDE.md: Project conventions override cookbook defaults
- No AI attribution: Never add "Generated with Claude" or "Co-Authored-By: Claude" to commits or PRs