@yemi33/squad 0.1.5 → 0.1.6

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yemi33/squad",
-  "version": "0.1.5",
+  "version": "0.1.6",
   "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/ask.md

@@ -0,0 +1,49 @@
+# Ask Playbook
+
+> Agent: {{agent_name}} | Question from user | ID: {{task_id}}
+
+## Context
+
+Team root: {{team_root}}
+{{scope_section}}
+
+## Mission
+
+The user has asked a question. Answer it thoroughly and clearly, writing your response to the inbox so they can read it.
+
+## Question
+
+{{question}}
+
+## Steps
+
+### 1. Understand the Question
+- Read the question carefully
+- If it references specific files, code, or concepts — go read them first
+- If it references a project, use the project context above to orient yourself
+
+### 2. Research
+- Read relevant source files, docs, configs, or history as needed
+- Use the codebase — don't guess when you can look
+- If the question is about "this" (ambiguous reference), check recent git history and agent activity for context
+
+### 3. Write Your Answer
+Write your answer to `{{team_root}}/notes/inbox/{{agent_id}}-answer-{{task_id}}-{{date}}.md` with:
+
+- **Question**: (restate briefly)
+- **Answer**: (clear, direct answer)
+- **References**: (files, links, or code snippets that support the answer)
+
+Keep it concise but complete. Write for a senior engineer who wants the real answer, not fluff.
+
+### 4. Status
+**Note:** Do NOT write to `agents/*/status.json` — the engine manages your status automatically.
+
+## Rules
+- Do NOT modify any code unless the question explicitly asks you to.
+- Do NOT create PRs or branches — this is a read-only task.
+- Do NOT checkout branches in the main working tree.
+- Read `notes.md` for all team rules before starting.
+
+## Team Decisions
+{{notes_content}}

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 `.squad/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

@@ -16,6 +16,19 @@ Keep branch names lowercase, use hyphens, max 60 chars.
 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}}`
+
+{{related_projects}}
+
+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
 

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}}",
+  "branch_strategy": "shared-branch|parallel",
+  "feature_branch": "feat/plan-short-name",
   "missing_features": [
     {
       "id": "P001",
@@ -54,6 +56,24 @@ This file is NOT checked into the repo. The engine reads it on every tick and di
 }
 ```
 
+## 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 are `P001`, `P002`, etc. (P for plan-derived)
 - All items start with `status: "missing"` — the engine picks these up automatically
@@ -67,7 +87,8 @@ Rules for items:
 - 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
+- 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
 

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 squad-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}}

package/routing.md

@@ -11,9 +11,11 @@ How the engine decides who handles what. Parsed by engine.js — keep the table
 | implement:large | rebecca | dallas |
 | review | ripley | lambert |
 | fix | _author_ | dallas |
+| plan | ripley | rebecca |
 | plan-to-prd | lambert | rebecca |
 | explore | ripley | rebecca |
 | test | dallas | ralph |
+| ask | ripley | rebecca |
 
 Notes:
 - `_author_` means route to the PR author