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

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

[![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** out of the box: Claude Code · GitHub Copilot · Cursor · OpenAI Codex · Aider · Windsurf · Cline · Continue.

---

## What it does

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

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

Verify:

```bash
sdlc --version
# sdlc 0.3.0
```

---

## Quickstart — new project (3 commands)

```bash
mkdir my-app && cd my-app
sdlc init                                 # scaffold the project (auto-detects stack)
sdlc start "Mobile task app for 5 people" # save your idea + show what to do next
                                          # → open project in Claude Code / Cursor / Codex
                                          # → tell the AI your idea verbatim — it auto-adopts
                                          #   pm-agent role and writes 01-Planning/01-PRD.md
sdlc scan --print                         # verify DoD items as the AI fills artifacts
sdlc next                                 # show paste-ready prompt for next pending item
sdlc dashboard --port 8765                # optional: live dashboard at localhost:8765
```

**That's it.** You don't need to know which agent / template / rule applies —
the AI tool reads `CLAUDE.md` / `.cursorrules` / `AGENTS.md` (written by `sdlc init`) and
adopts the right role automatically when you share an idea.

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

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

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

```text
# getting started
sdlc init [--stack=node|python|go] [--force]   scaffold a project (auto-detects stack)
sdlc start "<your idea>"                       save the idea + show what to do next
sdlc next [--json]                             paste-ready prompt for the next pending DoD item

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

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

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

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

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