Pi Herdr Orchestration

Deterministic, provider-agnostic multi-agent repository orchestration for coding agents. Dynamically coordinates task discovery, dependency graphs, isolated Git worktrees, terminal multiplexing with Herdr, and evidence-based verification across your entire development lifecycle.

The skill runs on Pi, Claude Code, OpenAI Codex, and Google Antigravity. It works out-of-the-box with plain Git and a single agent, and dynamically discovers optional high-leverage integrations at runtime: PiWorkflow, Gentle AI / Engram, Herdr, Guardian Angel (GGA), Engineering Excellence, Matt Pocock's skill suite, and context reduction engines.

Table of Contents

• Overview & Core Problems Solved
• Architecture & Workflow Lifecycle
  • The Command Hierarchy: Master, Chiefs, and Workers
  • Workspace Isolation with Herdr & Git Worktrees
• Cognitive Model & Decision Pipeline
  • 1. Independence-First Dispatch & Task Graph
  • 2. Progressive Disclosure & Bounded Contexts
  • 3. Evidence-Based Validation (Proof Before Claim)
  • 4. Non-Polluting Compact State Protocol
  • 5. Multi-Agent Supervision & Context-Preserving Architecture
  • 6. Two-Tier Integration & Merge Queue
• Skill Ecosystem Integrations
  • PiWorkflow (pi-extensible-workflows v6.2.0)
  • Pi Extensible Roles (@piewf/pi-ext-roles v0.2.0)
  • Gentle AI Suite & Engram
  • Engineering Excellence
  • Matt Pocock Skill Suite
  • Guardian Angel (GGA)
  • Context Reduction & Semantic Navigation Stack
  • Dynamic Routing Table
• Installation & Dependency Management
  • Install the Skill via Vercel Skills CLI
  • Dependency Bootstrap (System Runtimes & Skill Suites)
  • Mandatory Per-Repository Initialization
  • Environment Verification
  • Mailbox & Supervision Commands
  • Compaction & Overlap Rules
• Release and npm Trusted Publishing
• Sources & References
• License

Overview & Core Problems Solved

When AI coding agents are assigned complex multi-step backlogs, monorepo refactors, or concurrent issue queues, they typically encounter critical failure modes:

1. Agent Sprawl & Race Conditions: Multiple agents editing the same files on the same branch create merge conflicts, clobbered changes, and broken git history.
2. Context Window Degradation: Ingesting full transcripts, logs, and whole-codebase dumps degrades LLM attention, leading to hallucinations and sloppy code.
3. Premature "Done" Claims: Agents claiming completion based on conversational prose rather than machine-verifiable test runs, linter passes, and runtime evidence.
4. Coordination Debt: Parallelizing tasks that secretly share dependencies or API contracts, leading to integration disasters.

Pi Herdr Orchestration solves these problems deterministically. It establishes a strict division of labor, runs tasks in isolated Git worktrees under dedicated Herdr terminal panes, routes domain-specific skills on demand, and requires reproducible proof before any code is merged.

Architecture & Workflow Lifecycle

The Command Hierarchy: Master, Chiefs, and Workers

