sdlc-framework 0.5.0

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

SDLC Framework

Local-only, multi-AI SDLC framework. One sdlc CLI scaffolds a 4-phase project, auto-detects DoD evidence, dispatches the right specialist agent, and surfaces blockers via desktop notifications + GitHub issues.

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

---

What it does

flowchart LR
  Idea[Idea / brief] --> P1[📋 Phase 1<br/>Planning]
  P1 --> P2[🎨 Phase 2<br/>Design]
  P2 --> P3[💻 Phase 3<br/>Development]
  P3 --> P4[🚀 Phase 4<br/>Testing & Deploy]
  P4 -. metrics & feedback .-> P1

Phase	Output	DoD highlight
1. Planning	PRD, user stories, NFRs, stakeholder map, risks	PRD approved, NFRs quantified
2. Design	C4 architecture, API spec, DB schema, UI/UX, ADRs, threat model	C4 reviewed, OpenAPI lint clean, STRIDE done
3. Development	Coding/git/error/security standards, PR template, code-review checklist	Lint+test+security gating, AI disclosure in PR
4. Testing & Deploy	Test plan, CI/CD, runbook, SLOs, incident response	95% pass, SLO alerts wired, postmortem ready

The engine auto-scans your repo every 3 seconds (when in watch mode), evaluates 28 DoD rules per automation/rules.json, and writes a JSON state file that the dashboard renders. AI agents read the same rules to know what evidence to produce next.

---

Installation

uv tool install sdlc-framework        # recommended (uv manages a clean tool env)
# or
pip install --user sdlc-framework

Verify:

sdlc --version
# sdlc 0.3.0

---

Quickstart — new project

mkdir my-app && cd my-app
sdlc setup     # interactive: scaffold + pick which AI tool(s) to install commands for

The wizard asks which AI coding tools you use (Claude Code / Cursor / Copilot / Codex / Aider / Continue / Cline / Windsurf), auto-detects your stack from package.json / pyproject.toml / go.mod, and writes tool-native artifacts so you can stay inside your AI tool and use slash commands instead of a terminal CLI.

Or skip the prompts:

sdlc setup --tools=claude-code,cursor --stack=node

Then operate inside your AI tool

Claude Code — slash commands are wired:

/sdlc-start "Mobile task app for 5-person team"   begin Phase 1 (auto-invokes pm-agent subagent)
/sdlc-next                                        advance to the next pending item
/sdlc-scan                                        refresh progress summary
/sdlc-dispatch                                    inspect the full dispatch decision
/sdlc-dashboard                                   serve the live UI on localhost

The slash commands shell out to the sdlc CLI underneath; you don't need to context-switch to a terminal.

Cursor — rules in .cursor/rules/sdlc.mdc are auto-loaded. Just share your idea in chat; Cursor adopts the pm-agent persona. From Cursor's integrated terminal you can also run sdlc start "<idea>" etc.

GitHub Copilot Chat — prompt files in .github/prompts/sdlc-*.prompt.md are usable via the Copilot Chat prompts UI.

Codex / Aider / Continue / Cline / Windsurf — text rules at the project root (AGENTS.md, CONVENTIONS.md, .continuerules, .clinerules, .windsurfrules) are auto-loaded. From the tool's terminal you run the sdlc CLI commands directly.

Why an explicit subagent invocation?

