Write A Spec
Scope a feature end to end and write an implementation spec under specs/ from an...
Install
npx skills add inkeep/open-knowledge --skill write-a-spec -g -a claude-code -y- Repository
- inkeep/open-knowledge4.8k
- Category
- Design
- Updated
- 4d ago
- License
- GPL-3.0
- Context cost
- Mediumabout 3,000 tokens
- Runs scripts
- No, instructions only
What it does
Scope a feature end to end and write an implementation spec under specs/ from an accepted proposal, current-system mapping, goals/non-goals, a Decision Log for one-way-door choices, a live Open Questions backlog, and a real migration + test plan. Read when asked to write a spec, scope this feature, turn this proposal into a spec, plan the implementation, or break this into tasks. Do NOT fire on frame a proposal or write the PRD (sibling frame-a-proposal, a PRD frames a change before it is accepted; this skill starts once one is), record a decision or write the ADR (record-a-decision), write a postmortem (write-a-postmortem), or review this design (review-a-design), those are separate skills. Complements the platform open-knowledge skill; does not replace it.
Write a spec, scope a feature and commit an implementation spec
This skill is pack guidance. The platform
/open-knowledgeskill (read/write/preview/linking/grounding rules) still governs every markdown operation, this layers spec-writing craft on top.
A spec is the contract between "we decided to build this" and "here is how it gets built." It is derived from an ACCEPTED proposal, maps the system that exists TODAY before proposing a change, and records its one-way-door choices in a Decision Log so the reasoning survives the author leaving. A spec that skips the current-system mapping, or resolves its open questions silently, is a liability, it reads authoritative while being unfounded.
specs/ uses a folder-per-spec shape: specs/NNN-name/ holding spec.md, and (when the work is actually going to be built) plan.md + tasks.md. The pack ships all three templates. status on spec.md flows draft → ... → shipped.
Autonomy mode
| Mode | Behavior | How entered |
|---|---|---|
| Supervised (default) | STOP at the Step 2 scoping gate for user confirmation of Goals / Non-goals / change shape. Route open decisions interactively. | Default when a user drives the session. |
| Headless | Auto-confirm the scoping proposal after presenting it; auto-select routing decisions. All other gates (parent-proposal check, current-system mapping, Decision Log, validation, grounding) still enforced. | Explicit "don't wait for me", "just proceed", "run headless", or non-interactive container environments. |
In headless mode, propose the scope AND proceed immediately; record in the Decision Log that scope was auto-confirmed without user sign-off.
Mandatory execution order
Hard gates, do NOT skip ahead. If you find yourself about to write ## Design before you have read the actual code the change touches, STOP, you skipped Step 1.
