plan-feature

name	plan-feature
description	Orchestrates the implementation planning process — generating plan artifacts, architecture decisions, and design documents from a feature specification. Use when running /sddp-plan or when implementation planning is needed.

Software Architect — Plan Feature Workflow

- Report compact progress at major milestones: outcome, key delta, next step - Follow all writing rules in `.github/skills/plan-authoring/SKILL.md` (read in Step 0) — including Instructions Check gate, NEEDS CLARIFICATION resolution, research consolidation, and artifact conventions - **Question batching**: Batch all user-facing questions into a single interaction point. Never issue separate sequential prompts when one combined prompt works. - **Delegation**: Use specialized roles for Data Modeling, API Contracts, and Compliance Auditing - Research before designing — **Delegate: Technical Researcher**; reuse `FEATURE_DIR/research.md` when sufficient - If user attaches/references a technical context document → capture path, persist in `.github/sddp-config.md`

0. Acquire Skills

1. Resolve Context

Resolve FEATURE_DIR from git branch (specs/<branch>/) or user context.

Delegate: Context Gatherer in quick mode (.github/agents/_context-gatherer.md).

• HAS_SPEC = false → ERROR "Missing spec.md at FEATURE_DIR/spec.md. Run /sddp-specify [description] to create it."
• plan.md missing → read template from .github/skills/plan-authoring/assets/plan-template.md, create FEATURE_DIR/plan.md
• plan.md exists:
  • Autopilot guard (P1): AUTOPILOT = true → default Overwrite. Log a decision row to FEATURE_DIR/autopilot-log.md: Timestamp=now, Phase=Plan, Event=decision, Detail="Existing plan.md found", Outcome="Overwrite", Rationale="autopilot default", Artifacts=[plan.md](plan.md).
  • AUTOPILOT = false → ask overwrite or refine

Load FEATURE_DIR/spec.md. Detect SPEC_TYPE from frontmatter (absent → product).

Spec Maturity Check: Read spec_maturity from frontmatter (absent → draft).

• draft → WARN: "Spec has not been through clarification. Consider running /sddp-clarify first to reduce rework risk."
• clarified or higher → continue without warning.

1.5. Technical Context Document

Check for user-attached file or path in $ARGUMENTS/conversation.

1. Detect: file attachments, explicit paths, mentions of "tech context"/"architecture doc"/"SAD"/etc.
2. Auto-adopt default: HAS_TECH_CONTEXT_DOC = false + no new doc + specs/sad.md exists → read it, persist to .github/sddp-config.md, set TECH_CONTEXT_DOC/TECH_CONTEXT_CONTENT → Step 2
3. Existing registered: HAS_TECH_CONTEXT_DOC = true + no new doc → read TECH_CONTEXT_DOC → TECH_CONTEXT_CONTENT → Step 2
4. New file detected:
   • Validate readable (unreadable → warn, proceed without)
   • If HAS_TECH_CONTEXT_DOC = true + different path:
     • TECH_CONTEXT_DOC is specs/sad.md:
       • Autopilot guard (P2): AUTOPILOT = true → Keep existing, log
       • AUTOPILOT = false → ask "Keep existing" (recommended) / "Replace"
     • TECH_CONTEXT_DOC is not specs/sad.md:
       • Autopilot guard (P2): AUTOPILOT = true → Replace, log
       • AUTOPILOT = false → ask "Replace" (recommended) / "Keep existing"
   • Confirmed or no prior doc → write path to .github/sddp-config.md, store TECH_CONTEXT_CONTENT
5. Nothing detected + no existing: set TECH_CONTEXT_PENDING = true (batched with Step 2 questions)
6. No document: TECH_CONTEXT_CONTENT = empty. Planning proceeds with interactive Q&A.

Tech context path is a reference — original file read on demand. Missing file → graceful error handling.

1.6. Spec → Plan Gate

Mandatory structural validation of spec.md before designing plan.md. Blocks the Plan phase on FAIL.

Delegate: Spec Validator (.github/agents/_spec-validator.md):

• SpecPath: FEATURE_DIR/spec.md
• ChecklistPath: null (read-only verdict; do NOT generate a checklist file)

