Metadata-Version: 2.4
Name: sdlc-framework
Version: 0.2.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 — Multi-AI-Assistant

> Hệ thống SDLC end-to-end, **generic & reusable** cho nhiều dự án, hỗ trợ đồng thời:
> Claude · GitHub Copilot · Cursor · Codex · Aider · Continue · và bất kỳ tool nào đọc rules từ project root.

## TL;DR — flow tự động

```
1. Copy folder này vào project mới.
2. bash scripts/setup-ai-configs.sh        # wire AI configs ra root
3. bash scripts/sdlc-watch.sh &             # engine watch mode (auto re-scan mỗi 3s)
4. bash scripts/sdlc-serve.sh               # serve dashboard tại http://localhost:8765/dashboard/
5. AI agent (Claude/Codex/Cursor) đọc automation/AGENT-LOOP.md → tự đẩy SDLC.
   - Agent dừng và hỏi user CHỈ KHI: ambiguity / conflict / gate / high-risk action.
   - Dashboard tự refresh khi state thay đổi.
```

**Không cần tick tay**. Engine scan repo và đánh dấu DoD theo evidence (file tồn tại, regex, content...).

## 🗂️ Cấu trúc

```
SDLC/
├── 01-Planning/                  # Phase 1 — PRD, user stories, requirements
│   ├── README.md
│   ├── templates/                # 5 templates: PRD, US, RS, Stakeholder, Risk
│   └── examples/                 # (your filled-in copies)
├── 02-Design/                    # Phase 2 — Architecture, API, DB, UI/UX, ADR, Threat
│   ├── README.md
│   ├── templates/                # 6 templates
│   ├── diagrams/                 # mermaid / png exports
│   └── examples/
├── 03-Development/               # Phase 3 — Coding standards, git, security, code review
│   ├── README.md
│   ├── standards/                # coding, git, errors, security
│   └── templates/                # PR, CR checklist, DoD
├── 04-Testing-Deploy/            # Phase 4 — Test plan, CI/CD, deploy, SLO, incident
│   ├── README.md
│   ├── templates/
│   └── runbooks/
├── ai-tools/                     # ⭐ Multi-AI configs
│   ├── README.md
│   ├── claude/CLAUDE.md
│   ├── cursor/.cursorrules
│   ├── github-copilot/copilot-instructions.md
│   ├── codex/AGENTS.md
│   ├── aider/.aider.conf.yml + CONVENTIONS.md
│   └── shared-prompts/           # Reusable prompts per phase
├── agents/                       # ⭐ 9 specialist agents (orchestrator + 4 phase + 4 cross)
│   ├── README.md                 #   roster + hand-off protocol
│   ├── orchestrator.md
│   ├── phase-1-pm.md  ...  phase-4-sre.md
│   ├── cross/                    #   security-reviewer, test-author, doc-keeper, clarification-triager
│   └── _brief-template.md
├── .claude/agents/               #   same agents in Claude Code subagent format (frontmatter)
├── automation/                   # ⭐ Auto-detect SDLC engine
│   ├── README.md                 #   how engine works
│   ├── AGENT-LOOP.md             #   spec for AI agents (autonomous mode)
│   ├── rules.json                #   declarative DoD detection rules
│   ├── sdlc_engine.py            #   scanner → state.json
│   ├── state.json                #   live state (auto-generated)
│   ├── clarifications/           #   AI drops questions here when stuck
│   └── signoffs/                 #   user creates YAML to approve gates
├── dashboard/
│   ├── index.html                # 🎬 Auto-refresh TikTok-style dashboard
│   └── state.json                #   read by dashboard (mirror of automation/state.json)
├── workflows/                    # cross-phase workflow docs
├── scripts/
│   ├── setup-ai-configs.sh       # wire CLAUDE.md / .cursorrules / etc. to root
│   ├── sdlc-scan.sh              # one-shot scan
│   ├── sdlc-watch.sh             # continuous re-scan
│   ├── sdlc-serve.sh             # serve dashboard via HTTP (needed for fetch())
│   └── sdlc-dispatch.py          # decide next agent + auto-build brief
└── README.md                     # this file
```

