import-spec

/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.

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/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

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/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 existing)

Step 6: Stage Research Artifacts

Create the phase 1 directory and stage spec-kit research artifacts:

mkdir -p .shipyard/phases/1

If research.md exists: Copy it as the base:

cp <feature-path>/research.md .shipyard/phases/1/RESEARCH.md

If data-model.md exists: Append to RESEARCH.md with a section header:

---
## Data Model (from spec-kit)
[contents of data-model.md]

If contracts/ directory exists: List its files and append a summary section to RESEARCH.md:

---
## API Contracts (from spec-kit)
[brief summary of each contract file found, with the file path]

If none of research.md, data-model.md, or contracts/ exist: skip this step.

If tasks.md exists: Write a note file at .shipyard/phases/1/SPECKIT-TASKS.md with:

# spec-kit Tasks (seed input for architect)

> These tasks were generated by `/speckit.tasks` and are available as input when running `/shipyard:plan 1`.
> The architect agent will use these to seed task decomposition into Shipyard's wave/plan format.

[full contents of tasks.md]

Step 7: Commit & Update State

Create a git commit:

git add .shipyard/PROJECT.md
# Stage ROADMAP.md if created:
git add .shipyard/ROADMAP.md 2>/dev/null || true
# Stage phase research if created:
git add .shipyard/phases/ 2>/dev/null || true
git commit -m "shipyard: import spec-kit spec from <feature-path>"

Follow State Update Protocol (update .shipyard/STATE.json and .shipyard/HISTORY.md via state-write.sh; see docs/PROTOCOLS.md) -- update state:

• Phase: 1
• Position: Project definition imported from spec-kit, ready for planning
• Status: ready

Step 8: Route Forward

Display next step based on what was created:

If ROADMAP.md was created:

Import complete! Your next step:

Run /shipyard:plan 1 — Your project definition and roadmap are ready. Shipyard will use the staged research artifacts and spec-kit tasks to accelerate phase 1 planning.

If ROADMAP.md was NOT created:

Import complete! Your next step:

Run /shipyard:plan — This will generate a roadmap from your project definition, then plan the first phase. Staged research artifacts will be used automatically.

Always append this tip if tasks.md was staged:

Tip: spec-kit tasks have been staged at .shipyard/phases/1/SPECKIT-TASKS.md — the architect will use these as a seed when you run /shipyard:plan 1, so you'll get accurate task decomposition with less hallucination.