SDLC

Structured Development Lifecycle — Closed-loop AI-assisted development for Claude Code.

npx @corecave/sdlc-framework

Works on Mac, Windows, and Linux.

"Every step forces the next. Every law is enforced. Every loop closes."

Why SDLC · Getting Started · The Loop · Commands · Engineering Laws · CI/CD

Why SDLC

AI-assisted development has a quality problem. Research shows:

• Context rot — LLM accuracy drops 60% past certain thresholds (Chroma Research, 2025)
• Security vulnerabilities 10x — AI code produces 10x more security findings (Apiiro, 2025)
• Rules get ignored — Cursor, Windsurf, and other tools routinely ignore their own rules
• Specs drift from code — OpenSpec, SpecKit, and others can't keep specs and code aligned
• Multi-agent chaos — 17x compounding error rate when chaining unreliable agents (MAST, 2025)
• No code review — Most frameworks skip review entirely, shipping unchecked AI output
• Manual testing — Frameworks that include testing require humans to click through UIs

SDLC fixes all of this with five principles:

1. Closed loop — SPEC → IMPLEMENT → VERIFY. Steps auto-advance with a 10-second delay — reply to intervene. No orphan plans. No skipped reviews.

2. Engineering Laws — SOLID, DRY, YAGNI, Clean Code, Security, and Testing are enforced as blocking gates at review. Not suggestions. Laws.

3. Automated verification — Playwright MCP replaces manual UAT. Acceptance criteria become automated tests.

4. Sub-agent driven development — Implementation tasks run in parallel via dependency-ordered waves. Each agent gets the spec, the laws, and the boundaries.

5. Clarification over assumption — The spec phase asks questions with recommendations. No guessing. No "I assumed you wanted..."

Who This Is For

Developers using Claude Code who want reliable, high-quality AI-assisted development.

• Junior developers — The framework explains every step. Follow the prompts.
• Senior developers — Engineering laws enforce the standards you care about. Fast-forward path for simple tasks.
• Teams — Consistent process across developers. Specs, reviews, and summaries create an audit trail.

Getting Started

npx @corecave/sdlc-framework

Choose global (all projects) or local (current project only). Verify with /sdlc:help in Claude Code.

Quick Start

# 1. Initialize the framework
/sdlc:init

# 2. (Optional) Brainstorm — AI asks questions, produces a PRD
/sdlc:discuss add user notifications

# 3. Define what to build (asks clarification questions)
/sdlc:spec

# 4. Build it (spawns parallel sub-agents)
/sdlc:impl

# 5. Steps auto-advance with 10s delay — reply to intervene
# Verify tests ACs, reviews code, reconciles, and closes the loop

Just Tell It What To Do

/sdlc:fast add a loading spinner to the submit button
/sdlc:fast the login form crashes on empty password
/sdlc:fast refactor auth to use dependency injection

/sdlc:fast is the default entry point. Describe your work in plain language. The framework classifies it (feature, bug, refactor, etc.), estimates complexity, and either executes inline or routes to the right command. Simple work runs the full loop in one shot. Complex work routes to /sdlc:spec with pre-filled context.

For Bugs

/sdlc:debug login form submits twice on slow connections

Follows: reproduce → isolate → root-cause → fix → verify.

The Loop

┌──────────────────────────────────────────────────────────┐
│  SPEC ──→ IMPLEMENT ──→ VERIFY                            │
│   │                        │                              │
│   └──── next cycle ←───────┘                              │
│                                                           │
│  Define    Build (parallel   Three-phase:                  │
│  work +    sub-agents per    1. AC testing                 │
│  ask Qs    dependency wave)  2. Laws review                │
│                              3. Reconcile + close          │
└──────────────────────────────────────────────────────────┘

DISCUSS — Explore the idea (optional, pre-loop)

• AI-driven brainstorming — you describe an idea, AI asks structured questions
• 4 rounds max: problem space → scope → research unknowns → approach validation → requirements detail
• Spawns research subagents when unknowns are detected (codebase patterns, external APIs, library choices)
• Every question includes a recommendation with concrete trade-offs
• Produces a PRD document at .sdlc/discuss/{topic}-PRD.md with research findings included
• User approval gate — PRD must be approved before routing to /sdlc:spec

SPEC — Define the work

• Asks clarification questions (no guessing)
• Presents options with trade-offs and recommendations
• Defines BDD acceptance criteria (Given/When/Then) with explicit verification types — each AC declares whether it's tested via Playwright MCP, curl, Bash, test runner, or DB queries
• Decomposes tasks with dependency graph for parallel execution
• Codebase gap analysis — reads existing code the spec touches, flags missing error handling, edge cases, validation gaps, and integration risks before implementation starts
• Spec integrity review — checks completeness, consistency, feasibility, verification types, and gap analysis (7 checks)
• User approval gate — spec must be explicitly approved before implementation starts

