spec-management

spec-management

takt spec is the canonical tool for managing spec files. Always use it for spec lifecycle operations; do not use mv, manual frontmatter edits, or direct file manipulation.

Getting Started

Before using any spec commands, make sure the project has a specs directory.

Initialise specs/ if absent

Check whether the project already has a specs directory:

test -d specs && echo "exists" || echo "missing"

If missing, initialise it before doing anything else:

uv run takt spec init

This creates specs/, specs/drafts/, specs/planned/, and specs/done/. Only needs to be done once per project.

Note: If specs/ already exists but is missing its lifecycle subdirectories, the create subcommand will create them automatically. spec init is only required to create the top-level specs/ directory itself.

"drafts", "planned", and "done" are the default lifecycle stages, but custom status values are supported. The skill enforces that a spec file lives in the folder matching its status frontmatter field, so if you use custom status values, the skill script will enforce the correct folder structure automatically.

Invocation

Run from the project root (where specs/ lives):

uv run takt spec <subcommand> [args]

takt spec ships with takt; there is nothing to locate or install separately.

Subcommands

create <title> — Create a new spec

Creates a new spec file in specs/drafts/ with a generated ID and a standard template.

uv run takt spec create "My Feature Title"

Output: path to the created file and its generated ID (e.g. spec-a3f19c2b).

The filename is derived from the title as a slug (lowercase, hyphens, .md extension).

If specs/ exists but the lifecycle subdirectories (drafts/, planned/, done/) are absent, create creates them automatically. Running spec init beforehand is not required when specs/ already exists.

---

list — List all specs

Lists specs across all lifecycle folders with their ID, status, priority, complexity, and name.

uv run takt spec list
uv run takt spec list --status draft
uv run takt spec list --status planned
uv run takt spec list --tag backend
uv run takt spec list --priority high

Filters can be combined. Legacy specs (no frontmatter) are shown with status legacy.

---

show <spec> — Show spec details

Prints the frontmatter and first 20 lines of body for a spec. Use --full to print the entire body. Use --body-only to print the body without frontmatter — always use this when passing a spec to the spec-reviewer agent or any other agent that should not see frontmatter fields.

uv run takt spec show spec-a3f19c2b
uv run takt spec show my-feature
uv run takt spec show --full spec-a3f19c2b
uv run takt spec show --body-only spec-a3f19c2b

See ID and filename resolution for how <spec> is matched.

---

set status <value> <spec> — Transition lifecycle status

Updates the status field in frontmatter and moves the file to the matching lifecycle folder. This is the only supported way to change a spec's lifecycle stage.

uv run takt spec set status planned spec-a3f19c2b
uv run takt spec set status done    spec-a3f19c2b
uv run takt spec set status draft   spec-a3f19c2b

Valid values: draft, planned, done.

Status	Folder
draft	specs/drafts/
planned	specs/planned/
done	specs/done/

Output: new path of the file after the move.

Do not use mv to move spec files between folders. set status keeps the frontmatter and filesystem location in sync atomically.

Merge-on-done: When transitioning to done from a non-done status, set status done also validates and applies the spec's ## Requirements section to the capability files under specs/current/. If validation fails, the command exits 1, leaves the spec in its original folder, and writes nothing to specs/current/. On success, it prints one merged: <OP> <capability> / <requirement name> line per delta applied.

Custom status values are supported. The skill will create the necessary folders as needed and enforce that the status field matches the folder name.

---

set feature-root <bead-id> <spec> — Link to a feature root bead

Sets the feature_root_id frontmatter field.

uv run takt spec set feature-root B-a7bc3f91 spec-a3f19c2b

---

set tags <tag1,tag2,...> <spec> — Replace tags

Replaces the tags list in frontmatter. Provide tags as a comma-separated string.

uv run takt spec set tags "backend,auth" spec-a3f19c2b

---

set priority <value> <spec> — Set priority

Sets the priority field. Valid values: high, medium, low.

uv run takt spec set priority high spec-a3f19c2b

---

set description <text> <spec> — Set description

Sets the description frontmatter field to a single-line text value.

uv run takt spec set description "Adds OAuth login support" spec-a3f19c2b

---

migrate <spec> — Add frontmatter to a legacy spec

Adds a standard frontmatter block to a spec file that has none. Infers the name from the first # Heading or the filename, generates a new ID, and infers the status from the file's current folder.

uv run takt spec migrate old-spec-filename

Fails if the spec already has frontmatter.

---

search <query> — Search specs

Hybrid (semantic + keyword) search over the section-level index of all specs. Returns ranked documents with ID, status, title, section and snippet. Use it instead of grepping specs/ or searching the memory specs namespace.

uv run takt spec search "<query>" [--status S]... [--tag T]... [--limit N] [--chunks] [--json] [--plain]
uv run takt spec search "merge=ours" --status planned --limit 5

• --status S — repeatable; OR across values.
• --tag T — repeatable; AND across values.
• --limit N — maximum results (default 10).
• --chunks — return individual matching sections instead of the best section per spec.
• --json — array of {id, type, status, title, path, section, snippet, score}.
• --plain — tab-separated id\tstatus\tsection\tscore\ttitle, no snippet.

No hits prints No matches. (exit 0). Search first syncs the index with the files, so it reflects hand edits and moves. From a feature worktree it reads the main checkout's index and files. Exits 1 if there is no .takt/ project.

