AI-SDLC Project

AI-SDLC (AI Software Development Life Cycle) - Applying AI to the software development process.

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

Table of Contents

• Project Objectives
• Dùng CASAN cho dự án thực tế
• 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
• FPT Deliverable List for NES
  • A. Development Deliverables
  • B. Process Records (Required)
  • C. Process Design Document
  • D. Specification Files
  • E. Review & Insights
  • Optional Deliverables
• 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 okr.bossbuiltin, which executes all steps automatically from start to finish.

Flow Steps

Step	Agent	Output	Category
STEP 1	okr.srs	SRS (ソフトウェア要件定義書)	📄 IPA Doc Gen
STEP 2	okr.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	okr.reviewspec 🔄	Spec review (auto-retry)	🔍 Agent Review
STEP 6	speckit.plan	plan.md + data-model + contracts	📝 Spec-Kit
STEP 7	okr.reviewplan 🔄	Plan review (auto-retry)	🔍 Agent Review
STEP 8	okr.dd	DD — 内部設計 (Detail Design)	📄 IPA Doc Gen
STEP 8b	okr.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	okr.reviewcode 🔄	Code review + DB data check (auto-retry)	🔍 Agent Review
STEP 12	okr.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) ────┐
          │  okr.srsallsystem → docs/output/srs-systems/     │
          └────────────────────┬──────────────────────────────┘
                               │
  ╔════════════════════════════╧══════════════════════════════════╗
  ║  okr.bossbuiltin  (Orchestrator)                       ║
  ║                                                              ║
  ║  ┌─── IPA Doc Gen ───────────────────────────────────────┐   ║
  ║  │  STEP 1   okr.srs        → SRS                  │   ║
  ║  │  STEP 2   okr.bd         → BD (外部設計)         │   ║
  ║  └───────────────────────────────────────────────────────┘   ║
  ║        │                                                     ║
  ║        ▼                                                     ║
  ║  ┌─── Spec-Kit + Review Loop ────────────────────────────┐   ║
  ║  │  STEP 3   speckit.specify      → spec.md              │   ║
  ║  │  STEP 4   speckit.clarify      → resolve ambiguities  │   ║
  ║  │  STEP 5   okr.reviewspec 🔄 auto-retry          │   ║
  ║  │        │                                               │   ║
  ║  │        ▼                                               │   ║
  ║  │  STEP 6   speckit.plan         → plan.md + data-model │   ║
  ║  │  STEP 7   okr.reviewplan 🔄 auto-retry          │   ║
  ║  └───────────────────────────────────────────────────────┘   ║
  ║        │                                                     ║
  ║        ▼                                                     ║
  ║  ┌─── IPA Doc Gen (Detail) ──────────────────────────────┐   ║
  ║  │  STEP 8   okr.dd         → DD (内部設計)         │   ║
  ║  │  STEP 8b  okr.testkit    → gen-testcases         │   ║
  ║  └───────────────────────────────────────────────────────┘   ║
  ║        │                                                     ║
  ║        ▼                                                     ║
  ║  ┌─── Implementation ───────────────────────────────────┐    ║
  ║  │  STEP 9   speckit.tasks        → tasks.md            │    ║
  ║  │  STEP 10  speckit.implement    🔄 build & fix        │    ║
  ║  │  STEP 11  okr.reviewcode 🔄 code review        │    ║
  ║  │  STEP 12  okr.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
okr.bossbuiltin	Orchestrator — runs all 13 steps end-to-end automatically
okr.srs	Generate SRS (ソフトウェア要件定義書) per module → docs/output/ipa-docs/
okr.bd	Generate BD / 外部設計 (Basic Design) per module → docs/output/ipa-docs/
okr.dd	Generate DD / 内部設計 (Detail Design) per module → docs/output/ipa-docs/
okr.srsallsystem	Generate system-wide SRS (one-time, pre-flow) → docs/output/srs-systems/
okr.reviewspec	Review — validate spec.md quality and completeness
okr.reviewplan	Review — validate plan.md conformance to spec
okr.reviewcode	Review — code review + DB data check
okr.testkit	Test — generate test cases from SRS + BD + DD; run automated tests
Flow-Agent	General-purpose flow agent

---

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 okr.srsallsystem to generate system-wide SRS → docs/output/srs-systems/
4. Run AI Flow: Invoke okr.bossbuiltin to execute the full 13-step flow automatically, with strict TDD enforced across specification, planning, task generation, and implementation
5. 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)
│   │   ├── okr.bossbuiltin.md      #   Boss orchestrator agent
│   │   ├── speckit.*.md            #   Spec-Kit agents (specify, clarify, plan, tasks, implement, analyze, checklist, taskstoissues)
│   │   ├── okr.*.md                #   FPT-defined agents (srs, bd, dd, reviewspec, reviewplan, reviewcode, srsallsystem, testkit)
│   │   ├── 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
│       ├── okr.bossbuiltin.md      #   Run full pipeline (/okr.bossbuiltin)
│       ├── speckit.*.md            #   Spec-Kit slash commands
│       └── okr.*.md                #   OKR agent slash 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 FPT-defined agents (okr.*):

• IPA Doc Gen agents — okr.srs, okr.bd, okr.dd: generate IPA-standard design documents (SRS, BD, DD) per module, output to docs/output/ipa-docs/.
• Review agents — okr.reviewspec, okr.reviewplan, okr.reviewcode: validate the quality of Spec-Kit artifacts (spec.md, plan.md, source code) with auto-retry loops.
• Orchestrator — okr.bossbuiltin: runs the full 13-step flow end-to-end automatically.
• Test agent — okr.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, /okr.bossbuiltin, 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 okr.srs, okr.bd, okr.dd, and okr.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 okr.srsallsystem. 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:

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