{"_id":"@baryonlabs/pi-agent-harness","_rev":"2-d0477b97876094055869f41a1ff70272","name":"@baryonlabs/pi-agent-harness","dist-tags":{"latest":"2.1.0"},"versions":{"2.0.0":{"name":"@baryonlabs/pi-agent-harness","version":"2.0.0","keywords":["pi-package","pi","pi-coding-agent","pi-agent","pi-plugin","harness","harness-factory","team-architecture-factory","agent-team","subagent","skill-architect","meta-skill","orchestration","agent-scaffolding","multi-agent","agent-skills","pipeline","fan-out-fan-in","expert-pool","producer-reviewer","supervisor","hierarchical-delegation"],"author":{"url":"https://github.com/revfactory","name":"robin"},"license":"Apache-2.0","_id":"@baryonlabs/pi-agent-harness@2.0.0","maintainers":[{"name":"chan3785","email":"chanho3785@gmail.com"},{"name":"martinhong","email":"hongbuzz@gmail.com"}],"homepage":"https://github.com/baryonlabs/pi-agent-harness","bugs":{"url":"https://github.com/baryonlabs/pi-agent-harness/issues"},"pi":{"image":"https://raw.githubusercontent.com/baryonlabs/pi-agent-harness/main/harness_social.png","skills":["./skills"],"extensions":["./extensions/subagent/index.ts"]},"dist":{"shasum":"01ee23cd2609609fae5588fbbebe0b8e7dd2e025","tarball":"https://registry.npmjs.org/@baryonlabs/pi-agent-harness/-/pi-agent-harness-2.0.0.tgz","fileCount":16,"integrity":"sha512-1hVVHI+V1IoAWzsx2EsvjydiXEWrjwyNN5sTTHmwkygChHZXbZDbgA+I6EPzH12GpidX73sLd+kRp47lOxKJuQ==","signatures":[{"sig":"MEUCIGcK0LFXja0PK+bmQL0gBWBRnhwQ1SH7W/XGi6LffY/TAiEAgwCy4mTa2I+4l+hLp0sJNVupnz4YKLPOvIlUROrO40o=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":212683},"gitHead":"e65e5e832df41f6ad3629dbe83aa9176334af8bc","_npmUser":{"name":"martinhong","email":"hongbuzz@gmail.com"},"repository":{"url":"git+https://github.com/baryonlabs/pi-agent-harness.git","type":"git"},"_npmVersion":"11.4.2","description":"Team-architecture factory for the pi coding agent — turns one domain sentence into a multi-agent team: specialist agents (.pi/agents), their skills (.pi/skills), and orchestration prompts (.pi/prompts), with six team patterns and a bundled subagent (singl","directories":{},"_nodeVersion":"24.4.0","publishConfig":{"access":"public"},"_hasShrinkwrap":false,"peerDependencies":{"typebox":"*","@earendil-works/pi-ai":"*","@earendil-works/pi-tui":"*","@earendil-works/pi-agent-core":"*","@earendil-works/pi-coding-agent":"*"},"_npmOperationalInternal":{"tmp":"tmp/pi-agent-harness_2.0.0_1782912289753_0.332696427268357","host":"s3://npm-registry-packages-npm-production"}},"2.1.0":{"name":"@baryonlabs/pi-agent-harness","version":"2.1.0","publishConfig":{"access":"public"},"description":"Team-architecture factory for the pi coding agent — turns one domain sentence into a multi-agent team: specialist agents (.pi/agents), their skills (.pi/skills), and orchestration prompts (.pi/prompts), with six team patterns and a bundled subagent (singl","author":{"name":"robin","url":"https://github.com/revfactory"},"homepage":"https://github.com/baryonlabs/pi-agent-harness","repository":{"type":"git","url":"git+https://github.com/baryonlabs/pi-agent-harness.git"},"bugs":{"url":"https://github.com/baryonlabs/pi-agent-harness/issues"},"license":"Apache-2.0","keywords":["pi-package","pi","pi-coding-agent","pi-agent","pi-plugin","harness","harness-factory","team-architecture-factory","agent-team","subagent","skill-architect","meta-skill","orchestration","agent-scaffolding","multi-agent","agent-skills","pipeline","fan-out-fan-in","expert-pool","producer-reviewer","supervisor","hierarchical-delegation"],"pi":{"extensions":["./extensions/subagent/index.ts"],"skills":["./skills"],"image":"https://raw.githubusercontent.com/baryonlabs/pi-agent-harness/main/harness_social.png"},"peerDependencies":{"@earendil-works/pi-ai":"*","@earendil-works/pi-agent-core":"*","@earendil-works/pi-coding-agent":"*","@earendil-works/pi-tui":"*","typebox":"*"},"_id":"@baryonlabs/pi-agent-harness@2.1.0","gitHead":"0159bbb5f8142e095ea95835e4f347124a228f80","_nodeVersion":"24.4.0","_npmVersion":"11.4.2","dist":{"integrity":"sha512-7ObmS7Stb30hFcARFvDs496MMtK3jguOuv0oA35dMQwJdlEvOKg0sdZr9kGfk5Q0ezIAO82m9j9UcQFC8SnhHQ==","shasum":"30d57155cccfd2c6d7f710ca7bf71abb210e7616","tarball":"https://registry.npmjs.org/@baryonlabs/pi-agent-harness/-/pi-agent-harness-2.1.0.tgz","fileCount":16,"unpackedSize":220301,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEQCIAVLjOc3CR7l+vqNwcfCoeqFn9xQR9ku5PrNxwzO2jvEAiAs4gpJi+mBYADOYRL/EGSwR/TEkF5m9VVVzFUVQ8hQmg=="}]},"_npmUser":{"name":"martinhong","email":"hongbuzz@gmail.com"},"directories":{},"maintainers":[{"name":"chan3785","email":"chanho3785@gmail.com"},{"name":"martinhong","email":"hongbuzz@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/pi-agent-harness_2.1.0_1782912763413_0.004387413218750247"},"_hasShrinkwrap":false}},"time":{"created":"2026-07-01T13:24:49.613Z","modified":"2026-07-01T13:32:43.801Z","2.0.0":"2026-07-01T13:24:49.898Z","2.1.0":"2026-07-01T13:32:43.654Z"},"bugs":{"url":"https://github.com/baryonlabs/pi-agent-harness/issues"},"author":{"name":"robin","url":"https://github.com/revfactory"},"license":"Apache-2.0","homepage":"https://github.com/baryonlabs/pi-agent-harness","keywords":["pi-package","pi","pi-coding-agent","pi-agent","pi-plugin","harness","harness-factory","team-architecture-factory","agent-team","subagent","skill-architect","meta-skill","orchestration","agent-scaffolding","multi-agent","agent-skills","pipeline","fan-out-fan-in","expert-pool","producer-reviewer","supervisor","hierarchical-delegation"],"repository":{"type":"git","url":"git+https://github.com/baryonlabs/pi-agent-harness.git"},"description":"Team-architecture factory for the pi coding agent — turns one domain sentence into a multi-agent team: specialist agents (.pi/agents), their skills (.pi/skills), and orchestration prompts (.pi/prompts), with six team patterns and a bundled subagent (singl","maintainers":[{"name":"chan3785","email":"chanho3785@gmail.com"},{"name":"martinhong","email":"hongbuzz@gmail.com"}],"readme":"
\n \n
\n\n
\n \n \n \n \n \n \n
\n\n
\n \n \n \n
\n\n# pi-agent-harness — The Team-Architecture Factory for pi\n\n**English** | [한국어](README_KO.md) | [日本語](README_JA.md)\n\n> **pi-agent-harness is a team-architecture factory for [pi](https://github.com/earendil-works/pi), the minimal terminal coding agent.** Say **\"build a harness for this project\"** (English) or **\"하네스 구성해줘\"** (한국어) or **\"ハーネスを構成して\"** (日本語), and it turns your domain description into pi agent definitions, the skills they use, and the orchestration prompts that drive them — picked from six pre-defined team-architecture patterns.\n\n> **Ported from Claude Code.** This package is a pi-only port of the original [Harness](https://github.com/revfactory/harness) (a Claude Code plugin). It maps the same factory onto pi's primitives — `.pi/agents/`, `.pi/skills/`, `.pi/prompts/`, and the bundled `subagent` extension — because pi deliberately ships **no built-in subagents, no MCP, no plan mode, no todos**.\n\n## Overview\n\npi is intentionally minimal: it gives the model four tools (`read`, `write`, `edit`, `bash`) and everything else is added via skills, prompt templates, extensions, and packages. This harness leverages that extensibility to decompose complex tasks into coordinated specialist agents. Say \"build a harness for this project\" and it generates:\n\n- **Agent definitions** (`.pi/agents/*.md`) — specialist personas with `tools`/`model` frontmatter; each runs in an isolated `pi` process\n- **Skills** (`.pi/skills/*/SKILL.md`) — Agent Skills standard procedural knowledge\n- **Orchestration prompts** (`.pi/prompts/*.md`) — `/commands` that drive the `subagent` tool in `single` / `parallel` / `chain` modes\n\nThe bundled **`subagent` extension** (`extensions/subagent/`) supplies the delegation tool pi lacks natively, so generated harnesses run out of the box.\n\n## Category — Where Harness Sits\n\nHarness lives at the **L3 Meta-Factory** layer — the layer that generates other harnesses rather than being one. Inside L3, we pick a specific sub-layer: **Team-Architecture Factory**. This package targets the **pi runtime**.\n\n| Layer | What it does | Neighbors |\n|-------|--------------|-----------|\n| **L3 — Meta-Factory / Team-Architecture Factory** (us) | Domain sentence → pi agent team + skills + orchestration prompts, via 6 team patterns | — |\n| L3 — Meta-Factory / Runtime-Configuration Factory | Deterministic, repeatable runtime configurations | [coleam00/Archon](https://github.com/coleam00/Archon) |\n| L3 — Meta-Factory / Claude Code original | Same concept, Claude Code runtime | [revfactory/harness](https://github.com/revfactory/harness) |\n| L2 — Cross-Harness Workflow | Standardize skills/rules/hooks across harnesses | [affaan-m/ECC](https://github.com/affaan-m/everything-claude-code) |\n\n## Key Features\n\n- **Agent Design** — 6 architectural patterns: Pipeline, Fan-out/Fan-in, Expert Pool, Producer-Reviewer, Supervisor, and Hierarchical Delegation — mapped to pi's `single`/`parallel`/`chain` delegation modes\n- **Skill Generation** — Auto-generates Agent-Skills-standard skills with Progressive Disclosure for efficient context management\n- **Orchestration** — `subagent`-tool prompts with `{previous}` chaining, `_workspace/` file handoff, and error handling\n- **Model Tiering** — Per-agent model selection (`claude-haiku-4-5` for recon, `claude-sonnet-4-5` for work, `claude-opus-4-7` for hard reasoning)\n- **Validation** — Trigger verification, dry-run testing, and with-skill vs without-skill comparison via the `subagent` tool\n\n## Why this vs other pi harnesses\n\nThe pi.dev gallery has 40+ \"harness\" packages. Most are **single-agent guardrail/workflow tools for software coding only**. pi-agent-harness is positioned differently (full landscape in [`docs/competitive-analysis.md`](docs/competitive-analysis.md)):\n\n- **Zero companion dependencies.** Multi-agent harnesses like `skynex-pi` require 4 extra packages to install alongside. We **bundle** the `subagent` delegation tool — `pi install` and go.\n- **Domain-agnostic, not code-only.** Every direct competitor targets software engineering. This factory builds teams for **any** domain — research, novels, webtoons, marketing, *and* code.\n- **A team-architecture factory, not a profile manager.** vs `pi-harness-factory` (single-agent modes) and governance-only harnesses: we *decompose a domain into a coordinated team* with 6 named patterns.\n- **Lean surface.** vs `ultimate-pi`'s 20+ commands: one orchestration prompt per domain, generated to fit.\n\nWe also **adopt** what works across the ecosystem: complexity triage (scale process to task size), a structured inter-agent handoff schema, run manifests (artifacts-as-truth), a verification gate + bounded repair loop, HITL checkpoints, and no-auto-commit governance.\n\n## Workflow\n\n```\nPhase 1: Domain Analysis\n ↓\nPhase 2: Architecture Design (single / parallel / chain delegation)\n ↓\nPhase 3: Agent Definition Generation (.pi/agents/)\n ↓\nPhase 4: Skill Generation (.pi/skills/)\n ↓\nPhase 5: Orchestration Prompts (.pi/prompts/) + AGENTS.md pointer\n ↓\nPhase 6: Validation & Testing\n ↓\nPhase 7: Harness Evolution (feedback-driven)\n```\n\n## Installation\n\nInstall as a pi package (the bundled `subagent` extension and the `harness` skill load automatically):\n\n```bash\n# From npm (pi.dev gallery)\npi install npm:@baryonlabs/pi-agent-harness\n\n# Or from git\npi install git:github.com/baryonlabs/pi-agent-harness\n\n# Or a local checkout\npi install /absolute/path/to/pi-agent-harness\n\n# Project-local install (shareable with your team via .pi/settings.json)\npi install -l npm:@baryonlabs/pi-agent-harness\n```\n\nTry it without installing:\n\n```bash\npi -e /absolute/path/to/pi-agent-harness\n```\n\nThen, inside pi, trigger it:\n\n```\n하네스 구성해줘\nBuild a harness for this project\n```\n\n## Package Structure\n\n```\npi-agent-harness/\n├── package.json # pi manifest (extensions + skills)\n├── extensions/\n│ └── subagent/ # Bundled delegation tool (single/parallel/chain)\n│ ├── index.ts\n│ ├── agents.ts\n│ └── README.md\n├── skills/\n│ └── harness/\n│ ├── SKILL.md # Main skill (7-Phase workflow)\n│ └── references/\n│ ├── agent-design-patterns.md # 6 patterns + Claude→pi mapping\n│ ├── orchestrator-template.md # Orchestration prompt templates\n│ ├── team-examples.md # 5 real-world configurations\n│ ├── skill-writing-guide.md # Skill authoring guide\n│ ├── skill-testing-guide.md # Testing & evaluation methodology\n│ └── qa-agent-guide.md # QA agent integration guide\n└── README.md\n```\n\n## Usage\n\n### Delegation Modes\n\npi has no built-in agent teams or live messaging. Collaboration is implemented by the main agent delegating via the bundled `subagent` tool and exchanging results through `_workspace/` files. The orchestration prompt must pass `agentScope: \"both\"` so project-level `.pi/agents/` are discovered.\n\n| Mode | Tool params | Use for |\n|------|-------------|---------|\n| **single** | `{ agent, task }` | One-off isolated task, expert-pool selection |\n| **parallel** | `{ tasks: [...] }` (≤8, 4 concurrent) | Fan-out/fan-in independent work; main integrates |\n| **chain** | `{ chain: [...] }` with `{previous}` | Sequential pipeline, producer-reviewer loops |\n\n
\n \n
\n\n### Architecture Patterns → pi modes\n\n| Pattern | pi mapping |\n|---------|------------|\n| Pipeline | `chain` |\n| Fan-out/Fan-in | `parallel` → main integrates |\n| Expert Pool | `single` (selective) |\n| Producer-Reviewer | `chain` (worker → reviewer → worker) |\n| Supervisor | main agent's dynamic `parallel` loop |\n| Hierarchical Delegation | 2-level delegation |\n\n## Output\n\nFiles generated by Harness in your project:\n\n```\nyour-project/\n├── .pi/\n│ ├── agents/ # Agent definitions (name, description, tools, model)\n│ │ ├── analyst.md\n│ │ ├── builder.md\n│ │ └── qa-inspector.md\n│ ├── skills/ # Skill files\n│ │ ├── analyze/\n│ │ │ └── SKILL.md\n│ │ └── build/\n│ │ ├── SKILL.md\n│ │ └── references/\n│ └── prompts/ # Orchestration prompts (/commands)\n│ └── build-feature.md\n└── AGENTS.md # Harness pointer (trigger rule + change log)\n```\n\n## Use Cases — Try These Prompts\n\nAfter installing, trigger any of these inside pi:\n\n**Deep Research** — `Build a harness for deep research: parallel agents investigating a topic from official, media, and community angles, then the main agent cross-validates and writes a report.`\n\n**Website Development** — `Build a harness for full-stack website development as a chain: design → frontend (React/Next.js) → backend API → QA testing.`\n\n**Code Review** — `Build a harness for comprehensive code review: parallel agents checking architecture, security, and performance, then merged into a single report.`\n\n**Webtoon Production** — `Build a harness for webtoon episodes: a producer-reviewer chain where an artist agent generates panels and a reviewer agent enforces style consistency.`\n\n**Marketing Campaign** — `Build a harness for marketing campaigns: research the market, write ad copy, design visual concepts, and plan A/B tests with iterative review.`\n\n## Requirements\n\n- [pi coding agent](https://github.com/earendil-works/pi) installed (`npm install -g --ignore-scripts @earendil-works/pi-coding-agent`)\n- A model provider authenticated in pi (`/login` or an API key such as `ANTHROPIC_API_KEY`)\n- The bundled `subagent` extension (installed automatically with this package) — no extra setup\n\n> **Security note:** the `subagent` tool runs project-local agents (`.pi/agents/*.md`) only when invoked with `agentScope: \"both\"`/`\"project\"`, and prompts for confirmation in interactive mode. Only enable for repositories you trust. See `extensions/subagent/README.md`.\n\n## Built with Harness (Claude Code original)\n\nThe original Claude Code harness was validated in a controlled A/B study and shipped a large catalog. Those artifacts target Claude Code; the methodology carries over to this pi port.\n\n- **[revfactory/harness-100](https://github.com/revfactory/harness-100)** — 100 production-ready agent team harnesses across 10 domains (EN + KO).\n- **[revfactory/claude-code-harness](https://github.com/revfactory/claude-code-harness)** — A/B experiment (n=15): +60% avg quality (49.5 → 79.3), 15/15 win-rate, −32% variance (author-measured, third-party replications pending).\n\n> Full paper: *Hwang, M. (2026). Harness: Structured Pre-Configuration for Enhancing LLM Code Agent Output Quality.*\n\n## FAQ\n\n\nQ1. How is this different from the original Harness?\n\n**A.** Same factory, different runtime. The original [revfactory/harness](https://github.com/revfactory/harness) is a Claude Code plugin that generates `.claude/agents/` + `.claude/skills/` and relies on Claude Code's native agent teams (`TeamCreate`/`SendMessage`/`TaskCreate`). This package is a **pi-only port**: it generates `.pi/agents/` + `.pi/skills/` + `.pi/prompts/` and implements collaboration through the bundled `subagent` extension (`single`/`parallel`/`chain`) plus `_workspace/` file handoff, because pi has no built-in subagents or live team messaging.\n\n\n\nQ2. pi has no subagents — how do agent teams work?\n\n**A.** This package bundles a `subagent` extension that spawns a separate `pi` process per delegation, each with an isolated context window. The main agent acts as coordinator: it fans out with `parallel`, chains dependent steps with `chain` (passing `{previous}`), and integrates results itself (pi has no team-consensus channel). See `skills/harness/references/agent-design-patterns.md` for the full Claude→pi mapping.\n\n\n\nQ3. Can I reuse my existing Claude Code skills?\n\n**A.** Yes. pi can load skills from other harnesses by adding their directories to `settings.json` (e.g. `\"skills\": [\"~/.claude/skills\"]`). Agent Skills standard SKILL.md files are largely portable between Claude Code and pi.\n\n\n\nQ4. How is this different from pi-harness-factory?\n\n**A.** They solve different problems and are complementary.\n\n- **[`pi-harness-factory`](https://github.com/kswift1/pi-harness-factory)** is a **single-agent profile manager**: it defines \"working modes\" (presets like `tdd`, `safe-coder`, `code-reviewer`, `researcher`) that constrain *one* agent's tool access, mutation scope, validation strictness, and safety gates. It answers **\"what is this one agent allowed to do, and how strict should it be?\"** — a *runtime-configuration* factory (guardrails).\n- **`pi-agent-harness`** (this project) is a **multi-agent team factory**: from one domain sentence it generates a *team* of specialist agents (`.pi/agents/`), their skills (`.pi/skills/`), and orchestration prompts (`.pi/prompts/`) that fan out and chain work via the bundled `subagent` tool. It answers **\"how do I decompose this domain into a coordinated team of agents?\"** — a *team-architecture* factory.\n\n| | `pi-harness-factory` | `pi-agent-harness` (this) |\n|---|---|---|\n| Unit of work | One agent, many modes | Many agents, one team |\n| Produces | JSON profiles (`.pi/harness-factory/`) | Agents + skills + orchestration prompts (`.pi/`) |\n| Focus | Guardrails / constraints | Decomposition / orchestration |\n| Layer | Runtime-configuration factory | Team-architecture factory |\n\nYou can use both: constrain each generated agent with `pi-harness-factory` modes while `pi-agent-harness` designs and orchestrates the team.\n\n\n## License\n\nApache 2.0\n","readmeFilename":"README.md"}
![\"Harness](\"harness_banner.png\")
\n![\"Version\"](\"https://img.shields.io/badge/Version-2.1.0-brightgreen.svg\"){kind=icon}
\n ![\"License\"](\"https://img.shields.io/badge/License-Apache_2.0-blue.svg\"){kind=icon}
\n ![\"pi](\"https://img.shields.io/badge/pi-Package-purple.svg\"){kind=icon}
\n ![\"6](\"https://img.shields.io/badge/Patterns-6_Architectures-orange.svg\"){kind=icon}
\n ![\"Delegation](\"https://img.shields.io/badge/Modes-single%20%7C%20parallel%20%7C%20chain-green.svg\"){kind=icon}
\n ![\"GitHub](\"https://img.shields.io/github/stars/revfactory/harness?style=social\")
![\"Layer\"](\"https://img.shields.io/badge/Layer-L3%20Meta--Factory-orange\"){kind=icon}
![\"Sub-layer\"](\"https://img.shields.io/badge/Sub--layer-Team--Architecture%20Factory-teal\"){kind=icon}
![\"i18n\"](\"https://img.shields.io/badge/README-EN%20%7C%20KO%20%7C%20JA-lightgrey\"){kind=icon}
![\"Harness](\"harness_team.png\")
\n