@yemi33/squad 0.1.0

package/docs/self-improvement.md

@@ -0,0 +1,277 @@
+# Self-Improvement Loop
+
+How the squad learns from its own work and gets better over time.
+
+## Overview
+
+The squad has four self-improvement mechanisms that form a continuous feedback loop:
+
+```
+Agent completes task
+  │
+  ├─ 1. Learnings Inbox        → notes.md (all future agents see it)
+  ├─ 2. Per-Agent History       → history.md (agent sees its own past)
+  ├─ 3. Review Feedback Loop    → author gets reviewer's findings
+  └─ 4. Quality Metrics         → engine/metrics.json (tracks performance)
+```
+
+## 1. Learnings Inbox → notes.md
+
+**The core loop.** Every playbook instructs agents to write findings to `notes/inbox/`. The engine consolidates these into `notes.md`, which is injected into every future playbook prompt.
+
+### Flow
+
+```
+Agent finishes task
+  → writes notes/inbox/<agent>-<date>.md
+  → engine checks inbox on each tick
+  → at 5+ files: consolidateInbox() runs
+  → items categorized (reviews, feedback, learnings, other)
+  → summary appended to notes.md
+  → originals moved to notes/archive/
+  → notes.md injected into every future agent prompt
+```
+
+### Smart Consolidation
+
+The engine doesn't just dump files — it categorizes them:
+- **Reviews** — files containing "review" or PR references
+- **Feedback** — review feedback files for authors
+- **Learnings** — build summaries, explorations, implementation notes
+- **Other** — everything else
+
+Each category gets a header with item count and one-line summaries.
+
+### Auto-Pruning
+
+When `notes.md` exceeds 50KB, the engine prunes old consolidation sections, keeping the header and last 8 consolidations. This prevents the file from growing unbounded while retaining recent institutional knowledge.
+
+## 2. Per-Agent History
+
+Each agent maintains a `history.md` file that tracks its last 20 tasks. This is injected into the agent's system prompt so it knows what it did recently.
+
+### Flow
+
+```
+Agent finishes task
+  → engine calls updateAgentHistory()
+  → prepends entry to agents/<name>/history.md
+  → trims to 20 entries
+  → next time agent spawns: history.md injected into system prompt
+```
+
+### What's tracked per entry
+
+- Timestamp
+- Task description
+- Type (implement, review, fix, explore)
+- Result (success/error)
+- Project name
+- Branch name
+- Dispatch ID
+
+### Why it matters
+
+Without history, an agent has no memory. It might:
+- Re-explore code it already explored yesterday
+- Repeat mistakes it made last session
+- Not know that it already has a PR open for a similar feature
+
+With history, the agent sees "I already implemented M005 yesterday (success)" and can build on that context.
+
+## 3. Review Feedback Loop
+
+When a reviewer (e.g., Ripley) reviews a PR and writes findings, the engine automatically creates a feedback file for the PR author (e.g., Dallas) in the inbox.
+
+### Flow
+
+```
+Ripley reviews Dallas's PR
+  → writes notes/inbox/ripley-review-pr123-2026-03-12.md
+  → engine detects review completion
+  → updatePrAfterReview() runs
+  → createReviewFeedbackForAuthor() runs
+  → creates notes/inbox/feedback-dallas-from-ripley-pr123-2026-03-12.md
+  → next consolidation: feedback appears in notes.md
+  → Dallas's next task: he sees what Ripley flagged
+```
+
+### What the feedback file contains
+
+```markdown
+# Review Feedback for Dallas
+
+**PR:** PR-123 — Add retry logic
+**Reviewer:** Ripley
+**Date:** 2026-03-12
+
+## What the reviewer found
+<full content of Ripley's review>
+
+## Action Required
+Read this feedback carefully. When you work on similar tasks
+in the future, avoid the patterns flagged here.
+```
+
+### Why it matters
+
+Without this, review findings only exist in the inbox file under the reviewer's name. The author never explicitly sees them unless they happen to read the consolidated notes.md. The feedback loop ensures the author gets a direct, targeted learning from every review.
+
+## 4. Quality Metrics
+
+The engine tracks per-agent performance metrics in `engine/metrics.json`. Updated after every task completion and PR review.
+
+### Metrics tracked
+
+| Metric | Updated when |
+|--------|-------------|
+| `tasksCompleted` | Agent exits with code 0 |
+| `tasksErrored` | Agent exits with non-zero code |
+| `prsCreated` | Agent completes an implement task |
+| `prsApproved` | Reviewer approves the agent's PR |
+| `prsRejected` | Reviewer requests changes on the agent's PR |
+| `reviewsDone` | Agent completes a review task |
+| `lastTask` | Every completion |
+| `lastCompleted` | Every completion |
+
+### Where metrics are visible
+
+- **CLI:** `node engine.js status` shows a metrics table
+- **Dashboard:** "Agent Metrics" section with approval rates color-coded (green ≥70%, red <70%)
+
+### Sample output
+
+```
+Metrics:
+  Agent        Done   Err    PRs    Approved   Rejected   Reviews
+  ----------------------------------------------------------
+  dallas       12     1      8      6 (75%)    2          0
+  ripley       0      0      0      0 (-)      0          10
+  ralph        5      0      4      3 (75%)    1          0
+  rebecca      3      0      2      2 (100%)   0          0
+  lambert      2      0      0      0 (-)      0          4
+```
+
+### Future use
+
+Metrics are currently informational — displayed in status and dashboard. Planned uses:
+- **Routing adaptation:** If an agent's approval rate drops below a threshold, deprioritize them for implementation tasks
+- **Auto-escalation:** If an agent errors 3 times in a row, pause their dispatch and alert
+- **Capacity planning:** Track throughput per agent to optimize `maxConcurrent`
+
+## How It All Connects
+
+```
+                         ┌──────────────────────┐
+                         │    notes.md       │
+                         │  (institutional       │
+                         │   knowledge)          │
+                         └──────┬───────────────┘
+                                │ injected into every playbook
+                                ▼
+┌──────────┐           ┌──────────────────┐           ┌──────────┐
+│ history  │──injects──│   Agent works    │──writes──→│  inbox/  │
+│ .md      │           │   on task        │           │  *.md    │
+│ (past    │           └────────┬─────────┘           └────┬─────┘
+│  tasks)  │                    │                          │
+└──────────┘                    │ on completion            │ consolidateInbox()
+     ▲                          ▼                          ▼
+     │                 ┌──────────────────┐         ┌──────────┐
+     └─updateHistory───│   Engine         │─prune──→│decisions  │
+                       │   post-hooks     │         │  .md     │
+                       └────────┬─────────┘         └──────────┘
+                                │
+                    ┌───────────┼───────────┐
+                    ▼           ▼           ▼
+             ┌──────────┐ ┌──────────┐ ┌──────────┐
+             │ metrics  │ │ feedback │ │ history  │
+             │ .json    │ │ for      │ │ .md      │
+             │          │ │ author   │ │ updated  │
+             └──────────┘ └──────────┘ └──────────┘
+```
+
+## 5. Skills — Agent-Discovered Workflows
+
+When an agent discovers a repeatable multi-step procedure, it can save it as a **skill** — a structured, reusable workflow compatible with Claude Code's skill system. Skills are stored in two locations:
+
+- **Squad-wide:** `~/.squad/skills/<name>.md` — shared across all agents, no PR required
+- **Project-specific:** `<project>/.claude/skills/<name>/SKILL.md` — scoped to one repo, requires a PR
+
+### Flow
+
+```
+Agent discovers repeatable pattern during task
+  → writes skills/<name>.md with frontmatter (name, description, trigger, allowed-tools)
+  → engine detects new skill files on next tick
+  → builds skill index (name + trigger + file path)
+  → index injected into every agent's system prompt
+  → future agents see "Available Skills" and follow matching ones
+  → skills are also invocable via Claude Code's /skill-name command
+```
+
+### Skill Format
+
+```markdown
+---
+name: fix-yarn-lock-conflict
+description: Resolves yarn.lock merge conflicts by regenerating the lockfile
+trigger: when merging branches that both modified yarn.lock
+allowed-tools: Bash, Read, Write
+author: dallas
+created: 2026-03-12
+project: any
+---
+
+# Skill: Fix Yarn Lock Conflicts
+
+## When to Use
+When a git merge or rebase produces conflicts in yarn.lock.
+
+## Steps
+1. Delete yarn.lock
+2. Run `yarn install` to regenerate
+3. Stage the new yarn.lock
+4. Continue the merge/rebase
+
+## Notes
+- Never manually edit yarn.lock
+- Always run `yarn build` after regenerating to verify
+```
+
+### How it differs from notes.md
+
+| | notes.md | Skills |
+|---|---|---|
+| **Format** | Free-form prose, appended by engine | Structured with frontmatter, one file per workflow |
+| **Granularity** | Rules, conventions, findings | Step-by-step procedures |
+| **Authored by** | Engine (consolidation) | Agents directly |
+| **Trigger** | Always injected (all context) | Agent matches trigger to current situation |
+| **Lifespan** | Grows forever (pruned at 50KB) | Permanent, individually editable |
+| **Claude Code** | Not directly invocable | Invocable via `/skill-name` |
+
+### When agents should create skills
+
+- Multi-step procedures they had to figure out (build setup, deployment, migration)
+- Error recovery patterns (how to fix a specific class of failure)
+- Project-specific workflows that aren't documented elsewhere
+- Cross-repo coordination steps
+
+## Configuration
+
+| Setting | Default | What it controls |
+|---------|---------|-----------------|
+| `engine.inboxConsolidateThreshold` | 5 | Files needed before consolidation triggers |
+| notes.md max size | 50KB | Auto-prunes old sections above this |
+| Agent history entries | 20 | Max entries kept in history.md |
+| Metrics file | `engine/metrics.json` | Auto-created on first completion |
+
+## Files
+
+| File | Purpose | Written by |
+|------|---------|-----------|
+| `notes/inbox/*.md` | Agent findings drop-box | Agents |
+| `notes/archive/*.md` | Archived inbox files | Engine (consolidation) |
+| `notes.md` | Accumulated team knowledge | Engine (consolidation) |
+| `agents/<name>/history.md` | Per-agent task history | Engine (post-completion) |
+| `engine/metrics.json` | Quality metrics per agent | Engine (post-completion + review) |
+| `notes/inbox/feedback-*.md` | Review feedback for authors | Engine (post-review) |

