hero-vibe-kit 0.1.0

package/templates/docs/en/BRANCHING.md

@@ -0,0 +1,44 @@
+# Branching & Commit Convention
+
+> Model: **{{BRANCHING_MODEL}}** for a {{TEAM_SIZE}} team. `main` is always deployable.
+
+## Branches
+- **`main`** — protected. NO direct commits/pushes. All changes land via a **Merge/Pull Request (MR/PR)**.
+- Short-lived working branches, created from `main`, named `<type>/<short-kebab-description>`:
+
+| Prefix | Use for | Task type (router) |
+|--------|---------|--------------------|
+| `feat/` | new feature | #7 |
+| `fix/` | bug fix | #3 |
+| `change/` | change existing feature logic | #5 |
+| `refactor/` | cleanup, no behavior change | #6 |
+| `chore/` | build, deps, config | #2 |
+| `docs/` | docs only | #2 |
+| `hotfix/` | urgent prod patch (off `main`) | #4 |
+| `spike/` | research/POC (throwaway, code not merged) | #8 |
+
+Examples: `feat/user-login`, `fix/null-cart-total`, `change/discount-rounding`.
+
+## Merge/Pull Request
+- **At least 1 reviewer** approval required before merge.
+- Must meet the [DEFINITION_OF_DONE.md](./DEFINITION_OF_DONE.md) of its path (CI green).
+- **Squash merge** into `main` for a clean history (1 branch = 1 meaningful commit).
+- Delete the branch after merge.
+- The MR description states **what + why**, links PRD/TDD for Standard/Full.
+
+## Commits — Conventional Commits
+Format: `<type>(<scope>): <description>` — type matches the branch prefix: `feat` `fix` `refactor` `chore` `docs` `test` `perf`.
+
+```
+feat(auth): add email login
+fix(cart): handle null total when cart is empty
+```
+
+- BREAKING CHANGE: add `!` after the type (`feat!:`) or a `BREAKING CHANGE:` footer.
+- Do NOT use `--no-verify` / `--no-gpg-sign` unless the user explicitly asks (the hook will block it).
+
+## Hotfix & backport
+1. Create `hotfix/<...>` from `main`.
+2. Minimal patch + a reproducing test → fast MR (still reviewed) → merge into `main`.
+3. **Backport**: cherry-pick/merge the change into the open development branch so it isn't lost when that branch merges later.
+4. Log the incident for a post-mortem (Phase 5 retro).

package/templates/docs/en/COMMUNICATION_PROTOCOL.md

@@ -0,0 +1,59 @@
+# Communication Protocol — Human ↔ AI
+
+> The communication contract between the **human** (Product Owner / Dev) and the **AI agents** on this project. Applies to **every interaction**, especially when **clarifying requirements** (Phase 1). A mandatory part of [AGENCY_WORKFLOW.md](./AGENCY_WORKFLOW.md).
+>
+> Because this product *is* an AI assistant, the quality of requirements clarification drives the quality of the product — this protocol exists to eliminate silent misunderstandings.
+
+## 1. Language & style
+- The team's working language is the default when talking to the user; **keep technical terms in English** (API, endpoint, prompt, token…).
+- Concise and direct, no rambling. Present important options with a clear recommendation.
+- Cite `file:line` when discussing code.
+
+## 2. Core principles
+1. **No silent assumptions** — Never fabricate missing information. When something is missing, either **ASK**, or state an **explicit assumption** labeled `ASSUMPTION:` so the user can easily reject it.
+2. **Layered certainty** — Clearly separate:
+   - ✅ **Certain** (read the code/docs, have evidence)
+   - 🤔 **Inferred** (reasonable inference, not verified)
+   - ❓ **Needs confirmation** (depends on a user decision)
+3. **Truth over agreement** — The AI pushes back when a request is contradictory/risky; it doesn't just agree to be agreeable. (The reverse direction: when receiving feedback, use the `receiving-code-review` skill — verify technically, no performative agreement.)
+4. **Evidence before assertions** — Never declare "done/passing" without running a verification command (see `verification-before-completion`).
+
+## 3. Requirements clarification protocol
+### 3.1. Question classification
+| Type | Definition | Handling |
+|------|-----------|----------|
+| **Blocking** | Without an answer you CANNOT proceed correctly (e.g. scope, audience, hard constraints) | Must ask & wait for the user |
+| **Non-blocking** | Has a reasonable default | The AI **decides via the default**, stating the `ASSUMPTION:` used so the user can adjust later |
+
+> Goal: don't block progress on things that have a reasonable default; only block on what genuinely needs a human decision.
+
+### 3.2. How to ask
+- **Independent questions** → batch them via **`AskUserQuestion`** (up to ~4, each with options + a recommendation).
+- **Exploratory / dependent questions** → ask **sequentially, one at a time** (per the `brainstorming` skill) so later questions build on earlier ones.
+- Prefer multiple-choice over open-ended when possible.
+
+### 3.3. End every clarification round
+Each round closes with 3 items:
+1. **Summary of current understanding** (a short paragraph — for the user to spot mistakes).
+2. **Open questions** (which blocking ones are unanswered).
+3. **Assumptions in effect** (the assumptions register — the list of `ASSUMPTION:`s currently in use).
+
+## 4. Confirmation, sign-off & repairing misunderstandings
+- **Gate = real Plan Mode**: lock the PRD/TDD via `EnterPlanMode → ExitPlanMode`, not a prose "awaiting approval".
+- **Loop repair on misunderstanding**: when the user corrects something → the AI **restates the NEW understanding in its own words** and **waits for confirmation** before continuing. No silent "re-understanding".
+- Once the user approves, treat it as a **commitment** — to change it, reopen the gate, don't silently change direction.
+
+## 5. Decision log & Assumptions register
+Recorded per feature in the PRD (see template):
+- **Decision Log**: `| Date | Question/Issue | Decision | Decided by | Rationale |` — so later you know "why we chose that back then".
+- **Assumptions Register**: the list of assumptions in effect + status (`pending` / `confirmed` / `rejected`).
+
+## 6. Rules for sub-agents (multi-agent)
+- **Sub-agents do NOT talk to the user directly.** If information is missing / a human decision is needed → **report to the Main Agent**, which aggregates and then asks the user. Avoids multiple agents asking conflicting questions.
+- The Main Agent is the **single point of contact** with the user.
+- Prompts handed to sub-agents must be **self-contained** (see [TEAM_ROSTER.md](./TEAM_ROSTER.md)) — including the relevant assumptions/decisions already settled with the user.
+
+## 7. Related
+- [AGENCY_WORKFLOW.md](./AGENCY_WORKFLOW.md) — Phase 1 applies this protocol.
+- [templates/PRD_AI_FEATURE.md](./templates/PRD_AI_FEATURE.md) — dimensions to clarify for AI features.
+- [INTERACTION_PATTERNS.md](./INTERACTION_PATTERNS.md) — how the *product* talks to end-users (distinct from this doc: this is human↔AI during development).

