create-spec
/create-spec
Author a new house-style spec into the SpecForge store. Use when the user asks to "write a spec", "create a design doc", "draft a spec for <x>", "research <x>", "write a PRD / UX spec / test plan / launch plan / security review", or "plan to implement <x>". Reads the installed spec types and picks the one whose "when to use" line fits, then scaffolds that type's shell and authors its sections against the guidance it carries — light/dark HTML, stable section ids, a floating TOC; impl types also get a Stages/Tasks plan, a live task tracker, and impl-time stubs; general is the fallback when nothi
- Author
- NitinJ ↗
- Repository
- specforge ↗
- Licence
- MIT
- Last repository change
- 23.09.2026
Assessment and security
- Files in this package
- 1
- Scripts
- 0
- HTML comments
- 0
- URLs in SKILL.md
- 0
No signals detected. Repository changed on 23.09.2026, without references to retired models or APIs.
MIT, open: use and modify while retaining author attribution.
What it does and when to use it
Author a new house-style spec into the SpecForge store. Use when the user asks to "write a spec", "create a design doc", "draft a spec for <x>", "research <x>", "write a PRD / UX spec / test plan / launch plan / security review", or "plan to implement <x>". Reads the installed spec types and picks the one whose "when to use" line fits, then scaffolds that type's shell and authors its sections against the guidance it carries — light/dark HTML, stable section ids, a floating TOC; impl types also get a Stages/Tasks plan, a live task tracker, and impl-time stubs; general is the fallback when nothi
Triggers from the description
Original author description
Author a new house-style spec into the SpecForge store. Use when the user asks to "write a spec", "create a design doc", "draft a spec for <x>", "research <x>", "write a PRD / UX spec / test plan / launch plan / security review", or "plan to implement <x>". Reads the installed spec types and picks the one whose "when to use" line fits, then scaffolds that type's shell and authors its sections against the guidance it carries — light/dark HTML, stable section ids, a floating TOC; impl types also get a Stages/Tasks plan, a live task tracker, and impl-time stubs; general is the fallback when nothi
How it works
- 1. Understand the request + pick the type
- 2. Scaffold into the store
- 3. Author from the shell — sections by type
- 3.5 Language (read before writing prose)
- 4. The gate — loop until it passes
- 5. Hand off + arm review delivery
SKILL.md preview
---
name: create-spec
user-invocable: false
description: |
Author a new house-style spec into the SpecForge store. Use when the user asks to
"write a spec", "create a design doc", "draft a spec for <x>", "research <x>",
"write a PRD / UX spec / test plan / launch plan / security review", or "plan to
implement <x>". Reads the installed spec types and picks the one whose "when to
use" line fits, then scaffolds that type's shell and authors its sections against
the guidance it carries — light/dark HTML, stable section ids, a floating TOC;
impl types also get a Stages/Tasks plan, a live task tracker, and impl-time
stubs; general is the fallback when nothing fits and the sections come from the
use case. Lints the universal basics before done.
allowed-tools: Read, Write, Edit, Bash, Glob, Grep
---
# 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
`spec-nav section <id> --spec "<htmlPath>"`, edit in place between the section's
existing tags, then move to the next. The style block, the TOC and the section
ids never need re-reading; the `verify` gate checks TOC sync and section ids
either way.
**Most types arrive with their sections already in place.** The shell you get is
that type's own: its headings, its table of contents, its `{{ … }}` placeholders.
When that is what you find, the section set is decided and your job is to fill it,
not to redesign it. Only `general` arrives with nothing but a TL;DR, because
choosing the sections is what that type is for.
**`language` is the writing contract in force, and it is the whole of it.** Not a
note added to a contract you read somewhere else: it already contains SpecForge's
own rules, unless this store's owner edited or removed them. Follow what it says and nothing it does not.
Do not go looking for `references/spec-language.md` to supplement it: a rule the owner deleted is deleted,
and reading the shipped file behind their back reinstates it. They edit this in the Configuration pane,
under Language.
**Read `prompts` before you write.** Each entry is `{ section, text }`: authoring
guidance the spec type attaches to one section, written by the user into the
template and stripped out of your copy so a reader never sees it. It is
instruction, not content — follow it when you write that section. Open questions
and Decisions carry one on most types, because those are the two sections review
corrects most.
**Projects.** With no `--project`, the spec is filed into whichever project the
home page is showing, which is usually what the user means: they are working
inside that body of work. Pass it explicitly only when the request names a
different one, or when the spec plainly belongs elsewhere — and say where it went
in the one-line confirmation, since the default is invisible otherwise. Use
`--project ""` to file it nowhere. A project that does not exist yet is created
by using its name.
The shell comes from the store's per-type **template spec** (`template-<type>`,
listed under Templates on the index) when one exists, else the bundled file. To
change what future specs start from, edit the template spec like any other spec
(open `template-<type>` and edit its html). Never delete a template spec.
## 3. Author from the shell — sections by type
Replace every `{{ … }}` placeholder (`{{TITLE}}`, `{{DATE}}` = today YYYY-MM-DD,
`{{STATUS}}` = `draft`, `{{OWNER}}`).
**If the shell already carries this type's sections, they are the skeleton.** The
`prompts` from `create` say what belongs in each one, and the skeletons below are
for the types that do not ship with their own: read them as an example of the
shape, not as a list to impose on a scaffold that already has one. Adding, cutting
or reordering a shipped type's sections is a decision worth making, not a default:
they are what makes that type worth having, and the type's rules are written
against them.
Whatever sections you end up with:
- **Keep every `<section>` with a stable, unique `id`** (anchors + comments depend
on them). Keep the theme CSS (light/dark vars, `[data-theme]`,
`prefers-color-scheme`, `--maxw`) — the review layer drives theme + width.
- **Leave the stamped component block alone.** The shell's `<style>` opens with
`/* specforge:components v1 start */ … /* specforge:components end */`. It is
generated; editing it is refused by `components sync` and overwritten by the
next build. Your own rules go after it and win. Use the library's classes
rather than restyling them: a notice is `<div class="callout decision">`, never
`<div class="callout warn">`.
- **Color only via the canonical palette tokens** (`--bg --panel --panel2 --ink
--muted --line --accent --green --amber --red --code --shadow --mono`) — the lint
requires them and the review-layer theme variants re-tint by overriding exactly
these. Don't invent per-spec color names (`--card`, `--ecru`, …); derive any tint
with `color-mix(... var(--token) …)`. See `templates/house-rules.md` → Palette tokens.
- **Keep `<nav class="toc">` as the floating left sidebar** and keep its
`<a href="#…">` entries in sync with the sections you end up with.
**general** — the shell ships `tldr` and nothing else, because the sections are
the use case's to decide. Work out what this document needs before you write it
(a proposal wants context / proposal / impact / decision; a postmortem wants
timeline / impact / root cause / actions; a runbook wants preconditions / steps /
rollback), then author those sections with stable kebab-case ids, add one TOC link
per section in document order, and stop. Do not import another type's skeleton
wholesale. If the document turns out to need stages and tasks, it is a
design-impl or impl spec: say so and rescaffold rather than growing a plan here.
**design** — `tldr` · `overview` (problem / motivation) · `goals` (goals &
non-goals) · `design` (the core: architecture, components, alternatives,
tradeoffs — use panels / tables / diagrams) · `decisions` · `open-questions`.
No build plan.
**research** — repurpose the doc shell's sections: `tldr` (headline finding) ·
`question` (objective) · `background` · `method` (scope + sources consulted) ·
`findings` (the bulk, organized by sub-question; cite evidence) · `analysis`
(synthesis) · `recommendations` · `open-questions` (gaps) · `sources`. Rename the
section headings + ids accordingly and update the TOC to match.
**design-impl** (impl shell) — author `tldr` · `overview` · `goals` · `design` ·
`decisions` · `open-questions`, then build `impl-plan` as Stages → Tasks using the
`data-sf-stage` / `data-sf-task` / `data-sf-status` markup (one stage = one PR,
each task a `verify:` note) and mirror it into the `task-tracker` snapshot table.
Leave `impl-decisions` / `deviations` / `tradeoffs` as the empty stubs — or the
`runtime` section holding them, depending on the template. They are filled during
implementation, and each entry has one fixed card shape and a fixed set of bold
labels: the section's own prompt carries it, and so does
`specforge doc house-rules`.
**impl** (impl shell) — keep the design prose light: `tldr` · `overview` (scope +
link to the design if it lives elsewhere) · a brief `design` (prerequisites /
context). Focus on `impl-plan` (Stages → Tasks) + the `task-tracker` snapshot, and
keep the Runtime stubs. Trim `goals` / `decisions` if they add nothing.
## 3.5 Language (read before writing prose)
Specs follow a language contract, and **`language` from step 2 is that contract**.
Read it there, in full, before you write a sentence of the spec. It is short.
There is no summary of it here on purpose. This store's owner edits these rules,
and a summary would go on stating a rule after they had deleted it: a rule that
is gone from the contract has nothing left to contradict a copy of itself.
## 4. The gate — loop until it passes
```
node "${CLAUDE_PLUGIN_ROOT}/lib/specforge-cli.mjs" verify <id> --json
```
**The spec is not finished until this exits 0.** It is a gate, not a report: run
it, fix what it names, run it again, repeat.
On FAIL it returns `failing`, and every entry says what is wrong and what to do:
- `kind: "check"` — a function found a defect. **Fix the spec.**
- `kind: "judge"` — no function can answer this one. **Read the spec against
it.** If the spec satisfies it, name it in `--judged` on the next run. If it
does not, fix the spec.
```
node "${CLAUDE_PLUGIN_ROOT}/lib/specforge-cli.mjs" verify <id> --judged tldr-matches-body,decisions-have-reasons
```
`--judged` is your word, and it lasts one run — nothing is stored, so the next
run asks again. A rule it does not recognise fails the gate rather than being
ignored, so a typo cannot quietly settle nothing. A judged id never papers over a
`check` defect: claiming to have judged a broken spec still fails.
**Judge in a subagent if your harness can run one**, handing it only the spec
path and the rules to judge. A fresh reader judges a document more honestly than
its author, and the author is you: an agent that has just written a spec is the
party least able to notice its TL;DR overclaims. If your harness has no subagent,
judge them yourself, reading the spec from the top as though you had not written
it.
**At most three rounds.** An agent that cannot satisfy a rule in three attempts
is usually failing to understand the rule rather than the spec. If you run out,
hand over and say in one line which rules still fail — do not judge a rule you do
not believe just to reach 0.
`advisories` are reported and never block. `spec-language` is one of them: the
mechanically detectable slice of the contract, as code. Being code, it reports
the rules SpecForge ships whatever this store's contract now says, so read a hit
against `language` before acting on it, and clear the ones that contract still
asks for. It cannot see register at all, so a clean report is a floor, not a
pass.
The lint still exists and the gate is a superset of it; run
`node "${CLAUDE_PLUGIN_ROOT}/lib/lint-spec.mjs" <htmlPath>` only when you want
the mechanical checks alone.
## 5. Hand off + arm review delivery
- Print the spec `url` (open it to review). Edits to `htmlPath` live-reload.
- The spec is attached to this session. In Codex, finish the turn: lifecycle hooks
own the background watcher and deliver browser comments automatically. Do not
start a watcher or wait for comments in a tool call.
- For an explicit Codex pickup, run
`node "${CLAUDE_PLUGIN_ROOT}/lib/specforge-cli.mjs" review-wait` once. It checks
queued work and returns immediately. Follow `reason` when `ready` is true;
when `reason` is `next-turn`, finish without re-arming.
- In Claude Code, run that command as one background task per session and
re-arm it after handling delivered work. Pi owns delivery through its extension.
Versions
| Repository | Score | Licence |
|---|---|---|
| This page · NitinJ/specforge | 100 | MIT |
| jkaloger/lazyspec | 100 | MIT |
| sequenzia/agent-alchemy | 95 | MIT |
Database snapshot: 13.11.2026 · package version 364571f329fd (SHA-256 digest of the entire package)
Downloads in the last 30 days: 0 · ranking
Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.
Similar skills
- 100convert-spec
Convert an existing design/spec file into a SpecForge spec in the store. Use when the user asks to "convert <file> to a spec", "import this design doc", or "turn this markdown/HTML into a SpecForge spec". Handles two cases: an existing SpecForge-style .html is ingested as-is; a… - 100write-review
Review a SpecForge spec as a reviewer agent, and file the review as a child spec of the spec being reviewed. Use when asked to "review spec <id>", "critique this spec", "give a second opinion on <spec>", or when a workflow hands you a spec to review. Creates the review with… - 90specforge-project
Use when the user wants to build, create, plan, architect, scope, or spec a software project, app, platform, agent, API, tool, SaaS product, or major development feature. This skill requires routing development-project requests through the SpecForge tool before implementation. - 90write-product-spec
Use when a user asks for a product spec with invariants, a tech spec, or a PRD. Modes: product (default), technical, requirements. Not for task breakdown: use plan. - 100prd
Use this skill whenever a user asks to write a PRD, create a PRD, draft a PRD, spec out a feature, or create a one-pager. Triggers include: "write a PRD", "create a PRD", "draft a PRD", "PRD for [feature]", "spec out [feature]", "one pager for [feature]", or any request to… - 100write-spec
Write a feature spec or PRD from a problem statement or feature idea. Use when creating product requirements documents.