cc-os/openspec/specs/adr-plugin-packaging/spec.md

Spec: ADR Plugin Packaging

Purpose

Defines how the os-adr plugin is packaged, named, installed, and structured: cc-os naming conventions, git-tracked source with a symlinked install, full three-place marketplace registration, plugin-relative hook wiring, and an object-oriented Ruby core with model-free deterministic tests.

Requirements

Requirement: Plugin naming and skill naming conventions

The plugin SHALL be named os-adr (kebab-case, os- prefix) and its skills SHALL use verb-first kebab-case names invoked as /os-adr:<verb> (create, init, migrate, find), with no commands/ dispatcher directory — matching the cc-os plugin/skill naming convention.

Scenario: Skills register under verb-first names

• WHEN the plugin is installed and claude plugin details os-adr@local-plugins is run
• THEN the listed skills are create, init, migrate, and find, and no commands/ directory exists in the plugin

Requirement: Source of truth in cc-os with symlinked install

The plugin source SHALL live git-tracked at cc-os/plugins/os-adr/ and be installed via a symlink ~/.claude/plugins/os-adr pointing at it, matching the os-vault/os-doc-hygiene/ os-orchestration pattern.

Scenario: Symlinked install

• WHEN installation is complete
• THEN ~/.claude/plugins/os-adr is a symlink resolving to the git-tracked plugin directory

Requirement: Full three-place marketplace registration

Installation SHALL update all three registration surfaces — the plugin directory/symlink, the local-plugins marketplace manifest (~/.claude/plugins/.claude-plugin/marketplace.json), and settings.json enabledPlugins — then refresh plugin-manager state via claude plugin marketplace update and claude plugin install, and verify skill registration with claude plugin list and claude plugin details.

Scenario: Skills resolve after install

• WHEN the registration procedure completes
• THEN claude plugin list shows os-adr@local-plugins enabled and its skills are invocable as slash commands in a fresh session

Requirement: Hooks wired through plugin hooks.json

Plugin hooks SHALL be declared in hooks/hooks.json using ${CLAUDE_PLUGIN_ROOT}-relative commands (the os-doc-hygiene pattern), not by absolute paths in settings.json, so hook registration cannot silently outlive or diverge from plugin registration.

Scenario: Hook path is plugin-relative

• WHEN the plugin's hook configuration is inspected
• THEN the SessionStart command references ${CLAUDE_PLUGIN_ROOT} and no os-adr hook entry exists in settings.json

Requirement: OO core with tested deterministic behavior

The plugin's core logic SHALL be implemented as an object-oriented Ruby library (small single-responsibility classes, dependency-injected paths/IO, no globals) exposed through thin CLI entry points, with a thin Python script only for the SessionStart hook. All deterministic behaviors (ID assignment, index regeneration, shape detection, existence check, retrieval layers 1–2) SHALL have automated tests runnable without any LLM, including golden-example fixtures.

Scenario: Deterministic tests run model-free

• WHEN the plugin's test suite runs on a machine with no model access
• THEN all tests for ID assignment, index regeneration, detection, existence check, and frontmatter retrieval pass

Scenario: Skills delegate to CLI entry points

• WHEN a skill performs a mechanical operation (numbering, indexing, detection, filtering)
• THEN it does so by invoking a bin/ CLI rather than re-implementing the logic in prompt instructions