specforge-convert-spec

name	specforge:convert-spec
user-invocable	false
description	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 .md or freeform design doc is re-authored into a full house-style HTML spec. Attaches the result to this session and lints before finishing.
allowed-tools	Read, Write, Edit, Bash, Glob, Grep

convert-spec

Bring an existing file into the SpecForge store. ${CLAUDE_PLUGIN_ROOT} is the installed plugin directory.

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, or a freeform .html/design doc → re-author into a house-style spec (step 2B).
• 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). Default to design-impl when unsure. Pass it as --type below.

2A. Ingest an existing HTML spec

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

Prints { id, htmlPath, url, status, type } — the file is copied into the store, attached to this session, daemon ensured. Lint htmlPath (step 3). If lint fails because it isn't house-style, fall back to 2B (author into the same htmlPath).

2B. Re-author a design doc into a house-style spec

• Read the house rules: ${CLAUDE_PLUGIN_ROOT}/templates/house-rules.md.

• Scaffold a fresh store spec from the template:

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

  It prints { id, htmlPath, url, type }. Author into htmlPath.

• 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).

3. Lint (must pass)

node "${CLAUDE_PLUGIN_ROOT}/lib/lint-spec.mjs" <htmlPath>

Fix and re-run until PASS. Do not finish on a failing lint.

4. Hand off + arm the review watcher

• Print the spec url. The spec is attached to this session; browser review comments are delivered back here automatically. Mention the original file is left untouched (its path is recorded as the spec's origin).
• Arm the review watcher (once per session) so comments are picked up while you're idle. If it isn't already running this session, start it in the background: node "${CLAUDE_PLUGIN_ROOT}/lib/specforge-cli.mjs" wait-batch. On its { ready, pending } return, run review-spec for each pending spec then relaunch it; on timeout, just relaunch. One watcher covers every spec here.