Codestin Search App

someiyoshino-lab · 2026-07-07T15:10:00Z

Summary

rules/common/agents.md tells agents to "ALWAYS use parallel Task execution for independent operations", but defines no completion contract for delegation. This PR adds a Delegation Completion Contract section right after the parallel-execution rule.

The failure mode this prevents

Observed in practice with parallel research agents:

Parent spawns 4 research agents (children), each with a well-scoped task
3 of 4 children — following the parallel-execution rule — spawn their own children (grandchildren) instead of doing the work
The children then end their turn with "waiting for background agents to complete" as their final answer
All grandchildren complete their research successfully, but their results are orphaned: a parent whose turn has ended cannot receive completion notifications
Result: zombie "running" tasks in the UI, lost work, and children that returned no deliverable

The root cause is not delegation itself (the grandchildren's output quality was fine) and not task decomposition (the same 4-way split succeeded when re-run with a completion constraint). It is the missing lifecycle contract: a subagent's final message IS its return value, so "waiting" is an abandoned return value.

What this adds

Three rules that apply at every delegation depth:

Your final message IS the deliverable. Never end your turn with "waiting for background agents" — a spawned task is not a completed task.
If you delegate, you own collection. Wait for results, integrate them, then return. Fire-and-forget delegation is forbidden.
Decompose only when the work cannot fit in one context. Depth is an outcome, not a plan.

With this contract in place, the same parallel research fan-out completed with zero orphaned tasks.

Changes

rules/common/agents.md: +10 lines (new "Delegation Completion Contract" section between "Parallel Task Execution" and "Multi-Perspective Analysis")

…n rules The 'Parallel Task Execution' rule encourages agents to spawn subagents, but defines no completion contract. Observed failure mode: subagents followed the rule, spawned their own children, and returned 'waiting for background agents' as their final answer. All children completed successfully, but their results were orphaned because a parent whose turn has ended cannot receive completion notifications - leaving zombie 'running' tasks and lost work. Adds three rules that apply at every delegation depth: 1. Your final message IS the deliverable (never end with 'waiting') 2. If you delegate, you own collection (no fire-and-forget) 3. Decompose only when work cannot fit in one context

coderabbitai · 2026-07-07T15:10:57Z

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Pro

Run ID: 59dbecec-beb1-4adc-b765-95d2a68b260e

📥 Commits

Reviewing files that changed from the base of the PR and between 4130457 and 50e046c.

📒 Files selected for processing (1)

rules/common/agents.md

📜 Recent review details

⏰ Context from checks skipped due to timeout. (1)

GitHub Check: Greptile Review

🧰 Additional context used

📓 Path-based instructions (1)

{skills,commands,agents,rules}/**

⚙️ CodeRabbit configuration file

{skills,commands,agents,rules}/**: Focus on prompt-injection resilience, tool-permission scope, destructive action guards, and secret exfiltration risks.

Files:

rules/common/agents.md

🔇 Additional comments (1)

rules/common/agents.md (1)

43-52: LGTM!

📝 Walkthrough

Summary by CodeRabbit

Documentation
- Clarified agent coordination guidance to ensure work is completed and collected before a response is returned.
- Added stronger rules to prevent unfinished parallel tasks from being left out of the final result.
- Included advice to avoid splitting already-scoped work across multiple layers of delegation.

Walkthrough

Adds a "Delegation Completion Contract" section to rules/common/agents.md, specifying that delegating agents must own result collection, prohibiting fire-and-forget returns while child tasks run, and adding a rule against re-delegating single-agent-scoped work, with supporting rationale.

Changes

Delegation Completion Contract

Layer / File(s)	Summary
New completion contract section `rules/common/agents.md`	Adds guidance requiring agents to collect and integrate delegated results before returning, forbids fire-and-forget delegation, discourages unnecessary re-delegation, and includes rationale citing an orphaned-results failure mode.

Estimated code review effort: 1 (Trivial) | ~3 minutes

Related PRs: None identified.

Suggested labels: documentation

Suggested reviewers: None identified.

🐰 A hop, a rule, a tidy line —
"Finish your task before you dine!"
No orphaned children left to roam,
Collect the results and bring them home.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title accurately names the new Delegation Completion Contract added to the agent orchestration rules.
Description check	✅ Passed	The description directly matches the documented change and explains the added delegation contract.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

🧪 Generate unit tests (beta)

Create PR with unit tests

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

_{Comment @coderabbitai help to get the list of available commands.}

greptile-apps · 2026-07-07T15:12:02Z

Greptile Summary

This PR adds a Delegation Completion Contract section to rules/common/agents.md, placing it between the existing "Parallel Task Execution" and "Multi-Perspective Analysis" sections. It introduces three rules ensuring agents wait for and return delegated results rather than ending their turn with a "waiting" message that orphans child results.

Adds rule that an agent's final message is its deliverable — ending a turn while child tasks are still running abandons their output
Adds rule that agents which delegate must collect, integrate, and return all results before completing
Adds rule limiting re-delegation to cases where work genuinely cannot fit in a single context, with a rationale blockquote describing the observed zombie-task failure mode

Confidence Score: 4/5

Safe to merge — pure documentation change with no executable code altered

The three rules are logically sound and well-placed between the parallel-execution and multi-perspective sections. The only gap is that the root AGENTS.md carries its own parallel-execution advice but no corresponding completion constraint, so agents bootstrapped solely from that file would still be missing the guardrail this PR is meant to install.

AGENTS.md (root) — carries a parallel-execution directive without the new completion contract

Important Files Changed

Filename	Overview
rules/common/agents.md	Adds a 10-line "Delegation Completion Contract" section with three rules and a rationale blockquote; the root AGENTS.md still only advises parallel execution without the matching completion guardrail, so agents reading only the root file miss the new constraint

Sequence Diagram

%%{init: {'theme': 'neutral'}}%%
sequenceDiagram
    participant P as Parent Agent
    participant C1 as Child Agent 1
    participant C2 as Child Agent 2
    participant G as Grandchild Agents

    Note over P,G: ❌ BEFORE — fire-and-forget (zombie tasks)
    P->>C1: spawn (parallel)
    P->>C2: spawn (parallel)
    C1->>G: re-spawn children
    C1-->>P: "waiting for background agents" ← turn ends
    G-->>C1: results (orphaned — C1 turn already ended)

    Note over P,G: ✅ AFTER — Delegation Completion Contract
    P->>C1: spawn (parallel)
    P->>C2: spawn (parallel)
    C1->>C1: do work directly (fits in one context)
    C1-->>P: integrated deliverable
    C2-->>P: integrated deliverable
    P-->>P: integrate all results → final message IS the deliverable

%%{init: {'theme': 'base', 'themeVariables': {"darkMode": true, "background": "#0d1117", "primaryColor": "#21262d", "primaryTextColor": "#e6edf3", "primaryBorderColor": "#8b949e", "lineColor": "#8b949e", "textColor": "#e6edf3", "edgeLabelBackground": "#161b22", "actorBkg": "#21262d", "actorBorder": "#8b949e", "actorTextColor": "#e6edf3", "actorLineColor": "#8b949e", "signalColor": "#8b949e", "signalTextColor": "#e6edf3", "noteBkgColor": "#373320", "noteBorderColor": "#d4a72c", "noteTextColor": "#f0e6c0", "labelBoxBkgColor": "#21262d", "labelBoxBorderColor": "#8b949e", "labelTextColor": "#e6edf3", "loopTextColor": "#e6edf3", "activationBkgColor": "#30363d", "activationBorderColor": "#8b949e"}}}%%
sequenceDiagram
    participant P as Parent Agent
    participant C1 as Child Agent 1
    participant C2 as Child Agent 2
    participant G as Grandchild Agents

    Note over P,G: ❌ BEFORE — fire-and-forget (zombie tasks)
    P->>C1: spawn (parallel)
    P->>C2: spawn (parallel)
    C1->>G: re-spawn children
    C1-->>P: "waiting for background agents" ← turn ends
    G-->>C1: results (orphaned — C1 turn already ended)

    Note over P,G: ✅ AFTER — Delegation Completion Contract
    P->>C1: spawn (parallel)
    P->>C2: spawn (parallel)
    C1->>C1: do work directly (fits in one context)
    C1-->>P: integrated deliverable
    C2-->>P: integrated deliverable
    P-->>P: integrate all results → final message IS the deliverable

_{Reviews (1): Last reviewed commit: "docs(rules): add Delegation Completion C..." | Re-trigger Greptile}

greptile-apps · 2026-07-07T15:12:06Z

+1. **Your final message IS the deliverable.** Never end your turn with "waiting for background agents" — a spawned task is not a completed task. Ending your turn while children are running orphans their results (completed children cannot notify a parent whose turn has ended).
+2. **If you delegate, you own collection.** Wait for results, integrate them, then return. Fire-and-forget delegation is forbidden.
+3. **Decompose only when the work cannot fit in one context.** Do not re-delegate a task already sized for a single agent — depth is an outcome, not a plan.
+
+> Rationale: observed failure mode — research agents followed "Parallel Task Execution" above, spawned children, and returned "waiting" as their final answer. All children completed successfully but their results were orphaned. The parallel rule without a completion contract produces zombie tasks.


Root AGENTS.md still missing the completion guardrail

The root-level AGENTS.md contains its own parallel-execution directive ("Use parallel execution for independent operations — launch multiple agents simultaneously.") but has no corresponding completion contract. Agents that are initialized only from AGENTS.md — or that cache it independently — will get the parallel mandate without the collection requirement, recreating exactly the failure mode this PR fixes. A brief note in AGENTS.md (e.g., "agents that delegate must collect and return all results before completing their turn") would close that gap.

Note: If this suggestion doesn't match your team's coding style, reply to this and let me know. I'll remember it for next time!

daltino

DECISION: APPROVE

This PR adds a clear and well-articulated "Delegation Completion Contract" rule to the agent orchestration documentation, emphasizing proper message handling and result integration for delegated tasks. The guidance aligns well with the repo's goal of improving agent workflows and is concise. No issues found; the additions enhance clarity.

someiyoshino-lab requested a review from affaan-m as a code owner July 7, 2026 15:10

greptile-apps Bot reviewed Jul 7, 2026

View reviewed changes

daltino reviewed Jul 7, 2026

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

docs(rules): add Delegation Completion Contract to agent orchestration rules#2471

docs(rules): add Delegation Completion Contract to agent orchestration rules#2471
someiyoshino-lab wants to merge 1 commit into
affaan-m:mainfrom
someiyoshino-lab:docs/delegation-completion-contract

someiyoshino-lab commented Jul 7, 2026

Uh oh!

coderabbitai Bot commented Jul 7, 2026 •

edited

Loading

Summary by CodeRabbit

Walkthrough

Changes

Uh oh!

greptile-apps Bot commented Jul 7, 2026

Greptile Summary

Confidence Score: 4/5

Sequence Diagram

Uh oh!

greptile-apps Bot Jul 7, 2026

Uh oh!

daltino left a comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Uh oh!

Conversation

someiyoshino-lab commented Jul 7, 2026

Summary

The failure mode this prevents

What this adds

Changes

Uh oh!

coderabbitai Bot commented Jul 7, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary by CodeRabbit

Walkthrough

Changes

Uh oh!

greptile-apps Bot commented Jul 7, 2026

Greptile Summary

Confidence Score: 4/5

Important Files Changed

Sequence Diagram

Uh oh!

greptile-apps Bot Jul 7, 2026

Choose a reason for hiding this comment

Uh oh!

daltino left a comment

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

coderabbitai Bot commented Jul 7, 2026 •

edited

Loading