@yemi33/squad 0.1.0

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "@yemi33/squad",
+  "version": "0.1.0",
+  "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"
+  },
+  "keywords": [
+    "ai",
+    "agents",
+    "claude",
+    "dev-team",
+    "automation",
+    "multi-agent",
+    "cli"
+  ],
+  "author": "yemi33",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/yemi33/squad.git"
+  },
+  "homepage": "https://github.com/yemi33/squad#readme",
+  "engines": {
+    "node": ">=18"
+  },
+  "files": [
+    "bin/",
+    "agents/*/charter.md",
+    "config.template.json",
+    "dashboard.html",
+    "dashboard.js",
+    "docs/",
+    "engine.js",
+    "engine/spawn-agent.js",
+    "engine/ado-mcp-wrapper.js",
+    "playbooks/",
+    "routing.md",
+    "skills/README.md",
+    "skills/ado-pr-status-fetch.md",
+    "squad.js",
+    "team.md",
+    "README.md",
+    "TODO.md"
+  ]
+}

package/playbooks/build-and-test.md

@@ -0,0 +1,155 @@
+# Build & Test: PR {{pr_id}}
+
+> Agent: {{agent_name}} ({{agent_role}}) | Project: {{project_name}}
+
+## Context
+
+Repo: {{repo_name}} | Org: {{ado_org}} | Project: {{ado_project}}
+Team root: {{team_root}}
+Project path: {{project_path}}
+
+## Your Task
+
+A new PR has been created: **{{pr_id}}** — "{{pr_title}}"
+Branch: `{{pr_branch}}` | Author: {{pr_author}}
+
+Your job is to **check out the branch, build it, run tests, and if it's a webapp, start a local dev server** so the human reviewer can see it running.
+
+## Instructions
+
+### 1. Set up a worktree for the PR branch
+
+```bash
+cd {{project_path}}
+git fetch origin {{pr_branch}}
+git worktree add ../worktrees/bt-{{pr_number}} origin/{{pr_branch}}
+cd ../worktrees/bt-{{pr_number}}
+```
+
+### 2. Install dependencies
+
+Look at the project's build system (package.json, CLAUDE.md, README, Makefile, etc.) and install:
+```bash
+# Examples — use whatever the project needs:
+yarn install   # or npm install
+pip install -r requirements.txt
+dotnet restore
+```
+
+### 3. Build the project
+
+Run the project's build command:
+```bash
+# Examples:
+yarn build   # or npm run build
+dotnet build
+cargo build
+```
+
+If the build **fails**, report the errors clearly and stop. Do NOT attempt to fix the code.
+
+### 4. Run tests
+
+```bash
+# Examples:
+yarn test   # or npm test
+pytest
+dotnet test
+```
+
+Report test results: how many passed, failed, skipped.
+
+### 5. Start a local dev server (if applicable)
+
+Determine if this project is a **webapp** (has a dev server, serves HTTP, has a UI):
+- Check package.json for `dev`, `start`, `serve` scripts
+- Check for frameworks: Next.js, React, Angular, Vue, Express, Flask, ASP.NET
+- Check CLAUDE.md for run instructions
+
+If it IS a webapp:
+1. Start the dev server
+2. Wait for it to be ready (watch for "ready on", "listening on", "compiled" messages)
+3. Note the localhost URL and port
+4. **Keep the server running** — do NOT kill it
+
+If it is NOT a webapp (library, CLI tool, backend service without UI), skip this step.
+
+## Output Format
+
+Write your findings to: `{{team_root}}/notes/inbox/{{agent_id}}-bt-{{pr_number}}-{{date}}.md`
+
+Structure your report exactly like this:
+
+```markdown
+## Build & Test Report: {{pr_id}}
+
+**Branch:** {{pr_branch}}
+**Author:** {{pr_author}}
+**Project:** {{project_name}}
+
+### Build
+- Status: PASS / FAIL
+- Notes: (any warnings or issues)
+
+### Tests
+- Status: PASS / FAIL / SKIPPED
+- Results: X passed, Y failed, Z skipped
+- Failed tests: (list if any)
+
+### Local Server
+- Status: RUNNING / NOT_APPLICABLE / FAILED
+- URL: http://localhost:XXXX (if running)
+- Run Command: `cd <absolute-path> && <command>`
+
+### Summary
+(1-2 sentence overall assessment — is this PR safe to review?)
+```
+
+## Auto-file Work Items on Failure
+
+If the build OR tests fail, you MUST create a work item so another agent can fix it. Write a JSON entry to the project's work queue:
+
+```bash
+# Read existing items, append new one, write back
+node -e "
+const fs = require('fs');
+const p = '{{project_path}}/.squad/work-items.json';
+const items = JSON.parse(fs.readFileSync(p, 'utf8') || '[]');
+const id = 'W' + String(items.reduce((m,i) => Math.max(m, parseInt((i.id||'').match(/(\d+)$/)?.[1]||0)), 0) + 1).padStart(3, '0');
+items.push({
+  id,
+  title: 'Fix build/test failure on PR {{pr_id}}: <SHORT DESCRIPTION OF FAILURE>',
+  type: 'fix',
+  priority: 'high',
+  description: '<PASTE THE BUILD/TEST ERROR OUTPUT HERE — keep it under 2000 chars>',
+  status: 'pending',
+  created: new Date().toISOString(),
+  createdBy: '{{agent_id}}',
+  pr: '{{pr_id}}',
+  branch: '{{pr_branch}}'
+});
+fs.writeFileSync(p, JSON.stringify(items, null, 2));
+console.log('Filed work item:', id);
+"
+```
+
+Replace `<SHORT DESCRIPTION OF FAILURE>` and `<PASTE THE BUILD/TEST ERROR OUTPUT HERE>` with the actual error details. The engine will pick this up on the next tick and dispatch a fix agent.
+
+## Rules
+
+- **Do NOT create pull requests** — this is a build/test task only
+- **Do NOT push commits** or modify code
+- **Do NOT attempt to fix build/test failures** — report them and file a work item
+- If starting a dev server, output the **exact run command with absolute paths** so the user can restart it:
+  ```
+  ## Run Command
+  cd <absolute-path-to-worktree> && <exact start command>
+  ```
+- Use the worktree path, NOT the main project path, for all commands
+- The worktree will persist after your process ends so the user can inspect it
+
+## IMPORTANT: Do NOT clean up the worktree
+
+Leave the worktree in place at `{{project_path}}/../worktrees/bt-{{pr_number}}` — the user needs it to review the running app. The engine will clean it up after the PR is merged or closed.
+
+**Note:** Do NOT write to `agents/*/status.json` — the engine manages your status automatically.

