open/ktg-plugin-marketplace
1
0
Fork 0
Code Issues Pull requests Releases Wiki Activity Actions
ktg-plugin-marketplace/plugins/ultra-cc-architect/CLAUDE.md
Kjell Tore Guttormsen ab504bdf8c refactor(marketplace): split cc-architect from ultraplan-local into its own plugin 
Extract `/ultra-cc-architect-local` and `/ultra-skill-author-local` plus all 7
supporting agents, the `cc-architect-catalog` skill (13 files), the
`ngram-overlap.mjs` IP-hygiene script, and the skill-factory test fixtures
from `ultraplan-local` v2.4.0 into a new `ultra-cc-architect` plugin v0.1.0.

Why: ultraplan-local had drifted into containing two distinct domains — a
universal planning pipeline (brief → research → plan → execute) and a
Claude-Code-specific architecture phase. Keeping them together forced users
to inherit an unfinished CC-feature catalog (~11 seeds) when they only
wanted the planning pipeline, and locked the catalog and the pipeline into
the same release cadence. The architect was already optional and decoupled
at the code level — only one filesystem touchpoint remained
(auto-discovery of `architecture/overview.md`), which already handles
absence gracefully.

Plugin manifests:
- ultraplan-local: 2.4.0 → 3.0.0 (description + keywords updated)
- ultra-cc-architect: new at 0.1.0 (pre-release; catalog is thin, Fase 2/3
  of skill-factory unbuilt, decision-layer empty, fallback list still
  needed)

What stays in ultraplan-local: brief/research/plan/execute commands, all
19 planning agents, security hooks, plan auto-discovery of
`architecture/overview.md` (filesystem-level contract, not code-level).

What moved (28 files via git mv, R100 — full history preserved):
- 2 commands, 8 agents, 1 skill catalog (13 files), 2 scripts, 8 fixtures

Documentation updates: plugin CLAUDE.md and README.md for both plugins,
root README.md (added ultra-cc-architect section, updated ultraplan-local
section), root CLAUDE.md (added ultra-cc-architect to repo-struktur),
marketplace.json (registered ultra-cc-architect), ultraplan-local
CHANGELOG.md (v3.0.0 entry with migration guidance).

Test verification: ngram-overlap.test.mjs passes 23/23 from new location.

Memory updated: feedback_no_architect_until_v3.md now points at the new
plugin and reframes the threshold around catalog maturity rather than an
ultraplan-local milestone.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
2026-04-30 17:18:47 +02:00

