Doc-first Software Development Lifecycle methodology for AI coding agents.
Works natively on six harnesses — Claude Code (CLI + VS Code + Cursor
extension + JetBrains + claude.ai/code web), Cursor Agent, GitHub
Copilot CLI, OpenAI Codex CLI/App, Google Gemini CLI, and OpenCode.
v2.0.0 · Released 2026-04-23 · MIT · Python 3.11+ only
A scaffolded 6-phase waterfall SDLC tree (docs/sdlc/01_requirement/ … docs/sdlc/06_maintenance/)
plus a runtime that keeps AI coding agents honest about it.
At session start, a 5-rule contract is auto-injected as IMPORTANT context.
At phase sign-off, a two-pass reconciliation gate blocks drift between
signed docs and shipped code. Throughout, an on-demand skill
(/sdlc-strict-waterfall) provides the full protocol: Core rules 1-10,
per-phase workflows, change/migration/hotfix/removal procedures, and a
traceability matrix from requirement to commit.
Everything is measurement-backed: every NFR carries a numeric target; a
metrics subsystem (tools/sdlc_metrics/) reports token cost per phase; a
residue guard refuses to sign docs with placeholder content; a SHA-pinned hook
script refuses to inject a tampered contract.
Pick your agent. One command. Done.
| Agent | Install |
|---|---|
| Claude Code | claude plugin marketplace add Electronics-Extreme/claude-sdlc && claude plugin install claude-sdlc@claude-sdlc |
| Codex | Clone repo → /plugins → Search "SDLC" → Install |
| Gemini CLI | gemini extensions install https://github.com/Electronics-Extreme/claude-sdlc |
| Cursor | npx skills add Electronics-Extreme/claude-sdlc -a cursor |
| Windsurf | npx skills add Electronics-Extreme/claude-sdlc -a windsurf |
| Copilot | npx skills add Electronics-Extreme/claude-sdlc -a github-copilot |
| Cline | npx skills add Electronics-Extreme/claude-sdlc -a cline |
| Any other | npx skills add Electronics-Extreme/claude-sdlc |
Install once. Use in every session. On first interaction, the agent loads the SDLC contract, detects a missing scaffold, and offers to bootstrap.
- Open your project in the agent
- Ask: "What are the 5 non-negotiable rules?"
- Agent loads SDLC contract → detects no scaffold → offers bootstrap
- Accept →
docs/sdlc/01_requirement/...06_maintenance/created - Start spec in
docs/sdlc/01_requirement/srs.md
No agent install needed — use the CLI directly.
# Option A — npx (no global install)
cd ~/Projects/MyApp
npx @electronics-extreme/claude-sdlc init --harness claude
# Option B — global install (shorter command)
npm install -g @electronics-extreme/claude-sdlc
cd ~/Projects/MyApp
claude-sdlc init --harness claudeSix phases, strictly ordered. No phase skips. Every phase gates on four checks plus two-pass reconciliation before sign-off:
+------------------+ +------------------+ +------------------+ +------------------+ +------------------+ +------------------+
| 01_requirement | → | 02_design | → | 03_implementation| → | 04_testing | → | 05_deployment | → | 06_maintenance |
| | | | | | | | | | | |
| SRS | | Architecture | | Source code | | Test report | | Release | | Change requests |
| signed off | | + DB + API | | + unit tests | | + defects log | | + runbook | | + incident log |
+------------------+ +------------------+ +------------------+ +------------------+ +------------------+ +------------------+
Five non-negotiable rules (always-loaded via SessionStart hook):
- REFUSE direct code edits — route via CR + doc amendment
- No code without a doc parent in signed 01/02/03
- No phase skipping — N+1 requires N sign-off
- Signed docs are frozen — amend via Post-vX.Y.Z sections
- Reconciliation gate before every phase sign-off (two ordered passes)
Each rule ships with an Excuse / Reality rationalization table that anticipates the specific rationalizations an agent (or human) invents to skip the rule.
Core rule 7 — TDD inside every slice. RED-GREEN-REFACTOR per TO-###. Tests derive from AC-### / TC-### in the signed docs — never invent behavior.
Core rule 9 — Four gates + two-pass reconciliation:
- typecheck + lint + full test suite + reconciliation Pass 1 (spec) before Pass 2 (quality) before sign-off
See skill/sdlc-contract.md for the 5 rules in full; skill/SKILL.md for
Core rules 1-10, per-phase workflows, and protocols.
| Area | Contents |
|---|---|
| Phase scaffolds | docs/sdlc/01_requirement/ … docs/sdlc/06_maintenance/ — 39 artifact templates per phase |
| Skill | skill/sdlc-contract.md, skill/SKILL.md, skill/reconciliation.md, skill/traceability-matrix.md, workflows × 4, protocols × 4, references × 2, required-reads manifest |
| Hooks | hooks/session_start.py (6-harness env-detect + SHA integrity + banner), run-hook.cmd / .sh launchers |
| Scripts | 12 Python 3.11+ stdlib scripts: bootstrap, build-archive, check_frontmatter, check_residue, check_task_types, update_contract_sha, sync_wrappers, reconcile, bump_version, release_check, add_frontmatter |
| Metrics subsystem | tools/sdlc_metrics/ — phase-aware token analyzer with 6 adapter stubs, 4 report formats (text/JSON/markdown/HTML), SQLite history, budget gate, secrets pre-filter |
| Config | config/pricing.yaml, budgets.yaml, phase-markers.yaml, task-types.yaml, harnesses.yaml, residue-exceptions.yaml |
| Schemas | schemas/doc-frontmatter.schema.yaml, task-types.schema.yaml |
| Harness adapters | .claude/, .claude-plugin/, .cursor/, .windsurf/, .clinerules/, .github/copilot-instructions.md, .codex/, .opencode/, gemini-extension.json, AGENTS.md, GEMINI.md |
| Policy docs | PRIVACY.md, NOTICE.md, LICENSE, CHANGELOG.md, docs/VERSIONING.md |
| CI workflows | .github/workflows/sdlc-tests.yml, release.yml, airgap.yml |
Total: ~290 files, ~830 KB dist.zip.
Every claim in this README is backed by a measurement or CI gate:
| Claim | Verified by |
|---|---|
| Zero telemetry, zero analytics, zero remote fetch except user-invoked | .github/workflows/airgap.yml runs every script with network denied; exit 0 required |
| Works on Windows 11 natively | .github/workflows/sdlc-tests.yml matrix includes windows-2022 |
| Python 3.11 stdlib only | Grep-check on import lines + airgap job |
| Every phase doc has valid frontmatter | scripts/check_frontmatter.py in CI |
| No placeholder residue in signed docs | scripts/check_residue.py in CI |
| Contract + hook integrity (SHA-pinned) | scripts/update_contract_sha.py --check in CI |
| Harness wrappers stay in sync | scripts/sync_wrappers.py --check in CI |
| SemVer correctness on release | scripts/release_check.py --tag in release workflow |
| HTML metrics report is self-contained ≤ 500 KiB | NFR-METRICS-OUT-1 asserted in tests |
| Metrics adapter ≤ 200 LOC for well-formed transcripts | NFR-METRICS-ADAPT-1 — Claude Code reference is 180 LOC |
Default per-phase budgets (from config/budgets.yaml, editable per adopter):
| Phase | Token hard-cap | Cost hard-cap | Cache floor |
|---|---|---|---|
| 01 requirement | 80K | $0.40 | 60% |
| 02 design | 100K | $0.55 | 65% |
| 03 implementation | 150K | $0.75 | 70% |
| 04 testing | 90K | $0.45 | 70% |
| 05 deployment | 60K | $0.30 | 55% |
| 06 maintenance | 70K | $0.35 | 60% |
Run python3 tools/sdlc_metrics/analyze.py budget-check <session.jsonl> --phase 3 to enforce. Exit 1 on breach.
Strict SemVer 2.0. The kit follows a bootstrap pattern — existing
projects stay on the kit version they installed; new features land in new
bootstrapped projects. See docs/VERSIONING.md.
This kit is distributed as-is. Changes go through the kit's own SDLC:
- File a CR in
docs/sdlc/06_maintenance/change_requests.md(use the template) - Approve per class (minor = TL; major = TL + PO; breaking = TL + PO + Security)
- Amend Phase 1/2/3 docs as declared in the CR
- Implement per Core rule 7 (TDD)
- Close reconciliation — Pass 1 spec compliance, then Pass 2 code quality
- Bump VERSION, promote CHANGELOG, tag
release.ymlpublishesdist.zip
MIT — see LICENSE.
Zero telemetry. Zero analytics. Zero remote fetch except user-invoked
pricing-sync and harness marketplace installs. See PRIVACY.md.