specify-meta — Claude Code skill for spec workflows
specify-meta is a Claude Code skill that creates specification folders and tracks requirements, solution, and plan stages. It records approvals and decisions for a task.
MIT ★ 587 updated 2026-10-26
/plugin marketplace add rsmdt/the-startup
/plugin install start@the-startupWhat specify-meta does
For a new feature, specify-meta creates a numbered spec directory, fills in spec.md from a template, and adds .tracker/. For an existing spec, it reads the current state and points to the next stage based on completed approvals. The document defines the intended outcome; implementation happens separately through /implement.
Each stage has its own approval gate. Gate values live in spec.md frontmatter, while decisions and assumptions go in the Ledger. The skill records changes in an event log, which the progress dashboard uses. Directory work runs through node ${CLAUDE_PLUGIN_ROOT}/scripts/spec.js.
The user confirms before a phase transition. Older specs without spec.md continue in their legacy files: README.md, requirements.md, solution.md, and plan.md. That distinction matters when reopening an existing specification.
What it helps with
- scaffold a spec directory with an assigned ID
- check a spec's status and find its next stage
- record a decision with its rationale
- advance a spec after the user confirms the transition
Example prompts for the agent
- Create a specification for the new CSV import feature.
- Read spec
003and suggest where work should continue. - Record the decision to process imports through a job queue.
How to install specify-meta
1Plugin marketplace
/plugin marketplace add rsmdt/the-startup/plugin install start@the-startupThis installs the whole start plugin with all its skills
2Skills CLI (Vercel)
npx skills add rsmdt/the-startup --skill specify-meta -a claude-code3Manually: put the files in place
~/.claude/skills/specify-meta/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/specify-meta/
1Skills CLI (Vercel)
npx skills add rsmdt/the-startup --skill specify-meta -a codex2Manually: put the files in place
.agents/skills/specify-meta/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add rsmdt/the-startup --skill specify-meta -a cursor2Manually: put the files in place
.cursor/skills/specify-meta/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install rsmdt/the-startup plugins/start/skills/specify-meta2Manually: put the files in place
.github/skills/specify-meta/SKILL.md1Skills CLI (Vercel)
npx skills add rsmdt/the-startup --skill specify-meta -a gemini-cli2Platform CLI
gemini skills install https://github.com/rsmdt/the-startup --path plugins/start/skills/specify-metaManually: put the files in place
.devin/skills/specify-meta/SKILL.mdThe legacy .windsurf/skills/ path still works
Claude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
Step by step, with commands for each platform: How to install skills in Claude Code: five ways
Questions about specify-meta
How do I install specify-meta in Claude Code?
Add the marketplace with /plugin marketplace add rsmdt/the-startup, then install the plugin with /plugin install start@the-startup.
What does specify-meta do?
It scaffolds specification folders, tracks approval gates, and records workflow decisions. It uses node ${CLAUDE_PLUGIN_ROOT}/scripts/spec.js for directory operations.
Where does specify-meta store phase status?
Gate values are kept in the frontmatter of spec.md, and changes are written to the event log. The skill asks the user to confirm before moving to another phase.
Source text
SKILL.md · MIT
---
name: specify-meta
user-invocable: false
description: Scaffold, status-check, and manage specification directories. Use when creating a new spec, reading spec status, transitioning between phases, or logging decisions on a spec in .start/specs/.
---
## Persona
Act as a specification workflow orchestrator that manages specification directories and tracks user decisions throughout the Requirements (WHY) → Solution (WHAT — design) → Plan (slice and scenario tasks) workflow. Every phase writes its own part of one document, `spec.md`, closed by its own approval gate; the Plan phase also creates the phase, slice, and scenario tasks in the spec's tracker. The specification describes the target state; /implement builds it by running those slice tasks.
## Interface
SpecStatus {
id: string // 3-digit zero-padded (001, 002, ...)
name: string
directory: string // .start/specs/[NNN]-[name]/
phase: Initialization | Requirements | Solution | Plan | Ready
gates: {
requirements: pending | draft | approved | skipped
solution: pending | draft | approved | skipped
plan: pending | draft | approved | skipped
}
}
State {
specId = ""
currentPhase: Initialization | Requirements | Solution | Plan | Ready
gates: {}
}
## Constraints
**Always:**
- Use `node ${CLAUDE_PLUGIN_ROOT}/scripts/spec.js` for all directory operations.
- Keep phase state in the `gates` frontmatter of `spec.md` and the decisions and assumptions in its `## Ledger` part — `spec.md` has no README beside it.
- Log all significant decisions with date, decision, and rationale.
- Keep the Assumptions table current — status changes (Proposed → Confirmed/Corrected/Standing) are updates to it, made when the specify skill reports them.
- Record every gate change, decision, open question, and assumption status change in the spec's event log as you make it: `node ${CLAUDE_PLUGIN_ROOT}/scripts/spec.js {specId} --event '<json>'` (event kinds in reference/spec-management.md). The progress dashboard reads only this log.
- A spec with no `spec.md` uses the legacy layout (`README.md`, `requirements.md`, `solution.md`, `plan.md`): read and continue it in those files.
- Confirm next steps with user before phase transitions.
**Never:**
- Transition phases without updating the `gates` frontmatter.
- Skip decision logging when user makes workflow choices.
## Reference Materials
- [Spec Management](reference/spec-management.md) — Spec ID format, directory structure, script commands, phase workflow, decision logging
- [Spec Template](template.md) — `spec.md`: the Requirements, Solution, and Plan parts plus the Ledger
## Workflow
### 1. Scaffold
Create a new spec with an auto-incrementing ID.
1. Run `node ${CLAUDE_PLUGIN_ROOT}/scripts/spec.js "$featureName"` in the terminal. It creates the spec directory, `spec.md` from template.md, and `.tracker/`.
2. Report the created spec status.
### 2. Read Status
Read existing spec metadata.
1. Run `node ${CLAUDE_PLUGIN_ROOT}/scripts/spec.js "$specId" --read` in the terminal.
2. Parse TOML output into SpecStatus.
3. Read the `gates` frontmatter of `spec.md` and suggest the next continuation point:
match (gates) {
plan approved => "Plan approved. Proceed to implementation with /implement?"
solution approved, plan not => "Solution approved. Continue to Plan (phases, slice and scenario tasks)?"
requirements approved, solution not => "Requirements approved. Continue to Solution?"
nothing approved => "Start from Requirements?"
}
4. If the spec directory has no `events.jsonl`, run `node ${CLAUDE_PLUGIN_ROOT}/scripts/spec.js "$specId" --snapshot` once to start its event log from the current state.
### 3. Transition Phase
Update the spec directory to reflect the new phase.
1. Set the finished part's gate to `approved` (or `skipped`) and the next part's gate to `draft`, and record both as `gate` events.
2. Log the phase transition in the Decision log.
3. Hand off to the document-specific skill:
match (phase) {
Requirements => specify-requirements skill
Solution => specify-solution skill
Plan => specify-plan skill (writes the Plan part + tracker tasks)
}
4. On completion, return here for the next phase transition.
### 4. Log Decision
Append a row to the Decision log table in the Ledger part of `spec.md`.
### Entry Point
match ($ARGUMENTS) {
featureName (new) => execute step 1 (Scaffold)
specId (existing) => execute steps 2, 3, and 4 in order
}
© Rudolf S. · MIT · rsmdt/the-startup