spec

What this skill does

# Create an OpenSpec Specification

You are creating or updating an OpenSpec specification. Every spec is a **paired artifact**: `spec.md` (requirements — what the system does) and `design.md` (architecture and rationale — how and why it does it).

**You MUST ALWAYS create or update BOTH files together. They are a single unit of truth. Never create, edit, or deliver one without the other.**

**When updating an existing spec, you MUST review the companion file for alignment.** If `spec.md` changes, read `design.md` and update it where the architectural decisions or rationale no longer reflect the updated requirements — and vice versa. The two files MUST remain internally consistent at all times.

When creating a new spec from scratch, both files are created together — alignment is automatic. The pairing review obligation applies to subsequent updates where one file may change without the other.

## Process

<!-- Governing: ADR-0016 (Workspace Mode), SPEC-0014 REQ "Artifact Path Resolution" -->

0. **Resolve artifact paths**: Follow the **Artifact Path Resolution** pattern from `references/shared-patterns.md` to determine the spec directory. If `$ARGUMENTS` contains `--module <name>`, resolve paths relative to that module. The resolved spec directory is referred to as `{spec-dir}` below.

1. **Determine the capability name**: Use kebab-case (e.g., `web-dashboard`, `webhook-trigger`). If converting from an ADR, derive from the ADR title. If `$ARGUMENTS` is empty (ignoring flags like `--review` and `--module`), use `AskUserQuestion` to ask the user what capability they want to specify.

2. **Check for existing directory**: If `{spec-dir}/{capability-name}/` already exists, use `AskUserQuestion` to ask whether to update the existing spec or choose a different name. If updating: read both the existing `spec.md` and `design.md` before making changes, then update both files maintaining alignment between them.

3. **Determine the next SPEC number**: Scan `{spec-dir}` for existing spec.md files, find the highest SPEC number used, and increment. SPEC numbers are formatted as `SPEC-XXXX` (e.g., SPEC-0001). Start at SPEC-0001 if none exist. **IMPORTANT**: The prefix is `SPEC-`, NOT `RFC-`. Do not confuse spec numbering with RFC 2119 (which is a language standard for requirements keywords).

3a. **qmd-aware edge pre-search** (v5.0.0+):

   <!-- Governing: ADR-0024 (qmd as hard dependency), SPEC-0019 REQ "qmd-Smart Authoring Skills" -->

   Before drafting, qmd-search the existing spec corpus to find related prior specs whose IDs SHOULD appear in the new spec's frontmatter as `requires`, `extends`, or `supersedes` edges. Also search ADRs to identify which ADRs the new spec should declare it `implements`.

   1. Construct a hybrid query per `references/qmd-helpers.md` § "Hybrid Retrieval":
      - `lex`: capability name + key technologies/concepts
      - `vec`: a one-sentence framing of what the new spec covers
      - `intent: "/sdd:spec — find related prior specs and governing ADRs to suggest as frontmatter edges"`
      - `collections: ["{repo}-specs", "{repo}-adrs"]` (or per-module variants per `qmd-helpers.md` § "This-Repo Collection Identification")
      - `limit: 8`, `minScore: 0.3`

   2. Classify each result above the threshold:
      - **requires** (spec → spec): the new spec depends on capability the matched spec provides
      - **extends** (spec → spec): the new spec is a behavioral extension of the matched spec
      - **supersedes** (spec → spec): the new spec replaces the matched spec
      - **implements** (spec → ADR): the new spec realizes the matched ADR's decision

   3. Surface candidate edges via `AskUserQuestion` BEFORE writing the file. Show each with the matched artifact's ID, title, and proposed edge classification. Options for each: "Include as `{edge}`", "Include as different edge", "Skip".

   4. If qmd returns zero results above the threshold, proceed without surfacing edge suggestions and emit: "No related specs or ADRs found — drafting from scratch."

   5. On qmd unreachable / timeout per `qmd-helpers.md` § "Error Handling", surface the error and stop. Per ADR-0024, no fallback in v5.

4. **Choose drafting mode**: Check if `$ARGUMENTS` contains `--review`.

   **Default (no `--review`)**: Single-agent mode. Research the codebase (read relevant files, understand the current architecture), draft both spec.md and design.md directly, self-review against the architect's checklist in the Rules section, then write both files.

   **With `--review`**: Team review mode.
   - Tell the user: "Creating a drafting team to write and review the spec. This takes a minute or two."
   - Create a Claude Team with `TeamCreate` to draft and review:
     - Spawn a **spec-writer** agent (`general-purpose`) to write both spec.md and design.md based on the user's description or ADR: `$ARGUMENTS`. **Remind the spec-writer that specs use `SPEC-XXXX` numbering, NOT `RFC-XXXX`.**
     - Spawn an **architect** agent (`general-purpose`) to review both documents for completeness, accuracy, RFC 2119 keyword compliance, and proper scenario format. **The architect MUST verify the spec uses `SPEC-XXXX` numbering, not `RFC-XXXX`.**
     - The architect MUST review and approve BOTH documents before they are finalized
     - If converting from an ADR, the spec-writer should read the ADR and use it as the basis
     - If `TeamCreate` fails, fall back to single-agent mode: draft both files directly, then self-review against the architect's checklist in the Rules section before writing.

4b. **Optional call graph generation** (v5.1.0+):

   <!-- Governing: ADR-0033 (cgg call graph integration), SPEC-0034 REQ "Call Graph Generation Uses cgg With Filtering" -->

   After requirements are authored (Step 4) and before writing to disk (Step 5), ask the user whether to generate call graphs showing the current implementation scope.

   **Opt-in prompt**: Use `AskUserQuestion` with the text:

   > Generate call graphs showing current implementation scope? (yes / no / skip)

   Default to **no** on timeout or in batch/non-interactive mode. If the user answers **no** or **skip**, skip this step entirely — spec.md and design.md are written without an `## Implementation` section. No error, no deviation.

   **When user answers yes**:

   1. **Availability check**: Run `which cgg >/dev/null 2>&1` per `references/cgg-integration.md` § "Availability Check". If cgg is not found, surface the one-line unavailability notice from that section and skip to Step 5 — write spec.md without an `## Implementation` section.

   2. **Extract requirement keywords**: For each `### Requirement:` section heading in the drafted spec.md, extract the requirement name (text after `### Requirement:`). Apply the **From requirement keywords** filter derivation from `references/cgg-integration.md` § "Filter Derivation Strategy":
      - Lowercase and split on spaces/punctuation
      - Strip common stop words
      - Compose a regex alternation from remaining terms (e.g., `payment|processing|token|validation`)

   3. **Find implementing code files via qmd**: Search the `{repo}-code` collection (or `{repo}-{module}-code` in workspace mode) using the requirement keywords as query terms. This surfaces the file paths most likely to implement each requirement.

   4. **Invoke cgg**: Use the invocation pattern from `references/cgg-integration.md` § "cgg Invocation Pattern":
      - Derive `--filter` by combining qmd file-path stems with requirement keyword terms per § "Filter Derivation Strategy" → "From qmd code matches"
      - Apply the 20-node cap and Mermaid normalization per § "Node cap" and § "Mermaid Output Normalization"
      - Handle all exit codes and degradation cases per § "Exit code handling" and § "Graceful Degradation"
      - In workspace mode, scope `<target-path>` to the module directory per § "Workspace-Mode Scoping"

   5. **Build the `## Implementation` section**: Append to the in-memory spec