Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

ADR-0035: Decouple skill and agent installation from project initialization

Status: accepted | Date: 2026-03-17

Tags: skills-agents

References: RFC-0002, ADR-0033, ADR-0028

Context

govctl init currently bundles three concerns into one command: governance directory scaffolding (gov/), JSON Schema deployment, and agent asset installation (skills + agents to .claude/). ADR-0033 introduced plugin distribution, giving users a second path to receive skills and agents — globally, via the Claude Code plugin system.

Problem Statement

  1. Redundant local copies for plugin users. Users who install govctl as a Claude Code plugin receive skills and agents globally. govctl init also writes them locally, creating two copies with unclear authority.
  2. Missing schemas for old projects. Projects initialized with earlier govctl versions lack gov/schema/*.json files. The #:schema relative-path comments in TOML artifacts resolve to nonexistent files, breaking IDE validation. Neither govctl sync nor govctl migrate fills this gap.
  3. Unclear sync naming. govctl sync only syncs agent assets (skills + agents), but the name implies general synchronization.

Constraints

  • RFC-0002:C-GLOBAL-COMMANDS specifies init with “optionally creates .claude/commands/” — the skill dump was always optional.
  • RFC-0002:C-GLOBAL-COMMANDS requires new global commands to be added via RFC amendment and meet at least one criterion (multi-resource, project-level init/cleanup, or meta-information).
  • govctl sync is not specified in RFC-0002 — it exists only as an implementation convenience.

Decision

We will separate the three concerns as follows:

  1. govctl init creates governance structure (gov/ directories, config.toml, JSON Schemas). It no longer installs skills or agents. After completion, it prints a hint about govctl init-skills and plugin installation.

  2. govctl init-skills (replaces govctl sync) explicitly installs skills and agents into the configured agent_dir. This is the opt-in command for users who do not use the plugin. Supports -f to overwrite existing files.

  3. govctl migrate ensures all bundled JSON Schema files exist in gov/schema/, always overwriting with the latest version. This fills the gap for projects initialized with older govctl versions.

Implementation Notes

  • init removes the skill/agent writing loop and the hardcoded .claude path.
  • init-skills reuses the existing sync_commands() implementation unchanged.
  • migrate adds a schema-sync step that runs unconditionally (not gated by schema version), writing all ARTIFACT_SCHEMA_TEMPLATES entries to config.schema_dir().
  • RFC-0002:C-GLOBAL-COMMANDS is amended to add init-skills and update the init and migrate descriptions.

Consequences

Positive

  • Plugin users no longer get redundant local skill/agent copies from init
  • Old projects get working #:schema comments after running govctl migrate
  • Command names are self-documenting: init = governance, init-skills = agent assets
  • The hardcoded .claude path in init is eliminated; init-skills uses the configured agent_dir

Negative

  • Users who had govctl init in onboarding docs will find .claude/ empty after upgrading (mitigation: init prints a hint, and the changelog documents the change)
  • Two commands instead of one for full setup (mitigation: plugin users need zero commands for agent assets; CLI-only users run init then init-skills)

Neutral

  • govctl sync is removed as a command name; init-skills replaces it
  • Schema files are now overwritten on every migrate run, even if unchanged — this is safe since they are generated artifacts

Alternatives Considered

Keep init bundled: init continues to dump skills/agents alongside governance structure (rejected)

  • Cons: Redundant for plugin users, Hardcoded .claude path ignores agent_dir config
  • Rejected because: Plugin distribution per ADR-0033 makes unconditional local dumping obsolete

Add –skills flag to init instead of separate command: govctl init –skills dumps agent assets (rejected)

  • Cons: Discovery problem: users must know the flag exists, Couples governance init with agent concerns
  • Rejected because: Separate command is more discoverable and aligns with single-responsibility