pi-herdr-agents 1.3.0 → 1.4.0

package/AGENTS.md

@@ -55,7 +55,7 @@ Read [`docs/worktree-subagents.md`](docs/worktree-subagents.md) before changing
 ## Orchestration guidance
 
 - Use ordinary panes for read-only scouts and reviewers.
-- Use unique worktree branches for independent parallel writing tasks.
+- A single or sequential writer can work in the parent checkout; reserve unique worktree branches for independent parallel writing tasks.
 - Keep overlapping or dependent writing tasks sequential unless the dependency is committed and used as the next exact base.
 - Tell worktree workers whether to commit. A good default is: edit, test, commit, report the SHA, and do not push/merge/remove.
 - The parent owns review, integration, publication, and cleanup.

package/CHANGELOG.md

@@ -7,11 +7,29 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 Generated by [`auto-changelog`](https://github.com/CookPete/auto-changelog).
 
-## [v1.3.0](https://github.com/giuseppecrj/pi-herdr-agents/compare/v1.2.3...v1.3.0)
+## [v1.4.0](https://github.com/giuseppecrj/pi-herdr-agents/compare/v1.3.1...v1.4.0)
+
+### Commits
+
+- test: disable commit signing in git fixtures [`c87e20d`](https://github.com/giuseppecrj/pi-herdr-agents/commit/c87e20dd3d4d7ff058b555759904de36bf881875)
+- feat: state the coordinator contract in always-visible guidelines [`08b1dc6`](https://github.com/giuseppecrj/pi-herdr-agents/commit/08b1dc6ffdfbb4ef03289b0871cc4fbc48883032)
+- fix: stop implying every writing subagent needs a worktree [`114c239`](https://github.com/giuseppecrj/pi-herdr-agents/commit/114c239f71666a8a9c9a2c8705197b70c5f4e7a2)
+- fix: point reviewers of worktree results at the retained worktree path [`4d84718`](https://github.com/giuseppecrj/pi-herdr-agents/commit/4d84718ada823eba830195e865c327155f37a8dd)
+
+## [v1.3.1](https://github.com/giuseppecrj/pi-herdr-agents/compare/v1.3.0...v1.3.1) - 2026-08-29
+
+### Commits
+
+- fix: recommend tier-first model selection over parent inheritance [`c86e002`](https://github.com/giuseppecrj/pi-herdr-agents/commit/c86e0027d857f3b31c8a9925789baf56203e5bba)
+- docs: align remaining spawn examples with tier-first policy [`776f656`](https://github.com/giuseppecrj/pi-herdr-agents/commit/776f656419f8afe8a998705803cb2d1889218b97)
+- chore: release v1.3.1 [`79fce1f`](https://github.com/giuseppecrj/pi-herdr-agents/commit/79fce1fd88717c9d7b15701939bb649bbdefb05b)
+
+## [v1.3.0](https://github.com/giuseppecrj/pi-herdr-agents/compare/v1.2.3...v1.3.0) - 2026-08-18
 
 ### Commits
 
 - feat: identify workflow review nodes [`6919ab1`](https://github.com/giuseppecrj/pi-herdr-agents/commit/6919ab1c655f0e6c50944011889df14800cf2021)
+- chore: release v1.3.0 [`36c8187`](https://github.com/giuseppecrj/pi-herdr-agents/commit/36c8187098e24f3d65dc309e19ccd44e6432f8ce)
 
 ## [v1.2.3](https://github.com/giuseppecrj/pi-herdr-agents/compare/v1.2.2...v1.2.3) - 2026-08-18
 

package/README.md

@@ -71,12 +71,12 @@ For an isolated writing task:
 Pi can also call the tool directly:
 
 ```typescript
-subagent({ name: "Auth scout", agent: "scout", task: "Map the authentication flow" });
-subagent({ name: "DB scout", agent: "scout", task: "Map the session schema" });
+subagent({ name: "Auth scout", agent: "scout", model: "<provider>/<fast-tier-id>", thinking: "low", task: "Map the authentication flow" });
+subagent({ name: "DB scout", agent: "scout", model: "<provider>/<fast-tier-id>", thinking: "low", task: "Map the session schema" });
 // Both return immediately; each result comes back independently.
 ```
 
-Use ordinary panes for read-only agents. Give each independent writing agent a unique managed worktree; see [Worktree subagents](docs/worktree-subagents.md).
+Use ordinary panes for read-only agents. A single or sequential writer can work in the parent checkout; give each parallel independent writing agent a unique managed worktree. See [Worktree subagents](docs/worktree-subagents.md).
 
 ## How it works
 
@@ -197,9 +197,15 @@ This package does not install optional prerequisites.
 
 Bundled agents use model defaults from `config.json` when configured; otherwise
 they inherit the parent model. Thinking defaults still come from agent
-frontmatter or the parent level. The orchestrating agent can override either
-field for a specific task using an exact authenticated model ID and a supported
-Pi thinking level. Prefer changing thinking before changing models.
+frontmatter or the parent level. This resolution chain remains available as a
+fallback, but orchestrators should explicitly set each child's exact
+authenticated `provider/model-id` and supported thinking level. Select the
+model tier first: fast for bounded mechanical work and recon, mid for ordinary
+implementation or review, and frontier for architecture, security, hard
+diagnosis, or adversarial review. Then select thinking within that model's
+supported range. Independent reviewers must use a different provider/family
+than the model that produced the work; a stronger model in the same family is a
+quality escalation, not independent review.
 
 Discovery loads definitions in **package → global → project** order, so effective
 priority remains **project** (`.pi/agents/`) > **global**
@@ -340,22 +346,24 @@ status and model configuration are loaded when the extension starts.
 ## Spawning Subagents
 
 ```typescript
-// Named agent with defaults from agent definition or config.json
-subagent({ name: "Scout", agent: "scout", task: "Analyze the codebase..." });
+// Explicit fast-tier runtime for bounded reconnaissance
+subagent({ name: "Scout", agent: "scout", model: "<provider>/<fast-tier-id>", thinking: "low", task: "Analyze the codebase..." });
 
 // Force a full-context fork for this spawn
-subagent({ name: "Iterate", fork: true, task: "Fix the bug where..." });
+subagent({ name: "Iterate", fork: true, model: "<provider>/<mid-tier-id>", thinking: "medium", task: "Fix the bug where..." });
 
-// Agent defaults can choose a different session-mode via frontmatter
-subagent({ name: "Planner", agent: "planner", task: "Work through the design with me" });
+// Explicit frontier-tier runtime for architecture work
+subagent({ name: "Planner", agent: "planner", model: "<provider>/<frontier-tier-id>", thinking: "high", task: "Work through the design with me" });
 
-// Custom working directory
-subagent({ name: "Designer", agent: "game-designer", cwd: "agents/game-designer", task: "..." });
+// Explicit mid-tier runtime with a custom working directory
+subagent({ name: "Designer", agent: "game-designer", model: "<provider>/<mid-tier-id>", thinking: "medium", cwd: "agents/game-designer", task: "..." });
 
 // Isolated ticket branch in a Herdr-managed Git worktree
 subagent({
   name: "Ticket 123",
   agent: "worker",
+  model: "<provider>/<mid-tier-id>",
+  thinking: "medium",
   worktree: { branch: "ticket/123", base: "main" },
   task: "Implement ticket 123, test it, and commit the result",
 });
@@ -371,7 +379,7 @@ subagent({
 | `fork`                 | boolean | `false`        | Force the full-context fork mode for this spawn, overriding any agent `session-mode` frontmatter  |
 | `interactive`          | boolean | derived        | Mark this spawn as interactive (don't wake the parent on stall/recovery). Defaults to the agent's `interactive` frontmatter, otherwise the inverse of `auto-exit`. |
 | `model`                | string  | configured or parent | Exact authenticated `provider/model-id`, or an ordered comma-separated Pi fallback list; fallback lists are unavailable for worktree spawns. Resolution is tool argument → agent frontmatter → per-agent config → global config → parent |
-| `thinking`             | string  | parent level   | Pi thinking level (`off` through `max`); omit to inherit the parent                                |
+| `thinking`             | string  | parent level   | Pick the model tier first, then set thinking within that model's range: minimal/low for bounded mechanical work, medium for ordinary implementation or review, high+ for architecture, security, or hard diagnosis. Omitting still inherits the parent level; this is a discouraged fallback for orchestrated children. |
 | `systemPrompt`         | string  | —              | Role/system-prompt text for a bare spawn; named agents keep their definition body                  |
 | `skills`               | string  | —              | Comma-separated skill names                                                                       |
 | `tools`                | string  | —              | Comma-separated tool names                                                                        |
@@ -389,7 +397,7 @@ prompts, handoffs, and results.
 
 ### Isolated worktree runs
 
-Use one worktree per independent writing task; keep read-only agents in ordinary panes. `cwd` selects the source Git repository, `branch` must be unique, and `base` is resolved to an exact commit before creation. If `base` is omitted, the source checkout's committed `HEAD` is used. Parent-checkout changes that have not been committed are not copied.
+Use one worktree per parallel independent writing task; a single or sequential writer can work in the parent checkout, and read-only agents use ordinary panes. `cwd` selects the source Git repository, `branch` must be unique, and `base` is resolved to an exact commit before creation. If `base` is omitted, the source checkout's committed `HEAD` is used. Parent-checkout changes that have not been committed are not copied.
 
 A launch with `worktree` and an effective bundled `scout`, `reviewer`, or `adversarial-reviewer` returns a non-blocking warning. Scouts and reviewers normally need an ordinary pane; the adversarial reviewer is a coordinator that uses an ordinary pane for its child reviewers. To inspect or review an existing worker result, start an ordinary child in that retained worktree path. Project or global role overrides do not receive these bundled-role warnings.
 

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

@@ -132,7 +132,9 @@ the package's `/plan` workflow, not as a second kind of subagent definition.
 A role describes the work; a runtime describes which authenticated Pi
 provider/model and thinking level one invocation uses. The model-resolution
 chain is explicit invocation choice, agent default, per-agent configuration,
-global configuration, then the parent model.
+global configuration, then the parent model. Inheritance is the resolver fallback,
+not the orchestrator default; independent review requires a different
+provider/family than the model that produced the work.
 
 Apply these rules:
 

package/docs/worktree-subagents.md

@@ -10,6 +10,8 @@ Run Pi inside Herdr from a Git checkout, then give each independent writing task
 subagent({
   name: "Ticket 123",
   agent: "worker",
+  model: "<worker-provider>/<mid-tier-id>",
+  thinking: "medium",
   cwd: "/path/to/repository",
   worktree: { branch: "ticket/123", base: "main" },
   task: "Implement ticket 123, run its tests, commit the result, and report the commit SHA. Do not push, merge, or remove the worktree.",
@@ -28,6 +30,8 @@ Use an ordinary subagent pane instead when the task is read-only, interactive, o
 subagent({
   name: "Scout auth",
   agent: "scout",
+  model: "<scout-provider>/<fast-tier-id>",
+  thinking: "low",
   task: "Map the auth flow; do not modify files.",
 });
 ```
@@ -70,6 +74,8 @@ Independent tasks can launch concurrently from the same committed base:
 subagent({
   name: "API ticket",
   agent: "worker",
+  model: "<worker-provider>/<mid-tier-id>",
+  thinking: "medium",
   worktree: { branch: "tickets/api", base: "main" },
   task: "Implement the API ticket, test it, and commit. Do not push or merge.",
 });
@@ -77,6 +83,8 @@ subagent({
 subagent({
   name: "UI ticket",
   agent: "worker",
+  model: "<worker-provider>/<mid-tier-id>",
+  thinking: "medium",
   worktree: { branch: "tickets/ui", base: "main" },
   task: "Implement the UI ticket, test it, and commit. Do not push or merge.",
 });
@@ -138,6 +146,8 @@ For parallel read-only review, prepare one stable existing checkout of the pull
 subagent({
   name: "PR reviewer",
   agent: "reviewer",
+  model: "<review-provider>/<mid-tier-id>",
+  thinking: "medium",
   cwd: "/path/to/pr-checkout",
   task: "Review base <base-sha> through head <head-sha>. First report git rev-parse HEAD. Do not modify files.",
 });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-herdr-agents",
-  "version": "1.3.0",
+  "version": "1.4.0",
   "description": "Asynchronous Pi subagents and approved review workflows in Herdr, with optional isolated Git worktrees",
   "keywords": [
     "pi-package",

package/pi-extension/subagents/index.ts

@@ -169,10 +169,13 @@ function getFirstText(
 
 function buildSubagentRoutingGuidelines(catalog?: string): string[] {
 	return [
-		"For subagent model and thinking selection, inherit the parent runtime by omitting both fields unless the task warrants an override.",
-		"For subagent tasks, prefer changing thinking before changing models: minimal/low for bounded mechanical work, medium for ordinary implementation or review, and high+ for architecture, concurrency, security, or hard diagnosis.",
-		"When overriding a subagent model, use an exact authenticated provider/model-id from the live catalog below. Do not invent aliases or fuzzy names.",
-		"Before launching a new group of subagents, choose a short task slug and name each new child <task>-<role>[-n], for example login-api or login-test2. Use only plan, research, ui, api, build, test, review, browser, security, perf, or merge as roles; leave existing names unchanged. After the final launch, print name | agent kind | role | model | worktree, then use each name in prompts, handoffs, and results.",
+		"Act as the coordinator: decompose the work, give each child one bounded outcome — goal, allowed files, verification, and whether to commit — and keep dependent writes sequential; parallelize only independent tasks.",
+		"Children are leaves by default: they do not push, merge, deploy, or orchestrate further agents unless their task explicitly authorizes it. The parent inspects each result or worktree handoff (diff against the reported base, run relevant tests) and owns integration, verification, and cleanup.",
+		"For orchestrated subagent work, explicitly set both model and thinking for every child: first choose a fast, mid, or frontier provider-family tier matched to task complexity, then set thinking within that model's supported range.",
+		"Use fast tier for bounded mechanical work and recon, mid tier for ordinary implementation or review, and frontier tier for architecture, security, hard diagnosis, or adversarial review. Use minimal/low thinking for mechanical work, medium for ordinary work, and high+ for hard work.",
+		"Review agents must use a different provider/family than the model that produced the work; a stronger model in the same family is quality escalation, not independent review. Use an exact authenticated provider/model-id from the live catalog below, never an alias or fuzzy name.",
+		"Omitting model and thinking still inherits the parent runtime, but this is a discouraged fallback for orchestrated children.",
+		"Before launching a new group of subagents, choose a short task slug and name each new child <task>-<role>[-n], for example login-api or login-test2. Use only plan, research, ui, api, build, test, review, browser, security, perf, or merge as roles; leave existing names unchanged. After the final launch, print name | agent kind | role | model | worktree (if any), then use each name in prompts, handoffs, and results.",
 		catalog ??
 			"Authenticated subagent model catalog becomes available after session start.",
 	];
@@ -184,7 +187,7 @@ const ThinkingLevelSchema = Type.Union(
 	THINKING_LEVELS.map((level) => Type.Literal(level)),
 	{
 		description:
-			"Pi thinking level. Omit to inherit the parent level. Prefer changing thinking before changing models: minimal/low for bounded mechanical work, medium for ordinary implementation or review, high+ for architecture, concurrency, security, or hard diagnosis.",
+			"Pi thinking level. Pick the model tier first, then set thinking within that model's range: minimal/low for bounded mechanical work, medium for ordinary implementation or review, high+ for architecture, security, or hard diagnosis. Omitting still inherits the parent level; do not omit on orchestrated child work.",
 	},
 );
 
@@ -209,7 +212,7 @@ const SubagentParams = Type.Object({
 	model: Type.Optional(
 		Type.String({
 			description:
-				"Exact authenticated provider/model-id, or an ordered comma-separated fallback list. Omit to inherit the parent model. Fallbacks are Pi-backed only and cannot be used with worktrees.",
+				"Explicitly pick an exact authenticated provider/model-id in a fast, mid, or frontier provider-family tier matched to the task, or use an ordered comma-separated fallback list. Review must use a different provider/family than the producing model. Omitting still inherits the parent model; do not omit for orchestrated children. Fallbacks are Pi-backed only and cannot be used with worktrees.",
 		}),
 	),
 	thinking: Type.Optional(ThinkingLevelSchema),
@@ -3054,8 +3057,10 @@ export default function subagentsExtension(pi: ExtensionAPI) {
 			label: "Subagent",
 			description:
 				"Spawn a sub-agent in a dedicated terminal herdr pane, or in an isolated Herdr-managed Git worktree when worktree is provided. " +
-				"Use unique worktree branches for independent writing tasks; use ordinary panes for read-only tasks. The worktree base is committed state, so uncommitted parent changes are not copied. " +
+				"Use ordinary panes for read-only tasks; a single or sequential writer can work in the parent checkout without a worktree. " +
+				"Reserve unique worktree branches for parallel independent writers starting from committed state — the worktree base is committed HEAD, so uncommitted parent changes are not copied. " +
 				"Worktree runs retain their workspace after completion for parent review; they are not pushed, merged, or removed automatically. " +
+				"To inspect a retained worktree result, spawn read-only agents in an ordinary pane with cwd set to that worktree path — do not create a new worktree for them. " +
 				"This is a fire-and-forget async tool: the call returns immediately with only an acknowledgement. " +
 				"When the sub-agent finishes, the harness AUTOMATICALLY delivers its result as a steer message that wakes you up and starts a new turn — you do not need to do anything to receive it. " +
 				"DO NOT write polling loops, sleep/wait commands, tail/watch scripts, or repeatedly read session/log files to detect completion. DO NOT call subagents_list or any other tool to 'check' status. All of that is wasted work — the harness handles delivery for you. " +
@@ -3063,8 +3068,10 @@ export default function subagentsExtension(pi: ExtensionAPI) {
 				"After spawning, either end your turn immediately, or work on other independent tasks (including spawning more subagents in parallel). The harness will wake you with the result when it is ready.",
 			promptSnippet:
 				"Spawn a sub-agent in a dedicated terminal herdr pane, or in an isolated Herdr-managed Git worktree when worktree is provided. " +
-				"Use unique worktree branches for independent writing tasks; use ordinary panes for read-only tasks. The worktree base is committed state, so uncommitted parent changes are not copied. " +
+				"Use ordinary panes for read-only tasks; a single or sequential writer can work in the parent checkout without a worktree. " +
+				"Reserve unique worktree branches for parallel independent writers starting from committed state — the worktree base is committed HEAD, so uncommitted parent changes are not copied. " +
 				"Worktree runs retain their workspace after completion for parent review; they are not pushed, merged, or removed automatically. " +
+				"To inspect a retained worktree result, spawn read-only agents in an ordinary pane with cwd set to that worktree path — do not create a new worktree for them. " +
 				"This is a fire-and-forget async tool: the call returns immediately with only an acknowledgement. " +
 				"When the sub-agent finishes, the harness AUTOMATICALLY delivers its result as a steer message that wakes you up and starts a new turn — you do not need to do anything to receive it. " +
 				"DO NOT write polling loops, sleep/wait commands, tail/watch scripts, or repeatedly read session/log files to detect completion. DO NOT call subagents_list or any other tool to 'check' status. All of that is wasted work — the harness handles delivery for you. " +

package/pi-extension/subagents/plan-skill.md

@@ -38,6 +38,10 @@ Phase 7: Review
 
 ---
 
+## Runtime
+
+Set `model` and `thinking` on every spawn. Use an exact authenticated provider/model ID: a fast-tier model for scouts, a mid-tier model for ordinary workers, and a frontier-tier model only for architecture or hard diagnosis. Reviewers must use a different provider/family than workers. Do not omit `model` in this workflow.
+
 ## Fire-and-forget completion
 
 `subagent` is fire-and-forget. After each spawn:
@@ -83,6 +87,8 @@ Standard filenames:
 subagent({
   name: "🔍 Scout",
   agent: "scout",
+  model: "<scout-provider>/<fast-tier-id>",
+  thinking: "low",
   task: `Analyze the codebase for [user's request area]. Map file structure, key modules, patterns, conventions, and existing code related to [feature area]. Focus on what a planner would need to understand before designing this feature.
 
 Put your full findings in your final assistant message.`,
@@ -105,6 +111,8 @@ Spawn the interactive planner with the scout's context and the user's request. T
 subagent({
   name: "💬 Planner",
   agent: "planner",
+  model: "<planner-provider>/<frontier-tier-id>",
+  thinking: "high",
   interactive: true,
   task: `Plan: [what the user wants to build]
 
@@ -132,6 +140,8 @@ If the planner significantly changed scope (new subsystems, areas the original s
 subagent({
   name: "🔍 Scout (updated scope)",
   agent: "scout",
+  model: "<scout-provider>/<fast-tier-id>",
+  thinking: "low",
   task: "The plan changed scope. Gather context for [new areas]. Read the plan at [plan path]. Focus on [specific files/modules the planner identified that weren't in the original scout]. Put findings in your final assistant message.",
 });
 ```
@@ -171,6 +181,8 @@ Sequential example:
 subagent({
   name: "🔨 Worker 1/N",
   agent: "worker",
+  model: "<worker-provider>/<mid-tier-id>",
+  thinking: "medium",
   task: `Implement Task 1 from the plan.
 
 Plan: [plan path]
@@ -187,6 +199,8 @@ For independent writing tasks, first ensure their shared base is committed. The
 subagent({
   name: "🔨 Task-1",
   agent: "worker",
+  model: "<worker-provider>/<mid-tier-id>",
+  thinking: "medium",
   cwd: "/absolute/path/to/source-repo",
   worktree: { branch: "plan-name/task-1", base: "HEAD" },
   task: `Implement Task 1.
@@ -229,6 +243,8 @@ After all shared-checkout changes and accepted worktree results are integrated:
 subagent({
   name: "Reviewer",
   agent: "reviewer",
+  model: "<review-provider>/<mid-tier-id>",
+  thinking: "medium",
   interactive: false,
   task: "Review the recent changes. Plan: [plan path]. Put the full review in your final assistant message.",
 });

package/pi-extension/subagents/runtime-routing.ts

@@ -336,12 +336,12 @@ export function buildAuthenticatedModelCatalog(
     ].filter(Boolean);
     lines.push(`- ${model.provider}/${model.id} — ${facts.join(", ")}`);
   }
-  if (models.length === 0) lines.push("- none discovered; inherit the parent runtime");
+  if (models.length === 0) lines.push("- none discovered; omitting model still inherits the parent runtime");
   if (models.length > visibleModels.length) {
     lines.push(`- … ${models.length - visibleModels.length} more authenticated models omitted`);
   }
   lines.push(
-    "Default: inherit the parent model and thinking. Override thinking first; override model only when task capability, speed, cost, modality, or context warrants it.",
+    "For orchestrated children, explicitly select an exact provider/model-id by task tier first (fast for bounded mechanical work and recon, mid for ordinary implementation or review, frontier for architecture, security, hard diagnosis, or adversarial review), then set supported thinking. Reviews must use a different provider/family than the producing model. Omitting model and thinking inherits the parent runtime as a discouraged fallback.",
   );
   return lines.join("\n");
 }

package/skills/orchestrate/SKILL.md

@@ -43,7 +43,14 @@ role. Every declared role must be Pi-backed and have a non-empty read-only tool
 set after runner derivation. Use bounded caps no higher than `maxAgents: 8` and
 `maxConcurrency: 4`; leave enough agent calls for one synthesizer and any
 permitted replacement. Exact model and thinking are mandatory for every node.
-Never inherit, guess, or fall back to a parent or role default.
+Pick each node's exact authenticated `provider/model-id` by the tier matched to
+its task: fast for bounded mechanical work and recon, mid for ordinary review,
+and frontier for architecture or hard diagnosis. Then set thinking within that
+model's supported range. When more than one provider is authenticated,
+independent reviewer nodes must use a different provider/family than the model
+that produced the work; do not reuse that family for its review. Never inherit,
+guess, or fall back to a parent or role default. Do not add tier fields to
+workflow metadata; each node continues to pin its exact provider/model.
 
 The first flow is review-only. Do not plan writers, commits, worktrees for
 writing, ticket changes, pull requests, merges, deployments, publishing,