Spec

---
name: spec
description: Turn an accepted intent into the requirements and design spec (Stage 2, Design) - OpenSpec proposal.md, delta specs and design.md with policies applied and areas of concern flagged. Use after the intent gate is approved, or when the user asks to write or refine requirements or the design.
argument-hint: "[change-id]"
license: "PolyForm-Noncommercial-1.0.0 with sdlc Additional Permissions, or sdlc Commercial License (https://github.com/marin-ai-tech/sdlc)"
compatibility: Requires the sdlc CLI (sdlc) from the sdlc package.
allowed-tools: Bash(sdlc *)
metadata:
  author: marin-ai technologies
  version: "1"
  generatedBy: "sdlc 0.23.7"
---

Write the requirements and design spec - Stage 2 (Design): `proposal.md`, delta specs under `specs/`, and `design.md`. Policy is applied while the spec is written, not discovered in a review weeks later.

**Harness contract** (applies to every SDLC workflow)
- `sdlc` is the source of truth for lifecycle state. Read it (`sdlc status --change <id> --json`) instead of inferring the stage from the conversation, and re-read artifacts from disk before using them.
- Gates are human decisions. Never run `sdlc approve`, `sdlc reject`, `sdlc waive` or `sdlc tests unlock`, and never edit `.sdlc.yaml`. When a gate needs a person, stop, name the people from the hint (`next.people` in `sdlc next --json`) rather than the role, and give them the exact command to run in their own terminal.
- An answer in chat is never an approval: gate approvals, `track set`, `backlog move`/`drop` and other human decisions happen only as a command the person runs in their own terminal. Offer the choice, explain the consequences, and give the exact command.
- OpenSpec is the specification subsystem: `sdlc openspec <args>` runs the bundled OpenSpec CLI (`list --specs`, `show`, `validate`, `instructions`). Change folders live in `openspec/changes/<id>/`.
- **Change selection**: use the change named in the input. Otherwise run `sdlc status --json`; with exactly one active change use it, with several ask which one. Announce "Using change: <id>".
- **Language**: talk to the person, and write notes and artifacts, in the person's language; when `locale:` is set in `openspec/sdlc.yaml`, use that language. Keep command names, file names, ids and the template headings as they are (sdlc and OpenSpec parse those headings).
- End every workflow with the next step from `sdlc next --json` (the exact command when a person must act).

**Input**: the user's request (a change id, or a description of the work)

**Steps**

1. **Check the gate.** `sdlc status --change <id> --json`: the `intent` gate must be `approved`, `waived` or `n/a`. Otherwise stop and report who must approve it.
2. **Load policy.** Read CLAUDE.md / AGENTS.md conventions and REVIEW.md. Load every available skill that encodes a relevant organizational policy (security, privacy, compliance, API design, UX, brand, data handling).
3. **Write the artifacts in dependency order.** For each of `proposal`, `specs`, `design` that is not done:
   - `sdlc instructions <artifact> --change <id> --json`
   - read its `dependencies` from disk (always re-read; people edit them)
   - inspect the relevant code, tests and configuration read-only, proportional to the change (delegate broad exploration to the `sdlc-researcher` subagent to keep this context clean)
   - write the file at `resolvedOutputPath` following `template` and `instruction`; apply `context` and `rules` as constraints without copying them
4. **Validate**: `sdlc validate --change <id>`. It runs OpenSpec and the harness's delta checks.
   Fix every error before reporting a pass. Show every warning to the person verbatim; warnings alone
   do not block approval. `sdlc approve spec` runs the same validation.
5. **Flag concerns.** `design.md` must list every area of concern with its owner - conflicting policies, security or privacy risk, migrations, compatibility breaks, unanswered intent questions. For design alternatives, use the AskUserQuestion tool with 2-4 choices and a recommended one. Never resolve a policy conflict silently.
6. **Debate the key decision (when the lens is on).** If `openspec/sdlc.yaml` has `design: { debate: true }`, pick the design decision with the most at stake and delegate it to two `sdlc-advocate` subagents in parallel, one per priority of `design.debate_sides` (default: simplicity and speed / robustness and safety). Write the result into design.md under `## Debate`: a `### Position: <priority>` subsection for each with its case in a few lines, then ask the person to decide with the AskUserQuestion tool (the two positions as choices, plus their own) and record their choice and reason under `### Decision`: the decision is theirs, not yours. The spec cannot be approved without it. With the lens off, skip this step.
7. **Stop at the gate.** Summarize: capabilities touched, requirements added/modified/removed, open concerns and who owns each. Then give the product owner the approval command: `sdlc approve spec --change <id>` (for `risk: high` a tech lead also runs `sdlc approve spec --change <id> --as tech-lead`). Planning continues with `/sdlc:plan` only after approval.

**Guardrails**
- Planning only: no code edits.
- Ask about ambiguity that changes scope, externally visible behavior, compatibility or acceptance criteria; record minor assumptions in the artifacts.
- Specs describe behavior; implementation detail goes to design.md and plan.md.
- Open questions in proposal.md or design.md are the person's to answer. Never write an answer yourself (an `Answer` line you add does not count); keep them as list items under the `## Open questions` heading, and at the gate give the command for each (never run it yourself): `sdlc answer <n> --change <id> --artifact <proposal|design> --text "<answer>"`. The spec cannot be approved while one is unanswered.

<!--
Generated by sdlc 0.23.7 (https://github.com/marin-ai-tech/sdlc).
Required Notice: Copyright (c) 2026 marin-ai technologies (https://github.com/marin-ai-tech/sdlc)
License: PolyForm Noncommercial 1.0.0 (https://polyformproject.org/licenses/noncommercial/1.0.0) with the sdlc Additional Permissions, or a commercial license; see https://github.com/marin-ai-tech/sdlc
-->