Metadata-Version: 2.4
Name: sdlc-framework
Version: 0.11.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 sequential TDD strict.

[![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.

---

## 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 & 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` (security-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

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

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

---

## Quickstart — existing running project

For a project already mid-development or in production, run:

```bash
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 between schema versions

**v0.6.x → v0.7+ (3-phase → 5-phase):**

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

**v0.7/v0.8 → v0.9 (rename + reorder):**

```bash
sdlc migrate-v3 [--dry-run] [--auto]
```

Backs up `automation/rules.json` → `rules.json.v2.bak`, replaces with the v3 schema (verb-first IDs, no abbreviations, reordered by causal flow), renames keys in `automation/.verifications.json` (preserves verify history), renames signoff filenames (`phase1-prd.yaml → phase1-signoff.yaml`, `phase2-design.yaml → phase2-signoff.yaml`, `phase5-prod.yaml → phase5-signoff.yaml`), bumps `project.yaml.schema_version` to 3. Idempotent.

---

## CLI reference

```text
# 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 migrate-v3                          upgrade v0.7/v0.8 project to v3 (rename + reorder)

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-targets` | needs `p99` AND (`RTO` or `RPO`) | `p95` / `p99` | optional |
| `security-threat-model` | STRIDE + `Mitigation` per asset | STRIDE only | optional |
| `tdd-coverage-active` | strict 1:1 across all tiers (mandatory) | 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 |

Schema:

```yaml
schema_version: 3
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: alice@org.com
  eng_lead: bob@org.com
  sre: dave@org.com
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:

```bash
sdlc verify prd-drafted --name="alice"
# → records to automation/.verifications.json
# → appends marker to all matching files
```

Or paste the marker manually at the bottom of the file:

```markdown
<!-- 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:

```bash
sdlc tasks bootstrap   # parses 01-Planning/02-User-Stories.md `## Story:` headings
                       # creates one automation/tasks/<slug>.yaml per story
```

Manual:

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

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

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

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

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

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

### How auto-refresh stays live

The dashboard is polling-based (re-fetches `state.json` every 3s). The state file is rewritten **only when the engine runs** — `sdlc dashboard` itself just serves static files. To keep the UI live without a watch loop, the in-scope agents (5 phase + clarification-triager / doc-keeper / ux-designer) are configured to run a silent `sdlc scan` after **every** artifact write to a phase-owned path. This works the same way across Claude, Copilot, Cursor and Gemini because the instruction lives in the shared agent markdown.

If the dashboard ever looks stale:

```bash
sdlc scan                                          # one-shot refresh
python3 automation/sdlc_engine.py --watch          # background refresh every 3s
```

---

## Project memory bundle

Every `sdlc scan` regenerates a small markdown summary at `automation/.context-bundle.md` (mirrored to `dashboard/.context-bundle.md`). It collects:

- Project name + stack + current phase
- Top 3 PRD goals
- Last 8 ADRs
- Active DoD item, recent agent runs, open clarifications, pending gates
- Anything you put in `automation/CONTEXT-PINS.md` (see below)

Sub-agents read this bundle (or a role-tailored slice of it via the brief) instead of re-reading PRD + stories + architecture every invocation. Cap is 12 KB; sections truncate before the cap is hit.

The bundle file is auto-generated and listed in `.gitignore`. Treat it as derived state.

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

Some facts the engine cannot infer from artifacts: a verbal decision, a gotcha, a deprecation in flight. Pin them here:

```markdown
# Context Pins
> Manually pinned facts merged verbatim into .context-bundle.md.

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

The pin file is a plain markdown file. No DB, no service — just edit, save, run `sdlc scan`. The engine concatenates its contents under a `## User pins` section in the bundle. If the file does not exist, the section is omitted.

Keep entries short (one line each). Pins should be facts that, if an agent did not know, would cause it to make a wrong call. Do **not** put PRD-level requirements or architecture details here — those belong in their own documents.

---

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

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

MIT.

## Links

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