CASAN/README.md

CASAN AI-SDLC

CASAN là governance harness cho AI Software Development Life Cycle. Harness có thể được cài một lần ở máy developer rồi adopt vào nhiều dự án hiện hữu mà không copy toàn bộ CASAN hoặc dựng lại project shell.

Bắt đầu nhanh: xem CASAN Quick Start. Tài liệu chi tiết: cài đặt hybrid, dùng CASAN cho dự án thực tế và tạo project shell production.

Table of Contents

• CASAN Quick Start
• Project Objectives
• Dùng CASAN cho dự án thực tế
• CASAN Project Shell production
• Requirements
• Input for Flow
• Output for Flow
• Full AI-SDLC Flow
  • Flow Steps
  • Flow Diagram
  • Legend
• Agents
  • Spec-Kit Agents (Core Flow)
  • FPT-Defined Agents (IPA Gen + Review + Orchestrator + Test)
• AI-SDLC Usage Guide
• Directory Structure
  • Directory Details

CASAN Quick Start

1. Cài CASAN một lần trên máy developer

Yêu cầu chung: Python 3. Trên macOS/Linux cần Bash; trên Windows cần PowerShell và Git for Windows (Git Bash).

macOS/Linux, chạy từ checkout CASAN:

sh install.sh --level devkit
# Nếu installer báo launcher chưa nằm trên PATH:
export PATH="${CASAN_HOME:-$HOME/.casan}/bin:$PATH"
casan version

Windows PowerShell, chạy từ checkout CASAN:

pwsh .\install.ps1

Sau lần cài đầu tiên trên Windows, mở PowerShell mới rồi kiểm tra:

casan version

Mặc định harness được cài tại ~/.casan trên macOS/Linux và %LOCALAPPDATA%\casan trên Windows.

2. Adopt CASAN vào dự án

Chạy tại root của dự án cần bảo vệ:

cd <project-root>
casan init

Trong terminal tương tác, casan init hiển thị menu cho phép chọn một hoặc nhiều integration:

1. Claude Code
2. Codex
3. GitHub Copilot trong VS Code

Có thể cấu hình không tương tác:

casan init --client claude
casan init --client claude,codex
casan init --client vscode-copilot --vscode-install yes
casan init --client all

Mặc định production là --mode enforce. Chỉ dùng --mode observe cho giai đoạn pilot telemetry-only.

casan init an toàn với dự án đã có project shell, agents, skills hoặc hooks:

• Không sửa source code và không dựng lại vỏ dự án.
• Merge idempotent vào .claude/settings.json, .codex/hooks.json và .vscode/extensions.json.
• Giữ nguyên cấu hình/hook của dự án; chạy lại không tạo hook CASAN trùng lặp.
• Chỉ ghi bootstrap/config per-project; harness vẫn dùng bản global đã pin hash.

Nếu ứng dụng tự gọi LLM API qua backend riêng, ngoài Claude Code/Codex/Copilot, luồng đó không tự động đi qua project hooks và cần adapter CASAN riêng.

Với project đã adopt CASAN theo mô hình cũ và đang chứa packages/casan-harness, init nhận diện đây là vendored application thay vì source hub:

• Không cần --force.
• Không xóa harness, scripts, workflow hoặc evidence cũ.
• Tự nâng cấp các block nằm giữa marker CASAN_PROMPT_ENFORCEMENT_START/END.
• Báo rõ file nào còn prose legacy ngoài marker cần review thủ công.

3. Hành vi chat theo client

Client đã enable	Prompt đi qua CASAN	Onboarding bắt buộc
Claude Code CLI/extension	Tự động với chat bình thường	Mở project ở trusted workspace
Codex CLI/extension	Tự động với chat bình thường	Mở /hooks, review và trust đúng hook hash
GitHub Copilot Chat	Chỉ khi gửi @casan <prompt>	Cài CASAN VSIX; built-in Copilot chat không bị global-intercept