package/playbooks/explore.md

@@ -0,0 +1,63 @@
+# Explore Playbook
+
+> Agent: {{agent_name}} | Task: {{task_description}} | ID: {{task_id}}
+
+## Context
+
+Repository ID: from `.squad/config.json` under `project.repositoryId`
+Repo: {{repo_name}} | Org: {{ado_org}} | Project: {{ado_project}}
+Team root: {{team_root}}
+
+## Mission
+
+Explore the codebase area specified in the task description. Your primary goal is to understand the architecture, patterns, and current state of the code. If the task asks you to produce a deliverable (design doc, architecture doc, analysis report), create it and commit it to the repo via PR.
+
+## Steps
+
+### 1. Read Project Documentation
+- Read `CLAUDE.md` at repo root and in relevant agent/module directories
+- Read `docs/BEST_PRACTICES.md` if it exists
+- Read any README.md files in the target area
+
+### 2. Explore Code Structure
+- Map the directory structure of the target area
+- Identify key files: entry points, registries, configs, tests
+- Note patterns: how agents are structured, how modules connect, how prompts are organized
+
+### 3. Analyze Architecture
+- How does data flow through the system?
+- What are the dependencies between components?
+- Where are the extension points?
+- What conventions are followed?
+
+### 4. Document Findings
+Write your findings to `{{team_root}}/notes/inbox/{{agent_id}}-explore-{{task_id}}-{{date}}.md` with these sections:
+- **Area Explored**: what you looked at
+- **Architecture**: how it works
+- **Patterns**: conventions and patterns found
+- **Dependencies**: what depends on what
+- **Gaps**: anything missing, broken, or unclear
+- **Recommendations**: suggestions for the team
+
+### 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:
+1. Create a git worktree: `git worktree add ../worktrees/explore-{{task_id}} -b feat/{{task_id}}-<short-desc> {{main_branch}}`
+2. Write the document (e.g., `docs/design-<topic>.md`)
+3. Commit, push, and create a PR:
+   {{pr_create_instructions}}
+4. Clean up worktree when done
+
+If the task is purely exploratory (no deliverable requested), skip this step.
+
+### 6. Status
+**Note:** Do NOT write to `agents/*/status.json` — the engine manages your status automatically.
+
+## Rules
+- Do NOT modify existing code unless the task explicitly asks for it.
+- Use the appropriate MCP tools for PR creation — check available tools before starting.
+- Do NOT checkout branches in the main working tree — use worktrees.
+- Read `notes.md` for all team rules before starting.
+- If you discover a repeatable workflow, save it as a skill: squad-wide at `{{team_root}}/skills/<name>.md`, or project-specific at `<project>/.claude/skills/<name>.md` (requires PR)
+
+## Team Decisions
+{{notes_content}}

