viepilot 3.7.2 → 3.8.0

package/CHANGELOG.md

@@ -9,6 +9,28 @@ 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
+- sync README.md badges to v3.7.3: version, skills (21), workflows (14), tests (2210 passing)
+- add vp-design, vp-intake, vp-persona sections to docs/skills-reference.md (21 skills total)
+- update docs/dev/architecture.md orchestration model — ENH-096/097 delegation: tracker-agent, vp-git-agent, read+spawn-only orchestrator
+- remove confusing dual-version paragraph from README.md versioning note
+
+---
+
 ## [3.7.2] - 2026-05-23
 
 ### Added — ENH-097: vp-auto Full Orchestrator Delegation (Phase 142)

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.1.1-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-18-purple.svg)](#skills-reference)
-[![Workflows](https://img.shields.io/badge/workflows-13-orange.svg)](#workflows)
-[![Templates](https://img.shields.io/badge/templates-17-cyan.svg)](#templates)
-[![Tests](https://img.shields.io/badge/tests-1324%20passing-brightgreen.svg)](tests/)
+[![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-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)
 
-**Versioning:** Shield **2.19.0** is the **ViePilot framework SemVer** tracked in `.viepilot/TRACKER.md` and `CHANGELOG.md`. The npm `package.json` field `version` (**2.19.0**) is the Node package identifier for this repo; use the framework version for milestone releases and docs.
+**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.
 
@@ -28,13 +28,13 @@ Nếu ViePilot giúp ích cho bạn, bạn có thể ủng hộ một ly cafe:
 
 | Chỉ số / Metric | Giá trị / Value |
 |-----------------|-----------------|
-| Total LOC | **~51,713+** (`.md`, `.js`, `.cjs`, `.yml`, `.json`, `.sh`; không gồm `node_modules`) |
-| Skills | **18** |
-| Workflows | **12** |
-| Templates | **17** (Project: 12, Phase: 5) |
+| Total LOC | **~94,739+** (`.md`, `.js`, `.cjs`, `.yml`, `.json`, `.sh`; không gồm `node_modules`) |
+| Skills | **21** |
+| Workflows | **14** |
+| Templates | **18** (Project: 13, Phase: 5) |
 | CLI Commands | **18** (`vp-tools` 17 subcommands + `viepilot` installer) |
-| Tests | **607** (34 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`) | **62** phase cycles — **v2.4.0** FEAT-015 Codex adapter; **v2.3.x** ENH-036~037 installer cleanup; **v2.0.0** FEAT-013 dynamic adapters; **v1.x** M1.29 (FEAT-001~013); xem `CHANGELOG.md` |
+| 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` |
 | Standards | 5 (SemVer, Commits, Changelog, Comments, Contributors) |
 
 > Metric `Total LOC` có thể được refresh tự động bằng `npm run readme:sync` (dùng `cloc`; nếu thiếu `cloc` script sẽ fallback an toàn).
@@ -43,29 +43,29 @@ Nếu ViePilot giúp ích cho bạn, bạn có thể ủng hộ một ly cafe:
 
 | Thành phần / Component | Số lượng / Count | Mô tả / Description |
 |------------------------|------------------|---------------------|
-| Skill Definitions | **17** | SKILL.md files với trigger, process, success criteria |
-| Workflow Files | **12** | Step-by-step execution guides |
+| Skill Definitions | **21** | SKILL.md files với trigger, process, success criteria |
+| Workflow Files | **14** | Step-by-step execution guides |
 | Project Templates | 12 | AI-GUIDE, ARCHITECTURE, VIEPILOT-META, README, SYSTEM-RULES, etc. |
 | Phase Templates | 5 | SPEC, PHASE-STATE, TASK, VERIFICATION, SUMMARY |
 | CLI Tools | 2 | vp-tools.cjs (**17** subcommands) + viepilot.cjs (guided installer) |
-| Test Files | 34 | Jest: 33 unit + 1 integration (contracts, installer + Claude paths, info/update, FEAT-009/010/011~015, ENH-021~037, BUG-009~013 guards, adapter tests, scope policy, …) |
+| Test Files | 111 | Jest: 111 test files (contracts, installer + Claude paths, info/update, FEAT-009/010/011~015, ENH-021~037, BUG-009~013 guards, adapter tests, scope policy, …) |
 
 ---
 
 ## Độ hoàn thiện / Completion Status
 
 ```
-Tổng thể / Overall:  ████████████████████  ~99% ✅ Latest **v2.4.0** FEAT-015 Codex adapter; **v2.3.x** ENH-036~037 installer cleanup; **v2.1.x** BUG-009~013; **v2.0.0** FEAT-013 dynamic adapters
+Tổng thể / Overall:  ████████████████████  ~99% ✅ Latest **v3.7.3** ENH-095~097 orchestrator delegation; **v3.0.0** M3.0 Per-Adapter Intelligence; **v2.4.0** FEAT-015 Codex adapter; **v2.0.0** FEAT-013 dynamic adapters
 ```
 
 | Lĩnh vực / Area | Trạng thái | Chi tiết |
 |-----------------|------------|----------|
-| Core Skills (18) | ✅ Hoàn thiện | brainstorm, crystallize, auto, pause, resume, status, info, request, evolve, docs, update, task, debug, rollback, audit, ui-components, proposal, **skills** |
-| Workflows (13) | ✅ Hoàn thiện | Full step-by-step guides với success criteria |
+| Core Skills (21) | ✅ Hoàn thiện | brainstorm, crystallize, auto, pause, resume, status, info, request, evolve, docs, update, task, debug, rollback, audit, ui-components, proposal, skills, **design, intake, persona** |
+| Workflows (14) | ✅ Hoàn thiện | Full step-by-step guides với success criteria |
 | Project Templates (12) | ✅ Hoàn thiện | Placeholders cho customization (+ `VIEPILOT-META` FEAT-009) |
 | Phase Templates (5) | ✅ Hoàn thiện | Task tracking, verification, summary |
 | CLI Tools (18) | ✅ Hoàn thiện | vp-tools 17 subcommands + viepilot installer; bundle `info` / `update` |
-| Tests (957) | ✅ Hoàn thiện | Unit, integration, AI compat, workflow contracts, installer, scope policy, FEAT-009~015, ENH-021~048, BUG-009~013, adapter tests, AskUserQuestion adapter-aware prompts |
+| Tests (2210) | ✅ Hoàn thiện | Unit, integration, AI compat, workflow contracts, installer, scope policy, FEAT-009~015, ENH-021~048, BUG-009~013, adapter tests, AskUserQuestion adapter-aware prompts |
 | CI/CD | ✅ Hoàn thiện | GitHub Actions, Node 18/20/22 matrix, coverage >80% |
 | Documentation | ✅ Hoàn thiện | dev/, user/, api/, videos/, examples/, troubleshooting |
 | Standards | ✅ Hoàn thiện | SemVer, Conventional Commits, Keep a Changelog |
@@ -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/docs/dev/architecture.md

@@ -216,6 +216,32 @@ User Request
 | No external runtime | Works with any AI assistant |
 | CommonJS (no ESM) | Maximum Node.js compatibility |
 
+## Agent Orchestration Model (ENH-096/097)
+
+As of v3.7.2, the vp-auto orchestrator is **read + spawn only**. It never calls Edit, Write, or Bash for any write operation. All work is delegated to specialized subagents:
+
+| Agent | Role | Tools Permitted |
+|-------|------|-----------------|
+| vp-auto orchestrator | Read state, spawn workers, gate phase transitions | Read, Bash (read-only git only), Agent |
+| vp-task-executor | All implementation — code, docs, config edits | Read, Edit, Write, MultiEdit, Bash, Glob, Grep, LS |
+| vp-quality-gate | Run verification commands, report PASS/FAIL | Read, Bash, Grep, Glob, LS |
+| vp-phase-planner | Build dependency graph, identify parallel task clusters | Read, Glob, Grep, LS |
+| tracker-agent | Write state files: PHASE-STATE.md, TRACKER.md, HANDOFF.json, ROADMAP.md | Read, Edit, Write |
+| vp-git-agent | Git operations: create-tag, push-branch, push-tags, push-all, git-status | Bash only |
+| changelog-agent | Write CHANGELOG.md entries for features and fixes | Read, Edit, Write |
+
+**Result formats:**
+- `TASK_RESULT: PASS | FAIL | PARTIAL` — returned by vp-task-executor and vp-quality-gate
+- `GIT_RESULT: PASS | FAIL | SKIP` — returned by vp-git-agent
+
+**Orchestration flow:**
+1. Orchestrator reads PHASE-STATE.md + task contracts
+2. Spawns tracker-agent → set tasks `in_progress`
+3. Spawns vp-task-executor(s) — parallel fan-out for independent tasks
+4. Spawns vp-quality-gate for each completed task
+5. On PASS: spawns tracker-agent → mark task done, update HANDOFF.json
+6. On phase complete: spawns vp-git-agent (tag + push), tracker-agent (ROADMAP update), changelog-agent
+
 ## Extension Points
 
 | Point | How to Extend |

package/docs/skills-reference.md

@@ -547,3 +547,99 @@ Full guide: `docs/user/features/proposal.md`
 - Fallback: `~/.cursor/viepilot/bin/vp-tools.cjs` for Cursor adapter.
 - Registry file: `~/.viepilot/skill-registry.json` — shared across all projects.
 - Confirmation AUQ prompt before destructive `uninstall` (Claude Code terminal only).
+
+---
+
+## /vp-design
+
+Visual/UI direction skill. Generates UI architecture: component map, color system, typography,
+responsive breakpoints, and Pencil design file integration.
+
+### Triggers
+`vp-design`, `/vp-design`, "thiết kế UI", "UI direction", "design system"
+
+### Flags
+- `--new` : Start fresh UI direction session
+- `--component <name>` : Design a specific component
+- `--mobile` : Mobile-first emphasis
+- `--architect` : Generate Architect HTML view alongside
+
+### Flow
+1. Collect product goals + target audience + brand constraints
+2. Generate UI direction: color palette, typography, spacing scale, component inventory
+3. Output Pencil design stubs (if Pencil MCP available) or Architect HTML fallback
+4. Write `docs/ui-direction.md` and `PROJECT-CONTEXT.md ## UI Direction`
+
+### Output
+- `docs/ui-direction.md` (created/updated)
+- `PROJECT-CONTEXT.md` UI Direction section (locked by `/vp-crystallize` Step 1E)
+- Optional: Pencil `.pen` file stubs via `mcp__pencil__batch_design`
+
+### Adapter-Aware Prompts
+Uses `AskUserQuestion` on Claude Code terminal for design-direction questions.
+
+---
+
+## /vp-intake
+
+Structured intake from Google Sheets, Excel (M365), CSV files, and browser URLs. Reads rows
+from a configured source, creates ViePilot request files, and optionally writes results back.
+
+### Triggers
+`vp-intake`, `/vp-intake`, "đọc intake", "intake từ sheet", "load requests from sheet"
+
+### Flags
+- `--channel <id>` : Force a specific intake channel (sheets/excel/csv/browser)
+- `--dry-run` : Parse and triage without writing request files
+- `--no-writeback` : Skip writing results back to source
+- `--setup` : Launch AUQ-driven channel configuration wizard (ENH-084)
+
+### Flow
+1. Load intake manifest (`~/.viepilot/intake-manifests/<project>.json`) or prompt setup
+2. Read rows from configured channel (Google Sheets via API, Excel via M365 Graph, CSV, or browser-agent for public URLs)
+3. Triage each row: detect type (bug/feature/enhancement/debt), extract title/description
+4. Create `.viepilot/requests/{TYPE}-{N}.md` for each valid row
+5. Write-back status column to source row (if writable channel)
+
+### Output
+- `.viepilot/requests/{TYPE}-{N}.md` per intake row
+- Intake manifest updated with last-read cursor
+- Source row status updated (write-back, if enabled)
+
+### Adapters
+Full support: Claude Code. Partial: Cursor (no AUQ). Text fallback: Codex/Copilot/Antigravity.
+
+---
+
+## /vp-persona
+
+Manages the global developer persona profile stored in `~/.viepilot/config.json`. Persona
+controls output style, stack preferences, and team-size assumptions injected into every skill.
+
+### Triggers
+`vp-persona`, `/vp-persona`, "cấu hình persona", "set persona", "developer profile"
+
+### Flags
+- `--set` : Interactively set persona fields
+- `--show` : Print current active persona
+- `--auto-switch` : Switch persona based on current project stack (used internally by skills)
+- `--context` : Print persona as `## User Persona` block (used by skill banners)
+
+### Persona Fields
+| Field | Values | Default |
+|-------|--------|---------|
+| `role` | backend / frontend / fullstack / devops / data / mobile | backend |
+| `domain` | web-saas / mobile / api / data / infra / other | web-saas |
+| `stacks` | comma-separated list | — |
+| `outputStyle` | lean / verbose | lean |
+| `phaseTemplate` | lean-startup / enterprise / research | lean-startup |
+| `teamSize` | solo / small / medium / large | solo |
+
+### Flow
+1. `vp-tools persona auto-switch` — detects stack from package.json / pyproject.toml / build.gradle
+2. `vp-tools persona context` — outputs `## User Persona` markdown block
+3. Skills inject this block silently before task execution
+
+### Output
+- `~/.viepilot/config.json` updated
+- `## User Persona` injected into each skill session

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "viepilot",
-  "version": "3.7.2",
+  "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