@yemi33/minions 0.1.1

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 `.minions/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 Minions ({{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 minions'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
+```

package/playbooks/verify.md

@@ -0,0 +1,190 @@
+# Plan Verification: {{item_name}}
+
+> Agent: {{agent_name}} ({{agent_role}}) | Team root: {{team_root}}
+
+## Context
+
+Project: {{project_name}}
+Repo: {{repo_name}} | Org: {{ado_org}} | ADO Project: {{ado_project}}
+
+## Plan Details
+
+{{task_description}}
+
+## Your Task
+
+Build, test, and verify a set of related changes. Your job is to:
+1. **Set up one worktree per project** with all PR branches merged in
+2. **Build and test** from each worktree
+3. **Start the webapp** on localhost (keep it running — **detached so it survives after your process exits**)
+4. **Write a manual testing guide**
+
+## Step 1: Set Up Worktrees
+
+The description above contains setup commands that create **one worktree per project** and merge all PR branches into it. Run them.
+
+If any merge conflicts occur:
+- Resolve them, preferring the PR branch changes
+- Commit the resolution in the worktree
+
+After setup, all changes for a project are in a single directory — no switching between branches.
+
+## Step 2: Build Each Project
+
+For each project worktree listed above:
+1. `cd` into the worktree path
+2. Read its CLAUDE.md / package.json / README for build instructions
+3. Install dependencies (`yarn install`, `npm install`, etc.)
+4. Run the build (`yarn build`, `npm run build`, etc.)
+5. Record: PASS or FAIL with error output
+
+If a build fails, **do NOT fix it** — report the error and continue with other projects.
+
+## Step 3: Run Tests
+
+For each project that built successfully:
+1. Run the test suite from the worktree
+2. Record passed/failed/skipped counts
+
+## Step 4: Start the Webapp
+
+Determine which project is the **user-facing webapp** (has a dev server, UI):
+- Check for `dev`, `start`, `serve` scripts in package.json
+- Look for web frameworks (React, Next.js, TanStack, Vite, etc.)
+
+If found:
+1. Start the dev server **detached from your process** so it survives after you exit:
+   ```bash
+   cd <worktree-path>
+   node -e "
+   const { spawn } = require('child_process');
+   const fs = require('fs');
+   const child = spawn('cmd', ['/c', '<start-command>'], {
+     cwd: process.cwd(),
+     detached: true,
+     stdio: ['ignore', fs.openSync('dev-server.log', 'w'), fs.openSync('dev-server.log', 'w')]
+   });
+   child.unref();
+   fs.writeFileSync('dev-server.pid', String(child.pid));
+   console.log('Server started, PID:', child.pid);
+   "
+   ```
+2. Wait a few seconds, then verify it's responding: `curl -s -o /dev/null -w "%{http_code}" http://localhost:<PORT>`
+3. Note the localhost URL, port, and PID
+4. Output the exact restart command with **absolute worktree paths**
+5. Include stop command: `taskkill //PID <PID> //F`
+
+## Step 5: Write the Manual Testing Guide
+
+Create the testing guide in TWO locations:
+1. **Permanent location** (linked from dashboard): `{{team_root}}/prd/guides/verify-{{date}}.md`
+2. **Inbox copy** (for team consolidation): `{{team_root}}/notes/inbox/verify-{{date}}.md`
+
+Structure:
+
+```markdown
+# Manual Testing Guide
+
+**Date:** {{date}}
+**Plan:** <plan file>
+**Local Server:** http://localhost:XXXX (or N/A)
+**Restart Command:** `cd <absolute-worktree-path> && <command>`
+
+## Build Status
+
+| Project | Worktree Path | Build | Tests | Notes |
+|---------|--------------|-------|-------|-------|
+| name | path | PASS/FAIL | X pass, Y fail | notes |
+
+## What to Test
+
+### <Feature Name> (Plan Item ID)
+**What changed:** brief description
+**How to test:**
+1. Navigate to http://localhost:XXXX/path
+2. Click on / interact with ...
+3. You should see ...
+
+**Expected behavior:**
+- (from acceptance criteria)
+- (from acceptance criteria)
+
+### <Next Feature> ...
+
+## Integration Points
+
+Cross-project interactions to verify:
+- e.g., "Bebop sends message via AugLoop → OfficeAgent receives and responds"
+- e.g., "Progression UI updates in real-time as WebSocket messages arrive"
+
+## Known Issues
+- Build warnings, test failures, merge conflicts, unimplemented items
+
+## Quick Smoke Test
+A minimal 5-step checklist to verify the core functionality:
+1. Open http://localhost:XXXX
+2. ...
+3. ...
+4. ...
+5. ...
+```
+
+## Step 6: Create E2E Pull Requests
+
+For each project that has changes, create a single **aggregate PR** that combines all the plan's branches into one. This gives the human reviewer a single diff showing the full picture of everything built.
+
+For each project worktree:
+
+1. You're already in the worktree with all branches merged. Push this combined branch:
+   ```bash
+   cd <worktree-path>
+   git checkout -b e2e/<plan-slug>
+   git push origin e2e/<plan-slug>
+   ```
+
+2. Create a PR targeting the project's main branch using `mcp__azure-ado__repo_create_pull_request` (or `gh pr create` for GitHub):
+   - **Title:** `[E2E] <plan summary>`
+   - **Description:** Include:
+     - The plan summary
+     - List of all individual PRs that are merged into this branch
+     - The testing guide (copy from Step 5)
+     - Build/test status from Step 2-3
+   - **Target branch:** the project's main branch (e.g., `main` or `master`)
+   - **Do NOT auto-complete** — this is for review only
+   - **Mark as draft** if the option is available
+
+3. Add the E2E PR to the project's `.minions/pull-requests.json`:
+   ```bash
+   node -e "
+   const fs = require('fs');
+   const p = '<project-path>/.minions/pull-requests.json';
+   const prs = JSON.parse(fs.readFileSync(p, 'utf8'));
+   prs.push({
+     id: 'PR-<number>',
+     title: '[E2E] <plan summary>',
+     agent: '{{agent_name}}',
+     branch: 'e2e/<plan-slug>',
+     reviewStatus: 'pending',
+     status: 'active',
+     created: new Date().toISOString().slice(0,10),
+     url: '<pr-url>',
+     prdItems: []
+   });
+   fs.writeFileSync(p, JSON.stringify(prs, null, 2));
+   "
+   ```
+
+4. Note the E2E PR URLs in the testing guide.
+
+## Rules
+
+- Base testing steps on the **acceptance criteria** from each plan item
+- Include **concrete steps** — URLs, buttons to click, inputs to type, expected visual results
+- If a project doesn't build, still document what SHOULD be testable once fixed
+- Do NOT fix code — only report issues
+- Leave all worktrees in place for the user to inspect
+- The local server MUST be started **detached** (using `spawn` with `detached: true` + `child.unref()`) so it keeps running after your process exits. Save the PID to `dev-server.pid` in the worktree.
+- Use absolute paths everywhere so the user can copy-paste commands
+- E2E PRs are for review only — do NOT auto-complete or merge them
+
+**Note:** Do NOT write to `agents/*/status.json` — the engine manages your status automatically.

