viepilot 1.3.1 → 1.8.0

package/templates/project/ROADMAP.md

@@ -51,6 +51,33 @@
 
 ---
 
+## Post-MVP / Product horizon
+
+> **Mandatory block (crystallize):** Populate from brainstorm **`## Product horizon`**, or state **single-release** explicitly. Tier tags: `(MVP)` ship first; `(Post-MVP)` after first release; `(Future)` exploratory.
+
+### Horizon mode
+
+{{HORIZON_MODE_LINE}}
+
+### Post-MVP themes (epic-level)
+
+{{POST_MVP_EPICS}}
+
+### Future / exploratory
+
+{{FUTURE_EPICS}}
+
+### Deferred capabilities (from MVP)
+
+{{DEFERRED_CAPABILITIES}}
+
+### Non-goals for MVP (reference)
+
+{{MVP_NON_GOALS_ROADMAP}}
+
+---
+
 ## Notes
 - Created: {{DATE}}
 - Last Updated: {{DATE}}
+- **Horizon:** Keep Post-MVP / Future content in sync with `PROJECT-CONTEXT.md` *Product vision & phased scope* after crystallize.

package/workflows/autonomous.md

@@ -90,6 +90,13 @@ read:
   - context_required files from task file
 ```
 
+Architecture context rule (ENH-018):
+- If `.viepilot/ARCHITECTURE.md` includes a diagram applicability matrix, load only diagrams relevant to current task:
+  - `required`: must be consulted before implementation/debug decisions.
+  - `optional`: consult when directly related; do not block task if absent.
+  - `N/A`: respect rationale; do not force diagram regeneration.
+- If matrix is missing, continue with explicit assumption notes in task logs.
+
 #### Validate Task Contract (required before code)
 Task must include execution-grade details:
 - Objective (specific outcome)

package/workflows/brainstorm.md

@@ -41,6 +41,7 @@ Nếu user chọn tiếp tục:
 2. Tóm tắt nội dung đã thảo luận
 3. Xác định các open questions / action items còn lại
 4. Tiếp tục từ điểm dừng
+5. Nếu session đã có section **`## Product horizon`**: tóm tắt nhanh MVP / Post-MVP / Future hiện có; mọi cập nhật sau đó phải **merge** vào section đó (không xóa im lặng, không làm mất tier tags) trừ khi user chủ động yêu cầu thu hẹp/mở rộng scope.
 </step>
 
 <step name="brainstorm_mode">
@@ -58,6 +59,12 @@ Gợi ý các topics để brainstorm:
    - System components
    - Data flow
    - Technology stack
+   - Diagram applicability signals (for crystallize):
+     - Service/module count and boundaries
+     - Event-driven usage (queues, webhooks, async jobs)
+     - Deployment topology (single node vs multi-env / distributed)
+     - User journey complexity (single actor/simple flow vs multi-actor)
+     - External integration surface (few vs many protocols/services)
 
 3. **Data Model**
    - Core entities
@@ -74,6 +81,13 @@ Gợi ý các topics để brainstorm:
    - Monitoring
    - Scaling
 
+6. **Product horizon (MVP vs Post-MVP vs Future)** — **bắt buộc duy trì trong session file** khi user thảo luận bất kỳ tính năng / milestone nào:
+   - **Mục tiêu**: tách rõ phạm vi ship đầu tiên với tầm nhìn sau MVP để `/vp-crystallize` không “mất” ý tưởng dài hạn.
+   - **Quy ước tag** (đặt ở cuối dòng bullet): `(MVP)` | `(Post-MVP)` | `(Future)`.
+   - **Non-goals for MVP**: những gì cố tình *không* làm ở bản đầu (tránh hiểu nhầm là quên).
+   - **Deferred capabilities**: tính năng đã thống nhất nhưng **lùi sau MVP** — ghi rõ để crystallize map vào roadmap horizon.
+   - Nếu sản phẩm **single-release** (không có post-MVP): ghi một dòng explicit trong session, ví dụ: `**Scope**: single-release only — no deferred epics.`
+
 ### Interactive Q&A
 Cho mỗi topic:
 1. Đặt câu hỏi cụ thể
