/init

description: "Initialize Shipyard project settings and directory structure"
disable-model-invocation: true
argument-hint: "[--fresh] — start over with a fresh .shipyard/ directory"

/shipyard:init - Project Initialization

You are executing the Shipyard initialization workflow. Follow these steps precisely and in order.

<prerequisites>

Step 1: Check Existing State

Check if a `.shipyard/` directory already exists in the current project root.

• **If it exists AND `.shipyard/config.json` exists:** Read existing config.json values. These become the pre-filled defaults shown in Step 3 (in parentheses after each option). Proceed to Step 2 — the user may want to change any or all settings.

• **If `--fresh` flag is provided:** Require explicit confirmation from the user before proceeding. If confirmed, rename `.shipyard/` to `.shipyard-archive-{YYYY-MM-DD}/` and create a fresh `.shipyard/` directory (no pre-filled defaults). If not confirmed, stop.

• **If `.shipyard/` does not exist:** Create the `.shipyard/` directory and proceed to Step 2.

Step 2: Lightweight Project Detection

Determine whether this is a **brownfield** (existing source code) or **greenfield** (empty/new project) by checking for source files and package manifests (e.g., `package.json`, `go.mod`, `Cargo.toml`, `requirements.txt`, `*.py`, `*.ts`, `*.go`, `*.rs`, etc.).

Also check if `docs/codebase/` exists and contains `.md` files. If it does, this means a previous `/shipyard:map` was run and committed — store this as `detected_codebase_path = "docs/codebase"` for use in Step 4.

This is used to tailor next-steps guidance in Step 5 and to set a smart default for `codebase_docs_path` — no codebase mapping or analysis is performed.

</prerequisites>

<execution>

Step 3: Collect Settings

Collect workflow preferences from the user using three `AskUserQuestion` calls. Each call stays within the 4-question limit. Wait for the user's answers before proceeding to the next batch.

Batch 1: Workflow Preferences

Use `AskUserQuestion` with these 3 questions:

1. **Interaction style** — "Do you prefer interactive mode or autonomous mode?"

• `Interactive (Recommended)` — Approve each phase before execution. Safer for unfamiliar codebases.
• `Autonomous` — Execute full roadmap with checkpoints. Faster for well-defined projects.

2. **Git tracking** — "How should Shipyard create commits?"

• `Per task (Recommended)` — Atomic commit after each completed task. Easy to review and revert.
• `Per phase` — Batch all task changes into one commit per phase. Cleaner history.
• `Manual` — Shipyard won't commit. You control all git operations.

3. **Review depth** — "How thorough should review gates be?"

• `Detailed (Recommended)` — Two-stage review (spec compliance + code quality) between build steps.
• `Lightweight` — Quick verification only. Faster but catches fewer issues.

Batch 2: Quality Gates

Use `AskUserQuestion` with these 4 questions:

4. **Security auditing** — "Should Shipyard run a security audit after each phase build?"

• `Yes (Recommended)` — OWASP checks, secrets detection, dependency vulnerabilities. Recommended for production projects.
• `No` — Skip security auditing. You can still run `/shipyard:audit` manually.

5. **Code simplification** — "Should Shipyard check for duplication and complexity after each phase?"

• `Yes (Recommended)` — Detects AI-generated bloat, dead code, and over-engineering. Recommended for AI-heavy workflows.
• `No` — Skip simplification review. You can still run `/shipyard:simplify` manually.

6. **IaC validation** — "Should Shipyard validate infrastructure-as-code files (Terraform, Ansible, Docker)?"

• `Auto (Recommended)` — Validate only when IaC files are detected in the changeset.
• `Always` — Run IaC validation on every phase regardless.
• `Never` — Skip IaC validation entirely.

7. **Documentation generation** — "Should Shipyard generate documentation after each phase build?"

• `Yes (Recommended)` — Auto-generate and update docs after each phase. Keeps documentation current.
• `No` — Skip documentation generation. You can still run `/shipyard:document` manually.

Batch 3: Storage, Model & Context Preferences

Use `AskUserQuestion` with these 3 questions:

8. **Codebase docs location** — "Where should Shipyard store codebase analysis docs?"

• `.shipyard/codebase (Recommended)` — Keeps analysis in the local `.shipyard/` directory (gitignored by default).
• `docs/codebase` — Stores in the project's `docs/` directory so analysis is committed and shared with the team.

If a `docs/codebase/` directory with `.md` files was detected in Step 2, note this to the user and default to `docs/codebase`.

9. **Model routing** — "Which model routing strategy should Shipyard use for its agents?"

• `Default routing (Recommended)` — Haiku for validation, Sonnet for building/review/planning/auditing/simplification/documentation/mapping, Opus for architecture/debugging. Balances cost and quality.
• `All Sonnet` — Use Sonnet for everything. Good balance of speed and capability.
• `All Opus` — Use Opus for everything. Maximum quality, highest cost.

10. **Context loading** — "How much project context should Shipyard load at session start?"

• `Auto (Recommended)` — Adjusts based on current state (minimal when idle, full during execution).
• `Minimal` — Always load minimal context. Fastest startup, less awareness.
• `Full` — Always load everything including codebase docs. Slowest startup, maximum awareness.

Step 4: Write Configuration & State

After collecting all answers, write the following files:

config.json

Write `.shipyard/config.json` with the user's choices. Map answers to config keys:

• Batch 1: `interaction_mode` (`"interactive"` / `"autonomous"`), `git_strategy` (`"per_task"` / `"per_phase"` / `"manual"`), `review_depth` (`"detailed"` / `"lightweight"`)
• Batch 2: `security_audit` (`true` / `false`