@electronics-extreme/claude-sdlc

SDLC Strict Waterfall Kit

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

What this kit is

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.

Install

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.

Quick start (after install)

• 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

Manual bootstrap (alternative)

# Run inside your project directory — no arguments needed
cd ~/Projects/MyApp
npx @electronics-extreme/claude-sdlc init --harness claude

The methodology

Six phases, strictly ordered. No phase skips. Every phase gates on four checks plus two-pass reconciliation before sign-off:

docs/sdlc/01_requirement  →  docs/sdlc/02_design  →  docs/sdlc/03_implementation  →  docs/sdlc/04_testing  →  docs/sdlc/05_deployment  →  docs/sdlc/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.

What's in the kit

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.

Verifiable claims

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

Token budget

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.

Versioning + stability

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.

Contributing

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.yml publishes dist.zip

License

MIT — see LICENSE.

Privacy

Zero telemetry. Zero analytics. Zero remote fetch except user-invoked pricing-sync and harness marketplace installs. See PRIVACY.md.