ai-artifacts/projects/dotfiles/026-pi-subagents-dotfiles-deployment-task.md

status, claimed-by, claimed-at, completed-at, parent, blocked-by, tags

status	claimed-by	claimed-at	completed-at	parent	blocked-by	tags
done	019fba91-eabf-76ae-b086-a37ac061d6e8	2026-07-31T21:17:55-04:00	2026-07-31T21:18:12-04:00	002-pi-subagents-map		ticket/task/afk

Dotfiles deployment seam

Question

Define the dotfiles deployment seam for the new Pi subagent extension, including development placement, flake-managed promotion, configuration files, and verification commands needed before implementation starts.

Result

The extension should be developed as a Pi extension under modules/agents/pi/extensions/subagents/ and deployed by the existing Home Manager file link from modules/agents/pi/pi.nix to ~/.pi/agent/extensions. Finished work must be promoted through the dotfiles module before it counts as deployed. Direct files under ~/.pi/agent/extensions are acceptable only for throwaway development or local experiments. This matches the repository gotcha that flake-managed Pi extension, prompt, and skill directories may be written directly for experiments but durable deployment must go through the dotfiles module. Source: /home/alexion/wrk/dotfiles/AGENTS.md.

No install step should be part of the implementation plan without explicit user consent. The durable path should avoid pi install, npm package installation, or git package installation for version one. If runtime dependencies become unavoidable, the implementation spec must pause for consent and then model the dependency declaratively in Nix rather than asking Pi to install it interactively. Source: user constraint and Pi package security docs in /nix/store/rg248h9sz8dylm8p6a9w9fj4zrv4sgm5-pi-coding-agent-0.82.1/lib/node_modules/pi-monorepo/docs/packages.md.

Current Pi deployment shape

modules/agents/pi/pi.nix enables programs.pi-coding-agent through Home Manager. It writes Pi settings with defaultProvider, defaultModel, defaultThinkingLevel, theme, and telemetry choices. It force-manages ~/.pi/agent/settings.json but intentionally leaves login credential state unmanaged. Source: modules/agents/pi/pi.nix.

The same module recursively links modules/agents/pi/extensions to ~/.pi/agent/extensions. It also recursively links modules/agents/pi/prompts to ~/.pi/agent/prompts. Source: modules/agents/pi/pi.nix.

The current modules/agents/pi/extensions directory contains only .gitkeep. That means a new extension can be added there without colliding with existing Pi extension code. Source: find modules/agents/pi -maxdepth 3 -type f during this task.

Pi's extension docs say global extensions are auto-discovered from ~/.pi/agent/extensions/*.ts and ~/.pi/agent/extensions/*/index.ts. Project-local extensions are auto-discovered from .pi/extensions/*.ts and .pi/extensions/*/index.ts after project trust. Source: /nix/store/rg248h9sz8dylm8p6a9w9fj4zrv4sgm5-pi-coding-agent-0.82.1/lib/node_modules/pi-monorepo/docs/extensions.md.

Pi can hot-reload auto-discovered extension locations with /reload. Source: /nix/store/rg248h9sz8dylm8p6a9w9fj4zrv4sgm5-pi-coding-agent-0.82.1/lib/node_modules/pi-monorepo/docs/extensions.md.

Proposed repository layout

Use this layout for version one:

modules/agents/pi/extensions/subagents/
├── index.ts
├── agents.ts
├── config.ts
├── runner.ts
├── supervisor.ts
├── status.ts
├── types.ts
└── ui.ts

index.ts should be the extension entry point and should export the default Pi extension factory. agents.ts should load and validate named agent definitions. config.ts should resolve extension settings and default policy. runner.ts should implement the subprocess RPC ChildRunner. supervisor.ts should own child records, lifecycle, cancellation, timers, and concurrency. status.ts should define parent-session entries and renderable status data. types.ts should hold shared TypeScript types. ui.ts should isolate optional TUI/RPC status and confirmation helpers.

Keep filenames lowercase. This follows the user's global filename preference and the repository convention. Source: /home/alexion/.pi/agent/AGENTS.md and /home/alexion/wrk/dotfiles/AGENTS.md.

Do not add a package.json unless implementation discovers an unavoidable external runtime dependency. Pi extensions can import Pi-provided packages such as @earendil-works/pi-coding-agent, @earendil-works/pi-ai, @earendil-works/pi-tui, and typebox directly. Source: /nix/store/rg248h9sz8dylm8p6a9w9fj4zrv4sgm5-pi-coding-agent-0.82.1/lib/node_modules/pi-monorepo/docs/extensions.md.

Agent definition deployment seam

The extension should load user-level agent definitions from ~/.pi/agent/agents/ and project-level definitions from .pi/agents/ after trust. Because the current dotfiles module does not link modules/agents/pi/agents, add this managed directory when real agent definitions are committed. The module should link it recursively to ~/.pi/agent/agents in the same style as extensions and prompts.

Proposed durable layout:

modules/agents/pi/agents/
└── .gitkeep

Proposed Nix addition when needed:

"${piDir}/agents" = {
  source = ./agents;
  recursive = true;
};

The initial extension should not ship opinionated agent definition files. The directory can contain .gitkeep only until the user intentionally adds named agents. This satisfies the constraint that named agents, prompts, and policy belong in Pi config rather than the neutral extension.

Settings seam

