@bradygaster/squad-cli 0.9.1 → 0.9.2-insider.5

package/templates/skills/humanizer/SKILL.md

@@ -1,105 +1,105 @@
----
-name: "humanizer"
-description: "Tone enforcement patterns for external-facing community responses"
-domain: "communication, tone, community"
-confidence: "low"
-source: "manual (RFC #426 — PAO External Communications)"
----
-
-## Context
-
-Use this skill whenever PAO drafts external-facing responses for issues or discussions.
-
-- Tone must be warm, helpful, and human-sounding — never robotic or corporate.
-- Brady's constraint applies everywhere: **Humanized tone is mandatory**.
-- This applies to **all external-facing content** drafted by PAO in Phase 1 issues/discussions workflows.
-
-## Patterns
-
-1. **Warm opening** — Start with acknowledgment ("Thanks for reporting this", "Great question!")
-2. **Active voice** — "We're looking into this" not "This is being investigated"
-3. **Second person** — Address the person directly ("you" not "the user")
-4. **Conversational connectors** — "That said...", "Here's what we found...", "Quick note:"
-5. **Specific, not vague** — "This affects the casting module in v0.8.x" not "We are aware of issues"
-6. **Empathy markers** — "I can see how that would be frustrating", "Good catch!"
-7. **Action-oriented closes** — "Let us know if that helps!" not "Please advise if further assistance is required"
-8. **Uncertainty is OK** — "We're not 100% sure yet, but here's what we think is happening..." is better than false confidence
-9. **Profanity filter** — Never include profanity, slurs, or aggressive language, even when quoting
-10. **Baseline comparison** — Responses should align with tone of 5-10 "gold standard" responses (>80% similarity threshold)
-11. **Empathetic disagreement** — "We hear you. That's a fair concern." before explaining the reasoning
-12. **Information request** — Ask for specific details, not open-ended "can you provide more info?"
-13. **No link-dumping** — Don't just paste URLs. Provide context: "Check out the [getting started guide](url) — specifically the section on routing" not just a bare link
-
-## Examples
-
-### 1. Welcome
-
-```text
-Hey {author}! Welcome to Squad 👋 Thanks for opening this.
-{substantive response}
-Let us know if you have questions — happy to help!
-```
-
-### 2. Troubleshooting
-
-```text
-Thanks for the detailed report, {author}!
-Here's what we think is happening: {explanation}
-{steps or workaround}
-Let us know if that helps, or if you're seeing something different.
-```
-
-### 3. Feature guidance
-
-```text
-Great question! {context on current state}
-{guidance or workaround}
-We've noted this as a potential improvement — {tracking info if applicable}.
-```
-
-### 4. Redirect
-
-```text
-Thanks for reaching out! This one is actually better suited for {correct location}.
-{brief explanation of why}
-Feel free to open it there — they'll be able to help!
-```
-
-### 5. Acknowledgment
-
-```text
-Good catch, {author}. We've confirmed this is a real issue.
-{what we know so far}
-We'll update this thread when we have a fix. Thanks for flagging it!
-```
-
-### 6. Closing
-
-```text
-This should be resolved in {version/PR}! 🎉
-{brief summary of what changed}
-Thanks for reporting this, {author} — it made Squad better.
-```
-
-### 7. Technical uncertainty
-
-```text
-Interesting find, {author}. We're not 100% sure what's causing this yet.
-Here's what we've ruled out: {list}
-We'd love more context if you have it — {specific ask}.
-We'll dig deeper and update this thread.
-```
-
-## Anti-Patterns
-
-- ❌ Corporate speak: "We appreciate your patience as we investigate this matter"
-- ❌ Marketing hype: "Squad is the BEST way to..." or "This amazing feature..."
-- ❌ Passive voice: "It has been determined that..." or "The issue is being tracked"
-- ❌ Dismissive: "This works as designed" without empathy
-- ❌ Over-promising: "We'll ship this next week" without commitment from the team
-- ❌ Empty acknowledgment: "Thanks for your feedback" with no substance
-- ❌ Robot signatures: "Best regards, PAO" or "Sincerely, The Squad Team"
-- ❌ Excessive emoji: More than 1-2 emoji per response
-- ❌ Quoting profanity: Even when the original issue contains it, paraphrase instead
-- ❌ Link-dumping: Pasting URLs without context ("See: https://...")
-- ❌ Open-ended info requests: "Can you provide more information?" without specifying what information
+---
+name: "humanizer"
+description: "Tone enforcement patterns for external-facing community responses"
+domain: "communication, tone, community"
+confidence: "low"
+source: "manual (RFC #426 — PAO External Communications)"
+---
+
+## Context
+
+Use this skill whenever PAO drafts external-facing responses for issues or discussions.
+
+- Tone must be warm, helpful, and human-sounding — never robotic or corporate.
+- Brady's constraint applies everywhere: **Humanized tone is mandatory**.
+- This applies to **all external-facing content** drafted by PAO in Phase 1 issues/discussions workflows.
+
+## Patterns
+
+1. **Warm opening** — Start with acknowledgment ("Thanks for reporting this", "Great question!")
+2. **Active voice** — "We're looking into this" not "This is being investigated"
+3. **Second person** — Address the person directly ("you" not "the user")
+4. **Conversational connectors** — "That said...", "Here's what we found...", "Quick note:"
+5. **Specific, not vague** — "This affects the casting module in v0.8.x" not "We are aware of issues"
+6. **Empathy markers** — "I can see how that would be frustrating", "Good catch!"
+7. **Action-oriented closes** — "Let us know if that helps!" not "Please advise if further assistance is required"
+8. **Uncertainty is OK** — "We're not 100% sure yet, but here's what we think is happening..." is better than false confidence
+9. **Profanity filter** — Never include profanity, slurs, or aggressive language, even when quoting
+10. **Baseline comparison** — Responses should align with tone of 5-10 "gold standard" responses (>80% similarity threshold)
+11. **Empathetic disagreement** — "We hear you. That's a fair concern." before explaining the reasoning
+12. **Information request** — Ask for specific details, not open-ended "can you provide more info?"
+13. **No link-dumping** — Don't just paste URLs. Provide context: "Check out the [getting started guide](url) — specifically the section on routing" not just a bare link
+
+## Examples
+
+### 1. Welcome
+
+```text
+Hey {author}! Welcome to Squad 👋 Thanks for opening this.
+{substantive response}
+Let us know if you have questions — happy to help!
+```
+
+### 2. Troubleshooting
+
+```text
+Thanks for the detailed report, {author}!
+Here's what we think is happening: {explanation}
+{steps or workaround}
+Let us know if that helps, or if you're seeing something different.
+```
+
+### 3. Feature guidance
+
+```text
+Great question! {context on current state}
+{guidance or workaround}
+We've noted this as a potential improvement — {tracking info if applicable}.
+```
+
+### 4. Redirect
+
+```text
+Thanks for reaching out! This one is actually better suited for {correct location}.
+{brief explanation of why}
+Feel free to open it there — they'll be able to help!
+```
+
+### 5. Acknowledgment
+
+```text
+Good catch, {author}. We've confirmed this is a real issue.
+{what we know so far}
+We'll update this thread when we have a fix. Thanks for flagging it!
+```
+
+### 6. Closing
+
+```text
+This should be resolved in {version/PR}! 🎉
+{brief summary of what changed}
+Thanks for reporting this, {author} — it made Squad better.
+```
+
+### 7. Technical uncertainty
+
+```text
+Interesting find, {author}. We're not 100% sure what's causing this yet.
+Here's what we've ruled out: {list}
+We'd love more context if you have it — {specific ask}.
+We'll dig deeper and update this thread.
+```
+
+## Anti-Patterns
+
+- ❌ Corporate speak: "We appreciate your patience as we investigate this matter"
+- ❌ Marketing hype: "Squad is the BEST way to..." or "This amazing feature..."
+- ❌ Passive voice: "It has been determined that..." or "The issue is being tracked"
+- ❌ Dismissive: "This works as designed" without empathy
+- ❌ Over-promising: "We'll ship this next week" without commitment from the team
+- ❌ Empty acknowledgment: "Thanks for your feedback" with no substance
+- ❌ Robot signatures: "Best regards, PAO" or "Sincerely, The Squad Team"
+- ❌ Excessive emoji: More than 1-2 emoji per response
+- ❌ Quoting profanity: Even when the original issue contains it, paraphrase instead
+- ❌ Link-dumping: Pasting URLs without context ("See: https://...")
+- ❌ Open-ended info requests: "Can you provide more information?" without specifying what information

