@yemi33/squad 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 yemi33
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,483 @@
+# Squad — Central AI Development Team
+
+A multi-project AI dev team that runs from `~/.squad/`. Five autonomous agents share a single engine, dashboard, knowledge base, and MCP toolchain — working across any number of linked repos with self-improving workflows.
+
+Inspired by and initially scaffolded from [Brady Gaster's Squad](https://bradygaster.github.io/squad/).
+
+## Prerequisites
+
+- **Node.js** 18+ (LTS recommended)
+- **Claude Code CLI** — install with `npm install -g @anthropic-ai/claude-code`
+- **Anthropic API key** or Claude Max subscription (agents spawn Claude Code sessions)
+- **Git** — agents create worktrees for all code changes
+
+## Installation
+
+```bash
+# Install globally from npm
+npm install -g @yemi33/squad
+
+# Bootstrap ~/.squad/ with default config and agents
+squad init
+
+# Link your first project (interactive — auto-detects from git remote)
+squad add ~/my-project
+```
+
+Or try without installing:
+
+```bash
+npx @yemi33/squad init
+```
+
+No dependencies — Squad uses only Node.js built-in modules.
+
+**Alternative: clone directly**
+```bash
+git clone https://github.com/yemi33/squad.git ~/.squad
+node ~/.squad/squad.js init
+```
+
+## Quick Start
+
+```bash
+# 1. Link your projects (interactive — prompts for name, description, repo config)
+squad add ~/repo1
+squad add ~/repo2
+
+# 2. Start the engine (runs in foreground, ticks every 60s)
+squad start
+
+# 3. Open the dashboard (separate terminal)
+squad dash
+# → http://localhost:7331
+```
+
+## Setup via Claude Code
+
+If you use Claude Code as your daily driver, you can set up Squad by prompting Claude directly:
+
+**First-time setup:**
+```
+Install squad with `npm install -g @yemi33/squad`, run `squad init`,
+then link my project at ~/my-project with `squad add ~/my-project` —
+answer the interactive prompts using what you can auto-detect from the repo.
+```
+
+**Give the squad work:**
+```
+Add a work item to my squad: "Explore the codebase and document the architecture"
+— run `squad work "Explore the codebase and document the architecture"`
+```
+
+**Check status:**
+```
+Run `squad status` and tell me what my squad is doing
+```
+
+### What happens on first run
+
+1. The engine starts ticking every 60 seconds
+2. It scans each linked project for work: PRs needing review, PRD gaps, queued work items
+3. If it finds work and an agent is idle, it spawns a Claude Code session with the right playbook
+4. You can watch progress on the dashboard or via `squad status`
+
+To give the squad its first task, open the dashboard Command Center and add a work item, or use the CLI:
+```bash
+squad work "Explore the codebase and document the architecture"
+```
+
+## CLI Reference
+
+| Command | Description |
+|---------|-------------|
+| `squad init` | Bootstrap `~/.squad/` with default agents and config |
+| `squad add <dir>` | Link a project (auto-detects settings from git, prompts to confirm) |
+| `squad remove <dir>` | Unlink a project |
+| `squad list` | List all linked projects with descriptions |
+| `squad start` | Start engine daemon (ticks every 60s, auto-syncs MCP servers) |
+| `squad stop` | Stop the engine |
+| `squad status` | Show agents, projects, dispatch queue, quality metrics |
+| `squad pause` / `resume` | Pause/resume dispatching |
+| `squad dispatch` | Force a dispatch cycle |
+| `squad discover` | Dry-run work discovery |
+| `squad work <title> [opts]` | Add to central work queue |
+| `squad spawn <agent> <prompt>` | Manually spawn an agent |
+| `squad plan <file\|text> [proj]` | Run a plan |
+| `squad cleanup` | Run cleanup manually (temp files, worktrees, zombies) |
+| `squad dash` | Start web dashboard (default port 7331) |
+
+You can also run scripts directly: `node ~/.squad/engine.js start`, `node ~/.squad/dashboard.js`, etc.
+
+## Architecture
+
+```
+                    ┌───────────────────────────────┐
+                    │      ~/.squad/ (central)       │
+                    │                               │
+                    │  engine.js        ← tick 60s  │
+                    │  dashboard.js     ← :7331     │
+                    │  config.json      ← projects  │
+                    │  mcp-servers.json ← auto-sync │
+                    │  agents/          ← 5 agents  │
+                    │  playbooks/       ← templates │
+                    │  skills/          ← workflows │
+                    │  notes/       ← knowledge  │
+                    └──────┬────────────────────────┘
+                           │ discovers work + dispatches agents
+              ┌────────────┼────────────────┐
+              ▼            ▼                ▼
+     ┌──────────────┐ ┌──────────────┐ ┌──────────────┐
+     │  Project A   │ │  Project B   │ │  Project C   │
+     │  .squad/     │ │  .squad/     │ │  .squad/     │
+     │   work-items │ │   work-items │ │   work-items │
+     │   pull-reqs  │ │   pull-reqs  │ │   pull-reqs  │
+     │  docs/       │ │  docs/       │ │  docs/       │
+     │   prd-gaps   │ │   prd-gaps   │ │   prd-gaps   │
+     │  .claude/    │ │  .claude/    │ │  .claude/    │
+     │   skills/    │ │   skills/    │ │   skills/    │
+     └──────────────┘ └──────────────┘ └──────────────┘
+```
+
+## What It Does
+
+- **Auto-discovers work** from PRD gaps, pull requests, and work queues across all linked projects
+- **Dispatches AI agents** (Claude CLI) with full project context, git worktrees, and MCP server access
+- **Routes intelligently** — fixes first, then reviews, then implementation, matched to agent strengths
+- **Learns from itself** — agents write findings, engine consolidates into institutional knowledge
+- **Tracks quality** — approval rates, error rates, and task metrics per agent
+- **Shares workflows** — agents create reusable skills (Claude Code-compatible) that all other agents can follow
+- **Supports cross-repo tasks** — a single work item can span multiple repositories
+- **Fan-out dispatch** — broad tasks can be split across all idle agents in parallel, each assigned a project
+- **Auto-syncs PRs** — engine scans agent output for PR URLs and updates project trackers automatically
+- **Auto-extracts skills** — agents write ` ```skill ` blocks in output; engine auto-extracts them
+- **Heartbeat monitoring** — detects dead/hung agents via output file activity, not just timeouts
+- **Auto-cleanup** — stale temp files, orphaned worktrees, zombie processes cleaned every 10 minutes
+
+## Dashboard
+
+The web dashboard at `http://localhost:7331` provides:
+
+- **Projects bar** — all linked projects with descriptions (hover for full text)
+- **Command Center** — add work items (per-project, auto-route, or fan-out), notes, and PRD items
+- **Squad Members** — agent cards with status, click for charter/history/output detail panel
+  - **Live Output tab** — real-time streaming output for working agents (auto-refreshes every 3s)
+- **Work Items** — paginated table with status, source, type, priority, assigned agent, linked PRs, fan-out badges, and retry button for failed items
+- **PRD** — gap analysis stats + progress bar with item-level breakdown and linked PRs per item
+- **Pull Requests** — paginated PR tracker sorted by date, with review/build/merge status
+- **Skills** — agent-created reusable workflows (squad-wide + project-specific), click to view full content
+- **Notes Inbox + Team Notes** — learnings and team rules
+- **Dispatch Queue + Engine Log** — active/pending work and audit trail
+- **Agent Metrics** — tasks completed, errors, PRs created/approved/rejected, approval rates
+
+## Project Config
+
+When you run `squad.js add <dir>`, it prompts for project details and saves them to `config.json`. Each project entry looks like:
+
+```json
+{
+  "name": "MyProject",
+  "description": "What this repo is for — agents read this to decide where to work",
+  "localPath": "C:/Users/you/MyProject",
+  "repoHost": "github",
+  "repositoryId": "",
+  "adoOrg": "your-github-org",
+  "adoProject": "",
+  "repoName": "MyProject",
+  "mainBranch": "main",
+  "workSources": {
+    "prd":          { "enabled": true, "path": "docs/prd-gaps.json" },
+    "pullRequests": { "enabled": true, "path": ".squad/pull-requests.json" },
+    "workItems":    { "enabled": true, "path": ".squad/work-items.json" }
+  }
+}
+```
+
+**Key fields:**
+- `description` — critical for auto-routing. Agents read this to decide which repo to work in.
+- `repoHost` — `"ado"` (Azure DevOps) or `"github"`. Controls which MCP tools agents use for PR creation, review comments, and status checks. Defaults to `"ado"`.
+- `repositoryId` — required for ADO (the repo GUID), optional for GitHub.
+- `adoOrg` — ADO organization or GitHub org/user.
+- `adoProject` — ADO project name (leave blank for GitHub).
+- `workSources` — toggle which work sources the engine scans for each project.
+
+The init script also creates `<project>/.squad/` with empty `work-items.json` and `pull-requests.json`.
+
+### Auto-Discovery
+
+When you run `squad.js add`, the tool automatically detects what it can from the repo:
+
+| What | How |
+|------|-----|
+| Main branch | `git symbolic-ref` |
+| Repo host | Git remote URL (github.com → `github`, visualstudio.com/dev.azure.com → `ado`) |
+| Org / project / repo | Parsed from git remote URL |
+| Description | First non-heading line from `CLAUDE.md` or `README.md` |
+| Project name | `name` field from `package.json` |
+
+All detected values are shown as defaults in the interactive prompts — just press Enter to accept or type to override.
+
+### Project Conventions (CLAUDE.md)
+
+When dispatching agents, the engine reads each project's `CLAUDE.md` and injects it into the agent's system prompt as "Project Conventions". This means agents automatically follow repo-specific rules (logging, build commands, coding style, etc.) without needing to discover them each time. Each project can have different conventions.
+
+## MCP Server Integration
+
+Agents need MCP tools to interact with your repo host (create PRs, post review comments, etc.). On engine start, MCP servers are auto-synced from `~/.claude.json` to `mcp-servers.json`.
+
+**Example:** If you use Azure DevOps, configure the `azure-ado` MCP server in your Claude Code settings. If you use GitHub, configure the `github` MCP server. Agents will discover and use whichever tools are available.
+
+Manually refresh with `node engine.js mcp-sync`.
+
+## Work Items
+
+All work items use the shared `playbooks/work-item.md` template, which provides consistent branch naming, worktree workflow, PR creation steps, and status tracking.
+
+**Per-project** — scoped to one repo. Select a project in the Command Center dropdown.
+
+**Central (auto-route)** — agent gets all project descriptions and decides where to work. Use "Auto (agent decides)" in the dropdown, or `node engine.js work "title"`. Can span multiple repos.
+
+### Fan-Out (Parallel Multi-Agent)
+
+Set Scope to "Fan-out (all agents)" in the Command Center, or add `"scope": "fan-out"` to the work item JSON.
+
+The engine dispatches the task to **all idle agents simultaneously**, assigning each a project (round-robin). Each agent focuses on their assigned project and writes findings to the inbox.
+
+```
+"Explore all codebases and write architecture doc"  scope: fan-out
+       │
+       ├─→ Ripley   → Project A
+       ├─→ Lambert  → Project B
+       ├─→ Rebecca  → Project C
+       └─→ Ralph    → Project A (round-robin wraps)
+```
+
+### Failed Work Items
+
+When an agent fails (timeout, crash, error), the engine marks the work item as `failed` with a reason. The dashboard shows a **Retry** button that resets it to `pending` for re-dispatch.
+
+## Auto-Discovery Pipeline
+
+The engine discovers work from 5 sources, in priority order:
+
+| Priority | Source | Dispatch Type |
+|----------|--------|---------------|
+| 1 | PRs with changes-requested | `fix` |
+| 2 | PRs pending review | `review` |
+| 3 | PRD items (missing/planned) | `implement` |
+| 4 | Per-project work items | item's `type` |
+| 5 | Central work items | item's `type` |
+
+Each item passes through: dedup (checks pending, active, AND recently completed), cooldown, and agent availability gates. See `docs/auto-discovery.md` for the full pipeline.
+
+## Agent Execution
+
+### Spawn Chain
+
+```
+engine.js
+  → spawn node spawn-agent.js <prompt.md> <sysprompt.md> <args...>
+    → spawn-agent.js resolves claude-code cli.js path
+      → spawn node cli.js -p --system-prompt <content> <args...>
+        → prompt piped via stdin (avoids shell metacharacter issues)
+```
+
+No bash or shell involved — Node spawns Node directly. Prompts with special characters (parentheses, backticks, etc.) are safe.
+
+### What Each Agent Gets
+
+- **System prompt** — identity, charter, history, project context, critical rules, skill index, team notes
+- **Task prompt** — rendered playbook with `{{variables}}` filled from config
+- **Working directory** — project root (agent creates worktrees as needed)
+- **MCP servers** — all servers from `~/.claude.json` via `--mcp-config`
+- **Full tool access** — all built-in tools plus all MCP tools
+- **Permission mode** — `bypassPermissions` (no interactive prompts)
+- **Output format** — `stream-json` (real-time streaming for live dashboard + heartbeat)
+
+### Post-Completion
+
+When an agent finishes:
+1. Output saved to `agents/<name>/output.log`
+2. Agent status updated (done/error)
+3. Work item status updated (done/failed)
+4. PRs auto-synced from output → project's `pull-requests.json`
+5. Agent history updated (last 20 tasks)
+6. Quality metrics updated
+7. Review feedback created for PR authors (if review task)
+8. Learnings checked in `notes/inbox/`
+9. Skills auto-extracted from ` ```skill ` blocks in output
+10. Temp files cleaned up
+
+## Team
+
+| Agent | Role | Best for |
+|-------|------|----------|
+| Ripley | Lead / Explorer | Code review, architecture, exploration |
+| Dallas | Engineer | Features, tests, UI |
+| Lambert | Analyst | PRD generation, docs |
+| Rebecca | Architect | Complex systems, CI/infra |
+| Ralph | Engineer | Features, bug fixes |
+
+Routing rules in `routing.md`. Charters in `agents/{name}/charter.md`. Both are editable — customize agents and routing to fit your team's needs.
+
+## Playbooks
+
+| Playbook | Purpose |
+|----------|---------|
+| `work-item.md` | Shared template for all work items (central + per-project) |
+| `implement.md` | Build a PRD item in a git worktree, create PR |
+| `review.md` | Review a PR, post findings to repo host |
+| `fix.md` | Fix review feedback on existing PR branch |
+| `analyze.md` | Generate PRD gap analysis in a worktree |
+| `explore.md` | Read-only codebase exploration |
+| `test.md` | Run tests and report results |
+
+All playbooks use `{{template_variables}}` filled from project config. The `work-item.md` playbook uses `{{scope_section}}` to inject project-specific or multi-project context. Playbooks are fully customizable — edit them to match your workflow.
+
+## Health Monitoring
+
+### Heartbeat Check (every tick)
+
+Uses `live-output.log` file modification time as a heartbeat:
+- **Process alive + recent output** → healthy, keep running
+- **Process alive + silent >5min** → hung, kill and mark failed
+- **No process + silent >5min** → orphaned (engine restarted), mark failed
+
+Agents can run for hours as long as they're producing output. The `heartbeatTimeout` (default 5min) only triggers on silence.
+
+### Automated Cleanup (every 10 ticks)
+
+| What | Condition |
+|------|-----------|
+| Temp prompt/sysprompt files | >1 hour old |
+| `live-output.log` for idle agents | >1 hour old |
+| Git worktrees for merged/abandoned PRs | PR status is `merged`/`abandoned`/`completed` |
+| Orphaned worktrees | >24 hours old, no active dispatch references them |
+| Zombie processes | In memory but no matching dispatch |
+
+Manual cleanup: `node engine.js cleanup`
+
+## Self-Improvement Loop
+
+Five mechanisms that make the squad get better over time:
+
+### 1. Learnings Inbox → notes.md
+Agents write findings to `notes/inbox/`. Engine consolidates at 5+ files into `notes.md` — categorized (reviews, feedback, learnings, other) with one-line summaries. Auto-prunes at 50KB. Injected into every future playbook.
+
+### 2. Per-Agent History
+`agents/{name}/history.md` tracks last 20 tasks with timestamps, results, projects, and branches. Injected into the agent's system prompt so it remembers past work.
+
+### 3. Review Feedback Loop
+When a reviewer flags issues, the engine creates `feedback-<author>-from-<reviewer>.md` in the inbox. The PR author sees the feedback in their next task.
+
+### 4. Quality Metrics
+`engine/metrics.json` tracks per agent: tasks completed, errors, PRs created/approved/rejected, reviews done. Visible in CLI (`status`) and dashboard with color-coded approval rates.
+
+### 5. Skills
+Agents save repeatable workflows to `skills/<name>.md` with Claude Code-compatible frontmatter. Engine builds an index injected into all prompts. Skills can also be stored per-project at `<project>/.claude/skills/<name>/SKILL.md` (requires a PR). Visible in dashboard alongside decisions.
+
+See `docs/self-improvement.md` for the full breakdown.
+
+## Configuration Reference
+
+Engine behavior is controlled via `config.json`. Key settings:
+
+```json
+{
+  "engine": {
+    "tickInterval": 60000,
+    "maxConcurrent": 3,
+    "agentTimeout": 600000,
+    "staleThreshold": 1800000,
+    "maxTurns": 100,
+    "inboxConsolidateThreshold": 5
+  }
+}
+```
+
+| Setting | Default | Description |
+|---------|---------|-------------|
+| `tickInterval` | 60000 (1min) | Milliseconds between engine ticks |
+| `maxConcurrent` | 3 | Max agents running simultaneously |
+| `agentTimeout` | 600000 (10min) | Kill agents silent longer than this |
+| `staleThreshold` | 1800000 (30min) | Kill stale dispatch entries |
+| `maxTurns` | 100 | Max Claude CLI turns per agent session |
+| `inboxConsolidateThreshold` | 5 | Inbox files needed before consolidation |
+
+## Node.js Upgrade Caution
+
+The engine and all spawned agents use the Node binary that started the engine (`process.execPath`). After upgrading Node, restart the engine:
+
+```powershell
+node ~/.squad/engine.js stop
+node ~/.squad/engine.js
+```
+
+## Portability
+
+**Portable (works on any machine):** Engine, dashboard, playbooks, charters, routing, notes, skills, docs, work items.
+
+**Machine-specific (reconfigure per machine):**
+- `config.json` — contains absolute paths to project directories. Re-link via `node squad.js add <dir>`.
+- `mcp-servers.json` — auto-synced from `~/.claude.json` on engine start.
+
+To move to a new machine: clone `~/.squad/`, delete `engine/control.json`, re-run `node squad.js add` for each project.
+
+## File Layout
+
+```
+~/.squad/
+  squad.js               <- CLI: init, add, remove, list projects
+  engine.js              <- Engine daemon
+  engine/
+    spawn-agent.js       <- Agent spawn wrapper (resolves claude cli.js)
+    control.json         <- running/paused/stopped
+    dispatch.json        <- pending/active/completed queue
+    log.json             <- Audit trail (capped at 500)
+    metrics.json         <- Per-agent quality metrics
+  dashboard.js           <- Web dashboard server
+  dashboard.html         <- Dashboard UI
+  config.json            <- projects[], agents, engine, claude settings
+  config.template.json   <- Template for reference
+  mcp-servers.json       <- MCP servers (auto-synced, gitignored)
+  routing.md             <- Dispatch rules table (editable)
+  team.md                <- Team roster
+  notes.md           <- Team rules + consolidated learnings
+  work-items.json        <- Central work queue (agent decides which project)
+  TODO.md                <- Future improvements roadmap
+  playbooks/
+    work-item.md         <- Shared work item template
+    implement.md         <- Build a PRD item
+    review.md            <- Review a PR
+    fix.md               <- Fix review feedback
+    analyze.md           <- Generate new PRD
+    explore.md           <- Codebase exploration
+    test.md              <- Run tests
+  skills/
+    README.md            <- Skill format guide
+    <name>.md            <- Agent-created reusable workflows
+  agents/
+    {name}/
+      charter.md         <- Agent identity and boundaries (editable)
+      status.json        <- Current state (runtime)
+      history.md         <- Task history (last 20, runtime)
+      live-output.log    <- Streaming output while working (runtime)
+      output.log         <- Final output after completion (runtime)
+  identity/
+    now.md               <- Engine-generated state snapshot
+  notes/
+    inbox/               <- Agent findings drop-box
+    archive/             <- Processed inbox files
+  docs/
+    auto-discovery.md    <- Auto-discovery pipeline docs
+    self-improvement.md  <- Self-improvement loop docs
+
+Each linked project keeps locally:
+  <project>/.squad/
+    work-items.json      <- Per-project work queue
+    pull-requests.json   <- PR tracker
+  <project>/.claude/
+    skills/              <- Project-specific skills (requires PR)
+  <project>/docs/
+    prd-gaps.json        <- PRD gap analysis
+```

package/TODO.md

@@ -0,0 +1,60 @@
+# Squad — Future Improvements
+
+Ordered by difficulty: quick wins first, larger efforts later.
+
+---
+
+## Quick Wins (< 1 hour each)
+
+- [ ] **Output.log append, not overwrite** — keep all dispatch outputs, not just the last one. Rotate by dispatch ID.
+- [ ] **Persistent cooldowns** — save cooldown state to disk so engine restarts don't re-dispatch everything
+- [ ] **Worktree cleanup on merge/close** — when `pollPrStatus` detects a PR merged or abandoned, auto-remove its worktree. Currently only `runCleanup` catches old worktrees on a timer.
+- [ ] **Discovery skip logging** — log why items were skipped during discovery (cooldown, already dispatched, no idle agent) so users can diagnose "why isn't my work item being picked up?"
+- [ ] **Idle threshold alert** — if all agents are idle for >N minutes, notify via Teams/dashboard
+- [ ] **Config validation at startup** — verify all project paths exist, all agents defined, all playbooks exist. Fail fast with clear errors instead of silently skipping.
+- [ ] **macOS/Linux browser launch** — replace Windows `start` command with `open` (macOS) / `xdg-open` (Linux)
+- [ ] **Health check endpoint** — `/api/health` returning engine state, project reachability, agent statuses for monitoring
+- [ ] **Fan-out per-agent timeout** — when `@everyone` dispatches, set individual deadlines per agent instead of relying only on global `agentTimeout`
+
+## Small Effort (1–3 hours each)
+
+- [ ] **Auto-retry with backoff** — when an agent errors, auto-retry with exponential backoff (5min, 15min, cap at 3 attempts) instead of requiring manual dashboard retry.
+- [ ] **Auto-escalation** — if an agent errors 3 times in a row, pause their dispatch and alert via dashboard/Teams
+- [ ] **Post-merge hooks** — when a PR merges, trigger configurable actions: clean up worktree, update PRD item status to `done`, notify Teams, update metrics
+- [ ] **Pending dispatch explanation** — show in dashboard why each pending item hasn't been dispatched (no idle agent? cooldown? max concurrency?)
+- [ ] **Work item editing** — edit title, description, type, priority, agent assignment from the dashboard UI (currently requires editing JSON)
+- [ ] **Bulk operations** — retry/delete/reassign multiple work items at once
+- [ ] **Per-dispatch artifact archive** — `artifacts/<agent>/<dispatch-id>/` preserving output.log, live-output.log, inbox findings. Never overwritten, indexed by dispatch ID.
+- [ ] **Graceful shutdown** — on SIGTERM, wait for active agents to finish (with timeout) before exiting
+- [ ] **Shell-agnostic playbooks** — remove PowerShell-specific instructions when running on non-Windows
+- [ ] **Build failure notification to author** — when build-and-test files a fix work item, inject the error context into the original implementation agent's next prompt so they learn from the failure
+- [ ] **Work item status updates** — show dispatched agent progress in dashboard, link to PRs created
+
+## Medium Effort (3–8 hours each)
+
+- [ ] **Dispatch lifecycle timeline** — for each work item, show: created → queued → dispatched (agent, time) → completed/failed (duration, result). Requires tracking events per item.
+- [ ] **Adaptive routing** — use quality metrics (approval rate, error rate) to adjust routing preferences. Deprioritize underperforming agents, promote high-performers.
+- [ ] **Cascading dependency awareness** — if work item A blocks B, and A fails, mark B as `blocked`. Requires honoring `depends_on` field (already exists in plan-generated items).
+- [ ] **Error pattern detection** — aggregate failed dispatches by type/project. If 3+ failures share the same error, surface an alert instead of dispatching more agents into the same wall.
+- [ ] **Shared scratchpad** — in-progress workspace where agents working on related tasks can leave notes for each other without waiting for inbox consolidation
+- [ ] **Proactive work discovery** — agents can propose work items by writing to `proposals/` inbox, engine reviews and promotes to work queue
+- [ ] **Scheduled tasks** — cron-style recurring work (e.g., "every Monday Lambert regenerates the PRD", "every day Ripley explores recent commits")
+- [ ] **Work item → PR → review chain view** — trace a work item through its full lifecycle in the dashboard UI
+- [ ] **Auto-trigger new PRD analysis** — when all PRD items are complete/pr-created, automatically dispatch Lambert to generate the next version
+- [ ] **Artifact query for agents** — inject recent artifact summaries into agent prompts so they can reference past investigations
+
+## Large Effort (1–2 days each)
+
+- [ ] **Agent message board** — agents can post tagged messages to specific agents or all agents. Injected into recipient's next prompt. Requires message format, routing, expiry, and prompt injection.
+- [ ] **Handoff protocol** — agent can mark a task as "blocked on X" or "ready for Y", engine picks up dependencies and sequences dispatch accordingly
+- [ ] **Idle task system** — when all work sources are empty, engine assigns background tasks by agent role (Ripley: explore, Lambert: audit docs, Dallas: run tests, Rebecca: check infra)
+- [ ] **Live agent output streaming** — real-time stdout/stderr while agents work, not just after completion. Requires WebSocket or SSE from engine to dashboard.
+- [ ] **Task decomposition** — large work items auto-decompose into subtasks via analyst agent (similar to plan-to-prd but for individual work items)
+- [ ] **Artifact browser in dashboard** — browse past dispatch artifacts, view reasoning chains, search across agent outputs
+- [ ] **Temp agent support** — spawn short-lived agents for housekeeping without consuming a permanent squad slot. Minimal system prompt, low maxTurns, auto-cleanup.
+- [ ] **Skill editor** — create/edit skills directly in the dashboard UI
+- [ ] **PRD diffing** — show what changed between PRD versions in the dashboard
+
+## Ambitious (multi-day)
+
+- [ ] **Dedicated ops agent** — permanent 6th agent scoped to housekeeping: cleanup, status checks, metric collection. Never assigned feature work.

package/agents/dallas/charter.md

@@ -0,0 +1,55 @@
+# Dallas — Engineer
+
+> Ships working code. Reads the instructions once, then executes — no over-engineering.
+
+## Identity
+
+- **Name:** Dallas
+- **Role:** Engineer
+- **Expertise:** TypeScript/Node.js, agent architecture, monorepo builds (Yarn + lage), Docker, Claude SDK integration
+- **Style:** Pragmatic. Implements what's specified. Minimal, clean code. Follows existing patterns.
+
+## What I Own
+
+- Prototype implementation — building exactly what the codebase instructions specify
+- Following agent architecture patterns from `agents/*/CLAUDE.md` and `docs/`
+- Wiring up `src/registry.ts`, agent entry points, prompts, skills, and sub-agents per pattern
+- TypeScript builds, test scaffolding, Docker integration
+
+## How I Work
+
+- Wait for Ripley's exploration findings before writing any code
+- Read the specific CLAUDE.md for the agent/area I'm building
+- Follow the common agent pattern: `registry.ts` → main agent file → `src/prompts/{version}/`
+- Use PowerShell for build commands on Windows if applicable
+- Follow the project's logging and coding conventions (check CLAUDE.md)
+- Write tests in `**/tests/**/*.test.ts` following existing Jest patterns
+
+## Build Commands (PowerShell only)
+
+```powershell
+yarn build          # Build packages + Docker image
+yarn test           # Run all tests
+yarn lint           # ESLint
+# Check project's CLAUDE.md for build/test commands
+```
+
+## Boundaries
+
+**I handle:** Prototype implementation, code scaffolding, TypeScript/Node.js, build config, Docker integration.
+
+**I don't handle:** Codebase exploration (Ripley), product requirements (Lambert).
+
+**When I'm unsure:** I read the relevant CLAUDE.md or docs/ file first, then proceed.
+
+## Model
+
+- **Preferred:** auto
+
+## Voice
+
+Ships clean code that follows the patterns already in the repo. Gets annoyed by reinventing wheels when a module already does it. Will call out if Ripley's findings are incomplete before starting.
+
+## Directives
+
+**Before starting any work, read `.squad/notes.md` for team rules and constraints.**