/design

name: design
version: 1.4.0
description: >
  Plan implementation before coding: investigate the repo, write spec and plan,
  and validate with a peer. Use for "plan", "design approach", "scope", or any
  coding task needing a plan. Not system-design thinking
  (/ship:arch-design) or full /ship:auto.
allowed-tools:
  - Bash
  - Read
  - Write
  - Edit
  - Glob
  - Grep
  - Agent
  - AskUserQuestion
  - mcp__codex__codex
  - mcp__codex__codex-reply

Ship: Design

You ARE the planner. You read code, investigate, write spec and plan. Read the load-bearing code yourself — a plan written from someone else's summary loses the context that makes it executable. On a large repo you may use read-only search agents to scout breadth (locate files, callers, conventions), but scouts locate code; they never replace your own reading of what you cite. A peer agent investigates independently and produces its own spec for adversarial comparison.

Runtime Resolution

_Path note: `../shared/*.md` references resolve against this skill's base directory (announced as "Base directory for this skill" when the skill loaded), not your working directory._

See `../shared/runtime-resolution.md` for the host/peer concept and dispatch commands. In /ship:design, the peer plays two roles: **investigator** (Phase 2) and **drill agent** (Phase 6).

Scope Mode

The prompt may specify `Scope mode: full` (default) or `Scope mode: refactor`. It controls how much adversarial validation runs:

| Phase | `full` | `refactor` | |-------|--------|-----------| | 1 Init | ✅ | ✅ | | 2 Investigate (host + peer) | ✅ | ✅ | | 3 Write spec | ✅ | ✅ (behavior-contract template) | | 4 Diff & verify | ✅ | ✅ | | 5 Write plan | ✅ | ✅ | | 6 Execution drill | ✅ | ⏭ **skipped** |

**Why refactor mode skips Phase 6:** for behavior-preserving changes (refactor, simplify, rename, extract, dedupe), the plan steps are usually small, mechanical code movements. The drill's "is every step implementable" check earns little here while adding a full peer round-trip. Peer investigation and diff stay on because they catch the real refactor failure mode — "moved complexity instead of removing it."

If no scope mode is specified (e.g. standalone /ship:design invocation), default to `full`.

Process Flow

Phase 1  Init            resolve task_id, create .ship/tasks/<id>/plan/
Phase 2  Investigate     dispatch peer (parallel) ─┐
                         you read the code         │
                         ↓                         │
Phase 3  Write spec      write host spec.md  ←─── peer writes peer-spec.md
                         vague? ask user → re-investigate
                         ↓
Phase 4  Diff & verify   compare specs → resolve each divergence
                         disagree? → debate peer (max 2 rounds)
                         still open? → escalate to user
                         critical gap? → re-investigate (max 1 loop)
                         ↓
Phase 5  Write plan      write plan.md with executable tasks
                         self-review against spec
                         ↓
Phase 6  Execution drill dispatch peer (fresh session) to validate plan
                         BLOCKED step?  → escalate
                         UNCLEAR step?  → revise plan (max 1 loop)
                         all CLEAR      → ready for execution

Roles

| Phase | Who | Why | |-------|-----|-----| | Investigation (read code, trace paths) | **Host + peer (parallel)** | Independent investigation catches different blind spots | | Write spec (host version) | **You** | Investigation context must not be lost | | Write spec (peer version) | **Peer agent** | Independence requires separation | | Diff & verify divergences | **You** | You have the context + code access to judge | | Write plan.md | **You** | Spec context must flow into plan | | Execution Drill | **Peer agent** (fresh session) | Fresh eyes test implementability |

Quality Gates

| Gate | Condition | Fail action | |------|-----------|-------------| | Investigation → Spec | All claims trace to file:line you read | Re-investigate | | Spec → Diff | spec.md has flexible sections scaled to complexity, self-reviewed | Revise | | Diff → Plan | Zero `escalated` items (resolved by evidence or debate, or user resolved them) | Ask user | | Plan → Drill | plan.md has TDD tasks, checkbox steps, complete code, no placeholders | Revise | | Drill → Ready | Zero BLOCKED steps, zero UNCLEAR steps | Revise plan (max 1 loop) |

No artifact passes to the next phase without meeting its gate.

Progress Tracking

Track your progress with the harness's task/todo list. After Phase 1 (init), create items that reflect the actual work ahead. Adapt them to what you discover — skip items for phases that don't apply, add items for loops you enter (re-investigation, drill revision).

**Principle**: one item per major phase the user would care about. Update the in-progress label to reflect what's happening within a phase.

**Example** (full run with peer available):

[in_progress] Investigate codebase (host + peer)
[pending]     Write spec
[pending]     Diff host vs peer specs
[pending]     Write implementation plan
[pending]     Execution drill

**Adaptations** (not exhaustive — use judgment):

• Peer unavailable → drop "Diff" item, rename "Investigate" to reflect self-produced peer spec
• Upstream spec already exists → drop "Write spec", start with "Validate existing spec"
• Re-investigation needed → re-mark "Investigate" as in progress
• Drill revision needed → keep "Execution drill" as in progress

Red Flag

**Never:**

• Cite files you haven't opened
• Let the peer see your spec before producing its own
• Resolve divergences by reasoning instead of code evidence (max 2 debate rounds, both cite file:line)
• Trust prior conversation over disk artifacts
• Mark plan ready when drill has BLOCKED or UNCLEAR items
• Skip the drill because "the plan looks solid"
• Write a spec claim from a sub-agent's su