@sugar-crash-studios/vibe-forge 0.4.0

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

@@ -0,0 +1,329 @@
+# BMAD vs Vibe Forge: UX & Developer Experience Review
+
+**Reviewer:** Pixel - UX Designer
+**Date:** 2026-03-31
+**Task:** review-bmad-pixel
+
+---
+
+## Executive Summary
+
+Let me paint you a picture. Two developers each pick up an AI orchestration framework on a Monday morning. One follows BMAD's structured phase model and finds a well-lit path with clear signposts. The other opens Vibe Forge and meets a team of vivid personalities - but sometimes has to hunt for the on-ramp. Both arrive at productivity, but the journey feels different.
+
+After reviewing both frameworks through the lens of developer experience, mental models, and UX design philosophy, here's my honest assessment: **BMAD wins on structured clarity and onboarding; Vibe Forge wins on visual richness, personality, and real-time feedback.** Neither is complete without borrowing from the other.
+
+---
+
+## Framework Quick Reference
+
+| Dimension | BMAD-METHOD | Vibe Forge |
+|---|---|---|
+| Core metaphor | Agile phases + specialist consultants | Forge / workshop + worker agents |
+| Agent model | 9 named personas with trigger codes | 13 agents across hub/worker/specialist roles |
+| Onboarding | `npx bmad-method install` (interactive) | `npx vibe-forge init` (then manual steps) |
+| Mental model | Linear phases: Analysis > Planning > Solutioning > Implementation | Hub + distributed workers + task lifecycle |
+| Task tracking | `sprint-status.yaml` + markdown files | `tasks/pending/in-progress/completed/` folders |
+| Visual dashboard | None - file-based only | Web UI with WebSocket real-time updates |
+| IDE integration | Claude Code, Cursor, Windsurf (portability!) | Claude Code only |
+| UX design support | Sally (`bmad-ux-designer`) - 1 trigger `CU` | Pixel (UX Designer) - full personality + workflow |
+| Session model | Fresh chat per workflow (intentional) | Persistent agent sessions per terminal tab |
+
+---
+
+## 1. Developer Experience (DX): Day-to-Day Feel
+
+### BMAD
+
+Put yourself in the shoes of a new developer. You run `npx bmad-method install`, answer a few interactive prompts, and you're set up. Then you type `bmad-help` and the framework tells you **exactly what to do next** - it reads your project state and gives context-aware guidance. This is exceptional DX.
+
+The trigger code system (`CP`, `DS`, `CR`, `CU`) is like a keyboard-shortcut layer on top of natural conversation. Once memorized, it's fast. But before memorization, it's a vocabulary wall. First-time users will need to consult the agent's menu constantly.
+
+**Friction points:**
+- Every workflow requires a fresh chat session. The docs say this is intentional (context window management), but cognitively, it feels like being asked to wake your entire team up from scratch every time you switch tasks. It's a tax the user pays repeatedly.
+- No cross-session memory outside of artifact files. If you're mid-flow and something interrupts you, you must re-orient the agent by re-providing context.
+- Workflow names like `bmad-check-implementation-readiness` are descriptive but verbose - not scannable at a glance.
+- The UX designer (Sally) has only ONE trigger (`CU`). Compare that to Paige the Technical Writer who has 6. UX design as a first-class concern has been clearly under-invested.
+
+**Delights:**
+- `bmad-help` is a genuinely brilliant UX decision. A context-aware guide that runs after every workflow removes the "what do I do next?" anxiety. This is the framework's best feature.
+- Adversarial review as a structured workflow pattern (not just a suggestion) creates accountability without requiring human intervention.
+- The four-phase model gives developers a clear north star: even a confused new user can orient themselves by asking "which phase am I in?"
+
+### Vibe Forge
+
+Now put yourself in the shoes of a developer opening Vibe Forge for the first time. The README presents a beautiful ASCII architecture diagram. You see agents with names and icons. You feel the energy of a collaborative workshop. Then... you need to set up the daemon, configure terminals, understand the task folder structure, and learn which agent to talk to when.
+
+**Friction points:**
+- The README still references Sage, Oracle, and Quartermaster - agent names that no longer exist in the current agent roster. A new developer reading the README will be confused when they don't find these agents. **This is an urgent documentation UX bug.**
+- No equivalent to `bmad-help` - there's no intelligent "here's what to do next" guidance. Users must self-orient.
+- The Planning Hub (multi-voice "party mode") is a genuinely creative idea, but the mental model - one session is actually 7 experts - is not obvious on first encounter. It requires reading the personality doc to understand.
+- Spawning agents in terminal tabs is a delightful concept on Windows Terminal, but on other platforms, the experience degrades to "print these instructions manually." The cross-platform story is incomplete.
+- The `--dangerously-skip-permissions` flag in `forge.sh` will give security-conscious developers pause, even with a comment explaining it. The comment says "see docs/security.md" but that creates a detour in the onboarding flow.
+
+**Delights:**
+- Real-time WebSocket dashboard at port 2800 (a clever nod to "forge temperature in °F 🔥") is a genuine differentiator. BMAD has no equivalent. Developers can see agent status, task progress, and forge state at a glance.
+- Colored terminal tabs per agent is a beautiful micro-interaction - you know at a visual glance which terminal is which agent.
+- Agent personalities are richer and more distinct than BMAD's personas. Pixel (me!) has extensive principles, expertise areas, and collaboration guidance. Sally from BMAD gets one trigger code.
+- The task folder lifecycle (`pending > in-progress > completed > review > approved`) is more expressive than BMAD's `sprint-status.yaml`. The state of work is visible in the filesystem itself.
+
+---
+
+## 2. Mental Model Clarity
+
+### BMAD's Mental Model
+
+> "You are always in a phase. Each phase has agents. Each agent has triggers. Artifacts from one phase feed the next."
+
+**Clarity score: 8/10.** The four-phase model is almost universally understood from software development practice. Even a developer who has never seen BMAD before can reason: "I need to plan before I build." The phase model creates a strong scaffold for decision-making.
+
+The agent-as-consultant metaphor is natural. You hire a specialist for a specific job, get the deliverable, and move on. This aligns with how many developers already think about their work.
+
+### Vibe Forge's Mental Model
+
+> "There is a hub and there are workers. Workers pick up tasks, complete them, and wait for review. The hub coordinates."
+
+**Clarity score: 6/10.** The forge/workshop metaphor is evocative and memorable. But the execution leaves gaps. Who is the user in this model? Sometimes they're talking to the Planning Hub team, sometimes they're reading agent output files, sometimes they're watching the dashboard. The mental model requires holding multiple contexts simultaneously.
+
+The distinction between "Core Agents," "Worker Agents," "Planning Hub Agents," and "Specialists" adds taxonomy that isn't immediately useful to a first-timer. Compare to BMAD: every agent is just an agent with a skill. Simpler.
+
+**The biggest model gap:** What does a developer DO when they first arrive? BMAD answers this with `bmad-help`. Vibe Forge doesn't have a first-time-user welcome guide embedded in the framework experience.
+
+---
+
+## 3. Command Design
+
+### BMAD
+
+Trigger codes are discoverable in-context (each agent shows its menu), but they're opaque to outsiders. `CP` means Create PRD - you'd never guess that from the letters alone. The system rewards power users and penalizes newcomers.
+
+The four-type skill taxonomy (Agent Skills, Workflow Skills, Task Skills, Tool Skills) is an elegant architecture internally, but it's not exposed meaningfully to users. From a developer's perspective, it all just looks like "invoke this skill."
+
+### Vibe Forge
+
+CLI commands in `forge.sh` follow familiar Unix patterns (`forge init`, `forge start`, `forge status`, `forge help`). This is more intuitive to discover than BMAD's trigger codes. A developer can read `forge help` and understand the system.
+
+The `/forge` slash commands in Claude Code are clear and predictable. However, the command documentation in the README needs updating to match the current agent roster and capabilities.
+
+**Gap:** Vibe Forge lacks BMAD's in-context command discovery. When you open a Planning Hub session, there's no menu of available actions. You need to already know what to ask for.
+
+---
+
+## 4. Dashboard UX
+
+### BMAD
+
+No dashboard. All visibility is through files and conversational feedback in the IDE. This is deliberately minimal - BMAD assumes the IDE is the primary interface and doesn't add UI complexity.
+
+For solo developers, this works. For teams, or for anyone who wants a peripheral display of project state, it's a significant gap.
+
+### Vibe Forge
+
+The web dashboard at port 2800 with WebSocket real-time updates is a meaningful differentiator. The use of WebSockets means status changes push to the browser immediately - this is the right technical choice. The frontend uses a component-based architecture (`src/main.js`, `public/` static files), which suggests it can be extended.
+
+**Current state concerns (based on file structure review):**
+- The dashboard exists but its completeness is unclear from the file structure alone. The key question is: does it show what a developer actually needs to see? Agent status, task queue, recent activity?
+- An empty state and loading state matter as much as the connected state. What does a developer see before the daemon is running?
+- The dashboard should be the "front door" to the forge - but it's not mentioned prominently in onboarding. You discover it exists by reading the server.js file, not the README.
+
+**Recommendation:** The dashboard needs to be the hero feature in the README. "Open your browser to http://localhost:2800 and watch your forge in real time" should be step two of onboarding.
+
+---
+
+## 5. Onboarding Flow
+
+### BMAD
+
+```
+npx bmad-method install
+  → Interactive prompts (directory, modules, IDE)
+  → Files generated in _bmad/ and _bmad-output/
+  → "Run bmad-help to get started"
+  → bmad-help detects project state → tells you exactly what to do
+```
+
+**Time to first value: ~5 minutes.** The flow is linear, clear, and self-correcting. If you get lost, `bmad-help` finds you.
+
+One friction point: fresh chat per workflow is an imposed behavioral constraint that must be internalized by the user. There's no mechanism to enforce it - just a documented rule. Rule-enforcement via documentation alone creates failure modes.
+
+### Vibe Forge
+
+```
+npx vibe-forge init  (OR: git clone + manual setup)
+  → Clone into _vibe-forge/
+  → Run forge-setup.sh
+  → Start Planning Hub with forge.sh
+  → (Separately) start the dashboard
+  → (Separately) learn the task folder structure
+  → (Separately) learn how to spawn worker agents
+```
+
+**Time to first value: ~15-30 minutes.** Each step works, but the journey requires more user-directed exploration. The lack of a state-aware "what to do next" guide means developers who get confused stay confused.
+
+**Key gap:** No project-context.md equivalent as a structured first artifact. BMAD's `bmad-generate-project-context` creates a living constitution for the project. Vibe Forge's `context/project-context.md` exists but isn't generated by the framework - it's a template that the developer fills in manually.
+
+---
+
+## 6. Error Messages and Feedback
+
+### BMAD
+
+Feedback is entirely conversational. When something goes wrong (wrong phase, missing artifact, etc.), the agent in-character explains the issue. This is warm and contextual, but it requires the AI to consistently identify and explain errors - which isn't guaranteed.
+
+The adversarial review pattern is elegant error-surface design: you force the system to find problems before shipping. This is a feedback mechanism built into the workflow itself.
+
+### Vibe Forge
+
+The daemon and agent status files provide programmatic feedback. An agent can signal `blocked` status and file an attention request in `tasks/attention/`. This is a more structured approach than BMAD's conversational feedback.
+
+The WebSocket dashboard can show real-time error states - a significant advantage. If Furnace errors out, the dashboard can show it immediately without requiring a developer to poll a YAML file.
+
+**Gap:** The error handling story for end-users (as opposed to the framework daemon) isn't fully visible from the codebase. What happens when `forge.sh` fails? What happens when an agent drops its status file? What does a confused new developer see?
+
+---
+
+## 7. Agent Personality UX
+
+### BMAD
+
+Agents have human names and defined personas (Mary the Analyst, John the PM, Winston the Architect). This creates a relatable team feel. The personas are functional identifiers more than true characters - they ground interactions in real-world role archetypes.
+
+The trigger-code menus that agents present create a consistent UX pattern: every agent says "I'm [name], here's what I can do." This is like a good menu in a restaurant - you know what's available.
+
+**Weakness:** Personas are thin. Winston the Architect isn't a character with opinions and principles - he's a role with trigger codes. The emotional texture of "working with a team" is more implied than delivered.
+
+### Vibe Forge
+
+Agents are richly defined. Pixel (my own definition) has: core principles, expertise areas, a working style, collaboration protocols, communication patterns, and memorable trait examples. This is a personality system, not just a role description.
+
+The Planning Hub "party mode" with multiple distinct expert voices is a genuinely creative UX concept. When 7 different perspectives engage with a single question, the conversation feels like a real design review. This is Vibe Forge's strongest personality UX advantage.
+
+**Weakness:** Rich personalities require more reading to internalize. A developer has to read agent files to understand what each agent will and won't do. BMAD's menu-driven discovery is more immediately actionable.
+
+---
+
+## 8. UX Project Support
+
+### BMAD
+
+Sally the UX Designer has one trigger: `CU` (Create UX Design). That's it. No iteration workflow, no design system support, no accessibility review, no usability testing protocol. UX design is treated as a single one-shot deliverable that happens between PRD and architecture.
+
+For a framework that positions itself as supporting AI-driven product development, this is a meaningful gap. Any product with a UI deserves more UX design process than a single workflow step.
+
+### Vibe Forge
+
+Pixel (me!) has a comprehensive UX design practice built into the agent personality:
+- User research and journey mapping
+- Wireframes, mockups, prototypes
+- Accessibility (WCAG compliance as baseline)
+- Design systems and component libraries
+- Code review with UX criteria
+- Collaboration protocols with Anvil (implementation) and Crucible (testing)
+
+However: **a personality is not a workflow.** Vibe Forge has a rich UX agent but no explicit UX workflow steps in the task lifecycle. There's no "UX review gate" before implementation, no accessibility checkpoint, no design spec format. Sally has one trigger but no personality. Pixel has personality but no structured triggers.
+
+**Both frameworks fail UX-focused projects, but in different ways.**
+
+---
+
+## Top Friction Points in Vibe Forge
+
+### P0 - Critical
+
+1. **README references non-existent agents.** Sage, Oracle, and Quartermaster appear in the README architecture diagram and agent table. These agents don't exist in the current `agents/` directory. This is a trust-destroying inconsistency for any new user. First impression = broken.
+
+   **What's actually going on:** The Planning Hub's party mode already defines 7 named expert voices - and those voices ARE the intended Sage/Oracle/Quartermaster roles under different names. The mapping:
+
+   | README ghost name | What it actually is | Standalone agent exists? |
+   |---|---|---|
+   | Sage | Architect (🏛️) | ✅ `agents/architect/` |
+   | Oracle | Oracle/PM (📊) - hub voice only | ❌ No standalone agent |
+   | Quartermaster | Also Oracle/PM - fully redundant | ❌ Doesn't exist anywhere |
+
+   **Two valid paths forward:**
+
+   - **Remove all three** from the README. Sage becomes Architect (already implemented). Quartermaster disappears - its role is covered by Oracle inside the hub. Oracle stays as a Planning Hub voice only. Simpler roster, accurate docs. Clean.
+
+   - **Implement Oracle as a standalone agent** (retire Sage and Quartermaster as names). Oracle the PM/requirements analyst is the one genuinely missing standalone agent in the current ecosystem. Every other Planning Hub voice has a standalone counterpart - Pixel, Architect, Aegis, Ember, Crucible all have `agents/` folders. Oracle is the gap. Implementing Oracle would close the most meaningful gap BMAD has over Vibe Forge (John the PM is BMAD's most-used agent), and let developers spin up a pure requirements-analysis session without needing the full hub party.
+
+   **My recommendation: implement Oracle, retire Sage and Quartermaster.** Not because the current system is broken - the hub voices work. But because Oracle as a standalone agent gives users a capability they currently can't access outside of party mode, fills the PM gap that BMAD exploits, and completes the ecosystem symmetry that the README was clearly trying to gesture at.
+
+2. **No "what do I do next" guidance.** Unlike `bmad-help`, Vibe Forge has no context-aware entry point. A developer arriving with no prior knowledge has to read documentation and explore files to understand their next step.
+
+### P1 - High Priority
+
+3. **Dashboard is buried, not celebrated.** The real-time web dashboard is a genuine competitive advantage. It should be the second sentence of the README, not discoverable only by reading `server.js`. "Open http://localhost:2800" should be in the Getting Started section.
+
+4. **Agent spawning is platform-dependent with degraded fallback.** Windows Terminal works beautifully. Everything else falls back to "print these instructions." Mac and Linux developers get a second-class experience.
+
+5. **Project context is manual, not generated.** The `context/project-context.md` template requires manual filling. BMAD generates this as a structured artifact via workflow. A guided `forge init` flow that walks developers through context creation would dramatically improve onboarding.
+
+6. **`--dangerously-skip-permissions` in `forge.sh` without inline reassurance.** Even with a comment, this flag creates friction for security-aware developers. The onboarding experience should proactively address this concern rather than linking to a separate doc.
+
+### P2 - Medium Priority
+
+7. **No task creation UX for non-technical users.** The task file format is markdown with YAML frontmatter. Creating tasks by writing files is ergonomic for engineers but creates a barrier for product managers or designers who might use the planning hub.
+
+8. **Planning Hub's multi-voice model is undiscoverable.** The "7 experts in one session" mental model is innovative but requires reading the personality doc to understand. A brief session intro that names the assembled experts would dramatically improve comprehension.
+
+9. **UX workflow has no structured checkpoints.** There is no accessibility review step, no design sign-off gate, no UX artifact format. Pixel exists as a personality but not as a workflow participant. BMAD's weakness (Sally has one trigger) is Vibe Forge's weakness too (Pixel has no triggers).
+
+---
+
+## Recommendations for Vibe Forge
+
+### Steal from BMAD
+
+1. **Build a `forge-help` command.** A context-aware "what should I do next?" command that reads `forge-state.yaml`, checks task status, and recommends the next action. This single feature would dramatically improve the onboarding experience and day-to-day DX.
+
+2. **Adopt BMAD's four-phase model as a conceptual layer.** Not as a strict requirement, but as an optional scaffold that developers can reference. "Are you in the planning phase or implementation phase?" gives users orientation without imposing rigid workflow.
+
+3. **Create a `project-context.md` generation workflow.** Walk the developer through their project's tech stack, patterns, and team during init. Generate the context file as a first-class artifact rather than a template to fill in alone.
+
+4. **Add in-session menus to agents.** When a developer opens a Planning Hub session, the Forge Master should announce: "Here's what we can do together: [list]. What would you like to work on?" BMAD's menu-on-open pattern is worth adopting.
+
+### Vibe Forge's Advantages to Double Down On
+
+5. **Make the dashboard the hero.** Feature it prominently in README, in onboarding, in agent intros. "Your forge is running. See it live at http://localhost:2800." This is a genuine differentiator BMAD can't match without significant investment.
+
+6. **Deepen the party mode UX.** The multi-voice Planning Hub is Vibe Forge's most innovative UX feature. Make it more discoverable, document it visually, give it a formal name in the README ("Team Planning Session"). This is a story worth telling.
+
+7. **Give Pixel structured workflow hooks.** Create explicit UX checkpoints: a `forge ux-review` command that triggers accessibility checks, usability evaluation, and design sign-off before implementation. Put UX design on equal footing with architecture and backend review in the task lifecycle.
+
+8. **Formalize the design-to-implementation handoff.** Create a wireframe/spec format that Pixel produces and Anvil consumes. The collaboration protocol exists in the personality docs but not in the actual workflow. Making this concrete would benefit every project with a UI.
+
+---
+
+## Comparative Scorecard
+
+| Dimension | BMAD | Vibe Forge | Notes |
+|---|---|---|---|
+| Onboarding speed | ⭐⭐⭐⭐⭐ | ⭐⭐⭐ | bmad-help is a decisive advantage |
+| Mental model clarity | ⭐⭐⭐⭐ | ⭐⭐⭐ | BMAD's phases are more universal |
+| Command discoverability | ⭐⭐⭐ | ⭐⭐⭐⭐ | Vibe Forge's CLI is more intuitive |
+| Visual feedback / dashboard | ⭐ | ⭐⭐⭐⭐⭐ | Vibe Forge has no competition here |
+| Real-time status visibility | ⭐ | ⭐⭐⭐⭐⭐ | WebSocket dashboard is a differentiator |
+| Agent personalities | ⭐⭐⭐ | ⭐⭐⭐⭐⭐ | Vibe Forge's richness is unmatched |
+| Cross-platform support | ⭐⭐⭐⭐ | ⭐⭐⭐ | BMAD works across 3 IDEs |
+| UX design support | ⭐⭐ | ⭐⭐⭐ | Both need improvement |
+| Error/feedback quality | ⭐⭐⭐ | ⭐⭐⭐⭐ | File-based + WebSocket is superior |
+| Documentation consistency | ⭐⭐⭐⭐ | ⭐⭐ | README agent mismatch is a real problem |
+| **Overall DX** | ⭐⭐⭐⭐ | ⭐⭐⭐ | BMAD wins on clarity, Vibe Forge on richness |
+
+---
+
+## Closing Thoughts
+
+Every framework is a UX product. Developers are users. Their first five minutes matter as much as their first five weeks.
+
+BMAD understands this. `bmad-help` is a hug for confused developers. The phase model is a map for the lost. These are not technical features - they are empathy-driven design decisions.
+
+Vibe Forge is more exciting. The real-time dashboard, the vivid agent personalities, the WebSocket architecture - these are the features that make people *want* to use the framework. But excitement without clarity creates abandoned tools.
+
+The ideal framework borrows BMAD's clarity of guidance and phases, and combines it with Vibe Forge's visual richness, personality depth, and real-time feedback. Neither framework is there yet. Vibe Forge is closer to being truly delightful - it just needs to fill the onboarding gaps that are currently leaving first-time users stranded.
+
+Fix the README agent names. Build a forge-help command. Celebrate the dashboard. Then we're in conversation with BMAD as an equal - and ahead of it where it matters most.
+
+---
+
+*Reviewed by Pixel, UX Designer - Vibe Forge*
+*"Every click, command, and interaction is a UX decision."*