111 lines
9 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# ultra-cc-architect
Claude-Code-specific architecture matching and skill-factory authoring. Extracted from `ultraplan-local` v2.4.0 in v0.1.0 (2026-04-30).
**Status: pre-release (v0.1.0).** Catalog is thin (~11 seed skills across 8 features), Fase 2/3 of the skill-factory remain unbuilt, decision-layer skills are intentionally empty. Expect breaking changes before v1.0.
**Design principle: Context Engineering** — match a task brief and research against available CC features, propose a feature set with brief-anchored rationale, surface honest coverage gaps. The plugin consumes upstream artifacts (typically from `ultraplan-local`) and produces an architecture note that downstream `ultraplan-local` can auto-discover as priors.
## Commands
| Command | Description | Model |
|---------|-------------|-------|
| `/ultra-cc-architect-local` | Architect — match brief+research against Claude Code features; produce architecture note with explicit gaps. Requires `--project` | opus |
| `/ultra-skill-author-local` | Authoring (skill-factory Fase 1) — generate one cc-architect-catalog draft from a local source with IP-hygiene | opus |
### /ultra-cc-architect-local modes
| Flag | Behavior |
|------|----------|
| `--project <dir>` | **Required** — read `{dir}/brief.md` and `{dir}/research/*.md`, write `{dir}/architecture/overview.md` + `{dir}/architecture/gaps.md` |
| `--fg` | No-op alias (foreground is default) |
| `--quick` | Skip adversarial review (architecture-critic) |
| `--no-gaps` | Skip gap-identifier; overview.md only |
Architect sits between `/ultraresearch-local` and `/ultraplan-local` in the typical pipeline. It matches the task brief + research against available Claude Code features (Hooks, Subagents, Skills, Output Styles, MCP, Plan Mode, Worktrees, Background Agents) using the seeded `cc-architect-catalog` skill, and produces a proposed feature set with brief-anchored rationale plus explicit gaps (missing reference, pattern, decision, or outside-CC-scope).
### /ultra-skill-author-local modes
| Flag | Behavior |
|------|----------|
| _(default)_ | Run the pipeline (concept → draft → IP-hygiene) foreground |
| `--fg` | Same as default; flag accepted for pipeline-convention consistency |
| `--quick` | Skip IP-hygiene with BIG WARNING (drafting-pipeline test only) |
Manual one-skill-at-a-time generator for the `cc-architect-catalog`. A curated local source enters, one draft skill exits in `skills/cc-architect-catalog/.drafts/` with its n-gram containment score against the source stamped into the frontmatter (or the draft is deleted when the overlap is too high).
## Agents
| Agent | Model | Role |
|-------|-------|------|
| architect-orchestrator | opus | Inline reference documentation for the architecture phase workflow (feature-matcher + gap-identifier + critic) |
| feature-matcher | sonnet | Match brief+research to CC features using catalog; brief-anchored rationale + fallback ranking |
| gap-identifier | sonnet | Detect catalog/pattern/decision/outside-CC-scope gaps; emit issue-ready drafts |
| architecture-critic | sonnet | Adversarial review of architecture note (hallucination gate, brief-anchor integrity, gap honesty) |
| skill-author-orchestrator | opus | Inline reference for the `/ultra-skill-author-local` 3-stage pipeline |
| concept-extractor | sonnet | Read one local source file and extract a structured concept JSON (cc_feature, layer, slug) |
| skill-drafter | sonnet | Consume concept JSON + source; produce draft SKILL.md with 9-field frontmatter |
| ip-hygiene-checker | sonnet | Score draft against source via ngram-overlap.mjs; stamp verdict or delete draft |
## Architecture
**Architect:** Foreground workflow: Parse mode (`--project` required) → Read inputs + audit catalog skill → Parallel `feature-matcher` + `gap-identifier` (spawned from main context) → Synthesize `overview.md` (6 sections + YAML frontmatter) → Adversarial review via `architecture-critic` (skipped in `--quick`; hallucination gate is BLOCKER) → Write `gaps.md` + stats → Present summary. Writes to `{dir}/architecture/overview.md` and `{dir}/architecture/gaps.md`. Additive — downstream `/ultraplan-local` auto-discovers the note if present.
**Skill-factory Fase 1 (`/ultra-skill-author-local`):** Sequential 3-stage pipeline, no parallelism, no retry. Source file → `concept-extractor` (JSON: cc_feature/layer/slug) → `skill-drafter` (writes `.drafts/<slug>.md`, 9-field frontmatter, 150–600 word body in user voice) → `ip-hygiene-checker` (runs `scripts/ngram-overlap.mjs`; `accepted`/`needs-review` stamps `ngram_overlap_score` into frontmatter, `rejected` deletes the draft).
## CC-feature catalog
The `cc-architect-catalog` skill at `skills/cc-architect-catalog/` indexes Claude Code primitives across three layers:
- **`reference`** — how a feature works
- **`pattern`** — when to reach for it
- **`decision`** — adoption heuristics (intentionally empty in v0.1.0; pending skill-factory Fase 2)
The `feature-matcher` agent only proposes features covered by the catalog *or* an explicit fallback list — a hallucination gate that `architecture-critic` enforces as BLOCKER severity. The `gap-identifier` agent emits issue-ready drafts for missing catalog entries so the catalog grows with real usage rather than speculation.
**Slug convention:** catalog files follow `<cc_feature>[-<qualifier>]-<layer>.md`.
- **Unqualified slugs** (e.g., `hooks-pattern.md`) are the canonical baseline — one per `(feature, layer)` pair, covering generic shapes and decision-heuristics for the feature.
- **Qualified slugs** (e.g., `hooks-observability-pattern.md`) cover specific named sub-patterns. Zero-or-more per `(feature, layer)` pair. The qualifier MUST be kebab-case and descriptive (`observability`, `migration`, `multi-tenant`).
- **Matcher logic:** `feature-matcher` builds `cc_feature → {layer → [skills]}` and prefers the unqualified baseline when the brief does not specifically justify a variant. Multiple skills can be proposed together when they cover non-overlapping aspects of the same feature.
- **Critic enforcement:** `architecture-critic` verifies every cited `supporting_skill` name exists as a real file in the catalog (blocker severity). The `cc_feature` hallucination gate is unchanged — still validates against the taxonomy, not slugs.
- **Collision handling:** skill-factory drafts that would overwrite an approved slug are a hard error. Resolution is either to qualify the new slug or revise the existing baseline.
- **Drafter collision hint:** `skill-drafter` reads `{catalog_root}/<slug>.md` before writing, and prepends a warning block to its confirmation output when an existing skill would be overwritten during manual `mv` promotion. The draft is still written to `.drafts/<slug>.md` — the check is a hint, not a block.
Seeds (v0.1.0, inherited from ultraplan-local v2.3.1): 11 skills across 8 features — one qualified pattern (`hooks-observability-pattern.md`, promoted from `ai-psychosis/README.md`, ngram-overlap 0.01, approved). Decision-layer intentionally empty pending skill-factory Fase 2.
## Project-directory contract (consumed)
The plugin participates in the `ultraplan-local` project-directory contract. It is not strictly required to use `ultraplan-local`, but the typical workflow assumes those upstream artifacts exist:
```
.claude/projects/{YYYY-MM-DD}-{slug}/
brief.md ← consumed (typically produced by /ultrabrief-local)
research/*.md ← consumed (typically produced by /ultraresearch-local)
architecture/ ← produced by this plugin
overview.md
gaps.md
plan.md ← downstream consumer is /ultraplan-local (it auto-discovers overview.md)
```
Path discipline: the plugin only reads from `brief.md` + `research/*.md`, only writes to `architecture/overview.md` + `architecture/gaps.md`. No code dependency on `ultraplan-local` — the contract is filesystem-level only.
## Stats
- Architect stats: `${CLAUDE_PLUGIN_DATA}/ultra-cc-architect-stats.jsonl`
- Skill-author stats: `${CLAUDE_PLUGIN_DATA}/ultra-skill-author-local-stats.jsonl`
## Roadmap to v1.0
Pre-release because:
- Catalog is thin (11 seed skills; gaps in pattern + decision layers across most features)
- Decision-layer skills are intentionally empty — Fase 2 of skill-factory not yet built
- Skill-factory has only Fase 1 (manual one-source one-draft); Fase 2/3 (CC-changelog watcher, batch processing, cross-feature decision skills) remain
- `feature-matcher` falls back to a hardcoded list when catalog is sparse — fragile until catalog grows
See `ROADMAP.md` (gitignored) for current milestone tracking.
## Terminology
- **Architecture note** — the artifact produced by `/ultra-cc-architect-local`: `overview.md` + `gaps.md`. Proposes which Claude Code features fit the task with brief-anchored rationale and explicit gaps.
- **Catalog skill** — a single file in `skills/cc-architect-catalog/<slug>.md`. Indexes one (feature, layer) pair, possibly with a qualifier.
- **Draft** — output of `skill-drafter`, written to `skills/cc-architect-catalog/.drafts/<slug>.md`. Promoted to the catalog by manual `mv` after review.
Reference in a new issue View git blame Copy permalink