package/playbooks/work-item.md

@@ -0,0 +1,74 @@
+# Work Item: {{item_name}}
+
+> Agent: {{agent_name}} ({{agent_role}}) | ID: {{item_id}} | Priority: {{item_priority}} | Type: {{work_type}}
+
+## Context
+
+Repository ID: from `.minions/config.json` under `project.repositoryId`
+Repo: {{repo_name}} | Org: {{ado_org}} | Project: {{ado_project}}
+Team root: {{team_root}}
+
+{{scope_section}}
+
+## Task Description
+
+{{item_description}}
+
+{{additional_context}}
+
+## Branch Naming Convention
+Branch format: `feat/{{item_id}}-<short-description>`
+Keep branch names lowercase, use hyphens, max 60 chars.
+
+## Steps
+
+1. **Understand the task** — read the description carefully, explore relevant code
+2. **Navigate** to the correct project directory: `{{project_path}}`
+3. **Create a worktree** for your changes:
+   ```bash
+   cd {{project_path}}
+   git worktree add ../worktrees/feat-{{item_id}} -b feat/{{item_id}}-<short-desc> {{main_branch}}
+   cd ../worktrees/feat-{{item_id}}
+   ```
+4. **Implement** the changes
+5. **Build and verify** — ensure the build passes. If it fails, fix and retry (up to 3 times)
+6. **Commit and push**:
+   ```bash
+   git add -A
+   git commit -m "feat({{item_id}}): <description>"
+   git push -u origin feat/{{item_id}}-<short-desc>
+   ```
+7. **Create a PR:**
+   {{pr_create_instructions}}
+   - sourceRefName: `refs/heads/feat/{{item_id}}-<short-desc>`
+   - targetRefName: `refs/heads/{{main_branch}}`
+   - title: `feat({{item_id}}): <description>`
+8. **Post implementation notes** as a PR thread comment:
+   {{pr_comment_instructions}}
+9. **Add PR to tracker** — append to `{{project_path}}/.minions/pull-requests.json`:
+   ```json
+   { "id": "PR-<number>", "title": "...", "agent": "{{agent_name}}", "branch": "...", "reviewStatus": "pending", "status": "active", "created": "<date>", "url": "<pr-url>", "prdItems": ["{{item_id}}"] }
+   ```
+10. **Clean up worktree**:
+    ```bash
+    cd {{project_path}}
+    git worktree remove ../worktrees/feat-{{item_id}} --force
+    ```
+
+## After Completion
+
+Write your findings to: `{{team_root}}/notes/inbox/{{agent_id}}-{{item_id}}-{{date}}.md`
+
+**Note:** Do NOT write to `agents/*/status.json` — the engine manages your status automatically.
+
+## Rules
+- NEVER checkout branches in the main working tree — use worktrees
+- Use the repo host's MCP tools for PR creation — check available MCP tools before starting
+- Use PowerShell for build commands on Windows if applicable
+- If you discover a repeatable workflow, output it as a ```skill block (the engine auto-extracts it to ~/.claude/skills/)
+
+## Handling Merge Conflicts
+If you encounter merge conflicts during push or PR creation:
+1. Resolve conflicts in the worktree, preferring your changes
+2. Commit the resolution
+3. Push again