@@ -113,26 +127,42 @@ User có thể yêu cầu research ngay trong brainstorm (không cần đổi sk
 Nếu assistant nhận thấy topic có độ mơ hồ cao hoặc rủi ro quyết định sai, assistant nên chủ động đề xuất:
 `Mục này nên research nhanh trước khi chốt, bạn muốn mình research luôn trong phiên này không?`
 
-### UI Direction Mode (design-in-the-loop; FEAT-002)
+### UI Direction Mode (design-in-the-loop; FEAT-002 + FEAT-007)
 Nếu user đang brainstorm cho dự án có UI/UX hoặc yêu cầu thiết kế trực quan:
 
-1. Tạo workspace direction cho phiên hiện tại:
-   - `.viepilot/ui-direction/{session-id}/index.html`
-   - `.viepilot/ui-direction/{session-id}/style.css`
-   - `.viepilot/ui-direction/{session-id}/notes.md`
+**Layout — chọn một:**
+
+- **Legacy (một màn):** `.viepilot/ui-direction/{session-id}/index.html` + `style.css` + `notes.md`.
+- **Multi-page (nhiều màn):** cùng thư mục session, thêm `pages/{slug}.html` cho từng page; `index.html` là **hub** (liên kết tới mọi page). `style.css` shared.
+
+**Quy tắc chung**
+
+1. Tạo workspace direction cho phiên hiện tại (tối thiểu `style.css` + `notes.md`; HTML theo layout đã chọn).
 2. Mỗi lần user đổi requirement/layout/component:
    - Cập nhật trực tiếp HTML/CSS direction
-   - Ghi decision + rationale vào `notes.md` (single source of truth)
+   - Ghi decision + rationale vào `notes.md` (single source of truth cho design intent)
+
+**Hook bắt buộc (multi-page only)**
+
+Khi thư mục `pages/` tồn tại hoặc bất kỳ `pages/*.html` nào được thêm / đổi tên / xóa:
+
+- Cập nhật **hub** `index.html` (nav / danh sách link tới mọi page còn lại).
+- Cập nhật ngay section **`## Pages inventory`** trong `notes.md` (bảng: Slug | File | Title | Purpose | Key sections | Nav to) — phải khớp 100% tập file `pages/*.html` hiện có.
+- Không kết thúc topic / không coi session UI đã “sync” nếu inventory lệch với file trên disk.
+
 3. Nếu user gửi references/components (bao gồm 21st.dev prompt/link), ghi rõ:
    - nguồn tham chiếu
-   - phần UI áp dụng
+   - phần UI áp dụng (page slug nếu multi-page)
    - điều chỉnh theo mục tiêu sản phẩm
 4. Giữ prototype ở mức mô tả định hướng (directional), không ép build production-ready code ở bước brainstorm.
 
+Tham chiếu user: `docs/user/features/ui-direction.md`.
+
 ### Kết thúc mỗi topic
 - Tóm tắt decisions
 - List action items
 - Note open questions
+- Nếu topic thêm/sửa capability: cập nhật **`## Product horizon`** trong bản nháp session (hoặc nhắc user lưu `/save`) với tag tier phù hợp
 </step>
 
 <step name="save_session">
@@ -148,6 +178,42 @@ Tạo/cập nhật file: `docs/brainstorm/session-{YYYY-MM-DD}.md`
 - **Participants**: User, Claude
 - **Status**: In Progress | Completed
 
+## Product horizon
+
+> Single source for **MVP / Post-MVP / Future** scope. Bắt buộc giữ section này khi tiếp tục session; crystallize đọc để không bỏ sót post-MVP.
+
+### MVP (ship first)
+- Capability / theme — `(MVP)`
+- ...
+
+### Post-MVP (after first release)
+- Capability / theme — `(Post-MVP)`
+- ...
+
+### Future / exploratory
+- Idea — `(Future)`
+- ...
+
+### Non-goals for MVP
+- ...
+
+### Deferred capabilities (from MVP)
+- ...
+
+**Scope note (optional):** Nếu không có post-MVP: `Single-release product — no separate horizon epics.`
+
+## Architecture diagram applicability inputs
+
+> Input contract for `/vp-crystallize` Step 4. Keep concise and explicit.
+
+- **Project complexity**: simple | moderate | complex
+- **Services/modules**: {single | multiple} + boundaries
+- **Event-driven**: yes/no + channels (queue/webhook/cron)
+- **Deployment shape**: local-only | single-env cloud | multi-env/distributed
+- **User flow complexity**: simple | multi-step | multi-actor
+- **Integration surface**: low | medium | high
+- **Initial diagram hints** (optional): required / optional / N/A candidates
+
 ## Topics Discussed
 
 ### Topic 1: {Name}
@@ -179,12 +245,14 @@ Tạo/cập nhật file: `docs/brainstorm/session-{YYYY-MM-DD}.md`
 
 **UI Direction Artifacts** (if applicable):
 - Session id: {session-id}
+- Layout: legacy (single `index.html`) | multi-page (`pages/*.html` + hub `index.html`)
 - Files:
-  - `.viepilot/ui-direction/{session-id}/index.html`
+  - `.viepilot/ui-direction/{session-id}/index.html` (hub hoặc single-screen)
   - `.viepilot/ui-direction/{session-id}/style.css`
-  - `.viepilot/ui-direction/{session-id}/notes.md`
+  - `.viepilot/ui-direction/{session-id}/notes.md` (must include `## Pages inventory` when `pages/` exists)
+  - `.viepilot/ui-direction/{session-id}/pages/*.html` (when multi-page)
 - Preview focus:
-  - {layout/flow summary}
+  - {layout/flow summary; list each page slug if multi-page}
 
 ---
 
@@ -228,7 +296,7 @@ Next step: /vp-crystallize
 This will transform your brainstorm into:
 - Project structure
 - Architecture documents
-- Development roadmap
+- Development roadmap (MVP phases + **Post-MVP / horizon** when documented above)
 ```
 </step>
 
@@ -247,6 +315,7 @@ User có thể dùng các lệnh trong phiên brainstorm:
 
 <success_criteria>
 - [ ] Session file created với đầy đủ sections
+- [ ] `## Product horizon` present với MVP / Post-MVP / Future (hoặc explicit single-release statement)
 - [ ] Decisions có rationale
 - [ ] Open questions tracked
 - [ ] Action items captured

package/workflows/crystallize.md

@@ -80,12 +80,25 @@ For each session file:
 3. Extract database schemas
 4. Extract features/requirements
 5. Extract tech stack choices
+6. **Product horizon (mandatory)** — parse `## Product horizon` when present (contract: `workflows/brainstorm.md`):
+   - Classify bullets under **MVP (ship first)**, **Post-MVP (after first release)**, and **Future / exploratory** using trailing tags `(MVP)` / `(Post-MVP)` / `(Future)` when present.
+   - Capture **Non-goals for MVP** and **Deferred capabilities (from MVP)** as first-class lists (these feed roadmap horizon and architecture constraints).
+   - Record **extensibility / platform notes** that imply deferred work (e.g., plugin model later, multi-tenant after MVP) if written in horizon or architecture sections.
+   - If the session states **single-release only** / **no deferred epics** (see brainstorm scope note), record `horizon_mode: single_release` in working notes for Step 7.
+
+**Consolidate across sessions** into a single **horizon inventory** (dedupe by capability name; if the same capability appears under conflicting tiers → stop and ask the user which tier wins).
+
+**Horizon validation gate (before leaving Step 1):**
+- [ ] Every brainstorm file was checked for `## Product horizon` **or** an explicit in-session single-release / no-deferred statement.
+- [ ] If `## Product horizon` is missing and the session still discusses releases beyond MVP without a single-release statement → stop and ask the user to update the session (e.g. `/vp-brainstorm` save) or confirm **single-release only** for the whole project.
+- [ ] Either **horizon inventory is non-empty** (Post-MVP/Future/deferred items captured) **or** **single-release** is explicitly recorded — no silent default.
 
 Validate completeness:
 - [ ] Tech stack defined
 - [ ] Core features identified
 - [ ] Database schema exists
 - [ ] API requirements clear
+- [ ] Product horizon processed per gate above (inventory or explicit single-release)
 
 If gaps found → ask user to clarify or return to brainstorm.
 </step>
@@ -101,11 +114,16 @@ ls -la .viepilot/ui-direction/ 2>/dev/null
 
 When available, for the selected/latest session:
 - Read `.viepilot/ui-direction/{session-id}/notes.md` first (source of design decisions)
-- Read `index.html` + `style.css` to extract:
-  - layout hierarchy
-  - component candidates
-  - interaction expectations
-- Record how each UI direction item maps into target tech stack implementation plan.
+- If `pages/` exists and contains `*.html`:
+  - Require section **`## Pages inventory`** in `notes.md`; treat it as the **site map** (page count, purpose, navigation).
+  - List all `pages/*.html` and confirm each file is represented in the inventory table (if mismatch → stop and ask user to fix brainstorm artifacts or document assumptions).
+  - Read **each** `pages/{slug}.html` for section structure, components, and interaction hints.
+  - Read hub `index.html` for cross-page navigation intent.
+- Else (legacy single-file layout):
+  - Read `index.html` + `style.css` only (no `pages/`).
+- Always read `style.css` for shared styling constraints.
+- Extract from HTML: layout hierarchy, component candidates, interaction expectations.
+- In architecture / UI plan output, **enumerate every page** from inventory (or state explicitly single-page legacy).
 
 If UI scope is present but artifacts are missing:
 - Warn user and request either:
@@ -177,7 +195,7 @@ Create `.viepilot/AI-GUIDE.md` using template:
 
 Customize with:
 - Project-specific file references
-- Context loading strategy based on project size
+- Context loading strategy based on project size — **preserve template ordering** where `PROJECT-CONTEXT.md` **`<product_vision>`** and **`ROADMAP.md` horizon** (Post-MVP / Future) are read **before** deep implementation / architecture lock; state this explicitly in the generated `AI-GUIDE.md` if you trim sections
 - Quick lookup for project-specific terms
 - Fast stack lookup section:
   - Read `.viepilot/STACKS.md`
@@ -211,6 +229,23 @@ Extract from brainstorm:
 - Data flow
 - Technology decisions with rationale
 - Integration points
+
+Before writing diagrams, create a **diagram applicability matrix** from brainstorm signals (complexity, service boundaries, event usage, deployment shape, user-flow complexity, integration surface):
+
+| Diagram type | Status | Rule |
+|--------------|--------|------|
+| `system-overview` | required/optional/N/A | Required if >1 major component or integration boundary |
+| `data-flow` | required/optional/N/A | Required when request/response or data pipeline is central |
+| `event-flows` | required/optional/N/A | Required when async events/webhooks/queues exist |
+| `module-dependencies` | required/optional/N/A | Required when multi-module/layer boundaries matter |
+| `deployment` | required/optional/N/A | Required for multi-env/distributed deployment concerns |
+| `user-use-case` | required/optional/N/A | Required when user journey/actor interactions drive design |
+
+Generation rules:
+- `required`: include explicit ` ```mermaid ` block in `.viepilot/ARCHITECTURE.md`
+- `optional`: may be simplified or merged with a nearby section, but keep section heading discoverable
+- `N/A`: keep heading and add one-line rationale (`Not applicable: ...`) so `vp-audit` and `vp-auto` can interpret intent
+- Never default to “all six detailed diagrams”; diagram depth must scale with project complexity from brainstorm.
 </step>
 
 <step name="generate_context">
@@ -255,14 +290,22 @@ Create `.viepilot/ROADMAP.md` using template:
 `@$HOME/.cursor/viepilot/templates/project/ROADMAP.md`
 
 From brainstorm features/MVP breakdown:
-1. Create phases
+1. Create **executable MVP phases** (what `/vp-auto` can run next; near-term delivery only).
 2. For each phase:
    - Define goal
    - Break into tasks
    - Set acceptance criteria
    - Add verification checkpoints
    - Estimate complexity (S/M/L/XL)
-3. Define dependencies between phases
+3. Define dependencies between MVP phases.
+4. **Post-MVP / product horizon (mandatory section in `.viepilot/ROADMAP.md`):**
+   - After MVP phases, always add a dedicated block (heading e.g. `## Post-MVP / Product horizon` or match the project template’s equivalent) that is **never omitted**:
+     - If Step 1 recorded **single-release** / no deferred epics: state explicitly *e.g.* **Single-release scope — no separate post-MVP epics** and that deferred capabilities are none by confirmation (do not invent future work).
+     - Otherwise: summarize **horizon inventory** items as **epic-level** entries (dependencies, rough sequencing OK; full task breakdown optional).
+   - Where a future epic depends on MVP deliverables, note **dependency links** back to the MVP phase(s) that unlock it.
+5. **ROADMAP self-check before finalize:**
+   - If Step 1 **horizon inventory** is non-empty but the draft ROADMAP **drops** those items or lacks the horizon block → **stop** and ask the user to reconcile (do not ship a roadmap that silently omits post-MVP content from brainstorm).
+   - If brainstorm contained Post-MVP ideas only in free text without `## Product horizon` → you should already have stopped in Step 1; do not proceed to commit ROADMAP.
 </step>
 
 <step name="generate_schemas">
@@ -408,10 +451,11 @@ Note: global stack cache at `~/.viepilot/stacks/` is machine-level knowledge and
 - [ ] All metadata collected
 - [ ] Official research completed for each selected stack
 - [ ] Global stack cache written under ~/.viepilot/stacks/{stack}/
+- [ ] Step 1: product horizon extracted **or** explicit single-release recorded; validation gate satisfied
 - [ ] All artifacts created in .viepilot/
 - [ ] PROJECT-META.md complete
 - [ ] SYSTEM-RULES.md has all standards
-- [ ] ROADMAP.md has phases with tasks
+- [ ] ROADMAP.md has MVP phases with tasks **and** mandatory Post-MVP / horizon block (or explicit single-release statement)
 - [ ] Phase directories created
 - [ ] Project files created
 - [ ] Git committed