开源AI工作流

3. Create matching branch in submodule (required before editing)

cd flask_blogs git checkout -b worktree-git-issue-42-add-user-authentication git push -u origin worktree-git-issue-42-add-user-authentication cd ..

2. Philosophy — Why build your own?

Everyone should build their own Pi. This repo is my personal Pi agent harness. Fork it as a starting point, but the real power comes from shaping it into your own — your preferred tools, your workflows, your guardrails.

Why? Every developer and every team is different. The most effective way of working with an AI coding harness is the one that fits your workflow, not a one-size-fits-all maximalist suite. A harness packed with every imaginable feature often gets in the way. The best harness is the one you build for yourself.

Customize ruthlessly. Make it yours.

---

4. Installation — How to set it up

Quick-start

git clone git@github.com:SchneiderDaniel/agentcastle.git
cd agentcastle
./agent-castle.sh

That's it. The wrapper script: 1. Builds the OCI image from docker/Dockerfile (first run, ~2 min; cached thereafter) 2. Starts the container with your repo bind-mounted, API keys loaded, and UID/GID mapped 3. Drops you into the Pi TUI inside the container

Step-by-step

1. Clone the repo

git clone git@github.com:SchneiderDaniel/agentcastle.git && cd agentcastle

2. Configure API keys ```bash cp docker/agent_env.example .agent_env

5. Orientation — What did I just install?

5.1 Architecture

┌────────────────────────────────────────────────────┐
│  Terminal (Docker)                                  │
│  ┌──────────────────────────────────────────────┐  │
│  │  Pi TUI (Terminal) — agentcastle theme       │  │
│  │  ┌──────────┐ ┌──────────┐ ┌──────────────┐ │  │
│  │  │ Exts     │ │ AI Prov │ │ Rich Footer  │ │  │
│  │  │ .pi/     │ │OpenCode  │ │branch model  │ │  │
│  │  │ exts/    │ │Go/...    │ │tokens TPS    │ │  │
│  │  └───┬──────┘ └──────────┘ └──────────────┘ │  │
│  │      │                                        │  │
│  └──────┼────────────────────────────────────────┘  │
└─────────┼───────────────────────────────────────────┘
          │
     ┌────▼────────────────────────────┐
     │  External tools                  │
     │  ┌──────────┐ ┌───────────────┐ │
     │  │ ctags    │ │ ast-grep      │ │
     │  │map_code- │ │structural_    │ │
     │  │base tool │ │search tool    │ │
     │  └──────────┘ └───────────────┘ │
     │  ┌──────────┐ ┌───────────────┐ │
     │  │ ripgrep  │ │ crawl4ai      │ │
     │  │ripgrep_  │ │Python venv    │ │
     │  │search    │ │(host browser) │ │
     │  └──────────┘ └───────────────┘ │
     └─────────────────────────────────┘

Key principle: All tools run locally. Web crawling runs on host (network-only for crawl). Ctags, ast-grep, ripgrep are system binaries invoked via pi.exec(). No MCP servers, no network-exposed tool endpoints.

5.2 Why extensions instead of MCP?

This project deliberately avoids the Model Context Protocol (MCP). All tools are pi extensions — TypeScript files in .pi/extensions/ that run inside the agent's Node.js runtime. No external MCP servers, no network-exposed tool endpoints, no separate processes.

Two reasons: security and token efficiency.

🔒 Security: MCP servers introduce a new attack surface (OWASP maintains the MCP Top 10). Extensions treat tool execution as a function call. No network layer = no network attack surface.

📉 Token Efficiency: MCP servers expose full JSON Schema tool descriptions to the LLM on every request. Pi extensions use prompt snippets — concise one-line descriptions (~50-120 tokens vs ~300-800 for MCP). Full schema is only loaded when the tool is actually called. Saves thousands of tokens per turn.

5.3 What's in the box — File Manifest

5.4 Extensions Deep Dive

Pi auto-discovers extensions from .pi/extensions/ in the project root. No config file needed. No --extension flag.

5.5 Agent Definitions

Agents are Markdown files in .pi/agents/ with YAML frontmatter. The supervisor reads them at runtime.

All agents use opencode-go/deepseek-v4-flash model. Developer additionally uses format-on-save and tsc-checkpoint extensions.

5.6 Prompt Templates

Invocable via /name in Pi's editor:

5.7 Tool Benchmark

Empirical token consumption comparing tool configurations on a real audit task ("Audit test coverage of chart/figure generation methods"). Config 4 (ripgrep) is the most token-efficient tool-enabled config.

Config 4 uses 27% fewer total tokens and runs 33% faster than mapper-only (config 2). The ripgrep fix resolved the earlier issue where ripgrep made token consumption worse.

The agent footer also shows a TPS (tokens-per-second) gauge during streaming, computed from a rolling 30s window, plus worktree name in brackets next to the branch when inside a git worktree.

Run with scripts/benchmark-tools.sh (2 runs per config). Results saved to scripts/benchmark-results/.

5.8 Skills

Currently no skills installed (.pi/skills/.gitkeep). Skills are used sparingly in this project — every skill's description injects ~50-150 tokens into the context window on every turn, causing context rot. Prefer extensions (concise prompt snippets) or prompt templates (lazy-loaded) over skills.

---

Legacy Installation (host-level)

For users who prefer a host-level install (Node.js, apt packages, Pi on bare metal), the original install scripts are preserved in scripts/legacy/:

These scripts are deprecated — the Docker workflow is the supported path. They remain for reference and for users who cannot run Docker.

Edit .agent_env with your keys (e.g., APIFY_TOKEN)

**3. Launch**

**4. Set provider (first session only)**

What happens under the hood

./agent-castle.sh runs docker compose up with: - Image built from docker/Dockerfile (Debian 12-slim, Node.js 22, Python 3, ctags, ripgrep, ast-grep, pi, gosu) - Repo root bind-mounted to /workspaces/main inside the container - .agent_env file mounted and sourced automatically - Host UID/GID mapped to container user agentuser (no permission issues with bind mounts) - Interactive TTY for the Pi TUI

---

8. Power User — The Multi-Agent Pipeline

The supervisor (/supervisor <issue-number>) is the heart of this harness. It takes a GitHub issue, runs it through 5 agent stages in a Kanban loop, creates git worktrees, runs quality gates, and creates pull requests — all autonomously.

8.1 Pipeline Flow

     ┌─────────────────────────────────────────────────────────────────────────┐
     │                         GITHUB PROJECT BOARD                           │
     │  ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────────┐ ┌─────────┐  │
     │  │ Research │ │Architect.│ │TestDesign│ │Implement.    │ │  Audit  │  │
     │  │          │ │          │ │          │ │              │ │         │  │
     │  └────┬─────┘ └────┬─────┘ └────┬─────┘ └──────┬───────┘ └────┬────┘  │
     │       │             │            │              │              │       │
     └───────┼─────────────┼────────────┼──────────────┼──────────────┼───────┘
             │             │            │              │              │
    ┌────────▼────────┐ ┌──▼────────┐ ┌─▼───────────┐ │    ┌─────────▼──────┐
    │  Researcher     │ │ Architect │ │ TestDesigner │ │    │   Auditor      │
    │  crawls web     │ │ proposes  │ │ writes       │ │    │   reviews      │
    │  for best       │ │ target    │ │ test plan    │ │    │   implements   │
    │  practices,     │ │ architec- │ │ from archi-  │ │    │   creates PR   │
    │  lib versions,  │ │ ture      │ │ tecture      │ │    │   or rejects   │
    │  pitfalls       │ │           │ │              │ │    │                │
    └────────┬────────┘ └──┬────────┘ └─┬───────────┘ │    └────────┬───────┘
             │             │            │              │             │
             ▼             ▼            ▼              │             ▼
     GitHub Comment   GitHub Comment  GitHub Comment   │    GitHub Comment
     ## Research      ## Architectu-  ## Test Plan      │    ## Audit Approved
     Findings         re Approach                       │    + PR created
                                                        │
                        ┌───────────────────────────────┘
                        │
                        ▼
              ┌──────────────────────┐
              │  QUALITY GATES       │
              │  ┌────────────────┐  │
              │  │ TSC --noEmit   │──│──→ pass → continue
              │  │ (tsc-checkpoint)│  │     fail → back to Implementation
              │  └────────────────┘  │
              │  ┌────────────────┐  │
              │  │ LSP pre-audit  │──│──→ pass → continue
              │  │ (lsp-auditor)  │  │     fail → back to Implementation
              │  │                │  │     (max 3 retries)
              │  └────────────────┘  │
              └──────────────────────┘
                        │
                        ▼
              ┌──────────────────────┐
              │  Auditor decision    │
              │  ┌──────────────┐    │
              │  │ APPROVED?    │──│──→ Yes → Create PR → DONE
              │  │              │    │     No  → back to Implementation
              │  └──────────────┘    │
              └──────────────────────┘
                        │
                        ▼
              ┌──────────────────────┐
              │  POST-PIPELINE       │
              │  Check PR for        │
              │  merge conflicts     │
              │  Auto-merge or       │
              │  dispatch Developer  │
              └──────────────────────┘

Loop rules: - Each agent posts a structured GitHub comment on the issue - Supervisor reads the agent's output for a completion marker to know the agent finished - If agent times out, supervisor logs it and stops - Auditor can reject → sends back to Implementation (counts as 1 rejection) - LSP/TSC errors → sends back to Implementation (does NOT count as rejection, max 3 retries) - maxRejections (default 5) stops the loop to prevent infinite cycles

8.2 Agent Deep Dive

8.3 Git Worktree Lifecycle

Each issue gets an isolated git worktree. This prevents agents from interfering with each other and keeps main clean.

Branch naming: worktree-git-issue-<number>-<title-slug> (e.g., worktree-git-issue-42-add-user-authentication)

Worktree path: ../worktree-git-issue-<number>-<title-slug>/

Lifecycle (supervisor-owned):

1. Supervisor creates worktree before Developer dispatch
   └── git worktree add -b <branch> ../<branch> <defaultBranch>

2. Supervisor dispatches Developer agent with cwd=<worktree-path>
   └── Agent tools (write, edit, bash, read) resolve against worktree

3. Developer implements, commits, pushes (inside worktree via cwd)
   ├── git add -A
   ├── git commit -m "feat(#42): Add user auth"
   └── git push origin <branch>

4. Supervisor dispatches Auditor agent with same cwd=<worktree-path>
   └── git diff <defaultBranch>

5. On approval: Auditor creates PR
   └── gh pr create --repo owner/repo --base <defaultBranch> --head <branch> --title "feat(#42): ..." --body "Closes #42"

6. Post-pipeline: supervisor cleans up worktree
   ├── git worktree remove --force ../<branch>
   ├── git worktree prune
   └── git branch -D <branch>

Key rules: - Worktree is created and owned by the supervisor pipeline — agents never create or remove worktrees - Agent cwd is set to worktree path automatically — no cd needed in agent tasks - All Git operations happen inside the worktree (tools resolve against cwd) - Worktree persists across feedback loops (auditor reject → re-implement) - Supervisor cleans up worktree after pipeline completes (success, failure, or stop) - Configurable via supervisor.worktreeBase and supervisor.branchPrefix in .pi/settings.json

8.4 Submodule Strategy

When the repo has submodules, the Developer works on both repos simultaneously using a matched-branch pattern:

Main repo (agentcastle)          Submodule (flask_blogs)
│                                │
├─ Branch: worktree-git-...     ├─ Branch: worktree-git-... (same name)
├─ Commit includes submodule    ├─ Actual code changes
│  pointer update (pinned SHA)  │
└───────────────────────────────┴───────────────────────────────

Detailed workflow:

```

