sdlc-framework 0.7.1

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 (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 from v0.6.x

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.

---

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 --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-quantified	needs p99 AND (RTO or RPO)	p95 / p99	optional
threat-model	STRIDE + Mitigation per asset	STRIDE only	optional
tdd-coverage	strict 1:1 across all tiers (mandatory)	strict 1:1	strict 1:1
prod-deploy-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: 2
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-exists --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-mitigated 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-prod
# → 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 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/

---

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