sdlc-framework 0.13.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 sequential TDD strict.

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

---

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 & Requirements	PRD, user stories, NFRs, RACI, risks (per-artifact verify)	—	pm-agent, security-reviewer (risks)
2. Design	C4 architecture + UI/UX	🏛️ Architecture · 🎨 UI/UX	architect-agent, ux-designer, security-reviewer (security-threat-model)
3. Development	Setup infrastructure + per-task Kanban with sequential TDD	🛠️ Setup · ✅ Tasks	test-author → developer-agent → code-reviewer
4. E2E & Integration Testing	E2E specs, integration, smoke, regression, load	—	qa-engineer
5. Deploy & Monitor	CI/CD, runbook, SLOs, incident response, observability	—	sre-agent

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

---

Quickstart — new project

pip install --upgrade sdlc-framework

mkdir my-app && cd my-app
sdlc setup                                       # interactive: picks AI tools + scaffolds
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 the pm-agent subagent, drafts 01-Planning/01-PRD.md from 01-Planning/IDEA.md, and reports progress. Run /sdlc-next to advance to the next pending item.

CLI alternatives if you prefer terminal:

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

---

Quickstart — existing running project

For a project already mid-development or in production, run:

cd ~/Projects/existing-app
sdlc adopt                 # auto-detects PRDs, designs, code, runbooks
                           # auto-verifies what already exists
                           # marks src/** as legacy_code_globs (no TDD enforcement on old code)

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

For Phase 3 development, you choose:

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

After sdlc adopt, run sdlc resume to see your starting point.

---

Migrating between schema versions

v0.6.x → v0.7+ (3-phase → 5-phase):

sdlc migrate-v2 [--dry-run] [--auto]

Backs up automation/rules.json → rules.json.v1.bak, replaces with the v2 5-phase schema, renames phase4-prod.yaml signoff to phase5-prod.yaml, bumps project.yaml.schema_version to 2. Idempotent.

v0.7/v0.8 → v0.9 (rename + reorder):

sdlc migrate-v3 [--dry-run] [--auto]

Backs up automation/rules.json → rules.json.v2.bak, replaces with the v3 schema (verb-first IDs, no abbreviations, reordered by causal flow), renames keys in automation/.verifications.json (preserves verify history), renames signoff filenames (phase1-prd.yaml → phase1-signoff.yaml, phase2-design.yaml → phase2-signoff.yaml, phase5-prod.yaml → phase5-signoff.yaml), bumps project.yaml.schema_version to 3. Idempotent.

---

CLI reference

# getting started
sdlc setup [--tools=...] [--stack=...]   interactive scaffold + AI tool selection
sdlc adopt [--auto] [--dry-run]          retrofit SDLC on an existing project
sdlc start "<idea>"                      save your idea (used by /sdlc-start)
sdlc next [--json]                       paste-ready prompt for the next pending item

# day-to-day
sdlc resume                              "where am I?" — phase, last activity, next action
                                         (aliases: status, where)
sdlc verify <item-id> [--name=<who>]     mark a Phase 1/2/4 artifact as verified
sdlc tasks bootstrap                     auto-create tasks from Phase 1 user stories
sdlc tasks list                          list tasks with current stage
sdlc tasks new <id> [--label=...]        manual task creation
sdlc tasks rm <id>                       delete a task

# engine
sdlc scan [--watch] [--print]            run the engine; write state.json
sdlc dispatch [--json]                   inspect dispatch decision (next agent + parallel + blocked)
sdlc dashboard [--port N]                serve the live UI

# adjustments
sdlc replan [--scope=...] [--clear]      mark items dirty after a major change
                                         scope: requirements / ui-ux / tech-stack / scale-nfr / custom

# integrations (low-level wrappers; AI agents call them automatically)
sdlc agent-log start|done|fail ...       activity log entry
sdlc notify <kind> <id> <title> <body>   desktop notification
sdlc gh-issue --clarification PATH       file a GitHub Issue (idempotent)
sdlc gh-pr [--ready] [--base BRANCH]     open a Draft PR
sdlc build-ai-configs                    regenerate the 8 AI tool configs
sdlc migrate-v2                          upgrade v0.6.x project to v2 schema
sdlc migrate-v3                          upgrade v0.7/v0.8 project to v3 (rename + reorder)

