| name | sprint |
| description | Wave-based execution of a feature/task by a multi-agent team — research → wave plan (5-8 agents in 2-5 waves) → approval → wave-by-wave teammate spawn via TeamCreate. Two modes — full sprint (with research phase) and lightweight wave (uses current chat context). Each wave is independent parallel work by agents under strict file ownership; dependent tasks go in the next wave. At every wave-close, **automatically emits one EvidencePack per touched artifact via forgeplan MCP** (`mcp__forgeplan__forgeplan_new` + `forgeplan_update` + `forgeplan_link`) — no opt-in. At sprint-close, prompts the user to bulk-activate the collected EVIDs. Soft CLI fallback if MCP unavailable; warns instead of silent-skip if a sprint closes with zero EVIDs. Use for large feature implementation, refactor sprints, milestones. Triggers (EN/RU) — "sprint", "wave plan", "implement feature in waves", "запусти спринт", "распланируй волны", "реализуй фичу", "implement RFC-XXX", "/sprint", "/wave". |
| origin | forgeplan |
Wave-Based Sprint Execution
Wave-based task execution — research, plan, approval, wave-by-wave teammate spawn.
Combines two modes: full sprint (research-first) and lightweight wave (uses
chat context). Builds on team and, when needed,
research.
Project context (read first)
If /setup ran in the project, paths, commands, and terminology are pinned in:
@docs/agents/paths.md — where RFCs, TODOs, sources live (for the file-ownership map)@docs/agents/build-config.md — build/test commands for inter-wave checks@CONTEXT.md — domain glossary (use when phrasing teammate tasks)
Check with test -d docs/agents. If present, hand it to teammates in the prompt.
If not, auto-detect: glob the project, parse package.json / Cargo.toml / go.mod
for commands.
Never assume pnpm/cargo/etc or specific paths — read docs/agents/*.md or detect
in-session.
Tool selection (MCP vs shell — PRD-021)
/sprint uses forgeplan for claim, dispatch, new evidence, link. Two paths:
| Path | When | How |
|---|
| MCP-first (preferred) | mcp__forgeplan__* tools present in deferred-tools list (forgeplan MCP server wired and reachable) | Call mcp__forgeplan__forgeplan_claim, forgeplan_dispatch, forgeplan_new, forgeplan_link directly. Returns typed dicts + _next_action server hint to relay. |
| Shell fallback | MCP tools absent (server not started, or .mcp.json not configured) | forgeplan claim ... / forgeplan dispatch ... via Bash. Same semantics, less structured I/O. |
| Neither available | command -v forgeplan fails | Warn, skip artifact ops, run sprint as chat-driven coordination only |
How to probe: list available tools via ToolSearch query="select:mcp__forgeplan__forgeplan_health". If schema returns — MCP path active. Else shell. Probe once per sprint, not per teammate.
Teammate sub-agents inherit: when team-lead spawns teammates, include the probe result + the appropriate command syntax in the teammate prompt (see §4b.g below).
When to use
- Big feature / RFC needing 5-8+ agents and 2-5 waves.
- Refactor with clear dependency layers.
- Milestone of many sub-tasks that can be partially parallelized.
- User said: "sprint", "wave", "реализуй", "implement RFC-XXX", "запусти волны".
When NOT to use
- Pinpoint fix (1 file, 1 function) — single agent.
- Pure research without an implementation plan —
research.
- Code review —
audit.
Two modes
| Mode | When | Step 1 | Step 2 |
|---|
| Full Sprint | Fresh task, empty or thin context | Research via research (3 parallel Explore agents) | Generate plan |
| Lightweight Wave | Task already discussed, context is rich | Extract context from chat (skip research) | Generate plan |
All other steps are shared.
Iron Rules
The six iron rules from team apply here without
exception — TeamCreate-only, team-lead = coordinator, teammates do all
the work, extra work spawns a new teammate, ask before TeamDelete,
one-file-per-agent-per-wave. Read them in team; do not paraphrase
them in plans (they drift).
Sprint-specific application: file ownership is enforced at the wave
level — within a single wave, every file is owned by exactly one teammate;
if two teammates need the same file, split into sequential waves. See
the wave examples below for how this maps to a real plan.
Step 1: Research / Extract context
Full Sprint (default)
3 parallel Explore agents:
Agent R1: Read RFC + TODO
→ Read referenced RFC (if any)
→ Read relevant TODO sections (offset/limit)
→ Extract: completed phases, remaining work, blockers
Agent R2: Scan codebase
→ Glob/Grep for files related to scope
→ Map: existing, reusable, file ownership
→ Note patterns from similar modules
Agent R3: Memory + known issues
→ memory_recall("{topic}") if available
→ Read KNOWN-ISSUES.md
→ Recent git log for context
(Can delegate to research for the deep variant.)
Lightweight Wave
Don't spawn Explore agents. Extract from chat:
- Files read or discussed.
- Tasks / TODOs mentioned.
- Architectural decisions taken.
- RFC references.
- User preferences / requirements.
Plus quick local checks:
git branch --show-current
Context summary (shared)
Branch: {git}
Task: {what we're doing}
Done: {checkboxes from RFC/TODO}
Remaining: {what's left}
Key files: {from chat or research}
Constraints: {from CLAUDE.md, RFC, user preferences}
Step 2: Generate FULL TEXT PLAN
Sizing rules
| Context | Waves | Agents total |
|---|
| Small (1-3 tasks) | 1-2 | 2-4 |
| Medium (4-8 tasks) | 2-3 | 4-6 |
| Large (9+ tasks) | 3-5 | 5-8 |
Hard limits:
- Max 5 waves.
- Max 5 agents per wave.
- Max 400 LOC per agent (>400 — split into 2 agents).
- Min 100 LOC per agent (<100 — merge with another).
Agent description format
**Agent {i}: `{kebab-name}`** (subagent_type: `{type}`)
- Files: NEW/MODIFY
- `{path}` (~{LOC})
- Task: {one-line}
- Study: {2-4 files FIRST}
- Create: {bullet points}
- Requirements: {2-4 constraints}
Subagent type selection
| Task type | subagent_type |
|---|
| Generic implementation | general-purpose |
| Frontend (React/Vue/etc) | frontend-developer / nextjs-developer |
| Backend / API / services | backend-architect / microservices-architect |
| TypeScript types | typescript-pro |
| Tests | general-purpose or tester |
| Docs | documentation-engineer |
(Adapt to subagent types available in the project's agents/ dir.)
Bake project red lines into the plan (marketplace#169)
Before Step 3 presents the plan, fold the project's hard constraints —
host-isolation, allow-lists, primitive-ownership, or any other MUST-NOT
rule — verbatim into the plan itself (not paraphrased), so the plan
review (Step 3) catches a spec-vs-constraint violation before any teammate
is spawned. Pull them from CLAUDE.md/AGENTS.md "Hard rules"/"Red lines"
if present. A plan that would violate a red line should propose the
constraint-respecting alternative directly (client-side instead of a
forbidden server endpoint, etc.) rather than being caught only after Wave 1
fails.
Wave dependency patterns
- Foundation → Features → Polish
- Backend → Frontend → Integration
- Parallel Domains → Integration → Tests
Within a wave — parallel. Between waves — sequential, dependencies flow through files.
Step 3: Present plan, wait for approval
CRITICAL: emit the plan as text. No execution until the user says "go".
# {Title} — Sprint/Wave Plan
## Context
- Branch: `{branch}`
- RFC: `{path}` (if any)
- TODO: `{path}` (with line range if known)
## Already done
✅ {item 1} ({summary — LOC, tests, deliverables})
✅ {item 2} (...)
## Remaining work
### {Category 1}: {name} (~{LOC})
- {sub-task} (~{LOC})
### {Category 2}: {name}
- [ ] {task} (~{LOC}) — `{file-path}`
## Existing resources (study them!)
| File | What's there | How to reuse |
|---|---|---|
| `{path}` | {desc} | {how} |
## Waves
### Wave 1 — {Name}: {summary} ({M} agents in parallel)
**Agent 1: `{name}`** (subagent_type: `{type}`)
- Files: NEW
- `{path}` (~{LOC})
- Task: ...
- Study: ...
- Create: ...
- Requirements: ...
**Agent 2: `{name}`** (...)
...
### Wave 2 — ... (same pattern)
## File Ownership
| Agent | Files (NEW/MODIFY) | Read-only deps |
|---|---|---|
| agent-1 | shared/types.ts (NEW) | — |
| agent-2 | features/store.ts (NEW) | shared/types.ts |
| agent-3 | features/page.tsx (NEW) | features/store.ts |
(If two agents in the same wave touch one file — stop and replan.)
## Dependencies
Wave 1: [agent-a] [agent-b] [agent-c] — parallel
↓
Wave 2: [agent-d] [agent-e] — parallel
↑ depends on {what from wave 1}
## Key files
| File | Why |
|---|---|
| `{path}` | reason |
## Rules
1. Each agent — ONLY its own files.
2. Follow CLAUDE.md project rules.
3. {sprint-specific rule from research / chat}
4. 0 new type-check errors.
## Effort Summary
| Wave | Agents | LOC | Tests | Description |
|---|---|---|---|---|
| 1 | 3 | ~420 | 12 | Foundation |
| 2 | 3 | ~810 | 18 | Features |
After the plan — ask:
---
**Plan ready. {N} waves, {M} agents, ~{LOC} LOC, ~{tests} tests.**
Options:
1. ✅ Run it — TeamCreate → Wave 1
2. ✏️ Adjust — tell me what to change
3. 📋 Save plan to file
4. ❌ Cancel
Don't proceed until an explicit "go" / "yes" / "1".
Step 4: Execute wave-by-wave
4a. Setup
1. CHECK existing teams:
- If a "sprint-*" / "wave-*" team exists — check state:
· all teammates finished? → DONE
· unresponsive / stuck? → HUNG
· still working? → ACTIVE (wait or ask)
- ASK user: "Team '{name}' — {status}. TeamDelete it?"
- Confirmed → TeamDelete | Refused → ask what to do
2. TeamCreate(team_name="sprint-{topic}" or "wave-{topic}")
3. team-lead = coordination ONLY
4. teammates = all the work
4a-bis. Forgeplan dispatch + session derivation
Always run when forgeplan is reachable (MCP or shell) — even for chat-driven sprints. The dispatcher needs affected_files on real artifacts to be useful, but the session-id derivation below applies to every sprint regardless.
MCP-first path (per Tool Selection preamble):
SESSION_ID = "SESSION-" + datetime.utcnow().strftime("%Y-%m-%d-%H%M%S")
if has_real_artifact_ids(wave_plan):
result = mcp__forgeplan__forgeplan_dispatch(agents={agents-per-wave})
relay_to_report(result.get("_next_action"))
else:
log(f"dispatch skipped — no artifact IDs in plan; using {SESSION_ID}")
Shell fallback (when MCP tools absent):
SESSION_ID="SESSION-$(date -u +%Y-%m-%d-%H%M%S)"
if grep -qE 'PRD-[0-9]+|RFC-[0-9]+|SPEC-[0-9]+' <<< "{wave-plan-text}"; then
command -v forgeplan && forgeplan dispatch -n {agents-per-wave} --json
else
echo "dispatch skipped — no artifact IDs in plan; will use $SESSION_ID for claim-loop"
fi
The SESSION-YYYY-MM-DD-HHMMSS synthetic ID is load-bearing — it's what teammates claim in §4b.g when no real artifact-ID is present. Without it, chat-driven sprints would leave forgeplan claims empty and forgeplan activity would have no agent attribution.
forgeplan dispatch (when called) returns a parallel-safe grouping (PRD-057 dispatcher with Jaccard file-overlap detection at threshold 0.3). Use it as a second opinion on your wave plan:
| Dispatch says | Your plan says | Action |
|---|
| Group A: [PRD-001, PRD-003] | Same wave | ✅ go |
| Group A: [PRD-001, PRD-003] | Different waves | OK — your split is more conservative; go |
| Group A: [PRD-001, PRD-003] | Same wave, but PRD-001 and PRD-003 share files in your file-ownership table | ⚠️ stop — your file map disagrees with Jaccard. Re-check the ownership table before spawning |
Pass each agent the artifact ID they own — see 4b teammate prompt addendum below.
4b. Team-lead prompt
You are the team lead for "{title}".
!!! IRON RULE — YOUR ROLE: COORDINATE ONLY !!!
- You do NOT write code. EVER.
- You do NOT edit files. EVER.
- You do NOT run tests. EVER.
- You ONLY: spawn teammates → monitor → verify → report → next wave.
- Extra work discovered? → Spawn NEW teammate. NEVER add to existing.
## Full Plan
{plan from Step 3}
## Execution Protocol
For each Wave (sequential):
1. ANNOUNCE: "🌊 Wave {N}/{total}: {wave name} — spawning {M} agents"
2. SPAWN all wave agents as teammates (parallel).
Each teammate prompt includes:
a) Their specific task from plan
b) Files they own (NEW/MODIFY)
c) What to study FIRST
d) Requirements
e) "Follow CLAUDE.md project rules"
f) "Report back: files created/modified, LOC, issues"
g) Forgeplan-aware — UNCONDITIONAL claim/release loop (PRD-020 + PRD-021 MCP-first):
Each teammate uses `${ARTIFACT_ID:-$SESSION_ID}` — real artifact when present, derived
`SESSION-YYYY-MM-DD-HHMMSS` (set in §4a-bis) as fallback for chat-driven sprints.
**MCP-first** (when teammate sees `mcp__forgeplan__forgeplan_claim` in their tool list):
- BEFORE starting work: call `mcp__forgeplan__forgeplan_claim(id="${ARTIFACT_ID:-$SESSION_ID}", agent="{kebab-name}", note="{wave-N task}")`
— capture the response's `_next_action` for inclusion in final report.
- AFTER completing: report the artifact ID (or session ID) + LOC summary so team-lead can
emit `mcp__forgeplan__forgeplan_new(kind="evidence", title="...")` post-wave.
- On failure / abort: `mcp__forgeplan__forgeplan_release(id="${ARTIFACT_ID:-$SESSION_ID}", agent="{kebab-name}")` to free the slot.
**Shell fallback** (MCP tools not present):
- BEFORE: `forgeplan claim ${ARTIFACT_ID:-$SESSION_ID} --agent {kebab-name} --note "{wave-N task}"`
- AFTER: report ID + LOC for team-lead to emit `forgeplan new evidence ...`
- On failure: `forgeplan release ${ARTIFACT_ID:-$SESSION_ID} --agent {kebab-name}`
Why unconditional: PRD-018 operating contract + PRD-020 close the gap where chat-driven
sprints (no artifact ID in the task) bypassed the artifact graph entirely. PRD-021 adds
MCP-first preference: when MCP tools are available, prefer them — they return typed dicts
and methodology hints (`_next_action`) that can be relayed verbatim to user reports.
3. WAIT for all wave agents to complete.
4. VERIFY:
- Did all agents report completion?
- Any type-check errors? (ask one agent to run typecheck)
- Any file conflicts?
5. UPDATE task overlay (send to user):
"✅ Wave {N} complete: {summary}
Remaining: Wave {N+1}..."
6. ASK user: "Wave {N} done. Continue to Wave {N+1}? (yes / pause / abort)"
After ALL waves:
1. Final verification (typecheck/build/tests).
2. INSIGHTS EXTRACTION (mandatory — see Step 6).
3. SPRINT-CLOSE EVID BULK ACTIVATION (mandatory — see Step 7).
4. Summary report.
5. Shutdown teammates.
6. Signal completion.
4b-bis. Wave-close evidence autopublish (MANDATORY — PRD-077 FR-012)
This step is not optional. Team-lead MUST execute it after every wave that
reports back. Skipping it = sprint methodology failure → forgeplan health
stays blind and forgeplan score underweights the work.
After all teammates in wave N report back, team-lead runs the autopublish
algorithm before announcing "wave complete" to the user:
Algorithm
1. enumerate touched_artifacts (set):
- any PRD-NNN / RFC-NNN / SPEC-NNN / ADR-NNN / EPIC-NNN ID mentioned in:
a) teammate prompts (the {ARTIFACT_ID} they claimed)
b) commit Refs: trailers landed during this wave
c) the wave-plan's File Ownership / Effort tables
- dedupe (one EVID per artifact, even if 2-3 teammates worked on it)
2. if touched_artifacts is empty:
- this is a chat-driven wave with no artifact attribution
- emit ONE session-level EVID linked to the SESSION_ID (§4a-bis), title:
"{SESSION_ID}: wave N — {1-line work summary}"
- skip the per-artifact link step; SESSION_IDs are ephemeral
- continue to step 5
3. for each artifact_id in touched_artifacts:
a) build EVID title: "{sprint_name}: wave N — {work summary for this artifact}"
b) build EVID body (see §4b-ter for the required structured fields)
c) MCP-first: evid = mcp__forgeplan__forgeplan_new(kind="evidence", title=...)
mcp__forgeplan__forgeplan_update(id=evid["id"], body=...)
mcp__forgeplan__forgeplan_link(source=evid["id"], target=artifact_id, relation="informs")
relay evid["_next_action"] into the wave-close report
d) Shell fallback (MCP unavailable, see step 6):
forgeplan new evidence "{title}" # capture EVID-MMM from output
$EDITOR .forgeplan/evidence/EVID-MMM-*.md # fill ## Structured Fields
forgeplan link EVID-MMM {artifact_id} --relation informs
4. record (evid_id, target_artifact_id, wave_n) in the sprint's collected_evids
list — used by §7 sprint-close batch prompt.
5. announce in the wave-close handoff (see §4d):
"Wave N evidence: {len(collected_evids_this_wave)} EVID(s) emitted —
{EVID-AAA → PRD-XXX, EVID-BBB → RFC-YYY, …}"
6. if MCP tools unavailable AND CLI fallback also fails (no forgeplan binary on PATH):
- DO NOT silently skip
- WARN explicitly: "MCP+CLI both unavailable — N evidence captures
deferred. Copy-paste these commands manually after the sprint:
<print the would-have-been shell commands>"
- still record placeholder entries in collected_evids so §7 surfaces them
Why per-artifact, not per-teammate or per-wave
- A single artifact may be built by 2-3 teammates across waves (Wave 1 scaffolding + Wave 2 integration). Evidence describes the artifact's state, not whose hands.
- One wave may touch 0, 1, or many artifacts — the algorithm handles all three.
- One artifact may accumulate multiple EVIDs across waves (Wave 1 EVID for "scaffolded", Wave 2 EVID for "integration done"). These are linked separately and bulk-activated together in §7.
Do NOT auto-activate at this step
Wave-close emits draft EVIDs. Activation is batched at sprint close (§7) so
the user reviews all evidence at once instead of being interrupted N times.
4b-ter. EvidencePack body — required structured fields
Critical for R_eff. Without these fields the parser sets CL0
(penalty 0.9) and the artifact's score collapses to 0.1. The autopublish
writes them automatically; if you customize the body, do not strip them.
After forgeplan_new returns the EVID ID, immediately call forgeplan_update
(or edit the file in CLI fallback) with a body matching this template:
## Structured Fields
verdict: supports
congruence_level: 3
evidence_type: measurement
## Wave summary
- Sprint: {sprint_name}
- Wave: {N} of {total}
- Workers spawned: {kebab-name-1}, {kebab-name-2}, ...
- Commits: {short-sha-1}, {short-sha-2}, ... # only this wave's commits
- Files changed: {count} ({list — truncate to top 5 + "+ N more"})
- Tests added: {count} ({pass/fail summary})
- Pipeline gates: fmt ✓, check ✓, test ✓, clippy ✓ # whichever ran
- Merge commit: {sha if integration branch already merged, else "pending"}
## Acceptance criteria validation
{paste the acceptance criteria for this artifact and tick ✓/✗ each one}
Defaults rationale: sprint work is the implementation of acceptance
criteria from the parent PRD/RFC. That maps to evidence_type: measurement
(quantitative check against criteria). verdict: supports is the default
because sprint completion implies the design hypothesis held; flip to
weakens only if the wave produced contrary findings (rare — usually those
go into a separate EVID via /audit).
congruence_level: 3 (CL3, same-context) is the default because the EVID
captures the exact artifact it informs. Lower only if cross-artifact
inferences were involved.
4c. Dynamic teammates
If extra work surfaces mid-wave (bug, missing file, needed component):
- Team-lead spawns a NEW teammate for that task
- New teammate runs in ITS OWN process, ITS OWN context
- Don't pile on existing teammates
- Team-lead waits for ALL teammates (original + new) before closing the wave
4c-bis. Resilience: self-verify + claim-sweep on teammate crash (marketplace#169)
If a wave teammate crashes or a verify/review dispatch fails (e.g. the
StructuredOutput retry-cap — see the claim-hygiene discipline in
AGENT-AUTHORING-GUIDE.md), team-lead does two things, not one:
- Self-verify — re-run the affected checks yourself
(typecheck/build/tests for a crashed builder; re-read the diff for a
crashed reviewer) instead of closing the wave on an unverified claim.
Record the substitute verification in the wave's EVID body (§4b-ter).
- Sweep the claim — if the crashed teammate held a
forgeplan_claim
(§4b.g), release it (forgeplan_release --force) before the wave
closes; don't wait for TTL. A held claim blocks the next wave's
dispatch onto that artifact.
Don't ship a wave as "complete" on a crashed teammate's say-so.
4d. Wave handoff + token budget
Between waves, hand off to the user with a progress snapshot and next-step options. Format and token-budget warning thresholds (30% / 15%) are defined verbatim in references/OUTPUT-FORMATS.md §1.
Always emit the handoff at the same moments — never skip, never improvise the layout mid-sprint.
Step 5: Wave completion overlay
After each wave, emit a cumulative task overlay. Format is defined verbatim in references/OUTPUT-FORMATS.md §2 — table of waves with status / agents / LOC / output, files modified, key decisions, next wave, and a fixed set of user-facing options.
Use the format as-is; don't redesign it mid-sprint.
Step 6: Final — Insights Extraction (MANDATORY)
After ALL waves complete, the team must extract and document insights.
Without this, the sprint is not finished.
What to collect
- Architectural decisions (ADR) — what was chosen and why.
- Bottlenecks — context overflow, cascading errors, stale build.
- Tech debt — what didn't get done, stubs, follow-ups.
- Reusable patterns — what good thing emerged that's worth copying.
- Spec ↔ as-built reconciliation (marketplace#169) — if a wave
correctly omitted something the parent PRD/RFC mandated (because it
conflicted with a project red line), don't leave the mandate
unreconciled. Append an "As-Built Reconciliation" note to the artifact
body (superseded-by-build + reason) BEFORE §7 offers activation — an
artifact that still claims the forbidden surface while the shipped code
correctly doesn't is a silent lie in the graph.
Where to record
-
RFC / design doc (if exists) — section Implementation Log → Sprint Insights & Bottlenecks. See rfc.
-
TODO files — section Sprint Insights & Technical Debt:
| # | Task | RFC/Ref | Priority | Why it matters |
| - | ---- | ------- | -------- | -------------- |
| 1 | ... | ... | P1/P2 | ... |
-
KNOWN-ISSUES.md (if bugs were found):
### N. {Short Description}
**File:** `path/to/file:line`
**Description:** ...
**Status:** Open
**Found:** YYYY-MM-DD ({Sprint context})
-
Memory (if available): memory_retain ADR + tech debt + patterns + insights.
Final output
Emit the Sprint Complete report — format in references/OUTPUT-FORMATS.md §3. It includes deliverables, cumulative file list, insights & tech debt block (mandatory — see "What to collect" above), and next-step checklist (test / type-check / commit / audit).
Step 7: Sprint-close — bulk EVID activation prompt (MANDATORY — PRD-077 FR-012)
After Step 6 (Insights Extraction) and before signalling "sprint complete",
team-lead consolidates the EVIDs collected in §4b-bis across every wave and
hands control to the user for activation.
7a. Summary print
## Sprint evidence summary
Sprint "{sprint_name}" emitted **{N} EVID(s)** across **{M} artifact(s)**
in **{W} wave(s)**.
| EVID | Target artifact | Wave | Verdict | Status |
|---|---|---|---|---|
| EVID-AAA | PRD-XXX | 1 | supports | draft |
| EVID-BBB | RFC-YYY | 1 | supports | draft |
| EVID-CCC | PRD-XXX | 2 | supports | draft |
| EVID-DDD | SESSION-2026-… | 3 | supports | draft | # chat-driven, no link
If M == 0 (no artifacts touched, no SESSION-level EVID emitted either),
this is a methodology failure — see §7c below.
7b. Activation prompt
{N} EVID(s) created during this sprint. Activate them now?
Options:
1. ✅ Activate ALL ({N}) — bulk forgeplan_activate
2. 🔧 Review one-by-one (walk through, activate selectively)
3. ⏸️ Defer — keep as draft, activate manually later
4. ❌ Discard — drop EVIDs without activation (rare; explain why)
Wait for explicit user response. Do not auto-activate.
When user picks (1):
for evid_id in collected_evids:
mcp__forgeplan__forgeplan_activate(id=evid_id)
for evid_id in collected_evids:
forgeplan activate $evid_id
When user picks (2): print each EVID title + target + structured fields →
forgeplan_activate per yes.
When user picks (3) or (4): record the choice in the sprint final report so
later sessions know these EVIDs exist as drafts.
7c. Zero-EVID warning (methodology failure)
If the sprint closes with zero EVIDs emitted (touched_artifacts was empty
on every wave AND no SESSION-level EVID landed):
⚠️ Sprint closed without evidence.
This is a methodology gap: the artifact graph has no record of the {W} waves
of work just completed. `forgeplan health` will report a blind spot.
Suggested remediation — emit a session-level EVID retroactively:
forgeplan new evidence "{sprint_name}: {1-line summary}"
# → captures EVID-MMM, edit body to add Structured Fields:
# verdict: supports
# congruence_level: 3
# evidence_type: measurement
# optionally link to a Note:
forgeplan new note "Sprint outcome: {description}"
forgeplan link EVID-MMM NOTE-NNN --relation informs
Run these before merging the release branch.
7d. Non-interactive (/autorun) considerations
When /sprint is invoked from /autorun or another non-interactive
orchestrator that cannot prompt the user, behaviour:
- §7b prompt is skipped; collected EVIDs are left as draft
- the sprint final report lists all collected EVIDs and emits a single
line:
Bulk-activate when ready: forgeplan activate EVID-AAA EVID-BBB ...
- §7c zero-EVID warning still fires (it's a print, not a prompt)
- callers can pass
auto_activate=true (orchestrator convention) to skip
the prompt and execute option (1) directly — only enable this when the
orchestrator has already gated user approval upstream
Wave Patterns Quick Reference
| Type | Pattern | Waves | Agents |
|---|
| Full-stack feature | Stores/Types → Backend → Frontend → Tests | 4 | 8 |
| UI-only | Stores/Hooks → Components → Pages → Tests | 3-4 | 6-8 |
| Backend-only | Schema/Types → Services → Actions → Tests | 3 | 5-6 |
| Refactor | Foundation → Migration → Integration → Cleanup | 3-4 | 6-8 |
| Bug sprint | Research → Fixes → Verification → Docs | 2-3 | 4-6 |
Anti-Patterns (break = sprint fails)
| Anti-Pattern | Why | Do this instead |
|---|
⛔ Task() instead of TeamCreate | No coordination, no handoff | ALWAYS TeamCreate |
| ⛔ Team-lead writes code | Roles blur, control lost | Team-lead = coordination ONLY |
| ⛔ Extra work onto existing teammate | Overload, focus loss | NEW teammate per extra task |
| ⛔ Two agents on one file | Conflicts, lost code | Strict file ownership |
| Execute without user approval | Wrong plan, wasted tokens | ALWAYS show plan, wait for "go" |
| >5 agents per wave | Token explosion | Split across more waves |
| >400 LOC per agent | Quality drops | Split into 2 |
| Ignoring stale teams | TeamCreate fails | TeamDelete the old ones first |
| No task overlay between waves | Lost context | ALWAYS overlay |
| Ignoring token budget | Mid-sprint overflow | Check before every wave |
| Duplicating CLAUDE.md rules | Wasted tokens | "Follow CLAUDE.md" + 3-4 specifics |
| Skip insights extraction | Knowledge is lost | INSIGHTS — mandatory |
| ⛔ Skip wave-close evidence autopublish | Artifact graph stays blind, R_eff underweights work | §4b-bis is MANDATORY — one EVID per touched artifact per wave |
| ⛔ Auto-activate EVIDs without user prompt | Bypasses user review of generated evidence | §7b ALWAYS prompts (unless auto_activate=true from gated orchestrator) |
| Silent skip when MCP+CLI both unavailable | User never learns evidence wasn't captured | WARN explicitly with copy-paste fallback commands |
Related skills
team — foundation (Mode A/B, file ownership, recipes).research — research phase of full sprint.audit — post-sprint audit.rfc — Implementation Log + Insights land in the RFC.do — chains everything together.build — when a research report with IMPLEMENTATION-PLAN.md already exists.restore — at session start, before a sprint.
Forgeplan integration
/sprint is forgeplan-aware end-to-end when forgeplan is on $PATH or
mcp__forgeplan__* tools are exposed:
- Dispatch + claim loop — wired into Step 4 (4a-bis, 4b.g)
- Wave-close evidence autopublish — MANDATORY (§4b-bis), one EVID per
touched artifact per wave, structured fields filled by the skill
- Sprint-close batch activation — MANDATORY (§7), prompts user to
bulk-activate the collected draft EVIDs
No manual forgeplan new evidence is required at wave-close anymore; the
skill writes it for you. The commands below describe the shape; the skill
calls them.
Before /sprint <task> (still user's responsibility)
forgeplan health
forgeplan route "<task>"
forgeplan new prd "<title>"
forgeplan validate PRD-NNN
forgeplan reason PRD-NNN
During /sprint (skill calls these automatically)
forgeplan dispatch -n {agents-per-wave} --json
forgeplan claim {artifact-id} --agent {kebab-name}
forgeplan new evidence "{artifact-id}: wave N — ..."
forgeplan link EVID-MMM {artifact-id} --relation informs
After /sprint completes (skill prompts, user picks)
forgeplan activate EVID-AAA
forgeplan activate EVID-BBB
forgeplan score PRD-NNN
forgeplan activate PRD-NNN
If the user picks "defer" or "discard" at §7b, EVIDs stay draft and the
sprint report records the deferred list. If MCP+CLI are both unavailable,
the skill prints copy-paste commands rather than silently skipping.
Want this orchestrated for you?
Install forgeplan-workflow and run /forge-cycle "<task>" instead — it auto-routes, creates the PRD, delegates the build to skills like this one, creates evidence, activates, and prepares the commit. /sprint is the executor; /forge-cycle is the orchestrator.
/plugin install forgeplan-workflow@ForgePlan-marketplace
/reload-plugins
Decision Guide: full sprint vs lightweight wave
Do you already have context in chat?
├── YES → lightweight wave (skip research, generate plan)
│ ├── Discussed the task → wave
│ ├── Read RFC/TODO → wave
│ └── Did research → wave
│
└── NO → full sprint (research + plan)
├── New task → full sprint
└── Session start after a break → restore, then full sprint
