choco-pi

choco-pi is a private Pi package that turns the Pi coding agent into a more opinionated local work environment. It installs runtime extensions, two skills, prompt templates, work-mode policies, persistent state, and tests for those pieces.

한국어 README

This README describes implemented behavior only. It is based on package.json, the extension code, and the current tests.

Status

• Current package version: 0.18.4.
• License field: UNLICENSED.
• Package manager: pnpm@10.29.3.
• Main peer runtime: @earendil-works/pi-coding-agent.
• Default verification script: pnpm run check.

What choco-pi adds

choco-pi is not a standalone app. Pi loads it through the pi field in package.json.

Surface	Loaded entries
Extensions	extensions/choco-autopilot/index.ts, extensions/input-newline/index.ts, extensions/todo-widget.ts, extensions/choco-footer/index.ts, extensions/choco-header/index.ts, extensions/fff-search/index.ts, node_modules/pi-lsp-client/src/index.ts, extensions/focus-rendering/index.ts, extensions/raw-paste/index.ts, extensions/btw.ts
Skills	skills/choco-autopilot, skills/prd-architect
Prompts	prompts/

At runtime, those entries provide:

• an autopilot policy layer for planning, execution, verification, memory, ledgers, source tracking, reloads, updates, and quality gates;
• an autonomous protocol runtime that routes prompts to branch/micro-coding/coding/parallel/lane/integration/approval flows, preserves long-running protocol continuity, and tracks required tool satisfaction;
• a session/project todo tool and /todos UI;
• custom header and footer rendering;
• FFF-backed grep, find, and multi_grep tools;
• compact focused tool-output rendering;
• raw paste and multiline extension input behavior;
• a Korean-localized /btw side-conversation overlay;
• an LSP client extension loaded from pi-lsp-client.

Fresh environment setup

Install the GitHub package after the target revision has been pushed:

pi install git:github.com/ddotz/choco-pi

Install from a local checkout:

git clone https://github.com/ddotz/choco-pi.git /absolute/path/to/choco-pi
cd /absolute/path/to/choco-pi
pnpm install --frozen-lockfile
pnpm run check
pi install /absolute/path/to/choco-pi

Reload an already running Pi session after installation:

/reload-runtime

Runtime behavior

Autopilot policy

extensions/choco-autopilot/index.ts is the main extension. It appends the choco-pi policy prompt during agent startup and installs tools/commands for structural review, dynamic SDD, autonomous protocol routing, source tracking, parallel-work planning, runtime reloads, memory, ledgers, dogfood capture, updates, and work-mode control.

The implemented policy includes these defaults:

• User-facing replies are Korean by default unless the user asks for another language.
• Replies should use respectful Korean.
• Do not use praise or validation openers.
• Do not end replies with suggestion-led opt-in phrasing.
• New Pi feature work should check https://pi.dev/packages before building from scratch. If a high-similarity package exists, inspect its source, license, and security before reuse.
• Mode isolation is mandatory for every work mode.
• No mode may change default or any other mode as a side effect.
• Completion claims require observable verification and a structural review when work is non-trivial.
• Prompt intent is routed into an autonomy protocol when branch, micro-coding, coding, report-research, parallel, worktree-lane, integration, or approval-boundary behavior is needed.
• Approval-boundary routing is execution-intent aware: PRDs, examples, non-goals, and do-not-deploy wording can mention deploy/publish without blocking the whole implementation turn.
• Required protocol tools are tracked from tool results; structural_gate fails closed when completion is attempted before required tools are satisfied and repair prompts name the protocol kind plus the next required action.
• Long-running parallel/worktree/integration protocols survive continuation prompts until the manifest is closed/integrated or the task is superseded.

Autonomous protocol runtime

Protocol	Required completion tools	Notes
micro-coding	structural_gate	For small typo, wording, rename, or one-line edits. It avoids spec_gate ceremony while keeping completion safety.
single-branch	branch_switch_guard, structural_gate	Branch names are validated before Git commands and dirty/occupied worktrees block unsafe switching.
coding	spec_gate, structural_gate	Non-trivial implementation keeps Working Spec + final structural review.
ulw	spec_gate, ulw_harness, structural_gate	Explicit ulw/ultrawork requests and deep autonomous harness prompts preserve markdown context, evidence, and tmux QA artifacts before completion.
report-research	spec_gate, report_research_gate, structural_gate	Report requests require an active evidence-scope decision: run right-sized web-analysis for current/external/source-backed claims, or record a no-external-research boundary when research is forbidden or unnecessary.
parallel-work	spec_gate, parallel_work_plan, agent_orchestrator, worktree_manage, integration_verifier, structural_gate	Requires ownership planning, manifest orchestration, worktree lifecycle, and final integration evidence.
worktree-lane	agent_orchestrator, worktree_manage, write_scope_guard, structural_gate	Active lane activation is blocked for planned/blocked/failed/verified/integrated/serial lanes and invalid writable worktree lanes.
integration	integration_verifier, structural_gate	Verification commands are allowlisted and pnpm --dir must stay inside the integration cwd.
approval-boundary	none before boundary	Stops before deploy/publish/payment/secret/destructive/private-transfer boundaries with blocked/deferred completion.

