pi-herdr-subagents-planning

One pi package for the entire /plan grill-and-plan workflow on herdr subagents.

pi-herdr-subagents-planning bundles the whole pipeline into a single install (cached + fresh contexts):

Cached context (.agent/)  →  architecture, conventions, decisions, domain (stable, reused)
Fresh context (per task)  →  request + relevant files + plan + diff (small, independent)

Phase 1  quick orientation          (main session, ~30s — checks .agent/ + stack)
Phase 2  Grill-and-Plan planner     (interactive, one session — grilling + domain-modeling → plan.md + pointer todos)
       ↳ Scout (optional, only for unfamiliar/large areas)
Phase 3  human gate                 (verify plan.md + ISC + todos)
Phase 4  sequential workers         (pointer-contract, one worker per todo — cached + plan § + relevant source)
Phase 5  reviewer                   (ISC evidence + P0-P3 triage — cached + plan + diff)
Phase 6  knowledge update           (permanent knowledge → .agent/, task reasoning discarded)

Workflow graph

flowchart TD
    Request["User request"] --> PlanCommand["Run plan command"]
    PlanCommand --> Bootstrap["Initialize missing agent cache<br/>from bundled templates without overwrite"]
    Bootstrap --> Orientation["Quick orientation<br/>cache and relevant stack"]

    Cache["Agent cache<br/>architecture, conventions, decisions, domain"] --> Planner
    Orientation --> Planner["Interactive planner<br/>grilling and domain modeling"]
    Planner -->|needs facts| Scout["Optional scout<br/>focused read-only facts"]
    Scout --> Planner
    Planner --> Domain["Update product glossary or ADR<br/>only when warranted"]
    Planner --> Plan["Write durable plan<br/>ISC and acceptance commands"]
    Planner --> Todos["Create pointer-contract todos<br/>forwarded to parent session"]
    Domain --> Plan
    Plan --> Gate{"Human review<br/>plan, ISC, and todos"}
    Todos --> Gate

    Cache --> Worker["Sequential worker<br/>one todo at a time"]
    Gate -->|approved| Worker
    Worker --> Source["Fresh task context<br/>plan section, pattern files, diff"]
    Source --> Verify["Acceptance commands<br/>LSP and lens diagnostics"]
    Verify -->|next todo| Worker
    Verify -->|all complete| Reviewer

    Cache --> Reviewer["Reviewer<br/>plan and diff"]
    Plan --> Reviewer
    Reviewer --> Review["ISC evidence<br/>P0 to P3 triage"]
    Review -->|P0 or P1| Repair["Create repair todo"]
    Repair --> Worker
    Review -->|pass or P2 P3 noted| Promote{"Permanent knowledge"}
    Promote -->|yes| Update["Update cache or product domain docs"]
    Promote -->|no| Discard["Discard fresh task reasoning"]
    Update --> Done["Completed task"]
    Discard --> Done

CONTEXT.md and ADRs model the product domain; .agent/ models durable project knowledge. The plan, scout report, source reads, diff, and test evidence are fresh task context and are not promoted unless they become permanent.

Install once, get the slash commands, every agent, every skill, todo forwarding, and diagnostics — no five-package choreography. On the first /plan (or session_start), the extension worktree-aware primes the target project's .agent/ cache — copies from main in a worktree, otherwise mines via primer scout — without overwriting existing knowledge.

pi install npm:pi-herdr-subagents-planning
# or local dev
pi install ./pi-herdr-subagents-planning
# try without persisting
pi -e ./pi-herdr-subagents-planning

Then inside herdr:

/plan Add a dark-mode toggle to the settings page

Why a single package?

The V2 workflow was spread across global installs and hand-maintained agent overrides:

• the subagents runtime (pi-herdr-subagents)
• the todo overlay (@juicesharp/rpiv-todo)
• the diagnostics lens (pi-lens)
• two local skills (grilling, domain-modeling)
• a global extension (planner-todo-forward.ts) that shuttled planner todos back to the parent session

Keeping those in sync across machines was brittle. This package vendors the workflow and acknowledges every baseline it composes via dependencies + bundledDependencies + the table below, so pi install pulls one tarball that contains the whole graph with pinned versions.

What's inside

Extensions (loaded via pi.extensions)

| Extension | Source in this package | Baseline | What it does | | --- | --- | --- | --- | | herdr-subagents | extensions/herdr-subagents/index.ts (vendored) | pi-herdr-subagents@^0.1.7 | subagent / subagent_resume / subagent_interrupt / subagents_list, /plan / /prime / /iterate / /subagent slash commands, herdr pane lifecycle, model routing (config.json), status widget, worktree-aware prime (copy-from-main vs primer scout) | | planner-todo-forward | extensions/planner-todo-forward.ts | previously ~/.pi/agent/extensions/planner-todo-forward.ts (global) | ensures the interactive planner's todos land in the parent session (sidecar + live-store import) instead of dying with the ephemeral planner session | | rpiv-todo | node_modules/@juicesharp/rpiv-todo/index.ts | @juicesharp/rpiv-todo@^2.7.1 | todo tool, live overlay, replay, blockedBy graph, persistence | | pi-lens | node_modules/pi-lens/dist/index.js | pi-lens@^3.8.74 | LSP + Biome/Ruff/ast-grep/knip/jscpd diagnostics for workers (lens_diagnostics, lsp_diagnostics, symbol_search, module_report, …) |

The herdr-subagents extension is vendored rather than loaded from node_modules/pi-herdr-subagents/... so the V2 agent prompts (planner's Do not suggest a recommended answer, exit-gate, worker pointer-contract,…) ship with the package even though the upstream npm tarball may lag behind local V2 snapshots. The original source is acknowledged as the baseline and kept in dependencies/bundledDependencies for traceability.

Agents (vendored in agents/)

| Agent | Model (default) | Role | | --- | --- | --- | | planner | openai-codex/gpt-5.6-sol | one-session griller + planner: design-tree rounds → CONTEXT.md/docs/adr → pointer plan.md + pointer todos | | worker | opencode-go/muse-spark-1.2-contributor | pointer-task executor: resolves pattern from code, grounds APIs via query-docs/symbol_search, runs acceptance commands, lsp_diagnostics/lens_diagnostics clean, commits, closes todo | | scout | openai-codex/gpt-5.6-luna | fast read-only reconnaissance for facts the planner needs | | primer | openai-codex/gpt-5.6-luna | .agent cache primer: mines architecture/conventions/decisions/domain from repo (spawned by /prime mine path, idempotent) | | reviewer | openai-codex/gpt-5.6-terra | ISC-evidence review against plan.md + CONTEXT.md + ADRs, P0-P3 triage | | visual-tester | (inherits models.default) | Chrome-CDP visual QA (bundled from upstream) |

Model routing is fixed via config.json (models.default → models.agents.<role>) — no per-run picker. Overrides follow tool-arg → agent frontmatter → per-agent config → global default → parent model.

Skills (vendored in skills/)

| Skill | Source | Baseline | Used by | | --- | --- | --- | --- | | grilling | skills/grilling/SKILL.md | ~/.agents/skills/grilling (local) | planner's design-tree frontier | | domain-modeling | skills/domain-modeling/ (SKILL.md + ADR-FORMAT.md + CONTEXT-FORMAT.md) | ~/.agents/skills/domain-modeling (local) | planner's glossary/ADR discipline (CONTEXT.md, docs/adr/NNNN-*.md) |

Skills declare name + description in SKILL.md frontmatter; they are discovered via pi.skills manifest entries.

Config

config.json.example mirrors the upstream pi-herdr-subagents example:

{
  "status": { "enabled": true },
  "models": {
    "default": "opencode-go/muse-spark-1.2-contributor",
    "agents": {
      "planner": "openai-codex/gpt-5.6-sol",
      "worker": "opencode-go/muse-spark-1.2-contributor",
      "reviewer": "openai-codex/gpt-5.6-terra"
    }
  }
}

Copy to config.json and replace IDs with exact authenticated provider/model-id values if you want custom routing. Otherwise the agent frontmatter models above run.

Baseline acknowledgments

This package does not reimplement the workflow from scratch — it composes and vendors the following baselines. All are retained under their original licenses (MIT unless noted) and pinned in package.json.

| Baseline | Version pinned | License | NPM / Source | Role in this package | | --- | --- | --- | --- | --- | | pi-herdr-subagents | ^0.1.7 (built 2026-08-25 against 0.1.7) | MIT | npm:pi-herdr-subagents | subagents runtime, /plan command, plan-skill.md, lifecycle/status/activity/terminal/herdr plugins | | @juicesharp/rpiv-todo | ^2.7.1 | MIT | npm:@juicesharp/rpiv-todo | todo state/reducer/store/replay + overlay | | pi-lens | ^3.8.74 | MIT | npm:pi-lens | diagnostics, LSP, ast-grep, lint, complexity | | grilling skill | snapshot 2026-08-25 | — (local skill, MIT-compatible) | ~/.agents/skills/grilling/SKILL.md | design-tree grilling engine | | domain-modeling skill | snapshot 2026-08-25 | — (local skill, MIT-compatible) | ~/.agents/skills/domain-modeling/* | glossary/ADR discipline | | planner-todo-forward extension | snapshot 2026-08-25 | MIT | ~/.pi/agent/extensions/planner-todo-forward.ts | cross-session todo forwarding |

Peer dependencies are not bundled (per packages.md guidance): @earendil-works/pi-ai, @earendil-works/pi-coding-agent, @earendil-works/pi-tui, typebox remain peerDependencies: "*" and are provided by the pi runtime.

Vendored sources preserve upstream attribution comments where present (e.g. herdr:pi integration header, skill frontmatter name/description).

How baselines are bundled

package.json declares:

{
  "dependencies": {
    "pi-herdr-subagents": "^0.1.7",
    "@juicesharp/rpiv-todo": "^2.7.1",
    "pi-lens": "^3.8.74"
  },
  "bundledDependencies": ["pi-herdr-subagents", "@juicesharp/rpiv-todo", "pi-lens"],
  "pi": {
    "extensions": [
      "./extensions/herdr-subagents/index.ts",
      "./extensions/planner-todo-forward.ts",
      "node_modules/@juicesharp/rpiv-todo/index.ts",
      "node_modules/pi-lens/dist/index.js"
    ],
    "skills": ["./skills/grilling", "./skills/domain-modeling"]
  }
}

• dependencies + bundledDependencies guarantee npm pack / pi install embeds the baselines in the tarball and npm install hoists them under node_modules/ (so pi-lens grammars, @juicesharp/rpiv-config, etc. resolve).
• pi.extensions / pi.skills use local vendored paths for herdr-subagents + the two skills, and node_modules/ paths for rpiv-todo + pi-lens, exactly as prescribed in packages.md ("extensions": ["extensions", "node_modules/shitty-extensions/extensions"]).
• Pi loads packages with separate module roots, so separate global installs do not collide.

To update a baseline: bump the version in dependencies, run npm install, re-vendor the changed source files if vendored, and record in CHANGELOG.md.

Usage

Requires herdr (the only supported terminal) with HERDR_ENV=1.

herdr
pi
/prime            # optional: explicitly prime .agent (worktree→copy from main, else primer scout)
/plan <your request>

The slash commands are extensions/herdr-subagents/plan-skill.md (cached + fresh). The main agent then:

1. session_start worktree-aware prime (copy-from-main in worktree, else heuristic mine) — no manual step needed; /prime is the explicit deep variant (spawns primer scout when .agent is stub)
2. ~30s orientation (ls .agent/, find, package.json peek) then spawns one interactive planner (interactive: true) — loads cached context, grill rounds until frontier empty → writes .agent/plans/YYYY-MM-DD-<name>/plan.md + CONTEXT.md/docs/adr + pointer todos (forwarded to parent)
3. human gate (you review ISC + todos)
4. sequential worker loop — each worker loads cached context + plan.md § + pattern file only (caller_ping on ambiguity); scout only if unfamiliar/large
5. reviewer against ISC/acceptance commands (cached + plan + diff)
6. knowledge update — permanent decisions/conventions → .agent/, task reasoning discarded

Artifacts: .agent/plans/<name>/plan.md, .agent/*.md (cached), CONTEXT.md, docs/adr/NNNN-*.md, todos in session.

Development

npm install          # pulls bundled baselines for local dev
npm pack --dry-run   # verify files + bundled tarballs
pi install ./        # test local install (project-scope: pi install -l ./)

Lint / typecheck vendored extensions via project tsc if present.

License

MIT — see LICENSE. Baselines retain their own MIT licenses (see table above). This package's vendored copies preserve upstream license headers and are licensed compatibly.