Metadata-Version: 2.4
Name: sdlc-framework
Version: 0.16.0
Summary: Local-only multi-AI SDLC framework with auto-detect engine, tier-aware DoD, and GitHub integration
Project-URL: Homepage, https://github.com/vuonglq01685/SDLC
Project-URL: Source, https://github.com/vuonglq01685/SDLC
Project-URL: Issues, https://github.com/vuonglq01685/SDLC/issues
Author-email: Lam Vuong <vuonglq01685@gmail.com>
License-Expression: MIT
Keywords: ai-agent,claude,codex,cursor,github,sdlc
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Requires-Python: >=3.10
Requires-Dist: pyyaml>=6.0
Description-Content-Type: text/markdown

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

[![PyPI](https://img.shields.io/pypi/v/sdlc-framework.svg)](https://pypi.org/project/sdlc-framework/)
[![Python](https://img.shields.io/pypi/pyversions/sdlc-framework.svg)](https://pypi.org/project/sdlc-framework/)

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

---

## Table of contents

1. [What it does](#what-it-does)
2. [Install + first project](#install--first-project)
3. [Adopt an existing project](#adopt-an-existing-project)
4. [Workflow guideline (6 approaches)](GUIDELINE.md)
5. [Daily commands](#daily-commands)
6. [Concepts](#concepts)
7. [AI tool support](#ai-tool-support)
8. [Specialist subagents](#specialist-subagents)
9. [Repo layout](#repo-layout)
10. [Advanced](#advanced)
11. [Contributing](#contributing)

---

## What's new

### 0.16.0 — 2026-05-02

**Phase 2 → Phase 3 architecture-to-code bridge + activity-based stage labels.**

#### Architecture-to-code bridge

Closes the defect where bootstrap created `src/<user-story-slug>/` folders regardless of architecture, producing parallel "code-soup" islands that the user had to manually rewire (observed across Cursor, Copilot, and Claude). Cursor / Copilot / Claude were *following the rails correctly* — the rails were laid in the wrong direction.

- New Phase 2 DoD item `code-structure-mapped` (architecture sub-track). Architect-agent must produce `02-Design/00-Code-Structure.md` mapping each C4-L2 container to a `src/<folder>/` and each user story to its primary container.
- Scaffold template `02-Design/templates/00-Code-Structure.md` with §1 container → folder, §2 user-story → container, §3 dependency rules.
- `sdlc tasks bootstrap` now consults `02-Design/*Code-Structure*.md`. Each task yaml gains a `container:` field; `code_glob` becomes `src/<container>/<module-hint>*` instead of `src/<slug>/**`. Unmapped stories surface a warning per story so the user can fill them in. When the file is absent, the legacy slug behavior is preserved with a one-line deprecation warning.
- `developer-agent`, `phase-3-developer`, `test-author`, `code-reviewer`, `security-reviewer` brief slices now include the §1 container → folder map and §3 dependency rules. Code-writing agents finally see the architectural anchor instead of inferring layout from the task glob alone.
- `phase-2-architect.md` mandate updated: Code Structure is now listed as a non-negotiable Phase 2 deliverable for tier 1/2 projects.

#### Phase 3 stage labels — activity-based

Closes the lag where the dashboard / state.json named stages after the *deliverable already produced* instead of the *activity in flight*. Symptom: while developer-agent was actively writing code, the stage still showed `write-tests` because tests existed and code did not — one nhịp behind reality. Same lag at every transition.

- Stages renamed to label the activity happening NOW. Old: `pending → write-tests → write-code → review → done`. New (6 stages): `pending → write-tests → write-code → review → await-merge → done`.
- `pending` is now narrowed to *queued behind the Phase 3 serial lock* (inactive groups). Active tasks with no deliverables go straight to `write-tests` — that is the activity test-author is performing.
- `await-merge` is new — distinguishes "code-reviewer is doing its local job" (`review`) from "PR open, waiting for human merge" (`await-merge`).
- `auto-mad-step` behavior preserved exactly: at stage `review` (both files, no PR) it auto-opens the PR; at stage `await-merge` it parses the verdict block and auto squash-merges on PASS + critical=0.
- `stage_to_subagent` mapping shifted accordingly: `write-tests` → `test-author`, `write-code` → `developer-agent`, `review` → `code-reviewer` (or `security-reviewer` for sensitive areas), `await-merge` → none, `pending` → none.

### 0.15.0 — 2026-05-02

**Phase 3 serial lock + mad-mode auto-PR-merge.**

- Phase 3 now runs strictly serial: only one `feature_id` group is "active" at a time. Inactive tasks always show `stage: pending` regardless of filesystem state. Fixes the bug where one task's commit advanced every task to `write-code` simultaneously (most visible on GitHub Copilot).
- `auto-mad-step` now auto-opens PRs after `write-code` and auto squash-merges after `review` when the code-reviewer verdict block is `PASS` with zero `critical` findings. New stop reasons: `code_review_failed`, `pr_open_failed`, `merge_failed`.
- New CLI: `sdlc tasks activate <id>`, `sdlc tasks active`, `sdlc tasks unlock`, `sdlc tasks force-merge <id> --i-accept-the-risk`.
- Code-reviewer agent prompt now mandates a `<!-- sdlc:review-verdict ... -->` block at the end of every review file. Missing/malformed → fail-safe to BLOCK.
- AI-tool prompts (Copilot, Cursor, Cline, Continue, Windsurf, Aider, Codex) now include a CONTRACT section forbidding direct state mutation and cross-phase drift.
- Schema migration `state.json` v2 → v3 (idempotent, automatic on first scan after upgrade). Adds `phase3` block.

---

## What it does

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

```bash
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:

```bash
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:

```bash
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](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

```text
# 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:

```yaml
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 `<!-- sdlc:verified-by: <name> <iso-date> -->`).
Both required for `done`.

```bash
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:

```bash
sdlc tasks bootstrap   # one task per `## Story:` heading in 01-Planning/02-User-Stories.md
```

Or manual:

```bash
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:

```bash
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?

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

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.

```bash
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):

```markdown
# 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

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

```bash
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](https://pypi.org/project/sdlc-framework/)
- [GitHub](https://github.com/vuonglq01685/SDLC)
- [C4 model](https://c4model.com)
- [OWASP ASVS](https://owasp.org/www-project-application-security-verification-standard/)
- [Conventional Commits](https://www.conventionalcommits.org)