Không cần chỉ định một “CASAN agent” khi chat bằng Claude Code hoặc Codex. GitHub Copilot là ngoại lệ: VS Code không cung cấp API cho extension intercept mọi built-in Copilot prompt, nên CASAN cung cấp route explicit @casan.

4. Kiểm tra sau khi init

casan doctor
casan verify-harness

Với Codex, doctor kiểm tra config/bootstrap/runtime nhưng bước trust vẫn phải thực hiện trong /hooks. Với Copilot, nếu máy chưa có code CLI, init trả về đường dẫn VSIX để cài bằng lệnh Extensions: Install from VSIX....

Khi nâng cấp global CASAN, chạy lại casan init trong project để cập nhật bootstrap và pin hash mới. Xem đầy đủ tùy chọn và troubleshooting tại CASAN_INSTALL_HYBRID.md.

Project Objectives

Apply AI to the SDLC process to automate and optimize the creation of software products from initial requirements to complete source code.

Requirements

• Flow + Prompt + Template: Spec-Kit
• AI Tool của flow demo/legacy: Claude Code là assistant chính; CASAN harness và Control Panel có thể chạy độc lập bằng browser/CLI/CI hoặc dùng model local/OmniRoute.
• AI-SDLC: AI-integrated SDLC process Spec-Kit Modified (Add IPA Gen + Review Loop + Orchestrator)
• IPA Template: Following IPA (Information-technology Promotion Agency) template standards

---

Input for Flow

• apps/<project-id>/domain/input/requirement.md — project requirements
• apps/<project-id>/domain/input/architecture.md — architecture and constraints
• Project-owned input, reference, agent, and skill directories remain untouched

Output for Flow

Output	Location	Description
IPA Docs (SRS, BD, DD, Test Cases, Test Reports)	docs/output/ipa-docs/	Design documents generated by IPA agents (organized in srs/, bd/, dd/, testcase/, testreport/ subdirectories)
AI Agent Logs	docs/output/output_logs/	Execution logs from AI agents
SRS-Systems	docs/output/srs-systems/	System-wide SRS (generated once during input clarification phase, not part of the main flow steps)
Spec-Kit Artifacts	specs/[FEATURE_NAME]/	Feature artifacts generated by Spec-Kit agents (spec.md, plan.md, tasks.md, contracts, checklists)
Source Code	Project-defined locations	CASAN does not impose an application framework or source layout

---

Full AI-SDLC Flow

The entire flow is orchestrated by casan.pipeline, which executes all steps automatically from start to finish.

Flow Steps

Step	Agent	Output	Category
STEP 1	casan.srs	SRS (ソフトウェア要件定義書)	📄 IPA Doc Gen
STEP 2	casan.bd	BD — 外部設計 (Basic Design)	📄 IPA Doc Gen
STEP 3	speckit.specify	spec.md	📝 Spec-Kit
STEP 4	speckit.clarify	Resolve ambiguities (NO PAUSE)	📝 Spec-Kit
STEP 5	casan.reviewspec 🔄	Spec review (auto-retry)	🔍 Agent Review
STEP 6	speckit.plan	plan.md + data-model + contracts	📝 Spec-Kit
STEP 7	casan.reviewplan 🔄	Plan review (auto-retry)	🔍 Agent Review
STEP 8	casan.dd	DD — 内部設計 (Detail Design)	📄 IPA Doc Gen
STEP 8b	casan.testkit	Test cases (gen-testcases)	🧪 Test
STEP 9	speckit.tasks	tasks.md	📝 Spec-Kit
STEP 10	speckit.implement 🔄	Implementation + build & fix (auto-retry)	📝 Spec-Kit
STEP 11	casan.reviewcode 🔄	Code review + DB data check (auto-retry)	🔍 Agent Review
STEP 12	casan.testkit 🔄	Run tests (run-tests) — BACK-TO-PLAN on fail	🧪 Test
STEP 13	Boss (direct)	Build BE + connect DB + Build FE + Launch UI → open_browser_page	🚀 Deploy

Flow Diagram

┌─────────────────────────────────────────────────────────────┐
│  INPUT                                                      │
│  [ Raw Requirement ]  [ Clear Requirement ]  [ Tech Stack ] │
└──────────────────────────────┬──────────────────────────────┘
                               │
          ┌────────────────────┴──── (one-time, pre-flow) ────┐
          │  casan.srs → docs/output/srs-systems/     │
          └────────────────────┬──────────────────────────────┘
                               │
  ╔════════════════════════════╧══════════════════════════════════╗
  ║  casan.pipeline  (Orchestrator)                       ║
  ║                                                              ║
  ║  ┌─── IPA Doc Gen ───────────────────────────────────────┐   ║
  ║  │  STEP 1   casan.srs        → SRS                  │   ║
  ║  │  STEP 2   casan.bd         → BD (外部設計)         │   ║
  ║  └───────────────────────────────────────────────────────┘   ║
  ║        │                                                     ║
  ║        ▼                                                     ║
  ║  ┌─── Spec-Kit + Review Loop ────────────────────────────┐   ║
  ║  │  STEP 3   speckit.specify      → spec.md              │   ║
  ║  │  STEP 4   speckit.clarify      → resolve ambiguities  │   ║
  ║  │  STEP 5   casan.reviewspec 🔄 auto-retry          │   ║
  ║  │        │                                               │   ║
  ║  │        ▼                                               │   ║
  ║  │  STEP 6   speckit.plan         → plan.md + data-model │   ║
  ║  │  STEP 7   casan.reviewplan 🔄 auto-retry          │   ║
  ║  └───────────────────────────────────────────────────────┘   ║
  ║        │                                                     ║
  ║        ▼                                                     ║
  ║  ┌─── IPA Doc Gen (Detail) ──────────────────────────────┐   ║
  ║  │  STEP 8   casan.dd         → DD (内部設計)         │   ║
  ║  │  STEP 8b  casan.testkit    → gen-testcases         │   ║
  ║  └───────────────────────────────────────────────────────┘   ║
  ║        │                                                     ║
  ║        ▼                                                     ║
  ║  ┌─── Implementation ───────────────────────────────────┐    ║
  ║  │  STEP 9   speckit.tasks        → tasks.md            │    ║
  ║  │  STEP 10  speckit.implement    🔄 build & fix        │    ║
  ║  │  STEP 11  casan.reviewcode 🔄 code review        │    ║
  ║  │  STEP 12  casan.testkit    🔄 run-tests          │    ║
  ║  │           (BACK-TO-PLAN on fail)                      │    ║
  ║  └──────────────────────────────────────────────────────┘    ║
  ║        │                                                     ║
  ║        ▼                                                     ║
  ║  ┌─── Deploy ───────────────────────────────────────────┐    ║
  ║  │  STEP 13  Boss → build BE + DB + FE → open_browser   │    ║
  ║  └──────────────────────────────────────────────────────┘    ║
  ║                                                              ║
  ╚══════════════════════════════════════════════════════════════╝

Legend

Symbol	Meaning
🔄	Auto-retry loop (agent retries until pass)

---

Agents

Spec-Kit Agents (Core Flow)

Agent	Description
speckit.constitution	Define project principles and constraints
speckit.specify	Convert requirements into feature specification (spec.md)
speckit.clarify	Resolve ambiguous requirements (no pause)
speckit.plan	Create implementation plan (plan.md + data-model + contracts)
speckit.tasks	Generate task list (tasks.md)
speckit.implement	Implementation with auto build & fix
speckit.analyze	Cross-artifact consistency and quality analysis
speckit.checklist	Generate custom quality checklists
speckit.taskstoissues	Convert tasks to GitHub issues

FPT-Defined Agents (IPA Gen + Review + Orchestrator + Test)

