feat(skills): add iterative-retrieval skill -- max-3-cycle agent spawn protocol by tamirdresher · Pull Request #622 · bradygaster/squad

tamirdresher · 2026-03-25T21:24:00Z

Summary

Adds the \iterative-retrieval\ skill — a structured protocol for coordinator → sub-agent handoffs that prevents unbounded cycles and silent failures.

Battle-tested in a 13-agent production deployment across 6 months of daily multi-agent orchestration.

What it does

Mandates WHY context in every agent spawn prompt (task + motivation + success criteria + escalation path)
Caps cycles at 3 — if 3 cycles don't converge, the problem is in the requirements, not the agent
Coordinator validation checklist before accepting output and closing issues
Issue dedup check — agents must search before creating GitHub issues
Research-then-execute mandate — pure analysis without a concrete follow-up action is rejected

Design

Provider-agnostic — works with any agent runtime
Fits Squad's coordinator pattern
Complements agent charters (each coordinator can reference this skill)

Zero breaking changes.

chore: promote dev to main (docs dark mode fix)

… protocol Structured protocol for sub-agent spawning: - Mandates WHY context in every spawn prompt - Caps cycles at 3 before escalation - Coordinator validation checklist before accepting output - Issue dedup check to prevent duplicate GitHub issues - Research-then-execute mandate (no pure analysis reports) Battle-tested across 6+ months of production multi-agent orchestration. Zero breaking changes. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

bradygaster · 2026-03-26T06:15:45Z

🔍 Squad Team Review

Reviewed by: Procedures (Prompt Architect) — Pass 3 of consensus ceremony
Action: Hold — proposal-first policy applies
Team Consensus: 5/5 AGREE

Review Summary

This PR introduces iterative-retrieval patterns for skills, enabling multi-step information gathering workflows.

Process Note

Per our team's documented proposal-first policy (.squad/decisions.md): "Meaningful changes require a proposal in docs/proposals/ before execution." This is a feature-class change that needs a proposal document before merge.

What's Needed

Create a proposal in docs/proposals/ describing the skill's purpose, integration points, and expected behavior
Retarget this PR from main to dev (our staging branch)
Once proposal is reviewed and approved, this PR can proceed

Thank you for the contribution! The implementation looks solid — we just need the process alignment. 🙏

⏸️ Action: HOLD — awaiting proposal + retarget to dev

bradygaster

FIDO Quality Review — PR #622: iterative-retrieval skill

Verdict: ⚠️ NEEDS CHANGES

Blocking Issue

❌ Wrong package names in changeset: The .changeset/iterative-retrieval-skill.md uses squad-cli and squad-sdk instead of @bradygaster/squad-cli and @bradygaster/squad-sdk. This will cause changeset resolution to fail.

Fix: Change the changeset frontmatter to:
\\yaml

"@bradygaster/squad-cli": minor
"@bradygaster/squad-sdk": minor

\\

Non-Blocking Notes

Target branch: Targets main — consider dev for consistency with #625.
Frontmatter deviations: Has license: MIT (not in template), missing source field. Minor.
Content quality: Strong. The 3-cycle protocol, spawn prompt template, coordinator validation checklist, and issue dedup check are all well-thought-out. The good/bad spawn prompt examples are particularly useful.
File paths: Correct — packages/squad-cli/templates/skills/ and packages/squad-sdk/templates/skills/.

Fix the changeset package names and this is merge-ready.

tamirdresher · 2026-03-26T08:17:02Z

Fixed per FIDO review: corrected changeset package names from squad-cli/squad-sdk to @bradygaster/squad-cli/@bradygaster/squad-sdk. Also retargeting to dev branch.

bradygaster · 2026-03-26T08:22:39Z

Thank you for this work, Tamir! 🚀

To get this PR ready for team review and merge, we need two quick adjustments:

*Retarget to \dev* — All feature work merges to the \dev\ branch first (not \main). You can change the base branch in the PR settings.
Add a proposal document — Feature-class skills need a brief proposal in \docs/proposals/\ before merging. Include:
- What the skill does
- Why it's needed
- How it fits into our existing skill architecture

