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

These details have not been verified by PyPI

Project links

Project description

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.

What it does
Install + first project
Adopt an existing project
Daily commands
Concepts
AI tool support
Specialist subagents
Repo layout
Advanced
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.

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: alice@org.com
  eng_lead: bob@org.com
  sre: dave@org.com
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 ). 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  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.

Project details

These details have not been verified by PyPI

Project links

Release history Release notifications | RSS feed

1.3.0

May 6, 2026

1.2.7

May 5, 2026

1.2.6

May 5, 2026

1.2.5

May 5, 2026

1.2.4

May 5, 2026

1.2.3

May 5, 2026

1.2.2

May 5, 2026

1.2.1

May 5, 2026

1.2.0

May 5, 2026

1.1.9

May 5, 2026

1.1.8

May 5, 2026

1.1.7

May 5, 2026

1.1.6

May 5, 2026

1.1.5

May 5, 2026

1.1.4

May 5, 2026

1.1.3

May 5, 2026

1.1.2

May 5, 2026

1.1.1

May 5, 2026

1.1.0

May 5, 2026

1.0.4

May 4, 2026

1.0.3

May 4, 2026

1.0.2

May 4, 2026

1.0.1

May 4, 2026

0.21.0

May 3, 2026

0.20.0

May 3, 2026

0.19.2

May 3, 2026

0.19.1

May 3, 2026

0.19.0

May 3, 2026

0.18.1

May 3, 2026

0.18.0

May 2, 2026

0.17.4

May 2, 2026

0.17.3

May 2, 2026

0.17.2

May 2, 2026

0.17.1

May 2, 2026

0.17.0

May 2, 2026

0.16.1

May 2, 2026

0.16.0

May 2, 2026

0.15.0

May 2, 2026

0.14.1

May 2, 2026

This version

0.14.0

May 1, 2026

0.13.1

May 1, 2026

0.13.0

May 1, 2026

0.12.0

May 1, 2026

0.11.3

May 1, 2026

0.11.2

May 1, 2026

0.11.0

May 1, 2026

0.10.0

May 1, 2026

0.9.0

May 1, 2026

0.8.0

May 1, 2026

0.7.1

May 1, 2026

0.7.0

May 1, 2026

0.6.3

May 1, 2026

0.6.2

May 1, 2026

0.6.1

May 1, 2026

0.6.0

Apr 30, 2026

0.5.0

Apr 30, 2026

0.4.1

Apr 30, 2026

0.4.0

Apr 30, 2026

0.3.0

Apr 30, 2026

0.2.0

Apr 30, 2026

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

sdlc_framework-0.14.0.tar.gz (182.2 kB view details)

Uploaded May 1, 2026 Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

The dropdown lists show the available interpreters, ABIs, and platforms. Enable javascript to be able to filter the list of wheel files.

sdlc_framework-0.14.0-py3-none-any.whl (291.5 kB view details)

Uploaded May 1, 2026 Python 3

File details

Details for the file sdlc_framework-0.14.0.tar.gz.

File metadata

Download URL: sdlc_framework-0.14.0.tar.gz
Upload date: May 1, 2026
Size: 182.2 kB
Tags: Source
Uploaded using Trusted Publishing? No
Uploaded via: twine/6.2.0 CPython/3.13.6

File hashes

Hashes for sdlc_framework-0.14.0.tar.gz
Algorithm	Hash digest
SHA256	`0b750eeae6281966f8d20ff4dee5c2694d1fbd73015a62b8f5c3042fe908a887`
MD5	`ccf57eec3af08af22d4f085988d36cb8`
BLAKE2b-256	`1a92d8ecbe1a6cb4ba04f971eff78fbb7890c45874245a2c425ada911bd00557`

See more details on using hashes here.

File details

Details for the file sdlc_framework-0.14.0-py3-none-any.whl.

File metadata

Download URL: sdlc_framework-0.14.0-py3-none-any.whl
Upload date: May 1, 2026
Size: 291.5 kB
Tags: Python 3
Uploaded using Trusted Publishing? No
Uploaded via: twine/6.2.0 CPython/3.13.6

File hashes

Hashes for sdlc_framework-0.14.0-py3-none-any.whl
Algorithm	Hash digest
SHA256	`644aa8ee57b9c5f1bcdb4428d3803ddcfae39319582eae49264e7368d54810b5`
MD5	`6fa30c31d4245d044c8c488718376089`
BLAKE2b-256	`6439534c6f1569560f2842e321de531ab0a20abd68ce309071ccad8c2c5ddd67`

See more details on using hashes here.

sdlc-framework 0.14.0

Navigation

Verified details

Maintainers

Unverified details

Project links

Meta

Classifiers

Project description

SDLC Framework

Table of contents

What it does

Install + first project

Adopt an existing project

Daily commands

Concepts

project.yaml — tier-aware DoD strictness

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

Phase 3 task lifecycle (sequential TDD strict)

Autopilot

Smart dispatcher

Replan workflow

STOP triggers (autonomous loop)

AI tool support

Specialist subagents

Repo layout

Advanced

Dashboard

Project memory bundle

automation/CONTEXT-PINS.md — your override file

Desktop notifications

GitHub integration

TDD coverage rule

Contributing

License & links

Project details

Verified details

Maintainers

Unverified details

Project links

Meta

Classifiers

Release history Release notifications | RSS feed

Download files

Source Distribution

Built Distribution

File details

File metadata

File hashes

File details

File metadata

File hashes

`project.yaml` — tier-aware DoD strictness

`automation/CONTEXT-PINS.md` — your override file