autospec-plan

name	autospec-plan
description	Generate YAML implementation plan from feature specification.

autospec-plan

This Agent Skill is generated from autospec.plan. When the user invokes "$autospec-plan" or "/autospec.plan", load and follow these instructions directly. Treat the text after the skill or command name as "$ARGUMENTS". Do not route back through "autospec plan"; this skill is the prompt for the stage.

Project specs directory: ./specs

User Input

$ARGUMENTS

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

Pre-computed Context

The following paths have been pre-computed and are available for use:

• FEATURE_DIR: {{.FeatureDir}}
• FEATURE_SPEC: {{.FeatureSpec}}
• AUTOSPEC_VERSION: {{.AutospecVersion}}
• CREATED_DATE: {{.CreatedDate}}

Outline

1. Load context:

   • Read the spec file at {{.FeatureSpec}}
   • Read project constitution if exists (.autospec/constitution.yaml or AGENTS.md, falling back to agent-specific file like CLAUDE.md)
   • Extract: feature description, user stories, requirements, constraints

2. Execute plan workflow:

   Phase 0: Outline & Research

   a. Identify technical unknowns from the spec:

   • For each unclear technology choice → research task
   • For each dependency → best practices research
   • For each integration → patterns research

   b. Resolve unknowns through exploration:

   • Examine existing codebase patterns
   • Consider project constraints
   • Make informed technology decisions

   c. Document research findings for inclusion in plan

   Phase 1: Design & Architecture

   a. Define technical context based on spec and research:

   • Language/framework (detect from existing code or choose)
   • Primary dependencies
   • Storage requirements
   • Testing approach
   • Target platform

   b. Design project structure:

   • Documentation files to create
   • Source code organization
   • Test file locations

   c. Identify data model entities from spec requirements

   d. Design API contracts if applicable

3. Generate plan.yaml: Create the YAML plan file with this structure:

   plan:
     branch: "<current git branch>"
     created: "<today's date YYYY-MM-DD>"
     spec_path: "<relative path to spec file>"
   
   summary: |
     <1-2 paragraph summary of the implementation approach.
     Explain key technical decisions and how they address the spec requirements.>
   
   technical_context:
     language: "<primary language>"
     framework: "<framework if applicable, or 'None'>"
     primary_dependencies:
       - name: "<dependency name>"
         version: "<version constraint>"
         purpose: "<why needed>"
     storage: "<storage technology or 'None'>"
     testing:
       framework: "<test framework>"
       approach: "<unit/integration/e2e strategy>"
     target_platform: "<platform(s)>"
     project_type: "<cli|web|mobile|library|service>"
     performance_goals: "<specific targets from spec>"
     constraints:
       - "<constraint from spec or technical>"
     scale_scope: "<expected scale/scope>"
   
   constitution_check:
     constitution_path: "<path to constitution file or 'Not found'>"
     gates:
       - name: "<principle name from constitution>"
         status: "PASS"  # or "FAIL" or "N/A"
         notes: "<how this plan addresses the principle>"
   
   research_findings:
     decisions:
       - topic: "<what was researched>"
         decision: "<what was chosen>"
         rationale: "<why chosen>"
         alternatives_considered:
           - "<alternative 1>"
           - "<alternative 2>"
   
   data_model:
     entities:
       - name: "<entity name>"
         description: "<what it represents>"
         fields:
           - name: "<field name>"
             type: "<data type>"
             description: "<purpose>"
             constraints: "<validation rules>"
         relationships:
           - target: "<related entity>"
             type: "<one-to-many|many-to-many|etc>"
             description: "<relationship meaning>"
   
   api_contracts:
     endpoints:
       - method: "<HTTP method>"
         path: "<endpoint path>"
         description: "<what it does>"
         request:
           content_type: "<content type>"
           body_schema: "<inline schema or reference>"
         response:
           success_code: 200
           body_schema: "<inline schema or reference>"
         errors:
           - code: 400
             description: "<when this occurs>"
   
   project_structure:
     documentation:
       - path: "<relative path>"
         description: "<purpose of this file>"
     source_code:
       - path: "<relative path or pattern>"
         description: "<what this contains>"
     tests:
       - path: "<relative path or pattern>"
         description: "<what tests live here>"
   
   implementation_phases:
     - phase: 1
       name: "<phase name>"
       goal: "<what this phase accomplishes>"
       deliverables:
         - "<deliverable 1>"
         - "<deliverable 2>"
     - phase: 2
       name: "<phase name>"
       goal: "<what this phase accomplishes>"
       dependencies:
         - "Phase 1"
       deliverables:
         - "<deliverable>"
   
   open_questions:
     - question: "<unresolved question>"
       context: "<why it matters>"
       proposed_resolution: "<suggested approach>"
   
   _meta:
     version: "1.0.0"
     generator: "autospec"
     generator_version: "{{.AutospecVersion}}"
     created: "{{.CreatedDate}}"
     artifact_type: "plan"
   

4. Write the plan to {{.FeatureDir}}/plan.yaml

5. Validate the artifact:

   autospec artifact {{.FeatureDir}}/plan.yaml
   

   • If validation fails: fix schema errors (missing required fields, invalid types) and retry
   • If validation passes: proceed to report

6. Report: Output:

   • Branch name
   • Full path to plan.yaml
   • Summary of technical context
   • Number of implementation phases
   • Any constitution gate failures (CRITICAL if any FAIL)
   • Readiness for $autospec-tasks

Key Rules

• Output MUST be valid YAML (use autospec artifact {{.FeatureDir}}/plan.yaml to verify schema compliance)
• Technical context should reflect actual project setup (detect from existing code)
• Constitution gates are mandatory if constitution exists
• Research findings should document all significant technical decisions
• Data model should be derived from spec requirements
• Project structure should follow existing codebase conventions
• All YAML arrays use list syntax (not JSON inline)
• Multi-line strings use | or > block scalar style