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.

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
Agents
- Spec-Kit Agents (Core Flow)
- FPT-Defined Agents (IPA Gen + Review + Orchestrator + Test)
AI-SDLC Usage Guide
Directory Structure
- Directory Details
OKR Web Application — Quick Start

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:

Claude Code
Codex
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.

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/okr/domain/input/okr-requirement.md — Raw requirements from customers
docs/technical_architecture.md — Technical stack decisions and constraints
apps/okr/domain/input/change-request/ — Change requests (e.g., change-0406.md)

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	`apps/okr/backend/` + `apps/okr/frontend/`	Application source code (NestJS backend + React frontend)

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

Adopt governance: Run casan init, select the IDE clients, complete any trust/VSIX onboarding, then run casan doctor
Prepare Input: Place raw requirements in apps/okr/domain/input/okr-requirement.md and tech stack in docs/technical_architecture.md
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
(One-time) Generate System SRS: Run casan.srs to generate system-wide SRS → docs/output/srs-systems/
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
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.)
- apps/okr/backend/ + apps/okr/frontend/ — Source code (NestJS backend + React frontend)

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
│
├── docs/
│   ├── input/                      # Input for the entire AI-SDLC flow
│       ├── change-request/         #   Change requests
│   │   └── okr-requirement.md      #   Raw requirements from customers
│   ├── technical_architecture.md   # Technical stack decisions and constraints
│   └── 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/                          # Spec-Kit feature artifacts (per feature)
│   ├── 001-access-authentication/
│   ├── 002-workspace-dashboard/
│   ├── 003-objective-keyresult/
│   └── 004-review-collaboration/
│
├── e2e/                            # End-to-end tests (Playwright)
│   └── auth/                       #   Auth E2E tests
│
├── apps/okr/frontend/                       # React + Vite SPA (source code)
│
├── apps/okr/backend/                        # NestJS API service (source code)
│
├── docker/                         # Docker utilities
└── docker-compose.yml              # Docker Compose orchestration

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/okr/domain/input/`

Input data for the AI-SDLC flow:

okr-requirement.md — Raw requirement documents from the customer.

`docs/technical_architecture.md`

Technical stack decisions and constraints (languages, frameworks, infrastructure).

`apps/okr/domain/input/change-request/`

Change requests applied during the project lifecycle (e.g., change-0406.md).

`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

Source code generated by Agents during speckit.implement (STEP 10). apps/okr/backend/ and apps/okr/frontend/ contain the application source code, co-located with the monorepo root:

apps/okr/backend/ — NestJS application. src/ contains feature modules (auth/, users/, objectives/, workspaces/, common/). prisma/ contains schema.prisma, migrations, and seed.ts. test/ contains unit tests organized by module (auth/, objectives/, users/). Includes Dockerfile.
apps/okr/frontend/ — React + Vite SPA (TypeScript). src/pages/ for route-level components (Login, ForgotPassword, Dashboard, CreateObjective, EditObjective, ObjectiveDetail, KeyResultDetail); src/components/ organized by feature (auth/, dashboard/, objective-detail/, objective-form/), layout/ (Sidebar, AppHeader, AppLayout) and ui/ (Button, Input, Alert). src/hooks/ (useAuth, useObjectives, useUsers, useWorkspaces), src/lib/ (api, queryClient), src/schemas/, src/types/. test/ contains unit tests (hooks/, pages/). Includes Dockerfile.
e2e/ — End-to-end tests using Playwright, organized by feature (e.g., auth/auth.spec.ts).
docker/ — Docker utilities. Main orchestration is in docker-compose.yml at the project root.

OKR Web Application — Quick Start

Description

The OKR Web Application is a full-stack web app for managing Objectives and Key Results (OKR). It consists of:

Backend: NestJS REST API with Prisma ORM and MySQL
Frontend: React + Vite SPA with Tailwind CSS
Database: MySQL 8.0

Prerequisites

Docker and Docker Compose
Node.js 20.x and npm (for local development without Docker)

Quick Start (Docker)

# Navigate to the repository root
cd <repo-root>

# Build and start all services (MySQL + Backend + Frontend)
docker compose up --build

# To run in detached mode
docker compose up --build -d

Docker Compose will automatically:

Start MySQL and wait for it to be healthy
Run Prisma migrations (prisma migrate deploy)
Seed the database with default data (prisma db seed)
Start the NestJS backend
Start the React frontend dev server

Default Credentials

Role	Email	Password
Admin	`admin@okr.local`	`Password@123`
Manager	`manager@okr.local`	`Password@123`
Employee	`employee@okr.local`	`Password@123`

Service URLs

Service	URL
Frontend	http://localhost:5173
Backend API	http://localhost:3000
API Documentation (Swagger)	http://localhost:3000/api/docs
MySQL	localhost:3307

Development Without Docker

Backend

cd apps/okr/backend

# Install dependencies
npm install

# Copy and configure environment variables
cp .env.example .env
# Edit .env — set DATABASE_URL to point to your local MySQL instance

# Run database migrations
npx prisma migrate dev

# Seed the database
npx prisma db seed

# Start the development server
npm run start:dev

Frontend

cd apps/okr/frontend

# Install dependencies
npm install

# Copy and configure environment variables
cp .env.example .env
# Edit .env if the backend runs on a different port

# Start the Vite dev server
npm run dev

The frontend will be available at http://localhost:5173 and proxies API requests to http://localhost:3000/api/v1.

Stopping Services

# Stop all containers
docker compose down

# Stop and remove volumes (resets the database)
docker compose down -v

README.md

CASAN AI-SDLC

Table of Contents