In Claude Code, plugins like superpowers:brainstorming auto-fire on idea prompts and write design specs into the wrong folder. The slash commands this framework ships call use the pm-agent subagent explicitly, which forces Claude Code to load .claude/agents/pm-agent.md (this repo's authoritative role spec) and bypass conflicting plugins.

The first command scaffolds:

• 4 phase folders (01-Planning/, 02-Design/, 03-Development/, 04-Testing-Deploy/) with 24 templates + 4 standards docs + runbooks.
• 9 specialist agent definitions (agents/orchestrator.md, phase-1-pm.md, ..., cross/security-reviewer.md).
• 8 AI tool config files at the project root (CLAUDE.md, .cursorrules, .github/copilot-instructions.md, etc.) — generated from a single shared source.
• project.yaml template — fill in name, team, tier (1=critical / 2=standard / 3=experiment), owners, GitHub URL.
• automation/rules.json — declarative DoD detection rules.
• .github/workflows/ci.yml (when stack is detected) — Node/Python/Go matrix CI template.

After init, edit project.yaml:

schema_version: 1
name: my-app
team: platform
stack: node            # auto-detected; override with --stack at init
tier: 2                # 1=critical, 2=standard, 3=experiment
phase_target: 1        # the phase your team is currently focused on
repo_url: https://github.com/your-org/my-app
owners:
  sponsor: [e-mail]
  eng_lead: [e-mail]
  sre: [e-mail]
  # security: required when tier == 1
flags:
  ai_disclosure_required: true
  signoffs_strict: auto

---

Quickstart — existing project

sdlc init is idempotent and non-destructive: it skips files that already exist. Drop it on top of any repo:

cd ~/Projects/existing-app           # has package.json / pyproject.toml / etc.
sdlc init                             # auto-detects stack, skips existing files
sdlc scan --print                     # see which DoD items are already satisfied

What you'll see on the first run:

• Phase 1 is mostly red because PRD / user stories / NFRs likely don't exist yet → fill them in 01-Planning/templates/.
• Phase 3 "AI tool configs" + "coding standards" green because sdlc init just wrote them.
• Phase 4 "CI/CD pipeline configured" green if the auto-detected ci.yml matches your stack; otherwise the existing workflow stays untouched.
• owners-defined red until you fill project.yaml.owners.

What sdlc init will NOT overwrite (unless --force):

• Your existing README.md, LICENSE, package.json, source code.
• .github/workflows/ci.yml if you already have one.
• project.yaml once you've edited it.

To force regeneration of a single file: delete it then re-run sdlc init. To force everything: sdlc init --force (use carefully).

---

CLI reference

# getting started (you usually only need `sdlc setup`)
sdlc setup [--tools=...] [--stack=...] [--force]  interactive: scaffold + pick AI tools
sdlc init [--stack=node|python|go] [--force]      scaffold without picking tools (low-level)
sdlc start "<your idea>"                          save the idea (used by /sdlc-start)
sdlc next [--json]                                show next pending DoD item (used by /sdlc-next)

# workflow
sdlc scan [--watch] [--interval N] [--print]      run the engine; write state.json
sdlc dispatch [--json] [--brief]                  next-agent decision + ready-to-paste brief
sdlc dashboard [--port N]                         serve dashboard/index.html on localhost

# integrations
sdlc agent-log start|done|fail <agent> <item>  append activity entry (50-line ring buffer)
sdlc notify <kind> <id> <title> <body>         desktop notification (osascript / notify-send)
sdlc gh-issue --clarification PATH | --gate ID file a GitHub Issue (idempotent)
sdlc gh-pr [--ready] [--base BRANCH]           open a Draft PR (or reuse existing)
sdlc build-ai-configs                          regenerate the 8 AI tool configs from shared sources

sdlc --version                                 print version

---

Concepts

project.yaml — tier-aware DoD strictness

The engine reads project.yaml and adjusts what evidence is required 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
tests-present	required	recommended	optional
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

Missing project.yaml = engine uses tier: 2 defaults; the owners-defined DoD item stays red until you fill the file in.

Agent activity log

Every agent (Claude / Cursor / Codex / human dev) calls sdlc agent-log start|done|fail to append a JSONL entry to automation/agent-runs.jsonl. The dashboard renders the last 10 entries in a live "🤖 Agent activity" panel — so you can watch the loop without tailing a terminal.

SDLC_TOOL=claude-code sdlc agent-log start pm-agent prd-exists
# ... agent does work ...
sdlc agent-log done pm-agent prd-exists --summary="created 01-PRD.md"

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 still written to automation/notifications.log)

Notifications are transition-only: an item that stays pending across many scans only fires once. Engine startup baselines and does not spam.

Smart dispatcher

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

• The primary agent for the next pending DoD item.
• A parallel_agents list — cross-cutting agents the orchestrator should invoke in parallel (e.g. api-spec done → invite security-reviewer).
• A blocked_by field — names the earlier-phase blocker (gate / clarification / high-risk path) when phase preference can't be honored.

It also reads project.yaml.phase_target: if the team has declared they're focused on phase 3, the dispatcher prefers phase 3 items unless an earlier phase has a hard blocker.

GitHub integration

Two wrappers surface STOP triggers from the local repo to GitHub via the gh CLI:

sdlc gh-issue --clarification automation/clarifications/001-foo.md
# → creates a GitHub Issue with body=clarification content + sdlc-clarification label
# → writes `issue_url:` back into the file (idempotent on re-run)

sdlc gh-issue --gate phase4-prod
# → creates "🔒 Gate pending: <label>" issue, writes URL into automation/signoffs/<id>.yaml

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

Both exit 0 when gh is missing/unauthenticated — agents call them unconditionally; nothing breaks offline. The engine reads issue_url back into state.json and the dashboard shows a small ↗ icon next to each item.

Autonomous loop (automation/AGENT-LOOP.md)

