Skip to main content
skill CX Codex

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

Install into Claude Code · Plugin marketplace All methods and platforms ↓
/plugin marketplace add rsmdt/the-startup
/plugin install start@the-startup
Open on GitHub

What 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 003 and 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-startup

This installs the whole start plugin with all its skills

2Skills CLI (Vercel)

npx skills add rsmdt/the-startup --skill specify-meta -a claude-code

3Manually: put the files in place

~/.claude/skills/specify-meta/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/specify-meta/

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

Similar skills

All skills for Agent setup: memory, context, orchestration →

From the same set50

The whole set →
document Coordinates parallel documentation generation for source code, APIs, and project architecture. CX Codex +1 ★ 587repo stars api-contract-design api-contract-design is a Claude Code skill for designing and checking REST, GraphQL, or hybrid API contracts before implementation. CX Codex +1 ★ 587repo stars review-robustness review-robustness flags fragile code before merge: abstraction layers nothing needs yet, and shared state handled carelessly in async flows. Useful on PR review and for bugs that surface only under load. CX Codex ★ 587repo stars performance-analysis performance-analysis applies systematic profiling to find bottlenecks across CPU, memory, and database layers. It enforces measuring baselines before proposing optimizations. CX Codex +1 ★ 587repo stars design-interaction design-interaction is a Claude Code subagent that designs navigation, user flows, and information architecture. Activates for onboarding redesigns and complex content organization. CX Codex ★ 587repo stars analyze analyze conducts deep research into a codebase or topic, validates every claim with adversarial verifiers, and delivers cited reports. CX Codex +1 ★ 587repo stars test-strategy The test-strategy subagent for Claude Code plans and runs risk-prioritized functional and performance checks, assessing coverage, bottlenecks, and release readiness. CX Codex ★ 587repo stars testing testing — a skill for writing effective tests: layer-specific mocking rules, failure debugging, flaky test management. CX Codex +1 ★ 587repo stars

Project sponsors

Companies that keep this analytics open