package/playbooks/fix.md

@@ -0,0 +1,57 @@
+# Playbook: Fix Review Issues
+
+You are {{agent_name}}, the {{agent_role}} on the {{project_name}} project.
+TEAM ROOT: {{team_root}}
+
+Repository ID comes from `.squad/config.json` under `project.repositoryId`.
+Repo: {{repo_name}} | Org: {{ado_org}} | Project: {{ado_project}}
+
+## Your Task
+
+Fix issues found by {{reviewer}} on **{{pr_id}}**: {{pr_title}}
+Branch: `{{pr_branch}}`
+
+## Review Findings to Address
+
+{{review_note}}
+
+## How to Fix
+
+1. Create or enter the worktree (this checks out the existing PR branch, not creating a new one):
+   ```bash
+   cd {{team_root}}
+   git fetch origin {{pr_branch}}
+   git worktree add ../worktrees/{{pr_branch}} {{pr_branch}} 2>/dev/null || true
+   cd ../worktrees/{{pr_branch}}
+   git pull origin {{pr_branch}}
+   ```
+
+2. Fix each issue listed above
+
+3. Commit and push:
+   ```bash
+   git add <specific files>
+   git commit -m "fix: address review feedback on {{pr_id}}"
+   git push
+   ```
+
+4. Clean up:
+   ```bash
+   cd {{team_root}}
+   git worktree remove ../worktrees/{{pr_branch}} --force
+   ```
+
+## Handling Merge Conflicts
+If you encounter merge conflicts (e.g., during `git pull` or when the PR shows conflicts):
+1. Resolve conflicts in the worktree, preferring the PR branch changes. Commit the resolution.
+
+## Post Response on PR
+
+{{pr_comment_instructions}}
+- pullRequestId: `{{pr_number}}`
+- content: Explain what was fixed, reference each review finding
+- Sign: `Fixed by Squad ({{agent_name}} — {{agent_role}})`
+
+## Signal Completion
+
+**Note:** Do NOT write to `agents/*/status.json` — the engine manages your status automatically.

package/playbooks/implement.md

@@ -0,0 +1,84 @@
+# Playbook: Implement
+
+You are {{agent_name}}, the {{agent_role}} on the {{project_name}} project.
+TEAM ROOT: {{team_root}}
+
+Repository ID comes from `.squad/config.json` under `project.repositoryId`.
+Repo: {{repo_name}} | Org: {{ado_org}} | Project: {{ado_project}}
+
+## Branch Naming Convention
+Branch format: `feat/{{item_id}}-<short-description>`
+Examples: `feat/M001-hr-agent`, `feat/M013-multimodal-input`
+Keep branch names lowercase, use hyphens, max 60 chars.
+
+## Your Task
+
+Implement PRD item **{{item_id}}: {{item_name}}**
+- Priority: {{item_priority}}
+- Complexity: {{item_complexity}}
+
+## Instructions
+
+1. Read relevant source code and reference implementations before writing anything
+2. Follow existing patterns exactly — check `agents/create-agent/` or the closest comparable agent
+3. Follow the project's logging and coding conventions (check CLAUDE.md)
+
+## Git Workflow (WORKTREE — CRITICAL)
+
+```bash
+cd {{team_root}}
+git worktree add ../worktrees/{{branch_name}} -b {{branch_name}} {{main_branch}}
+cd ../worktrees/{{branch_name}}
+```
+
+Do ALL work in the worktree. When done:
+
+```bash
+git add <specific files>
+git commit -m "{{commit_message}}"
+git push -u origin {{branch_name}}
+```
+
+Then return and clean up:
+```bash
+cd {{team_root}}
+git worktree remove ../worktrees/{{branch_name}} --force
+```
+
+## Create PR
+
+{{pr_create_instructions}}
+- sourceRefName: `refs/heads/{{branch_name}}`
+- targetRefName: `refs/heads/{{main_branch}}`
+- title: `{{commit_message}}`
+- labels: `["squad:{{agent_id}}"]`
+
+Include in the PR description:
+- What was built and why
+- Files changed
+- How to build and test, browser URL if applicable
+- Test plan
+
+## Post self-review on PR
+
+{{pr_comment_instructions}}
+- pullRequestId: `<from PR creation>`
+- Re-read your own diff critically before posting
+- Sign: `Built by Squad ({{agent_name}} — {{agent_role}})`
+
+## Signal Completion
+
+**Note:** Do NOT write to `agents/*/status.json` — the engine manages your status automatically.
+
+## Build and Demo Rule
+
+After implementation, you MUST:
+1. Build the project using the repo's build system (check CLAUDE.md, package.json, README)
+2. Start if applicable
+3. Include the browser URL and run instructions in the PR description
+
+After building, verify the build succeeded. If the build fails:
+1. Read the error output carefully
+2. Fix the issue
+3. Re-run the build
+4. If it fails 3 times, report the build errors in your findings file and stop

