@selvakumaresra/specship 0.1.3 → 0.4.0

package/dist/workflows/defaults/claude-design-implement.yaml

@@ -0,0 +1,336 @@
+name: claude-design-implement
+description: Import a Claude Design (live URL or a designer handoff bundle) — snapshot + tokens + source record — draft the spec, gate at review, write the spec — ready to hand off to /ss-implement.
+tags: [spec, ui, claude-design, default]
+requires: [specship, git]
+
+# Worktree isolation: the spec draft and snapshot live in the user's
+# working tree (not the worktree) so the artifacts survive the run,
+# but the worktree gives the spec author a clean diff to review and
+# means a rejected run leaves no half-written specs/<slug>.md.
+worktree:
+  enabled: true
+
+# Two entry shapes (provide exactly one source):
+#   - CONNECTOR_URL  — a live claude.ai/design URL (the `/ss-design-implement`
+#     command). The snapshot node fetches it, preferring the `designer` MCP.
+#   - HANDOFF_DIR    — a designer handoff bundle already on disk (the
+#     `/ss-design-loop` command, after the human-tasted loop + designer_handoff).
+#     The snapshot node reads files straight from the bundle — no fetch, no CDP.
+# Optional inputs default to "" (see the CLI's declared-default handling), so a
+# `$INPUT.X` reference to an omitted optional input resolves to "" rather than
+# throwing — that is what lets a single snapshot node branch on whichever
+# source was supplied.
+inputs:
+  - name: CONNECTOR_URL
+    description: A live Claude Design URL (https://claude.ai/design/p/<id>/?file=<name>.html). Provide this OR HANDOFF_DIR.
+    required: false
+    default: ""
+  - name: HANDOFF_DIR
+    description: Path to a designer handoff bundle (artifacts/<key>/handoff-<ts>/) containing project/ + decision-record.md. Provide this OR CONNECTOR_URL.
+    required: false
+    default: ""
+  - name: CHOSEN_FILE
+    description: When importing from HANDOFF_DIR, the variant filename inside project/ to spec (e.g. "dashboard.html"). Omit if the bundle has a single obvious file.
+    required: false
+    default: ""
+  - name: FILE_LABEL
+    description: Human label for the imported file (e.g. "Data Flow")
+    required: true
+  - name: SLUG
+    description: Kebab-case directory name under specs/ (e.g. "data-flow")
+    required: true
+  - name: OWNER
+    description: Spec owner — used in frontmatter when set
+    required: false
+    default: ""
+  - name: PRIORITY
+    description: high / medium / low — used in frontmatter when set
+    required: false
+    default: ""
+
+systemPromptAppend: |
+  You are implementing a Claude Design import for SpecShip.
+
+  The fidelity principle: never paraphrase or summarise design content
+  when capturing it. The snapshot HTML and tokens.css are the
+  zero-loss reference layer; the spec captures contract only (behaviour,
+  accessibility, responsive, interaction states, data shape).
+
+  There are two import shapes — exactly one source input is non-empty:
+    - HANDOFF_DIR set → read the design files straight off disk from the
+      designer handoff bundle. No network, no CDP, no MCP fetch.
+    - CONNECTOR_URL set → pull the live design. Prefer the `designer`
+      MCP (it reads the real rendered HTML over CDP); a plain fetch of a
+      claude.ai/design URL returns only a ~1 KB loader shell.
+
+  Either way: save the source byte-for-byte to specs/$INPUT.SLUG/snapshot.html.
+  Never edit the snapshot during this workflow.
+
+nodes:
+  - id: snapshot
+    kind: prompt
+    output_type: snapshot_summary
+    allowed_tools:
+      - Read
+      - Write
+      - Bash
+      - mcp__specship__specship_explore
+      - mcp__specship__specship_search
+      - mcp__specship__designer_snapshot
+      - mcp__specship__designer_handoff
+    prompt: |
+      File label:   $INPUT.FILE_LABEL
+      Slug:         $INPUT.SLUG
+      Handoff dir:  $INPUT.HANDOFF_DIR
+      Chosen file:  $INPUT.CHOSEN_FILE
+      Source URL:   $INPUT.CONNECTOR_URL
+
+      Goal: snapshot the Claude Design source into specs/$INPUT.SLUG/
+      so the rest of the workflow has a zero-loss reference layer.
+
+      Exactly one of "Handoff dir" or "Source URL" above is non-empty.
+      If BOTH are empty, stop and report the error — there is nothing to
+      import. Pick the branch by which one is set.
+
+      1. Create the directory `specs/$INPUT.SLUG/` if it doesn't exist.
+
+      ── BRANCH A — Handoff dir is set (preferred; reads disk, no fetch) ──
+
+      A1. Locate the chosen design file inside the bundle:
+          - If "Chosen file" is set, use `$INPUT.HANDOFF_DIR/project/$INPUT.CHOSEN_FILE`.
+          - Else list `$INPUT.HANDOFF_DIR/project/`: if there is exactly one
+            top-level `.html`, use it; if several, STOP and report the
+            candidate filenames, asking the caller to re-run with CHOSEN_FILE.
+      A2. Copy that file BYTE-FOR-BYTE to `specs/$INPUT.SLUG/snapshot.html`
+          (use `cp`, do not re-render). Copy any CSS / JS / asset files it
+          references from `project/` alongside it.
+      A3. Write `specs/$INPUT.SLUG/source.md` as the import audit record,
+          then APPEND the bundle's decision record verbatim — it is the
+          richest provenance you have (every prompt + reply + the human's
+          final reaction):
+
+          ```markdown
+          # $INPUT.FILE_LABEL — Claude Design import (handoff bundle)
+
+          **Imported:** <today's date in YYYY-MM-DD>
+          **Handoff bundle:** $INPUT.HANDOFF_DIR
+          **Chosen file:** <the file you copied>
+
+          **Snapshot:** snapshot.html (byte-for-byte capture)
+          **Tokens:** tokens.css (extracted CSS custom properties)
+
+          ## Design decision record (verbatim)
+
+          <full contents of $INPUT.HANDOFF_DIR/decision-record.md, copied in
+          unchanged — if that file is missing, say so here>
+          ```
+
+      ── BRANCH B — Source URL is set (live fetch) ──
+
+      B1. Fetch the design content from $INPUT.CONNECTOR_URL. Try in order:
+            a. The `designer` MCP — `mcp__specship__designer_snapshot`
+               (reads the real rendered HTML over CDP from inside the
+               cross-origin preview iframe). This is the only path that
+               reliably returns the real design for a claude.ai/design URL.
+            b. Any other Claude Design MCP connector tool in this session
+               (look for `mcp__*design*`), or the `figma-implement-design`
+               / `figma-use` skill if loaded.
+            c. A direct `curl` of the URL, as a last resort (warning: for
+               claude.ai/design this usually returns only a loader shell).
+          Save the FULL rendered HTML byte-for-byte to
+          `specs/$INPUT.SLUG/snapshot.html`. Do NOT filter, summarise, or
+          re-format. Save any linked CSS / asset files alongside.
+      B2. Write `specs/$INPUT.SLUG/source.md` with the import audit record:
+
+          ```markdown
+          # $INPUT.FILE_LABEL — Claude Design import
+
+          **Imported:** <today's date in YYYY-MM-DD>
+          **Connector URL:** $INPUT.CONNECTOR_URL
+          **Project ID:** <extracted from the URL — the segment after /p/>
+          **File:** $INPUT.FILE_LABEL
+
+          **Snapshot:** snapshot.html (byte-for-byte capture)
+          **Tokens:** tokens.css (extracted CSS custom properties)
+
+          **Original prompt:**
+          > Import this Claude Design project: $INPUT.CONNECTOR_URL
+          > Implement: $INPUT.FILE_LABEL
+          ```
+
+      ── BOTH BRANCHES ──
+
+      4. Extract CSS custom properties + literal token-like values
+         (colors, spacing, font sizes, radii, transitions) from the
+         snapshot to `specs/$INPUT.SLUG/tokens.css`. Use
+         `specship_explore` first to find the project's existing token
+         system — if a value in the snapshot matches an existing
+         project token, map it by name instead of duplicating.
+
+      Output: a ≤250-word summary covering:
+        - Which branch ran and the file captured.
+        - Snapshot structure (top-level layout, key components).
+        - Token mapping (which match existing project tokens, which are
+          new and added to tokens.css).
+        - Any visible interaction or state cues in the CSS (`:hover`,
+          `:focus`, `:disabled`, `[aria-*]` selectors) the spec
+          author should be aware of.
+        - For Branch A: note that source.md carries the verbatim decision
+          record — the draft step should mine it for stated behaviour.
+
+  - id: draft_spec
+    kind: prompt
+    depends_on: [snapshot]
+    output_type: spec_markdown
+    allowed_tools:
+      - Read
+      - mcp__specship__specship_explore
+      - mcp__specship__specship_search
+      - mcp__specship__specship_node
+      - mcp__specship__specship_spec
+    prompt: |
+      Use the spec-author skill (~/.claude/skills/spec-author/SKILL.md
+      and its references/) to draft a SpecShip-compatible spec for the
+      Claude Design import. Inputs available on disk:
+
+        - specs/$INPUT.SLUG/snapshot.html  (visual + structural source)
+        - specs/$INPUT.SLUG/tokens.css     (design tokens)
+        - specs/$INPUT.SLUG/source.md      (audit record)
+
+      Spec scope: $INPUT.FILE_LABEL component(s).
+      Optional inputs: owner=$INPUT.OWNER  priority=$INPUT.PRIORITY
+      (an empty value means "not provided" — use "[needs review]").
+
+      If `source.md` contains a "Design decision record (verbatim)"
+      section (a handoff-bundle import), READ IT FIRST and mine it for
+      contract: interaction states, failure modes, data shapes, and the
+      human's stated intent are often spelled out in that transcript.
+      Prefer what the record states over guessing; reserve [needs review]
+      for items genuinely absent from both the snapshot and the record.
+
+      Cover, as separate REQs:
+        - Behavioural contract (what the component renders, given what data).
+        - Each visible state (default, hover, focused, pressed, disabled,
+          loading, error, empty) — derive from the CSS, gap-fill the rest.
+        - Accessibility (keyboard nav, ARIA roles, focus order, contrast,
+          screen-reader behaviour).
+        - Responsive behaviour (breakpoints by name, not pixels).
+        - Data shape + failure-mode contracts.
+        - Performance contract (initial render budget, interaction
+          latency, if applicable).
+
+      DO NOT put exact hex colors, pixel values, font names, or animation
+      durations in the spec. Reference design tokens by name
+      (`MUST use the --error color token`). The values themselves live
+      in tokens.css.
+
+      Embed the import-source record in the spec's frontmatter so the
+      spec carries its provenance:
+
+      ```yaml
+      ---
+      id: <SLUG-DOC>
+      title: <FILE_LABEL>
+      owner: <OWNER or "[needs review]">
+      priority: <PRIORITY or "[needs review]">
+      source: specs/<SLUG>/source.md
+      snapshot: specs/<SLUG>/snapshot.html
+      tokens: specs/<SLUG>/tokens.css
+      ---
+      ```
+
+      Output: the full Markdown body of the proposed spec
+      (with frontmatter, embedded `<!-- id: -->` markers, RFC 2119
+      keywords, acceptance bullets with .A1/.A2 IDs). DO NOT write
+      it to disk yet — the next node is a review gate.
+
+  - id: gap_review
+    kind: approval
+    depends_on: [draft_spec]
+    message: |
+      Spec draft ready for $INPUT.FILE_LABEL.
+
+      Walk the [needs review] markers and gap-fill questions, then
+      approve to write the file. Reject with feedback to revise.
+
+      ─────── DRAFT ───────
+      $draft_spec.output
+    capture_response: true
+    on_reject:
+      prompt: |
+        The draft was rejected with this feedback. Revise the spec
+        per the feedback; keep ALL existing REQ IDs stable so any
+        downstream tracking survives the rewrite.
+
+        Feedback:
+        $gap_review.output
+
+        Current draft:
+        $draft_spec.output
+
+        Output the revised draft.
+      max_attempts: 3
+
+  - id: write_spec
+    kind: prompt
+    depends_on: [gap_review]
+    output_type: file_path
+    allowed_tools:
+      - Write
+      - Read
+      - Bash
+    prompt: |
+      Write the approved spec to `specs/$INPUT.SLUG.md` using the Write
+      tool. The spec content is the DRAFT below; the reviewer's gate
+      response carries the gap-fill answers / edits to fold in.
+
+      APPROVED DRAFT (this is the spec to write):
+      $draft_spec.output
+
+      REVIEWER GATE RESPONSE (gap-fill answers / edits — apply these,
+      resolving any `[needs review]` markers the reviewer answered; if it
+      is just "approved" with no substantive content, write the draft as
+      is):
+      $gap_review.output
+
+      Rules:
+        - Write the full spec Markdown (frontmatter + REQ bodies +
+          acceptance bullets), NOT the reviewer's comment verbatim.
+        - Resolve `[needs review]` markers the reviewer answered; leave
+          any they didn't as `[needs review]`.
+        - Keep ALL existing REQ IDs stable.
+        - If `specs/$INPUT.SLUG.md` already exists (re-importing an
+          iteration), APPEND new requirements instead of overwriting and
+          preserve existing REQ IDs. Tell the user explicitly what you did.
+
+      Then run:
+        specship sync
+
+      Output: the relative path of the file written + the first REQ
+      ID (e.g. "REQ-DATA-FLOW-001") so the next step can hand it to
+      /ss-implement.
+
+  - id: handoff
+    kind: prompt
+    depends_on: [write_spec]
+    output_type: handoff_message
+    allowed_tools:
+      - Read
+    prompt: |
+      The spec is now indexed. Output a short hand-off message for the
+      user with EXACTLY these elements:
+
+        1. The path of the spec file: `specs/$INPUT.SLUG.md`.
+        2. The full list of REQ IDs the spec defines, one per line.
+        3. The reference files the implementation phase should read:
+             - specs/$INPUT.SLUG/snapshot.html
+             - specs/$INPUT.SLUG/tokens.css
+             - specs/$INPUT.SLUG/source.md
+        4. The exact next command:
+             /ss-implement <first REQ ID>
+        5. A one-line reminder that the implementation step should
+           load the snapshot for visual fidelity — the spec covers
+           contract only.
+
+      Keep the message ≤200 words. The user is about to switch from
+      this workflow to the implement workflow; this is the bridge.

package/dist/workflows/defaults/index.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Bundled default workflows.
+ *
+ * Workflow YAMLs are stored as `.yaml` files in this directory and
+ * compile-time embedded by reading them at build time. We don't use a
+ * code-generator (matches the rest of the codebase that avoids generated
+ * files); instead, the build's `copy-assets` script copies the .yaml
+ * files into `dist/workflows/defaults/`, and this module reads them at
+ * import time from `__dirname`.
+ *
+ * Bundled workflows (v1):
+ *   - spec-implement.yaml   — implement an unimplemented spec
+ *   - spec-fix.yaml         — fix a drifted / broken link
+ *   - spec-verify.yaml      — run verification across `implemented` links
+ *   - spec-relink.yaml      — re-attach an orphaned link
+ *
+ * See workflow-discovery.ts for the three-tier precedence model.
+ */
+export interface BundledWorkflow {
+    /** Filename stem (no .yaml extension). */
+    name: string;
+    /** Raw YAML source. */
+    yaml: string;
+}
+export declare const bundledDefaults: BundledWorkflow[];
+//# sourceMappingURL=index.d.ts.map

package/dist/workflows/defaults/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/workflows/defaults/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAKH,MAAM,WAAW,eAAe;IAC9B,0CAA0C;IAC1C,IAAI,EAAE,MAAM,CAAC;IACb,uBAAuB;IACvB,IAAI,EAAE,MAAM,CAAC;CACd;AASD,eAAO,MAAM,eAAe,EAAE,eAAe,EAAmB,CAAC"}

package/dist/workflows/defaults/index.js

@@ -0,0 +1,94 @@
+"use strict";
+/**
+ * Bundled default workflows.
+ *
+ * Workflow YAMLs are stored as `.yaml` files in this directory and
+ * compile-time embedded by reading them at build time. We don't use a
+ * code-generator (matches the rest of the codebase that avoids generated
+ * files); instead, the build's `copy-assets` script copies the .yaml
+ * files into `dist/workflows/defaults/`, and this module reads them at
+ * import time from `__dirname`.
+ *
+ * Bundled workflows (v1):
+ *   - spec-implement.yaml   — implement an unimplemented spec
+ *   - spec-fix.yaml         — fix a drifted / broken link
+ *   - spec-verify.yaml      — run verification across `implemented` links
+ *   - spec-relink.yaml      — re-attach an orphaned link
+ *
+ * See workflow-discovery.ts for the three-tier precedence model.
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.bundledDefaults = void 0;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+/**
+ * Lazy-loaded bundled defaults from `<dist|src>/workflows/defaults/*.yaml`.
+ * Populated on first read. Always re-reads from disk in tests where the
+ * file set may have been mutated; production callers call once at startup.
+ */
+let cached = null;
+exports.bundledDefaults = loadDefaults();
+function loadDefaults() {
+    if (cached)
+        return cached;
+    const out = [];
+    let entries;
+    try {
+        entries = fs.readdirSync(__dirname, { withFileTypes: true });
+    }
+    catch {
+        cached = [];
+        return cached;
+    }
+    for (const entry of entries) {
+        if (!entry.isFile())
+            continue;
+        const lower = entry.name.toLowerCase();
+        if (!lower.endsWith('.yaml') && !lower.endsWith('.yml'))
+            continue;
+        try {
+            const yaml = fs.readFileSync(path.join(__dirname, entry.name), 'utf-8');
+            const stem = entry.name.replace(/\.(ya?ml)$/i, '');
+            out.push({ name: stem, yaml });
+        }
+        catch {
+            // Skip unreadable files; discovery will surface the gap on next load.
+        }
+    }
+    cached = out;
+    return cached;
+}
+//# sourceMappingURL=index.js.map

package/dist/workflows/defaults/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/workflows/defaults/index.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;GAiBG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAEH,uCAAyB;AACzB,2CAA6B;AAS7B;;;;GAIG;AACH,IAAI,MAAM,GAA6B,IAAI,CAAC;AAE/B,QAAA,eAAe,GAAsB,YAAY,EAAE,CAAC;AAEjE,SAAS,YAAY;IACnB,IAAI,MAAM;QAAE,OAAO,MAAM,CAAC;IAC1B,MAAM,GAAG,GAAsB,EAAE,CAAC;IAClC,IAAI,OAAoB,CAAC;IACzB,IAAI,CAAC;QACH,OAAO,GAAG,EAAE,CAAC,WAAW,CAAC,SAAS,EAAE,EAAE,aAAa,EAAE,IAAI,EAAE,CAAC,CAAC;IAC/D,CAAC;IAAC,MAAM,CAAC;QACP,MAAM,GAAG,EAAE,CAAC;QACZ,OAAO,MAAM,CAAC;IAChB,CAAC;IACD,KAAK,MAAM,KAAK,IAAI,OAAO,EAAE,CAAC;QAC5B,IAAI,CAAC,KAAK,CAAC,MAAM,EAAE;YAAE,SAAS;QAC9B,MAAM,KAAK,GAAG,KAAK,CAAC,IAAI,CAAC,WAAW,EAAE,CAAC;QACvC,IAAI,CAAC,KAAK,CAAC,QAAQ,CAAC,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,QAAQ,CAAC,MAAM,CAAC;YAAE,SAAS;QAClE,IAAI,CAAC;YACH,MAAM,IAAI,GAAG,EAAE,CAAC,YAAY,CAAC,IAAI,CAAC,IAAI,CAAC,SAAS,EAAE,KAAK,CAAC,IAAI,CAAC,EAAE,OAAO,CAAC,CAAC;YACxE,MAAM,IAAI,GAAG,KAAK,CAAC,IAAI,CAAC,OAAO,CAAC,aAAa,EAAE,EAAE,CAAC,CAAC;YACnD,GAAG,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC;QACjC,CAAC;QAAC,MAAM,CAAC;YACP,sEAAsE;QACxE,CAAC;IACH,CAAC;IACD,MAAM,GAAG,GAAG,CAAC;IACb,OAAO,MAAM,CAAC;AAChB,CAAC"}

package/dist/workflows/defaults/spec-author.yaml

@@ -0,0 +1,214 @@
+name: spec-author
+description: Author a new spec. Draft → gap-fill review → quality review → final approval → write file.
+tags: [spec, default]
+requires: [specship, git]
+
+# Worktree isolation isn't strictly needed for spec authoring (no code
+# changes) — but enabling it keeps the artifact directory under the same
+# umbrella the other spec workflows use, and a future expansion that adds
+# example-code touches stays safe.
+worktree:
+  enabled: true
+
+inputs:
+  - name: DESCRIPTION
+    description: One-line description of the feature you want to spec
+    required: true
+  - name: PARENT_DOC
+    description: Optional spec ID of an existing doc to attach the new requirements under
+    required: false
+  - name: OWNER
+    description: Owner team or person (e.g. "security", "payments-team")
+    required: false
+  - name: PRIORITY
+    description: high / medium / low
+    required: false
+
+systemPromptAppend: |
+  You are authoring a SpecShip-compatible Markdown spec. Use the
+  spec-author skill loop and references throughout this workflow.
+  The output of every node should be markdown that is ready for the
+  next stage — do NOT write the file until the `write_file` node.
+
+nodes:
+  - id: ground
+    kind: prompt
+    output_type: code_grounding
+    allowed_tools:
+      - mcp__specship__specship_explore
+      - mcp__specship__specship_search
+      - mcp__specship__specship_files
+      - Read
+    prompt: |
+      Feature: $INPUT.DESCRIPTION
+
+      Walk the codebase to find where this feature would live:
+
+      1. Use specship_explore on terms drawn from the description to
+         surface relevant existing symbols.
+      2. Note any existing conventions, similar features, or shared
+         primitives the new spec should align with.
+      3. List candidate file paths + qualified symbol names that the
+         new implementation might touch — these become the `implementations:`
+         block of the spec.
+
+      If this is greenfield (no relevant existing code), say so explicitly
+      and propose a target directory under src/ where the implementation
+      will live.
+
+      Output: a ≤300-word grounding report — paths, conventions, and
+      candidate symbols. Do NOT write the spec yet.
+
+  - id: draft
+    kind: prompt
+    depends_on: [ground]
+    output_type: spec_draft
+    allowed_tools:
+      - mcp__specship__specship_spec
+      - mcp__specship__specship_explore
+      - mcp__specship__specship_node
+      - Read
+    prompt: |
+      Feature: $INPUT.DESCRIPTION
+      Optional parent doc: $INPUT.PARENT_DOC
+      Optional owner: $INPUT.OWNER
+      Optional priority: $INPUT.PRIORITY
+
+      Code grounding:
+      $ground.output
+
+      Produce a complete first-draft Markdown spec following the spec-author
+      skill's `references/format.md`:
+
+      - YAML frontmatter with id/title/owner/priority (use the inputs if
+        provided; mark as `[needs review]` if not).
+      - Embedded `<!-- id: -->` markers above every heading.
+      - RFC 2119 keyword (MUST / SHOULD / MAY) in each requirement title.
+      - One concern per requirement.
+      - `## Acceptance` section with bulleted criteria, each carrying its
+        own `.A<N>` ID. Cover both happy path and failure path.
+      - Optional `implementations:` block, populated from the grounding
+        report (or empty for greenfield).
+      - Wherever the description doesn't tell you something, insert a
+        `[needs user confirmation]` marker — DO NOT invent.
+
+      Output: the full spec markdown, ready for the gap-fill review.
+
+  - id: gap_review
+    kind: approval
+    depends_on: [draft]
+    message: |
+      Draft is ready. The gap-fill questions below identify areas the
+      description didn't cover. Approve with answers (e.g. "owner: security,
+      TTL: 1h, on non-existent email: 200 OK"), or reject with feedback to
+      revise.
+
+      Draft:
+      $draft.output
+
+      Gap-fill questions for THIS draft — walk references/gap-questions.md
+      and surface only the unanswered ones (max 5):
+      [the agent fills these in based on the draft above]
+    capture_response: true
+    on_reject:
+      prompt: |
+        The draft was rejected with this feedback. Revise the draft to
+        address it. Keep all existing IDs stable so any pre-existing links
+        survive.
+
+        Feedback:
+        $gap_review.output
+      max_attempts: 3
+
+  - id: incorporate
+    kind: prompt
+    depends_on: [gap_review]
+    output_type: spec_draft
+    allowed_tools:
+      - Read
+    prompt: |
+      Apply the gap-fill answers to the draft. Replace `[needs user
+      confirmation]` markers with the user's answers where given; leave
+      others as `[needs review]` if they explicitly skipped.
+
+      Draft:
+      $draft.output
+
+      Answers:
+      $gap_review.output
+
+      Output: the updated spec markdown.
+
+  - id: quality_review
+    kind: prompt
+    depends_on: [incorporate]
+    output_type: review_findings
+    allowed_tools:
+      - mcp__specship__specship_explore
+      - mcp__specship__specship_node
+      - mcp__specship__specship_search
+      - Read
+    prompt: |
+      Run the spec-author skill's `references/review-checklist.md` against
+      this draft and produce a structured findings list.
+
+      Updated draft:
+      $incorporate.output
+
+      Group findings into STRUCTURAL (blocks the file write), QUALITY (block
+      on critical, warn on minor), HYGIENE (warn only). For each, give:
+      line number, what's wrong, suggested fix. Don't be polite — sharp
+      signal is more useful than soft language.
+
+      If any STRUCTURAL findings exist, propose a corrected version of the
+      affected sections inline.
+
+  - id: finalize
+    kind: approval
+    depends_on: [quality_review]
+    message: |
+      Quality review complete. Approve to write the spec file, or reject to
+      revise further.
+
+      Review:
+      $quality_review.output
+
+      Final draft:
+      $incorporate.output
+    capture_response: true
+    on_reject:
+      prompt: |
+        Final approval was rejected. Revise the draft per the feedback,
+        re-run the quality review pass, and produce a new draft.
+
+        Feedback:
+        $finalize.output
+
+        Current draft:
+        $incorporate.output
+      max_attempts: 2
+
+  - id: write_file
+    kind: prompt
+    depends_on: [finalize]
+    output_type: file_path
+    allowed_tools:
+      - Write
+      - Read
+      - Bash
+    prompt: |
+      Write the approved spec to disk.
+
+      Final draft:
+      $incorporate.output
+
+      Use the `Write` tool to create `specs/<slug>.md` at the project root,
+      where `<slug>` is derived from the feature name (kebab-case, no date
+      prefix). If a file with that name already exists, APPEND the new
+      requirements to it (preserving any pre-existing content) instead of
+      overwriting; the user will resolve the merge in review.
+
+      After writing:
+      - Run `specship sync` to index the new spec.
+      - Output the relative path of the file written + a one-line note
+        about what to do next (typically: `/ss-implement <REQ-ID>`).