Spec Generation

Generate structured specification files for Choo Choo Ralph.

IMPORTANT: NEVER add <?xml version="1.0"...?> to spec files. These are markdown files, NOT XML files. Start directly with <project_specification>.

Critical Format Rules

1. YAML frontmatter required - Every spec starts with --- frontmatter block
2. NO XML DECLARATION - NEVER include <?xml ...?> - this breaks the spec
3. File is markdown with XML-like tags - Not a true XML file
4. Empty review tags - Use <review></review> not self-closing
5. After frontmatter - First XML line must be <project_specification>

YAML Frontmatter

Every spec file MUST start with YAML frontmatter:

---
title: "Project or Feature Name"
created: 2026-01-11
poured: []
iteration: 1
auto_discovery: false
auto_learnings: false
---

Fields:

• title: Human-readable name for the spec (matches <project_name>)
• created: Date created (use date +%Y-%m-%d bash command for accuracy)
• poured: Array of root bead IDs created when /pour runs (starts empty)
• iteration: Refinement count (1 = initial, increments on each /spec refinement)
• auto_discovery: (optional, default: false) Enable auto task creation from discovered gaps during implementation
• auto_learnings: (optional, default: false) Enable auto skill creation from learnings captured during implementation

Core Principles

1. Flexible scale: Same format works for one feature or entire applications
2. Human-reviewable: Easy to read and edit in any text editor
3. Machine-parseable: Clear structure for automated processing

Spec Format

The spec uses YAML frontmatter followed by XML-like tags in markdown for clarity and editability.

---
title: "Project or Feature Name"
created: 2026-01-11
poured: []
iteration: 1
auto_discovery: false
auto_learnings: false
---
<project_specification>
<project_name>Project or Feature Name</project_name>

  <overview>
    Brief description of what we're building.
    Context and goals.
  </overview>

  <!-- Context from codebase/tech research (populated by /spec command) -->
  <context>
    <existing_patterns>
      - Patterns found in the existing codebase to follow
      - e.g., "Authentication follows pattern in src/auth/"
    </existing_patterns>
    <integration_points>
      - Files/services this feature will integrate with
      - e.g., "Extends UserService in src/services/user.ts"
    </integration_points>
    <new_technologies>
      - Research notes for technologies not in codebase
      - e.g., "Stripe: Use stripe-node SDK, webhook verification required"
    </new_technologies>
    <conventions>
      - Coding conventions discovered in codebase
      - e.g., "Tests colocated with source files (*.test.ts)"
    </conventions>
  </context>

  <!-- Optional: For greenfield projects -->

<technology_stack>
<frontend>React, Tailwind</frontend>
<backend>Node.js, SQLite</backend>
</technology_stack>

  <!-- Core content: Tasks to implement -->
  <tasks>
    <task id="task-1" priority="1" category="infrastructure">
      <title>Setup Project Foundation</title>
      <description>
        Initialize the project structure with required dependencies.
      </description>
      <steps>
        - Create directory structure
        - Initialize package.json
        - Install core dependencies
        - Set up build configuration
      </steps>
      <test_steps>
        1. Run `npm install` or `bun install` - verify no errors
        2. Run build command - verify successful build
        3. Run dev server - verify it starts without errors
      </test_steps>
      <review>
        <!-- User comments here -->
      </review>
    </task>

    <task id="task-2" priority="2" category="functional">
      <title>Implement Core Feature</title>
      <description>
        Build the main functionality.
      </description>
      <steps>
        - Create component structure
        - Implement business logic
        - Add error handling
        - Write tests
      </steps>
      <test_steps>
        1. Navigate to the feature location
        2. Perform the main user action
        3. Verify expected behavior occurs
        4. Check for console errors
        5. Test edge cases
      </test_steps>
      <review></review>
    </task>

  </tasks>

  <!-- Optional: Success criteria -->

<success_criteria> - Feature works as described - Tests pass - No regressions
</success_criteria>
</project_specification>

Scaling the Format

Simple Feature (1-3 tasks)

---
title: "Dark Mode Toggle"
created: 2026-01-11
poured: []
iteration: 1
auto_discovery: false
auto_learnings: false
---
<project_specification>
  <project_name>Dark Mode Toggle</project_name>
  <overview>Add dark mode to settings page.</overview>
  <tasks>
    <task id="dark-mode" priority="2" category="functional">
      <title>Implement Dark Mode Toggle</title>
      <description>Add toggle, persist to localStorage, apply theme.</description>
      <steps>
        - Add toggle to settings
        - Create theme context
        - Persist preference
        - Update CSS variables
      </steps>
      <test_steps>
        1. Navigate to settings page
        2. Click the dark mode toggle
        3. Verify theme changes to dark
        4. Refresh the page
        5. Verify dark mode preference persisted
      </test_steps>
      <review></review>
    </task>
  </tasks>
</project_specification>

Full Application (30+ tasks)

Include technology_stack, database_schema, api_endpoints, implementation_steps sections. See references/anthropic-spec-format.md for complete example.

Task State

Task state is determined by the <review> tag:

State	How to identify	Action
Needs refinement	<review> tag has content	Run /spec again to process feedback
Ready to pour	<review> tag is empty	Can be poured into beads
Rejected	Task deleted from spec	N/A

This keeps the workflow simple:

• Add feedback in <review> tags → run /spec to refine
• Clear <review> tags (or leave empty) → ready for /pour
• Delete tasks you don't want
• After pouring, spec is archived

Priority Levels

Priority	Meaning
0	Critical - do first
1	High
2	Medium (default)
3	Low
4	Backlog

Category Types

Category	Description
functional	Core features, business logic
style	Visual polish, animations, UI tweaks
infrastructure	Build, deploy, tooling, project setup
documentation	README, comments, docs

Categories help prioritize work - functional tasks typically come before style tasks.

Test Steps (Integration Guidance)

The <test_steps> section in the spec provides integration-level test guidance for the feature as a whole. These are high-level verification steps that test the complete user flow.

Important: When the spec is poured into beads, the pour process generates granular test steps for each individual bead. The spec-level test steps guide the overall integration testing, while bead-level test steps verify the specific implementation.

Example flow:

• Spec task: "User Authentication" with test steps for complete login flow
• Poured beads: "Create login form", "Add validation", "Implement API endpoint" - each with their own granular test steps

Granularity Guidelines

When --target-tasks is specified:

• Each task should be independently verifiable
• Tasks can have dependencies (expressed via order or explicit deps)
• Better to have more granular tasks than fewer large ones

Context Section

The <context> section is populated by the /spec command using sub-agents that research the codebase and technologies before generating the spec. This ensures tasks are informed by the actual codebase.

Section	Purpose	Example
existing_patterns	Code patterns to follow	"Components use shadcn/ui conventions"
integration_points	Files/services to integrate with	"Extends UserService in src/services/user.ts"
new_technologies	Research notes for new tech	"Stripe: Use webhook verification for security"
conventions	Naming, testing, style conventions	"Tests colocated with source (*.test.ts)"

For greenfield projects: Context section may be minimal or empty, but should still include technology research if using unfamiliar tech.

For existing codebases: Context section should be thorough - tasks reference patterns and integration points to ensure consistency.

Additional Resources

See references/anthropic-spec-format.md for the full specification format based on Anthropic's autonomous coding research.