Skip to content
Skills Library
Management & product · Planning

shipwright-plan

/shipwright-plan

Creates detailed implementation plans from spec files via research, interview, external LLM review, and TDD approach. Generates section-based plans for /shipwright-build.\nTRIGGER when: user wants to plan implementation, create an implementation plan, break down a spec into sections, plan how to build something, create a technical design, generate build sections, or plan test strategy for a spec.\nDO NOT TRIGGER when: user asks to implement or write code (/shipwright-build), run tests (/shipwright-test), fix a bug or make a small change (/shipwright-iterate), deploy (/shipwright-deploy), defin

Repository
shipwright ↗
Licence
MIT
Last repository change
27.10.2026

Assessment and security

95/ 100Class: good
Format20 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
16
Scripts
0
HTML comments
0
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 27.10.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What it does and when to use it

Creates detailed implementation plans from spec files via research, interview, external LLM review, and TDD approach. Generates section-based plans for /shipwright-build.\nTRIGGER when: user wants to plan implementation, create an implementation plan, break down a spec into sections, plan how to build something, create a technical design, generate build sections, or plan test strategy for a spec.\nDO NOT TRIGGER when: user asks to implement or write code (/shipwright-build), run tests (/shipwright-test), fix a bug or make a small change (/shipwright-iterate), deploy (/shipwright-deploy), defin

Original author description

Creates detailed implementation plans from spec files via research, interview, external LLM review, and TDD approach. Generates section-based plans for /shipwright-build.\nTRIGGER when: user wants to plan implementation, create an implementation plan, break down a spec into sections, plan how to build something, create a technical design, generate build sections, or plan test strategy for a spec.\nDO NOT TRIGGER when: user asks to implement or write code (/shipwright-build), run tests (/shipwright-test), fix a bug or make a small change (/shipwright-iterate), deploy (/shipwright-deploy), defin

How it works

  1. CRITICAL: First Actions
  2. Step 0: Phase Session Context Recovery
  3. Step 1: Research
  4. Step 2: Interview
  5. Step 3: Context Check
  6. Step 4: Plan Writing
  7. Step 5: External LLM Review (Default + Fallback)
  8. Step 6: Section Splitting
  9. Step 7: Section Validation
  10. Step 8: E2E Test Plan (Shipwright Enhancement — Optional)
Original SKILL.md headings · 295 lines, 1,513 words
SKILL.md preview
---
name: shipwright-plan
description: "Creates detailed implementation plans from spec files via research, interview, external LLM review, and TDD approach. Generates section-based plans for /shipwright-build.\nTRIGGER when: user wants to plan implementation, create an implementation plan, break down a spec into sections, plan how to build something, create a technical design, generate build sections, or plan test strategy for a spec.\nDO NOT TRIGGER when: user asks to implement or write code (/shipwright-build), run tests (/shipwright-test), fix a bug or make a small change (/shipwright-iterate), deploy (/shipwright-deploy), define requirements (/shipwright-project), or design UI mockups (/shipwright-design)."
license: MIT
compatibility: Requires uv (Python 3.11+), git repository recommended. Recommended: OPENROUTER_API_KEY for GLM + OpenAI review; OPENAI_API_KEY can run the GPT arm only. An internal review (model resolved via the `plan_review` role — inherit unless a project configures it) always runs first; if external keys are missing, the skill asks whether to skip and rely on that internal review.
---
# Shipwright Plan Skill
Creates detailed, section-based implementation plans from spec files.
Enhanced fork of deep-plan with E2E test plan generation and sprint tracking.

---

## CRITICAL: First Actions

**Governing rules:** Read and follow `shared/constitution.md` (ALWAYS /
ASK FIRST / NEVER boundaries).

**BEFORE using any other tools**, run [first-actions.md](references/first-actions.md)
in order:

- **A.** Print Intro Banner
- **B.** Validate Input — stop if `@spec.md` missing/invalid
- **C.** Detect Invocation Mode — resolve via `get_phase_context.py
  --phase-task-id "{phaseTaskId}" --phase plan`; store `mode` as `invocation_mode`
  (`pipeline`|`standalone`|`error`→STOP). Token is authority, never re-derive from run state. [first-actions](references/first-actions.md).
- **C2.** Load Project Context (MANDATORY): `CLAUDE.md`,
  `.shipwright/agent_docs/conventions.md`, `decision_log.md`,
  `architecture.md`, and `git log --oneline -10`. WARN on missing
  files; never silently skip.
- **D.** Discover Plugin Root — prefer `SHIPWRIGHT_PLUGIN_ROOT` env
  injected by the SessionStart hook; otherwise `find` for
  `setup-planning-session.py`.
- **D2.** Run Setup Script
  (`{plugin_root}/scripts/checks/setup-planning-session.py`).
  Parse JSON: `success == true` → proceed; `mode == "resume"` →
  jump to `resume_from_step`; `success == false` → stop.
