A pipeline for AI coding agents that takes an idea to a reviewed pull request. The front half
settles intent, a checkable contract, a sound architecture, a grounded stack, and an atomic task
plan, with a read-only gate that confirms it all hangs together before a line of code is written.
The back half executes it: build runs the plan test-first (light: no per-task reviewer; full:
one initial review), and pr-review opens the PR and runs Review panel.
Test and deploy are the next stages downstream, extending the same chain.
- You own the thinking; the agent owns the breakdown — every stage leads with a recommendation and alternatives, and you decide.
- A traceability spine (
criterion -> component -> product -> task) runs the whole pipeline; a read-only gate walks it before any code exists. - Test-first build — one atomic green commit per task, resumable from a committed ledger. Light skips the per-task reviewer; full reviews once, then one remediations pass.
- A deterministic checker (
sdlc-check, zero-dep Node) enforces the mechanically-decidable promises — coverage, trace integrity, ledger↔git, proof maps — fail-closed. - Start anywhere — enter at any stage, from any source (a prompt, a doc, a Linear issue set), without weakening a single gate; a light tier compresses authoring for small fixes.
- Five standalone skills — three documentation skills (
writing-readmes,writing-repo-docs,writing-technical-docs) for documenting what you build,repo-setupfor scaffolding it, andhandofffor the live "where we left off" doc — usable on any repo.
Packaged as a plugin for Claude Code,
Cursor, and OpenAI Codex (this repo
is its own single-plugin marketplace, agent-sdlc), and installable as a package on
pi. The skills are plain Markdown to the open SKILL.md standard, portable to any
agent that reads instruction files.
Pairs with Review panel — multi-model review that writes a report and does not merge.
pr-reviewcallsreview_panelwhen installed, and degrades to a portable reviewer subagent when it isn't. The owner is the merge gate.
Contents: Quickstart · The idea · Stages · Standalone skills · Install · Layout · Documentation · Contributing · License
/plugin marketplace add smarzban/agent-sdlc
/plugin install agent-sdlc
Then, in the repo you want to build in, state what you want — "I want to add a feature: …" —
and the pipeline picks it up at light (the default for small work) or idea when a full-chain
trigger fires. Or ask /agent-sdlc:getting-started to route you.
A run leaves a committed spec chain in docs/specs/<feature>/ and ends in a reviewed PR.
Full walkthrough: docs/quickstart.md.
You own the thinking. The agent owns the breakdown. Every stage leads with a recommendation and the alternatives, and you decide. A single traceability spine runs through the whole pipeline:
criterion -> component -> product -> task
Each stage adds one link; the gate walks the whole chain, so anything unmapped surfaces before code rather than during it.
| Skill | Invoke explicitly | Owner | Output |
|---|---|---|---|
light |
/agent-sdlc:light |
you review | Brief + AC + Plan in one pass (default for small work) |
idea |
/agent-sdlc:idea |
you | ## Brief (problem + scope); full chain only |
acceptance-criteria |
/agent-sdlc:acceptance-criteria |
you review | ## Acceptance Criteria (the contract) |
architecture-design |
/agent-sdlc:architecture-design |
you, agent proposes | ## Design (## Architecture at project level) |
techstack |
/agent-sdlc:techstack |
you, agent proposes | ## Tech Stack |
plan |
/agent-sdlc:plan |
agent | ## Plan (atomic tasks) |
gate |
/agent-sdlc:gate |
automated (read-only) | gate-report.md |
build |
/agent-sdlc:build |
agent | product code (a green branch) + build-report.md |
pr-review |
/agent-sdlc:pr-review |
agent | an open PR + Review panel report (does not merge) |
getting-started |
auto / /agent-sdlc:getting-started |
router | this is the entry point |
Start with getting-started; it routes you. Light is the default. Full chain only on a
narrow trigger or when you ask for it.
Start anywhere. Run the whole chain, or invoke any stage on its own — each resolves its input
from whatever you give it (the spec, a prompt, a doc, a Linear issue set, a repo artifact),
materializes it into the spec with a provenance marker, then runs. A plan already in Linear? build
ingests it, runs the gate inline, and builds — you don't have to hand-run the front half first. The
gate, the per-task TDD loop, and traceability are never skipped; a missing upstream link is marked
untraced and surfaced, never invented. Details: docs/usage/start-anywhere.md.
For a small self-contained fix, the light tier folds brief + criteria + plan into one short
pass — same gate, build, and checker: docs/usage/light-tier.md.
Invocation. Installed as a plugin, every skill auto-activates when your request matches its
description— that's the primary path, and you rarely type a command. To invoke one explicitly, use the mandatory plugin namespace, e.g./agent-sdlc:idea. Bare names like/idearesolve only to personal skills (~/.claude/skills/), never to plugin skills — theagent-sdlc:prefix can't be dropped. Want shorter explicit names (e.g./agent-sdlc:criteria)? Add acommands/<name>.mdfile to the plugin; it's still namespaced as/agent-sdlc:<name>.
Five skills outside the pipeline: three for documenting a codebase, repo-setup for the
operational machinery, and handoff for the live working-state doc. The three documentation
skills are source-grounded (every concrete claim is checked against the actual code) and adapt
their structure to the repo's type. They split by depth: the front door, the essentials, the
internals. repo-setup sits alongside them — not a documentation skill but its machinery
counterpart: it stubs a repo's operational baseline (the agent-instruction split, CI/templates/
CODEOWNERS scaffolding, and a seeded HANDOFF.md) for these three to later fill with prose.
handoff scaffolds, updates, and prunes HANDOFF.md itself, and two pipeline stages (build,
pr-review) update it automatically when it already exists.
| Skill | What it does |
|---|---|
writing-readmes |
Write/overhaul a project's front-door README.md — leads with what/why, keeps a lean quickstart distinct from full install, links out to deeper docs instead of inlining them. |
writing-repo-docs |
The essentials a repo needs to be usable and contributable — landing index + quickstart + install + comprehensive per-feature usage + running-it-locally + contributing/community-health files, plus at most a light architecture overview. |
writing-technical-docs |
Full maintainer-grade internals — architecture with design rationale, data models, per-subsystem pages with invariants, the security model, and a complete module/API reference under a coverage-ledger contract (every exported symbol documented or explicitly excluded). |
repo-setup |
Take a repo — empty or existing — to an operational baseline: the public/private agent-instruction split, gitignore/CI/templates/CODEOWNERS scaffolding, and opt-in pipeline setup. Machinery and marked skeletons, not prose. |
handoff |
Scaffold, update, or prune HANDOFF.md, the working copy's live "where we left off" doc: what's in flight, what to pick up next, ignored by default. |
How they chain and when to pick which: docs/usage/documentation-skills.md.
/plugin marketplace add smarzban/agent-sdlc
/plugin install agent-sdlc
Skills then trigger on their description, or invoke explicitly with the plugin namespace, e.g.
/agent-sdlc:idea or /agent-sdlc:writing-readmes.
OpenAI Codex:
codex plugin marketplace add smarzban/agent-sdlc
codex plugin add agent-sdlc@agent-sdlc
pi:
pi install git:github.com/smarzban/agent-sdlc
Cursor imports the repo URL as a team marketplace. The skills are plain Markdown to the open
SKILL.md standard, portable to any agent that reads instruction files. The per-harness
walkthroughs, updating, and requirements are all in docs/install.md.
agent-sdlc/ ← repo root = the plugin AND its marketplace
├── .claude-plugin/ ← marketplace.json + plugin.json (Claude Code)
├── .cursor-plugin/ ← marketplace.json + plugin.json (Cursor)
├── .codex-plugin/plugin.json ← plugin manifest (OpenAI Codex)
├── .agents/plugins/marketplace.json ← Codex marketplace manifest
├── package.json ← pi package manifest (pi.skills)
├── bin/sdlc-check ← on-PATH launcher for the checker
├── checker/sdlc-check.mjs ← the enforcement-spine checker (zero-dep Node, + tests)
├── skills/
│ ├── light/SKILL.md ← default small-change authoring
│ ├── idea/SKILL.md
│ ├── acceptance-criteria/SKILL.md
│ ├── architecture-design/SKILL.md
│ ├── techstack/ ← SKILL.md + reference/probing.md
│ ├── plan/SKILL.md
│ ├── gate/SKILL.md
│ ├── build/ ← SKILL.md + reference/ (subagent-loop · tdd · source-driven · simplicity · debugging · plan-amendments · ingesting-plans)
│ ├── pr-review/ ← SKILL.md + reference/finishing.md
│ ├── getting-started/ ← SKILL.md + reference/ (input-resolution · light-tier)
│ ├── linear-sync/ ← SKILL.md + reference/mapping.md (optional engine)
│ ├── writing-readmes/ ← documentation skill (front door) + reference/
│ ├── writing-repo-docs/ ← documentation skill (repo essentials) + reference/
│ ├── writing-technical-docs/ ← documentation skill (full internals) + reference/
│ └── repo-setup/ ← standalone: repo scaffolding + machinery, not prose + reference/
└── docs/ ← user + contributor documentation (see below)
└── specs/ ← this repo's own dogfood spec tree
A run produces, per feature:
docs/specs/<feature>/
├── <feature>.md ← ## Brief · ## Acceptance Criteria · ## Design · ## Tech Stack · ## Plan
├── gate-report.md ← gate output (read-only)
├── build-report.md ← build output (the resumable task ledger)
└── verification-report.md ← pr-review's AC → proof map (checker-verified pre-PR)
plus, at project level, docs/specs/overview.md (## Overview · ## Architecture · ## Tech Stack)
and docs/specs/adr/ for decision records, and root-level constitution.md + CONTEXT.md (glossary).
(A repo that already has a spec tree at root specs/ keeps using it — the back-compat rule in the
getting-started skill; new spec trees are created at docs/specs/.)
build then lands the code on a feature branch and pr-review opens the reviewed PR — neither edits the
spec.
Agent SDLC can mirror each stage into Linear as you go — initiative (product)
→ project (feature) → milestone (build phase) → issue (task) — and advance the T-N issues as you
build and pr-review. Off by default; enabled via .agent-sdlc/config.json, and skipped cleanly when
the Linear MCP isn't connected. Setup + mapping: docs/usage/linear-sync.md.
- Use it → docs/quickstart.md, the five-minute example run, then docs/usage/
— one page per capability (the pipeline, start-anywhere, the light tier,
sdlc-check, Linear sync, the documentation skills — plusrepo-setup, documented in its own SKILL.md). - Install / update it → docs/install.md — Claude Code, Cursor, any other agent.
- Contribute to it → docs/development.md + CONTRIBUTING.md.
- Understand the repo → docs/architecture.md;
docs/specs/is the repo building itself through its own pipeline.
Zero-dependency by design: the skills are Markdown, and the only executable is the checker
(Node ≥ 22, node --test checker/*.test.mjs). Skills are auto-discovered from skills/<name>/SKILL.md
— a new skill needs no manifest edit. Branch → PR, Conventional Commits, fast-forward merges (the
checker depends on preserved SHAs). Full conventions: CONTRIBUTING.md.