Pi + Archon + Plannotator: Deterministic AI Coding Workflows

Why This Matters

When features are optional extensions rather than built-in bloat:

• The core remains stable and predictable
• You control exactly what your agent can do
• System prompt changes are under your control
• You can replicate any Claude Code feature without the bloat

Installation

Pi installs in a single command:

1
npm install -g @mariozechner/pi-coding-agent

Authenticate and start:

1
export ANTHROPIC_API_KEY=sk-ant-...
2
pi

Or use your existing subscription with the /login command.

What Archon Solves

When you ask an AI agent to “fix this bug,” the outcome depends on the model’s mood:

• Maybe it skips planning
• Maybe it forgets to run tests
• Maybe it writes a PR description that ignores your template

Archon fixes this by enforcing structure:

1
nodes:
2
  - id: plan
3
    prompt: "Explore the codebase and create an implementation plan"
4

5
  - id: implement
6
    depends_on: [plan]
7
    loop:
8
      prompt: "Read the plan. Implement the next task. Run validation."
9
      until: ALL_TASKS_COMPLETE
10

11
  - id: run-tests
12
    depends_on: [implement]
13
    bash: "bun run validate"
14

15
  - id: review
16
    depends_on: [run-tests]
17
    prompt: "Review all changes against the plan."
18

19
  - id: create-pr
20
    depends_on: [review]
21
    prompt: "Push changes and create a pull request"

Key Capabilities

• Repeatable: Same workflow, same sequence, every time
• Isolated: Every workflow run gets its own git worktree — parallel execution without conflicts
• Fire and forget: Kick off a workflow, come back to a finished PR
• Composable: Mix deterministic nodes (bash, git ops) with AI nodes (planning, generation)
• Portable: Define workflows in .archon/workflows/, commit to repo, share with team

Multi-Agent Support

Archon now supports three coding agents out of the box:

• Claude Code
• OpenAI Codex
• Pi — the third supported agent, recently added

The combination of Pi + Archon is powerful. Pi provides the minimal, predictable agent. Archon provides the deterministic workflow structure.

Installation

1
pi install npm:@plannotator/pi-extension

Configure in .archon/config.yaml:

1
assistants:
2
  pi:
3
    extensionFlags:
4
      plan: true
5
    env:
6
      PLANNOTATOR_REMOTE: "1"  # binds plannotator on 127.0.0.1:19432

Phase 1: Clarify (Archon + Claude)

Claude asks 2-3 targeted questions via Archon’s human-in-the-loop (HITL) system to converge on intent before handing off to Pi.

1
- id: clarify
2
  loop:
3
    prompt: |
4
      Get enough clarity that the Pi agent can produce a useful plan.
5
      Ask about DECISIONS (scope, extend vs new, testing bar), not information.
6
    until: READY_FOR_PLAN
7
  max_iterations: 6
8
  interactive: true

Output: A clear understanding of scope, key decisions, files likely to change.

Phase 2: Plan (Pi + Plannotator)

A Pi session writes PLAN.md and submits it to Plannotator for review. The reviewer receives a URL (127.0.0.1:19432) and approves or denies with feedback. If denied, Pi iterates on the plan inside its session.

1
- id: plannotator-plan
2
  depends_on: [clarify]
3
  provider: pi
4
  model: openai-codex/gpt-5.4-mini
5
  idle_timeout: 3600000  # 1 hour for human review
6
  prompt: |
7
    You are a PLANNER, not an implementer:
8
    1. Write PLAN.md (only file you may edit)
9
    2. Submit via plannotator_submit_plan
10
    3. Iterate if denied
11
    4. On approval: print one line and exit
12

13
    DO NOT start implementing after approval — Claude handles that.

PLAN.md structure:

1
# Plan: {feature name}
2

3
## Summary
4
{1-2 sentences — what and why}
5

6
## In Scope
7
- {bullet}
8
## Out of Scope
9
- {bullet}
10

11
## Architecture Decisions
12
- {decision — rationale}
13

14
## Tasks
15
- [ ] Task 1: {ACTION} `{path}` — {what and why}
16
- [ ] Task 2: {ACTION} `{path}` — {what and why}
17
- [ ] Task N: {ACTION} `{path}` — {what and why}
18

19
## Validation
20
- {command(s) that prove feature works}
21
- {lint / type-check / test commands}
22

23
## Risks
24
- {risk} — {mitigation}

Critical constraint: Pi is explicitly forbidden from implementing. It writes the plan, submits it, and hands off. The plannotator extension may say “full tool access is now unlocked,” but Pi ignores it — those tools are for the next node.

Phase 3: Implement (Claude)

Claude reads the approved PLAN.md and implements task-by-task with validation and commits. This uses Archon’s loop feature to iterate through tasks.

1
- id: implement
2
  depends_on: [verify-plan]
3
  idle_timeout: 600000
4
  loop:
5
    prompt: |
6
      Fresh session each iteration. Read PLAN.md, implement ONE task,
7
      validate, commit, exit. Golden Rule: never commit broken code.
8
    until: IMPL_DONE
9
  max_iterations: 20
10
  fresh_context: true

Each implementation iteration:

1. Selects the next unchecked task from PLAN.md
2. Reads relevant files
3. Makes changes following conventions
4. Runs validation: bun run type-check && bun run lint && bun run test
5. Commits if validation passes (or fixes up to 3 attempts)
6. Marks task complete in PLAN.md
7. Signals completion when all tasks done

