Design and implement OMP-only, per-session skill management in `code`

[atyrode]

Context

The dotfiles repository already owns portable, cross-project agent tooling through Home Manager. Today:

• generic core skills live in agents/skills/ and are exposed at ~/.agents/skills;
• code is the OMP prompt/profile TUI and launches omp-managed or ompu;
• project-specific skills belong in each project's .agents/skills/ directory;
• infra pins/selects the portable dotfiles environment but does not own user-level skill content.

We want to add curated third-party UX/UI/design aids (initial candidates include Impeccable, Intent, Web Interface Guidelines, Taste Skill, and UI UX Pro Max) without making every skill active in every task or coupling them to a single application repository.

The desired ownership rule is:

Dotfiles owns which OMP skills are available on a machine. code owns which optional skills are activated for an OMP session. Application repositories own project truth. Infrastructure only selects and pins the portable environment.

This issue tracks the architecture, implementation, OMP fixes, safety hardening, tests, and documentation needed to make that rule real.

Scope boundary

This feature is deliberately OMP-only.

• code remains an OMP launcher/profile generator; it does not become a general multi-agent launcher.
• Do not add Codex or Claude Code launch adapters, settings overrides, skill enablement, or catalog management.
• The existing Codex and Claude Code configuration remains only for compatibility with the desktop apps and other incidental use.
• Do not modify home/codex.nix, home/claude.nix, Codex seeds, or Claude settings for this feature.
• Optional catalog skills should not be placed in a globally shared discovery root if doing so would make them visible to desktop Codex or another compatible consumer.

Terminology

Keep these separate throughout the implementation:

1. Catalogued/available: skill content is pinned in the Nix-managed OMP catalog and can be selected by code.
2. Enabled for a session: code injects a selected optional skill into one OMP process invocation.
3. Invoked: the user or model actually applies the skill during that OMP session.

Cataloguing a skill must not imply enabling it. Enabling a skill must not imply that it will be invoked. Skills are agent instruction content and must be treated as trusted code/configuration, not as harmless prompt snippets.

Directory ownership and hierarchy

The intended repository source tree is:

agents/
|-- skills/                       # existing, trusted core/personal skills
|   |-- ts-react-dead-code-sweep/
|   |   `-- SKILL.md
|   `-- tui-visual-verification/
|       `-- SKILL.md
|-- skill-catalog/                # optional, curated, default-off OMP skills
|   |-- impeccable/
|   |   `-- SKILL.md
|   |-- intent/
|   |   `-- SKILL.md
|   |-- web-interface-guidelines/
|   |   `-- SKILL.md
|   |-- taste-skill/
|   |   `-- SKILL.md
|   `-- ui-ux-pro-max/
|       `-- SKILL.md
`-- capabilities.yml              # OMP catalog metadata and activation policy

Important: skills/, skill-catalog/, and capabilities.yml are siblings, all directly under agents/. skill-catalog/ is not inside skills/. The existing dead-code and TUI verification skills appear under skills/ because they are already generic cross-project core skills; they are not members of the UX/UI catalog.

Deployment model

Keep core and optional skills physically and behaviorally distinct:

Core skills

• Preserve the existing agents/skills/ -> ~/.agents/skills Home Manager projection.
• Existing core skills retain their current cross-project discovery behavior.
• This shared compatibility path is not the optional catalog.

Optional OMP catalog

• Package agents/skill-catalog/ into read-only Nix store paths.
• Do not merge optional catalog entries into ~/.agents/skills.
• Build an OMP discovery root per optional skill (or another deterministic isolated representation) so selecting one skill does not expose every catalog entry.
• Export a small generated catalog/manifest for code, containing the display metadata and Nix store discovery root for each entry.
• For a managed launch, code creates a one-shot OMP config overlay that adds only the selected skill discovery roots through OMP's native skills.customDirectories support.
• With no optional selection, code adds no catalog root. Core and project-local skills continue to behave normally.
• Explicit “disable all skills” is a separate action and should use OMP's native --no-skills; it disables core/project skills too and must not be confused with “no optional catalog skills selected”.

