123 lines
5.4 KiB
Markdown
123 lines
5.4 KiB
Markdown
---
|
|
name: chat-to-plan
|
|
description: Enrich a plan markdown with precise file locations, API signatures, and event firing conditions. Use when a plan has been discussed in chat and needs to be made implementation-ready, or when asked to "enrich a plan", "refine a plan", or "chat-to-plan".
|
|
---
|
|
|
|
# Chat-to-Plan Enrichment
|
|
|
|
Take a plan written in chat or a markdown file and enrich it with precise, verifiable details so a coding agent can execute it without guessing.
|
|
|
|
## When to Use
|
|
|
|
- A plan has been discussed in chat and needs to be written to markdown
|
|
- A markdown plan exists but lacks file locations, API signatures, or event details
|
|
- The user says "enrich this plan", "refine the plan", or "chat-to-plan <file>"
|
|
|
|
## Enrichment Checklist
|
|
|
|
For each phase/step in the plan, add the following where applicable:
|
|
|
|
### 1. File Locations
|
|
- **What to do:** Grep the source code to find the exact files that need modification.
|
|
- **How:** Use `grep`/`find`/`rg` to locate relevant code, imports, and type definitions.
|
|
- **Output:** A table or list of files with a brief note on what changes in each.
|
|
- **Example:**
|
|
```
|
|
| File | Change |
|
|
|------|--------|
|
|
| `src/turn-limit.ts` | Add command registration, widget updates, confirmation logic |
|
|
```
|
|
|
|
### 2. API Signatures
|
|
- **What to do:** Grep the pi-coding-agent type definitions for exact handler signatures.
|
|
- **How:** Search `~/.local/share/mise/installs/node/*/lib/node_modules/@mariozechner/pi-coding-agent/dist/core/extensions/types.d.ts` for relevant interfaces.
|
|
- **Key things to check:**
|
|
- `registerCommand` handler signature: `(args: string, ctx: ExtensionCommandContext) => Promise<void>`
|
|
- `registerShortcut` handler signature: `(ctx: ExtensionContext) => Promise<void> | void`
|
|
- `registerFlag` options shape
|
|
- `ui.confirm`, `ui.notify`, `ui.setWidget` signatures
|
|
- Event handler signatures: `(event: E, ctx: ExtensionContext) => Promise<R | void>`
|
|
- **Output:** Include the exact signature in the plan, not just a description.
|
|
- **Example:**
|
|
```
|
|
Handler signature: `async (args: string, ctx: ExtensionCommandContext) => Promise<void>`
|
|
- `args` is a single string (not array), use `args.trim().split(/\s+/)` for parsing
|
|
```
|
|
|
|
### 3. Event Firing Conditions
|
|
- **What to do:** Check when each event fires (fresh start, reload, compact, etc.).
|
|
- **How:** Search `agent-session.js` for `this._extensionRunner.emit({ type: "..."` to find event emission points.
|
|
- **Key mappings:**
|
|
- `session_start` with `reason: "startup"` — fresh session start
|
|
- `session_start` with `reason: "reload"` — session reload
|
|
- `agent_start` — agent begins a new turn (NOT on reload)
|
|
- `turn_start` — each agent turn begins
|
|
- `agent_end` — agent finishes a turn
|
|
- **Output:** Note when each event fires in the plan.
|
|
- **Example:**
|
|
```
|
|
Note: `session_start` fires on both startup (reason: "startup") and reload (reason: "reload").
|
|
`agent_start` only fires when the agent begins a turn, NOT on reload.
|
|
```
|
|
|
|
### 4. Required Imports
|
|
- **What to do:** Check what imports are needed for new APIs.
|
|
- **How:** Look at existing imports in the file and grep for new types/functions.
|
|
- **Output:** List any new imports needed.
|
|
- **Example:**
|
|
```
|
|
No new imports needed — `pi.registerCommand` is available on the `pi` object.
|
|
```
|
|
|
|
### 5. Type Definitions to Reference
|
|
- **What to do:** Note which type interfaces are relevant.
|
|
- **How:** List the exact interface names from the type definitions.
|
|
- **Output:** Link to the relevant types.
|
|
- **Example:**
|
|
```
|
|
Relevant types: `RegisteredCommand`, `ExtensionCommandContext`, `ExtensionContext`, `ExtensionAPI`
|
|
Location: `@mariozechner/pi-coding-agent/dist/core/extensions/types.d.ts`
|
|
```
|
|
|
|
## Process
|
|
|
|
1. **Read the plan** — understand what needs to be implemented.
|
|
2. **Grep source files** — find the exact files, functions, and types involved.
|
|
3. **Grep pi-coding-agent types** — find exact API signatures.
|
|
4. **Grep event emission points** — find when events fire.
|
|
5. **Enrich the plan** — add the findings to the markdown.
|
|
6. **Save the enriched plan** — overwrite the original file or create a new one.
|
|
|
|
## Example Enrichment
|
|
|
|
Given a plan phase like:
|
|
```markdown
|
|
- [ ] Add `/turn-limit` command
|
|
- Register via `pi.registerCommand()`
|
|
- Handler parses args, validates positive integer
|
|
- Updates `maxTurns` in-memory variable
|
|
```
|
|
|
|
Enrich it to:
|
|
```markdown
|
|
- [ ] Add `/turn-limit` command
|
|
- **File:** `packages/pi-turn-limit/src/turn-limit.ts`
|
|
- **API:** `pi.registerCommand("turn-limit", { description, handler })`
|
|
- **Handler signature:** `async (args: string, ctx: ExtensionCommandContext) => Promise<void>`
|
|
- `args` is a single string — use `args.trim().split(/\s+/)` for parsing
|
|
- `ctx` is `ExtensionCommandContext` (extends `ExtensionContext`) — has `ctx.ui`, `ctx.abort()`
|
|
- **Handler:**
|
|
- Parse `args.trim()` as integer
|
|
- If invalid: `ctx.ui.notify("Invalid turn limit. Must be a positive integer.", "error")`
|
|
- Update `maxTurns` in-memory variable (change `const` to `let`)
|
|
- `ctx.ui.setWidget("turn-limit", ["Turns: ${turnCount}/${maxTurns}"])`
|
|
- `ctx.ui.notify("Turn limit set to {N}.", "info")`
|
|
```
|
|
|
|
## Tips
|
|
|
|
- **Be specific, not descriptive.** Prefer exact signatures over "parses args as integer".
|
|
- **Verify before including.** Don't guess — grep the actual files.
|
|
- **Keep it concise.** The enrichment should make the plan actionable, not bloated.
|
|
- **Preserve the original structure.** Add enrichment inline, don't rewrite the plan.
|