Agent	Description
casan.pipeline	Orchestrator — runs all 13 steps end-to-end automatically
casan.srs	Generate SRS (ソフトウェア要件定義書) per module → docs/output/ipa-docs/
casan.bd	Generate BD / 外部設計 (Basic Design) per module → docs/output/ipa-docs/
casan.dd	Generate DD / 内部設計 (Detail Design) per module → docs/output/ipa-docs/
casan.srs	Generate system-wide SRS (one-time, pre-flow) → docs/output/srs-systems/
casan.reviewspec	Review — validate spec.md quality and completeness
casan.reviewplan	Review — validate plan.md conformance to spec
casan.reviewcode	Review — code review + DB data check
casan.testkit	Test — generate test cases from SRS + BD + DD; run automated tests
Flow-Agent	General-purpose flow agent

---

AI-SDLC Usage Guide

1. Adopt governance: Run casan init, select the IDE clients, complete any trust/VSIX onboarding, then run casan doctor
2. Prepare Input: Place requirements and architecture under apps/<project-id>/domain/input/
3. Configuration: Set up the project constitution first, keep specifications focused on what and why, and only decide technical stack where the input explicitly requires it
4. (One-time) Generate System SRS: Run casan.srs to generate system-wide SRS → docs/output/srs-systems/
5. Run AI Flow: Invoke casan.pipeline to execute the full 13-step flow automatically, with strict TDD enforced across specification, planning, task generation, and implementation
6. Output:
   • docs/output/ipa-docs/ — IPA design documents (SRS, BD, DD, Test Cases)
   • docs/output/output_logs/ — AI agent execution logs
   • docs/output/srs-systems/ — System-wide SRS (generated once)
   • specs/[FEATURE_NAME]/ — Spec-Kit artifacts (spec.md, plan.md, tasks.md, etc.)
   • Source code remains in the locations defined by the adopted project

---

Directory Structure

├── .claude/
│   ├── agents/                     # All agent definitions (subagents)
│   │   ├── casan.pipeline.md      #   Boss orchestrator agent
│   │   ├── speckit.*.md            #   Spec-Kit agents (specify, clarify, plan, tasks, implement, analyze, checklist, taskstoissues)
│   │   ├── casan.*.md              #   Reusable CASAN agents (srs, bd, dd, reviews, testkit, pipeline)
│   │   ├── protocols/              #   Shared protocols (auto-resolve, gate-retry, logging, pipeline-context, etc.)
│   │   ├── steps/                  #   Step definitions for orchestrator (steps-01-04, steps-05-07, etc.)
│   │   └── templates/              #   Agent output templates (pipeline-completion, report-templates)
│   └── commands/                   # Claude Code slash commands
│       ├── casan.pipeline.md      #   Run full pipeline (/casan.pipeline)
│       ├── speckit.*.md            #   Spec-Kit slash commands
│       └── casan.*.md              #   Reusable CASAN commands
│
├── CLAUDE.md                       # Global Claude Code project instructions
│
├── .specify/                       # SpecKit configuration and templates
│   ├── init-options.json           # Initialization options
│   ├── memory/
│   │   └── constitution.md         # Project-wide principles and constraints
│   ├── scripts/                    # Utility scripts
│   │   ├── bash/                   #   Bash scripts
│   │   └── powershell/             #   PowerShell scripts
│   └── templates/
│       ├── agent-file-template.md  # Agent definition template
│       ├── checklist-template.md   # Quality checklist template
│       ├── constitution-template.md
│       ├── spec-template.md        # Spec-Kit templates
│       ├── plan-template.md
│       ├── tasks-template.md
│       ├── srs-template.md         # IPA templates (SRS, BD, DD)
│       ├── bd-ipa-template.md
│       └── dd-ipa-template.md
│
├── apps/
│   └── <project-id>/domain/        # Per-project CASAN domain pack
│       ├── input/
│       │   ├── requirement.md      # Project requirements
│       │   └── architecture.md     # Architecture and constraints
│       ├── corpus/                 # Benign/red-team evaluation corpus
│       ├── golden-runs/            # Golden outputs for drift checks
│       └── traceability-map.json
│
├── docs/
│   └── output/                     # Output of the AI-SDLC process
│       ├── ipa-docs/               #   IPA documents
│       │   ├── srs/                #     SRS documents per module
│       │   ├── bd/                 #     BD documents per module
│       │   ├── dd/                 #     DD documents per module
│       │   ├── testcase/           #     Test case documents per module
│       │   └── testreport/         #     Test report documents per module
│       ├── output_logs/            #   AI agent execution logs (per feature)
│       └── srs-systems/            #   System-wide SRS (generated once, pre-flow)
│
├── specs/                          # Optional Spec-Kit feature artifacts
├── <existing-source-directories>/  # Project-owned; CASAN init preserves them
└── <existing-ci-and-tooling>/      # Project-owned; CASAN init preserves them

