sdlc-framework 1.0.4

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 Epic → Story → Task progress with strict sequential TDD plus multi-reviewer review packs.

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

Hierarchy commands

# Epic
sdlc epic new <slug> [--title "..."]    # scaffold epic markdown
sdlc epic sync <slug>                   # parse epic.md → epic.yaml
sdlc epic list                          # list all epics with status
sdlc epic bootstrap <slug>              # invoke sm-agent → draft child stories
sdlc epic compile <slug>                # force-recompile epic-context cache
sdlc epic verify <slug>                 # mark epic verified (after all stories done)

# Story
sdlc story new <slug> [--epic <slug>] [--title "..."]
sdlc story refine <slug>                # invoke sm-agent dialog
sdlc story complete-draft <slug>        # gate: draft → ready
sdlc story sync <slug>                  # parse story.md → story.yaml
sdlc story list [--epic <slug>] [--status <state>]

# Ticket (non-feature work)
sdlc ticket new <slug> --kind=<bug|chore|hotfix|support>

# Tasks (extended)
sdlc tasks new <id> --story <slug> [--kind feature]
sdlc tasks bootstrap <story-slug>

# Review packs + audit
sdlc audit list                          # forced-skip-review log
sdlc audit show <id>                     # full audit yaml for an artifact

# Per-tool render (multi-tool parity)
sdlc render-agents [--tool=<x>] [--check]
sdlc render-commands [--tool=<x>] [--check]

---

Concepts

Hierarchy — Epic / Story / Task / Kanban ticket

The framework uses a four-level work hierarchy. Pick the entry mode that fits the work you're starting:

Mode	When to use	Command
Epic-first	Multi-story product feature (e.g. "VNPay refund flow"). Decompose into stories upfront.	sdlc epic new <slug> → sdlc epic bootstrap <slug>
Story-first	Single coherent user need (e.g. "Initialize refund request").	sdlc story new <slug> [--epic <epic>]
Ticket-first	Non-feature work — bugs, chores, hotfixes, support.	sdlc ticket new <slug> --kind=<bug|chore|hotfix|support>

Source of truth split: humans + SM agent write narrative markdown (01-Planning/epics/<slug>.md, 01-Planning/stories/<slug>.md). The engine maintains state yaml (automation/{epics,stories}/<slug>.yaml) and never touches the markdown body. sdlc <type> sync <slug> parses md → yaml.

Tasks live under Stories (or stand alone for Kanban tickets) and follow the strict-TDD ladder from Phase 3. Each task yaml may declare story_id (groups it under a Story for PR boundary purposes); siblings share one branch + one PR.

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: 1
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 6 stages sequentially:

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

Stage labels name the activity in flight, not the artifact already produced. Stage detection is automatic (filesystem + gh pr view):

Stage	When	Subagent invoked
pending	queued behind Phase 3 serial lock	none
write-tests	active task, no deliverables	test-author
write-code	tests exist, no code	developer-agent
review	both exist, no PR	code-reviewer (or security-reviewer if sensitive)
await-merge	PR open	none (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

16 canonical role specs that any AI tool can read (rendered into per-tool surfaces by sdlc render-agents).

Subagent	Phase / stage	Role
pm-agent	Phase 1	PRDs, user stories with G/W/T, quantified NFRs, stakeholders, risks
sm-agent	Phase 1 (story drafting)	Scrum Master persona — drafts stories from Epic narrative, refines ACs collaboratively
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 write-tests	Tests-first (TDD red phase)
developer-agent	Phase 3 write-code	Production code (TDD green phase)
code-reviewer	Phase 3 review	Code quality review
qa-engineer	Phase 4	E2E, integration, smoke, regression, load
sre-agent	Phase 5	CI/CD, runbook, SLOs, incident response
orchestrator	cross-cutting	Reads state.json and dispatches the right specialist
doc-keeper	cross-cutting	Sync docs after behavior changes
clarification-triager	cross-cutting	Resolve STOP triggers
business-reviewer	cross-cutting	ROI / market-fit / business goal alignment
accessibility-reviewer	cross-cutting	WCAG 2.2 AA — UI/UX specs and frontend tasks
edge-case-reviewer	cross-cutting	Boundary conditions, off-by-one, null/empty, race conditions

All 16 canonical specs live at automation/agents/*.md. The renderer projects them into per-tool surfaces (.claude/agents/, .copilot/agents/, .cursor/agents/). Per-tool files carry a <!-- generated-from: ... --> marker; user-edited files (no marker) are never clobbered.

Run sdlc render-agents after editing any canonical agent file so per-tool surfaces stay in sync. CI gate: sdlc render-agents --check.

---

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
├── automation/agents/                 # 16 canonical role specs (source of truth)
├── .claude/
│   ├── agents/                        # Claude Code subagent render (from automation/agents/)
│   ├── commands/sdlc-*.md             # slash commands
│   └── skills/sdlc/SKILL.md           # auto-trigger skill
├── .copilot/agents/                   # Copilot CLI render (from automation/agents/)
├── .cursor/agents/                    # Cursor render (from automation/agents/)
├── 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][await-merge][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