[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"skill:01M6DS18M9ZVEBTD7GQWB0YFAG":3,"skill-same:01M6DS18M9ZVEBTD7GQWB0YFAG":69},{"skillNo":4,"name":5,"nameZh":6,"description":7,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":16,"categories":17,"keywords":18,"publishedAt":42,"linkOnly":43,"markdownContent":44,"markdownBody":45,"frontMatter":46,"refName":48,"commitSha":49,"skillDirectory":50,"forksCount":14,"repositoryHtmlUrl":51,"repositoryHomepageUrl":6,"ownerHtmlUrl":52,"ownerBlogUrl":53,"ownerDescription":6,"updatedAt":54,"install":55,"resources":68},"01M6DS18M9ZVEBTD7GQWB0YFAG","spec-management",null,"This skill supports managing spec files, as part of spec-driven development. The skill exposes functions for creating, listing, showing, and updating spec files. This skill must always be used to create and manage specs, and to update metadata for spec files (description, dependencies, priority, complexity, status, tags, and scope). Editing of the content of spec files, except for the frontmatter fields that the skill manages for the metadata, is outside the scope of this skill and should be done by agents directly in the file. Agents should not edit any frontmatter fields directly in the file, but should use the provided functions to ensure the filesystem and frontmatter stay in sync.","oscarrenalias\u002Ftakt","oscarrenalias","https:\u002F\u002Favatars.githubusercontent.com\u002Fu\u002F199804?v=4","01M6DS0MTQXECAD11T5GHG2840","Oscar Renalias","01M6DS0MZNDBEE9DVZ852ZV4ZD",0,"MIT","https:\u002F\u002Fgithub.com\u002Foscarrenalias\u002Ftakt\u002Fblob\u002Fmain\u002F.claude\u002Fskills\u002Fskill-spec-management\u002FSKILL.md",[],[19,20,21,22,23,24,25,26,27,28,29,30,31,32,33,34,35,36,37,38,39,40,41],"spec","spec management","management","listing","frontmatter","spec-driven","scope","as","done","but","manage","files","complexity","edit","write","read","editing","Bash","update","create","development","status","sync","2026-11-10 10:12:30",false,"---\nname: spec-management\ndescription: This skill supports managing spec files, as part of spec-driven development. The skill exposes functions for creating, listing, showing, and updating spec files. This skill must always be used to create and manage specs, and to update metadata for spec files (description, dependencies, priority, complexity, status, tags, and scope). Editing of the content of spec files, except for the frontmatter fields that the skill manages for the metadata, is outside the scope of this skill and should be done by agents directly in the file. Agents should not edit any frontmatter fields directly in the file, but should use the provided functions to ensure the filesystem and frontmatter stay in sync.\ntools: Read, Write, Edit, Glob, Grep, Bash\nlicense: MIT\n---\n\n# spec-management\n\n`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.\n\n## Getting Started\n\nBefore using any spec commands, make sure the project has a specs directory.\n\n### Initialise specs\u002F if absent\n\nCheck whether the project already has a specs directory:\n\n```bash\ntest -d specs && echo \"exists\" || echo \"missing\"\n```\n\nIf missing, initialise it before doing anything else:\n\n```bash\nuv run takt spec init\n```\n\nThis creates `specs\u002F`, `specs\u002Fdrafts\u002F`, `specs\u002Fplanned\u002F`, and `specs\u002Fdone\u002F`. Only needs to be done once per project.\n\n> **Note:** If `specs\u002F` 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\u002F` directory itself.\n\n\"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.\n\n## Invocation\n\nRun from the project root (where `specs\u002F` lives):\n\n```bash\nuv run takt spec \u003Csubcommand> [args]\n```\n\n`takt spec` ships with takt; there is nothing to locate or install separately.\n\n## Subcommands\n\n### `create \u003Ctitle>` — Create a new spec\n\nCreates a new spec file in `specs\u002Fdrafts\u002F` with a generated ID and a standard template.\n\n```bash\nuv run takt spec create \"My Feature Title\"\n```\n\nOutput: path to the created file and its generated ID (e.g. `spec-a3f19c2b`).\n\nThe filename is derived from the title as a slug (lowercase, hyphens, `.md` extension).\n\nIf `specs\u002F` exists but the lifecycle subdirectories (`drafts\u002F`, `planned\u002F`, `done\u002F`) are absent, `create` creates them automatically. Running `spec init` beforehand is not required when `specs\u002F` already exists.\n\n---\n\n### `list` — List all specs\n\nLists specs across all lifecycle folders with their ID, status, priority, complexity, and name.\n\n```bash\nuv run takt spec list\nuv run takt spec list --status draft\nuv run takt spec list --status planned\nuv run takt spec list --tag backend\nuv run takt spec list --priority high\n```\n\nFilters can be combined. Legacy specs (no frontmatter) are shown with status `legacy`.\n\n---\n\n### `show \u003Cspec>` — Show spec details\n\nPrints 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.\n\n```bash\nuv run takt spec show spec-a3f19c2b\nuv run takt spec show my-feature\nuv run takt spec show --full spec-a3f19c2b\nuv run takt spec show --body-only spec-a3f19c2b\n```\n\nSee [ID and filename resolution](#id-and-filename-resolution) for how `\u003Cspec>` is matched.\n\n---\n\n### `set status \u003Cvalue> \u003Cspec>` — Transition lifecycle status\n\nUpdates 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.\n\n```bash\nuv run takt spec set status planned spec-a3f19c2b\nuv run takt spec set status done    spec-a3f19c2b\nuv run takt spec set status draft   spec-a3f19c2b\n```\n\nValid values: `draft`, `planned`, `done`.\n\n| Status | Folder |\n|--------|--------|\n| `draft` | `specs\u002Fdrafts\u002F` |\n| `planned` | `specs\u002Fplanned\u002F` |\n| `done` | `specs\u002Fdone\u002F` |\n\nOutput: new path of the file after the move.\n\n> **Do not use `mv`** to move spec files between folders. `set status` keeps the frontmatter and filesystem location in sync atomically.\n\n**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\u002Fcurrent\u002F`. If validation fails, the command exits 1, leaves the spec in its original folder, and writes nothing to `specs\u002Fcurrent\u002F`. On success, it prints one `merged: \u003COP> \u003Ccapability> \u002F \u003Crequirement name>` line per delta applied.\n\nCustom status values are supported. The skill will create the necessary folders as needed and enforce that the `status` field matches the folder name.\n\n---\n\n### `set feature-root \u003Cbead-id> \u003Cspec>` — Link to a feature root bead\n\nSets the `feature_root_id` frontmatter field.\n\n```bash\nuv run takt spec set feature-root B-a7bc3f91 spec-a3f19c2b\n```\n\n---\n\n### `set tags \u003Ctag1,tag2,...> \u003Cspec>` — Replace tags\n\nReplaces the `tags` list in frontmatter. Provide tags as a comma-separated string.\n\n```bash\nuv run takt spec set tags \"backend,auth\" spec-a3f19c2b\n```\n\n---\n\n### `set priority \u003Cvalue> \u003Cspec>` — Set priority\n\nSets the `priority` field. Valid values: `high`, `medium`, `low`.\n\n```bash\nuv run takt spec set priority high spec-a3f19c2b\n```\n\n---\n\n### `set description \u003Ctext> \u003Cspec>` — Set description\n\nSets the `description` frontmatter field to a single-line text value.\n\n```bash\nuv run takt spec set description \"Adds OAuth login support\" spec-a3f19c2b\n```\n\n---\n\n### `migrate \u003Cspec>` — Add frontmatter to a legacy spec\n\nAdds 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.\n\n```bash\nuv run takt spec migrate old-spec-filename\n```\n\nFails if the spec already has frontmatter.\n\n---\n\n### `search \u003Cquery>` — Search specs\n\nHybrid (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\u002F` or searching the memory `specs` namespace.\n\n```bash\nuv run takt spec search \"\u003Cquery>\" [--status S]... [--tag T]... [--limit N] [--chunks] [--json] [--plain]\nuv run takt spec search \"merge=ours\" --status planned --limit 5\n```\n\n- `--status S` — repeatable; OR across values.\n- `--tag T` — repeatable; AND across values.\n- `--limit N` — maximum results (default 10).\n- `--chunks` — return individual matching sections instead of the best section per spec.\n- `--json` — array of `{id, type, status, title, path, section, snippet, score}`.\n- `--plain` — tab-separated `id\\tstatus\\tsection\\tscore\\ttitle`, no snippet.\n\nNo 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\u002F` project.\n\n### `reindex` — Rebuild the spec index\n\n```bash\nuv run takt spec reindex           # rebuild from scratch; prints \"indexed \u003Cn> spec documents (\u003Cm> chunks)\"\nuv run takt spec reindex --check   # dry run; prints \"would add \u003Ca>, update \u003Cu>, remove \u003Cr> (\u003Ck> unchanged)\"\n```\n\nNormally unnecessary (search reconciles automatically); use it after bulk file changes or to inspect drift with `--check`.\n\n### `remove \u003Cspec>` — Delete a spec file\n\nPermanently deletes the spec file. Behaviour depends on status:\n\n- **draft** specs are deleted immediately with no confirmation.\n- **planned** or **done** specs prompt for confirmation (`[y\u002FN]`) to prevent accidental deletion.\n\n```bash\nuv run takt spec remove spec-a3f19c2b\nuv run takt spec remove my-feature\n```\n\nUse `--force` to skip the confirmation prompt (useful in automated or non-interactive contexts):\n\n```bash\nuv run takt spec remove --force spec-a3f19c2b\n```\n\n> **Note for agents:** always use `--force` when deleting specs non-interactively, otherwise the confirmation prompt will block execution.\n\n---\n\n### `validate \u003Cspec>` — Validate the Requirements section\n\nChecks the `## Requirements` section for structural correctness and consistency with `specs\u002Fcurrent\u002F`.\n\n```bash\nuv run takt spec validate spec-a3f19c2b\nuv run takt spec validate my-feature\nuv run takt spec validate path\u002Fto\u002Fspec.md   # also accepts a file path\n```\n\nExit codes:\n- **0** — all entries are valid (or no Requirements section is present); prints `OK: \u003Cpath> (\u003Cn> requirement deltas)` or `OK: \u003Cpath> (no Requirements section)`\n- **1** — one or more structural or consistency errors; each printed to stderr as `error: \u003Cpath>: \u003Cheading>: \u003Cmessage>`\n\n`validate` reads files only; it never creates or modifies anything.\n\n---\n\n## ID and Filename Resolution\n\nEvery subcommand that takes a `\u003Cspec>` argument resolves it as follows:\n\n1. **Exact ID match** — if the query equals the `id` field (e.g. `spec-a3f19c2b`) in any spec's frontmatter, that spec is returned immediately.\n2. **Partial filename match** — if the query is a substring of a spec's filename stem (case-insensitive), the matching files are collected.\n   - Exactly one match → that spec is used.\n   - Zero matches → `error: no spec matching \"\u003Cquery>\"` (exit 1).\n   - Multiple matches → `error: \"\u003Cquery>\" matches multiple specs: \u003Cid-list>` (exit 1). Use a more specific query or the full ID.\n\nExact ID match always takes priority over filename matching.\n\n## Frontmatter Schema\n\nNew specs are created with this template:\n\n```yaml\n---\nname: \u003Ctitle>\nid: spec-\u003C8-hex-chars>\ndescription:\ndependencies:\npriority:\ncomplexity:\nstatus: draft\ntags: []\nscope:\n  in:\n  out:\nfeature_root_id:\n---\n```\n\nEdit the body freely; `takt spec` preserves body content when updating frontmatter fields.\n\n---\n\n## Folder Structure and Lifecycle\n\n```\nspecs\u002F\n  drafts\u002F     # Spec written, not yet planned (no beads created)\n  planned\u002F    # Planner has run and beads are persisted; implementation in progress\n  done\u002F       # All beads merged to main; feature is live\n  current\u002F    # Reserved — per-capability living specs, updated by set status done\n```\n\n**Rule:** A spec lives in exactly one folder. Move it forward only when the transition condition is met.\n\n`specs\u002Fcurrent\u002F` 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`.\n\n---\n\n## Requirements Section Format\n\nSpecs 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.\n\nEach entry is a level-3 heading:\n\n```\n### ADDED|MODIFIED|REMOVED: \u003Ccapability> \u002F \u003Crequirement name>\n```\n\n- `\u003Ccapability>` is a kebab-case slug (e.g. `bead-lifecycle`, `tui-tree-panel`) naming `specs\u002Fcurrent\u002F\u003Ccapability>.md`.\n- `\u003Crequirement name>` is free text, unique within the capability (case-insensitive).\n\n**ADDED and MODIFIED entries** must contain:\n- At least one sentence using `SHALL` or `MUST` (uppercase)\n- At least one `#### Scenario: \u003Cname>` sub-heading, with `- **WHEN**` and `- **THEN**` lines\n\n**REMOVED entries** must contain a `Reason:` line and must not contain scenarios.\n\nExample:\n\n```markdown\n## Requirements\n\n### ADDED: bead-lifecycle \u002F Recovery bead on missing structured output\nThe scheduler SHALL create a `{bead_id}-recovery` bead when a worker\nfinishes without structured output.\n\n#### Scenario: Developer bead returns prose only\n- **WHEN** a developer bead's runner output contains no parseable JSON\n- **THEN** a bead `\u003Cid>-recovery` with `agent_type=recovery` is created\n\n### REMOVED: bead-lifecycle \u002F Manual retry required after parse failure\nReason: superseded by automatic recovery beads.\n```\n\nUse `uv run takt spec validate \u003Cspec>` to check a spec's Requirements section before running the planner or transitioning to done.\n\n---\n\n## Writing a Spec\n\n### Template\n\nA 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.\n\nThe default template is `specs\u002Fspec-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.\n\n### Good spec practices\n\n- Be prescriptive: agents implement exactly what the spec says. Vague specs produce vague implementations.\n- Include concrete examples (function signatures, config YAML, CLI output) where helpful\n- Reference existing code by file:line when the change is to a specific location\n- Keep acceptance criteria verifiable — avoid \"the code is clean\" or \"it works correctly\"\n- Resolved pending decisions should stay in the spec with their resolution, not be deleted\n\n### What NOT to put in a spec\n\n- Implementation details the agent should decide (e.g. variable names, internal algorithm choice)\n- Speculative future features — scope to what's actually being built\n- Duplicate content from project-level instructions","# spec-management\n\n`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.\n\n## Getting Started\n\nBefore using any spec commands, make sure the project has a specs directory.\n\n### Initialise specs\u002F if absent\n\nCheck whether the project already has a specs directory:\n\n```bash\ntest -d specs && echo \"exists\" || echo \"missing\"\n```\n\nIf missing, initialise it before doing anything else:\n\n```bash\nuv run takt spec init\n```\n\nThis creates `specs\u002F`, `specs\u002Fdrafts\u002F`, `specs\u002Fplanned\u002F`, and `specs\u002Fdone\u002F`. Only needs to be done once per project.\n\n> **Note:** If `specs\u002F` 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\u002F` directory itself.\n\n\"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.\n\n## Invocation\n\nRun from the project root (where `specs\u002F` lives):\n\n```bash\nuv run takt spec \u003Csubcommand> [args]\n```\n\n`takt spec` ships with takt; there is nothing to locate or install separately.\n\n## Subcommands\n\n### `create \u003Ctitle>` — Create a new spec\n\nCreates a new spec file in `specs\u002Fdrafts\u002F` with a generated ID and a standard template.\n\n```bash\nuv run takt spec create \"My Feature Title\"\n```\n\nOutput: path to the created file and its generated ID (e.g. `spec-a3f19c2b`).\n\nThe filename is derived from the title as a slug (lowercase, hyphens, `.md` extension).\n\nIf `specs\u002F` exists but the lifecycle subdirectories (`drafts\u002F`, `planned\u002F`, `done\u002F`) are absent, `create` creates them automatically. Running `spec init` beforehand is not required when `specs\u002F` already exists.\n\n---\n\n### `list` — List all specs\n\nLists specs across all lifecycle folders with their ID, status, priority, complexity, and name.\n\n```bash\nuv run takt spec list\nuv run takt spec list --status draft\nuv run takt spec list --status planned\nuv run takt spec list --tag backend\nuv run takt spec list --priority high\n```\n\nFilters can be combined. Legacy specs (no frontmatter) are shown with status `legacy`.\n\n---\n\n### `show \u003Cspec>` — Show spec details\n\nPrints 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.\n\n```bash\nuv run takt spec show spec-a3f19c2b\nuv run takt spec show my-feature\nuv run takt spec show --full spec-a3f19c2b\nuv run takt spec show --body-only spec-a3f19c2b\n```\n\nSee [ID and filename resolution](#id-and-filename-resolution) for how `\u003Cspec>` is matched.\n\n---\n\n### `set status \u003Cvalue> \u003Cspec>` — Transition lifecycle status\n\nUpdates 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.\n\n```bash\nuv run takt spec set status planned spec-a3f19c2b\nuv run takt spec set status done    spec-a3f19c2b\nuv run takt spec set status draft   spec-a3f19c2b\n```\n\nValid values: `draft`, `planned`, `done`.\n\n| Status | Folder |\n|--------|--------|\n| `draft` | `specs\u002Fdrafts\u002F` |\n| `planned` | `specs\u002Fplanned\u002F` |\n| `done` | `specs\u002Fdone\u002F` |\n\nOutput: new path of the file after the move.\n\n> **Do not use `mv`** to move spec files between folders. `set status` keeps the frontmatter and filesystem location in sync atomically.\n\n**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\u002Fcurrent\u002F`. If validation fails, the command exits 1, leaves the spec in its original folder, and writes nothing to `specs\u002Fcurrent\u002F`. On success, it prints one `merged: \u003COP> \u003Ccapability> \u002F \u003Crequirement name>` line per delta applied.\n\nCustom status values are supported. The skill will create the necessary folders as needed and enforce that the `status` field matches the folder name.\n\n---\n\n### `set feature-root \u003Cbead-id> \u003Cspec>` — Link to a feature root bead\n\nSets the `feature_root_id` frontmatter field.\n\n```bash\nuv run takt spec set feature-root B-a7bc3f91 spec-a3f19c2b\n```\n\n---\n\n### `set tags \u003Ctag1,tag2,...> \u003Cspec>` — Replace tags\n\nReplaces the `tags` list in frontmatter. Provide tags as a comma-separated string.\n\n```bash\nuv run takt spec set tags \"backend,auth\" spec-a3f19c2b\n```\n\n---\n\n### `set priority \u003Cvalue> \u003Cspec>` — Set priority\n\nSets the `priority` field. Valid values: `high`, `medium`, `low`.\n\n```bash\nuv run takt spec set priority high spec-a3f19c2b\n```\n\n---\n\n### `set description \u003Ctext> \u003Cspec>` — Set description\n\nSets the `description` frontmatter field to a single-line text value.\n\n```bash\nuv run takt spec set description \"Adds OAuth login support\" spec-a3f19c2b\n```\n\n---\n\n### `migrate \u003Cspec>` — Add frontmatter to a legacy spec\n\nAdds 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.\n\n```bash\nuv run takt spec migrate old-spec-filename\n```\n\nFails if the spec already has frontmatter.\n\n---\n\n### `search \u003Cquery>` — Search specs\n\nHybrid (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\u002F` or searching the memory `specs` namespace.\n\n```bash\nuv run takt spec search \"\u003Cquery>\" [--status S]... [--tag T]... [--limit N] [--chunks] [--json] [--plain]\nuv run takt spec search \"merge=ours\" --status planned --limit 5\n```\n\n- `--status S` — repeatable; OR across values.\n- `--tag T` — repeatable; AND across values.\n- `--limit N` — maximum results (default 10).\n- `--chunks` — return individual matching sections instead of the best section per spec.\n- `--json` — array of `{id, type, status, title, path, section, snippet, score}`.\n- `--plain` — tab-separated `id\\tstatus\\tsection\\tscore\\ttitle`, no snippet.\n\nNo 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\u002F` project.\n\n### `reindex` — Rebuild the spec index\n\n```bash\nuv run takt spec reindex           # rebuild from scratch; prints \"indexed \u003Cn> spec documents (\u003Cm> chunks)\"\nuv run takt spec reindex --check   # dry run; prints \"would add \u003Ca>, update \u003Cu>, remove \u003Cr> (\u003Ck> unchanged)\"\n```\n\nNormally unnecessary (search reconciles automatically); use it after bulk file changes or to inspect drift with `--check`.\n\n### `remove \u003Cspec>` — Delete a spec file\n\nPermanently deletes the spec file. Behaviour depends on status:\n\n- **draft** specs are deleted immediately with no confirmation.\n- **planned** or **done** specs prompt for confirmation (`[y\u002FN]`) to prevent accidental deletion.\n\n```bash\nuv run takt spec remove spec-a3f19c2b\nuv run takt spec remove my-feature\n```\n\nUse `--force` to skip the confirmation prompt (useful in automated or non-interactive contexts):\n\n```bash\nuv run takt spec remove --force spec-a3f19c2b\n```\n\n> **Note for agents:** always use `--force` when deleting specs non-interactively, otherwise the confirmation prompt will block execution.\n\n---\n\n### `validate \u003Cspec>` — Validate the Requirements section\n\nChecks the `## Requirements` section for structural correctness and consistency with `specs\u002Fcurrent\u002F`.\n\n```bash\nuv run takt spec validate spec-a3f19c2b\nuv run takt spec validate my-feature\nuv run takt spec validate path\u002Fto\u002Fspec.md   # also accepts a file path\n```\n\nExit codes:\n- **0** — all entries are valid (or no Requirements section is present); prints `OK: \u003Cpath> (\u003Cn> requirement deltas)` or `OK: \u003Cpath> (no Requirements section)`\n- **1** — one or more structural or consistency errors; each printed to stderr as `error: \u003Cpath>: \u003Cheading>: \u003Cmessage>`\n\n`validate` reads files only; it never creates or modifies anything.\n\n---\n\n## ID and Filename Resolution\n\nEvery subcommand that takes a `\u003Cspec>` argument resolves it as follows:\n\n1. **Exact ID match** — if the query equals the `id` field (e.g. `spec-a3f19c2b`) in any spec's frontmatter, that spec is returned immediately.\n2. **Partial filename match** — if the query is a substring of a spec's filename stem (case-insensitive), the matching files are collected.\n   - Exactly one match → that spec is used.\n   - Zero matches → `error: no spec matching \"\u003Cquery>\"` (exit 1).\n   - Multiple matches → `error: \"\u003Cquery>\" matches multiple specs: \u003Cid-list>` (exit 1). Use a more specific query or the full ID.\n\nExact ID match always takes priority over filename matching.\n\n## Frontmatter Schema\n\nNew specs are created with this template:\n\n```yaml\n---\nname: \u003Ctitle>\nid: spec-\u003C8-hex-chars>\ndescription:\ndependencies:\npriority:\ncomplexity:\nstatus: draft\ntags: []\nscope:\n  in:\n  out:\nfeature_root_id:\n---\n```\n\nEdit the body freely; `takt spec` preserves body content when updating frontmatter fields.\n\n---\n\n## Folder Structure and Lifecycle\n\n```\nspecs\u002F\n  drafts\u002F     # Spec written, not yet planned (no beads created)\n  planned\u002F    # Planner has run and beads are persisted; implementation in progress\n  done\u002F       # All beads merged to main; feature is live\n  current\u002F    # Reserved — per-capability living specs, updated by set status done\n```\n\n**Rule:** A spec lives in exactly one folder. Move it forward only when the transition condition is met.\n\n`specs\u002Fcurrent\u002F` 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`.\n\n---\n\n## Requirements Section Format\n\nSpecs 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.\n\nEach entry is a level-3 heading:\n\n```\n### ADDED|MODIFIED|REMOVED: \u003Ccapability> \u002F \u003Crequirement name>\n```\n\n- `\u003Ccapability>` is a kebab-case slug (e.g. `bead-lifecycle`, `tui-tree-panel`) naming `specs\u002Fcurrent\u002F\u003Ccapability>.md`.\n- `\u003Crequirement name>` is free text, unique within the capability (case-insensitive).\n\n**ADDED and MODIFIED entries** must contain:\n- At least one sentence using `SHALL` or `MUST` (uppercase)\n- At least one `#### Scenario: \u003Cname>` sub-heading, with `- **WHEN**` and `- **THEN**` lines\n\n**REMOVED entries** must contain a `Reason:` line and must not contain scenarios.\n\nExample:\n\n```markdown\n## Requirements\n\n### ADDED: bead-lifecycle \u002F Recovery bead on missing structured output\nThe scheduler SHALL create a `{bead_id}-recovery` bead when a worker\nfinishes without structured output.\n\n#### Scenario: Developer bead returns prose only\n- **WHEN** a developer bead's runner output contains no parseable JSON\n- **THEN** a bead `\u003Cid>-recovery` with `agent_type=recovery` is created\n\n### REMOVED: bead-lifecycle \u002F Manual retry required after parse failure\nReason: superseded by automatic recovery beads.\n```\n\nUse `uv run takt spec validate \u003Cspec>` to check a spec's Requirements section before running the planner or transitioning to done.\n\n---\n\n## Writing a Spec\n\n### Template\n\nA 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.\n\nThe default template is `specs\u002Fspec-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.\n\n### Good spec practices\n\n- Be prescriptive: agents implement exactly what the spec says. Vague specs produce vague implementations.\n- Include concrete examples (function signatures, config YAML, CLI output) where helpful\n- Reference existing code by file:line when the change is to a specific location\n- Keep acceptance criteria verifiable — avoid \"the code is clean\" or \"it works correctly\"\n- Resolved pending decisions should stay in the spec with their resolution, not be deleted\n\n### What NOT to put in a spec\n\n- Implementation details the agent should decide (e.g. variable names, internal algorithm choice)\n- Speculative future features — scope to what's actually being built\n- Duplicate content from project-level instructions",{"name":5,"tools":47,"license":15,"description":7},"Read, Write, Edit, Glob, Grep, Bash","main","8c935c89500566d47835b9a4afa2fd0db6bdcd19",".claude\u002Fskills\u002Fskill-spec-management","https:\u002F\u002Fgithub.com\u002Foscarrenalias\u002Ftakt","https:\u002F\u002Fgithub.com\u002Foscarrenalias","http:\u002F\u002Fwww.renalias.net","2026-11-09 18:58:06",{"source":8,"skillName":5,"commands":56,"prompt":66,"zipAvailable":67},[57,60,63],{"tool":58,"command":59},"npx","npx skills add oscarrenalias\u002Ftakt --skill spec-management",{"tool":61,"command":62},"bunx","bunx skills add oscarrenalias\u002Ftakt --skill spec-management",{"tool":64,"command":65},"pnpm","pnpm dlx skills add oscarrenalias\u002Ftakt --skill spec-management","安装技能，技能地址：https:\u002F\u002Fgithub.com\u002Foscarrenalias\u002Ftakt\u002Fblob\u002Fmain\u002F.claude\u002Fskills\u002Fskill-spec-management\u002FSKILL.md",true,[],[70,93,98],{"skillNo":71,"name":72,"nameZh":6,"description":73,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":74,"categories":75,"keywords":76,"publishedAt":42},"01M70S42W5NC39PRKN6987PQ0F","adr-management","Manage Architecture Decision Records (ADRs) with `takt adr` — creating, listing, showing, approving, rejecting, superseding and validating ADRs. Use when a non-feature architectural decision (technology choice, project-wide constraint, cross-feature principle) needs to be recorded, or when asked to look up or change an existing decision. Do not use for feature work; that belongs in a spec.","https:\u002F\u002Fgithub.com\u002Foscarrenalias\u002Ftakt\u002Fblob\u002Fmain\u002Fsrc\u002Fagent_takt\u002F_data\u002Fclaude_skills\u002Fskill-adr-management\u002FSKILL.md",[],[21,77,78,79,80,81,82,83,29,84,85,86,87,88,89,90,91,36,22,92],"adr management","adr","do","architecture decision","feature","for","project","records","up","decision","choice","technology","use","Existing","when","architecture",{"skillNo":94,"name":72,"nameZh":6,"description":73,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":95,"categories":96,"keywords":97,"publishedAt":42},"01M70S3JV851RP3A6WVD2HQV5Q","https:\u002F\u002Fgithub.com\u002Foscarrenalias\u002Ftakt\u002Fblob\u002Fmain\u002F.claude\u002Fskills\u002Fskill-adr-management\u002FSKILL.md",[],[78,77,21,88,80,92,22,36,91,90,89,87,79,81,82,83,29,84,85,86],{"skillNo":99,"name":5,"nameZh":6,"description":7,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":100,"categories":101,"keywords":102,"publishedAt":42},"01M6DS2338RQ5CRY3F3B9EAG1S","https:\u002F\u002Fgithub.com\u002Foscarrenalias\u002Ftakt\u002Fblob\u002Fmain\u002Fsrc\u002Fagent_takt\u002F_data\u002Fclaude_skills\u002Fskill-spec-management\u002FSKILL.md",[],[19,21,20,39,31,25,30,27,36,38,37,34,33,32,41,40,28,26,35,29,24,22,23]]