spec-create

spec-create

Add ONE new spec to the project's spec set, then re-weave the index (markdown specs) or refresh the viewer manifest (pipeline-specs).

Mode selection — markdown spec vs pipeline-spec

Inspect $ARGUMENTS for --pipeline (or interpret intent: "pipeline", "flow chart", "workflow walkthrough", "visual diagram of how X moves").

• Markdown spec (default): grounded in symbols, anchored to code, lives in spec/<topic>.md, participates in the spec index + audit. Use the GitNexus preflight. Follow the rest of this file.
• Pipeline-spec (--pipeline): user-facing HTML walkthrough, lives in spec/pipelines/<topic>.html, exempt from spec-audit/spec-lint. Read ${CLAUDE_PLUGIN_ROOT}/skills/spec-create/_pipeline-mode.md and follow it instead of the markdown-spec process below. Without --pipeline, do NOT load that file.

Preconditions

• spec/INDEX.md must exist. If it doesn't → tell the user to run /adam:setup first and stop.
• CLAUDE.md must contain a spec index table. If it doesn't → same.
• The user must have specified (or implied) a topic. If unclear, ask.

Process — markdown spec (default)

1. Confirm the topic isn't already covered. Read every existing spec/*.md description; if there's a clear match, propose updating that spec instead.

2. Run the GitNexus preflight script to get a code-grounded briefing for the topic. Do not interpret these steps yourself; call the script.

   bash ${CLAUDE_PLUGIN_ROOT}/scripts/tools/spec-preflight.sh "<topic>" [path-hint ...]
   

   The script:

   • Verifies gitnexus is on PATH and that the current repo is indexed.
   • Calls gitnexus query for processes/definitions matching the topic.
   • Calls gitnexus context on the resulting symbols (plus any path hints the user passed).
   • Emits a single JSON briefing on stdout: {topic, repo, summary, candidates, search_processes, path_hints} where candidates[] contains {name, uid, kind, file, line, incoming, outgoing} for each symbol.

   Capture the JSON. If status != "ok" (gitnexus missing or repo unindexed), surface the error and stop — tell the user to run /adam:setup or gitnexus analyze. Do not delegate to the agent without a briefing.

3. Select a stack-specific seed so the new spec lands on the conventional layout for the project's framework. Do not interpret these steps yourself; call the script.

   bash ${CLAUDE_PLUGIN_ROOT}/scripts/template/select-seed.sh "$PWD"
   

   The script inspects package.json, pyproject.toml, requirements*.txt, and manage.py to detect the stack and emits JSON: {"stack": "<name>", "seed": "<absolute path>"} or {"stack": "unknown", "seed": null}. Currently shipped seeds: nextjs, hono, fastapi, django. If seed is null, skip the seed-injection paragraph in step 4 and fall back to the unseeded prompt.

4. Open the actual code the new spec will describe (use the briefing's primary_files as the read list) so the spec is grounded in real symbols/paths.

5. Delegate to the adam sub-agent, passing both the preflight briefing and (if available) the seed contents in one prompt:

   Add a new spec for <topic> to this project. The GitNexus preflight identified the following code structure — treat it as canonical, do not re-grep symbols already resolved here:

   <briefing JSON from step 2>
   

   Use the following stack-specific seed as your structural starting point — keep its section layout (anchors block, How-to recipe, conventions list), replace the <…> placeholders with concrete project values, and drop sections that don't apply. Do not invent sections that aren't in the seed; consistency across specs is part of how adam keeps the index readable.

   <contents of the seed file from step 3>
   

   Write spec/<topic>.md with standard frontmatter (name, description, tags, updated, anchors). Use the candidates[] list from the briefing to populate the anchors block — every entry there is a verified file:line:symbol triple. Then add a row to both spec/INDEX.md and the spec table in CLAUDE.md, picking the correct reading-order position. Run the spec-lint MCP and token-count MCP to verify and to fill the token column.

   If seed: null, drop the seed paragraph but keep the briefing paragraph.

6. Surface the agent's report.

Frontmatter for the new spec

---
name: <topic>
description: <one-line summary, used by future spec-create/update calls for relevance checks>
tags: [<a few>]
updated: YYYY-MM-DD
---

Use today's date. Tags should be the 2–4 closest topical labels (e.g. [backend, fastapi, auth]).

Reading-order placement

In INDEX.md and the CLAUDE.md table:

• overview.md always first.
• Major subsystem specs (backend, frontend, infrastructure) before integration / detail specs.
• Integration specs (one per external service) grouped together, after subsystem specs.
• Workflow / flowchart specs last.

Output format

Show the agent's final report to the user. Then one line:

If this concept replaces or overlaps with an existing spec, run /adam:spec-update to reconcile.

(Pipeline-spec mode has its own follow-up line — see _pipeline-mode.md.)