<!-- pi_agent_rust installer managed skill -->

Pi Agent Rust

Use This Skill When

• You are working inside pi_agent_rust and need the fastest path to safe, verified edits.
• You are touching provider/tool/session/extension behavior and need targeted triage.
• You are changing installer/uninstaller/skill install behavior and need deterministic safety checks.
• You need symptom-first debugging playbooks instead of ad-hoc command hunting.

60-Second Bootstrap

bash
export CARGO_TARGET_DIR="/data/tmp/pi_agent_rust/${USER:-agent}"
export TMPDIR="/data/tmp/pi_agent_rust/${USER:-agent}/tmp"
mkdir -p "$TMPDIR"

rch exec -- cargo check --all-targets
rch exec -- cargo clippy --all-targets -- -D warnings
cargo fmt --check
bash tests/installer_regression.sh

Symptom Router

| Symptom | First 3 Commands | |---|---| | Provider stream/tool-call regression | cargo test provider_streaming -- --nocapture ; rg -n "stream|tool|delta|event|SSE" src/providers src/sse.rs ; cargo test conformance | | Session replay/index drift | cargo test session -- --nocapture ; rg -n "Session|save|open|index|jsonl|sqlite" src/session.rs src/session_index.rs ; cargo test conformance | | Extension policy/runtime failure | cargo test extension -- --nocapture ; rg -n "policy|hostcall|capability|quickjs|deny|allow" src/extensions.rs src/extensions_js.rs ; cargo test conformance | | Installer/uninstaller/skill issue | bash tests/installer_regression.sh ; rg -n "AGENT_SKILL_STATUS|CHECKSUM_STATUS|SIGSTORE_STATUS|COMPLETIONS_STATUS" install.sh ; rg -n "managed skill|expected skill directory|PIAR_AGENT_SKILL" uninstall.sh | | Interactive vs RPC divergence | cargo test e2e_rpc -- --nocapture ; rg -n "interactive|rpc|stdin|event|session" src/main.rs src/interactive.rs src/rpc.rs ; cargo test conformance |

For deeper diagnosis, use references/DEBUGGING-PLAYBOOKS.md.

Non-Negotiables

• Read AGENTS.md first, then follow it exactly.
• Do not delete files or run destructive git/filesystem commands.
• Keep edits in-place; avoid creating variant files for the same purpose.
• Use main semantics in docs/scripts; do not introduce master.
• Prefer rg for fast text recon and ast-grep for structural matching/refactors.
• Prefer rch exec -- <cargo ...> for heavy compile/test workloads.
• After substantive edits, run compile/lint/format gates and the smallest relevant regression slice.

Core Workflow

• ] Recon: identify exact change surface and invariants.
• ] Implement: minimal, behavior-focused patch with explicit failure semantics.
• ] Validate: targeted tests first, broaden only as needed.
• ] Verify UX: error/status output is explicit, stable, and non-ambiguous.
• ] Sync docs: update README.md when flags/behavior/user guidance changed.

Changed Files -> Required Tests

