[EPIC] Publish a machine-readable knowledge and skill catalog

[dieterbaier]

As an architect or toolkit consumer, I want a coherent catalog of the toolkit's architecture knowledge, skills, templates, schemas, generators, and adapters, so that both humans and automated tools can discover, understand, and use the available capabilities.

Context

The repository already acts as a Git-based knowledge library. Its content is useful for human architecture work and can also be consumed by AI agents and other tooling. What is still missing is one stable, machine-readable catalog that exposes the available assets without replacing their human-readable source documents.

The catalog must therefore support two equally important usage modes:

• human architects browsing and selecting guidance, methods, skills, templates, and examples;
• tools and AI agents discovering suitable assets, metadata, relations, and executable capabilities.

Human-readable architecture knowledge remains canonical. Machine-readable catalog entries describe and link to that knowledge rather than turning the toolkit into an AI-only protocol.

For skills, the catalog is also the metadata source for portable Agent Skills-compatible projections, task-oriented routing, starter bundles, conformance checks, and evaluation fixtures. It must describe how a skill is discovered and composed without duplicating the canonical instructions in SKILL.md.

Goals

• Define a catalog model covering at least skills, contracts, templates, schemas, generators, adapters, examples, and relevant documentation assets.
• Generate a deterministic catalog from canonical repository metadata.
• Make catalog entries useful to both human-facing documentation and automated consumers.
• Preserve stable IDs and relations across releases.
• Expose enough metadata for discovery without duplicating canonical knowledge content.
• Describe portable skill capabilities, compatibility, package policy, and composition metadata.
• Support task-oriented routing and curated skill bundles without hard-coding them independently in multiple consumers.
• Link skills to conformance, trigger, routing, and behavioural evaluation data from [EPIC] Establish Agent Skills conformance and evaluation #65.
• Validate catalog completeness and consistency during the build.

Acceptance Criteria

• A documented catalog schema exists.
• The build generates a deterministic machine-readable catalog, initially as JSON or YAML.
• Every catalog entry has a stable ID, asset type, title, description, canonical source location, and lifecycle status.
• Relevant entries can declare relations, dependencies, supported tasks, required inputs, and produced outputs.
• Skill entries can declare an Agent Skills-compatible profile or standard version, invocation mode, role or workflow category, runtime compatibility, and package policy.
• Skill entries distinguish canonical guidance from generated portable packages, executable assets, references, adapters, and optional runtime-specific metadata.
• Skill dependencies identify whether they are bundled, referenced externally, generated, installed, or optional.
• Skills can reference should-trigger, should-not-trigger, boundary, routing, and behavioural evaluation fixtures defined under [EPIC] Establish Agent Skills conformance and evaluation #65.
• The catalog can represent curated bundles such as minimal architecture, bootstrap, and SDLC workflow sets without duplicating skill content.
• The catalog exposes enough metadata to generate or validate a thin task router while keeping canonical skill descriptions authoritative.
• The catalog represents engine-independent assets separately from engine-specific adapters.
• Human-readable catalog documentation can be generated from the same catalog data or canonical metadata.
• Broken references, duplicate IDs, unsupported types, inconsistent relations, invalid bundle membership, and unresolved skill dependencies fail validation.
• Catalog generation and validation are covered by automated tests.
• Catalog validation cross-checks canonical skills and the conformance metadata required by [EPIC] Establish Agent Skills conformance and evaluation #65.
• The catalog format is versioned independently enough to evolve compatibly.

Candidate User Stories

• Generate the complete catalog from canonical repository metadata.
• Define stable catalog identifiers and asset types.
• Define portable skill metadata, compatibility, invocation, and package policies.
• Represent dependencies and relations between toolkit assets.
• Represent curated skill bundles and minimal starter sets.
• Link skills to trigger, boundary, routing, and behavioural evaluation fixtures.
• Generate a browsable human-facing skill and knowledge index.
• Generate or validate a thin task-oriented skill router from catalog metadata.
• Provide task-oriented discovery for architects and automated consumers.
• Validate catalog completeness and compatibility.

Relationship to Other Epics

• [EPIC] Publish the toolkit as a versioned consumable distribution #63 consumes the catalog to build versioned distributions, portable skill packages, and bundles.
• [EPIC] Provide a consumer CLI for toolkit adoption and updates #64 consumes the catalog for discovery, selection, installation, validation, and updates.
• [EPIC] Establish Agent Skills conformance and evaluation #65 validates that canonical skills, catalog entries, portable packages, routers, and evaluation metadata remain consistent.

Out of Scope

• Replacing canonical Markdown or AsciiDoc knowledge with generated catalog descriptions.
• Requiring an AI agent to use the toolkit.
• Implementing installation or update behavior; that belongs to the consumer CLI epic.
• Defining release packaging; that belongs to the versioned distribution epic.
• Defining the complete skill conformance and evaluation framework; that belongs to [EPIC] Establish Agent Skills conformance and evaluation #65.