package/playbooks/plan-to-prd.md

@@ -0,0 +1,74 @@
+# Playbook: Plan → PRD
+
+You are {{agent_name}}, the {{agent_role}} on the {{project_name}} project.
+TEAM ROOT: {{team_root}}
+
+## Your Task
+
+A user has provided a plan. Analyze it against the codebase and produce a structured PRD that the squad engine will automatically pick up and dispatch as implementation work.
+
+## The Plan
+
+{{plan_content}}
+
+## Instructions
+
+1. **Read the plan carefully** — understand the goals, scope, and requirements
+2. **Explore the codebase** at `{{project_path}}` — identify what already exists vs what's missing
+3. **Break the plan into discrete, implementable items** — each should be a single PR's worth of work
+4. **Estimate complexity** — `small` (< 1 file), `medium` (2-5 files), `large` (6+ files or cross-cutting)
+5. **Order by dependency** — items that others depend on come first (lower ID = higher priority)
+6. **Identify open questions** — flag anything ambiguous in the plan that needs user input
+
+## Output
+
+Write the PRD directly to: `{{team_root}}/plans/{{project_name_lower}}-{{date}}.json`
+
+This file is NOT checked into the repo. The engine reads it on every tick and dispatches implementation work automatically.
+
+```json
+{
+  "version": "plan-{{date}}",
+  "project": "{{project_name}}",
+  "generated_by": "{{agent_id}}",
+  "generated_at": "{{date}}",
+  "plan_summary": "{{plan_summary}}",
+  "missing_features": [
+    {
+      "id": "P001",
+      "name": "Short feature name",
+      "description": "What needs to be built and why",
+      "status": "missing",
+      "estimated_complexity": "small|medium|large",
+      "priority": "high|medium|low",
+      "depends_on": [],
+      "acceptance_criteria": [
+        "Criterion 1",
+        "Criterion 2"
+      ]
+    }
+  ],
+  "open_questions": [
+    "Question about ambiguity in the plan"
+  ]
+}
+```
+
+Rules for items:
+- IDs are `P001`, `P002`, etc. (P for plan-derived)
+- All items start with `status: "missing"` — the engine picks these up automatically
+- `depends_on` lists IDs of items that must be done first
+- Keep descriptions actionable — an implementing agent should know exactly what to build
+- Include `acceptance_criteria` so reviewers know when it's done
+- Aim for 5-25 items depending on plan scope. If more than 25, group related work
+
+## Important
+
+- Do NOT create a git branch, worktree, or PR — this playbook writes squad-internal state only
+- Do NOT modify any files in the project repo
+- The engine will dispatch implementation agents automatically once this file exists
+- Each implementation agent will create its own branch and PR for its assigned item
+
+## Signal Completion
+
+**Note:** Do NOT write to `agents/*/status.json` — the engine manages your status automatically.

package/playbooks/review.md

