Generates structured spec files for Choo Choo Ralph with YAML frontmatter and XML-like markdown tags. Use for /choo-choo-ralph:spec commands or task breakdowns.
From choo-choo-ralphnpx claudepluginhub mj-meyer/choo-choo-ralphThis skill uses the workspace's default tool permissions.
references/anthropic-spec-format.mdSearches, retrieves, and installs Agent Skills from prompts.chat registry using MCP tools like search_skills and get_skill. Activates for finding skills, browsing catalogs, or extending Claude.
Searches prompts.chat for AI prompt templates by keyword or category, retrieves by ID with variable handling, and improves prompts via AI. Use for discovering or enhancing prompts.
Compares coding agents like Claude Code and Aider on custom YAML-defined codebase tasks using git worktrees, measuring pass rate, cost, time, and consistency.
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>.
--- frontmatter block<?xml ...?> - this breaks the spec<review></review> not self-closing<project_specification>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:
<project_name>)date +%Y-%m-%d bash command for accuracy)/pour runs (starts empty)/spec refinement)false) Enable auto task creation from discovered gaps during implementationfalse) Enable auto skill creation from learnings captured during implementationThe 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>
---
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>
Include technology_stack, database_schema, api_endpoints, implementation_steps sections.
See references/anthropic-spec-format.md for complete example.
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:
<review> tags → run /spec to refine<review> tags (or leave empty) → ready for /pour| Priority | Meaning |
|---|---|
| 0 | Critical - do first |
| 1 | High |
| 2 | Medium (default) |
| 3 | Low |
| 4 | Backlog |
| 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.
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:
When --target-tasks is specified:
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.
See references/anthropic-spec-format.md for the full specification format based on Anthropic's autonomous coding research.