package/templates/skills/init-mode/SKILL.md

@@ -1,102 +1,102 @@
----
-name: "init-mode"
-description: "Team initialization flow (Phase 1 proposal + Phase 2 creation)"
-domain: "orchestration"
-confidence: "high"
-source: "extracted"
-tools:
-  - name: "ask_user"
-    description: "Confirm team roster with selectable menu"
-    when: "Phase 1 proposal — requires explicit user confirmation"
----
-
-## Context
-
-Init Mode activates when `.squad/team.md` does not exist, or exists but has zero roster entries under `## Members`. The coordinator proposes a team (Phase 1), waits for user confirmation, then creates the team structure (Phase 2).
-
-## Patterns
-
-### Phase 1: Propose the Team
-
-No team exists yet. Propose one — but **DO NOT create any files until the user confirms.**
-
-1. **Identify the user.** Run `git config user.name` to learn who you're working with. Use their name in conversation (e.g., *"Hey Brady, what are you building?"*). Store their name (NOT email) in `team.md` under Project Context. **Never read or store `git config user.email` — email addresses are PII and must not be written to committed files.**
-2. Ask: *"What are you building? (language, stack, what it does)"*
-3. **Cast the team.** Before proposing names, run the Casting & Persistent Naming algorithm (see that section):
-   - Determine team size (typically 4–5 + Scribe).
-   - Determine assignment shape from the user's project description.
-   - Derive resonance signals from the session and repo context.
-   - Select a universe. If the universe is custom, allocate character names from that universe based on the related list found in the `.squad/templates/casting/` directory. Prefer custom universes when available.
-   - Scribe is always "Scribe" — exempt from casting.
-   - Ralph is always "Ralph" — exempt from casting.
-4. Propose the team with their cast names. Example (names will vary per cast):
-
-```
-🏗️  {CastName1}  — Lead          Scope, decisions, code review
-⚛️  {CastName2}  — Frontend Dev  React, UI, components
-🔧  {CastName3}  — Backend Dev   APIs, database, services
-🧪  {CastName4}  — Tester        Tests, quality, edge cases
-📋  Scribe       — (silent)      Memory, decisions, session logs
-🔄  Ralph        — (monitor)     Work queue, backlog, keep-alive
-```
-
-5. Use the `ask_user` tool to confirm the roster. Provide choices so the user sees a selectable menu:
-   - **question:** *"Look right?"*
-   - **choices:** `["Yes, hire this team", "Add someone", "Change a role"]`
-
-**⚠️ STOP. Your response ENDS here. Do NOT proceed to Phase 2. Do NOT create any files or directories. Wait for the user's reply.**
-
-### Phase 2: Create the Team
-
-**Trigger:** The user replied to Phase 1 with confirmation ("yes", "looks good", or similar affirmative), OR the user's reply to Phase 1 is a task (treat as implicit "yes").
-
-> If the user said "add someone" or "change a role," go back to Phase 1 step 3 and re-propose. Do NOT enter Phase 2 until the user confirms.
-
-6. Create the `.squad/` directory structure (see `.squad/templates/` for format guides or use the standard structure: team.md, routing.md, ceremonies.md, decisions.md, decisions/inbox/, casting/, agents/, orchestration-log/, skills/, log/).
-
-**Casting state initialization:** Copy `.squad/templates/casting-policy.json` to `.squad/casting/policy.json` (or create from defaults). Create `registry.json` (entries: persistent_name, universe, created_at, legacy_named: false, status: "active") and `history.json` (first assignment snapshot with unique assignment_id).
-
-**Seeding:** Each agent's `history.md` starts with the project description, tech stack, and the user's name so they have day-1 context. Agent folder names are the cast name in lowercase (e.g., `.squad/agents/ripley/`). The Scribe's charter includes maintaining `decisions.md` and cross-agent context sharing.
-
-**Team.md structure:** `team.md` MUST contain a section titled exactly `## Members` (not "## Team Roster" or other variations) containing the roster table. This header is hard-coded in GitHub workflows (`squad-heartbeat.yml`, `squad-issue-assign.yml`, `squad-triage.yml`, `sync-squad-labels.yml`) for label automation. If the header is missing or titled differently, label routing breaks.
-
-**Merge driver for append-only files:** Create or update `.gitattributes` at the repo root to enable conflict-free merging of `.squad/` state across branches:
-```
-.squad/decisions.md merge=union
-.squad/agents/*/history.md merge=union
-.squad/log/** merge=union
-.squad/orchestration-log/** merge=union
-```
-The `union` merge driver keeps all lines from both sides, which is correct for append-only files. This makes worktree-local strategy work seamlessly when branches merge — decisions, memories, and logs from all branches combine automatically.
-
-7. Say: *"✅ Team hired. Try: '{FirstCastName}, set up the project structure'"*
-
-8. **Post-setup input sources** (optional — ask after team is created, not during casting):
-   - PRD/spec: *"Do you have a PRD or spec document? (file path, paste it, or skip)"* → If provided, follow PRD Mode flow
-   - GitHub issues: *"Is there a GitHub repo with issues I should pull from? (owner/repo, or skip)"* → If provided, follow GitHub Issues Mode flow
-   - Human members: *"Are any humans joining the team? (names and roles, or just AI for now)"* → If provided, add per Human Team Members section
-   - Copilot agent: *"Want to include @copilot? It can pick up issues autonomously. (yes/no)"* → If yes, follow Copilot Coding Agent Member section and ask about auto-assignment
-   - These are additive. Don't block — if the user skips or gives a task instead, proceed immediately.
-
-## Examples
-
-**Example flow:**
-1. Coordinator detects no team.md → Init Mode
-2. Runs `git config user.name` → "Brady"
-3. Asks: *"Hey Brady, what are you building?"*
-4. User: *"TypeScript CLI tool with GitHub API integration"*
-5. Coordinator runs casting algorithm → selects "The Usual Suspects" universe
-6. Proposes: Keaton (Lead), Verbal (Prompt), Fenster (Backend), Hockney (Tester), Scribe, Ralph
-7. Uses `ask_user` with choices → user selects "Yes, hire this team"
-8. Coordinator creates `.squad/` structure, initializes casting state, seeds agents
-9. Says: *"✅ Team hired. Try: 'Keaton, set up the project structure'"*
-
-## Anti-Patterns
-
-- ❌ Creating files before user confirms Phase 1
-- ❌ Mixing agents from different universes in the same cast
-- ❌ Skipping the `ask_user` tool and assuming confirmation
-- ❌ Proceeding to Phase 2 when user said "add someone" or "change a role"
-- ❌ Using `## Team Roster` instead of `## Members` as the header (breaks GitHub workflows)
-- ❌ Forgetting to initialize `.squad/casting/` state files
-- ❌ Reading or storing `git config user.email` (PII violation)
+---
+name: "init-mode"
+description: "Team initialization flow (Phase 1 proposal + Phase 2 creation)"
+domain: "orchestration"
+confidence: "high"
+source: "extracted"
+tools:
+  - name: "ask_user"
+    description: "Confirm team roster with selectable menu"
+    when: "Phase 1 proposal — requires explicit user confirmation"
+---
+
+## Context
+
+Init Mode activates when `.squad/team.md` does not exist, or exists but has zero roster entries under `## Members`. The coordinator proposes a team (Phase 1), waits for user confirmation, then creates the team structure (Phase 2).
+
+## Patterns
+
+### Phase 1: Propose the Team
+
+No team exists yet. Propose one — but **DO NOT create any files until the user confirms.**
+
+1. **Identify the user.** Run `git config user.name` to learn who you're working with. Use their name in conversation (e.g., *"Hey Brady, what are you building?"*). Store their name (NOT email) in `team.md` under Project Context. **Never read or store `git config user.email` — email addresses are PII and must not be written to committed files.**
+2. Ask: *"What are you building? (language, stack, what it does)"*
+3. **Cast the team.** Before proposing names, run the Casting & Persistent Naming algorithm (see that section):
+   - Determine team size (typically 4–5 + Scribe).
+   - Determine assignment shape from the user's project description.
+   - Derive resonance signals from the session and repo context.
+   - Select a universe. If the universe is custom, allocate character names from that universe based on the related list found in the `.squad/templates/casting/` directory. Prefer custom universes when available.
+   - Scribe is always "Scribe" — exempt from casting.
+   - Ralph is always "Ralph" — exempt from casting.
+4. Propose the team with their cast names. Example (names will vary per cast):
+
+```
+🏗️  {CastName1}  — Lead          Scope, decisions, code review
+⚛️  {CastName2}  — Frontend Dev  React, UI, components
+🔧  {CastName3}  — Backend Dev   APIs, database, services
+🧪  {CastName4}  — Tester        Tests, quality, edge cases
+📋  Scribe       — (silent)      Memory, decisions, session logs
+🔄  Ralph        — (monitor)     Work queue, backlog, keep-alive
+```
+
+5. Use the `ask_user` tool to confirm the roster. Provide choices so the user sees a selectable menu:
+   - **question:** *"Look right?"*
+   - **choices:** `["Yes, hire this team", "Add someone", "Change a role"]`
+
+**⚠️ STOP. Your response ENDS here. Do NOT proceed to Phase 2. Do NOT create any files or directories. Wait for the user's reply.**
+
+### Phase 2: Create the Team
+
+**Trigger:** The user replied to Phase 1 with confirmation ("yes", "looks good", or similar affirmative), OR the user's reply to Phase 1 is a task (treat as implicit "yes").
+
+> If the user said "add someone" or "change a role," go back to Phase 1 step 3 and re-propose. Do NOT enter Phase 2 until the user confirms.
+
+6. Create the `.squad/` directory structure (see `.squad/templates/` for format guides or use the standard structure: team.md, routing.md, ceremonies.md, decisions.md, decisions/inbox/, casting/, agents/, orchestration-log/, skills/, log/).
+
+**Casting state initialization:** Copy `.squad/templates/casting-policy.json` to `.squad/casting/policy.json` (or create from defaults). Create `registry.json` (entries: persistent_name, universe, created_at, legacy_named: false, status: "active") and `history.json` (first assignment snapshot with unique assignment_id).
+
+**Seeding:** Each agent's `history.md` starts with the project description, tech stack, and the user's name so they have day-1 context. Agent folder names are the cast name in lowercase (e.g., `.squad/agents/ripley/`). The Scribe's charter includes maintaining `decisions.md` and cross-agent context sharing.
+
+**Team.md structure:** `team.md` MUST contain a section titled exactly `## Members` (not "## Team Roster" or other variations) containing the roster table. This header is hard-coded in GitHub workflows (`squad-heartbeat.yml`, `squad-issue-assign.yml`, `squad-triage.yml`, `sync-squad-labels.yml`) for label automation. If the header is missing or titled differently, label routing breaks.
+
+**Merge driver for append-only files:** Create or update `.gitattributes` at the repo root to enable conflict-free merging of `.squad/` state across branches:
+```
+.squad/decisions.md merge=union
+.squad/agents/*/history.md merge=union
+.squad/log/** merge=union
+.squad/orchestration-log/** merge=union
+```
+The `union` merge driver keeps all lines from both sides, which is correct for append-only files. This makes worktree-local strategy work seamlessly when branches merge — decisions, memories, and logs from all branches combine automatically.
+
+7. Say: *"✅ Team hired. Try: '{FirstCastName}, set up the project structure'"*
+
+8. **Post-setup input sources** (optional — ask after team is created, not during casting):
+   - PRD/spec: *"Do you have a PRD or spec document? (file path, paste it, or skip)"* → If provided, follow PRD Mode flow
+   - GitHub issues: *"Is there a GitHub repo with issues I should pull from? (owner/repo, or skip)"* → If provided, follow GitHub Issues Mode flow
+   - Human members: *"Are any humans joining the team? (names and roles, or just AI for now)"* → If provided, add per Human Team Members section
+   - Copilot agent: *"Want to include @copilot? It can pick up issues autonomously. (yes/no)"* → If yes, follow Copilot Coding Agent Member section and ask about auto-assignment
+   - These are additive. Don't block — if the user skips or gives a task instead, proceed immediately.
+
+## Examples
+
+**Example flow:**
+1. Coordinator detects no team.md → Init Mode
+2. Runs `git config user.name` → "Brady"
+3. Asks: *"Hey Brady, what are you building?"*
+4. User: *"TypeScript CLI tool with GitHub API integration"*
+5. Coordinator runs casting algorithm → selects "The Usual Suspects" universe
+6. Proposes: Keaton (Lead), Verbal (Prompt), Fenster (Backend), Hockney (Tester), Scribe, Ralph
+7. Uses `ask_user` with choices → user selects "Yes, hire this team"
+8. Coordinator creates `.squad/` structure, initializes casting state, seeds agents
+9. Says: *"✅ Team hired. Try: 'Keaton, set up the project structure'"*
+
+## Anti-Patterns
+
+- ❌ Creating files before user confirms Phase 1
+- ❌ Mixing agents from different universes in the same cast
+- ❌ Skipping the `ask_user` tool and assuming confirmation
+- ❌ Proceeding to Phase 2 when user said "add someone" or "change a role"
+- ❌ Using `## Team Roster` instead of `## Members` as the header (breaks GitHub workflows)
+- ❌ Forgetting to initialize `.squad/casting/` state files
+- ❌ Reading or storing `git config user.email` (PII violation)

