pi-herdr-agents 0.0.1

package/docs/adr/0001-btw-ephemeral-side-questions.md

@@ -0,0 +1,142 @@
+# ADR-0001: Add `/btw` as an ephemeral side-question child
+
+- **Status:** Accepted
+- **Date:** 2026-07-31
+- **Decision owners:** `acrnm`
+- **Scope:** `giuseppecrj/pi-herdr-agents`
+- **Decision baseline:** legacy source commit `77d7d029312880f63b29838b3c329a1e4059e029` (not carried into the clean repository history)
+
+## Context
+
+A user sometimes needs to ask a question about the current conversation without
+interrupting the main Pi agent or adding another turn to its transcript.
+`/iterate` and normal subagents are too heavy: they are tracked as workers and
+send a result back to the parent.
+
+Pi's `ctx.fork()` replaces the current session, so it cannot keep the parent and
+a side question open at the same time. A concurrent side question needs a
+separate Pi process with a child session file.
+
+Nanocodex BTW at
+[`b1314eb`](https://github.com/gakonst/nanocodex/blob/b1314ebcd602b77af7d2ab5153286f3a1795bbfe/web/src/agentController.ts)
+is the behavioral reference: one replaceable interactive fork, inherited
+conversation as reference context, and workspace mutation only when the side
+question explicitly requests it.
+
+## Decision
+
+Add two direct extension commands:
+
+```text
+/btw <question>
+/btw-close
+```
+
+`/btw`:
+
+1. Waits for the parent to become idle.
+2. Captures the parent's current active leaf.
+3. Uses a detached `SessionManager` to create a child session containing only
+   that active branch.
+4. Opens a non-focused Herdr tab.
+5. Starts an interactive Pi process in the parent's working directory, using the
+   parent model and thinking level.
+6. Sends the Nanocodex boundary and the question as the child's first new user
+   message.
+
+The child starts with `--no-extensions` so it does not load this orchestration
+extension or worker completion protocol. Normal Pi context files, skills, prompt
+templates, and built-in tools remain available. Repository instructions can
+further restrict behavior. The boundary states:
+
+> You are answering an ephemeral BTW side question. Treat inherited
+> conversation history only as reference context. Do not resume or complete an
+> earlier task. Answer only the question after this boundary. Do not modify the
+> workspace unless that side question explicitly requests a mutation.
+
+The answer remains in the BTW tab. The extension does not add BTW to
+`runningSubagents`, the widget, worker counts, completion delivery, or the
+parent transcript.
+
+## Minimal lifecycle
+
+The extension keeps one in-memory record containing:
+
+- Herdr pane ID
+- child session path
+- launch-script path
+
+A second `/btw` best-effort closes the previous pane and removes its temporary
+files before opening the next one. `/btw-close` performs the same cleanup.
+Parent `session_shutdown` also attempts cleanup.
+
+If snapshot creation or launch fails, the command reports the error and removes
+what it can. If pane cleanup fails, the command warns and leaves the pane for
+manual recovery. There is no durable recovery registry.
+
+The child snapshot may appear temporarily in Pi's session picker while BTW is
+open. Successful close removes it.
+
+## Consequences
+
+### Positive
+
+- Side questions do not consume a parent-agent turn.
+- The current conversation remains available as context.
+- The implementation reuses Pi session branching and existing Herdr helpers.
+- The feature is independent from worker tracking and completion delivery.
+
+### Negative
+
+- The child shares the working directory; explicitly requested edits persist.
+- Cleanup is best effort after crashes, reload failures, or manual pane changes.
+- A parent branch without a persisted assistant message cannot be opened as BTW.
+- The snapshot is visible to `/resume` until successful cleanup.
+
+## Deliberately deferred
+
+- Durable cleanup or crash recovery
+- Process observers and completion delivery
+- Worktree isolation
+- Multiple or named BTW panes
+- Tab-split ownership
+- Automatic merge, commit, push, or PR behavior
+- A generalized child-session manager
+
+Add these only if real usage demonstrates a need.
+
+## Verification
+
+Unit tests must prove:
+
+- active-branch snapshotting excludes abandoned siblings;
+- snapshotting does not modify the parent session;
+- an unpersisted child snapshot fails closed;
+- the launch command uses `--no-extensions`, the parent runtime, and the BTW
+  boundary without worker-control arguments;
+- empty `/btw` and idle `/btw-close` are harmless and do not steer the parent.
+
+Herdr integration must prove:
+
+- `/btw` opens a non-focused tab;
+- the child can answer from the latest completed parent context;
+- the parent session receives no BTW result or follow-up turn;
+- a second `/btw` replaces the first child;
+- `/btw-close` closes the child.
+
+Run:
+
+```sh
+npm test
+npm run lint
+git diff --check
+npm run test:integration
+npm pack --dry-run
+```
+
+## References
+
+- [Pi Herdr Agents](https://github.com/giuseppecrj/pi-herdr-agents)
+- [Nanocodex BTW controller](https://github.com/gakonst/nanocodex/blob/b1314ebcd602b77af7d2ab5153286f3a1795bbfe/web/src/agentController.ts)
+- [Pi extension API](https://github.com/earendil-works/pi/blob/main/packages/coding-agent/docs/extensions.md)
+- [Pi session format](https://github.com/earendil-works/pi/blob/main/packages/coding-agent/docs/session-format.md)

package/docs/adr/0002-agent-workflow-skill-runtime-taxonomy.md

@@ -0,0 +1,265 @@
+# ADR-0002: Adopt the agent, workflow, skill, and runtime taxonomy
+
+- **Status:** Accepted
+- **Date:** 2026-08-02
+- **Decision owners:** `acrnm`
+- **Scope:** `giuseppecrj/pi-herdr-agents`
+- **Historical tracking:** legacy issues #4 and #5 (not carried into the clean repository)
+
+## Decision
+
+Keep `pi-herdr-agents` small: it owns **agent execution**, not a second
+skill system or a general workflow engine.
+
+Use these terms consistently:
+
+- **Agent role** — A reusable child-agent responsibility with an operating
+  prompt and capability limits. Owned by this package or a project override;
+  sometimes user-facing through `/subagent`.
+- **Workflow** — A named recipe that composes roles, order, artifacts, and
+  runtime policy to achieve an outcome. Owned by the parent/orchestrator and
+  user-facing.
+- **Skill** — A Pi-native instruction set that teaches the current agent a
+  reusable procedure. It may invoke workflows or roles. Owned by Pi or the
+  skill author and user-facing.
+- **Runtime** — How a role executes: Pi or an external CLI, plus model and
+  thinking selection. Owned by invocation/configuration and not user-facing.
+- **Adapter** — An internal, runtime-specific role used by a workflow, such as
+  the Claude review pass. Owned by this package and not user-facing.
+
+An agent role is **not** a workflow merely because it can spawn other agents.
+A coordinator role is allowed when it owns an interactive or multi-stage child
+session. A workflow is the user-intent layer above it.
+
+## Why this is needed
+
+The package has a sound execution model but exposes mixed concepts on the same
+surface:
+
+- Agent definitions are discovered from package, global, and project folders,
+  with project definitions overriding global and bundled definitions.
+- The bundled list includes reusable roles (`scout`, `worker`, `reviewer`), a
+  multi-stage orchestration (`adversarial-reviewer`), and a Claude-specific
+  implementation (`claude-reviewer`).
+- The extension can request Pi skills, select model defaults, and start
+  sessions, but it has no first-class workflow definition or agent-definition
+  schema validation.
+
+That makes `/subagent list` technically accurate but semantically unclear: it
+is a list of executable definitions, not a list of comparable user tasks.
+
+## Standard
+
+### 1. Agent roles have one responsibility
+
+An agent definition answers: **what responsibility can this child take on,
+and under which constraints?** It must not promise a broad product outcome.
+
+A bundled role should have:
+
+- a stable, verb-first or noun-role name (`scout`, `reviewer`, `worker`);
+- a description stating its input and output, not its implementation;
+- the minimum tools and skills needed for that responsibility;
+- explicit `spawning`, `auto-exit`, and interaction behavior when it matters;
+- a report or handoff contract in its body; and
+- no user-specific model ID unless the role cannot function without that
+  runtime.
+
+Use an agent role directly when a caller has already chosen the task and needs
+one bounded child responsibility. Examples: inspect a module, review a diff,
+or implement a specified change.
+
+`planner` is a coordinator role: it may delegate factual gaps because that is
+part of planning. `reviewer`, `scout`, and `worker` are leaf roles and should
+keep `spawning: false`.
+
+### 2. Workflows own user intent and composition
+
+A workflow answers: **what result does the user want, and which roles run in
+what order to produce it?** It owns:
+
+- entry-point name and user-facing description;
+- required context and optional inputs;
+- role selection, sequence, and fan-out;
+- artifact locations and aggregation;
+- runtime-selection policy; and
+- completion and verification criteria.
+
+The package already exposes these workflow surfaces:
+
+- **Planning** — `/plan`, a user-facing command backed by `plan-skill.md` that
+  coordinates scout, interactive planner, workers, and reviewer.
+- **Iteration** — `/iterate`, a user-facing command that forks the current
+  session for focused work.
+- **Side question** — `/btw` and `/btw-close`, user-facing commands that manage
+  an ephemeral interactive side session.
+- **Adversarial review** — `adversarial-reviewer`, a user-facing orchestration
+  agent that is incorrectly presented as an agent rather than a workflow.
+- **Approved review runner** — `herdr_workflow`, a low-level control tool for
+  exact approved project-local JavaScript. It is an execution surface, not the
+  user-facing workflow recipe.
+- **Orchestrated review authoring** — bundled native `/skill:orchestrate`, which
+  teaches the parent to author and approve the first-flow review workflow.
+
+An orchestration agent remains a compatibility implementation detail—not a
+general pattern for new roles. Do not add more user-outcome orchestration
+prompts to `agents/` just because `subagent` is an available launcher.
+
+The next user-facing review surface should be a workflow named for the outcome,
+not a child implementation:
+
+- **Review** — one or more evidence-backed review passes against a supplied
+  base/ref and rubric.
+- **Adversarial review** — independent multi-runtime passes followed by
+  verification of proposed findings.
+
+Whether these become commands, Pi skills, or a parent prompt is a separate UX
+decision. The workflow contract should be settled before adding a new command.
+
+### 3. Skills remain outside this package's taxonomy
+
+A skill teaches the current Pi agent how to act. It is not an agent definition,
+even if it causes `subagent` calls. This package should:
+
+- accept the existing `skills` agent field as a dependency declaration;
+- document required skill names and prerequisites; and
+- not discover, install, version, or duplicate Pi skills.
+
+A package-owned `plan-skill.md` should be described as the instruction backing
+the package's `/plan` workflow, not as a second kind of subagent definition.
+
+### 4. Runtimes are selected by policy, not role identity
+
+A role describes the work; a runtime describes how one invocation performs it.
+For Pi-backed agents, the current model-resolution chain is the correct
+foundation: explicit invocation choice, agent default, per-agent configuration,
+global configuration, then the parent model. Claude CLI adapters instead use
+`cli` and `cli-model`; do not set a Pi `model` on an adapter expecting it to
+select the CLI model.
+
+Apply these rules:
+
+1. Prefer per-invocation `model` and `thinking` for a workflow's deliberate
+   diversity or cost/quality policy.
+2. Use ignored local `config.json` for a person's durable role preferences.
+3. Leave bundled Pi-role `model` unset unless a particular model is a functional
+   prerequisite.
+4. Treat `cli` and `cli-model` as a runtime adapter concern, not a review or
+   planning policy.
+5. State runtime prerequisites before launch and fail closed when a required
+   runtime is unavailable.
+
+This preserves the useful multi-model review behavior without baking a
+particular vendor choice into the generic `reviewer` role.
+
+### 5. Internal adapters are hidden from task discovery
+
+An adapter exists to satisfy a workflow's runtime contract, not to ask a user
+what they want to do. It should use `disable-model-invocation: true` and have a
+name that makes its internal nature clear.
+
+`claude-reviewer` is the current example. It uses
+`disable-model-invocation: true`: hidden adapters remain explicitly invokable
+by exact name, including from the existing adversarial-review orchestrator.
+
+### 6. Agent frontmatter is a constrained contract
+
+The package should document and validate the frontmatter it consumes. Do not
+silently add fields that are neither parsed nor documented. In particular,
+standardize on `skills` (plural); compatibility support for `skill` can remain
+until a documented deprecation date.
+
+The current parser is permissive: unsupported or unknown frontmatter may be
+ignored instead of rejected. The README therefore provides a complete template,
+a checklist, and a list/launch smoke-test procedure rather than promising schema
+validation that does not exist yet.
+
+For a future validation pass, require at least `name` and `description`, reject
+unknown package-owned fields, validate tool/skill list syntax, and report the
+source path in errors. The authoring template must cover the complete existing
+README frontmatter reference (`tools`, `deny-tools`, `thinking`, `system-prompt`,
+`spawning`, `auto-exit`, `interactive`, `session-mode`, `cwd`, `cli`,
+`cli-model`, and `disable-model-invocation`) rather than introduce a partial
+second schema. Keep extension fields separate from arbitrary prompt metadata so
+project authors can still add their own namespaced fields.
+
+## Current mapping
+
+- `scout` — Leaf agent role. Keep.
+- `worker` — Leaf agent role. Keep.
+- `reviewer` — Leaf agent role. Keep as the model-neutral review pass.
+- `planner` — Coordinator agent role. Keep; `/plan` remains the workflow that
+  invokes it.
+- `poteto` — Coordinator agent role. Keep only if its distinct autonomous
+  engineering responsibility remains intentional.
+- `visual-tester` — Leaf agent role with skill prerequisite. Keep its
+  `chrome-cdp` dependency declared through canonical `skills` metadata.
+- `claude-reviewer` — Hidden internal runtime adapter. Workflows can still
+  invoke it by exact name.
+- `adversarial-reviewer` — Workflow implementation pending a workflow surface.
+  Do not clone this pattern for new outcomes; migrate its user contract to an
+  adversarial-review workflow.
+- `plan-skill.md` — Planning workflow instruction. Document by workflow purpose,
+  not agent type.
+- `skills/orchestrate/SKILL.md` — Bundled native authoring skill for the first
+  review workflow; exposed with the package through Pi skills metadata.
+
+## Small migration plan
+
+Phases 1 and 2 are implemented in the current package. Phase 3 remains
+conditional on repeated registry needs; the low-level `herdr_workflow` runner is
+not a general workflow registry.
+
+### Phase 1 — establish the contract (documentation only)
+
+1. Adopt this vocabulary in the README and agent-authoring reference.
+2. Add a short agent-authoring template and a checklist for role authors.
+3. Audit bundled frontmatter for undocumented or unconsumed keys, including
+   `scout`'s `output` metadata and `visual-tester`'s compatibility `skill` key.
+4. Document every current workflow—planning, iteration, side questions, and
+   adversarial review—with its roles, artifacts, prerequisites, and runtime
+   policy in one place.
+5. Mark `claude-reviewer` with `disable-model-invocation: true`; this is an
+   existing visibility control, not new framework work.
+
+### Phase 2 — improve discovery without a new framework
+
+1. Make `subagents_list` show the source for every visible definition.
+2. Keep `/subagent` focused on directly runnable roles; describe workflows in
+   the command/skill documentation that owns them.
+
+### Phase 3 — add a workflow registry only when two surfaces need the same mechanics
+
+If `/plan` and adversarial review need the same registration, discovery, and
+artifact mechanics, add the smallest explicit workflow registry. It should
+compose existing roles and call `subagent`; it must not reimplement session,
+worktree, model-resolution, or completion lifecycle logic.
+
+Do not add a workflow engine, durable scheduler, or another configuration
+language before that repeated need exists.
+
+## Acceptance criteria
+
+- A user can distinguish a workflow from a directly runnable role before
+  launching either.
+- `subagents_list` does not advertise internal runtime adapters as peer tasks.
+- A role author can create and smoke-test a valid definition from one documented
+  template; schema-level frontmatter errors remain a deferred validation pass.
+- A workflow can select different authenticated runtimes per child without
+  changing generic role definitions.
+- Existing project/global override precedence and runtime-resolution behavior
+  remain unchanged.
+- No behavior is added to the package solely to duplicate Pi's skill system.
+
+## Evidence
+
+This decision is based on the current implementation:
+
+- `pi-extension/subagents/index.ts` parses and discovers agent definitions in
+  package → global → project load order (later definitions win), so effective
+  priority is project > global > package; it also launches child sessions.
+- `pi-extension/subagents/model-config.ts` provides per-agent and global model
+  defaults; launch-time arguments remain the appropriate workflow override.
+- `README.md` documents `/plan`, `/iterate`, `/btw`, agent discovery,
+  frontmatter, and runtime precedence.
+- `agents/` contains the mixed role/coordinator/adapter set mapped above.

package/docs/adr/0003-installable-role-packs.md

@@ -0,0 +1,135 @@
+# ADR-0003: Discover installable role packs through Pi's event bus
+
+- **Status:** Accepted
+- **Date:** 2026-08-02
+- **Decision owners:** `acrnm`
+- **Scope:** `giuseppecrj/pi-herdr-agents`
+
+## Decision
+
+Treat Pi packages as the plugin system for third-party subagent roles.
+A role pack ships Markdown role definitions plus a small Pi extension that
+responds synchronously to:
+
+```text
+pi-herdr-subagents:roles:discover:v1
+```
+
+That event name is a stable protocol identifier and is not renamed with the package.
+
+The discovery request exposes one operation:
+
+```ts
+register(path: string): void
+```
+
+`path` is an absolute Markdown file or a directory whose direct `.md` children
+are role definitions. `pi-herdr-agents` reads and validates those files when
+roles are listed or launched.
+
+Role packs use the existing agent-definition format. The filename stem is the
+canonical role name; `name` frontmatter is optional and, when present, must
+match the stem. `description` is required for contributed roles.
+
+## Why
+
+Pi already owns package installation, updates, project trust, enablement, and
+removal. Reusing `pi install` avoids a second package manager and keeps package
+security expectations explicit.
+
+Pi currently discovers only extensions, skills, prompts, and themes. It does
+not expose custom package resources or installed package roots to extensions.
+The inter-extension event bus is the smallest public seam that lets separately
+installed packages contribute roles without scanning Pi's private npm or Git
+directories.
+
+Pull-based discovery is load-order independent: every extension factory has
+registered its listeners before a user lists or launches a role. Synchronous
+registration matches Pi's non-awaiting event bus and keeps role lookup local and
+deterministic. Each contributor must retain the unsubscribe function returned by
+`pi.events.on()` and invoke it from `session_shutdown`; Pi reuses its event bus
+across reloads, so listener cleanup prevents removed or updated packs from
+leaving stale roles.
+
+## Catalog and precedence
+
+Listing and exact-name launch use one resolved catalog. Collection order is:
+
+1. bundled package roles;
+2. registered role-pack definitions;
+3. global definitions;
+4. project definitions.
+
+Effective precedence remains:
+
+```text
+project > global > package
+```
+
+Role-pack definitions remain in the `package` source layer and add package name,
+version, and path provenance. Global and project definitions can intentionally
+override them.
+
+Within the package layer:
+
+- bundled roles are protected fallbacks;
+- a role pack colliding with a bundled name is rejected;
+- a name contributed by multiple role packs is disabled;
+- collisions never resolve through incidental extension load order.
+
+Invalid registrations do not suppress unrelated roles. Listing surfaces report
+concise diagnostics, and an exact-name launch reports the matching diagnostic
+instead of treating an invalid contribution as a bare agent.
+
+## Reload and security
+
+Role files are read on each list or launch, so editing Markdown does not require
+`/reload`. Installing, removing, updating, or changing a role-pack extension
+uses Pi's normal reload flow. Contributor `session_shutdown` cleanup removes the
+old event listener before replacement extensions register. Already-running
+children retain their resolved role and lifecycle.
+
+This is not a sandbox. Pi packages and extensions already execute with the
+user's permissions. The host accepts only explicitly registered paths, performs
+no network access or package installation, and does not evaluate role Markdown
+as code.
+
+## Rejected alternatives
+
+### Scan Pi package directories
+
+Rejected because npm/Git install paths are private Pi implementation details and
+would bypass package filtering, trust, and provenance.
+
+### Add a second plugin installer or settings inventory
+
+Rejected because it duplicates Pi's package state and creates two update/removal
+flows.
+
+### Share an SDK module between packages
+
+Rejected because Pi packages have separate module roots. A mandatory helper
+would create fragile runtime coupling or bundle duplicate host code.
+
+### General contribution manifests for workflows and adapters
+
+Deferred. ADR-0002 keeps skills in Pi and prohibits a speculative workflow
+engine. The v1 seam contributes roles only. Future concrete contribution types
+should receive their own explicitly versioned contract when repeated need
+exists.
+
+### Pure Markdown packages
+
+This is the preferred long-term authoring experience but requires a Pi-core
+custom-resource or contribution hook. If Pi gains one, role packs can remove
+the bridge extension without changing their Markdown definitions or user-facing
+commands.
+
+## Consequences
+
+- Installing a role pack remains `pi install <source>`.
+- Authors write one tiny event listener until Pi supports custom resources.
+- The public event name is versioned; breaking changes require a new channel.
+- Package identity is derived from the nearest `package.json`, avoiding repeated
+  manifest metadata in the registration call.
+- The existing global and project authoring paths remain compatible.

package/docs/adr/0004-require-active-user-approval-for-workflow-execution.md

@@ -0,0 +1,17 @@
+# ADR-0004: Require active user approval for workflow-script execution
+
+- **Status:** Accepted
+- **Date:** 2026-08-03
+- **Scope:** `giuseppecrj/pi-herdr-agents`
+
+## Context
+
+An approved workflow script launches child agents with bounded capabilities. A persisted `approved` field could become stale, be copied to changed bytes or another repository, or be executed by a later parent session without the user seeing the exact strategy.
+
+## Decision
+
+For v1, execution requires the user to reply `APPROVE <8-character SHA-256 prefix>` after preparation in the same active parent session for one exact workflow-script revision. Preparation binds the session and branch position, complete script hash, canonical repository root and Git common directory, exact committed base, materialized source evidence, resolved role behavior, runtimes, and effective tools. Start revalidates that complete policy before consuming approval once. The run journal is created only at start, and its first event records the full approval binding and approving user-entry ID. Persisted and cross-session approval are deferred.
+
+## Consequences
+
+The runner must fail closed when approval predates preparation, comes from another session, or any bound byte, repository identity, source evidence, or policy changed. Read-only discovery remains a separate pre-approval activity. Preparation creates no run effect, and no workflow child can start before approval is recorded as the journal's first event.

package/docs/adr/0005-parent-owns-workflow-script-authority.md

@@ -0,0 +1,17 @@
+# ADR-0005: Keep workflow-script authority with the parent
+
+- **Status:** Accepted
+- **Date:** 2026-08-03
+- **Scope:** `giuseppecrj/pi-herdr-agents`
+
+## Context
+
+Children can discover facts and recommend work, but allowing them to author or revise the workflow script after planning makes it unclear which strategy the user approved and permits unbounded dynamic fan-out.
+
+## Decision
+
+For v1, only the parent may author or revise `workflow.js`. Children return findings, evidence, help requests, or non-executable draft artifacts; they cannot change the strategy or its policy envelope.
+
+## Consequences
+
+The runner accepts only a parent-authored workflow script. Any material child recommendation must be evaluated by the parent and, when it changes the approved strategy or policy envelope, requires a revised script and renewed user approval.

package/docs/adr/0006-limit-v1-execution-effects-to-isolated-worktrees.md

@@ -0,0 +1,18 @@
+# ADR-0006: Limit the first workflow to read-only effects
+
+- **Status:** Accepted
+- **Date:** 2026-08-03
+- **Scope:** `giuseppecrj/pi-herdr-agents`
+- **Filename note:** The historical filename still says `isolated-worktrees`; the decision is the read-only first-flow effect boundary.
+
+## Context
+
+The first production workflow exists to prove approved JavaScript orchestration, fresh review, evidence, and lifecycle behavior. Writer worktrees, commits, candidate handoffs, and external-system actions add separate ownership and recovery questions that are not needed to validate that runtime.
+
+## Decision
+
+The first workflow permits only fresh read-only Pi nodes against one runner-owned detached checkout pinned to the approved committed source. It cannot write files, create commits, mutate the parent checkout, integrate work, or mutate external systems.
+
+## Consequences
+
+The bundled skill must not author writer nodes for this flow. Ticket mutation, deployment, messaging, publishing, PR actions, merges, commits, and cleanup remain explicit parent or upstream operations. A later writer workflow requires separate prototype evidence, acceptance criteria, and approval before this boundary changes.

package/docs/adr/0007-require-fresh-review-for-workflow-scripts.md

@@ -0,0 +1,19 @@
+# ADR-0007: Require fresh review in skill-authored review workflows
+
+- **Status:** Accepted
+- **Date:** 2026-08-03
+- **Scope:** `giuseppecrj/pi-herdr-agents`
+
+## Context
+
+The first workflow reviews an exact source or candidate. The parent author and any prior workers can share assumptions, so its useful result needs independent examination without inherited implementation context.
+
+## Decision
+
+The bundled `orchestrate` skill authors every v1 review workflow with independent fresh read-only review nodes followed by one fresh review synthesizer. Each reviewer and the synthesizer receive the exact source or candidate evidence rather than inherited implementation context. The synthesizer receives every explicit reviewer success or failure and returns the task-specific result.
+
+The runtime remains task-agnostic: it enforces the approved capability envelope and operational evidence but does not infer prompts, impose a fixed review receipt, or prove JavaScript data flow. Exact-script human approval is the task-semantics boundary.
+
+## Consequences
+
+The skill must not present a script for approval when it omits independent review or synthesis. Worker self-review, inherited-context review, filtered failures, and parent-side synthesis do not satisfy the policy. The trade-off is that the runner does not independently certify review completeness; adding such certification would require the fixed task state machine rejected for v1.