obsidian-owl/sw-design

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 clear or rewrite unrelated active works in other top-level worktrees. Starting a new design in this worktree changes only this worktree's session attachment.
• If this worktree was previously attached to a shipped work and the user starts a new design, print exactly one informational notice before retargeting this worktree: Clearing prior shipped work {unitId}. Run /sw-learn first if pattern capture is desired. The notice is informational only; sw-learn remains optional.
• During legacy fallback migration, if prior currentWork has status shipped, clear that legacy attachment and reset workUnits to null before retargeting this worktree.
• The new selected work's workflow.json.status is designing.
• The new selected work's targetRef records the concrete remote, branch, role, resolution source, and resolution time for the selected work.
• The new selected work's freshness is seeded from the resolved git.freshness config at design time, carrying validation, reconcile, and checkpoints, with status: "unknown" and lastCheckedAt: null.
• The new selected work's baselineCommit is the SHA of the resolved target branch HEAD captured before any work begins and is never overwritten on re-entry.
• targetRef also written to {workDir}/context.md for historical reference.
• baselineCommit also written to {workDir}/context.md for historical reference.

Protocol References

• protocols/stage-boundary.md -- scope, termination, and handoff
• protocols/decision.md -- autonomous decision framework, gate handoff, convergence loop, assumption lifecycle
• protocols/state.md -- workflow state updates and locking
• protocols/context.md -- anchor doc and config loading
• protocols/delegation.md -- agent delegation for research and critic
• protocols/recovery.md -- compaction recovery
• protocols/landscape.md -- codebase reference document format
• protocols/audit.md -- codebase health findings format
• protocols/backlog.md -- backlog item format and write targets
• protocols/approvals.md -- pending design artifact set and approval contract
• protocols/research.md -- external research brief format and consumption

Failure Modes

| Condition | Action | |-----------|--------| | Request too vague | Apply DISAMBIGUATION from codebase + charter context. Record interpretation. If undetermined, surface at gate. | | Active work in progress | Apply DISAMBIGUATION: if argument provided, start new. If no argument, continue existing. Record choice. | | Selected work owned by another live top-level worktree | STOP with explicit /sw-adopt guidance | | design.md exists, no argument | Apply DISAMBIGUATION: if user's message implies change, treat as change request. Otherwise, present status at gate. | | Critic rejects entire approach | Apply DISAMBIGUATION to choose best alternative. Record in decisions.md. | | User rejects design at gate | Revise per user feedback and re-run critic. User overrides critic — note in design.md. | | Unresolved Type 1 assumptions | Surface at gate handoff as deficiencies. Do not auto-proceed. | | Compaction during design | Read workflow.json, check which artifacts exist, resume next missing phase |