open-knowledge-pack-software-lifecycle-write-a-spec

What it does

The skill guides an agent to scope a feature end-to-end and convert an accepted proposal into a formal implementation spec placed under specs/. It ensures the spec links to the current system, records goals and non-goals, traces one-way-door decisions in a Decision Log, maintains a live Open Questions backlog, and includes a real Migration + Test plan. It instructs the agent to locate the parent proposal, map the current system, perform scoping with user confirmation, create the spec folder and spec.md from a template, fill Goals and Non-goals, draft Design with current vs proposed changes, append a Decision Log with one-entry-per-one-way-door choice, add Open Questions, and populate Migration and Test plan sections. It also enforces the mandatory order of steps and prohibits skipping gates, including the creation of plan.md and tasks.md only when implementation is to proceed. The mode can be Supervised (default) or Headless, affecting whether the scoping gate waits for user confirmation.

The skill operates within the open-knowledge framework and requires the OpenKnowledge MCP server and specific Claude tools; it uses commands and file structure outlined in the spec template, and its workflow is explicitly designed to be anchorable to a parent proposal and then to a spec directory "specs/NNN-name/" with files like spec.md (and later plan.md, tasks.md if built).

How it works

• Find the parent proposal behind the feature to derive a spec.
• Map the CURRENT system by reading real code (via host tools) and existing specs/guides (via OpenKnowledge verbs) to produce a "Current system" Design subsection with concrete pointers.
• Enter the Scoping STOP gate: present a Proposed scope block to the user including Parent proposal, Goals, Non-goals, Shape of the change, and Open questions.
• In Supervised mode, wait for confirmation; in Headless mode, auto-confirm scope and record in the Decision Log.
• Create the spec folder: allocate the next NNN under specs/, create specs/NNN-name/spec.md from the spec template, and populate frontmatter including parent_proposal and status.
• Fill Goals and Non-goals with observable outcomes and explicit non-goals with reasons.
• Draft Design with two layers: Current system mapping and Proposed change, detailing design options and rationale for the chosen path; one-way-door choices must go to the Decision Log.
• Append a Decision Log (DL) section with entries for each one-way-door choice, including a rationale and reversal conditions.
• Add Open Questions as a live backlog to remain open until resolved.
• Populate Migration and Test plan with real states, data changes, verifiable tests, and notes on what cannot be verified before ship.
• Only later, if the spec is greenlit for implementation, create plan.md and tasks.md.

When to use it

• When asked to write a spec from an accepted proposal and scope the feature end-to-end.
• When you need to map the current system and formalize decisions, migrations, and tests before implementation.
• When you must ensure one-way-door decisions are documented and Open Questions tracked.

What it can touch

• It touches the specs/ folder structure and creates spec.md within specs/NNN-name/. It expects to interact with host tools to inspect the current codebase and with OpenKnowledge verbs to read existing specs/guides. It will reference a parent proposal path and place a status of draft in the new spec.

Caveats

• The process requires an accepted parent proposal; if none exists, the skill instructs how to handle the skip and to record this rationale in the Decision Log.
• Plan.md and Tasks.md are generated only when the spec proceeds to building; otherwise they are omitted.
• All steps rely on the platform’s governance: the OpenKnowledge MCP server and the specified Claude tools; the workflow does not bypass these constraints.