Parse the returned verdict (Result: PASS | FAIL, Score, Failing Items, Recommendations).

• PASS → continue to Step 2.
• FAIL:
  • Report the failing items and recommendations table.
  • Autopilot guard (P0): AUTOPILOT = true → HALT. Log a halt row to FEATURE_DIR/autopilot-log.md (when present): Timestamp=now, Phase=Plan, Event=halt, Detail="Spec → Plan gate FAIL", Outcome="Halt planning", Rationale="mandatory structural validation failed", Artifacts=[spec.md](spec.md). Do not proceed to design.
  • AUTOPILOT = false → prompt the user:
    • "Fix spec and retry (recommended) — resolve the failing items, then re-run /sddp-plan"
    • "Proceed anyway — continue planning despite the validation failures (downstream phases may produce a low-quality plan)"
    • Handle choice: "Fix and retry" → halt, direct user to /sddp-specify//sddp-clarify. "Proceed anyway" → continue to Step 2 (the bypass is recorded only in this conversation; no persistent marker is written).

2. Alignment & Pre-Research Gate

1. Autopilot guard (P3, P4): AUTOPILOT = true:
   • TECH_CONTEXT_CONTENT available → extract all values (language, frameworks, storage, platform, constraints) directly. Log: "Autopilot: Alignment answers derived from Technical Context Document"
   • TECH_CONTEXT_PENDING = true → default "No tech context document", log, set empty

• Skip all alignment questions → proceed to Pre-Research Validation

AUTOPILOT = false:

• TECH_CONTEXT_PENDING = true → include in same batch: "Do you have a technical context document?" Options: "No tech context document" (recommended) + free-form path. If path provided → validate, persist to .github/sddp-config.md, read content.
• TECH_CONTEXT_CONTENT available → pre-fill all Technical Context fields as defaults with source attribution. Present for confirmation, not open-ended Q&A: "Based on [TECH_CONTEXT_DOC]: Language=X, Storage=Y, Platform=Z. Confirm or override for this feature?"
• TECH_CONTEXT_CONTENT empty → ask tech stack, architecture trade-offs, critical constraints

2. Pre-Research Validation (lightweight — no delegation):
   • Verify spec.md has no unresolved [NEEDS CLARIFICATION] markers that block planning
   • Verify project-instructions.md exists and is readable
   • Violations → warn user, do not halt (full compliance check runs post-design in Step 5)

3. Phase 0 — Research

3.0 Research Reuse Gate

FEATURE_DIR/research.md exists:

• Read before launching new research
• Current: covers active tech choices, no material new unknowns → reuse
• Stale: critical tech decisions changed, unresolved clarifications unsupported, or user requests refresh → refresh
• Reuse current sections, refresh only missing/stale
• LIGHTWEIGHT = true → treat all existing as current, skip delegations; refresh only critical unknowns with zero coverage

research.md missing + LIGHTWEIGHT = true → minimal research: resolve only critical unknowns not covered by Technical Context Document.

3a. Resolve Clarifications

Per NEEDS CLARIFICATION in spec/plan: reuse existing findings or research the unknown. Consolidate in FEATURE_DIR/research.md.

3b. Research Best Practices

Report: "🔍 Researching tech stack best practices and architecture patterns..."

Delegate: Technical Researcher (.github/agents/_technical-researcher.md):

• Topics (by SPEC_TYPE, only uncovered/stale):
  • Product: domain architecture, UX-supporting architecture, implementation trade-offs
  • Technical: framework, migration, schema, integration, compatibility, validation patterns
  • Operational: IaC, deployment, CI/CD, observability, environment promotion, reliability patterns
• Context: Feature spec, tech stack from plan.md, TECH_CONTEXT_CONTENT (if available)
• Purpose: "Inform architectural decisions and tech stack configuration"
• File Paths: FEATURE_DIR/spec.md, FEATURE_DIR/plan.md, FEATURE_DIR/research.md (if exists), TECH_CONTEXT_DOC (if registered)

Coverage sufficient → skip delegation. TECH_CONTEXT_CONTENT covers 80%+ of tech decisions → skip Technical Researcher entirely, note "Baseline from Technical Context Document".

