My personal Pi setup for software development. It adds a structured workflow for clarifying intent, designing systems, specifying bounded changes, planning, simplifying, and challenging implementation, advancing plans through resumable tasks and milestone gates with durable evidence, optionally driving full plans through bounded session goals, and independently reviewing the result.
The repository contains the skills, extensions, prompts, and saved workflows that power that setup. Custom extensions are written in TypeScript and maintained with tests and documentation.
The harness combines a simple development loop with tools that keep work scoped, observable, and verifiable.
- Clarify and route ambiguous requests with
clarifywhen the right design artifact is not yet clear. - Design and specify broad systems with
architect, then turn each outcome—or one smaller standalone change—into a Ready specification withspecify. - Plan and stress-test one specification with
plan, the explicit-onlysimplifyskill for unnecessary complexity, andchallengefor substantial risks. - Implement one bounded, resumable plan step with
advance-plan: either one main-session task or one milestone gate, while the main session owns implementation, run state, verification, decisions, evidence, and commits. For autonomous execution, use the minimal/goalinvocation emitted byplanto calladvance-planonce per turn. - Review completed changes with
review, which combines repository context, deterministic checks, and independent analysis.
The harness provides three complementary orchestration primitives. Choose based on what needs to be isolated or controlled:
| Primitive | Use it when | What it provides |
|---|---|---|
| Subagents | A task benefits from a fresh perspective, a different model or reasoning effort, isolation from the main context, or independent parallelism. | A one-shot child session with a self-contained prompt, explicit capabilities, and a centrally configured fast, balanced, or strong profile. |
| Workflows | The orchestration is predictable and reusable—especially for fan-out/fan-in research, review, verification, or audit patterns. | Deterministic JavaScript control flow around bounded subagent calls, including parallelism, pipelines, structured output, verification gates, and budgets. |
| Goals | Work must advance incrementally across agent turns, and each next action may depend on what the previous turn discovered or completed. | A session-scoped objective with bounded continuation, lifecycle controls, and evidence-backed completion. |
Use a subagent when the primary need is another isolated reasoning context. Children start cold, so tasks must be self-contained. Read-only exploration and review are the default use cases; mutable delegation is kept sequential and explicitly bounded.
Use a workflow when the control graph should live in code rather than be improvised by the model. Workflows are best when decomposition, concurrency, synthesis, and termination can be defined in advance. In this configuration they are read-mostly and are not a mechanism for parallel workspace mutation or open-ended execution.
Use a goal when progress is adaptive but can be made and audited one turn at a time. Goals keep the main agent moving toward an objective until it completes, yields, is interrupted, or reaches a configured bound. A goal supplies continuation and steering; it does not replace a durable plan or prescribe a fixed phase graph.
These primitives compose. A goal-driven plan may advance one main-session implementation step per turn and use read-only subagents or workflows for bounded research, diagnosis, or explicitly required review. The outer goal owns continuation, the main session owns workspace mutation and plan evidence, the workflow owns deterministic orchestration, and each subagent owns one isolated unit of reasoning.
For explicit worktree-based delegation, the model-invokable spin-out skill starts a fresh Pi agent in a Herdr-managed worktree with a durable local task brief only when the user asks to spin out work.
Custom TypeScript extensions under pi/agent/extensions/ provide:
- Work tracking and automation: goals, TODOs, and scheduled tasks
- Delegation and orchestration: isolated subagents, saved workflows, and structured output
- External access: broker-backed services and web research
- Interaction and context: user prompts, context reporting, compact tool output, and TUI status information
See pi/README.md for the complete extension and skill catalog.
Herdr provides the terminal and worktree control plane used by the herdr and spin-out skills. Herdr's Pi integration installs a local lifecycle bridge, while the repository-owned ask_user extension reports interactive questions through that bridge. See the Pi Herdr integration documentation for component ownership, installation, and updates.
Extensions are directory-based TypeScript modules with colocated tests and user-facing documentation. Non-trivial extensions also include design guidance, while shared helpers live under pi/agent/extensions/_shared/.
make install-dev # install dependencies and Git hooks
npm run lint # lint extensions and saved workflows
npm run format:check # check formatting
make typecheck # run TypeScript checks
make test # run unit testsagent-tools provides external utilities that complement this configuration repo.
The main integration point is the MCP broker: a credentials-holding proxy that lets sandboxed agents use authenticated external services without holding secrets directly. In Pi, the mcp-broker extension exposes broker-backed tools through mcp_search, mcp_describe, and mcp_call, and guards direct gh or remote-git usage when broker tools are preferred.
agent-tools also includes a sandbox manager (sb) for isolated agent runs. It is relevant to Pi as an outer isolation layer: this Pi config adds workflow guidance and broker preferences, but it does not implement shell command restrictions itself.
notes/ contains public essays and working notes about agent harness design, permissions, subagents, planning workflows, and related topics.
- Pi agent
- Herdr for pane, agent, and worktree integration
- Homebrew
- Node.js 24+
- macOS assumed, adaptable for Linux
git clone git@github.com:averycrespi/agent-config.git
cd agent-config
brew bundle # install system dependencies on macOS
make install-dev # install Node dependencies and Husky git hooks
make install-playwright # for browser automation and web-access JS rendering
make stow-pi # symlink pi/agent/ into ~/.pi/agent/
herdr integration install pi # install/update the local Pi lifecycle bridge- Repository licensed under MIT
- Individual components may have their own licenses