Directory Details

.claude/agents/

Contains all agent definition files used by Claude Code. This includes both Spec-Kit agents (core flow: speckit.specify, speckit.clarify, speckit.plan, speckit.tasks, speckit.implement, plus utility agents speckit.analyze, speckit.checklist, speckit.taskstoissues) and reusable CASAN agents (casan.*):

• IPA Doc Gen agents — casan.srs, casan.bd, casan.dd: generate IPA-standard design documents (SRS, BD, DD) per module, output to docs/output/ipa-docs/.
• Review agents — casan.reviewspec, casan.reviewplan, casan.reviewcode: validate the quality of Spec-Kit artifacts (spec.md, plan.md, source code) with auto-retry loops.
• Orchestrator — casan.pipeline: runs the full 13-step flow end-to-end automatically.
• Test agent — casan.testkit: generates test cases from SRS + BD + DD and executes automated tests (Jest / Playwright).
• Subdirectories — protocols/ (shared protocols for auto-resolve, gate-retry, logging, etc.), steps/ (orchestrator step definitions), templates/ (output report templates).

.claude/commands/

Claude Code slash commands that invoke the corresponding agents. Type /speckit.specify, /casan.pipeline, etc. in Claude Code to trigger the pipeline.

.specify/

Spec-Kit configuration directory. Stores project-wide principles, scripts, and all templates:

• init-options.json — Initialization options for Spec-Kit setup.
• memory/constitution.md — The project constitution: shared principles, constraints, and conventions that apply to every feature across the entire project.
• scripts/ — Utility scripts in bash/ and powershell/ for automation tasks.
• templates/ — Format templates used by agents to generate artifacts. Includes Spec-Kit templates (spec-template.md, plan-template.md, tasks-template.md, constitution-template.md, checklist-template.md, agent-file-template.md) and IPA templates (srs-template.md, bd-ipa-template.md, dd-ipa-template.md).

apps/<project-id>/domain/input/

Per-project requirements and architecture used by CASAN gates and traceability. The L2 initializer creates missing domain-pack files without overwriting existing project content.

docs/output/

All artifacts produced by the AI-SDLC process:

• ipa-docs/ — IPA design documents organized in subdirectories: srs/, bd/, dd/, testcase/, testreport/. Generated by casan.srs, casan.bd, casan.dd, and casan.testkit. Each subdirectory contains per-module documents.
• output_logs/ — Execution logs from AI agents organized per feature (e.g., 000-system-srs/, 001-access-authentication/, etc.), useful for debugging and auditing the generation process.
• srs-systems/ — System-wide SRS generated once at the beginning by casan.srs. Contains per-module SRS overviews (mod01-access-authentication/, mod02-workspace-dashboard/, etc.) plus srs-overview-system.md. Not part of the 13-step flow.

specs/

Each folder contains spec.md, plan.md, tasks.md, checklists/, and contracts/. This directory serves as the knowledge base for agents.

Source Code

CASAN does not prescribe NestJS, React, Java, .NET, or any other application stack. Existing source, CI, .claude, .github, agents, skills, prompts, and project instructions remain project-owned. Hybrid init only adds or merges the CASAN integration files documented above.