sdlc-framework 0.16.0

Local-only multi-AI SDLC framework with auto-detect engine, tier-aware DoD, and GitHub integration

SDLC Framework

A local-only, multi-AI SDLC framework. One sdlc CLI scaffolds a 5-phase project, auto-detects DoD evidence, dispatches the right specialist subagent for each stage, and tracks per-feature task progress with strict sequential TDD.

Works with 8 AI coding tools: Claude Code · GitHub Copilot · Cursor · OpenAI Codex · Aider · Windsurf · Cline · Continue.

---

Table of contents

1. What it does
2. Install + first project
3. Adopt an existing project
4. Workflow guideline (6 approaches)
5. Daily commands
6. Concepts
7. AI tool support
8. Specialist subagents
9. Repo layout
10. Advanced
11. Contributing

---

What's new

0.16.0 — 2026-05-02

Phase 2 → Phase 3 architecture-to-code bridge + activity-based stage labels.

Architecture-to-code bridge

Closes the defect where bootstrap created src/<user-story-slug>/ folders regardless of architecture, producing parallel "code-soup" islands that the user had to manually rewire (observed across Cursor, Copilot, and Claude). Cursor / Copilot / Claude were following the rails correctly — the rails were laid in the wrong direction.

• New Phase 2 DoD item code-structure-mapped (architecture sub-track). Architect-agent must produce 02-Design/00-Code-Structure.md mapping each C4-L2 container to a src/<folder>/ and each user story to its primary container.
• Scaffold template 02-Design/templates/00-Code-Structure.md with §1 container → folder, §2 user-story → container, §3 dependency rules.
• sdlc tasks bootstrap now consults 02-Design/*Code-Structure*.md. Each task yaml gains a container: field; code_glob becomes src/<container>/<module-hint>* instead of src/<slug>/**. Unmapped stories surface a warning per story so the user can fill them in. When the file is absent, the legacy slug behavior is preserved with a one-line deprecation warning.
• developer-agent, phase-3-developer, test-author, code-reviewer, security-reviewer brief slices now include the §1 container → folder map and §3 dependency rules. Code-writing agents finally see the architectural anchor instead of inferring layout from the task glob alone.
• phase-2-architect.md mandate updated: Code Structure is now listed as a non-negotiable Phase 2 deliverable for tier 1/2 projects.

Phase 3 stage labels — activity-based

Closes the lag where the dashboard / state.json named stages after the deliverable already produced instead of the activity in flight. Symptom: while developer-agent was actively writing code, the stage still showed write-tests because tests existed and code did not — one nhịp behind reality. Same lag at every transition.

• Stages renamed to label the activity happening NOW. Old: pending → write-tests → write-code → review → done. New (6 stages): pending → write-tests → write-code → review → await-merge → done.
• pending is now narrowed to queued behind the Phase 3 serial lock (inactive groups). Active tasks with no deliverables go straight to write-tests — that is the activity test-author is performing.
• await-merge is new — distinguishes "code-reviewer is doing its local job" (review) from "PR open, waiting for human merge" (await-merge).
• auto-mad-step behavior preserved exactly: at stage review (both files, no PR) it auto-opens the PR; at stage await-merge it parses the verdict block and auto squash-merges on PASS + critical=0.
• stage_to_subagent mapping shifted accordingly: write-tests → test-author, write-code → developer-agent, review → code-reviewer (or security-reviewer for sensitive areas), await-merge → none, pending → none.

0.15.0 — 2026-05-02

Phase 3 serial lock + mad-mode auto-PR-merge.

• Phase 3 now runs strictly serial: only one feature_id group is "active" at a time. Inactive tasks always show stage: pending regardless of filesystem state. Fixes the bug where one task's commit advanced every task to write-code simultaneously (most visible on GitHub Copilot).
• auto-mad-step now auto-opens PRs after write-code and auto squash-merges after review when the code-reviewer verdict block is PASS with zero critical findings. New stop reasons: code_review_failed, pr_open_failed, merge_failed.
• New CLI: sdlc tasks activate <id>, sdlc tasks active, sdlc tasks unlock, sdlc tasks force-merge <id> --i-accept-the-risk.
• Code-reviewer agent prompt now mandates a <!-- sdlc:review-verdict ... --> block at the end of every review file. Missing/malformed → fail-safe to BLOCK.
• AI-tool prompts (Copilot, Cursor, Cline, Continue, Windsurf, Aider, Codex) now include a CONTRACT section forbidding direct state mutation and cross-phase drift.
• Schema migration state.json v2 → v3 (idempotent, automatic on first scan after upgrade). Adds phase3 block.

---

What it does

flowchart LR
  Idea[Idea / brief] --> P1[1. Planning]
  P1 --> P2[2. Design]
  P2 --> P3[3. Development]
  P3 --> P4[4. E2E & Integration]
  P4 --> P5[5. Deploy & Monitor]
  P5 -. metrics & feedback .-> P1

Phase	Focus	Sub-tracks	Subagent(s)
1 — Planning	PRD, user stories, NFRs, RACI, risks	—	pm-agent, security-reviewer (risks)
2 — Design	C4 architecture + UI/UX	Architecture · UI/UX	architect-agent, ux-designer, security-reviewer
3 — Development	Setup + per-task Kanban with sequential TDD	Setup · Tasks	test-author → developer-agent → code-reviewer
4 — Testing	E2E, integration, smoke, regression, load	—	qa-engineer
5 — Deploy & Monitor	CI/CD, runbook, SLOs, incident response	—	sre-agent

The engine scans your repo (sdlc scan or sdlc scan --watch), evaluates DoD rules from automation/rules.json, writes state.json, and the dashboard renders it. AI agents read the same rules to know what evidence to produce next.

---

Install + first project

pip install --upgrade sdlc-framework

mkdir my-app && cd my-app
sdlc setup                                      # interactive: pick AI tools, scaffold
sdlc start "Mobile task app for 5-person team"  # save your idea

Then in Claude Code (or your AI tool of choice):

/sdlc-start "Mobile task app for 5-person team"

The slash command invokes pm-agent, drafts 01-Planning/01-PRD.md from 01-Planning/IDEA.md, and reports progress. Run /sdlc-next to advance.

Prefer the terminal? Same loop:

sdlc next                  # paste-ready prompt for the next pending item
sdlc scan --print          # progress summary
sdlc resume                # "where am I?"
sdlc dashboard --port 8765 # live UI

---

Adopt an existing project

For a project already mid-development or in production:

cd ~/Projects/existing-app
sdlc adopt

sdlc adopt is idempotent and non-destructive: it scans for existing assets (docs/PRD.md, docs/ARCHITECTURE.md, runbooks, SLO docs, CI workflows…), creates symlinks (or copies on Windows) into the canonical SDLC paths, and auto-verifies them with the marker imported-from-existing. Your existing files stay where they are.

For Phase 3 you choose:

• Legacy mode — existing src/ is grandfathered (no TDD enforcement); only new features go through tasks.
• Skip mode — manage tasks manually.

After adopt, sdlc resume shows your starting point.

Not sure which workflow fits your situation? See GUIDELINE.md for 6 approaches (greenfield, new feature, replan, auto-adopt, manual adopt, legacy reconstruct) with a decision table, command sequences, and the file-path ↔ DoD item-id mapping used by sdlc verify.

---

Daily commands

# day-to-day
sdlc resume                              "where am I?" (aliases: status, where)
sdlc next [--json]                       paste-ready prompt for next pending item
sdlc verify <item-id> [--name=<who>]     mark a Phase 1/2/4 artifact verified
sdlc tasks bootstrap                     auto-create tasks from user stories
sdlc tasks list | new <id> | rm <id>     manage Phase 3 tasks

# engine
sdlc scan [--watch] [--print]            run engine, write state.json
sdlc dispatch [--json]                   inspect next-agent decision
sdlc dashboard [--port N]                serve the live UI

# autopilot
sdlc auto-step                           one iteration of /sdlc-auto
sdlc auto-mad-step                       one iteration of /sdlc-auto-mad (YOLO)

# adjustments
sdlc replan [--scope=...] [--clear]      mark items dirty after a major change

# integrations (low-level; agents call these automatically)
sdlc agent-log start|done|fail ...
sdlc notify <kind> <id> <title> <body>
sdlc gh-issue --clarification PATH | --gate ID
sdlc gh-pr [--ready] [--base BRANCH]
sdlc build-ai-configs                    regenerate the 8 AI tool configs

# migrations
sdlc migrate-v2                          v0.6.x → v2 (3-phase → 5-phase)
sdlc migrate-v3                          v0.7/v0.8 → v3 (rename + reorder)

sdlc --version

---

Concepts

project.yaml — tier-aware DoD strictness

The engine reads project.yaml and adjusts evidence strictness per tier:

Rule	Tier 1 (critical)	Tier 2 (standard)	Tier 3 (experiment)
nfr-targets	p99 AND (RTO or RPO)	p95 / p99	optional
security-threat-model	STRIDE + Mitigation per asset	STRIDE only	optional
tdd-coverage-active	strict 1:1	strict 1:1	strict 1:1
phase5-signoff	sponsor + eng_lead + sre + security	sponsor + eng_lead + sre	eng_lead only
owners-defined	sponsor + eng_lead + security + sre	sponsor + eng_lead + sre	sponsor + eng_lead

Minimal schema:

schema_version: 3
name: my-app
team: platform
stack: node
tier: 2
phase_target: 3
repo_url: https://github.com/your-org/my-app
owners:
  sponsor: [e-mail]
  eng_lead: [e-mail]
  sre: [e-mail]
flags:
  ai_disclosure_required: true
  signoffs_strict: auto
legacy_code_globs: []     # for retrofits — exclude from TDD coverage

Per-artifact verify (Phase 1, 2, 4)

Each artifact has two states: drafted (file exists with content) and verified (file ends with <!-- sdlc:verified-by: <name> <iso-date> -->). Both required for done.

sdlc verify prd-drafted --name="alice"
# records to automation/.verifications.json + appends marker

For retrofits, sdlc adopt --auto writes the marker as imported-from-existing so the audit trail honestly reflects provenance.

Phase 3 task lifecycle (sequential TDD strict)

Tasks live in automation/tasks/<id>.yaml. Each progresses through 5 stages sequentially:

pending → write-tests → write-code → review → done

Stage detection is automatic (filesystem + gh pr view):

Stage	Detection	Subagent invoked
pending	no code, no tests	test-author
write-tests	tests exist, no code	developer-agent
write-code	tests ≥ code, no PR	code-reviewer (or security-reviewer if sensitive)
review	PR open	(waits for human merge)
done	PR merged	(terminal)

Each subagent runs in a fresh context — no memory leakage between stages. Bootstrap from user stories:

sdlc tasks bootstrap   # one task per `## Story:` heading in 01-Planning/02-User-Stories.md

Or manual:

sdlc tasks new feature-billing --label="Billing — Stripe" \
  --code-glob="src/billing/**/*.ts" \
  --test-glob="src/billing/**/*.test.ts"

