ss-tools/.agent/workflows/speckit.plan.md

description, handoffs

description	handoffs
Execute the implementation planning workflow using the plan template to generate design artifacts.	label agent prompt send Create Tasks speckit.tasks Break the plan into tasks true label agent prompt Create Checklist speckit.checklist Create a checklist for the following domain...

User Input

$ARGUMENTS

You MUST consider the user input before proceeding (if not empty).

Outline

1. Setup: Run .specify/scripts/bash/setup-plan.sh --json from repo root and parse JSON for FEATURE_SPEC, IMPL_PLAN, SPECS_DIR, BRANCH. For single quotes in args like "I'm Groot", use escape syntax: e.g 'I'''m Groot' (or double-quote if possible: "I'm Groot").

2. Load context: Read .ai/ROOT.md and .ai/PROJECT_MAP.md to understand the project structure and navigation. Then read required standards: .ai/standards/constitution.md and .ai/standards/semantics.md. Load IMPL_PLAN template.

3. Execute plan workflow: Follow the structure in IMPL_PLAN template to:

   • Fill Technical Context (mark unknowns as "NEEDS CLARIFICATION")
   • Fill Constitution Check section from constitution
   • Evaluate gates (ERROR if violations unjustified)
   • Phase 0: Generate research.md (resolve all NEEDS CLARIFICATION)
   • Phase 1: Generate data-model.md, contracts/, quickstart.md
   • Phase 1: Update agent context by running the agent script
   • Re-evaluate Constitution Check post-design

4. Stop and report: Command ends after Phase 2 planning. Report branch, IMPL_PLAN path, and generated artifacts.

Phases

Phase 0: Outline & Research

1. Extract unknowns from Technical Context above:

   • For each NEEDS CLARIFICATION → research task
   • For each dependency → best practices task
   • For each integration → patterns task

2. Generate and dispatch research agents:

   For each unknown in Technical Context:
     Task: "Research {unknown} for {feature context}"
   For each technology choice:
     Task: "Find best practices for {tech} in {domain}"
   

3. Consolidate findings in research.md using format:

   • Decision: [what was chosen]
   • Rationale: [why chosen]
   • Alternatives considered: [what else evaluated]

Output: research.md with all NEEDS CLARIFICATION resolved

Phase 1: Design & Contracts

Prerequisites: research.md complete

0. Validate Design against UX Reference:

   • Check if the proposed architecture supports the latency, interactivity, and flow defined in ux_reference.md.
   • Linkage: Ensure key UI states from ux_reference.md map to Component Contracts (@UX_STATE).
   • CRITICAL: If the technical plan compromises the UX (e.g. "We can't do real-time validation"), you MUST STOP and warn the user.

1. Extract entities from feature spec → data-model.md:

   • Entity name, fields, relationships, validation rules.

2. Design & Verify Contracts (Semantic Protocol):

   • Drafting: Define [DEF:id:Type] Headers, Contracts, and closing [/DEF:id:Type] for all new modules based on .ai/standards/semantics.md.
   • TIER Classification: Explicitly assign @TIER: [CRITICAL|STANDARD|TRIVIAL] to each module.
   • CRITICAL Requirements: For all CRITICAL modules, define full @PRE, @POST, and (if UI) @UX_STATE contracts. MUST also define testing contracts: @TEST_CONTRACT, @TEST_FIXTURE, @TEST_EDGE, and @TEST_INVARIANT.
   • Self-Review:
     • Completeness: Do @PRE/@POST cover edge cases identified in Research? Are test contracts present for CRITICAL?
     • Connectivity: Do @RELATION tags form a coherent graph?
     • Compliance: Does syntax match [DEF:id:Type] exactly and is it closed with [/DEF:id:Type]?
   • Output: Write verified contracts to contracts/modules.md.

3. Simulate Contract Usage:

   • Trace one key user scenario through the defined contracts to ensure data flow continuity.
   • If a contract interface mismatch is found, fix it immediately.

4. Generate API contracts:

   • Output OpenAPI/GraphQL schema to /contracts/ for backend-frontend sync.

5. Agent context update:

   • Run .specify/scripts/bash/update-agent-context.sh agy
   • These scripts detect which AI agent is in use
   • Update the appropriate agent-specific context file
   • Add only new technology from current plan
   • Preserve manual additions between markers

Output: data-model.md, /contracts/*, quickstart.md, agent-specific file

Key rules

• Use absolute paths
• ERROR on gate failures or unresolved clarifications