1. Use requirements as the source of truth - If

   ce-brainstorm

   produced a requirements document, planning should build from it rather than re-inventing behavior.
2. Decisions, not code - Capture approach, boundaries, files, dependencies, risks, and test scenarios. Do not pre-write implementation code or shell command choreography. Pseudo-code sketches or DSL grammars that communicate high-level technical design are welcome when they help a reviewer validate direction — but they must be explicitly framed as directional guidance, not implementation specification.
3. Research before structuring - Explore the codebase, institutional learnings, and external guidance when warranted before finalizing the plan.
4. Right-size the artifact - Small work gets a compact plan. Large work gets more structure. The philosophy stays the same at every depth.
5. Separate planning from execution discovery - Resolve planning-time questions here. Explicitly defer execution-time unknowns to implementation.
6. Keep the plan portable - The plan should work as a living document, review artifact, or issue body without embedding tool-specific executor instructions.
7. Carry execution posture lightly when it matters - If the request, origin document, or repo context clearly implies test-first, characterization-first, or another non-default execution posture, reflect that in the plan as a lightweight signal. Do not turn the plan into step-by-step execution choreography.
8. Honor user-named resources - When the user names a specific resource — a CLI, MCP server, URL, file, doc link, or prior artifact — treat it as authoritative input, not a suggestion. Discover it if unknown (

   command -v

   , fetch, read) before assuming it's unavailable. Use it in place of generic alternatives. If it fails or doesn't exist, say so explicitly rather than silently substituting.

• A clear problem frame and scope boundary
• Concrete requirements traceability back to the request or origin document
• Repo-relative file paths for the work being proposed (never absolute paths — see Planning Rules)
• Explicit test file paths for feature-bearing implementation units
• Decisions with rationale, not just tasks
• Existing patterns or code references to follow
• Enumerated test scenarios for each feature-bearing unit, specific enough that an implementer knows exactly what to test without inventing coverage themselves
• Clear dependencies and sequencing

docs/plans/

• Read it
• Confirm whether to update it in place or create a new plan
• If updating, preserve completed checkboxes and revise only the still-relevant sections

docs/plans/

status: active

• If the plan lacks YAML frontmatter (non-software plans use a simple

  # Title

  heading with

  Created:

  date instead of frontmatter), route to

  references/universal-planning.md

  for editing or deepening instead of Phase 5.3. Non-software plans do not use the software confidence check.
• Otherwise, short-circuit to Phase 5.3 (Confidence Check and Deepening) in interactive mode. This avoids re-running the full planning workflow and gives the user control over which findings are integrated.

deepened: YYYY-MM-DD

docs/brainstorms/

*-requirements.md

• The topic semantically matches the feature description
• It was created within the last 30 days (use judgment to override if the document is clearly still relevant or clearly stale)
• It appears to cover the same user problem or scope

1. Read it thoroughly
2. Announce that it will serve as the origin document for planning
3. Carry forward all of the following:
   • Problem frame
   • Requirements and success criteria
   • Scope boundaries
   • Key decisions and rationale
   • Dependencies or assumptions
   • Outstanding questions, preserving whether they are blocking or deferred
4. Use the source document as the primary input to planning and research
5. Reference important carried-forward decisions in the plan with

   (see origin: <source-path>)

6. Do not silently omit source content — if the origin document discussed it, the plan must address it even if briefly. Before finalizing, scan each section of the origin document to verify nothing was dropped.

• Assess whether the request is already clear enough for direct technical planning — if so, continue to Phase 0.5
• If the ambiguity is mainly product framing, user behavior, or scope definition, recommend

  ce-brainstorm

  as a suggestion — but always offer to continue planning here as well
• If the user wants to continue here (or was already explicit about wanting a plan), run the planning bootstrap below

• Problem frame
• Intended behavior
• Scope boundaries and obvious non-goals
• Success criteria
• Blocking questions or assumptions

• Recommend

  ce-brainstorm

  again
• If the user still wants to continue, require explicit assumptions before proceeding

