hero-vibe-kit 0.1.0 → 0.2.0

package/CHANGELOG.md

@@ -9,11 +9,11 @@ All notable changes to hero-vibe-kit are documented here. Format based on
 - `update` — re-renders framework-managed regions while preserving user edits and working files (ACTIVE_STATE).
 - `doctor` — validates settings.json, hook self-tests, doc-link integrity, and tool presence.
 - Bilingual docs (EN + VI): AGENCY_WORKFLOW (task-type router + 5 phases), DEFINITION_OF_DONE, BRANCHING,
-  TEAM_ROSTER, ACTIVE_STATE, COMMUNICATION_PROTOCOL, INTERACTION_PATTERNS, SECURITY_STANDARDS,
-  PERFORMANCE_STANDARDS, and a PRD_AI_FEATURE template.
+  TEAM_ROSTER, ACTIVE_STATE, ARTIFACTS_AND_STORAGE, COMMUNICATION_PROTOCOL, INTERACTION_PATTERNS,
+  SECURITY_STANDARDS, PERFORMANCE_STANDARDS, and a PRD_AI_FEATURE template.
 - Enforcement hooks for Claude Code: `git-guard` (blocks force-push / `--no-verify` / `reset --hard` /
   direct push to main; reminds on commit) and `stop-reminder`.
 - Managed-region markers (`<!-- hero-vibe-kit:start/end -->`) for safe updates.
 - Presets: solo, small-team, enterprise.
 - Optional integrations (reference & auto-install, never bundled): superpowers/taste skills via the `skills`
-  CLI, GitNexus indexing, Serena pointer-memories. All degrade gracefully when absent.
+  CLI, GitNexus indexing, and Serena semantic code-intelligence support. All degrade gracefully when absent.

package/README.md

@@ -41,9 +41,10 @@ npx hero-vibe-kit init --yes --preset small-team --lang en --skip-integrations
 your-project/
   CLAUDE.md          # hero-vibe-kit managed block (your other content preserved)
   AGENTS.md          # cross-agent entry pointer
-  docs/              # AGENCY_WORKFLOW (SSOT) + DEFINITION_OF_DONE, BRANCHING, TEAM_ROSTER,
-                     # ACTIVE_STATE, COMMUNICATION_PROTOCOL, INTERACTION_PATTERNS,
-                     # SECURITY_STANDARDS, PERFORMANCE_STANDARDS, templates/PRD_AI_FEATURE
+  docs/              # AGENCY_WORKFLOW (SSOT) + ARTIFACTS_AND_STORAGE, DEFINITION_OF_DONE,
+                     # BRANCHING, TEAM_ROSTER, ACTIVE_STATE, COMMUNICATION_PROTOCOL,
+                     # INTERACTION_PATTERNS, SECURITY_STANDARDS, PERFORMANCE_STANDARDS,
+                     # templates/PRD_AI_FEATURE; later specs/, plans/, reports/ as needed
   .claude/
     settings.json    # hooks merged into your existing settings (not clobbered)
     hooks/           # git-guard.cjs, stop-reminder.cjs
