@gonrocca/devteam-pi

Installable pi package that ships a development team of role-based subagents plus one orchestrator command that triages any task and routes it through the relevant roles.

---

devteam-pi is a pi (pi.dev) package that deploys a complete development team as composable subagents. Each role is a plain .md file with its own model, thinking level, and tool allowlist. A single /devteam command reads your task, asks a triage role to figure out which teammates to involve, and executes the plan — in parallel where roles work independently, in worktrees where they write to overlapping trees, serial where there is real dependency.

This is the team layer of the zero family of pi packages. See Integration with zero-pi below for how to compose /devteam with /forge.

📦 Install

pi install npm:@gonrocca/devteam-pi
pi install npm:pi-subagents      # required — devteam delegates to sub-agents

Needs Node ≥ 20.6.0. Restart pi after an install or upgrade.

🛠 /devteam — the orchestrator

Type /devteam <task> and the dispatcher routes the work through the team.

/devteam "Add a /health endpoint to the API and ship a smoke test for it"
/devteam --continue           # resume an unfinished run (picker if multiple)
/devteam --continue my-slug   # resume a specific slug

Internally:

1. Triage. The orchestrator hands your task plus the live role catalog to devteam.dispatcher. The dispatcher returns one JSON routing plan (validated against a strict schema). On invalid output the orchestrator retries once, then falls back to a hardcoded recon → implement → review plan.
2. Execute. The plan walks in topological order. Each step is one subagent(...) call: single-agent, parallel fanout, or parallel-with-worktrees, with dependency outputs spliced into downstream task briefs.
3. Synthesize. A code-composed Spanish envelope (Estado: / Resumen: / Artefactos: / Siguiente:) lands in .devteam/<slug>/synthesis.md and is shown to you via ctx.ui.notify.

Artifacts live under .devteam/<slug>/:

.devteam/<slug>/
├── plan.json                  validated routing plan
├── <step>.md                  single-agent step output
├── <step>.<agent>.md          per-agent output for parallel steps
├── <step>.error.md            only when the step failed
└── synthesis.md               the final Spanish envelope

--continue reads plan.json, identifies which steps already have output files, and resumes at the first incomplete step. The artifacts are the durable state — there is no separate run file.

👥 Roles shipped

Role	Purpose	Tools
dispatcher	Reads the task + the catalog and returns one routing JSON plan. Never executes steps.	read, grep, find, ls
architect	Read-only recon: maps modules, conventions, integration points, risks.	read, grep, find, ls, bash
backend	Server-side, API, data layer, integrations. Test-first where practical.	read, grep, find, ls, bash, edit, write
frontend	UI, client state, styling, browser-side logic.	read, grep, find, ls, bash, edit, write
qa	Adversarial test/quality review — runs tests, exercises behavior end-to-end. Read-only.	read, grep, find, ls, bash
reviewer	Adversarial code review — correctness, regressions, simplicity. Read-only.	read, grep, find, ls, bash
devops	Build, CI, packaging, deployment, IaC.	read, grep, find, ls, bash, edit, write

