From 3bab757f29429f464fc89bf01400c1ce3651ed45 Mon Sep 17 00:00:00 2001 From: Defame1297 Date: Sun, 5 Jul 2026 12:30:23 +0000 Subject: [PATCH] docs(agents): document fork task-scope and TaskList access constraints Adds a Subagent orchestration section to AGENTS.md so orchestrating agents know upfront: forks must stop once their assigned task is done rather than autonomously draining a shared TaskList, governance-gated actions must not be exposed to forks without a fresh confirmation round, and TaskGet/TaskUpdate/TaskList are fork-only so the coordinator must own task-list bookkeeping for fresh subagents itself. Refs #68, #70 Co-Authored-By: Claude Sonnet 5 Claude-Session: https://claude.ai/code/session_01FNJWdVvdgvZCHi1hZGqgVQ --- AGENTS.md | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/AGENTS.md b/AGENTS.md index ff4b7a3..0cbb650 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -24,3 +24,9 @@ Read these on demand: ## Working context This repo is built by a junior developer as a homelab tool intended to scale to professional environments. Challenge ideas and reference industry standards rather than validate assumptions. Explain the why behind decisions — assume the user is learning, not just executing. Flag significant actions before taking them. + +## Subagent orchestration + +- **Forks stop when their assigned task is done.** A `fork` inherits the coordinator's full context, including visibility into any shared TaskList. That visibility is not license to keep going: once a fork's assigned task is reported complete, it must stop rather than autonomously picking up further items from the list. Forks that keep pulling work race against the coordinator's own orchestration and can duplicate or conflict with tasks the coordinator has separately delegated. +- **Don't hand a fork a TaskList that includes governance-gated actions** (push, publish, merge) unless you are prepared for it to act on those items without a fresh confirmation round. A fork acting on its own initiative is not party to any pending human confirmation the coordinator is mid-flow on, so it can bypass a gate that was meant to hold. +- **`TaskGet`/`TaskUpdate`/`TaskList` only work for forks.** Fresh (non-fork) subagents cannot discover or call these tools. When delegating to a fresh subagent, the coordinator owns all task-list bookkeeping itself — claim and complete the entry on the agent's behalf — rather than instructing the fresh agent to self-claim or self-complete.