pi-herdr-agents 1.3.0 → 1.3.1

package/CHANGELOG.md

@@ -7,11 +7,19 @@ 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.3.1](https://github.com/giuseppecrj/pi-herdr-agents/compare/v1.3.0...v1.3.1)
+
+### 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)
+
+## [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,8 +71,8 @@ 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.
 ```
 
@@ -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                                                                        |

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.3.1",
   "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,9 +169,10 @@ 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.",
+		"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, then use each name in prompts, handoffs, and results.",
 		catalog ??
 			"Authenticated subagent model catalog becomes available after session start.",
@@ -184,7 +185,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 +210,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),

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,