## 🎯 4 Phases tóm tắt

| # | Phase | Output | DoD highlight |
|---|---|---|---|
| 1 | 📋 Planning | PRD, User Stories, Requirements, Stakeholder, Risk | PRD approved, NFRs định lượng |
| 2 | 🎨 Design | Architecture, API, DB, UI/UX, ADRs, Threat model | C4 reviewed, OpenAPI lint clean, STRIDE done |
| 3 | 💻 Development | Standards, PR template, CR checklist, AI configs | Lint+test+security gating, AI disclosure trong PR |
| 4 | 🚀 Testing & Deploy | Test plan, CI/CD, runbook, SLOs, incident | 95% pass, SLO alerts wired, postmortem template ready |

## 🤖 AI Tools — Cùng 1 brain, nhiều mặt nạ

Tất cả các tool đều **reference cùng SDLC standards** trong `03-Development/standards/`:

| Tool | Config root path | Auto-load? |
|---|---|---|
| **Claude** (Code/Desktop/API) | `CLAUDE.md` | ✅ |
| **GitHub Copilot** | `.github/copilot-instructions.md` | ✅ |
| **Cursor** | `.cursorrules` | ✅ |
| **Codex / OpenAI agent** | `AGENTS.md` | ✅ |
| **Aider** | `.aider.conf.yml` + `CONVENTIONS.md` | ✅ |
| **Continue / Cody / Windsurf** | đọc `.cursorrules` hoặc `CLAUDE.md` | ✅ |

→ Đổi tool, project standards **không** phải viết lại.

## 🎬 Dashboard — Auto-tracking TikTok-style

Phải serve qua HTTP (vì dashboard `fetch('state.json')`):

```bash
bash scripts/sdlc-serve.sh   # http://localhost:8765/dashboard/
```

Trong terminal khác chạy:
```bash
bash scripts/sdlc-watch.sh   # auto re-scan mỗi 3s
```

Bây giờ:
- Mỗi khi anh / AI thay đổi file trong repo → engine pick up trong vòng 3s → state.json refresh → dashboard tự cập nhật.
- Sidebar phải hiển thị **🔍 Clarifications waiting** (AI đang chờ user) và **🔒 Gates pending** (cần human approve).
- Mỗi DoD item show evidence reason: nếu fail, hiển thị `glob X: found 0 (need ≥ 1)` để biết phải làm gì.
- Vuốt / phím ↑↓ / 1-4 / 0 / R (manual refresh).

## 🧑‍💼 Agent Roster — chuyên môn hóa thay vì "1 prompt làm tất cả"

Hệ thống có **9 specialist agents** trong `agents/`:

| Loại | Agents |
|---|---|
| Orchestrator | `orchestrator` — đọc state, dispatch đúng người |
| Phase specialists | `pm-agent` (P1), `architect-agent` (P2), `developer-agent` (P3), `sre-agent` (P4) |
| Cross-cutting | `security-reviewer`, `test-author`, `doc-keeper`, `clarification-triager` |

Mỗi agent có persona, tools, hard rules riêng. Format Claude Code subagent ở `.claude/agents/` (auto-detect).

**Pick agent kế tiếp**:
```bash
python3 scripts/sdlc-dispatch.py
# In ra: agent nào nên invoke + brief sẵn dùng + invocation hints cho từng tool
```

## 🤖 Agent Loop — AI tự đẩy SDLC

File `automation/AGENT-LOOP.md` là **runbook duy nhất** cho mọi AI tool khi chạy autonomous:

1. Read `state.json` → biết item nào pending
2. Read `rules.json` → biết evidence cần tạo
3. Plan → execute (small steps) → verify (re-scan engine) → commit
4. **STOP triggers** (tạo clarification rồi ngừng):
   - 🔍 Ambiguity (không đủ thông tin)
   - ⚔️ Conflict (2 nguồn yêu cầu mâu thuẫn)
   - 🚪 Gate (cần signoff)
   - 🛑 High-risk path (auth/crypto/payment/migrations/secrets)

