diff --git a/README.md b/README.md index c8e5ed1..ed401ed 100644 --- a/README.md +++ b/README.md @@ -1,15 +1,17 @@ -# AI-SDLC Project +# CASAN AI-SDLC -AI-SDLC (AI Software Development Life Cycle) - Applying AI to the software development process. +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 từ đây nếu bạn muốn dùng CASAN:** -> [Dùng CASAN để làm dự án — giải thích thực tế, dễ hiểu](docs/guides/CASAN_USING_FOR_REAL_PROJECTS_VI.md). -> [Tạo project shell production đa dự án](docs/guides/CASAN_PROJECT_SHELL_PRODUCTION.md). -> CASAN core không phụ thuộc Codex, VS Code hay Claude Code; các agent được mô tả -> dưới đây là flow demo/legacy có thể đặt phía sau CASAN governance. +> **Bắt đầu nhanh:** xem [CASAN Quick Start](#casan-quick-start). Tài liệu chi +> tiết: [cài đặt hybrid](docs/casan/CASAN_INSTALL_HYBRID.md), +> [dùng CASAN cho dự án thực tế](docs/guides/CASAN_USING_FOR_REAL_PROJECTS_VI.md) +> và [tạo project shell production](docs/guides/CASAN_PROJECT_SHELL_PRODUCTION.md). ## Table of Contents +- [CASAN Quick Start](#casan-quick-start) - [Project Objectives](#project-objectives) - [Dùng CASAN cho dự án thực tế](docs/guides/CASAN_USING_FOR_REAL_PROJECTS_VI.md) - [CASAN Project Shell production](docs/guides/CASAN_PROJECT_SHELL_PRODUCTION.md) @@ -26,15 +28,104 @@ AI-SDLC (AI Software Development Life Cycle) - Applying AI to the software devel - [AI-SDLC Usage Guide](#ai-sdlc-usage-guide) - [Directory Structure](#directory-structure) - [Directory Details](#directory-details) -- [FPT Deliverable List for NES](#fpt-deliverable-list-for-nes) - - [A. Development Deliverables](#a-development-deliverables) - - [B. Process Records (Required)](#b-process-records-required) - - [C. Process Design Document](#c-process-design-document) - - [D. Specification Files](#d-specification-files) - - [E. Review & Insights](#e-review--insights) - - [Optional Deliverables](#optional-deliverables) -- [License](#license) +- [OKR Web Application — Quick Start](#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: + +```bash +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: + +```powershell +pwsh .\install.ps1 +``` + +Sau lần cài đầu tiên trên Windows, mở PowerShell mới rồi kiểm tra: + +```powershell +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ệ: + +```bash +cd +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: + +```bash +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 ` | 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 + +```bash +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](docs/casan/CASAN_INSTALL_HYBRID.md). ## Project Objectives @@ -50,13 +141,13 @@ Apply AI to the SDLC process to automate and optimize the creation of software p --- -## Input for Flow +## 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 for Flow | Output | Location | Description | |--------|----------|-------------| @@ -188,11 +279,12 @@ The entire flow is orchestrated by **`casan.pipeline`**, which executes all step ## AI-SDLC Usage Guide -1. **Prepare Input**: Place raw requirements in `apps/okr/domain/input/okr-requirement.md` and tech stack in `docs/technical_architecture.md` -2. **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 -3. **(One-time) Generate System SRS**: Run `casan.srs` to generate system-wide SRS → `docs/output/srs-systems/` -4. **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 -5. **Output**: +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) @@ -337,8 +429,8 @@ The **OKR Web Application** is a full-stack web app for managing Objectives and ### Quick Start (Docker) ```bash -# Clone the repository and navigate to project root -cd AINative_OKR_Claude_GHCP +# Navigate to the repository root +cd # Build and start all services (MySQL + Backend + Frontend) docker compose up --build @@ -376,7 +468,7 @@ Docker Compose will automatically: #### Backend ```bash -cd backend +cd apps/okr/backend # Install dependencies npm install @@ -398,7 +490,7 @@ npm run start:dev #### Frontend ```bash -cd frontend +cd apps/okr/frontend # Install dependencies npm install