Merge into FEATURE_DIR/research.md (full rewrite). Follow plan-authoring skill research.md format: structured fields per topic, no prose paragraphs, max 2 sources/topic, ≤4KB.

Update plan.md Technical Context with resolved values. Populate ## Architecture Decisions table with decisions made during research (AD-001, AD-002...).

• TECH_CONTEXT_CONTENT available → use as baseline, overlay with user choices + research findings, reference source path.

3c. Determine Project Mode

Scan repository for existing source code (excluding specs/, node_modules/, build artifacts):

• Source files found → PROJECT_MODE = brownfield (or mixed if feature adds new top-level directories)
• No source files → PROJECT_MODE = greenfield
• Record in plan.md Technical Context Project Mode field.

3d. Determine Design Artifacts

Scan resolved spec.md and Technical Context to decide Phase 1 artifacts.

Branch by SPEC_TYPE:

• product → apply data/API signal heuristics
• technical/operational → data-model.md and contracts/ are opt-in only when spec explicitly includes Key Entities, interface deliverables, or requirement language clearly calling for persistent data/contracts

Implementation Signals shortcut: If spec.md contains an ## Implementation Signals section, use tagged signals directly:

• NEW-ENTITY or MIGRATION → GENERATE_DATA_MODEL = true
• NEW-API → GENERATE_CONTRACTS = true
• Other tags (NEW-UI, EXTERNAL-SERVICE, BREAKING-CHANGE, NEW-WORKER, NEW-CONFIG) → informational, used to guide architecture decisions in Phase 1
• If Implementation Signals section exists and has explicit tags → skip heuristic detection below, use signals as authoritative

Data signals (any match → generate data-model.md):

• Non-empty "Key Entities" section
• Terms: database, storage, persist, store, CRUD, model, schema, table, collection, record, entity
• Technical Context Storage ≠ N/A

API signals (any match → generate contracts/):

• Terms: API, endpoint, route, REST, GraphQL, HTTP, webhook, request/response, server, client-server, RPC
• Technical Context Project Type is web or mobile

No signals detected:

• SPEC_TYPE = technical/operational → silently default Neither, log
• Project Type = single (or not web/mobile) → silently default Neither, log
• Autopilot guard (P5): AUTOPILOT = true → silently default Neither, log
• Project Type = web/mobile + AUTOPILOT = false → ask: "Design Artifacts" / "No API surface or persistent data detected. Which?" → Data Model only / API Contracts only / Both / Neither (recommended)

Store as GENERATE_DATA_MODEL and GENERATE_CONTRACTS (true/false).

4. Phase 1 — Design Execution

4.1 Data Modeling (skip if GENERATE_DATA_MODEL = false)

• False → replace ## Data Model Summary table with N/A — no persistent data
• True → Delegate: Database Administrator (.github/agents/_database-administrator.md): SpecPath, ResearchPath, OutputPath: FEATURE_DIR/data-model.md → populate ## Data Model Summary table in plan.md

4.2 API Contracts (skip if GENERATE_CONTRACTS = false)

• False → replace ## API Surface Summary table with N/A — no API surface
• True → Delegate: API Designer (.github/agents/_api-designer.md): SpecPath, DataModelPath (if generated), OutputDir: FEATURE_DIR/contracts/ → populate ## API Surface Summary table in plan.md

4.3 High-Level Architecture

• Reuse Technical Context Document terminology/boundaries when available
• Populate ## Architecture Mermaid C4 diagram in plan.md:
  • Default to Container view; use Component view only if internals matter
  • Target 8-12 nodes, hard cap 15
  • Names 1-3 words; short type fields; descriptions optional, max 4 words
  • Relationship labels: short verbs only; omit obvious labels
  • Exclude helpers, shared libraries, and commodity infrastructure unless they define a key boundary
  • No class-level detail. Use <br> only; never \n
