diff --git a/.github/agents/Flow-Agent.md b/.github/agents/Flow-Agent.md index daff0f9..e13d1c5 100644 --- a/.github/agents/Flow-Agent.md +++ b/.github/agents/Flow-Agent.md @@ -1,424 +1,25 @@ -# Flow Agent — Pipeline - -> Describes the operational flow of the multi-agent system for the Feature Development Pipeline. - ---- - -## 1. Architecture Overview - -``` -┌─────────────────────────────────────────────────────────────────┐ -│ okr.bossbuiltin (Boss) │ -│ claude-sonnet-4-6 — Orchestrator │ -│ │ -│ 📋 protocols/ 📝 steps/ 📄 templates/ 📊 logs/ │ -└──────────┬──────────────────────────────────────────────────────┘ - │ delegates to 12 specialist sub-agents - ▼ -┌──────────────────────────────────────────────────────────────────┐ -│ okr.srs │ okr.bd │ okr.dd │ -│ speckit.specify │ speckit.clarify │ speckit.plan │ -│ speckit.tasks │ speckit.implement │ │ -│ okr.reviewspec │ okr.reviewplan │ │ -│ okr.reviewcode │ okr.testkit │ │ -└──────────────────────────────────────────────────────────────────┘ -``` - ---- - -## 2. Pipeline Flow — 5 Phases, 16 Steps - -``` -USER INPUT ($ARGUMENTS: feature description) - │ - ▼ -╔══════════════════════════════════════════════════════════════════╗ -║ PHASE 1: DESIGN (Steps 0–4) ║ -║ 📄 steps/steps-01-04-design.md ║ -╠══════════════════════════════════════════════════════════════════╣ -║ ║ -║ STEP 0 ─ Boss (self) ║ -║ │ Detect existing spec in specs/ directory ║ -║ │ → mode = CREATE or UPDATE ║ -║ ▼ ║ -║ STEP 1 ─ okr.srs (gpt-5.4) ║ -║ │ Input: srs-systems/ (overview + module detail + wireframe) ║ -║ │ Output: docs/output/ipa-docs/srs/srs--.md ║ -║ │ Report: 01-srs-report.md ║ -║ ▼ ║ -║ STEP 2 ─ okr.bd (gpt-5.4) ║ -║ │ Input: SRS + system overview + technical architecture ║ -║ │ Output: docs/output/ipa-docs/bd/bd--.md ║ -║ │ Report: 02-bd-report.md ║ -║ │ 🔧 Auto-Resolve: [NEEDS CLARIFICATION] markers ║ -║ ▼ ║ -║ STEP 3 ─ speckit.specify (gpt-5.4) ║ -║ │ Input: Feature desc + SRS + BD ║ -║ │ Output: specs//spec.md ║ -║ │ Report: 03-specify-report.md ║ -║ │ 🔧 Post-check: Boss auto-resolves [NEEDS CLARIFICATION] ║ -║ ▼ ║ -║ STEP 4 ─ speckit.clarify (gpt-5.4) ║ -║ Input: spec.md ║ -║ Output: spec.md (updated) + 04-clarify-qa.md ║ -║ Report: 04-clarify-report.md ║ -║ ⚠️ NO HUMAN PAUSE — auto-resolve all questions ║ -║ ║ -╚══════════════════════════════════════════════════════════════════╝ - │ - ▼ -╔══════════════════════════════════════════════════════════════════╗ -║ PHASE 2: REVIEW (Steps 5–7) ║ -║ 📄 steps/steps-05-07-review.md ║ -╠══════════════════════════════════════════════════════════════════╣ -║ ║ -║ STEP 5 ─ okr.reviewspec (claude-sonnet-4-6) 🔄 GATE ║ -║ │ Input: spec.md + SRS + constitution ║ -║ │ Verdict: ✅ APPROVED / ⚠️ CONDITIONS / ❌ REJECTED ║ -║ │ Report: 05-review-spec-report.md ║ -║ │ ║ -║ │ ❌ REJECTED → speckit.specify fixes → re-review (max 5x) ║ -║ │ ✅/⚠️ → continue ║ -║ ▼ ║ -║ STEP 6 ─ speckit.plan (gpt-5-3-codex) ║ -║ │ Input: spec.md + constitution + docs/technical_architecture.md ║ -║ │ Output: plan.md + data-model.md + contracts/ + research.md ║ -║ │ Report: 06-plan-report.md ║ -║ │ 🔧 Auto-Resolve: [NEEDS CLARIFICATION] in plan artifacts ║ -║ ▼ ║ - -║ STEP 7 ─ okr.reviewplan (claude-sonnet-4-6) 🔄 GATE ║ -║ Input: plan.md + spec.md + data-model.md + tech arch ║ -║ Verdict: ✅ APPROVED / ⚠️ CONDITIONS / ❌ REJECTED ║ -║ Report: 07-review-plan-report.md ║ -║ ║ -║ ❌ REJECTED → speckit.plan fixes → re-review (max 5x) ║ -║ ✅/⚠️ → continue ║ -║ ║ -╚══════════════════════════════════════════════════════════════════╝ - │ - ▼ -╔══════════════════════════════════════════════════════════════════╗ -║ PHASE 3: DETAIL DESIGN (Steps 8–9) ║ -║ 📄 steps/steps-08-09-detail.md ║ -╠══════════════════════════════════════════════════════════════════╣ -║ ║ -║ STEP 8 ─ okr.dd (gpt-5-3-codex) ║ -║ │ Input: BD + SRS + spec + plan + tech arch ║ -║ │ Output: docs/output/ipa-docs/dd/dd--.md ║ -║ │ Report: 08-dd-report.md ║ -║ │ 🔧 Auto-Resolve: [NEEDS CLARIFICATION] in DD ║ -║ ▼ ║ -║ STEP 8b ─ okr.testkit (claude-sonnet-4-6) ║ -║ │ Mode: gen-testcases ║ -║ │ Input: SRS + BD + DD + spec + plan ║ -║ │ Output: docs/output/ipa-docs/testcase/testcase--.md ║ -║ │ Report: 08b-testcases-report.md ║ -║ │ Boss validates: FEA/BR/SCR coverage ≥ 1 TC each ║ -║ ▼ ║ -║ STEP 9 ─ speckit.tasks (gpt-5.4) ║ -║ Input: plan.md + spec.md + data-model.md ║ -║ Output: specs//tasks.md ║ -║ Report: 09-tasks-report.md ║ -║ ║ -╚══════════════════════════════════════════════════════════════════╝ - │ - ▼ -╔══════════════════════════════════════════════════════════════════╗ -║ PHASE 4: IMPLEMENTATION & QA (Steps 10–12) ║ -║ 📄 steps/steps-10-12-implement.md ║ -╠══════════════════════════════════════════════════════════════════╣ -║ ║ -║ STEP 10 ─ speckit.implement (gpt-5-3-codex) 🔄 GATE ║ -║ │ Input: tasks.md + plan.md + data-model.md + contracts/ ║ -║ │ Output: src/modules// (source code) ║ -║ │ Phase 1: implement all tasks ║ -║ │ Phase 2: build & fix all errors ║ -║ │ Report: 10-implement-report.md (incl. Screen Verification) ║ -║ │ ⚡ REAL EXECUTION — npm build, docker up, npm start ║ -║ │ ║ -║ │ ❌ Build fails → auto-fix → re-build (max 5x) ║ -║ │ ✅ Build success + app starts → continue ║ -║ ▼ ║ -║ STEP 11 ─ okr.reviewcode (claude-sonnet-4-6) 🔄 GATE ║ -║ │ Input: source code + spec + tasks + constitution ║ -║ │ Check: code quality + DB data usage (no mock data) ║ -║ │ Verdict: ✅ APPROVED / ⚠️ CONDITIONS / ❌ REJECTED ║ -║ │ Report: 11-review-code-report.md ║ -║ │ ║ -║ │ ❌ REJECTED → speckit.implement fixes → re-review (max 5x) ║ -║ │ ✅/⚠️ → continue ║ -║ ▼ ║ -║ STEP 12 ─ okr.testkit (claude-sonnet-4-6) 🔄 GATE ║ -║ Mode: run-tests ║ -║ Input: testcases + running app ║ -║ Output: testreport--.md ║ -║ Report: 12-testkit-report.md ║ -║ ⚡ REAL EXECUTION — Jest + Playwright ║ -║ ║ -║ ❌ FAIL → 🔙 BACK-TO-PLAN (speckit.plan → ... → re-test) ║ -║ ✅ PASS → continue ║ -║ Max 3 BACK-TO-PLAN cycles → force continue with defects ║ -║ ║ -╚══════════════════════════════════════════════════════════════════╝ - │ - ▼ -╔══════════════════════════════════════════════════════════════════╗ -║ PHASE 5: LAUNCH (Step 13) ║ -║ 📄 steps/step-13-launch.md ║ -╠══════════════════════════════════════════════════════════════════╣ -║ ║ -║ STEP 13 ─ Boss (direct: build + DB + launch) ║ -║ │ Build BE + connect DB + build FE + start services ║ -║ │ Report: 13-launch-report.md (incl. Launch Status) ║ -║ │ ⚡ REAL EXECUTION — npm build, docker up, npm build+start ║ -║ │ open_browser_page → user sees working UI ║ -║ ▼ ║ -║ ✅ PIPELINE COMPLETE ║ -║ │ Write final pipeline-completion report ║ -║ │ Write [END] boss log entry ║ -║ ║ -╚══════════════════════════════════════════════════════════════════╝ -``` - ---- - -## 3. Agent Roster - -### 3.1 Generation Agents (artifact creation) - -| Agent | Model | Steps | Role | Primary Output | -|-------|-------|-------|------|----------------| -| `okr.srs` | gpt-5.4 | 1 | Requirements analysis → SRS | `srs--.md` | -| `okr.bd` | gpt-5.4 | 2 | External design (BD / External Design) | `bd--.md` | -| `speckit.specify` | gpt-5.4 | 3 | Create feature spec | `spec.md` | -| `speckit.clarify` | gpt-5.4 | 4 | Detect & resolve ambiguities | `spec.md` (updated) | -| `speckit.plan` | gpt-5-3-codex | 6 | Implementation planning | `plan.md`, `data-model.md`, `contracts/` | -| `okr.dd` | gpt-5-3-codex | 8 | Detailed design (DD / Internal Design) | `dd--.md` | -| `speckit.tasks` | gpt-5.4 | 9 | Task decomposition | `tasks.md` | -| `speckit.implement` | gpt-5-3-codex | 10,12,13 | Code implementation + build + launch | `src/modules//` | - -### 3.2 Review Agents (quality assurance) - -| Agent | Model | Steps | Role | Gate | -|-------|-------|-------|------|------| -| `okr.reviewspec` | claude-sonnet-4-6 | 5 | Review spec vs SRS | 🔄 Auto-Retry (max 5) | -| `okr.reviewplan` | claude-sonnet-4-6 | 7 | Review plan vs spec | 🔄 Auto-Retry (max 5) | -| `okr.reviewcode` | claude-sonnet-4-6 | 11 | Review code vs spec/constitution | 🔄 Auto-Retry (max 5) | - -### 3.3 QA Agent (independent testing) - -| Agent | Model | Steps | Mode | Role | -|-------|-------|-------|------|------| -| `okr.testkit` | claude-sonnet-4-6 | 8b | `gen-testcases` | Generate test cases from SRS+BD+DD | -| `okr.testkit` | claude-sonnet-4-6 | 12 | `run-tests` | Execute tests (Jest + Playwright) | - -### 3.4 Boss Orchestrator - -| Agent | Model | Steps | Role | -|-------|-------|-------|------| -| `okr.bossbuiltin` | claude-sonnet-4-6 | ALL | Coordinate the entire pipeline, auto-resolve all issues | - -### 3.5 Model Selection Rationale by Group - -| Group | Agents | Main Task | Preferred Model | Technical Reason | -|-------|--------|-----------|-----------------|------------------| -| Requirements and specification synthesis | `okr.srs`, `okr.bd`, `speckit.specify` | Convert large upstream inputs into formal, internally consistent specification documents | `gpt-5.4` | `gpt-5.4` is a good fit because it handles long-context document synthesis well and keeps structure and terminology stable while writing. That makes it suitable for turning large upstream inputs into long-form specifications with consistent organization and wording. | -| Planning and implementation design | `speckit.plan`, `okr.dd`, `speckit.implement` | Translate approved requirements into implementable technical design and executable code changes | `gpt-5-3-codex` | `gpt-5-3-codex` is a good fit because it is stronger at code-centric reasoning, including code-adjacent design, patch creation and editing, interface- and typing-aware implementation, and build/test-fix loops. That makes it suitable for translating requirements into implementable technical design and executable source changes. | -| Review and orchestration | `okr.reviewspec`, `okr.reviewplan`, `okr.reviewcode`, `okr.testkit`, `okr.bossbuiltin` | Evaluate artifacts, control pipeline progression, and decide pass/fail or retry actions across steps | `claude-sonnet-4-6` | `claude-sonnet-4-6` is a good fit because it is stronger at review and critique, long-context comparison across artifacts, inconsistency and coverage-gap detection, and consistent decision-making. That makes it suitable for gate pass/fail decisions and multi-step pipeline orchestration. | - ---- - -## 4. Communication Mechanisms (Context Exchange) - -### 4.1 Boss → Sub-Agent: Structured $ARGUMENTS - -```yaml -feature-id: 001-xxx -module-id: mod01 -module-keyword: OKR -pipeline-context: docs/output/output_logs/001-xxx/pipeline-context.yaml -mode: autonomous -language: Vietnamese -``` - -### 4.2 Sub-Agent → Boss: Step Result Block - -```yaml - -``` - -### 4.3 Pipeline Context File (shared state) - -``` -docs/output/output_logs//pipeline-context.yaml -``` - -- Created at Step 0 (immutable fields: feature-id, module-id, tech-stack) -- Updated after each step with artifact paths + metrics from STEP-RESULT -- Sub-agents read this file to discover outputs from prior steps → **no need to re-read large files** - ---- - -## 5. Gate Mechanisms - -### 5.1 Report Hard Gate ⛔ -- Applies to: **EVERY step** (after completion) -- Requirement: Report file MUST exist with all required sections -- Protocol: `protocols/report-gate-protocol.md` - -### 5.2 Review Gate 🔄 -- Applies to: Steps 5, 7, 11 (review agents) -- Logic: REJECTED → fix agent corrects → re-review (maximum 5 times) -- Protocol: `protocols/gate-retry-protocol.md` - -### 5.3 Build Gate 🔄 -- Applies to: Step 10 (implementation + build & fix) -- Logic: Build fail → auto-fix → re-build (maximum 5 times) - -### 5.4 Test Gate 🔙 -- Applies to: Step 12 (test execution) -- Logic: Test FAIL → **BACK-TO-PLAN** (return to Step 6 → re-plan → re-implement → re-test) -- Maximum 3 BACK-TO-PLAN cycles → force continue - -### 5.5 Auto-Resolve 🔧 -- Applies to: When encountering `[NEEDS CLARIFICATION]` markers -- Logic: Boss automatically resolves using optimal assumption, logs to report -- Protocol: `protocols/auto-resolve-protocol.md` - ---- - -## 6. File Structure - -``` -.github/agents/ -├── okr.bossbuiltin.agent.md ← Boss orchestrator (~163 lines) -├── okr.srs.agent.md ← Step 1 -├── okr.bd.agent.md ← Step 2 -├── speckit.specify.agent.md ← Step 3 -├── speckit.clarify.agent.md ← Step 4 -├── okr.reviewspec.agent.md ← Step 5 -├── speckit.plan.agent.md ← Step 6 -├── okr.reviewplan.agent.md ← Step 7 -├── okr.dd.agent.md ← Step 8 -├── okr.testkit.agent.md ← Steps 8b, 12 -├── speckit.tasks.agent.md ← Step 9 -├── speckit.implement.agent.md ← Step 10 -├── okr.reviewcode.agent.md ← Step 11 -│ -├── protocols/ ← Protocols (read on-demand) -│ ├── auto-resolve-protocol.md -│ ├── gate-retry-protocol.md -│ ├── report-gate-protocol.md -│ ├── timestamp-protocol.md -│ ├── log-formats.md -│ ├── implement-delegation.md -│ ├── step-result-block.md -│ └── pipeline-context.md -│ -├── steps/ ← Step definitions (read on-demand) -│ ├── steps-01-04-design.md -│ ├── steps-05-07-review.md -│ ├── steps-08-09-detail.md -│ ├── steps-10-12-implement.md -│ └── step-13-launch.md -│ -└── templates/ ← Shared templates - ├── report-templates.md ← Universal report structure - └── pipeline-completion.md ← Pipeline completion template -``` - ---- - -## 7. Output Structure (Runtime) - -``` -docs/output/ -├── ipa-docs/ -│ ├── srs/srs-mod01-xxx.md ← Step 1 -│ ├── bd/bd-mod01-xxx.md ← Step 2 -│ ├── dd/dd-mod01-xxx.md ← Step 8 -│ ├── testcase/testcase-mod01-xxx.md ← Step 8b -│ └── testreport/testreport-mod01-xxx.md ← Step 12 -│ -└── output_logs// - ├── 00-boss.log.md ← Boss log (all steps) - ├── pipeline-context.yaml ← Shared state - └── reports/ - ├── 01-srs-report.md - ├── 02-bd-report.md - ├── 03-specify-report.md - ├── 04-clarify-report.md - ├── 05-review-spec-report.md - ├── 06-plan-report.md - ├── 07-review-plan-report.md - ├── 08-dd-report.md - ├── 08b-testcases-report.md - ├── 09-tasks-report.md - ├── 10-implement-report.md - ├── 11-review-code-report.md - ├── 12-testkit-report.md - └── 13-launch-report.md - -specs// -├── spec.md ← Step 3 -├── plan.md ← Step 6 -├── data-model.md ← Step 6 -├── research.md ← Step 6 -├── tasks.md ← Step 9 -├── contracts/*.md ← Step 6 -└── checklists/requirements.md ← Step 3 -``` - ---- - -## 8. BACK-TO-PLAN Cycle (Special Flow) - -When Step 12 (test execution) FAILS: - -``` -STEP 12 FAIL - │ - ▼ -Boss logs [BACK-TO-PLAN] - │ - ▼ -STEP 6 speckit.plan ← re-plan with failure context - │ - ▼ -STEP 7 okr.reviewplan ← re-review plan - │ - ▼ -STEP 8 okr.dd ← re-generate DD - │ - ▼ -STEP 9 speckit.tasks ← re-generate tasks - │ - ▼ -STEP 10 speckit.implement ← re-implement + build - │ - ▼ -STEP 11 okr.reviewcode ← re-review code - │ - ▼ -STEP 12 okr.testkit ← re-test - │ - ├─ ✅ PASS → STEP 13 (fix & launch) - └─ ❌ FAIL → repeat cycle (max 3 total) - └─ After 3 cycles → force STEP 13 with known defects -``` +# CASAN Manifest-Driven Delivery Flow + +The production flow is selected by `apps//domain/project.manifest.json` and is identical +for every registered project: + +```text +manifest validation + → SRS → business design → specification → spec review + → plan → plan review/retry → detailed design → test design + → tasks → implementation draft → code review/retry + → manifest build + test → evidence → release candidate +``` + +All generation steps preserve requirement IDs from the selected requirement document. Review +steps use the selected quality profile. Build/test and post-patch verification execute only argv +arrays declared by the manifest. Rejected reviews return to the owning generation step with a +bounded retry; verification failure rolls back the approved patch. Application deployment is a +separate environment adapter and must define workload identity, health checks, and rollback. + +Run: + +```bash +bin/casan project validate --manifest apps//domain/project.manifest.json +bin/casan pipeline --manifest apps//domain/project.manifest.json +``` diff --git a/.github/agents/casan.bd.agent.md b/.github/agents/casan.bd.agent.md new file mode 100644 index 0000000..2bd3db9 --- /dev/null +++ b/.github/agents/casan.bd.agent.md @@ -0,0 +1,8 @@ +--- +name: casan.bd +description: Generate project-neutral business and external design from approved inputs. +--- + +Load the selected manifest. Derive journeys and SCR IDs only from its requirement, preserve the +architecture's API/data boundaries, define validation/error states, accessibility and responsive +behavior, and keep full FR/SCR traceability. diff --git a/.github/agents/casan.dd.agent.md b/.github/agents/casan.dd.agent.md new file mode 100644 index 0000000..777bc82 --- /dev/null +++ b/.github/agents/casan.dd.agent.md @@ -0,0 +1,7 @@ +--- +name: casan.dd +description: Generate detailed design within manifest source roots and architecture constraints. +--- + +Map components, authorization, validation, data/transaction boundaries, observability, failure +recovery, and tests to requirement IDs. Never place product logic in shared CASAN packages. diff --git a/.github/agents/casan.pipeline.agent.md b/.github/agents/casan.pipeline.agent.md new file mode 100644 index 0000000..9dfed28 --- /dev/null +++ b/.github/agents/casan.pipeline.agent.md @@ -0,0 +1,9 @@ +--- +name: casan.pipeline +description: Coordinate the complete manifest-driven CASAN delivery pipeline. +agents: [casan.srs, casan.bd, casan.reviewspec, casan.reviewplan, casan.dd, casan.reviewcode, casan.testkit] +--- + +Validate one project manifest before starting. Run the flow documented in `Flow-Agent.md`, enforce +bounded review retries, preserve audit/telemetry correlation, stop on unresolved rejection or +failed build/test, and create only a release candidate unless an approved deployment adapter exists. diff --git a/.github/agents/casan.reviewcode.agent.md b/.github/agents/casan.reviewcode.agent.md new file mode 100644 index 0000000..14f2bf4 --- /dev/null +++ b/.github/agents/casan.reviewcode.agent.md @@ -0,0 +1,9 @@ +--- +name: casan.reviewcode +description: Review implementation evidence without product-specific assumptions. +--- + +Inspect only manifest source roots. Check requirement fidelity, architecture boundaries, input +validation, authorization, persistence correctness, safe errors/logging, test depth, dependency +policy, and matched verification rules. A model review supplements deterministic gates; it never +overrides a failed rule. diff --git a/.github/agents/casan.reviewplan.agent.md b/.github/agents/casan.reviewplan.agent.md new file mode 100644 index 0000000..28d2d47 --- /dev/null +++ b/.github/agents/casan.reviewplan.agent.md @@ -0,0 +1,8 @@ +--- +name: casan.reviewplan +description: Review implementation plans against manifest, architecture, and quality gates. +--- + +Require architecture ownership, implementation workstreams, build/test argv commands, golden +regression, rollback, security, traceability, and companion artifacts. Reject any source root or +command not declared by the manifest. diff --git a/.github/agents/casan.reviewspec.agent.md b/.github/agents/casan.reviewspec.agent.md new file mode 100644 index 0000000..3d32000 --- /dev/null +++ b/.github/agents/casan.reviewspec.agent.md @@ -0,0 +1,8 @@ +--- +name: casan.reviewspec +description: Fail-closed specification review using the selected quality profile. +--- + +Verify complete requirement coverage, source fidelity, testable acceptance criteria, validation, +authorization, data boundaries, error behavior, and contradictions. Return APPROVED or REJECTED +with concrete issues; never approve missing evidence. diff --git a/.github/agents/casan.srs.agent.md b/.github/agents/casan.srs.agent.md new file mode 100644 index 0000000..d041619 --- /dev/null +++ b/.github/agents/casan.srs.agent.md @@ -0,0 +1,8 @@ +--- +name: casan.srs +description: Generate a traceable SRS for the project selected by a CASAN manifest. +--- + +Load the selected manifest, requirement, architecture, and quality profile. Preserve every FR ID, +separate functional/non-functional requirements, cite sources, and write only to the manifest's +artifact namespace. Do not add behavior absent from the requirement. diff --git a/.github/agents/casan.testkit.agent.md b/.github/agents/casan.testkit.agent.md new file mode 100644 index 0000000..92c3204 --- /dev/null +++ b/.github/agents/casan.testkit.agent.md @@ -0,0 +1,8 @@ +--- +name: casan.testkit +description: Design and execute manifest-bound production quality tests. +--- + +Create normal, boundary, invalid, unauthorized, concurrency/idempotency where applicable, +integration, golden-drift, and failure-recovery cases for every requirement ID. Execute only +manifest argv commands and report exact exit codes and evidence paths. diff --git a/.github/agents/copilot-instructions.md b/.github/agents/copilot-instructions.md index 6de2e06..7f7ff4e 100644 --- a/.github/agents/copilot-instructions.md +++ b/.github/agents/copilot-instructions.md @@ -1,517 +1,34 @@ -# GitHub Copilot Instructions for "OKR Web Application" Project - -You are an expert full-stack developer specializing in NestJS and a **master of React with Vite and Tailwind CSS**. Your primary goal is to generate code that is secure, efficient, and **strictly follows this project's architecture and design documents**. Do not invent features or logic. Every piece of code must be traceable to a design specification. - -## 1. The Supreme Rule: Adhere to Architecture & Design - -**Before generating any code, you must understand the project's structure.** - -- **Architecture:** Refer to `docs/technical_architecture.md` for the overall system design, module responsibilities, and technology stack. - -- **Requirements:** Refer to `apps/okr/domain/input/okr-requirement.md` for functional requirements, use cases, and UI mockups. - -- **Your Task:** Your role is to translate these designs into code, not to be creative. - -**Example Check:** - -- **CORRECT:** Logic for key result progress updates belongs in the `key-results` module. - -- **INCORRECT:** Placing key result logic directly within the `objectives` service. - -- **Typescript Types:** Use TypeScript types and interfaces as defined in the design documents. Do not create new types unless explicitly required by the design. - -## 2. Key Technologies & Libraries to Prioritize - -⚠️ **ABSOLUTE LIBRARY RESTRICTION - ZERO TOLERANCE POLICY:** -- **FORBIDDEN:** Installing ANY new libraries beyond those already listed in package.json -- **MANDATORY:** Use ONLY existing libraries from architecture.md dependencies -- **EXCEPTION PROCESS:** If absolutely critical to add a new library, must: - 1. Stop all code generation - 2. Ask explicit permission from user - 3. Provide detailed justification of purpose and necessity - 4. Explain why existing libraries cannot fulfill the requirement - 5. Wait for user approval before proceeding -- **FOCUS:** Maximize capabilities of existing libraries rather than seeking new ones - -**Use only libraries from architecture.md, do not install new libraries.** - -### Frontend Stack (React + Vite SPA): - -| Library | Role | -|---------|------| -| **React 18.x** | UI framework | -| **Vite 5.x** | Build tool & dev server with HMR | -| **React Router DOM 6.x** | Client-side routing (``, ``, ``) | -| **TanStack Query 5.x** | Server state management, caching (`useQuery`, `useMutation`) | -| **Axios 1.x** | HTTP client — all API calls via `src/lib/api.ts` | -| **React Hook Form 7.x** | Form state and submission | -| **Zod 3.x** | Schema validation — schemas in `src/schemas/`, shared with backend DTOs | -| **Tailwind CSS 3.x** | Utility-first styling — **only** styling tool, no CSS-in-JS | - -### Backend Stack (NestJS): - -| Library | Role | -|---------|------| -| **NestJS 10.x** | Application framework (modules, controllers, services, decorators) | -| **Prisma 5.x** | ORM — `schema.prisma` is single source of truth, use Prisma client for all DB ops | -| **@nestjs/jwt** | JWT sign/verify (no Passport — Username/Password only, no SSO) | -| **bcrypt** | Password hashing (cost factor 12) | -| **class-validator + class-transformer** | DTO validation with `ValidationPipe` | -| **@nestjs/swagger** | OpenAPI/Swagger UI at `/api/docs` (dev only) | - -## 2.1. Design Style Guidelines - -**Design Style: Clean Modern Dashboard (Pure Tailwind CSS)** - -This project uses **pure Tailwind CSS** — no external component library (no MUI, no Ant Design). The design is clean, professional, and matches the OKR dashboard wireframes defined in `apps/okr/domain/input/okr-requirement.md`. - -### Layout Structure (matches OKR wireframes): - -``` -+------------------+----------------------------------------------+ -| Sidebar (fixed) | Top Header (fixed) | -| - Year nav +----------------------------------------------+ -| - My OKRs | Main Content Area (scrollable) | -| - Members | | -| - OKR - all | | -+------------------+----------------------------------------------+ -``` - -### Color Palette: - -| Color Name | Tailwind Class | Usage | -|------------|----------------|-------| -| **Background** | `bg-gray-50` | Page background | -| **White** | `bg-white` | Cards, sidebar, content areas | -| **Primary Text** | `text-gray-800` | Titles, important content | -| **Secondary Text** | `text-gray-500` | Labels, descriptions, metadata | -| **Primary Blue** | `bg-blue-600` / `text-blue-600` | Primary actions, active nav links | -| **Success Green** | `text-green-600` / `bg-green-100` | Success status (100% / Completed) | -| **Warning Orange** | `text-orange-500` / `bg-orange-100` | In-progress / pending status | -| **Border** | `border-gray-200` | Card borders, dividers | -| **Sidebar** | `bg-white border-r border-gray-200` | Left navigation panel | - -### Component Style Rules: - -1. **No CSS-in-JS** — no `sx` prop, no `styled()` — all styling via Tailwind utility classes. -2. **Cards:** `bg-white rounded-xl shadow-sm border border-gray-200 p-6` -3. **Primary button:** `bg-blue-600 hover:bg-blue-700 text-white px-4 py-2 rounded-lg font-medium transition-colors` -4. **Secondary button:** `border border-gray-300 text-gray-700 hover:bg-gray-50 px-4 py-2 rounded-lg transition-colors` -5. **Input fields:** `w-full border border-gray-300 rounded-lg px-3 py-2 text-sm focus:outline-none focus:ring-2 focus:ring-blue-500` -6. **Select/Dropdown:** `border border-gray-300 rounded-lg px-3 py-2 text-sm bg-white focus:outline-none focus:ring-2 focus:ring-blue-500` -7. **Status badges:** - - Not Started: `bg-gray-100 text-gray-600 px-2 py-1 rounded-full text-xs font-medium` - - In Progress: `bg-orange-100 text-orange-700 px-2 py-1 rounded-full text-xs font-medium` - - Completed: `bg-green-100 text-green-700 px-2 py-1 rounded-full text-xs font-medium` -8. **Progress bar:** - ```tsx -
-
-
- ``` -9. **Sidebar nav item (active):** `bg-blue-50 text-blue-600 font-medium` -10. **Sidebar nav item (inactive):** `text-gray-600 hover:bg-gray-50 hover:text-gray-800` - -### Consistent Visual Rules: - -- All interactive elements must have hover effects (`hover:shadow-md`, `hover:-translate-y-px`, `transition-colors`). -- Use consistent spacing: multiples of 4px (`p-4`, `gap-4`, `mt-6`). -- Text must always use `gray` (not `grey`) — `text-gray-700`, `border-gray-200`. +# CASAN Multi-Project Repository Instructions -## 2.2. Tailwind CSS Configuration Rules (Tailwind v3) +This repository contains shared CASAN platform code and multiple independently governed +applications. Never infer that the active project is OKR from the repository location. -⚠️ **TAILWIND CSS v3 SPECIFIC REQUIREMENTS:** +## Project selection is mandatory -### CSS Import Rules (v3): -```css -✅ CORRECT: -@tailwind base; -@tailwind components; -@tailwind utilities; +Before changing application code, locate exactly one `apps//domain/project.manifest.json`: -❌ WRONG: @import "tailwindcss"; -❌ WRONG: @import "tailwindcss/base"; -``` +1. Prefer `CASAN_PROJECT_MANIFEST` when supplied. +2. Otherwise select the manifest whose `source_roots` contains every target file. +3. If zero or multiple manifests match, stop and request an explicit project selection. -### Configuration File: -```javascript -// tailwind.config.ts -import type { Config } from 'tailwindcss'; +The selected manifest is authoritative for project ID, source roots, requirement input, +architecture input, quality profile, build/test argv commands, verification mapping, and +artifact namespace. Paths must remain repository-relative and inside the repository root. -const config: Config = { - content: ['./index.html', './src/**/*.{js,ts,jsx,tsx}'], - theme: { - extend: {}, - }, - plugins: [], -}; +## Implementation contract -export default config; -``` +- Read the manifest's requirement and architecture documents before generating code. +- Every behavior must trace to a requirement ID; do not invent product functionality. +- Follow the selected architecture and use only its approved dependencies. +- Keep application code inside manifest `source_roots`. +- Run manifest build and test commands without shell interpolation. +- Run every verification rule matching changed files. +- A draft is not accepted until build, test, security, traceability, review, and evidence gates pass. +- Never weaken a gate, golden baseline, test, corpus, or threshold to make a project pass. +- Shared CASAN code must not contain product-specific paths, roles, entities, endpoints, or fixtures. -### PostCSS Config: -```javascript -// postcss.config.js -export default { - plugins: { - tailwindcss: {}, - autoprefixer: {}, - }, -}; -``` +## Repository-wide files -### Color Class Rules: -```css -✅ CORRECT: text-gray-700, bg-gray-50, border-gray-200 -❌ WRONG: text-grey-700, bg-grey-50, border-grey-200 -``` - -### Layout Rules: -```tsx -✅ CORRECT: Use semantic HTML + Tailwind flex/grid -
-