IMPLEMENT — Build it

• Pre-flight plan verification — validates AC↔task coverage, file existence, boundary compliance, and dependency integrity before spawning agents
• Analyzes task dependencies (DAG)
• Spawns parallel sub-agents per wave
• Each agent gets: task spec, engineering laws, boundaries
• Tracks progress via todo list

VERIFY — Test it + review it + close it (three phases in one command)

Phase 1 — Acceptance Criteria:

• Reads the declared verification type from each AC — no keyword guessing
• UI_INTERACTION: Playwright MCP (navigate, click, snapshot, screenshot, fill_form) with pre-check for browser availability
• API_ENDPOINT: curl requests with status code and body assertions
• CLI_BEHAVIOR: Bash command execution with stdout/stderr/exit code capture
• BUSINESS_LOGIC: project test runner (bun test, npm test, vitest, jest, pytest)
• DATA_INTEGRITY: database queries via CLI
• ACs missing a Type field are marked FAIL — never skipped, never guessed
• If any AC fails, stops immediately — no engineering review on broken code

Phase 2 — Engineering Laws Review (only runs after all ACs pass):

• Reviews all modified files against LAWS.md
• Checks: SOLID, DRY, YAGNI, Clean Code, Security, Testing, Naming, Error Handling
• Severity levels: BLOCKER (must fix), WARNING (should fix), INFO (consider)
• Blockers prevent loop closure — routes to /sdlc:fix for systematic fixing
• /sdlc:fix analyzes fix dependencies, applies fixes (parallel where possible), auto re-verifies

Phase 3 — Reconciliation & Closure (only runs after both quality gates pass):

• Reconciles spec vs actual implementation (tasks, ACs, files, boundaries)
• Records deviations, decisions, lessons learned
• Creates combined VERIFY.md with all three phases for audit trail
• Advances state to next plan or handles phase transition inline
• Phase transitions: verifies completeness, updates PROJECT.md, creates git commit, advances to next phase

Commands

10 commands, grouped by purpose. Run /sdlc:help for the full reference.

Core Loop

| Command | What it does | Forces next | |---------|-------------|-------------| | /sdlc:spec | Define work with acceptance criteria | → /sdlc:impl | | /sdlc:impl | Build via parallel sub-agents (with pre-flight plan verification) | → /sdlc:verify | | /sdlc:verify | Three-phase: AC testing + engineering laws review + reconcile and close the loop | → /sdlc:spec |

Quick Entry

| Command | What it does | |---------|-------------| | /sdlc:fast <desc> | Default entry point. Describe work → framework classifies, routes, or executes inline |

Fix & Debug

| Command | What it does | |---------|-------------| | /sdlc:fix | Fix code quality blockers systematically, auto re-verify | | /sdlc:debug <issue> | Structured debugging: reproduce → isolate → fix → verify |

Session & Status

| Command | What it does | |---------|-------------| | /sdlc:status | Show loop position, progress, forced next action | | /sdlc:status pause | Save context for break, create HANDOFF.md | | /sdlc:status resume | Restore context, ONE next action |

Planning & Discovery

| Command | What it does | |---------|-------------| | /sdlc:discuss [idea] | Brainstorm and research — AI asks questions, spawns research subagents for unknowns, produces a PRD |

Setup

| Command | What it does | |---------|-------------| | /sdlc:init | Initialize framework or add milestones | | /sdlc:help | Show command reference |

Engineering Laws

Laws are enforced at /sdlc:verify (Phase 2). Violations at error severity block loop closure.

| Law | Default | What it enforces | |-----|---------|-----------------| | SOLID | error | Single Responsibility, Open/Closed, Liskov, Interface Segregation, Dependency Inversion | | DRY | error | Search before create. No duplicate logic (3+ similar lines) | | YAGNI | error | Only build what's in the spec. No speculative features | | CLEAN_CODE | error | Max 40 lines/function, max 3 params, max 3 nesting levels | | SECURITY | error | No hardcoded secrets, input validation, parameterized queries | | TESTING | error | Every behavior change needs tests with meaningful assertions | | NAMING | warning | Descriptive names, no abbreviations, self-documenting code | | ERROR_HANDLING | error | No empty catch blocks, domain-specific exceptions, no swallowed errors |

Severity is configurable per project in .sdlc/LAWS.md:

• error — Blocks loop closure. Must fix.
• warning — Reported in review. Should fix.
• info — Noted only. Consider fixing.

Project Structure

