gitea-admin/CASAN
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
7cea023dced5a43d46916e574f4f340ae2c04e99
CASAN/README.md
T
thanhnvandClaude Opus 4.8 36a4812ef3 refactor(structure): promote app to repo root + remove redundant workspace cruft 
Standard production layout: the OKR app (was nested under AINative_OKR_CASAN5/) is now
the repository root. No more wrapper directory.

- Promote AINative_OKR_CASAN5/* -> repo root (backend/ frontend/ packages/ apps/
  .specify/ docs/ infra/ nginx/ scripts/ + configs). Merge tool dirs: .gitea (kept the
  active deploy ci.yml, added harness-ci.yml + runbooks), .claude (agents/commands +
  launch.json), .github moved up.
- Remove redundant: 00_SUBMISSION_PACKAGE, scattered root notes (FPT_CASAN_Full.md,
  tu-tuong-casan.md, casan-tu-sinh..., casan_harness_assessment.md, source-review...,
  README_CASAN5_REFINED.md), casan-next-plans/ and optimize-docs/ (competition/planning
  artifacts — roadmap + design history preserved in git log / commit messages).
- Update all references to the old layout:
  - .gitea/workflows/{ci,harness-ci}.yml, .github/workflows/{ci,deploy}.yml:
    working-directory .; drop AINative_OKR_CASAN5/ prefix; .specify/{tests,scripts}
    -> packages/casan-harness/... (.specify/logs state kept)
  - .claude/launch.json, .gitea/*-runbook.md: path prefixes
  - CLAUDE.md, README.md: docs/input -> apps/okr/domain/input
  - policy-bundle.yaml: 8 policy paths -> packages/casan-harness/...; manifest re-signed
- secrets-scan.sh: fixture excludes -> new package/domain paths.

Full gate from the new root: PASS=64 FAIL=0 SKIP=3.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
2026-07-08 13:26:36 +09:00

415 lines
23 KiB
Markdown
Raw Blame History

# AI-SDLC Project
AI-SDLC (AI Software Development Life Cycle) - Applying AI to the software development process.
## Table of Contents
- [Project Objectives](#project-objectives)
- [Requirements](#requirements)
- [Input for Flow](#input-for-flow)
- [Output for FLow](#output-for-flow)
- [Full AI-SDLC Flow](#full-ai-sdlc-flow)
- [Flow Steps](#flow-steps)
- [Flow Diagram](#flow-diagram)
- [Legend](#legend)
- [Agents](#agents)
- [Spec-Kit Agents (Core Flow)](#spec-kit-agents-core-flow)
- [FPT-Defined Agents (IPA Gen + Review + Orchestrator + Test)](#fpt-defined-agents-ipa-gen--review--orchestrator--test)
- [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)
## 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**: Using **Claude Code** as the main AI assistant
- **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** | `backend/` + `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.)
- `backend/` + `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
│
├── frontend/ # React + Vite SPA (source code)
│
├── 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).
`backend/` and `frontend/` contain the application source code, co-located with the monorepo root:
- **`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`.
- **`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](https://docs.docker.com/get-docker/) and Docker Compose
- Node.js 20.x and npm (for local development without Docker)
### Quick Start (Docker)
```bash
# 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
```bash
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
```bash
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
```bash
# 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