sdlc-framework 0.2.0

Local-only multi-AI SDLC framework with auto-detect engine, tier-aware DoD, and GitHub integration

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 scripts/sdlc-serve.sh   # http://localhost:8765/dashboard/

Trong terminal khác chạy:

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:

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)

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

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: [e-mail]
  eng_lead: [e-mail]
  sre: [e-mail]
  # 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).

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.

# 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
sdlc notify <kind> <id> <title> <body>	Desktop notification
`sdlc gh-issue --clarification	--gate`
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

# 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

• 4 phase folders với README + templates
• Coding/git/error/security standards
• AI configs cho 5 tools chính
• Shared prompts library theo phase
• TikTok-style dashboard với progress tracking
• 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.