/sessions shows the current protocol, missing/blocked required tools, active lane, manifests, branch, mode, and worktrees. Manifest discovery uses the Git repo root, so subdirectory cwd sessions still show repo-level .pi/agent-runs.

Work modes and intensity

Built-in work modes are defined in extensions/choco-autopilot/mode.ts and documented in modes/.

Mode	Purpose
default	Root all-purpose policy baseline. It can apply specialized modes as temporary session-scoped overlays.
coding	TDD-first implementation, debugging, refactoring, and coding quality guard.
report	Evidence-led report writing with active web-analysis scoping, report_research_gate provenance, source confidence review, and report quality guard.
design	Product/UI design work with design quality guard.
web-analysis	Retrieval-first external research with web research quality guard.
adoption-analysis	External source/package/repo adoption review with adoption quality guard.

Execution intensity is a process-weight setting. The implemented values are micro, standard, and deep.

/mode add registers custom modes as planned. The built-in code does not make arbitrary custom modes executable work modes.

Skills

skills/choco-autopilot documents the autonomous execution flow used by the main prompt and extension.

skills/prd-architect handles PRD, product-requirements, and planning-document work. PRD Architect does not replace brainstorming. Its routing is:

• fuzzy idea: explore or brainstorm first, then converge into a PRD;
• clear direction: use prd-architect directly;
• existing PRD: use prd-architect directly for critique, gap analysis, or strengthening.

Tools and commands

Tools

Tool	Implemented in	Purpose
spec_gate	dynamic-sdd.ts	Start/list/clear a turn-local Working Spec, record Spec Deltas, and take snapshots.
loop_transition	structural-gate.ts	Record deliberate plan/todo boundary transitions.
structural_gate	structural-gate.ts	Record final acceptance, runtime, failure-mode, verification, loop, and completion review.
ulw_harness	ulw-harness-tool.ts	Start/read ULW markdown context, record evidence, and capture tmux-managed QA transcripts under .pi/ulw/<sessionId>/.
report_research_gate	report-research-gate.ts	Record report objective, user materials, external source provenance, source confidence review, conflicts, evidence gaps, or explicit no-external-research boundary.
source_registry	index.ts	Manage external sources with list/add/watch/adopt/reject/due/changed/check actions.
branch_switch_guard	branch-switch-guard.ts	Safely switch the current session cwd to a branch after dirty-state and worktree occupancy checks.
parallel_work_plan	parallel-work-plan-tool.ts	Produce a collision-avoidance plan before writable parallel work.
worktree_manage	worktree-manage-tool.ts	Plan, create, list, inspect, hand off, merge-check, and clean-remove isolated git worktrees.
agent_orchestrator	agent-orchestrator-tool.ts	Start, dispatch, update, summarize, and close manifest-backed parallel agent runs.
integration_verifier	integration-verifier-tool.ts	Run final integration verification for manifest-backed parallel lanes before completion.
mode_scaffold	mode-scaffold-tool.ts	Generate planned or implementation-stub files for isolated work modes.
Active lane write guard	index.ts, write-scope-guard.ts	Guard active-lane writes from cwd/session-scoped state and record bash post-diff scope violations.
reload_runtime	runtime-reload.ts	Reload Pi runtime resources directly or through tmux self-input fallback.
todo	todo-widget.ts	Manage session or project todo files.
grep, find, multi_grep	fff-search/index.ts	Search files and content through FFF-backed tools.

Slash commands

