Narrow Imp agents and routing: practice drills

Exercises covering Codex-versus-Imp selection, health checks, routing and execution modes, dash-prefix hooks, bounded marker packets, fleet management, evolution review, narrow Imp design, failure recovery, tests, and final handoff receipts.

These exercises practice routing narrow tool-shaped work to Imps.

Exercise 1: Regular Codex Or Imp?

Choose regular Codex or Imp.

Task Choice Why
Find every place checkout disabled state is computed.
Decide which checkout architecture to use.
Summarize current git dirty state.
Implement saved payment methods.
Query JSON for users by plan.
Trim a video file.
Explain product risk of auth/session rotation.
Find GitHub examples of a file pattern.

Exercise 2: Check Health

Run:

imp -l
imps list
imps ps
imps doctor

Fill out:

# Imp Health

- roster visible? yes/no:
- warm processes:
- doctor status:
- auth status:
- command that failed:
- next check:

Exercise 3: Route Before Running

Run:

imp --which "what changed in git since yesterday?"
imp --which "find the TODOs in src; then commit everything"
imp --which "find examples of DESIGN.md created in the past 2 months"

Fill out:

# Routing Notes

- prompt:
- chosen Imp:
- compound route? yes/no:
- split points:
- would you run it? yes/no:
- why:

Exercise 4: Run imp-rg

Run:

imp-rg --run "find TODOs in src"

Quiet mode:

imp-rg -q "find TODOs in src"

No warm mode:

imp-rg --no-warm "find TODOs in src"

Fill out:

# imp-rg Notes

- command:
- files searched:
- matches:
- exact command evidence present? yes/no:
- when to use `--run`:
- when to use `-q`:
- when to use `--no-warm`:

Exercise 4A: Single-Dash Hook Route

Submit a foreground Imp prompt from Codex:

-rg find TODOs in src

Fill out:

# Single-Dash Hook Notes

- prompt:
- resolved Imp:
- executable path included? yes/no:
- description included? yes/no:
- task text preserved? yes/no:
- cwd included? yes/no:
- did the main prompt continue? yes/no:
- did the main agent avoid rediscovering the Imp? yes/no:
- command evidence returned:

Exercise 4B: Double-Dash Fork Route

Submit a forked Imp prompt from Codex:

--rg find TODOs in src

Fill out:

# Double-Dash Fork Notes

- original prompt:
- normalized fork prompt:
- did current prompt block? yes/no:
- workspace:
- pane:
- surface:
- window:
- read-screen command:
- top command:
- focus-pane command:
- what output appeared in the fork:

Exercise 4C: Unknown Or Ambiguous Imp

Try an intentionally unclear route:

-g find TODOs in src

Fill out:

# Ambiguous Route Notes

- prompt:
- blocked? yes/no:
- suggested matches:
- would you clarify, use `imp --which`, or create with `imp-create`?
- corrected prompt:

Exercise 5: Section 8 Marker Packet To Imp

Start with a bounded marker packet.

# Marker Packet

- marker id:
- marker label: Checkout button stayed disabled
- marker note:
- nearby evidence terms:
  - acceptedTerms
  - selectedShipping
  - checkout disabled
- privacy boundary:
  - storage values exported? no
  - request bodies exported? no
  - response bodies exported? no

Route:

imp --which "find code paths related to acceptedTerms, selectedShipping, and checkout disabled"

Run:

imp-rg --run "Search for acceptedTerms, selectedShipping, and checkout disabled. Return file:line matches and exact rg commands used."

Fill out:

# Marker Packet Imp Run

- marker id:
- chosen Imp:
- exact command:
- file:line evidence:
- what the Imp must not infer:
- next regular Codex task:

Exercise 6: Fleet Management

Run:

imps ps
imps stop imp-rg
imps stop --all
imps doctor

Fill out:

# Fleet Management

- warm imps before:
- stopped:
- warm imps after:
- doctor status:
- when to stop a warm Imp:

Exercise 7: Inspect Evolution Suggestions

Run:

imps evolve
imps evolve imp-rg

Fill out:

# Evolution Review

- suggestion path:
- suggested change:
- safe? yes/no:
- keeps one tool? yes/no:
- keeps command evidence? yes/no:
- accept, edit, or reject:
- why:

Exercise 8: Design A New Imp

Pick one CLI tool.

Examples:

sqlite3
redis-cli
internal search tool
project-specific deploy CLI

Fill out:

# New Imp Design

