managing-specs
Skill11 starsChanged 51 days agoMITView on GitHub
Canonical rules for spec manifest management — statuses, transitions, and the manifest-ops script. Auto-loads when working with spec files.
In this repository44 other files it gives its agents.
- AGENTS.mdAGENTS.md
- .claude/CLAUDE.mdCLAUDE.md
- auditing-uiSkill
- browser-testingSkill
- capturing-product-mediaSkill
- ci-local-exportSkill
- ci-pulseSkill
- ci-quarantineSkill
- ci-statusSkill
- creating-pull-requestsSkill
- debugging-systematicallySkill
- debugging-test-failuresSkill
- debugging-typescript-errorsSkill
- deps-weeklySkill
- designing-frontendSkill
- opensrcSkill
- organizing-fsd-architectureSkill
- runtime-watchSkill
- stewarding-ci-pipelineSkill
- syncing-agent-skillsSkill
- verification-before-completionSkill
- vision-drift-checkSkill
- visual-companionSkill
- writing-adrsSkill
- writing-app-copySkill
- writing-blog-postsSkill
- writing-changelogsSkill
- writing-developer-guidesSkill
- writing-for-humansSkill
- writing-to-usersSkill
- adding-config-fieldsSkill
- clarifying-requirementsSkill
- maintaining-dependenciesSkill
- maintaining-dev-playgroundSkill
- marketplace-devSkill
- orchestrating-parallel-workSkill
- reading-session-transcriptsSkill
- receiving-code-reviewSkill
- requesting-code-reviewSkill
- styling-with-tailwind-shadcnSkill
- test-driven-developmentSkill
- upgrading-runtime-dependenciesSkill
- working-in-worktreesSkill
- dorkbot-triageSkill
The file
We split this skill into the rules it gives an agent
5 rules. About 0 are common, 1 is distinctive, and 4 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈1
Distinctive · estimate
This author's own choices. Worth a look.
4
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 20
Only four statuses are valid:
- Very specific: line 37
After writing 01-ideation.md -> set to ideation
- Very specific: line 39
After all implementation tasks complete -> set to implemented
- Very specific: line 40
When replaced by a newer spec -> set to superseded
- Very specific: line 87
When to archive (policy, not an automated rule): a spec that is implemented and shipped more than ~6 months ago, or one that is superseded …
≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Managing the Spec Manifest
The spec manifest (specs/manifest.json) tracks every specification in the project. Never edit it by hand — always use the manifest-ops script.
Running the Script
node --experimental-strip-types --disable-warning=ExperimentalWarning .claude/scripts/spec-manifest-ops.ts <command> [args] [options]Canonical Statuses
Only four statuses are valid:
| Status | Meaning |
ideation | Spec has 01-ideation.md |
specified | Spec has 02-specification.md |
implemented | Spec has 04-implementation.md |
superseded | Replaced by a newer spec |
Non-canonical aliases are normalized automatically: draft -> ideation, specification -> specified, completed -> implemented.
Status Progression
Statuses move forward only: ideation -> specified -> implemented -> superseded. The script rejects regressions unless --force is passed.
When to Update Status
- After writing
01-ideation.md-> set toideation - After writing
02-specification.md-> set tospecified - After all implementation tasks complete -> set to
implemented - When replaced by a newer spec -> set to
superseded
Commands
Update status
node --experimental-strip-types --disable-warning=ExperimentalWarning \
.claude/scripts/spec-manifest-ops.ts update-status <slug> <status>Add a new spec
node --experimental-strip-types --disable-warning=ExperimentalWarning \
.claude/scripts/spec-manifest-ops.ts add <slug> "Title" --status=ideationOptions: --status=<s>, --project=<p>, --created=YYYY-MM-DD.
Other operations
| Command | Purpose |
get <slug> | Print a spec entry as JSON |
list [--status=<s>] | List specs, optionally filtered |
audit [--json] | Audit manifest vs filesystem |
fix [--dry-run] | Auto-fix all audit findings |
remove <slug> | Remove a spec entry from the manifest (leaves files) |
archive <slug> | Retire a spec: move to specs/archive/ and drop the entry |
Archiving Retired Specs
specs/ is append-only by default: implemented specs stay listed forever. To
retire one, archive it. This mirrors the decisions/archive/ lifecycle: the
spec directory is MOVED to specs/archive/<slug>/ and its entry is REMOVED from
specs/manifest.json, so the active manifest only ever lists live specs.
node --experimental-strip-types --disable-warning=ExperimentalWarning \
.claude/scripts/spec-manifest-ops.ts archive <slug>archive vs superseded: superseded is a manifest status for a spec that
is still tracked; archiving removes the spec from the manifest entirely. A
spec can be archived from any status (usually implemented or superseded).
When to archive (policy, not an automated rule): a spec that is implemented and
shipped more than ~6 months ago, or one that is superseded by a shipped
replacement, or an abandoned direction. When in doubt, leave it in place. Before
archiving, grep for inbound specs/<slug> references and re-point any you move.
The full policy and recovery steps live in
specs/archive/README.md. Bulk-migrating the
existing backlog is a separate, deliberate follow-up, not something this command
does in one sweep.
Identifiers (timestamp ids)
New specs get a coordination-free timestamp id (YYMMDD-HHMMSS), which add
stamps from the local clock via .claude/scripts/id.ts — no shared counter, so
two branches can never allocate the same id (spec #271 / DOR-184). The ~260
existing specs are frozen and keep their legacy number; list, audit, and
fix display each entry by its key (the timestamp id, or a zero-padded legacy
number, which sorts before timestamp ids). There is no nextNumber field to
maintain — add and fix self-allocate ids, and archiving or removing an entry
is always safe because ids are never reused.
Integration Points
These slash commands should update the manifest as part of their workflow:
| Command | Manifest action |
/flow:ideate | add <slug> "Title" --status=ideation |
/flow:specify | Ensure entry exists with status specified |
/flow:execute | update-status <slug> implemented on completion |
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