Title

- -
- -❌ WRONG: Use third-party layout components - - Title - -``` - -### Hover State Rules: -```css -✅ CORRECT: hover:bg-gray-50, hover:bg-gray-100 -❌ WRONG: hover:bg-gray-25 (doesn't exist in Tailwind) -``` - -### Custom Styles Rules: -```css -✅ CORRECT: Use standard CSS in index.css (no @apply with @layer) -.okr-card { - background: white; - border-radius: 0.75rem; - border: 1px solid #e5e7eb; -} - -❌ WRONG: Use @apply with @layer -@layer components { - .okr-card { @apply bg-white rounded-xl border border-gray-200; } -} -``` - -## 3. Backend Generation Rules (NestJS + Prisma) - -### Controller Rules: - -- **Location:** Must be in `backend/src/[module-name]/[module-name].controller.ts`. -- **Responsibility:** Keep controllers "thin". They only receive requests, trigger guards, validate DTOs, and call a single service method. -- **Auth:** Use `@UseGuards(JwtAuthGuard)` and `@Roles()` decorator on all protected routes. - -### Service Rules: - -- **Location:** Must be in `backend/src/[module-name]/[module-name].service.ts`. -- **Responsibility:** All business logic lives here. -- **Key Logic:** - - Use Prisma client for all DB operations — **no raw SQL** in application code. - - Filter data by role: ADMIN sees all, MANAGER sees all, EMPLOYEE sees only own objectives. - - Throw specific NestJS exceptions (`NotFoundException`, `ForbiddenException`). - -### Prisma Schema Rules: - -- **Single source of truth:** `backend/prisma/schema.prisma` defines ALL tables. -- **Migrations:** Use `npx prisma migrate dev --name ` — never edit migration files manually. -- **Types:** Always use Prisma-generated types (`Prisma.ObjectiveCreateInput`, `Prisma.KeyResultUpdateInput`). - -### Module Structure (OKR Domain): - -``` -backend/src/ -├── auth/ # JWT login, refresh token endpoints -├── users/ # User CRUD (Admin/Manager only) -├── objectives/ # Objective CRUD, filtering by quarter/owner/status -├── key-results/ # KR CRUD, progress update (PATCH /:id/progress) -└── common/ # Guards, filters, interceptors, decorators -``` - -### Database Seed Management: - -- **CRITICAL:** After completing backend code with schema changes, **ALWAYS** update the seed file. -- **Seed file location:** `backend/prisma/seed.ts` -- **Execution:** `npx prisma db seed` (or automatically on container start — always seeded in workshop environment) -- **Idempotency:** Use Prisma `upsert` keyed on stable identifiers — running seed twice must produce no duplicates. - -```typescript -// backend/prisma/seed.ts -import { PrismaClient } from '@prisma/client'; -import * as bcrypt from 'bcrypt'; - -const prisma = new PrismaClient(); - -async function main() { - // Always seed — workshop environment, no env gate needed - - const passwordHash = await bcrypt.hash('Password@123', 10); - - // Users — upsert keyed on email - const admin = await prisma.user.upsert({ - where: { email: 'admin@okr.local' }, - update: {}, - create: { name: 'System Admin', email: 'admin@okr.local', password: passwordHash, role: 'ADMIN' }, - }); - - const manager = await prisma.user.upsert({ - where: { email: 'manager@okr.local' }, - update: {}, - create: { name: 'Nguyen Van Manager', email: 'manager@okr.local', password: passwordHash, role: 'MANAGER' }, - }); - - const employee = await prisma.user.upsert({ - where: { email: 'employee@okr.local' }, - update: {}, - create: { name: 'Nguyen Van A', email: 'employee@okr.local', password: passwordHash, role: 'EMPLOYEE' }, - }); - - // Objectives — upsert keyed on id - const obj1 = await prisma.objective.upsert({ - where: { id: 1 }, - update: {}, - create: { - title: 'POC AI for SQL Injection prevention', - description: 'Evaluate AI tools for automated SQL injection detection', - ownerId: employee.id, - quarter: 'Q2/2026', - status: 'IN_PROGRESS', - }, - }); - - // Key Results — upsert keyed on id - await prisma.keyResult.upsert({ - where: { id: 1 }, - update: {}, - create: { - objectiveId: obj1.id, - title: 'Complete 3 POC sessions with security team', - progress: 0, - startValue: 0, - targetValue: 3, - deadline: new Date('2026-06-30'), - }, - }); - - console.log('Seed completed successfully.'); -} - -main() - .catch((e) => { console.error(e); process.exit(1); }) - .finally(() => prisma.$disconnect()); -``` - -### Seed Data Requirements (OKR Domain): - -| Category | Records | Notes | -|----------|---------|-------| -| Users | ≥ 3 | Admin, Manager, Employee — password `Password@123` hashed with bcrypt | -| Objectives | ≥ 2 | One per owner, varied statuses (`NOT_STARTED`, `IN_PROGRESS`) | -| Key Results | ≥ 4 | Linked to objectives, with `progress`, `startValue`, `targetValue`, `deadline` | - -- **When to update seed:** After adding new Prisma model fields, after changing relations, after completing any backend module. -- **Run seed:** `docker-compose exec backend npx prisma db seed` - -## 4. Frontend Generation Rules (React + Vite) - -### Routing Rules (React Router DOM v6): - -```tsx -// frontend/src/App.tsx — route structure - - } /> - }> - }> - } /> - } /> - } /> - } /> - - - -``` - -### Component & File Location Rules: - -- **Route-level pages:** `frontend/src/pages/` (Login, Dashboard, OKRDetail, CreateObjective, KeyResultDetail) -- **Layout components:** `frontend/src/components/layout/` (Sidebar, Header, AppLayout) -- **Reusable UI components:** `frontend/src/components/ui/` (Button, ProgressBar, Badge, Table) -- **Custom hooks:** `frontend/src/hooks/` (useAuth, useObjectives, useKeyResults) -- **API client:** `frontend/src/lib/api.ts` — all Axios calls go here -- **Query client config:** `frontend/src/lib/queryClient.ts` -- **Zod schemas:** `frontend/src/schemas/` -- **TypeScript interfaces:** `frontend/src/types/` - -### Layout Construction Rules: - -- **ONLY** use semantic HTML elements (`
`, `