/sw-design

name: sw-design
description: >-
  Autonomous solution architecture. Researches the codebase, designs a
  solution, challenges it adversarially, and produces design artifacts.
argument-hint: "[what you want to build or change]"
allowed-tools:
  - Read
  - Write
  - Edit
  - Bash
  - Glob
  - Grep
  - Task

Specwright Design

Goal

Research the codebase, design a solution, challenge it adversarially, and produce design artifacts. Output is a design — not specs, not code. Operates autonomously between research and gate handoff, applying `protocols/decision.md` for all decisions.

Inputs

• The user's request (argument or conversation)
• `{projectArtifactsRoot}/CONSTITUTION.md` -- practices to follow
• `{projectArtifactsRoot}/CHARTER.md` -- vision and invariants
• `{projectArtifactsRoot}/config.json` -- project configuration
• `{worktreeStateRoot}/session.json` -- current worktree attachment, when present
• `{repoStateRoot}/work/*/workflow.json` -- other active works for collision checks
• The codebase itself

Outputs

When complete, runtime and auditable artifacts exist in both locations:

• `{repoStateRoot}/work/{id}/stage-report.md` -- runtime-local design handoff digest with attention-required at the top
• `{workArtifactsRoot}/{id}/design.md` -- solution overview, approach, integration points, risk assessment
• Required section: `## Blast Radius` listing: modules/files the design touches, failure propagation scope for each (local/adjacent/systemic), and what the design does NOT change.
• `{workArtifactsRoot}/{id}/context.md` -- research findings, file paths, gotchas (travels with downstream agents)
• design assumptions artifact under `{workArtifactsRoot}/{id}/` -- classified assumptions with resolution status
• `{workArtifactsRoot}/{id}/decisions.md` -- all autonomous decisions recorded per `protocols/decision.md`

When warranted: `data-model.md`, `contracts.md`, `testing-strategy.md`, `infra.md`, `migrations.md`.

Constraints

**Stage boundary (LOW freedom):** Follow `protocols/stage-boundary.md`. Produce design artifacts and research context. NEVER write specs, decompose, implement, branch, or test. After gate handoff, STOP.

**Ownership guard (LOW freedom):**

• When the current worktree session is already attached to an existing work,

resolve live ownership from `session.json`, not from branch names alone.

• If another live top-level worktree owns that work, STOP and point the

operator to the explicit `/sw-adopt` flow rather than mutating design artifacts here.

• `/sw-adopt` may attach only the current worktree session. `sw-design` must

never rewrite another worktree's `session.json`.

**Research (HIGH freedom):**

• Load LANDSCAPE.md, AUDIT.md, research briefs if they exist. Scan code, dependencies, patterns.md.
• Delegate to `specwright-researcher` and `specwright-architect` as needed.
• Derive hard constraints from constitution + charter (do not ask — these are documented).
• When the request itself is ambiguous, apply `protocols/decision.md` DISAMBIGUATION:

infer intent from the argument, codebase context, and charter vision. Record the interpretation in decisions.md. If genuinely undetermined, surface at the gate.

• Research is complete when: integration is described, main risk is identified with

mitigation, blast radius is bounded, no major gaps remain.

**Design (HIGH freedom):**

• Propose the simplest solution grounded in research. Justify abstractions.
• When choosing between alternatives, apply `protocols/decision.md` DISAMBIGUATION

hierarchy. Record the choice and which rule resolved it in decisions.md.

**Critic (HIGH freedom):**

• For non-trivial requests, delegate to `specwright-architect` for adversarial review.
• Follow `protocols/decision.md#convergence-loop` for the iterative critic loop.

Convergence at ≥4/5 on all dimensions with no BLOCKs auto-approves per `protocols/decision.md#approval`.

• Auto-revise BLOCKs (up to 2 iterations). Document WARNs in design.md.
• If critic rejects the entire approach: apply DISAMBIGUATION to choose the best

alternative. Record in decisions.md.

**Assumption resolution (MEDIUM freedom):**

• Follow `protocols/decision.md#assumption-lifecycle` for format, classification,

and autonomous resolution.

• After critic: auto-resolve per `protocols/decision.md#autonomous-resolution`.

Clarify+technical → auto-ACCEPT. Reference/external → auto-DEFER to backlog per `protocols/backlog.md`.

• Assumptions contradicting an AC are Type 1 structural override — always blocking.

Type 1 deficiencies halt and surface at the gate (do not auto-proceed).

**Change requests (MEDIUM freedom):**

• `design.md` exists + argument: change request, re-run critic.
• `design.md` exists + no argument: apply DISAMBIGUATION — if the user's prior message

implies a change, treat as change request. Otherwise, present status at the gate.

**Approval target (LOW freedom):** Per `protocols/approvals.md`, identify the design artifact set awaiting approval for `/sw-plan`: `design.md`, `context.md`, `decisions.md`, the design assumptions artifact, and any optional design supplements written in this run. `sw-design` does not write `APPROVED` entries itself.

**Gate handoff (LOW freedom):** On completion, emit the three-line handoff per the `protocols/decision.md` Gate Handoff section. Write `{repoStateRoot}/work/{id}/stage-report.md` before the handoff. The Artifacts line points at `Artifacts: {repoStateRoot}/work/{id}/stage-report.md`. Detail lives in the auditable artifact files under `{workArtifactsRoot}/{id}/` (`design.md`, `decisions.md`, design assumptions artifact, `context.md`). The Next line remains machine-parseable: `Next: /sw-plan`.

**State mutations (LOW freedom):** Follow `protocols/state.md` for read-modify-write mechanics. Postconditions:

• New work created at `{repoStateRoot}/work/{id}/`.
• `{worktreeStateRoot}/session.json.attachedWorkId` is set to the new work ID for

the current worktree only.

• Do not cle