2. Init submodule (arrives in detached HEAD — by design)

git submodule update --init --recursive

5. Push submodule FIRST (critical order)

cd flask_blogs git add -A && git commit -m "feat(#42): Add user auth" git push origin worktree-git-issue-42-add-user-authentication cd ..

6. Push agentcastle (includes submodule pointer update)

git add -A git commit -m "feat(#42): Add user auth" git push origin worktree-git-issue-42-add-user-authentication

**Why submodule must be pushed first:** The agentcastle commit records a specific submodule SHA. If that SHA only exists locally, teammates get `fatal: reference is not a tree`. The `push.recurseSubmodules check` config blocks the push if submodule commits haven't been pushed — a safety net, not a replacement for correct order.

**Why submodules start in detached HEAD:** Git submodules pin a specific commit, not a branch. `git submodule update` checks out that exact commit. You must explicitly checkout a branch to make editable changes — standard Git behavior.

**Result:** Two branches with same name exist:
- `agentcastle:worktree-git-issue-42-add-user-authentication`
- `flask_blogs:worktree-git-issue-42-add-user-authentication`

**Disk usage note:** Each worktree clones submodules independently (under `.git/worktrees/<name>/modules/`). Not shared across worktrees — known Git design tradeoff.

**Auditor PR creation order:**

