60 lines
5.3 KiB
Markdown
60 lines
5.3 KiB
Markdown
---
|
|
status: resolved
|
|
parent: "[[038-implement-skill-map]]"
|
|
claimed-by: "019fbb66-80d0-7a01-8ac9-01255adfc7b2"
|
|
claimed-at: "2026-07-31T23:46:29-04:00"
|
|
blocked-by: []
|
|
tags:
|
|
- ticket/research
|
|
---
|
|
|
|
# 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.
|