# Design: Robust Pi subagent workflow for Nimrod

## Phase Contract

Allowed reads:
- `tickets/active/2026-06-03-robust-pi-subagents.md`
- `tickets/artifacts/2026-06-03-robust-pi-subagents/00-context.md`
- `tickets/artifacts/2026-06-03-robust-pi-subagents/01-questions.md`
- `tickets/artifacts/2026-06-03-robust-pi-subagents/02-research.md`

Will write:
- `tickets/artifacts/2026-06-03-robust-pi-subagents/03-design.md`

## User Judgment Answers

1. MVP must be write-capable. Risks should be identified and mitigated, but this is currently low stakes.
2. Fork and adapt Pi's example subagent extension.
3. Do not ask for project-local agent confirmation in this trusted repo. Use git workflow and rollback discipline instead.
4. Subagents should write to artifacts.
5. Create all QRSPI-style agents and use subagents/emulated QRSPI while building the robust solution.

## Current State

- Nimrod has a documented QRSPI adaptation with phase artifacts and role boundaries in `docs/qrspi-adaptation.md`.
- Nimrod does not yet have true isolated subagents in project-local Pi configuration.
- Pi provides a working subagent extension example that spawns separate `pi --mode json -p --no-session` subprocesses with delegated prompts/tools and isolated context windows.
- Pi project-local extensions are discovered from `.pi/extensions/*.ts` and `.pi/extensions/*/index.ts`.
- Pi project-local agent definitions can live in `.pi/agents/*.md` and include frontmatter for `name`, `description`, `tools`, and optional `model`.

## Desired End State

Nimrod has a project-local subagent system that:

- Provides a `nimrod_subagent` tool adapted from Pi's example.
- Loads project-local agents from `.pi/agents/` by default.
- Does not prompt for project-local agent trust in this repository by default.
- Supports single, parallel, and chain execution.
- Allows agents to write/update QRSPI artifact files when instructed.
- Includes all core QRSPI-style agents:
  - `nimrod-locator`
  - `nimrod-researcher`
  - `nimrod-analyzer`
  - `nimrod-pattern-finder`
  - `nimrod-designer`
  - `nimrod-structurer`
  - `nimrod-planner`
  - `nimrod-implementer`
  - `nimrod-reviewer`
- Uses git workflow as the primary rollback/safety mechanism.

## Patterns / Constraints to Follow

- Fork/adapt the Pi example rather than building from scratch, because it already implements subprocess isolation, JSON parsing, streaming, usage tracking, abort handling, parallel/chain modes, and agent discovery.
- Keep the extension project-local under `.pi/extensions/nimrod-subagents/`.
- Keep agent prompts project-local under `.pi/agents/`.
- Keep QRSPI durable handoff artifacts under `tickets/artifacts/<ticket-id>/`.
- Each agent prompt must reinforce phase boundaries: do its own role, write bounded output, avoid doing downstream work early.
- Write-capable agents must be told to limit changes to the requested artifact or implementation scope.
- The parent assistant must check git status before substantive work and review diffs after changes.

## Design Decisions

1. **Extension base**: Fork Pi's example subagent extension into `.pi/extensions/nimrod-subagents/` — fastest path to robust isolation while allowing Nimrod defaults.
2. **Tool name**: Register the tool as `nimrod_subagent` instead of generic `subagent` — avoids collision with future global subagent extensions and signals project-specific behavior.
3. **Default agent scope**: Use project-local agents by default — Nimrod's agents are part of the repo and should travel with the workflow.
4. **Confirmation**: Disable project-agent confirmation by default — this repo is trusted and git rollback is preferred over repeated prompts.
5. **Write capability**: Include write/edit tools for agents that need artifact or code changes — risks mitigated by narrow prompts, artifact paths, git diff review, and rollback.
6. **MVP artifact writing**: Agents write artifact files directly when assigned a target path — this reduces parent-context load and makes outputs durable.
7. **Model selection**: Do not pin model names in MVP agent frontmatter — child sessions should use the configured/default Pi model unless a future need emerges.
8. **Implementation safety**: Because the worktree is already dirty from unrelated work, do not auto-commit now. Keep changes scoped and report exact files changed; commit later when repo state is cleaned or a dedicated branch/worktree is created.

## Not Doing

- Not modifying Pi internals.
- Not building a full SDK-based orchestrator yet.
- Not adding remote/infrastructure agent capabilities in this ticket.
- Not enforcing hard filesystem sandboxes in MVP.
- Not solving all QRSPI command UX in the first pass.

## Risks

- **Write-capable subagents can modify more than intended.** Mitigation: narrow prompts, role instructions, scoped plans, git status/diff review, and eventual branch/worktree use.
- **Project-local prompts are powerful.** Mitigation: prompts are repo-reviewed and version controlled.
- **Child Pi invocation/model config may not work until `/reload` or model defaults are available.** Mitigation: include a simple verification command and document reload requirement.
- **Extension copied from example may drift from upstream.** Mitigation: note source and keep fork minimal.
- **Main context can still grow if parent reads too much.** Mitigation: use `nimrod_subagent` for research/planning and have children write artifacts.

## Acceptance Criteria

- `.pi/extensions/nimrod-subagents/` exists and registers `nimrod_subagent`.
- `.pi/agents/` contains all listed Nimrod QRSPI role agents.
- Documentation explains usage and safety model.
- A basic syntax/load check passes where possible.
- The ticket artifacts document design, structure, plan, and review.