# Implementation Plan: 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`
- `tickets/artifacts/2026-06-03-robust-pi-subagents/04-structure.md`

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

## Overview

Create a project-local Nimrod subagent extension based on Pi's example, plus QRSPI role agents that can run in isolated Pi subprocesses and write artifacts directly.

## Phase 1: Install/adapt subagent extension shell

### Changes

#### 1. Copy extension runner

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

**Action:** create

Details:
- Copy from Pi example subagent extension.
- Keep subprocess JSON-mode architecture.
- Keep single/parallel/chain modes.
- Keep usage tracking, abort handling, and TUI rendering.

#### 2. Adapt Nimrod defaults

**File:** `.pi/extensions/nimrod-subagents/index.ts`
**Action:** modify copied file

Details:
- Rename tool from `subagent` to `nimrod_subagent`.
- Update label to `Nimrod Subagent`.
- Default `agentScope` to `project` in schema description and runtime.
- Default `confirmProjectAgents` to `false` in schema description and runtime.
- Update tool description to say it uses project-local Nimrod agents by default.

#### 3. Add extension README

**File:** `.pi/extensions/nimrod-subagents/README.md`
**Action:** create

Details:
- Explain source fork.
- Explain usage.
- Explain safety and rollback.
- Note `/reload` requirement.

### Verification

Automated:
- [x] `test -f .pi/extensions/nimrod-subagents/index.ts`
- [x] `test -f .pi/extensions/nimrod-subagents/agents.ts`
- [x] `grep -q 'nimrod_subagent' .pi/extensions/nimrod-subagents/index.ts`
- [x] `grep -q 'params.agentScope ?? "project"' .pi/extensions/nimrod-subagents/index.ts`
- [x] `grep -q 'params.confirmProjectAgents ?? false' .pi/extensions/nimrod-subagents/index.ts`

Manual:
- [ ] After `/reload`, `nimrod_subagent` is available as an LLM tool.

### Rollback

- Delete `.pi/extensions/nimrod-subagents/`.

---

## Phase 2: Add Nimrod QRSPI role agents

### Changes

#### 1. Create project agent directory

**File:** `.pi/agents/`
**Action:** create directory

#### 2. Create role agents

**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`

**Action:** create

Details:
- Include frontmatter: `name`, `description`, `tools`.
- Do not pin model initially.
- Give each role strict phase boundaries.
- Allow artifact-writing agents to write only specified artifact paths unless implementer is explicitly assigned code changes.
- Include git workflow requirements for implementer/reviewer.

### Verification

Automated:
- [x] `for f in .pi/agents/nimrod-*.md; do grep -q '^name:' "$f" && grep -q '^description:' "$f" && grep -q '^tools:' "$f"; done`
- [x] `test $(find .pi/agents -maxdepth 1 -name 'nimrod-*.md' | wc -l) -eq 9`

Manual:
- [ ] After `/reload`, `nimrod_subagent` lists or can run project agents.

### Rollback

- Delete `.pi/agents/nimrod-*.md`.

---

## Phase 3: Document workflow and usage

### Changes

#### 1. Update QRSPI adaptation docs

**File:** `docs/qrspi-adaptation.md`
**Action:** modify

Details:
- Replace future-tense roadmap with current robust-subagent MVP note.
- Document `nimrod_subagent` as standard for context-heavy Nimrod work.

#### 2. Update AGENTS durable instructions

**File:** `AGENTS.md`
**Action:** modify

Details:
- Add explicit note that robust subagent isolation is now project-local standard when available.
- Mention `.pi/extensions/nimrod-subagents/` and `.pi/agents/`.

### Verification

Automated:
- [x] `grep -q 'nimrod_subagent' docs/qrspi-adaptation.md`
- [x] `grep -q 'nimrod-subagents' AGENTS.md`

Manual:
- [ ] User can find usage instructions in docs.

### Rollback

- Revert the doc edits.

---

## Phase 4: Review and closeout

### Changes

#### 1. Update this plan

**File:** `tickets/artifacts/2026-06-03-robust-pi-subagents/05-plan.md`
**Action:** modify

Details:
- Check automated verification items that passed.
- Leave manual `/reload` checks unchecked until user confirms.

#### 2. Write review artifact

**File:** `tickets/artifacts/2026-06-03-robust-pi-subagents/06-review.md`
**Action:** create

Details:
- Summarize files changed.
- Include verification commands and outputs.
- Include rollback notes.

### Verification

Automated:
- [x] `git diff --stat` shows expected scoped files.
- [x] `find .pi/extensions/nimrod-subagents .pi/agents -type f | sort` lists expected files.

Manual:
- [ ] User reloads Pi and confirms `nimrod_subagent` can run a simple `nimrod-locator` task.

### Rollback

- Delete `.pi/extensions/nimrod-subagents/` and `.pi/agents/nimrod-*.md`; revert doc/ticket artifact edits.