alexion/ai-artifacts

Fork 0

Files

alexion 3230f9395b Add artifact vault contents

2026-08-01 14:05:09 -04:00

5.5 KiB

Raw Blame History

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

status

claimed-by

claimed-at

completed-at

parent

blocked-by

Pi subagents Nix config seam

Question

After the subagent configuration schema is settled, what Nix/Home Manager seam should deploy subagents.json, managed user agent definitions, and any related defaults without making the neutral extension Nix-aware?

Result

Detailed dotfiles module option design is out of scope for the subagent extension specification. This repository's Pi module can later decide whether to link plain files, render JSON from Nix attrs, or expose typed modules.agents.pi.subagents options. The implementation-ready extension spec should only require stable runtime file paths and should not prescribe the dotfiles module's internal interface.

Keep the extension Nix-unaware. The extension reads Pi-native runtime files:

Global extension config: ~/.pi/agent/subagents.json.
Trusted project extension config: .pi/subagents.json through Pi's CONFIG_DIR_NAME.
Global named agent definitions: ~/.pi/agent/agents/*.md.
Trusted project named agent definitions: .pi/agents/*.md through Pi's CONFIG_DIR_NAME.

The dotfiles module may choose to manage the global files declaratively, but the extension should not know or care whether they came from Home Manager, direct user edits, or another deployment tool. This matches the configuration boundary from 021-pi-subagents-config-boundary-grill.

Do not create or manage ~/.pi/agent/subagents.json until the user has actual overrides to declare. The extension has in-code neutral defaults and must not write a default config file automatically. A missing subagents.json is therefore a valid, expected state.

When global overrides are wanted, the dotfiles Pi module may manage the runtime JSON file however the module owner prefers. A plain source file such as modules/agents/pi/subagents.json is a simple option, but it is not mandated. Rendering the JSON from Nix attrs or adding typed module options is a dotfiles-module decision, not an extension-spec decision. Do not make any particular Nix option interface a prerequisite for version one.

Do not link ~/.pi/agent/agents until there are durable user agent definitions to manage. An empty Home Manager-managed agent directory would make direct local experiments under ~/.pi/agent/agents awkward, because Home Manager would own the path. Until durable agent definitions exist, leave the directory unmanaged so the user can create throwaway local agents freely. When durable agent definitions are added, create:

modules/agents/pi/agents/

and link it with:

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

The first managed agents/ rollout should include only user-intended Markdown agent definitions. Do not add opinionated bundled agents as part of the neutral extension.

Current module implications

modules/agents/pi/pi.nix already manages ~/.pi/agent/settings.json, ~/.pi/agent/extensions, and ~/.pi/agent/prompts. It intentionally leaves login credential state unmanaged. Source: modules/agents/pi/pi.nix.

The implementation spec should extend that module only when there is an actual file or directory to deploy. The extension code itself should still live under:

modules/agents/pi/extensions/subagents/

and the existing recursive extension link will deploy it. No package installation or pi install path is needed for version one.

Recommended version-one Nix stance

Only the deployment paths are in scope here:

modules/agents/pi/extensions/subagents/ for the extension implementation.
~/.pi/agent/subagents.json as the optional runtime config target.
~/.pi/agent/agents/*.md as the optional global named-agent target.

Avoid these in the extension specification:

Prescribing typed modules.agents.pi.subagents.* options.
Prescribing a plain-file versus generated-json module implementation.
Requiring a generated default subagents.json when no overrides exist.
Requiring an empty managed ~/.pi/agent/agents directory.
Nix-aware logic in the extension.
pi install or package-manager-managed Pi packages.

Verification commands

Before implementation, existing checks still apply:

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

Expected result: true.

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.

If the dotfiles module later manages subagents.json or agents/, verify the resulting Home Manager file entries with targeted nix eval commands chosen for that module implementation. The exact attr paths depend on whether the module uses plain file links, generated JSON, or typed options, so they are intentionally left to that later dotfiles-module work.

Before merging any implementation, run the repository's primary verification seam:

nix flake check

Implementation-spec notes

The implementation spec should state that missing global config and missing global agent directory are normal. The extension should create neither automatically. The extension may expose an explicit user-command to print or write a starter config later, but only after the user requests it.

5.5 KiB Raw Blame History