sdlc --version                           print 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	needs p99 AND (RTO or RPO)	p95 / p99	optional
security-threat-model	STRIDE + Mitigation per asset	STRIDE only	optional
tdd-coverage-active	strict 1:1 across all tiers (mandatory)	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

Schema:

schema_version: 3
name: my-app
team: platform
stack: node                 # auto-detected
tier: 2                     # 1=critical, 2=standard, 3=experiment
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

# Optional
custom_items: []
legacy_code_globs: []        # for retrofits — exclude from TDD coverage
observability:
  dashboard_url: https://grafana.example.com/d/abc/my-app
e2e_glob: "e2e/**/*.{spec,test}.*"
integration_glob: "tests/integration/**"

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

Each artifact has a two-state model: drafted (file exists with content) and verified (file contains the marker <!-- sdlc:verified-by: <name> <iso-date> -->). Both must be true for the item to be done.

Two ways to verify:

sdlc verify prd-drafted --name="alice"
# → records to automation/.verifications.json
# → appends marker to all matching files

Or paste the marker manually at the bottom of the file:

<!-- sdlc:verified-by: alice 2026-05-01T10:00:00Z -->

For retrofit projects, sdlc adopt uses --auto which marks artifacts 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 task 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 (or fewer tests than code, regression)	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 (Claude Code subagent / .claude/agents/<name>.md) — no memory leakage between stages. The dashboard renders task rows with stage pills:

feature-login    [✓ pending] [✓ write-tests] [⏳ write-code] [· review] [· done]
                                                  ↑ current, animated

Bootstrap from user stories:

sdlc tasks bootstrap   # parses 01-Planning/02-User-Stories.md `## Story:` headings
                       # creates one automation/tasks/<slug>.yaml per story

Manual:

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

TDD coverage (mandatory)

Built-in rule tdd-coverage (Phase 3 Setup sub-track) enforces strict 1:1 source-to-test pairing across all tiers. The rule excludes paths in legacy_code_globs, so retrofit projects don't get punished for old code.

Smart dispatcher

sdlc dispatch (or the engine's state.next_dispatch) returns:

• The primary agent for the next pending item (resolved in order: stage-specific for tasks > item.agent override > phase default).
• A parallel_agents list — cross-cutting agents to invoke alongside (e.g., risks-identified invites both pm-agent and security-reviewer).
• A blocked_by field — names the earlier-phase blocker when phase preference can't be honored.
• phase_target from project.yaml is honored unless an earlier phase has a hard blocker.

Replan workflow — handle mid-project changes

Requirements changed? Tech stack pivot? Use sdlc replan to mark downstream DoD items dirty:

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

Resume support

Stepped away for a day or week? sdlc resume answers "where am I?":

$ sdlc resume
📍 my-app — 42% done (12/28 items)
⏳ Currently pending: phase 3 · feature-login (stage: write-code)
🕐 Last activity: developer-agent finished write-code 12m ago
✋ 1 open clarification(s)
🔒 1 pending gate(s)

Next steps:
  → /sdlc-next   (in your AI tool — invokes code-reviewer)

The dashboard's Resume card shows the same info with a one-click Copy button.

Desktop notifications

When the engine runs in --watch mode, every newly appearing clarification or pending gate fires a desktop notification:

• 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)

Both exit 0 when gh is missing/unauthenticated. Engine reads issue_url back into state.json and the dashboard shows ↗ icons.

Autonomous loop (automation/AGENT-LOOP.md)

When operating without a human in the loop, AI agents follow AGENT-LOOP.md. STOP triggers (write a clarification file then halt):

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

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

---

AI tool support

The package ships one shared source in ai-tools/shared-prompts/standards.md plus a per-tool header. sdlc setup generates 8 tool configs:

Tool	Output path	Native commands
Claude Code	CLAUDE.md + .claude/agents/*.md (subagents) + .claude/commands/sdlc-*.md (slash) + .claude/skills/sdlc/SKILL.md	/sdlc-init /sdlc-start /sdlc-next /sdlc-scan /sdlc-dispatch /sdlc-dashboard
Cursor	.cursorrules + .cursor/rules/sdlc.mdc	(auto-loaded rules)
GitHub Copilot Chat	.github/copilot-instructions.md + .github/prompts/sdlc-*.prompt.md	(prompt files in chat UI)
OpenAI Codex / agent	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

The framework ships 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
security-reviewer	Phase 1 risks, Phase 2 security-threat-model, Phase 3 sensitive code	AppSec
ux-designer	Phase 2 (UI/UX)	UI specs, wireframes, design system, accessibility
test-author	Phase 3 task pending → write-tests	Tests for features (TDD red phase)
developer-agent	Phase 3 task write-tests → write-code	Production code (TDD green phase)
code-reviewer	Phase 3 task 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).

---

Dashboard

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

Layout:

• Top header — live status dot (green / amber / red), 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. For Phase 3 tasks, shows the stage pill chain [pending][write-tests][write-code][review][done].
• Phase tracker — 5 phase rows, each with sub-tracks rendered as columns (Phase 2: 🏛️ Architecture / 🎨 UI/UX; Phase 3: 🛠️ Setup collapsed when done / ✅ Tasks Kanban).
• Side panel — Resume card, project info, activity timeline, quick links.

Item visual states:

• ⚪ pending (not drafted)
• 🟡 drafted, awaiting verify (amber)
• ✅ verified
• 🔒 gate (needs signoff)
• ⛔ replan-dirty

Run:

sdlc scan --watch                # re-scan every 3s, fires desktop notifications on transitions
sdlc dashboard --port 8765       # serves http://localhost:8765/dashboard/

How auto-refresh stays live

The dashboard is polling-based (re-fetches state.json every 3s). The state file is rewritten only when the engine runs — sdlc dashboard itself just serves static files. To keep the UI live without a watch loop, the in-scope agents (5 phase + clarification-triager / doc-keeper / ux-designer) are configured to run a silent sdlc scan after every artifact write to a phase-owned path. This works the same way across Claude, Copilot, Cursor and Gemini because the instruction lives in the shared agent markdown.

If the dashboard ever looks stale:

sdlc scan                                          # one-shot refresh
python3 automation/sdlc_engine.py --watch          # background refresh every 3s

---

Project memory bundle

Every sdlc scan regenerates a small markdown summary at automation/.context-bundle.md (mirrored to dashboard/.context-bundle.md). It collects:

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

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

The bundle file is auto-generated and listed in .gitignore. Treat it as derived state.

automation/CONTEXT-PINS.md — your override file

Some facts the engine cannot infer from artifacts: a verbal decision, a gotcha, a deprecation in flight. Pin them here:

# Context Pins
> Manually pinned facts merged verbatim into .context-bundle.md.

## 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.

The pin file is a plain markdown file. No DB, no service — just edit, save, run sdlc scan. The engine concatenates its contents under a ## User pins section in the bundle. If the file does not exist, the section is omitted.

Keep entries short (one line each). Pins should be facts that, if an agent did not know, would cause it to make a wrong call. Do not put PRD-level requirements or architecture details here — those belong in their own documents.

---

MAD MODE — /sdlc-auto-mad

⚠️ Opt-in YOLO autopilot. Use for prototypes, hackathons, throwaway projects. The AI auto-signs Phase 1/2/4/5 phase signoffs and auto-verifies drafted artifacts. Do NOT use this for production work where a human must be in the loop on signoffs.

Stop reason	/sdlc-auto	/sdlc-auto-mad
verify_needed	stop	auto-verify (marker ai-mad-mode)
gate	stop	auto-sign (yaml approved_by: ai-mad-mode)
clarification	stop	stop (kept — agent can't infer intent)
high_risk	stop	stop (kept — auth/crypto/payment)
review_pending	stop	stop (PR is external dep)

Every auto-signed yaml is clearly marked and includes an unsign_command for trivial revert. To revert ALL ai-mad-mode signoffs in one shot:

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

CLI: sdlc auto-mad-step (single iteration). Slash command: /sdlc-auto-mad for Claude Code; sdlc-auto-mad prompt for Copilot. Also documented in Cursor .cursor/rules/sdlc.mdc and the regenerated AI-tool configs.

---

Architecture

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 notify history (gitignored)
│   ├── .verifications.json                     # AUTO-GENERATED verify audit (gitignored)
│   └── .replan.json                            # AUTO-GENERATED replan 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 AI tool configs

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

---

Development (contributing to this framework)

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

MIT.

Links

• PyPI
• GitHub
• C4 model — https://c4model.com
• OWASP ASVS — https://owasp.org/www-project-application-security-verification-standard/
• Conventional Commits — https://www.conventionalcommits.org