gitea-admin/CASAN
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
a6c3a5d02f78fb85d5ab8268ff50583d30c99edd
CASAN/README.md
T
thanhnv a6c3a5d02f Update CASAN usage guide
2026-07-23 23:07:38 +07:00

26 KiB
Raw Blame History

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

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.

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

  1. Adopt governance: Run casan init, select the IDE clients, complete any trust/VSIX onboarding, then run casan doctor
  2. Prepare Input: Place raw requirements in apps/okr/domain/input/okr-requirement.md and tech stack in docs/technical_architecture.md
  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.)
    • 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:

  1. Start MySQL and wait for it to be healthy
  2. Run Prisma migrations (prisma migrate deploy)
  3. Seed the database with default data (prisma db seed)
  4. Start the NestJS backend
  5. 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
Reference in New Issue View Git Blame Copy Permalink