9288d34f50
Resolves v2.3.0 dogfood collision: skill-factory produced a
specialized hooks-pattern.md draft that would have overwritten the
generic seed. Qualified slugs let one feature host multiple named
patterns at different abstraction levels.
Slug convention: <cc_feature>[-<qualifier>]-<layer>.md. Unqualified =
canonical baseline. Qualified = sub-pattern (e.g., hooks-observability-
pattern.md) that does not displace the baseline.
Changes:
- SKILL.md: slug convention section, coverage-table qualified column,
matcher logic for N patterns per feature, modification rules cover
qualified-vs-canonical choice and collision handling.
- feature-matcher: catalog map is cc_feature -> {layer -> [skills]};
selection rules (baseline by default, qualified when justified,
multi-skill when non-overlapping); supporting_skill accepts list.
- gap-identifier: adds pattern_count[cc_feature] to coverage audit.
- architecture-critic: supporting-skill verification — every cited
skill name must exist in the catalog (blocker severity).
- First qualified skill: hooks-observability-pattern.md (promoted from
.drafts/, source ai-psychosis/README.md, ngram-overlap 0.01).
- Version bump 2.3.0 -> 2.3.1 across plugin.json, badges, table, root
CLAUDE.md, CHANGELOG.
Non-breaking: existing unqualified slugs keep working, no cc_feature
taxonomy changes, hallucination gate unchanged.
193 lines
8.5 KiB
Markdown
193 lines
8.5 KiB
Markdown
---
|
||
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: <skill-id> # unique, kebab-case
|
||
description: <one-line matcher hint> # used by feature-matcher
|
||
layer: reference | pattern | decision
|
||
cc_feature: <feature-id> # see table below
|
||
source: <URL> # canonical upstream source
|
||
concept: <short phrase> # 3–6 word concept handle
|
||
last_verified: <YYYY-MM-DD> # 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:
|
||
|
||
```
|
||
<cc_feature>[-<qualifier>]-<layer>.md
|
||
```
|
||
|
||
- **Unqualified slug** (`<feature>-<layer>.md`) — the baseline/canonical
|
||
entry for that (feature, layer) pair. One per pair. Example:
|
||
`hooks-pattern.md` = generic hook shapes and pitfalls.
|
||
- **Qualified slug** (`<feature>-<qualifier>-<layer>.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 `<feature>-<layer>.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 (`<feature>-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:<layer>` and `cc-feature:<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 `<feature>-<layer>.md` with the
|
||
frontmatter contract above. Bump the coverage table in this file.
|
||
- **Adding a qualified pattern skill:** create
|
||
`<feature>-<qualifier>-<layer>.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.
|