qa and reviewer deliberately exclude edit/write (a departure from pi-subagents' builtin reviewer). The pattern is review-only fanout: a separate implementer applies any fixes worth doing now. See reviewer.md's body for the full rationale.

⌨️ Commands

/devteam <task> and /devteam --continue [<slug>]

The orchestrator. See /devteam — the orchestrator above.

/devteam-models — per-role configuration

/devteam-models                                    # interactive picker
/devteam-models <role>=<model>                     # set model only
/devteam-models <role>=<provider>/<model>          # set provider + model
/devteam-models <role>=thinking:<level>            # off|low|medium|high|xhigh
/devteam-models <role>=enabled:<true|false>        # enable/disable a role

The interactive picker is a boxed-window TUI calcado de /zero-models. It discovers the live role list dynamically (no hardcoded names) so any role you add via the customization mechanic below shows up automatically.

🧩 Customization

Every role is a plain pi-subagents .md file with package: devteam in its frontmatter. To override a shipped role or add a new one, drop a .md file into the user or project scope:

• User scope (applies everywhere): ~/.pi/agent/agents/devteam/<role>.md
• Project scope (this repo only): <repo>/.pi/agents/devteam/<role>.md

Precedence follows pi-subagents' standard rule: project > user > package.

Example — a data-engineer role

Create ~/.pi/agent/agents/devteam/data-engineer.md:

---
name: data-engineer
description: Data pipelines, ETL, warehousing, dbt models, query performance.
package: devteam
systemPromptMode: replace
inheritProjectContext: true
inheritSkills: true
thinking: medium
tools: read, grep, find, ls, bash, edit, write
---

You are devteam-pi's data-engineer. You build and maintain data pipelines,
ETL/ELT jobs, warehouse models, and query performance work.

(... rest of the system prompt ...)

The next time you run /devteam, the dispatcher will see data-engineer in the role catalog and may route data-flavored tasks to it. The picker shows the new role under [user].

Note: an agent file shipped inside node_modules/<pkg>/agents/devteam/ is not discovered by pi-subagents directly — pi-subagents only scans the user/project scope dirs. devteam-pi handles this at install time: a devteam-agents.ts extension copies the bundled .md files into the user scope dir on every load, with per-role overrides from ~/.pi/devteam.json spliced into the frontmatter (model, thinking, disabled).

⚙️ Configuration — ~/.pi/devteam.json

Schema:

interface DevteamJson {
  version: string;                                 // "0.1.0"
  installedAt?: string;                            // ISO 8601
  models?: Record<string, string>;                 // role → model id
  providers?: Record<string, string>;              // role → provider id
  thinking?: Record<string, "off"|"low"|"medium"|"high"|"xhigh">;
  enabled?: Record<string, boolean>;               // default true when missing
}

Every map is sparse — missing entries fall back to the role's .md frontmatter defaults. Unknown top-level keys are preserved on write, so a future installer can store extra fields without /devteam-models clobbering them.

Next-session lag. /devteam-models writes devteam.json, but the provisioning extension (devteam-agents.ts) only reads it at extension load. A change takes effect on the next pi session — run /reload or restart pi to pick it up immediately.

⚡ Parallel patterns

The dispatcher tends to produce three shapes. You can also write plans by hand and pass them via direct subagent(...) calls; the runner accepts any plan that validates against the schema.

Review fanout (parallel, read-only)

{
  "steps": [
    {
      "name": "review",
      "agents": ["qa", "reviewer"],
      "parallel": true,
      "worktree": false,
      "context": "fresh",
      "depends_on": [],
      "task_brief": "Review the staged diff..."
    }
  ],
  "rationale": "two adversarial angles in parallel, no writes"
}

Implement with worktrees (parallel writes)

{
  "steps": [
    {
      "name": "build",
      "agents": ["backend", "frontend"],
      "parallel": true,
      "worktree": true,
      "context": "fork",
      "depends_on": [],
      "task_brief": "Backend: ship /api/health. Frontend: render status in <Header/>."
    }
  ],
  "rationale": "disjoint trees can be touched concurrently in worktrees"
}

Recon-then-implement (serial dependency)

{
  "steps": [
    {"name": "recon", "agents": ["architect"], "parallel": false, "worktree": false,
     "context": "fresh", "depends_on": [], "task_brief": "Map the affected modules..."},
    {"name": "implement", "agents": ["backend"], "parallel": false, "worktree": false,
     "context": "fork", "depends_on": ["recon"], "task_brief": "Implement using the recon findings."}
  ],
  "rationale": "constraints first, code second"
}

🔗 Integration with zero-pi (/forge)

devteam-pi composes cleanly with @gonrocca/zero-pi's spec-driven workflow. There is no code coupling — the integration is purely a documented composition pattern:

• During a /forge run, zero-build can fan out to devteam.qa + devteam.reviewer for adversarial review of its diff before reporting the build complete.
• zero-veredicto can consult the team (e.g., devteam.reviewer) before pronouncing its verdict.
• Symmetrically, /devteam can route an explicit "design + spec this feature" task to a flow that ends in /forge.

Neither package depends on or imports the other. They share pi-subagents as a common substrate; both expose their roles via package: <name> namespacing so devteam.reviewer and zero-veredicto never collide.

🛡️ Defensive defaults

• The devteam-agents.ts extension wraps every per-role read/write in try/catch; one malformed .md never blocks the other six.
• The dispatcher gets exactly one retry. After two invalid outputs the runner uses a deterministic fallback plan and emits a Spanish warning notification.
• Per-step failure is non-blocking for siblings: the failed step gets a <step>.error.md, its dependents are marked skipped, and the rest of the plan continues.
• runPipeline never throws — every failure path produces a synthesis envelope. The pi session keeps running.
• The picker shell catches transition bugs and closes cleanly via done({type: "quit"}). A render bug never wedges pi.

🧪 Development

git clone https://github.com/gonzalonicolasr/devteam-pi.git
cd devteam-pi
npm test   # node --test --experimental-strip-types

Dependency-free, no build step — pi loads the TypeScript extensions directly via jiti. Tests use node:test + node:assert/strict.

License

MIT © Gonzalo Rocca · github.com/gonzalonicolasr/devteam-pi