Command	Behavior
/mode	Open the selector or manage modes with status, list, set, add, and remove; status shows persistent mode, effective session overlay, automatic overlay state, and effective intensity.
/sessions	Show current session, cwd, branch, mode, todos, compact ledger summary, autonomy protocol status/hard boundary, active lane, manifests, and worktrees.
/ulw	Start or inspect the ULW harness context; /ulw start <objective> creates project-local markdown context and /ulw status shows it.
/intensity	Show or set micro, standard, or deep; status shows persistent intensity and effective session intensity.
/effort	Show or set supported model effort levels.
/source	Manage source registry records.
/memory	List memories or save a durable memory candidate.
/ledger	Show, reset, or add structured current cwd/session ledger entries with `add assumption
/dogfood	Show dogfood status, weekly report, latest report, queue length, or case explanation.
/update	Run Pi update flows, run choco-pi self-update, or manage auto-update status.
/reload-runtime	Reload extensions, skills, prompts, and themes.
/todos	Open the current session todo UI.
/paste	Arm or cancel raw paste mode.
/btw*	Manage Korean-localized side conversations.
/fff-*	Manage FFF search mode, health, and rescan.

State and data

Runtime state

The main state file is:

~/.pi/agent/choco-pi/state.json

The current state schema version is 5. The state object stores:

• runtime: persistent work mode and execution intensity;
• sessions: per-session effective work mode, suggested mode, automatic-mode flag, execution intensity, and timestamp;
• activeLanes: cwd/session-scoped active lane write-guard state;
• autonomyProtocols: cwd/session-scoped prompt protocol, required tools, satisfied tools, and blocked tool state;
• memories: durable facts saved through /memory;
• ledgers: cwd/session keyed context ledgers;
• sourceRegistry: external source tracking records;
• workModeRegistry: built-in and custom work-mode metadata;
• autoUpdate: choco-pi auto-update settings and the last result.

The autonomy protocol state is created or resumed at agent start from the latest prompt, active manifests, active lanes, and previous protocol lifecycle status. Tool results update satisfaction automatically; blocked required tools or missing protocol tools prevent ready completion through structural_gate. Active blocked protocols expose their status and hard boundary in /sessions; completed and superseded protocols are hidden from the active /sessions summary and pruned by recent-audit retention.

The context ledger tracks objective, assumptions, decisions, changed files, verifications, blockers, risks, and next actions. Automatic ledger updates record write/edit paths and verification-like bash results; /ledger add records explicit assumptions, decisions, blockers, risks, and next actions, and /sessions shows a compact ledger summary.

ULW harness storage

The ulw_harness tool stores project-local markdown state for the current session:

<cwd>/.pi/ulw/<sessionId>/context.md
<cwd>/.pi/ulw/<sessionId>/ledger.md
<cwd>/.pi/ulw/<sessionId>/evidence/*.txt

context.md keeps objective, criteria, plan, and next actions. ledger.md records start/evidence/tmux-test events with cleanup receipts. tmux-test evidence files contain captured pane output from a real tmux session.

Todo storage

The todo tool stores todos in the current cwd by default:

<cwd>/.pi/sessions/<sessionId>/todos.json

Project-shared todos use:

<cwd>/.pi/todos.json

Todo writes are schema-validated, serialized by path-level async locks, and written with atomic temp-file rename. Active todos are protected from accidental remove/clear unless force=true is supplied.

Source tracking

Source tracking is implemented in source-registry.ts and exposed through /source and source_registry.

• Source kinds: github, url.
• Statuses: candidate, watching, adopted, rejected.
• GitHub checks use git ls-remote <repo> HEAD.
• Non-GitHub URL checks return a message that model-led analysis is required.
• session_start checks up to five due GitHub sources and updates stored metadata.

Dogfood data

Dogfood capture is controlled by CHOCO_PI_IMPROVEMENT_MODE and CHOCO_PI_IMPROVEMENT_PROFILE. When enabled, case records are stored under:

~/.pi/agent/choco-pi/dogfood/

The collector stores salted prompt hashes, scope metadata, work mode, intensity, sanitized flow signals, tool counts, verification signals, structural-gate signals, and deterministic outcome fields. It does not store raw prompt text in the case record.

Development

Install dependencies:

pnpm install --frozen-lockfile

Run the full project gate:

pnpm run check

pnpm run check expands to:

pnpm run version:check && pnpm run lint && pnpm run typecheck && pnpm run test

Available scripts:

pnpm run version:check
pnpm run lint
pnpm run typecheck
pnpm run test
pnpm run check

scripts/check-version-sync.ts verifies that package.json, extensions/choco-autopilot/version.ts, and the README current-version line stay synchronized.

Repository map

extensions/choco-autopilot/   # main policy/state/guard/update/source/dogfood extension
extensions/choco-footer/      # footer formatting and runtime hooks
extensions/fff-search/        # FFF-backed find/grep/multi_grep
extensions/focus-rendering/   # focused tool-output rendering patch
extensions/input-newline/     # multiline extension prompt behavior
extensions/raw-paste/         # raw paste editor mode
extensions/btw.ts             # Korean side-conversation overlay
modes/                        # built-in mode policy files
skills/                       # choco-autopilot and prd-architect skills
prompts/                      # prompt templates
tests/                        # subsystem tests
scripts/check-version-sync.ts # version consistency check