.sdlc/
├── PROJECT.md          # Project context and requirements
├── STATE.md            # Loop position + forced next action
├── ROADMAP.md          # Milestones and phases
├── LAWS.md             # Engineering laws (configurable severity)
├── phases/
│   └── 01-phase-name/
│       ├── 01-01-SPEC.md
│       └── 01-01-VERIFY.md
├── discuss/            # PRD documents from /sdlc:discuss
└── research/           # Research findings (generated by /sdlc:discuss when unknowns detected)

How It Differs

vs. PAUL

| Aspect | PAUL | SDLC | |--------|------|------| | Commands | 26 (cognitive overload) | 11 (focused) | | Testing | Manual UAT | Automated (Playwright MCP) | | Code review | None | Engineering Laws enforcement | | Implementation | In-session | Sub-agent parallel waves | | Next action | Suggested | Forced | | Engineering standards | None | SOLID/DRY/YAGNI as blocking gates | | Fast path | None | /sdlc:fast for small tasks | | Debugging | None | /sdlc:debug structured flow |

vs. GSD / Speckit / OpenSpec

| Problem | Others | SDLC | |---------|--------|------| | Context rot | No mitigation | Session budget tracking, forced pause | | Rules ignored | Prompt-only | Post-generation validation at review | | Spec drift | Manual reconciliation | Automated close-loop reconciliation | | Security | Hope-based | Scanning as blocking gate | | Multi-agent errors | 17x compounding | Dependency-ordered waves, bounded scope | | Brownfield support | Greenfield focus | Incremental adoption, existing codebase first |

Installation Options

npx @corecave/sdlc-framework              # Interactive (choose global/local)
npx @corecave/sdlc-framework --global     # Install to ~/.claude/
npx @corecave/sdlc-framework --local      # Install to ./.claude/
npx @corecave/sdlc-framework --global --config-dir ~/.claude-custom

Staying Updated

npx @corecave/sdlc-framework@latest

CI/CD

Publishing to npm is automated via GitHub Actions with Trusted Publishers (OIDC provenance).

First-time setup

npm (Trusted Publisher):

1. Go to npmjs.com → @corecave/sdlc-framework → Settings → Trusted Publishers
2. Publisher: GitHub Actions
3. Organization or user: nadyshalaby
4. Repository: sdlc-framework
5. Workflow filename: publish.yml
6. Environment name: npm

GitHub:

1. Repo Settings → Environments → New environment → name it npm
2. Repo Settings → Secrets and variables → Actions → New repository secret → NPM_TOKEN (npm automation token)

Releasing a new version

# 1. Bump version
# Edit package.json version field

# 2. Commit and push
git add package.json
git commit -m "chore: bump version to x.y.z"
git push

# 3. Create a GitHub Release (triggers the publish workflow)
gh release create vx.y.z --title "vx.y.z" --notes "Description of changes"

The workflow runs npm publish --provenance --access public automatically.

Verifying a release

gh run list --workflow=publish.yml

Troubleshooting

Commands not found?

• Restart Claude Code to reload slash commands
• Verify files exist in ~/.claude/commands/sdlc/

Loop position seems wrong?

• Run /sdlc:status for current state
• Check .sdlc/STATE.md directly

Resuming after a break?

• Run /sdlc:status resume — it reads state and handoffs automatically

What's New in v1.0.2

• 3-step loop — The loop is now SPEC → IMPL → VERIFY. CLOSE is merged into VERIFY as Phase 3 (Reconciliation & Closure). One fewer command, one fewer step, one fewer artifact. The loop closes faster without sacrificing quality.
• Single artifact per plan — One VERIFY.md captures AC results (Phase 1), engineering laws review (Phase 2), and reconciliation summary with deliverables, deviations, decisions, and lessons (Phase 3). No separate SUMMARY.md.
• Model enforcement — New agent_model setting in STATE.md. Default: strongest (most capable model available at runtime). Sub-agents in /sdlc:impl and /sdlc:fix respect this setting for maximum code quality.
• Complete flow coverage — Every conditional path in every workflow has an explicit outcome. Deviation rejection routes back to implementation. No dead-ends.
• Rich chat output — Verify results use unicode box-drawing, status indicators (✅❌⚠️), and structured sections for clear observability during execution.
• 10 commands — /sdlc:close removed. Verify absorbs review and close. Research merged into discuss.

• Verify + Review merged into one command (two phases)
• Pre-flight plan verification in /sdlc:impl
• Playwright MCP pre-check for UI verifications
• Explicit verification types per AC (no keyword guessing)
• Codebase gap analysis and spec integrity review (7 checks)
• CI/CD via GitHub Actions with OIDC provenance

License

MIT License. See LICENSE for details.

AI writes code. SDLC makes it reliable.