5.3 KiB
status, parent, claimed-by, claimed-at, blocked-by, tags
| status | parent | claimed-by | claimed-at | blocked-by | tags | |
|---|---|---|---|---|---|---|
| resolved | 038-implement-skill-map | 019fbb66-80d0-7a01-8ac9-01255adfc7b2 | 2026-07-31T23:46:29-04:00 |
|
Implement skill Pi worktree extensions research
Question
What Pi extension APIs or examples are relevant if the migrated implement workflow should integrate with git worktrees or session/workspace automation?
Findings
Pi extensions can subscribe to lifecycle events, register custom tools, intercept tool calls, add commands, prompt users through ctx.ui, persist session state through entries, and customize rendering.
Extension use cases explicitly include git checkpointing, path protection, file watchers, external integrations, and CI triggers.
This means worktree integration is better suited to an optional Pi extension or external command than to static skill prose when automation needs session lifecycle hooks.
Source: /nix/store/rg248h9sz8dylm8p6a9w9fj4zrv4sgm5-pi-coding-agent-0.82.1/lib/node_modules/pi-monorepo/docs/extensions.md.
Pi extension placement supports global and project-local extensions, with project-local .pi/extensions loaded only after trust resolution.
A worktree integration that runs project-controlled setup commands must respect trust boundaries and should not make the implement skill silently load project-local automation.
Source: /nix/store/rg248h9sz8dylm8p6a9w9fj4zrv4sgm5-pi-coding-agent-0.82.1/lib/node_modules/pi-monorepo/docs/extensions.md.
Pi exposes session lifecycle hooks including session_before_switch, session_before_fork, session_shutdown, agent_end, and agent_settled.
These hooks are appropriate for guarding dirty repositories, releasing leases, updating status, or coordinating cleanup when a Pi session moves or exits.
A static skill cannot reliably perform those cleanup duties if the user abandons or forks the session mid-run.
Source: /nix/store/rg248h9sz8dylm8p6a9w9fj4zrv4sgm5-pi-coding-agent-0.82.1/lib/node_modules/pi-monorepo/docs/extensions.md.
The dirty-repo-guard.ts example blocks session changes when git status --porcelain shows uncommitted changes, defaulting to block in non-interactive mode and asking in UI-capable modes.
This is directly aligned with the old implement guardrail against automatic stashing or context switching over dirty work.
Source: /nix/store/rg248h9sz8dylm8p6a9w9fj4zrv4sgm5-pi-coding-agent-0.82.1/lib/node_modules/pi-monorepo/examples/extensions/dirty-repo-guard.ts.
The git-checkpoint.ts example creates git stash create checkpoints at each turn and offers to restore the code state when forking.
It demonstrates how Pi can bind source state to conversation entries, but it also relies on stash refs and UI choice rather than durable worktree leases.
The migrated implement skill should not depend on this for branch isolation, but a future extension could adapt the concept to record worktree lease state against session entries.
Source: /nix/store/rg248h9sz8dylm8p6a9w9fj4zrv4sgm5-pi-coding-agent-0.82.1/lib/node_modules/pi-monorepo/examples/extensions/git-checkpoint.ts.
The git-merge-and-resolve.ts example fetches and merges the upstream tracking ref after each agent turn only when the working tree is clean, and sends a follow-up user message listing conflict blocks when conflicts appear.
This shows Pi extensions can safely perform git maintenance and feed actionable conflict context back to the model, but automatic merge behavior is a separate policy decision from implementing one Wayfinder task.
Source: /nix/store/rg248h9sz8dylm8p6a9w9fj4zrv4sgm5-pi-coding-agent-0.82.1/lib/node_modules/pi-monorepo/examples/extensions/git-merge-and-resolve.ts.
The subagent extension example runs separate pi subprocesses with isolated contexts, supports parallel and chained workflows, and includes workflow prompts such as implement-and-review.
It can load user-level and trusted project-local agent definitions, and it warns that project-local agents are repo-controlled prompts.
This is relevant if implementation later becomes a visible multi-agent pipeline, but it is not required for a single-ticket skill.
Source: /nix/store/rg248h9sz8dylm8p6a9w9fj4zrv4sgm5-pi-coding-agent-0.82.1/lib/node_modules/pi-monorepo/examples/extensions/subagent/README.md.
Pi's docs and examples do not provide a built-in git worktree manager in the inspected extension set.
They provide the extension hooks and subprocess execution APIs needed to integrate external managers such as Treehouse, Herdr, or raw git worktree.
Sources: /nix/store/rg248h9sz8dylm8p6a9w9fj4zrv4sgm5-pi-coding-agent-0.82.1/lib/node_modules/pi-monorepo/docs/extensions.md, rg "worktree" /nix/store/rg248h9sz8dylm8p6a9w9fj4zrv4sgm5-pi-coding-agent-0.82.1/lib/node_modules/pi-monorepo/docs /nix/store/rg248h9sz8dylm8p6a9w9fj4zrv4sgm5-pi-coding-agent-0.82.1/lib/node_modules/pi-monorepo/examples/extensions.
Conclusion
Pi supports worktree-adjacent automation through extensions, but not a built-in worktree manager in the inspected docs and examples.
Since parallel Wayfinder implementation needs isolated working trees, the migrated implement workflow should plan for worktree acquisition as a real execution concern.
Dirty-repo guards, lease cleanup, visible Herdr panes, and multi-agent execution can still live in extensions or external tools unless the package-scope decision pulls them into the skill itself.