reindex — Rebuild the spec index

uv run takt spec reindex           # rebuild from scratch; prints "indexed <n> spec documents (<m> chunks)"
uv run takt spec reindex --check   # dry run; prints "would add <a>, update <u>, remove <r> (<k> unchanged)"

Normally unnecessary (search reconciles automatically); use it after bulk file changes or to inspect drift with --check.

remove <spec> — Delete a spec file

Permanently deletes the spec file. Behaviour depends on status:

• draft specs are deleted immediately with no confirmation.
• planned or done specs prompt for confirmation ([y/N]) to prevent accidental deletion.

uv run takt spec remove spec-a3f19c2b
uv run takt spec remove my-feature

Use --force to skip the confirmation prompt (useful in automated or non-interactive contexts):

uv run takt spec remove --force spec-a3f19c2b

Note for agents: always use --force when deleting specs non-interactively, otherwise the confirmation prompt will block execution.

---

validate <spec> — Validate the Requirements section

Checks the ## Requirements section for structural correctness and consistency with specs/current/.

uv run takt spec validate spec-a3f19c2b
uv run takt spec validate my-feature
uv run takt spec validate path/to/spec.md   # also accepts a file path

Exit codes:

• 0 — all entries are valid (or no Requirements section is present); prints OK: <path> (<n> requirement deltas) or OK: <path> (no Requirements section)
• 1 — one or more structural or consistency errors; each printed to stderr as error: <path>: <heading>: <message>

validate reads files only; it never creates or modifies anything.

---

ID and Filename Resolution

Every subcommand that takes a <spec> argument resolves it as follows:

1. Exact ID match — if the query equals the id field (e.g. spec-a3f19c2b) in any spec's frontmatter, that spec is returned immediately.
2. Partial filename match — if the query is a substring of a spec's filename stem (case-insensitive), the matching files are collected.
   • Exactly one match → that spec is used.
   • Zero matches → error: no spec matching "<query>" (exit 1).
   • Multiple matches → error: "<query>" matches multiple specs: <id-list> (exit 1). Use a more specific query or the full ID.

Exact ID match always takes priority over filename matching.

Frontmatter Schema

New specs are created with this template:

---
name: <title>
id: spec-<8-hex-chars>
description:
dependencies:
priority:
complexity:
status: draft
tags: []
scope:
  in:
  out:
feature_root_id:
---

Edit the body freely; takt spec preserves body content when updating frontmatter fields.

---

Folder Structure and Lifecycle

specs/
  drafts/     # Spec written, not yet planned (no beads created)
  planned/    # Planner has run and beads are persisted; implementation in progress
  done/       # All beads merged to main; feature is live
  current/    # Reserved — per-capability living specs, updated by set status done

Rule: A spec lives in exactly one folder. Move it forward only when the transition condition is met.

specs/current/ is reserved. takt spec list, show, and set never treat files under it as specs. set status current exits 1 with error: "current" is a reserved status name.

---

Requirements Section Format

Specs may include a ## Requirements section to record behavioural deltas. This section is optional — specs without it are valid, and set status done is a no-op for the delta merge step.

Each entry is a level-3 heading:

### ADDED|MODIFIED|REMOVED: <capability> / <requirement name>

• <capability> is a kebab-case slug (e.g. bead-lifecycle, tui-tree-panel) naming specs/current/<capability>.md.
• <requirement name> is free text, unique within the capability (case-insensitive).

ADDED and MODIFIED entries must contain:

• At least one sentence using SHALL or MUST (uppercase)
• At least one #### Scenario: <name> sub-heading, with - **WHEN** and - **THEN** lines

REMOVED entries must contain a Reason: line and must not contain scenarios.

Example:

## Requirements

### ADDED: bead-lifecycle / Recovery bead on missing structured output
The scheduler SHALL create a `{bead_id}-recovery` bead when a worker
finishes without structured output.

#### Scenario: Developer bead returns prose only
- **WHEN** a developer bead's runner output contains no parseable JSON
- **THEN** a bead `<id>-recovery` with `agent_type=recovery` is created

### REMOVED: bead-lifecycle / Manual retry required after parse failure
Reason: superseded by automatic recovery beads.

Use uv run takt spec validate <spec> to check a spec's Requirements section before running the planner or transitioning to done.

---

Writing a Spec

Template

A default template is used when creating a new spec with takt spec create. The template includes only markdown sections but no frontmatter with metadata, as those will be managed automatically by the skill when initializing the skill.

The default template is specs/spec-template.md. You or the user can edit this file to change the default content for new specs depending on the project's needs. The template can include any content but the default version is a good starting point.

Good spec practices

• Be prescriptive: agents implement exactly what the spec says. Vague specs produce vague implementations.
• Include concrete examples (function signatures, config YAML, CLI output) where helpful
• Reference existing code by file:line when the change is to a specific location
• Keep acceptance criteria verifiable — avoid "the code is clean" or "it works correctly"
• Resolved pending decisions should stay in the spec with their resolution, not be deleted

What NOT to put in a spec

• Implementation details the agent should decide (e.g. variable names, internal algorithm choice)
• Speculative future features — scope to what's actually being built
• Duplicate content from project-level instructions