viepilot 3.7.3 → 3.8.0

package/CHANGELOG.md

@@ -9,6 +9,18 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ---
 
+## [3.8.0] - 2026-05-24
+
+### Added
+- ENH-098: vp-brainstorm Stakeholder Generation Gate — AI infers domain-appropriate stakeholders
+  at end of session, creates `.claude/agents/{project-slug}-{role}.md` agent files (haiku-4-5, Read-only)
+- ENH-098: vp-crystallize Step 1G Stakeholder Review Gate — parallel fan-out of all project
+  stakeholder agents, gap analysis synthesis (Gaps/Risks/Suggestions), enriches PROJECT-CONTEXT.md
+  before ROADMAP generation; skippable with `--no-stakeholders`
+- `templates/stakeholder-agent.md` — canonical template for generated stakeholder agent files
+
+---
+
 ## [3.7.3] - 2026-05-23
 
 ### Documentation

package/README.md

@@ -2,15 +2,15 @@
 
 **Autonomous Vibe Coding Framework / Bộ khung phát triển tự động có kiểm soát**
 
-[![Version](https://img.shields.io/badge/version-3.7.3-blue.svg)](CHANGELOG.md)
+[![Version](https://img.shields.io/badge/version-3.8.0-blue.svg)](CHANGELOG.md)
 [![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
 [![Skills](https://img.shields.io/badge/skills-21-purple.svg)](#skills-reference)
 [![Workflows](https://img.shields.io/badge/workflows-14-orange.svg)](#workflows)
-[![Templates](https://img.shields.io/badge/templates-17-cyan.svg)](#templates)
+[![Templates](https://img.shields.io/badge/templates-18-cyan.svg)](#templates)
 [![Tests](https://img.shields.io/badge/tests-2210%20passing-brightgreen.svg)](tests/)
 [![GitHub](https://img.shields.io/github/stars/0-CODE/viepilot?style=social)](https://github.com/0-CODE/viepilot)
 
-**Version**: `3.7.3` — tracked in `package.json`, `CHANGELOG.md`, and `.viepilot/TRACKER.md`.
+**Version**: `3.8.0` — tracked in `package.json`, `CHANGELOG.md`, and `.viepilot/TRACKER.md`.
 
 ViePilot là bộ skill framework cho phép AI assistant (Claude, GPT, etc.) phát triển dự án một cách **tự động**, **có kiểm soát**, và **có thể khôi phục**. Thiết kế theo các tiêu chuẩn chuyên nghiệp: Semantic Versioning, Conventional Commits, Keep a Changelog.
 
@@ -31,7 +31,7 @@ Nếu ViePilot giúp ích cho bạn, bạn có thể ủng hộ một ly cafe:
 | Total LOC | **~94,739+** (`.md`, `.js`, `.cjs`, `.yml`, `.json`, `.sh`; không gồm `node_modules`) |
 | Skills | **21** |
 | Workflows | **14** |
-| Templates | **17** (Project: 12, Phase: 5) |
+| Templates | **18** (Project: 13, Phase: 5) |
 | CLI Commands | **18** (`vp-tools` 17 subcommands + `viepilot` installer) |
 | Tests | **2210** (111 suites: unit + integration + AI compat + README metrics + UI direction + ENH contracts + scope policy + FEAT-009/010/011/012/013/015 + ENH-021~037 routing/language/architect/adapter + BUG-009~013 guards + viepilot-info/update/install/adapters) |
 | ViePilot phases (local `.viepilot`) | **142** phase cycles — **v3.7.x** ENH-095~097 orchestrator delegation; **v3.0.0** M3.0 Per-Adapter Intelligence; **v2.4.0** FEAT-015 Codex; **v2.0.0** FEAT-013 dynamic adapters; xem `CHANGELOG.md` |
@@ -167,6 +167,7 @@ Tổng thể / Overall:  ██████████████████
 | `CONTRIBUTING.md` | Contribution guidelines |
 | `CONTRIBUTORS.md` | Attribution list |
 | `README.md` | Professional README template |
+| `stakeholder-agent.md` | Agent template for stakeholder reviews (generated by vp-brainstorm Step S2) |
 
 ### Phase Templates (5)
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "viepilot",
-  "version": "3.7.3",
+  "version": "3.8.0",
   "description": "**Autonomous Vibe Coding Framework / Bộ khung phát triển tự động có kiểm soát**",
   "main": "index.js",
   "bin": {

package/skills/vp-brainstorm/SKILL.md

@@ -201,6 +201,7 @@ Optional flags:
 - `--research` : Enable proactive research suggestions during the session
 - `--ui` : Enable UI Direction mode (live HTML/CSS direction artifacts + auto-generates `design.md` when design keywords present — ENH-076)
 - `--domain embedded` : Force-activate Embedded Domain Mode (hardware topology, RTOS, pin map, memory layout, protocol matrix, power budget pages + topic probes)
+- `--no-stakeholders` : Skip stakeholder agent generation at session end
 
 ### Reference URL Input (ENH-092)
 
@@ -279,6 +280,11 @@ Key steps:
 9. Before completing the session: **step 5 — Project meta intake (FEAT-009)** in `workflows/brainstorm.md` when binding is missing; sequential Q&A + profile-map disambiguation + write global profile + `.viepilot/META.md`
 10. Save session with structured format (including **`## Project meta intake (FEAT-009)`**, research notes + UI direction references + **`## Phases`**)
 11. Suggest next action: `/vp-crystallize`
+
+**Stakeholder Generation (ENH-098):**
+At session end (scope locked), automatically infers project stakeholders from the domain and
+creates `.claude/agents/{project-slug}-{role}.md` agent files. These are consumed by
+`/vp-crystallize` Step 1G for parallel context review. Skip with `--no-stakeholders`.
 </process>
 
 <success_criteria>

package/skills/vp-crystallize/SKILL.md

@@ -58,6 +58,9 @@ Silent if command unavailable or errors.
 - Skill được gọi khi user mention `vp-crystallize`, `/vp-crystallize`, hoặc "crystallize", "setup project"
 - Treat all user text after the skill mention as `{{VP_ARGS}}`
 
+**Flags:**
+- `--no-stakeholders` : Skip the Step 1G Stakeholder Review Gate (ENH-098)
+
 ## B. User Prompting
 Prompt user conversationally with numbered list options.
 
@@ -434,3 +437,14 @@ and injects skill best practices per task without re-prompting.
 Install skills: `vp-tools install-skill <source>`
 Registry: `vp-tools scan-skills`
 Docs: `docs/user/features/skill-registry.md`
+
+### Step 1F — Cross-Reference Gate
+
+Validates coverage matrix when both Architect and UI Direction workspaces are present.
+Warns on Phase 1 features with no architect OR UI coverage (non-blocking).
+
+### Step 1G — Stakeholder Review Gate (ENH-098)
+
+After scope lock, spawns `.claude/agents/` stakeholder agents in parallel fan-out,
+collects gap analysis (Gaps/Risks/Suggestions), synthesizes feedback to enrich
+PROJECT-CONTEXT.md before ROADMAP generation. Can be skipped with `--no-stakeholders` flag.

package/templates/stakeholder-agent.md

@@ -0,0 +1,51 @@
+---
+name: {{project_slug}}-{{role_slug}}
+description: >
+  Stakeholder reviewer for {{PROJECT_NAME}}. Reviews the project context document
+  from the perspective of a {{ROLE_TITLE}}. Returns a structured gap analysis
+  (Gaps / Risks / Suggestions) to enrich PROJECT-CONTEXT.md.
+model: claude-haiku-4-5
+tools:
+  - Read
+---
+
+You are a **{{ROLE_TITLE}}** reviewing the initial project definition for **{{PROJECT_NAME}}**.
+
+## Your Perspective
+
+{{ROLE_DESCRIPTION}}
+
+## What You Care About
+
+{{ROLE_CONCERNS}}
+
+## Your Task
+
+Read the project context file at `.viepilot/PROJECT-CONTEXT.md`.
+
+Evaluate it from your professional perspective and return a structured review:
+
+### Gaps
+
+List definitions, sections, or decisions that are vague, missing, or contradictory
+from your point of view.
+
+*(Maximum 5 items. One sentence each.)*
+
+### Risks
+
+List concerns, assumptions, or red flags that could cause problems during execution
+or deployment.
+
+*(Maximum 5 items. One sentence each.)*
+
+### Suggestions
+
+List specific additions, clarifications, or reframings that would make the project
+context more complete and actionable from your perspective.
+
+*(Maximum 5 items. One sentence each.)*
+
+---
+
+> Return ONLY the structured review above. Do not summarize the project or ask questions.

package/workflows/brainstorm.md

@@ -2111,6 +2111,107 @@ git push
 ```
 </step>
 
+<step name="stakeholder_gate">
+## 6B. Stakeholder Generation Gate (ENH-098)
+
+Executed automatically after scope is locked and summary is written.
+Skipped if: `--no-stakeholders` flag present in session context, or `config.json → crystallize.stakeholders.enabled: false`.
+
+### Step S1: Infer Stakeholders
+
+From the brainstorm summary, extract:
+- `domain`: the product domain (web-saas, mobile, api, data, e-commerce, infra, other)
+- `product_type`: what kind of product (SaaS, marketplace, internal tool, SDK, mobile app, etc.)
+- `team_size`: from PROJECT-META or persona context (solo/small/medium/large)
+- `project_slug`: short kebab-case name derived from project title (e.g., "myapp", "invoice-app")
+
+Determine stakeholder count:
+- solo + simple domain: 3 stakeholders
+- medium complexity: 4–5 stakeholders
+- enterprise / regulated (fintech, health, legal): 6 stakeholders
+
+Generate stakeholder list based on domain. Examples:
+
+| Domain | Stakeholders |
+|--------|--------------|
+| **web-saas** | cto, product-manager, ux-lead, end-user, business-owner |
+| **mobile** | product-owner, mobile-developer, end-user, app-store-reviewer |
+| **api/platform** | platform-engineer, api-consumer, devops-lead, sre |
+| **e-commerce** | business-owner, customer, marketing-manager, logistics-manager |
+| **data/ml** | data-scientist, ml-engineer, business-analyst, end-user |
+| **other** | infer contextually from brainstorm content |
+
+### Step S2: Write Agent Files
+
+For each stakeholder, create a file at `.claude/agents/{project_slug}-{role_slug}.md` using the template from `templates/stakeholder-agent.md`.
+
+Template structure:
+```markdown
+---
+name: {project_slug}-{role_slug}
+description: Stakeholder reviewer for {PROJECT_NAME}. Reviews project context from the
+  perspective of a {ROLE_TITLE}. Returns gap analysis (Gaps/Risks/Suggestions).
+model: claude-haiku-4-5
+tools:
+  - Read
+---
+
+You are a {ROLE_TITLE} reviewing the project definition for **{PROJECT_NAME}**.
+
+## Your Perspective
+{2-3 sentence role description — who you are, what you own, what matters to you}
+
+## What You Care About
+{4-6 bullet points of specific concerns from this role's angle}
+
+## Your Task
+Read `.viepilot/PROJECT-CONTEXT.md`. Return a structured review with three sections:
+
+### Gaps
+(sections/definitions that are vague, missing, or contradictory from your perspective)
+
+### Risks
+(concerns or red flags that could cause execution problems)
+
+### Suggestions
+(specific additions or clarifications to strengthen the context)
+
+Keep each item to 1 sentence. Maximum 5 items per section.
+```
+
+Substitute variables:
+- `{{project_slug}}` → kebab-case project identifier
+- `{{role_slug}}` → kebab-case role identifier
+- `{{PROJECT_NAME}}` → Full project name
+- `{{ROLE_TITLE}}` → Human-readable role title
+- `{{ROLE_DESCRIPTION}}` → 2-3 sentence persona description
+- `{{ROLE_CONCERNS}}` → 4-6 bullet list of role-specific concerns
+
+Write each file using the Edit/Write tool. Path is relative to project root (where `.claude/` lives).
+
+> **Note**: `.claude/agents/` is the project-level agents directory for Claude Code.
+> For other adapters (Cursor, Codex): skip this step gracefully — agent files won't be created,
+> and the crystallize Step 1G will detect no agents and skip the review gate.
+
+### Step S3: Record in Summary
+
+Append a `## Stakeholders Generated` section to the brainstorm session summary output:
+
+```markdown
+## Stakeholders Generated
+
+The following stakeholder agents have been created in `.claude/agents/`:
+
+| File | Role | Perspective |
+|------|------|-------------|
+| `{project_slug}-cto.md` | CTO | Technical feasibility, stack, security |
+| `{project_slug}-product-manager.md` | Product Manager | Scope, user stories, priorities |
+| ... | ... | ... |
+
+These agents will be called in vp-crystallize Step 1G to review PROJECT-CONTEXT.md.
+```
+</step>
+
 <step name="arch_to_ui_sync">
 ## 6C. Architect → UI Direction Sync (ENH-061)
 

package/workflows/crystallize.md

@@ -2205,6 +2205,90 @@ Run when BOTH `architect_read_complete: true` AND `ui_direction_read_complete: t
 **Skip condition**: if only one workspace is present (not both) → silently skip Step 1F (single-workspace is valid).
 </step>
 
+<step name="stakeholder_review_gate">
+---
+
+## Step 1G: Stakeholder Review Gate (ENH-098)
+
+**Trigger**: Runs automatically after Step 1F, before Step 2.
+
+**Skip conditions**:
+- `--no-stakeholders` flag passed to `/vp-crystallize`
+- `config.json → crystallize.stakeholders.enabled: false`
+- No `.claude/agents/{project-slug}-*.md` files found (gate is silently skipped)
+- Non-Claude-Code adapter (Cursor, Codex, Copilot): skip gracefully
+
+### Step 1G.1 — Discover Stakeholder Agents
+
+```bash
+# Find project stakeholder agents
+ls .claude/agents/ | grep "^{project_slug}-"
+```
+
+If 0 files found: print notice "No stakeholder agents found — skipping Step 1G. Run `/vp-brainstorm` first to generate stakeholder agents, or use `--no-stakeholders` to suppress."
+Then continue to Step 2.
+
+If files found: proceed.
+
+### Step 1G.2 — Parallel Stakeholder Review
+
+Spawn all found stakeholder agents simultaneously (parallel fan-out):
+
+For each `.claude/agents/{project_slug}-{role_slug}.md`:
+```
+Agent({
+  subagent: "{project_slug}-{role_slug}",
+  prompt: "Read .viepilot/PROJECT-CONTEXT.md. Return your structured review (Gaps/Risks/Suggestions)."
+})
+```
+
+Collect all results. Each result is a structured document with three sections:
+- `### Gaps` — missing or vague definitions
+- `### Risks` — execution concerns from this role's perspective
+- `### Suggestions` — specific additions to strengthen the context
+
+### Step 1G.3 — Synthesis
+
+After all agents return:
+
+1. **Aggregate**: collect all Gaps, Risks, Suggestions across all stakeholders
+2. **Deduplicate**: merge identical or near-identical points
+3. **Rank**: sort by frequency (raised by ≥2 stakeholders = high priority) and severity
+4. **Conflict resolution**: if stakeholders disagree (e.g., CTO wants more tech detail, PM wants less), note both perspectives and use the more conservative approach
+5. **Filter**: discard suggestions that are already addressed in PROJECT-CONTEXT.md
+
+### Step 1G.4 — Enrich PROJECT-CONTEXT.md
+
+Apply the top-ranked suggestions to `.viepilot/PROJECT-CONTEXT.md`:
+
+- Add missing sections (e.g., `## Security Considerations`, `## Success Metrics`)
+- Expand vague definitions with the suggested specifics
+- Flag unresolved conflicts as `> ⚠️ Open question: {conflict}` inline
+- Do NOT remove or replace existing content — only add/clarify
+
+### Step 1G.5 — Stakeholder Review Summary Banner
+
+Display to user:
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ STAKEHOLDER REVIEW COMPLETE ✓
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+ Stakeholders reviewed: {N}
+ Gaps found: {count} ({high-priority} high priority)
+ Risks flagged: {count}
+ Enrichments applied: {count} additions to PROJECT-CONTEXT.md
+ Open questions: {count} (flagged inline for your review)
+
+ Reviewers: {role_1}, {role_2}, ..., {role_N}
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+
+Then continue to Step 2 (ROADMAP generation).
+
+</step>
+
 <step name="generate_ai_guide">
 ## Step 2: Generate AI-GUIDE.md