package/engine/ado-mcp-wrapper.js

@@ -0,0 +1,49 @@
+#!/usr/bin/env node
+/**
+ * Wrapper for @azure-devops/mcp that fetches an ADO token via azureauth
+ * broker (no browser popup) and sets AZURE_DEVOPS_EXT_PAT before launching
+ * the MCP server.
+ */
+const { execSync, spawn } = require('child_process');
+const path = require('path');
+
+// Fetch token via azureauth broker (corp tool, no browser)
+let token;
+try {
+  token = execSync('azureauth ado token --mode broker --output token --timeout 1', {
+    encoding: 'utf8',
+    timeout: 30000,
+    windowsHide: true,
+  }).trim();
+} catch (e) {
+  // Fallback: try with web mode (may open browser as last resort)
+  try {
+    token = execSync('azureauth ado token --mode web --output token --timeout 5', {
+      encoding: 'utf8',
+      timeout: 120000,
+      windowsHide: true,
+    }).trim();
+  } catch (e2) {
+    process.stderr.write('ado-mcp-wrapper: Failed to get ADO token: ' + e2.message + '\n');
+    process.exit(1);
+  }
+}
+
+// Launch the actual MCP server with the token in env
+const args = process.argv.slice(2);
+const child = spawn(process.platform === 'win32' ? 'npx.cmd' : 'npx', [
+  '-y',
+  '--registry=https://registry.npmjs.org/',
+  '@azure-devops/mcp@latest',
+  ...args
+], {
+  stdio: 'inherit',
+  env: { ...process.env, AZURE_DEVOPS_EXT_PAT: token },
+  windowsHide: true,
+});
+
+child.on('exit', (code) => process.exit(code || 0));
+child.on('error', (err) => {
+  process.stderr.write('ado-mcp-wrapper: ' + err.message + '\n');
+  process.exit(1);
+});

