create-spec

Files (1)

• SKILL.md

SKILL.md (first lines)

# create-spec

Generate a new SpecForge spec in the global store (`~/.specforge/specs/<id>/`),
honoring house rules, and lint it before declaring done. The daemon serves it and
injects the review layer at serve time.

`${CLAUDE_PLUGIN_ROOT}` below denotes the installed plugin directory. Claude and
Pi export it; Codex provides the exact value in SpecForge SessionStart context.
Substitute that value in every path and shell command.

## 1. Understand the request + pick the type

- Identify the topic. If scope is unclear or has multiple interpretations, **ask
  before writing** — don't guess.
- **Read the type list before picking. It is the list, and it is not short:**

  ```
  node "${CLAUDE_PLUGIN_ROOT}/lib/spec-types-cli.mjs"
  ```

  Every type prints with a **when to use** line saying what it is for and what it
  is not for. That line is the rule. This skill deliberately does not repeat the
  types here: a copy in this file goes stale the moment a type is added or its
  description is sharpened, and a stale copy is worse than no copy because it
  reads as authoritative.

- **Pick by reading all of them, not by stopping at the first plausible match.**
  That is the failure this list exists to prevent, and it has a shape: a request
  to plan a release matches `general` on a quick read and `launch-plan` on a full
  one, and the first produces a document with none of the sections that make a
  launch survivable. Four rules settle nearly every case:

  - **The request names a type, take it.** "Write a PRD", "do a security review",
    "test plan for this" name a type. Do not reinterpret them.
  - **Two fit, take the more specific one.** A specific type carries sections and
    guidance the general one cannot. `design-impl` beats `general` for a design
    that will be built; `code-exploration-spec` beats `research` when the subject
    is code in this repo.
  - **The type is decided by what the document has to do, not by the verb.**
    "Explore" appears in `research`, `exploration-spec`, `code-exploration-spec`
    and `design-exploration-spec`, and the four differ by whether there is a
    question with a right answer, a space to map, a codebase to read, or options
    to compare.
  - **`general` is the fallback, never the way to avoid choosing.** Reach for it
    only when you have read the list and nothing fits, and say in one line what
    it did not fit, since that is how a missing type gets noticed.

- **Confirm in one line before writing** ("Creating a *launch-plan* spec — sound
  right?"). One line, not a menu: the user corrects a wrong pick faster than they
  answer a question about it.

**Is it a child spec?** A child spec is a full spec of its own that records
which spec it belongs to: its own id, its own URL, its own status, its own
review cycle. What it is for is one area of a larger spec that has grown enough
to be read on its own — the code grounding behind a design, the research it
rests on, the testing strategy that follows from it.

Pass `--parent <id>` when the user asks for one, in either of the two ways they
arrive:

- **In the request.** "Write a design spec for X, with a child spec for the code
  grounding" is two creates, the second carrying `--parent` with the first's id.
- **In a review comment.** A comment on a parent asking for a child is answered
  by making one and replying with its id and URL. See the `review-spec` skill.

Do **not** reach for one unasked. Splitting a spec is the user's call about how
they want to read it, and a design that is 900 words does not need a child spec
for its testing section. The type is still chosen from the list above and on the
same rules: a child is not a kind of spec, it is a spec with a parent.

A child takes its parent's project and collection unless you pass your own, so
it is filed beside the spec it belongs to rather than wherever the home page was
pointing.
- Read the house rules: `${CLAUDE_PLUGIN_ROOT}/templates/house-rules.md`.
- Read the component rules: `${CLAUDE_PLUGIN_ROOT}/references/spec-components.md`
  — keep its **Choosing** table (top of the file) in context; read an individual
  component's entry when that component is used (grep the file for its heading),
  not before. Pick by what a block
  **asserts**, never by how it should look. Its **Drawing** section is the choice
  between the three ways to draw; read it before writing any diagram, because the
  cheapest option and the most powerful one are different choices:
  - a graph (flowchart, sequence, state, ER, class) is
    `<pre data-lang="mermaid">`, and states the relationships rather than any
    coordinates;
  - a picture where exact placement carries meaning is inline SVG;
  - a comparison, peer items, or anything that must reflow is a table or a grid,
    not a diagram at all.

  Its **Interactive components** section covers the three blocks that respond to
  a reader (`<details class="disclosure">`, `.tabs`, `table.sortable`). Read it
  before reaching for one. All three are complete with no JavaScript, so write
  the content as though nothing will run; what they cost is a reader's attention,
  not their access. The disclosure is the safe one and the only one three
  document products ship natively. **Never put a section heading inside a
  disclosure** — a part of the argument behind a summary line is a part a reader
  misses, and the lint reports it.

## 2. Scaffold into the store

```
node "${CLAUDE_PLUGIN_ROOT}/lib/specforge-cli.mjs" create --title "<title>" --type <type> --model <your model id> [--project <name>] [--parent <id>]
```

**`--model` is your own model id**, exactly as your harness names it (for
example `claude-fable-5-1`, `gpt-6-astra`, `glm-5.3-flash`). The harness is
detected. Together they credit you as the spec's author, shown on the home page
row and in the spec's header as "✎ Claude · claude-fable-5-1". Leave it out
and the credit names only the harness.

If you are asked to **review** a spec rather than write one, this is the wrong
skill: `write-review` files the review as a child spec of the one you reviewed
and credits you as its reviewer.

Prints `{ id, htmlPath, url, status, type, project, parent, parentTitle, language, skeleton, prompts }`.
It has started/reused the daemon, copied the type's shell to `htmlPath`, and
attached the spec to this session. **Author into `htmlPath`** — that file IS the
spec — but do **not** read the whole file to find the blanks: the payload's
`skeleton` array lists every section with its id, line range, heading and
placeholder text. Fill sections one at a time: read the section's slice with

From NitinJ/specforge, MIT.

More from NitinJ/specforge