Metadata-Version: 2.4
Name: sdlc-framework
Version: 0.9.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/
```

---

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