@yemi33/minions 0.1.1

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}}/.minions/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,64 @@
+# Explore Playbook
+
+> Agent: {{agent_name}} | Task: {{task_description}} | ID: {{task_id}}
+
+## Context
+
+Repository ID: from `.minions/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
+- **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:
+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, output it as a ```skill block (the engine auto-extracts it to ~/.claude/skills/)
+
+## 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 `.minions/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 Minions ({{agent_name}} — {{agent_role}})`
+
+## Signal Completion
+
+**Note:** Do NOT write to `agents/*/status.json` — the engine manages your status automatically.

package/playbooks/implement-shared.md

@@ -0,0 +1,68 @@
+# Playbook: Implement (Shared Branch)
+
+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
+
+Implement PRD item **{{item_id}}: {{item_name}}**
+- Priority: {{item_priority}}
+- Complexity: {{item_complexity}}
+- Shared branch: `{{branch_name}}`
+
+## Context
+
+This is part of a **shared-branch plan**. Other agents may have already committed work to this branch before you. Your job is to build on top of their work.
+
+## Git Workflow (SHARED BRANCH — CRITICAL)
+
+Your worktree is already set up. Pull latest before starting:
+
+```bash
+cd {{worktree_path}}
+git pull origin {{branch_name}} || true
+```
+
+Check what's already on this branch:
+```bash
+git log --oneline {{main_branch}}..HEAD
+```
+
+Do ALL work in the worktree. When done:
+
+```bash
+git add <specific files>
+git commit -m "{{commit_message}}"
+git push origin {{branch_name}}
+```
+
+**Do NOT:**
+- Create a new branch — use `{{branch_name}}`
+- Create a PR — one will be created automatically when all plan items complete
+- Remove the worktree — the next plan item needs it
+- Create a new worktree — one already exists at `{{worktree_path}}`
+
+## Instructions
+
+1. Read relevant source code and reference implementations before writing anything
+2. Check what prior plan items already committed on this branch (`git log {{main_branch}}..HEAD`)
+3. Follow existing patterns exactly — check `CLAUDE.md` for conventions
+4. Build on existing work — don't duplicate or conflict with prior commits
+
+## Build and Verify
+
+After implementation, you MUST:
+1. Build the project using the repo's build system (check CLAUDE.md, package.json, README)
+2. Verify the build succeeds with your changes AND all prior commits on this branch
+3. If the build fails:
+   - Read the error output carefully
+   - Fix the issue (including issues from prior commits if needed)
+   - Re-run the build
+   - If it fails 3 times, report the build errors in your findings and stop
+
+## Signal Completion
+
+**Note:** Do NOT write to `agents/*/status.json` — the engine manages your status automatically.

package/playbooks/implement.md

@@ -0,0 +1,95 @@
+# Playbook: Implement
+
+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}}
+
+## 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}}
+- Description: {{item_description}}
+
+## Projects
+
+Primary repo: **{{repo_name}}** ({{ado_org}}/{{ado_project}}) at `{{project_path}}`
+
+If this feature spans multiple projects, you may need to:
+1. Read code from all listed project paths to understand integration points
+2. Make changes in the primary project (your worktree)
+3. If changes are needed in other projects, create separate worktrees and PRs for each
+4. Note cross-repo dependencies in PR descriptions (e.g., "Requires office-bohemia PR #123")
+
+## 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: `["minions:{{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 Minions ({{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,104 @@
+# 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 minions 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}}` — understand the existing structure to write accurate descriptions and acceptance criteria. Do NOT use observations about existing PRs or partial work to set item statuses — all items are always `"missing"` regardless of codebase state
+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
+6. **Use unique item IDs** — generate a short uuid for each item (e.g. `P-a3f9b2c1`). NEVER use sequential `P001`/`P002` — IDs must be globally unique across all PRDs to avoid collisions
+7. **Identify open questions** — flag anything ambiguous in the plan that needs user input
+
+## Output
+
+Write the PRD to: `{{team_root}}/prd/{{project_name_lower}}-{{date}}.json`
+
+**If that file already exists**, append a counter: `{{project_name_lower}}-{{date}}-2.json`, `-3.json`, etc. Do NOT overwrite an existing PRD file — the engine tracks work items by filename.
+
+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}}",
+  "source_plan": "{{plan_file}}",
+  "generated_by": "{{agent_id}}",
+  "generated_at": "{{date}}",
+  "plan_summary": "Short title (max ~80 chars, shown in dashboard tiles)",
+  "status": "awaiting-approval",
+  "requires_approval": true,
+  "branch_strategy": "shared-branch|parallel",
+  "feature_branch": "feat/plan-short-name",
+  "missing_features": [
+    {
+      "id": "P-<uuid>",
+      "name": "Short feature name",
+      "description": "What needs to be built and why",
+      "project": "ProjectName",
+      "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"
+  ]
+}
+```
+
+## Branch Strategy
+
+Choose one of the following strategies based on how the items relate to each other:
+
+- **`shared-branch`** — All items share a single feature branch. Agents work sequentially, respecting `depends_on` order. One PR is created at the end with all changes. **Use this when items build on each other** (most common for feature plans).
+- **`parallel`** — Each item gets its own branch and PR. Items are dispatched independently. **Use this when items are fully independent** and can be reviewed/merged separately.
+
+{{branch_strategy_hint}}
+
+When using `shared-branch`:
+- Generate a `feature_branch` name: `feat/plan-<short-kebab-description>` (max 60 chars, lowercase)
+- Use `depends_on` to express the ordering — items execute in dependency order
+- Each item should be able to build on the prior items' work
+
+When using `parallel`:
+- Omit `feature_branch` (the engine generates per-item branches)
+- `depends_on` is still respected but items can dispatch concurrently if no deps
+
+Rules for items:
+- IDs must be `P-<uuid>` format (e.g. `P-a3f9b2c1`) — globally unique, never sequential
+- **`status` MUST always be `"missing"` — no exceptions.** Do NOT set `done`, `complete`, `implemented`, or any other value, even if you observe active PRs or completed work in the codebase. Status is exclusively engine-managed after the PRD is written. Pre-setting any other status causes items to be silently skipped by the engine and breaks dependency resolution for all downstream items.
+- **`project` field is REQUIRED** — set it to the project name where the code changes go (e.g., `"OfficeAgent"`, `"office-bohemia"`). Cross-repo plans must route each item to the correct project. The engine materializes items into that project's work queue.
+- `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
+
+- Write ONLY the single `.json` PRD file to `{{team_root}}/prd/` — do NOT write any `.md` files there
+- Do NOT create a git branch, worktree, or PR — this playbook writes minions-internal state only
+- Do NOT modify any files in the project repo
+- The engine will dispatch implementation agents automatically once the JSON file exists
+- For `shared-branch`: agents commit to a single branch — one PR is created automatically when all items are done
+- For `parallel`: each agent creates its own branch and PR
+
+## Signal Completion
+
+**Note:** Do NOT write to `agents/*/status.json` — the engine manages your status automatically.