Once those are in place, the team will take another look and we can get this merged!

Thanks for your continued contributions to Squad 👍

… FIDO review

tamirdresher · 2026-03-26T08:31:58Z

Fixed per FIDO review: corrected changeset package names from squad-cli/squad-sdk to @bradygaster/squad-cli/@bradygaster/squad-sdk. Also retargeted this PR to the dev branch.

…policy

tamirdresher · 2026-03-26T08:45:02Z

Addressed both review items: (1) Fixed changeset package names to @bradygaster/squad-cli and @bradygaster/squad-sdk. (2) Added docs/proposals/iterative-retrieval.md proposal document. PR already retargeted to dev.

Copilot

Pull request overview

Adds a new “iterative-retrieval” skill that standardizes coordinator → sub-agent handoffs with required WHY context, a max-3-cycle loop cap, and coordinator validation steps, plus accompanying proposal doc and version bumps via changesets.

Changes:

Add the iterative-retrieval skill template to both CLI and SDK template bundles.
Add a written proposal describing the protocol and its intended fit with Squad.
Add a changeset to publish the new skill in both packages.

Reviewed changes

Copilot reviewed 4 out of 4 changed files in this pull request and generated 6 comments.

File	Description
packages/squad-sdk/templates/skills/iterative-retrieval/SKILL.md	New skill documentation shipped with the SDK templates.
packages/squad-cli/templates/skills/iterative-retrieval/SKILL.md	New skill documentation shipped with the CLI templates.
docs/proposals/iterative-retrieval.md	Proposal doc describing the protocol and rationale.
.changeset/iterative-retrieval-skill.md	Changeset to bump CLI/SDK for the new skill addition.

Copilot · 2026-03-28T13:55:10Z

+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


Skill frontmatter deviates from the repo’s documented skill schema (see .squad/skill.md), which expects fields like source and does not mention license. To keep parsing/conventions consistent, add a source: entry (and optional tools: if relevant) and avoid introducing nonstandard keys unless they’re used elsewhere.

Suggested change

license: MIT

source: "packages/squad-sdk/templates/skills/iterative-retrieval"

Copilot · 2026-03-28T13:55:10Z

+Example:
+- [ ] File X exists and contains Y
+- [ ] No regressions in existing tests
+- [ ] PR is open targeting main with description matching the issue


The success-criteria example says the PR should target main, but this repo’s contributing process uses --base dev (CONTRIBUTING.md). Consider changing this to dev or wording it generically as “default branch” so the template matches the project’s workflow.

Suggested change

- [ ] PR is open targeting main with description matching the issue

- [ ] PR is open targeting the project's default branch with description matching the issue

Copilot · 2026-03-28T13:55:10Z

+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


Skill frontmatter deviates from the repo’s documented skill schema (see .squad/skill.md), which expects fields like source and does not mention license. To keep parsing/conventions consistent, add a source: entry (and optional tools: if relevant) and avoid introducing nonstandard keys unless they’re used elsewhere.

Suggested change

license: MIT

source: "templates/skills/iterative-retrieval"

Copilot · 2026-03-28T13:55:11Z

+Example:
+- [ ] File X exists and contains Y
+- [ ] No regressions in existing tests
+- [ ] PR is open targeting main with description matching the issue


The success-criteria example says the PR should target main, but this repo’s contributing process uses --base dev (CONTRIBUTING.md). Consider changing this to dev or wording it generically as “default branch” so the template matches the project’s workflow.

Suggested change

- [ ] PR is open targeting main with description matching the issue

- [ ] PR is open targeting dev with description matching the issue

Copilot · 2026-03-28T13:55:11Z

+
+| Risk | Likelihood | Impact | Mitigation |
+|------|-----------|--------|------------|
+| 3-cycle limit is too restrictive for complex tasks | Low | Medium | Skill explicitly allows coordinator to extend with justification |


The Risks/Mitigations table says the skill “explicitly allows coordinator to extend with justification,” but the skill text states “no cycle 4.” Please align these (either document the extension mechanism in the skill, or update this mitigation to reflect a strict cap).