The orchestrator enforces a clean separation of concerns across three distinct operational tiers:

               ┌──────────────────────────────────────────────┐
               │         [MASTER] Pi Herdr Orchestrator       │
               │  (Control plane, dependency graph, decisions)│
               └──────────────────────┬───────────────────────┘
                                      │
         ┌──────────────┬─────────────┼──────────────┬──────────────┐
         ▼              ▼             ▼              ▼              ▼
   [CHIEF/SCOUT]  [CHIEF/BUILD] [CHIEF/QUALITY][CHIEF/MEMORY] [CHIEF/AUDIT]
    (Discovery)    (Execution)   (Verification) (Persistence)    (Cleanup)
         │              │             │              │              │
         └──────────────┼─────────────┴──────────────┴──────────────┘
                        │
         ┌──────────────┴──────────────┐
         ▼                             ▼
    [I#42] Auth Fix              [PR#18] Review
 (Worktree .worktrees/i42)    (Worktree .worktrees/pr18)

1. [MASTER] Pi Herdr Orchestrator (The Control Plane)

• Role: Owns the repository scope, backlog discovery, pairwise independence analysis, worktree reservations, merge queue, and final stop conditions.
• Golden Rule: The master never writes or implements code. A master session editing code while coordinating workers is an architectural defect.

2. Department Chiefs (Bounded Supervision)

When the host supports multiple sessions or subagents, the master delegates operational areas to specialized chiefs:

• [CHIEF/SCOUT] (Discovery & Triage): Maps monorepo boundaries, default branches, CI configurations, and clusters issues by root cause.
• [CHIEF/BUILD] (Implementation & Worktrees): Provisions worktrees, assigns tasks to workers, and supervises progress.
• [CHIEF/QUALITY] (Verification & Reviews): Orchestrates test execution, auto-grilling, adversarial reviews, and quality gates.
• [CHIEF/MEMORY] (Hydration & Persistence): Recalls historical ADRs and conventions via Engram and writes durable post-task learnings.
• [CHIEF/AUDIT] (Reconciliation & Teardown): Audits overall repository health and verifies resource cleanup.

Fallback: If the host cannot create independent subagents, the master flattens the hierarchy into structured phase headers without simulating false parallel execution.

3. Workers (Task Execution Sessions)

• Role: Execute a single, bounded contract ([I#42], [PR#87], [REV#12]).
• Contract Lifecycle: $$\text{DISCOVER} \longrightarrow \text{UNDERSTAND} \longrightarrow \text{PLAN} \longrightarrow \text{IMPLEMENT} \longrightarrow \text{VERIFY} \longrightarrow \text{SELF-REVIEW} \longrightarrow \text{HANDOFF} \longrightarrow \text{READY}$$
• Workers never declare themselves READY until all validation commands pass and evidence is logged.

Workspace Isolation with Herdr & Git Worktrees

The orchestrator guarantees clean workspace boundaries:

• 1 Task = 1 Branch = 1 Git Worktree = 1 Dedicated Session/Pane
• Single-Writer Rule: Exactly one writer modifies a given worktree at any time.
• Herdr Terminal Multiplexing:
  • One Herdr workspace per repository.
  • Panes and tabs are created with semantic labels immediately upon startup (repo:issue-42-auth, repo:pr-87-review, repo:compose-validation).
  • Terminal state and processes remain persistent and inspectable even during agent context switches.

Cognitive Model & Decision Pipeline

The orchestrator’s reasoning engine follows five deterministic principles:

1. Independence-First Dispatch & Task Graph

Concurrency is treated as an optimization tool, not an automatic default. Before dispatching any worker, the orchestrator constructs a dependency graph by performing pairwise relation analysis:

Before an implementer starts, the master records an ownership reservation in the task registry (e.g. frontend/auth/* -> I#42). Any subsequent task claiming that surface is blocked or queued.

2. Progressive Disclosure & Bounded Contexts

Model context windows are treated as scarce, depleting resources:

• Workers never receive a full dump of the repository, entire issue backlogs, or preceding conversation transcripts.
• Each worker receives a bounded brief: exact objective, issue context, allowed and forbidden file scope, required verification commands, and completion criteria.
• Domain skills are loaded only into the specific sessions that need them, keeping the master session lean.

3. Evidence-Based Validation (Proof Before Claim)

Prose claims of success are rejected. Validation follows a strict narrow-to-wide verification funnel:

1. Targeted Unit / Regression Check: Failing reproduction test first, followed by minimal fix and passing test.
2. Package-Level Suite: Ensures no localized regressions.
3. Type-Check & Linter: Compiler and static analysis passes.
4. Package Build: Artifact compilation verification.
5. Integration / E2E: Cross-package compatibility.
6. Docker Compose / Runtime Validation: Starting disposable stacks to check service startup, migrations, health checks, and API connectivity.
7. Browser / UI Verification: Checking rendering, responsiveness, console logs, network errors, and accessibility.

Every check is logged as PASS, FAIL, BLOCKED, or NOT RUN. A check marked NOT RUN is never treated as passing.

4. Non-Polluting Compact State Protocol

Parent sessions never ingest worker transcripts. All cross-session communication uses the canonical repo-orchestrator/v1 JSON envelope:

{
  "v": "repo-orchestrator/v1",
  "kind": "result",
  "id": "r_20261008_042",
  "parent": "chief-build-01",
  "run": "repo-run-10",
  "sender": {
    "role": "implementer",
    "session": "pi-i42",
    "tab": "[I#42] Config loading",
    "worktree": ".worktrees/issue-42-config-loading"
  },
  "task": { "id": "I#42", "type": "issue", "goal": "Fix config loading precedence" },
  "state": "READY",
  "branch": "fix/42-config-loading",
  "summary": "Config precedence now prioritizes environment variables over file defaults.",
  "checks": [
    { "name": "unit", "status": "PASS", "ref": "test-run-884" },
    { "name": "types", "status": "PASS", "ref": "tsc-clean" },
    { "name": "gga", "status": "PASS", "ref": "gga-hash-cache" }
  ],
  "evidence_ref": "ref:sha256:2df2a23aa02e0171",
  "decisions": ["Preserve backward compatibility for legacy JSON configurations."],
  "risks": [],
  "blockers": [],
  "memory": { "status": "persisted", "ref": "engram:obs-88219" },
  "next": "chief-review"
}

Human-readable Markdown reports (such as the cycle dashboard) are generated directly from these structured envelopes.

5. Multi-Agent Supervision & Context-Preserving Architecture

Dispatched sessions that operate without supervision or feedback loops lead to silent failures, runaway tokens, or deadlocks. Real-world multi-agent orchestration operates like an executive corporate office: master coordinates, workers execute, and communication strictly protects model context windows.

How the Architecture Preserves and Improves Context Windows

1. Semantic Evidence Offloading (ref:sha256:...):
   • The Problem: Dumping 300+ lines of raw npm test, compiler diagnostics, or multi-file git diffs directly into conversation tokens pollutes attention, degrades reasoning, and forces premature, lossy compaction.
   • The Fix: Raw artifacts are SHA-256 hashed and stored on disk under <git-common-dir>/orchestrator/<run>/evidence/<sha256>.txt. Only the immutable reference ref:sha256:... transits through prompts. The master inspects raw evidence only by exception.
2. Native Pi Extension (extensions/index.mjs) vs Subshell Clutter:
   • The Problem: Repeatedly spawning subshells (node scripts/mailbox.mjs ...) injects shell process wrappers, terminal ANSI codes, and stderr noise into conversation history.
   • The Fix: Native in-process Pi tools (orch_report, orch_status, orch_ask, orch_reply, orch_evidence) communicate purely via in-memory JavaScript objects and JSON files, bypassing shell noise completely.
3. Prompt Cache Continuity:
   • Static brief headers, role definitions, and invariant repository rules are anchored at the prefix of worker prompts. Dynamic per-task arguments are appended at the end. This guarantees maximum prompt cache hits on upstream providers (Anthropic, OpenAI, Gemini), dramatically cutting latency and API costs.
4. Bi-directional Ask / Reply Protocol (orch_ask / orch_reply):
   • When a worker encounters an ambiguous architectural question or missing credential, it invokes orch_ask, setting its state to BLOCKED with flag ASK.
   • The master sees the question in its supervision dashboard, provides an explicit decision via orch_reply, and automatically transitions the worker back to WORKING without hanging or busy-polling.
5. Cross-Platform Directory Locking (lock.mjs):
   • Protected by atomic directory locks using node:path basename, ensuring zero file corruption or interleaved JSON writes even when 4–6 parallel Herdr panes report simultaneously across Linux, macOS, or Windows.
6. Continuous Herdr Supervision Loop:
   • Master stays active, reconciling mailbox states with live Herdr process liveness (working, idle, done, blocked):
     • OK: Healthy and reporting on schedule.
     • ASK: Worker submitted a blocking question awaiting master reply.
     • DECIDE: Worker reported terminal state (READY, DEVELOPMENT, BLOCKED, FAILED). Master reconciles with Git/CI.
     • SILENT: Agent is idle in Herdr but last mailbox report was WORKING. Master reads recent pane output and nudges.
     • STALE: Agent is working in Herdr but has not reported within the stale threshold (default 10 minutes).
     • NEEDS_HUMAN: Herdr recognizes an approval or question dialog; master escalates to the human operator.
     • GONE: Worker agent process missing from Herdr; master checks the worktree and restarts if needed.
7. Interactive TUI Command (/orch):
   • Instant visual fleet status directly inside the active Pi session without context pollution.

Current Herdsman alignment

The orchestration contract follows the latest upstream Herdsman behavior:

• Select Agents by effective runtime capabilities, not filenames or configured child names. If no suitable child is available, investigate locally and record the capability gap instead of simulating delegation.
• Keep runtime capability discovery separate from layered definition configuration. Disabled definitions or definitions with unavailable required children are not selectable runtime capabilities.
• Treat role-derived Herdr tab labels (Lead, Managed Lead, Manager, Chief) as presentation only. They never grant authority or prove assignment ownership.
• Prefer deterministic simulated smoke for covered Pi/Herdr boundary scenarios; use live-model smoke when model/provider behavior or instruction adherence is under test.
• Treat model execution failure as nonterminal evidence: do not retry automatically, replay tools, stop children, integrate partial work, or publish a successful handoff.

These points are aligned with boadij/pi-herdsman commits 0dc62d39, a422c804, c72acadf, 44698e40, 56bd0258, and 321114de (October 2026).

6. Two-Tier Integration & Merge Queue

The master categorizes completed work based on empirical evidence:

• STABLE: All acceptance criteria, tests, and reviews pass. Ready to merge or publish to the primary branch (main).
• DEVELOPMENT: Incomplete, exploratory, or partially verified work. Preserved on an isolated feature branch with a documented handoff state.

Before merging individual green branches into main, the master executes an Integration Pass on the combined branch. Independent tasks that pass in isolation can still conflict when combined; the integration pass prevents broken main branches.

Skill Ecosystem Integrations

Pi Herdr Orchestration dynamically bridges and routes between major AI coding agent skill ecosystems:

PiWorkflow (pi-extensible-workflows v6.2.0)

• Role: Execution engine substrate.
• Capabilities Used:
  • Deterministic orchestration: workflow, parallel(...), pipeline(...), withWorktree(...), shell(...), and persistent agent.create(...) handles.
  • Aggregated Telemetry (#318): Automatic calculation of elapsed execution time and total token usage per phase and function, including nested child agents.
  • Effort-Aware Model Resolution (#314): Native parsing and propagation of namespaced and colon-bearing model strings (cliproxyapi/claude-opus-5-5:high, cliproxyapi/gemini-3.8-flash-high).
  • Reliable Linux Process Liveness: Uses /proc/<pid>/stat starttime instead of ctime to eliminate false positives from kernel PID recycling.
  • Workflow Recovery: Replaying completed operations through workflow_status, workflow_retry, and workflow_resume.

Pi Extensible Roles (@piewf/pi-ext-roles v0.2.0)

• Role: Independent role authoring, configuration, and runtime preparation.
• Capabilities Used:
  • Reusable Markdown role definitions (roles/*.md) with tool, skill, and context file selectors.
  • Independent CLI inspection: pi-role --identify <role> prints the resolved file path and complete role frontmatter.
  • Native workflow preparation adapter (registerRolePreparationHook) decoupling roles from the workflow core.

Gentle AI Suite & Engram

• Role: Harness discipline, durable memory, and review authority.
• Capabilities Used:
  • gentle-engram: Persistent project memory across sessions, hydration of historical decisions, cross-agent handoffs.
  • work-unit-commits: Atomic, reviewable, self-contained commit slices.
  • chained-pr: Splitting changes exceeding 400 lines into stacked, reviewable PR chains.
  • branch-pr: Issue-first branch and PR creation with human-in-the-loop confirmation.
  • rdd-defect-workflow & gentle_review: Receipt-Driven Development with cryptographic review lineages.
  • judgment-day: Blind dual or adversarial reviews for high-stakes changes.
  • systemic-issue-triage & issue-root-resolution: Identifying shared root causes across large issue backlogs.

Engineering Excellence

• Role: Software engineering standards, architecture, and production readiness.
• Capabilities Used: SDD (Spec-Driven Development), TDD standards, quality gates, security audits, performance profiling, accessibility/i18n standards, Docker/CI rules, container-test-matrix for multi-distribution testing, and context budgeting.

Matt Pocock Skill Suite

• Role: Tactical developer workflows and problem breakdown.
• Capabilities Used:
  • triage: Classifying incoming issues and bug reports.
  • wayfinder & to-spec: Navigating fuzzy, ambiguous tasks into actionable specifications.
  • to-tickets: Decomposing specifications into atomic ticket graphs with explicit blocking edges.
  • diagnosing-bugs: Tight reproduction loops before code changes.
  • codebase-design & improve-codebase-architecture: Seams, deep module boundaries, and interface contracts.
  • grill-with-docs / grill-me: Adversarial stress-testing of plans and design assumptions.
  • retro: Retrospective learnings capture.

Guardian Angel (GGA)

• Role: Provider-agnostic pre-commit and pre-PR quality gate.
• Capabilities Used:
  • Reviewed by default via kilo:cliproxyapi/gemini-3.8-flash-high with high reasoning effort.
  • Bridge integration agents/gga-pi/ routing reviews directly through pi --print to the local CLIProxyAPI gateway.
  • Verifies git diffs, rules, and repository invariants after tests and before declaring a worker READY. Uses hash caching to ensure idempotent verification.

Context Reduction & Semantic Navigation Stack

• Role: Token preservation and AST-level exploration.
• Capabilities Used:
  • Serena: Language-server backed semantic code navigation (symbol search, call graphs) without exploratory file reads.
  • graphifyy & LLMLingua: Code knowledge graph construction and prompt token reduction.
  • RTK & sqz: Output compression and terminal filtering for large test logs and build output.
  • Wizard-AI: Compatibility manager for TOON/LEA tabular data encodings.

Dynamic Routing Table

The orchestrator dynamically routes tasks to the minimal sufficient skill set based on the situation:

Installation & Dependency Management

Install the Skill via Vercel Skills CLI

Install the skill for any supported agent directly from GitHub:

# Global installation across supported agent runtimes
npx skills add darkrei08/pi-herdr-orchestration \
  --skill pi-herdr-orchestrator \
  --agent codex claude-code antigravity antigravity-cli pi \
  --global

Or from a local clone:

npx skills add . \
  --skill pi-herdr-orchestrator \
  --agent codex claude-code antigravity antigravity-cli pi \
  --global

Dependency Bootstrap (System Runtimes & Skill Suites)

The Vercel Skills CLI installs skill definition files only; it deliberately does not run third-party installers or post-install scripts. Run the dependency bootstrap script to inspect missing dependencies and install required runtimes as well as all 4 required skill suites (Engineering Excellence, Matt Pocock skills, Gentle AI skills, and Pi Herdr Orchestration):

# 1. Read-only dry run (inspects existing software/skills and prints a plan)
node scripts/bootstrap.mjs
# or: npm run bootstrap

# 2. Apply installations (requires explicit --apply flag)
node scripts/bootstrap.mjs --apply
# or: npm run bootstrap:apply

Mandatory Per-Repository Initialization

Every project or repository orchestrated by this skill must be initialized before workers begin execution. Run the repository initialization script:

# 1. Dry run in current repository
node scripts/init-repo.mjs
# or: npm run init-repo

# 2. Apply repository initialization
node scripts/init-repo.mjs --apply
# or: npm run init-repo:apply

# Or target a specific repository path:
node scripts/init-repo.mjs --dir /path/to/my-repo --apply

This command automatically configures:

• Git Baseline: Ensures repository initialization on main and creates .worktrees/.
• Gitignore Rules: Appends .worktrees/, .codegraph/, and .atl/ to .gitignore.
• Engram Memory Identity: Generates .git/engram-project-identity.json for isolated, persistent repository memory.
• Guardian Angel (GGA): Creates .gga quality-gate configuration and baseline AGENTS.md guidelines.
• Semantic Code Navigation: Deploys Serena project configuration for LSP symbol analysis.
• Token Compression: Injects sqz and rtk local hooks for terminal and tool reduction.
• Herdr Workspace: Creates a dedicated Herdr workspace named after the repository.
• Skill Registry: Catalogs all available skills into .atl/skill-registry.md.

Environment Verification

Run the read-only capability and host compatibility check:

# Output JSON report
node scripts/check.mjs --json
# or: npm run check:json

# Strict validation (exits nonzero if core runtimes or compaction conflicts exist)
node scripts/check.mjs --strict
# or: npm run check:strict

Mailbox & Supervision Commands

Supervise distributed worker sessions and inspect the shared mailbox:

# Check current run status and flagged tasks against Herdr agent liveness
node scripts/mailbox.mjs status --run <run-id>
# or: npm run mailbox:status -- --run <run-id>

# Run unit tests for supervision classification logic and file locking
npm test

# Native Pi interactive inspection (inside an active Pi session):
/orch

The report inspects:

• Core prerequisites: Node.js, Git, and Skill definitions.
• Agent runtimes: Pi, PiWorkflow, Gentle AI / Engram, Guardian Angel (GGA), and Herdr.
• Supporting CLIs: GitHub CLI (gh), Docker, and Docker Compose.
• Installed skill suites: Engineering Excellence, Matt Pocock, and Gentle AI.
• Context tooling: Wizard-AI, Serena, graphifyy, RTK, and sqz.
• Active Pi compaction owner.

Compaction & Overlap Rules

To prevent conflicting hooks and transcript corruption, the orchestrator enforces strict overlap guards:

• Pi Compaction Ownership: Under Vekexasia's dotenv model, pi-codex-context is the sole third-party compaction owner. The bootstrap intentionally skips @sting8k/pi-vcc. Multiple active compaction owners trigger an incompatible error and halt.
• Workflow & Memory Ownership: If Gentle AI / Engram or PiWorkflow is active, the orchestrator blocks the installation of overlapping Wizard-AI workflow, proxy, or memory modules, allowing only non-overlapping context tools (graphifyy, LLMLingua).
• Guardian Angel (GGA): The bootstrap installs the gga binary but never runs gga init or gga install automatically, preserving repository configuration.

Release and npm Trusted Publishing

Release tags must match the package.json version. The GitHub Actions workflow uses npm Trusted Publishing through OIDC; it does not depend on a long-lived NPM_TOKEN for normal releases. The one-time package bootstrap, npm login, npm trust, 2FA, GAT deprecation, and reusable commands are documented in docs/releasing.md.

Sources & References

The architecture and routing logic follow the published interfaces and documentation of these upstream projects:

• Vercel Agent Skills: Specification and CLI for universal cross-agent skill installation.
• OpenAI Codex Skills: Standardized SKILL.md operational contract format.
• Google Antigravity Skills: Skill discovery specification for Google Antigravity agents.
• Pi Coding Agent: Harness architecture, extensions, sessions, and tool calling by Mario Zechner.
• Pi Extensible Workflows: Multi-agent orchestration engine (workflow, parallel, withWorktree, checkpoints) by Roberto De Virgilio (@vekexasia).
• Engineering Excellence: Framework-agnostic AI software engineering standards by @darkrei08 (upstream fork of micio86dev/Engineering-Excellence).
• Matt Pocock's Skills: Agent workflows for triage, spec decomposition, bug diagnosis, architecture design, and grilling by Matt Pocock (@mattpocock).
• Gentle AI: Harness discipline, Receipt-Driven Development (RDD), and review authority by Gentleman Programming.
• Gentle Engram: Durable project memory and cross-session learning persistence by Gentleman Programming.
• Gentleman Guardian Angel: Provider-agnostic pre-commit and pre-PR quality gate by Gentleman Programming.
• Herdr: Terminal multiplexer and workspace coordinator designed for AI coding agents.
• Serena: Language-server backed semantic navigation engine for AI agents by Oraios.
• graphifyy: Graph-based code analysis and AST dependency extraction.
• LLMLingua: Prompt compression and token reduction framework by Microsoft.
• RTK: Terminal output filter and token reducer for AI agent command execution.
• sqz: Token compression for CLI output and file reads by Ojus Chugh.
• Wizard-AI: Guided setup manager and adapter tooling by @darkrei08.

License

This project is licensed under the MIT License.