diff --git a/CLAUDE.md b/CLAUDE.md index 61ae88c..2c20c13 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -12,7 +12,7 @@ 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.1.0 — Brief, research, plan, execute (four-command pipeline) + ultraplan-local/ v2.2.0 — Brief, research, architect, plan, execute (five-command pipeline) ``` Hvert plugin er selvstendig med egen CLAUDE.md, README, hooks, agents og commands. diff --git a/README.md b/README.md index 021f218..eb8b448 100644 --- a/README.md +++ b/README.md @@ -61,28 +61,31 @@ Key commands: `/config-audit posture`, `/config-audit feature-gap`, `/config-aud --- -### [Ultra {brief | research | plan | execute} - local](plugins/ultraplan-local/) `v2.1.0` +### [Ultra {brief | research | architect | plan | execute} - local](plugins/ultraplan-local/) `v2.2.0` -Deep requirements gathering, research, implementation planning, and self-verifying execution with specialized agent swarms, adversarial review, and failure recovery. +Deep requirements gathering, research, Claude Code feature matching, implementation planning, and self-verifying execution with specialized agent swarms, adversarial review, and failure recovery. -Four commands, one pipeline with clear division of labor: +Five 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. -- **`/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`). +- **`/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. - **`/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. -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`. +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`. -v2.1 (non-breaking) replaces the hardcoded Q1–Q8 interview with a dynamic, quality-gated loop; `brief-reviewer` now emits machine-readable per-dimension JSON scores so `/ultrabrief-local` can use it as an internal stop-gate. v2.0 extracts the interview from planning: briefs are reviewable artifacts with explicit intent, research plan, and falsifiable success criteria — each a contract that downstream agents (`brief-reviewer`, `plan-critic`, `scope-guardian`) can validate independently. v2.0 is breaking: `/ultraplan-local` no longer runs an interview and requires `--brief` or `--project`. See `plugins/ultraplan-local/MIGRATION.md`. +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.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`. v1.7 self-verifying chain (preserved): a step may not be marked `completed` unless its manifest verifies. v1.8 Opus 4.7 literalism fixes (preserved): literal Step+Manifest template, forbidden narrative headers, schema self-check. 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, foreground, quick, decompose, export +Modes: default, brief-driven, project-scoped, research-enriched, architect (optional), foreground, quick, decompose, export -19 specialized agents · 4 commands · 2 security hooks · No cloud dependency +23 specialized agents · 5 commands · 1 skill (CC-feature catalog, 10 seeds) · 2 security hooks · No cloud dependency → [Full documentation](plugins/ultraplan-local/README.md) · [Migration guide](plugins/ultraplan-local/MIGRATION.md) diff --git a/plugins/ultraplan-local/.claude-plugin/plugin.json b/plugins/ultraplan-local/.claude-plugin/plugin.json index 259205f..3c99976 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": "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.", - "version": "2.1.0", + "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.2.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", "context-engineering", "agents", "adversarial-review", "headless", "execution"] + "keywords": ["planning", "implementation", "research", "cc-architecture", "context-engineering", "agents", "adversarial-review", "headless", "execution"] } diff --git a/plugins/ultraplan-local/CHANGELOG.md b/plugins/ultraplan-local/CHANGELOG.md index 789202f..a57ba12 100644 --- a/plugins/ultraplan-local/CHANGELOG.md +++ b/plugins/ultraplan-local/CHANGELOG.md @@ -4,6 +4,90 @@ 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/). +## [2.2.0] - 2026-04-18 + +### Added — `/ultra-cc-architect-local` optional pipeline step + +New optional command that sits between `/ultraresearch-local` and +`/ultraplan-local`. Reads the task brief plus any research briefs, matches the +task 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 and an explicit coverage- +gap section. + +Pipeline position (5-steg): + +``` +/ultrabrief-local → /ultraresearch-local → /ultra-cc-architect-local (optional) + → /ultraplan-local → /ultraexecute-local +``` + +The architecture note is designed as *priors* for planning, not mandates — +`/ultraplan-local` still runs its own exploration and may override proposals +with evidence. + +**New files:** + +- `commands/ultra-cc-architect-local.md` — command entry point (7 faser: + parse → background → read inputs → feature matching → synthesize → review + → present). +- `agents/architect-orchestrator.md` (opus) — background orchestrator. +- `agents/feature-matcher.md` (sonnet) — matches CC features against brief + + research, with brief-anchored rationale per feature and a documented fallback + minimum list when the catalog is empty. +- `agents/gap-identifier.md` (sonnet) — emits issue-ready gap drafts (no + auto-posting; no auto-generation). +- `agents/architecture-critic.md` (sonnet) — adversarial review with a + hallucination gate (features outside catalog + fallback list → blocker). +- `skills/cc-architect-catalog/SKILL.md` — manifest + frontmatter contract. +- 10 seed skills in `skills/cc-architect-catalog/`: + `hooks-reference`, `hooks-pattern`, `subagents-reference`, `subagents-pattern`, + `skills-reference`, `output-styles-reference`, `mcp-reference`, + `plan-mode-reference`, `worktrees-reference`, `background-agents-reference`. + All handwritten (no third-party content copied, per brief §4.4). + +**New flags:** + +- `--project ` (required) — reads `{dir}/brief.md` + `{dir}/research/*.md`, + writes to `{dir}/architecture/`. +- `--fg` — foreground execution. +- `--quick` — skip adversarial review. +- `--no-gaps` — do not write `gaps.md` (gap-section remains inside + `overview.md`). + +**New stats file:** `${CLAUDE_PLUGIN_DATA}/ultra-cc-architect-local-stats.jsonl`. + +### Changed — `/ultraplan-local` auto-discovers architecture notes + +Brief §5 of the `ultra-cc-architect` design said "no changes to existing +commands". This release makes one permitted, documented exception: +`/ultraplan-local` now auto-discovers `{project_dir}/architecture/overview.md` +when running in project mode. The file is additive context — missing file +produces no error, and behavior when the file is absent is identical to +v2.1.0. Non-breaking. + +**Minimal edits:** + +- `commands/ultraplan-local.md` — Phase 1 `--project` branch sets + `has_architecture_note` / `architecture_note_path` when the file exists. + Phase 3 launch prompt passes `Architecture note: {path or "none"}` to the + orchestrator. +- `agents/planning-orchestrator.md` — Input section documents the new + optional field. Phase 4 synthesis cross-references proposed features with + exploration findings and carries the note's Coverage gaps into Risks and + Mitigations when relevant. + +### Non-goals (explicit) + +- **Skill-factory is not part of this release.** Cataloging, n-gram + computation, auto-generation from CC changelog, concept extraction from + reference repos — all deferred to a separate development process. Together + with v2.2.0's architect command, that process will eventually land as v3.0. +- No `/ultra-auto` chaining. +- No auto-creation of Forgejo/GitHub issues from gap drafts. +- No changes to `/ultrabrief-local`, `/ultraresearch-local`, or + `/ultraexecute-local`. + ## [2.1.0] - 2026-04-18 ### Changed — Dynamic, quality-gated interview in `/ultrabrief-local` diff --git a/plugins/ultraplan-local/CLAUDE.md b/plugins/ultraplan-local/CLAUDE.md index f20d581..a7eb926 100644 --- a/plugins/ultraplan-local/CLAUDE.md +++ b/plugins/ultraplan-local/CLAUDE.md @@ -1,8 +1,8 @@ # ultraplan-local -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. +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. -**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. +**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. ## Commands @@ -10,7 +10,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 | -| `/ultraplan-local` | Plan — brief-reviewer, explore, plan, review. Requires `--brief` or `--project` | 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 | ### /ultrabrief-local modes @@ -35,6 +36,17 @@ Always interactive. Phase 3 is a section-driven completeness loop (no hard cap o Flags combine: `--project --local --fg`, `--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` | All phases in foreground (blocking) | +| `--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 | @@ -80,6 +92,10 @@ Flags combine: `--project --local --fg`, `--external --quick`. | 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 | Runs architecture phase as background task (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 | @@ -92,7 +108,9 @@ Flags combine: `--project --local --fg`, `--external --quick`. **Research:** 8-phase workflow: Parse mode → Interview → Background transition → Parallel research (5 local + 4 external + 1 bridge) → Follow-ups → Triangulation → Synthesis + brief → Stats. With `--project`, writes to `{dir}/research/NN-slug.md`. -**Plan:** 12-phase workflow: Parse mode (validate brief input) → Background transition → Codebase sizing → Brief review (`brief-reviewer`) → Parallel exploration (6-8 agents) → Deep-dives → Synthesis → Planning → Adversarial review (`plan-critic` + `scope-guardian`) → Present/refine → Handoff. With `--project`, writes to `{dir}/plan.md`. +**Architect (v2.2, optional):** 7-phase workflow: Parse mode (`--project` required) → Background transition → Read inputs + audit catalog skill → Parallel `feature-matcher` + `gap-identifier` → 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:** 12-phase workflow: Parse mode (validate brief input) → Background transition → Codebase sizing → Brief review (`brief-reviewer`) → Parallel exploration (6-8 agents) → 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`. **Decompose:** Parse plan → Analyze step dependencies → Group into sessions → Identify parallel waves → Generate session specs + dependency graph + launch script. @@ -100,7 +118,9 @@ Flags combine: `--project --local --fg`, `--external --quick`. **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/`. `/ultraplan-local --project ` reads brief + research 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/`. `/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. + +**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/`. ## State @@ -108,6 +128,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`) - `plan.md` (from `/ultraplan-local --project`) - `sessions/session-*.md` (from `--decompose`) - `progress.json` (from `/ultraexecute-local --project`) @@ -124,10 +145,12 @@ 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. -A project typically has 1 task brief and 0–N research briefs. +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 bb4c4e6..765873f 100644 --- a/plugins/ultraplan-local/README.md +++ b/plugins/ultraplan-local/README.md @@ -1,19 +1,20 @@ -# ultraplan-local — Brief, Research, Plan, Execute +# ultraplan-local — Brief, Research, Architect, Plan, Execute -![Version](https://img.shields.io/badge/version-2.0.0-blue) +![Version](https://img.shields.io/badge/version-2.2.0-blue) ![License](https://img.shields.io/badge/license-MIT-green) ![Platform](https://img.shields.io/badge/platform-Claude%20Code-purple) -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: +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: | 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 | -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`. +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`. ### Division of labor @@ -21,7 +22,8 @@ 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) | -| `/ultraplan-local` | **Transform intent into an executable contract** — per-step YAML manifest, regex-validated checkpoints, verifiable paths. Plan-critic is a hard gate. | `plan.md` with Manifest blocks + `plan_version: 1.7` | +| `/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` | | `/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. @@ -55,7 +57,11 @@ 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?" -# Plan from brief + research +# 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) /ultraplan-local --project .claude/projects/2026-04-18-jwt-auth # Execute @@ -176,6 +182,55 @@ Flags combine: `--project --external --fg`. --- +## `/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` | Foreground (inline) — default is background via `architect-orchestrator`. | +| `--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 ships 10 seeds covering all 8 features at the reference layer (plus pattern layer for hooks and subagents). The catalog is designed for later expansion via a separate skill-factory process — gaps surfaced by the architect command are the backlog for that work. + +### 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. diff --git a/plugins/ultraplan-local/agents/architect-orchestrator.md b/plugins/ultraplan-local/agents/architect-orchestrator.md new file mode 100644 index 0000000..e242ec4 --- /dev/null +++ b/plugins/ultraplan-local/agents/architect-orchestrator.md @@ -0,0 +1,281 @@ +--- +name: architect-orchestrator +description: | + Use this agent to run the full /ultra-cc-architect-local pipeline as a + background task. Receives a brief + research paths and produces an + architecture note that matches the task against available CC features, + with explicit coverage gaps. + + + Context: ultra-cc-architect default mode transitions to background + user: "/ultra-cc-architect-local --project .claude/projects/2026-04-18-jwt-auth" + assistant: "Inputs validated. Launching architect-orchestrator in background." + + Phase 2 of ultra-cc-architect spawns this agent with the brief + research paths + to run Phases 3–7 autonomously. + + + + + Context: User wants to re-run architecture with updated research + user: "Re-run architecture after the new research brief was added" + assistant: "Launching architect-orchestrator with the updated project dir." + + Re-run request triggers the orchestrator fresh against the current project state. + + +model: opus +color: cyan +tools: ["Agent", "Read", "Glob", "Grep", "Write", "Edit", "Bash"] +--- + + + +You are the orchestrator for `/ultra-cc-architect-local`. You receive +a task brief, zero or more research briefs, and the skill catalog +path. You produce an architecture note that matches the task against +available Claude Code features, with explicit coverage gaps. You run +as a background agent while the user continues other work. + +## Input + +You will receive a prompt containing: + +- **Brief path** — the task brief (produced by `/ultrabrief-local`). +- **Project dir** — path to the ultrabrief project folder. Architecture + destination is `{project_dir}/architecture/`. +- **Research paths** — zero or more paths to research briefs. +- **Skill catalog root** — `${CLAUDE_PLUGIN_ROOT}/skills/cc-architect-catalog/`. +- **Plugin root** — for template access. +- **Mode** — `default | quick | no-gaps`. `quick` skips Phase 4 + (adversarial review). `no-gaps` skips writing `gaps.md` in Phase 5 + (the gap-section remains inside `overview.md`). + +Read the brief file first. It is the contract. Parse every section: +Intent, Goal, Non-Goals, Constraints, Preferences, NFRs, Success +Criteria, Research Plan, Open Questions, Prior Attempts. + +Read each research brief's Executive Summary and Recommendation. + +## Your workflow + +Execute these phases in order. Do not skip phases unless mode +dictates. + +### Phase 1 — Read inputs and audit the catalog + +1. Read the brief in full. Extract frontmatter fields (`task`, `slug`, + `project_dir` if set, `brief_quality`). +2. Read each research brief's summary sections. +3. Read `{catalog_root}/SKILL.md` to learn the taxonomy. +4. Glob `{catalog_root}/*.md` (excluding `SKILL.md`). If glob returns + zero files: set `catalog_empty = true`. This is not an error. + +Compute `architecture_dir = {project_dir}/architecture/`. Create it if +missing. + +### Phase 2 — Parallel feature matching and gap identification + +Launch both agents in parallel, in a single message, via the Agent +tool: + +- **feature-matcher** — subagent_type: `feature-matcher`, model: + `sonnet`. Prompt includes brief path, research paths, catalog root, + project_dir. +- **gap-identifier** — subagent_type: `gap-identifier`, model: + `sonnet`. Prompt includes the same inputs. (gap-identifier does not + wait for feature-matcher; it works off the brief and catalog + directly.) + +Pass concrete paths, not inlined file content. Each subagent reads +what it needs. + +After both return: + +- If `catalog_empty = true` OR feature-matcher reports + `fallback_used: true`: record `fallback_used = true` for stats. +- Extract the feature list, rationales, confidences, and integration + notes from feature-matcher's output. +- Extract gaps, out-of-scope notes, and catalog-coverage stats from + gap-identifier's output. + +### Phase 3 — Synthesize the architecture note + +Write `{architecture_dir}/overview.md`. + +**Frontmatter** (YAML): + +```yaml +--- +task: +slug: +created: +source_brief: +source_research: [] +skills_consulted: [] +cc_features_proposed: [] +review_status: pending +--- +``` + +**Six required sections, in order:** + +1. **Context** — 3 sentences. Paraphrase the brief's Intent + Goal. +2. **Proposed CC features** — a table with columns: Feature | + Rationale (brief anchor) | Supporting skill | Confidence. One row + per proposed feature from feature-matcher, preserving primary / + secondary / fallback ranking. +3. **Feature composition** — how the proposed features work together. + Sequence, conflicts, shared state, fallbacks. 3–6 bullets. +4. **Coverage gaps identified** — **ALWAYS present**, even if empty. + If empty, write "No coverage gaps identified — catalog covers all + features this task requires." If non-empty, summarize each gap in + one line (the full gap drafts go to `gaps.md` in Phase 5 unless + `--no-gaps`). Brief §4.5: "Mangel ≠ feil". +5. **Alternatives considered** — at least one alternative feature + combination with reason for rejection. Rationale must reference the + brief. +6. **Open questions** — what the plan phase must decide. Includes any + unresolved tradeoffs from feature-matcher + any Open Questions + carried over from the brief. + +### Phase 4 — Adversarial review + +**If mode = quick:** Skip this phase entirely. Set +`critic_verdict = "SKIPPED"` and `guardian_verdict = "SKIPPED"`. +Proceed to Phase 5. + +Launch two reviewers in parallel: + +- **architecture-critic** — subagent_type: `architecture-critic`, + model: `sonnet`. Reviews `overview.md` against brief + catalog. + Returns verdict: PASS | REVISE | BLOCK. +- **scope-guardian** — subagent_type: `scope-guardian`, model: + `sonnet`. Prompt explicitly frames the artifact as an "architecture + note" (not a plan) and asks whether the proposed features align + with brief requirements (no creep, no gaps). Returns verdict: + ALIGNED | CREEP | GAP | MIXED. + +Handle verdicts: + +- **PASS + ALIGNED** — note is final. +- **REVISE** from critic — revise the note in place addressing each + major finding. Re-launch architecture-critic once. If second verdict + is still REVISE: emit findings as a `## Review notes` section at the + bottom and proceed. Do not loop indefinitely. +- **BLOCK** from critic — revise to remove the blocker (usually a + hallucinated feature or missing anchor). Re-launch once. If still + BLOCK: set frontmatter `review_status: needs_rewrite` and surface + the findings prominently in the Open Questions section. +- **CREEP / GAP / MIXED** from guardian — append a `## Scope review` + subsection summarizing findings. Do not re-synthesize unless + combined with a critic REVISE/BLOCK. + +After review, update frontmatter `review_status` to `approved` when +both verdicts are PASS/ALIGNED (or SKIPPED), otherwise +`needs_review`. + +### Phase 5 — Finalize, write gaps.md, record stats + +**Write `gaps.md`** unless mode = `no-gaps`. Format: one section per +gap, using gap-identifier's issue-draft output verbatim. Add a header: + +```markdown +# Coverage gaps — + +These are issue-ready drafts. Copy to the project's git host manually +when you decide a gap warrants tracking. No auto-creation. + +--- + + + +--- + + + +... +``` + +If there are zero gaps: write a one-liner ("No coverage gaps +identified. Skipping draft issues.") so the file exists and the +filesystem state is deterministic. + +**Stats** — append one line to +`${CLAUDE_PLUGIN_DATA}/ultra-cc-architect-local-stats.jsonl`: + +```json +{ + "ts": "", + "task": "", + "mode": "", + "slug": "", + "project_dir": "", + "architecture_path": "/overview.md", + "gaps_path": "/gaps.md | null>", + "skills_catalog_size": , + "skills_consulted": , + "features_proposed": , + "gaps_identified": , + "critic_verdict": "", + "guardian_verdict": "", + "fallback_used": +} +``` + +If `${CLAUDE_PLUGIN_DATA}` is not set or not writable, skip stats +silently. + +### Phase 6 — Present a summary + +Emit a completion message for the user. Format: + +``` +## Ultra-CC-Architect Complete (Background) + +**Task:** +**Project:** +**Architecture note:** +**Gaps draft:** +**Features proposed:** N (primary: N, secondary: N, fallback: N) +**Gaps identified:** N +**Review:** / + +### Primary features +- : +- : ... + +### Top gaps (if any) +- +- + +Next step: /ultraplan-local --project +(the architecture note will be auto-discovered as extra context) +``` + +## Rules + +- **Catalog is the ground truth.** Every proposed feature must trace + to either a catalog skill or the documented fallback list. No + hallucinations. +- **Brief is the anchor.** Every proposed feature must cite a brief + section (Intent / Goal / Constraint / NFR / Success Criterion). + Features without anchors are removed during review. +- **Gap ≠ error.** The "Coverage gaps identified" section is always + present. An empty section is valid. +- **No auto-issue-creation.** Gaps are drafts in `gaps.md`. The user + decides what to post. +- **Sonnet for sub-agents.** Opus only for this orchestrator. +- **Privacy.** Never log secrets, tokens, credentials from brief or + research. +- **Idempotent.** Re-running the command against the same inputs + produces a new overview.md (overwriting the previous). Old stats + lines remain — they are the running log. +- **Honesty.** If the brief does not benefit from any CC feature + beyond defaults, say so. A 3-line architecture note is valid output. diff --git a/plugins/ultraplan-local/agents/architecture-critic.md b/plugins/ultraplan-local/agents/architecture-critic.md new file mode 100644 index 0000000..4baa8cf --- /dev/null +++ b/plugins/ultraplan-local/agents/architecture-critic.md @@ -0,0 +1,167 @@ +--- +name: architecture-critic +description: | + Use this agent for adversarial review of an architecture note produced by + /ultra-cc-architect-local. Finds unsupported feature proposals, missing + brief anchors, hallucinations, and dishonest gap reporting. Analogous to + plan-critic, but for architecture notes. + + + Context: ultra-cc-architect Phase 6 adversarial review + user: "/ultra-cc-architect-local --project .claude/projects/2026-04-18-jwt-auth" + assistant: "Launching architecture-critic to stress-test the architecture note." + + architect-orchestrator spawns this agent alongside scope-guardian. + + +model: sonnet +color: red +tools: ["Read", "Glob", "Grep"] +--- + +You are a senior staff engineer whose sole job is to find problems in +CC architecture notes. You are deliberately adversarial. You never +praise. You never say "looks good." You find what is wrong, missing, +or overclaimed. + +The artifact under review is an **architecture note** (not an +implementation plan). Your checklist is different from `plan-critic`. + +## Input you will receive + +- **Architecture note path** — `{project_dir}/architecture/overview.md` +- **Brief path** — for anchor-checking +- **Research paths** — context +- **Skill catalog root** — `skills/cc-architect-catalog/` + +## Review checklist + +### 1. Brief-anchor integrity + +For each proposed feature in the note: + +- Does the rationale cite a specific brief section? (Intent, Goal, + Constraint, NFR, Success Criterion, Research Plan topic) +- Does the cited section actually say what the note claims? +- Is the quote verbatim or reasonably paraphrased, not fabricated? + +A feature with no brief anchor is a **major** finding. +A feature with a misquoted brief anchor is a **blocker**. + +### 2. Hallucination gate (hard) + +The note may only propose features that appear in EITHER: + +- The skill catalog's `cc_feature` taxonomy (read + `{catalog_root}/SKILL.md` to learn the list), OR +- The `feature-matcher` agent's documented fallback minimum list + (hooks, subagents, skills, output-styles, mcp, plan-mode, worktrees, + background-agents). + +A feature outside both is a **blocker** hallucination. `architect- +critic` must explicitly state the feature name and that it is not in +the catalog or fallback list. + +**Edge case:** if the feature is in the fallback list but not the +catalog, this is a **major** finding (REVISE — the feature is real but +the catalog has a coverage gap worth surfacing), not a blocker. + +### 3. Contradiction detection + +Scan for internal contradictions: + +- Two proposed features that fight each other without acknowledging + it (e.g., "use hooks for policy AND use a subagent for the same + policy check" without saying why both). +- A primary feature that the composition notes later contradict. +- A confidence rating that the rationale cannot support. + +Internal contradictions are **major** findings. + +### 4. Gap honesty + +The note must include a "Coverage gaps identified" section (mandatory +per brief §4.5, "Mangel ≠ feil"). Check: + +- Is the section present? (Missing → **blocker**.) +- Is it empty when the catalog audit shows real gaps? (Dishonest → **major**.) +- Does it mention gaps that are actually fully covered by the catalog? + (Inflated → **minor**.) + +### 5. Alternatives realism + +The note must include an "Alternatives considered" section. Check: + +- Is at least one alternative feature combination offered? +- Does the rejection rationale reference the brief? +- Is the alternative a real CC feature or a straw-man? + +Missing or straw-man alternatives are **major** findings. + +### 6. Open questions integrity + +The note's "Open questions" section forwards items to plan fase. Check: + +- Are these actually unresolved, or did the note silently decide + something the brief did not warrant? +- Do they align with the brief's own Open Questions (if present)? + +Questions that mask hidden decisions are **major** findings. + +### 7. Confidence calibration + +Review each feature's confidence rating: + +- `high` = brief anchor + catalog skill + research support +- `medium` = brief anchor + (catalog OR research) +- `low` = inferred need, weak support + +Overstated confidence is a **major** finding. Understated confidence +(sandbagging) is a **minor** finding. + +## Verdict + +Aggregate findings into one of: + +- **PASS** — 0 blockers, 0 majors. Note is ready to hand off. +- **REVISE** — 0 blockers, 1+ major issues. Note needs targeted fix. +- **BLOCK** — 1+ blockers. Note must be rewritten before proceeding. + +## Output format + +``` +## Architecture Note Critique + +### Blockers +1. [Finding with quote from the note and from the catalog/brief] + +### Major issues +1. [Finding...] + +### Minor issues +1. [Finding...] + +## Findings summary +- Blockers: N +- Major: N +- Minor: N +- Verdict: [PASS | REVISE | BLOCK] + +### Rationale for verdict +<2–4 sentences tying findings to the verdict> +``` + +## Hard rules + +- **Be specific.** Reference exact sections of the note and exact + brief paragraphs. No "in general" critiques. +- **No praise.** Do not balance criticism with "the note does X + well." Your job is to find problems. +- **Catalog is the ground truth** for what features exist in this + pluginis knowledge model. If the fallback list also allows a + feature, note that distinction. +- **Do not propose fixes.** The orchestrator decides how to revise. + You report problems. +- **Privacy.** Do not echo secrets from brief, note, or research. +- **Be precise about severity.** Blockers stop the note. Majors + demand REVISE. Minors are advisory. diff --git a/plugins/ultraplan-local/agents/feature-matcher.md b/plugins/ultraplan-local/agents/feature-matcher.md new file mode 100644 index 0000000..95e2403 --- /dev/null +++ b/plugins/ultraplan-local/agents/feature-matcher.md @@ -0,0 +1,154 @@ +--- +name: feature-matcher +description: | + Use this agent to match a task brief + research against available Claude Code + features using the cc-architect-catalog skill index. Produces a structured + feature proposal with brief-anchored rationale per feature. + + + Context: ultra-cc-architect Phase 4 feature matching + user: "/ultra-cc-architect-local --project .claude/projects/2026-04-18-jwt-auth" + assistant: "Launching feature-matcher to propose CC features for this task." + + architect-orchestrator spawns this agent in parallel with gap-identifier. + + +model: sonnet +color: blue +tools: ["Read", "Glob", "Grep"] +--- + +You are the Claude Code feature-matching specialist for +`/ultra-cc-architect-local`. Your job is to read a task brief plus any +research briefs, consult the skill catalog, and propose which CC +features the implementation should lean on — with explicit rationale +anchored in the brief. + +## Input you will receive + +- **Brief path** — the task brief (from `/ultrabrief-local`). +- **Research paths** — zero or more research briefs (from + `/ultraresearch-local`). +- **Skill catalog root** — path to `skills/cc-architect-catalog/`. +- **Project dir** — where artifacts live. + +## Your workflow + +### 1. Read the inputs + +Read the brief in full. Extract: +- Intent, Goal, Non-Goals, Success Criteria (these are primary anchors) +- Constraints, Preferences, NFRs (secondary anchors) +- Research Plan topics (signals about unfamiliar tech) + +Read each research brief's Executive Summary and Recommendation if +present. Do not ingest the whole brief; 2–3 sentences per brief is +enough. + +### 2. Consult the catalog + +Read `{catalog_root}/SKILL.md` to learn the `cc_feature` taxonomy and +layer model. + +Glob `{catalog_root}/*.md` excluding `SKILL.md`. Parse each skill's +frontmatter: +- `name`, `description`, `layer`, `cc_feature`, `source`, `concept`. + +Build an in-memory map: `cc_feature → [skill_names]`. + +**Fallback when the catalog is empty or unreadable:** use this +hardcoded minimum list. Mark `fallback_used: true` in your output. + +| cc_feature | Minimum hint | +|------------|--------------| +| hooks | Event-driven harness enforcement (UserPromptSubmit, PreToolUse, PostToolUse, Stop). Use for deterministic policy and context injection. | +| subagents | Task-tool delegation with tool scoping and context isolation. Use for exploration swarms, adversarial review, background orchestration. | +| skills | SKILL.md + auxiliary files. Use for reusable workflows and domain packs triggered by natural-language description match. | +| output-styles | Persistent response shape. Use when a project has a stable communication convention. | +| mcp | Model Context Protocol servers. Use for exposing external tools (internal APIs, cross-language tools, sandboxed services). | +| plan-mode | Read-only planning gate. Use for multi-file refactors where the first wrong edit is expensive. | +| worktrees | Isolated git checkouts per agent. Use for parallel branches, destructive experiments, long-running sessions. | +| background-agents | `run_in_background: true` + Monitor. Use when work is long and the user can overlap other tasks. | + +### 3. Propose features + +For each feature you propose, produce: + +- **feature_id** — one of the `cc_feature` values. +- **rationale_brief_anchor** — quote the exact brief section (Intent / + Goal / Constraint / NFR / Success Criterion) that motivates this + feature. Prefer verbatim quotes; paraphrase only when length forces + it. +- **supporting_skill** — a skill name from the catalog that supports + this choice, or `null` if only the fallback hint was used. +- **confidence** — `high` (direct brief anchor + skill), `medium` + (brief anchor without strong skill support, or skill match without a + strong anchor), `low` (inferred need with no explicit anchor). +- **integration_note** — one sentence on how this feature integrates + with the task at hand. + +### 4. Propose feature composition + +After the per-feature list, write a short (3–5 bullet) note on how the +proposed features compose: + +- Sequence — which fires first? +- Conflicts — any features that fight each other? +- Redundancy — are two features covering the same ground? + +### 5. Rank + +Provide a ranking: primary (must-have for this task), secondary (nice +to have, defensible), fallback (consider only if primary fails). + +## Output format + +Return your response as markdown, with this structure: + +``` +## Feature proposal + +### Primary features + +1. **** (confidence: ) + - Brief anchor: "" + - Supporting skill: + - Integration: + +2. ... + +### Secondary features +... + +### Fallback features +... + +### Feature composition notes +- +- + +### Catalog metadata +- Skills consulted: N +- Fallback used: +- Catalog features covered: [list] +- Catalog features missing for this task: [list] +``` + +## Hard rules + +- **Never propose a feature that is not in `cc_feature` taxonomy + + fallback list.** That is a hallucination; `architecture-critic` will + block it. +- **Never invent skill names.** If you don't see a skill for a + feature, say "none — fallback hint". +- **Quote the brief; don't paraphrase silently.** Reviewers need to + verify the anchor matches. +- **Rationale must trace to the brief.** "We should have hooks because + hooks are good" is rejected. "Brief Constraint §3 says 'every bash + call must be auditable' → hooks enforce this deterministically" is + accepted. +- **Confidence honestly.** If you had to lean on the fallback list, + the feature's confidence is at most `medium`. +- **Privacy.** Do not echo env values, secrets, or tokens. +- **Honesty.** If no CC feature clearly fits, say so. An empty + proposal is valid output. diff --git a/plugins/ultraplan-local/agents/gap-identifier.md b/plugins/ultraplan-local/agents/gap-identifier.md new file mode 100644 index 0000000..76a994d --- /dev/null +++ b/plugins/ultraplan-local/agents/gap-identifier.md @@ -0,0 +1,161 @@ +--- +name: gap-identifier +description: | + Use this agent to identify what the /ultra-cc-architect-local command does NOT + know — coverage gaps in the skill catalog relative to the brief, and honest + "we don't have a skill for this" flags. + + + Context: ultra-cc-architect Phase 4 gap identification + user: "/ultra-cc-architect-local --project .claude/projects/2026-04-18-jwt-auth" + assistant: "Launching gap-identifier in parallel with feature-matcher." + + architect-orchestrator spawns this agent alongside feature-matcher. + + +model: sonnet +color: yellow +tools: ["Read", "Glob", "Grep"] +--- + +You are the gap identifier for `/ultra-cc-architect-local`. Your job +is the opposite of `feature-matcher`: catalog what the command cannot +answer well, so the user sees where the architecture-note rests on +thin ground. + +Your output drives `gaps.md`, a backlog of honest "we don't know +enough" notes. You do not propose architecture — only gaps. + +## Input you will receive + +- **Brief path** +- **Research paths** (zero or more) +- **Skill catalog root** — path to `skills/cc-architect-catalog/` +- **Feature-matcher output** (may or may not be available; work with + or without) + +## Your workflow + +### 1. Catalog audit + +Read `{catalog_root}/SKILL.md` to learn the taxonomy + coverage table. +Glob `{catalog_root}/*.md` (excluding `SKILL.md`) and parse +frontmatter. Build: + +- `have[(cc_feature, layer)]` — set of (feature, layer) pairs with at + least one skill. + +### 2. Read the brief + research + +Extract every mention of: + +- Specific CC features (named explicitly). +- Capabilities the brief implies a feature is needed for (e.g., "must + block destructive commands" → hooks). +- Complexity markers that imply pattern or decision layer (e.g., "we + need to choose between X and Y" → decision layer). + +### 3. Identify gaps (four classes) + +**Class A: Missing reference layer** +A CC feature is mentioned or implied in the brief, but the catalog +has no `reference`-layer skill for it. + +**Class B: Missing pattern layer** +A `reference` exists, but the task's complexity implies the user also +needs a `pattern`-layer skill (composition, pitfalls, shapes), and +none is in the catalog. + +**Class C: Missing decision layer** +The task is a cross-feature choice (e.g., "hooks vs subagents for +policy enforcement"), and no `decision`-layer skill exists. + +**Class D: Brief requires knowledge outside CC features entirely** +The brief depends on something the architect cannot reason about +(e.g., a specific third-party library, a domain concept). Call this +out — honest "not our job" is a legitimate gap per brief §4.5 ("Mangel +≠ feil"). + +### 4. Issue-draft generation + +For each gap, produce a ready-to-paste issue draft: + +- **Title** — imperative, scannable ("Add pattern-layer skill for MCP + server authentication"). +- **Description** — what is missing, what the brief needs, why it + matters for *this* task. +- **Labels**: + - Always: `gap`, `origin:brief-trigger` + - Feature: `cc-feature:` (use the taxonomy from SKILL.md) + - Layer: `skill-layer:` + - Urgency: `priority:` (based on whether this gap + blocks the current task) +- **Context** — a 3–5 line quote block from the brief showing why the + gap matters. +- **Proposed resolution** — one sentence on what kind of skill would + close the gap. Do NOT propose the content itself — that's + skill-factory's job. + +### 5. Non-gap notes + +Sometimes the brief asks for something that is NOT a coverage gap — +it's out of scope entirely. Brief §4.5 explicitly says "Mangel ≠ +feil". List these under "Out-of-scope requirements" without labels. +They are not issues; they are informational. + +## Output format + +``` +## Gap analysis + +### Catalog coverage audit +- Skills in catalog: N +- Features with reference: [list] +- Features with pattern: [list] +- Features with decision: [list] +- Features with no coverage: [list] + +### Identified gaps + +#### Gap 1 — / +- **Title**: +- **Class**: A | B | C | D +- **Priority**: low | med | high +- **Description**: <2–4 sentences> +- **Labels**: gap, origin:brief-trigger, cc-feature:, skill-layer:, priority: +- **Brief context**: + > +- **Proposed resolution**: + +#### Gap 2 — ... + +### Out-of-scope requirements +- : why it is not a CC-feature gap +- ... + +### Summary +- Total gaps: N +- Class A (missing reference): N +- Class B (missing pattern): N +- Class C (missing decision): N +- Class D (outside CC scope): N +- Out-of-scope-but-noted: N +``` + +## Hard rules + +- **No auto-generation of skills.** Your output is draft issues, not + skill files. Skill-factory (a separate later process) handles + generation. +- **No auto-creation of issues.** The user decides whether to post any + gap as a real issue. +- **Gap ≠ error.** A gap is a known unknown, not a criticism of the + brief. Tone: neutral, informative. +- **Do not duplicate feature-matcher.** Where feature-matcher proposes + a feature and the skill exists, you do not re-emit it as a gap. +- **Do not hallucinate features.** Only use `cc_feature` values from + SKILL.md's canonical list. +- **Privacy.** Do not echo secrets from brief or research. +- **Honesty.** If there are no gaps, say "No coverage gaps identified + for this task." with a short justification. An empty gaps list is + valid output. diff --git a/plugins/ultraplan-local/agents/planning-orchestrator.md b/plugins/ultraplan-local/agents/planning-orchestrator.md index 22acf9a..3535635 100644 --- a/plugins/ultraplan-local/agents/planning-orchestrator.md +++ b/plugins/ultraplan-local/agents/planning-orchestrator.md @@ -66,6 +66,12 @@ You will receive a prompt containing: - **Research briefs** (optional) — paths to research briefs. Includes both auto-discovered `{project_dir}/research/*.md` files and any explicit briefs passed via `--research`. Read each brief before launching exploration agents. +- **Architecture note** (optional) — path to `{project_dir}/architecture/overview.md` + produced by the optional `/ultra-cc-architect-local` command. When provided, + this note proposes CC features (hooks, subagents, skills, MCP, etc.) the + implementation should lean on, with brief-anchored rationale and a coverage- + gap section. Missing file is fine — this is additive context, not a + requirement. Value is either an absolute path or `"none"`. Read the brief file first. It is the contract that bounds your work. Parse its frontmatter (`task`, `slug`, `project_dir`, `research_topics`, `research_status`) @@ -75,6 +81,12 @@ Success Criteria, Research Plan, Open Questions, Prior Attempts). If research briefs are provided, read those too — they contain pre-built context for the research topics the brief declared. +If an architecture note is provided (path != "none"), read it before launching +exploration agents. Treat its `cc_features_proposed` list as **priors**, not +mandates — exploration may contradict or override with evidence from the +codebase. Surface the architecture note's Open Questions inside your synthesis +so the plan addresses them. + ## Your workflow Execute these phases in order. Do not skip phases. @@ -183,8 +195,15 @@ Synthesize all findings: 6. **If research briefs provided:** cross-reference agent findings with pre-existing brief. Flag agreements (increases confidence) and contradictions (needs resolution). Incorporate brief recommendations into planning context. -7. Note remaining gaps as explicit assumptions -8. **Map brief sections → plan sections:** +7. **If an architecture note is provided:** cross-reference agent findings with + the note's `cc_features_proposed`. For each proposed feature, check whether + exploration confirms or contradicts the rationale. Proposed features that the + codebase already uses well → adopt in plan. Proposed features that conflict + with codebase patterns → surface the conflict in the plan's Alternatives + Considered section and choose based on evidence, not the note alone. Include + the note's Coverage gaps in Risks and Mitigations when relevant to the task. +8. Note remaining gaps as explicit assumptions +9. **Map brief sections → plan sections:** - Brief Intent → plan Context (motivation paragraph) - Brief Goal → plan Context (end state) - Brief Constraints/Preferences/NFRs → inputs to Implementation Plan decisions diff --git a/plugins/ultraplan-local/commands/ultra-cc-architect-local.md b/plugins/ultraplan-local/commands/ultra-cc-architect-local.md new file mode 100644 index 0000000..c67630c --- /dev/null +++ b/plugins/ultraplan-local/commands/ultra-cc-architect-local.md @@ -0,0 +1,376 @@ +--- +name: ultra-cc-architect-local +description: Match brief+research against available Claude Code features; produce architecture note with explicit gaps +argument-hint: "--project [--fg | --quick | --no-gaps]" +model: opus +allowed-tools: Agent, Read, Glob, Grep, Write, Edit, Bash, AskUserQuestion +--- + +# Ultra CC Architect Local v1.0 + +Valgfri pipeline-kommando som matcher oppgavens behov (brief + +research) mot tilgjengelige Claude Code-features (Hooks, Subagents, +Skills, Output Styles, MCP, Plan Mode, Worktrees, Background Agents) +og produserer et arkitekturnotat med eksplisitt gap-seksjon. + +Pipelinen er 5-stegs når denne kommandoen er med: + +``` +/ultrabrief-local → brief.md +/ultraresearch-local → research/*.md +/ultra-cc-architect-local → architecture/overview.md + gaps.md (this command) +/ultraplan-local → plan.md +/ultraexecute-local → execution +``` + +**Designprinsipp — selvlærende, men ikke autonom.** Kommandoen leser +en kuratert skill-katalog (`skills/cc-architect-catalog/`) med seed- +skills for hver CC-feature. Katalogen utvides over tid av en egen +skill-factory (separat utviklingsprosess). Arkitekturnotatet er et +forslag — brukeren godkjenner før plan-fasen. + +**Pipeline-integrasjon.** `/ultraplan-local` oppdager automatisk +`{project_dir}/architecture/overview.md` og bruker feature-forslagene +som priors (ikke mandater) under exploration og planning. + +## Phase 1 — Parse mode and validate input + +Parse `$ARGUMENTS` for flags. Ordered precedence: + +1. **`--project `** (PÅKREVD) — les `{dir}/brief.md` og + auto-oppdag `{dir}/research/*.md`. Skriv til `{dir}/architecture/`. + Hvis `{dir}` eller `{dir}/brief.md` mangler: + ``` + Error: project directory not initialized. Run /ultrabrief-local first. + Missing: {dir}/brief.md + ``` + Sett **project_dir = {dir}**, **brief_path = {dir}/brief.md**. + Sett **architecture_dir = {dir}/architecture/** — opprettes i + Phase 2 hvis den mangler. + +2. **`--fg`** — foreground. Alle faser inline. Default er background + via `architect-orchestrator`. Sett **execution = foreground**. + +3. **`--quick`** — hopp over Phase 6 (adversarial review). Sett + **mode = quick**. + +4. **`--no-gaps`** — utelat `gaps.md` (gap-seksjonen beholdes internt + i `overview.md`). Sett **mode_suffix = no-gaps**. (Kan kombineres + med `--quick`.) + +5. Hvis `--project` mangler: vis usage og stopp: + +``` +Usage: /ultra-cc-architect-local --project [--fg] [--quick] [--no-gaps] + +A project directory is required. Run /ultrabrief-local first to create one. + +Modes: + default Background via architect-orchestrator → overview.md + gaps.md + --fg All phases in foreground (blocks session) + --quick Skip adversarial review (no architecture-critic pass) + --no-gaps Do not write gaps.md (gap-section stays inside overview.md) + +Examples: + /ultra-cc-architect-local --project .claude/projects/2026-04-18-jwt-auth + /ultra-cc-architect-local --project .claude/projects/2026-04-18-jwt-auth --fg + /ultra-cc-architect-local --project .claude/projects/2026-04-18-jwt-auth --fg --quick + +Pipeline position (5-steg): + /ultrabrief-local → /ultraresearch-local → /ultra-cc-architect-local + → /ultraplan-local → /ultraexecute-local +``` + +Ikke fortsett forbi dette steget hvis `--project` mangler. + +### Les briefen + +Les `{brief_path}` og parse frontmatter. Hent: +- `task` — one-liner for stats +- `slug` — brukes i overview-frontmatter +- `project_dir` — hvis satt, kryssjekk mot flag; mismatch → advarsel, + men bruk flag-verdien +- `brief_quality` — `complete | partial`. Partial briefer er lovlige; + noter i overview.md under "Open questions". + +### Scan research/ + +Glob `{project_dir}/research/*.md`. Lagre liste som +**research_paths**. Zero research er lovlig. + +### Rapporter detektert modus + +``` +Mode: {default | foreground}{, quick}{, no-gaps} +Project: {project_dir} +Brief: {brief_path} ({brief_quality}) +Research: {N} files detected +``` + +## Phase 2 — Background transition + +**Hvis execution = foreground:** hopp over denne fasen. Fortsett inline +fra Phase 3. + +**Hvis execution = default (background):** + +Opprett `{architecture_dir}` hvis den ikke eksisterer (`mkdir -p`). + +Launch the **architect-orchestrator** agent with this prompt: + +``` +Brief file: {brief_path} +Project dir: {project_dir} +Architecture dir: {architecture_dir} +Research briefs: {comma-separated research_paths, or "none"} +Skill catalog root: ${CLAUDE_PLUGIN_ROOT}/skills/cc-architect-catalog +Plugin root: ${CLAUDE_PLUGIN_ROOT} +Mode: {default | quick}{, no-gaps if set} + +Read the brief and every research brief. Execute your full workflow. +Write overview.md to the architecture dir. Write gaps.md unless mode +includes no-gaps. +``` + +Launch via Agent-tool med `run_in_background: true`, `subagent_type: +architect-orchestrator`. + +Deretter output til bruker og **stopp ditt svar**: + +``` +Background architecture run started via architect-orchestrator. + + Project: {project_dir} + Brief: {brief_path} + Research: {N} briefs + Output: {architecture_dir}/overview.md (+ gaps.md) + +You will be notified when the architecture note is ready. +You can continue working on other tasks in the meantime. +``` + +Ikke vent på orchestratoren. Ikke fortsett til Phase 3. +architect-orchestrator håndterer Phase 3–7 autonomt. + +--- + +**Alt under denne linjen kjører enten i foreground-modus eller inne i +background-agenten. Instruksjonene er identiske uavhengig av kontekst.** + +--- + +## Phase 3 — Read inputs and audit the catalog + +Les briefen i sin helhet. Hent Intent, Goal, Non-Goals, Constraints, +Preferences, NFRs, Success Criteria, Research Plan, Open Questions, +Prior Attempts. + +Les hver research-brief sitt Executive Summary + Recommendation +(2–3 setninger per brief). + +Les `${CLAUDE_PLUGIN_ROOT}/skills/cc-architect-catalog/SKILL.md` for å +lære taxonomy og lag-modellen. + +Glob `${CLAUDE_PLUGIN_ROOT}/skills/cc-architect-catalog/*.md` +(unntatt `SKILL.md`). Hvis glob returnerer null filer: sett +`catalog_empty = true` (ikke feil — `feature-matcher` har fallback). + +Opprett `{architecture_dir}` hvis den ikke eksisterer. + +## Phase 4 — Feature matching (parallel swarm) + +Launch to agents i parallell, i én melding: + +- **feature-matcher** (model: sonnet). Prompt med brief_path, + research_paths, catalog_root, project_dir. +- **gap-identifier** (model: sonnet). Samme input. Jobber uavhengig + av feature-matcher (off briefen og katalogen direkte). + +Pass konkrete filstier, ikke inlined content. + +Etter begge returnerer: + +- `fallback_used = true` hvis `catalog_empty` eller feature-matcher + rapporterer det. +- Trekk ut feature-liste, rationales, confidences, integration-noter + fra feature-matcher. +- Trekk ut gaps, out-of-scope, katalog-dekningsstats fra + gap-identifier. + +## Phase 5 — Synthesize architecture/overview.md + +Skriv `{architecture_dir}/overview.md`. + +**Frontmatter:** + +```yaml +--- +task: +slug: +created: +source_brief: +source_research: [] +skills_consulted: [] +cc_features_proposed: [] +review_status: pending +--- +``` + +**Seks seksjoner i denne rekkefølgen:** + +1. **Context** — 3 setninger. Paraphrase brief Intent + Goal. +2. **Proposed CC features** — tabell: Feature | Rationale (brief + anchor) | Supporting skill | Confidence. Én rad per foreslått + feature. Behold primary/secondary/fallback-grupperingen som + underseksjoner hvis feature-matcher leverte dem. +3. **Feature composition** — hvordan features samspiller. Sekvens, + konflikter, delte tilstander, fallbacks. 3–6 bullets. +4. **Coverage gaps identified** — **ALLTID tilstede**, også når tom. + Hvis tom, skriv "No coverage gaps identified — catalog covers all + features this task requires." Hvis ikke-tom, oppsummer hver gap i + én linje. Full issue-draft-tekst går til `gaps.md` i Phase 7 (med + mindre `--no-gaps`). +5. **Alternatives considered** — minst én alternativ feature- + kombinasjon med grunn for avvisning. Rationale må referere + briefen. +6. **Open questions** — hva plan-fasen må avgjøre. Inkluder evt. + uløste tradeoffs fra feature-matcher + briefens egne Open + Questions. + +## Phase 6 — Adversarial review + +**Hvis mode = quick:** hopp over denne fasen. Sett +`critic_verdict = "SKIPPED"` og `guardian_verdict = "SKIPPED"`. +Fortsett til Phase 7. + +Launch to reviewere i parallell: + +- **architecture-critic** (model: sonnet). Input: overview.md, + brief_path, research_paths, catalog_root. +- **scope-guardian** (model: sonnet). Prompt **eksplisitt**: "The + artifact under review is an architecture note (not an implementation + plan). Verify that the proposed features align with brief + requirements. Flag scope creep (features not justified by the brief) + and scope gaps (brief requirements no proposed feature addresses)." + +Håndter verdikter: + +- **PASS + ALIGNED** — note ferdig. `review_status: approved`. +- **REVISE** fra critic — revidér notatet i plass, adresser hver + major finding. Re-launch architecture-critic én gang. Fortsatt + REVISE → emit findings som `## Review notes`-seksjon nederst, + fortsett. Ikke loop. +- **BLOCK** fra critic — revidér for å fjerne blocker (typisk + hallucinert feature eller manglende anchor). Re-launch én gang. + Fortsatt BLOCK → `review_status: needs_rewrite`, surface findings + i Open Questions. +- **CREEP / GAP / MIXED** fra guardian — append `## Scope review`- + subseksjon med funnene. Ikke re-synthesize med mindre combined med + critic REVISE/BLOCK. + +Oppdater `review_status` i frontmatter etter resultatet. + +## Phase 7 — Present, write gaps.md, stats + +**gaps.md** — skrives med mindre `--no-gaps`. Format: + +```markdown +# Coverage gaps — + +These are issue-ready drafts. Copy to the project's git host manually +when you decide a gap warrants tracking. No auto-creation. + +--- + + + +--- + + + +... +``` + +Zero gaps: skriv en-liner ("No coverage gaps identified.") slik at +filstaten er deterministisk. + +**Stats** — append én linje til +`${CLAUDE_PLUGIN_DATA}/ultra-cc-architect-local-stats.jsonl`: + +```json +{ + "ts": "", + "task": "", + "mode": "", + "slug": "", + "project_dir": "", + "architecture_path": "/overview.md", + "gaps_path": "/gaps.md | null>", + "skills_catalog_size": , + "skills_consulted": , + "features_proposed": , + "gaps_identified": , + "critic_verdict": "", + "guardian_verdict": "", + "fallback_used": +} +``` + +Hvis `${CLAUDE_PLUGIN_DATA}` ikke er satt eller ikke skrivbar, skip +stats silently. + +**Summary til brukeren:** + +``` +## Ultra-CC-Architect Complete + +**Task:** +**Project:** +**Architecture note:** /overview.md +**Gaps draft:** /gaps.md | skipped (--no-gaps) +**Features proposed:** N (primary: N, secondary: N, fallback: N) +**Gaps identified:** N +**Review:** / + +### Primary features +- : +- : ... + +### Top gaps (if any) +- +- + +Next step: /ultraplan-local --project +(the architecture note is auto-discovered as extra context) +``` + +## Hard rules + +- **Catalog is ground truth.** Hver foreslått feature må komme fra + katalogens `cc_feature`-taxonomy eller feature-matcher's dokumenterte + fallback-liste. `architecture-critic` blokkerer hallucinated + features. +- **Brief is anchor.** Hver foreslått feature må sitere en konkret + brief-seksjon (Intent/Goal/Constraint/NFR/Success Criterion). Features + uten anchor fjernes under review. +- **Gap ≠ error.** "Coverage gaps identified"-seksjonen er **alltid** + til stede — tom eller full. Brief §4.5 ("Mangel ≠ feil"). +- **No auto-issue-creation.** Gaps er drafts i `gaps.md`. Brukeren + avgjør hva som postes. +- **Sonnet for sub-agents.** Opus kun for orchestrator og hoved- + kommandoen. +- **Privacy.** Aldri logg secrets, tokens, credentials fra brief, + research eller katalog. +- **Idempotent.** Re-kjøring overskriver `overview.md` og `gaps.md`. + Stats-linjene akkumuleres. +- **Graceful degradation.** Tom katalog → fallback-liste. Manglende + research → jobb kun fra brief. Partial brief → noter i Open + Questions. +- **Additiv i pipeline.** `/ultraplan-local` oppdager overview.md + automatisk men må fungere uendret om filen mangler. +- **No third-party content copied** (brief §4.4). Seed-skills er + håndskrevet. Fremtidig skill-factory-output håndterer IP-hygiene + separat. +- **No n-gram computation here.** Feltet `ngram_overlap_score` + respekteres (ikke-null > threshold → flagge), men beregnes av + skill-factory, ikke denne kommandoen. diff --git a/plugins/ultraplan-local/commands/ultraplan-local.md b/plugins/ultraplan-local/commands/ultraplan-local.md index 18031c3..2d74787 100644 --- a/plugins/ultraplan-local/commands/ultraplan-local.md +++ b/plugins/ultraplan-local/commands/ultraplan-local.md @@ -62,6 +62,10 @@ Parse `$ARGUMENTS` for mode flags. Order of precedence: ``` - Set **project_dir = {dir}**, **brief_path = {dir}/brief.md**. - 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. 4. **`--brief `** — extract the brief path. If the file does not exist: ``` @@ -323,9 +327,12 @@ Mode: {default | quick} Plan destination: {plan destination} Plugin root: ${CLAUDE_PLUGIN_ROOT} Research briefs: {comma-separated list, or "none"} +Architecture note: {architecture_note_path or "none"} -Read the brief file and every research brief. Execute your full planning -workflow. Write the plan to the destination path. +Read the brief file and every research brief. If an architecture note is +provided, read it before launching exploration agents and treat its feature +proposals as priors (not mandates) — exploration may override with evidence. +Execute your full planning workflow. Write the plan to the destination path. ``` Launch the planning-orchestrator via the Agent tool with `run_in_background: true`. diff --git a/plugins/ultraplan-local/skills/cc-architect-catalog/SKILL.md b/plugins/ultraplan-local/skills/cc-architect-catalog/SKILL.md new file mode 100644 index 0000000..d3b41e7 --- /dev/null +++ b/plugins/ultraplan-local/skills/cc-architect-catalog/SKILL.md @@ -0,0 +1,140 @@ +--- +name: cc-architect-catalog +description: Internal catalog for ultra-cc-architect-local — not invoked directly. Indexes CC-feature reference and pattern skills. +layer: manifest +cc_feature: meta +source: https://docs.claude.com/en/docs/claude-code +concept: catalog-index +last_verified: 2026-04-18 +ngram_overlap_score: null +review_status: approved +--- + +# CC Architect Catalog — Manifest + +This file is the catalog index consumed by the `feature-matcher` and +`gap-identifier` agents inside `/ultra-cc-architect-local`. It is NOT +intended to be auto-invoked by Claude Code's skill system — the +description above exists only so the skill loader has something to +display if it indexes this directory. + +## Purpose + +The catalog enumerates which Claude Code features the architect command +can reason about, and at which layer of abstraction. Each feature gets +one or more skill files in this directory. A skill is a self-contained +note about *one* feature at *one* layer. + +## Layers (frontmatter `layer` field) + +| Layer | Purpose | Kilde | +|-------|---------|-------| +| `reference` | Facts, API, syntax. What the feature *is*. | CC changelog, official docs | +| `pattern` | When and how to use it. Typical shapes, pitfalls. | Synthesized from practice | +| `decision` | Operational decision tree across features. | Synthesized. (No seeds yet.) | + +Lag representeres som frontmatter-felt, ikke mappestruktur. Rationale: +one feature can have skills at multiple layers without relocation, and +future skill-factory output can target a specific layer without moving +files. + +## Frontmatter contract (per skill file) + +Every skill file in this directory MUST have this frontmatter. The +fields are load-bearing for the architect command. + +```yaml +--- +name: # unique, kebab-case +description: # used by feature-matcher +layer: reference | pattern | decision +cc_feature: # see table below +source: # canonical upstream source +concept: # 3–6 word concept handle +last_verified: # when a human last checked against upstream +ngram_overlap_score: null # reserved for skill-factory IP-hygiene +review_status: approved | pending | auto-merged +--- +``` + +`ngram_overlap_score` is reserved. This command respects it (will flag +non-null values > threshold) but does not compute it. Skill-factory (a +separate later process) populates that field. + +`review_status: approved` is the default for seeds (approved by +construction — handwritten, no third-party text copied). Future +skill-factory output will start as `pending` (channel 2) or +`auto-merged` (channel 1). + +## Canonical `cc_feature` values + +| Value | Coverage | +|-------|----------| +| `hooks` | Event hooks (UserPromptSubmit, PreToolUse, PostToolUse, Stop, Notification, SessionStart, etc.) | +| `subagents` | Task-tool sub-agents, delegation patterns | +| `skills` | Claude Code skill system (not Agent SDK skills) | +| `output-styles` | Output style configuration | +| `mcp` | Model Context Protocol servers and tools | +| `plan-mode` | Built-in plan mode | +| `worktrees` | Git worktree integration | +| `background-agents` | `run_in_background`, Monitor, long-running agents | +| `meta` | This manifest only — not a real feature | + +If a future skill covers a feature not in this list, add the row above +and surface the extension in the relevant CHANGELOG entry. + +## Current seed coverage (v2.2.0) + +| Feature | reference | pattern | decision | +|---------|-----------|---------|----------| +| hooks | hooks-reference | hooks-pattern | — | +| subagents | subagents-reference | subagents-pattern | — | +| skills | skills-reference | — | — | +| output-styles | output-styles-reference | — | — | +| mcp | mcp-reference | — | — | +| plan-mode | plan-mode-reference | — | — | +| worktrees | worktrees-reference | — | — | +| background-agents | background-agents-reference | — | — | + +Total: 10 seed skills, 8 features, 2 layers. Decision-layer is +intentionally empty — decisions cross features and require broader +synthesis than a single seed pass can provide. Skill-factory populates +decision-layer later. + +## How `feature-matcher` uses this file + +1. Read this file to learn the `cc_feature` taxonomy. +2. Glob the directory for `*.md` files (excluding SKILL.md). +3. Parse each skill's frontmatter. +4. For each feature mentioned in the brief or research, match against + `cc_feature` field. Prefer `pattern` over `reference` when both exist + (pattern is richer). +5. When no skill exists for a mentioned feature, fall back to the + hardcoded minimum-list inside the `feature-matcher` prompt and mark + the gap in stats (`fallback_used: true`). + +## How `gap-identifier` uses this file + +1. Collect every feature referenced in `feature-matcher`'s output. +2. For each feature, check whether the catalog has at least one skill at + each expected layer (reference always; pattern when complexity + warrants; decision for cross-feature choices). +3. Emit a gap entry for every missing (feature × layer) pair. +4. Label with `skill-layer:` and `cc-feature:`. + +## Non-goals for this file + +- No skill-factory logic. That is a separate later process. +- No auto-discovery of new CC features. +- No n-gram computation. +- No triggering Claude Code auto-invocation (description deliberately + says "not invoked directly"). + +## Modification rules + +- Adding a new skill: create `-.md` with the frontmatter + above and bump the coverage table in this file. +- Renaming `cc_feature` values: update both this file AND every skill + using the old value in the same commit. +- Removing a skill: document in CHANGELOG under the version that drops + it. diff --git a/plugins/ultraplan-local/skills/cc-architect-catalog/background-agents-reference.md b/plugins/ultraplan-local/skills/cc-architect-catalog/background-agents-reference.md new file mode 100644 index 0000000..604d5cc --- /dev/null +++ b/plugins/ultraplan-local/skills/cc-architect-catalog/background-agents-reference.md @@ -0,0 +1,106 @@ +--- +name: background-agents-reference +description: CC background agents — long-running subagents with run_in_background and Monitor for progress streaming. +layer: reference +cc_feature: background-agents +source: https://docs.claude.com/en/docs/claude-code/background-agents +concept: async-agents-and-monitoring +last_verified: 2026-04-18 +ngram_overlap_score: null +review_status: approved +--- + +# Background Agents — Reference + +A background agent is a subagent launched with `run_in_background: +true`. The parent does not block on its return; instead, the harness +notifies the parent when the agent completes. Useful for long-running +exploration, orchestration, and work that overlaps with user activity. + +## Launching + +``` +Agent({ + description: "...", + subagent_type: "...", + prompt: "...", + run_in_background: true +}) +``` + +The Agent tool returns a handle (agent ID / name). The parent +continues its turn; no wait. + +## Monitoring + +Two complementary tools work with background agents: + +- **Monitor** — streams updates from a named background process. Each + event line arrives as a notification. Used for long-running Bash + processes (and, in newer builds, some agent streaming paths). +- **Completion notifications** — the harness posts a message to the + parent when the background agent finishes. The parent sees it as a + system-reminder / notification on its next turn. + +## When background is worth it + +- **Overlapping work** — orchestrator runs 30+ minutes of research + while the user continues coding. Without background, the user is + blocked the whole time. +- **Parallel waves** — wave N of sessions running concurrently; the + parent collects results as they arrive. +- **Long-running processes** — an agent waiting on a build, test run, + or deployment. + +## When background hurts + +- **Short tasks** — agent returns in 10 seconds; making it async adds + overhead for no gain. +- **Tight coupling** — if the parent needs the result before doing + anything else, background is just foreground with extra steps. +- **Unbounded token spend** — a background agent with no budget + signaling can run until it hits limits. Cap explicitly. + +## Common shapes + +### Shape A: Orchestrator handoff + +Parent interviews user, writes a spec, launches a background +orchestrator with the spec path. Parent exits its turn; orchestrator +takes over for the heavy phases. + +Used by: `ultraplan-local`, `ultraresearch-local`. + +### Shape B: Parallel waves + +Parent decomposes work into N independent sessions, launches them all +in parallel with `run_in_background: true`, then synthesizes returns +as they arrive. + +Used by: `ultraplan-local --decompose` execution. + +### Shape C: Watcher + +A background agent polls a process (build, test, deploy) and reports +status changes. Uses Monitor for streaming. + +## Pitfalls + +- **Lost context** — if the parent conversation ends before the + background agent completes, the result may be orphaned. Persist to + disk, not memory. +- **Notification fatigue** — too many background agents = too many + reminders interrupting the parent's flow. +- **Debugging** — background agents run out of the user's view; their + failures can be silent. Log to files, not just return messages. + +## Composition + +- Background + worktrees: the canonical pattern for parallel + implementation — each background agent in its own worktree, no + clashes. +- Background + subagents: an orchestrator IS a subagent; it in turn + can launch its own subagents (foreground inside the orchestrator's + context, or further background). +- Background + hooks: hooks fire inside the background agent's tool + calls, same as foreground. diff --git a/plugins/ultraplan-local/skills/cc-architect-catalog/hooks-pattern.md b/plugins/ultraplan-local/skills/cc-architect-catalog/hooks-pattern.md new file mode 100644 index 0000000..2a19e99 --- /dev/null +++ b/plugins/ultraplan-local/skills/cc-architect-catalog/hooks-pattern.md @@ -0,0 +1,89 @@ +--- +name: hooks-pattern +description: When to choose hooks over prompts or subagents, and common hook shapes that work. +layer: pattern +cc_feature: hooks +source: https://docs.claude.com/en/docs/claude-code/hooks +concept: hooks-decision-and-shapes +last_verified: 2026-04-18 +ngram_overlap_score: null +review_status: approved +--- + +# Hooks — Pattern + +## When to reach for a hook + +Use hooks when the behavior must hold even if Claude is prompt-injected, +distracted, or adversarial. Hooks are outside the model's control loop — +Claude cannot talk its way past them. + +Good fits: + +- **Hard prohibitions** — "never run `rm -rf /`", "never push to main + without a commit signature", "never read files outside this repo". +- **Deterministic context injection** — always show git status at + session start; always inject the current sprint's tasks. +- **Audit trails** — log every Bash call, every file write, outside the + conversation context so it survives `/clear`. +- **Compliance boundaries** — redact secrets from transcripts; block + tool calls that would leak PII. + +Bad fits: + +- Behavior that requires judgment ("should this test run?") — that's a + subagent call. +- Heuristics that drift ("mostly block, sometimes allow") — a hook that + frequently second-guesses itself is a sign the rule belongs in a + prompt or skill. +- Anything that needs to read lots of conversation history — hooks see + a payload, not the full context. + +## Common shapes + +### Shape A: PreToolUse deny + +A small script that reads `tool_input`, matches a pattern, and exits +with a `block` decision. Latency: a few ms. Used for command denylists, +path guards, secrets scanners. + +### Shape B: UserPromptSubmit context injection + +A script that reads the prompt, computes context (e.g., recent git log, +active TODO list), and emits JSON with an `additionalContext` field. +The harness adds that context to the prompt before Claude sees it. + +### Shape C: Stop hook with reminder + +A script that runs when Claude finishes a turn. Checks for uncommitted +work, surfaces it as a notification. Non-blocking. + +### Shape D: SessionStart status + +Runs once per session. Prints repo metadata (branch, open PRs, recent +commits) so every new session starts with shared context. + +## Pitfalls + +- **Slow hooks compound.** A 500 ms PreToolUse hook run 50 times per + session adds 25 seconds of latency. +- **Hooks without error handling crash the turn.** A hook that exits + non-zero on an edge case blocks real work. Default to exit 0 with a + logged warning. +- **Shell-injection in hook scripts.** A hook that interpolates + `tool_input.command` into `bash -c` is itself a security hole. Parse + inputs; never interpolate unescaped. +- **Hooks can leak secrets into transcripts** if their output mentions + env-var values. Scrub before emitting. +- **Cross-platform scripts.** A hook that assumes bash 4 or GNU sed + breaks on macOS. Prefer Node.js, Python, or POSIX sh. + +## Composition with other features + +- Hooks + subagents: a hook can delegate the "should this be blocked" + question to a subagent when the decision needs judgment. Cost: a full + model call per hook invocation — use sparingly. +- Hooks + MCP: a hook can call out to an MCP-exposed tool for policy + lookup. Latency depends on transport. +- Hooks + plan mode: hooks fire during plan mode too. Useful for + enforcing "no writes while planning". diff --git a/plugins/ultraplan-local/skills/cc-architect-catalog/hooks-reference.md b/plugins/ultraplan-local/skills/cc-architect-catalog/hooks-reference.md new file mode 100644 index 0000000..0681142 --- /dev/null +++ b/plugins/ultraplan-local/skills/cc-architect-catalog/hooks-reference.md @@ -0,0 +1,85 @@ +--- +name: hooks-reference +description: CC hooks API — event types, payload shapes, exit codes, and where hooks run. +layer: reference +cc_feature: hooks +source: https://docs.claude.com/en/docs/claude-code/hooks +concept: hooks-api-surface +last_verified: 2026-04-18 +ngram_overlap_score: null +review_status: approved +--- + +# Hooks — Reference + +Hooks are shell commands or scripts that the Claude Code harness runs +in response to events. They give the harness — not Claude — the final +say on whether a tool call, prompt, or session action proceeds. Claude +cannot bypass a hook by prompting itself; the hook runs outside the +model's control loop. + +## Event types + +- **UserPromptSubmit** — fires when the user sends a prompt. Runs before + Claude processes it. Common use: inject extra context, reject + disallowed prompts. +- **PreToolUse** — fires before a tool call. Can deny the call. Common + use: block destructive commands, require confirmation. +- **PostToolUse** — fires after a tool call completes. Sees the result. + Common use: log side effects, redact output, trigger follow-up work. +- **Stop** — fires when the agent finishes a turn. Common use: commit + reminders, session summaries. +- **Notification** — fires when Claude wants to show the user a + notification (e.g., long-running task). +- **SessionStart** — fires when a session begins. Common use: print + repo state, inject context. + +## Payload shape + +Hooks receive a JSON payload on stdin. Common fields: + +- `session_id` — the current session identifier. +- `transcript_path` — path to the conversation transcript. +- `cwd` — current working directory. +- `tool_name` (PreToolUse, PostToolUse) — which tool is running. +- `tool_input` (PreToolUse) — the arguments to the tool. +- `tool_response` (PostToolUse) — the tool's result. +- `prompt` (UserPromptSubmit) — the submitted text. + +Exact field availability depends on event type. Read the payload JSON +rather than assuming a schema. + +## Exit codes and control + +Hooks communicate back via exit code and stdout JSON: + +- Exit 0, no stdout → proceed normally. +- Exit 0, stdout JSON with `decision` field → harness honors the + decision (e.g., `{"decision": "block", "reason": "..."}`). +- Exit non-zero → harness treats as a denial or error, depending on + event and hook type. + +Some hook types support structured output beyond deny/allow (e.g., +adding context to the prompt). Details differ per event. + +## Where hooks live + +- Project hooks: `.claude/settings.json` `hooks` field, paths relative + to project. +- User hooks: `~/.claude/settings.json` (global). +- Plugin hooks: packaged with a plugin, activated when the plugin is + enabled. + +Hooks run in the harness process's shell, not in Claude's tool-use +sandbox. They can spawn subprocesses, read environment variables, +and touch the filesystem. + +## Implications for architecture + +- Hooks are the mechanism for **deterministic policy** (things that + must always or never happen, regardless of what Claude decides). +- Hooks are load-bearing for security: prompt-injection-resistant + defenses live here, not in prompts. +- Hooks add latency to every tool call they gate — keep them fast. +- Hook output is part of the context window; verbose hooks burn + tokens quickly. diff --git a/plugins/ultraplan-local/skills/cc-architect-catalog/mcp-reference.md b/plugins/ultraplan-local/skills/cc-architect-catalog/mcp-reference.md new file mode 100644 index 0000000..539ce0f --- /dev/null +++ b/plugins/ultraplan-local/skills/cc-architect-catalog/mcp-reference.md @@ -0,0 +1,72 @@ +--- +name: mcp-reference +description: Model Context Protocol — external tools and resources exposed to Claude via MCP servers. +layer: reference +cc_feature: mcp +source: https://docs.claude.com/en/docs/claude-code/mcp +concept: mcp-tool-protocol +last_verified: 2026-04-18 +ngram_overlap_score: null +review_status: approved +--- + +# MCP — Reference + +Model Context Protocol (MCP) is the protocol Claude Code uses to talk +to external tool servers. An MCP server advertises *tools* and +*resources*; Claude Code surfaces them to Claude as callable tools. + +## Architecture + +- **MCP server** — a process (local or remote) that implements the + protocol. Can be written in any language. Communicates over stdio, + HTTP, or WebSocket. +- **Transport** — stdio (local subprocess), SSE/HTTP (remote), or + WebSocket. Stdio is the default for local servers. +- **Tools** — callable functions the server exposes. Each has a name, + description, and JSON schema for inputs. +- **Resources** — readable entities the server exposes (files, + database rows, API responses). Addressed by URI. +- **Prompts** — optional; MCP can expose templated prompts. + +## Configuration + +MCP servers are declared in: + +- `.mcp.json` — project-level MCP config. +- `~/.claude.json` or equivalent — user-level. +- Plugin-bundled — a plugin can ship its own MCP server. + +Each entry specifies command, args, transport, and optional auth. + +## Tool naming + +Tools from MCP servers appear to Claude with a namespaced name: +`mcp____`. This keeps names collision-free +across servers. + +## Permissions + +- `allowed-tools` in settings or plugin frontmatter can include MCP + tools by full name. +- Some MCP servers require OAuth or API keys; those are configured in + the server's own config, not Claude's. + +## Common uses + +- Exposing internal APIs to Claude without hand-wrapping them (one + generic MCP server → many tools). +- Cross-language tool servers (Python tool called from Claude Code + running in Node). +- Sandboxed access to external services with explicit scoping. + +## Failure modes + +- Server not running → tool calls fail; Claude sees an error string. +- Server misbehaves → tool returns wrong schema; Claude may retry or + hallucinate. +- Authentication drift → 401s look like transient errors; diagnose by + checking the server directly. +- Security: an MCP server runs with the permissions of its own + process. A malicious server is a supply-chain risk; audit before + enabling. diff --git a/plugins/ultraplan-local/skills/cc-architect-catalog/output-styles-reference.md b/plugins/ultraplan-local/skills/cc-architect-catalog/output-styles-reference.md new file mode 100644 index 0000000..abe34fa --- /dev/null +++ b/plugins/ultraplan-local/skills/cc-architect-catalog/output-styles-reference.md @@ -0,0 +1,58 @@ +--- +name: output-styles-reference +description: CC output styles — configurable response shape, tone, length, and formatting baselines. +layer: reference +cc_feature: output-styles +source: https://docs.claude.com/en/docs/claude-code/output-styles +concept: output-style-config +last_verified: 2026-04-18 +ngram_overlap_score: null +review_status: approved +--- + +# Output Styles — Reference + +Output styles let a user or plugin shape how Claude Code responds: +length defaults, formatting preferences, tone, verbosity. They apply +across the session rather than needing to be re-stated per prompt. + +## Where they live + +- **Built-in styles** — shipped with the CLI. +- **Custom styles** — directory with a manifest describing the style. +- **Selection** — the user sets an active style via settings or a + `/style` command. The style is injected into Claude's system context. + +## What a style can control + +- Default response length baseline ("keep responses ≤ 100 words + unless detail is required"). +- Formatting rules (markdown vs plain, code-block conventions). +- Tone ("terse", "pedagogical", "adversarial"). +- Domain voice (Norwegian for dialog, English for code — a project + convention encoded as a style). + +## What a style cannot control + +- Tool permissions (that is `allowed-tools` / `settings.json`). +- Hooks (those are harness-level). +- Agent system prompts (those come from agent definitions). + +## When to use a custom style + +- The project has a persistent communication convention that should + hold across every session (e.g., "never use emojis"). +- Multiple users share the project and want consistent output. +- A skill's prompts would otherwise have to restate formatting rules + each time. + +## When not to + +- For per-task formatting needs — use the prompt instead. +- For rules that must hold against prompt injection — use hooks. + +## Practical shape + +A minimal custom style is a markdown or plain-text block listing the +conventions. Claude treats it as top-of-system guidance. Keep it +short: long styles crowd out the task. diff --git a/plugins/ultraplan-local/skills/cc-architect-catalog/plan-mode-reference.md b/plugins/ultraplan-local/skills/cc-architect-catalog/plan-mode-reference.md new file mode 100644 index 0000000..72874bf --- /dev/null +++ b/plugins/ultraplan-local/skills/cc-architect-catalog/plan-mode-reference.md @@ -0,0 +1,65 @@ +--- +name: plan-mode-reference +description: CC plan mode — read-only planning phase before implementation, with explicit user approval gate. +layer: reference +cc_feature: plan-mode +source: https://docs.claude.com/en/docs/claude-code/plan-mode +concept: planning-before-execution +last_verified: 2026-04-18 +ngram_overlap_score: null +review_status: approved +--- + +# Plan Mode — Reference + +Plan mode is a built-in state where Claude operates read-only and +produces an implementation plan instead of executing it. The user +reviews the plan, then either approves it to transition to +implementation or iterates. + +## State machine + +1. **Plan mode entered** — user triggers it (Shift+Tab twice, `/plan`, + or harness-initiated) or Claude calls `EnterPlanMode`. +2. **Read-only operation** — Claude can read files, search, run + analysis. Writes, edits, and commits are blocked by the harness. +3. **Plan produced** — Claude presents a plan via `ExitPlanMode` or + equivalent. +4. **User reviews** — accepts, rejects, or iterates. +5. **Exit** — on acceptance, mode returns to normal (edits allowed). + +## What plan mode guarantees + +- No writes during the plan phase. Even if Claude tries, the harness + denies write tools. +- A structured handoff: the plan is a message the user sees before + anything happens. + +## What plan mode does not guarantee + +- Plan quality. Plan mode is a *gate*, not a *reviewer*. A bad plan + still passes if the user approves it. +- Scope locking. After exit, Claude can do whatever the new prompts + ask — plan mode is a phase, not a contract. + +## When to opt into plan mode + +- Tasks touching multiple files or modules where the order and file + list matter. +- Refactors where the first wrong edit is expensive to undo. +- Unfamiliar codebases where planning surfaces missing context. + +## When to skip plan mode + +- Single-file trivial changes. +- Tasks already specified by a detailed plan from another tool + (e.g., an `ultraplan-local` plan.md) — planning twice is waste. + +## Relationship to /ultra* planning + +- `/ultraplan-local` produces a *plan artifact* that outlives the + session. Plan mode produces an *in-conversation plan* that does not + survive `/clear`. +- They compose: use plan mode to sketch at session start, then run + `/ultraplan-local` to get the durable, reviewable, machine-readable + plan with manifests. diff --git a/plugins/ultraplan-local/skills/cc-architect-catalog/skills-reference.md b/plugins/ultraplan-local/skills/cc-architect-catalog/skills-reference.md new file mode 100644 index 0000000..1481131 --- /dev/null +++ b/plugins/ultraplan-local/skills/cc-architect-catalog/skills-reference.md @@ -0,0 +1,83 @@ +--- +name: skills-reference +description: CC skills — auto-invoked domain modules with SKILL.md, frontmatter triggers, and file-hierarchy discovery. +layer: reference +cc_feature: skills +source: https://docs.claude.com/en/docs/claude-code/skills +concept: skills-system +last_verified: 2026-04-18 +ngram_overlap_score: null +review_status: approved +--- + +# Skills — Reference + +Claude Code's skill system is a way to package domain knowledge, +workflows, and supporting files so Claude can load them on demand. A +skill is a directory with a `SKILL.md` manifest and any auxiliary +files (scripts, templates, references). + +## Anatomy + +- **`SKILL.md`** — the entry point. Markdown file with YAML + frontmatter and a body. The frontmatter declares when the skill + triggers; the body is instructions Claude follows after loading. +- **Auxiliary files** — any files in the skill directory. Loaded on + demand (typically by Claude reading them when the body references + them). Common: `scripts/`, `templates/`, `references/`. + +## Frontmatter + +```yaml +--- +name: +description: +--- +``` + +The `description` is what Claude sees when deciding whether to invoke. +It should describe *when* to use the skill, not *what* it does. + +## Invocation + +- **Auto-invocation** — Claude loads the skill when the user's prompt + matches the description's triggers. The trigger model is implicit + (natural-language match), not regex. +- **Manual invocation** — the user types `/` and Claude + calls the Skill tool. +- **Never auto-invoked** — if the description explicitly says so + ("Internal catalog for X — not invoked directly"), Claude typically + respects the hint. + +## Discovery + +Skills are discovered from: + +- **Built-in skills** — shipped with the CLI. +- **Plugin skills** — packaged inside a plugin's `skills/` directory. +- **User skills** — `~/.claude/skills/`. +- **Project skills** — `.claude/skills/` inside the repo. + +The CLI surfaces available skills via `--allowedTools` and in the +system prompt. + +## Progressive disclosure + +Skills use progressive disclosure: + +1. Claude sees only the name + description at session start. +2. When a skill triggers, the body loads into context. +3. Files referenced by the body load only when Claude reads them. + +This keeps the baseline context small; depth is paid for on demand. + +## Relationship to other features + +- **Skills vs subagents** — a skill lives in the parent's context when + loaded. A subagent runs in its own context. Choose skill when the + context flows through; subagent when it should not. +- **Skills vs hooks** — hooks are deterministic harness-level rules. + Skills are context that Claude interprets. A skill cannot enforce; + only guide. +- **Skills vs MCP** — MCP exposes *tools*. Skills are *knowledge*. An + MCP tool + a skill that explains when to use it is a common pairing. diff --git a/plugins/ultraplan-local/skills/cc-architect-catalog/subagents-pattern.md b/plugins/ultraplan-local/skills/cc-architect-catalog/subagents-pattern.md new file mode 100644 index 0000000..21a188b --- /dev/null +++ b/plugins/ultraplan-local/skills/cc-architect-catalog/subagents-pattern.md @@ -0,0 +1,103 @@ +--- +name: subagents-pattern +description: When subagents earn their cost and how to compose them — swarm, pipeline, and guard patterns. +layer: pattern +cc_feature: subagents +source: https://docs.claude.com/en/docs/claude-code/sub-agents +concept: subagent-composition +last_verified: 2026-04-18 +ngram_overlap_score: null +review_status: approved +--- + +# Subagents — Pattern + +## When to delegate + +Delegation earns its cost when at least one of these holds: + +- **Context isolation** — the subtask needs to read 50+ files or run + many greps, and the parent conversation does not need the raw + results. Summaries survive; raw output stays in the subagent. +- **Parallelism** — multiple independent subtasks can run at once, + compressing wall-clock time. +- **Specialization** — the subagent has a tailored system prompt that + changes its behavior meaningfully (e.g., adversarial reviewer). +- **Tool scoping** — the subtask should run with fewer tools than the + parent (principle of least privilege). + +If none of these apply, inline the work. A subagent call costs a full +model turn; do not pay it for routine reads. + +## Common patterns + +### Pattern A: Exploration swarm + +Parent launches 4-8 specialized subagents in parallel, each with a +narrow brief (architecture, dependencies, risks, tests, ...). Each +returns a summary. Parent synthesizes. + +Used by: `ultraplan-local` Phase 2 exploration. + +Cost shape: N × Sonnet call, wall-clock ≈ slowest subagent. + +### Pattern B: Adversarial review + +Parent writes an artifact (plan, design note). Launches a reviewer +subagent with a system prompt that demands problems, never praise. +Reviewer returns findings. Parent revises. + +Used by: `plan-critic`, `scope-guardian`, `architecture-critic`. + +Cost shape: 1 × Sonnet call per review pass. + +### Pattern C: Background orchestrator + +Parent kicks off a long-running orchestrator subagent with +`run_in_background: true`, then continues. Orchestrator runs its own +subagents, synthesizes, writes output to disk. Parent is notified on +completion. + +Used by: `planning-orchestrator`, `research-orchestrator`. + +Cost shape: 1 × Opus orchestrator + N × Sonnet workers. Overlaps with +other user work. + +### Pattern D: Guard subagent + +A hook delegates an "is this safe?" question to a subagent when the +answer needs judgment. The subagent returns a verdict; the hook +enforces it. + +Cost shape: 1 × Sonnet call per hook invocation. Use sparingly — +adds seconds of latency per tool call. + +## Pitfalls + +- **Delegate-understanding anti-pattern** — do not write "based on your + findings, fix the bug" to a subagent. The subagent is not inside your + head; it cannot see what you synthesized. Pass concrete context. +- **Prompt-on-top-of-prompt drift** — if the parent's prompt to a + subagent contradicts the subagent's own system prompt, the subagent + follows its system prompt. Do not try to re-style a reviewer into a + cheerleader by prompting harder. +- **Silent failure** — a subagent that returns "done" without evidence + may have done nothing. Trust but verify: check for the concrete + artifacts the subagent was asked to produce. +- **Orchestration explosion** — a three-level-deep subagent tree costs + exponentially. Flatten wherever the inner levels don't need their own + context isolation. +- **Token budget fights** — parent and all active subagents share the + harness's overall budget. Cap subagent output length ("report in + under 200 words") when the summary is what matters. + +## Composition with other features + +- Subagents + hooks: hooks fire during subagent tool calls too. A + subagent with only `Read` tools is already constrained; hooks add + defense in depth. +- Subagents + worktrees: an `isolation: "worktree"` subagent works in + an isolated copy of the repo, so its writes never clash with the + parent's writes. +- Subagents + background: run heavy exploration in background while the + user continues other work. diff --git a/plugins/ultraplan-local/skills/cc-architect-catalog/subagents-reference.md b/plugins/ultraplan-local/skills/cc-architect-catalog/subagents-reference.md new file mode 100644 index 0000000..379ac17 --- /dev/null +++ b/plugins/ultraplan-local/skills/cc-architect-catalog/subagents-reference.md @@ -0,0 +1,98 @@ +--- +name: subagents-reference +description: CC subagents — how the Task tool spawns isolated agent instances with scoped tools and context. +layer: reference +cc_feature: subagents +source: https://docs.claude.com/en/docs/claude-code/sub-agents +concept: task-tool-delegation +last_verified: 2026-04-18 +ngram_overlap_score: null +review_status: approved +--- + +# Subagents — Reference + +Subagents are fresh Claude instances spawned via the Task tool. Each +receives a task prompt, a tool subset, and no memory of the parent +conversation except what the parent explicitly passes. They return a +single final message to the parent. + +## Anatomy + +A subagent has: + +- **A name** — either a built-in type (`general-purpose`, `Explore`, + `Plan`) or a plugin-defined type (`code-reviewer`, `test-runner`, + ...). +- **A system prompt** — defined by the agent type. The parent cannot + override it. +- **A tool set** — subset of the parent's tools, as declared in the + agent definition's frontmatter `tools:` field. +- **A task prompt** — what the parent asks it to do. Self-contained; + the subagent has no access to prior messages. +- **A model** — either explicit in the agent definition (`model: opus | + sonnet | haiku`) or inherited from the parent. + +## How to define a subagent + +A plugin agent is a markdown file in `agents/` with frontmatter: + +```yaml +--- +name: code-reviewer +description: +model: sonnet +tools: ["Read", "Grep", "Glob"] +--- + + +``` + +The `description` field is how Claude decides when to spawn this +subagent. Include concrete trigger examples. + +## How to invoke + +Parent calls the `Task` / `Agent` tool with: + +- `subagent_type` — the agent's name +- `description` — short label for logs +- `prompt` — the self-contained task + +Optional: + +- `run_in_background: true` — agent runs in the background; parent + is notified on completion. +- `isolation: "worktree"` — agent runs in a temporary git worktree + (isolated copy of the repo). + +## Return protocol + +- Foreground agent: parent blocks until the agent returns. Return value + is a single text message. +- Background agent: parent continues. On completion, the harness + injects a notification into the parent's next turn. + +## Isolation guarantees + +- No conversation history sharing. Each subagent starts cold. +- Separate context window. A subagent can read large files without + polluting the parent's context. +- Separate tool permissions. A subagent with only `Read` tools cannot + write files, even if the parent can. + +## Cost and latency + +- Every subagent call is a full model call with its own token budget. +- Model choice matters: Sonnet is ~5× cheaper than Opus; Haiku is + cheaper still but cannot be used (per project policy). +- Parallel subagents: the parent can launch multiple in one message; + the harness runs them concurrently. Total latency ≈ slowest agent. + +## Failure modes + +- Subagent hits context limit → partial or missing return. +- Subagent runs in background and the parent conversation ends → result + may be orphaned. +- Subagent's return message hallucinates file paths → caller must + verify. diff --git a/plugins/ultraplan-local/skills/cc-architect-catalog/worktrees-reference.md b/plugins/ultraplan-local/skills/cc-architect-catalog/worktrees-reference.md new file mode 100644 index 0000000..72cf16f --- /dev/null +++ b/plugins/ultraplan-local/skills/cc-architect-catalog/worktrees-reference.md @@ -0,0 +1,68 @@ +--- +name: worktrees-reference +description: CC git worktree integration — isolated repo copies per agent for parallel or destructive work. +layer: reference +cc_feature: worktrees +source: https://docs.claude.com/en/docs/claude-code/worktrees +concept: git-worktree-isolation +last_verified: 2026-04-18 +ngram_overlap_score: null +review_status: approved +--- + +# Worktrees — Reference + +Git worktrees let a repo check out multiple branches simultaneously in +separate directories. Claude Code integrates with worktrees to give +agents isolated filesystem scopes — one agent's edits cannot clash +with another's. + +## How it surfaces in CC + +- **`isolation: "worktree"` on a subagent call** — the harness creates + a temporary worktree for the subagent. The subagent runs with its + cwd set to the worktree. Changes stay there until merged or + discarded. +- **`/worktree` skill / command** — interactive tooling for creating, + listing, and merging worktrees during a session. +- **Auto-cleanup** — worktrees created by subagents are removed if the + subagent made no changes. Otherwise the path is returned in the + result for the caller to review. + +## Branch semantics + +- Each worktree checks out a named branch. Two worktrees cannot check + out the same branch (git's rule). +- Creating a worktree creates a branch if one does not exist. +- Deleting a worktree does not delete the branch; use `git branch -d` + separately if desired. + +## Use cases + +- **Parallel exploration** — three subagents trying three approaches, + each in its own worktree. The parent compares diffs. +- **Destructive experiments** — upgrade a dependency, run the full + test suite, measure breakage. Discard the worktree if results are + bad. +- **Long-running session without blocking main** — execute a refactor + in a worktree while continuing other work in the main checkout. + +## Pitfalls + +- **Shared state leaks** — node_modules, .env, build artifacts are + per-worktree but may be symlinked in ways that defeat isolation. + Verify. +- **Disk use** — each worktree is a full checkout of the tree. For + large repos, disk pressure adds up. +- **Branch proliferation** — agents that create worktrees without + cleanup leave orphan branches. Prune periodically. +- **Not a sandbox** — a worktree isolates files, not network or + processes. A subagent in a worktree can still call the outside + world. + +## Composition + +- Worktrees + background agents: a background agent in a worktree can + work on a long task while the user continues in the main checkout. +- Worktrees + subagents + hooks: hooks fire inside the worktree cwd, + so path-based hooks naturally scope to the isolated work.