# Phase 5: Richer System Prompts — Specification

**Priority:** P4 · **Effort:** 0.5 days · **Dependencies:** None  
**Reference:** `claude-code-main/src/tools/AgentTool/built-in/planAgent.ts`, `exploreAgent.ts`, `generalPurposeAgent.ts`

---

## 1. Problem Statement

The current pi-subagents system prompts for the Explore and Plan agents are functional but significantly shorter and less prescriptive than their Claude Code equivalents. Specifically:

| Aspect | pi-subagents | Claude Code |
|---|---|---|
| General-purpose prompt | ~30 lines (generic) | ~60 lines (role + guidelines + output format) |
| Explore prompt | ~40 lines | ~80+ lines (search strategies, parallel calls, output format) |
| Plan prompt | ~50 lines | ~250+ lines (detailed planning process, output format, read-only warnings) |

Better prompts produce better agent output — more consistent, more thorough, and less likely to produce vague or incomplete results.

---

## 2. Design

### 2.1. Prompt Extraction

Extract all system prompts into individual files under `src/prompts/` for maintainability:

```
src/prompts/
├── general-purpose.ts
├── explore.ts
├── plan.ts
└── verification.ts   (from Phase 3)
```

### 2.2. General-Purpose Prompt Improvements

Additions:
- Clear role statement: "You are a general-purpose coding agent..."
- Shared guidelines section: search strategies, analysis approach, file creation discipline
- Output format guidance: concise reports covering what was done and key findings
- Note on tool usage: prefer specialized tools over bash equivalents

### 2.3. Explore Prompt Improvements

Additions:
- Search strategy guidance: "Search broadly → narrow down. Use multiple strategies if the first fails."
- Parallel tool calls: "Make independent tool calls in parallel for efficiency."
- Output format: "Use absolute file paths in all references."
- No-emoji rule: "Do not use emojis."
- Thoroughness: "Adapt search approach based on thoroughness level specified."

### 2.4. Plan Prompt Improvements

The Plan prompt gets the most significant expansion. Current additions:

- **Planning process**: Understand requirements → explore thoroughly → design solution → detail the plan
- **Read-only enforcement**: Expanded prohibited operations list with explicit examples
- **Output format**: "End with critical files list (3-5 files most important for implementation)"
- **Architectural decisions**: "Consider trade-offs and architectural decisions"
- **Dependencies**: "Identify dependencies and sequencing"
- **Challenges**: "Anticipate potential challenges"
- **Existing patterns**: "Follow existing patterns where appropriate"

---

## 3. API Changes

No API changes. Only prompt text files change. The `default-agents.ts` imports switch from inline strings to `src/prompts/` imports.

---

## 4. Testing Plan

| Test | What it verifies |
|---|---|
| Prompts load correctly | Imported text is non-empty string |
| PromptMode unchanged | Still "replace" for Explore/Plan, "append" for general-purpose |
| No regressions | Existing agent tests still pass |