- name: imp-
- tool:
- sandbox mode:
- why this is single-purpose:
- what this Imp must never do:
- first safe command:
- first verification command:

## Operating Rule

Run <tool> via exec_command before any final answer. Do not answer from memory.

## Command Map

| User Intent | Exact Command |
| --- | --- |
| status | |
| list | |
| inspect | |
| help | |

## Worked Examples

### Example 1

1.
2.
3.

### Example 2

1.
2.
3.

## Error Recovery

| Error Text | Next Command |
| --- | --- |
| command not found | |
| unknown flag | |
| no results | |

## Output Rules

-
-
-

Answer:

# Narrowness Review

- does this use exactly one tool? yes/no:
- does it need broad repo reasoning? yes/no:
- should it be regular Codex instead? yes/no:
- what to split out:

Exercise 9: Failure Path Drill

Choose a recovery for each failure.

Failure Recovery
router picks the wrong Imp
prompt is too broad for an Imp
Imp answers without showing a command
warm server appears stale
auth.json missing
compound route split wrong
evolution suggestion looks unsafe
marker packet lacks nearby evidence terms
package Imp wants to mutate a pnpm project
ffmpeg Imp would overwrite input

Recovery options:

run `imp --which`
use an explicit route
split into smaller tool tasks
send broad reasoning back to regular Codex
strengthen Operating rule
add Worked examples
run `imps ps`
run `imps stop <imp>`
run `imps doctor`
rewrite compound prompt with `;` or `then`
dismiss unsafe evolution suggestions
sharpen marker packet
inspect lockfiles
require new output file and no overwrite
run read-only checks only

Fill out one in detail:

# Failure Recovery Detail

- failure:
- likely cause:
- first command:
- recovery:
- how to know it worked:

Exercise 10: Verify The Imp Project Safety Net

From the Imp project checkout, run:

bun test

Fill out:

# Test Check

- command: `bun test`
- pass count:
- fail count:
- test files:
- router covered? yes/no:
- parse args covered? yes/no:
- CLI smoke covered? yes/no:
- hot reload covered? yes/no:
- evolution covered? yes/no:
- would you edit routing without this passing? yes/no:
- why:

Optional focused checks:

bun test test/router.test.ts
bun test test/parseargs.test.ts
bun test test/cli-smoke.test.ts

Hook route checks:

-rg find TODOs in src
--rg find TODOs in src

Fill out:

# Dash Route Check

- can explain `-<imp>`? yes/no:
- can explain `--<imp>`? yes/no:
- can inspect a forked cmux session? yes/no:
- can explain why direct `codex fork ... -- '-imp ...'` is used? yes/no:

Exercise 11: Final Handoff

Write a final handoff file:

mkdir -p receipts
cat > receipts/section9-final-handoff.md <<'EOF'
# Section 9 Final Imp Handoff

- source: Section 8 marker packet
- DebugSession path:
- marker id:
- marker label:
- marker note:
- expected:
- actual:
- nearbyEventIds:
- evidence terms:
  -
  -
  -
- privacy boundary:
  - storage values exported?
  - request bodies exported?
  - response bodies exported?
- target Imp:
- why this target is single-purpose:
- command to run:
- required output:
- command evidence to preserve:
- what the Imp must not invent:
- next handoff after Imp result:
EOF

test -s receipts/section9-final-handoff.md && echo "handoff:OK"

Fill out:

# Final Handoff Review

- handoff file:
- target Imp:
- command:
- route checked with `imp --which`? yes/no:
- marker packet bounded? yes/no:
- expected output clear? yes/no:
- command evidence required? yes/no:
- privacy boundary explicit? yes/no:
- ready to run? yes/no:

Final Check

Run or review:

imp -l
imps list
imps ps
imps doctor
imp --which "find TODOs in src; then summarize git changes"
bun test

Fill out:

# Final Imps Check

- can explain regular Codex vs Imp? yes/no:
- can state the core sentence? yes/no:
- can route before running? yes/no:
- can explain compound routing? yes/no:
- can run direct interactive mode? yes/no:
- can run `--run`? yes/no:
- can run `-q`? yes/no:
- can explain warm mode? yes/no:
- can stop warm imps? yes/no:
- can explain isolation? yes/no:
- can inspect evolution suggestions? yes/no:
- can design a narrow Imp prompt? yes/no:
- can hand a Section 8 marker packet to an Imp? yes/no:
- can decide when to return to regular Codex? yes/no:

Source references