@yemi33/squad 0.1.13 → 0.1.15

package/dashboard.js

@@ -75,7 +75,7 @@ function getAgentDetail(id) {
   const agentDir = path.join(SQUAD_DIR, 'agents', id);
   const charter = safeRead(path.join(agentDir, 'charter.md')) || 'No charter found.';
   const history = safeRead(path.join(agentDir, 'history.md')) || 'No history yet.';
-  const outputLog = safeRead(path.join(agentDir, 'output.md')) || '';
+  const outputLog = safeRead(path.join(agentDir, 'output.log')) || '';
 
   const statusJson = safeRead(path.join(agentDir, 'status.json'));
   let statusData = null;
@@ -86,7 +86,25 @@ function getAgentDetail(id) {
     .filter(f => f.includes(id))
     .map(f => ({ name: f, content: safeRead(path.join(inboxDir, f)) || '' }));
 
-  return { charter, history, statusData, outputLog, inboxContents };
+  // Recent completed dispatches for this agent (last 10)
+  let recentDispatches = [];
+  try {
+    const dispatch = JSON.parse(safeRead(path.join(SQUAD_DIR, 'engine', 'dispatch.json')) || '{}');
+    recentDispatches = (dispatch.completed || [])
+      .filter(d => d.agent === id)
+      .slice(-10)
+      .reverse()
+      .map(d => ({
+        id: d.id,
+        task: d.task || '',
+        type: d.type || '',
+        result: d.result || '',
+        reason: d.reason || '',
+        completed_at: d.completed_at || '',
+      }));
+  } catch {}
+
+  return { charter, history, statusData, outputLog, inboxContents, recentDispatches };
 }
 
 function getAgents() {
@@ -424,6 +442,20 @@ function getWorkItems() {
   return allItems;
 }
 
+function getMcpServers() {
+  try {
+    const home = process.env.USERPROFILE || process.env.HOME || '';
+    const claudeJsonPath = path.join(home, '.claude.json');
+    const data = JSON.parse(safeRead(claudeJsonPath) || '{}');
+    const servers = data.mcpServers || {};
+    return Object.entries(servers).map(([name, cfg]) => ({
+      name,
+      command: cfg.command || '',
+      args: (cfg.args || []).slice(-1)[0] || '',
+    }));
+  } catch { return []; }
+}
+
 function getStatus() {
   const prdInfo = getPrdInfo();
   return {
@@ -440,6 +472,7 @@ function getStatus() {
     metrics: getMetrics(),
     workItems: getWorkItems(),
     skills: getSkills(),
+    mcpServers: getMcpServers(),
     projects: PROJECTS.map(p => ({ name: p.name, path: p.localPath, description: p.description || '' })),
     timestamp: new Date().toISOString(),
   };
@@ -740,7 +773,7 @@ const server = http.createServer(async (req, res) => {
         priority: body.priority || 'high', description: body.description || '',
         status: 'pending', created: new Date().toISOString(), createdBy: 'dashboard',
         chain: 'plan-to-prd',
-        branchStrategy: body.branch_strategy || 'shared-branch',
+        branchStrategy: body.branch_strategy || 'parallel',
       };
       if (body.project) item.project = body.project;
       if (body.agent) item.agent = body.agent;
@@ -858,6 +891,284 @@ const server = http.createServer(async (req, res) => {
     return;
   }
 
+  // GET /api/plans — list all plan files with status
+  if (req.method === 'GET' && req.url === '/api/plans') {
+    const plansDir = path.join(SQUAD_DIR, 'plans');
+    const files = safeReadDir(plansDir).filter(f => f.endsWith('.json'));
+    const plans = files.map(f => {
+      const plan = JSON.parse(safeRead(path.join(plansDir, f)) || '{}');
+      return {
+        file: f,
+        project: plan.project || '',
+        summary: plan.plan_summary || '',
+        status: plan.status || 'active',
+        branchStrategy: plan.branch_strategy || 'parallel',
+        featureBranch: plan.feature_branch || '',
+        itemCount: (plan.missing_features || []).length,
+        generatedBy: plan.generated_by || '',
+        generatedAt: plan.generated_at || '',
+        requiresApproval: plan.requires_approval || false,
+        revisionFeedback: plan.revision_feedback || null,
+      };
+    }).sort((a, b) => b.generatedAt.localeCompare(a.generatedAt));
+    return jsonReply(res, 200, plans);
+  }
+
+  // GET /api/plans/:file — read full plan JSON
+  const planFileMatch = req.url.match(/^\/api\/plans\/([^?]+)$/);
+  if (planFileMatch && req.method === 'GET') {
+    const file = decodeURIComponent(planFileMatch[1]);
+    if (file.includes('..') || file.includes('/') || file.includes('\\')) return jsonReply(res, 400, { error: 'invalid' });
+    const content = safeRead(path.join(SQUAD_DIR, 'plans', file));
+    if (!content) return jsonReply(res, 404, { error: 'not found' });
+    res.setHeader('Content-Type', 'application/json; charset=utf-8');
+    res.setHeader('Access-Control-Allow-Origin', '*');
+    res.end(content);
+    return;
+  }
+
+  // POST /api/plans/approve — approve a plan for execution
+  if (req.method === 'POST' && req.url === '/api/plans/approve') {
+    try {
+      const body = await readBody(req);
+      if (!body.file) return jsonReply(res, 400, { error: 'file required' });
+      const planPath = path.join(SQUAD_DIR, 'plans', body.file);
+      const plan = JSON.parse(safeRead(planPath) || '{}');
+      plan.status = 'approved';
+      plan.approvedAt = new Date().toISOString();
+      plan.approvedBy = body.approvedBy || os.userInfo().username;
+      safeWrite(planPath, plan);
+      return jsonReply(res, 200, { ok: true, status: 'approved' });
+    } catch (e) { return jsonReply(res, 400, { error: e.message }); }
+  }
+
+  // POST /api/plans/reject — reject a plan
+  if (req.method === 'POST' && req.url === '/api/plans/reject') {
+    try {
+      const body = await readBody(req);
+      if (!body.file) return jsonReply(res, 400, { error: 'file required' });
+      const planPath = path.join(SQUAD_DIR, 'plans', body.file);
+      const plan = JSON.parse(safeRead(planPath) || '{}');
+      plan.status = 'rejected';
+      plan.rejectedAt = new Date().toISOString();
+      plan.rejectedBy = body.rejectedBy || os.userInfo().username;
+      if (body.reason) plan.rejectionReason = body.reason;
+      safeWrite(planPath, plan);
+      return jsonReply(res, 200, { ok: true, status: 'rejected' });
+    } catch (e) { return jsonReply(res, 400, { error: e.message }); }
+  }
+
+  // POST /api/plans/revise — request revision with feedback, dispatches agent to revise
+  if (req.method === 'POST' && req.url === '/api/plans/revise') {
+    try {
+      const body = await readBody(req);
+      if (!body.file || !body.feedback) return jsonReply(res, 400, { error: 'file and feedback required' });
+      const planPath = path.join(SQUAD_DIR, 'plans', body.file);
+      const plan = JSON.parse(safeRead(planPath) || '{}');
+      plan.status = 'revision-requested';
+      plan.revision_feedback = body.feedback;
+      plan.revisionRequestedAt = new Date().toISOString();
+      plan.revisionRequestedBy = body.requestedBy || os.userInfo().username;
+      safeWrite(planPath, plan);
+
+      // Create a work item to revise the plan
+      const wiPath = path.join(SQUAD_DIR, 'work-items.json');
+      let items = [];
+      const existing = safeRead(wiPath);
+      if (existing) { try { items = JSON.parse(existing); } catch {} }
+      const maxNum = items.reduce(function(max, i) {
+        const m = (i.id || '').match(/(\d+)$/);
+        return m ? Math.max(max, parseInt(m[1])) : max;
+      }, 0);
+      const id = 'W' + String(maxNum + 1).padStart(3, '0');
+      items.push({
+        id, title: 'Revise plan: ' + (plan.plan_summary || body.file),
+        type: 'plan-to-prd', priority: 'high',
+        description: 'Revision requested on plan file: plans/' + body.file + '\n\nFeedback:\n' + body.feedback + '\n\nRevise the plan to address this feedback. Read the existing plan, apply the feedback, and overwrite the file with the updated version. Set status back to "awaiting-approval".',
+        status: 'pending', created: new Date().toISOString(), createdBy: 'dashboard:revision',
+        project: plan.project || '',
+        planFile: body.file,
+      });
+      safeWrite(wiPath, items);
+      return jsonReply(res, 200, { ok: true, status: 'revision-requested', workItemId: id });
+    } catch (e) { return jsonReply(res, 400, { error: e.message }); }
+  }
+
+  // POST /api/plans/discuss — generate a plan discussion session script
+  if (req.method === 'POST' && req.url === '/api/plans/discuss') {
+    try {
+      const body = await readBody(req);
+      if (!body.file) return jsonReply(res, 400, { error: 'file required' });
+      const planPath = path.join(SQUAD_DIR, 'plans', body.file);
+      const planContent = safeRead(planPath);
+      if (!planContent) return jsonReply(res, 404, { error: 'plan not found' });
+
+      const plan = JSON.parse(planContent);
+      const projectName = plan.project || 'Unknown';
+
+      // Build the session launch script
+      const sessionName = 'plan-review-' + body.file.replace(/\.json$/, '');
+      const sysPrompt = `You are a Plan Advisor helping a human review and refine a feature plan before it gets dispatched to an agent squad.
+
+## Your Role
+- Help the user understand, question, and refine the plan
+- Accept feedback and update the plan accordingly
+- When the user is satisfied, write the approved plan back to disk
+
+## The Plan File
+Path: ${planPath}
+Project: ${projectName}
+
+## How This Works
+1. The user will discuss the plan with you — answer questions, suggest changes
+2. When they want changes, update the plan items (add/remove/reorder/modify)
+3. When they say ANY of these (or similar intent):
+   - "approve", "go", "ship it", "looks good", "lgtm"
+   - "clear context and implement", "clear context and go"
+   - "go build it", "start working", "dispatch", "execute"
+   - "do it", "proceed", "let's go", "send it"
+
+   Then:
+   a. Read the current plan file fresh from disk
+   b. Update status to "approved", set approvedAt and approvedBy
+   c. Write it back to ${planPath} using the Write tool
+   d. Print exactly: "Plan approved and saved. The engine will dispatch work on the next tick. You can close this session."
+   e. Then EXIT the session — use /exit or simply stop responding. The user does NOT need to interact further.
+
+4. If they say "reject" or "cancel":
+   - Update status to "rejected"
+   - Write it back
+   - Confirm and exit.
+
+## Important
+- Always read the plan file fresh before writing (another process may have modified it)
+- Preserve all existing fields when writing back
+- Use the Write tool to save changes
+- You have full file access — you can also read the project codebase for context
+- When the user signals approval, ALWAYS write the file and exit. Do not ask for confirmation — their intent is clear.`;
+
+      const initialPrompt = `Here's the plan awaiting your review:
+
+**${plan.plan_summary || body.file}**
+Project: ${projectName}
+Strategy: ${plan.branch_strategy || 'parallel'}
+Branch: ${plan.feature_branch || 'per-item'}
+Items: ${(plan.missing_features || []).length}
+
+${(plan.missing_features || []).map((f, i) =>
+  `${i + 1}. **${f.id}: ${f.name}** (${f.estimated_complexity}, ${f.priority})${f.depends_on?.length ? ' → depends on: ' + f.depends_on.join(', ') : ''}
+   ${f.description || ''}`
+).join('\n\n')}
+
+${plan.open_questions?.length ? '\n**Open Questions:**\n' + plan.open_questions.map(q => '- ' + q).join('\n') : ''}
+
+What would you like to discuss or change? When you're happy, say "approve" and I'll finalize it.`;
+
+      // Write session files
+      const sessionDir = path.join(SQUAD_DIR, 'engine');
+      const sysFile = path.join(sessionDir, `plan-discuss-sys-${Date.now()}.md`);
+      const promptFile = path.join(sessionDir, `plan-discuss-prompt-${Date.now()}.md`);
+      safeWrite(sysFile, sysPrompt);
+      safeWrite(promptFile, initialPrompt);
+
+      // Generate the launch command
+      const cmd = `claude --system-prompt "$(cat '${sysFile.replace(/\\/g, '/')}')" --name "${sessionName}" --add-dir "${SQUAD_DIR.replace(/\\/g, '/')}" < "${promptFile.replace(/\\/g, '/')}"`;
+
+      // Also generate a PowerShell-friendly version
+      const psCmd = `Get-Content "${promptFile}" | claude --system-prompt (Get-Content "${sysFile}" -Raw) --name "${sessionName}" --add-dir "${SQUAD_DIR}"`;
+
+      return jsonReply(res, 200, {
+        ok: true,
+        sessionName,
+        command: cmd,
+        psCommand: psCmd,
+        sysFile,
+        promptFile,
+        planFile: body.file,
+      });
+    } catch (e) { return jsonReply(res, 400, { error: e.message }); }
+  }
+
+  // POST /api/ask-about — ask a question about a document with context, answered by Haiku
+  if (req.method === 'POST' && req.url === '/api/ask-about') {
+    try {
+      const body = await readBody(req);
+      if (!body.question) return jsonReply(res, 400, { error: 'question required' });
+      if (!body.document) return jsonReply(res, 400, { error: 'document required' });
+
+      const prompt = `You are answering a question about a document from a software engineering squad's knowledge base.
+
+## Document
+${body.title ? '**Title:** ' + body.title + '\n' : ''}
+${body.document.slice(0, 15000)}
+
+${body.selection ? '## Highlighted Selection\n\nThe user highlighted this specific part:\n> ' + body.selection.slice(0, 2000) + '\n' : ''}
+
+## Question
+
+${body.question}
+
+## Instructions
+
+Answer concisely and directly. Follow these rules:
+1. **Cite sources**: When the document includes file paths, line numbers, PR URLs, or code references — include them in your answer. Format: \`(source: path/to/file.ts:42)\`
+2. **Quote the document**: Reference the exact text that supports your answer.
+3. **Flag missing sources**: If the document makes a claim without a source reference (no file path, no PR link, no line number), say: "Note: this claim has no source reference in the document — verify independently."
+4. **Be honest**: If the document doesn't contain the answer, say so clearly. Don't speculate beyond what's written.
+5. Use markdown formatting.`;
+
+      const sysPrompt = 'You are a concise technical assistant. Answer based on the document provided. No preamble.';
+
+      // Write temp files
+      const id = Date.now();
+      const promptPath = path.join(SQUAD_DIR, 'engine', 'ask-prompt-' + id + '.md');
+      const sysPath = path.join(SQUAD_DIR, 'engine', 'ask-sys-' + id + '.md');
+      safeWrite(promptPath, prompt);
+      safeWrite(sysPath, sysPrompt);
+
+      // Spawn Haiku
+      const spawnScript = path.join(SQUAD_DIR, 'engine', 'spawn-agent.js');
+      const childEnv = { ...process.env };
+      for (const key of Object.keys(childEnv)) {
+        if (key === 'CLAUDECODE' || key.startsWith('CLAUDE_CODE') || key.startsWith('CLAUDECODE_')) delete childEnv[key];
+      }
+
+      const { spawn: cpSpawn } = require('child_process');
+      const proc = cpSpawn(process.execPath, [
+        spawnScript, promptPath, sysPath,
+        '--output-format', 'text', '--max-turns', '1', '--model', 'haiku',
+        '--permission-mode', 'bypassPermissions', '--verbose',
+      ], { cwd: SQUAD_DIR, stdio: ['pipe', 'pipe', 'pipe'], env: childEnv });
+
+      let stdout = '';
+      let stderr = '';
+      proc.stdout.on('data', d => { stdout += d.toString(); });
+      proc.stderr.on('data', d => { stderr += d.toString(); });
+
+      // Timeout 60s
+      const timeout = setTimeout(() => { try { proc.kill('SIGTERM'); } catch {} }, 60000);
+
+      proc.on('close', (code) => {
+        clearTimeout(timeout);
+        try { fs.unlinkSync(promptPath); } catch {}
+        try { fs.unlinkSync(sysPath); } catch {}
+        if (code === 0 && stdout.trim()) {
+          return jsonReply(res, 200, { ok: true, answer: stdout.trim() });
+        } else {
+          return jsonReply(res, 500, { error: 'Failed to get answer', stderr: stderr.slice(0, 200) });
+        }
+      });
+
+      proc.on('error', (err) => {
+        clearTimeout(timeout);
+        try { fs.unlinkSync(promptPath); } catch {}
+        try { fs.unlinkSync(sysPath); } catch {}
+        return jsonReply(res, 500, { error: err.message });
+      });
+      return; // Don't fall through — response handled in callbacks
+    } catch (e) { return jsonReply(res, 400, { error: e.message }); }
+  }
+
   // POST /api/inbox/persist — promote an inbox item to team notes
   if (req.method === 'POST' && req.url === '/api/inbox/persist') {
     try {
@@ -898,6 +1209,45 @@ const server = http.createServer(async (req, res) => {
     } catch (e) { return jsonReply(res, 400, { error: e.message }); }
   }
 
+  // POST /api/inbox/promote-kb — promote an inbox item to the knowledge base
+  if (req.method === 'POST' && req.url === '/api/inbox/promote-kb') {
+    try {
+      const body = await readBody(req);
+      const { name, category } = body;
+      if (!name) return jsonReply(res, 400, { error: 'name required' });
+      const validCategories = ['architecture', 'conventions', 'project-notes', 'build-reports', 'reviews'];
+      if (!category || !validCategories.includes(category)) {
+        return jsonReply(res, 400, { error: 'category required: ' + validCategories.join(', ') });
+      }
+
+      const inboxPath = path.join(SQUAD_DIR, 'notes', 'inbox', name);
+      const content = safeRead(inboxPath);
+      if (!content) return jsonReply(res, 404, { error: 'inbox item not found' });
+
+      // Add frontmatter if not present
+      const today = new Date().toISOString().slice(0, 10);
+      let kbContent = content;
+      if (!content.startsWith('---')) {
+        const titleMatch = content.match(/^#+ (.+)$/m);
+        const title = titleMatch ? titleMatch[1].trim() : name.replace('.md', '');
+        kbContent = `---\ntitle: ${title}\ncategory: ${category}\ndate: ${today}\nsource: inbox/${name}\n---\n\n${content}`;
+      }
+
+      // Write to knowledge base
+      const kbDir = path.join(SQUAD_DIR, 'knowledge', category);
+      if (!fs.existsSync(kbDir)) fs.mkdirSync(kbDir, { recursive: true });
+      const kbFile = path.join(kbDir, name);
+      safeWrite(kbFile, kbContent);
+
+      // Move inbox item to archive
+      const archiveDir = path.join(SQUAD_DIR, 'notes', 'archive');
+      if (!fs.existsSync(archiveDir)) fs.mkdirSync(archiveDir, { recursive: true });
+      try { fs.renameSync(inboxPath, path.join(archiveDir, `kb-${category}-${name}`)); } catch {}
+
+      return jsonReply(res, 200, { ok: true, category, file: name });
+    } catch (e) { return jsonReply(res, 400, { error: e.message }); }
+  }
+
   // POST /api/inbox/open — open inbox file in Windows explorer
   if (req.method === 'POST' && req.url === '/api/inbox/open') {
     try {

package/docs/blog-first-successful-dispatch.md

@@ -87,7 +87,7 @@ When the engine restarts, the in-memory `activeProcesses` Map is lost. Active di
 
 **Dispatch 1773292681199** — Dallas, central work item, auto-route:
 
-1. Engine spawns `node spawn-agent.js prompt.md sysprompt.md --output-format stream-json --verbose --permission-mode bypassPermissions --mcp-config mcp-servers.json`
+1. Engine spawns `node spawn-agent.js prompt.md sysprompt.md --output-format stream-json --verbose --permission-mode bypassPermissions`
 2. spawn-agent.js resolves `cli.js`, spawns `node cli.js -p --system-prompt <content> ...`
 3. Prompt piped via stdin — no shell interpretation
 4. MCP servers connect (azure-ado, azure-kusto, mobile, DevBox)

package/engine.js

@@ -212,39 +212,6 @@ function getInboxFiles() {
   try { return fs.readdirSync(INBOX_DIR).filter(f => f.endsWith('.md')); } catch { return []; }
 }
 
-// ─── MCP Server Sync ─────────────────────────────────────────────────────────
-
-const MCP_SERVERS_PATH = path.join(SQUAD_DIR, 'mcp-servers.json');
-
-function syncMcpServers() {
-  // Sync MCP servers from ~/.claude.json into squad's mcp-servers.json
-  const home = process.env.USERPROFILE || process.env.HOME || '';
-  const claudeJsonPath = path.join(home, '.claude.json');
-
-  if (!fs.existsSync(claudeJsonPath)) {
-    console.log('  ~/.claude.json not found — skipping MCP sync');
-    return false;
-  }
-
-  try {
-    const claudeJson = JSON.parse(fs.readFileSync(claudeJsonPath, 'utf8'));
-    const servers = claudeJson.mcpServers;
-    if (!servers || Object.keys(servers).length === 0) {
-      console.log('  No MCP servers found in ~/.claude.json');
-      return false;
-    }
-
-    safeWrite(MCP_SERVERS_PATH, { mcpServers: servers });
-    const names = Object.keys(servers);
-    console.log(`  MCP servers synced (${names.length}): ${names.join(', ')}`);
-    log('info', `Synced ${names.length} MCP servers from ~/.claude.json: ${names.join(', ')}`);
-    return true;
-  } catch (e) {
-    console.log(`  MCP sync failed: ${e.message}`);
-    return false;
-  }
-}
-
 // ─── Skills ──────────────────────────────────────────────────────────────────
 
 const SKILLS_DIR = path.join(SQUAD_DIR, 'skills');
@@ -313,6 +280,32 @@ function getSkillIndex() {
   } catch { return ''; }
 }
 
+function getKnowledgeBaseIndex() {
+  try {
+    const kbDir = path.join(SQUAD_DIR, 'knowledge');
+    if (!fs.existsSync(kbDir)) return '';
+    const categories = ['architecture', 'conventions', 'project-notes', 'build-reports', 'reviews'];
+    let entries = [];
+    for (const cat of categories) {
+      const catDir = path.join(kbDir, cat);
+      const files = safeReadDir(catDir).filter(f => f.endsWith('.md'));
+      for (const f of files) {
+        const content = safeRead(path.join(catDir, f)) || '';
+        const titleMatch = content.match(/^#\s+(.+)/m);
+        const title = titleMatch ? titleMatch[1].trim() : f.replace(/\.md$/, '');
+        entries.push({ cat, file: f, title });
+      }
+    }
+    if (entries.length === 0) return '';
+    let index = '## Knowledge Base Reference\n\n';
+    index += 'Deep-reference docs from past work. Read the file if you need detail.\n\n';
+    for (const e of entries) {
+      index += `- \`knowledge/${e.cat}/${e.file}\` — ${e.title}\n`;
+    }
+    return index + '\n';
+  } catch { return ''; }
+}
+
 function getPrs(project) {
   if (project) {
     const prPath = project.workSources?.pullRequests?.path;
@@ -412,7 +405,8 @@ function renderPlaybook(type, vars) {
   content += `- What you learned about the codebase\n`;
   content += `- Patterns you discovered or established\n`;
   content += `- Gotchas or warnings for future agents\n`;
-  content += `- Conventions to follow\n\n`;
+  content += `- Conventions to follow\n`;
+  content += `- **SOURCE REFERENCES for every finding** — file paths with line numbers, PR URLs, API endpoints, config keys. Format: \`(source: path/to/file.ts:42)\` or \`(source: PR-12345)\`. Without references, findings cannot be verified.\n\n`;
   content += `### Skill Extraction (IMPORTANT)\n\n`;
   content += `If during this task you discovered a **repeatable workflow** — a multi-step procedure, workaround, build process, or pattern that other agents should follow in similar situations — output it as a fenced skill block. The engine will automatically extract it.\n\n`;
   content += `Format your skill as a fenced code block with the \`skill\` language tag:\n\n`;
@@ -574,6 +568,12 @@ function buildAgentContext(agentId, config, project) {
     context += skillIndex + '\n';
   }
 
+  // Knowledge base index (paths + titles only — agents can Read if needed)
+  const kbIndex = getKnowledgeBaseIndex();
+  if (kbIndex) {
+    context += kbIndex + '\n';
+  }
+
   // Team notes (the big one — can be 50KB)
   if (notes) {
     context += `## Team Notes (MUST READ)\n\n${notes}\n\n`;
@@ -669,11 +669,8 @@ function spawnAgent(dispatchItem, config) {
     args.push('--allowedTools', claudeConfig.allowedTools);
   }
 
-  // MCP servers — pass config file if it exists
-  const mcpConfigPath = claudeConfig.mcpConfig || path.join(SQUAD_DIR, 'mcp-servers.json');
-  if (fs.existsSync(mcpConfigPath)) {
-    args.push('--mcp-config', mcpConfigPath);
-  }
+  // MCP servers: agents inherit from ~/.claude.json directly as Claude Code processes.
+  // No --mcp-config needed — avoids redundant config and ensures agents always have latest servers.
 
   log('info', `Spawning agent: ${agentId} (${id}) in ${cwd}`);
   log('info', `Task type: ${type} | Branch: ${branchName || 'none'}`);
@@ -3083,6 +3080,13 @@ function materializePlansAsWorkItems(config) {
     const plan = safeJson(path.join(PLANS_DIR, file));
     if (!plan?.missing_features) continue;
 
+    // Human approval gate: plans start as 'awaiting-approval' and must be approved before work begins
+    // Plans without a status (legacy) or with status 'approved' are allowed through
+    const planStatus = plan.status || (plan.requires_approval ? 'awaiting-approval' : null);
+    if (planStatus === 'awaiting-approval' || planStatus === 'rejected' || planStatus === 'revision-requested') {
+      continue; // Skip — waiting for human approval or revision
+    }
+
     const projectName = plan.project || file.replace(/-\d{4}-\d{2}-\d{2}\.json$/, '');
     const project = getProjects(config).find(p => p.name?.toLowerCase() === projectName.toLowerCase());
     if (!project) continue;
@@ -3973,7 +3977,7 @@ async function tickInner() {
   // 2. Consolidate inbox
   consolidateInbox(config);
 
-  // 2.5. Periodic cleanup (every 10 ticks = ~5 minutes)
+  // 2.5. Periodic cleanup + MCP sync (every 10 ticks = ~5 minutes)
   if (tickCount % 10 === 0) {
     runCleanup(config);
   }
@@ -4058,9 +4062,6 @@ const commands = {
     const config = getConfig();
     const interval = config.engine?.tickInterval || 60000;
 
-    // Sync MCP servers from Claude Code
-    syncMcpServers();
-
     // Validate project paths
     const projects = getProjects(config);
     for (const p of projects) {
@@ -4535,7 +4536,7 @@ const commands = {
   },
 
   'mcp-sync'() {
-    syncMcpServers();
+    console.log('MCP servers are read directly from ~/.claude.json — no sync needed.');
   },
 
   discover() {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yemi33/squad",
-  "version": "0.1.13",
+  "version": "0.1.15",
   "description": "Multi-agent AI dev team that runs from ~/.squad/ — five autonomous agents share a single engine, dashboard, and knowledge base",
   "bin": {
     "squad": "bin/squad.js"

package/playbooks/explore.md

@@ -38,6 +38,7 @@ Write your findings to `{{team_root}}/notes/inbox/{{agent_id}}-explore-{{task_id
 - **Dependencies**: what depends on what
 - **Gaps**: anything missing, broken, or unclear
 - **Recommendations**: suggestions for the team
+- **Source References**: for EVERY finding, include the source — file paths, line numbers, PR URLs, API endpoints, config keys. Format: `(source: path/to/file.ts:42)` or `(source: PR-12345)`. This is critical — other agents and humans need to verify your findings.
 
 ### 5. Create Deliverable (if the task asks for one)
 If the task asks you to write a design doc, architecture doc, or any durable artifact:

package/playbooks/plan-to-prd.md

@@ -33,6 +33,8 @@ This file is NOT checked into the repo. The engine reads it on every tick and di
   "generated_by": "{{agent_id}}",
   "generated_at": "{{date}}",
   "plan_summary": "{{plan_summary}}",
+  "status": "awaiting-approval",
+  "requires_approval": true,
   "branch_strategy": "shared-branch|parallel",
   "feature_branch": "feat/plan-short-name",
   "missing_features": [