Do not add extension-specific settings to programs.pi-coding-agent.settings until the implementation schema is finalized. When settings are needed, keep them under a clearly namespaced key such as subagents only if Pi preserves unknown settings for extension consumption. If Pi's typed settings reject unknown keys, store extension config in a separate user-level file such as ~/.pi/agent/subagents.json and manage it through Home Manager home.file. The implementation spec must verify Pi's settings parser behavior before choosing this.

Recommended initial defaults should live in extension code and be neutral:

• Runtime: subprocess-rpc.
• Max concurrent children: 2 or 3.
• Default context: unresolved by 022-pi-subagents-context-modes-grill.
• Project agents: disabled until project trust is confirmed.
• Project extension inheritance: disabled.
• Nested children: disabled.
• Tool policy: minimal and explicit.

Do not encode opinionated subagent types in settings. Do not add Herdr settings to the Pi extension seam. Herdr remains an optional later adapter and should not shape the core deployment.

Development workflow

For quick experiments, it is acceptable to copy or create a throwaway extension directly under ~/.pi/agent/extensions/subagents/. That is not durable and may be overwritten or hidden by Home Manager activation. Source: /home/alexion/wrk/dotfiles/AGENTS.md gotcha about flake-managed Pi directories.

For implementation work that should persist, edit modules/agents/pi/extensions/subagents/ in the repository. Then reload Pi or rebuild Home Manager depending on whether the current session sees the repository path through the existing symlink. Because modules/agents/pi/pi.nix recursively links the entire extensions directory, editing the source tree should normally be enough for /reload in the running Pi session to see the change. A rebuild is required to verify clean-machine deployment.

Use pi -e ./path.ts only for quick tests of an isolated file. The Pi docs identify -e as a quick-test path and say auto-discovered global or project locations are the right placement for /reload. Source: /nix/store/rg248h9sz8dylm8p6a9w9fj4zrv4sgm5-pi-coding-agent-0.82.1/lib/node_modules/pi-monorepo/docs/extensions.md.

Verification commands

Use these checks before implementation starts:

nix eval .#nixosConfigurations.neogaia.config.modules.agents.pi.enable

Expected result: true. This verifies the Pi module is enabled for the current host.

nix eval .#nixosConfigurations.neogaia.config.home-manager.users.alexion.home.file.'"/home/alexion/.pi/agent/extensions"'.source

Expected result: a Nix store path sourced from modules/agents/pi/extensions after evaluation. This verifies the deployment link remains declared.

nix eval .#nixosConfigurations.neogaia.config.home-manager.users.alexion.home.file.'"/home/alexion/.pi/agent/prompts"'.source

Expected result: a Nix store path sourced from modules/agents/pi/prompts. This is a control check matching the existing prompt link.

After adding modules/agents/pi/agents, add and run this check:

nix eval .#nixosConfigurations.neogaia.config.home-manager.users.alexion.home.file.'"/home/alexion/.pi/agent/agents"'.source

Expected result: a Nix store path sourced from modules/agents/pi/agents.

Use the repository's primary verification seam before merging implementation:

nix flake check

The project gotcha says nix flake check builds checks.x86_64-linux.<host> and is the primary build/verify seam for any host. Source: /home/alexion/wrk/dotfiles/AGENTS.md.

For cheap targeted evaluation during implementation, use nix eval .#nixosConfigurations.neogaia.config... rather than committing speculative host enablement. Source: /home/alexion/wrk/dotfiles/AGENTS.md.

Runtime verification after implementation

Use these manual checks after the extension exists:

pi --mode rpc --no-session

Then send a minimal JSONL prompt and confirm the process speaks RPC. This verifies the child runtime target independently of the extension. Source: Pi RPC docs in /nix/store/rg248h9sz8dylm8p6a9w9fj4zrv4sgm5-pi-coding-agent-0.82.1/lib/node_modules/pi-monorepo/docs/rpc.md.

Inside Pi, run /reload after editing the managed extension source and confirm the extension reloads without restarting Pi. This verifies the global extension discovery path. Source: Pi extension docs in /nix/store/rg248h9sz8dylm8p6a9w9fj4zrv4sgm5-pi-coding-agent-0.82.1/lib/node_modules/pi-monorepo/docs/extensions.md.

After adding a status renderer, spawn a trivial read-only child and verify these properties:

• Parent transcript receives a compact status entry.
• Child transcript or session remains separate.
• Cancelling the parent tool call cancels the child.
• The child exits or is killed on timeout.
• No project-local agent definition loads before project trust.
• No Herdr-specific behavior is required.

Files to change during implementation

Expected durable changes:

• modules/agents/pi/extensions/subagents/index.ts.
• modules/agents/pi/extensions/subagents/*.ts helper files.
• modules/agents/pi/agents/.gitkeep if the managed user-agent directory is introduced.
• modules/agents/pi/pi.nix only if the agents directory or extension config file is linked.

Avoid these changes unless explicitly justified:

• Do not edit ~/.pi/agent directly for durable deployment.
• Do not modify generated Home Manager output.
• Do not install Pi packages with pi install.
• Do not add Herdr-specific config to the Pi module for version one.
• Do not add named opinionated subagents to the neutral extension.

Open implementation questions

The implementation spec still needs decisions from 021-pi-subagents-config-boundary-grill and 022-pi-subagents-context-modes-grill. The status UI details still depend on 023-pi-subagents-status-ui-prototype. This deployment seam is therefore ready for implementation planning but not by itself sufficient to start coding the extension.