convert-spec

Files (1)

• SKILL.md

SKILL.md (first lines)

# convert-spec

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

## 1. Inspect the source

- The user names a file (`$ARGUMENTS`). Read it and decide:
  - **Already a SpecForge-style HTML spec** (has the section ids / theme contract /
    structured plan) → ingest as-is (step 2A).
  - **A `.md`** → convert with `import-md`, then edit the result (step 2B). Do not
    hand-author a markdown source: the CLI does the mechanical part faithfully and
    reports what it could not read, which is a better starting point than a blank
    scaffold and your reading of the file.
  - **A freeform `.html` design doc** → author it into a scaffolded spec by hand
    (step 2C). There is no deterministic path for arbitrary HTML.
- **Infer the spec type** from the source — `research` (a findings report),
  `design` (a design doc, no plan), `design-impl` (design + a plan), or `impl` (a
  build plan). When the source is none of those, use `general`: the scaffold plus
  a TL;DR, sections taken from the source's own headings. Pass it as `--type`
  below. A converted document keeps its own shape, so `general` is the right
  answer more often here than when authoring from scratch.

## 2A. Ingest an existing HTML spec

```
node "${CLAUDE_PLUGIN_ROOT}/lib/specforge-cli.mjs" import "<file>" --title "<title>" --type <type> --model <your model id>
```

Prints `{ id, htmlPath, url, status, type, language }` — the file is copied into
the store, attached to this session, daemon ensured. **Apply `language` to
anything you write into this spec**, on the terms in 2B. Lint `htmlPath`
(step 3). If lint fails
because it isn't house-style, fall back to **2C** and author into the `htmlPath`
you already have; 2C says so too, and running `create` there would leave this
spec behind and attach a second one. Not 2B: that path runs a markdown parser,
and handing it HTML would mechanically reconvert the document instead of shaping
it.

## 2B. Convert a `.md` — deterministic pass first, then edit

**A markdown source is converted by the CLI, not by hand.** It reads the file,
maps its headings onto sections, rebuilds any plan into the `data-sf-*` markup,
inlines the images that sit beside it, and produces a lint-passing spec:

```
node "${CLAUDE_PLUGIN_ROOT}/lib/specforge-cli.mjs" import-md "<file>" --model <your model id> [--title "<title>"] [--type <type>]
```

`--model` is your own model id; the harness is detected. It credits you as the
converted spec's author, the same way `create` does.

It prints `{ id, htmlPath, url, type, status, language, report }`. **Then edit
`htmlPath`** — the deterministic pass gives you a valid document to improve,
never a blank scaffold to fill.

**`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,
and apply it to everything you write while improving the converted document.
Do not go looking for `references/spec-language.md` to supplement it: a rule the owner deleted is deleted.
They edit this in the Configuration pane, under Language.

Read the `report` before you touch anything; it is the list of what needs you:

- **`unsupported`** — constructs the parser could not read (setext headings,
  footnotes, reference links), each with its line number. The content is in the
  spec as plain text; convert it to house markup by hand.
- **`assetsDropped`** — images that were not inlined, with the reason (missing,
  too large, outside the source directory). Say so when you hand off.
- **`lint`** — `PASS` normally. If it is `FAIL`, `lintFailures` names the checks.
- **`sections`** — how many the source produced.

Type: omit `--type` and the import is a **`general`** spec, which imposes no
section set — usually right, because a converted document keeps its own shape.
Pass `--type` only when the source really is a design / research / impl doc.

Then improve the result:

- Read the house rules: `${CLAUDE_PLUGIN_ROOT}/templates/house-rules.md`, and the
  language contract, which is the `language` field above rather than a file.
  This is where an original's essay voice leaks through: convert the content, not
  the register.
- Map the source onto the type's sections exactly as the `create-spec` skill
  describes (design / research / design-impl / impl) — adapt sections to the
  content; keep stable unique ids, the theme, and the floating TOC in sync. For
  impl types build `impl-plan` as Stages → Tasks (`data-sf-stage`/`data-sf-task`/
  `data-sf-status`, one stage = one PR, each task a `verify:` note) mirrored into
  `task-tracker`, and leave the Runtime stubs. Preserve the author's intent; don't
  invent scope.
- Keep every `<section id="…">`, the theme CSS, and the floating `<nav class="toc">`
  (update TOC links to match the sections you keep).

For a spec `general` no longer fits (the source turned out to be a design with a
build plan), rescaffold with `create --type <type>` and move the content across;
do not grow a plan inside a general spec and call it typed.

## 2C. Author a freeform HTML doc into a spec

Arbitrary HTML has no deterministic path: it carries someone else's structure and
styling, and there is nothing to map it onto mechanically. It gets authored.

**Arriving from 2A** (an HTML spec that turned out not to be house-style): you
already have an `htmlPath` in the store, attached to this session. **Author into
that file.** Do not run `create` — it would make a second spec and leave the
malformed one attached, so a later edit or handoff could pick up either. The
`language` 2A printed still applies: this is the authoring pass it was for.

**Arriving from step 1** with a freeform HTML doc and no spec yet, scaffold one:

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

It prints `{ id, htmlPath, url, type, language }`. **Author into `htmlPath`**,
following the same house rules, section mapping and language contract as 2B
above, and applying `language` on the same terms.

From NitinJ/specforge, MIT.

More from NitinJ/specforge