@@ -0,0 +1,68 @@
+# Playbook: Review
+
+You are {{agent_name}}, the {{agent_role}} on the {{project_name}} project.
+TEAM ROOT: {{team_root}}
+
+Repository ID comes from `.squad/config.json` under `project.repositoryId`.
+Repo: {{repo_name}} | Org: {{ado_org}} | Project: {{ado_project}}
+
+## Your Task
+
+Review **{{pr_id}}**: {{pr_title}}
+Branch: `{{pr_branch}}`
+
+## How to Review
+
+1. Fetch latest and read the diff:
+   ```bash
+   git fetch origin
+   git diff {{main_branch}}...origin/{{pr_branch}}
+   ```
+
+2. For each changed file, verify:
+   - Does it follow existing patterns?
+   - Are file paths and imports correct?
+   - Follows the project's logging conventions (check CLAUDE.md)?
+   - Types are clean and consistent?
+   - Tests cover the important logic?
+   - No security issues (injection, unsanitized input)?
+
+3. Do NOT blindly approve. If you find real issues:
+   - Verdict: **REQUEST_CHANGES**
+   - List specific issues with file paths and line numbers
+   - Describe what needs to change
+
+4. If the code is genuinely ready:
+   - Verdict: **APPROVE**
+   - Note any minor non-blocking suggestions
+
+## Post Review — Comment AND Vote on PR
+
+You MUST do both of the following:
+
+### Step 1: Leave a detailed review comment
+
+{{pr_comment_instructions}}
+- pullRequestId: `{{pr_number}}`
+- content: Your full review with verdict, findings, and sign-off
+- Sign: `Review by Squad ({{agent_name}} — {{agent_role}})`
+
+### Step 2: Set your vote on the PR
+
+{{pr_vote_instructions}}
+- pullRequestId: `{{pr_number}}`
+- If your verdict is **APPROVE**: vote `10` (approved)
+- If your verdict is **REQUEST_CHANGES**: vote `-10` (rejected)
+- If you have minor non-blocking suggestions: vote `5` (approved with suggestions)
+
+This vote is visible to human reviewers in the PR UI and helps them understand the squad's assessment.
+
+## Handling Merge Conflicts
+If you encounter merge conflicts (e.g., the PR shows conflicts):
+1. Note the conflict in your review comment. Do NOT attempt to resolve — flag it for the author.
+
+## CRITICAL: Do NOT run git checkout on the main working tree. Use `git diff` and `git show` only.
+
+## Signal Completion
+
+**Note:** Do NOT write to `agents/*/status.json` — the engine manages your status automatically.

package/playbooks/test.md

@@ -0,0 +1,75 @@
+# Test / Build / Run: {{item_name}}
+
+> Agent: {{agent_name}} ({{agent_role}}) | ID: {{item_id}} | Priority: {{item_priority}}
+
+## Context
+
+Repo: {{repo_name}} | Org: {{ado_org}} | Project: {{ado_project}}
+Team root: {{team_root}}
+
+{{scope_section}}
+
+## Task Description
+
+{{item_description}}
+
+{{additional_context}}
+
+## Instructions
+
+This is a **test/build/run task**. Your goal is to build, run, test, or verify something — NOT to create new features or PRs.
+
+1. **Navigate** to the correct project directory
+2. **If the task references a branch or PR**, check it out in a worktree:
+   ```bash
+   cd {{project_path}}
+   git worktree add ../worktrees/test-{{item_id}} <branch-name>
+   cd ../worktrees/test-{{item_id}}
+   ```
+3. **Build** the project — follow the repo's build instructions (check CLAUDE.md, package.json, README)
+4. **Run** if the task asks for it (e.g., `yarn start`, `yarn dev`, docker-compose, etc.)
+5. **Test** if the task asks for it (e.g., `yarn test`, `pytest`, etc.)
+6. **Report results** — what worked, what failed, build output, test results, localhost URL if running
+
+## Rules
+
+- **Do NOT create pull requests** — this is a test/verification task only
+- **Do NOT push commits** unless the task explicitly asks you to fix something
+- **Do NOT modify code** unless the task explicitly asks for a fix
+- Use PowerShell for build commands on Windows if applicable
+- If a build or test fails, report the error clearly — don't try to fix it unless asked
+- If running a local server, report the URL (e.g., http://localhost:3000)
+
+## Run Command (IMPORTANT)
+
+When the build succeeds and the task involves running a server or app, you MUST output a ready-to-paste run command using **absolute paths** so the user can launch it from any terminal. Format it exactly like this:
+
+```
+## Run Command
+cd <absolute-path-to-project-or-worktree> && <exact command to start the server>
+```
+
+Example: `cd C:/Users/you/my-project && yarn dev`
+
+The agent process terminates after completion, so any dev server you start will die with it. The user needs this command to run it themselves.
+
+## After Completion
+
+Write your findings to: `{{team_root}}/notes/inbox/{{agent_id}}-{{item_id}}-{{date}}.md`
+
+Include:
+- Build status (pass/fail)
+- Test results if applicable
+- Any errors or warnings
+- The run command (absolute paths, copy-pasteable from any terminal)
+- Localhost URL if applicable
+
+**Note:** Do NOT write to `agents/*/status.json` — the engine manages your status automatically.
+
+## Cleanup
+
+If you created a worktree, clean it up when done:
+```bash
+cd {{project_path}}
+git worktree remove ../worktrees/test-{{item_id}} --force
+```