Step 2 — Create main repo PR SECOND (includes submodule pointer): gh pr create --repo owner/agentcastle --base main --head <branch> --title "feat(#42): ..." --body "Closes #42"

#### 8.5 Quality Gates

Before transitioning `Implementation → Audit`, the supervisor runs two checks on the worktree:

**1. TSC Checkpoint** (`tsc-checkpoint` extension)
- Runs `npx tsc --noEmit` on the worktree
- Only runs if `tsconfig.json` exists
- Non-blocking if tsc binary not found

**2. LSP Pre-Audit** (`lsp-auditor` extension)
- Runs real LSP diagnostics on **modified files only** (git diff vs `defaultBranch`)
- Groups files by language server (TypeScript, Python, ESLint, etc.)
- Each group audited concurrently via separate LSP server process
- Auto-retries on errors (max 3 attempts), exponential backoff
- Only blocks if LSP server is available AND reports errors

**Decision table:**

| TSC | LSP | Outcome |
|-----|-----|---------|
| pass | pass | → Audit |
| pass | fail | → Implementation (retry LSP, max 3) |
| pass | N/A (no LSP) | → Audit |
| fail | (skipped) | → Implementation |
| N/A (no tsconfig) | pass | → Audit |

#### 8.6 Merge Conflict Resolution

