specify-meta
npx machina-cli add skill rsmdt/the-startup/specify-meta --openclawPersona
Act as a specification workflow orchestrator that manages specification directories and tracks user decisions throughout the PRD → SDD → PLAN workflow.
Interface
SpecStatus { id: string // 3-digit zero-padded (001, 002, ...) name: string directory: string // .start/specs/[NNN]-[name]/ (legacy: docs/specs/) phase: Initialization | PRD | SDD | PLAN | Ready documents: { name: string status: pending | in_progress | completed | skipped notes?: string }[] }
State { specId = "" currentPhase: Initialization | PRD | SDD | PLAN | Ready documents: [] }
Constraints
Always:
- Use spec.py (co-located with this SKILL.md) for all directory operations.
- Create README.md from template.md when scaffolding new specs.
- Log all significant decisions with date, decision, and rationale.
- Confirm next steps with user before phase transitions.
Never:
- Create spec directories manually — always use spec.py.
- Transition phases without updating README.md.
- Skip decision logging when user makes workflow choices.
Reference Materials
- Spec Management — Spec ID format, directory structure, script commands, phase workflow, decision logging, legacy fallback
- README Template — Template for spec README.md files
Workflow
1. Scaffold
Create a new spec with an auto-incrementing ID.
- Run
Bash("spec.py \"$featureName\""). - Create README.md from template.md.
- Report the created spec status.
2. Read Status
Read existing spec metadata.
- Run
Bash("spec.py \"$specId\" --read"). - Parse TOML output into SpecStatus.
- Suggest the next continuation point:
match (documents) { plan exists => "PLAN found. Proceed to implementation?" sdd exists, no plan => "SDD found. Continue to PLAN?" prd exists, no sdd => "PRD found. Continue to SDD?" no documents => "Start from PRD?" }
3. Transition Phase
Update the spec directory to reflect the new phase.
- Update README.md document status and current phase.
- Log the phase transition in the decisions table.
- Hand off to the document-specific skill:
match (phase) { PRD => specify-requirements skill SDD => specify-solution skill PLAN => specify-plan skill }
- On completion, return here for the next phase transition.
4. Log Decision
Append a row to the README.md Decisions Log table. Update the Last Updated field.
Entry Point
match ($ARGUMENTS) { featureName (new) => execute step 1 (Scaffold) specId (existing) => execute steps 2, 3, and 4 in order }
Source
git clone https://github.com/rsmdt/the-startup/blob/main/plugins/start/skills/specify-meta/SKILL.mdView on GitHub Overview
specify-meta orchestrates spec directories and tracks decisions across the PRD–SDD–PLAN workflow. It auto-increments IDs, creates and updates README.md, and logs key decisions during phase transitions. It uses .start/specs/ and falls back to docs/specs/ for legacy specs and is used by both specify and implement workflows.
How This Skill Works
Technically, it relies on the co-located spec.py for all directory operations, executed via Bash commands to scaffold, read, and update specs. It defines a SpecStatus shape (id, name, directory, phase, documents) and a State to track current progress, enforcing confirmation before phase changes and ensuring decisions are recorded in the README decisions log.
When to Use It
- Create a new spec and obtain an auto-incremented ID in the correct directory (.start/specs).
- Read status of an existing spec (specId) to understand which documents exist and what phase is next.
- Transition to the next phase (PRD → SDD → PLAN) after user confirmation and README updates.
- Log a significant decision or rationale in the spec's Decisions Log table.
- Handle legacy specs by falling back to docs/specs/ when scaffolding or reading metadata.
Quick Start
- Step 1: Bash("spec.py \"<featureName>\"") to scaffold a new spec with an auto-incremented ID.
- Step 2: Create README.md from template.md and report the new spec status.
- Step 3: For an existing spec, Bash("spec.py \"<specId>\" --read") to inspect status and plan the next transition after confirmation.
Best Practices
- Always use spec.py for all directory operations; never create dirs manually.
- Create README.md from template.md when scaffolding a new spec.
- Log all significant decisions with date, decision, and rationale.
- Confirm next steps with the user before any phase transition.
- Check for legacy specs and fall back to docs/specs/ as needed.
Example Use Cases
- Scaffold a new feature spec, receiving an auto-incremented ID like 003 and a ready README.md.
- Run a status read for spec 003, discovering PRD and plan the next step to SDD.
- Transition from PRD to SDD after user confirmation, updating README and logging the decision.
- Append a decision entry such as "Result: PRD completed; proceed to SDD" in the Decisions Log.
- Open an older spec confined to docs/specs/ due to legacy workflow, before migrating.
