Pi Agent Configuration

A setup for deliberate, intentional coding — not vibe coding.

Handoffs as Context Compression

Each phase of the workflow produces a focused artifact that carries only what the next phase needs. The handoff extension enables this by spawning new sessions with structured context, replacing lossy compaction with deliberate, structured context transfer. The handoff is the context, not the conversation history.

Workflow

  ┌─────────┐     ┌─────────┐     ┌─────────┐     ┌─────────┐
  │  GOAL   │────▶│  PLAN   │────▶│   DO    │────▶│ REVIEW  │
  │(collab) │     │(agent)  │     │(agent)  │     │(collab) │
  └─────────┘     └─────────┘     └─────────┘     └─────────┘
       ▲                                                │
       └────────────────────────────────────────────────┘

GOAL — Collaborative

The user and agent define what needs to be done. This is where understanding is built, assumptions are challenged, and problems are diagnosed.

• sync — Focused spec sessions to reach shared understanding before starting work.
• debug — Tmux-based reproduction and diagnosis of crashes and errors.

PLAN — Agent-Driven

The agent produces a structured plan via handoff. The user can review, modify, or ask for refinements before moving on.

• plan — Tracing-bullet implementation plans (vertical slices, end-to-end).
• fix-plan — Bug-fix plans based on root cause analysis.

DO — Agent Implements

The agent executes the plan with minimal user involvement. Each plan slice is implemented as a focused effort.

REVIEW — Collaborative

The agent and user validate the work together. Some verification requires the user's judgment or environment.

• test — Structured testing instructions and verification steps.
• review — Code review for bugs, correctness, and quality.
• security-review — Focused security vulnerability review.
• cleanup — Refactoring-only pass (naming, dead code, duplication, documentation).

Utilities

• git-commit — Stages and commits all changes following Conventional Commits. Does not push.
• webtools — Web search (SearXNG) and page fetching for the agent.