@@ -52,6 +53,7 @@ your-project/
 ```
 
 - **New project**: scaffolds everything.
+- **Language selection**: `--lang en|vi` renders exactly one active docs set into `docs/`; agents read `docs/AGENCY_WORKFLOW.md`, not duplicate `docs/en` + `docs/vi` trees.
 - **Brownfield**: never overwrites your `CLAUDE.md`/`AGENTS.md`/`settings.json` — it inserts a marked managed block and deep-merges hooks. Your `docs/ACTIVE_STATE.md` is never overwritten. Re-running is idempotent; touched files are backed up to `*.bak`.
 
 ## The task router (heart of it)
@@ -78,7 +80,7 @@ hero-vibe-kit **does not redistribute** third-party tools. `init` offers to set
 | **superpowers** | process skills (brainstorming, TDD, debugging…) from `obra/superpowers` | offers `npx skills add obra/superpowers` | recommended |
 | **taste-skill** | UI/design skills from `Leonxlnx/taste-skill` | offers to install; pick ONE direction | optional |
 | **GitNexus** | code-intelligence CLI/MCP | offers `npx gitnexus analyze` | optional |
-| **Serena** | MCP memory server | seeds pointer-memories if present | optional |
+| **Serena** | semantic code-intelligence MCP | detects existing `.serena/` setup and can seed lightweight pointer notes | optional |
 
 **Required:** Node ≥ 18 and Claude Code. Everything else is optional.
 
@@ -147,14 +149,15 @@ npx hero-vibe-kit init --yes --preset small-team --lang vi --skip-integrations
 
 ## init cài gì
 
-Như sơ đồ ở phần English: `docs/` (AGENCY_WORKFLOW là single source of truth + các chuẩn), `CLAUDE.md`/`AGENTS.md` (chèn **block có marker**, giữ nguyên nội dung của bạn), `.claude/` (hook + settings deep-merge), `.hero-vibe-kit/config.json`.
+Như sơ đồ ở phần English: `docs/` (AGENCY_WORKFLOW là single source of truth, ARTIFACTS_AND_STORAGE quy định output/storage + các chuẩn), `CLAUDE.md`/`AGENTS.md` (chèn **block có marker**, giữ nguyên nội dung của bạn), `.claude/` (hook + settings deep-merge), `.hero-vibe-kit/config.json`.
 
 - **Project mới**: scaffold đầy đủ.
+- **Chọn ngôn ngữ**: `--lang en|vi` chỉ render một bộ docs active vào `docs/`; agent đọc `docs/AGENCY_WORKFLOW.md`, không load trùng cây `docs/en` + `docs/vi`.
 - **Brownfield**: KHÔNG đè `CLAUDE.md`/`AGENTS.md`/`settings.json` — chỉ chèn block + merge hook. `docs/ACTIVE_STATE.md` không bị ghi đè. Chạy lại idempotent; file bị đụng được sao lưu `*.bak`.
 
 ## Tích hợp (tùy chọn — reference & auto-install)
 
-hero-vibe-kit **không redistribute** tool bên thứ ba. `init` mời cài từ nguồn gốc và degrade nếu thiếu: **superpowers** (`npx skills add obra/superpowers`, khuyến nghị), **taste-skill** (tùy chọn, chọn 1 hướng), **GitNexus** (`npx gitnexus analyze`, tùy chọn), **Serena** (seed pointer-memories, tùy chọn). **Bắt buộc:** Node ≥ 18 + Claude Code.
+hero-vibe-kit **không redistribute** tool bên thứ ba. `init` mời cài từ nguồn gốc và degrade nếu thiếu: **superpowers** (`npx skills add obra/superpowers`, khuyến nghị), **taste-skill** (tùy chọn, chọn 1 hướng), **GitNexus** (`npx gitnexus analyze`, tùy chọn), **Serena** (semantic code-intelligence MCP; pointer notes chỉ là phụ, tùy chọn). **Bắt buộc:** Node ≥ 18 + Claude Code.
 
 ## Lệnh & cập nhật
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "hero-vibe-kit",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "An opinionated, AI-assisted software development workflow for Claude Code — task-type router, gates, enforcement hooks, human↔AI communication protocol, and security/performance standards. Works for new and existing (brownfield) projects.",
   "keywords": [
     "claude-code",

package/src/integrations.cjs

@@ -70,15 +70,15 @@ async function run(ctx) {
     cfg.integrations.gitnexus = 'skipped';
   }
 
-  // ---- Serena (optional — seed pointer memories) ----
-  if (detect.hasSerena || await ask.yesno('Seed Serena pointer-memories? (only if you use the Serena MCP server)', detect.hasSerena)) {
+  // ---- Serena (optional — semantic code intelligence; notes are pointers only) ----
+  if (detect.hasSerena || await ask.yesno('Add lightweight Serena pointer notes? (Serena is primarily for semantic code intelligence)', detect.hasSerena)) {
     const memDir = path.join(target, '.serena', 'memories', 'project');
     ensureDir(memDir);
     for (const [name, content] of Object.entries(SERENA_MEMOS)) {
       fs.writeFileSync(path.join(memDir, name), content);
     }
     cfg.integrations.serena = 'seeded';
-    log.ok('Serena pointer-memories seeded (.serena/memories/project/).');
+    log.ok('Serena pointer notes seeded (.serena/memories/project/).');
   } else {
     cfg.integrations.serena = 'skipped';
   }

package/templates/AGENTS.md.tmpl

@@ -4,6 +4,6 @@
 >
 > 1. **Classify the request** via the router table → Read-only / Fast / Standard / Full. Don't run the heavy process for small tasks.
 > 2. **Gate paths** require plan/approval before writing code (Claude Code: Plan Mode).
-> 3. Follow [DEFINITION_OF_DONE](docs/DEFINITION_OF_DONE.md), [BRANCHING](docs/BRANCHING.md), [SECURITY_STANDARDS](docs/SECURITY_STANDARDS.md), [PERFORMANCE_STANDARDS](docs/PERFORMANCE_STANDARDS.md); keep [ACTIVE_STATE](docs/ACTIVE_STATE.md) updated.
+> 3. Follow [DEFINITION_OF_DONE](docs/DEFINITION_OF_DONE.md), [BRANCHING](docs/BRANCHING.md), [SECURITY_STANDARDS](docs/SECURITY_STANDARDS.md), [PERFORMANCE_STANDARDS](docs/PERFORMANCE_STANDARDS.md), and [ARTIFACTS_AND_STORAGE](docs/ARTIFACTS_AND_STORAGE.md); keep [ACTIVE_STATE](docs/ACTIVE_STATE.md) updated.
 > 4. Clarify requirements per [COMMUNICATION_PROTOCOL](docs/COMMUNICATION_PROTOCOL.md); for AI features use the [PRD_AI_FEATURE template](docs/templates/PRD_AI_FEATURE.md) and [INTERACTION_PATTERNS](docs/INTERACTION_PATTERNS.md).
 > 5. Delegate sub-agents with **self-contained** prompts ([TEAM_ROSTER](docs/TEAM_ROSTER.md)).

package/templates/CLAUDE.md.tmpl

@@ -2,9 +2,9 @@
 
 > **READ BEFORE DOING ANYTHING:** [`docs/AGENCY_WORKFLOW.md`](docs/AGENCY_WORKFLOW.md) is the **single source of truth** for the {{PROJECT_NAME}} development process. Classify every request via the router table → pick a path (Read-only / Fast / Standard / Full). Don't run the heavy process for small tasks.
 
-Docs: [AGENCY_WORKFLOW](docs/AGENCY_WORKFLOW.md) · [DEFINITION_OF_DONE](docs/DEFINITION_OF_DONE.md) · [BRANCHING](docs/BRANCHING.md) · [TEAM_ROSTER](docs/TEAM_ROSTER.md) · [ACTIVE_STATE](docs/ACTIVE_STATE.md) · [COMMUNICATION_PROTOCOL](docs/COMMUNICATION_PROTOCOL.md) · [INTERACTION_PATTERNS](docs/INTERACTION_PATTERNS.md) · [SECURITY_STANDARDS](docs/SECURITY_STANDARDS.md) · [PERFORMANCE_STANDARDS](docs/PERFORMANCE_STANDARDS.md) · [PRD_AI_FEATURE template](docs/templates/PRD_AI_FEATURE.md).
+Docs: [AGENCY_WORKFLOW](docs/AGENCY_WORKFLOW.md) · [ARTIFACTS_AND_STORAGE](docs/ARTIFACTS_AND_STORAGE.md) · [DEFINITION_OF_DONE](docs/DEFINITION_OF_DONE.md) · [BRANCHING](docs/BRANCHING.md) · [TEAM_ROSTER](docs/TEAM_ROSTER.md) · [ACTIVE_STATE](docs/ACTIVE_STATE.md) · [COMMUNICATION_PROTOCOL](docs/COMMUNICATION_PROTOCOL.md) · [INTERACTION_PATTERNS](docs/INTERACTION_PATTERNS.md) · [SECURITY_STANDARDS](docs/SECURITY_STANDARDS.md) · [PERFORMANCE_STANDARDS](docs/PERFORMANCE_STANDARDS.md) · [PRD_AI_FEATURE template](docs/templates/PRD_AI_FEATURE.md).
 
-- **Workflow state:** read `docs/ACTIVE_STATE.md` at the start of every session and keep it updated.
+- **Workflow state & artifacts:** read `docs/ACTIVE_STATE.md` at the start of every session; store durable PRDs/plans/reports under the paths defined in `docs/ARTIFACTS_AND_STORAGE.md`.
 - **Gates:** when a path requires a Gate, use Plan Mode (`EnterPlanMode` → `ExitPlanMode`) for real sign-off — not a prose promise.
 - **Enforcement:** `git-guard` (PreToolUse) + `stop-reminder` (Stop) hooks are installed under `.claude/`. Don't bypass them.
 - **GitNexus (if installed):** impact analysis is **conditional** — skip on an empty repo; apply once real code exists (Standard/Full paths) or per the escalation rule. If the index is stale, run `npx gitnexus analyze`.

package/templates/docs/en/ACTIVE_STATE.md

@@ -19,7 +19,7 @@
 
 ## Session Resume Protocol
 *An AI starting a new session READS this section:*
-1. Read [AGENCY_WORKFLOW.md](./AGENCY_WORKFLOW.md) (SSOT) for the router & paths.
+1. Read [AGENCY_WORKFLOW.md](./AGENCY_WORKFLOW.md) (SSOT) for the router & paths, then [ARTIFACTS_AND_STORAGE.md](./ARTIFACTS_AND_STORAGE.md) for artifact locations.
 2. Look at the "Active Features" table above + any **open MRs** (`git branch`, MR list) — do NOT rely on the previous session's TaskList (it's gone).
 3. By each feature's path & phase:
    - **Read-only/Fast**: continue/finish then open the MR.

package/templates/docs/en/AGENCY_WORKFLOW.md

@@ -1,6 +1,6 @@
 # Agency Workflow — Single Source of Truth
 
-> **This is the ONLY canonical process document.** Every other file (CLAUDE.md, AGENTS.md, TEAM_ROSTER.md, Serena memories) only **links** here — it must NOT copy the content. To change the process, edit only this file.
+> **This is the ONLY canonical process document.** Every other file (CLAUDE.md, AGENTS.md, TEAM_ROSTER.md, optional Serena notes) only **links** here — it must NOT copy the content. To change the process, edit only this file.
 
 The AI acts as a lean software agency. Operating scale: **{{TEAM_SIZE}} + AI**, following **{{BRANCHING_MODEL}}** (see [BRANCHING.md](./BRANCHING.md)). Completion criteria: see [DEFINITION_OF_DONE.md](./DEFINITION_OF_DONE.md).
 
@@ -76,7 +76,7 @@ See §3.
 1. Trigger the `brainstorming` skill. **Apply [COMMUNICATION_PROTOCOL.md](./COMMUNICATION_PROTOCOL.md)** throughout (how to ask, label assumptions, close each round with a summary + open questions + assumptions).
 2. Clarify: User Personas, Business Flows, Edge Cases, goals, acceptance criteria.
 3. **If it's an AI/assistant feature:** use the **[PRD_AI_FEATURE.md template](./templates/PRD_AI_FEATURE.md)** — it forces the AI-specific dimensions (behavior under ambiguity, guardrails/refusal, definition of "correct" + golden examples, eval strategy, fallback/HITL), and references [INTERACTION_PATTERNS.md](./INTERACTION_PATTERNS.md) for how the assistant talks to end-users.
-4. Output: **PRD / Scope Document** (copy to `docs/specs/YYYY-MM-DD-<feature>.md`, link in ACTIVE_STATE) — including a Decision Log + Assumptions Register.
+4. Output: **PRD / Scope Document** under `docs/specs/` per [ARTIFACTS_AND_STORAGE.md](./ARTIFACTS_AND_STORAGE.md), linked from ACTIVE_STATE — including a Decision Log + Assumptions Register.
 5. **GATE 1 (Plan Mode):** present the PRD → `ExitPlanMode` → wait for the user (Product Owner) to approve.
 
 ### Phase 2 — Architecture & Planning (lens: System Architect)
@@ -86,7 +86,7 @@ See §3.
 4. **Set the performance budget:** decide target latency/throughput/token-cost per [PERFORMANCE_STANDARDS.md](./PERFORMANCE_STANDARDS.md) (fill the `<TBD>`s).
 5. **Lock the API/interface contract** between components (FE↔BE, module↔module). *This is a prerequisite for parallelizing in Phase 3.*
 6. Trigger `writing-plans` to break down the work → create tasks with `TaskCreate` (session-scoped) + record in ACTIVE_STATE (durable).
-7. Output: **Technical Design Document (TDD)** + task list.
+7. Output: **Technical Design Document (TDD)** under `docs/plans/` + task list, with report artifacts under `docs/reports/` as required by [ARTIFACTS_AND_STORAGE.md](./ARTIFACTS_AND_STORAGE.md).
 8. **GATE 2 (Plan Mode):** present the TDD → `ExitPlanMode` → wait for approval of the technical approach.
 
 ### Phase 3 — Implementation (lens: Developer, possibly a sub-agent)
@@ -105,8 +105,8 @@ See §3.
 ### Phase 5 — Handover & Retro (lens: DevOps / Scrum Master)
 1. Trigger `finishing-a-development-branch` → open/merge the MR per [BRANCHING.md](./BRANCHING.md).
 2. Update **CLAUDE.md** if there are new architectural decisions (record only what's new, don't duplicate).
-3. **Light retro (3 lines):** what went well / what was painful / one improvement for next time — record in ACTIVE_STATE or the MR.
-4. Save project context to Serena memory (pointers, no content duplication).
+3. **Light retro (3 lines):** what went well / what was painful / one improvement for next time — record it in ACTIVE_STATE, the MR, or `docs/reports/<slug>/retro.md` per [ARTIFACTS_AND_STORAGE.md](./ARTIFACTS_AND_STORAGE.md).
+4. If Serena is configured, use it for semantic code navigation and keep any optional notes as pointers only, with no content duplication.
 5. Mark tasks `completed` + update ACTIVE_STATE.
 
 ---
@@ -119,6 +119,7 @@ See §3.
 | [BRANCHING.md](./BRANCHING.md) | Branching model, branch naming, Conventional Commits |
 | [TEAM_ROSTER.md](./TEAM_ROSTER.md) | Personas + sub-agent delegation rules + design direction |
 | [ACTIVE_STATE.md](./ACTIVE_STATE.md) | Pipeline state + resume protocol |
+| [ARTIFACTS_AND_STORAGE.md](./ARTIFACTS_AND_STORAGE.md) | Output artifacts, docs/specs/plans/reports layout, storage rules |
 | [COMMUNICATION_PROTOCOL.md](./COMMUNICATION_PROTOCOL.md) | Human↔AI communication protocol (requirements clarification) |
 | [templates/PRD_AI_FEATURE.md](./templates/PRD_AI_FEATURE.md) | PRD template for AI features (dimensions to clarify) |
 | [INTERACTION_PATTERNS.md](./INTERACTION_PATTERNS.md) | How the product (assistant) talks to end-users |

package/templates/docs/en/ARTIFACTS_AND_STORAGE.md

@@ -0,0 +1,82 @@
+# Artifacts & Storage
+
+> Defines what each workflow produces, where it is stored, and what is authoritative. The source of truth is the repository docs; Serena is for semantic code intelligence, with optional pointer notes only.
+
+## 1. Storage roles
+
+| Information | Primary storage | Purpose | Notes |
+|---|---|---|---|
+| Durable workflow state | `docs/ACTIVE_STATE.md` | Cross-session backlog and resume state | Update when a feature starts, changes phase/status, blocks, or finishes. |
+| PRD / scope | `docs/specs/YYYY-MM-DD-<slug>.md` | Requirements, acceptance criteria, decision log, assumptions | Required for Full path; optional for Standard when scope is complex. |
+| Technical plan / TDD | `docs/plans/YYYY-MM-DD-<slug>.md` | Architecture, API/interface contract, task breakdown, risk plan | Required for Standard/Full gated work. |
+| Impact analysis | `docs/reports/YYYY-MM-DD-<slug>/impact.md` | Blast radius, affected flows, risk level | Required for Standard changes to existing code and refactors. |
+| Security review | `docs/reports/YYYY-MM-DD-<slug>/security.md` | Threat model findings, OWASP LLM checks, unresolved risks | Required for Full path and sensitive surfaces. |
+| Performance review | `docs/reports/YYYY-MM-DD-<slug>/performance.md` | Budget, measurements, regressions, token/cost checks | Required when performance budget exists or hot path changes. |
+| QA / verification | `docs/reports/YYYY-MM-DD-<slug>/qa.md` | Test commands, manual checks, known gaps | Required before claiming done on Standard/Full. |
+| Retro / handover | `docs/reports/YYYY-MM-DD-<slug>/retro.md` | What went well, pain points, one improvement | Required for Full path; optional otherwise. |
+| Session task tracking | `TaskCreate` / `TaskList` | Current-session execution checklist | Not durable; recreate from `ACTIVE_STATE.md` + linked artifacts after restart. |
+| Semantic code understanding | Serena MCP | Symbol lookup, references, implementations, diagnostics, semantic edits | Not the primary storage layer. |
+| Optional Serena notes | `.serena/memories/project/*.md` | Lightweight pointers back to repo docs | Never duplicate canonical process, PRD, plans, or reports here. |
+
+## 2. Directory layout
+
+```txt
+docs/
+  AGENCY_WORKFLOW.md
+  ARTIFACTS_AND_STORAGE.md
+  ACTIVE_STATE.md
+  DEFINITION_OF_DONE.md
+  BRANCHING.md
+  TEAM_ROSTER.md
+  COMMUNICATION_PROTOCOL.md
+  SECURITY_STANDARDS.md
+  PERFORMANCE_STANDARDS.md
+  INTERACTION_PATTERNS.md
+
+  specs/
+    YYYY-MM-DD-feature-name.md
+
+  plans/
+    YYYY-MM-DD-feature-name.md
+
+  reports/
+    YYYY-MM-DD-feature-name/
+      impact.md
+      security.md
+      performance.md
+      qa.md
+      retro.md
+
+  templates/
+    PRD_AI_FEATURE.md
+```
+
+Create `specs/`, `plans/`, and `reports/` only when the first artifact of that type is needed.
+
+## 3. Artifact rules by path
+
+| Path | Required durable artifacts |
+|---|---|
+| Read-only | None. Answer with `file:line` citations; do not create docs unless the user asks. |
+| Fast | Update `ACTIVE_STATE.md` only if the task represents ongoing work. Bugfixes should include test evidence in the MR/PR; create `reports/.../qa.md` only when useful. |
+| Standard | `ACTIVE_STATE.md`, `plans/*.md`, `reports/.../impact.md`, and `reports/.../qa.md`. Add security/performance reports when the touched surface requires them. |
+| Full | `ACTIVE_STATE.md`, `specs/*.md`, `plans/*.md`, `reports/.../impact.md`, `security.md`, `performance.md`, `qa.md`, and `retro.md`. |
+| Spike | `docs/reports/YYYY-MM-DD-<slug>/recommendation.md`; do not merge throwaway POC code into main. |
+
+## 4. Naming rules
+
+- Use lowercase kebab-case slugs: `2026-06-02-checkout-retry.md`.
+- Use the same `<slug>` across specs, plans, and reports for the same work item.
+- Link artifacts from the row in `ACTIVE_STATE.md`.
+- Reports should record evidence and decisions, not duplicate long code excerpts.
+
+## 5. What is authoritative
+
+1. Process rules: `docs/AGENCY_WORKFLOW.md`.
+2. Artifact/storage rules: this file.
+3. Current work state: `docs/ACTIVE_STATE.md`.
+4. Requirements: linked file in `docs/specs/`.
+5. Technical approach: linked file in `docs/plans/`.
+6. Verification evidence: linked files in `docs/reports/`.
+
+If a tool memory or chat history conflicts with repo docs, trust the repo docs and update stale pointers.

package/templates/docs/en/DEFINITION_OF_DONE.md

@@ -50,7 +50,7 @@ Includes all of Standard path, plus:
 - [ ] `security-review` ran, no unresolved new findings.
 - [ ] **Security standards (Full):** meets [SECURITY_STANDARDS.md](./SECURITY_STANDARDS.md) §5; AI features checked against OWASP LLM Top 10 (§2) including abuse cases.
 - [ ] **Performance standards (Full):** meets the [PERFORMANCE_STANDARDS.md](./PERFORMANCE_STANDARDS.md) §1 budget; AI features meet the token/latency ceiling §2; load measurement exists for the main flow.
-- [ ] **Handover:** CLAUDE.md updated with new architectural decisions (if any); 3-line retro recorded; Serena memory updated (pointers); task `completed` + ACTIVE_STATE updated.
+- [ ] **Handover:** CLAUDE.md updated with new architectural decisions (if any); 3-line retro recorded; optional Serena notes updated as pointers; task `completed` + ACTIVE_STATE updated.
 
 ---
 

package/templates/docs/en/TEAM_ROSTER.md

@@ -6,7 +6,7 @@
 Holds the session, talks to the user, orchestrates sub-agents. Rotates hats:
 - **BA** — `brainstorming`: clarify requirements, write the PRD, get sign-off (Gate 1).
 - **System Architect** — `gitnexus_exploring` + `gitnexus_impact`: design, write the TDD, lock the API contract + threat model, split tasks (Gate 2).
-- **Scrum Master** — manages [ACTIVE_STATE.md](./ACTIVE_STATE.md), updates CLAUDE.md & Serena memory.
+- **Scrum Master** — manages [ACTIVE_STATE.md](./ACTIVE_STATE.md), updates CLAUDE.md, and uses Serena for semantic code navigation when configured.
 
 ## 2. Sub-agents (Dev / QA)
 Spawned via the `Agent` tool when the work is large enough (Standard/Full path).

package/templates/docs/vi/ACTIVE_STATE.md

@@ -19,7 +19,7 @@
 
 ## Session Resume Protocol
 *AI khởi tạo session mới ĐỌC mục này:*
-1. Đọc [AGENCY_WORKFLOW.md](./AGENCY_WORKFLOW.md) (SSOT) để nắm router & path.
+1. Đọc [AGENCY_WORKFLOW.md](./AGENCY_WORKFLOW.md) (SSOT) để nắm router & path, rồi đọc [ARTIFACTS_AND_STORAGE.md](./ARTIFACTS_AND_STORAGE.md) để biết nơi lưu artifact.
 2. Xem bảng "Active Features" ở trên + các **GitLab MR đang mở** (`git branch`, MR list) — KHÔNG dựa vào TaskList của session cũ (đã mất).
 3. Theo path & phase của từng feature:
    - **Read-only/Fast**: tiếp tục/hoàn tất rồi mở MR.

package/templates/docs/vi/AGENCY_WORKFLOW.md

@@ -1,6 +1,6 @@
 # Agency Workflow — Single Source of Truth
 
-> **Đây là tài liệu quy trình DUY NHẤT (canonical).** Mọi tài liệu khác (CLAUDE.md, AGENTS.md, TEAM_ROSTER.md, Serena memories) chỉ được **trỏ link** tới đây, KHÔNG được sao chép nội dung. Sửa quy trình → chỉ sửa file này.
+> **Đây là tài liệu quy trình DUY NHẤT (canonical).** Mọi tài liệu khác (CLAUDE.md, AGENTS.md, TEAM_ROSTER.md, ghi chú Serena tùy chọn) chỉ được **trỏ link** tới đây, KHÔNG được sao chép nội dung. Sửa quy trình → chỉ sửa file này.
 
 AI đóng vai một software agency tinh gọn. Quy mô vận hành: **{{TEAM_SIZE}} + AI**, theo **{{BRANCHING_MODEL}}** (xem [BRANCHING.md](./BRANCHING.md)). Tiêu chí hoàn thành: xem [DEFINITION_OF_DONE.md](./DEFINITION_OF_DONE.md).
 
@@ -76,7 +76,7 @@ Xem §3.
 1. Trigger skill `brainstorming`. **Áp dụng [COMMUNICATION_PROTOCOL.md](./COMMUNICATION_PROTOCOL.md)** xuyên suốt (cách hỏi, gắn nhãn giả định, kết mỗi vòng bằng tóm tắt + câu hỏi mở + giả định).
 2. Làm rõ: User Personas, Business Flows, Edge Cases, mục tiêu, tiêu chí chấp nhận (acceptance criteria).
 3. **Nếu là feature AI/assistant:** dùng **[template PRD_AI_FEATURE.md](./templates/PRD_AI_FEATURE.md)** — bắt buộc làm rõ các chiều đặc thù (hành vi khi mơ hồ, guardrails/refusal, định nghĩa "đúng" + golden examples, eval strategy, fallback/HITL), tham chiếu [INTERACTION_PATTERNS.md](./INTERACTION_PATTERNS.md) cho cách assistant giao tiếp với end-user.
-4. Output: **PRD / Scope Document** (copy vào `docs/specs/YYYY-MM-DD-<feature>.md`, link vào ACTIVE_STATE) — gồm Decision Log + Assumptions Register.
+4. Output: **PRD / Scope Document** trong `docs/specs/` theo [ARTIFACTS_AND_STORAGE.md](./ARTIFACTS_AND_STORAGE.md), link vào ACTIVE_STATE — gồm Decision Log + Assumptions Register.
 5. **GATE 1 (Plan Mode):** trình PRD → `ExitPlanMode` → chờ User (Product Owner) duyệt.
 
 ### Phase 2 — Architecture & Planning (lăng kính: System Architect)
@@ -86,7 +86,7 @@ Xem §3.
 4. **Đặt performance budget:** chốt latency/throughput/token-cost mục tiêu theo [PERFORMANCE_STANDARDS.md](./PERFORMANCE_STANDARDS.md) (điền `<TBD>`).
 5. **Chốt API/interface contract** giữa các thành phần (FE↔BE, module↔module). *Đây là điều kiện tiên quyết để được phép parallelize ở Phase 3.*
 6. Trigger `writing-plans` để chia nhỏ công việc → tạo task bằng `TaskCreate` (session-scoped) + ghi vào ACTIVE_STATE (bền vững).
-7. Output: **Technical Design Document (TDD)** + Task list.
+7. Output: **Technical Design Document (TDD)** trong `docs/plans/` + Task list, kèm report artifact trong `docs/reports/` theo [ARTIFACTS_AND_STORAGE.md](./ARTIFACTS_AND_STORAGE.md).
 8. **GATE 2 (Plan Mode):** trình TDD → `ExitPlanMode` → chờ User duyệt cách tiếp cận kỹ thuật.
 
 ### Phase 3 — Implementation (lăng kính: Developer, có thể là sub-agent)
@@ -105,8 +105,8 @@ Xem §3.
 ### Phase 5 — Handover & Retro (lăng kính: DevOps / Scrum Master)
 1. Trigger `finishing-a-development-branch` → mở/merge MR theo [BRANCHING.md](./BRANCHING.md).
 2. Cập nhật **CLAUDE.md** nếu có quyết định kiến trúc mới (chỉ ghi cái mới, không lặp).
-3. **Retro nhẹ (3 dòng):** cái gì chạy tốt / cái gì vướng / 1 cải tiến cho lần sau — ghi vào ACTIVE_STATE hoặc MR.
-4. Lưu ngữ cảnh dự án vào Serena memory (con trỏ, không lặp nội dung).
+3. **Retro nhẹ (3 dòng):** cái gì chạy tốt / cái gì vướng / 1 cải tiến cho lần sau — ghi vào ACTIVE_STATE, MR, hoặc `docs/reports/<slug>/retro.md` theo [ARTIFACTS_AND_STORAGE.md](./ARTIFACTS_AND_STORAGE.md).
+4. Nếu đã cấu hình Serena, dùng nó cho semantic code navigation và chỉ giữ ghi chú tùy chọn dạng con trỏ, không lặp nội dung.
 5. Đánh dấu task `completed` + cập nhật ACTIVE_STATE.
 
 ---
@@ -119,6 +119,7 @@ Xem §3.
 | [BRANCHING.md](./BRANCHING.md) | GitLab flow, đặt tên nhánh, Conventional Commits |
 | [TEAM_ROSTER.md](./TEAM_ROSTER.md) | Persona + quy tắc delegate sub-agent + design direction |
 | [ACTIVE_STATE.md](./ACTIVE_STATE.md) | Trạng thái pipeline + resume protocol |
+| [ARTIFACTS_AND_STORAGE.md](./ARTIFACTS_AND_STORAGE.md) | Output artifact, layout docs/specs/plans/reports, quy tắc lưu trữ |
 | [COMMUNICATION_PROTOCOL.md](./COMMUNICATION_PROTOCOL.md) | Giao thức giao tiếp Human↔AI (làm rõ yêu cầu) |
 | [templates/PRD_AI_FEATURE.md](./templates/PRD_AI_FEATURE.md) | Template PRD cho feature AI (các chiều cần làm rõ) |
 | [INTERACTION_PATTERNS.md](./INTERACTION_PATTERNS.md) | Cách sản phẩm (assistant) giao tiếp với end-user |

package/templates/docs/vi/ARTIFACTS_AND_STORAGE.md

@@ -0,0 +1,82 @@
+# Artifacts & Storage
+
+> Quy định mỗi workflow tạo output gì, lưu ở đâu, và cái gì là nguồn chính thức. Source of truth là docs trong repo; Serena dùng cho semantic code intelligence, ghi chú/pointer chỉ là phụ.
+
+## 1. Vai trò lưu trữ
+
+| Loại thông tin | Nơi lưu chính | Mục đích | Ghi chú |
+|---|---|---|---|
+| Trạng thái workflow bền vững | `docs/ACTIVE_STATE.md` | Backlog xuyên session và trạng thái resume | Cập nhật khi feature bắt đầu, đổi phase/status, bị block, hoặc hoàn tất. |
+| PRD / scope | `docs/specs/YYYY-MM-DD-<slug>.md` | Requirement, acceptance criteria, decision log, assumptions | Bắt buộc cho Full path; tùy chọn cho Standard nếu scope phức tạp. |
+| Technical plan / TDD | `docs/plans/YYYY-MM-DD-<slug>.md` | Kiến trúc, API/interface contract, chia task, kế hoạch rủi ro | Bắt buộc cho Standard/Full có gate. |
+| Impact analysis | `docs/reports/YYYY-MM-DD-<slug>/impact.md` | Blast radius, flow bị ảnh hưởng, mức rủi ro | Bắt buộc cho Standard khi sửa code cũ hoặc refactor. |
+| Security review | `docs/reports/YYYY-MM-DD-<slug>/security.md` | Threat model findings, OWASP LLM checks, rủi ro chưa xử lý | Bắt buộc cho Full path và bề mặt nhạy cảm. |
+| Performance review | `docs/reports/YYYY-MM-DD-<slug>/performance.md` | Budget, số đo, regression, token/cost checks | Bắt buộc khi có performance budget hoặc sửa hot path. |
+| QA / verification | `docs/reports/YYYY-MM-DD-<slug>/qa.md` | Lệnh test, kiểm tra thủ công, gap còn biết trước | Bắt buộc trước khi claim done ở Standard/Full. |
+| Retro / handover | `docs/reports/YYYY-MM-DD-<slug>/retro.md` | Cái gì tốt, cái gì vướng, một cải tiến | Bắt buộc cho Full path; tùy chọn path khác. |
+| Task tracking trong session | `TaskCreate` / `TaskList` | Checklist thực thi của session hiện tại | Không bền vững; sau restart tạo lại từ `ACTIVE_STATE.md` + artifact đã link. |
+| Semantic code understanding | Serena MCP | Symbol lookup, references, implementations, diagnostics, semantic edits | Không phải lớp storage chính. |
+| Ghi chú Serena tùy chọn | `.serena/memories/project/*.md` | Pointer nhẹ trỏ về docs trong repo | Không bao giờ duplicate process, PRD, plan, hoặc report canonical ở đây. |
+
+## 2. Cấu trúc thư mục
+
+```txt
+docs/
+  AGENCY_WORKFLOW.md
+  ARTIFACTS_AND_STORAGE.md
+  ACTIVE_STATE.md
+  DEFINITION_OF_DONE.md
+  BRANCHING.md
+  TEAM_ROSTER.md
+  COMMUNICATION_PROTOCOL.md
+  SECURITY_STANDARDS.md
+  PERFORMANCE_STANDARDS.md
+  INTERACTION_PATTERNS.md
+
+  specs/
+    YYYY-MM-DD-feature-name.md
+
+  plans/
+    YYYY-MM-DD-feature-name.md
+
+  reports/
+    YYYY-MM-DD-feature-name/
+      impact.md
+      security.md
+      performance.md
+      qa.md
+      retro.md
+
+  templates/
+    PRD_AI_FEATURE.md
+```
+
+Chỉ tạo `specs/`, `plans/`, và `reports/` khi cần artifact đầu tiên thuộc loại đó.
+
+## 3. Artifact theo từng path
+
+| Path | Artifact bền vững bắt buộc |
+|---|---|
+| Read-only | Không. Trả lời kèm trích dẫn `file:line`; không tạo docs trừ khi User yêu cầu. |
+| Fast | Chỉ cập nhật `ACTIVE_STATE.md` nếu task là việc đang kéo dài. Bugfix cần có bằng chứng test trong MR/PR; chỉ tạo `reports/.../qa.md` khi hữu ích. |
+| Standard | `ACTIVE_STATE.md`, `plans/*.md`, `reports/.../impact.md`, và `reports/.../qa.md`. Thêm security/performance report nếu bề mặt chạm tới yêu cầu. |
+| Full | `ACTIVE_STATE.md`, `specs/*.md`, `plans/*.md`, `reports/.../impact.md`, `security.md`, `performance.md`, `qa.md`, và `retro.md`. |
+| Spike | `docs/reports/YYYY-MM-DD-<slug>/recommendation.md`; không merge code POC vứt đi vào main. |
+
+## 4. Quy tắc đặt tên
+
+- Dùng lowercase kebab-case slug: `2026-06-02-checkout-retry.md`.
+- Dùng cùng `<slug>` cho specs, plans, và reports của cùng một work item.
+- Link artifact từ dòng tương ứng trong `ACTIVE_STATE.md`.
+- Report ghi evidence và quyết định, không copy đoạn code dài.
+
+## 5. Cái gì là authoritative
+
+1. Quy trình: `docs/AGENCY_WORKFLOW.md`.
+2. Quy tắc artifact/storage: file này.
+3. Trạng thái công việc hiện tại: `docs/ACTIVE_STATE.md`.
+4. Requirement: file đã link trong `docs/specs/`.
+5. Cách tiếp cận kỹ thuật: file đã link trong `docs/plans/`.
+6. Bằng chứng kiểm chứng: file đã link trong `docs/reports/`.
+
+Nếu tool memory hoặc chat history mâu thuẫn với docs trong repo, tin docs trong repo và cập nhật pointer đã cũ.

package/templates/docs/vi/DEFINITION_OF_DONE.md

@@ -50,7 +50,7 @@ Bao gồm toàn bộ Standard path, cộng thêm:
 - [ ] `security-review` đã chạy, không có finding mới chưa xử lý.
 - [ ] **Security standards (Full):** đạt [SECURITY_STANDARDS.md](./SECURITY_STANDARDS.md) §5; feature AI đã kiểm OWASP LLM Top 10 (§2) gồm ca lạm dụng.
 - [ ] **Performance standards (Full):** đạt budget [PERFORMANCE_STANDARDS.md](./PERFORMANCE_STANDARDS.md) §1; feature AI đạt token/latency ceiling §2; có số đo tải cho luồng chính.
-- [ ] **Handover:** CLAUDE.md cập nhật quyết định kiến trúc mới (nếu có); retro 3 dòng đã ghi; Serena memory cập nhật (con trỏ); task `completed` + ACTIVE_STATE cập nhật.
+- [ ] **Handover:** CLAUDE.md cập nhật quyết định kiến trúc mới (nếu có); retro 3 dòng đã ghi; ghi chú Serena tùy chọn cập nhật dạng con trỏ; task `completed` + ACTIVE_STATE cập nhật.
 
 ---
 

package/templates/docs/vi/TEAM_ROSTER.md

@@ -6,7 +6,7 @@
 Giữ session, nói chuyện với User, điều phối sub-agent. Luân phiên đội mũ:
 - **BA** — `brainstorming`: làm rõ yêu cầu, viết PRD, lấy sign-off (Gate 1).
 - **System Architect** — `gitnexus_exploring` + `gitnexus_impact`: thiết kế, viết TDD, chốt API contract + threat model, chia task (Gate 2).
-- **Scrum Master** — quản lý [ACTIVE_STATE.md](./ACTIVE_STATE.md), cập nhật CLAUDE.md & Serena memory.
+- **Scrum Master** — quản lý [ACTIVE_STATE.md](./ACTIVE_STATE.md), cập nhật CLAUDE.md, và dùng Serena cho semantic code navigation khi đã cấu hình.
 
 ## 2. Sub-agents (Dev / QA)
 Spawn qua `Agent` tool khi việc đủ lớn (Standard/Full path).