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. Tạo project shell production đa dự án. 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.

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
FPT Deliverable List for NES
License

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

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)

# Clone the repository and navigate to project root
cd AINative_OKR_Claude_GHCP

# 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 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 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

AI-SDLC Project

Table of Contents