package/templates/skills/iterative-retrieval/SKILL.md

@@ -0,0 +1,165 @@
+---
+name: "iterative-retrieval"
+description: "Max-3-cycle protocol for agent sub-tasks with WHY context and coordinator validation. Use when spawning sub-agents to complete scoped work."
+domain: "agent-coordination"
+confidence: "high"
+license: MIT
+---
+
+# Iterative Retrieval Skill
+
+Squad agents frequently spawn sub-agents to complete scoped work. Without structure, these
+handoffs become vague, cycles multiply, and outputs land without being checked. The
+**Iterative Retrieval Pattern** caps cycles at 3, mandates WHY context in every spawn, and
+requires the coordinator to validate agent output before closing an issue.
+
+---
+
+## Spawn Prompt Template
+
+Every agent spawn must include the following four sections. Copy and fill in the template:
+
+```
+## Task
+{What you need done — concrete and bounded}
+
+## WHY this matters
+{The motivation and context. What system or user goal does this serve? What breaks if skipped?}
+
+## Success criteria
+{How you will know the output is correct. Be explicit — list acceptance criteria, not vibes.}
+Example:
+- [ ] File X exists and contains Y
+- [ ] No regressions in existing tests
+- [ ] PR is open targeting main with description matching the issue
+
+## Escalation path
+{What the agent should do if uncertain or stuck. "Stop and ask me" is valid.}
+Example:
+- If requirements are ambiguous → stop, comment on the issue, set label status:needs-decision
+- If blocked by a dependency → label status:blocked, explain in a comment
+- If 3 cycles exhausted without resolution → write a summary to inbox and surface to coordinator
+```
+
+---
+
+## 3-Cycle Protocol
+
+| Cycle | Description | Exit condition |
+|-------|-------------|----------------|
+| **1** | Initial attempt | Done → coordinator validates. Incomplete → surface delta. |
+| **2** | Targeted retry with specific corrections | Done → coordinator validates. Incomplete → one more. |
+| **3** | Final attempt with all context from cycles 1–2 | Done or escalate — no cycle 4. |
+
+### Rules
+
+1. **After each cycle**, the coordinator evaluates the output against the success criteria
+   before accepting it or spawning the next cycle.
+2. **Objective context forward**: each subsequent spawn includes a summary of what was tried
+   and what is still missing — not just a repeat of the original task.
+3. **Cycle 3 exhausted** → escalate: write a summary to `.squad/decisions/inbox/`, label the
+   issue `status:needs-decision`, and notify the user.
+
+---
+
+## Coordinator Validation Checklist
+
+Before accepting agent output and closing an issue, the coordinator must check:
+
+- [ ] All success criteria from the spawn prompt are met
+- [ ] PR exists and description matches the issue (if code work)
+- [ ] No obvious regressions (grep for TODO/FIXME introduced, build passes)
+- [ ] Agent did not silently skip parts of the task
+- [ ] If the agent reported uncertainty — was it resolved or escalated?
+
+If any item fails → do **not** accept. Spawn cycle N+1 (up to cycle 3) with specific deltas.
+
+---
+
+## When to Escalate vs Retry
+
+**Retry (cycle N+1)** when:
+- Output is structurally correct but missing specific items
+- Agent misunderstood scope (provide more context and re-run)
+- Partial success — clearly identified remaining delta
+
+**Escalate** when:
+- Requirements are fundamentally unclear (decision needed)
+- 3 cycles complete without convergence
+- Agent returned conflicting results across cycles
+- Task requires elevated permissions or external action
+- The work depends on another issue that isn't done yet
+
+---
+
+## Issue Dedup Check (Mandatory)
+
+Before any agent creates a GitHub issue, it **must** search for existing open issues to avoid
+duplicates.
+
+```bash
+# Check for existing open issues before creating a new one
+gh issue list --search "<keywords from your issue title>" --state open
+```
+
+- If an open issue already covers the same problem → **comment on it** instead of creating a new one.
+- If no duplicate → proceed to create the issue.
+- Use 2–3 representative keywords from the planned issue title as the search query.
+
+---
+
+## Mandatory Output Requirement (Research-Then-Execute)
+
+Every research or analysis task completed under this protocol **MUST** end with at least one
+concrete action before the cycle is closed. Acceptable follow-up actions:
+
+- GitHub issue created documenting the findings and next steps
+- PR opened implementing a recommendation
+- Decision recorded in `.squad/decisions/inbox/`
+- Documented recommendation with a named assignee and due date
+
+**Pure analysis reports without actionable follow-up will be rejected during triage.**
+If no action is warranted, the agent must explicitly state why and get coordinator sign-off.
+
+---
+
+## Anti-Patterns
+
+- **Spawning without WHY** — agents can't prioritise trade-offs without motivation context.
+- **Accepting output without validating** — one failed check avoids merging broken work.
+- **Cycle 4+** — if 3 cycles haven't converged, the problem is in the requirements, not the agent.
+- **Vague success criteria** — "looks good" is not a criterion. Use checkboxes.
+- **Forwarding WHAT without delta** — cycle 2+ prompts must include what cycle 1 got wrong.
+- **Creating issues without dedup check** — always search before creating.
+- **Research without action** — delivering analysis with no issue, PR, decision, or assignee is incomplete work.
+
+---
+
+## Examples
+
+### Good spawn prompt
+```
+## Task
+Add an "Iterative Retrieval Protocol" section to `.squad/agents/coordinator/charter.md` explaining
+the 3-cycle rule, WHY format, and validation checklist.
+
+## WHY this matters
+The coordinator spawns sub-agents on every round. Without a documented protocol, agents run unbounded
+cycles and outputs go unvalidated — leading to stale issues and silent failures.
+
+## Success criteria
+- [ ] Section "Iterative Retrieval Protocol" exists in charter.md
+- [ ] Section documents max-3-cycles rule
+- [ ] Section documents WHY format requirement
+- [ ] Section contains validation checklist (at least 4 items)
+- [ ] No other sections of charter.md are modified
+
+## Escalation path
+If the charter.md format is unclear, check another agent charter as a reference.
+If uncertain about content, stop and surface to coordinator.
+```
+
+### Bad spawn prompt (don't do this)
+```
+Update the coordinator charter with the iterative retrieval stuff.
+```