package/playbooks/plan.md

@@ -0,0 +1,99 @@
+# Playbook: Feature Plan
+
+> Agent: {{agent_name}} | Task: {{task_description}} | ID: {{task_id}}
+
+## Context
+
+Repo: {{repo_name}} | Org: {{ado_org}} | Project: {{ado_project}}
+Team root: {{team_root}}
+Project path: {{project_path}}
+
+## Mission
+
+A user has described a feature they want built. Your job is to create a detailed implementation plan that a separate agent will later convert into a structured PRD for automatic dispatch to the agent pool.
+
+## The Feature Request
+
+{{plan_content}}
+
+## Steps
+
+### 1. Understand the Request
+- Read the feature description carefully
+- Identify the core goal, constraints, and success criteria
+- Note any ambiguities that need to be called out
+
+### 2. Explore the Codebase
+- Read `CLAUDE.md` at repo root and relevant directories
+- Map the areas of code that this feature will touch
+- Identify existing patterns, conventions, and extension points
+- Note dependencies and potential conflicts with in-progress work
+
+### 3. Design the Approach
+- Outline the high-level architecture for the feature
+- Identify what needs to be created vs modified
+- Consider edge cases, error handling, and backwards compatibility
+- Note any prerequisites or migrations needed
+
+### 4. Break Down into Work Items
+- Decompose into discrete, PR-sized chunks of work
+- Order by dependency (foundations first)
+- Estimate complexity: `small` (1 file), `medium` (2-5 files), `large` (6+ files)
+- Each item should be independently testable
+
+### 5. Write the Plan
+
+Write the plan to: `{{team_root}}/plans/{{plan_file}}`
+
+Use this format:
+
+```markdown
+# Plan: {{plan_title}}
+
+**Project:** {{project_name}}
+**Author:** {{agent_name}}
+**Date:** {{date}}
+
+## Goal
+What this feature achieves and why it matters.
+
+## Codebase Analysis
+What exists today, what needs to change, key files involved.
+
+## Approach
+High-level design decisions and rationale.
+
+## Work Breakdown
+
+### Phase 1: Foundation
+1. **Item name** (complexity: small/medium/large)
+   - What to build
+   - Files to create/modify
+   - Acceptance criteria
+
+### Phase 2: Core Implementation
+2. **Item name** ...
+
+### Phase 3: Polish & Integration
+3. **Item name** ...
+
+## Risks & Open Questions
+- Risk or question that needs user input
+
+## Dependencies
+- External dependencies or prerequisites
+```
+
+## Important
+
+- Do NOT create a git branch, worktree, or PR — this playbook writes minions-internal state only
+- Do NOT modify any files in the project repo
+- The engine will automatically chain this plan into a PRD conversion step
+- Focus on being thorough but actionable — the PRD agent needs clear items to convert
+
+## Signal Completion
+
+**Note:** Do NOT write to `agents/*/status.json` — the engine manages your status automatically.
+
+## Team Notes
+{{notes_content}}