# Structure: Robust Pi subagent workflow for Nimrod

## Phase Contract

Allowed reads:
- `tickets/artifacts/2026-06-03-robust-pi-subagents/02-research.md`
- `tickets/artifacts/2026-06-03-robust-pi-subagents/03-design.md`

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

## Approach

Fork Pi's example subagent extension into a Nimrod project-local extension, then add project-local QRSPI role agents that can run in isolated child Pi processes and write artifacts directly.

## Phase 1: Install/adapt subagent extension shell

Deliver a project-local extension that registers a Nimrod-specific subagent tool.

**Files:**
- `.pi/extensions/nimrod-subagents/index.ts`
- `.pi/extensions/nimrod-subagents/agents.ts`
- `.pi/extensions/nimrod-subagents/README.md`

**Key changes:**
- Copy Pi example subprocess runner.
- Rename registered tool from `subagent` to `nimrod_subagent`.
- Default `agentScope` to `project`.
- Default `confirmProjectAgents` to `false`.
- Document source and local safety model.

**Verify:**
- Automated: TypeScript parse/import shape check where possible.
- Manual: After `/reload`, tool should appear as `nimrod_subagent`.

## Phase 2: Add Nimrod QRSPI role agents

Deliver project-local agent prompt definitions for all QRSPI roles.

**Files:**
- `.pi/agents/nimrod-locator.md`
- `.pi/agents/nimrod-researcher.md`
- `.pi/agents/nimrod-analyzer.md`
- `.pi/agents/nimrod-pattern-finder.md`
- `.pi/agents/nimrod-designer.md`
- `.pi/agents/nimrod-structurer.md`
- `.pi/agents/nimrod-planner.md`
- `.pi/agents/nimrod-implementer.md`
- `.pi/agents/nimrod-reviewer.md`

**Key changes:**
- Each agent has frontmatter with name, description, and tool list.
- Research/planning agents can write artifacts when assigned a path.
- Implementer can edit/write code/docs but must follow plan and git workflow.
- Reviewer uses read-only inspection commands where possible.

**Verify:**
- Automated: All agent files contain required frontmatter.
- Manual: `nimrod_subagent` can discover project agents after reload.

## Phase 3: Document workflow and usage

Make the new subagent workflow discoverable and durable.

**Files:**
- `docs/qrspi-adaptation.md`
- `AGENTS.md`
- `.pi/extensions/nimrod-subagents/README.md`

**Key changes:**
- Reference `nimrod_subagent` as the standard robust subagent mechanism.
- Explain git rollback mitigation.
- Explain when to use direct parent work vs subagent delegation.

**Verify:**
- Automated: Markdown files exist and contain expected references.
- Manual: User can understand how to invoke subagents.

## Phase 4: Review and closeout

Capture what changed and how to roll back.

**Files:**
- `tickets/artifacts/2026-06-03-robust-pi-subagents/05-plan.md`
- `tickets/artifacts/2026-06-03-robust-pi-subagents/06-review.md`
- `tickets/active/2026-06-03-robust-pi-subagents.md`

**Key changes:**
- Check off completed plan items.
- Record verification output.
- Update ticket status or next actions.

**Verify:**
- Automated: `git diff --stat` shows expected scoped files.
- Manual: User can run `/reload` and test `nimrod_subagent`.

## Testing Checkpoints

- After Phase 1: project-local extension files exist and contain Nimrod defaults.
- After Phase 2: all QRSPI role agents exist and can be discovered by the copied discovery logic.
- After Phase 3: docs point to the robust subagent path.
- After Phase 4: review artifact captures verification and rollback.