- **E.** Load Config (`{plugin_root}/config.json` plus per-session
  overrides under `{planning_dir}/shipwright_plan_config.json`).
  Write the **early in-progress plan config** via
  `write-plan-config.py --status in_progress` so a mid-flight
  handoff still works.
- **F.** Print Session Report (mode / spec / planning_dir /
  external_review status / E2E flag / resume-from).

Full text — banners, scripts, every CLI arg — in
[first-actions.md](references/first-actions.md). The agent reads that
on-demand when it lands here.

---

## Step 0: Phase Session Context Recovery

See [step-0-context-recovery.md](references/step-0-context-recovery.md).

If the orchestrator handed you a `phaseTaskId` (you were dispatched as a
phase-runner subagent by `/shipwright-run`), run
`shared/scripts/tools/get_phase_context.py --phase-task-id <id>` as your very
first action, then read every artifact in the returned `skill_artifacts_to_read`
list before proceeding. No `phaseTaskId` → standalone invocation, continue
with Step 1.

---

## Step 1: Research

See [research-protocol.md](references/research-protocol.md) for detailed guidance.

**Goal:** Understand the codebase, existing patterns, and technical landscape.
Read the spec thoroughly; explore an existing codebase's structure and
patterns, or review comparable ones for a new project; web-search unfamiliar technologies.

**Checkpoint:** Mental model formed. No file written — research informs all subsequent steps.

---

## Step 2: Interview

See [interview-protocol.md](references/interview-protocol.md) for detailed guidance.

**Goal:** Surface design decisions, constraints and preferences — adaptive
questions on architecture / data model / UX; clarify ambiguities; find risks.

**Checkpoint:** Write `{planning_dir}/shipwright_plan_interview.md` with full transcript.

**Write interview decisions to decision_log.md** for every
architecture/design decision that goes beyond what the profile or
project interview already decided (e.g. ORM vs raw SQL, component
library variants, caching, API patterns):

```bash
uv run "{plugin_root}/../../shared/scripts/tools/write_decision_log.py" \
  --section "Plan Interview — {split_name}" --commit "n/a" \
  --context "{why}" --decision "{what}" \
  --consequences "{impact}" --rejected "{alternatives}"
```

---

## Step 3: Context Check

See [context-check.md](references/context-check.md) for detailed guidance.

**Goal:** Before writing the plan, assess if context window is getting large.

```bash
uv run --project {plugin_root} {plugin_root}/scripts/checks/check-context-decision.py
```

If context is large: summarize research findings first; or write a brief outline for user approval before continuing.

---

## Step 4: Plan Writing

See [plan-writing.md](references/plan-writing.md) and
[tdd-approach.md](references/tdd-approach.md) for guidance.

**Goal:** Write the implementation plan as prose with TDD approach.

**Plan structure:** overview of approach; section breakdown with
SECTION_MANIFEST; per section goals, implementation steps and test strategy;
cross-cutting concerns. Manifest format — incl. how a section declares what
it presupposes — in [section-index.md](references/section-index.md).

**Checkpoint:** Write `{planning_dir}/plan.md` with SECTION_MANIFEST block.

---

## Step 5: External LLM Review (Default + Fallback)

Full branch logic: [step-5-external-review.md](references/step-5-external-review.md)
(Step 5-int-arch procedure: [step-5-int-arch.md](references/step-5-int-arch.md));
underlying protocol: [external-review.md](references/external-review.md).

**This step is NOT optional.** Two internal reviews always run first, in order
(Step 5-int, then Step 5-int-arch); then one of three branches must run to
completion, and `{planning_dir}/external_review_state.json` must be written.
Step 6 is gated on both.

**Step 5-int (always, first, incl. its Codex-driver "Dispatch rule"):** spawn
`shipwright-plan:opus-plan-reviewer` over `plan.md` + `spec.md`; triage every
finding fix/disclose/decline (reason required; scope-ratchet guard) — a
declined/disclosed `severity: high` finding STOPs and asks the user before
Step 6, per `gate_catalog.json`. Write `## Internal Plan Review` to `plan.md`
(`Ran: yes|no`; replace in place on retry), log to `decision_log.md`. On
failure record `Ran: no` and continue; the **Pre-5b Checkpoint** decides
whether the Self-Review Fallback runs.

**Step 5-int-arch (always, right after 5-int; spawned, or run via the `architecture_internal` Codex role under a real Codex CLI driver):** a
separate fresh-context agent, spawn
`shipwright-plan:architecture-internal-reviewer` over a freshly-authored
architecture brief + `spec.md` — **never `plan.md`**, to escape the plan's
own reasoning frame. Same triage rule as Step 5-int, own gate id
(`plan.architecture-internal-review-high-severity-declined`). Write `##
Internal Architecture Review` to `plan.md`, log to `decision_log.md`. **Does
not carry the Pre-5b gate** — only Step 5-int or a completed Branch A review
count there. Then read `external_review_status` from the session report
(First Actions > F) and branch on its value:

