_type: issue

title: chore(downstream): migrate direct mkSkills callsites

description:
What to build
Migrate known downstream configurations that directly call the old AGENTS skill composition API. Each migrated callsite should use the new m3ta-nixpkgs Agent Skills Library and preserve the current rendered skill behavior unless intentionally changed by the new validation rules.

Acceptance criteria
- Known direct callers of the old AGENTS skill composition API are identified.
- Direct callers under the maintained configuration repositories are migrated to the new m3ta-nixpkgs agentSkills interface.
- Any callsite that cannot be migrated immediately is captured as an explicit follow-up issue.
- The migrated configuration evaluates or has a documented verification command.
- No remaining maintained callsite depends on the removed AGENTS skill composition API.

Blocked by
Issues 7 and 11

status: open

issue_type: chore

issue_id: nixpkgs-rrw

depends_on_id: nixpkgs-kfl

type: blocks


title: docs(agents): document AGENTS as skill data source

description:
What to build
Update the AGENTS repository role and documentation so AGENTS is treated as a skill data source only. Remove the old AGENTS-provided skill composition API and document the migration path to the m3ta-nixpkgs Agent Skills Library.

Acceptance criteria
- AGENTS no longer exposes the old skill composition function.
- AGENTS documentation explains that skill composition is provided by m3ta-nixpkgs.
- The migration path points users to the new m3ta-nixpkgs agentSkills interface.
- References that imply AGENTS is the canonical skill composition library are removed or rewritten.
- Documentation validation or grep-based checks confirm the obsolete API is not advertised.

Blocked by
Issue 7

issue_type: feature


title: feat(pi-skillset): apply active skillsets to Pi settings

description:
What to build
Complete the pi-skillset CLI by allowing it to apply named skillsets, none, and all to Pi settings. The CLI should translate active selections into Pi-native skills patterns, preserve manual settings using the sidecar state file, and write settings and state atomically.

Acceptance criteria
- `use <sets...>` activates all skills belonging to the named skillsets.
- `use none` disables all catalog-managed skills.
- `use all` activates all cataloged skills regardless of skillset membership.
- Generated patterns use one disable-all glob for the managed skills root and exact include patterns for active skill roots.
- Patterns are computed relative to the settings file directory in POSIX form.
- Previously generated patterns are removed using state before new patterns are written.
- Manual skill settings outside the generated pattern set are preserved.
- Invalid settings JSON fails without overwriting the existing settings file.
- Settings and state writes are atomic.
- Successful writes tell the user to run /reload in an active Pi session.
- Python unit tests cover named skillsets, none, all, manual preservation, state replacement, invalid JSON safety, relative paths, and reload messaging.

Blocked by
Issues 8 and 9

depends_on_id: nixpkgs-wqh


title: feat(pi-skillset): add list and status commands

description:
What to build
Add the initial Python-based pi-skillset CLI focused on safe read-only inspection. The CLI should read the catalog, settings, and state using sensible defaults or explicit flags, then report available skillsets and current managed state.

Acceptance criteria
- The CLI provides a list command that shows skillset names and skill counts.
- The CLI provides a verbose list mode that shows skills per skillset.
- The CLI provides a status command that reports active managed skillsets and managed skill counts.
- The status command indicates when manual skill settings are present without reimplementing Pi's full resource resolver.
- The CLI supports flags for alternate settings, catalog, state, and skills root locations.
- Python unit tests cover list, verbose list, status, defaults, and alternate path flags.

Blocked by
Issue 7

issue_id: nixpkgs-wqh


title: feat(pi): add mutable settings and skillset state bootstrap

description:
What to build
Introduce mutable Pi settings behavior and skillset state bootstrapping so runtime skillset changes survive Home Manager rebuilds. The slice should initialize settings and state from Nix defaults when needed, preserve existing runtime state by default, and support an explicit reset path.

Acceptance criteria
- Pi settings can be managed in a mutable mode that creates or merges a real settings file instead of forcing an immutable replacement.
- Runtime-owned fields used by skillset activation are preserved across rebuilds by default.
- A skillset state file records generated patterns and active skillsets.
- Default active skillsets are initialized when no state exists.
- Existing state is preserved when it exists.
- An explicit reset option restores the state to Nix defaults.
- Activation behavior is covered by tests or reproducible smoke checks.

Blocked by
Issue 7


title: feat(pi): deploy skills and catalog via Home Manager

description:
What to build
Wire the new Agent Skills Library into the Home Manager agent skill deployment path. Home Manager should use the m3ta-nixpkgs skill library as the canonical implementation, install the rendered skills directory for Pi and other tools, and publish the generated skill catalog for Pi runtime tooling.

Acceptance criteria
- Home Manager agent skill deployment no longer depends on AGENTS-provided skill composition logic.
- The rendered skills directory is deployed to the shared agent skills location.
- The generated catalog is deployed to the Pi skillsets location.
- Existing external skill source options remain backwards-compatible while supporting new source options.
- Home Manager evaluation tests or smoke tests prove a nested external skill fixture is deployed and cataloged.
- Documentation or option descriptions identify m3ta-nixpkgs as the canonical skill composition provider.

