diff --git a/.archon/workflows/defaults/archon-piv-loop.yaml b/.archon/workflows/defaults/archon-piv-loop.yaml index c232762b89..b544814e6b 100644 --- a/.archon/workflows/defaults/archon-piv-loop.yaml +++ b/.archon/workflows/defaults/archon-piv-loop.yaml @@ -198,14 +198,10 @@ nodes: 3. **Read example test files** — understand testing patterns 4. **Check for any recent changes** — `git log --oneline -10` - ## Step 2: Determine Plan Location + ## Step 2: Plan File Location - Generate a kebab-case slug from the feature name. - Save to `.claude/archon/plans/{slug}.plan.md`. - - ```bash - mkdir -p .claude/archon/plans - ``` + Save the plan to `$ARTIFACTS_DIR/plan.md`. + The directory already exists (pre-created by the workflow executor). ## Step 3: Write the Plan @@ -282,7 +278,7 @@ nodes: ``` ## Plan Created - **File**: `.claude/archon/plans/{slug}.plan.md` + **File**: `$ARTIFACTS_DIR/plan.md` **Tasks**: {count} **Files to change**: {count} @@ -310,13 +306,9 @@ nodes: --- - ## Step 1: Find and Read the Plan + ## Step 1: Read the Plan - ```bash - ls -t .claude/archon/plans/*.plan.md 2>/dev/null | head -1 - ``` - - Read the entire plan file. Also read CLAUDE.md for conventions. + Read `$ARTIFACTS_DIR/plan.md` and CLAUDE.md for conventions. ## Step 2: Process Feedback @@ -375,10 +367,10 @@ nodes: bash: | set -e - PLAN_FILE=$(ls -t .claude/archon/plans/*.plan.md 2>/dev/null | head -1) + PLAN_FILE="$ARTIFACTS_DIR/plan.md" - if [ -z "$PLAN_FILE" ]; then - echo "ERROR: No plan file found in .claude/archon/plans/" + if [ ! -f "$PLAN_FILE" ]; then + echo "ERROR: No plan file found at $ARTIFACTS_DIR/plan.md" exit 1 fi @@ -403,8 +395,12 @@ nodes: echo "" echo "=== PLAN_END ===" - TASK_COUNT=$(grep -c "^### Task [0-9]" "$PLAN_FILE" || true) - echo "TASK_COUNT=${TASK_COUNT:-0}" + TASK_COUNT=$(grep -c "^### Task [0-9]" "$PLAN_FILE" 2>/dev/null || echo "0") + if [ "$TASK_COUNT" -eq 0 ]; then + echo "ERROR: No '### Task N:' sections found in $PLAN_FILE. Plan may be malformed." + exit 1 + fi + echo "TASK_COUNT=${TASK_COUNT}" # ═══════════════════════════════════════════════════════════════ # PHASE 3b: IMPLEMENT — Task-by-Task Loop (Ralph pattern) @@ -415,7 +411,7 @@ nodes: - id: implement depends_on: [implement-setup] idle_timeout: 600000 - model: opus[1m] + model: claude-opus-4-6[1m] loop: prompt: | # PIV Loop — Implementation Agent @@ -447,7 +443,7 @@ nodes: may have changed things. **You MUST re-read from disk:** 1. **Read the plan file** — your implementation guide - 2. **Read progress tracking** — check if `.claude/archon/plans/progress.txt` exists + 2. **Read progress tracking** — check if `$ARTIFACTS_DIR/progress.txt` exists 3. **Read CLAUDE.md** — project conventions and constraints ### 0.3 Check Git State @@ -511,7 +507,7 @@ nodes: )" ``` - Track progress in `.claude/archon/plans/progress.txt`: + Track progress in `$ARTIFACTS_DIR/progress.txt`: ``` ## Task {N}: {title} — COMPLETED Date: {ISO date} @@ -552,11 +548,9 @@ nodes: --- - ## Step 1: Find and Read the Plan + ## Step 1: Read the Plan - ```bash - ls -t .claude/archon/plans/*.plan.md 2>/dev/null | head -1 - ``` + Read `$ARTIFACTS_DIR/plan.md` to understand the intended implementation. ## Step 2: Review All Changes @@ -581,7 +575,7 @@ nodes: Fix type errors, lint warnings, missing imports, formatting. Commit any fixes: ```bash - git add -A && git commit -m "fix: address code review findings" 2>/dev/null || true + git add -A && git commit -m "fix: address code review findings" || true ``` ## Step 6: Present Review @@ -627,11 +621,7 @@ nodes: ## Step 1: Read Context - ```bash - ls -t .claude/archon/plans/*.plan.md 2>/dev/null | head -1 - ``` - - Read the plan file and CLAUDE.md for conventions. + Read `$ARTIFACTS_DIR/plan.md` and CLAUDE.md for conventions. ## Step 2: Process Feedback @@ -710,7 +700,7 @@ nodes: ## Step 1: Push Changes ```bash - git push -u origin HEAD 2>&1 || true + git push -u origin HEAD 2>&1 || echo "WARNING: Push failed — verify remote authentication and branch state before creating the PR." ``` ## Step 2: Generate Summary @@ -720,7 +710,7 @@ nodes: git diff --stat $(git merge-base HEAD $BASE_BRANCH)..HEAD ``` - Read the plan file and progress tracking for context. + Read `$ARTIFACTS_DIR/plan.md` and `$ARTIFACTS_DIR/progress.txt` for context. ## Step 3: Create PR (if not already created) diff --git a/packages/workflows/src/defaults/bundled-defaults.generated.ts b/packages/workflows/src/defaults/bundled-defaults.generated.ts index 81b0c8b2ee..0485911bc9 100644 --- a/packages/workflows/src/defaults/bundled-defaults.generated.ts +++ b/packages/workflows/src/defaults/bundled-defaults.generated.ts @@ -65,7 +65,7 @@ export const BUNDLED_WORKFLOWS: Record = { "archon-idea-to-pr": "name: archon-idea-to-pr\ndescription: |\n Use when: You have a feature idea or description and want end-to-end development.\n Input: Feature description in natural language, or path to a PRD file\n Output: PR ready for merge with comprehensive review completed\n\n Full workflow:\n 1. Create comprehensive implementation plan with codebase analysis\n 2. Setup branch and extract scope limits\n 3. Verify plan research is still valid\n 4. Implement all tasks with type-checking\n 5. Run full validation suite\n 6. Create PR with template, mark ready\n 7. Comprehensive code review (5 parallel agents with scope limit awareness)\n 8. Synthesize and fix review findings\n 9. Final summary with decision matrix -> GitHub comment + follow-up recommendations\n\n NOT for: Executing existing plans (use archon-plan-to-pr), quick fixes, standalone reviews.\n\nnodes:\n # ═══════════════════════════════════════════════════════════════════\n # PHASE 0: CREATE PLAN\n # ═══════════════════════════════════════════════════════════════════\n\n - id: create-plan\n command: archon-create-plan\n context: fresh\n\n # ═══════════════════════════════════════════════════════════════════\n # PHASE 1: SETUP\n # ═══════════════════════════════════════════════════════════════════\n\n - id: plan-setup\n command: archon-plan-setup\n depends_on: [create-plan]\n context: fresh\n\n # ═══════════════════════════════════════════════════════════════════\n # PHASE 2: CONFIRM PLAN\n # ═══════════════════════════════════════════════════════════════════\n\n - id: confirm-plan\n command: archon-confirm-plan\n depends_on: [plan-setup]\n context: fresh\n\n # ═══════════════════════════════════════════════════════════════════\n # PHASE 3: IMPLEMENT\n # ═══════════════════════════════════════════════════════════════════\n\n - id: implement-tasks\n command: archon-implement-tasks\n depends_on: [confirm-plan]\n context: fresh\n model: opus[1m]\n\n # ═══════════════════════════════════════════════════════════════════\n # PHASE 4: VALIDATE\n # ═══════════════════════════════════════════════════════════════════\n\n - id: validate\n command: archon-validate\n depends_on: [implement-tasks]\n context: fresh\n\n # ═══════════════════════════════════════════════════════════════════\n # PHASE 5: FINALIZE PR\n # ═══════════════════════════════════════════════════════════════════\n\n - id: finalize-pr\n command: archon-finalize-pr\n depends_on: [validate]\n context: fresh\n\n # ═══════════════════════════════════════════════════════════════════\n # PHASE 6: CODE REVIEW\n # ═══════════════════════════════════════════════════════════════════\n\n - id: review-scope\n command: archon-pr-review-scope\n depends_on: [finalize-pr]\n context: fresh\n\n - id: sync\n command: archon-sync-pr-with-main\n depends_on: [review-scope]\n context: fresh\n\n - id: code-review\n command: archon-code-review-agent\n depends_on: [sync]\n context: fresh\n\n - id: error-handling\n command: archon-error-handling-agent\n depends_on: [sync]\n context: fresh\n\n - id: test-coverage\n command: archon-test-coverage-agent\n depends_on: [sync]\n context: fresh\n\n - id: comment-quality\n command: archon-comment-quality-agent\n depends_on: [sync]\n context: fresh\n\n - id: docs-impact\n command: archon-docs-impact-agent\n depends_on: [sync]\n context: fresh\n\n - id: synthesize\n command: archon-synthesize-review\n depends_on: [code-review, error-handling, test-coverage, comment-quality, docs-impact]\n trigger_rule: one_success\n context: fresh\n\n # ═══════════════════════════════════════════════════════════════════\n # PHASE 7: FIX REVIEW ISSUES\n # ═══════════════════════════════════════════════════════════════════\n\n - id: implement-fixes\n command: archon-implement-review-fixes\n depends_on: [synthesize]\n context: fresh\n\n # ═══════════════════════════════════════════════════════════════════\n # PHASE 8: FINAL SUMMARY & FOLLOW-UP\n # ═══════════════════════════════════════════════════════════════════\n\n - id: workflow-summary\n command: archon-workflow-summary\n depends_on: [implement-fixes]\n context: fresh\n", "archon-interactive-prd": "name: archon-interactive-prd\ndescription: |\n Use when: User wants to create a PRD through guided conversation.\n Triggers: \"create a prd\", \"new prd\", \"interactive prd\", \"plan a feature\",\n \"product requirements\", \"write a prd\".\n NOT for: Autonomous PRD generation without human input (use archon-ralph-generate).\n\n Interactive workflow that guides the user through problem-first PRD creation:\n 1. Understand the idea → ask foundation questions → wait for answers\n 2. Research market & codebase → ask deep dive questions → wait for answers\n 3. Assess technical feasibility → ask scope questions → wait for answers\n 4. Generate PRD → validate technical claims against codebase → output\n\nprovider: claude\ninteractive: true\n\nnodes:\n # ═══════════════════════════════════════════════════════════════\n # PHASE 1: INITIATE — Understand the idea\n # ═══════════════════════════════════════════════════════════════\n\n - id: initiate\n model: sonnet\n prompt: |\n You are a sharp product manager starting a PRD creation process.\n You think from first principles — start with primitives, not features.\n\n The user wants to build: $ARGUMENTS\n\n If the input is clear, restate your understanding in 2-3 sentences and confirm:\n \"I understand you want to build: {restated understanding}. Is this correct?\"\n\n If the input is vague or empty, ask:\n \"What do you want to build? Describe the product, feature, or capability.\"\n\n Then present the Foundation Questions (all at once — the user will answer in the next step):\n\n **Foundation Questions:**\n\n 1. **Who** has this problem? Be specific — not just \"users\" but what type of person/role?\n 2. **What** problem are they facing? Describe the observable pain, not the assumed need.\n 3. **Why** can't they solve it today? What alternatives exist and why do they fail?\n 4. **Why now?** What changed that makes this worth building?\n 5. **How** will you know if you solved it? What would success look like?\n\n Keep it conversational. Don't generate any PRD content yet.\n\n # ═══════════════════════════════════════════════════════════════\n # GATE 1: User answers foundation questions\n # ═══════════════════════════════════════════════════════════════\n\n - id: foundation-gate\n approval:\n message: \"Answer the foundation questions above. Your answers will guide the research phase.\"\n capture_response: true\n depends_on: [initiate]\n\n # ═══════════════════════════════════════════════════════════════\n # PHASE 2: GROUNDING — Research market & codebase\n # ═══════════════════════════════════════════════════════════════\n\n - id: research\n model: sonnet\n prompt: |\n You are researching context for a PRD. Think from first principles —\n what already exists before proposing anything new.\n\n **The idea**: $ARGUMENTS\n\n **User's foundation answers**:\n $foundation-gate.output\n\n Research the landscape:\n\n 1. Search the web for similar products, competitors, and how others solve this problem\n 2. **Explore the codebase deeply** — find related existing functionality, APIs, UI components,\n database tables, and patterns. Read actual files, don't assume. Note exact file paths and\n what each file does.\n 3. Look for common patterns, anti-patterns, and recent trends\n\n **First principles rule**: Before suggesting anything new, verify what already exists.\n If there's an existing API endpoint, UI page, or component that partially solves the\n problem, note it explicitly. The best solution extends what exists, not replaces it.\n\n Present a summary to the user:\n\n **What I found:**\n - {Market insights — similar products, competitor approaches}\n - {What already exists in the codebase — specific files, endpoints, components}\n - {Key insight that might change the approach}\n\n Then ask the **Deep Dive Questions**:\n\n 1. **Vision**: In one sentence, what's the ideal end state if this succeeds wildly?\n 2. **Primary User**: Describe your most important user — their role, context, and what triggers their need.\n 3. **Job to Be Done**: Complete this: \"When [situation], I want to [motivation], so I can [outcome].\"\n 4. **Non-Users**: Who is explicitly NOT the target?\n 5. **Constraints**: What limitations exist? (time, budget, technical, regulatory)\n\n Does the research change or refine your thinking? Answer the deep dive questions.\n depends_on: [foundation-gate]\n\n # ═══════════════════════════════════════════════════════════════\n # GATE 2: User answers deep dive questions\n # ═══════════════════════════════════════════════════════════════\n\n - id: deepdive-gate\n approval:\n message: \"Answer the deep dive questions above (vision, primary user, JTBD, constraints). Add any adjustments from the research.\"\n capture_response: true\n depends_on: [research]\n\n # ═══════════════════════════════════════════════════════════════\n # PHASE 3: TECHNICAL GROUNDING — Feasibility from what exists\n # ═══════════════════════════════════════════════════════════════\n\n - id: technical\n model: sonnet\n prompt: |\n You are assessing technical feasibility for a PRD.\n Think from first principles — start with what exists, not what you'd build from scratch.\n\n **The idea**: $ARGUMENTS\n **Foundation answers**: $foundation-gate.output\n **Deep dive answers**: $deepdive-gate.output\n\n **CRITICAL**: Explore the codebase by READING actual files. Do not guess or assume.\n For every claim you make about the codebase, cite the exact file and line.\n\n 1. **What already exists** that partially solves this problem?\n - Read existing API endpoints, DB queries, UI components\n - Note exact function names, table schemas, component names\n - What data is already being collected/stored?\n 2. **What's the smallest change** to the existing system that solves the core problem?\n - Prefer extending existing files over creating new ones\n - Prefer using existing endpoints over creating new ones\n - Prefer adding to existing UI pages over new pages\n 3. **What are the actual primitives** we need?\n - A new DB query? An existing one that needs a parameter?\n - A new component? Or an existing component that needs a prop?\n - A new endpoint? Or an existing endpoint that already returns the data?\n 4. **What's the risk?**\n - Where could this go wrong?\n - What assumptions need validation?\n\n Present a summary:\n\n **What Already Exists (verified by reading code):**\n - {endpoint/component/query} at `{file:line}` — {what it does}\n - {endpoint/component/query} at `{file:line}` — {what it does}\n\n **Smallest Change to Solve the Problem:**\n - {change 1}: {extend/modify} `{file}` — {what to do}\n - {change 2}: {extend/modify} `{file}` — {what to do}\n\n **Technical Context:**\n - Feasibility: {HIGH/MEDIUM/LOW} because {reason}\n - Key risk: {main concern}\n - Estimated phases: {rough breakdown}\n\n Then ask the **Scope Questions**:\n\n 1. **MVP Definition**: What's the absolute minimum to test if this works?\n 2. **Must Have vs Nice to Have**: What 2-3 things MUST be in v1? What can wait?\n 3. **Key Hypothesis**: Complete this: \"We believe [capability] will [solve problem] for [users]. We'll know we're right when [measurable outcome].\"\n 4. **Out of Scope**: What are you explicitly NOT building?\n 5. **Open Questions**: What uncertainties could change the approach?\n depends_on: [deepdive-gate]\n\n # ═══════════════════════════════════════════════════════════════\n # GATE 3: User answers scope questions\n # ═══════════════════════════════════════════════════════════════\n\n - id: scope-gate\n approval:\n message: \"Answer the scope questions above (MVP, must-haves, hypothesis, exclusions). This is the final input before PRD generation.\"\n capture_response: true\n depends_on: [technical]\n\n # ═══════════════════════════════════════════════════════════════\n # PHASE 4: GENERATE — Write the PRD\n # ═══════════════════════════════════════════════════════════════\n\n - id: generate\n model: sonnet\n prompt: |\n You are generating a PRD from the user's guided inputs.\n\n **The idea**: $ARGUMENTS\n **Foundation answers**: $foundation-gate.output\n **Deep dive answers**: $deepdive-gate.output\n **Scope answers**: $scope-gate.output\n\n Generate a complete PRD file at `$ARTIFACTS_DIR/prds/{kebab-case-name}.prd.md`.\n\n First create the directory:\n ```bash\n mkdir -p $ARTIFACTS_DIR/prds\n ```\n\n **First principles rule**: Before writing the Technical Approach section, READ the\n actual codebase files you're referencing. Verify:\n - File paths exist\n - Function/component names are correct\n - API endpoints you reference actually exist (or note they need to be created)\n - DB table and column names match the schema\n - Event type names match the constants in the code\n\n The PRD must include ALL of these sections, filled from the user's answers:\n\n 1. **Problem Statement** — from foundation answers (who/what/why)\n 2. **Evidence** — from research findings and user's evidence\n 3. **Proposed Solution** — synthesized from all inputs. Prefer extending existing\n primitives over creating new ones.\n 4. **Key Hypothesis** — from scope answers\n 5. **What We're NOT Building** — from scope answers\n 6. **Success Metrics** — from foundation \"how will you know\" + scope\n 7. **Open Questions** — from scope answers\n 8. **Users & Context** — from deep dive (primary user, JTBD, non-users)\n 9. **Solution Detail** — MoSCoW table from scope must-haves, MVP definition\n 10. **Technical Approach** — from technical feasibility. MUST reference actual\n verified file paths, function names, and schemas. Mark anything unverified\n as \"needs verification\".\n 11. **Implementation Phases** — from technical breakdown, with status table\n and parallel opportunities\n 12. **Decisions Log** — key decisions made during the conversation\n\n **Rules:**\n - If info is missing, write \"TBD — needs research\" not filler\n - Be specific and concrete, not generic\n - Every file path in Technical Approach must be verified by reading the file\n - Prefer \"extend X\" over \"create new Y\" in implementation phases\n\n After writing the file, output the file path only — the validator will check it.\n depends_on: [scope-gate]\n\n # ═══════════════════════════════════════════════════════════════\n # PHASE 5: VALIDATE — Check technical claims against codebase\n # ═══════════════════════════════════════════════════════════════\n\n - id: validate\n model: sonnet\n prompt: |\n You are a technical validator checking a PRD for accuracy.\n\n Read the PRD file that was just generated. The generate node output the file path:\n $generate.output\n\n Find the PRD file — check `$ARTIFACTS_DIR/prds/` for the most recently created `.prd.md` file:\n ```bash\n ls -t $ARTIFACTS_DIR/prds/*.prd.md | head -1\n ```\n\n Read the entire PRD, then verify EVERY technical claim against the actual codebase:\n\n **Check 1: File paths** — For every file referenced in \"Technical Approach\" and\n \"Implementation Phases\", verify it exists. If it doesn't, note the correction.\n\n **Check 2: API endpoints** — For every endpoint mentioned, check if it already exists\n in `packages/server/src/routes/api.ts`. If it does, the PRD should say \"extend\" not \"create\".\n If the PRD proposes a new endpoint for data that an existing endpoint already returns,\n flag it.\n\n **Check 3: DB schemas** — For every table/column referenced, verify the actual names\n in the migration files or schema code. Check event type names against the\n `WORKFLOW_EVENT_TYPES` constant.\n\n **Check 4: UI components** — For every component referenced, verify it exists.\n If the PRD proposes a new page but an existing page already serves a similar purpose,\n flag it.\n\n **Check 5: Function/type names** — Verify function names, type names, and interface\n names are correct.\n\n After checking, if there are ANY corrections needed:\n 1. Edit the PRD file directly — fix incorrect names, paths, and references\n 2. Add a `## Validation Notes` section at the bottom documenting what was corrected\n\n If everything checks out, add:\n ```\n ## Validation Notes\n\n All technical references verified against codebase. No corrections needed.\n ```\n\n Output a summary of what was checked and corrected:\n\n ```\n ## PRD Validated\n\n **File**: `{prd-path}`\n **Checks**: {N} file paths, {N} endpoints, {N} DB references, {N} components\n **Corrections**: {count}\n {list corrections if any}\n\n To start implementation: `/prp-plan {prd-path}`\n ```\n depends_on: [generate]\n", "archon-issue-review-full": "name: archon-issue-review-full\ndescription: |\n Use when: User wants a FULL, COMPREHENSIVE fix + review pipeline for a GitHub issue.\n Triggers: \"full review\", \"comprehensive fix\", \"fix with full review\", \"deep review\", \"issue review full\".\n NOT for: Simple issue fixes (use archon-fix-github-issue instead),\n questions about issues, CI failures, PR reviews, general exploration.\n\n Full workflow:\n 1. Investigate issue -> root cause analysis, implementation plan\n 2. Implement fix -> code changes, tests, PR creation\n 3. Comprehensive review -> 5 parallel agents with scope awareness\n 4. Fix review issues -> address CRITICAL/HIGH findings\n 5. Final summary -> decision matrix, follow-up recommendations\n\nnodes:\n # ═══════════════════════════════════════════════════════════════════\n # PHASE 1: INVESTIGATE\n # ═══════════════════════════════════════════════════════════════════\n\n - id: investigate\n command: archon-investigate-issue\n\n # ═══════════════════════════════════════════════════════════════════\n # PHASE 2: IMPLEMENT\n # ═══════════════════════════════════════════════════════════════════\n\n - id: implement\n command: archon-implement-issue\n depends_on: [investigate]\n context: fresh\n\n # ═══════════════════════════════════════════════════════════════════\n # PHASE 3: CODE REVIEW\n # ═══════════════════════════════════════════════════════════════════\n\n - id: review-scope\n command: archon-pr-review-scope\n depends_on: [implement]\n context: fresh\n\n - id: sync\n command: archon-sync-pr-with-main\n depends_on: [review-scope]\n context: fresh\n\n - id: code-review\n command: archon-code-review-agent\n depends_on: [sync]\n context: fresh\n\n - id: error-handling\n command: archon-error-handling-agent\n depends_on: [sync]\n context: fresh\n\n - id: test-coverage\n command: archon-test-coverage-agent\n depends_on: [sync]\n context: fresh\n\n - id: comment-quality\n command: archon-comment-quality-agent\n depends_on: [sync]\n context: fresh\n\n - id: docs-impact\n command: archon-docs-impact-agent\n depends_on: [sync]\n context: fresh\n\n - id: synthesize\n command: archon-synthesize-review\n depends_on: [code-review, error-handling, test-coverage, comment-quality, docs-impact]\n trigger_rule: one_success\n context: fresh\n\n # ═══════════════════════════════════════════════════════════════════\n # PHASE 4: FIX REVIEW ISSUES\n # ═══════════════════════════════════════════════════════════════════\n\n - id: implement-fixes\n command: archon-implement-review-fixes\n depends_on: [synthesize]\n context: fresh\n\n # ═══════════════════════════════════════════════════════════════════\n # PHASE 5: FINAL SUMMARY\n # ═══════════════════════════════════════════════════════════════════\n\n - id: summary\n command: archon-workflow-summary\n depends_on: [implement-fixes]\n context: fresh\n", - "archon-piv-loop": "name: archon-piv-loop\ndescription: |\n Use when: User wants guided Plan-Implement-Validate development with human-in-the-loop.\n Triggers: \"piv\", \"piv loop\", \"plan implement validate\", \"guided development\",\n \"structured development\", \"build a feature\", \"develop with review\".\n NOT for: Autonomous implementation without planning (use archon-feature-development).\n NOT for: PRD creation (use archon-interactive-prd).\n NOT for: Ralph story-based implementation (use archon-ralph-dag).\n\n Interactive PIV loop workflow — the foundational AI coding methodology:\n 1. EXPLORE: Iterative conversation with human to understand the problem (arbitrary rounds)\n 2. PLAN: Create structured plan -> iterative review & revision (arbitrary rounds)\n 3. IMPLEMENT: Autonomous task-by-task implementation from plan (Ralph loop)\n 4. VALIDATE: Automated code review -> iterative human feedback & fixes (arbitrary rounds)\n\n The PIV loop comes AFTER a PRD exists. Each PIV loop focuses on ONE granular feature or bug fix.\n Input: A description of what to build, a path to an existing plan, or a GitHub issue number.\n\nprovider: claude\ninteractive: true\n\nnodes:\n # ═══════════════════════════════════════════════════════════════\n # PHASE 1: EXPLORE — Iterative exploration with human\n # Understand the idea, explore the codebase, converge on approach\n # Loops until the user says they're ready to create the plan.\n # ═══════════════════════════════════════════════════════════════\n\n - id: explore\n loop:\n prompt: |\n # PIV Loop — Exploration\n\n You are a senior engineering partner in an iterative exploration session.\n Your goal: DEEPLY UNDERSTAND what to build before any code is written.\n\n **User's request**: $ARGUMENTS\n **User's latest input**: $LOOP_USER_INPUT\n\n ---\n\n ## If this is the FIRST iteration (no user input yet):\n\n ### Step 1: Parse the Input\n\n Determine what the user provided:\n\n **If it's a file path** (ends in `.md`, `.plan.md`, or `.prd.md`):\n - Read the file\n - If it's an existing plan → summarize it and ask if they want to refine or proceed\n - If it's a PRD → identify the specific phase/feature to focus on\n\n **If it's a GitHub issue** (`#123` format):\n - Fetch it: `gh issue view {number} --json title,body,labels,comments`\n - Summarize the issue context\n\n **If it's free text**:\n - This is a feature idea or bug description. Use it directly.\n\n ### Step 2: Explore the Codebase\n\n Before asking questions, DO YOUR HOMEWORK:\n\n 1. **Read CLAUDE.md** — understand project conventions, architecture, and constraints\n 2. **Search for related code** — find existing implementations similar to what the user wants\n 3. **Read key files** — understand the current state of code the user wants to change\n 4. **Check recent git history** — `git log --oneline -20` for recent changes in the area\n\n ### Step 3: Present Your Understanding\n\n ```\n ## What I Understand\n\n You want to: {restated understanding in 2-3 sentences}\n\n ## What Already Exists\n\n - {file:line} — {what it does and how it relates}\n - {file:line} — {what it does and how it relates}\n - {pattern/component} — {how it could be extended or reused}\n\n ## Initial Architecture Thoughts\n\n Based on what exists, I'm thinking:\n - {approach 1 — extend existing X}\n - {approach 2 — if approach 1 doesn't work}\n - {key architectural decision that needs your input}\n ```\n\n ### Step 4: Ask Targeted Questions\n\n Ask 4-6 questions focused on DECISIONS, not information gathering:\n - Scope boundaries, architecture preferences, tech decisions\n - Constraints, existing code extension vs fresh build, testing expectations\n - Reference actual code you found — don't ask generic questions\n\n ---\n\n ## If the user has provided input (subsequent iterations):\n\n ### Step 1: Process Their Response\n\n Read their answers carefully. Identify:\n - Decisions they've made\n - Areas they want you to explore further\n - Questions they asked YOU back (answer these with evidence!)\n\n ### Step 2: Do Targeted Research\n\n Based on their response:\n - If they mentioned specific technologies → research best practices\n - If they pointed you to specific code → read it thoroughly\n - If they asked you to explore an area → do a thorough investigation\n - If they made architecture decisions → validate against the codebase\n\n ### Step 3: Present Updated Understanding\n\n Show what you learned, answer their questions with file:line references,\n and present your refined architecture recommendation.\n\n ### Step 4: Converge or Continue\n\n **If there are still important open questions:**\n Ask 2-4 focused questions about remaining ambiguities.\n\n **If the picture is clear and you have enough to create a plan:**\n Present a final implementation summary:\n\n ```\n ## Implementation Summary\n\n ### What We're Building\n {Clear, specific description}\n\n ### Scope Boundary\n - IN: {what's included}\n - OUT: {what's explicitly excluded}\n\n ### Architecture\n - {key decisions}\n\n ### Files That Will Change\n - `{file}` — {what changes and why}\n\n ### Success Criteria\n - [ ] {specific, testable criterion}\n - [ ] All validation passes\n\n ### Key Risks\n - {risk — and mitigation}\n ```\n\n Then tell the user: \"I have a clear picture. Say **ready** and I'll create\n the structured implementation plan, or share any final thoughts.\"\n\n **CRITICAL — READ THIS CAREFULLY**:\n - NEVER output PLAN_READY unless the user's LATEST message contains\n an EXPLICIT phrase like \"ready\", \"create the plan\", \"let's go\", \"proceed\", or \"I'm done\".\n - If the user asked a question → do NOT emit the signal. Answer the question.\n - If the user gave feedback or requested changes → do NOT emit the signal. Address it.\n - If the user said \"also check X\" or \"one more thing\" → do NOT emit the signal. Explore it.\n - If you are unsure whether the user is approving → do NOT emit the signal. Ask them.\n - The ONLY correct time to emit the signal is when the user's message CLEARLY means\n \"stop exploring, I'm ready for you to create the plan.\"\n until: PLAN_READY\n max_iterations: 15\n interactive: true\n gate_message: |\n Answer the questions above, ask me to explore specific areas,\n or say \"ready\" when you're satisfied with the exploration.\n\n # ═══════════════════════════════════════════════════════════════\n # PHASE 2: PLAN — Create the structured implementation plan\n # ═══════════════════════════════════════════════════════════════\n\n - id: create-plan\n model: sonnet\n depends_on: [explore]\n context: fresh\n prompt: |\n # PIV Loop — Create Structured Plan\n\n You are creating a structured implementation plan from a completed exploration phase.\n This plan will be the SOLE GUIDE for the implementation agent — it must be complete,\n specific, and actionable.\n\n **Original request**: $ARGUMENTS\n **Final exploration summary**: $explore.output\n\n ---\n\n ## Step 1: Read the Codebase (Again)\n\n Before writing the plan, verify your understanding is current:\n\n 1. **Read CLAUDE.md** — capture all relevant conventions\n 2. **Read every file you plan to change** — note exact current state\n 3. **Read example test files** — understand testing patterns\n 4. **Check for any recent changes** — `git log --oneline -10`\n\n ## Step 2: Determine Plan Location\n\n Generate a kebab-case slug from the feature name.\n Save to `.claude/archon/plans/{slug}.plan.md`.\n\n ```bash\n mkdir -p .claude/archon/plans\n ```\n\n ## Step 3: Write the Plan\n\n Use this template. Fill EVERY section with specific, verified information.\n\n ```markdown\n # Feature: {Title}\n\n ## Summary\n {1-2 sentences: what changes and why}\n\n ## Mission\n {The core goal in one clear statement}\n\n ## Success Criteria\n - [ ] {Specific, testable criterion}\n - [ ] All validation passes (`bun run validate` or equivalent)\n - [ ] No regressions in existing tests\n\n ## Scope\n ### In Scope\n - {What we ARE building}\n ### Out of Scope\n - {What we are NOT building — and why}\n\n ## Codebase Context\n ### Key Files\n | File | Role | Action |\n |------|------|--------|\n | `{path}` | {what it does} | CREATE / UPDATE |\n\n ### Patterns to Follow\n {Actual code snippets from the codebase to mirror}\n\n ## Architecture\n - {Decision 1 — with rationale}\n - {Decision 2 — with rationale}\n\n ## Task List\n Execute in order. Each task is atomic and independently verifiable.\n\n ### Task 1: {ACTION} `{file path}`\n **Action**: CREATE / UPDATE\n **Details**: {Exact changes — specific enough for an agent with no context}\n **Pattern**: Follow `{source file}:{lines}`\n **Validate**: `{command to verify this task}`\n\n ## Testing Strategy\n | Test File | Test Cases | Validates |\n |-----------|-----------|-----------|\n | `{path}` | {cases} | {what it validates} |\n\n ## Validation Commands\n 1. Type check: `{command}`\n 2. Lint: `{command}`\n 3. Tests: `{command}`\n 4. Full validation: `{command}`\n\n ## Risks\n | Risk | Impact | Mitigation |\n |------|--------|------------|\n | {risk} | {HIGH/MED/LOW} | {specific mitigation} |\n ```\n\n ## Step 4: Verify the Plan\n\n 1. Check every file path referenced — verify they exist\n 2. Check every pattern cited — verify the code matches\n 3. Check task ordering — ensure dependencies are respected\n 4. Check completeness — could an agent with NO context implement this?\n\n ## Step 5: Report\n\n ```\n ## Plan Created\n\n **File**: `.claude/archon/plans/{slug}.plan.md`\n **Tasks**: {count}\n **Files to change**: {count}\n\n Key decisions:\n - {decision 1}\n - {decision 2}\n\n Please review the plan and provide feedback.\n ```\n\n # ═══════════════════════════════════════════════════════════════\n # PHASE 2b: PLAN — Iterative plan refinement\n # Review and revise the plan as many times as needed.\n # ═══════════════════════════════════════════════════════════════\n\n - id: refine-plan\n depends_on: [create-plan]\n loop:\n prompt: |\n # PIV Loop — Plan Refinement\n\n The user is reviewing the implementation plan and providing feedback.\n\n **User's feedback**: $LOOP_USER_INPUT\n\n ---\n\n ## Step 1: Find and Read the Plan\n\n ```bash\n ls -t .claude/archon/plans/*.plan.md 2>/dev/null | head -1\n ```\n\n Read the entire plan file. Also read CLAUDE.md for conventions.\n\n ## Step 2: Process Feedback\n\n **If there is no user feedback yet** (first iteration, $LOOP_USER_INPUT is empty):\n - Read the plan carefully\n - Present a summary of the plan's key decisions and task list\n - Ask the user to review and provide feedback\n - Do NOT emit the completion signal on the first iteration\n\n **If the user EXPLICITLY approved** (said \"approved\", \"looks good\", \"let's go\", etc.):\n - Make no changes\n - Output: \"Plan approved. Proceeding to implementation.\"\n - Signal completion: PLAN_APPROVED\n\n **If the user provided specific feedback:**\n - Parse each piece of feedback\n - Edit the plan file directly:\n - Add/remove/modify tasks as requested\n - Update success criteria if needed\n - Adjust testing strategy if needed\n - Re-verify file paths and patterns after changes\n\n **CRITICAL**: NEVER emit PLAN_APPROVED unless the user's latest\n message EXPLICITLY says \"approved\", \"looks good\", \"ship it\", or similar approval.\n Questions, feedback, and requests for changes are NOT approval.\n\n ## Step 3: Show Changes\n\n ```\n ## Plan Revised\n\n Changes made:\n - {change 1}\n - {change 2}\n\n Updated stats:\n - Tasks: {count}\n - Files to change: {count}\n\n Review the updated plan and provide more feedback, or say \"approved\" to proceed.\n ```\n until: PLAN_APPROVED\n max_iterations: 10\n interactive: true\n gate_message: |\n Review the plan document. Provide specific feedback on what to change,\n or say \"approved\" to begin implementation.\n\n # ═══════════════════════════════════════════════════════════════\n # PHASE 3: IMPLEMENT — Setup\n # Read the plan, prepare the environment\n # ═══════════════════════════════════════════════════════════════\n\n - id: implement-setup\n depends_on: [refine-plan]\n bash: |\n set -e\n\n PLAN_FILE=$(ls -t .claude/archon/plans/*.plan.md 2>/dev/null | head -1)\n\n if [ -z \"$PLAN_FILE\" ]; then\n echo \"ERROR: No plan file found in .claude/archon/plans/\"\n exit 1\n fi\n\n # Install dependencies if needed\n if [ -f \"bun.lock\" ] || [ -f \"bun.lockb\" ]; then\n echo \"Installing dependencies...\"\n bun install --frozen-lockfile 2>&1 | tail -3\n elif [ -f \"package-lock.json\" ]; then\n npm ci 2>&1 | tail -3\n elif [ -f \"yarn.lock\" ]; then\n yarn install --frozen-lockfile 2>&1 | tail -3\n elif [ -f \"pnpm-lock.yaml\" ]; then\n pnpm install --frozen-lockfile 2>&1 | tail -3\n fi\n\n echo \"BRANCH=$(git branch --show-current)\"\n echo \"GIT_ROOT=$(git rev-parse --show-toplevel)\"\n echo \"PLAN_FILE=$PLAN_FILE\"\n\n echo \"=== PLAN_START ===\"\n cat \"$PLAN_FILE\"\n echo \"\"\n echo \"=== PLAN_END ===\"\n\n TASK_COUNT=$(grep -c \"^### Task [0-9]\" \"$PLAN_FILE\" || true)\n echo \"TASK_COUNT=${TASK_COUNT:-0}\"\n\n # ═══════════════════════════════════════════════════════════════\n # PHASE 3b: IMPLEMENT — Task-by-Task Loop (Ralph pattern)\n # Fresh context each iteration. Reads plan from disk.\n # One task per iteration. Validates before committing.\n # ═══════════════════════════════════════════════════════════════\n\n - id: implement\n depends_on: [implement-setup]\n idle_timeout: 600000\n model: opus[1m]\n loop:\n prompt: |\n # PIV Loop — Implementation Agent\n\n You are an autonomous coding agent in a FRESH session — no memory of previous iterations.\n Your job: Read the plan from disk, implement ONE task, validate, commit, update tracking, exit.\n\n **Golden Rule**: If validation fails, fix it before committing. Never commit broken code.\n\n ---\n\n ## Phase 0: CONTEXT — Load State\n\n The setup node produced this context:\n\n $implement-setup.output\n\n **User's original request**: $USER_MESSAGE\n\n ---\n\n ### 0.1 Parse Plan File\n\n Extract the `PLAN_FILE=...` line from the context above.\n\n ### 0.2 Read Current State (from disk — not from context above)\n\n The context above is a snapshot from before the loop started. Previous iterations\n may have changed things. **You MUST re-read from disk:**\n\n 1. **Read the plan file** — your implementation guide\n 2. **Read progress tracking** — check if `.claude/archon/plans/progress.txt` exists\n 3. **Read CLAUDE.md** — project conventions and constraints\n\n ### 0.3 Check Git State\n\n ```bash\n git log --oneline -10\n git status\n ```\n\n ---\n\n ## Phase 1: SELECT — Pick Next Task\n\n From the plan file, identify tasks by `### Task N:` headers.\n Cross-reference with commits from previous iterations and progress tracking.\n\n **If ALL tasks are complete** → Skip to Phase 5 (Completion).\n\n ### Announce Selection\n\n ```\n -- Task Selected ------------------------------------------------\n Task: {N} — {task title}\n Action: {CREATE / UPDATE}\n File: {file path}\n -----------------------------------------------------------------\n ```\n\n ---\n\n ## Phase 2: IMPLEMENT — Execute the Task\n\n 1. Read the file you're about to change (if it exists)\n 2. Read the pattern file referenced in the plan\n 3. Make changes following the plan EXACTLY\n 4. Type-check after each file: `bun run type-check 2>&1 || true`\n\n ---\n\n ## Phase 3: VALIDATE — Verify the Task\n\n ```bash\n bun run type-check && bun run lint && bun run test && bun run format:check\n ```\n\n If validation fails: fix, re-run (up to 3 attempts). If unfixable, note in progress\n tracking and do NOT commit broken code.\n\n ---\n\n ## Phase 4: COMMIT — Save Changes\n\n ```bash\n git add -A\n git diff --cached --stat\n git commit -m \"$(cat <<'EOF'\n {type}: {task description}\n\n PIV Task {N}: {brief details}\n EOF\n )\"\n ```\n\n Track progress in `.claude/archon/plans/progress.txt`:\n ```\n ## Task {N}: {title} — COMPLETED\n Date: {ISO date}\n Files: {list}\n Commit: {short hash}\n ---\n ```\n\n ---\n\n ## Phase 5: COMPLETE — Check All Tasks\n\n If ALL tasks are done:\n 1. Run full validation: `bun run validate 2>&1`\n 2. Push: `git push -u origin HEAD`\n 3. Signal: `COMPLETE`\n\n If tasks remain, report status and end normally. The loop engine starts a fresh iteration.\n until: COMPLETE\n max_iterations: 15\n fresh_context: true\n\n # ═══════════════════════════════════════════════════════════════\n # PHASE 4: VALIDATE — Automated code review\n # Review all changes against the plan\n # ═══════════════════════════════════════════════════════════════\n\n - id: code-review\n model: sonnet\n depends_on: [implement]\n context: fresh\n prompt: |\n # PIV Loop — Automated Code Review\n\n The implementation phase is complete. Review ALL changes against the plan.\n\n **Implementation output**: $implement.output\n\n ---\n\n ## Step 1: Find and Read the Plan\n\n ```bash\n ls -t .claude/archon/plans/*.plan.md 2>/dev/null | head -1\n ```\n\n ## Step 2: Review All Changes\n\n ```bash\n git log --oneline --no-merges $(git merge-base HEAD $BASE_BRANCH)..HEAD\n git diff $BASE_BRANCH..HEAD --stat\n git diff $BASE_BRANCH..HEAD\n ```\n\n ## Step 3: Check Against Plan\n\n For EACH task: was it implemented correctly? Do success criteria hold?\n For EACH file: check quality, security, patterns, CLAUDE.md compliance.\n\n ## Step 4: Run Validation\n\n ```bash\n bun run validate 2>&1 || (bun run type-check && bun run lint && bun run test && bun run format:check)\n ```\n\n ## Step 5: Fix Obvious Issues\n\n Fix type errors, lint warnings, missing imports, formatting. Commit any fixes:\n ```bash\n git add -A && git commit -m \"fix: address code review findings\" 2>/dev/null || true\n ```\n\n ## Step 6: Present Review\n\n ```\n ## Code Review Complete\n\n ### Implementation Status\n | Task | Status | Notes |\n |------|--------|-------|\n | {task} | DONE / PARTIAL / MISSING | {notes} |\n\n ### Validation Results\n - Type-check: PASS / FAIL\n - Lint: PASS / FAIL\n - Tests: PASS / FAIL\n - Format: PASS / FAIL\n\n ### Code Quality Findings\n {Issues found, or \"No issues found.\"}\n\n ### Recommendation\n {READY FOR REVIEW / NEEDS FIXES}\n ```\n\n # ═══════════════════════════════════════════════════════════════\n # PHASE 4b: VALIDATE — Iterative human feedback & fixes\n # The user tests the implementation and provides feedback.\n # Loops until the user approves.\n # ═══════════════════════════════════════════════════════════════\n\n - id: fix-feedback\n depends_on: [code-review]\n loop:\n prompt: |\n # PIV Loop — Address Validation Feedback\n\n The human has reviewed the implementation and provided feedback.\n\n **Human's feedback**: $LOOP_USER_INPUT\n\n ---\n\n ## Step 1: Read Context\n\n ```bash\n ls -t .claude/archon/plans/*.plan.md 2>/dev/null | head -1\n ```\n\n Read the plan file and CLAUDE.md for conventions.\n\n ## Step 2: Process Feedback\n\n **If there is no user feedback yet** (first iteration, $LOOP_USER_INPUT is empty):\n - Present the code review results and ask the user to test the implementation\n - Do NOT emit the completion signal on the first iteration\n\n **If the user EXPLICITLY approved** (said \"approved\", \"looks good\", \"ship it\", etc.):\n - Output: \"Implementation approved!\"\n - Signal: VALIDATED\n\n **CRITICAL**: NEVER emit VALIDATED unless the user's latest\n message EXPLICITLY says \"approved\", \"looks good\", \"ship it\", or similar approval.\n\n **If the user provided specific feedback:**\n 1. Read the relevant files\n 2. Understand each issue\n 3. Make the fixes\n 4. Type-check after each change\n\n ## Step 3: Full Validation\n\n ```bash\n bun run validate 2>&1 || (bun run type-check && bun run lint && bun run test && bun run format:check)\n ```\n\n ## Step 4: Commit Fixes\n\n ```bash\n git add -A\n git commit -m \"$(cat <<'EOF'\n fix: address review feedback\n\n Changes:\n - {fix 1}\n - {fix 2}\n EOF\n )\"\n ```\n\n ## Step 5: Report\n\n ```\n ## Feedback Addressed\n\n Changes made:\n - {fix 1}\n - {fix 2}\n\n Validation: {PASS / FAIL with details}\n\n Review again, or say \"approved\" to finalize.\n ```\n until: VALIDATED\n max_iterations: 10\n interactive: true\n gate_message: |\n Test the implementation yourself and review the code changes.\n Provide specific feedback on what needs fixing, or say \"approved\" to finalize.\n\n # ═══════════════════════════════════════════════════════════════\n # PHASE 5: FINALIZE — Push, create PR, generate summary\n # ═══════════════════════════════════════════════════════════════\n\n - id: finalize\n model: sonnet\n depends_on: [fix-feedback]\n context: fresh\n prompt: |\n # PIV Loop — Finalize\n\n The implementation has been approved. Push changes and create a PR.\n\n ---\n\n ## Step 1: Push Changes\n\n ```bash\n git push -u origin HEAD 2>&1 || true\n ```\n\n ## Step 2: Generate Summary\n\n ```bash\n git log --oneline --no-merges $(git merge-base HEAD $BASE_BRANCH)..HEAD\n git diff --stat $(git merge-base HEAD $BASE_BRANCH)..HEAD\n ```\n\n Read the plan file and progress tracking for context.\n\n ## Step 3: Create PR (if not already created)\n\n ```bash\n gh pr view HEAD --json url 2>/dev/null || echo \"NO_PR\"\n ```\n\n If no PR exists:\n\n ```bash\n cat .github/pull_request_template.md 2>/dev/null || echo \"NO_TEMPLATE\"\n ```\n\n Create with `gh pr create --draft --base $BASE_BRANCH`:\n - Title from the plan's feature name\n - Body summarizing the implementation\n - Use a HEREDOC for the body\n\n ## Step 4: Output Summary\n\n ```\n ===============================================================\n PIV LOOP — COMPLETE\n ===============================================================\n\n Feature: {from plan}\n Plan: {plan file path}\n Branch: {branch name}\n PR: {url}\n\n -- Tasks Completed -----------------------------------------------\n {list from progress tracking}\n\n -- Commits -------------------------------------------------------\n {git log output}\n\n -- Files Changed -------------------------------------------------\n {git diff --stat output}\n\n -- Validation ----------------------------------------------------\n All checks passed.\n ===============================================================\n ```\n", + "archon-piv-loop": "name: archon-piv-loop\ndescription: |\n Use when: User wants guided Plan-Implement-Validate development with human-in-the-loop.\n Triggers: \"piv\", \"piv loop\", \"plan implement validate\", \"guided development\",\n \"structured development\", \"build a feature\", \"develop with review\".\n NOT for: Autonomous implementation without planning (use archon-feature-development).\n NOT for: PRD creation (use archon-interactive-prd).\n NOT for: Ralph story-based implementation (use archon-ralph-dag).\n\n Interactive PIV loop workflow — the foundational AI coding methodology:\n 1. EXPLORE: Iterative conversation with human to understand the problem (arbitrary rounds)\n 2. PLAN: Create structured plan -> iterative review & revision (arbitrary rounds)\n 3. IMPLEMENT: Autonomous task-by-task implementation from plan (Ralph loop)\n 4. VALIDATE: Automated code review -> iterative human feedback & fixes (arbitrary rounds)\n\n The PIV loop comes AFTER a PRD exists. Each PIV loop focuses on ONE granular feature or bug fix.\n Input: A description of what to build, a path to an existing plan, or a GitHub issue number.\n\nprovider: claude\ninteractive: true\n\nnodes:\n # ═══════════════════════════════════════════════════════════════\n # PHASE 1: EXPLORE — Iterative exploration with human\n # Understand the idea, explore the codebase, converge on approach\n # Loops until the user says they're ready to create the plan.\n # ═══════════════════════════════════════════════════════════════\n\n - id: explore\n loop:\n prompt: |\n # PIV Loop — Exploration\n\n You are a senior engineering partner in an iterative exploration session.\n Your goal: DEEPLY UNDERSTAND what to build before any code is written.\n\n **User's request**: $ARGUMENTS\n **User's latest input**: $LOOP_USER_INPUT\n\n ---\n\n ## If this is the FIRST iteration (no user input yet):\n\n ### Step 1: Parse the Input\n\n Determine what the user provided:\n\n **If it's a file path** (ends in `.md`, `.plan.md`, or `.prd.md`):\n - Read the file\n - If it's an existing plan → summarize it and ask if they want to refine or proceed\n - If it's a PRD → identify the specific phase/feature to focus on\n\n **If it's a GitHub issue** (`#123` format):\n - Fetch it: `gh issue view {number} --json title,body,labels,comments`\n - Summarize the issue context\n\n **If it's free text**:\n - This is a feature idea or bug description. Use it directly.\n\n ### Step 2: Explore the Codebase\n\n Before asking questions, DO YOUR HOMEWORK:\n\n 1. **Read CLAUDE.md** — understand project conventions, architecture, and constraints\n 2. **Search for related code** — find existing implementations similar to what the user wants\n 3. **Read key files** — understand the current state of code the user wants to change\n 4. **Check recent git history** — `git log --oneline -20` for recent changes in the area\n\n ### Step 3: Present Your Understanding\n\n ```\n ## What I Understand\n\n You want to: {restated understanding in 2-3 sentences}\n\n ## What Already Exists\n\n - {file:line} — {what it does and how it relates}\n - {file:line} — {what it does and how it relates}\n - {pattern/component} — {how it could be extended or reused}\n\n ## Initial Architecture Thoughts\n\n Based on what exists, I'm thinking:\n - {approach 1 — extend existing X}\n - {approach 2 — if approach 1 doesn't work}\n - {key architectural decision that needs your input}\n ```\n\n ### Step 4: Ask Targeted Questions\n\n Ask 4-6 questions focused on DECISIONS, not information gathering:\n - Scope boundaries, architecture preferences, tech decisions\n - Constraints, existing code extension vs fresh build, testing expectations\n - Reference actual code you found — don't ask generic questions\n\n ---\n\n ## If the user has provided input (subsequent iterations):\n\n ### Step 1: Process Their Response\n\n Read their answers carefully. Identify:\n - Decisions they've made\n - Areas they want you to explore further\n - Questions they asked YOU back (answer these with evidence!)\n\n ### Step 2: Do Targeted Research\n\n Based on their response:\n - If they mentioned specific technologies → research best practices\n - If they pointed you to specific code → read it thoroughly\n - If they asked you to explore an area → do a thorough investigation\n - If they made architecture decisions → validate against the codebase\n\n ### Step 3: Present Updated Understanding\n\n Show what you learned, answer their questions with file:line references,\n and present your refined architecture recommendation.\n\n ### Step 4: Converge or Continue\n\n **If there are still important open questions:**\n Ask 2-4 focused questions about remaining ambiguities.\n\n **If the picture is clear and you have enough to create a plan:**\n Present a final implementation summary:\n\n ```\n ## Implementation Summary\n\n ### What We're Building\n {Clear, specific description}\n\n ### Scope Boundary\n - IN: {what's included}\n - OUT: {what's explicitly excluded}\n\n ### Architecture\n - {key decisions}\n\n ### Files That Will Change\n - `{file}` — {what changes and why}\n\n ### Success Criteria\n - [ ] {specific, testable criterion}\n - [ ] All validation passes\n\n ### Key Risks\n - {risk — and mitigation}\n ```\n\n Then tell the user: \"I have a clear picture. Say **ready** and I'll create\n the structured implementation plan, or share any final thoughts.\"\n\n **CRITICAL — READ THIS CAREFULLY**:\n - NEVER output PLAN_READY unless the user's LATEST message contains\n an EXPLICIT phrase like \"ready\", \"create the plan\", \"let's go\", \"proceed\", or \"I'm done\".\n - If the user asked a question → do NOT emit the signal. Answer the question.\n - If the user gave feedback or requested changes → do NOT emit the signal. Address it.\n - If the user said \"also check X\" or \"one more thing\" → do NOT emit the signal. Explore it.\n - If you are unsure whether the user is approving → do NOT emit the signal. Ask them.\n - The ONLY correct time to emit the signal is when the user's message CLEARLY means\n \"stop exploring, I'm ready for you to create the plan.\"\n until: PLAN_READY\n max_iterations: 15\n interactive: true\n gate_message: |\n Answer the questions above, ask me to explore specific areas,\n or say \"ready\" when you're satisfied with the exploration.\n\n # ═══════════════════════════════════════════════════════════════\n # PHASE 2: PLAN — Create the structured implementation plan\n # ═══════════════════════════════════════════════════════════════\n\n - id: create-plan\n model: sonnet\n depends_on: [explore]\n context: fresh\n prompt: |\n # PIV Loop — Create Structured Plan\n\n You are creating a structured implementation plan from a completed exploration phase.\n This plan will be the SOLE GUIDE for the implementation agent — it must be complete,\n specific, and actionable.\n\n **Original request**: $ARGUMENTS\n **Final exploration summary**: $explore.output\n\n ---\n\n ## Step 1: Read the Codebase (Again)\n\n Before writing the plan, verify your understanding is current:\n\n 1. **Read CLAUDE.md** — capture all relevant conventions\n 2. **Read every file you plan to change** — note exact current state\n 3. **Read example test files** — understand testing patterns\n 4. **Check for any recent changes** — `git log --oneline -10`\n\n ## Step 2: Plan File Location\n\n Save the plan to `$ARTIFACTS_DIR/plan.md`.\n The directory already exists (pre-created by the workflow executor).\n\n ## Step 3: Write the Plan\n\n Use this template. Fill EVERY section with specific, verified information.\n\n ```markdown\n # Feature: {Title}\n\n ## Summary\n {1-2 sentences: what changes and why}\n\n ## Mission\n {The core goal in one clear statement}\n\n ## Success Criteria\n - [ ] {Specific, testable criterion}\n - [ ] All validation passes (`bun run validate` or equivalent)\n - [ ] No regressions in existing tests\n\n ## Scope\n ### In Scope\n - {What we ARE building}\n ### Out of Scope\n - {What we are NOT building — and why}\n\n ## Codebase Context\n ### Key Files\n | File | Role | Action |\n |------|------|--------|\n | `{path}` | {what it does} | CREATE / UPDATE |\n\n ### Patterns to Follow\n {Actual code snippets from the codebase to mirror}\n\n ## Architecture\n - {Decision 1 — with rationale}\n - {Decision 2 — with rationale}\n\n ## Task List\n Execute in order. Each task is atomic and independently verifiable.\n\n ### Task 1: {ACTION} `{file path}`\n **Action**: CREATE / UPDATE\n **Details**: {Exact changes — specific enough for an agent with no context}\n **Pattern**: Follow `{source file}:{lines}`\n **Validate**: `{command to verify this task}`\n\n ## Testing Strategy\n | Test File | Test Cases | Validates |\n |-----------|-----------|-----------|\n | `{path}` | {cases} | {what it validates} |\n\n ## Validation Commands\n 1. Type check: `{command}`\n 2. Lint: `{command}`\n 3. Tests: `{command}`\n 4. Full validation: `{command}`\n\n ## Risks\n | Risk | Impact | Mitigation |\n |------|--------|------------|\n | {risk} | {HIGH/MED/LOW} | {specific mitigation} |\n ```\n\n ## Step 4: Verify the Plan\n\n 1. Check every file path referenced — verify they exist\n 2. Check every pattern cited — verify the code matches\n 3. Check task ordering — ensure dependencies are respected\n 4. Check completeness — could an agent with NO context implement this?\n\n ## Step 5: Report\n\n ```\n ## Plan Created\n\n **File**: `$ARTIFACTS_DIR/plan.md`\n **Tasks**: {count}\n **Files to change**: {count}\n\n Key decisions:\n - {decision 1}\n - {decision 2}\n\n Please review the plan and provide feedback.\n ```\n\n # ═══════════════════════════════════════════════════════════════\n # PHASE 2b: PLAN — Iterative plan refinement\n # Review and revise the plan as many times as needed.\n # ═══════════════════════════════════════════════════════════════\n\n - id: refine-plan\n depends_on: [create-plan]\n loop:\n prompt: |\n # PIV Loop — Plan Refinement\n\n The user is reviewing the implementation plan and providing feedback.\n\n **User's feedback**: $LOOP_USER_INPUT\n\n ---\n\n ## Step 1: Read the Plan\n\n Read `$ARTIFACTS_DIR/plan.md` and CLAUDE.md for conventions.\n\n ## Step 2: Process Feedback\n\n **If there is no user feedback yet** (first iteration, $LOOP_USER_INPUT is empty):\n - Read the plan carefully\n - Present a summary of the plan's key decisions and task list\n - Ask the user to review and provide feedback\n - Do NOT emit the completion signal on the first iteration\n\n **If the user EXPLICITLY approved** (said \"approved\", \"looks good\", \"let's go\", etc.):\n - Make no changes\n - Output: \"Plan approved. Proceeding to implementation.\"\n - Signal completion: PLAN_APPROVED\n\n **If the user provided specific feedback:**\n - Parse each piece of feedback\n - Edit the plan file directly:\n - Add/remove/modify tasks as requested\n - Update success criteria if needed\n - Adjust testing strategy if needed\n - Re-verify file paths and patterns after changes\n\n **CRITICAL**: NEVER emit PLAN_APPROVED unless the user's latest\n message EXPLICITLY says \"approved\", \"looks good\", \"ship it\", or similar approval.\n Questions, feedback, and requests for changes are NOT approval.\n\n ## Step 3: Show Changes\n\n ```\n ## Plan Revised\n\n Changes made:\n - {change 1}\n - {change 2}\n\n Updated stats:\n - Tasks: {count}\n - Files to change: {count}\n\n Review the updated plan and provide more feedback, or say \"approved\" to proceed.\n ```\n until: PLAN_APPROVED\n max_iterations: 10\n interactive: true\n gate_message: |\n Review the plan document. Provide specific feedback on what to change,\n or say \"approved\" to begin implementation.\n\n # ═══════════════════════════════════════════════════════════════\n # PHASE 3: IMPLEMENT — Setup\n # Read the plan, prepare the environment\n # ═══════════════════════════════════════════════════════════════\n\n - id: implement-setup\n depends_on: [refine-plan]\n bash: |\n set -e\n\n PLAN_FILE=\"$ARTIFACTS_DIR/plan.md\"\n\n if [ ! -f \"$PLAN_FILE\" ]; then\n echo \"ERROR: No plan file found at $ARTIFACTS_DIR/plan.md\"\n exit 1\n fi\n\n # Install dependencies if needed\n if [ -f \"bun.lock\" ] || [ -f \"bun.lockb\" ]; then\n echo \"Installing dependencies...\"\n bun install --frozen-lockfile 2>&1 | tail -3\n elif [ -f \"package-lock.json\" ]; then\n npm ci 2>&1 | tail -3\n elif [ -f \"yarn.lock\" ]; then\n yarn install --frozen-lockfile 2>&1 | tail -3\n elif [ -f \"pnpm-lock.yaml\" ]; then\n pnpm install --frozen-lockfile 2>&1 | tail -3\n fi\n\n echo \"BRANCH=$(git branch --show-current)\"\n echo \"GIT_ROOT=$(git rev-parse --show-toplevel)\"\n echo \"PLAN_FILE=$PLAN_FILE\"\n\n echo \"=== PLAN_START ===\"\n cat \"$PLAN_FILE\"\n echo \"\"\n echo \"=== PLAN_END ===\"\n\n TASK_COUNT=$(grep -c \"^### Task [0-9]\" \"$PLAN_FILE\" 2>/dev/null || echo \"0\")\n if [ \"$TASK_COUNT\" -eq 0 ]; then\n echo \"ERROR: No '### Task N:' sections found in $PLAN_FILE. Plan may be malformed.\"\n exit 1\n fi\n echo \"TASK_COUNT=${TASK_COUNT}\"\n\n # ═══════════════════════════════════════════════════════════════\n # PHASE 3b: IMPLEMENT — Task-by-Task Loop (Ralph pattern)\n # Fresh context each iteration. Reads plan from disk.\n # One task per iteration. Validates before committing.\n # ═══════════════════════════════════════════════════════════════\n\n - id: implement\n depends_on: [implement-setup]\n idle_timeout: 600000\n model: claude-opus-4-6[1m]\n loop:\n prompt: |\n # PIV Loop — Implementation Agent\n\n You are an autonomous coding agent in a FRESH session — no memory of previous iterations.\n Your job: Read the plan from disk, implement ONE task, validate, commit, update tracking, exit.\n\n **Golden Rule**: If validation fails, fix it before committing. Never commit broken code.\n\n ---\n\n ## Phase 0: CONTEXT — Load State\n\n The setup node produced this context:\n\n $implement-setup.output\n\n **User's original request**: $USER_MESSAGE\n\n ---\n\n ### 0.1 Parse Plan File\n\n Extract the `PLAN_FILE=...` line from the context above.\n\n ### 0.2 Read Current State (from disk — not from context above)\n\n The context above is a snapshot from before the loop started. Previous iterations\n may have changed things. **You MUST re-read from disk:**\n\n 1. **Read the plan file** — your implementation guide\n 2. **Read progress tracking** — check if `$ARTIFACTS_DIR/progress.txt` exists\n 3. **Read CLAUDE.md** — project conventions and constraints\n\n ### 0.3 Check Git State\n\n ```bash\n git log --oneline -10\n git status\n ```\n\n ---\n\n ## Phase 1: SELECT — Pick Next Task\n\n From the plan file, identify tasks by `### Task N:` headers.\n Cross-reference with commits from previous iterations and progress tracking.\n\n **If ALL tasks are complete** → Skip to Phase 5 (Completion).\n\n ### Announce Selection\n\n ```\n -- Task Selected ------------------------------------------------\n Task: {N} — {task title}\n Action: {CREATE / UPDATE}\n File: {file path}\n -----------------------------------------------------------------\n ```\n\n ---\n\n ## Phase 2: IMPLEMENT — Execute the Task\n\n 1. Read the file you're about to change (if it exists)\n 2. Read the pattern file referenced in the plan\n 3. Make changes following the plan EXACTLY\n 4. Type-check after each file: `bun run type-check 2>&1 || true`\n\n ---\n\n ## Phase 3: VALIDATE — Verify the Task\n\n ```bash\n bun run type-check && bun run lint && bun run test && bun run format:check\n ```\n\n If validation fails: fix, re-run (up to 3 attempts). If unfixable, note in progress\n tracking and do NOT commit broken code.\n\n ---\n\n ## Phase 4: COMMIT — Save Changes\n\n ```bash\n git add -A\n git diff --cached --stat\n git commit -m \"$(cat <<'EOF'\n {type}: {task description}\n\n PIV Task {N}: {brief details}\n EOF\n )\"\n ```\n\n Track progress in `$ARTIFACTS_DIR/progress.txt`:\n ```\n ## Task {N}: {title} — COMPLETED\n Date: {ISO date}\n Files: {list}\n Commit: {short hash}\n ---\n ```\n\n ---\n\n ## Phase 5: COMPLETE — Check All Tasks\n\n If ALL tasks are done:\n 1. Run full validation: `bun run validate 2>&1`\n 2. Push: `git push -u origin HEAD`\n 3. Signal: `COMPLETE`\n\n If tasks remain, report status and end normally. The loop engine starts a fresh iteration.\n until: COMPLETE\n max_iterations: 15\n fresh_context: true\n\n # ═══════════════════════════════════════════════════════════════\n # PHASE 4: VALIDATE — Automated code review\n # Review all changes against the plan\n # ═══════════════════════════════════════════════════════════════\n\n - id: code-review\n model: sonnet\n depends_on: [implement]\n context: fresh\n prompt: |\n # PIV Loop — Automated Code Review\n\n The implementation phase is complete. Review ALL changes against the plan.\n\n **Implementation output**: $implement.output\n\n ---\n\n ## Step 1: Read the Plan\n\n Read `$ARTIFACTS_DIR/plan.md` to understand the intended implementation.\n\n ## Step 2: Review All Changes\n\n ```bash\n git log --oneline --no-merges $(git merge-base HEAD $BASE_BRANCH)..HEAD\n git diff $BASE_BRANCH..HEAD --stat\n git diff $BASE_BRANCH..HEAD\n ```\n\n ## Step 3: Check Against Plan\n\n For EACH task: was it implemented correctly? Do success criteria hold?\n For EACH file: check quality, security, patterns, CLAUDE.md compliance.\n\n ## Step 4: Run Validation\n\n ```bash\n bun run validate 2>&1 || (bun run type-check && bun run lint && bun run test && bun run format:check)\n ```\n\n ## Step 5: Fix Obvious Issues\n\n Fix type errors, lint warnings, missing imports, formatting. Commit any fixes:\n ```bash\n git add -A && git commit -m \"fix: address code review findings\" || true\n ```\n\n ## Step 6: Present Review\n\n ```\n ## Code Review Complete\n\n ### Implementation Status\n | Task | Status | Notes |\n |------|--------|-------|\n | {task} | DONE / PARTIAL / MISSING | {notes} |\n\n ### Validation Results\n - Type-check: PASS / FAIL\n - Lint: PASS / FAIL\n - Tests: PASS / FAIL\n - Format: PASS / FAIL\n\n ### Code Quality Findings\n {Issues found, or \"No issues found.\"}\n\n ### Recommendation\n {READY FOR REVIEW / NEEDS FIXES}\n ```\n\n # ═══════════════════════════════════════════════════════════════\n # PHASE 4b: VALIDATE — Iterative human feedback & fixes\n # The user tests the implementation and provides feedback.\n # Loops until the user approves.\n # ═══════════════════════════════════════════════════════════════\n\n - id: fix-feedback\n depends_on: [code-review]\n loop:\n prompt: |\n # PIV Loop — Address Validation Feedback\n\n The human has reviewed the implementation and provided feedback.\n\n **Human's feedback**: $LOOP_USER_INPUT\n\n ---\n\n ## Step 1: Read Context\n\n Read `$ARTIFACTS_DIR/plan.md` and CLAUDE.md for conventions.\n\n ## Step 2: Process Feedback\n\n **If there is no user feedback yet** (first iteration, $LOOP_USER_INPUT is empty):\n - Present the code review results and ask the user to test the implementation\n - Do NOT emit the completion signal on the first iteration\n\n **If the user EXPLICITLY approved** (said \"approved\", \"looks good\", \"ship it\", etc.):\n - Output: \"Implementation approved!\"\n - Signal: VALIDATED\n\n **CRITICAL**: NEVER emit VALIDATED unless the user's latest\n message EXPLICITLY says \"approved\", \"looks good\", \"ship it\", or similar approval.\n\n **If the user provided specific feedback:**\n 1. Read the relevant files\n 2. Understand each issue\n 3. Make the fixes\n 4. Type-check after each change\n\n ## Step 3: Full Validation\n\n ```bash\n bun run validate 2>&1 || (bun run type-check && bun run lint && bun run test && bun run format:check)\n ```\n\n ## Step 4: Commit Fixes\n\n ```bash\n git add -A\n git commit -m \"$(cat <<'EOF'\n fix: address review feedback\n\n Changes:\n - {fix 1}\n - {fix 2}\n EOF\n )\"\n ```\n\n ## Step 5: Report\n\n ```\n ## Feedback Addressed\n\n Changes made:\n - {fix 1}\n - {fix 2}\n\n Validation: {PASS / FAIL with details}\n\n Review again, or say \"approved\" to finalize.\n ```\n until: VALIDATED\n max_iterations: 10\n interactive: true\n gate_message: |\n Test the implementation yourself and review the code changes.\n Provide specific feedback on what needs fixing, or say \"approved\" to finalize.\n\n # ═══════════════════════════════════════════════════════════════\n # PHASE 5: FINALIZE — Push, create PR, generate summary\n # ═══════════════════════════════════════════════════════════════\n\n - id: finalize\n model: sonnet\n depends_on: [fix-feedback]\n context: fresh\n prompt: |\n # PIV Loop — Finalize\n\n The implementation has been approved. Push changes and create a PR.\n\n ---\n\n ## Step 1: Push Changes\n\n ```bash\n git push -u origin HEAD 2>&1 || echo \"WARNING: Push failed — verify remote authentication and branch state before creating the PR.\"\n ```\n\n ## Step 2: Generate Summary\n\n ```bash\n git log --oneline --no-merges $(git merge-base HEAD $BASE_BRANCH)..HEAD\n git diff --stat $(git merge-base HEAD $BASE_BRANCH)..HEAD\n ```\n\n Read `$ARTIFACTS_DIR/plan.md` and `$ARTIFACTS_DIR/progress.txt` for context.\n\n ## Step 3: Create PR (if not already created)\n\n ```bash\n gh pr view HEAD --json url 2>/dev/null || echo \"NO_PR\"\n ```\n\n If no PR exists:\n\n ```bash\n cat .github/pull_request_template.md 2>/dev/null || echo \"NO_TEMPLATE\"\n ```\n\n Create with `gh pr create --draft --base $BASE_BRANCH`:\n - Title from the plan's feature name\n - Body summarizing the implementation\n - Use a HEREDOC for the body\n\n ## Step 4: Output Summary\n\n ```\n ===============================================================\n PIV LOOP — COMPLETE\n ===============================================================\n\n Feature: {from plan}\n Plan: {plan file path}\n Branch: {branch name}\n PR: {url}\n\n -- Tasks Completed -----------------------------------------------\n {list from progress tracking}\n\n -- Commits -------------------------------------------------------\n {git log output}\n\n -- Files Changed -------------------------------------------------\n {git diff --stat output}\n\n -- Validation ----------------------------------------------------\n All checks passed.\n ===============================================================\n ```\n", "archon-plan-to-pr": "name: archon-plan-to-pr\ndescription: |\n Use when: You have an existing implementation plan and want to execute it end-to-end.\n Input: Path to a plan file ($ARTIFACTS_DIR/plan.md or .agents/plans/*.md)\n Output: PR ready for merge with comprehensive review completed\n\n Full workflow:\n 1. Read plan, setup branch, extract scope limits\n 2. Verify plan research is still valid\n 3. Implement all tasks with type-checking\n 4. Run full validation suite\n 5. Create PR with template, mark ready\n 6. Comprehensive code review (5 parallel agents with scope limit awareness)\n 7. Synthesize and fix review findings\n 8. Final summary with decision matrix -> GitHub comment + follow-up recommendations\n\n NOT for: Creating plans from scratch (use archon-idea-to-pr), quick fixes, standalone reviews.\n\nnodes:\n # ═══════════════════════════════════════════════════════════════════\n # PHASE 1: SETUP\n # ═══════════════════════════════════════════════════════════════════\n\n - id: plan-setup\n command: archon-plan-setup\n context: fresh\n\n # ═══════════════════════════════════════════════════════════════════\n # PHASE 2: CONFIRM PLAN\n # ═══════════════════════════════════════════════════════════════════\n\n - id: confirm-plan\n command: archon-confirm-plan\n depends_on: [plan-setup]\n context: fresh\n\n # ═══════════════════════════════════════════════════════════════════\n # PHASE 3: IMPLEMENT\n # ═══════════════════════════════════════════════════════════════════\n\n - id: implement-tasks\n command: archon-implement-tasks\n depends_on: [confirm-plan]\n context: fresh\n model: opus[1m]\n\n # ═══════════════════════════════════════════════════════════════════\n # PHASE 4: VALIDATE\n # ═══════════════════════════════════════════════════════════════════\n\n - id: validate\n command: archon-validate\n depends_on: [implement-tasks]\n context: fresh\n\n # ═══════════════════════════════════════════════════════════════════\n # PHASE 5: FINALIZE PR\n # ═══════════════════════════════════════════════════════════════════\n\n - id: finalize-pr\n command: archon-finalize-pr\n depends_on: [validate]\n context: fresh\n\n # ═══════════════════════════════════════════════════════════════════\n # PHASE 6: CODE REVIEW\n # ═══════════════════════════════════════════════════════════════════\n\n - id: review-scope\n command: archon-pr-review-scope\n depends_on: [finalize-pr]\n context: fresh\n\n - id: sync\n command: archon-sync-pr-with-main\n depends_on: [review-scope]\n context: fresh\n\n - id: code-review\n command: archon-code-review-agent\n depends_on: [sync]\n context: fresh\n\n - id: error-handling\n command: archon-error-handling-agent\n depends_on: [sync]\n context: fresh\n\n - id: test-coverage\n command: archon-test-coverage-agent\n depends_on: [sync]\n context: fresh\n\n - id: comment-quality\n command: archon-comment-quality-agent\n depends_on: [sync]\n context: fresh\n\n - id: docs-impact\n command: archon-docs-impact-agent\n depends_on: [sync]\n context: fresh\n\n - id: synthesize\n command: archon-synthesize-review\n depends_on: [code-review, error-handling, test-coverage, comment-quality, docs-impact]\n trigger_rule: one_success\n context: fresh\n\n # ═══════════════════════════════════════════════════════════════════\n # PHASE 7: FIX REVIEW ISSUES\n # ═══════════════════════════════════════════════════════════════════\n\n - id: implement-fixes\n command: archon-implement-review-fixes\n depends_on: [synthesize]\n context: fresh\n\n # ═══════════════════════════════════════════════════════════════════\n # PHASE 8: FINAL SUMMARY & FOLLOW-UP\n # ═══════════════════════════════════════════════════════════════════\n\n - id: workflow-summary\n command: archon-workflow-summary\n depends_on: [implement-fixes]\n context: fresh\n", "archon-ralph-dag": "name: archon-ralph-dag\ndescription: |\n Use when: User wants to run a Ralph implementation loop.\n Triggers: \"ralph\", \"run ralph\", \"ralph dag\", \"run ralph dag\".\n\n DAG workflow that:\n 1. Detects input: existing prd.json, existing prd.md (needs stories), or raw idea\n 2. Generates prd.md + prd.json if needed (explores codebase, breaks into stories)\n 3. Validates PRD files, reads project context, installs dependencies\n 4. Runs Ralph loop (fresh context per iteration) implementing one story per iteration\n 5. Creates PR and reports completion\n\n Accepts: An idea description, a path to an existing prd.md, or a directory with prd.md + prd.json\n\nprovider: claude\n\nnodes:\n # ═══════════════════════════════════════════════════════════════\n # NODE 1: DETECT INPUT\n # Determines what the user provided: full PRD, partial PRD, or idea\n # ═══════════════════════════════════════════════════════════════\n\n - id: detect-input\n model: haiku\n prompt: |\n # Detect Ralph Input\n\n **User input**: $ARGUMENTS\n\n Determine what the user provided and prepare the PRD directory. Follow these steps exactly:\n\n ## Step 1: Detect worktree\n\n Run `git worktree list --porcelain` to check if you're in a worktree.\n If you see multiple entries, you ARE in a worktree. The first entry (the one without \"branch\" pointing to your current branch) is the **main repo root**. Save it — you'll need it to find files.\n\n ## Step 2: Classify the input\n\n Look at the user input above. It's one of three things:\n\n **Case A — Ralph directory path** (contains `.archon/ralph/`):\n Extract the directory. Check if both `prd.json` and `prd.md` exist there (try locally first, then in the main repo root if in a worktree).\n\n **Case B — File path** (ends in `.md`):\n This is an external PRD file. Find it:\n 1. Try the path as-is (relative to cwd)\n 2. Try it as an absolute path\n 3. If in a worktree, try it relative to the **main repo root** from Step 1\n Once found, read the file to confirm it's a PRD.\n\n **Case C — Free text**:\n Not a file path — it's a feature idea.\n\n ## Step 3: Auto-discover existing ralph PRDs\n\n If the input didn't point to a specific path, check if `.archon/ralph/` contains any `prd.json` files:\n ```bash\n find .archon/ralph -name \"prd.json\" -type f 2>/dev/null\n ```\n\n ## Step 4: Take action based on classification\n\n **If Case A and both files exist** → output `ready` (no further action needed)\n\n **If Case B (external PRD found)**:\n 1. Derive a kebab-case slug from the PRD filename or title (e.g., `workflow-lifecycle-overhaul`)\n 2. Create the ralph directory: `mkdir -p .archon/ralph/{slug}`\n 3. Copy the PRD content to `.archon/ralph/{slug}/prd.md`\n 4. Output `external_prd` with the new prd_dir\n\n **If Case C or auto-discovered ralph dir has prd.md but no prd.json** → output `needs_generation`\n\n ## Output\n\n Your final output MUST be exactly one JSON object:\n ```json\n {\"input_type\": \"ready|external_prd|needs_generation\", \"prd_dir\": \".archon/ralph/{slug}\"}\n ```\n output_format:\n type: object\n properties:\n input_type:\n type: string\n enum: [ready, external_prd, needs_generation]\n prd_dir:\n type: string\n required: [input_type, prd_dir]\n\n # ═══════════════════════════════════════════════════════════════\n # NODE 2: GENERATE PRD\n # Scenario 1: User has an idea → generate prd.md + prd.json\n # Scenario 2: User has prd.md → generate prd.json with stories\n # Skipped if prd.json already exists\n # ═══════════════════════════════════════════════════════════════\n\n - id: generate-prd\n depends_on: [detect-input]\n when: \"$detect-input.output.input_type != 'ready'\"\n command: archon-ralph-generate\n context: fresh\n\n # ═══════════════════════════════════════════════════════════════\n # NODE 3: VALIDATE & SETUP\n # Finds PRD directory, reads all state files, installs deps,\n # verifies the environment is ready for implementation.\n # ═══════════════════════════════════════════════════════════════\n\n - id: validate-prd\n depends_on: [detect-input, generate-prd]\n trigger_rule: one_success\n bash: |\n set -e\n\n # ── 1. Find PRD directory (passed from detect-input) ──────\n PRD_DIR=$detect-input.output.prd_dir\n\n # If detect-input didn't know the PRD dir (generated from scratch), discover it\n if [ -z \"$PRD_DIR\" ] || [ ! -f \"$PRD_DIR/prd.json\" ]; then\n FOUND=$(find .archon/ralph -name \"prd.json\" -type f 2>/dev/null | head -1)\n if [ -n \"$FOUND\" ]; then\n PRD_DIR=$(dirname \"$FOUND\")\n fi\n fi\n\n if [ -z \"$PRD_DIR\" ] || [ ! -f \"$PRD_DIR/prd.json\" ]; then\n echo \"ERROR: No prd.json found after generation step.\"\n echo \"Check the generate-prd node output for errors.\"\n exit 1\n fi\n\n if [ ! -f \"$PRD_DIR/prd.md\" ]; then\n echo \"ERROR: prd.md not found in $PRD_DIR\"\n exit 1\n fi\n\n # ── 2. Install dependencies (worktrees lack node_modules) ──\n if [ -f \"bun.lock\" ] || [ -f \"bun.lockb\" ]; then\n echo \"Installing dependencies (bun)...\"\n bun install --frozen-lockfile 2>&1 | tail -3\n elif [ -f \"package-lock.json\" ]; then\n echo \"Installing dependencies (npm)...\"\n npm ci 2>&1 | tail -3\n elif [ -f \"yarn.lock\" ]; then\n echo \"Installing dependencies (yarn)...\"\n yarn install --frozen-lockfile 2>&1 | tail -3\n elif [ -f \"pnpm-lock.yaml\" ]; then\n echo \"Installing dependencies (pnpm)...\"\n pnpm install --frozen-lockfile 2>&1 | tail -3\n fi\n\n # ── 3. Git state ──────────────────────────────────────────\n echo \"BRANCH=$(git branch --show-current)\"\n echo \"GIT_ROOT=$(git rev-parse --show-toplevel)\"\n\n # ── 4. Output PRD context ─────────────────────────────────\n echo \"PRD_DIR=$PRD_DIR\"\n echo \"=== PRD_JSON_START ===\"\n cat \"$PRD_DIR/prd.json\"\n echo \"\"\n echo \"=== PRD_JSON_END ===\"\n echo \"=== PRD_MD_START ===\"\n cat \"$PRD_DIR/prd.md\"\n echo \"\"\n echo \"=== PRD_MD_END ===\"\n echo \"=== PROGRESS_START ===\"\n if [ -f \"$PRD_DIR/progress.txt\" ]; then\n cat \"$PRD_DIR/progress.txt\"\n else\n echo \"(no progress yet)\"\n fi\n echo \"\"\n echo \"=== PROGRESS_END ===\"\n\n # ── 5. Summary ────────────────────────────────────────────\n TOTAL=$(grep -c '\"passes\"' \"$PRD_DIR/prd.json\" || true)\n DONE=$(grep -c '\"passes\": true' \"$PRD_DIR/prd.json\" || true)\n TOTAL=${TOTAL:-0}\n DONE=${DONE:-0}\n echo \"STORIES_TOTAL=$TOTAL\"\n echo \"STORIES_DONE=$DONE\"\n echo \"STORIES_REMAINING=$(( TOTAL - DONE ))\"\n\n # ═══════════════════════════════════════════════════════════════\n # NODE 4: RALPH IMPLEMENTATION LOOP\n # Fresh context each iteration. Reads PRD state from disk.\n # One story per iteration. Validates before committing.\n # ═══════════════════════════════════════════════════════════════\n\n - id: implement\n depends_on: [validate-prd]\n idle_timeout: 600000\n model: opus[1m]\n loop:\n prompt: |\n # Ralph Agent — Autonomous Story Implementation\n\n You are an autonomous coding agent in a FRESH session — you have no memory of previous iterations.\n Your job: Read state from disk, implement ONE story, validate, commit, update tracking, exit.\n\n **Golden Rule**: If validation fails, fix it before committing. Never commit broken code. Never skip validation.\n\n ---\n\n ## Phase 0: CONTEXT — Load Project State\n\n The upstream setup node produced this context:\n\n $validate-prd.output\n\n **User message**: $USER_MESSAGE\n\n ---\n\n ### 0.1 Parse PRD Directory\n\n Extract the `PRD_DIR=...` line from the context above. This is the directory containing your PRD files.\n Store this path — use it for ALL file operations below.\n\n ### 0.2 Read Current State (from disk, not from context above)\n\n The context above is a snapshot from before the loop started. Previous iterations may have changed files.\n **You MUST re-read from disk to get the current state:**\n\n 1. **Read `{prd-dir}/progress.txt`** — your only link to previous iterations\n - Check the `## Codebase Patterns` section FIRST for learnings from prior iterations\n - Check recent entries for gotchas to avoid\n 2. **Read `{prd-dir}/prd.json`** — the source of truth for story completion state\n 3. **Read `{prd-dir}/prd.md`** — full requirements, technical patterns, acceptance criteria\n\n ### 0.3 Read Project Rules\n\n ```bash\n cat CLAUDE.md\n ```\n\n Note all coding standards, patterns, and rules. Follow them exactly.\n\n **PHASE_0_CHECKPOINT:**\n - [ ] PRD directory identified\n - [ ] progress.txt read (or noted as absent)\n - [ ] prd.json read — know which stories pass/fail\n - [ ] prd.md read — understand requirements\n - [ ] CLAUDE.md rules noted\n\n ---\n\n ## Phase 1: SELECT — Pick Next Story\n\n ### 1.1 Find Eligible Story\n\n From `prd.json`, find the **highest priority** story where:\n - `passes` is `false`\n - ALL stories in `dependsOn` have `passes: true`\n\n **If ALL stories have `passes: true`** → Skip to Phase 6 (Completion).\n\n **If no eligible stories exist** (all remaining are blocked):\n ```\n BLOCKED: No eligible stories. Remaining stories and their blockers:\n - {story-id}: blocked by {dep-id} (passes: false)\n ```\n End normally. The loop will terminate on max_iterations.\n\n ### 1.2 Announce Selection\n\n ```\n ── Story Selected ──────────────────────────────────\n ID: {story-id}\n Title: {story-title}\n Priority: {priority}\n Dependencies: {deps or \"none\"}\n\n Acceptance Criteria:\n - {criterion 1}\n - {criterion 2}\n - ...\n ────────────────────────────────────────────────────\n ```\n\n After announcing the selected story, emit the story started event:\n ```bash\n bun run cli workflow event emit --run-id $WORKFLOW_ID --type ralph_story_started --data '{\"story_id\":\"{story-id}\",\"title\":\"{story-title}\"}' || true\n ```\n\n **PHASE_1_CHECKPOINT:**\n - [ ] Eligible story found (or all complete / all blocked)\n - [ ] Acceptance criteria understood\n - [ ] Dependencies verified as complete\n\n ---\n\n ## Phase 2: IMPLEMENT — Code the Story\n\n ### 2.1 Explore Before Coding\n\n Before writing any code:\n 1. Read all files you plan to modify — understand current state\n 2. Check `## Codebase Patterns` in progress.txt for discovered patterns\n 3. Look for similar implementations in the codebase to mirror\n 4. Read the `technicalNotes` field from the story in prd.json\n\n ### 2.2 Implementation Rules\n\n **DO:**\n - Implement ONLY the selected story — one story per iteration\n - Follow existing code patterns exactly (naming, structure, imports, error handling)\n - Match the project's coding standards from CLAUDE.md\n - Write or update tests as required by acceptance criteria\n - Keep changes minimal and focused\n\n **DON'T:**\n - Refactor unrelated code\n - Add improvements not in the acceptance criteria\n - Change formatting of lines you didn't modify\n - Install new dependencies without justification from prd.md\n - Touch files unrelated to this story\n - Over-engineer — do the simplest thing that satisfies the criteria\n\n ### 2.3 Verify Types After Each File\n\n After modifying each file, run:\n ```bash\n bun run type-check\n ```\n\n **If types fail:**\n 1. Read the error carefully\n 2. Fix the type issue in your code\n 3. Re-run type-check\n 4. Do NOT proceed to the next file until types pass\n\n **PHASE_2_CHECKPOINT:**\n - [ ] Only the selected story was implemented\n - [ ] Types compile after each file change\n - [ ] Tests written/updated as needed\n - [ ] No unrelated changes\n\n ---\n\n ## Phase 3: VALIDATE — Full Verification\n\n ### 3.1 Static Analysis\n\n ```bash\n bun run type-check && bun run lint\n ```\n\n **Must pass with zero errors and zero warnings.**\n\n **If lint fails:**\n 1. Run `bun run lint:fix` for auto-fixable issues\n 2. Manually fix remaining issues\n 3. Re-run lint\n 4. Proceed only when clean\n\n ### 3.2 Tests\n\n ```bash\n bun run test\n ```\n\n **All tests must pass.**\n\n **If tests fail:**\n 1. Read the failure output\n 2. Determine: bug in your implementation or pre-existing failure?\n 3. If your bug → fix the implementation (not the test)\n 4. If pre-existing → note it but don't fix unrelated tests\n 5. Re-run tests\n 6. Repeat until green\n\n ### 3.3 Format Check\n\n ```bash\n bun run format:check\n ```\n\n **If formatting fails:**\n ```bash\n bun run format\n ```\n\n ### 3.4 Verify Acceptance Criteria\n\n Go through EACH acceptance criterion from the story:\n - Is it satisfied by your implementation?\n - Can you verify it (read the code, run a command, check a file)?\n\n If a criterion is NOT met, go back to Phase 2 and fix it.\n\n **PHASE_3_CHECKPOINT:**\n - [ ] Type-check passes\n - [ ] Lint passes (0 errors, 0 warnings)\n - [ ] All tests pass\n - [ ] Format is clean\n - [ ] Every acceptance criterion verified\n\n ---\n\n ## Phase 4: COMMIT — Save Changes\n\n ### 4.1 Review Staged Changes\n\n ```bash\n git add -A\n git status\n git diff --cached --stat\n ```\n\n Verify only expected files are staged. If unexpected files appear, investigate before committing.\n\n ### 4.2 Write Commit Message\n\n ```bash\n git commit -m \"$(cat <<'EOF'\n feat: {story-title}\n\n Implements {story-id} from PRD.\n\n Changes:\n - {change 1}\n - {change 2}\n - {change 3}\n EOF\n )\"\n ```\n\n **Commit message rules:**\n - Prefix: `feat:` for features, `fix:` for bugs, `refactor:` for refactors\n - Title: the story title (not the PRD name)\n - Body: list the actual changes made\n - Do NOT include AI attribution\n\n **PHASE_4_CHECKPOINT:**\n - [ ] Only expected files committed\n - [ ] Commit message is clear and accurate\n - [ ] Working directory is clean after commit\n\n ---\n\n ## Phase 5: TRACK — Update Progress Files\n\n ### 5.1 Update prd.json\n\n Set `passes: true` and add a note for the completed story:\n\n ```json\n {\n \"id\": \"{story-id}\",\n \"passes\": true,\n \"notes\": \"Implemented in iteration {N}. Files: {list}.\"\n }\n ```\n\n After updating prd.json, emit the story completed event:\n ```bash\n bun run cli workflow event emit --run-id $WORKFLOW_ID --type ralph_story_completed --data '{\"story_id\":\"{story-id}\",\"title\":\"{story-title}\"}' || true\n ```\n\n ### 5.2 Update progress.txt\n\n **Append** to `{prd-dir}/progress.txt`:\n\n ```\n ## {ISO Date} — {story-id}: {story-title}\n\n **Status**: PASSED\n **Files changed**:\n - {file1} — {what changed}\n - {file2} — {what changed}\n\n **Acceptance criteria verified**:\n - [x] {criterion 1}\n - [x] {criterion 2}\n\n **Learnings**:\n - {Any pattern discovered}\n - {Any gotcha encountered}\n - {Any deviation from expected approach}\n\n ---\n ```\n\n ### 5.3 Update Codebase Patterns (if applicable)\n\n If you discovered a **reusable pattern** that future iterations should know about, **prepend** it to the `## Codebase Patterns` section at the TOP of progress.txt.\n\n Format:\n ```\n ## Codebase Patterns\n\n ### {Pattern Name}\n - **Where**: `{file:lines}`\n - **Pattern**: {description}\n - **Example**: `{code snippet}`\n ```\n\n If the `## Codebase Patterns` section doesn't exist yet, create it at the top of the file.\n\n **PHASE_5_CHECKPOINT:**\n - [ ] prd.json updated with `passes: true`\n - [ ] progress.txt appended with iteration details\n - [ ] Codebase patterns updated (if applicable)\n\n ---\n\n ## Phase 6: COMPLETE — Check All Stories\n\n ### 6.1 Re-read prd.json\n\n ```bash\n cat {prd-dir}/prd.json\n ```\n\n Count stories where `passes: false`.\n\n ### 6.2 If ALL Stories Pass\n\n 1. **Push the branch:**\n ```bash\n git push -u origin HEAD\n ```\n\n 2. **Read the PR template:**\n Look for a PR template in the repo — check `.github/pull_request_template.md`, `.github/PULL_REQUEST_TEMPLATE.md`, and `docs/pull_request_template.md`. Read whichever one exists.\n\n If a template was found, fill in **every section** using the context from this implementation. Don't skip sections or leave placeholders — fill them honestly based on the actual changes (summary, architecture, validation evidence, security, compatibility, rollback, etc.).\n\n If no template was found, write a summary with: problem, what changed, stories table, and validation evidence.\n\n 3. **Create a draft PR** using `gh pr create --draft --base $BASE_BRANCH --title \"feat: {PRD feature name}\"` with the filled-in template as the body. Use a HEREDOC for the body.\n\n 4. **Output completion signal:**\n ```\n COMPLETE\n ```\n\n ### 6.3 If Stories Remain\n\n Report status and end normally:\n ```\n ── Iteration Complete ──────────────────────────────\n Story completed: {story-id} — {story-title}\n Stories remaining: {count}\n Next eligible: {next-story-id} — {next-story-title}\n ────────────────────────────────────────────────────\n ```\n\n The loop engine will start the next iteration with a fresh context.\n\n ---\n\n ## Handling Edge Cases\n\n ### Validation fails repeatedly\n - If type-check or tests fail 3+ times on the same error, step back\n - Re-read the acceptance criteria — you may be misunderstanding the requirement\n - Check if the story is too large (needs breaking down)\n - Note the blocker in progress.txt and end the iteration\n\n ### Story is too large for one iteration\n - Implement the minimum viable subset that satisfies the most critical acceptance criteria\n - Set `passes: true` only if ALL criteria are met\n - If you can't meet all criteria, leave `passes: false` and note what's done in progress.txt\n - The next iteration will pick it up and continue\n\n ### Pre-existing test failures\n - If tests were failing BEFORE your changes, note them but don't fix unrelated code\n - Run only the test files related to your changes if the full suite has pre-existing issues\n - Document pre-existing failures in progress.txt\n\n ### Dependency install fails\n - Check if `bun.lock` or equivalent exists\n - Try `bun install` without `--frozen-lockfile`\n - Note the issue in progress.txt\n\n ### Git state is dirty at iteration start\n - This shouldn't happen (fresh worktree), but if it does:\n - Run `git status` to understand what's dirty\n - If it's leftover from a failed previous iteration, commit or stash\n - Never discard changes silently\n\n ### Blocked stories — all remaining have unmet dependencies\n - Report the dependency chain in your output\n - Check if a dependency was incorrectly left as `passes: false`\n - If a dependency should be `passes: true` (the code exists and works), fix prd.json\n - Otherwise, end the iteration — the loop will exhaust max_iterations\n\n ---\n\n ## File Format Reference\n\n ### prd.json Schema\n\n ```json\n {\n \"feature\": \"Feature Name\",\n \"issueNumber\": 123,\n \"userStories\": [\n {\n \"id\": \"US-001\",\n \"title\": \"Short title\",\n \"description\": \"As a..., I want..., so that...\",\n \"acceptanceCriteria\": [\"criterion 1\", \"criterion 2\"],\n \"technicalNotes\": \"Implementation hints\",\n \"dependsOn\": [\"US-000\"],\n \"priority\": 1,\n \"passes\": false,\n \"notes\": \"\"\n }\n ]\n }\n ```\n\n ### progress.txt Format\n\n ```\n ## Codebase Patterns\n\n ### {Pattern Name}\n - Where: `file:lines`\n - Pattern: description\n - Example: `code`\n\n ---\n\n ## {Date} — {story-id}: {title}\n\n **Status**: PASSED\n **Files changed**: ...\n **Acceptance criteria verified**: ...\n **Learnings**: ...\n\n ---\n ```\n\n ---\n\n ## Success Criteria\n\n - **ONE_STORY**: Exactly one story implemented per iteration\n - **VALIDATED**: Type-check + lint + tests + format all pass before commit\n - **COMMITTED**: Changes committed with clear message\n - **TRACKED**: prd.json and progress.txt updated accurately\n - **PATTERNS_SHARED**: Discovered patterns added to progress.txt for future iterations\n - **NO_SCOPE_CREEP**: No unrelated changes, no refactoring, no \"improvements\"\n until: COMPLETE\n max_iterations: 15\n fresh_context: true\n\n # ═══════════════════════════════════════════════════════════════\n # NODE 5: COMPLETION REPORT\n # Reads final state and produces a summary.\n # ═══════════════════════════════════════════════════════════════\n\n - id: report\n depends_on: [implement]\n prompt: |\n # Completion Report\n\n The Ralph implementation loop has finished. Generate a completion report.\n\n ## Context\n\n **Loop output (last iteration):**\n\n $implement.output\n\n **Setup context:**\n\n $validate-prd.output\n\n ---\n\n ## Instructions\n\n ### 1. Read Final State\n\n Extract the `PRD_DIR=...` from the setup context above.\n Read the CURRENT files from disk:\n\n ```bash\n cat {prd-dir}/prd.json\n cat {prd-dir}/progress.txt\n ```\n\n ### 2. Gather Git Info\n\n ```bash\n git log --oneline --no-merges $(git merge-base HEAD $BASE_BRANCH)..HEAD\n git diff --stat $(git merge-base HEAD $BASE_BRANCH)..HEAD\n ```\n\n ### 3. Check PR Status\n\n ```bash\n gh pr view HEAD --json url,number,state 2>/dev/null || echo \"No PR found\"\n ```\n\n ### 4. Generate Report\n\n Output this format:\n\n ```\n ═══════════════════════════════════════════════════════\n RALPH DAG — COMPLETION REPORT\n ═══════════════════════════════════════════════════════\n\n Feature: {feature name from prd.json}\n PRD: {prd-dir}\n Branch: {branch name}\n PR: {url or \"not created\"}\n\n ── Stories ─────────────────────────────────────────\n\n | ID | Title | Status |\n |----|-------|--------|\n {for each story from prd.json}\n\n Total: {N}/{M} stories passing\n\n ── Commits ─────────────────────────────────────────\n\n {git log output}\n\n ── Files Changed ─────────────────────────────────\n\n {git diff --stat output}\n\n ── Patterns Discovered ─────────────────────────────\n\n {from ## Codebase Patterns in progress.txt, or \"None\"}\n\n ═══════════════════════════════════════════════════════\n ```\n\n Keep it factual. No commentary — just the data.\n", "archon-refactor-safely": "name: archon-refactor-safely\ndescription: |\n Use when: User wants to refactor code safely with continuous validation and behavior preservation.\n Triggers: \"refactor\", \"refactor safely\", \"split this file\", \"extract module\", \"break up\",\n \"decompose\", \"safe refactor\", \"split file\", \"extract into modules\".\n Does: Scans refactoring scope -> analyzes impact (read-only) -> plans ordered task list ->\n executes with type-check hooks after every edit -> validates full suite ->\n verifies behavior preservation (read-only) -> creates PR with before/after comparison.\n NOT for: Bug fixes (use archon-fix-github-issue), feature development (use archon-feature-development),\n general architecture sweeps (use archon-architect), PR reviews.\n\n Key safety features:\n - Analysis and verification nodes are read-only (denied_tools: [Write, Edit, Bash])\n - PreToolUse hooks check if each edit is in the plan\n - PostToolUse hooks force type-check after every file change\n - Behavior verification confirms no logic changes after refactoring\n\nprovider: claude\n\nnodes:\n # ═══════════════════════════════════════════════════════════════\n # PHASE 1: SCAN — Find files matching the refactoring target\n # ═══════════════════════════════════════════════════════════════\n\n - id: scan-scope\n bash: |\n echo \"=== REFACTORING TARGET ===\"\n echo \"User request: $ARGUMENTS\"\n echo \"\"\n\n echo \"=== FILE SIZE ANALYSIS (source files by size) ===\"\n find . -name '*.ts' -not -path '*/node_modules/*' -not -path '*/.git/*' -not -path '*/dist/*' -not -name '*.test.ts' -not -name '*.d.ts' \\\n -exec wc -l {} + 2>/dev/null | sort -rn | head -30\n echo \"\"\n\n echo \"=== FILES OVER 500 LINES ===\"\n find . -name '*.ts' -not -path '*/node_modules/*' -not -path '*/.git/*' -not -path '*/dist/*' -not -name '*.test.ts' -not -name '*.d.ts' \\\n -exec sh -c 'lines=$(wc -l < \"$1\"); if [ \"$lines\" -gt 500 ]; then echo \"$lines $1\"; fi' _ {} \\; 2>/dev/null | sort -rn\n echo \"\"\n\n echo \"=== FUNCTION COUNT PER FILE (top 20) ===\"\n for f in $(find . -name '*.ts' -not -path '*/node_modules/*' -not -path '*/.git/*' -not -path '*/dist/*' -not -name '*.test.ts' -not -name '*.d.ts'); do\n count=$(grep -cE '^\\s*(export\\s+)?(async\\s+)?function\\s|=>\\s*\\{' \"$f\" 2>/dev/null) || count=0\n if [ \"$count\" -gt 5 ]; then\n echo \"$count functions: $f\"\n fi\n done | sort -rn | head -20\n echo \"\"\n\n echo \"=== EXPORT ANALYSIS (files with many exports) ===\"\n for f in $(find . -name '*.ts' -not -path '*/node_modules/*' -not -path '*/.git/*' -not -path '*/dist/*' -not -name '*.test.ts' -not -name '*.d.ts'); do\n count=$(grep -c \"^export \" \"$f\" 2>/dev/null) || count=0\n if [ \"$count\" -gt 5 ]; then\n echo \"$count exports: $f\"\n fi\n done | sort -rn | head -20\n timeout: 60000\n\n # ═══════════════════════════════════════════════════════════════\n # PHASE 2: ANALYZE IMPACT — Read-only deep analysis\n # Maps call sites, identifies risk areas, understands dependencies\n # ═══════════════════════════════════════════════════════════════\n\n - id: analyze-impact\n prompt: |\n You are a senior software engineer analyzing code for a safe refactoring.\n\n ## Refactoring Request\n\n $ARGUMENTS\n\n ## Codebase Scan Results\n\n $scan-scope.output\n\n ## Instructions\n\n 1. Identify the PRIMARY file(s) targeted for refactoring based on the user's request\n and the scan results above\n 2. Read each target file thoroughly — understand every function, type, and export\n 3. For each target file, map ALL call sites:\n - Use Grep to find every import of the target file across the codebase\n - Track which specific exports are used and where\n - Note any dynamic imports or re-exports through index files\n 4. Identify risk areas:\n - Functions with complex internal dependencies (shared closures, module-level state)\n - Circular dependencies between functions in the file\n - Any module-level side effects (top-level `const`, initialization code)\n - Exports that are part of the public API vs internal-only\n 5. Check for existing tests:\n - Find test files for the target module(s)\n - Note what's tested and what isn't\n\n ## Output\n\n Write a thorough impact analysis to `$ARTIFACTS_DIR/impact-analysis.md` with:\n\n ### Target Files\n - File path, line count, function count\n - List of all exported symbols with brief descriptions\n\n ### Dependency Map\n - Which files import from the target (with specific imports used)\n - Which files the target imports from\n\n ### Risk Assessment\n - Module-level state or side effects\n - Complex internal dependencies between functions\n - Public API surface that must be preserved exactly\n\n ### Test Coverage\n - Existing test files and what they cover\n - Critical paths that must remain tested\n\n ### Recommended Decomposition Strategy\n - Suggested module boundaries (which functions group together)\n - Rationale for each grouping (cohesion, shared dependencies)\n depends_on: [scan-scope]\n context: fresh\n denied_tools: [Write, Edit, Bash]\n\n # ═══════════════════════════════════════════════════════════════\n # PHASE 3: PLAN REFACTOR — Ordered task list with rollback strategy\n # Read-only: produces the plan, does not execute it\n # ═══════════════════════════════════════════════════════════════\n\n - id: plan-refactor\n prompt: |\n You are planning a safe refactoring. You must produce a precise, ordered plan\n that another agent will follow literally.\n\n ## Impact Analysis\n\n $analyze-impact.output\n\n ## Refactoring Goal\n\n $ARGUMENTS\n\n ## Principles\n\n - **Behavior preservation**: The refactoring must NOT change any behavior — only structure\n - **Incremental**: Each step must leave the codebase in a compilable state\n - **Reversible**: Each step can be independently reverted\n - **No mixed concerns**: Do not combine refactoring with bug fixes or improvements\n - **Preserve public API**: All existing exports must remain accessible from the same import paths\n - **Maximum file size**: Target 500 lines or fewer per file after refactoring\n\n ## Instructions\n\n 1. Read the impact analysis from `$ARTIFACTS_DIR/impact-analysis.md`\n 2. Read the target file(s) to understand the current structure\n 3. Design the decomposition:\n - Group related functions into cohesive modules\n - Identify shared utilities, types, and constants\n - Plan the new file structure with descriptive names\n 4. Write an ordered task list where each task is:\n - Independent and leaves code compilable after completion\n - Specific about what to extract and where\n - Clear about import updates needed\n\n ## Output\n\n Write the plan to `$ARTIFACTS_DIR/refactor-plan.md` with:\n\n ### File Structure (Before)\n ```\n [current structure with line counts]\n ```\n\n ### File Structure (After)\n ```\n [planned structure with estimated line counts]\n ```\n\n ### Ordered Tasks\n\n For each task:\n ```\n ## Task N: [brief description]\n\n **Action**: CREATE | EXTRACT | UPDATE\n **Source**: [source file]\n **Target**: [target file]\n **What moves**:\n - function functionName (lines X-Y)\n - type TypeName (lines X-Y)\n\n **Import updates needed**:\n - [file]: change import from [old] to [new]\n\n **Rollback**: [how to undo this specific step]\n ```\n\n ### Validation Commands\n - Type check: `bun run type-check`\n - Lint: `bun run lint`\n - Tests: `bun run test`\n - Format: `bun run format:check`\n depends_on: [analyze-impact]\n context: fresh\n denied_tools: [Write, Edit, Bash]\n\n # ═══════════════════════════════════════════════════════════════\n # PHASE 4: EXECUTE REFACTOR — Implements the plan with guardrails\n # Hooks enforce type-check after every edit and plan adherence\n # ═══════════════════════════════════════════════════════════════\n\n - id: execute-refactor\n model: opus[1m]\n prompt: |\n You are executing a refactoring plan with strict safety guardrails.\n\n ## Plan\n\n Read the full plan from `$ARTIFACTS_DIR/refactor-plan.md` — follow it LITERALLY.\n\n ## Rules\n\n - **Follow the plan exactly** — do not add extra improvements or cleanups\n - **One task at a time** — complete each task fully before starting the next\n - **Type-check after every file change** — you'll be prompted to do this after each edit\n - **Preserve all behavior** — refactoring means moving code, not changing it\n - **Preserve the public API** — if the original file exported something, it must still be\n importable from the same path (use re-exports in the original file if needed)\n - **Update all import sites** — every file that imported from the original must be updated\n - **Commit after each logical task** — one commit per plan task with a clear message\n\n ## Process for Each Task\n\n 1. Read the plan task\n 2. Read the source file to understand current state\n 3. Create the new file (if extracting) with the functions/types being moved\n 4. Update the source file to remove the moved code and add imports from the new file\n 5. Update the original file's exports to re-export from the new module (API preservation)\n 6. Use Grep to find and update ALL import sites across the codebase\n 7. Run `bun run type-check` to verify (you'll be reminded by hooks)\n 8. Commit: `git add -A && git commit -m \"refactor: [task description]\"`\n 9. Move to next task\n\n ## Handling Problems\n\n - If type-check fails after a change: fix it immediately before proceeding\n - If a task is more complex than planned: complete it anyway, note the deviation\n - If you discover the plan missed an import site: update it and note it\n - NEVER skip a task — complete them in order\n depends_on: [plan-refactor]\n context: fresh\n hooks:\n PreToolUse:\n - matcher: \"Write|Edit\"\n response:\n hookSpecificOutput:\n hookEventName: PreToolUse\n additionalContext: >\n Before modifying this file: Is this file in your refactoring plan\n ($ARTIFACTS_DIR/refactor-plan.md)? If it's not a planned target file\n AND not a file that imports from the target, explain why you're touching it.\n Unplanned changes increase risk.\n PostToolUse:\n - matcher: \"Write|Edit\"\n response:\n systemMessage: >\n You just modified a file. STOP and do these things NOW before making any\n other changes:\n 1. Run `bun run type-check` to verify the change compiles\n 2. If type-check fails, fix the error immediately\n 3. Verify you preserved the exact same behavior — no logic changes, only structural moves\n Only proceed to the next change after type-check passes.\n - matcher: \"Bash\"\n response:\n hookSpecificOutput:\n hookEventName: PostToolUse\n additionalContext: >\n Check the exit code. If type-check or any validation failed, fix the issue\n before continuing. Do not accumulate broken state.\n\n # ═══════════════════════════════════════════════════════════════\n # PHASE 5: VALIDATE — Full test suite (bash, no AI escape hatch)\n # ═══════════════════════════════════════════════════════════════\n\n - id: validate\n bash: |\n echo \"=== TYPE CHECK ===\"\n bun run type-check 2>&1\n TC_EXIT=$?\n\n echo \"\"\n echo \"=== LINT ===\"\n bun run lint 2>&1\n LINT_EXIT=$?\n\n echo \"\"\n echo \"=== FORMAT CHECK ===\"\n bun run format:check 2>&1\n FMT_EXIT=$?\n\n echo \"\"\n echo \"=== TESTS ===\"\n bun run test 2>&1\n TEST_EXIT=$?\n\n echo \"\"\n echo \"=== FILE SIZE CHECK ===\"\n echo \"Files still over 500 lines:\"\n find . -name '*.ts' -not -path '*/node_modules/*' -not -path '*/.git/*' -not -path '*/dist/*' -not -name '*.test.ts' -not -name '*.d.ts' \\\n -exec sh -c 'lines=$(wc -l < \"$1\"); if [ \"$lines\" -gt 500 ]; then echo \"$lines $1\"; fi' _ {} \\; 2>/dev/null | sort -rn\n echo \"\"\n\n echo \"=== RESULTS ===\"\n echo \"Type check: $([ $TC_EXIT -eq 0 ] && echo 'PASS' || echo 'FAIL')\"\n echo \"Lint: $([ $LINT_EXIT -eq 0 ] && echo 'PASS' || echo 'FAIL')\"\n echo \"Format: $([ $FMT_EXIT -eq 0 ] && echo 'PASS' || echo 'FAIL')\"\n echo \"Tests: $([ $TEST_EXIT -eq 0 ] && echo 'PASS' || echo 'FAIL')\"\n\n if [ $TC_EXIT -eq 0 ] && [ $LINT_EXIT -eq 0 ] && [ $FMT_EXIT -eq 0 ] && [ $TEST_EXIT -eq 0 ]; then\n echo \"VALIDATION_STATUS: PASS\"\n else\n echo \"VALIDATION_STATUS: FAIL\"\n fi\n depends_on: [execute-refactor]\n timeout: 300000\n\n # ═══════════════════════════════════════════════════════════════\n # PHASE 6: FIX VALIDATION FAILURES (if any)\n # Only does real work if validation failed\n # ═══════════════════════════════════════════════════════════════\n\n - id: fix-failures\n prompt: |\n Review the validation output below.\n\n ## Validation Output\n\n $validate.output\n\n ## Instructions\n\n If the output ends with \"VALIDATION_STATUS: PASS\", respond with\n \"All checks passed — no fixes needed.\" and stop.\n\n If there are failures:\n\n 1. Read the validation failures carefully\n 2. Fix ONLY what's broken — do not make additional improvements\n 3. If a fix requires changing behavior (not just fixing a type/lint error),\n revert the original change instead\n 4. Run the specific failing check after each fix to confirm it passes\n 5. After all fixes, run the full validation suite: `bun run validate`\n\n If there are files still over 500 lines, note them but do NOT attempt further\n splitting in this node — that would require a new plan cycle.\n depends_on: [validate]\n context: fresh\n hooks:\n PostToolUse:\n - matcher: \"Write|Edit\"\n response:\n systemMessage: >\n You just made a fix. Run the specific failing validation check NOW\n to verify your fix works. Do not batch fixes — verify each one.\n PreToolUse:\n - matcher: \"Write|Edit\"\n response:\n hookSpecificOutput:\n hookEventName: PreToolUse\n additionalContext: >\n You are fixing validation failures only. Do not make any changes\n beyond what's needed to pass the failing checks. If in doubt, revert\n the original change that caused the failure.\n\n # ═══════════════════════════════════════════════════════════════\n # PHASE 7: VERIFY BEHAVIOR — Read-only confirmation\n # Ensures the refactoring preserved behavior by tracing call paths\n # ═══════════════════════════════════════════════════════════════\n\n - id: verify-behavior\n prompt: |\n You are a code reviewer verifying that a refactoring preserved exact behavior.\n You can ONLY read files — you cannot make any changes.\n\n ## Refactoring Plan\n\n Read the plan from `$ARTIFACTS_DIR/refactor-plan.md` to understand what was intended.\n\n ## Instructions\n\n 1. Use Grep and Glob to find all files in the new module locations listed in\n the plan, then Read each one. (Note: Bash is denied in this read-only node,\n so use Grep/Glob/Read to discover changes instead of git commands.)\n 2. For each new file created by the refactoring:\n - Verify the extracted functions match the originals exactly (no logic changes)\n - Check that all types and interfaces are preserved\n 3. For the original file(s):\n - Verify re-exports exist for all symbols that were previously exported\n - Confirm no function bodies were changed (only moved)\n 4. For all import sites updated:\n - Verify imports resolve to the correct new locations\n - Check that no import was missed\n 5. Verify the public API is preserved:\n - Any code that imported from the original file should still work unchanged\n - Re-exports in the original file should cover all moved symbols\n\n ## Output\n\n Write your verification report to `$ARTIFACTS_DIR/behavior-verification.md`:\n\n ### Verdict: PASS | FAIL\n\n ### Functions Verified\n | Function | Original Location | New Location | Behavior Preserved |\n |----------|------------------|--------------|-------------------|\n | funcName | file.ts:42 | new-file.ts:10 | Yes/No |\n\n ### Public API Check\n - [ ] All original exports still accessible from original import path\n - [ ] Re-exports correctly configured\n\n ### Import Sites Updated\n - [ ] All N import sites verified\n\n ### Issues Found\n [List any behavior changes detected, or \"None — refactoring is behavior-preserving\"]\n depends_on: [fix-failures]\n context: fresh\n denied_tools: [Write, Edit, Bash]\n\n # ═══════════════════════════════════════════════════════════════\n # PHASE 8: CREATE PR — Detailed description with before/after\n # ═══════════════════════════════════════════════════════════════\n\n - id: create-pr\n prompt: |\n Create a pull request for the refactoring.\n\n ## Context\n\n - **Refactoring goal**: $ARGUMENTS\n - **Impact analysis**: Read `$ARTIFACTS_DIR/impact-analysis.md`\n - **Refactoring plan**: Read `$ARTIFACTS_DIR/refactor-plan.md`\n - **Validation**: $validate.output\n - **Behavior verification**: Read `$ARTIFACTS_DIR/behavior-verification.md`\n\n ## Instructions\n\n 1. Stage all changes and create a final commit if there are uncommitted changes\n 2. Push the branch: `git push -u origin HEAD`\n 3. Check if a PR already exists: `gh pr list --head $(git branch --show-current)`\n 4. Create the PR with the format below\n 5. Save the PR URL to `$ARTIFACTS_DIR/.pr-url`\n\n ## PR Format\n\n - **Title**: `refactor: [concise description]` (under 70 chars)\n - **Body**:\n\n ```markdown\n ## Refactoring: [goal]\n\n ### Motivation\n\n [Why this refactoring was needed — file sizes, complexity, maintainability]\n\n ### Before\n\n ```\n [Original file structure with line counts from the plan]\n ```\n\n ### After\n\n ```\n [New file structure with line counts]\n ```\n\n ### Changes\n\n [For each new module: what was extracted and why it's a cohesive unit]\n\n ### Safety\n\n - [x] Type check passes\n - [x] Lint passes\n - [x] Tests pass (all existing tests still green)\n - [x] Public API preserved (re-exports maintain backward compatibility)\n - [x] Behavior verification passed (read-only audit confirmed no logic changes)\n - [x] Each task committed separately for easy review/revert\n\n ### Review Guide\n\n Each commit represents one extraction step. Review commits individually for easiest review.\n All commits are behavior-preserving structural moves.\n ```\n depends_on: [verify-behavior]\n context: fresh\n hooks:\n PreToolUse:\n - matcher: \"Write|Edit\"\n response:\n hookSpecificOutput:\n hookEventName: PreToolUse\n permissionDecision: deny\n permissionDecisionReason: \"PR creation node — do not modify source files. Use only git and gh commands.\"\n PostToolUse:\n - matcher: \"Bash\"\n response:\n hookSpecificOutput:\n hookEventName: PostToolUse\n additionalContext: >\n Verify this command succeeded. If git push or gh pr create failed,\n read the error message carefully before retrying.\n",