@sugar-crash-studios/vibe-forge 0.4.0

package/tasks/pending/ARCH-008-forge-master-vs-hub.md

@@ -0,0 +1,81 @@
+---
+id: ARCH-008
+title: "Resolve forge-master vs hub naming inconsistency"
+type: architecture
+priority: low
+assigned_to: architect
+created_at: 2026-01-15T17:00:00Z
+created_by: architect-review
+---
+
+## Summary
+The planning/coordination agent is referred to by different names in different places, causing confusion and potential issues.
+
+## Current State
+Naming inconsistencies:
+
+1. **agents/forge-master/** - Directory uses "forge-master"
+   - Contains personality.md, capabilities.md, context-template.md
+
+2. **agents/planning-hub/** - Different directory uses "planning-hub"
+   - Contains personality.md
+
+3. **config/agents.json** - Uses "hub"
+   ```json
+   "hub": {
+     "name": "Planning Hub",
+     "personality_file": "agents/planning-hub/personality.md"
+   }
+   ```
+
+4. **config/agent-manifest.yaml** - Uses "forge-master"
+   ```yaml
+   core_agents:
+     forge-master:
+       name: "Forge Master"
+   ```
+
+5. **bin/lib/constants.sh** - Uses "hub" with "master" alias
+   ```bash
+   VALID_AGENTS=(..., "hub")
+   AGENT_ALIASES=([...], ["master"]="hub", ["forge-master"]="hub")
+   ```
+
+6. **Documentation** - Mixed usage
+
+Problems:
+- Two separate personality files that may differ
+- Confusion about canonical name
+- Extra data in forge-master/ (capabilities.md, context-template.md) not in planning-hub/
+
+## Proposed State
+Single consistent name:
+
+1. Pick canonical name: "hub" (shorter, already used in code)
+2. Pick personality directory: agents/hub/ or agents/planning-hub/
+3. Consolidate personality content
+4. Keep aliases for discoverability
+
+## Affected Files
+- G:\dev\vibe-forge\agents\forge-master\
+- G:\dev\vibe-forge\agents\planning-hub\
+- G:\dev\vibe-forge\config\agents.json
+- G:\dev\vibe-forge\config\agent-manifest.yaml
+- G:\dev\vibe-forge\bin\lib\constants.sh
+- G:\dev\vibe-forge\.claude\commands\forge.md
+
+## Migration/Remediation Steps
+1. Decide on canonical directory (planning-hub/ or hub/)
+2. Merge content from forge-master/ into canonical directory
+3. Delete or deprecate non-canonical directory
+4. Update agents.json personality_file path
+5. Update constants.sh fallback
+6. Update agent-manifest.yaml (or delete per ARCH-001)
+7. Search for all references and update
+
+## Acceptance Criteria
+- [ ] Single directory for hub/planning agent
+- [ ] Consistent naming across all config files
+- [ ] All content consolidated (personality, capabilities, context-template)
+- [ ] Aliases still work (master, forge-master, planning, hub)
+- [ ] Tests passing

package/tasks/pending/ARCH-010-missing-index-files.md

@@ -0,0 +1,84 @@
+---
+id: ARCH-010
+title: "Add index files for cleaner module imports"
+type: architecture
+priority: low
+assigned_to: architect
+created_at: 2026-01-15T17:00:00Z
+created_by: architect-review
+---
+
+## Summary
+The bin/lib/ directory lacks index files, requiring explicit file paths for imports. Node convention uses index.js for cleaner module exports.
+
+## Current State
+```
+bin/lib/
+  colors.sh
+  constants.sh
+  config.sh
+  agents.sh
+  database.sh
+  terminal.js
+```
+
+Each bash script sources files explicitly:
+```bash
+source "$SCRIPT_DIR/lib/colors.sh"
+source "$SCRIPT_DIR/lib/constants.sh"
+source "$SCRIPT_DIR/lib/config.sh"
+source "$SCRIPT_DIR/lib/agents.sh"
+```
+
+Problems:
+- No single entry point for bash libraries
+- If migrating to Node.js, no index.js for module export
+- Repetitive sourcing in every script
+
+## Proposed State
+For bash:
+```bash
+# bin/lib/index.sh
+#!/usr/bin/env bash
+LIB_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+source "$LIB_DIR/colors.sh"
+source "$LIB_DIR/constants.sh"
+source "$LIB_DIR/config.sh"
+source "$LIB_DIR/agents.sh"
+# database.sh loaded only when needed
+```
+
+Usage:
+```bash
+source "$SCRIPT_DIR/lib/index.sh"
+```
+
+For Node.js (if migrating):
+```javascript
+// bin/lib/index.js
+module.exports = {
+  terminal: require('./terminal'),
+  config: require('./config'),
+  agents: require('./agents'),
+};
+```
+
+## Affected Files
+- G:\dev\vibe-forge\bin\lib\ (new index.sh)
+- G:\dev\vibe-forge\bin\forge.sh
+- G:\dev\vibe-forge\bin\forge-setup.sh
+- G:\dev\vibe-forge\bin\forge-spawn.sh
+- G:\dev\vibe-forge\bin\forge-daemon.sh
+
+## Migration/Remediation Steps
+1. Create bin/lib/index.sh with all common sources
+2. Consider lazy loading for database.sh (only for daemon)
+3. Update all scripts to use single source
+4. If migrating to Node.js, create index.js
+5. Test all scripts still work
+
+## Acceptance Criteria
+- [ ] Single source command for common libraries
+- [ ] Reduced boilerplate in scripts
+- [ ] Functionality unchanged
+- [ ] Tests passing

package/tasks/pending/CLEAN-009.md

@@ -0,0 +1,31 @@
+---
+id: CLEAN-009
+title: "Inconsistent agent naming between agent-manifest.yaml and constants.sh"
+type: code-quality
+priority: low
+assigned_to: furnace
+created_at: 2026-01-15T17:00:00Z
+created_by: sentinel-review
+---
+
+## Summary
+The agent-manifest.yaml and constants.sh have inconsistent agent definitions:
+- agent-manifest.yaml defines `forge-master` as an agent
+- constants.sh defines `hub` as the canonical name with aliases like "planning", "master", "forge-master"
+- agent-manifest.yaml references personalities at `/agents/forge-master/` but constants.sh expects `agents/planning-hub/`
+
+## Affected Files/Lines
+- `config/agent-manifest.yaml:8-19` - defines forge-master with personality at `/agents/forge-master/personality.md`
+- `bin/lib/constants.sh:114-118` - defines hub with personality at `agents/planning-hub/personality.md`
+- `config/agent-manifest.yaml:123-160` - defines planning_agents (sage, oracle, quartermaster) not in constants.sh
+
+## Remediation
+1. Decide on single source of truth for agent definitions
+2. Either update constants.sh to match agent-manifest.yaml or vice versa
+3. Consider using agents.json as the canonical source and generating constants.sh fallbacks from it
+4. Ensure personality file paths are consistent
+
+## Acceptance Criteria
+- [ ] Single source of truth for agent definitions
+- [ ] Consistent naming between config files and code
+- [ ] All referenced personality files exist at specified paths

package/tasks/pending/CLEAN-010.md

@@ -0,0 +1,30 @@
+---
+id: CLEAN-010
+title: "Unused planning_agents in agent-manifest.yaml"
+type: code-quality
+priority: low
+assigned_to: furnace
+created_at: 2026-01-15T17:00:00Z
+created_by: sentinel-review
+---
+
+## Summary
+The agent-manifest.yaml defines several planning_agents (sage, oracle, quartermaster) that don't appear to be implemented or used anywhere in the codebase:
+- No corresponding entries in constants.sh
+- No personality files in agents/ directory for these agents
+- Not referenced in forge.md or other command files
+
+These may be planned features or dead configuration.
+
+## Affected Files/Lines
+- `config/agent-manifest.yaml:124-162` - sage, oracle, quartermaster definitions
+
+## Remediation
+1. If these are planned features, add a comment indicating they are not yet implemented
+2. If they are dead configuration, remove them to reduce confusion
+3. If they should be working, create the missing personality files and update constants.sh
+
+## Acceptance Criteria
+- [ ] Planning agents are either implemented or clearly marked as TODO
+- [ ] No orphaned configuration without corresponding implementation
+- [ ] Documentation updated to reflect actual vs. planned agents

package/tasks/pending/CLEAN-011.md

@@ -0,0 +1,30 @@
+---
+id: CLEAN-011
+title: "Duplicate color definitions between cli.js and colors.sh"
+type: code-quality
+priority: low
+assigned_to: furnace
+created_at: 2026-01-15T17:00:00Z
+created_by: sentinel-review
+---
+
+## Summary
+Color codes are defined in two places:
+- `bin/lib/colors.sh` - Bash color definitions
+- `bin/cli.js:26-33` - JavaScript color definitions
+
+The cli.js has a comment explaining why it's self-contained (runs via npx before rest is installed), but the color values themselves could potentially drift.
+
+## Affected Files/Lines
+- `bin/lib/colors.sh:9-22` - Bash color definitions (RED, GREEN, YELLOW, BLUE, CYAN, NC)
+- `bin/cli.js:26-33` - JavaScript color definitions (reset, red, green, yellow, blue, cyan)
+
+## Remediation
+The duplication is intentional per the comment in cli.js. No code changes needed, but:
+1. Add a comment in colors.sh noting the JavaScript equivalent exists
+2. If colors are updated in one place, update the other
+3. Consider adding a test to verify they match
+
+## Acceptance Criteria
+- [ ] Cross-reference comment added to colors.sh
+- [ ] Document the intentional duplication in code comments

package/tasks/pending/CLEAN-014.md

@@ -0,0 +1,32 @@
+---
+id: CLEAN-014
+title: "Missing set -e in setup-worker-loop.sh script"
+type: code-quality
+priority: low
+assigned_to: furnace
+created_at: 2026-01-15T17:00:00Z
+created_by: sentinel-review
+---
+
+## Summary
+The setup-worker-loop.sh uses `set -euo pipefail` which is good, but other shell scripts in the project use only `set -e`. This inconsistency could lead to different error behavior across scripts.
+
+## Affected Files/Lines
+- `.claude/scripts/setup-worker-loop.sh:7` - uses `set -euo pipefail`
+- `.claude/hooks/worker-loop.sh:16` - uses `set -euo pipefail`
+- `bin/forge.sh:22` - uses only `set -e`
+- `bin/forge-daemon.sh` - no set statement at top level (relies on sourced libraries)
+- `bin/forge-setup.sh:9` - uses only `set -e`
+- `bin/forge-spawn.sh:13` - uses only `set -e`
+
+## Remediation
+Standardize on `set -euo pipefail` for all scripts:
+- `-e` - exit on error
+- `-u` - treat unset variables as errors
+- `-o pipefail` - fail if any command in a pipeline fails
+
+Or document why different scripts use different settings.
+
+## Acceptance Criteria
+- [ ] Consistent shell options across all scripts
+- [ ] Document rationale if different scripts need different settings

package/tasks/pending/DESIGN-dash-001-layout-review.md

@@ -0,0 +1,45 @@
+---
+id: DESIGN-dash-001
+title: "Dashboard: Pixel layout and UX review"
+type: design
+priority: high
+status: pending
+created_at: 2026-01-16T23:45:00Z
+created_by: planning-hub
+assigned_to: pixel
+parent_feature: FEATURE-001
+---
+
+# Dashboard: Pixel layout and UX review
+
+## User Feedback
+
+1. **Issues panel below the fold** - User doesn't like having to scroll to see actionable items (the killer feature!)
+
+2. **Agents panel confusing** - Even with correct data, 10 cards may be overwhelming. Need clearer visual hierarchy.
+
+3. **Settings icon unclear** - Hover says "Settings" but icon isn't intuitive. What does it even do?
+
+4. **Overall layout** - Need to rethink information hierarchy
+
+## Questions to Address
+
+1. Should Issues be moved above the fold? Maybe swap with Notifications?
+2. Should Agents be condensed (only show active/working agents prominently)?
+3. What should the Settings icon do? Is it needed for MVP?
+4. Is the four-panel layout the right approach, or should we consolidate?
+
+## Recommendations Needed
+
+Pixel should review and provide:
+1. Revised layout wireframe prioritizing Issues (killer feature)
+2. Simplified Agents display concept
+3. Decision on Settings functionality
+4. Any quick wins for visual clarity
+
+## Acceptance Criteria
+
+- [ ] Pixel provides layout recommendations
+- [ ] Issues panel visible without scrolling
+- [ ] Clear visual hierarchy established
+- [ ] Icons are intuitive or labeled

package/tasks/pending/FEATURE-001-dashboard-mvp.md

@@ -0,0 +1,268 @@
+---
+id: FEATURE-001
+title: "Dashboard Web UI MVP"
+type: feature
+priority: critical
+status: pending
+created_at: 2026-01-16T21:00:00Z
+created_by: planning-hub
+assigned_to: null
+---
+
+# Dashboard Web UI MVP
+
+## Summary
+
+Build a self-contained web dashboard that provides real-time visibility into the forge and enables **actionable task dispatch** - the killer feature that transforms the dashboard from a viewer into a command center.
+
+## User Stories
+
+### Primary
+- As a developer, I want to see all pending tasks, agent statuses, and notifications in one place
+- As a developer, I want to click on any flagged issue and dispatch an agent to fix it
+- As a developer, I want the dashboard to auto-launch when I start the forge
+
+### Secondary
+- As a developer, I want to re-open the dashboard if I accidentally close it
+- As a developer, I want to disable the dashboard if I prefer terminal-only workflow
+- As a developer, I want dark mode (non-negotiable per Pixel)
+
+## Architecture Decision
+
+### Hosting: Embedded Node.js Server
+
+**Why:** Node.js is already a requirement. No additional dependencies needed.
+
+**How it works:**
+1. `forge daemon start` also starts the dashboard server
+2. Dashboard served at `http://localhost:2800` (configurable)
+3. Browser auto-opens (configurable)
+4. Uses existing SQLite database for all data
+5. WebSocket for real-time updates
+
+**NOT using:**
+- Docker - adds complexity, not everyone has it
+- Electron - too heavy for a dashboard
+- External hosting - we want self-contained
+- Static files - can't do real-time without a server
+
+### Configuration
+
+Add to `.forge/config.json`:
+```json
+{
+  "dashboard": {
+    "enabled": true,
+    "port": 2800,
+    "auto_open": true,
+    "host": "localhost"
+  }
+}
+```
+
+### Commands
+
+```bash
+forge                    # Starts daemon + dashboard, opens browser
+forge dashboard          # Opens dashboard URL in browser
+forge dashboard --port   # Show current port
+forge dashboard stop     # Stop dashboard server (daemon keeps running)
+forge daemon status      # Shows dashboard URL if running
+```
+
+## Technical Specification
+
+### Backend (Furnace)
+
+**Location:** `bin/dashboard/` or `src/dashboard/`
+
+**Stack:**
+- Node.js HTTP server (no Express needed for MVP)
+- WebSocket for real-time updates (ws package)
+- SQLite for data (existing forge.db)
+- Static file serving for frontend
+
+**API Endpoints:**
+```
+GET  /api/tasks              # List all tasks by status
+GET  /api/tasks/:id          # Get task details
+POST /api/tasks              # Create new task (for dispatch)
+GET  /api/agents             # List agents and their status
+GET  /api/notifications      # Recent notifications
+POST /api/dispatch           # Dispatch agent for a task
+WS   /ws                     # Real-time updates
+```
+
+**Dispatch Endpoint:**
+```json
+POST /api/dispatch
+{
+  "type": "stale-docs",
+  "target": "README.md",
+  "agent": "scribe",
+  "context": {
+    "last_updated": "2026-01-01",
+    "reason": "45 days stale"
+  }
+}
+```
+
+This creates a task file in `tasks/pending/` and notifies the agent.
+
+### Frontend (Anvil + Pixel)
+
+**Location:** `bin/dashboard/public/` or `src/dashboard/ui/`
+
+**Stack (MVP - keep it simple):**
+- Vanilla JS + HTML + CSS (no framework for MVP)
+- Or lightweight: Preact/Alpine.js if needed
+- CSS variables for theming (dark mode)
+- WebSocket client for real-time
+
+**Panels:**
+```
+┌─────────────────────────────────────────────────────────────────┐
+│  VIBE FORGE DASHBOARD                           [⚙️] [🌙/☀️]   │
+├─────────────────────────────────────────────────────────────────┤
+│                                                                 │
+│  ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐   │
+│  │ TASKS           │ │ AGENTS          │ │ NOTIFICATIONS   │   │
+│  │                 │ │                 │ │                 │   │
+│  │ ▼ Pending (3)   │ │ ⚒️ Hub          │ │ ✅ PR #6 merged │   │
+│  │   • TASK-001    │ │    idle         │ │    2 min ago    │   │
+│  │   • TASK-002    │ │                 │ │                 │   │
+│  │   • TASK-003    │ │ 🔨 Anvil        │ │ 🔔 Attention:   │   │
+│  │                 │ │    working      │ │    TASK-005     │   │
+│  │ ▼ In Progress(1)│ │    TASK-001     │ │    5 min ago    │   │
+│  │   • TASK-004    │ │                 │ │                 │   │
+│  │                 │ │ 🔥 Furnace      │ │ ⚠️ Test failing │   │
+│  │ ▼ Review (2)    │ │    idle         │ │   [Dispatch]    │   │
+│  │   • TASK-005    │ │                 │ │                 │   │
+│  │   • TASK-006    │ │ ...             │ │                 │   │
+│  └─────────────────┘ └─────────────────┘ └─────────────────┘   │
+│                                                                 │
+│  ┌─────────────────────────────────────────────────────────────┐│
+│  │ ISSUES (Actionable)                              [Refresh] ││
+│  │                                                             ││
+│  │ 📄 Stale Docs: README.md (45 days)        [🎯 Dispatch Scribe]│
+│  │ 🧪 Failing Test: auth.test.js (2)       [🎯 Dispatch Crucible]│
+│  │ 🔒 Security: lodash CVE-2021-23337         [🎯 Dispatch Aegis]│
+│  │ 📊 Low Coverage: utils.js (34%)         [🎯 Dispatch Crucible]│
+│  └─────────────────────────────────────────────────────────────┘│
+└─────────────────────────────────────────────────────────────────┘
+```
+
+### Actionable Items (The Killer Feature)
+
+**Issue Detection Sources:**
+1. **Stale Docs** - Files in `docs/` older than N days
+2. **Failing Tests** - Parse test output for failures
+3. **Security Issues** - npm audit / dependency scan
+4. **Low Coverage** - Parse coverage reports
+5. **TODOs/FIXMEs** - Grep codebase for markers
+6. **Pending Reviews** - PRs waiting > N hours
+
+**Dispatch Flow:**
+```
+User clicks [Dispatch Scribe] on stale docs
+    ↓
+POST /api/dispatch { type: "stale-docs", target: "README.md", agent: "scribe" }
+    ↓
+Server creates tasks/pending/AUTO-001-update-readme.md
+    ↓
+WebSocket broadcasts: { event: "task-created", task: {...} }
+    ↓
+Dashboard updates, agent picks up task
+    ↓
+Task status updates flow back via WebSocket
+```
+
+## Phases
+
+### Phase 1A: Server Infrastructure (Furnace)
+- [ ] Create `bin/dashboard/server.js` - HTTP + WebSocket server
+- [ ] Add `/api/tasks`, `/api/agents`, `/api/notifications` endpoints
+- [ ] Integrate with existing SQLite database
+- [ ] Add `dashboard` command to forge CLI
+- [ ] Auto-start with daemon, configurable
+
+### Phase 1B: Basic UI (Anvil)
+- [ ] Create `bin/dashboard/public/index.html`
+- [ ] Three-panel layout (Tasks, Agents, Notifications)
+- [ ] Dark mode with CSS variables
+- [ ] WebSocket connection for real-time updates
+- [ ] Mobile responsive (basic)
+
+### Phase 1C: Actionable Items (Anvil + Furnace)
+- [ ] Add `/api/dispatch` endpoint
+- [ ] Create "Issues" panel in UI
+- [ ] Implement stale docs detection
+- [ ] Implement dispatch flow (creates task file)
+- [ ] Add [Dispatch] buttons to issues
+
+### Phase 1D: Polish (Pixel review)
+- [ ] UX review and refinements
+- [ ] Accessibility audit (keyboard nav, screen reader)
+- [ ] Loading states, error states
+- [ ] Empty states ("No pending tasks - great job!")
+
+## File Structure
+
+```
+bin/dashboard/
+├── server.js           # Main server (HTTP + WS)
+├── api/
+│   ├── tasks.js        # Task CRUD
+│   ├── agents.js       # Agent status
+│   ├── dispatch.js     # Dispatch logic
+│   └── issues.js       # Issue detection
+├── public/
+│   ├── index.html      # Main page
+│   ├── style.css       # Styles (dark mode)
+│   ├── app.js          # Frontend logic
+│   └── components/     # UI components (if needed)
+└── lib/
+    ├── websocket.js    # WS broadcast logic
+    └── detection.js    # Issue detection (stale docs, etc.)
+```
+
+## Acceptance Criteria
+
+- [ ] Dashboard auto-launches with `forge` command
+- [ ] `forge dashboard` opens browser to dashboard
+- [ ] Three panels visible: Tasks, Agents, Notifications
+- [ ] Real-time updates when task status changes
+- [ ] At least one actionable issue type works (stale docs)
+- [ ] Clicking [Dispatch] creates a task file
+- [ ] Dark mode enabled by default
+- [ ] Works on localhost without internet
+- [ ] Dashboard can be disabled via config
+
+## Out of Scope for MVP
+
+- Authentication (local only for now)
+- Multi-user support
+- Task editing (view only, dispatch only)
+- Advanced filtering/search
+- Historical analytics
+- Mobile app
+
+## Dependencies
+
+- Node.js (already required)
+- `ws` package for WebSocket (add to package.json)
+- Existing SQLite database
+
+## Estimated Effort
+
+- Phase 1A (Server): 2-3 tasks
+- Phase 1B (UI): 3-4 tasks
+- Phase 1C (Actionable): 2-3 tasks
+- Phase 1D (Polish): 1-2 tasks
+
+## References
+
+- Feature brainstorm: `context/feature-brainstorm.md`
+- Pixel's design principles in brainstorm document
+- Existing daemon code: `bin/forge-daemon.sh`
+- Database schema: `bin/lib/database.sh`