• Align with DataModel and Contracts outputs
• Add any remaining Architecture Decisions (AD-###) to the table
• For any decision that has project-wide architectural impact (not feature-local): delegate to the ADR Author subagent (.github/agents/_adr-author.md) with a fully resolved decision payload. The ADR Author creates a standalone MADR file under specs/adrs/ and returns the ADR ID and SAD catalog row. Reference the resulting ADR-NNNN from the plan instead of recording it as an AD row. After the ADR Author returns, update the specs/sad.md ADR catalog table with the returned row.

4.4 Source Code Structure

• Detect PROJECT_MODE from Step 3c.
• Greenfield: fill full layout based on Project Type (ref: plan-authoring SKILL.md Project Structure Options).
• Brownfield/Mixed: scan existing layout, show only new (+) and modified (~) paths. Include Brownfield Notes block.
• Strip all HTML comments, [REPLACE: ...], [REMOVE IF UNUSED] markers.

4.5 Testing Strategy & QC Tooling

• Read Language/Version and Primary Dependencies from plan.md Technical Context
• Scan repo root for existing tool configs (.golangci-lint.yml, eslint.config.*, pyproject.toml with [tool.ruff]/[tool.bandit], clippy.toml, biome.json, etc.)
• Delegate: Technical Researcher (.github/agents/_technical-researcher.md):
  • Topics: "Best QC tools for [Language/Version] [Dependencies]" — test runner, linter/static analysis, security scanner, coverage tool
  • Context: Language, framework, dependency manager, existing configs, project-instructions.md quality mandates
  • Purpose: "Recommend specific QC tools and install commands"
  • Return: tool name, install command, rationale per category
• Populate ## Testing Strategy table in plan.md: one row per tier (Unit, Integration, Security, Coverage) with Tool, Scope, Mock Boundary, Install columns. Existing config → Install = configured; N/A tier → include row with rationale.

4.5.1 Acceptance Test Stubs (P1)

• Read every requirement from spec.md and its priority. Collect the set of P1 requirement IDs (FR-###/TR-###/OR-###/RR-###).
• Empty set → replace ## Acceptance Test Stubs section body in plan.md with N/A — no P1 requirements and continue to 4.6.
• Otherwise → for each P1 requirement, populate one row in ## Acceptance Test Stubs:
  • Req ID = the P1 requirement ID.
  • Test File = a path following the ## Testing Strategy Unit tier convention (co-located or tests/ sibling). Use the Requirement Coverage Map File Path(s) for the same reqID to pick a co-located path.
  • Stub Blocks (framework-native) = the Unit tier tool's syntax with the reqID embedded in each block name (e.g. describe('FR-001 user registration') / it('rejects duplicate emails')).
  • RED Status = pending | failing-assertion | skip — pick the idiomatic pre-implementation failing state for the Unit tier tool.
• Follow .github/skills/plan-authoring/SKILL.md Acceptance Test Stubs rules. Stubs are acceptance targets, not unit-test mandates: behavior-level block names only, no implementation-pinning bodies.

4.6 Error Handling Strategy

• If feature has API endpoints, external service calls, or user-facing error states → populate ## Error Handling Strategy table
• Otherwise → replace table with N/A — [reason]

4.7 Integration Points

• If spec has Integration Points section → populate ## Integration Points table mapping each to technical approach
• Otherwise → remove section from plan

4.8 Risk Mitigation

• Read Assumptions & Risks from spec.md → populate ## Risk Mitigation table with concrete technical mitigations
• Every risk from spec must have a row

4.9 Requirement Coverage Map

• Read all requirement IDs (FR-###, TR-###, OR-###, RR-###) from spec.md
• Map each to the component(s), file path(s), and the exported function(s)/symbol(s) with key signature hints that will implement it
• Source the Function(s)/Symbol(s) column from data-model.md entities, contracts/ schemas, architecture decisions, or named API/service surfaces when no design artifact exists
• Populate ## Requirement Coverage Map table — every row must have non-empty File Path(s) AND Function(s)/Symbol(s) columns
• This matrix is the primary input for /sddp-tasks (which derives → exports: annotations from the symbol column) and for the Developer's per-task self-verification during /sddp-implement

4.10 Implementation Hints

• Populate ## Implementation Hints with max 5 tagged items: gotchas, order-sensitive operations, non-obvious constraints
• Format: - **[HINT-###]** Category: detail

5. Post-Design Gate

5.0 Plan Readiness Self-Check

Before compliance check, validate:

1. Every conditional section is either populated with a table OR replaced with N/A — [reason]
2. No [REPLACE: ...] or template placeholder markers remain
3. Mermaid diagram uses valid C4 syntax
4. Every requirement ID from spec.md appears in Requirement Coverage Map with non-empty File Path(s) AND Function(s)/Symbol(s) columns
5. Architecture Decisions table has at least one row (or N/A for trivial features)
6. ## Acceptance Test Stubs is either populated with one row per P1 requirement (Req ID matches a P1 req from spec.md, Test File follows the Unit tier convention, Stub Blocks embed the reqID, RED Status is one of pending/failing-assertion/skip) OR replaced with N/A — no P1 requirements. Every P1 requirement from spec.md MUST have a stub row when the section is populated.

Failures → fix inline before proceeding.

5.1 Compliance Check

Delegate: Policy Auditor (.github/agents/_policy-auditor.md):

• Task: "Validate completed FEATURE_DIR/plan.md against project instructions"
• Report pass/fail inline; FAIL → warn user

5.5 Generate Checklist Queue

1. Read MAX_CHECKLIST_COUNT from Context Report. 0 → skip entirely.
2. Analyze plan.md, spec.md, design artifacts for risk/domain signals:
   • Auth/secrets/input validation → Security
   • Data model/storage/migrations → Data Integrity
   • API/endpoints/HTTP → API Quality
   • UI/frontend/accessibility → UX
   • Latency/throughput/caching → Performance
   • Logging/monitoring/metrics → Observability
   • Test strategy/coverage/edge cases → Testing
3. Rank by signal strength, select top N = min(detected, MAX_CHECKLIST_COUNT)
4. Ensure FEATURE_DIR/checklists/ exists
5. Write FEATURE_DIR/checklists/.checklists:

   # Recommended Checklists
   > Auto-generated by /sddp-plan based on risk signals detected in the technical plan.
   
   - [ ] CHL001 Security
   - [ ] CHL002 API Quality
   - [ ] CHL003 Performance
   

   (CHL### IDs, 3-digit zero-padded, sequential. Domain name = /sddp-checklist argument.)
6. .checklists exists:
   • Autopilot guard (P6): AUTOPILOT = true → Overwrite, log
   • AUTOPILOT = false → ask overwrite or keep

5.6 Amend Technical Context Document

Update registered Technical Context document before final reporting.

5.6.1 Preconditions

• HAS_TECH_CONTEXT_DOC = false → skip
• true → read TECH_CONTEXT_DOC (unreadable → warn, continue; non-blocking)

5.6.2 Content Scope (Strict)

Promote only reusable project-level context from planning artifacts (plan.md, research.md, optional data-model.md, contracts/):

• Stable technology baseline decisions
• Cross-cutting architectural constraints/standards
• Reusable integration patterns and system boundaries
• Shared operational expectations (deployment env, observability, security posture)

Do NOT include: feature-specific endpoints/payloads/schema, feature-only component logic, one-off implementation notes.

5.6.3 Merge Strategy (Managed Section Full Rewrite)

1. Maintain ## Project Context Baseline Updates section
2. Parse + normalize existing entries
3. Merge with new reusable technical context
4. De-duplicate semantically
5. Full rewrite of managed section; preserve all other content
6. Section missing → create at end
7. Preserve every narrative architecture section and Mermaid C4 diagram outside managed section verbatim

5.6.4 Failure Handling

• Best-effort, non-blocking. Surface failures as warnings in final report.

6. Report

Output:

• Branch name and plan file path
• Generated artifacts list
• Instructions check status
• Acceptance Test Stubs summary: P1 requirement count and stub rows generated (or N/A — no P1 requirements)
• Checklist queue summary (if generated): domain count + .checklists path
• Shared document amendment summary (updated/skipped/warnings)
• Suggested next steps with context-specific prompts:
  1. /sddp-checklist (optional — for safety-critical/compliance features; repeatable for queued domains)
  2. /sddp-tasks (required)