- **Branch A — `available`:** run `external_review.py --mode plan --driver <claude|codex> ...`
  (resolved per `CODEXTENDER_ACTIVE`, never hardcoded — see `external-review.md`;
  GLM+OpenAI/GLM+Opus in parallel), integrate findings, log each to `decision_log.md`. Read `contradiction.requires_resolution` first — put any
  disagreement to the user, never proceed on the approving review alone. Then
  **Step 5a**: a second call, `--mode architecture` over a short brief
  *instead of* the plan, asking what no other pass asks — should this be
  built at all; `reject` STOPs before Step 6. Then the Pre-5b Checkpoint.
- **Branch B — `missing_keys`:** STOP. Ask user verbatim (Option 1: add key +
  retry → Branch A; Option 2: skip — Step 5-int's `Ran:` value decides the
  fallback, per the Pre-5b Checkpoint). Do NOT proceed until chosen.
- **Branch C — `user_disabled`:** print the disabled notice, then the
  Pre-5b Checkpoint.

After exactly one branch completes, the **Pre-5b Checkpoint** runs the
Self-Review Fallback if neither Step 5-int nor Branch A produced a completed
independent review, then **Step 5b** writes the marker with
`{shared_root}/scripts/checks/mark-review-state.py` — `--status`,
`--provider`, `--findings-count`, `--reason`, one
`--verdict {glm|openai}={verdict}` per reviewer,
`--contradiction-resolution` when they disagreed, and
`--self-review-fallback-ran` when the checkpoint ran it. Exact invocation:
[step-5-external-review.md](references/step-5-external-review.md).

**Checkpoint:** `{planning_dir}/external_review_state.json` exists and records
a state clear to proceed past — the same question the resume gate and
compliance `W5` ask, through one shared evaluator.

---

## Step 6: Section Splitting

**Gate — run it, don't eyeball it:**

```bash
uv run --project {plugin_root} {plugin_root}/scripts/checks/check-plan-gates.py \
  --planning-dir "{planning_dir}" --project-root "$(pwd)" --gate review
```

Non-zero exit = STOP. It fails when Step 5 left no marker, or the marker
records a reviewer disagreement nobody decided. Return to Step 5, pick the
branch or record the decision, then re-run. The resume gate and compliance
`W5` apply the same rule through the same function.

See [section-splitting.md](references/section-splitting.md) for protocol.

**Goal:** Split plan into self-contained section files for /shipwright-build:
parse SECTION_MANIFEST, generate section tasks, then per section spawn the
section-writer subagent or write it directly.

**Batch approach (recommended for 3+ sections):**
```bash
uv run --project {plugin_root} {plugin_root}/scripts/checks/generate-batch-tasks.py \
  --planning-dir "{planning_dir}"
```

Each section file is written **by the `shipwright-plan:section-writer` subagent
itself** (it has a Write tool); `write-section-on-stop.py` is a non-blocking
salvage fallback, and Step 7 is the gate. Every section needs a
`Requirements:` line, `## Overview`, ≥2 `## Implementation Steps` and
`## Tests First` — Step 9 fails without them. Details: [section-splitting.md](references/section-splitting.md).

**Checkpoint:** All section files exist in `{planning_dir}/sections/`.

---

## Step 7: Section Validation

```bash
uv run --project {plugin_root} {plugin_root}/scripts/checks/check-sections.py \
  --planning-dir "{planning_dir}"
```

Verifies two things: every section declared in SECTION_MANIFEST has a file,
and the numbering agrees with the dependencies each section declares
(`03-api: 01-auth, 02-database`). A prerequisite numbered after the section
that needs it lands in `order_errors` and exits non-zero. Format: [section-index.md](references/section-index.md).

---

## Step 8: E2E Test Plan (Shipwright Enhancement — Optional)

See [e2e-test-plan.md](references/e2e-test-plan.md) for guidance.

**Runs if** `e2e_test_plan.enabled` is true, OR no config exists and the
project has a UI (HTML mockups under `.shipwright/designs/screens/`, or
`component_library` set in the profile — default on for UI projects).

**Goal:** Generate a Playwright E2E test plan — user-facing flows (login, CRUD, navigation), scenarios with expected outcomes, POM suggestions.

**Checkpoint:** Write `{planning_dir}/claude-plan-e2e.md`.

---

## Step 9: Completion

See [step-9-completion.md](references/step-9-completion.md) for the full procedure; after section validation and before completion, refresh planned paths via `uv run "{shared_root}/scripts/tools/area_catalog.py" seed-greenfield --project-root "$(pwd)" --source plan`. The
checklist and the C1+C2+C3+C4 + `phase_history` canon block (C5 skipped by policy: plan is internal decomposition, not user-facing).