Suggested change

| 3-cycle limit is too restrictive for complex tasks | Low | Medium | Skill explicitly allows coordinator to extend with justification |

| 3-cycle limit is too restrictive for complex tasks | Low | Medium | Strict 3-cycle cap; coordinator must escalate or stop at cycle 3 (no extension) |

Copilot · 2026-03-28T13:55:11Z

+"@bradygaster/squad-cli": minor
+"@bradygaster/squad-sdk": minor
+---
+feat: add iterative-retrieval skill for structured max-3-cycle agent spawning


Most changesets in this repo use an imperative sentence without a feat: prefix (e.g. .changeset/cross-squad-orchestration.md). Consider dropping the feat: prefix here so the generated changelog stays consistent.

Suggested change

feat: add iterative-retrieval skill for structured max-3-cycle agent spawning

add iterative-retrieval skill for structured max-3-cycle agent spawning

bradygaster and others added 2 commits March 23, 2026 10:08

Merge pull request bradygaster#570 from bradygaster/dev

6a656b0

chore: promote dev to main (docs dark mode fix)

bradygaster requested changes Mar 26, 2026

View reviewed changes

bradygaster mentioned this pull request Mar 26, 2026

feat(skills): add directive-capture skill -- auto-detect and persist user directives #614

Closed

tamirdresher changed the base branch from main to dev March 26, 2026 08:16

fix: correct changeset package names to @bradygaster scoped names per…

511b0f5

… FIDO review

tamirdresher force-pushed the feat/iterative-retrieval-skill branch from 9a98215 to 511b0f5 Compare March 26, 2026 08:30

feat: add proposal document for iterative-retrieval skill per review …

c7a4294

…policy

Merge branch 'dev' into feat/iterative-retrieval-skill

9bc2b0b

Copilot AI review requested due to automatic review settings March 28, 2026 13:49

Copilot started reviewing on behalf of bradygaster March 28, 2026 13:50 View session

Copilot AI reviewed Mar 28, 2026

View reviewed changes

bradygaster merged commit 87e9381 into bradygaster:dev Mar 28, 2026
7 checks passed

	license: MIT
	source: "packages/squad-sdk/templates/skills/iterative-retrieval"

	- [ ] PR is open targeting main with description matching the issue
	- [ ] PR is open targeting the project's default branch with description matching the issue

	- [ ] PR is open targeting main with description matching the issue
	- [ ] PR is open targeting dev with description matching the issue

	\| 3-cycle limit is too restrictive for complex tasks \| Low \| Medium \| Skill explicitly allows coordinator to extend with justification \|
	\| 3-cycle limit is too restrictive for complex tasks \| Low \| Medium \| Strict 3-cycle cap; coordinator must escalate or stop at cycle 3 (no extension) \|

	feat: add iterative-retrieval skill for structured max-3-cycle agent spawning
	add iterative-retrieval skill for structured max-3-cycle agent spawning

Conversation

tamirdresher commented Mar 25, 2026

Summary

What it does

Design

Uh oh!

bradygaster commented Mar 26, 2026

🔍 Squad Team Review

Review Summary

Process Note

What's Needed

Uh oh!

bradygaster left a comment

Choose a reason for hiding this comment

FIDO Quality Review — PR #622: iterative-retrieval skill

Blocking Issue

Fix: Change the changeset frontmatter to: \\yaml

"@bradygaster/squad-cli": minor "@bradygaster/squad-sdk": minor

Non-Blocking Notes

Uh oh!

tamirdresher commented Mar 26, 2026

Uh oh!

bradygaster commented Mar 26, 2026

Uh oh!

tamirdresher commented Mar 26, 2026

Uh oh!

tamirdresher commented Mar 26, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Copilot AI Mar 28, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Mar 28, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Mar 28, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Mar 28, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Mar 28, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Mar 28, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Fix: Change the changeset frontmatter to:
\\yaml

"@bradygaster/squad-cli": minor
"@bradygaster/squad-sdk": minor