This isolated-root approach is preferred over globally exposing all optional skills and then trying to ignore them. Phase 0 must verify the exact customDirectories and discovery semantics against the pinned OMP version before finalizing it.

Architectural decisions

1. Dotfiles is the OMP catalog authority

• Keep cross-project core and optional OMP skills in this repository and deploy/package them through Home Manager/Nix.
• Preserve the existing rule that application-specific skills live in the application repository under .agents/skills/.
• Do not place the generic catalog in tyrode-dev/infra. Infra may enable/pin the dotfiles capability that deploys the catalog, but it must not become the content owner.
• Do not copy generic third-party skills into archi_simple. A future thin archi-simple-design-review skill may live there to point OMP at that repository's owning design docs, tokens, evidence rules, tests, and accessibility constraints.

2. Core and optional skills have different defaults

• agents/skills/: reviewed core skills that retain current always-available behavior.
• agents/skill-catalog/: reviewed but optional OMP skills that are not discoverable unless selected for a managed session.
• Newly added optional skills must never silently become active in bare OMP, managed OMP, or ompu merely because Home Manager deployed the catalog.
• Per-task selections are ephemeral by default. Do not add them to the persisted model/profile facet state.
• Named sets may be persisted as declarative catalog metadata, but the user's most recent ad-hoc selection must not become the next session's implicit default.

3. code owns per-session OMP activation

Extend code with a runtime capability selector. Do not turn skill choices into build-time routing facets: the model facet grid is generated at package build time, while skill selection is runtime state and would create a combinatorial profile explosion.

Target interaction:

• a TUI section/panel lists optional capabilities with a multi-select control;
• default optional selection is none on every invocation;
• named sets provide shortcuts (for example web-review or ux-research);
• CLI flags support scripting and bypassing the TUI where practical;
• the launch preview states which optional skills will be added to OMP;
• incompatible skills cannot be selected together without an explicit override or a clear warning;
• m and generated-profile launches receive the same selected skills;
• u/ompu ignores or rejects catalog selections and always disables all skills.

Exact CLI spelling should be settled during implementation without ambiguously colliding with OMP's existing forwarded --skills/--no-skills flags. A code-specific spelling such as --catalog-skills / --skill-set may be clearer. The TUI is the primary interaction; scripting must remain deterministic.

4. Use native OMP controls

OMP v16.5.2 exposes:

• --no-skills to disable skill discovery/loading;
• --skills <comma-separated-globs> to filter loaded skills;
• skill configuration fields including customDirectories, includeSkills, ignoredSkills, and source toggles.

Implementation work:

• use a one-shot overlay to add only selected optional skill roots;
• keep skills out of the generated model-routing profile files;
• preserve ordinary core and project-local skill discovery for trusted sessions;
• reserve --no-skills for explicit disable-all and ompu;
• parse and remove code-specific catalog arguments before forwarding to OMP;
• add regression tests for execForward and launchGenerated rather than relying on their current raw os.Args[1:] forwarding;
• verify native precedence and duplicate-name behavior against the pinned OMP version.

Catalog manifest

Add a declarative manifest at agents/capabilities.yml (or document a better final name in an ADR before implementation). It should be the single machine-readable source for OMP catalog behavior and should cover both core and optional skills.

Minimum metadata per entry:

• stable ID and display name;
• source directory;
• tier: core or optional;
• default enabled state;
• OMP skill name and generated discovery root;
• origin URL, immutable revision/version, license, and update notes for third-party content;
• trust/review status;
• short purpose/when-to-use text shown in code;
• contribution type (visual craft, UX research, accessibility/checklist, implementation, etc.);
• conflict group(s), supersedence, and known overlaps;
• named sets containing the skill.

Illustrative only:

skills:
  impeccable:
    path: skill-catalog/impeccable
    tier: optional
    default: false
    ompName: impeccable
    conflictGroups: [visual-craft]
    sets: [web-review]
    source:
      url: https://github.com/...
      revision: <immutable-revision>
    review: reviewed

sets:
  web-review:
    skills: [impeccable, web-interface-guidelines]

