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>
This commit is contained in:
Kjell Tore Guttormsen
parent
97c5c9d934
commit
ab504bdf8c
48 changed files with 627 additions and 177 deletions
|
|
@ -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."
|
||||
}
|
||||
]
|
||||
}
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
|
|
|||
43
README.md
43
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 <dir>` 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 <dir>` 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 (`<cc_feature>[-<qualifier>]-<layer>.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}/<slug>.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: `<cc_feature>[-<qualifier>]-<layer>.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.
|
||||
|
|
|
|||
12
plugins/ultra-cc-architect/.claude-plugin/plugin.json
Normal file
12
plugins/ultra-cc-architect/.claude-plugin/plugin.json
Normal file
|
|
@ -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"]
|
||||
}
|
||||
21
plugins/ultra-cc-architect/.gitignore
vendored
Normal file
21
plugins/ultra-cc-architect/.gitignore
vendored
Normal file
|
|
@ -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
|
||||
51
plugins/ultra-cc-architect/CHANGELOG.md
Normal file
51
plugins/ultra-cc-architect/CHANGELOG.md
Normal file
|
|
@ -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/<slug>.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: `<cc_feature>[-<qualifier>]-<layer>.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.
|
||||
111
plugins/ultra-cc-architect/CLAUDE.md
Normal file
111
plugins/ultra-cc-architect/CLAUDE.md
Normal file
|
|
@ -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 <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.
|
||||
21
plugins/ultra-cc-architect/LICENSE
Normal file
21
plugins/ultra-cc-architect/LICENSE
Normal file
|
|
@ -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.
|
||||
191
plugins/ultra-cc-architect/README.md
Normal file
191
plugins/ultra-cc-architect/README.md
Normal file
|
|
@ -0,0 +1,191 @@
|
|||
# ultra-cc-architect — Match tasks to Claude Code features
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
*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 <dir>` | **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 <source>
|
||||
→ concept-extractor (sonnet) → JSON: cc_feature, layer, slug
|
||||
→ skill-drafter (sonnet) → .drafts/<slug>.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 <source>` | Run the pipeline foreground |
|
||||
| **`--fg`** | `/ultra-skill-author-local <source> --fg` | Same as default; flag accepted for pipeline-convention consistency |
|
||||
| **`--quick`** | `/ultra-skill-author-local <source> --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:** `<cc_feature>[-<qualifier>]-<layer>.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)
|
||||
|
|
@ -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"]
|
||||
}
|
||||
|
|
|
|||
9
plugins/ultraplan-local/.gitignore
vendored
9
plugins/ultraplan-local/.gitignore
vendored
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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 <dir> --local`, `--external --quick`.
|
||||
|
||||
### /ultra-cc-architect-local modes *(optional, v2.2)*
|
||||
|
||||
| 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 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 <dir>` fills in `{dir}/research/`. `/ultra-cc-architect-local --project <dir>` *(optional, v2.2)* matches available Claude Code features against brief+research and writes `{dir}/architecture/`. `/ultraplan-local --project <dir>` reads brief + research (+ architecture note if present) to produce `{dir}/plan.md`. `/ultraexecute-local --project <dir>` executes and writes `{dir}/progress.json`. All artifacts live in one project directory.
|
||||
**Pipeline:** `/ultrabrief-local` produces the task brief. `/ultraresearch-local --project <dir>` fills in `{dir}/research/`. `/ultraplan-local --project <dir>` 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 <dir>` 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 `<cc_feature>[-<qualifier>]-<layer>.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}/<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 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/<slug>.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.
|
||||
|
|
|
|||
|
|
@ -1,23 +1,23 @@
|
|||
# ultraplan-local — Brief, Research, Architect, Plan, Execute
|
||||
# ultraplan-local — Brief, Research, Plan, Execute
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
*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 <dir> --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 <dir>` | **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 `<cc_feature>[-<qualifier>]-<layer>.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}/<slug>.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>`: `{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 <source>
|
||||
→ concept-extractor (sonnet) → JSON: cc_feature, layer, slug
|
||||
→ skill-drafter (sonnet) → .drafts/<slug>.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 <source>` | Run the pipeline (concept → draft → IP-hygiene) foreground |
|
||||
| **`--fg`** | `/ultra-skill-author-local <source> --fg` | Same as default; flag accepted for pipeline-convention consistency |
|
||||
| **`--quick`** | `/ultra-skill-author-local <source> --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
|
||||
|
|
|
|||
|
|
@ -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 <path>`** — extract the brief path. If the file does not exist:
|
||||
```
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue