/import-spec

name: import-spec
description: Import a spec-kit feature spec into Shipyard, replacing brainstorming. Use when a spec-kit feature directory exists with spec.md.
argument-hint: "[feature-path] — path to spec-kit feature directory (e.g. specs/003-chat-system)"

/shipyard:import-spec - Import spec-kit Artifacts

You are executing the Shipyard spec-kit import workflow. This replaces `/shipyard:brainstorm` when you have already created a spec using spec-kit. Follow these steps precisely.

<prerequisites>

Step 1: Parse Argument

• If an argument is provided, use it as the feature path (e.g., `specs/003-chat-system`).
• If no argument is provided, check if a `specs/` directory exists in the project root.
• If `specs/` exists and contains subdirectories: use `AskUserQuestion` to present the available feature directories and ask the user to choose one.
• If `specs/` does not exist or is empty: tell the user: "No spec-kit feature directory found. Provide the path as an argument: `/shipyard:import-spec specs/<feature-name>`" and stop.

Step 2: Validate Prerequisites

1. Verify `.shipyard/` directory exists. If not, tell the user to run `/shipyard:init` first, then stop. 2. Verify the feature path exists and contains `spec.md`. If `spec.md` is missing, tell the user: "spec.md not found in `<feature-path>`. Run `/speckit.specify` first to generate the feature spec." and stop. 3. Inventory which artifacts exist — note which are present for use in later steps:

• `<feature-path>/spec.md` (required)
• `<feature-path>/plan.md` (optional — used for ROADMAP.md generation)
• `<feature-path>/research.md` (optional — copied to phase RESEARCH.md)
• `<feature-path>/data-model.md` (optional — appended to RESEARCH.md)
• `<feature-path>/contracts/` directory (optional — summarized into RESEARCH.md)
• `<feature-path>/tasks.md` (optional — seeded into architect input at plan time)
• `.specify/memory/constitution.md` (optional — added to PROJECT.md constraints)

Step 3: Check Existing PROJECT.md

If `.shipyard/PROJECT.md` already exists, use `AskUserQuestion` to ask: > "A project definition already exists in `.shipyard/PROJECT.md`. What would you like to do?"

• `Replace with spec-kit import (Recommended)` — overwrite PROJECT.md with the imported spec content
• `Merge — update requirements section only` — keep existing PROJECT.md but replace the Requirements section with spec-kit user stories
• `Cancel` — stop

</prerequisites>

<execution>

Step 4: Map spec.md -> .shipyard/PROJECT.md

Read `<feature-path>/spec.md` and extract the following to write `.shipyard/PROJECT.md`:

**Mapping rules:**

• **Project Name**: extract the feature name from the spec's `# Feature Specification: [NAME]` heading or the directory name
• **Description**: synthesize a 1-2 paragraph description from the spec's user story context and purpose
• **Goals**: each user story (US1, US2, US3...) becomes a numbered goal in priority order (P1 first)
• **Non-Goals**: look for any explicit exclusions in the spec; if none present, write "Not yet defined"
• **Requirements (Functional)**: expand each user story's acceptance scenarios into concrete requirements, grouped by user story
• **Non-Functional Requirements**: extract any performance, security, or scale constraints mentioned
• **Success Criteria**: map each user story's "Independent Test" description into a success criterion
• **Constraints**: note any `[NEEDS CLARIFICATION]` markers as open questions; if `.specify/memory/constitution.md` exists, extract relevant principles as technical constraints

**Handle `[NEEDS CLARIFICATION]` markers:** If spec.md contains unresolved `[NEEDS CLARIFICATION: ...]` markers, list them in a `## Open Questions` section at the bottom of PROJECT.md and notify the user: "The imported spec has N unresolved clarification items — see Open Questions in PROJECT.md."

**Write `.shipyard/PROJECT.md`** using this structure:

# [Project Name]

## Description
[1-2 paragraphs]

## Goals
1. [Goal from US1 — P1]
2. [Goal from US2 — P2]
...

## Non-Goals
- [explicit exclusions or "Not yet defined"]

## Requirements

### [User Story 1 Title]
- [requirement derived from acceptance scenario 1]
- [requirement derived from acceptance scenario 2]

### [User Story 2 Title]
...

## Non-Functional Requirements
- [extracted constraints]

## Success Criteria
- [from US1 Independent Test]
- [from US2 Independent Test]

## Constraints
- [from constitution.md principles, if present]
- [technical constraints from plan.md, if present]

## Open Questions
- [any [NEEDS CLARIFICATION] items from spec.md]

Step 5: Generate ROADMAP.md

Check if `.shipyard/ROADMAP.md` already exists.

**If plan.md exists (and ROADMAP.md does not exist or user chose Replace):**

Follow **Model Routing Protocol** (select the correct model for each agent role using `model_routing` from config; see `docs/PROTOCOLS.md`) -- read `model_routing` from config for architect model selection.

Dispatch an **architect agent** (subagent_type: `"shipyard:architect"`) with:

• The full content of `<feature-path>/plan.md`
• The just-written `.shipyard/PROJECT.md`
• Instruction: "Generate `.shipyard/ROADMAP.md` from this spec-kit implementation plan. Decompose the plan into logical phases (1-3 phases typical). Each phase should represent a coherent milestone. Do not break into tasks — only phases with titles and descriptions."

Present the roadmap to the user for approval. Allow up to **2 revision cycles**. After approval, finalize.

**If plan.md does not exist:** Offer to dispatch the architect with PROJECT.md alone (same as `/shipyard:brainstorm` step 5). Ask: "No plan.md found. Generate a roadmap from the project definition alone?"

• `Yes` — dispatch architect with PROJECT.md
• `Not now` — skip; user can run `/shipyard:plan` later which will generate ROADMAP.md

**If ROADMAP.md already exists:** Ask: "ROADMAP.md already exists. Replace it using plan.md?" (Yes / Keep exist