From 93ffae93a80d790ad6b1ff53eb4077c3d4106748 Mon Sep 17 00:00:00 2001 From: thanhnv Date: Thu, 23 Jul 2026 23:36:43 +0700 Subject: [PATCH] optimize redme --- README.md | 59 +++++++++++++++++++++++++++++++++++++++---------------- 1 file changed, 42 insertions(+), 17 deletions(-) diff --git a/README.md b/README.md index a1946f2..6ba95e7 100644 --- a/README.md +++ b/README.md @@ -18,8 +18,8 @@ copy toàn bộ CASAN hoặc dựng lại project shell. - [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) +- [Optional Reference AI-SDLC Flow](#optional-reference-ai-sdlc-flow) + - [Reference Steps](#reference-steps) - [Flow Diagram](#flow-diagram) - [Legend](#legend) - [Agents](#agents) @@ -135,6 +135,27 @@ Khi nâng cấp global CASAN, chạy lại `casan init` trong project để cậ 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). +### 5. CASAN không yêu cầu flow 13 bước + +CASAN governance chạy theo từng prompt/tool turn của IDE đã enable, độc lập với +workflow nghiệp vụ của project. Vì vậy project hiện hữu có thể giữ nguyên: + +- Slash commands riêng như `/bd:boss`, `/bd:generation`, `/bd:review`. +- Agents, skills, prompts và hooks đã có trong `.claude/`, `.codex/`, + `.github/` hoặc thư mục riêng. +- Số bước, thứ tự bước, vòng review và cấu trúc source hiện tại. + +Không cần đổi workflow đó sang `casan.pipeline`. Pipeline 13 bước bên dưới chỉ +là flow tham chiếu tùy chọn đi kèm repository này. Sau `casan init`, chat và +tool calls qua Claude Code/Codex vẫn được CASAN kiểm soát dù người dùng gọi +agent/command riêng hoặc không chỉ định agent CASAN. Với GitHub Copilot Chat, +vẫn phải dùng route explicit `@casan`. + +Chỉ cần tích hợp thêm adapter nếu ứng dụng tự gọi LLM API ngoài các IDE hooks. +Nếu muốn CI hoặc một workflow tùy biến có chứng nhận end-to-end riêng, có thể +gọi CASAN CLI tại các gate phù hợp; đây là tăng cường tùy chọn, không phải điều +kiện để CASAN hoạt động. + ## Project Objectives Apply AI to the SDLC process to automate and optimize the creation of software products from initial requirements to complete source code. @@ -167,11 +188,14 @@ Apply AI to the SDLC process to automate and optimize the creation of software p --- -## Full AI-SDLC Flow +## Optional Reference AI-SDLC Flow -The entire flow is orchestrated by **`casan.pipeline`**, which executes all steps automatically from start to finish. +CASAN governance không phụ thuộc vào flow này. Repository cung cấp +**`casan.pipeline`** như một orchestrator tham chiếu tùy chọn cho những project +muốn dùng Spec-Kit + IPA theo trình tự bên dưới. Project có workflow riêng +không cần cài, gọi hoặc chuyển đổi sang pipeline này. -### Flow Steps +### Reference Steps | Step | Agent | Output | Category | |------|-------|--------|----------| @@ -272,7 +296,7 @@ The entire flow is orchestrated by **`casan.pipeline`**, which executes all step | Agent | Description | |-------|-------------| -| `casan.pipeline` | **Orchestrator** — runs all 13 steps end-to-end automatically | +| `casan.pipeline` | **Optional reference orchestrator** — runs the bundled 13-step Spec-Kit + IPA flow | | `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/` | @@ -287,12 +311,10 @@ The entire flow is orchestrated by **`casan.pipeline`**, which executes all step ## 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 requirements and architecture under `apps//domain/input/` -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**: +1. **Adopt governance**: Run `casan init`, select the IDE clients, complete any trust/VSIX onboarding, then run `casan doctor`. +2. **Continue the project workflow**: Use the project's existing commands, agents, skills, review loops, and source layout normally. CASAN does not require a fixed number of steps. +3. **Optional reference flow**: Only when the project intentionally adopts the bundled Spec-Kit + IPA workflow, prepare input under `apps//domain/input/`, configure the constitution, optionally generate the system SRS, then invoke `casan.pipeline`. +4. **Reference-flow 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) @@ -306,14 +328,14 @@ The entire flow is orchestrated by **`casan.pipeline`**, which executes all step ``` ├── .claude/ │ ├── agents/ # All agent definitions (subagents) -│ │ ├── casan.pipeline.md # Boss orchestrator agent +│ │ ├── casan.pipeline.md # Optional reference 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) +│ ├── casan.pipeline.md # Run optional reference pipeline │ ├── speckit.*.md # Spec-Kit slash commands │ └── casan.*.md # Reusable CASAN commands │ @@ -368,12 +390,15 @@ The entire flow is orchestrated by **`casan.pipeline`**, which executes all step 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. +- **Optional reference orchestrator** — `casan.pipeline`: runs the bundled + 13-step Spec-Kit + IPA flow when a project explicitly chooses that workflow. - **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. +Claude Code slash commands that invoke the corresponding agents. A project may +use its own commands normally; `/casan.pipeline` is only for triggering the +optional bundled reference pipeline. #### `.specify/` Spec-Kit configuration directory. Stores project-wide principles, scripts, and all templates: @@ -391,7 +416,7 @@ project content. 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. +- **`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 optional reference pipeline steps. #### `specs/`