Phase 4: Validate (Claude)

Final review comparing plan vs. reality, full validation suite, and status report.

1
- id: final-review
2
  depends_on: [implement]
3
  prompt: |
4
    Gather context:
5
    - Run full validation: bun run validate
6
    - Check git log and diff
7
    - Read PLAN.md and progress file
8

9
    Cross-check plan vs reality:
10
    - Is each task checked?
11
    - Does a commit exist for it?
12
    - Do changed files match task descriptions?
13

14
    Output summary with readiness recommendation.

Output:

1
===============================================================
2
PLANNOTATOR-PIV — SUMMARY
3
===============================================================
4

5
Feature: {from PLAN.md}
6
Branch: {current branch}
7

8
-- Tasks --
9
{tasks from PLAN.md with status}
10

11
-- Commits --
12
{git log}
13

14
-- Validation --
15
type-check: PASS/FAIL
16
lint:       PASS/FAIL
17
tests:      PASS/FAIL
18
format:     PASS/FAIL
19

20
-- Recommendation --
21
{READY FOR PR / NEEDS FIXES — with specifics}
22
===============================================================

Determinism

Every run follows the same structure:

1. Clarify → questions resolved
2. Plan → human-approved specification
3. Implement → task-by-task execution
4. Validate → comprehensive verification

No more “model’s mood” variations. No skipped tests. No forgotten validation.

Separation of Concerns

Each agent does what it’s best at. Pi focuses on planning with minimal tooling. Claude handles implementation with full tool access. Plannotator provides the human gate.

Iteration Without Breaking Flow

• Plan iteration: Happens in Pi session before approval. The loop is contained — Plan.md updates, resubmits, blocks again.
• Implementation iteration: Happens per-task in Claude. If validation fails, fix before committing.
• No cross-boundity: Planning doesn’t bleed into implementation. Implementation doesn’t skip back to planning.

Step 1: Install Prerequisites

1
# Pi
2
npm install -g @mariozechner/pi-coding-agent
3

4
# Plannotator extension
5
pi install npm:@plannotator/pi-extension
6

7
# Archon (if not already installed)
8
git clone https://github.com/coleam00/Archon
9
cd Archon
10
bun install

Step 2: Configure Plannotator

Create or edit .archon/config.yaml:

1
assistants:
2
  pi:
3
    extensionFlags:
4
      plan: true
5
    env:
6
      PLANNOTATOR_REMOTE: "1"

Step 3: Copy the Reference Workflow

Copy archon-plannotator-piv.yaml from the Archon repo or GitHubIssueTriager example into your project’s .archon/workflows/ directory.

Step 4: Run the Workflow

From your project directory:

1
claude

Then invoke:

1
Use archon to run archon-plannotator-piv workflow to implement: {your feature description}

Archon will:

1. Start the clarify phase (Claude asks questions)
2. Hand off to Pi for planning
3. Pi writes PLAN.md and submits to plannotator
4. You’ll see a URL: [pi extension ℹ️] Review your plan at http://127.0.0.1:19432
5. Open the URL, review, approve or deny with feedback
6. If denied, Pi updates the plan and re-submits
7. If approved, Claude implements task-by-task
8. Final validation and summary

1. Predictable System Prompt

Claude Code’s system prompt changes with every release. Your workflow works today, breaks tomorrow.

Pi’s system prompt is under your control. Extensions add functionality by modifying prompts explicitly. You can read the code, understand what’s happening, and adjust.

2. No Unwanted Features

Claude Code ships features you don’t want — sub-agents, MCP, plan mode — adding to token cost and unpredictability.

Pi ships with four tools. Add what you need, nothing more.

3. Explicit Human Gates

Claude Code’s interactive mode is conversational. “Ask me before” is a request, not a gate.

Archon’s interactive: true + Plannotator’s approval UI are hard gates. Workflow literally blocks until you approve. No accidental work proceeds.

4. Isolated Executions

Claude Code sessions live in your working directory. Parallel work means branch switching or conflict management.

Archon creates git worktrees for each workflow run. Execute 5 fixes in parallel with zero conflicts.

5. Observable and Auditable

Claude Code sessions are ephemeral unless you export manually.

Archon logs every step, node transition, tool call, and human interaction. The dashboard shows running workflows, history by project/status/date, and step-by-step progress.

Multi-Agent Implementation

1
- id: implement-feature
2
  provider: claude
3
  model: sonnet
4

5
- id: implement-tests
6
  provider: pi
7
  model: openai-codex/gpt-5.4-mini
8

9
- id: implement-docs
10
  provider: claude
11
  model: haiku

Use Claude for complex feature logic, Pi for test generation (cost-effective), and Haiku for documentation.

Parallel Review

1
- id: review-code
2
  depends_on: [implement]
3
  parallel:
4
    - provider: claude
5
      model: sonnet
6
      prompt: "Review for correctness and security"
7
    - provider: claude
8
      model: opus
9
      prompt: "Review for architecture and performance"
10
    - provider: pi
11
      model: openai-codex/gpt-5.4
12
      prompt: "Review for edge cases and errors"

Three simultaneous reviewers, each with different focus. Synthesize findings.

Conditional Gates

1
- id: security-review
2
  depends_on: [implement]
3
  condition: |
4
    Files changed include: auth, session, token, password, credential
5
  prompt: "Security review required for auth-related changes"
6
  interactive: true

Only require security review when touching sensitive files.