• Symptom without a root cause (user describes broken behavior but hasn't identified why) — announce that investigation is needed before planning and load the

  ce-debug

  skill. A plan requires a known problem to solve; debugging identifies what that problem is. Announce the routing clearly: "This needs investigation before planning — switching to ce-debug to find the root cause."
• Clear task ready to execute (known root cause, obvious fix, no architectural decisions) — suggest

  ce-work

  as a faster alternative alongside continuing with planning. The user decides.

Resolve Before Planning

• Review each one before proceeding
• Reclassify it into planning-owned work only if it is actually a technical, architectural, or research question
• Keep it as a blocker if it would change product behavior, scope, or success criteria

• Surface them clearly
• Ask the user, using the platform's blocking question tool when available (see Interaction Method), whether to:
  1. Resume

     ce-brainstorm

     to resolve them
  2. Convert them into explicit assumptions or decisions and continue
• Do not continue planning while true blockers remain unresolved

• Lightweight - small, well-bounded, low ambiguity
• Standard - normal feature or bounded refactor with some technical decisions to document
• Deep - cross-cutting, strategic, high-risk, or highly ambiguous implementation work

• If an origin document exists, summarize the problem frame, requirements, and key decisions from that document
• Otherwise use the feature description directly

• Task research:ce-repo-research-analyst(Scope: technology, architecture, patterns. {planning context summary})
• Task research:ce-learnings-researcher(planning context summary) Collect:
• Technology stack and versions (used in section 1.2 to make sharper external research decisions)
• Architectural patterns and conventions to follow
• Implementation patterns, relevant files, modules, and tests
• AGENTS.md guidance that materially affects the plan, with CLAUDE.md used only as compatibility fallback when present
• Institutional learnings from

  docs/solutions/

• Tools available + user asked: Dispatch

  research:ce-slack-researcher

  with the planning context summary in parallel with other Phase 1.1 agents. If the origin document has a Slack context section, pass it verbatim so the researcher focuses on gaps. Include findings in consolidation.
• Tools available + user didn't ask: Note in output: "Slack tools detected. Ask me to search Slack for organizational context at any point, or include it in your next prompt."
• No tools + user asked: Note in output: "Slack context was requested but no Slack tools are available. Install and authenticate the Slack plugin to enable organizational context search."

• The user explicitly asks for TDD, test-first, or characterization-first work
• The origin document calls for test-first implementation or exploratory hardening of legacy code
• Local research shows the target area is legacy, weakly tested, or historically fragile, suggesting characterization coverage before changing behavior

• User familiarity — Are they pointing to specific files or patterns? They likely know the codebase well.
• User intent — Do they want speed or thoroughness? Exploration or execution?
• Topic risk — Security, payments, external APIs warrant more caution regardless of user signals.
• Uncertainty level — Is the approach clear or still open-ended?

• If specific frameworks and versions were detected (e.g., Rails 7.2, Next.js 14, Go 1.22), pass those exact identifiers to ce-framework-docs-researcher so it fetches version-specific documentation
• If the feature touches a technology layer the scan found well-established in the repo (e.g., existing Sidekiq jobs when planning a new background job), lean toward skipping external research -- local patterns are likely sufficient
• If the feature touches a technology layer the scan found absent or thin (e.g., no existing proto files when planning a new gRPC service), lean toward external research -- there are no local patterns to follow
• If the scan detected deployment infrastructure (Docker, K8s, serverless), note it in the planning context passed to downstream agents so they can account for deployment constraints
• If the scan detected a monorepo and scoped to a specific service, pass that service's tech context to downstream research agents -- not the aggregate of all services. If the scan surfaced the workspace map without scoping, use the feature description to identify the relevant service before proceeding with research

• The topic is high-risk: security, payments, privacy, external APIs, migrations, compliance
• The codebase lacks relevant local patterns -- fewer than 3 direct examples of the pattern this plan needs
• Local patterns exist for an adjacent domain but not the exact one -- e.g., the codebase has HTTP clients but not webhook receivers, or has background jobs but not event-driven pub/sub. Adjacent patterns suggest the team is comfortable with the technology layer but may not know domain-specific pitfalls. When this signal is present, frame the external research query around the domain gap specifically, not the general technology
• The user is exploring unfamiliar territory
• The technology scan found the relevant layer absent or thin in the codebase

• The codebase already shows a strong local pattern -- multiple direct examples (not adjacent-domain), recently touched, following current conventions
• The user already knows the intended shape
• Additional external context would add little practical value
• The technology scan found the relevant layer well-established with existing examples to follow

• "Your codebase has solid patterns for this. Proceeding without external research."
• "This involves payment processing, so I'll research current best practices first."

• Task research:ce-best-practices-researcher(planning context summary)
• Task research:ce-framework-docs-researcher(planning context summary)

• Relevant codebase patterns and file paths
• Relevant institutional learnings
• Organizational context from Slack conversations, if gathered (prior discussions, decisions, or domain knowledge relevant to the feature)
• External references and best practices, if gathered
• Related issues, PRs, or prior art
• Any constraints that should materially shape the plan

• Environment variables consumed by external systems, CI, or other repositories
• Exported public APIs, CLI flags, or command-line interface contracts
• CI/CD configuration files (

  .github/workflows/

  ,

  Dockerfile

  , deployment scripts)
• Shared types or interfaces imported by downstream consumers
• Documentation referenced by external URLs or linked from other systems

• Task workflow:ce-spec-flow-analyzer(planning context summary, research findings)

• Identify missing edge cases, state transitions, or handoff gaps
• Tighten requirements trace or verification strategy
• Add only the flow details that materially improve the plan

• Deferred questions in the origin document
• Gaps discovered in repo or external research
• Technical decisions required to produce a useful plan

• Resolved during planning - the answer is knowable from repo context, documentation, or user choice
• Deferred to implementation - the answer depends on code changes, runtime behavior, or execution-time discovery

• Draft a clear, searchable title using conventional format such as

  feat: Add user authentication

  or

  fix: Prevent checkout double-submit

• Determine the plan type:

  feat

  ,

  fix

  , or

  refactor

• Build the filename following the repository convention:

  docs/plans/YYYY-MM-DD-NNN-<type>-<descriptive-name>-plan.md

  • Create

    docs/plans/

    if it does not exist
  • Check existing files for today's date to determine the next sequence number (zero-padded to 3 digits, starting at 001)
  • Keep the descriptive name concise (3-5 words) and kebab-cased
  • Examples:

    2026-01-15-001-feat-user-authentication-flow-plan.md

    ,

    2026-02-03-002-fix-checkout-race-condition-plan.md

  • Avoid: missing sequence numbers, vague names like "new-feature", invalid characters (colons, spaces)

• Focused on one component, behavior, or integration seam
• Usually touching a small cluster of related files
• Ordered by dependency
• Concrete enough for execution without pre-writing code
• Marked with checkbox syntax for progress tracking

• 2-5 minute micro-steps
• Units that span multiple unrelated concerns
• Units that are so vague an implementer still has to invent the plan

• Well-patterned work where prose and file paths tell the whole story
• Straightforward CRUD or convention-following changes
• Lightweight plans where the approach is obvious

## Output Structure

• The plan creates 3+ new files in a new directory hierarchy
• The directory layout itself is a meaningful design decision

• The plan only modifies existing files
• The plan creates 1-2 files in an existing directory — the per-unit file lists are sufficient

**Files:**

• Goal - what this unit accomplishes
• Requirements - which requirements or success criteria it advances
• Dependencies - what must exist first
• Files - repo-relative file paths to create, modify, or test (never absolute paths)
• Approach - key decisions, data flow, component boundaries, or integration notes
• Execution note - optional, only when the unit benefits from a non-default execution posture such as test-first or characterization-first
• Technical design - optional pseudo-code or diagram when the unit's approach is non-obvious and prose alone would leave it ambiguous. Frame explicitly as directional guidance, not implementation specification
• Patterns to follow - existing code or conventions to mirror
• Test scenarios - enumerate the specific test cases the implementer should write, right-sized to the unit's complexity and risk. Consider each category below and include scenarios from every category that applies to this unit. A simple config change may need one scenario; a payment flow may need a dozen. The quality signal is specificity — each scenario should name the input, action, and expected outcome so the implementer doesn't have to invent coverage. For units with no behavioral change (pure config, scaffolding, styling), use

  Test expectation: none -- [reason]

  instead of leaving the field blank.
  • Happy path behaviors - core functionality with expected inputs and outputs
  • Edge cases (when the unit has meaningful boundaries) - boundary values, empty inputs, nil/null states, concurrent access
  • Error and failure paths (when the unit has failure modes) - invalid input, downstream service failures, timeout behavior, permission denials
  • Integration scenarios (when the unit crosses layers) - behaviors that mocks alone will not prove, e.g., "creating X triggers callback Y which persists Z". Include these for any unit touching callbacks, middleware, or multi-layer interactions
• Verification - how an implementer should know the unit is complete, expressed as outcomes rather than shell command scripts

**Files:**

Execution note

• Execution note: Start with a failing integration test for the request/response contract.

• Execution note: Add characterization coverage before modifying this legacy parser.

• Execution note: Implement new domain behavior test-first.

RED/GREEN/REFACTOR

• Exact method or helper names
• Final SQL or query details after touching real code
• Runtime behavior that depends on seeing actual test failures
• Refactors that may become unnecessary once implementation starts

• Keep the plan compact
• Usually 2-4 implementation units
• Omit optional sections that add little value

• Use the full core template, omitting optional sections (including High-Level Technical Design) that add no value for this particular work
• Usually 3-6 implementation units
• Include risks, deferred questions, and system-wide impact when relevant

• Use the full core template plus optional analysis sections where warranted
• Usually 4-8 implementation units
• Group units into phases when that improves clarity
• Include alternatives considered, documentation impacts, and deeper risk treatment when warranted

• Alternative Approaches Considered
• Success Metrics
• Dependencies / Prerequisites
• Risk Analysis & Mitigation
• Phased Delivery
• Documentation Plan
• Operational / Rollout Notes
• Future Considerations only when they materially affect current design

• R1. [Requirement or success criterion this plan must satisfy]
• R2. [Requirement or success criterion this plan must satisfy]

• [Explicit non-goal or exclusion]

• [Work that will be done separately]: [Where or when -- e.g., "separate PR in repo-x", "future iteration"]

• [Existing file, class, component, or pattern to follow]

• [Relevant

  docs/solutions/

  insight]

• [Relevant external docs or best-practice source, if used]

• [Question or unknown]: [Why it is intentionally deferred]

This illustrates the intended approach and is directional guidance for review, not implementation specification. The implementing agent should treat it as context, not code to reproduce.

• Unit 1: [Name]

• Create:

  path/to/new_file

• Modify:

  path/to/existing_file

• Test:

  path/to/test_file

• [Key design or sequencing decision]

• [Existing file, class, or pattern]

• [Scenario: specific input/action -> expected outcome. Prefix with category — Happy path, Edge case, Error path, or Integration — to signal intent]

• [Outcome that should hold when this unit is complete]

• Interaction graph: [What callbacks, middleware, observers, or entry points may be affected]
• Error propagation: [How failures should travel across layers]
• State lifecycle risks: [Partial-write, cache, duplicate, or cleanup concerns]
• API surface parity: [Other interfaces that may require the same change]
• Integration coverage: [Cross-layer scenarios unit tests alone will not prove]
• Unchanged invariants: [Existing APIs, interfaces, or behaviors that this plan explicitly does not change — and how the new work relates to them. Include when the change touches shared surfaces and reviewers need blast-radius assurance]

• [Docs, rollout, monitoring, or support impacts when relevant]

• Origin document: docs/brainstorms/YYYY-MM-DD-<topic>-requirements.md
• Related code: [path or symbol]
• Related PRs/issues: #[number]
• External docs: [url]

For larger `Deep` plans, extend the core template only when useful with sections such as:

```markdown

• [Approach]: [Why rejected or not chosen]

• [How we will know this solved the intended problem]

• [Technical, organizational, or rollout dependency]

• [What lands first and why]

• [What follows and why]

• [Docs or runbooks to update]

• [Monitoring, migration, feature flag, or rollout considerations]

undefined

• All file paths must be repo-relative — never use absolute paths like

  /Users/name/Code/project/src/file.ts

  . Use

  src/file.ts

  instead. Absolute paths make plans non-portable across machines, worktrees, and teammates. When a plan targets a different repo than the document's home, state the target repo once at the top of the plan (e.g.,

  **Target repo:** my-other-project

  ) and use repo-relative paths throughout
• Prefer path plus class/component/pattern references over brittle line numbers
• Keep implementation units checkable with

  - [ ]

  syntax for progress tracking
• Do not include implementation code — no imports, exact method signatures, or framework-specific syntax
• Pseudo-code sketches and DSL grammars are allowed in the High-Level Technical Design section and per-unit technical design fields when they communicate design direction. Frame them explicitly as directional guidance, not implementation specification
• Mermaid diagrams are encouraged when they clarify relationships or flows that prose alone would make hard to follow — ERDs for data model changes, sequence diagrams for multi-service interactions, state diagrams for lifecycle transitions, flowcharts for complex branching logic
• Do not include git commands, commit messages, or exact test command recipes
• Do not expand implementation units into micro-step

  RED/GREEN/REFACTOR

  instructions
• Do not pretend an execution-time question is settled just to make the plan look complete

• The plan does not invent product behavior that should have been defined in

  ce-brainstorm

• If there was no origin document, the bounded planning bootstrap established enough product clarity to plan responsibly
• Every major decision is grounded in the origin document or research
• Each implementation unit is concrete, dependency-ordered, and implementation-ready
• If test-first or characterization-first posture was explicit or strongly implied, the relevant units carry it forward with a lightweight

  Execution note

• Each feature-bearing unit has test scenarios from every applicable category (happy path, edge cases, error paths, integration) — right-sized to the unit's complexity, not padded or skimped
• Test scenarios name specific inputs, actions, and expected outcomes without becoming test code
• Feature-bearing units with blank or missing test scenarios are flagged as incomplete — feature-bearing units must have actual test scenarios, not just an annotation. The

  Test expectation: none -- [reason]

  annotation is only valid for non-feature-bearing units (pure config, scaffolding, styling)
• Deferred items are explicit and not hidden as fake certainty
• If a High-Level Technical Design section is included, it uses the right medium for the work, carries the non-prescriptive framing, and does not contain implementation code (no imports, exact signatures, or framework-specific syntax)
• Per-unit technical design fields, if present, are concise and directional rather than copy-paste-ready
• If the plan creates a new directory structure, would an Output Structure tree help reviewers see the overall shape?
• If Scope Boundaries lists items that are planned work for a separate PR or task, are they under

  ### Deferred to Separate Tasks

  rather than mixed with true non-goals?
• Would a visual aid (dependency graph, interaction diagram, comparison table) help a reader grasp the plan structure faster than scanning prose alone?

• The chosen approach still matches the product intent
• Scope boundaries and success criteria are preserved
• Blocking questions were either resolved, explicitly assumed, or sent back to

  ce-brainstorm

• Every section of the origin document is addressed in the plan — scan each section to confirm nothing was silently dropped

• Auto mode (default during plan generation): Runs without asking the user for approval. The user sees what is being strengthened but does not need to make a decision. Sub-agent findings are synthesized directly into the plan.
• Interactive mode (activated by the re-deepen fast path in Phase 0.1): The user explicitly asked to deepen an existing plan. Sub-agent findings are presented individually for review before integration. The user can accept, reject, or discuss each agent's findings. Only accepted findings are synthesized into the plan.

ce-doc-review

• Use the

  ce-doc-review

  skill when the document needs clarity, simplification, completeness, or scope control
• This confidence check strengthens rationale, sequencing, risk treatment, and system-wide thinking when the plan is structurally sound but still needs stronger grounding

• Lightweight - small, bounded, low ambiguity, usually 2-4 implementation units
• Standard - moderate complexity, some technical decisions, usually 3-6 units
• Deep - cross-cutting, high-risk, or strategically important work, usually 4-8 units or phased delivery

• Authentication, authorization, or security-sensitive behavior
• Payments, billing, or financial flows
• Data migrations, backfills, or persistent data changes
• External APIs or third-party integrations
• Privacy, compliance, or user data handling
• Cross-interface parity or multi-surface behavior
• Significant rollout, monitoring, or operational concerns

• Lightweight plans usually do not need deepening unless they are high-risk
• Standard plans often benefit when one or more important sections still look thin
• Deep or high-risk plans often benefit from a targeted second pass
• Thin local grounding override: If Phase 1.2 triggered external research because local patterns were thin (fewer than 3 direct examples or adjacent-domain match), always proceed to scoring regardless of how grounded the plan appears. When the plan was built on unfamiliar territory, claims about system behavior are more likely to be assumptions than verified facts. The scoring pass is cheap — if the plan is genuinely solid, scoring finds nothing and exits quickly