[EPIC] Provide a consumer CLI for toolkit adoption and updates

[dieterbaier]

As an architect or project maintainer, I want a consumer CLI for discovering, referencing, installing, validating, and updating toolkit capabilities, so that I can adopt the toolkit consistently without manually reproducing repository-specific setup steps.

Context

The CLI is not intended to hide the toolkit's architecture knowledge behind automation. Human-readable skills, contracts, templates, and guidance remain directly browsable and usable by architects.

The CLI complements that human usage by automating repetitive integration work. It should use the machine-readable catalog from #62 and versioned distributions from #63 to determine what exists, what a project needs, and which assets should be referenced or installed.

The default strategy remains reference, don't copy. Only executable tools, schemas, templates, generated wrappers, portable skill packages, or other explicitly distributable assets may be copied or installed in a controlled and traceable way. Canonical toolkit knowledge remains referenced unless a generated release package is explicitly intended for installation into an Agent Skills-compatible runtime.

The CLI should also expose the deterministic conformance and drift checks from #65 and make model-dependent routing or behavioural evaluations available as explicit, separately reported operations.

Goals

• Provide a small, deterministic consumer-facing command-line interface.
• Support both interactive human workflows and scriptable automation.
• Make toolkit adoption, validation, and updates reproducible.
• Preserve a clear boundary between referenced knowledge, installed assets, generated adapters, and portable skill packages.
• Support installation of individual skills and curated bundles from a versioned distribution.
• Explain dependency closure and package policy before changing a repository or user-level skill installation.
• Expose skill conformance, package integrity, and drift diagnostics from [EPIC] Establish Agent Skills conformance and evaluation #65.
• Keep model-dependent routing and behavioural evaluations explicit and separate from deterministic repository validation.
• Avoid coupling the CLI to one AI engine or one repository layout.

Acceptance Criteria

• The CLI consumes the catalog defined by [EPIC] Publish a machine-readable knowledge and skill catalog #62.
• The CLI can select and consume a specific distribution version from [EPIC] Publish the toolkit as a versioned consumable distribution #63.
• A project can initialize or bootstrap toolkit integration through a documented command.
• The CLI records the selected toolkit version and relevant installed asset versions in a lock or manifest file.
• The CLI can show available knowledge areas, skills, bundles, templates, generators, and adapters in a human-readable form.
• The CLI can select and install an individual portable skill package where the catalog marks it as installable.
• The CLI can select and install a curated skill bundle and resolves its dependency closure from catalog metadata.
• The CLI distinguishes project-local skill installation, user-level skill installation, referenced canonical knowledge, installed executable assets, and generated engine adapters.
• The CLI previews planned actions using explicit categories such as REFERENCE, INSTALL, GENERATE, LOCK, KEEP, and REMOVE before applying changes interactively.
• Non-interactive mode can emit the same plan in a stable machine-readable form.
• The CLI can explain why an asset is referenced, installed, generated, bundled, or omitted.
• The CLI validates portable skill package integrity, relative references, declared dependencies, catalog consistency, and applicable structural conformance requirements from [EPIC] Establish Agent Skills conformance and evaluation #65.
• The CLI can detect drift between locked versions, installed skill packages, canonical references, generated adapters, and locally modified files.
• The CLI can invoke or report the deterministic skill conformance checks defined by [EPIC] Establish Agent Skills conformance and evaluation #65.
• The CLI can optionally run routing or behavioural evaluations from [EPIC] Establish Agent Skills conformance and evaluation #65 and records the model, runtime, toolkit version, and evaluation data version separately from deterministic validation results.
• The CLI can validate repository integration, references, installed assets, configuration, and version compatibility.
• The CLI can report available updates and distinguish compatible from potentially breaking changes.
• Update behavior does not silently overwrite locally modified files.
• The CLI can update generated portable skill packages from their canonical release source while preserving or reporting local modifications.
• Commands support non-interactive execution suitable for CI and AI-assisted workflows.
• Core behavior is covered by automated tests.
• CLI output and exit codes are stable enough for scripting.

Candidate Commands

Names are provisional and should be validated during implementation:

• toolkit catalog or toolkit list — browse available knowledge and capabilities.
• toolkit catalog skills — browse skills, supported tasks, compatibility, dependencies, and package policy.
• toolkit bundles — list curated starter and workflow bundles.
• toolkit init — initialize toolkit integration in a project.
• toolkit add <asset> — reference or install a selected capability according to catalog policy.
• toolkit add skill <skill-id> — install or reference an individual skill according to its package policy.
• toolkit add bundle <bundle-id> — install a curated skill and asset set with its dependency closure.
• toolkit plan — show the actions required to reach the requested integration state without changing files.
• toolkit doctor — validate integration, compatibility, package integrity, and drift.
• toolkit skills validate — run deterministic skill and package conformance checks from [EPIC] Establish Agent Skills conformance and evaluation #65.
• toolkit skills eval routing — explicitly run model-dependent routing evaluations from [EPIC] Establish Agent Skills conformance and evaluation #65.
• toolkit status — show selected version, references, installed assets, generated adapters, and drift.
• toolkit update — inspect or apply compatible updates.

Candidate User Stories

• Browse the skill and knowledge catalog from the terminal.
• Browse curated minimal, bootstrap, and SDLC bundles.
• Preview which assets will be referenced, installed, generated, and locked.
• Initialize a project using the toolkit's reference-first strategy.
• Install an individual portable skill package into a supported project-local or user-level location.
• Install a curated skill bundle with deterministic dependency resolution.
• Add a selected template, schema, validator, generator, or adapter.
• Record and inspect the consumed toolkit version.
• Validate project integration with a doctor command.
• Validate portable skill package conformance and integrity.
• Detect drift and locally modified installed assets.
• Run routing or behavioural evaluations explicitly when required.
• Check for and apply compatible updates.
• Run all relevant deterministic operations non-interactively in CI.

Relationship to Other Epics

• [EPIC] Publish a machine-readable knowledge and skill catalog #62 provides discovery, task, dependency, compatibility, package-policy, bundle, and evaluation metadata.
• [EPIC] Publish the toolkit as a versioned consumable distribution #63 provides the versioned release artifacts, portable skill packages, bundles, manifests, and checksums consumed by the CLI.
• [EPIC] Establish Agent Skills conformance and evaluation #65 provides structural conformance, routing, boundary, behavioural evaluation, and drift requirements exposed by CLI diagnostics.

Out of Scope

• Replacing the human-readable catalog or architecture guidance.
• Automatically performing architecture decisions without human review.
• Embedding engine-specific architecture semantics in the CLI.
• Treating all toolkit content as files that must be copied into consumers.
• Making model-dependent behavioural evaluations part of every deterministic CLI operation.
• Maintaining portable skill copies independently from their canonical toolkit sources.