The actual schema must be validated at build/check time. Do not allow duplicate IDs, duplicate OMP names, missing SKILL.md, nonexistent paths, unresolved set members, cycles, contradictory defaults, or unsafe discovery roots.

Acquisition, pinning, and updates

• Treat all third-party skill instructions as supply-chain input.
• Preview and review content before importing it; never install latest-at-runtime from code.
• Pin every external source to an immutable revision and preserve provenance/license metadata.
• Prefer deterministic Nix fetches or reviewed vendoring, whichever better preserves multi-file skill assets and licenses. Document the selected policy.
• Keep acquisition/update separate from activation. gh skill or Vercel's skills CLI may be useful for discovery/preview/import experiments, but neither should become the runtime authority or mutate Home Manager-owned paths.
• Add an explicit update workflow/check that produces reviewable diffs. No background auto-update.

Conflict and guidance policy

Several design skills overlap and may produce competing aesthetic instructions. Define conflict groups and safe defaults rather than encouraging “enable everything”.

Initial policy proposal:

• impeccable, taste-skill, and ui-ux-pro-max share a visual-craft conflict group and should not normally be active together;
• web-interface-guidelines is primarily a standards/review aid and may accompany one visual-craft skill;
• intent is for explicit UX/IA/research work and should not be included in every implementation task;
• project-owned instructions and design systems always outrank generic catalog advice.

For tyrode-dev/archi_simple, the likely initial set is Impeccable + Web Interface Guidelines + a future thin project-owned design-review skill. Intent should be selected only for tasks that genuinely involve UX research, information architecture, or product intent.

Untrusted-session hardening

The current omp/untrusted.yml disables skill commands but does not clearly guarantee that every discovered skill provider is disabled. Before exposing the catalog:

• make ompu force --no-skills or the pinned OMP equivalent;
• strip/reject --skills, catalog selection flags, one-shot skill configuration, and custom skill directory overrides on the untrusted path;
• ensure the u key never inherits a selected trusted catalog set or personal auth profile;
• add tests at both argument-construction and wrapper/package levels;
• document that disabling skills reduces instruction exposure but is only one part of the untrusted boundary.

Implementation phases

Phase 0 — ADR/spike

• Add an ADR recording the four-way boundary: dotfiles OMP availability, code OMP session activation, project-owned truth, infra pin/selection.
• Verify pinned OMP discovery, customDirectories, config precedence, duplicate-name, and --no-skills behavior.
• Decide manifest schema and deterministic source pinning strategy.
• Prove that isolated optional catalog roots are invisible to bare OMP and desktop compatibility consumers until code injects them.

Phase 1 — Catalog and isolated Nix roots

• Add agents/skill-catalog/ and agents/capabilities.yml.
• Import a small first cohort (prefer Impeccable and Web Interface Guidelines) with immutable provenance and licenses.
• Preserve the current shared projection for agents/skills/ core entries.
• Build isolated, read-only OMP discovery roots for optional entries without adding them to ~/.agents/skills.
• Generate the runtime catalog consumed by code.
• Preserve current behavior for ts-react-dead-code-sweep and tui-visual-verification.

Phase 2 — OMP activation in code

• Add runtime catalog loading/validation to code.
• Add ephemeral multi-select UI, clear default-none state, named-set expansion, conflicts, and launch preview.
• Add CLI equivalents suitable for scripting.
• Generate a one-shot OMP overlay containing only selected optional discovery roots.
• Apply the selection equally to m and generated model routes.
• Keep skills out of build-time generated profile facets/config files.
• Harden u/ompu to force no skills and reject activation overrides.

Phase 3 — Project integration and maintenance

• Add a thin project-owned archi-simple-design-review skill in tyrode-dev/archi_simple only when that repository is ready.
• Define named sets after real usage rather than prematurely adding many combinations.
• Add a reviewed update workflow and drift/provenance reporting.
• Let infra select/pin the finished dotfiles capability; do not copy catalog content there.

Likely implementation surfaces