package/engine/spawn-agent.js

@@ -0,0 +1,98 @@
+#!/usr/bin/env node
+/**
+ * spawn-agent.js — Wrapper to spawn claude CLI safely
+ * Reads prompt and system prompt from files, avoiding shell metacharacter issues.
+ *
+ * Usage: node spawn-agent.js <prompt-file> <sysprompt-file> [claude-args...]
+ */
+
+const { spawn, execSync } = require('child_process');
+const fs = require('fs');
+const path = require('path');
+
+const [,, promptFile, sysPromptFile, ...extraArgs] = process.argv;
+
+if (!promptFile || !sysPromptFile) {
+  console.error('Usage: node spawn-agent.js <prompt-file> <sysprompt-file> [args...]');
+  process.exit(1);
+}
+
+const prompt = fs.readFileSync(promptFile, 'utf8');
+const sysPrompt = fs.readFileSync(sysPromptFile, 'utf8');
+
+// Clean CLAUDECODE env vars
+const env = { ...process.env };
+delete env.CLAUDECODE;
+delete env.CLAUDE_CODE_ENTRYPOINT;
+for (const key of Object.keys(env)) {
+  if (key.startsWith('CLAUDE_CODE') || key.startsWith('CLAUDECODE_')) delete env[key];
+}
+
+// Resolve claude binary — find the actual JS entry point
+let claudeBin;
+const searchPaths = [
+  // npm global install locations
+  path.join(process.env.npm_config_prefix || '', 'node_modules', '@anthropic-ai', 'claude-code', 'cli.js'),
+  'C:/.tools/.npm-global/node_modules/@anthropic-ai/claude-code/cli.js',
+  path.join(process.env.APPDATA || '', 'npm', 'node_modules', '@anthropic-ai', 'claude-code', 'cli.js'),
+];
+for (const p of searchPaths) {
+  if (p && fs.existsSync(p)) { claudeBin = p; break; }
+}
+// Fallback: parse the shell wrapper
+if (!claudeBin) {
+  try {
+    const which = execSync('bash -c "which claude"', { encoding: 'utf8', env }).trim();
+    const wrapper = execSync(`bash -c "cat '${which}'"`, { encoding: 'utf8', env });
+    const m = wrapper.match(/node_modules\/@anthropic-ai\/claude-code\/cli\.js/);
+    if (m) {
+      const basedir = path.dirname(which.replace(/^\/c\//, 'C:/').replace(/\//g, path.sep));
+      claudeBin = path.join(basedir, 'node_modules', '@anthropic-ai', 'claude-code', 'cli.js');
+    }
+  } catch {}
+}
+
+// Debug log
+const debugPath = path.join(__dirname, 'spawn-debug.log');
+fs.writeFileSync(debugPath, `spawn-agent.js at ${new Date().toISOString()}\nclaudeBin=${claudeBin || 'not found'}\nprompt=${promptFile}\nsysPrompt=${sysPromptFile}\nextraArgs=${extraArgs.join(' ')}\n`);
+
+const cliArgs = ['-p', '--system-prompt', sysPrompt, ...extraArgs];
+
+if (!claudeBin) {
+  fs.appendFileSync(debugPath, 'FATAL: Cannot find claude-code cli.js\n');
+  process.exit(1);
+}
+
+const proc = spawn(process.execPath, [claudeBin, ...cliArgs], {
+  stdio: ['pipe', 'pipe', 'pipe'],
+  env
+});
+
+fs.appendFileSync(debugPath, `PID=${proc.pid || 'none'}\n`);
+
+// Write PID file for parent engine to verify spawn
+const pidFile = promptFile.replace(/prompt-/, 'pid-').replace(/\.md$/, '.pid');
+fs.writeFileSync(pidFile, String(proc.pid || ''));
+
+// Send prompt via stdin
+proc.stdin.write(prompt);
+proc.stdin.end();
+
+// Capture stderr separately for debugging
+let stderrBuf = '';
+proc.stderr.on('data', (chunk) => {
+  stderrBuf += chunk.toString();
+  process.stderr.write(chunk);
+});
+
+// Pipe stdout to parent
+proc.stdout.pipe(process.stdout);
+
+proc.on('close', (code) => {
+  fs.appendFileSync(debugPath, `EXIT: code=${code}\nSTDERR: ${stderrBuf.slice(0, 500)}\n`);
+  process.exit(code || 0);
+});
+proc.on('error', (err) => {
+  fs.appendFileSync(debugPath, `ERROR: ${err.message}\n`);
+  process.exit(1);
+});