User intervention:
- **Resolve clarification**: edit file `automation/clarifications/<NNN>-*.md`, đổi `STATUS: open` → `STATUS: resolved`
- **Approve gate**: tạo `automation/signoffs/<gate-id>.yaml` với `approved: true`

## 🚀 Quy trình end-to-end (suggested)

```mermaid
flowchart LR
  A[Idea / brief] --> P1[📋 Phase 1: Planning]
  P1 --> P2[🎨 Phase 2: Design]
  P2 --> P3[💻 Phase 3: Development]
  P3 --> P4[🚀 Phase 4: Testing & Deploy]
  P4 -. metrics & feedback .-> P1
```

Mỗi phase có **entry criteria** (vào được khi phase trước Done) và **exit criteria** (DoD trong README phase đó).

## 🧾 Project metadata — `project.yaml`

Optional file at repo root. When present, the engine reads it and:

- Drives **DoD strictness** by tier:
  - tier 1 (critical) — strictest: NFR needs `p99` AND `RTO`/`RPO`; tests required; full sign-off chain.
  - tier 2 (standard) — current behaviour.
  - tier 3 (experiment) — looser; only `eng_lead` sign-off needed.
- Enforces **owner roles** per tier (`owners-defined` rule fails closed when required keys are missing).
- Pins the `stack` so `setup-ai-configs.sh` can wire the right CI workflow without a flag.

Schema (`schema_version: 1`):

```yaml
schema_version: 1
name: my-app
team: platform
stack: node            # node | python | go
tier: 2                # 1=critical, 2=standard, 3=experiment
phase_target: 3        # 1..4
repo_url: https://github.com/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   # auto | always | never
```

Missing `project.yaml` is supported (defaults: tier 2, no owners). The
`owners-defined` DoD item will be red until you fill it in.

## 🧱 Stacks supported

| Stack | CI template wired by `setup-ai-configs.sh --stack=<x>` |
|---|---|
| `node` | `04-Testing-Deploy/templates/ci-workflows/node-ci.yml` |
| `python` | `04-Testing-Deploy/templates/ci-workflows/python-ci.yml` |
| `go` | `04-Testing-Deploy/templates/ci-workflows/go-ci.yml` |

Adding a stack: drop `<stack>-ci.yml` into `04-Testing-Deploy/templates/ci-workflows/`.

## 🤖 Agent activity log

Each AI agent (Claude/Cursor/Codex/Aider/Continue/Cline/Windsurf/Copilot) calls
`scripts/agent-log.sh start|done|fail` to record what it ran. The log is
`automation/agent-runs.jsonl` (gitignored, 50-entry self-trimming ring buffer).

```bash
SDLC_TOOL=claude-code scripts/agent-log.sh start pm-agent prd-exists
# ... agent does work ...
scripts/agent-log.sh done pm-agent prd-exists --summary="created 01-PRD.md"
```

The engine reads the last 20 entries on every scan and exposes them in
`state.json` under `agent_runs`. The dashboard shows them in the intro card
(top 5) and in the sidebar panel "🤖 Agent activity (live)" (top 10).

If an agent doesn't call the wrapper, nothing breaks — the panel just shows
"no runs yet". The log is observability; agents are not blocked when it fails
(disk full, permission errors, etc.).

## 🔔 Notifications

When the engine runs in watch mode (`bash scripts/sdlc-watch.sh` or
`python3 automation/sdlc_engine.py --watch`), 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)

A persistent line is appended to `automation/notifications.log` regardless of
delivery success (capped at 50 lines, gitignored).

Notifications are transition-only: an item that stays pending across many
scans only fires once. The first scan after `watch` starts is treated as
baseline (no notifications) so engine startup does not spam.

One-shot scans (`python3 automation/sdlc_engine.py` without `--watch`) do
not fire notifications.

## 🔗 GitHub integration

Two wrappers surface SDLC STOP triggers to GitHub via the `gh` CLI:

- `scripts/gh-issue.sh --clarification <file>` — files a GitHub Issue from a
  clarification markdown file and writes the resulting `issue_url:` line back
  into the file (idempotent).
- `scripts/gh-issue.sh --gate <gate-id>` — files a Gate Pending issue and
  writes the URL into `automation/signoffs/<gate-id>.yaml`.
- `scripts/gh-pr.sh` — opens a Draft PR for the current branch
  (`--ready` opens a regular PR; `--base <branch>` overrides the default `main`).

The engine reads `issue_url:` back into `state.clarifications[*].issue_url`
and `state.gates[*].issue_url`. The dashboard shows a small ↗ link next to
each item so collaborators can jump to the GitHub thread.

Both wrappers exit 0 when `gh` is missing or unauthenticated — agents call
them unconditionally; nothing breaks when running offline.

## 📦 Installation

The framework is now installable as a Python package.

```bash
# install once globally (uv recommended)
uv tool install sdlc-framework

# or via pip
pip install --user sdlc-framework

# scaffold a new project
mkdir my-app && cd my-app
sdlc init --stack=node     # node | python | go
sdlc scan --print          # populate state.json
sdlc dashboard --port 8765 # browse the dashboard
```

Available subcommands:

| Command | Purpose |
|---------|---------|
| `sdlc init [--stack ...] [--force]` | Scaffold a new project from bundled templates |
| `sdlc scan [--watch] [--print]` | Run engine, write `state.json` |
| `sdlc dispatch [--json] [--brief]` | Print next-agent brief |
| `sdlc agent-log start|done|fail` | Activity log wrapper |
| `sdlc notify <kind> <id> <title> <body>` | Desktop notification |
| `sdlc gh-issue --clarification | --gate` | File a GitHub Issue |
| `sdlc gh-pr [--ready] [--base ...]` | Open a draft PR |
| `sdlc build-ai-configs` | Regenerate the 8 AI tool configs |
| `sdlc dashboard [--port N]` | Serve the dashboard HTML |

The framework targets local development on macOS / Linux. The autonomy loop is
file-based: edit `automation/clarifications/*.md` to resolve open questions,
write `automation/signoffs/<id>.yaml` with `approved: true` to approve gates.

## 🧰 Setup nhanh cho project mới

```bash
# 1) Copy framework
cp -r path/to/SDLC ~/Projects/my-new-app
cd ~/Projects/my-new-app

# 2) Wire AI configs
bash scripts/setup-ai-configs.sh

# 3) Replace placeholders (macOS)
grep -rl "{{PROJECT_NAME}}" . | xargs sed -i '' 's/{{PROJECT_NAME}}/My App/g'

# 4) Open dashboard
open dashboard/index.html
```

## 📋 Definition of Done — Framework

- [x] 4 phase folders với README + templates
- [x] Coding/git/error/security standards
- [x] AI configs cho 5 tools chính
- [x] Shared prompts library theo phase
- [x] TikTok-style dashboard với progress tracking
- [x] Setup script + master README
- [ ] Fill in `{{PROJECT_NAME}}` cho project cụ thể của anh
- [ ] Tuỳ chỉnh checklist trong dashboard cho từng phase

## 🤝 Đóng góp / mở rộng

Khi thêm template mới:
1. Đặt vào folder phase tương ứng (`0X-.../templates/`).
2. Update README phase đó (table deliverables).
3. Nếu liên quan đến AI workflow → thêm prompt vào `ai-tools/shared-prompts/`.
4. Nếu là DoD mới → thêm vào checklist trong `dashboard/index.html` (mảng `PHASES`).

## 📚 Tham chiếu

- C4 model — https://c4model.com
- OWASP ASVS — https://owasp.org/www-project-application-security-verification-standard/
- SLO concepts — Google SRE book
- Conventional Commits — https://www.conventionalcommits.org

---
**Made for**: Project Managers + AI-augmented dev teams.
**License**: anh tuỳ chỉnh — đề xuất MIT cho team / Apache 2.0 cho enterprise.