When operating without a human in the loop, AI agents follow AGENT-LOOP.md:

1. Read state.json → know what's pending.
2. Read rules.json → know what evidence to produce.
3. Plan → execute → verify (re-scan engine) → commit.
4. 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 small per-tool header. sdlc init (and sdlc build-ai-configs) generates 8 tool-specific configs:

Tool	Output path	Auto-loaded
Claude Code / Desktop / Agent SDK	CLAUDE.md	✅
GitHub Copilot	.github/copilot-instructions.md	✅
Cursor	.cursorrules	✅
OpenAI Codex / agent	AGENTS.md	✅
Aider	.aider.conf.yml + CONVENTIONS.md	✅
Windsurf	.windsurfrules	✅
Cline	.clinerules	✅
Continue	.continue/config.json + .continuerules	✅

Edit the shared source, run sdlc build-ai-configs, and all 8 files regenerate. Each generated file carries a <!-- AUTO-GENERATED --> header so devs don't hand-edit them.

---

Specialist agents

The agents/ directory ships 9 role specs that any AI coding tool can read:

Agent	Role
orchestrator	Reads state, picks next agent (mirrors sdlc dispatch).
pm-agent (Phase 1)	PRDs, user stories with G/W/T, quantified NFRs.
architect-agent (Phase 2)	C4, API spec, DB schema, ADRs, STRIDE.
developer-agent (Phase 3)	Coding standards, PR/CR checklists.
sre-agent (Phase 4)	CI/CD, deploy runbooks, SLOs, incident response.
security-reviewer (cross)	AppSec review on auth/data/crypto-touching changes.
test-author (cross)	Test strategy + actual test files.
doc-keeper (cross)	Sync docs with behavior changes.
clarification-triager (cross)	Triages ambiguity into structured clarification files.

Same roster ships in .claude/agents/ (Claude Code subagent format with frontmatter). Other tools read agents/*.md directly per their conventions.

---

Dashboard

The bundled HTML auto-fetches dashboard/state.json every 3 seconds. Layout:

• Top bar: project name · team · tier · focus phase · overall %.
• Intro card: KPI grid + "🤖 Agent activity (live)" panel showing the last 5 agent runs.
• 4 phase cards (swipe / arrow keys / number keys 1-4): per-phase progress + per-item ✓/✗ with the failing-rule message inline.
• Sidebar (desktop ≥ 900px): live snapshot, next dispatch, agent roster, agent activity, clarifications waiting, gates pending. Each clarification/gate that has a GitHub issue shows a ↗ icon link.

Run sdlc scan --watch in one terminal and sdlc dashboard in another:

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

---

Architecture

your-repo/
├── project.yaml                                # metadata (engine reads this)
├── 01-Planning/                                # Phase 1 templates + your filled-in artifacts
├── 02-Design/                                  # Phase 2 ditto
├── 03-Development/                             # Phase 3 ditto
│   └── standards/                              # coding-standards, git-workflow, error-handling, security-checklist
├── 04-Testing-Deploy/                          # Phase 4 ditto
│   └── templates/ci-workflows/                 # node-ci.yml / python-ci.yml / go-ci.yml
├── agents/                                     # role specs read by AI tools
├── ai-tools/
│   ├── shared-prompts/standards.md             # source of truth for all tool configs
│   └── <tool>/                                 # AUTO-GENERATED per-tool config files
├── automation/
│   ├── rules.json                              # declarative DoD detection
│   ├── state.json                              # AUTO-GENERATED snapshot (gitignored)
│   ├── clarifications/*.md                     # AI raises STOPs here, user resolves
│   ├── signoffs/<gate-id>.yaml                 # user approves gates here
│   ├── agent-runs.jsonl                        # AUTO-GENERATED activity log (gitignored)
│   └── notifications.log                       # AUTO-GENERATED notify history (gitignored)
├── dashboard/
│   ├── index.html                              # bundled UI
│   └── state.json                              # mirror of automation/state.json
├── .github/workflows/ci.yml                    # selected CI template
├── CLAUDE.md / .cursorrules / AGENTS.md / ...  # 8 AI tool configs (auto-generated)
└── .gitignore

State flows: AI agent does work → engine scans → writes state.json → dashboard fetches → 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       # 47 tests
bash scripts/tests/test_setup.sh             # smoke
bash scripts/tests/test_agent_log.sh
bash scripts/tests/test_notify.sh
bash scripts/tests/test_gh_wrappers.sh

# After editing scaffold templates, sync into the package:
bash scripts/sync-scaffold.sh

# Build wheel + sdist:
python3 -m build

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