Create Plan

Output contract

Return a concise status report using this exact section structure:

1. Plan path: absolute path to plan.md
2. Artifacts generated: bullet list of generated files/directories
3. Gate results: pass/fail with brief reasons
4. Open risks: unresolved items, if any
5. Next command: /create-tasks or a blocking remediation step

Phases

Phase 0: Outline & Research

1. Extract unknowns from Technical Context

   • For each NEEDS CLARIFICATION item, create one research task.
   • For each major dependency choice, create one best-practice check.
   • For each integration, create one implementation pattern check.

2. Generate and dispatch research agents (or equivalent direct research):

   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]

4. Close the loop back to plan.md

   • Update Technical Context in plan.md so resolved unknowns are no longer marked unclear.

Output: research.md with all important unknowns resolved

Phase 1: Design & Contracts

Prerequisites: research.md complete

1. Extract entities from spec_file → data-model.md:

   • Entity name, fields, relationships
   • Validation rules from requirements
   • State transitions if applicable

2. Define interface contracts (if project has external interfaces) → /contracts/:

   • Identify what interfaces the project exposes to users or other systems
   • Document the contract format appropriate for the project type
   • Examples: public APIs for libraries, command schemas for CLI tools, endpoints for web services, grammars for parsers, UI contracts for applications
   • Skip if project is purely internal (build scripts, one-off tools, etc.)

3. Agent context update:

   • Add only new technology from current plan using the agents-md-refactor skill
   • Preserve manual additions between markers

4. Consistency check:

   • quickstart.md steps must align with contracts and data model.
   • Any notable constraint in research.md must appear in plan/design artifacts.

Output: data-model.md, optional contracts/*, quickstart.md, updated agent context

Key rules

• Use absolute paths in reports and when writing output locations.
• Return ERROR on gate failures that are not justified.
• Do not invent repository structure; read existing paths and align with current layout.
• Prefer explicit trade-offs over vague recommendations.
• Keep artifacts implementation-oriented; avoid abstract prose with no engineering actionability.