Using Agent SDLC: idea to a reviewed PR

Agent SDLC takes an idea to a reviewed pull request. The front half is five thinking stages plus a read-only gate: you own the thinking (intent, scope, criteria, shape, stack), the agent owns the breakdown (plan), and the gate confirms it all hangs together before any code is written. The back half is build, which executes the plan test-first, then an explicit user decision whether to start pr-review, which opens the reviewed PR. (Test and deploy are later additions to the same chain.)

The stages

Feature-tier sections live in docs/specs/<feature>/<feature>.md; project-tier sections (## Overview, ## Architecture, ## Tech Stack) live in docs/specs/overview.md. Stages 1–5 each own and edit only their own section; build writes product code + build-report.md, and pr-review opens the PR — neither edits the spec.

Cross-cutting: constitution.md (standing guardrails, seeded by idea, checked at design and plan) and the gate (/agent-sdlc:gate; read-only; walks the chain and writes gate-report.md). The gate stands between plan and build: build runs only on a clean verdict.

The default flow for small work: light -> gate -> build -> pr-review. The full flow: idea -> acceptance-criteria -> architecture-design -> techstack -> plan -> gate -> build -> pr-review.

Optional: Linear sync

If enabled in .agent-sdlc/config.json (linear.enabled: true), each stage mirrors its output into Linear at its hand-off — initiative (product) → project (feature) → milestone (build phase) → issue (task). build and pr-review transition those milestones and issues as code lands and the PR opens (Backlog → In Progress → In Review → Done, plus PR attachment). The mechanics live in the linear-sync skill; with the Linear MCP absent (e.g. headless runs) the steps are skipped. Off by default — Agent SDLC runs identically without it.

Shared operating rules (every stage obeys these)

Stated once here; the stage skills reference them by name rather than restating.

• Recommend, don't just ask. Every stage leads with the agent's recommended answer and the alternatives it considered with tradeoffs. You decide. plan and build run autonomously; after build, the agent always asks whether to start pr-review. Once authorized, pr-review runs autonomously and stops only at a genuine blocker.
• One question at a time. Multiple-choice where possible. Walk the decision tree, do not dump.
• Code over questions. If the repo answers it, go read it instead of asking.
• Resolve inputs from any source. A stage's input can come from the canonical spec, a prompt, a doc, a Linear issue set, or a repo artifact. Resolve it, materialize it into the spec with a provenance marker, then run — the precondition is that the input exists and is settled, not that the upstream file exists at its path. Never fabricate an input to clear a gate, and never weaken a gate to enter mid-chain. See reference/input-resolution.md.
• Loop, don't force. When a stage exposes that an earlier one was not actually settled, go back and re-settle, then continue. A fuzzy input is never patched over.
• Traceability is the spine. criterion -> component -> product -> task. Each stage adds one link; the gate walks the whole chain, and build commits one task at a time against it. Anything unmapped surfaces before code.
• YAGNI throughout. Build only what the criteria need, at every stage: no aspirational criteria, no speculative components, no needless dependencies, no gold-plated tasks.
• Stay in your stage. Tech-agnostic until design; product-free until techstack; no code until build; no PR until pr-review. Each stage names the next thing down, not all of them.
• Test-first in build. Every task names its failing test in the plan; build writes that test before any code and keeps the repo green between tasks.
• Ground in live docs over memory, at techstack and again in build: verify current versions and APIs against official documentation, and record what you checked and when.
• Evidence before "done". Claim a suite green, a task complete, or a PR ready only after running the check and reading its output — never from memory or expectation.
• Resolve the checker the same way at every invocation point (checker-resolution rule). Try in order, first hit wins: (1) bare sdlc-check (Claude Code puts the plugin's bin/ on the Bash PATH); (2) "${CLAUDE_PLUGIN_ROOT}/bin/sdlc-check" where the harness substitutes that variable; (3) node <plugin-install-dir>/checker/sdlc-check.mjs — the install dir is wherever this skill file itself lives. Command-not-found with node present is a resolution problem: try the next form, don't degrade. The announced degraded fallback applies only when no form resolves (no reachable install dir, or no node).
• Contracts in the body, depth in reference/. Load-bearing contracts — artifact formats, checker/invocation points, mandatory disciplines — live in the SKILL body; a reference/ file holds optional depth and mechanics. Where a reference doc IS load-bearing at a specific step, the owning SKILL body mandates reading it at that step, not merely links it — an agent may legitimately never open a doc that is only linked.
• Rules ratchet down, not up. A new rule added to a pipeline skill (usually after an incident) must displace, generalize, or merge with an existing line — appending is the exception and needs justifying in the PR. Pipeline SKILL bodies hold a soft ceiling of ~300 lines; a change that breaches it says why. Instruction sets only ever grow unless subtraction is a rule too.
• If HANDOFF.md exists at the repo root, read it first. It carries live working state, where the last session left off, as against the standing rules in the instruction files. See the handoff skill to set one up or keep it current.

Routing: project vs feature

Decide the level the way idea does, and carry it through.

• Project (clean repo, building a whole app): idea writes docs/specs/overview.md ## Overview (incl. the feature list) and seeds constitution.md and CONTEXT.md. architecture-design writes the north-star ## Architecture, and techstack the cross-cutting ## Tech Stack, both in overview.md. Each feature then runs the full chain in its own docs/specs/<feature>/<feature>.md.
• Feature (existing project, adding a piece): run the chain in docs/specs/<feature>/<feature>.md, fitting the existing overview.md architecture and stack, justifying any deviation with an ADR in docs/specs/adr/.

Routing: light vs full (ask this first)

Light is the default. Full is the exception. Ask size before starting idea.

• Small and self-contained (a bug fix, a targeted edit, tens of lines, a few files) with no new runtime dependency, no new public API, and no new trust or process boundary -> light. Invoke /agent-sdlc:light. Read reference/light-tier.md now. Gate still runs. Build uses the light path (no per-task reviewer). pr-review runs Review panel.
• Full chain only if the user asks for it, or a narrow trigger fires: new runtime dependency, new public API, or new trust/process boundary. Then start at idea.

When unsure, stay light. Upgrade mid-flight if a trigger appears: author the missing ## Design/## Tech Stack through the normal materialize path (input-resolution) into the same spec file.

Visual aids: idea and architecture-design only

These two stages are the only ones that draw. If idea or architecture-design, and a question would land better drawn than described, read reference/visual-aids.md now: it is the load-bearing visual-aid discipline (the visual test, the two kinds of visual aid, and the consent protocol).

File layout

/
├── constitution.md          ← standing principles (project-wide)
├── CONTEXT.md               ← glossary (project-wide)
└── docs/
    └── specs/
        ├── overview.md      ← project tier: ## Overview · ## Architecture · ## Tech Stack
        ├── adr/             ← decision records
        │   └── ADR-NNNN-<slug>.md
        └── <feature>/
            ├── <feature>.md           ← feature tier: ## Brief · ## Acceptance Criteria · ## Design · ## Tech Stack · ## Plan
            ├── gate-report.md         ← gate output (read-only)
            ├── build-report.md        ← build output (the resumable ledger)
            └── verification-report.md ← pr-review output (the AC → proof map)

Back-compat rule (the authoritative statement — the other skills reference it rather than restating it): if the repo already has a spec tree at root specs/, KEEP using it — never split a repo across both locations, and never auto-migrate a user's repo. New spec trees are created at docs/specs/. Root-level constitution.md and CONTEXT.md stay at the repo root either way.

Spec lifecycle

A feature spec (docs/specs/<feature>/<feature>.md) is an immutable snapshot — once shipped it is not edited; pr-review stamps a one-line status header at the top (status · version · date) recording what was built. docs/specs/overview.md is living — its project-tier ## Overview · ## Architecture · ## Tech Stack are updated as the project evolves. Each feature's design stage owns updating ## Architecture (in overview.md) on a material change: a new feature that reshapes the north-star updates the living architecture there, never by rewriting a shipped feature spec. This matters more under start-anywhere — old specs are now load-bearing inputs, so a shipped spec must stay a faithful snapshot of what was built.

Where to start

• A small, self-contained change: light. This is the default.
• A new app, vague idea: start at idea, project level.
• A new feature with a new public API, new runtime dependency, or new trust boundary: idea, feature level, full chain.
• You already have a settled problem and scope: start at acceptance-criteria.
• You have approved criteria: architecture-design, then techstack, then plan.
• A ## Plan section exists in <feature>.md: run gate, then build.
• The branch is built and green (build-report.md all done): ask whether to run pr-review to open the reviewed PR.

Starting from outside the spec chain — a prompt, a doc, or Linear — any stage can still run (it resolves and materializes its input first; see reference/input-resolution.md):

• Intent lives in a prompt or doc, no spec yet: start at idea (or acceptance-criteria if the problem is already settled), ingesting the source as the ## Brief.
• A plan already lives in Linear or a doc: run build — it ingests the plan (materializes ## Plan), runs the gate inline, then builds (light or full per the spec). You do not have to hand-run the front half first.
• Any single stage on its own ("just write the criteria", "just plan this"): invoke that stage; it resolves its input from the source you give it. Single-stage mode produces just that section; resume-to-pr-review mode backfills only the minimum upstream the gates require, marking genuinely absent links untraced rather than inventing them.

If you are unsure which stage you are in, you are probably one stage earlier than you think. The cheapest fix is always upstream.