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
This commit is contained in:
Bryan Ramos 2026-04-02 07:05:43 -04:00
parent 41c31a2a85
commit 7699f67959
2 changed files with 10 additions and 4 deletions

View file

@ -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

View file

@ -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.