| name | claude-code-sdlc |
| description | SDLC orchestration plugin for Claude Code. Drives projects through a
9-phase software development lifecycle with company-configurable profiles,
compliance gates, and quality enforcement.
Triggers: "start sdlc", "sdlc setup", "initialize project lifecycle",
"run phase gate", "advance phase", "sdlc status", "compliance check",
"project setup wizard", "lifecycle management".
|
claude-code-sdlc
SDLC orchestration plugin for Claude Code. Drives projects through a 9-phase software development lifecycle with company-configurable profiles, compliance gates, and quality enforcement.
What This Does
This plugin makes structured SDLC methodology executable in Claude Code. It provides:
- 9 phases — gated open (Discovery, Requirements, Design, Foundation) and gated close (Documentation, Deployment, Monitoring, Close & Transfer) bracketing a continuous Build loop (Intent→Delegate→Discern per change, no batch exit gate)
- Company profiles (YAML) defining stack, quality thresholds, compliance frameworks, and conventions
- 7-gate validation at every phase transition (integrity, completeness, metrics, compliance, consistency, quality, exit criteria)
- Compliance enforcement for SOC 2, HIPAA, GDPR, PCI-DSS
- Skill orchestration — maps each phase to existing Claude Code skills (
/deep-plan, /deep-implement, /tdd, /code-review, /security-review, /e2e, etc.)
Commands
| Command | Purpose |
|---|
/sdlc-setup | Interactive setup wizard — select profile, initialize .sdlc/ in your project |
/sdlc | Show current phase guidance, next action, required artifacts |
/sdlc-status | Progress dashboard with phase table and completion percentage |
/sdlc-gate | Run exit criteria checks for current phase (does not advance) |
/sdlc-next | Advance to next phase if all MUST gates pass |
/sdlc-enhance | Generate narrative companions for stakeholder review (optional) |
/sdlc-coach | Interactive coaching mode — adaptive dialogue for current phase |
/sdlc-intake | Catalog and summarize an external document corpus (Phase 0, opt-in) |
/sdlc-brief | Prep a stakeholder workshop brief from the document corpus |
/sdlc-spec | Author a ready Build-loop spec (specs/NNNN-name.md) and enforce the Definition of Ready |
/sdlc-review | Multi-perspective artifact review (council, adversarial, or edge-case modes) |
/sdlc-phase-report | Generate phase HTML report with artifact inventory and gate results |
/sdlc-audit | Analyze gate effectiveness across completed phases — identify always-pass and high-fail gates |
Quick Start
- Run
/sdlc-setup in your project directory
- Select a profile (e.g.,
microsoft-enterprise or starter)
- Run
/sdlc to see Phase 0 guidance
- Work through each phase, creating required artifacts
- Run
/sdlc-next when ready to advance
How It Works
The plugin maintains state in .sdlc/state.yaml in your project directory. Each phase has:
- Entry criteria — what must be true to start the phase
- Workflow — steps to follow, skills to use
- Required artifacts — files you must produce (stored in
.sdlc/artifacts/XX-phase/)
- Exit gates — 7-gate validation that must pass before advancing (gated phases only; the Build loop checks per change instead)
Phase transitions are atomic — either all MUST gates pass and you advance, or none do and you get a blockers report.
For long-running phases (especially the Build loop), session continuity is maintained through session-handoff.json — a structured JSON file that tracks section progress, blockers, and next actions across sessions. The session start hook reads this file and displays a continuity summary.
Profiles
Profiles configure the plugin for your company/team:
microsoft-enterprise — C#/.NET 8 + Angular 17 + Azure + SOC 2 compliancestarter — Minimal profile, no compliance, quick start
Profiles define: technology stack, quality thresholds (coverage, file size limits), compliance frameworks, coding conventions (commit format, naming, immutability).
Phases
Phase ids are strings (build and close are non-numeric); the 4/5/6 gap is intentional — batched check phases were replaced by per-change checking inside the Build loop. Advancement is always manual.
| id | Phase | Key Skills |
|---|
| 0 | Discovery | /plan |
| 1 | Requirements | /deep-project |
| 2 | Design | /deep-plan, /visual-explainer |
| 3 | Foundation | /deep-plan |
| build | Build Loop | /tdd, /code-review, /security-review, /e2e, /test-coverage |
| 7 | Documentation | /update-docs |
| 8 | Deployment | CI/CD |
| 9 | Monitoring | Manual |
| close | Close & Transfer | Manual |
Frozen Layers
After each phase completes (gates pass + human sign-off), a frozen layer is generated — a token-efficient (1500-2000 token) summary of all phase artifacts. Frozen layers:
- Enable cross-phase context continuity without reloading full artifacts
- Contain locked metrics (budget, timeline, scope) checked for consistency in later phases
- Are written to
.sdlc/context/layers/phase{N}-{name}.md
- Are generated by Claude reading all phase artifacts and condensing them into the template at
templates/frozen-layer.md
- Are validated by
scripts/validate_frozen_layer.py
- Are immutable once created
The /sdlc-next command handles frozen layer generation as step 5 (after HITL sign-off, before state advancement). See references/frozen-layers.md for format details.
Context Architecture
The plugin uses a 3-tier context system for token-efficient cross-phase continuity:
| Tier | Content | When Loaded | Budget |
|---|
| 1 Foundation | Project identity, constitution extract | Always (session start) | ~500 tokens |
| 1.5 Intake Index | Document corpus index with DOC-NNN IDs | Session start (when available) | ~5K tokens (configurable) |
| 2 Frozen Layers | Phase summaries with locked metrics | Session start (recent 3) | ~2K per layer |
| 3 Reference | Validation rules, compliance, guides | On-demand | Unbounded |
The session-start hook automatically loads Tiers 1-2 (and 1.5 when document intake was performed). Tier 1.5 is opt-in — only loaded when .sdlc/context/intake/index.md exists. Tier 3 docs in references/ are loaded when Claude needs specific guidance. See references/context-tiers.md for details.
Narrative Enhancement
Every SDLC artifact can have a .narrative.md companion — a prose-rich, stakeholder-friendly version that makes the same information accessible to non-technical audiences. Narratives are optional (gates don't require them) but recommended before stakeholder reviews.
- Run
/sdlc-enhance to generate narratives for the current phase's artifacts
- The
narrative-enhancer agent handles all generation
- See
references/narrative-patterns.md for transformation rules
Multi-Perspective Review
Run /sdlc-review to evaluate phase artifacts from multiple angles before advancing. Three modes:
--council (default) — 4-viewpoint review: Architecture, Product, Quality, Security--adversarial — Cynical QA: challenge assumptions, find quality issues--edge-cases — Exhaustive path analysis: find unhandled conditions and boundaries
Recommended before /sdlc-gate on design-heavy phases (2, 3) and during the Build loop. See references/agent-roster.md for phase-specific suggestions.
Smart Repair
When gate checks fail on structural issues (missing templates, empty sections, placeholder content), the gate-repair agent can attempt automatic fixes before escalating to the human. Repair is conservative — it scaffolds structure but never generates substantive content. The human always reviews what was repaired. See references/smart-repair.md for the full repair classification.
Conversational Coaching
For users who prefer guided dialogue over step lists, /sdlc-coach provides an adaptive coaching mode. The coach assesses the current phase state (which artifacts exist, what's missing), asks diagnostic questions, and generates artifacts as the conversation progresses.
Coaching mode enforces the same gates and requirements as the structured approach — it just changes the interaction style. See references/conversational-coaching.md for the full pattern library and per-phase diagnostic questions.
Human-in-the-Loop Protocol
This protocol is mandatory. Claude MUST NOT make significant project decisions autonomously. The SDLC is a collaboration — Claude drives the process, humans make the decisions.
When Claude MUST Stop and Ask
1. Before writing any artifact in a new phase
Read the incoming handoff document. Check for Q-NN (Open Questions) or AQ-NN (Architectural Questions). If any exist, resolve them with the human — using AskUserQuestion with concrete options — BEFORE writing any artifacts.
2. Before writing any ADR (Phase 2 and beyond)
Never choose an architectural approach without presenting options. For each decision:
- State the problem in one sentence
- Offer 2–3 concrete options with trade-offs
- Get a human selection
- Then write the ADR encoding that decision
3. Before finalizing scope or requirements (Phase 0–1)
Draft the key framing (executive summary, root cause statement, requirements list) and present it to the human for correction before writing the full artifact.
4. Before writing section plans (Phase 3: Foundation)
Present the proposed section breakdown — boundaries, order, complexity estimates — and get human approval before writing individual SECTION-NNN.md files.
5. Before advancing any phase
Do not call advance_phase.py immediately after gates pass. Present the phase summary and explicitly ask for human sign-off.
What Claude May Do Without Asking
- Read files, search the codebase, explore project structure
- Write artifact drafts for human review (but flag them as drafts)
- Run gate checks and report results
- Format, organize, and structure content within a human-approved direction
Pause Markers in Phase Definitions
Phase definition files use > HITL GATE: blockquotes to mark mandatory pause points. When Claude encounters one, it MUST stop and interact with the human before proceeding.
Phase definitions also use > CHECKPOINT: blockquotes to mark mandatory agent-enforced stopping points. The agent MUST complete all listed conditions before proceeding. Unlike HITL GATE, checkpoints do not require human interaction — they enforce workflow discipline within the agent's execution.
Visual Report Protocol
This protocol is mandatory for every phase. Before requesting human sign-off to advance, Claude MUST generate an interactive HTML visual report summarizing the phase's artifacts, decisions, and key data. These reports replace ASCII art and inline markdown tables for stakeholder review.
When to Generate
Generate a visual report as the second-to-last step of every phase, immediately before the "Generate Phase Report" step (which runs the gate check). The visual report is the stakeholder review artifact; the gate report is the automated validation artifact. Both are required.
What Each Phase Report Contains
| Phase | Visual Report | Key Visualizations |
|---|
| 0 Discovery | Problem space overview | Persona cards, current state flow diagram, scope boundaries |
| 1 Requirements | Requirements matrix | Requirements by domain/priority, traceability matrix, epic overview |
| 2 Design | Architecture diagrams | Layer diagram, core flow, data flow, section dependencies, trust boundaries |
| 3 Foundation | Section review & sprint plan | Section breakdown table, sprint timeline, dependency DAG, risk cards |
| build Build Loop | Build progress | Section completion status, test coverage dashboard, code metrics, review & security findings, test pass/fail by category |
| 7 Documentation | Documentation audit | Docs completeness matrix, API coverage, README status |
| 8 Deployment | Release checklist | Deployment readiness, environment status, rollback plan |
| 9 Monitoring | Monitoring dashboard | Health checks, alert configuration, baseline metrics |
| close Close & Transfer | Handoff & retrospective | Transfer checklist, lessons learned, final metrics, ownership map |
How to Generate
- If
/visual-explainer skill is available: Invoke it with a detailed prompt describing the phase's data, the desired diagrams, and output path (.sdlc/reports/phaseNN-visual.html).
- If not available: Generate equivalent self-contained HTML directly using Mermaid.js CDN for flowcharts/DAGs, HTML
<table> for data tables, and CSS Grid for card layouts.
- Never fall back to ASCII art in the final report. Inline text summaries are fine for chat, but the review artifact must be rendered HTML.
Visual Standards
- Self-contained HTML (no external assets except CDN fonts and Mermaid)
- Dark theme default matching SDLC reports (
#0f1117 bg, #6c8ef7 accent, #4ade80 green)
- Sticky sidebar TOC for navigation between sections
- Zoom controls on all Mermaid diagrams
- Staggered fade-in animations (respect
prefers-reduced-motion)
- Both light and dark theme support via
prefers-color-scheme
- Responsive layout (sidebar collapses to horizontal bar on mobile)
Artifact Sub-Pages (MANDATORY)
Every phase visual report MUST include linked sub-pages for each artifact. The main report is a summary; sub-pages contain full artifact detail.
- Main report:
.sdlc/reports/phaseNN-visual.html (or phaseNN-discovery.html, etc.) -- summary with highlights from each artifact
- Sub-pages:
.sdlc/reports/phaseNN-<artifact-name>.html -- full rendered content of each artifact (e.g., phase00-problem-statement.html, phase00-constraints.html)
- Linking: The main report's artifact inventory section MUST link to each sub-page. Each sub-page MUST link back to the main report.
- Consistency: Sub-pages use the same dark theme and styling as the main report.
This ensures the summary stays scannable while full detail is always one click away for stakeholder review.
Project Index Page (MANDATORY)
An index page at .sdlc/reports/index.html MUST exist. It serves as the single entry point for all project documentation.
- Auto-create: Generate
index.html when the first phase report is created (typically Phase 0).
- Auto-update: Update
index.html every time a phase report is generated or a phase advances. Update phase status badges, dates, and report links.
- Contents: Project header (name, profile, type, start date, current phase), mission statement, link to constitution, and a timeline of all 9 phases showing status (active/completed/pending) with links to phase reports.
- End state: By project completion,
index.html is a complete navigable dashboard of the entire SDLC history.
Output Location
All reports are written to .sdlc/reports/:
index.html -- project dashboard (single entry point)phase00-visual.html, phase01-visual.html, ..., build-visual.html, ..., close-visual.html -- phase summary reports (numeric phases use phaseNN-; the Build loop and Close use their build / close slug)phase00-<artifact>.html, phase01-<artifact>.html, ... -- artifact sub-pages- Additional named reports (e.g.,
architecture-diagrams.html, phase03-section-review.html) are encouraged alongside the numbered report
Agent Orchestration Protocol
Claude MUST use the Agent tool to spawn specialized subagents rather than doing all work inline. The Agent tool produces better results for non-trivial tasks: subagents have focused context, specialized instructions, and independent execution. This is not optional.
See references/agent-roster.md for the full phase-by-phase mapping with conditions, parallel groups, and background policy.
Mandatory Spawns (No Exceptions)
| Trigger | Agent | Behavior |
|---|
| Build or compilation fails | build-error-resolver | Spawn immediately. Do not attempt manual fixes first. |
| Code touches auth, payments, secrets, or PII | security-reviewer | Foreground. STOP on CRITICAL/HIGH findings. |
| Build loop + profile requires TDD | tdd-guide | Spawn BEFORE writing any code for the change. |
| Per-change check in the Build loop | code-reviewer + security-reviewer | Spawn both in a single message (parallel, foreground). |
| A change in the Build loop completes | section-evaluator | Foreground, blocking. FAIL verdict = fix before proceeding. |
| Build loop with independent changes | Domain-specific agents | Spawn in parallel (single message) for non-dependent changes. |
| Gate check fails unexpectedly | Explore | Investigate root cause before attempting fixes. |
Phase-by-Phase Agent Roster (Summary)
| Phase | Primary Agents | Conditional Agents |
|---|
| 0 Discovery | — | Explore (existing codebase) |
| 1 Requirements | — | Explore, feedback-synthesizer |
| 2 Design | architect | backend-architect, frontend-developer, security-reviewer |
| 3 Foundation | deep-plan:section-writer | Plan, Explore |
| build Build Loop | Domain agents per change | tdd-guide, section-evaluator, code-reviewer, security-reviewer, build-error-resolver, test-writer-fixer, e2e-runner, api-tester, performance-benchmarker, refactor-cleaner (background) |
| 7 Documentation | doc-updater | backend-architect (API docs) |
| 8 Deployment | devops-automator | e2e-runner (smoke tests), build-error-resolver |
| 9 Monitoring | — | performance-benchmarker, feedback-synthesizer |
| close Close & Transfer | — | doc-updater, feedback-synthesizer |
Parallel Execution Rules
Use a single message with multiple Agent tool calls when:
- Two or more Build loop changes have no dependency on each other (e.g., backend + frontend changes).
- A per-change check fires in the Build loop — always launch
code-reviewer and security-reviewer simultaneously.
- Testing in the Build loop — launch
test-writer-fixer, e2e-runner, and api-tester simultaneously when all apply.
- Phase 3 (Foundation) has multiple independent section plans to generate.
Use sequential Agent calls when:
- One agent's output is the input to the next (e.g.,
tdd-guide must complete before the implementation agent starts).
- A security CRITICAL/HIGH finding must be resolved before proceeding.
- A build failure must be fixed before continuing.
Pattern for parallel change implementation:
# Single message — two Agent tool calls fire simultaneously:
Agent(backend-architect, "Implement SECTION-002 per .sdlc/artifacts/03-foundation/section-plans/SECTION-002.md")
Agent(frontend-developer, "Implement SECTION-003 per .sdlc/artifacts/03-foundation/section-plans/SECTION-003.md")
Background Agents
Run with run_in_background: true (non-blocking):
doc-updater — documentation updates during the Build looprefactor-cleaner — dead code cleanup during the Build loopcode-reviewer — rolling per-change review in the Build loopdeep-implement:code-reviewer — diff review against section plans
Never background: security reviews, build error resolution, or any work producing phase gate artifacts.
Domain Agent Selection (Build loop)
| Change domain | Primary agent |
|---|
| Python / C# / server-side logic | backend-architect |
| HTML / CSS / Angular / React | frontend-developer |
| CI/CD / cloud infrastructure | devops-automator |
| Spike / proof-of-concept | rapid-prototyper |
| Any change with auth / payments / secrets | + security-reviewer (foreground) |
Reference Material
Detailed documentation is in the references/ directory:
state-machine.md — State format and transition rulesvalidation-rules.md — 7-gate validation system detailsskill-mapping.md — Phase-to-skill mappingagent-roster.md — Phase-to-subagent mapping with parallel groups and conditionscompliance-frameworks.md — SOC 2, HIPAA, GDPR, PCI-DSS gate definitions