package/templates/docs/en/DEFINITION_OF_DONE.md

@@ -0,0 +1,60 @@
+# Definition of Done (DoD)
+
+> **Measurable** completion criteria. A change is "done" only when it meets the DoD for its path. The path is decided by [AGENCY_WORKFLOW.md §1](./AGENCY_WORKFLOW.md#1-task-classification--workflow-router).
+
+## ⚙️ Placeholders to fill when the tech stack is chosen
+Stack not decided yet — fill these in the first PRD/TDD, then update this file:
+
+| Variable | Value | Example |
+|----------|-------|---------|
+| `<TEST_CMD>` | test command | `npm test` / `pytest` |
+| `<LINT_CMD>` | lint + format check | `npm run lint` / `ruff check .` |
+| `<BUILD_CMD>` | build command | `npm run build` / `—` |
+| `<COVERAGE_MIN>` | minimum coverage threshold | `80%` |
+| `<TYPECHECK_CMD>` | type check (if any) | `tsc --noEmit` / `mypy .` |
+
+---
+
+## Checklist by path
+
+### Read-only (Q&A / Explain)
+- [ ] Answers the core of the question.
+- [ ] Cites `file:line` for every claim about code.
+- [ ] No branch / no commit / no file edits.
+
+### Fast path (Chore / Docs / Config / Small bugfix / Hotfix)
+- [ ] Correct branch prefix ([BRANCHING.md](./BRANCHING.md)).
+- [ ] `<TEST_CMD>` green · `<LINT_CMD>` green · `<BUILD_CMD>` green.
+- [ ] **Bugfix/Hotfix:** a test reproducing the bug went RED → GREEN; regression suite still passes.
+- [ ] **Chore/Docs:** no runtime behavior change.
+- [ ] Conventional Commits; MR briefly describes *what + why*.
+- [ ] Ran `gitnexus_detect_changes` (when code exists) — scope as expected.
+- [ ] **Security (light):** no new secret committed (see [SECURITY_STANDARDS.md](./SECURITY_STANDARDS.md) §5). **Performance (light):** no obvious regression / no new N+1 ([PERFORMANCE_STANDARDS.md](./PERFORMANCE_STANDARDS.md) §4).
+
+### Standard path (Change logic / Refactor)
+Includes all of Fast path, plus:
+- [ ] Passed the **Gate** (Plan Mode) and the user approved the approach.
+- [ ] `gitnexus_impact` (upstream) ran & **blast radius + risk level reported**; HIGH/CRITICAL risk accepted by the user.
+- [ ] `<TYPECHECK_CMD>` green (if applicable).
+- [ ] **Refactor:** the same test suite passes before & after (behavior unchanged); renames use `gitnexus_rename`, not manual find-replace.
+- [ ] **Change logic:** old regression tests still green + new tests for new behavior.
+- [ ] QA sub-agent reviewed (`code-review`); `security-review` if touching a sensitive surface.
+- [ ] **Security (Standard):** input validation for touched code + authz checks if touched ([SECURITY_STANDARDS.md](./SECURITY_STANDARDS.md) §5). **Performance (Standard):** before/after bench for hot paths; (AI) prompt caching preserved ([PERFORMANCE_STANDARDS.md](./PERFORMANCE_STANDARDS.md) §4).
+
+### Full path (New feature)
+Includes all of Standard path, plus:
+- [ ] **PRD** approved (Gate 1) and linked in ACTIVE_STATE.
+- [ ] **TDD** approved (Gate 2): includes a light threat model + API/interface contract.
+- [ ] Coverage ≥ `<COVERAGE_MIN>` for new code.
+- [ ] Meets all acceptance criteria in the PRD.
+- [ ] `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.
+
+---
+
+## Invariants (all paths)
+1. **Never claim "done/passing" without running a verification command** — evidence before assertions (`verification-before-completion`).
+2. **Tests must actually test behavior**, not empty/fully-mocked tests just to pass.
+3. **ACTIVE_STATE.md is updated** when work status changes.

package/templates/docs/en/INTERACTION_PATTERNS.md

@@ -0,0 +1,58 @@
+# Interaction Patterns — Assistant ↔ End-User (Product Layer)
+
+> A library of **patterns for how the PRODUCT talks to end-users**. Distinct from [COMMUNICATION_PROTOCOL.md](./COMMUNICATION_PROTOCOL.md) (human↔AI during *development*) — this is how the *built assistant* talks to *end-users*.
+>
+> A **reusable asset**: each AI-feature PRD (§3, §5, §8 of the [template](./templates/PRD_AI_FEATURE.md)) references these patterns instead of redesigning from scratch. Specific thresholds/details (`<TBD>`) are locked per PRD.
+
+## Foundational principles
+1. **The user stays in control** — the assistant assists; it doesn't unilaterally make hard-to-reverse decisions for the user.
+2. **Be transparent about limits** — say clearly when unsure, when it doesn't know, or when it can't do something; never fabricate.
+3. **Error cost shapes behavior** — low-risk actions → just do them; high-risk/hard-to-reverse → confirm first.
+
+---
+
+## P1 — Clarification (clarifying intent)
+- **When to ask back:** ambiguous intent, missing required parameters, or multiple interpretations leading to very different results.
+- **When NOT to ask:** there's a safe/clear default → just do it and **state the assumption** ("I understood it as X, let me know if that's wrong").
+- **How to ask:** one focused question, with 2–4 options if possible; don't torture the user with a chain of questions.
+- **Threshold:** at most `<TBD>` questions before giving a best-effort attempt.
+
+## P2 — Confirmation (confirm before acting)
+- **Confirmation required** before actions that are: hard to reverse, affect data/money/other people, or go outward (send email, publish…).
+- **Not needed** for read-only/non-destructive actions.
+- State **what's about to happen + the consequence**, then ask for consent.
+
+## P3 — Uncertainty / Low-confidence
+- When unsure → **state the confidence level** + offer to verify, instead of asserting confidently.
+- Cite sources/grounding when available. Distinguish "I know" vs "I'm inferring".
+
+## P4 — Error & Graceful Degradation
+- On error → explain **in the user's language** (don't swallow the error, don't dump a stack trace).
+- Prefer **a partial result + naming what's missing** over a blank failure.
+- Suggest the next step / how to retry.
+
+## P5 — Refusal (safe refusal)
+- Structure: **a concise refusal + reason + (if any) a valid alternative**.
+- Keep a respectful, non-judgmental tone; don't reveal internal filtering details.
+- Distinguish "not allowed" vs "can't do it" vs "needs more info".
+
+## P6 — Handoff to Human
+- When to escalate: out of scope, high risk, the user requests it, or repeated failure.
+- Hand off with a **context summary** so the receiving human doesn't have to ask from scratch.
+
+## P7 — Conversation Repair
+- The user says "that's not it" → the assistant **briefly acknowledges, restates the new understanding, confirms**, then continues.
+- Don't repeat the same wrong answer; don't get defensive.
+
+## P8 — Memory & Privacy
+- Be clear about **what the assistant remembers / doesn't**; give the user a way to view/delete it.
+- Don't expose sensitive data in responses/logs; follow the PRD §5 PII policy.
+
+## P9 — Tone & Consistency
+- One consistent persona across features (locked in [TEAM_ROSTER.md](./TEAM_ROSTER.md) §3 / PRD §4).
+- Concise by default; detailed when the user needs it.
+
+---
+
+## How to use
+In an AI-feature PRD: §3 (ambiguity) points to **P1**; §5 (safety) points to **P5/P8**; §8 (fallback) points to **P4/P6/P7**; §4 (tone) points to **P9**. Each pattern gets the specific threshold/details for that feature.

package/templates/docs/en/PERFORMANCE_STANDARDS.md

@@ -0,0 +1,31 @@
+# Performance Standards
+
+> A **measurable** performance budget for {{PROJECT_NAME}}. Part of [DEFINITION_OF_DONE.md](./DEFINITION_OF_DONE.md), considered at **Phase 2 (set the budget)** + **Phase 4 (verify)** in [AGENCY_WORKFLOW.md](./AGENCY_WORKFLOW.md).
+>
+> Fill the `<TBD>`s per product requirements when locked in the first PRD/TDD.
+
+## 1. General budget (parameterized)
+- **Latency**: API p95 ≤ `<TBD>` ms, p99 ≤ `<TBD>` ms.
+- **Throughput**: ≥ `<TBD>` req/s at target load.
+- **Size**: payload/response ≤ `<TBD>`; frontend bundle (if any) ≤ `<TBD>` KB.
+- **Database**: no N+1; queries per request ≤ `<TBD>`; indexes for hot queries.
+- **Memory/CPU**: no leaks; baseline ≤ `<TBD>`.
+
+## 2. AI-specific (required for AI features)
+> Cross-reference `templates/PRD_AI_FEATURE.md §9`.
+- **Prompt caching — REQUIRED**: leverage Claude's caching for static prompt parts (system, grounding docs) to cut cost & latency. This is the biggest lever.
+- **Model selection by task**: use the lightest sufficient model (Haiku → Sonnet → Opus); don't default to the strongest model for everything.
+- **Token/cost ceiling**: a per-request token & cost ceiling `<TBD>`; alert on breach.
+- **Streaming**: stream long responses to reduce perceived latency.
+- **Context discipline**: load only the needed context; avoid stuffing whole documents into every turn.
+- **Batching**: batch large non-realtime workloads.
+
+## 3. Performance regression gate
+- **`change/` + `refactor/` touching a hot path**: measure a **before & after bench**, don't regress more than `<TBD>`%.
+- **Feature** (Full path): at least one load measurement/assessment for the critical flow before merge.
+- **Observability**: track p95/p99, token/cost, error rate after going to prod (see PRD §10).
+
+## 4. Checklist by path (feeds the DoD)
+- **Fast path**: no obvious performance regression; no new N+1.
+- **Standard path**: + before/after bench for code touching a hot path; + (AI) prompt caching preserved/applied.
+- **Full path**: + meets the §1 budget; + (AI feature) meets the §2 token/latency ceiling; + a load measurement exists for the main flow.

package/templates/docs/en/SECURITY_STANDARDS.md

@@ -0,0 +1,37 @@
+# Security Standards
+
+> A **measurable** security baseline for {{PROJECT_NAME}}. It is the bar `security-review` (Phase 4) grades against and part of [DEFINITION_OF_DONE.md](./DEFINITION_OF_DONE.md). Shift-left: most of it is considered during **threat modeling in Phase 2** ([AGENCY_WORKFLOW.md](./AGENCY_WORKFLOW.md)).
+>
+> Fill the `<TBD>`s per your stack/compliance when locked in the first PRD/TDD.
+
+## 1. General baseline (every project)
+- **Secrets**: NEVER hardcode secrets/keys/API tokens in code or logs. Use env vars / a secret manager. `.env` must be in `.gitignore`. Enable secret-scanning (§4).
+- **Dependency & supply-chain**: pin versions (lockfile); run `<AUDIT_CMD>` (e.g. `npm audit` / `pip-audit`); enable auto-updates (Dependabot/Renovate); only add dependencies from trusted sources.
+- **Input validation & output encoding**: validate all external input (user, API, file); encode output by context (prevent XSS/SQLi/command injection). Use parameterized queries, no string concatenation.
+- **AuthN/AuthZ**: explicit authentication; **least privilege** for every role/key/resource; check permissions server-side, never trust the client.
+- **Transport & data at rest**: TLS for all traffic; encrypt sensitive data at rest where needed.
+- **Logging**: log enough to investigate but **never leak secrets/PII**; don't print stack traces/internals to end-users.
+- **Error handling**: user-facing errors don't reveal system details (paths, versions, queries…).
+
+## 2. AI-specific — OWASP LLM Top 10 (required for AI features)
+> Cross-reference `templates/PRD_AI_FEATURE.md §5`.
+- **Prompt injection**: separate the **system prompt** from **untrusted content** (user input, fetched data, tool output). Do NOT blindly execute/follow instructions embedded in untrusted data.
+- **Sensitive information disclosure**: don't let the model leak secrets/PII/other customers' data; filter output; minimize data put into context.
+- **Excessive agency**: restrict **tool/agent permissions** (grant only the tools truly needed); hard-to-reverse actions require confirmation/human-in-the-loop (see [INTERACTION_PATTERNS.md](./INTERACTION_PATTERNS.md) P2/P6).
+- **Insecure output handling**: treat model output as **untrusted data** — validate/sanitize before rendering HTML, executing code, or passing it downstream.
+- **Guardrails & refusal**: a policy for refusing forbidden content (PRD §5); resist abuse/jailbreaks.
+- **Model/plugin supply chain**: only use models/MCP/plugins from trusted sources; record versions.
+
+## 3. Process security (partly enforced by hooks)
+- `main` is protected; changes land via MR ([BRANCHING.md](./BRANCHING.md)). The `git-guard` hook blocks force-push, `commit --no-verify`, `reset --hard`.
+- Don't bypass hooks/CI "to go faster".
+
+## 4. Automated tools (optional — degrade if absent)
+- **Secret scanning**: e.g. `gitleaks` (can run as a pre-commit hook to **block**). `<TBD: on/off>`
+- **`<AUDIT_CMD>`** in CI / the `doctor` command.
+- **SAST** (stack-dependent): `<TBD>`.
+
+## 5. Checklist by path (feeds the DoD)
+- **Fast path**: no new secret committed; `<AUDIT_CMD>` reports no new critical issues.
+- **Standard path**: + input validation for touched code; + permission checks if touching authz.
+- **Full path**: + the threat model (Phase 2) is addressed; + `security-review` passes; + (AI feature) all of §2 verified, including abuse cases.

package/templates/docs/en/TEAM_ROSTER.md

@@ -0,0 +1,35 @@
+# Team Roster & Agent Personas
+
+> Personas are **thinking lenses**, not mandatory ceremony for every task. The process & paths: see [AGENCY_WORKFLOW.md](./AGENCY_WORKFLOW.md) (SSOT).
+
+## 1. Main Agent (Lead)
+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.
+
+## 2. Sub-agents (Dev / QA)
+Spawned via the `Agent` tool when the work is large enough (Standard/Full path).
+
+> ⚠️ **Sub-agents do NOT inherit the Main Agent's conversation, skills, or context.** So **every spawn prompt must be SELF-CONTAINED**, including:
+> 1. Links to the specific **PRD/TDD** files to read.
+> 2. Persona + **the skill names to invoke** (be explicit, e.g. "use the `test-driven-development` skill").
+> 3. **Done criteria** (point to the matching path in [DEFINITION_OF_DONE.md](./DEFINITION_OF_DONE.md)).
+> 4. The list of relevant files/areas + constraints (API contract).
+
+| Role | Skills/Tools | Job |
+|------|--------------|-----|
+| **Frontend Dev** | the locked design direction (see §3), test-driven-development | Implement the UI per the TDD, follow the design system |
+| **Backend Dev** | test-driven-development | Logic / API / DB schema, safe & efficient |
+| **Code Reviewer** (`code-reviewer`) | code-review, simplify | Review diffs: correctness, security, cleanliness |
+| **QA / Security** | security-review, systematic-debugging, verification-before-completion, verify | Break the code, find bugs, ensure execution flows are intact |
+
+## 3. Design direction — PICK ONE
+There are many design skills (`design-taste-frontend`, `minimalist-ui`, `industrial-brutalist-ui`, `high-end-visual-design`, `gpt-taste`, `brandkit`…). **Pick exactly ONE direction for {{PROJECT_NAME}}** (decided in the first PRD/TDD), define tokens/type scale/spacing once, then Frontend follows it.
+- Chosen design direction: **`<TBD — fill when the first UI feature appears>`**
+- Do NOT invoke multiple design skills at once within one feature → avoids inconsistent UI.
+
+## 4. Delegation rules
+1. **Don't write the bulk of the code in the main thread** if the work is large → delegate to sub-agents.
+2. **Conditional parallelization**: only spawn FE & BE in parallel **after the API contract is locked in Phase 2**.
+3. **Worktrees**: use `isolation: "worktree"` when multiple agents may edit overlapping files.

package/templates/docs/en/templates/PRD_AI_FEATURE.md

@@ -0,0 +1,85 @@
+# PRD — <AI feature name>
+
+> A PRD template **specifically for AI/assistant features**. Purpose: force the dimensions that deterministic software usually misses. Fill everything in; for unknowns write `ASSUMPTION:` or `<TBD>` (don't leave silent blanks). Follow [COMMUNICATION_PROTOCOL.md](../COMMUNICATION_PROTOCOL.md).
+>
+> Copy this file to `docs/specs/YYYY-MM-DD-<feature>.md` when starting Phase 1.
+
+**Status:** Draft | In Review | Approved
+**Date:** YYYY-MM-DD · **Product Owner:** · **Path (router):** Full / Standard
+
+---
+
+## 1. Context & goals
+- **User problem:** <what pain does this feature solve?>
+- **Measurable goal:** <e.g. reduce X% time, reach Y% correct answers>
+- **Persona / audience:**
+
+## 2. Assistant Intent & Scope  ⭐
+- **DOES (in-scope):** <what the assistant must be able to do>
+- **DOES NOT (explicitly out-of-scope):** <boundaries — crucial against scope creep & unintended behavior>
+- **Primary use cases (prioritized):**
+
+## 3. Behavior under AMBIGUITY / missing info  ⭐
+> A core decision for an assistant. Reference [INTERACTION_PATTERNS.md](../INTERACTION_PATTERNS.md).
+- When user intent is unclear → does the assistant **ask back / guess-then-state / refuse**? <pick & justify>
+- **Confidence threshold** to act vs ask back: `<TBD>`
+- Max questions before it must act: `<TBD>`
+
+## 4. Tone & Persona
+- Voice (formal/friendly/concise…):
+- Things the assistant must **never** say/do stylistically:
+- Supported languages:
+
+## 5. Guardrails & Safety  ⭐
+> Follow [SECURITY_STANDARDS.md](../SECURITY_STANDARDS.md) — especially §2 (OWASP LLM Top 10).
+- **Refusal policy:** which requests must be refused + how (see the Refusal pattern in INTERACTION_PATTERNS).
+- **Sensitive data / PII:** what's collected, what's stored, how it's masked, which regulations.
+- **Prompt injection / abuse:** defenses (separate system/user content, check output…).
+- **Forbidden / restricted content:**
+
+## 6. Definition of "CORRECT" (output is non-deterministic)  ⭐
+> You can't use a single `assertEquals` for AI output. You must define *what good looks like*.
+- **Evaluation rubric** (criteria + scale): e.g. factual / on-spec / safe / tone.
+- **Golden examples** (input → expected behavior/output): ≥ 5–10 representative ones, including hard/edge cases.
+  | Input | Expected behavior/output | Why |
+  |-------|--------------------------|-----|
+  | | | |
+
+## 7. Eval strategy  ⭐
+- **Automated eval set** run on the golden set (scored by the §6 rubric) — this is the AI feature's "tests".
+- **Prompt regression:** when changing prompt/model → re-run the eval, compare before/after scores.
+- Pass threshold: `<TBD>` (e.g. average rubric score ≥ X, no safety case failing).
+- Relation to DoD: add to [DEFINITION_OF_DONE.md](../DEFINITION_OF_DONE.md) for AI features.
+
+## 8. Fallback & Human-in-the-loop  ⭐
+- When the model **fails / times out / is low-confidence** → what does the assistant do? (apologize + suggest / return partial / hand off to a human).
+- **Human checkpoints (HITL):** which actions need human approval before execution?
+- Behavior when a dependent tool/API fails.
+
+## 9. Model, cost & performance
+> Follow [PERFORMANCE_STANDARDS.md](../PERFORMANCE_STANDARDS.md) §2 (AI-specific).
+- Model used (e.g. Claude Opus/Sonnet/Haiku) + rationale; **prompt caching REQUIRED** for static prompt parts.
+- Token budget / target cost per request (ceiling).
+- Target latency (p95).
+
+## 10. Observability
+- What to log (with PII redacted), how to assess quality *after* going to prod (collect feedback, sample review).
+- Metrics to track (refusal rate, confidence, satisfaction…).
+
+## 11. Acceptance Criteria
+- [ ] <criterion 1 — measurable>
+- [ ] Eval meets the §7 threshold
+- [ ] §5 guardrails tested (including abuse cases)
+
+## 12. API / Interface contract (for parallelization)
+> Must be locked before spawning FE & BE in parallel (see AGENCY_WORKFLOW Phase 2/3).
+
+## 13. Decision Log
+| Date | Question/Issue | Decision | Decided by | Rationale |
+|------|----------------|----------|------------|-----------|
+| | | | | |
+
+## 14. Assumptions Register
+| Assumption | Status (pending/confirmed/rejected) |
+|------------|-------------------------------------|
+| | |

package/templates/docs/vi/ACTIVE_STATE.md

@@ -0,0 +1,28 @@
+# Project Active State
+
+**Last Updated:** {{DATE}}
+**Current Global Phase:** 0 — Initialization & Setup
+
+> 📌 **Bảng "Active Features" dưới đây LÀ backlog bền vững xuyên session.** Đây là nguồn trạng thái chính khi resume.
+> `TaskCreate`/`TaskList` chỉ sống **trong session hiện tại** (in-memory, mất khi đóng session) — chỉ dùng để theo dõi việc đang làm, KHÔNG dùng làm backlog dài hạn. Mỗi khi trạng thái một feature đổi → cập nhật bảng này và (nếu có) GitLab MR/issue tương ứng.
+
+## Active Features in Pipeline
+
+| Feature / Epic | Path | Phase hiện tại | Branch / MR | Status | PRD | TDD |
+| :--- | :--- | :--- | :--- | :--- | :--- | :--- |
+| N/A | N/A | N/A | - | Idle | - | - |
+
+## Blockers / Pending Actions
+- Chờ Product Owner đề xuất feature/ý tưởng đầu tiên.
+- Chốt tech stack → điền placeholder trong [DEFINITION_OF_DONE.md](./DEFINITION_OF_DONE.md).
+- Chốt design direction → cập nhật [TEAM_ROSTER.md](./TEAM_ROSTER.md) §3.
+
+## 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.
+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.
+   - **Standard/Full ở Phase 1–2**: tiếp tục brainstorming/planning với User (qua Plan Mode gate).
+   - **Standard/Full ở Phase 3–4**: mở PRD/TDD đã link, kiểm tra trạng thái code & branch, tái tạo task bằng `TaskCreate` cho session này, hỏi User trước khi resume code/test.
+4. Cập nhật lại bảng này khi bắt đầu làm.

package/templates/docs/vi/AGENCY_WORKFLOW.md

@@ -0,0 +1,126 @@
+# 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.
+
+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).
+
+Persona (BA / Architect / Developer / QA / Scrum Master) là **lăng kính tư duy**, không phải nghi thức bắt buộc cho mọi việc — chi tiết ở [TEAM_ROSTER.md](./TEAM_ROSTER.md).
+
+---
+
+## 0. Quy tắc vàng
+
+1. **Bắt đầu mọi yêu cầu bằng việc PHÂN LOẠI task** (bảng §1) → chọn đúng *path*. Đừng mặc định chạy full 5-phase cho mọi việc.
+2. **Không lao vào code khi yêu cầu chưa rõ.** Với Standard/Full path, làm rõ scope trước.
+3. **Gate = Plan Mode thật, không phải lời hứa.** Khi một path yêu cầu "Gate", dùng `EnterPlanMode` → trình kế hoạch → `ExitPlanMode` để User duyệt. Đây là cơ chế chặn được harness enforce, thay cho câu chữ "chờ sign-off".
+4. **Cập nhật [ACTIVE_STATE.md](./ACTIVE_STATE.md)** khi bắt đầu / kết thúc một đơn vị công việc. Đây là backlog bền vững xuyên session (TaskCreate chỉ sống trong session hiện tại).
+5. **Tuân [COMMUNICATION_PROTOCOL.md](./COMMUNICATION_PROTOCOL.md) trong mọi tương tác** — đặc biệt khi làm rõ yêu cầu: no silent assumptions, phân tầng độ chắc chắn, phân loại câu hỏi blocking/non-blocking, đóng vòng khi hiểu sai.
+
+---
+
+## 1. Bảng phân loại task → workflow (ROUTER)
+
+Khi nhận yêu cầu, tra bảng này trước để chọn path, branch, bước bắt buộc và DoD.
+
+| # | Loại task | Trigger / ví dụ | Path | Gate | Branch | Bước bắt buộc | Skills / Tools | DoD rút gọn |
+|---|---|---|---|---|---|---|---|---|
+| 1 | **Q&A / Explain / Find code** | "Giải thích X", "tìm chỗ xử lý Y", "code này làm gì" | Read-only | Không | — | Trả lời trực tiếp, **không sửa file** | `gitnexus_query`, `gitnexus_context`, serena `find_symbol` | Trả lời đúng + trích `file:line`; không tạo branch/commit |
+| 2 | **Chore / Docs / Config** | sửa README, đổi config, bump version, format | Fast | Không | `chore/` `docs/` | sửa → MR | — | build/lint xanh; không đổi hành vi runtime |
+| 3 | **Bugfix nhỏ (khu trú)** | lỗi rõ nguyên nhân, ≤ ~2 file, không phải symbol dùng chung | Fast | Không (nhưng **bắt buộc repro test**) | `fix/` | `systematic-debugging` → viết test ĐỎ tái hiện bug → fix → test XANH → MR | systematic-debugging, test-driven-development, verification-before-completion | test tái hiện bug (đỏ→xanh); regression xanh; root cause ghi trong MR |
+| 4 | **Hotfix (prod khẩn cấp)** | sự cố production cần vá gấp | Fast (expedited) | Không | `hotfix/` (off `main`) | fix tối thiểu + test → MR nhanh → backport về nhánh phát triển | systematic-debugging, verify | vá sự cố + test; đã backport; ghi lại để hậu kiểm |
+| 5 | **Sửa / đổi logic tính năng đã có** | "đổi cách tính X", "thêm điều kiện cho Y", "đổi hành vi Z" | Standard | **CÓ** | `change/` | **impact analysis BẮT BUỘC** → đảm bảo/ bổ sung regression test → impl → QA review | `gitnexus_impact` (upstream), test-driven-development, code-review | impact đã báo cáo; regression + test mới xanh; `detect_changes` đúng phạm vi |
+| 6 | **Refactor (KHÔNG đổi hành vi)** | "tách module", "đổi tên", "dọn code" | Standard | **CÓ** | `refactor/` | test XANH trước → impact analysis → đổi (dùng `gitnexus_rename`) → test XANH sau (không đổi) | gitnexus_rename, gitnexus_impact, simplify | cùng bộ test pass trước & sau; KHÔNG find-replace thủ công |
+| 7 | **Feature mới** | "xây tính năng Z" | Full (5-phase) | **CÓ (2 gate: PRD + TDD)** | `feat/` | §3 đầy đủ | brainstorming, writing-plans, test-driven-development, design system, code-review, security-review | đủ [DEFINITION_OF_DONE.md](./DEFINITION_OF_DONE.md) |
+| 8 | **Spike / Research / POC** | "nghiên cứu khả thi", "thử nghiệm cách tiếp cận" | Timeboxed | Không (timebox thay gate) | `spike/` (vứt đi) | timebox rõ ràng → output **doc khuyến nghị**; **KHÔNG merge code POC** vào main | deep-research, gitnexus_exploring | có doc kết luận + khuyến nghị; code POC không vào main |
+
+### Escalation rule (nâng cấp path)
+Một task đang ở **Fast path** mà phát hiện:
+- chạm symbol có nhiều caller / `gitnexus_impact` trả về **MEDIUM trở lên**, HOẶC
+- thay đổi lan ra **> 5 file**,
+
+→ **dừng lại, nâng lên Standard path**: mở Plan Mode (gate), chạy & báo cáo impact analysis trước khi tiếp tục.
+
+---
+
+## 2. Bốn path (định nghĩa)
+
+### Read-only
+Trả lời câu hỏi, đọc/giải thích code. Không branch, không gate, không commit. Ưu tiên `gitnexus_query`/`gitnexus_context` thay vì grep mù. Luôn trích dẫn `file:line`.
+
+### Fast path
+Cho việc nhỏ, rủi ro thấp (chore/docs/bugfix khu trú/hotfix).
+1. Tạo branch đúng tiền tố (xem [BRANCHING.md](./BRANCHING.md)).
+2. Thực hiện thay đổi. Nếu là **bugfix**: viết test tái hiện bug (đỏ) TRƯỚC khi sửa.
+3. Self-review nhanh (`code-review` nếu muốn) + chạy test/lint.
+4. Mở MR theo DoD "Fast" trong [DEFINITION_OF_DONE.md](./DEFINITION_OF_DONE.md).
+> Không cần Plan sign-off. Nhưng nếu chạm trúng escalation rule → nâng lên Standard.
+
+### Standard path
+Cho thay đổi logic tính năng đã có & refactor.
+1. **Gate**: `EnterPlanMode` → khảo sát + chạy `gitnexus_impact` (upstream) → trình kế hoạch nêu **blast radius + mức rủi ro** → `ExitPlanMode` chờ User duyệt.
+2. Cảnh báo User nếu rủi ro **HIGH/CRITICAL** trước khi tiếp tục.
+3. Implement theo TDD; refactor thì giữ test không đổi.
+4. QA: spawn sub-agent review (`code-review` + `security-review` nếu chạm bề mặt nhạy cảm) + `gitnexus_detect_changes`.
+5. MR theo DoD "Standard".
+
+### Full path (5-phase) — chỉ cho Feature mới
+Xem §3.
+
+---
+
+## 3. Full path: 5 phase cho Feature mới
+
+> Chỉ áp dụng cho task loại **#7 (Feature)**. Việc nhỏ KHÔNG chạy phase này.
+
+### Phase 1 — Discovery & Scoping (lăng kính: Business Analyst)
+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.
+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)
+1. `gitnexus_exploring` để hiểu kiến trúc hiện tại (bỏ qua nếu vùng liên quan còn trống).
+2. `gitnexus_impact` cho mọi sửa đổi lên code đã có.
+3. **Threat modeling nhẹ (shift-left):** liệt kê bề mặt tấn công / dữ liệu nhạy cảm / quyền hạn ngay tại đây theo [SECURITY_STANDARDS.md](./SECURITY_STANDARDS.md) — đừng để dồn hết về QA.
+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.
+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)
+1. Cập nhật task `in_progress` (`TaskUpdate`) + ACTIVE_STATE.
+2. Việc lớn → **delegate cho sub-agent** qua `Agent` tool. **Prompt sub-agent phải self-contained** (sub-agent KHÔNG tự kế thừa hội thoại/skill): nhúng link PRD/TDD, nêu rõ skill cần invoke, tiêu chí Done, file liên quan. Chi tiết: [TEAM_ROSTER.md](./TEAM_ROSTER.md).
+3. **Parallelize CÓ ĐIỀU KIỆN:** chỉ spawn FE & BE song song **sau khi API contract (Phase 2.5) đã chốt**. Khi nhiều agent sửa file chồng nhau → `isolation: "worktree"`.
+4. Developer áp dụng `test-driven-development`.
+5. Frontend bám **một** design direction đã chốt (không gọi nhiều design skill cùng lúc — xem TEAM_ROSTER §design).
+
+### Phase 4 — Quality Assurance (lăng kính: QA, sub-agent)
+1. Spawn Code Reviewer / QA sub-agent (prompt self-contained).
+2. QA chạy `verification-before-completion`, `security-review`, `systematic-debugging` khi cần. Đối chiếu [SECURITY_STANDARDS.md](./SECURITY_STANDARDS.md) + [PERFORMANCE_STANDARDS.md](./PERFORMANCE_STANDARDS.md) (gồm OWASP LLM Top 10 cho feature AI, và budget hiệu năng).
+3. `gitnexus_detect_changes` để xác nhận không vỡ execution flow ngoài dự kiến.
+4. Phải đạt [DEFINITION_OF_DONE.md](./DEFINITION_OF_DONE.md) (mức Full) trước khi merge.
+
+### 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).
+5. Đánh dấu task `completed` + cập nhật ACTIVE_STATE.
+
+---
+
+## 4. Tài liệu liên quan
+| File | Nội dung |
+|------|----------|
+| [TASK router §1](#1-bảng-phân-loại-task--workflow-router) | Chọn path theo loại task |
+| [DEFINITION_OF_DONE.md](./DEFINITION_OF_DONE.md) | Tiêu chí hoàn thành đo được (theo path) |
+| [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 |
+| [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 |
+| [SECURITY_STANDARDS.md](./SECURITY_STANDARDS.md) | Baseline bảo mật + OWASP LLM Top 10 |
+| [PERFORMANCE_STANDARDS.md](./PERFORMANCE_STANDARDS.md) | Budget hiệu năng + chuẩn AI (prompt caching…) |

package/templates/docs/vi/BRANCHING.md

@@ -0,0 +1,44 @@
+# Branching & Commit Convention
+
+> Mô hình: **GitLab flow** cho nhóm nhỏ 2–5 người. `main` luôn ở trạng thái deploy được.
+
+## Nhánh
+- **`main`** — protected. KHÔNG commit/push trực tiếp. Mọi thay đổi vào qua **Merge Request (MR)**.
+- Nhánh làm việc ngắn hạn, tạo từ `main`, đặt tên `<type>/<mô-tả-ngắn-kebab>`:
+
+| Tiền tố | Dùng cho | Loại task (router) |
+|---------|----------|--------------------|
+| `feat/` | tính năng mới | #7 |
+| `fix/` | sửa bug | #3 |
+| `change/` | đổi logic tính năng đã có | #5 |
+| `refactor/` | dọn code, không đổi hành vi | #6 |
+| `chore/` | build, deps, config | #2 |
+| `docs/` | chỉ tài liệu | #2 |
+| `hotfix/` | vá khẩn cấp prod (off `main`) | #4 |
+| `spike/` | nghiên cứu/POC (vứt đi, không merge code) | #8 |
+
+Ví dụ: `feat/user-login`, `fix/null-cart-total`, `change/discount-rounding`.
+
+## Merge Request
+- **Bắt buộc ≥ 1 reviewer** duyệt trước khi merge.
+- Phải thỏa [DEFINITION_OF_DONE.md](./DEFINITION_OF_DONE.md) của path tương ứng (CI xanh).
+- **Squash merge** vào `main` để giữ lịch sử sạch (1 nhánh = 1 commit ý nghĩa).
+- Xóa nhánh sau khi merge.
+- Mô tả MR nêu rõ **what + why**, link PRD/TDD nếu là Standard/Full.
+
+## Commit — Conventional Commits
+Định dạng: `<type>(<scope>): <mô tả>` — type khớp tiền tố nhánh: `feat` `fix` `refactor` `chore` `docs` `test` `perf`.
+
+```
+feat(auth): thêm đăng nhập bằng email
+fix(cart): xử lý total null khi giỏ rỗng
+```
+
+- BREAKING CHANGE: thêm `!` sau type (`feat!:`) hoặc footer `BREAKING CHANGE:`.
+- KHÔNG dùng `--no-verify` / `--no-gpg-sign` trừ khi User yêu cầu rõ (hook sẽ chặn).
+
+## Hotfix & backport
+1. Tạo `hotfix/<...>` từ `main`.
+2. Vá tối thiểu + test tái hiện → MR nhanh (vẫn cần review) → merge vào `main`.
+3. **Backport**: cherry-pick/merge thay đổi đó về nhánh phát triển đang mở để không bị mất khi nhánh đó merge sau.
+4. Ghi lại sự cố để hậu kiểm (Phase 5 retro).