--- name: cc-architect-catalog description: Internal catalog for ultra-cc-architect-local — not invoked directly. Indexes CC-feature reference and pattern skills. layer: manifest cc_feature: meta source: https://docs.claude.com/en/docs/claude-code concept: catalog-index last_verified: 2026-04-18 ngram_overlap_score: null review_status: approved --- # CC Architect Catalog — Manifest This file is the catalog index consumed by the `feature-matcher` and `gap-identifier` agents inside `/ultra-cc-architect-local`. It is NOT intended to be auto-invoked by Claude Code's skill system — the description above exists only so the skill loader has something to display if it indexes this directory. ## Purpose The catalog enumerates which Claude Code features the architect command can reason about, and at which layer of abstraction. Each feature gets one or more skill files in this directory. A skill is a self-contained note about *one* feature at *one* layer. ## Layers (frontmatter `layer` field) | Layer | Purpose | Kilde | |-------|---------|-------| | `reference` | Facts, API, syntax. What the feature *is*. | CC changelog, official docs | | `pattern` | When and how to use it. Typical shapes, pitfalls. | Synthesized from practice | | `decision` | Operational decision tree across features. | Synthesized. (No seeds yet.) | Lag representeres som frontmatter-felt, ikke mappestruktur. Rationale: one feature can have skills at multiple layers without relocation, and future skill-factory output can target a specific layer without moving files. ## Frontmatter contract (per skill file) Every skill file in this directory MUST have this frontmatter. The fields are load-bearing for the architect command. ```yaml --- name: # unique, kebab-case description: # used by feature-matcher layer: reference | pattern | decision cc_feature: # see table below source: # canonical upstream source concept: # 3–6 word concept handle last_verified: # when a human last checked against upstream ngram_overlap_score: null # reserved for skill-factory IP-hygiene review_status: approved | pending | auto-merged --- ``` `ngram_overlap_score` is reserved. This command respects it (will flag non-null values > threshold) but does not compute it. Skill-factory (a separate later process) populates that field. `review_status: approved` is the default for seeds (approved by construction — handwritten, no third-party text copied). Future skill-factory output will start as `pending` (channel 2) or `auto-merged` (channel 1). ## Canonical `cc_feature` values | Value | Coverage | |-------|----------| | `hooks` | Event hooks (UserPromptSubmit, PreToolUse, PostToolUse, Stop, Notification, SessionStart, etc.) | | `subagents` | Task-tool sub-agents, delegation patterns | | `skills` | Claude Code skill system (not Agent SDK skills) | | `output-styles` | Output style configuration | | `mcp` | Model Context Protocol servers and tools | | `plan-mode` | Built-in plan mode | | `worktrees` | Git worktree integration | | `background-agents` | `run_in_background`, Monitor, long-running agents | | `meta` | This manifest only — not a real feature | If a future skill covers a feature not in this list, add the row above and surface the extension in the relevant CHANGELOG entry. ## Slug convention Skill filenames follow this pattern: ``` [-]-.md ``` - **Unqualified slug** (`-.md`) — the baseline/canonical entry for that (feature, layer) pair. One per pair. Example: `hooks-pattern.md` = generic hook shapes and pitfalls. - **Qualified slug** (`--.md`) — a specialized variant covering one specific sub-pattern or use-case. Zero-or-more per pair. Example: `hooks-observability-pattern.md` = progressive-alert observability pattern specifically. Qualifiers exist because one CC feature can support multiple non-overlapping patterns at different abstraction levels. Forcing everything into a single `-.md` either bloats the canonical entry or loses useful specialization. Qualified slugs let the catalog grow with concrete, named patterns without displacing the baseline. `feature-matcher` treats all skills with the same `cc_feature` + `layer` as candidates and picks the most relevant to the brief (or proposes several if they cover different aspects). See "How `feature-matcher` uses this file" below. ## Current seed coverage (v2.3.0 — see .drafts/ for skill-factory output) | Feature | reference | pattern | qualified patterns | decision | |---------|-----------|---------|--------------------|----------| | hooks | hooks-reference | hooks-pattern | hooks-observability-pattern | — | | subagents | subagents-reference | subagents-pattern | — | — | | skills | skills-reference | — | — | — | | output-styles | output-styles-reference | — | — | — | | mcp | mcp-reference | — | — | — | | plan-mode | plan-mode-reference | — | — | — | | worktrees | worktrees-reference | — | — | — | | background-agents | background-agents-reference | — | — | — | Total: 11 seed skills, 8 features, 2 layers. Decision-layer is intentionally empty — decisions cross features and require broader synthesis than a single seed pass can provide. Skill-factory populates decision-layer later. ## How `feature-matcher` uses this file 1. Read this file to learn the `cc_feature` taxonomy and slug convention. 2. Glob the directory for `*.md` files (excluding SKILL.md). 3. Parse each skill's frontmatter. 4. For each feature mentioned in the brief or research, match against `cc_feature` field. Build the candidate set per feature, grouped by layer. Selection rules: - **Layer preference:** prefer `pattern` over `reference` when both exist (pattern is richer). - **Multiple patterns per feature:** when two or more pattern-layer skills share the same `cc_feature`, read each `description` and pick the one(s) most relevant to the brief. If two cover non-overlapping aspects that both apply, propose both with clear rationale. Prefer the unqualified baseline (`-pattern.md`) when the brief does not specifically justify a qualified variant. - **Be explicit:** name the chosen skill in `supporting_skill` so `architecture-critic` can verify the match. 5. When no skill exists for a mentioned feature, fall back to the hardcoded minimum-list inside the `feature-matcher` prompt and mark the gap in stats (`fallback_used: true`). ## How `gap-identifier` uses this file 1. Collect every feature referenced in `feature-matcher`'s output. 2. For each feature, check whether the catalog has at least one skill at each expected layer (reference always; pattern when complexity warrants; decision for cross-feature choices). 3. Emit a gap entry for every missing (feature × layer) pair. 4. Label with `skill-layer:` and `cc-feature:`. ## Non-goals for this file - No skill-factory logic. That is a separate later process. - No auto-discovery of new CC features. - No n-gram computation. - No triggering Claude Code auto-invocation (description deliberately says "not invoked directly"). ## Modification rules - **Adding a canonical skill:** create `-.md` with the frontmatter contract above. Bump the coverage table in this file. - **Adding a qualified pattern skill:** create `--.md` when the new pattern covers a distinct sub-case that does not belong in the unqualified baseline. The qualifier MUST be kebab-case and descriptive (e.g., `observability`, `migration`, `multi-tenant`). Add it to the "qualified patterns" column in the coverage table. - **Choosing qualified vs. canonical:** if no unqualified skill exists yet for a `(feature, layer)` pair, the new skill SHOULD be the unqualified baseline — don't ship a qualified skill without a canonical one, because `feature-matcher` prefers baseline when the brief has no specific justification for a variant. - **Renaming `cc_feature` values:** update both this file AND every skill using the old value in the same commit. - **Removing a skill:** document in CHANGELOG under the version that drops it. - **Slug collision:** two skills with the same slug are a hard error. Skill-factory (`/ultra-skill-author-local`) must refuse to promote a draft that would overwrite an approved skill. Collision is resolved either by qualifying the new slug or by revising the baseline.