After pipeline reaches `Done`, supervisor checks the created PR for merge conflicts:

#### 8.7 GitHub Interaction

The supervisor interacts with GitHub on every step:

| Action | Method | Purpose |
|--------|--------|---------|
| `gh issue view <N> --json ...` | pi.exec | Fetch issue data (pre-filtered to trusted codeowners) |
| `gh project view <projectNumber> ...` | pi.exec | Get field IDs for status options |
| `gh project item-list <projectNumber> ...` | pi.exec | Find issue's project item, read current status |
| `gh api graphql ...` (set status) | pi.exec | Move issue to next status on board |
| `gh issue comment <N> --repo <R> --body <B>` | pi.exec | Agent posts structured comment |
| `gh pr create --repo <R> --base <B> --head <H>` | pi.exec | Auditor creates PR on approval |
| `gh pr view <branch> --json ...` | pi.exec | Post-pipeline merge conflict check |

**Security:** All issue data is **pre-filtered** before reaching agents — only the body (if author is a codeowner) and comments from trusted codeowners are passed. The agent is explicitly instructed: "Use ONLY the issue data provided above. Do NOT run `gh issue view`." This prevents prompt injection via untrusted issue comments.

#### 8.8 Configuration Reference

All supervisor settings in `.pi/settings.json` under the `supervisor` key:

#### 8.9 Complete Walkthrough

Here's what happens end-to-end when you run `/supervisor 42`:

── Step 1: Fetch ──────────────────────────────────────────────── Supervisor reads .pi/settings.json → repo, project board, statuses Fetches issue #42 from GitHub, filters to trusted codeowners only Reads issue's current status from project board → "Research"

── Step 2: Researcher ─────────────────────────────────────────── Spins up agent with researcher system prompt + issue data Agent crawls 3-5 web pages about the issue topic Posts: gh issue comment 42 --repo owner/repo --body "## Research Findings..." Outputs: RESEARCH_COMPLETE Supervisor moves issue → "Architecture" on board

── Step 3: Architect ──────────────────────────────────────────── Spins up agent with architect prompt + issue + research findings Analyzes codebase using read, bash, structural_search, ripgrep_search Proposes architecture following Clean Architecture + PEAA principles Posts: gh issue comment 42 --body "## Architecture Approach..." Outputs: ARCHITECTURE_COMPLETE Supervisor moves issue → "TestDesign"

── Step 4: TestDesigner ───────────────────────────────────────── Spins up agent with test-designer prompt + issue + architecture Writes test plan: unit, integration, characterization tests Posts: gh issue comment 42 --body "## Test Plan..." Outputs: TEST_PLAN_COMPLETE Supervisor moves issue → "Implementation"

── Step 5: Developer ──────────────────────────────────────────── Supervisor creates worktree: git worktree add -b <branch> ../<branch> main Spins up agent with developer prompt + issue + arch + test plan, cwd=<worktree-path> Implements feature, runs tests, formats code git add -A && git commit -m "feat(#42): ..." git push origin <branch> Outputs: IMPLEMENTATION_COMPLETE

── Step 6: Quality Gates ──────────────────────────────────────── TSC: runs npx tsc --noEmit on worktree → pass LSP: runs diagnostics on modified files → pass Supervisor moves issue → "Audit"

── Step 7: Auditor ────────────────────────────────────────────── Spins up agent with auditor prompt + all previous data, cwd=<worktree-path> git diff main (reviews changes) Reviews against architecture + test plan Decision: APPROVED ✔ Creates submodule PRs if needed Creates main PR: gh pr create --repo owner/repo --head <branch> --title "feat(#42): ..." Posts: ## Audit Approved Outputs: AUDIT_APPROVED Supervisor moves issue → "Done"

── Step 8: Post-pipeline ──────────────────────────────────────── Checks PR for merge conflicts If conflicted → asks you if you want to auto-fix If yes → attempts auto-merge If auto-merge fails → dispatches Developer to resolve

── Done ───────────────────────────────────────────────────────── Issue #42 is complete with a PR ready for final review. ```

Note: The walkthrough above shows the updated pipeline: dependency gate, in-process agent execution (live TUI widget), architecture-before-research sequence, auditor summary file protocol, and post-pipeline merge conflict resolution.

---

9. Troubleshooting — Something broke

Container doesn't start

Rebuild the image without cache:

docker compose build --no-cache
./agent-castle.sh

Web crawl fails with Chromium errors

The extension auto-installs system libraries inside the container. If it persists:

rm -rf .pi/crawl4ai-venv .pi/chromium-deps    # Next call auto-recreates

Permission errors on bind-mounted files

UID/GID mapping is automatic via agent-castle.sh. If you need to run manually:

HOST_UID=$(id -u) HOST_GID=$(id -g) docker compose up

gh auth status shows "not logged in"

Inside the container, run:

gh auth login

Authenticate with Login with a web browser.

.piignore blocking legitimate paths

Edit .piignore and add a negation pattern:

!path/to/allow

---