Specture System

Specture is a spec-driven development system. Specs are design documents in the specs/ directory that describe planned changes — features, refactors, redesigns, tooling improvements. Each spec contains the design rationale, decisions, and an implementation task list.

Spec numbers are stored in the YAML frontmatter number field. New specs use slug-only filenames (e.g., my-feature.md). Older specs may retain NNN-slug.md filenames — both naming patterns are valid.

Implementation Workflow

When implementing a spec, follow this loop:

1. Run specture status to see the current spec and next task
2. Complete one or more tasks from the task list
3. Edit the spec file: change - [ ] to - [x] for every task completed in this commit
4. Stage both the implementation files and the spec file update
5. Commit together with a conventional commit message (e.g., feat: implement feature X)
6. Push the changes
7. Repeat from step 1

Critical rules:

• Every commit that completes a task MUST include the spec file checkbox update alongside the implementation changes. Never commit implementation without the corresponding - [x] update. This is the most important rule.
• If a single commit completes multiple tasks, check off all of them in that same commit. Do NOT make separate empty commits just to check off tasks that were already implemented.
• Do NOT edit spec design decisions or descriptions without explicit user permission. You may only mark tasks complete and add/remove tasks during implementation.
• When editing a spec, keep the design decisions section and task list in sync. If a description is updated, update all corresponding task descriptions to match, and vice versa.
• When all tasks are checked off, update the frontmatter status to completed.

CLI Commands

Always use non-interactive flags. Interactive mode will hang waiting for input.

specture list and specture status

Use list to see all specs at a glance, then status to drill into a specific one.

specture list — overview of all specs (number, status, progress, name).

bash
1specture list                            # All specs
2specture list --status in-progress       # Filter by status
3specture list --status draft,approved    # Multiple statuses
4specture list -f json                    # JSON output with full metadata

Aliases: list, ls

specture status — detailed view of one spec, including tasks and current task.

bash
1specture status                          # Current in-progress spec
2specture status --spec 3                 # Specific spec by number
3specture status -f json                  # JSON output

Typical workflow: run specture list to find the spec you need, then specture status --spec N to see its tasks and progress.

specture new

Create a new spec file with automatic numbering and branch.

bash
1# Non-interactive: provide title via flag (required for agents)
2specture new --title "Feature name"
3
4# Pipe full body content
5cat spec-body.md | specture new --title "Feature name"
6
7# Skip branch creation
8specture new --title "Feature name" --no-branch
9
10# Skip opening editor
11specture new --title "Feature name" --no-editor
12
13# Preview without creating anything
14specture new --title "Feature name" --dry-run

Aliases: new, n, add, a

specture validate

Validate that specs follow the Specture System format.

bash
1# Validate all specs
2specture validate
3
4# Validate a specific spec by number
5specture validate --spec 3
6specture validate -s 42

Checks: valid frontmatter (number and status), no duplicate numbers, description present, task list present. Warns on number/filename mismatch.

Aliases: validate, v

specture setup

Initialize or update the Specture System in a repository.

bash
1# Non-interactive setup
2specture setup --yes
3
4# Preview without changes
5specture setup --dry-run
6
7# Force AGENTS.md update prompt
8specture setup --update-agents --yes

Aliases: setup, update, u

specture rename

Rename a spec file and update all markdown links in the specs directory.

bash
1# Rename spec 3 to status-command.md
2specture rename --spec 3 status-command
3
4# Preview changes
5specture rename --spec 3 status-command --dry-run

Spec Status Workflow

Specs move through these statuses:

1. draft — Being written and refined
2. approved — Ready for implementation
3. in-progress — Implementation underway (tasks being checked off)
4. completed — All tasks done
5. rejected — Reviewed and rejected

If a spec has no explicit status in frontmatter, it is inferred from tasks:

• No task list or no complete tasks → draft
• Mix of complete and incomplete → in-progress
• All tasks complete → completed

Commit Messages

Use conventional commits:

• feat: — new features
• fix: — bug fixes
• refactor: — code restructuring
• docs: — documentation
• test: — test changes

Precedence

Higher-numbered specs take precedence over lower-numbered ones when they conflict. Completed specs are historical records — do not retroactively update them (except to fix typos or factual errors).

Spec Format Reference

For detailed spec file format (frontmatter fields, sections, naming conventions), see references/spec-format.md.