| Changed Files (examples) | Minimum Required Tests | |---|---| | install.sh, uninstall.sh, .claude/skills/pi-agent-rust/** | bash -n install.sh uninstall.sh tests/installer_regression.sh ; shellcheck -x install.sh uninstall.sh tests/installer_regression.sh ; bash tests/installer_regression.sh ; bash scripts/skill-smoke.sh | | src/providers/**, src/provider.rs, src/sse.rs | cargo test provider_streaming ; cargo test conformance | | src/session.rs, src/session_index.rs, src/session_test.rs | cargo test session ; cargo test conformance | | src/extensions.rs, src/extensions_js.rs | cargo test extension ; cargo test conformance | | src/tools.rs | cargo test tools ; cargo test conformance | | src/interactive.rs, src/rpc.rs, src/main.rs | cargo test e2e_rpc ; cargo test conformance |

Do Not Run Yet

Run these only after targeted repro + focused slice indicates need:

• Broad cargo test across entire workspace when a narrower slice already reproduces.
• Heavy multi-surface runs before confirming changed-file impact.
• Repeated full conformance loops while the core failing slice is still unstable.

High-Value Commands

bash
# Fast recon
git status --short
rg -n "install|uninstall|skill|checksum|sigstore|completion|provider|session|extension" \
  install.sh uninstall.sh README.md tests/installer_regression.sh src/

# Installer + skill safety gates
bash -n install.sh uninstall.sh tests/installer_regression.sh
shellcheck -x install.sh uninstall.sh tests/installer_regression.sh
bash tests/installer_regression.sh
bash scripts/skill-smoke.sh

# Rust gates
rch exec -- cargo check --all-targets
rch exec -- cargo clippy --all-targets -- -D warnings
cargo fmt --check

For an expanded command cookbook, see references/COMMANDS.md. For deep incident triage, see references/DEBUGGING-PLAYBOOKS.md.

Critical Files

• src/main.rs: CLI entry and mode dispatch.
• src/agent.rs: agent loop and tool iteration behavior.
• src/provider.rs: provider trait contract.
• src/providers/: provider implementations and factory wiring.
• src/tools.rs: built-in tools (read, write, edit, bash, grep, find, ls).
• src/session.rs: JSONL session persistence.
• src/session_index.rs: session index and metadata cache.
• src/extensions.rs + src/extensions_js.rs: extension policy and QuickJS bridge.
• src/interactive.rs + src/rpc.rs: TUI and RPC/stdin surfaces.
• install.sh + uninstall.sh: install lifecycle, migration, and skill management.
• tests/installer_regression.sh: installer regression harness.
• scripts/skill-smoke.sh: skill integrity + inline-sync validation.

Known Footguns

• Custom artifact install paths without compatible release context can fall back incorrectly if not explicitly guarded.
• Skill status can become misleading on mixed outcomes unless partial/failure branches are explicit.
• Uninstall logic must enforce both marker checks and expected destination path shape.
• Installer progress/status text should stay on stderr when stdout is used for data plumbing.
• Bundled skill and inline fallback can silently drift unless explicitly checked.

Patch Patterns

Pattern 1: Mixed Outcome Status Clarity

bash
# BEFORE: everything collapsed into "skipped custom"
if [ "$skipped_custom" -ge 1 ]; then
  AGENT_SKILL_STATUS="skipped (existing custom skill)"
fi

# AFTER: distinguish custom-skip from write failure
if [ "$skipped_custom" -ge 1 ] && [ "$failed_writes" -ge 1 ]; then
  AGENT_SKILL_STATUS="partial (custom skill kept; other install failed)"
elif [ "$skipped_custom" -ge 1 ]; then
  AGENT_SKILL_STATUS="skipped (existing custom skill)"
fi

Pattern 2: Safe Skill Replacement

bash
# BEFORE: remove destination before validating copy result
rm -rf "$destination"
cp "$source" "$destination/SKILL.md"

# AFTER: stage then atomically move into place
staged="$(mktemp -d ...)"
cp "$source" "$staged/SKILL.md"
mv "$staged" "$destination"

Failure Triage

• Installer summary/status mismatch:

trace AGENT_SKILL_STATUS, CHECKSUM_STATUS, and COMPLETIONS_STATUS in install.sh.

• Install/uninstall safety concern:

verify marker checks and expected destination guards in both scripts.

• Provider/session/extension regressions:

use symptom router, then follow references/DEBUGGING-PLAYBOOKS.md.

• Docs drift:

ensure README.md flags/examples match current installer behavior.

Done Criteria

• Changed-file matrix minimum tests passed.
• Compile/lint/format checks passed for touched surfaces.
• Installer/skill changes pass tests/installer_regression.sh and scripts/skill-smoke.sh.
• Behavior is explicit on failure paths; no silent fallback surprises.
• Skill docs and inline fallback remain aligned and current.