• agents/skills/
• agents/skill-catalog/ (new)
• agents/capabilities.yml (new)
• modules/home/agent-tools.nix
• omp/defaults.yml, omp/plain-seed.yml, and omp/untrusted.yml
• pkgs/code-tui/main.go, selection/argument helpers, and tests
• pkgs/omp-configured/default.nix and agent-tools package checks
• docs/agent-tools.md, docs/agent-security.md, and a new ADR

Explicitly out of scope: home/codex.nix, Codex seed tooling, home/claude.nix, Claude settings, and multi-harness launch code.

Tests and verification

Add the narrowest durable tests for each layer:

• manifest schema validation and deterministic ordering;
• core/optional source classification;
• unique IDs/OMP names and valid source paths;
• isolated optional discovery-root contents and Nix store targets;
• optional catalog skills are not present under ~/.agents/skills;
• optional catalog skills are invisible to bare OMP and desktop compatibility consumers;
• core skills retain current discoverability;
• set expansion, conflict detection, and explicit override behavior;
• CLI parsing does not accidentally forward code-only flags;
• one-shot overlay contains exactly the selected optional roots;
• OMP managed/default-generated launch parity;
• no optional selection adds no catalog directories while retaining core/project skills;
• explicit disable-all uses --no-skills and disables all skill sources;
• ompu always forces no-skills and cannot be re-enabled by forwarded args/config;
• no skill selection is persisted between independent code invocations;
• existing model facet selection persistence remains unchanged;
• clean-home/package checks prove no mutable runtime state is written into the Nix store or repository.

Manual verification should cover:

1. code with no optional selection: core/project skills behave normally; optional catalog skills are absent.
2. code with one optional skill: exactly that optional root is added.
3. a named set: deterministic expansion is visible before launch.
4. a conflicting pair: blocked or explicitly warned according to policy.
5. m and generated launch: identical selected-skill behavior.
6. explicit disable-all: no core, optional, or project skill is loaded.
7. u: no skill is loaded regardless of prior selection or forwarded arguments.
8. bare omp: optional catalog remains undiscoverable.
9. desktop Codex/Claude compatibility: no optional catalog integration or configuration has been introduced.

Acceptance criteria

• The hierarchy and ownership model clearly distinguish core skills from the sibling optional catalog.
• One declarative manifest describes OMP core/optional skills, provenance, sets, and conflicts.
• Home Manager/Nix packages optional skills into isolated OMP roots rather than ~/.agents/skills.
• Optional skills are unavailable to bare OMP and compatibility consumers unless intentionally injected by code into managed OMP.
• code can enable selected optional skills for one OMP task without persistent config mutation or build-time profile generation.
• A fresh code invocation starts with no optional skills selected.
• No optional selection preserves ordinary core and project-local skill behavior.
• Explicit disable-all and ompu reliably disable every skill source.
• OMP managed/default-generated paths behave consistently.
• Conflicts fail clearly before launch.
• Third-party content is pinned, licensed, reviewable, and never updated implicitly.
• Codex and Claude Code configuration/launch behavior is unchanged.
• Project-specific truth remains in project repositories; infra remains a selector/pinner only.
• Tests and owning documentation are updated with the implementation.

Non-goals

• Supporting, launching, or configuring Codex or Claude Code skill activation.
• Turning code into a multi-harness launcher.
• Building a general-purpose public plugin marketplace.
• Automatically downloading arbitrary skills at session start.
• Treating skill enable/disable controls as a complete security sandbox.
• Moving project-specific facts or workflows into dotfiles.
• Moving the catalog into infra.
• Enabling every design skill simultaneously.
• Replacing the existing code model routing facet system.

Upstream references

• OMP pinned CLI docs in this repository: docs/omp/cli.md
• OMP v16.5.2 skills documentation: https://github.com/can1357/oh-my-pi/blob/v16.5.2/docs/skills.md
• GitHub skill CLI (useful for discovery/import review, not authority): https://cli.github.com/manual/gh_skill
• Vercel skills CLI (useful for discovery/experiments, not authority): https://github.com/vercel-labs/skills

OMP interfaces above must be verified against the repository-pinned version during Phase 0; the issue records the intended architecture, not permission to follow latest-at-runtime behavior.