@sugar-crash-studios/vibe-forge 0.4.0

package/docs/roadmap-2026.md

@@ -0,0 +1,519 @@
+# Vibe Forge Integration Roadmap — 2026
+
+**Generated:** 2026-03-31
+**Based on:** BMAD gap analysis (9 agent reports), Claude Code source patterns, vibe-lab exploration
+**Current version:** Vibe Forge 0.4.0
+
+---
+
+## How to Read This
+
+Work is organized into **parallel workstreams** — groups of tasks that have no dependencies on each other and can run simultaneously — and **sequential chains** where earlier items unlock later ones.
+
+**Priority tiers:**
+- **Tier 0:** Security fixes — do these before any other work
+- **Tier 1:** High-value, low-risk improvements — do these next sprint
+- **Tier 2:** Framework maturity — do these over the following 2-3 sprints
+- **Tier 3:** Strategic expansion — larger initiatives, plan carefully
+
+**Effort legend:** `XS` (<2h) | `S` (half-day) | `M` (1-2 days) | `L` (3-5 days) | `XL` (1+ week)
+
+---
+
+## Tier 0: Security (Do First, Can Parallelize)
+
+These are independent of each other and should all be done before any feature work. A compromised CI pipeline or RCE vector outweighs any feature benefit.
+
+### T0-1: Fix `design` Alias Collision `[XS]`
+**Source:** CRIT-3
+**Location:** `config/agents.json`
+Both `architect` and `pixel` claim `"design"`. Pixel silently wins. `forge spawn design` spawns the wrong agent.
+
+**Fix:** Remove `"design"` from `architect.aliases`. Architect has `"arch"` already.
+
+**Parallel with:** T0-2, T0-3
+
+---
+
+### T0-2: Eliminate `eval` of Node-Generated Shell Code `[M]`
+**Source:** CRIT-2 (Sentinel, Aegis)
+**Location:** `bin/lib/config.sh:142`
+
+`load_agents_from_json()` runs Node.js, captures its stdout (shell assignments), then `eval`s it. Any bug in `escapeForShell()` or a compromised `agents.json` is RCE.
+
+**Fix:** During `forge init` (or on first config load), write a static `agents.env` file with validated variable assignments. Source that file instead of eval-ing dynamically. Node.js only runs to rebuild the file when `agents.json` changes (compare mtime).
+
+**Parallel with:** T0-1, T0-3
+
+---
+
+### T0-3: Add Pre-commit Hook Infrastructure `[S]`
+**Source:** CRIT-4 (Crucible)
+**Why now:** Prevents any code from entering main without basic gates. Low effort, high protection.
+
+**Fix:** Add a minimal `.husky/pre-commit` that runs:
+1. `node --check bin/cli.js` (syntax only — already in CI)
+2. `npm test` if tests exist and pass in <30s
+3. `shellcheck bin/*.sh` for any modified shell files
+
+**Parallel with:** T0-1, T0-2
+
+---
+
+## Tier 1: High-Value Quick Wins
+
+These are largely independent. All can be worked in parallel once Tier 0 is done.
+
+### Workstream A: Quality Enforcement
+
+#### T1-A1: Numbered Acceptance Criteria Enforcement `[S]`
+**Source:** Crucible, task-template.md rewrite (done)
+The task template now has numbered ACs. Next: Sentinel's review checklist should explicitly verify each numbered AC passes before approving.
+
+Add to Sentinel's personality: "When reviewing, enumerate each AC 1..N and confirm YES/NO/PARTIAL with evidence. A PR cannot be approved unless all ACs are YES."
+
+#### T1-A2: Definition of Done Gate in Task Flow `[M]`
+**Source:** CRIT-4 (Crucible)
+Tasks move to `review/` with the DoD checklist in the template. Sentinel should be instructed to reject PRs where `ready_for_review: false` in the completion YAML or where DoD checkboxes are unchecked.
+
+Update Sentinel personality + add forge-daemon verification step: scan task file for `ready_for_review: false` before notifying review queue.
+
+#### T1-A3: HALT Conditions in All Agent Personalities `[M]`
+**Source:** Furnace, Sentinel
+Agents must know when to stop and escalate rather than improvise or self-approve.
+
+Add to every worker agent personality (Anvil, Furnace, Crucible, Ember, Aegis, Pixel, Scribe):
+```
+**When to STOP and write to tasks/attention/:**
+- Required package not in project (get approval before adding)
+- 3 consecutive test failures on the same test
+- Acceptance criteria are ambiguous or contradictory
+- Schema or migration would affect live data
+- Security concern (escalate to Aegis)
+- Your confidence is low — stopping is correct
+```
+
+---
+
+### Workstream B: Developer Experience
+
+#### T1-B1: Fix README — Remove Non-Existent Agents `[XS]`
+**Source:** Pixel (HIGH-9)
+README references Sage, Oracle, and Quartermaster which do not exist in `agents.json`. Creates confusion for new users trying to spawn these agents.
+
+**Fix:** Audit README against `agents.json` canonical names. Remove all references to agents that don't exist. Update examples to use real aliases.
+
+#### T1-B2: Alias Collision Detection in CI `[S]`
+**Source:** forge doctor (done)
+`forge doctor` now detects alias collisions at runtime. Next: add the same check to CI so it catches regressions.
+
+Add a `node -e "..."` step to `.github/workflows/ci.yml` that reads `agents.json` and exits 1 if any alias maps to two different canonical agents.
+
+#### T1-B3: `forge init` Validates `agents.json` on Setup `[XS]`
+**Source:** Ember
+`forge init` should run the alias collision check before completing setup. If collisions exist, warn loudly and offer to fix them.
+
+#### T1-B4: Session Anti-Pattern Guards in Hub Personality `[S]`
+**Source:** Sentinel
+Planning Hub must not lie about task completion or stop sessions prematurely. Add explicit prohibitions to Hub personality:
+
+- "Never mark a task complete without reading the completion YAML in the task file."
+- "Never end your session without checking for pending tasks."
+- "If a task is in `in-progress/` with no recent activity, flag it to the user."
+
+---
+
+### Workstream C: Task System Improvements
+
+#### T1-C1: Epic/Story Hierarchy Directory Structure `[M]`
+**Source:** HIGH-1, BMAD comparison
+BMAD's epic → story → task tree is its most powerful planning tool. Vibe Forge has tasks but no hierarchy above them.
+
+**Fix:** Create `specs/epics/` directory with an epic template. Update task-template to reference parent epic via `specs/epics/{EPIC_ID}.md`. Hub should create epics first, then decompose them into tasks. No need to replicate all of BMAD's planning phases — just the hierarchy.
+
+Epic template fields: `id`, `title`, `goal`, `success_metrics`, `stories[]`, `status`.
+
+#### T1-C2: `forge-state.yaml` Sprint Summary `[M]`
+**Source:** HIGH-4 (missing sprint-status.yaml equivalent)
+BMAD's `sprint-status.yaml` gives a single-file answer to "what is the team working on right now?" Vibe Forge's `forge-state.yaml` exists but is often empty.
+
+**Fix:** Hub should update `context/forge-state.yaml` on startup and after completing each task batch:
+```yaml
+sprint: null
+last_updated: 2026-03-31T12:00:00Z
+active_tasks:
+  - id: task-042
+    title: "Add login form"
+    assigned_to: anvil
+    status: in-progress
+pending_count: 7
+completed_today: 3
+blocked: []
+```
+
+#### T1-C3: `tasks/attention/` Escalation Routing `[S]`
+**Source:** Furnace
+The `attention/` directory exists in the task template but there are no instructions for what happens to files placed there. Hub should monitor it and surface items to the user on startup.
+
+Add to Hub's startup behavior: check `tasks/attention/` and display any files with a summary. These are agent escalations that require human input.
+
+---
+
+### Workstream D: Daemon & Infrastructure
+
+#### T1-D1: Fix Daemon Cross-Platform Date Parsing `[S]`
+**Source:** Ember (BUG-daemon-001)
+Daemon uses `date -d` which is GNU/Linux only. macOS uses `date -j -f`. This silently breaks all time-based features on macOS.
+
+**Fix:** Use Node.js `new Date(str)` for all date operations in daemon scripts instead of shell `date` command. Or add a platform detection branch.
+
+#### T1-D2: Fix `stat` Portability in Daemon `[XS]`
+**Source:** Ember (BUG-daemon-002)
+Daemon uses `stat -c '%Y'` (Linux) vs `stat -f '%m'` (macOS) for file modification times.
+
+**Fix:** Same as above — move file mtime operations to Node.js `fs.statSync(f).mtimeMs`.
+
+#### T1-D3: Wire Up `db_record_status_history()` `[S]`
+**Source:** Ember
+`db_record_status_history()` exists in the daemon but is never called. The `status_history` table is always empty. This means the dashboard's history features show no data.
+
+**Fix:** Call `db_record_status_history()` whenever a task moves between directories. The daemon's file watcher should be the trigger point.
+
+---
+
+## Tier 2: Framework Maturity
+
+These are larger features. Some have dependencies. Do in the order shown within each workstream.
+
+### Workstream E: Planning & Requirements Phase
+
+These items are sequential — each builds on the last.
+
+#### T2-E1: Context Directory Bootstrap `[S]`
+**Dependency:** None (prerequisite for E2, E3)
+Ensure `context/` directory exists with documented files:
+- `project-context.md` — what this project is, who the users are, tech stack
+- `architecture.md` — key decisions, patterns, guardrails
+- `agent-overrides/` — per-agent customization files (see T2-E3)
+
+`forge init` should create these with prompts for key fields.
+
+#### T2-E2: Hub Planning Mode `[L]`
+**Dependency:** T1-C1 (epic hierarchy)
+**Source:** HIGH-1, BMAD Phase 1-3
+
+Hub currently jumps straight to task assignment. Add a "planning mode" that Hub enters at project start (or when `specs/epics/` is empty):
+
+1. **Discovery:** Ask the user to describe the goal in plain language
+2. **Decomposition:** Break into epics, each with a clear success metric
+3. **Tasking:** Decompose each epic into tasks, assign types and agent targets
+4. **Commit:** Write epic files and task files, then hand off to workers
+
+This is the single biggest gap vs BMAD. Hub is a great executor — it needs to also be a planner.
+
+#### T2-E3: Per-Project Agent Customization `[M]`
+**Dependency:** T2-E1
+**Source:** HIGH-7, BMAD `.customize.yaml`
+
+BMAD agents read a `.customize.yaml` that overrides their behavior for the specific project (tech stack, conventions, forbidden patterns). Vibe Forge agents receive only their personality file — no per-project tuning.
+
+**Fix:** Hub reads `context/agent-overrides/<agent>.md` and appends it to the agent's system prompt when spawning. Each override file is a short markdown of project-specific rules.
+
+---
+
+### Workstream F: Token & Session Management
+
+#### T2-F1: Token Budget Warnings `[M]`
+**Source:** HIGH-3 (Sentinel)
+No agent knows how much context it has consumed or when it's approaching its limit. This leads to silent context truncation and degraded quality near session end.
+
+**Fix:** Add to daemon: when an agent's session log shows >100k tokens (estimate from task file sizes and conversation length), emit a notification to `tasks/attention/` with a suggestion to `/compact` or start a new session.
+
+Longer term: workers should self-monitor. Add to worker personality: "If you notice your responses becoming repetitive or forgetting earlier decisions, immediately use /compact-context before continuing."
+
+#### T2-F2: Session Handoff Protocol `[M]`
+**Dependency:** T2-F1
+**Source:** HIGH-3
+
+When a worker hits context limits mid-task, it should write a handoff file before ending:
+```yaml
+# tasks/handoffs/task-042-handoff.md
+task_id: task-042
+agent: anvil
+handoff_reason: context_limit
+completed_subtasks: [1.1, 1.2]
+remaining_subtasks: [1.3, 2.1]
+last_state: "login form markup done, need to wire submit handler"
+context_dump: |
+  Key files touched: src/components/Login.tsx
+  Pattern used: React Hook Form with Zod validation
+  Next: add onSubmit handler calling POST /api/auth/login
+```
+
+Next agent picks up the handoff instead of starting from scratch.
+
+---
+
+### Workstream G: Dashboard & Observability
+
+#### T2-G1: Fix Dashboard Bugs `[M]`
+**Source:** Pixel (BUG-dash-001, BUG-dash-002)
+
+Known bugs in the Svelte dashboard:
+- BUG-dash-001: Task counts don't update in real time — WebSocket events not triggering reactive updates
+- BUG-dash-002: "Completed" column shows all-time tasks, not just current session
+
+Fix both before adding any new dashboard features.
+
+#### T2-G2: Agent Activity Feed `[M]`
+**Dependency:** T1-D3 (status history wired up)
+**Source:** Pixel
+
+Add a live activity feed to the dashboard: a chronological stream of agent events (task started, task completed, escalation filed, error). Sourced from `status_history` table (once T1-D3 is fixed).
+
+This replaces the need to `tail` log files to understand what the forge is doing.
+
+#### T2-G3: In-Session Agent Menu `[M]`
+**Source:** HIGH-5 (Sentinel)
+Hub has no way to show "which agents are currently active" during a session. Add a `/agents` command to Hub that lists all agents with their current task assignment and status (idle, working, blocked).
+
+---
+
+### Workstream H: Architecture Cleanup
+
+#### T2-H1: Consolidate forge-master / planning-hub `[M]`
+**Source:** Sentinel
+There are references to both "forge-master" and "planning-hub" in personality files and docs. They are the same role. Standardize on one name throughout. Recommended: keep "planning-hub" since it's the canonical agent name in `agents.json`.
+
+#### T2-H2: Daemon Dependency Resolution `[L]`
+**Source:** Furnace (HIGH-2)
+The daemon routes tasks to agents based on `type` field only. Tasks with `blocked_by: [task-041]` are not checked for blockers before assignment — a blocked task can be dispatched before its dependency completes.
+
+**Fix:** When selecting a task from `tasks/pending/`, daemon should:
+1. Check `blocked_by` list in frontmatter
+2. Verify each blocking task is in `tasks/completed/` or `tasks/merged/`
+3. Only dispatch if all blockers are resolved
+
+---
+
+## Tier 3: Strategic Expansion
+
+Large initiatives. Plan before building. Some depend on Tier 2 completion.
+
+### T3-1: Vibe Lab Integration `[XL]`
+**Dependency:** T2-F2 (session handoff protocol), T2-G2 (activity feed)
+
+This is the highest-leverage strategic opportunity. Vibe Lab is a mature Python pipeline (Sentinel service, 9 specialized agents, SQLite pipeline.db, dashboard, MCP server) that handles the CI/CD and release pipeline. Vibe Forge is the development session layer. They are complementary.
+
+**Integration opportunities:**
+
+**A. Planning Hub as Vibe Lab Story Creator**
+Hub's planning mode (T2-E2) should be able to write stories directly to vibe-lab's sprint-status.yaml via MCP. Instead of creating local task files, Hub creates vibe-lab stories that the Sentinel service picks up and dispatches automatically.
+
+```
+Hub: "Okay, I've decomposed this epic into 5 stories. Creating them in vibe-lab now."
+Hub: mcp__vibe-lab__create_story(project_path="...", id="STORY-042", ...)
+```
+
+**B. Forge Daemon Reads vibe-lab Pipeline State**
+Forge daemon currently only knows about local `tasks/` directories. When vibe-lab is present, it should also expose vibe-lab story status in the dashboard — showing the full pipeline from "story in backlog" through "released."
+
+**C. Vibe-lab Agents Spawned via Forge**
+Vibe Lab uses `claude -p` subprocesses for its agents. Forge's `spawn` command (which handles terminal, tab color, personality) could become the launcher for vibe-lab agents, giving them the same session management and visual identity that forge agents have.
+
+**D. Shared Observer**
+A single observer MCP server that both systems publish events to, enabling cross-system dashboarding. Vibe Lab already has its MCP server (`mcp__vibe-lab__*`). Forge adds its events to the same sink.
+
+**Recommended starting point:** Integration A (Hub as story creator) is highest impact, lowest risk. Start there. Read vibe-lab's `_vibe-chain/templates/` to understand the story format, then add MCP calls to Hub.
+
+---
+
+### T3-2: BMAD Planning Phase Port `[XL]`
+**Dependency:** T2-E2 (Hub planning mode)
+
+Once Hub has a planning mode (T2-E2), extend it to implement the full BMAD analysis phase:
+- Analyst agent: extract requirements from user input
+- Product Manager agent: write PRDs with acceptance criteria
+- Architect agent: produce architecture decision records
+
+This would close the largest single gap vs BMAD. It's a significant undertaking — treat it as a separate project with its own epic.
+
+---
+
+### T3-3: Adversarial Review Agent `[L]`
+**Source:** Crucible (BMAD's "adversarial" CodeRabbit pattern)
+
+Add a review agent configured to find problems, not rubber-stamp work. Unlike Sentinel (which checks compliance), this agent actively attempts to break the implementation:
+- Write tests designed to fail
+- Look for edge cases the agent missed
+- Check for security anti-patterns beyond the DoD checklist
+- Report findings even if all ACs technically pass
+
+This is the pattern behind BMAD's high code quality reputation.
+
+---
+
+### T3-4: Multi-Developer Support `[XL]`
+**Source:** HIGH-6 (Sentinel)
+
+Currently, Vibe Forge assumes a single developer running a single forge. Multiple developers sharing a project would have:
+- Racing task assignments (two agents pick the same task)
+- No coordination on which developer's instance is authoritative
+- Dashboard only shows one developer's daemon state
+
+This requires distributed locking (file-based or SQLite WAL), developer identity in task frontmatter, and daemon discovery across machines.
+
+---
+
+## Parallel vs Sequential Summary
+
+```
+Tier 0 (all parallel):
+  T0-1: alias collision fix
+  T0-2: eliminate eval
+  T0-3: pre-commit hooks
+
+Tier 1 (parallel workstreams, sequential within):
+  Workstream A (quality): T1-A1 → T1-A2 → T1-A3
+  Workstream B (DX): T1-B1, T1-B2, T1-B3, T1-B4 (all parallel)
+  Workstream C (tasks): T1-C1 → T1-C3, T1-C2 (independent)
+  Workstream D (daemon): T1-D1, T1-D2 (parallel), then T1-D3
+
+Tier 2 (parallel workstreams, sequential within):
+  Workstream E (planning): T2-E1 → T2-E2 → T2-E3
+  Workstream F (tokens): T2-F1 → T2-F2
+  Workstream G (dashboard): T2-G1 → T2-G2, T2-G3 (independent)
+  Workstream H (arch): T2-H1 (independent), T2-H2 (independent)
+
+Tier 3 (after Tier 2 gates):
+  T3-1: vibe-lab integration (start after T2-F2)
+  T3-2: BMAD planning phase (start after T2-E2)
+  T3-3: adversarial review (independent)
+  T3-4: multi-dev support (independent, large)
+```
+
+---
+
+## Priority Matrix
+
+| ID | Title | Tier | Effort | Parallel With |
+|----|-------|------|--------|---------------|
+| T0-1 | Fix design alias collision | 0 | XS | T0-2, T0-3 |
+| T0-2 | Eliminate eval in config.sh | 0 | M | T0-1, T0-3 |
+| T0-3 | Add pre-commit hooks | 0 | S | T0-1, T0-2 |
+| T1-B1 | Fix README (remove phantom agents) | 1 | XS | All T1 |
+| T1-B2 | Alias collision check in CI | 1 | S | All T1 |
+| T1-B3 | forge init validates agents.json | 1 | XS | All T1 |
+| T1-D1 | Fix daemon date parsing (macOS) | 1 | S | T1-D2 |
+| T1-D2 | Fix stat portability in daemon | 1 | XS | T1-D1 |
+| T1-A1 | Numbered AC enforcement in Sentinel | 1 | S | T1-B*, T1-D* |
+| T1-C3 | attention/ escalation routing | 1 | S | All T1 |
+| T1-B4 | Session anti-pattern guards (Hub) | 1 | S | All T1 |
+| T1-A2 | DoD gate in task flow | 1 | M | After T1-A1 |
+| T1-A3 | HALT conditions in all personalities | 1 | M | All T1 |
+| T1-C1 | Epic/story hierarchy | 1 | M | T1-C2 |
+| T1-C2 | forge-state.yaml sprint summary | 1 | M | T1-C1 |
+| T1-D3 | Wire db_record_status_history | 1 | S | After T1-D1, T1-D2 |
+| T2-G1 | Fix dashboard bugs | 2 | M | T2-H1, T2-F1 |
+| T2-H1 | Consolidate forge-master/hub naming | 2 | S | T2-G1 |
+| T2-F1 | Token budget warnings | 2 | M | T2-G1, T2-H1 |
+| T2-E1 | Context directory bootstrap | 2 | S | T2-F1, T2-G1 |
+| T2-F2 | Session handoff protocol | 2 | M | After T2-F1 |
+| T2-G2 | Agent activity feed | 2 | M | After T1-D3, T2-G1 |
+| T2-E2 | Hub planning mode | 2 | L | After T2-E1 |
+| T2-E3 | Per-project agent customization | 2 | M | After T2-E1 |
+| T2-G3 | In-session agent menu | 2 | M | T2-G2 |
+| T2-H2 | Daemon dependency resolution | 2 | L | T2-E2 |
+| T3-3 | Adversarial review agent | 3 | L | Independent |
+| T3-1 | Vibe Lab integration | 3 | XL | After T2-F2 |
+| T3-2 | BMAD planning phase port | 3 | XL | After T2-E2 |
+| T3-4 | Multi-developer support | 3 | XL | Independent |
+
+---
+
+## Vibe Lab Integration Detail
+
+Vibe Lab (`G:\dev\vibe-lab`) is a production-grade Python pipeline at **v0.20.0**:
+
+### What vibe-lab is
+- **Sentinel service** (Python, Windows NSSM service) — event-driven filesystem watcher, spawns Dispatcher, manages subagent processes deterministically in Python (no LLM PID management), logs to SQLite
+- **10 specialized agents**: Story Factory, Dispatcher, Dev, Arch Review, UX Review, Code Review, Code Review Verifier, Test Runner, Release Manager, Docs
+- **SQLite pipeline.db** — agent runs, token costs, cycle time, story metrics (100+ tests, 18 pytest files)
+- **Hub REST API** on accserver (`https://vibe-dash.local.cogg.haus`) — stories, costs, dispatch, events
+- **Svelte dashboard** with Kanban board (7 columns), story drawer, cost panel, agent activity
+- **Two MCP servers**: local Sentinel MCP (`mcp__vibe-lab__*`, Python FastMCP) + remote Hub MCP (`mcp__vibe-hub__*`, Node.js)
+- **18+ handoff types** with strict YAML frontmatter schema, validation, and deduplication
+- **Per-story git worktrees** for true parallel execution without merge conflicts
+
+### What vibe-lab has that vibe-forge doesn't
+- Deterministic Python process management (SubagentManager — no LLM tracking PIDs)
+- Token tracking and cost aggregation per agent type and per story
+- Story cycle time metrics and full pipeline observability
+- Per-story git worktrees (parallel execution)
+- Formal handoff validation with schema enforcement and deduplication
+- Severity-ranked code review with a dedicated verification pass agent
+- Graceful shutdown, orphan detection, revision-needed back-routing
+- Full CI/CD release pipeline with changelog, semver, and deploy steps
+
+### What vibe-forge has that vibe-lab doesn't
+- Agent personalities (character-driven, UX-rich sessions with icons and tab colors)
+- `--dangerously-skip-permissions` managed startup (no repeated prompts)
+- Windows terminal integration (new window/tab spawning with color)
+- Ralph Loop (Stop hook worker loop) for persistent worker sessions
+- `forge doctor` diagnostics
+- Planning Hub as orchestrator persona
+- Task templates with formal DoD checklists
+
+### The integration thesis
+Vibe Lab owns the **pipeline** (story lifecycle, review, release, CI/CD). Vibe Forge owns the **sessions** (personality, startup UX, worker loop, human-facing monitoring). They are complementary layers — Forge is where humans and agents interact; vibe-lab is where automated execution runs. Wire them so data flows between them; don't merge them.
+
+### Near-term integration (start here): Hub as Story Creator
+When Hub decomposes an epic into stories, it calls `mcp__vibe-lab__create_story` to register them directly in the vibe-lab pipeline:
+
+```
+Hub: "Decomposing epic into 3 stories. Registering in vibe-lab..."
+Hub calls: mcp__vibe-lab__create_story(
+  project_path="G:/dev/vibe-lab",
+  id="STORY-042",
+  title="Add OAuth login",
+  status="ready-for-dev"
+)
+```
+
+Stories created by Hub flow through the full vibe-lab review/release chain automatically. This requires Hub's planning mode (T2-E2) to exist first.
+
+### Mid-term integration: Forge Dashboard shows Pipeline State
+Add a panel to the forge Svelte dashboard that reads vibe-lab status via MCP:
+
+```javascript
+const stories = await mcp.call('mcp__vibe-lab__list_stories', {
+  project_path: 'G:/dev/vibe-lab'
+});
+const sentinel = await mcp.call('mcp__vibe-lab__sentinel_status', {
+  project_path: 'G:/dev/vibe-lab'
+});
+```
+
+One dashboard showing both "what forge workers are doing" and "where the pipeline is."
+
+### Long-term integration: forge spawn targets vibe-lab Agents
+`forge spawn` currently targets agents in `config/agents.json`. Extend to also spawn vibe-lab agents by reading `_vibe-chain/agents/agent-N-*.md` — they'd get the same tab-color and terminal treatment as forge agents.
+
+### MCP tools available right now
+Both MCP servers are already registered in vibe-lab's `.mcp.json` and discoverable in any Claude Code session there:
+
+**Sentinel MCP (local pipeline.db):**
+- `mcp__vibe-lab__list_stories(project_path)` — all stories with status
+- `mcp__vibe-lab__create_story(project_path, id, title, status)` — create story
+- `mcp__vibe-lab__update_story_status(project_path, story_id, status)` — transition
+- `mcp__vibe-lab__list_pending_handoffs(project_path)` — what's waiting
+- `mcp__vibe-lab__sentinel_status(project_path)` — is sentinel running
+- `mcp__vibe-lab__get_agent_stats(project_path)` — token/cost by agent
+- `mcp__vibe-lab__get_pipeline_events(project_path, limit)` — event timeline
+
+**Hub MCP (remote accserver DB):**
+- `mcp__vibe-hub__get_stories(project_id, status)` — filtered story list
+- `mcp__vibe-hub__add_issue(title, description, priority)` — file a bug
+- `mcp__vibe-hub__add_dispatch(instruction, priority)` — trigger work
+- `mcp__vibe-hub__get_costs(project_id)` — token spend breakdown
+- `mcp__vibe-hub__get_active_agents(project_id)` — what's running now

package/docs/security.md

@@ -0,0 +1,144 @@
+# Vibe Forge Security Documentation
+
+This document explains security considerations and intentional design decisions in Vibe Forge.
+
+## The `--dangerously-skip-permissions` Flag
+
+### What It Does
+
+When starting agents, Vibe Forge uses Claude Code's `--dangerously-skip-permissions` flag:
+
+```bash
+claude --dangerously-skip-permissions --system-prompt "$system_prompt" "startup"
+```
+
+This flag disables Claude Code's permission prompts for file operations, command execution, and other actions that would normally require user confirmation.
+
+### Why We Use It
+
+Vibe Forge is designed for **terminal-native vibe coding** - a workflow where you launch multiple AI agents that work autonomously on your codebase. The typical workflow involves:
+
+1. Starting a Planning Hub that coordinates work
+2. Spawning worker agents (frontend, backend, testing, etc.) in separate terminals
+3. Agents working autonomously on assigned tasks
+4. Human review at defined checkpoints
+
+With permission prompts enabled, each agent would constantly interrupt for confirmation, breaking the autonomous workflow that makes Vibe Forge effective.
+
+### Security Mitigations
+
+We implement several security measures to offset the risks:
+
+#### 1. Agent Whitelist Validation
+
+All agent names go through strict whitelist validation before execution:
+
+```bash
+# bin/lib/constants.sh
+VALID_AGENTS=("anvil" "furnace" "crucible" ...)
+
+# bin/lib/agents.sh
+resolve_agent() {
+    local canonical="${AGENT_ALIASES[$normalized]:-}"
+    if [[ -n "$canonical" ]]; then
+        echo "$canonical"
+        return 0
+    fi
+    return 1  # Reject unknown agents
+}
+```
+
+This prevents command injection through agent names.
+
+#### 2. Path Traversal Protection
+
+Personality file paths are validated to ensure they remain within the expected directory:
+
+```bash
+get_agent_personality_path() {
+    local real_path=$(cd "$(dirname "$personality_path")" && pwd)/$(basename "$personality_path")
+    local agents_dir=$(cd "$forge_root/agents" && pwd)
+
+    if [[ "$real_path" != "$agents_dir"/* ]]; then
+        echo "Security error: Path traversal detected" >&2
+        return 1
+    fi
+}
+```
+
+#### 3. Safe JSON Parsing
+
+We use Node.js for JSON parsing instead of `grep`/`cut` which could be vulnerable to injection:
+
+```bash
+json_get_string() {
+    node -e "
+        const fs = require('fs');
+        const data = JSON.parse(fs.readFileSync('$file', 'utf8'));
+        if (data['$key'] !== undefined) console.log(String(data['$key']));
+    "
+}
+```
+
+#### 4. Daemon Security
+
+The background daemon includes multiple protections:
+
+- **Symlink protection**: Skips symlinks to prevent symlink attacks
+- **Path validation**: Verifies destinations are within FORGE_ROOT
+- **Atomic operations**: Uses temp files + move for safe writes
+- **Lock files**: Prevents multiple daemon instances
+- **Log rotation**: Bounded log growth prevents disk exhaustion
+
+### Risks to Be Aware Of
+
+Even with mitigations, understand these risks:
+
+1. **AI agents can modify any file** in your project without confirmation
+2. **AI agents can execute any command** without confirmation
+3. **Malicious prompts** could potentially be injected if context files are compromised
+4. **Network access** is unrestricted - agents could make API calls
+
+### Recommendations
+
+1. **Use in development environments only** - Don't run on production systems
+2. **Use with version control** - Git makes it easy to review and revert changes
+3. **Review at checkpoints** - Check agent work during task transitions
+4. **Understand the personality files** - They define agent behavior
+5. **Keep project context secure** - Don't include secrets in context files
+6. **Run in isolated environments** - Consider containers for sensitive projects
+
+### Alternative: Manual Approval Mode
+
+If you prefer permission prompts, you can modify the agent startup in `bin/forge.sh`:
+
+```bash
+# Change this:
+claude --dangerously-skip-permissions --system-prompt "$system_prompt" "startup"
+
+# To this (removes the flag):
+claude --system-prompt "$system_prompt" "startup"
+```
+
+Note: This will significantly impact the autonomous workflow.
+
+## Reporting Security Issues
+
+If you discover a security vulnerability in Vibe Forge:
+
+1. **Do not open a public issue**
+2. Email security concerns to the maintainers
+3. Include steps to reproduce
+4. Allow time for a fix before public disclosure
+
+## Security Checklist for Contributors
+
+When contributing to Vibe Forge:
+
+- [ ] Never pass user input directly to shell commands
+- [ ] Always validate agent names against the whitelist
+- [ ] Use safe JSON parsing (Node.js, not grep/cut)
+- [ ] Validate file paths don't traverse outside expected directories
+- [ ] Use atomic file operations where race conditions are possible
+- [ ] Add tests for security-sensitive functions
+- [ ] Document any new security considerations