plan

CodeBrain Plan

Single-task implementation planning with automatic verification. The core Plan → Execute → Verify workflow.

Usage

/codebrain:plan <task description>

Workflow

Phase 0: Linear Context Loading (when linearSync is enabled)

Read .codebrain/config.json for linearSync, linearProjectId, and linearIssueMap.

If linearSync is "required" or "optional" (with Linear available):

1. Identify the Linear issue for this task:

   • If working on an epic ticket: look up the ticket slug in linearIssueMap to get the Linear issue ID
   • Call get_issue with the issue ID to load:
     • Latest description (may have been updated in Linear since last session)
     • Current status (if already "Done" → warn and stop; if "In Progress" → warn about concurrent work)
     • Acceptance criteria from the description
   • Call list_comments to load:
     • Clarifications from team members
     • Prior verification results
     • Any [NEEDS CLARIFICATION] resolutions posted as comments
   • If the Linear description differs from the local ticket file: use the Linear version (it's the source of truth)

2. Update Linear status:

   • Call update_issue to set status to "In Progress"
   • This signals to other sessions/agents that this ticket is being worked on

3. Load the PRD from Linear (not local cache):

   • Call list_documents for the project to find the PRD document
   • Call get_document to read the latest PRD
   • Use this for spec reconciliation later (Phase 4b)

Phase 1: Deterministic Context Prefetch (Stripe Minions Pattern)

All context is assembled BEFORE any agent is spawned. The skill itself (not the agent) gathers everything deterministically. The agent receives a pre-assembled context package and focuses purely on planning — no discovery.

Tools to use in this phase: codebrain MCP (memory, config), codebase-memory MCP (architecture, search), Linear MCP (issue details). NO agentic tools.

1. Call mcp__codebrain__codebrain_memory_read with file: "all" to load project memory.
2. Read constitution — .codebrain/memory/constitution.md is non-negotiable.
3. Call mcp__codebrain__codebrain_config_read to get project settings.
4. Read the project's conventions file (path from config, e.g., CLAUDE.md).
5. Check for reusable patterns: Read .codebrain/memory/patterns.md — if a similar task was completed before, load that pattern as a starting template for the planner. (Blueprint Reuse — Stripe Minions Pattern 8)

Phase 1b: Codebase Intelligence Prefetch

If codebase-memory MCP is available (deterministic MCP calls, not agentic): 6. Call mcp__codebase_memory__get_architecture to get the module map. 7. Call mcp__codebase_memory__search_graph with task keywords to find relevant code. 8. Call mcp__codebase_memory__detect_changes to check for recent modifications.

Phase 1c: API Research (agentic, but scoped)

If the task involves API endpoints, SDKs, or third-party integrations: 9. Spawn api-researcher agent with ONLY:

• The task description
• Which APIs/SDKs are involved
• Tools to use: Context7 MCP, Sonatype MCP, Read, Bash (read-only). No other MCP servers.

10. The api-researcher returns: documentation source, correct patterns, version status, deprecated methods.

Phase 2: Planning (Agent receives pre-assembled context)

11. Bundle the context package:

    Context package = {
      task: user's task description,
      constitution: full text,
      memory: { continuity, architecture, patterns, known_issues, decisions },
      conventions: project conventions file content,
      codebase: { architecture_map, relevant_modules, recent_changes },
      api_research: (if Phase 1c ran) { official_docs, correct_patterns, version_info },
      reusable_pattern: (if found in Step 5) { prior_plan_template },
      linear_context: (if Phase 0 ran) { issue_description, comments, status }
    }
    

12. Spawn the planner agent with the context package and instructions to:

    • Do NOT discover context — it's already provided. Focus on planning.
    • Tools to use: Read, Glob, Grep, Bash (read-only). Use codebase-memory MCP and code-review-graph MCP for blast radius. Do NOT use Lighthouse, Sentry, Socket, test-coverage, or ESLint — those are for verification, not planning.
    • If a reusable pattern was provided, adapt it rather than planning from scratch
    • Flag ALL ambiguities with [NEEDS CLARIFICATION] markers
    • Use EARS notation for verification criteria
    • Include constitution compliance check
    • Produce a structured plan with blast radius analysis

13. Review the plan for [NEEDS CLARIFICATION] markers.

    • If markers found: present each to the user and ask for resolution
    • Update the plan with resolved answers
    • Re-run planning only for affected sections if resolution changes scope
    • Do NOT proceed to execution while any markers remain

14. Present the plan to the user for approval.

    • If rejected: ask what to change, re-plan
    • If approved: proceed to execution

Phase 3: Execution

11. Save the plan to .codebrain/active/plan.md via mcp__codebrain__codebrain_artifact_write.
12. Execute the plan step by step:
    • Read each target file before modifying
    • Apply changes using Edit (for modifications) or Write (for new files)
    • Follow the execution order from the plan
    • Task recitation: Before EACH implementation step, re-read the relevant verification criteria from the plan to stay anchored to the spec

Phase 4: Verification

13. Invoke /codebrain:verify .codebrain/active/plan.md to run verification.
14. If verification fails with Critical/Major issues:
    • Fix the issues
    • Re-verify (max 2 cycles — then generate handoff summary)
15. If verification passes: proceed to spec reconciliation.

Phase 4b: Spec Reconciliation

16. Compare implementation against the plan:
    • Did you implement everything the plan specified?
    • Did you implement anything NOT in the plan? (scope creep detection)
    • Did any implementation detail differ from the plan?
17. For each divergence:
    • Add a [SPEC_DEVIATION: plan says X, implementation does Y — reason: Z] marker
    • Ask the user: update the plan to match, or fix the code?
18. If this plan was for an epic ticket, update the ticket's execution log.

Phase 4c: Linear Post-Completion (when linearSync is enabled)

If Linear sync is active and this task maps to a Linear issue:

1. Update issue status:

   • If verification PASSED: call update_issue to set status to "Done"
   • If verification FAILED but within fix cycles: keep as "In Progress"
   • If verification FAILED after 2 cycles: set to "In Review" for manual attention

2. Post completion comment:

   • Call create_comment on the issue with:

     ## Implementation Complete
     
     **Verification:** PASS/FAIL
     **Files changed:** [list of modified files]
     **Spec deviations:** [any SPEC_DEVIATION markers and their resolution]
     **Key decisions:** [decisions made during implementation]
     
     Executed by codebrain:plan on [date]
     

3. Check for unblocked downstream tickets:

   • If this ticket was blocking others (via Linear issue relations), those tickets are now unblocked
   • Note which tickets are now ready in the completion report

Phase 5: Memory Update

19. Call mcp__codebrain__codebrain_memory_update for continuity with:
    • What was done (task summary)
    • Key decisions made during implementation
    • What's next (follow-up work identified)
    • Any [SPEC_DEVIATION] markers and their resolution
20. Update CLAUDE.md — If the plan introduced new tech decisions or patterns, append them to the project's conventions file so future sessions have context.
21. Report completion with verification results.

Key Principles

• Constitution is law. Read it, follow it, justify any deviation.
• [NEEDS CLARIFICATION] blocks execution. Plans with unresolved markers cannot proceed.
• Plan before code. Never start editing without a plan.
• Task recitation. Re-read the spec objectives before each implementation step to prevent drift.
• Spec reconciliation. After implementation, diff against the plan and surface divergences.
• EARS for acceptance criteria. When/While/Where/If-Then-Otherwise format.
• Reference existing patterns. The planner agent must cite file:line for every claim.
• Verify before claiming done. Verification is not optional.
• Update memory. Every completed task updates continuity.