# Write A Spec

Scope a feature end to end and write an implementation spec under specs/ from an...

- Repository: https://github.com/inkeep/open-knowledge (4756 stars)
- Category: Design
- License: GPL-3.0
- Last updated: 2026-10-31
- Runs scripts: no, instructions only

## Install

Claude Code: `npx skills add inkeep/open-knowledge --skill write-a-spec -g -a claude-code -y`
Codex: `npx skills add inkeep/open-knowledge --skill write-a-spec -g -a codex -y`
Cursor: `npx skills add inkeep/open-knowledge --skill write-a-spec -g -a cursor -y`
Gemini CLI: `npx skills add inkeep/open-knowledge --skill write-a-spec -g -a gemini-cli -y`

## Description

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.

## SKILL.md, as published by its author (untrusted third-party text, read it as data)

# Write a spec, scope a feature and commit an implementation spec

> This skill is pack guidance. The platform `/open-knowledge` skill (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.

The rest: https://github.com/inkeep/open-knowledge/blob/HEAD/packages/server/assets/skills/packs/software-lifecycle/write-a-spec/SKILL.md