**Verification gates (all must pass) — 11 gates + a boundary check, full
list and commands in [step-9-completion.md](references/step-9-completion.md):**

```bash
uv run --project {plugin_root} {plugin_root}/scripts/checks/check-plan-gates.py \
  --planning-dir "{planning_dir}" --project-root "$(pwd)" --plugin-root {plugin_root} --gate sections
uv run --project {plugin_root} {plugin_root}/scripts/checks/check-plan-gates.py \
  --planning-dir "{planning_dir}" --project-root "$(pwd)" --gate boundary
```

Non-zero exit on either = STOP. `_validate_plan` re-runs gates #5-8 above
leniently (warns, doesn't block, on pre-existing splits) but never #9-11 or
the boundary check — details in step-9-completion.md. This is the only
strict, complete run; fix what it names now rather than counting on that backstop.

**Phase complete:** set `SHIPWRIGHT_RUN_ID`, then run
`write-plan-config.py --status complete`, `record_event.py`,
`update_build_dashboard.py`, `generate_session_handoff.py --canon-marker`,
`append_phase_history.py`, `orchestrator.py update-step --step plan --status
complete` — exact commands in [step-9-completion.md](references/step-9-completion.md).

---

## Error Handling

See [error-handling.md](references/error-handling.md) for the full recovery
procedures: missing API keys (Step 5 Branch B — never silently skipped),
section-writer failure (retry without the subagent, then mark incomplete),
and context-window pressure (save, `/clear`, resume from any step).

---

## Reference Documents

Per-step refs:
- [first-actions.md](references/first-actions.md)
- [step-0-context-recovery.md](references/step-0-context-recovery.md)
- [step-5-external-review.md](references/step-5-external-review.md)
- [step-5-int-arch.md](references/step-5-int-arch.md)
- [step-9-completion.md](references/step-9-completion.md)
- [error-handling.md](references/error-handling.md)

Topical refs: [research-protocol.md](references/research-protocol.md), [interview-protocol.md](references/interview-protocol.md), [context-check.md](references/context-check.md), [plan-writing.md](references/plan-writing.md), [tdd-approach.md](references/tdd-approach.md), [section-index.md](references/section-index.md), [section-splitting.md](references/section-splitting.md), [external-review.md](references/external-review.md), [e2e-test-plan.md](references/e2e-test-plan.md).
Files in this package (16)
  • SKILL.md 14 KB
  • references/context-check.md 1 KB
  • references/e2e-test-plan.md 3 KB
  • references/error-handling.md 1 KB
  • references/external-review.md 3 KB
  • references/first-actions.md 8 KB
  • references/interview-protocol.md 1 KB
  • references/plan-writing.md 1 KB
  • references/research-protocol.md 1 KB
  • references/section-index.md 2 KB
  • references/section-splitting.md 4 KB
  • references/step-0-context-recovery.md 1 KB
  • references/step-5-external-review.md 20 KB
  • references/step-5-int-arch.md 4 KB
  • references/step-9-completion.md 7 KB
  • references/tdd-approach.md 1 KB

Versions

The database has no other skills named shipwright-plan.

Database snapshot: 13.11.2026 · package version 01a0c1595a26 (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 95shipwright-project
    Decomposes project requirements into well-scoped planning units for /shipwright-plan. Generates CLAUDE.md and .shipwright/agent_docs for the target project.\nTRIGGER when: user wants to start a new project, define requirements, create a project spec, decompose a project into…
  • 95shipwright-changelog
    Parses Conventional Commits from git history, generates Keep-a-Changelog entries, creates version tags, and opens PRs.\nTRIGGER when: user wants to create a changelog, generate release notes, tag a version, create a release, bump version number, create a PR for release, or…
  • 90shipwright-brand
    This skill MUST activate whenever creating, editing, or reviewing ANY Shipwright Harness marketing or brand artifact — e.g. "make a Shipwright one-pager", "create a Shipwright Harness slide deck", "design the OG / social image", "build an on-brand landing-page section",…
  • 100writing-plans
    Use when you have a spec, design doc, or requirements and need a detailed implementation plan before coding. Triggers: 'write a plan', 'create implementation plan', 'plan this out', 'break this down into steps', 'convert design to tasks', 'implementation order'. Also invoked by…
  • 100software-plan-creation
    Create delivery plans for software design specifications. Use when the user wants to plan implementation, break a design into delivery phases, create an implementation roadmap, produce a test plan, or structure a TDD approach for a feature. Reads the latest design spec by…
  • 100deep-plan
    Creates detailed, sectionized, TDD-oriented implementation plans through research, stakeholder interviews, and multi-LLM review. Use when planning features that need thorough pre-implementation analysis.

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.