Autopilot

Two modes — same loop, different stop policy.

Stop reason	/sdlc-auto	/sdlc-auto-mad
verify_needed	stop	auto-verify (marker ai-mad-mode)
gate	stop	auto-sign (approved_by: ai-mad-mode)
clarification	stop	stop
high_risk	stop	stop (auth / crypto / payment)
review_pending	stop	stop (PR is external)

/sdlc-auto-mad is opt-in YOLO for prototypes / hackathons / throwaway projects. Every auto-signed yaml is clearly marked with an unsign_command. To revert ALL ai-mad-mode signoffs:

grep -l "approved_by: ai-mad-mode" automation/signoffs/*.yaml | xargs rm
sdlc scan

Smart dispatcher

sdlc dispatch returns:

• The primary agent for the next pending item (resolved as: stage-specific for tasks > item override > phase default).
• A parallel_agents list — cross-cutting agents to invoke alongside (e.g., risks-identified invites pm-agent + security-reviewer).
• A blocked_by field — names the earlier-phase blocker when phase_target can't be honored.

Replan workflow

Requirements changed? Tech-stack pivot?

sdlc replan
# Interactive: pick scope (requirements / ui-ux / tech-stack / scale-nfr / custom)
# Affected items go red until you redo them.
# Audit clarification written to automation/clarifications/replan-<ts>.md
sdlc replan --clear   # drop dirty markers when done

STOP triggers (autonomous loop)

When operating without a human, agents follow automation/AGENT-LOOP.md and stop on:

• 🔍 Ambiguity — insufficient information
• ⚔️ Conflict — sources disagree
• 🚪 Gate — sign-off needed
• 🛑 High-risk path — auth / crypto / payment / migrations / secrets

Resolve a clarification: edit the file, change STATUS: open → resolved. Approve a gate: write automation/signoffs/<gate-id>.yaml with approved: true.

---

AI tool support

Single shared source in ai-tools/shared-prompts/standards.md plus a per-tool header. sdlc setup (or sdlc build-ai-configs) generates 8 configs:

Tool	Output path	Native commands
Claude Code	CLAUDE.md + .claude/agents/*.md + .claude/commands/sdlc-*.md + .claude/skills/sdlc/SKILL.md	/sdlc-init /sdlc-start /sdlc-next /sdlc-scan /sdlc-dispatch /sdlc-dashboard /sdlc-auto /sdlc-auto-mad
Cursor	.cursorrules + .cursor/rules/sdlc.mdc	(auto-loaded rules)
GitHub Copilot Chat	.github/copilot-instructions.md + .github/prompts/sdlc-*.prompt.md	(prompt files)
OpenAI Codex	AGENTS.md	(text rules)
Aider	.aider.conf.yml + CONVENTIONS.md	(text rules + CLI)
Windsurf	.windsurfrules	(text rules)
Cline	.clinerules	(text rules)
Continue	.continuerules + .continue/config.json	(text rules)

Edit ai-tools/shared-prompts/standards.md, run sdlc build-ai-configs, all 8 files regenerate. Each carries a <!-- AUTO-GENERATED --> header so devs don't hand-edit.

---

Specialist subagents

11 role specs that any AI tool can read.

Subagent	Phase / stage	Role
pm-agent	Phase 1	PRDs, user stories with G/W/T, quantified NFRs, stakeholders, risks
architect-agent	Phase 2 (Architecture)	C4, API spec, DB schema, ADRs
ux-designer	Phase 2 (UI/UX)	UI specs, wireframes, design system, accessibility
security-reviewer	Phase 1/2/3	AppSec — risks, threat model, sensitive code review
test-author	Phase 3 pending → write-tests	Tests-first (TDD red phase)
developer-agent	Phase 3 write-tests → write-code	Production code (TDD green phase)
code-reviewer	Phase 3 write-code → review	Code quality review
qa-engineer	Phase 4	E2E, integration, smoke, regression, load
sre-agent	Phase 5	CI/CD, runbook, SLOs, incident response
doc-keeper	cross-cutting	Sync docs after behavior changes
clarification-triager	cross-cutting	Resolve STOP triggers

Same files in .claude/agents/ (Claude Code subagent format with frontmatter — opt-in, bypasses plugin skills).

---

Repo layout

your-repo/
├── project.yaml                       # metadata (engine reads this)
├── automation/
│   ├── rules.json                     # DoD rules (5 phases, sub-tracks)
│   ├── state.json                     # AUTO-GENERATED snapshot (gitignored)
│   ├── tasks/<id>.yaml                # Phase 3 task definitions
│   ├── clarifications/*.md            # STOP triggers; user resolves
│   ├── signoffs/<gate-id>.yaml        # gate approvals
│   ├── reviews/<task-id>-<ts>.md      # code-reviewer findings
│   ├── agent-runs.jsonl               # AUTO-GENERATED activity log (gitignored)
│   ├── notifications.log              # AUTO-GENERATED (gitignored)
│   ├── .verifications.json            # AUTO-GENERATED verify audit (gitignored)
│   └── .replan.json                   # AUTO-GENERATED dirty markers (gitignored)
├── 01-Planning/                       # Phase 1 templates + filled artifacts
├── 02-Design/                         # Phase 2 (architecture + UI/UX)
├── 03-Development/                    # Phase 3 standards + AI configs
├── 04-Testing-Deploy/                 # Phase 4 + 5 templates + filled artifacts
├── agents/                            # 11 role specs (English)
├── .claude/
│   ├── agents/                        # Claude Code subagent format
│   ├── commands/sdlc-*.md             # slash commands
│   └── skills/sdlc/SKILL.md           # auto-trigger skill
├── ai-tools/<tool>/<file>             # 8 AI tool configs (auto-generated)
├── .cursor/rules/sdlc.mdc             # Cursor rules
├── .github/
│   ├── workflows/ci.yml               # selected CI template
│   ├── copilot-instructions.md        # Copilot
│   └── prompts/sdlc-*.prompt.md       # Copilot Chat prompts
├── dashboard/
│   ├── index.html                     # ops-console UI
│   └── state.json                     # mirror of automation/state.json
└── CLAUDE.md / .cursorrules / AGENTS.md / ...    # 8 root-level configs

State flow: AI agent writes file → engine scans → state.json updated → dashboard refreshes → dispatcher decides → next agent.

---

Advanced

Dashboard

A compact ops-console (single viewport, no scroll). Auto-fetches dashboard/state.json every 3 seconds.

• Top header — live status dot, project meta, overall %.
• Alert banners — STOP triggers, gates, replan-dirty, unverified drafts (each with a [Copy path] button).
• "You are here" card — current phase + active item + paste-ready /sdlc-next prompt. Phase 3 tasks show stage pills [pending][write-tests][write-code][review][done].
• Phase tracker — 5 phase rows with sub-track columns.
• Side panel — Resume card, project info, activity timeline, quick links.

sdlc scan --watch                # re-scan every 3s; fires desktop notifications
sdlc dashboard --port 8765       # http://localhost:8765/dashboard/

The state file is rewritten only when the engine runs (sdlc dashboard itself just serves static files). Agents call sdlc scan after every artifact write to a phase-owned path so the UI stays live without a watch loop.

Project memory bundle

Every sdlc scan regenerates automation/.context-bundle.md (mirrored to dashboard/.context-bundle.md) with:

• Project name + stack + current phase
• Top 3 PRD goals
• Last 8 ADRs
• Active DoD item, recent agent runs, open clarifications, pending gates
• Anything in automation/CONTEXT-PINS.md

Sub-agents read this bundle (or a role-tailored slice) instead of re-reading PRD + stories + architecture every invocation. Cap is 12 KB; sections truncate before the cap.

automation/CONTEXT-PINS.md — your override file

For facts the engine cannot infer (verbal decisions, gotchas, deprecations in flight):

# Context Pins
## Tech decisions
- Auth: VNPay (NOT Stripe — switched 2026-04-15 due to VN customer base)

## Gotchas
- Postgres users.email — always wrap in LOWER(); legacy rows mixed-case.

Plain markdown — no DB, no service. Edit, save, run sdlc scan. The engine concatenates its contents under ## User pins in the bundle.

Desktop notifications

In --watch mode, every newly appearing clarification or pending gate fires:

• macOS — osascript display notification (sound on gate)
• Linux — notify-send -u critical|normal --app-name=SDLC
• elsewhere — silent fallback (log line in automation/notifications.log)

Transition-only: items that stay pending across many scans only fire once.

GitHub integration

sdlc gh-issue --clarification automation/clarifications/001-foo.md
# → creates a GitHub Issue, writes issue_url back into the file (idempotent)

sdlc gh-issue --gate phase5-signoff
# → creates "Gate pending: <label>" issue

sdlc gh-pr [--ready] [--base main]
# → opens a Draft PR (or reuses existing)

All three exit 0 when gh is missing/unauthenticated. The engine reads issue_url back into state.json and the dashboard shows ↗ icons.

TDD coverage rule

The built-in tdd-coverage rule (Phase 3 Setup sub-track) enforces strict 1:1 source-to-test pairing across all tiers. Paths in legacy_code_globs are excluded — retrofit projects don't get punished for old code.

---

Contributing

git clone https://github.com/vuonglq01685/SDLC.git
cd SDLC
python3 -m pip install --user -e .
python3 -m pip install --user -r automation/requirements-dev.txt

python3 -m pytest automation/tests/ -v
bash scripts/tests/test_setup.sh
bash scripts/tests/test_agent_log.sh
bash scripts/tests/test_notify.sh
bash scripts/tests/test_gh_wrappers.sh

bash scripts/sync-scaffold.sh     # refresh package scaffold from repo content
python3 -m build                  # build wheel + sdist

The framework eats its own dog food: it has its own project.yaml, runs its own engine on itself, and the owners-defined rule is intentionally red here so you can see it work in the dashboard.

---

License & links

MIT.

• PyPI
• GitHub
• C4 model
• OWASP ASVS
• Conventional Commits