diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json index ab50587..84bb7f8 100644 --- a/.claude-plugin/marketplace.json +++ b/.claude-plugin/marketplace.json @@ -23,12 +23,37 @@ { "name": "ultraplan-local", "source": "./plugins/ultraplan-local", - "description": "Deep implementation planning with interview, specialized agent swarms, external research, adversarial review, session decomposition, and headless execution support" + "description": "Four-command context-engineering pipeline (brief → research → plan → execute) with specialized agent swarms, external research triangulation, adversarial review, session decomposition, and headless execution" + }, + { + "name": "ultra-cc-architect", + "source": "./plugins/ultra-cc-architect", + "description": "Match a task brief and research against available Claude Code features (Hooks, Subagents, Skills, MCP, Plan Mode, Worktrees, Background Agents) with brief-anchored rationale and explicit coverage gaps. Includes the skill-factory authoring command. Pre-release (v0.1.0)." }, { "name": "linkedin-thought-leadership", "source": "./plugins/linkedin-thought-leadership", "description": "Build LinkedIn thought leadership with algorithmic understanding, strategic consistency, and authentic engagement. Updated for the January 2026 360Brew algorithm change." + }, + { + "name": "graceful-handoff", + "source": "./plugins/graceful-handoff", + "description": "Produce session-handoff artifacts, commit and push pending work, and print a copy-paste prompt for the next session. Designed for context-constrained models like Opus 4.7." + }, + { + "name": "ai-psychosis", + "source": "./plugins/ai-psychosis", + "description": "Meta-awareness tools for healthy AI interaction patterns. Detects reinforcement loops, scope escalation, narrative crystallization, and other compulsive patterns." + }, + { + "name": "ms-ai-architect", + "source": "./plugins/ms-ai-architect", + "description": "Microsoft AI Solution Architect — structured architecture guidance for the full Microsoft AI stack." + }, + { + "name": "okr", + "source": "./plugins/okr", + "description": "Expert OKR guidance for Norwegian public sector. Write, review, cascade, track and govern OKR based on Google/Doerr methodology adapted for 4-month tertial cycles." } ] } diff --git a/CLAUDE.md b/CLAUDE.md index 527f4ed..87bce2c 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -13,7 +13,8 @@ plugins/ llm-security/ v6.0.0 — Security scanning, auditing, threat modeling ms-ai-architect/ v1.8.0 — Microsoft AI architecture (Cosmo Skyberg persona) okr/ v1.0.0 — OKR guidance for Norwegian public sector - ultraplan-local/ v2.3.2 — Brief, research, architect, plan, execute (five-command pipeline + skill-factory Fase 1) + ultraplan-local/ v3.0.0 — Brief, research, plan, execute (four-command universal pipeline) + ultra-cc-architect/ v0.1.0 — Claude-Code-specific architecture matching + skill-factory (extracted from ultraplan-local in v3.0.0) ``` Hvert plugin er selvstendig med egen CLAUDE.md, README, hooks, agents og commands. diff --git a/README.md b/README.md index b15cf69..16865e4 100644 --- a/README.md +++ b/README.md @@ -71,26 +71,22 @@ Key commands: `/config-audit posture`, `/config-audit feature-gap`, `/config-aud --- -### [Ultra {brief | research | architect | plan | execute} - local](plugins/ultraplan-local/) `v2.4.0` +### [Ultra {brief | research | plan | execute} - local](plugins/ultraplan-local/) `v3.0.0` -Deep requirements gathering, research, Claude Code feature matching, implementation planning, self-verifying execution, and skill-factory authoring with specialized agent swarms, adversarial review, IP-hygiene scoring, and failure recovery. +Deep requirements gathering, research, implementation planning, and self-verifying execution with specialized agent swarms, adversarial review, and failure recovery. -Five core commands plus an authoring command, one pipeline with clear division of labor: +Four commands, one pipeline with clear division of labor: - **`/ultrabrief-local`** — Capture intent. Dynamic, quality-gated interview: a section-driven completeness loop (Phase 3) followed by a `brief-reviewer` stop-gate (Phase 4, max 3 review iterations). Required sections must reach an initial-signal gate AND pass review across completeness, consistency, testability, scope clarity, and research-plan validity before `brief.md` is written. Identifies research topics with copy-paste-ready `/ultraresearch-local` commands. Optional auto-orchestration runs research + planning in foreground. Always interactive. - **`/ultraresearch-local`** — Gather context. Deep multi-source research with triangulation: 5 local agents + 4 external agents + Gemini bridge, producing structured briefs with confidence ratings. Makes no build decisions. -- **`/ultra-cc-architect-local`** *(optional, v2.2)* — Match Claude Code features to the task. Reads `brief.md` + `research/*.md`, consults a seeded CC-feature catalog skill (hooks, subagents, skills, output styles, MCP, plan mode, worktrees, background agents), and produces `architecture/overview.md` with brief-anchored rationale plus `architecture/gaps.md` with issue-ready drafts for missing catalog entries. Hallucination gate (enforced by `architecture-critic`) blocks proposals for features not covered by the catalog. -- **`/ultraplan-local`** — Transform intent into an executable contract. Per-step YAML manifests (`expected_paths`, `commit_message_pattern`, `bash_syntax_check`). Plan-critic is a hard gate on manifest quality. Requires a task brief as input (`--brief` or `--project`). Auto-discovers the architecture note when present and cross-references its `cc_features_proposed` against exploration findings. +- **`/ultraplan-local`** — Transform intent into an executable contract. Per-step YAML manifests (`expected_paths`, `commit_message_pattern`, `bash_syntax_check`). Plan-critic is a hard gate on manifest quality. Requires a task brief as input (`--brief` or `--project`). Auto-discovers `architecture/overview.md` when the optional `ultra-cc-architect` plugin is installed and cross-references its `cc_features_proposed` against exploration findings. - **`/ultraexecute-local`** — Execute the contract disciplined. Manifest-based verification, independent Phase 7.5 audit from git log + filesystem (ignores agent bookkeeping), Phase 7.6 bounded recovery dispatch for missing steps. Step 0 pre-flight catches sandbox push-denial before any work. `--validate` mode offers a fast schema-only sanity-check between planning and execution. -- **`/ultra-skill-author-local`** *(authoring, v2.3, skill-factory Fase 1)* — Generate one `cc-architect-catalog` draft skill from a curated local source file with IP-hygiene enforcement. Sequential pipeline: `concept-extractor` → `skill-drafter` → `ip-hygiene-checker`. Drafts land in `skills/cc-architect-catalog/.drafts/` for manual review and `mv` promotion. Pure-Node n-gram containment scorer (`scripts/ngram-overlap.mjs`) enforces verdict bands; rejected drafts are deleted. Channel 2 of the skill-factory strategy — manual, one-source-at-a-time, no automation. -All artifacts land in one project directory: `.claude/projects/{YYYY-MM-DD}-{slug}/` contains `brief.md`, `research/NN-*.md`, `architecture/` *(v2.2)*, `plan.md`, `sessions/`, and `progress.json`. `--project ` works across `/ultraresearch-local`, `/ultra-cc-architect-local`, `/ultraplan-local`, and `/ultraexecute-local`. +All artifacts land in one project directory: `.claude/projects/{YYYY-MM-DD}-{slug}/` contains `brief.md`, `research/NN-*.md`, `plan.md`, `sessions/`, and `progress.json`. `--project ` works across `/ultraresearch-local`, `/ultraplan-local`, and `/ultraexecute-local`. -v2.4.0 (breaking, default behavior) removes background mode from `/ultraplan-local`, `/ultraresearch-local`, `/ultra-cc-architect-local`, and `/ultrabrief-local` auto-mode. The commands now run foreground in the main context because the harness does not expose the Agent tool to sub-agents — background orchestrators silently degraded the swarm to inline reasoning without external research tools. The `--fg` flag is preserved as a no-op alias for backward compatibility. Source: github.com/anthropics/claude-code/issues/19077. +v3.0.0 extracts the Claude-Code-specific architecture phase to a separate plugin (`ultra-cc-architect`, see below). The planning pipeline now stays technology-agnostic; CC-feature matching becomes opt-in. The plan command still auto-discovers `architecture/overview.md` if the new plugin is installed — the contract is filesystem-level, not code-level. Non-breaking for users of brief/research/plan/execute. See `plugins/ultraplan-local/CHANGELOG.md` for migration steps. -v2.3 (non-breaking) ships the skill-factory Fase 1 MVP: `/ultra-skill-author-local` plus four supporting agents (1 opus orchestrator + 3 sonnet workers) and `scripts/ngram-overlap.mjs` (pure Node stdlib, word-5-gram containment + longest-run secondary signal, calibrated against three source/draft fixture pairs). Catalog growth is now tractable without touching the architect's hallucination gate. Non-goals stay explicit: no automation, no batch, no decision-layer skills, no remote sources — manual `mv` from `.drafts/` to catalog root is the promotion mechanism. v2.3.1 adds a qualified-slug convention (`[-]-.md`) so one feature can host multiple named patterns at different abstraction levels without displacing the baseline — resolved a collision surfaced in v2.3.0 dogfood. v2.3.2 closes the UX gap: `skill-drafter` now reads `{catalog_root}/.md` before writing and surfaces a collision warning in its confirmation output with a suggested qualified slug, so users see the overwrite risk before running `mv` — not after. - -v2.2 (non-breaking) adds the optional `/ultra-cc-architect-local` step between research and planning. The architect phase is backed by a versioned catalog skill (`cc-architect-catalog`) with 10 seed entries across three layers (reference, pattern, decision). Gaps are captured as issue-ready drafts so the catalog grows from real usage rather than speculation. `/ultraplan-local` auto-discovers the architecture note — existing pipelines keep working unchanged. +v2.4.0 (breaking, default behavior) removes background mode. The commands now run foreground in the main context because the harness does not expose the Agent tool to sub-agents — background orchestrators silently degraded the swarm to inline reasoning without external research tools. The `--fg` flag is preserved as a no-op alias for backward compatibility. Source: github.com/anthropics/claude-code/issues/19077. v2.1 (non-breaking) replaced the hardcoded Q1–Q8 interview with a dynamic, quality-gated loop; `brief-reviewer` emits machine-readable per-dimension JSON scores so `/ultrabrief-local` can use it as an internal stop-gate. v2.0 (breaking) extracted the interview from planning: briefs are reviewable artifacts that downstream agents (`brief-reviewer`, `plan-critic`, `scope-guardian`) validate independently. `/ultraplan-local` requires `--brief` or `--project`. See `plugins/ultraplan-local/MIGRATION.md`. @@ -98,14 +94,35 @@ v1.7 self-verifying chain (preserved): a step may not be marked `completed` unle Defense-in-depth security: plugin hooks block destructive commands and sensitive path writes, prompt-level denylist works in headless sessions, pre-execution plan scan catches dangerous commands before they run, scoped `--allowedTools` replaces `--dangerously-skip-permissions` in parallel sessions. -Modes: default, brief-driven, project-scoped, research-enriched, architect (optional), foreground, quick, decompose, export +Modes: default, brief-driven, project-scoped, research-enriched, foreground, quick, decompose, export -23 specialized agents · 5 commands · 1 skill (CC-feature catalog, 10 seeds) · 2 security hooks · No cloud dependency +19 specialized agents · 4 commands · 2 security hooks · No cloud dependency → [Full documentation](plugins/ultraplan-local/README.md) · [Migration guide](plugins/ultraplan-local/MIGRATION.md) --- +### [Ultra CC Architect](plugins/ultra-cc-architect/) `v0.1.0` `🚧 pre-release` + +Match a task brief and research against available Claude Code features, with brief-anchored rationale and explicit coverage gaps. Extracted from `ultraplan-local` v2.4.0 in 2026-04-30. + +Two commands, both Claude-Code-specific: + +- **`/ultra-cc-architect-local`** — Reads `brief.md` + `research/*.md` (typically produced by `ultraplan-local`), consults the seeded `cc-architect-catalog` skill (hooks, subagents, skills, output styles, MCP, plan mode, worktrees, background agents), and produces `architecture/overview.md` with brief-anchored rationale plus `architecture/gaps.md` with issue-ready drafts for missing catalog entries. Hallucination gate (enforced by `architecture-critic`) blocks proposals for features not covered by the catalog. +- **`/ultra-skill-author-local`** *(skill-factory Fase 1)* — Generates one `cc-architect-catalog` draft skill from a curated local source file with IP-hygiene enforcement. Sequential pipeline: `concept-extractor` → `skill-drafter` → `ip-hygiene-checker`. Drafts land in `skills/cc-architect-catalog/.drafts/` for manual review and `mv` promotion. Pure-Node n-gram containment scorer (`scripts/ngram-overlap.mjs`) enforces verdict bands; rejected drafts are deleted. + +The plugin sits between `/ultraresearch-local` and `/ultraplan-local` in the typical workflow. `ultraplan-local` v3.0.0+ auto-discovers `architecture/overview.md` when present — install both plugins to keep the full pipeline (brief → research → architect → plan → execute) working. + +**Pre-release because:** catalog is thin (11 seed skills across 8 features), decision-layer is intentionally empty, skill-factory has only Fase 1 (Fase 2/3 unbuilt), and `feature-matcher` falls back to a hardcoded list when the catalog is sparse. v1.0 ships when the catalog is dense enough that the fallback list can be removed. + +Slug convention: `[-]-.md`. Unqualified slugs are the canonical baseline per `(feature, layer)` pair; qualified slugs cover specific sub-patterns. `feature-matcher` prefers the unqualified baseline unless the brief justifies a variant. Slug collisions with approved skills are a hard error. `skill-drafter` warns before overwrite. + +8 specialized agents · 2 commands · 1 skill (CC-feature catalog, 11 seeds) · 1 IP-hygiene script + +→ [Full documentation](plugins/ultra-cc-architect/README.md) + +--- + ### [AI Psychosis](plugins/ai-psychosis/) `v1.0.0` Meta-awareness tools that counteract sycophancy, reinforcement loops, and compulsive AI interaction patterns. diff --git a/plugins/ultra-cc-architect/.claude-plugin/plugin.json b/plugins/ultra-cc-architect/.claude-plugin/plugin.json new file mode 100644 index 0000000..569a4f5 --- /dev/null +++ b/plugins/ultra-cc-architect/.claude-plugin/plugin.json @@ -0,0 +1,12 @@ +{ + "name": "ultra-cc-architect", + "description": "Match a task brief and research against available Claude Code features (Hooks, Subagents, Skills, MCP, Plan Mode, Worktrees, Background Agents) with brief-anchored rationale and explicit coverage gaps. Includes the skill-factory authoring command for catalog growth. Pre-release — catalog is thin, expect breaking changes before v1.0.", + "version": "0.1.0", + "author": { + "name": "Kjell Tore Guttormsen" + }, + "homepage": "https://git.fromaitochitta.com/open/ktg-plugin-marketplace", + "repository": "https://git.fromaitochitta.com/open/ktg-plugin-marketplace.git", + "license": "MIT", + "keywords": ["claude-code", "architecture", "feature-matching", "skills", "hooks", "subagents", "catalog", "ip-hygiene", "context-engineering"] +} diff --git a/plugins/ultra-cc-architect/.gitignore b/plugins/ultra-cc-architect/.gitignore new file mode 100644 index 0000000..cc083fc --- /dev/null +++ b/plugins/ultra-cc-architect/.gitignore @@ -0,0 +1,21 @@ +# OS files +.DS_Store +Thumbs.db +Desktop.ini + +# Editor files +*.swp +*.swo +*~ +.vscode/ +.idea/ + +# Local configuration / session files (gitignored across the marketplace) +*.local.md +REMEMBER.md +TODO.md +ROADMAP.md + +# Skill-factory drafts (Fase 1 — manual promotion via mv) +skills/cc-architect-catalog/.drafts/*.md +!skills/cc-architect-catalog/.drafts/.gitkeep diff --git a/plugins/ultra-cc-architect/CHANGELOG.md b/plugins/ultra-cc-architect/CHANGELOG.md new file mode 100644 index 0000000..8117607 --- /dev/null +++ b/plugins/ultra-cc-architect/CHANGELOG.md @@ -0,0 +1,51 @@ +# Changelog + +All notable changes to `ultra-cc-architect` are documented here. + +The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). + +## [0.1.0] — 2026-04-30 + +### Initial release — extracted from `ultraplan-local` v2.4.0 + +`ultra-cc-architect` is the CC-specific architecture phase pulled out of the `ultraplan-local` plugin. The split decouples the universal planning pipeline (brief → research → plan → execute) from the Claude-Code-specific feature-matching logic, so users can adopt the planning pipeline without inheriting an unfinished CC-feature catalog and skill-factory. + +**Why pre-release (0.1.0):** +- Catalog is thin: 11 seed skills across 8 features, decision-layer intentionally empty. +- Skill-factory has only Fase 1 (one source → one draft, manual promotion). Fase 2 (CC-changelog watcher) and Fase 3 (cross-feature decision skills) are unbuilt. +- `feature-matcher` falls back to a hardcoded list when the catalog is sparse — this fallback should disappear before v1.0. +- Slug convention is stable but catalog-growth tooling (batch authoring, automated taxonomy updates) is not. + +### Inherited from ultraplan-local v2.4.0 + +**Commands (2):** +- `/ultra-cc-architect-local` — feature matching with brief-anchored rationale and explicit coverage gaps. Modes: `--project` (required), `--quick` (skip critic), `--no-gaps`, `--fg` (no-op alias). +- `/ultra-skill-author-local` — skill-factory Fase 1 manual authoring. Modes: default, `--quick` (skip IP-hygiene), `--fg` (no-op alias). + +**Agents (8):** +- `architect-orchestrator` (opus) — inline reference for the architect workflow +- `feature-matcher` (sonnet) — match brief+research to CC features with brief-anchored rationale +- `gap-identifier` (sonnet) — surface catalog/pattern/decision/outside-CC-scope gaps +- `architecture-critic` (sonnet) — adversarial review with hallucination gate (BLOCKER) +- `skill-author-orchestrator` (opus) — inline reference for the 3-stage authoring pipeline +- `concept-extractor` (sonnet) — read source, output concept JSON with cc_feature/layer/slug +- `skill-drafter` (sonnet) — write `.drafts/.md` with 9-field frontmatter +- `ip-hygiene-checker` (sonnet) — run `ngram-overlap.mjs`, stamp verdict or delete + +**Skill catalog:** `skills/cc-architect-catalog/` (13 files: SKILL.md manifest + 11 seeds + `.drafts/.gitkeep`) + +**Scripts:** `scripts/ngram-overlap.mjs` + `scripts/ngram-overlap.test.mjs` (zero-dependency Node) + +**Test fixtures:** `tests/fixtures/skill-factory/` (calibration prose for verdict bands) + `tests/fixtures/skill-drafter/slug-collision-expected.md` + +### Slug-convention version + +Inherits the v2.3.1 slug convention from ultraplan-local: `[-]-.md`. Unqualified slug = canonical baseline per (feature, layer); qualified slugs cover specific sub-patterns. Slug-collision hint in `skill-drafter` (v2.3.2) preserved. + +### Breaking changes + +None at the command level — `/ultra-cc-architect-local` and `/ultra-skill-author-local` keep their names and flag surfaces. Users who installed `ultraplan-local` v2.4.0 must additionally install `ultra-cc-architect` v0.1.0+ to keep using these commands. See `ultraplan-local` v3.0.0 CHANGELOG for migration steps. + +### Filesystem contract + +Both plugins write into `.claude/projects/{YYYY-MM-DD}-{slug}/`. The directory contract is owned by `ultraplan-local`; this plugin opt-in writes to the `architecture/` subdirectory. No code-level dependency between plugins — the contract is filesystem-level documentation only. diff --git a/plugins/ultra-cc-architect/CLAUDE.md b/plugins/ultra-cc-architect/CLAUDE.md new file mode 100644 index 0000000..ef27486 --- /dev/null +++ b/plugins/ultra-cc-architect/CLAUDE.md @@ -0,0 +1,111 @@ +# 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 ` | **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/.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 `[-]-.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}/.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/.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/.md`. Indexes one (feature, layer) pair, possibly with a qualifier. +- **Draft** — output of `skill-drafter`, written to `skills/cc-architect-catalog/.drafts/.md`. Promoted to the catalog by manual `mv` after review. diff --git a/plugins/ultra-cc-architect/LICENSE b/plugins/ultra-cc-architect/LICENSE new file mode 100644 index 0000000..1105208 --- /dev/null +++ b/plugins/ultra-cc-architect/LICENSE @@ -0,0 +1,21 @@ +MIT License + +Copyright (c) 2026 Kjell Tore Guttormsen + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. diff --git a/plugins/ultra-cc-architect/README.md b/plugins/ultra-cc-architect/README.md new file mode 100644 index 0000000..7bb342f --- /dev/null +++ b/plugins/ultra-cc-architect/README.md @@ -0,0 +1,191 @@ +# ultra-cc-architect — Match tasks to Claude Code features + +![Version](https://img.shields.io/badge/version-0.1.0-orange) +![Status](https://img.shields.io/badge/status-pre--release-yellow) +![License](https://img.shields.io/badge/license-MIT-green) +![Platform](https://img.shields.io/badge/platform-Claude%20Code-purple) + +*AI-generated: all code produced by Claude Code through dialog-driven development. [Full disclosure →](../../README.md#ai-generated-code-disclosure)* + +A [Claude Code](https://docs.anthropic.com/en/docs/claude-code) plugin that matches a task brief and research against available Claude Code features (Hooks, Subagents, Skills, Output Styles, MCP, Plan Mode, Worktrees, Background Agents) and produces an architecture note with brief-anchored rationale plus explicit coverage gaps. + +> **Pre-release (v0.1.0).** Extracted from `ultraplan-local` v2.4.0 on 2026-04-30. The catalog is thin (11 seed skills) and the skill-factory has only Fase 1. Expect breaking changes before v1.0. See [Roadmap to v1.0](#roadmap-to-v10). + +| Command | What it does | +|---------|--------------| +| **`/ultra-cc-architect-local`** | Match brief+research against CC features; produce architecture note with explicit gaps | +| **`/ultra-skill-author-local`** | Skill-factory Fase 1 — generate one cc-architect-catalog draft from a local source with IP-hygiene | + +## Why a separate plugin + +`ultraplan-local` provides a universal planning pipeline (brief → research → plan → execute) that is technology-agnostic. `ultra-cc-architect` is the Claude-Code-specific layer on top: it only makes sense if you're building features for Claude Code itself. Splitting them out: + +- Lets you adopt the planning pipeline without inheriting an unfinished CC-feature catalog +- Lets the catalog and feature-matching logic version independently from the planning flow +- Makes it explicit when a workflow takes a CC-specific turn + +## Typical workflow + +`ultra-cc-architect` consumes the same project-directory contract as `ultraplan-local`. The full pipeline: + +```bash +# 1. Capture intent (ultraplan-local plugin) +/ultrabrief-local Add a custom prompt-injection hook to all our plugins +# → .claude/projects/2026-04-30-prompt-injection-hook/brief.md + +# 2. Research (ultraplan-local plugin) +/ultraresearch-local --project .claude/projects/2026-04-30-prompt-injection-hook --external "How do PreToolUse hooks compose with prompt-level rules?" +# → .claude/projects/2026-04-30-prompt-injection-hook/research/01-*.md + +# 3. Match to CC features (THIS plugin) +/ultra-cc-architect-local --project .claude/projects/2026-04-30-prompt-injection-hook +# → architecture/overview.md + architecture/gaps.md + +# 4. Plan (ultraplan-local plugin — auto-discovers architecture/overview.md) +/ultraplan-local --project .claude/projects/2026-04-30-prompt-injection-hook + +# 5. Execute (ultraplan-local plugin) +/ultraexecute-local --project .claude/projects/2026-04-30-prompt-injection-hook +``` + +You don't have to use `ultraplan-local` — the plugin reads `brief.md` + `research/*.md` from any directory matching the contract. But the natural upstream is `/ultrabrief-local` + `/ultraresearch-local`, and the natural downstream is `/ultraplan-local`. + +## `/ultra-cc-architect-local` — Architect + +Reads the task brief and any research, then matches against available Claude Code features and produces an architecture note with brief-anchored rationale per feature and an explicit coverage-gap section. + +Use the architect step when: +- The task touches orchestration, policy, or long-running work where CC-feature choice matters +- You want a reviewed, explicit feature selection before planning instead of letting the planner pick implicitly +- You want a backlog of coverage gaps (things the skill catalog does not yet know) in a shareable form + +### How it works + +1. Read `{project_dir}/brief.md` + all `{project_dir}/research/*.md` +2. Read the CC-feature skill catalog from `skills/cc-architect-catalog/` +3. Run `feature-matcher` + `gap-identifier` in parallel +4. Write `architecture/overview.md` (six required sections, YAML frontmatter) +5. Run `architecture-critic` (unless `--quick`) — hallucination gate is BLOCKER +6. Write `architecture/gaps.md` as issue-ready drafts (unless `--no-gaps`) + +Downstream: `/ultraplan-local` auto-discovers `architecture/overview.md` in project mode and treats its `cc_features_proposed` as *priors* — exploration agents may override with evidence. + +### Modes + +| Flag | Behavior | +|------|----------| +| `--project ` | **Required.** Read `{dir}/brief.md` + `{dir}/research/*.md`; write to `{dir}/architecture/`. | +| `--fg` | No-op alias (foreground is default). | +| `--quick` | Skip adversarial review (no `architecture-critic` pass). | +| `--no-gaps` | Do not write `gaps.md` (gap section remains inside `overview.md`). | + +### What the architecture note contains + +- **Context** — 3 sentences paraphrasing brief Intent + Goal +- **Proposed CC features** — table with rationale (brief-anchored), supporting skill, confidence per feature +- **Feature composition** — sequence, conflicts, fallbacks +- **Coverage gaps identified** — always present, even if empty. Honest "what we don't know yet" +- **Alternatives considered** — at least one rejected feature combination with rationale from the brief +- **Open questions** — forwarded to the plan phase + +### Hallucination gate + +The `architecture-critic` agent blocks any feature proposal that is not in the catalog's `cc_feature` taxonomy or the `feature-matcher`'s documented fallback minimum list. This prevents the architect from inventing CC features that do not exist. + +## `/ultra-skill-author-local` — Skill-factory Fase 1 + +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). + +### Why it exists + +`/ultra-cc-architect-local` enforces a hallucination gate that only permits feature proposals backed by the catalog. With 11 seed skills covering 8 features, the matcher falls back to a hardcoded list more often than it should. This command grows the catalog without spinning up automation: one source → one draft → manual review → manual `mv` for promotion. + +### Pipeline + +Sequential, no retry, no parallelism: + +``` +/ultra-skill-author-local + → concept-extractor (sonnet) → JSON: cc_feature, layer, slug + → skill-drafter (sonnet) → .drafts/.md, 9-field frontmatter + → ip-hygiene-checker (sonnet) → runs scripts/ngram-overlap.mjs + verdict accepted/needs-review → stamp ngram_overlap_score + verdict rejected → rm draft (no preservation) +``` + +### Modes + +| Mode | Usage | Behavior | +|------|-------|----------| +| **Default** | `/ultra-skill-author-local ` | Run the pipeline foreground | +| **`--fg`** | `/ultra-skill-author-local --fg` | Same as default; flag accepted for pipeline-convention consistency | +| **`--quick`** | `/ultra-skill-author-local --quick` | Skip IP-hygiene with BIG WARNING (drafting-pipeline test only) | + +### IP-hygiene utility + +`scripts/ngram-overlap.mjs` — pure Node stdlib, zero dependencies. Word-5-gram containment similarity (asymmetric draft⊆source) plus longest-consecutive-shingle-run secondary signal. Verdict bands: `accepted` (<0.15 AND <8), `needs-review` (mid), `rejected` (≥0.35 OR ≥15). Short-text fallback to n=4 when min(words) <500. CLI emits JSON. + +Calibration fixtures in `tests/fixtures/skill-factory/` pin the verdict bands against representative prose. Re-verify any threshold change against these fixtures. + +### Non-goals (explicit, Fase 1) + +- No automation, cron, or watcher +- No CC changelog diffing or auto-research +- No batch processing or review command +- No decision-layer skills (cross-feature comparison is Fase 2+) +- No URL or remote sources — local files only +- Manual `mv` from `.drafts/` to catalog root is the promotion mechanism + +## CC-feature catalog + +The catalog at `skills/cc-architect-catalog/` indexes Claude Code primitives across three layers (`reference`, `pattern`, `decision`). v0.1.0 inherits the v2.3.1 seeds from `ultraplan-local`: 11 skills covering 8 features, with one qualified pattern (`hooks-observability-pattern.md`). + +**Slug convention:** `[-]-.md`. Unqualified slugs are the canonical baseline per `(feature, layer)` pair; qualified slugs cover specific sub-patterns. `feature-matcher` prefers the unqualified baseline when the brief does not specifically justify a qualified variant. Slug collisions with approved skills are a hard error. + +The catalog is designed for expansion via `/ultra-skill-author-local`. Gaps surfaced by `/ultra-cc-architect-local` are the backlog for catalog growth. + +## 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 + +v1.0 ships when the catalog is dense enough that the fallback list can be removed and decision-layer skills exist for the most common adoption-question patterns. + +## Installation + +Add the marketplace and enable both plugins: + +```bash +claude plugin marketplace add https://git.fromaitochitta.com/open/ktg-plugin-marketplace.git +``` + +Then in `~/.claude/settings.json`: + +```json +{ + "enabledPlugins": { + "ultraplan-local@ktg-plugin-marketplace": true, + "ultra-cc-architect@ktg-plugin-marketplace": true + } +} +``` + +You can install `ultra-cc-architect` without `ultraplan-local`, but the typical workflow assumes brief + research artifacts produced upstream. + +## Cost profile + +- **Architect**: 1 Opus orchestration + 2-3 Sonnet agents (feature-matcher + gap-identifier in parallel; architecture-critic if not `--quick`) +- **Skill-author**: 3 Sonnet agents sequential (concept-extractor + skill-drafter + ip-hygiene-checker) + +## Requirements + +- [Claude Code](https://docs.anthropic.com/en/docs/claude-code) (CLI, desktop app, or web app) +- Claude subscription with Opus access (Max plan recommended) +- For typical pipeline use: `ultraplan-local` plugin (provides upstream `/ultrabrief-local` + `/ultraresearch-local` and downstream `/ultraplan-local`) + +## License + +[MIT](LICENSE) diff --git a/plugins/ultraplan-local/agents/architect-orchestrator.md b/plugins/ultra-cc-architect/agents/architect-orchestrator.md similarity index 100% rename from plugins/ultraplan-local/agents/architect-orchestrator.md rename to plugins/ultra-cc-architect/agents/architect-orchestrator.md diff --git a/plugins/ultraplan-local/agents/architecture-critic.md b/plugins/ultra-cc-architect/agents/architecture-critic.md similarity index 100% rename from plugins/ultraplan-local/agents/architecture-critic.md rename to plugins/ultra-cc-architect/agents/architecture-critic.md diff --git a/plugins/ultraplan-local/agents/concept-extractor.md b/plugins/ultra-cc-architect/agents/concept-extractor.md similarity index 100% rename from plugins/ultraplan-local/agents/concept-extractor.md rename to plugins/ultra-cc-architect/agents/concept-extractor.md diff --git a/plugins/ultraplan-local/agents/feature-matcher.md b/plugins/ultra-cc-architect/agents/feature-matcher.md similarity index 100% rename from plugins/ultraplan-local/agents/feature-matcher.md rename to plugins/ultra-cc-architect/agents/feature-matcher.md diff --git a/plugins/ultraplan-local/agents/gap-identifier.md b/plugins/ultra-cc-architect/agents/gap-identifier.md similarity index 100% rename from plugins/ultraplan-local/agents/gap-identifier.md rename to plugins/ultra-cc-architect/agents/gap-identifier.md diff --git a/plugins/ultraplan-local/agents/ip-hygiene-checker.md b/plugins/ultra-cc-architect/agents/ip-hygiene-checker.md similarity index 100% rename from plugins/ultraplan-local/agents/ip-hygiene-checker.md rename to plugins/ultra-cc-architect/agents/ip-hygiene-checker.md diff --git a/plugins/ultraplan-local/agents/skill-author-orchestrator.md b/plugins/ultra-cc-architect/agents/skill-author-orchestrator.md similarity index 100% rename from plugins/ultraplan-local/agents/skill-author-orchestrator.md rename to plugins/ultra-cc-architect/agents/skill-author-orchestrator.md diff --git a/plugins/ultraplan-local/agents/skill-drafter.md b/plugins/ultra-cc-architect/agents/skill-drafter.md similarity index 100% rename from plugins/ultraplan-local/agents/skill-drafter.md rename to plugins/ultra-cc-architect/agents/skill-drafter.md diff --git a/plugins/ultraplan-local/commands/ultra-cc-architect-local.md b/plugins/ultra-cc-architect/commands/ultra-cc-architect-local.md similarity index 100% rename from plugins/ultraplan-local/commands/ultra-cc-architect-local.md rename to plugins/ultra-cc-architect/commands/ultra-cc-architect-local.md diff --git a/plugins/ultraplan-local/commands/ultra-skill-author-local.md b/plugins/ultra-cc-architect/commands/ultra-skill-author-local.md similarity index 100% rename from plugins/ultraplan-local/commands/ultra-skill-author-local.md rename to plugins/ultra-cc-architect/commands/ultra-skill-author-local.md diff --git a/plugins/ultraplan-local/scripts/ngram-overlap.mjs b/plugins/ultra-cc-architect/scripts/ngram-overlap.mjs similarity index 100% rename from plugins/ultraplan-local/scripts/ngram-overlap.mjs rename to plugins/ultra-cc-architect/scripts/ngram-overlap.mjs diff --git a/plugins/ultraplan-local/scripts/ngram-overlap.test.mjs b/plugins/ultra-cc-architect/scripts/ngram-overlap.test.mjs similarity index 100% rename from plugins/ultraplan-local/scripts/ngram-overlap.test.mjs rename to plugins/ultra-cc-architect/scripts/ngram-overlap.test.mjs diff --git a/plugins/ultraplan-local/skills/cc-architect-catalog/.drafts/.gitkeep b/plugins/ultra-cc-architect/skills/cc-architect-catalog/.drafts/.gitkeep similarity index 100% rename from plugins/ultraplan-local/skills/cc-architect-catalog/.drafts/.gitkeep rename to plugins/ultra-cc-architect/skills/cc-architect-catalog/.drafts/.gitkeep diff --git a/plugins/ultraplan-local/skills/cc-architect-catalog/SKILL.md b/plugins/ultra-cc-architect/skills/cc-architect-catalog/SKILL.md similarity index 100% rename from plugins/ultraplan-local/skills/cc-architect-catalog/SKILL.md rename to plugins/ultra-cc-architect/skills/cc-architect-catalog/SKILL.md diff --git a/plugins/ultraplan-local/skills/cc-architect-catalog/background-agents-reference.md b/plugins/ultra-cc-architect/skills/cc-architect-catalog/background-agents-reference.md similarity index 100% rename from plugins/ultraplan-local/skills/cc-architect-catalog/background-agents-reference.md rename to plugins/ultra-cc-architect/skills/cc-architect-catalog/background-agents-reference.md diff --git a/plugins/ultraplan-local/skills/cc-architect-catalog/hooks-observability-pattern.md b/plugins/ultra-cc-architect/skills/cc-architect-catalog/hooks-observability-pattern.md similarity index 100% rename from plugins/ultraplan-local/skills/cc-architect-catalog/hooks-observability-pattern.md rename to plugins/ultra-cc-architect/skills/cc-architect-catalog/hooks-observability-pattern.md diff --git a/plugins/ultraplan-local/skills/cc-architect-catalog/hooks-pattern.md b/plugins/ultra-cc-architect/skills/cc-architect-catalog/hooks-pattern.md similarity index 100% rename from plugins/ultraplan-local/skills/cc-architect-catalog/hooks-pattern.md rename to plugins/ultra-cc-architect/skills/cc-architect-catalog/hooks-pattern.md diff --git a/plugins/ultraplan-local/skills/cc-architect-catalog/hooks-reference.md b/plugins/ultra-cc-architect/skills/cc-architect-catalog/hooks-reference.md similarity index 100% rename from plugins/ultraplan-local/skills/cc-architect-catalog/hooks-reference.md rename to plugins/ultra-cc-architect/skills/cc-architect-catalog/hooks-reference.md diff --git a/plugins/ultraplan-local/skills/cc-architect-catalog/mcp-reference.md b/plugins/ultra-cc-architect/skills/cc-architect-catalog/mcp-reference.md similarity index 100% rename from plugins/ultraplan-local/skills/cc-architect-catalog/mcp-reference.md rename to plugins/ultra-cc-architect/skills/cc-architect-catalog/mcp-reference.md diff --git a/plugins/ultraplan-local/skills/cc-architect-catalog/output-styles-reference.md b/plugins/ultra-cc-architect/skills/cc-architect-catalog/output-styles-reference.md similarity index 100% rename from plugins/ultraplan-local/skills/cc-architect-catalog/output-styles-reference.md rename to plugins/ultra-cc-architect/skills/cc-architect-catalog/output-styles-reference.md diff --git a/plugins/ultraplan-local/skills/cc-architect-catalog/plan-mode-reference.md b/plugins/ultra-cc-architect/skills/cc-architect-catalog/plan-mode-reference.md similarity index 100% rename from plugins/ultraplan-local/skills/cc-architect-catalog/plan-mode-reference.md rename to plugins/ultra-cc-architect/skills/cc-architect-catalog/plan-mode-reference.md diff --git a/plugins/ultraplan-local/skills/cc-architect-catalog/skills-reference.md b/plugins/ultra-cc-architect/skills/cc-architect-catalog/skills-reference.md similarity index 100% rename from plugins/ultraplan-local/skills/cc-architect-catalog/skills-reference.md rename to plugins/ultra-cc-architect/skills/cc-architect-catalog/skills-reference.md diff --git a/plugins/ultraplan-local/skills/cc-architect-catalog/subagents-pattern.md b/plugins/ultra-cc-architect/skills/cc-architect-catalog/subagents-pattern.md similarity index 100% rename from plugins/ultraplan-local/skills/cc-architect-catalog/subagents-pattern.md rename to plugins/ultra-cc-architect/skills/cc-architect-catalog/subagents-pattern.md diff --git a/plugins/ultraplan-local/skills/cc-architect-catalog/subagents-reference.md b/plugins/ultra-cc-architect/skills/cc-architect-catalog/subagents-reference.md similarity index 100% rename from plugins/ultraplan-local/skills/cc-architect-catalog/subagents-reference.md rename to plugins/ultra-cc-architect/skills/cc-architect-catalog/subagents-reference.md diff --git a/plugins/ultraplan-local/skills/cc-architect-catalog/worktrees-reference.md b/plugins/ultra-cc-architect/skills/cc-architect-catalog/worktrees-reference.md similarity index 100% rename from plugins/ultraplan-local/skills/cc-architect-catalog/worktrees-reference.md rename to plugins/ultra-cc-architect/skills/cc-architect-catalog/worktrees-reference.md diff --git a/plugins/ultraplan-local/tests/fixtures/skill-drafter/slug-collision-expected.md b/plugins/ultra-cc-architect/tests/fixtures/skill-drafter/slug-collision-expected.md similarity index 100% rename from plugins/ultraplan-local/tests/fixtures/skill-drafter/slug-collision-expected.md rename to plugins/ultra-cc-architect/tests/fixtures/skill-drafter/slug-collision-expected.md diff --git a/plugins/ultraplan-local/tests/fixtures/skill-factory/README.md b/plugins/ultra-cc-architect/tests/fixtures/skill-factory/README.md similarity index 100% rename from plugins/ultraplan-local/tests/fixtures/skill-factory/README.md rename to plugins/ultra-cc-architect/tests/fixtures/skill-factory/README.md diff --git a/plugins/ultraplan-local/tests/fixtures/skill-factory/draft-accepted.md b/plugins/ultra-cc-architect/tests/fixtures/skill-factory/draft-accepted.md similarity index 100% rename from plugins/ultraplan-local/tests/fixtures/skill-factory/draft-accepted.md rename to plugins/ultra-cc-architect/tests/fixtures/skill-factory/draft-accepted.md diff --git a/plugins/ultraplan-local/tests/fixtures/skill-factory/draft-needs-review.md b/plugins/ultra-cc-architect/tests/fixtures/skill-factory/draft-needs-review.md similarity index 100% rename from plugins/ultraplan-local/tests/fixtures/skill-factory/draft-needs-review.md rename to plugins/ultra-cc-architect/tests/fixtures/skill-factory/draft-needs-review.md diff --git a/plugins/ultraplan-local/tests/fixtures/skill-factory/draft-rejected.md b/plugins/ultra-cc-architect/tests/fixtures/skill-factory/draft-rejected.md similarity index 100% rename from plugins/ultraplan-local/tests/fixtures/skill-factory/draft-rejected.md rename to plugins/ultra-cc-architect/tests/fixtures/skill-factory/draft-rejected.md diff --git a/plugins/ultraplan-local/tests/fixtures/skill-factory/source-accepted.md b/plugins/ultra-cc-architect/tests/fixtures/skill-factory/source-accepted.md similarity index 100% rename from plugins/ultraplan-local/tests/fixtures/skill-factory/source-accepted.md rename to plugins/ultra-cc-architect/tests/fixtures/skill-factory/source-accepted.md diff --git a/plugins/ultraplan-local/tests/fixtures/skill-factory/source-needs-review.md b/plugins/ultra-cc-architect/tests/fixtures/skill-factory/source-needs-review.md similarity index 100% rename from plugins/ultraplan-local/tests/fixtures/skill-factory/source-needs-review.md rename to plugins/ultra-cc-architect/tests/fixtures/skill-factory/source-needs-review.md diff --git a/plugins/ultraplan-local/tests/fixtures/skill-factory/source-rejected.md b/plugins/ultra-cc-architect/tests/fixtures/skill-factory/source-rejected.md similarity index 100% rename from plugins/ultraplan-local/tests/fixtures/skill-factory/source-rejected.md rename to plugins/ultra-cc-architect/tests/fixtures/skill-factory/source-rejected.md diff --git a/plugins/ultraplan-local/.claude-plugin/plugin.json b/plugins/ultraplan-local/.claude-plugin/plugin.json index 5e6c891..b1a7180 100644 --- a/plugins/ultraplan-local/.claude-plugin/plugin.json +++ b/plugins/ultraplan-local/.claude-plugin/plugin.json @@ -1,12 +1,12 @@ { "name": "ultraplan-local", - "description": "Five-command context-engineering pipeline (brief → research → architect → plan → execute) with project folders, CC-feature matching, specialized agent swarms, external research triangulation, adversarial review, session decomposition, and headless execution.", - "version": "2.4.0", + "description": "Four-command context-engineering pipeline (brief → research → plan → execute) with project folders, specialized agent swarms, external research triangulation, adversarial review, session decomposition, and headless execution. CC-feature matching extracted to the separate ultra-cc-architect plugin in v3.0.0.", + "version": "3.0.0", "author": { "name": "Kjell Tore Guttormsen" }, "homepage": "https://git.fromaitochitta.com/open/ultraplan-local", "repository": "https://git.fromaitochitta.com/open/ultraplan-local.git", "license": "MIT", - "keywords": ["planning", "implementation", "research", "cc-architecture", "context-engineering", "agents", "adversarial-review", "headless", "execution"] + "keywords": ["planning", "implementation", "research", "context-engineering", "agents", "adversarial-review", "headless", "execution"] } diff --git a/plugins/ultraplan-local/.gitignore b/plugins/ultraplan-local/.gitignore index c0ef0c3..e28a372 100644 --- a/plugins/ultraplan-local/.gitignore +++ b/plugins/ultraplan-local/.gitignore @@ -10,9 +10,8 @@ Desktop.ini .vscode/ .idea/ -# Local configuration +# Local configuration / session files *.local.md - -# Skill-factory drafts (Fase 1 — manual promotion via mv) -skills/cc-architect-catalog/.drafts/*.md -!skills/cc-architect-catalog/.drafts/.gitkeep +REMEMBER.md +TODO.md +ROADMAP.md diff --git a/plugins/ultraplan-local/CHANGELOG.md b/plugins/ultraplan-local/CHANGELOG.md index 2715726..9c7aa43 100644 --- a/plugins/ultraplan-local/CHANGELOG.md +++ b/plugins/ultraplan-local/CHANGELOG.md @@ -4,6 +4,92 @@ All notable changes to this project will be documented in this file. The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). +## [3.0.0] - 2026-04-30 + +### Architect extracted to its own plugin + +The `/ultra-cc-architect-local` and `/ultra-skill-author-local` commands, all +seven of their agents, the `cc-architect-catalog` skill, the `ngram-overlap.mjs` +script, and the skill-factory test fixtures moved out of `ultraplan-local` and +into the new `ultra-cc-architect` plugin (v0.1.0). + +### Why + +`ultraplan-local` had drifted into containing two distinct domains: + +1. A **universal planning pipeline** (brief → research → plan → execute) that + is technology-agnostic and works for any implementation task. +2. A **Claude-Code-specific architecture phase** that only makes sense when + building features for Claude Code itself. + +Keeping them in one plugin caused three problems: + +- Users who wanted only the planning pipeline had to clone an unfinished + CC-feature catalog and seven architect/skill-author agents they would + never invoke. +- The architect catalog (~11 seed skills) and the planning pipeline lived on + different release cadences. Architect work blocked pipeline development + and vice-versa. +- New users saw six commands when only four belonged to the core flow. + +The architect was already marked `optional, v2.2` and was fully decoupled at +the code level — only one filesystem touchpoint remained: `/ultraplan-local` +auto-discovers `architecture/overview.md` if present, and gracefully handles +its absence. The split is therefore non-breaking for the planning flow. + +### What moved to `ultra-cc-architect` + +- **Commands:** `/ultra-cc-architect-local`, `/ultra-skill-author-local` +- **Agents:** `architect-orchestrator`, `feature-matcher`, `gap-identifier`, + `architecture-critic`, `skill-author-orchestrator`, `concept-extractor`, + `skill-drafter`, `ip-hygiene-checker` +- **Skills:** `skills/cc-architect-catalog/` (13 files) +- **Scripts:** `scripts/ngram-overlap.mjs`, `scripts/ngram-overlap.test.mjs` +- **Test fixtures:** `tests/fixtures/skill-factory/`, + `tests/fixtures/skill-drafter/` + +All moves used `git mv`, so history follows the files into the new plugin. + +### What stayed unchanged in ultraplan-local + +- `/ultraplan-local` Phase 1 still auto-discovers `architecture/overview.md`. + The discovery is filesystem-based, not plugin-based — installing both + plugins gives you the full pipeline (brief → research → architect → plan + → execute). +- `agents/planning-orchestrator.md` retains its architecture-note + cross-reference. +- All other commands (`/ultrabrief-local`, `/ultraresearch-local`, + `/ultraexecute-local`) are untouched. + +### Migration + +If you only used `/ultrabrief-local`, `/ultraresearch-local`, +`/ultraplan-local`, and `/ultraexecute-local`: no action needed. Update the +plugin and continue. + +If you used `/ultra-cc-architect-local` or `/ultra-skill-author-local`: +install the new plugin alongside this one. In `~/.claude/settings.json`: + +```json +{ + "enabledPlugins": { + "ultraplan-local@ktg-plugin-marketplace": true, + "ultra-cc-architect@ktg-plugin-marketplace": true + } +} +``` + +Custom seed skills you added to `cc-architect-catalog/` follow with the +catalog. Use `git log --follow` if you need to track them in the new +location. + +### plugin.json changes + +- `version`: `2.4.0` → `3.0.0` +- `description`: now describes a four-command pipeline; CC-feature matching + is described as living in the separate `ultra-cc-architect` plugin +- `keywords`: removed `cc-architecture` + ## [2.4.0] - 2026-04-19 ### Breaking change — background mode removed diff --git a/plugins/ultraplan-local/CLAUDE.md b/plugins/ultraplan-local/CLAUDE.md index 3db0d01..c6a0c7a 100644 --- a/plugins/ultraplan-local/CLAUDE.md +++ b/plugins/ultraplan-local/CLAUDE.md @@ -1,8 +1,10 @@ # ultraplan-local -Deep implementation planning and research with an explicit brief step, specialized agent swarms, external research, CC-feature matching, adversarial review, session decomposition, disciplined execution, and headless support. A local alternative to Anthropic's Ultraplan. +Deep implementation planning and research with an explicit brief step, specialized agent swarms, external research, adversarial review, session decomposition, disciplined execution, and headless support. A local alternative to Anthropic's Ultraplan. -**Design principle: Context Engineering** — build the right context by orchestrating specialized agents. Each step in the pipeline (brief → research → architect → plan → execute) produces a structured artifact that the next step consumes. +**Design principle: Context Engineering** — build the right context by orchestrating specialized agents. Each step in the pipeline (brief → research → plan → execute) produces a structured artifact that the next step consumes. + +> **v3.0.0 — architect extracted to separate plugin.** `/ultra-cc-architect-local` and `/ultra-skill-author-local` were moved to the `ultra-cc-architect` plugin (v0.1.0). The plan command still auto-discovers `architecture/overview.md` if present, so installing both plugins gives you the full five-stage flow. See [CHANGELOG.md](CHANGELOG.md) for migration steps. ## Commands @@ -10,10 +12,8 @@ Deep implementation planning and research with an explicit brief step, specializ |---------|-------------|-------| | `/ultrabrief-local` | Brief — interactive interview produces a task brief with explicit research plan; optionally orchestrates the pipeline | opus | | `/ultraresearch-local` | Research — deep local + external research, produces structured research brief | opus | -| `/ultra-cc-architect-local` | Architect *(optional, v2.2)* — match brief+research against Claude Code features; produce architecture note with gaps. Requires `--project` | opus | | `/ultraplan-local` | Plan — brief-reviewer, explore, plan, review. Requires `--brief` or `--project`. Auto-discovers `architecture/overview.md` if present | opus | | `/ultraexecute-local` | Execute — disciplined plan/session-spec executor with failure recovery | opus | -| `/ultra-skill-author-local` | Authoring *(v2.3, skill-factory Fase 1)* — generate one cc-architect-catalog draft from a local source with IP-hygiene | opus | ### /ultrabrief-local modes @@ -37,17 +37,6 @@ Always interactive. Phase 3 is a section-driven completeness loop (no hard cap o Flags combine: `--project --local`, `--external --quick`. -### /ultra-cc-architect-local modes *(optional, v2.2)* - -| Flag | Behavior | -|------|----------| -| `--project ` | **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 since v2.4.0) | -| `--quick` | Skip adversarial review (architecture-critic) | -| `--no-gaps` | Skip gap-identifier; overview.md only | - -Architect sits between `/ultraresearch-local` and `/ultraplan-local`. It matches the task brief + research against available Claude Code features (Hooks, Subagents, Skills, Output Styles, MCP, Plan Mode, Worktrees, Background Agents) using a seeded catalog skill, and produces a proposed feature set with brief-anchored rationale plus explicit gaps (missing reference, pattern, decision, or outside-CC-scope). - ### /ultraplan-local modes | Flag | Behavior | @@ -62,6 +51,8 @@ Architect sits between `/ultraresearch-local` and `/ultraplan-local`. It matches **Breaking change (v2.0):** one of `--brief` or `--project` is required. There is no interview inside `/ultraplan-local`. The `--spec` flag has been removed — use `/ultrabrief-local` to produce a brief instead. +If `{project_dir}/architecture/overview.md` exists (typically produced by the separate `ultra-cc-architect` plugin), the plan command auto-discovers it and treats `cc_features_proposed` as priors. Missing file is fine — discovery is additive, not required. + ### /ultraexecute-local modes | Flag | Behavior | @@ -93,10 +84,6 @@ Architect sits between `/ultraresearch-local` and `/ultraplan-local`. It matches | plan-critic | sonnet | Adversarial plan review (9 dimensions) | | scope-guardian | sonnet | Scope alignment (creep + gaps) | | session-decomposer | sonnet | Splits plans into headless sessions with dependency graph | -| 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) | | docs-researcher | sonnet | Official documentation, RFCs, vendor docs (Tavily, MS Learn) | | community-researcher | sonnet | Community experience: issues, blogs, discussions | | security-researcher | sonnet | CVEs, audit history, supply chain risks | @@ -109,9 +96,7 @@ Architect sits between `/ultraresearch-local` and `/ultraplan-local`. It matches **Research:** Foreground workflow (v2.4.0): Parse mode → Interview → Parallel research swarm (5 local + 4 external + 1 bridge, spawned from main context) → Follow-ups → Triangulation → Synthesis + brief → Stats. With `--project`, writes to `{dir}/research/NN-slug.md`. -**Architect (v2.2, optional):** Foreground workflow (v2.4.0): 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. With `--project`, writes `{dir}/architecture/overview.md` and `{dir}/architecture/gaps.md`. Additive — downstream `/ultraplan-local` auto-discovers the note if present. - -**Plan:** Foreground workflow (v2.4.0): Parse mode (validate brief input) → Codebase sizing → Brief review (`brief-reviewer`) → Parallel exploration (6-8 agents, spawned from main context) → Deep-dives → Synthesis (with architecture-note cross-reference if present) → Planning → Adversarial review (`plan-critic` + `scope-guardian`) → Present/refine → Handoff. With `--project`, writes to `{dir}/plan.md` and auto-detects `{dir}/architecture/overview.md`. +**Plan:** Foreground workflow (v2.4.0): Parse mode (validate brief input) → Codebase sizing → Brief review (`brief-reviewer`) → Parallel exploration (6-8 agents, spawned from main context) → Deep-dives → Synthesis (with architecture-note cross-reference if present) → Planning → Adversarial review (`plan-critic` + `scope-guardian`) → Present/refine → Handoff. With `--project`, writes to `{dir}/plan.md` and auto-detects `{dir}/architecture/overview.md` (produced by the separate `ultra-cc-architect` plugin if installed). **Decompose:** Parse plan → Analyze step dependencies → Group into sessions → Identify parallel waves → Generate session specs + dependency graph + launch script. @@ -119,20 +104,22 @@ Architect sits between `/ultraresearch-local` and `/ultraplan-local`. It matches **Security:** 4-layer defense-in-depth: plugin hooks (pre-bash-executor, pre-write-executor), prompt-level denylist (works in headless sessions), pre-execution plan scan (Phase 2.4), scoped `--allowedTools` replacing `--dangerously-skip-permissions`. Hard Rules 14-16 enforce verify command security, repo-boundary writes, and sensitive path protection. -**Pipeline:** `/ultrabrief-local` produces the task brief. `/ultraresearch-local --project ` fills in `{dir}/research/`. `/ultra-cc-architect-local --project ` *(optional, v2.2)* matches available Claude Code features against brief+research and writes `{dir}/architecture/`. `/ultraplan-local --project ` reads brief + research (+ architecture note if present) to produce `{dir}/plan.md`. `/ultraexecute-local --project ` executes and writes `{dir}/progress.json`. All artifacts live in one project directory. +**Pipeline:** `/ultrabrief-local` produces the task brief. `/ultraresearch-local --project ` fills in `{dir}/research/`. `/ultraplan-local --project ` reads brief + research to produce `{dir}/plan.md` (and auto-discovers `{dir}/architecture/overview.md` if the separate `ultra-cc-architect` plugin produced one). `/ultraexecute-local --project ` executes and writes `{dir}/progress.json`. All artifacts live in one project directory. -**CC-feature catalog skill:** The architect phase loads the `cc-architect-catalog` skill, which indexes Claude Code primitives (hooks, subagents, skills, output styles, MCP, plan mode, worktrees, background agents) across three layers: `reference` (how a feature works), `pattern` (when to reach for it), `decision` (adoption heuristics). 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. The catalog lives at `skills/cc-architect-catalog/`. +**Project-directory contract (v3.0.0):** ultraplan-local owns the directory layout below. The `architecture/` subdirectory is opt-in and produced by the separate `ultra-cc-architect` plugin — install that plugin to participate in the architect step. -**Slug convention (v2.3.1):** catalog files follow `[-]-.md`. +``` +.claude/projects/{YYYY-MM-DD}-{slug}/ + brief.md ← ultrabrief-local writes; everyone reads + research/*.md ← ultraresearch-local writes; plan + architect read + architecture/ ← OPT-IN, owned by ultra-cc-architect plugin + overview.md + gaps.md + plan.md ← ultraplan-local writes; ultraexecute reads + progress.json ← ultraexecute-local writes +``` -- **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 (v2.3.2):** `skill-drafter` reads `{catalog_root}/.md` before writing, and prepends a warning block to its confirmation output when an existing skill would be overwritten during manual `mv` promotion. The warning cites the existing file's `review_status` and suggests a qualified slug derived from the `concept` handle. The draft is still written to `.drafts/.md` — the check is a hint, not a block. - -Seeds 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. +No code-level dependency between plugins — the contract is filesystem-level only. ## State @@ -140,7 +127,7 @@ All artifacts in one project directory (default): - Project root: `.claude/projects/{YYYY-MM-DD}-{slug}/` - `brief.md` (task brief from `/ultrabrief-local`) - `research/{NN}-{slug}.md` (research briefs from `/ultraresearch-local --project`) - - `architecture/overview.md` + `architecture/gaps.md` (optional, v2.2, from `/ultra-cc-architect-local --project`) + - `architecture/overview.md` + `architecture/gaps.md` (opt-in, produced by the separate `ultra-cc-architect` plugin) - `plan.md` (from `/ultraplan-local --project`) - `sessions/session-*.md` (from `--decompose`) - `progress.json` (from `/ultraexecute-local --project`) @@ -157,12 +144,11 @@ Stats: - Plan stats: `${CLAUDE_PLUGIN_DATA}/ultraplan-stats.jsonl` - Exec stats: `${CLAUDE_PLUGIN_DATA}/ultraexecute-stats.jsonl` - Research stats: `${CLAUDE_PLUGIN_DATA}/ultraresearch-stats.jsonl` -- Architect stats: `${CLAUDE_PLUGIN_DATA}/ultra-cc-architect-stats.jsonl` ## Terminology - **Task brief** — produced by `/ultrabrief-local`. Declares intent, goal, and research plan. Drives planning. - **Research brief** — produced by `/ultraresearch-local`. Answers a specific research question. Feeds planning. -- **Architecture note** — produced by `/ultra-cc-architect-local`. Proposes which Claude Code features fit the task with brief-anchored rationale + explicit gaps. Enriches planning. +- **Architecture note** — opt-in, produced by `/ultra-cc-architect-local` from the separate `ultra-cc-architect` plugin. Proposes which Claude Code features fit the task with brief-anchored rationale + explicit gaps. When present, enriches planning. A project typically has 1 task brief, 0–N research briefs, and 0 or 1 architecture note. diff --git a/plugins/ultraplan-local/README.md b/plugins/ultraplan-local/README.md index a7064da..ff6b1c6 100644 --- a/plugins/ultraplan-local/README.md +++ b/plugins/ultraplan-local/README.md @@ -1,23 +1,23 @@ -# ultraplan-local — Brief, Research, Architect, Plan, Execute +# ultraplan-local — Brief, Research, Plan, Execute -![Version](https://img.shields.io/badge/version-2.4.0-blue) +![Version](https://img.shields.io/badge/version-3.0.0-blue) ![License](https://img.shields.io/badge/license-MIT-green) ![Platform](https://img.shields.io/badge/platform-Claude%20Code-purple) *AI-generated: all code produced by Claude Code through dialog-driven development. [Full disclosure →](../../README.md#ai-generated-code-disclosure)* -A [Claude Code](https://docs.anthropic.com/en/docs/claude-code) plugin for deep implementation planning, multi-source research, CC-feature architecture matching, and autonomous execution. Five commands, one pipeline: +A [Claude Code](https://docs.anthropic.com/en/docs/claude-code) plugin for deep implementation planning, multi-source research, and autonomous execution. Four commands, one pipeline: | Command | What it does | |---------|-------------| | **`/ultrabrief-local`** | Brief — interactive interview produces a task brief with explicit research plan | | **`/ultraresearch-local`** | Research — deep local + external research with triangulation | -| **`/ultra-cc-architect-local`** | Architect (optional) — match brief+research against available CC features; produce architecture note with explicit gaps | | **`/ultraplan-local`** | Plan — agent swarm exploration, Opus planning, adversarial review | | **`/ultraexecute-local`** | Execute — disciplined step-by-step implementation with failure recovery | -| **`/ultra-skill-author-local`** | Authoring (v2.3, skill-factory Fase 1) — generate one cc-architect-catalog draft from a local source with IP-hygiene | -Every artifact lives in one project directory: `.claude/projects/{YYYY-MM-DD}-{slug}/` contains `brief.md`, `research/NN-*.md`, `architecture/overview.md` (+ `gaps.md`), `plan.md`, `sessions/`, and `progress.json`. +Every artifact lives in one project directory: `.claude/projects/{YYYY-MM-DD}-{slug}/` contains `brief.md`, `research/NN-*.md`, `plan.md`, `sessions/`, and `progress.json`. + +> **v3.0.0 — architect extracted to its own plugin.** The `/ultra-cc-architect-local` and `/ultra-skill-author-local` commands moved to the separate `ultra-cc-architect` plugin (v0.1.0). The plan command still auto-discovers `architecture/overview.md` if present, so installing both plugins gives you the full pipeline (brief → research → architect → plan → execute). See [CHANGELOG.md](CHANGELOG.md) for migration steps. ### Division of labor @@ -25,8 +25,7 @@ Every artifact lives in one project directory: `.claude/projects/{YYYY-MM-DD}-{s |---|---|---| | `/ultrabrief-local` | **Capture intent** — intent, goal, non-goals, success criteria, and a research plan with explicit topics. Interactive only. | `brief.md` (task brief) | | `/ultraresearch-local` | **Gather context** — code state, external docs, community, risk. Makes NO build decisions. | `research/NN-slug.md` (research brief) | -| `/ultra-cc-architect-local` | **Match to CC features** (optional) — match brief+research against Claude Code feature catalog (Hooks, Subagents, Skills, MCP, …) with brief-anchored rationale and honest coverage gaps. | `architecture/overview.md` + `architecture/gaps.md` | -| `/ultraplan-local` | **Transform intent into an executable contract** — per-step YAML manifest, regex-validated checkpoints, verifiable paths. Plan-critic is a hard gate. Auto-discovers `architecture/overview.md` as priors. | `plan.md` with Manifest blocks + `plan_version: 1.7` | +| `/ultraplan-local` | **Transform intent into an executable contract** — per-step YAML manifest, regex-validated checkpoints, verifiable paths. Plan-critic is a hard gate. Auto-discovers `architecture/overview.md` as priors when the `ultra-cc-architect` plugin is installed. | `plan.md` with Manifest blocks + `plan_version: 1.7` | | `/ultraexecute-local` | **Execute the contract disciplined** — fresh verification, independent manifest audit, honest reporting. Does NOT compensate for weak plans — escalates. | `progress.json` + structured report + manifest-audit status | **Principle:** Each step consumes the previous step's structured artifact. If execute has to guess, the plan is weak and must be revised upstream — not patched downstream. @@ -60,11 +59,7 @@ claude plugin marketplace add https://git.fromaitochitta.com/open/ktg-plugin-mar # Research each topic identified in the brief (manual default) /ultraresearch-local --project .claude/projects/2026-04-18-jwt-auth --external "What are current JWT best practices?" -# Match task against available CC features (optional, v2.2) -/ultra-cc-architect-local --project .claude/projects/2026-04-18-jwt-auth -# → architecture/overview.md + architecture/gaps.md - -# Plan from brief + research + architecture (architecture auto-discovered) +# Plan from brief + research /ultraplan-local --project .claude/projects/2026-04-18-jwt-auth # Execute @@ -73,6 +68,8 @@ claude plugin marketplace add https://git.fromaitochitta.com/open/ktg-plugin-mar Or opt into auto-mode in `/ultrabrief-local` — it will run research and planning sequentially inline in the main context, and return when `plan.md` is ready. +For Claude-Code-specific architecture matching (matching brief+research to features like Hooks, Subagents, Skills, MCP), install the separate `ultra-cc-architect` plugin. It sits between research and plan — `/ultraplan-local` auto-discovers its output. + > **v2.4.0 — background mode removed.** All four orchestrator commands now run foreground in the main context. The `--fg` flag is preserved as a no-op alias for backward compatibility. Background mode silently degraded the agent swarm (the harness does not expose the Agent tool to sub-agents) — see [CHANGELOG](CHANGELOG.md) for the full rationale. ## When to use it @@ -187,57 +184,6 @@ Flags combine: `--project --external`. --- -## `/ultra-cc-architect-local` — Architect *(optional, v2.2)* - -Matches the task brief and any research against available Claude Code features (Hooks, Subagents, Skills, Output Styles, MCP, Plan Mode, Worktrees, Background Agents) and produces an **architecture note** with brief-anchored rationale per feature and an explicit coverage-gap section. - -This step is optional. You can go straight from research to planning. Use the architect step when: - -- The task touches orchestration, policy, or long-running work where CC-feature choice matters. -- You want a reviewed, explicit feature selection before planning instead of letting the planner pick implicitly. -- You want a backlog of coverage gaps (things the skill catalog does not yet know) in a shareable form. - -### How it works - -1. Read `{project_dir}/brief.md` + all `{project_dir}/research/*.md`. -2. Read the CC-feature skill catalog from `skills/cc-architect-catalog/`. -3. Run `feature-matcher` + `gap-identifier` in parallel. -4. Write `architecture/overview.md` (six required sections, YAML frontmatter). -5. Run `architecture-critic` + `scope-guardian` in parallel (unless `--quick`). -6. Write `architecture/gaps.md` as issue-ready drafts (unless `--no-gaps`). - -Downstream: `/ultraplan-local` auto-discovers `architecture/overview.md` in project mode and treats its `cc_features_proposed` as *priors* — exploration agents may override with evidence. - -### Modes - -| Flag | Behavior | -|------|----------| -| `--project ` | **Required.** Read `{dir}/brief.md` + `{dir}/research/*.md`; write to `{dir}/architecture/`. | -| `--fg` | No-op alias (foreground is default since v2.4.0). | -| `--quick` | Skip adversarial review (no `architecture-critic` pass). | -| `--no-gaps` | Do not write `gaps.md` (gap-section remains inside `overview.md`). | - -### What the architecture note contains - -- **Context** — 3 sentences paraphrasing brief Intent + Goal. -- **Proposed CC features** — a table with rationale (brief-anchored), supporting skill, and confidence per feature. -- **Feature composition** — sequence, conflicts, fallbacks. -- **Coverage gaps identified** — always present, even if empty. Honest "what we don't know yet". -- **Alternatives considered** — at least one rejected feature combination with rationale from the brief. -- **Open questions** — forwarded to the plan phase. - -### CC-feature catalog - -The architect command reads from `skills/cc-architect-catalog/`, a plugin-internal catalog of hand-written skills covering each CC feature at one or more layers (`reference`, `pattern`, `decision`). v2.2 shipped 10 seeds covering all 8 features at the reference layer (plus pattern layer for hooks and subagents). The catalog is designed for expansion via the skill-factory process (v2.3) — gaps surfaced by the architect command are the backlog for that work. - -**Slug convention (v2.3):** files follow `[-]-.md`. Unqualified slugs (e.g., `hooks-pattern.md`) are the baseline/canonical entry for a `(feature, layer)` pair. Qualified slugs (e.g., `hooks-observability-pattern.md`) cover specific sub-patterns without displacing the baseline. `feature-matcher` prefers the baseline when the brief does not specifically justify a qualified variant; it may propose multiple supporting skills when they cover non-overlapping aspects. Slug collisions with approved skills are a hard error — skill-factory drafts must qualify or revise instead. **v2.3.2:** `skill-drafter` performs a pre-write check against `{catalog_root}/.md` and prepends a warning block to its confirmation when the proposed slug would collide, suggesting a qualified slug derived from the concept handle. The draft still writes to `.drafts/` — the warning exists so users see the overwrite risk before running `mv`. - -### Hallucination gate - -The `architecture-critic` agent blocks any feature proposal that is not in the catalog's `cc_feature` taxonomy or the `feature-matcher`'s documented fallback minimum list. This prevents the architect from inventing CC features that do not exist. - ---- - ## `/ultraplan-local` — Planning Produces an implementation plan detailed enough for autonomous execution. **v2.0 breaking change:** requires `--brief` or `--project`. There is no longer an interview inside `/ultraplan-local` — use `/ultrabrief-local` first. @@ -248,10 +194,11 @@ Produces an implementation plan detailed enough for autonomous execution. **v2.0 2. **Spec review** → **brief review** — `brief-reviewer` validates completeness, consistency, testability, scope clarity, and research plan validity 3. **Explore** — 6-8 specialized Sonnet agents analyze your codebase in parallel 4. **Research** — optional research briefs enrich planning (`--research`, or auto-discovered in `{project_dir}/research/`) -5. **Synthesize** — findings merged into a unified codebase understanding -6. **Plan** — Opus creates a comprehensive implementation plan with per-step YAML manifests -7. **Critique** — adversarial review by `plan-critic` (9 dimensions) and `scope-guardian` -8. **Handoff** — plan written; execute now, save for later, or export +5. **Architecture priors** — if `{project_dir}/architecture/overview.md` exists (produced by the optional `ultra-cc-architect` plugin), `cc_features_proposed` are loaded as priors. Missing file is fine. +6. **Synthesize** — findings merged into a unified codebase understanding +7. **Plan** — Opus creates a comprehensive implementation plan with per-step YAML manifests +8. **Critique** — adversarial review by `plan-critic` (9 dimensions) and `scope-guardian` +9. **Handoff** — plan written; execute now, save for later, or export Output: - With `--project `: `{dir}/plan.md` @@ -402,52 +349,6 @@ The executor implements defense-in-depth security across four layers: --- -## `/ultra-skill-author-local` — Authoring *(skill-factory Fase 1, v2.3)* - -Manual one-skill-at-a-time generator for the `cc-architect-catalog`. Channel 2 of the skill-factory strategy: 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). - -### Why it exists - -`/ultra-cc-architect-local` enforces a hallucination gate that only permits feature proposals backed by the catalog. With 10 seed skills covering 8 features × 2 layers, the matcher rarely finds support and silently produces empty proposals. This command grows the catalog without spinning up automation: one source → one draft → manual review → manual `mv` for promotion. - -### Pipeline - -Sequential, no retry, no parallelism: - -``` -/ultra-skill-author-local - → concept-extractor (sonnet) → JSON: cc_feature, layer, slug - → skill-drafter (sonnet) → .drafts/.md, 9-field frontmatter - → ip-hygiene-checker (sonnet) → runs scripts/ngram-overlap.mjs - verdict accepted/needs-review → stamp ngram_overlap_score - verdict rejected → rm draft (no preservation) -``` - -### Modes - -| Mode | Usage | Behavior | -|------|-------|----------| -| **Default** | `/ultra-skill-author-local ` | Run the pipeline (concept → draft → IP-hygiene) foreground | -| **`--fg`** | `/ultra-skill-author-local --fg` | Same as default; flag accepted for pipeline-convention consistency | -| **`--quick`** | `/ultra-skill-author-local --quick` | Skip IP-hygiene with BIG WARNING (drafting-pipeline test only) | - -### IP-hygiene utility - -`scripts/ngram-overlap.mjs` — pure Node stdlib, zero dependencies. Word-5-gram containment similarity (asymmetric draft⊆source) plus longest-consecutive-shingle-run secondary signal. Verdict bands: `accepted` (<0.15 AND <8), `needs-review` (mid), `rejected` (≥0.35 OR ≥15). Short-text fallback to n=4 when min(words) <500. CLI emits JSON. - -Calibration fixtures in `tests/fixtures/skill-factory/` pin the verdict bands against representative prose. Re-verify any threshold change against these fixtures. - -### Non-goals (explicit, Fase 1) - -- No automation, cron, or watcher -- No CC changelog diffing or auto-research -- No batch processing or review command -- No decision-layer skills (cross-feature comparison is Fase 2+) -- No URL or remote sources — local files only -- Manual `mv` from `.drafts/` to catalog root is the promotion mechanism - ---- - ## The full pipeline ``` @@ -459,7 +360,7 @@ Calibration fixtures in `tests/fixtures/skill-factory/` pin the verdict bands ag │ ↓ │ │ ↓ │ │ agents (parallel) │ │ ↓ │ │ Research │ │ Triangulation │ │ ↓ │ │ Execute steps │ │ topics │ │ ↓ │ │ Opus planning │ │ (verify + manifest │ - │ ↓ │ → brief → (optional) ─→ → │ ↓ │→ │ + checkpoint) │ + │ ↓ │ → brief → → → → → → → → → → → ↓ │→ │ + checkpoint) │ │ brief.md │ │ research/*.md │ │ plan-critic + │ │ ↓ │ └──────────────┘ └───────────────────┘ │ scope-guardian │ │ Phase 7.5 manifest │ │ ↓ │ │ audit + 7.6 recovery│ @@ -470,6 +371,8 @@ Calibration fixtures in `tests/fixtures/skill-factory/` pin the verdict bands ag All artifacts live under `.claude/projects/{YYYY-MM-DD}-{slug}/`. +To insert a Claude-Code-specific architecture-matching step between research and plan, install the separate `ultra-cc-architect` plugin — `/ultraplan-local` auto-discovers its `architecture/overview.md` output as priors. + ### Example workflows **Standard pipeline (manual control):** @@ -521,6 +424,28 @@ All artifacts live under `.claude/projects/{YYYY-MM-DD}-{slug}/`. --- +## Upgrading from v2.x to v3.0.0 + +v3.0.0 is a structural release that does **not** break the planning flow but changes plugin layout: + +- `/ultra-cc-architect-local` and `/ultra-skill-author-local` were moved to the new `ultra-cc-architect` plugin (v0.1.0). +- `/ultraplan-local` still auto-discovers `architecture/overview.md` if present — install both plugins to keep the full pipeline working. +- `cc-architect-catalog` skill moved to the new plugin. If you customized seeds locally, follow `git log --follow` to track them in the new location. +- `ngram-overlap.mjs` script and skill-factory test fixtures moved with the new plugin. + +If you only used `/ultrabrief-local`, `/ultraresearch-local`, `/ultraplan-local`, and `/ultraexecute-local`: no action needed. Update the plugin and continue. + +If you used `/ultra-cc-architect-local` or `/ultra-skill-author-local`: install the new plugin alongside this one: + +```json +{ + "enabledPlugins": { + "ultraplan-local@ktg-plugin-marketplace": true, + "ultra-cc-architect@ktg-plugin-marketplace": true + } +} +``` + ## Upgrading from v1.x v2.0.0 is a **breaking release**. See [MIGRATION.md](MIGRATION.md) for a step-by-step guide. Short version: @@ -570,6 +495,8 @@ Or enable directly in `~/.claude/settings.json`: } ``` +For Claude-Code-specific architecture matching (between research and plan), also enable `ultra-cc-architect@ktg-plugin-marketplace`. + ## Cost profile - **Brief**: 1 Opus session (interactive; interview + write) @@ -596,7 +523,7 @@ The plugin minimizes Opus usage by front-loading cheap Sonnet exploration. ``` ultraplan-local/ ├── .claude-plugin/ -│ └── plugin.json # Plugin manifest (v2.0.0) +│ └── plugin.json # Plugin manifest (v3.0.0) ├── agents/ # 19 specialized agents │ ├── architecture-mapper.md # Codebase structure and patterns │ ├── dependency-tracer.md # Import chains and data flow @@ -641,6 +568,8 @@ ultraplan-local/ └── README.md ``` +CC-feature catalog, skill-factory, and architect/skill-author commands moved to the separate `ultra-cc-architect` plugin in v3.0.0. + Pure markdown commands and agents. Hooks are self-contained Node.js with zero dependencies. ## Contributing diff --git a/plugins/ultraplan-local/commands/ultraplan-local.md b/plugins/ultraplan-local/commands/ultraplan-local.md index c7ed18a..6bc6e5e 100644 --- a/plugins/ultraplan-local/commands/ultraplan-local.md +++ b/plugins/ultraplan-local/commands/ultraplan-local.md @@ -64,8 +64,8 @@ Parse `$ARGUMENTS` for mode flags. Order of precedence: - Set **has_research_brief = true** if `{dir}/research/*.md` matches ≥ 1 file. - Set **has_architecture_note = true** if `{dir}/architecture/overview.md` exists. If set, **architecture_note_path = {dir}/architecture/overview.md**. Produced by - the optional `/ultra-cc-architect-local` command. Missing file is fine — this is - additive discovery, not a requirement. + the optional `/ultra-cc-architect-local` command from the separate `ultra-cc-architect` + plugin. Missing file is fine — this is additive discovery, not a requirement. 4. **`--brief `** — extract the brief path. If the file does not exist: ```