Blocked by
Issues 5 and 6

issue_id: nixpkgs-kfl

depends_on_id: nixpkgs-nas


title: feat(agent-skills): resolve skillsets in catalog

description:
What to build
Add skillset modeling and resolution to the Agent Skills catalog. The slice should allow global skillsets, source-wide default skillsets, and per-skill source mappings, then emit resolved skillset membership for each catalog skill while preserving skillset definitions for debugging.

Acceptance criteria
- Global skillsets can include skills by name or relative path.
- Global skillsets can include categories by relative path prefix.
- Global skillsets can exclude individual skills and category prefixes.
- Source-wide default skillsets add membership to installed skills from that source.
- Per-skill source mappings add membership only for final installed skills.
- Skillset membership is merged additively.
- Empty categories fail fast in phase 1.
- Unknown or ambiguous skillset references fail fast.
- The catalog includes both resolved membership per skill and the source skillset definitions.
- Tests cover direct skill membership, category membership, excludes, source defaults, per-skill mappings, additive merge behavior, and validation failures.

Blocked by
Issue 5

issue_id: nixpkgs-nas


title: feat(agent-skills): emit catalog v1 with provenance

description:
What to build
Generate the first version of the Agent Skills catalog as a machine-readable artifact alongside the rendered skills directory. The catalog should use portable relative paths, include source provenance, and act as the contract consumed by later skillset and runtime tooling.

Acceptance criteria
- The skill bundle produces a catalog artifact with schema version 1.
- Catalog skills include skill name and relative target path.
- Catalog skills do not require absolute runtime paths.
- Catalog source provenance includes source label, skills directory, and original relative skill path.
- External source labels are supported, with a stable fallback when no explicit label is provided.
- Catalog generation is covered by fixture or golden-output tests.

Blocked by
Issues 1 and 3


title: feat(agent-skills): validate custom and external collisions

description:
What to build
Make the final skill bundle strict about conflicts across custom and external sources. The slice should discover custom skills recursively using the same rules as external sources and fail fast when the final catalog would contain duplicate skill names or duplicate target paths.

Acceptance criteria
- Custom skills are discovered recursively using the same terminal SKILL.md root rule as external skills.
- Custom skills and external skills participate in the same final catalog validation.
- Duplicate final skill names fail fast, including custom-versus-external duplicates.
- Duplicate final target paths fail fast.
- Positive tests verify custom and external skills can coexist.
- Negative tests verify duplicate names and duplicate paths fail with clear diagnostics.

Blocked by
Issues 1 and 3

issue_id: nixpkgs-vsp


title: feat(agent-skills): add source layouts and category validation

description:
What to build
Add per-source layout control to the Agent Skills Library so skill sources can be rendered in preserved, flat, or category-prefixed form. The slice should produce verifiable output paths for all three layouts and strictly validate category configuration.

Acceptance criteria
- The preserve layout keeps each skill root's relative source path under the target skills root.
- The flat layout renders each skill under its skill name.
- The under layout renders each skill under a validated category prefix while preserving the source structure below that prefix.
- The default layout is preserve.
- Category values are validated as safe relative paths.
- A category is required for under layout.
- Supplying a category with preserve or flat layout fails fast.
- Fixture tests verify all layouts and invalid category combinations.

Blocked by
Issue 1


title: feat(agent-skills): support select and exclude semantics

description:
What to build
Extend the Agent Skills Library tracer so callers can include and exclude skills from each source predictably. The slice should support selecting skills by skill name or relative skill path, excluding skills by skill name or relative skill path, preserve the distinction between selecting all skills and selecting no skills, and fail fast when references are unknown or ambiguous.

Acceptance criteria
- selectSkills accepts both skill names and relative skill paths.
- selectSkills set to null includes all discovered skills from a source.
- selectSkills set to an empty list includes no skills from a source.
- excludeSkills removes matching skills from a source and is validated against discovered source skills.
- Unknown skill references fail with a clear error.
- Ambiguous skill-name references fail with a clear error and require relative path disambiguation.
- Fixture tests cover selection by name, selection by path, exclusion, unknown references, ambiguous references, null selection, and empty selection.

Blocked by
Issue 1


title: feat(agent-skills): add recursive skill bundle tracer

description:
What to build
Create the first end-to-end tracer for the new m3ta-nixpkgs Agent Skills Library. The slice should expose the new skill bundle interface, provide a convenience interface for callers that only need the rendered skills directory, discover skill directories recursively, treat a directory containing SKILL.md as a terminal skill root, ignore hidden directories and dependency directories, derive skill names from parent directory names, and prove the resulting skill tree can be built from nested fixture sources.

Acceptance criteria
- A public agent-skills library interface exists for building a skill bundle and for retrieving only the rendered skills directory.
- Nested skill directories containing SKILL.md are discovered and rendered into the output skill tree.
- Discovery stops below a discovered skill root and does not treat nested content inside a skill as another skill.
- Hidden directories and dependency directories are ignored during discovery.
- Skill names are derived from the direct parent directory of SKILL.md.
- Nix fixture tests or build/eval tests verify the tracer behavior end-to-end.

Blocked by
None - can start immediately