From 7699f67959b6a74a48982b9ef2e6e165aac8072d Mon Sep 17 00:00:00 2001 From: Bryan Ramos Date: Thu, 2 Apr 2026 07:05:43 -0400 Subject: [PATCH] fix: correct stale agent names, false cost claims, and document permissionMode override - Replace "Karen/Verification" with "reviewer/auditor" in worker-protocol - Reframe parallel dispatch rationale from false "~10% token cost" (only applies to fork agents with identical prefixes) to accurate wall-clock latency savings - Add Permission model section documenting that permissionMode is overridden when parent runs in acceptEdits mode; disallowedTools is the actual safety boundary --- skills/orchestrate/SKILL.md | 10 ++++++++-- skills/worker-protocol/SKILL.md | 4 ++-- 2 files changed, 10 insertions(+), 4 deletions(-) diff --git a/skills/orchestrate/SKILL.md b/skills/orchestrate/SKILL.md index 5770b2a..6a95dc7 100644 --- a/skills/orchestrate/SKILL.md +++ b/skills/orchestrate/SKILL.md @@ -83,7 +83,7 @@ If the plan flags unresolved blockers or unverified assumptions, escalate to the For each wave in the plan: -1. **Spawn ALL workers in the wave in a single response.** This is not optional — it is a cost and performance requirement. Parallel workers share the same cached context prefix at ~10% token cost. Serializing independent workers wastes both money and time. +1. **Spawn ALL workers in the wave in a single response.** This is not optional — it is a performance requirement. Parallel agents run concurrently, reducing wall-clock time proportional to the number of agents. Serializing independent workers wastes time linearly. 2. Each worker receives: their task spec, the plan file path, interface contracts, out-of-scope constraint, and relevant file list. @@ -184,13 +184,19 @@ When multiple risk tags are present, take the union. Spawn all required reviewer **documenter** - Spawn after implementation wave is complete. Background. One instance per completed scope area. +### Permission model + +Agent `permissionMode` in frontmatter is overridden when the parent (you, the orchestrator) runs in `acceptEdits` or `bypassPermissions` mode — the child inherits the parent's mode. This means `permissionMode: plan` on read-only agents like architect, researcher, and reviewer is **not enforced at runtime**. + +The actual write protection for read-only agents comes from `disallowedTools: Write, Edit` — this is enforced regardless of permission mode. Do not rely on `permissionMode` as a safety boundary; rely on tool restrictions. + ### Parallelism mandate **Same-wave workers must be spawned in a single response.** **Reviewer and auditor must be spawned in a single response.** **All researchers must be spawned in a single response.** -Spawning agents sequentially when they could run in parallel is a protocol violation, not a style choice. Parallel agents share a cached context prefix — each additional parallel agent costs ~10% of what the first agent paid for that shared context. +Spawning agents sequentially when they could run in parallel is a protocol violation, not a style choice. Parallel dispatch reduces wall-clock latency proportionally — N agents in parallel complete in the time of the slowest, not the sum of all. ### Git flow diff --git a/skills/worker-protocol/SKILL.md b/skills/worker-protocol/SKILL.md index ddeb137..c188923 100644 --- a/skills/worker-protocol/SKILL.md +++ b/skills/worker-protocol/SKILL.md @@ -54,6 +54,6 @@ If blocked (tool failure, missing file, build error): try to work around it and ## Receiving reviewer feedback -Your orchestrator may resume you with findings from Karen (analytical review) or Verification (runtime/test review), or both. +Your orchestrator may resume you with findings from the reviewer (code quality + AC verification) or the auditor (security + runtime validation), or both. -You already have the task context and your previous work. Address the issues specified. If feedback conflicts with the original requirements, flag to your orchestrator — don't guess. Resubmit complete output in standard format. In Self-Assessment, note which issues you addressed and reference the reviewer (Karen / Verification) for each. +You already have the task context and your previous work. Address the issues specified. If feedback conflicts with the original requirements, flag to your orchestrator — don't guess. Resubmit complete output in standard format. In Self-Assessment, note which issues you addressed and reference the reviewer or auditor for each.