feat(ultraplan-local): v2.2.0 — /ultra-cc-architect-local
New optional command between /ultraresearch-local and /ultraplan-local that matches brief+research against Claude Code features (hooks, subagents, skills, output-styles, MCP, plan-mode, worktrees, background-agents) and produces an architecture note with brief-anchored rationale plus explicit gaps. Added: - commands/ultra-cc-architect-local.md (--project, --fg, --quick, --no-gaps) - agents/architect-orchestrator.md (opus) — 6-phase background orchestrator - agents/feature-matcher.md (sonnet) — fallback-ranked feature proposals - agents/gap-identifier.md (sonnet) — 4 gap classes with issue-ready drafts - agents/architecture-critic.md (sonnet) — hallucination gate as BLOCKER - skills/cc-architect-catalog/ — SKILL.md + 10 seed entries (reference/pattern) Changed (non-breaking): - commands/ultraplan-local.md — auto-discovers architecture/overview.md - agents/planning-orchestrator.md — cross-references cc_features_proposed - plugin.json — 2.1.0 → 2.2.0, description, cc-architecture keyword - CHANGELOG, README, CLAUDE.md (plugin + marketplace root) Pipeline becomes brief → research → architect → plan → execute. Architect is optional; existing project dirs keep working unchanged. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
This commit is contained in:
Kjell Tore Guttormsen
parent
23aaaa6e6c
commit
2da95b3cd3
24 changed files with 2325 additions and 28 deletions
|
|
@ -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.
|
||||
|
|
|
|||
19
README.md
19
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 <dir>` 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 <dir>` 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)
|
||||
|
||||
|
|
|
|||
|
|
@ -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"]
|
||||
}
|
||||
|
|
|
|||
|
|
@ -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 <dir>` (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`
|
||||
|
|
|
|||
|
|
@ -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 <dir> --local --fg`, `--external --quick`.
|
||||
|
||||
### /ultra-cc-architect-local modes *(optional, v2.2)*
|
||||
|
||||
| Flag | Behavior |
|
||||
|------|----------|
|
||||
| `--project <dir>` | **Required** — read `{dir}/brief.md` and `{dir}/research/*.md`, write `{dir}/architecture/overview.md` + `{dir}/architecture/gaps.md` |
|
||||
| `--fg` | 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 <dir> --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 <dir> --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 <dir> --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 <dir>` fills in `{dir}/research/`. `/ultraplan-local --project <dir>` reads brief + research to produce `{dir}/plan.md`. `/ultraexecute-local --project <dir>` executes and writes `{dir}/progress.json`. All artifacts live in one project directory.
|
||||
**Pipeline:** `/ultrabrief-local` produces the task brief. `/ultraresearch-local --project <dir>` fills in `{dir}/research/`. `/ultra-cc-architect-local --project <dir>` *(optional, v2.2)* matches available Claude Code features against brief+research and writes `{dir}/architecture/`. `/ultraplan-local --project <dir>` reads brief + research (+ architecture note if present) to produce `{dir}/plan.md`. `/ultraexecute-local --project <dir>` executes and writes `{dir}/progress.json`. All artifacts live in one project directory.
|
||||
|
||||
**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.
|
||||
|
|
|
|||
|
|
@ -1,19 +1,20 @@
|
|||
# ultraplan-local — Brief, Research, Plan, Execute
|
||||
# ultraplan-local — Brief, Research, Architect, Plan, Execute
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
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 <dir> --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 <dir>` | **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.
|
||||
|
|
|
|||
281
plugins/ultraplan-local/agents/architect-orchestrator.md
Normal file
281
plugins/ultraplan-local/agents/architect-orchestrator.md
Normal file
|
|
@ -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.
|
||||
|
||||
<example>
|
||||
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."
|
||||
<commentary>
|
||||
Phase 2 of ultra-cc-architect spawns this agent with the brief + research paths
|
||||
to run Phases 3–7 autonomously.
|
||||
</commentary>
|
||||
</example>
|
||||
|
||||
<example>
|
||||
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."
|
||||
<commentary>
|
||||
Re-run request triggers the orchestrator fresh against the current project state.
|
||||
</commentary>
|
||||
</example>
|
||||
model: opus
|
||||
color: cyan
|
||||
tools: ["Agent", "Read", "Glob", "Grep", "Write", "Edit", "Bash"]
|
||||
---
|
||||
|
||||
<!-- Phase mapping: orchestrator → command
|
||||
Orchestrator Phase 1 = Command Phase 3 (Read inputs)
|
||||
Orchestrator Phase 2 = Command Phase 4 (Feature matching)
|
||||
Orchestrator Phase 3 = Command Phase 5 (Synthesis — write overview.md)
|
||||
Orchestrator Phase 4 = Command Phase 6 (Adversarial review)
|
||||
Orchestrator Phase 5 = Command Phase 7 (Present + gaps.md + stats)
|
||||
This agent handles Phases 3–7 when mode = default (background). -->
|
||||
|
||||
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: <from brief frontmatter>
|
||||
slug: <from brief frontmatter>
|
||||
created: <ISO date>
|
||||
source_brief: <relative path from overview.md to brief.md>
|
||||
source_research: [<list of relative paths>]
|
||||
skills_consulted: [<list of skill `name` values from catalog>]
|
||||
cc_features_proposed: [<list of feature_id values>]
|
||||
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 — <task>
|
||||
|
||||
These are issue-ready drafts. Copy to the project's git host manually
|
||||
when you decide a gap warrants tracking. No auto-creation.
|
||||
|
||||
---
|
||||
|
||||
<gap 1>
|
||||
|
||||
---
|
||||
|
||||
<gap 2>
|
||||
|
||||
...
|
||||
```
|
||||
|
||||
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": "<ISO-8601>",
|
||||
"task": "<brief task, first 100 chars>",
|
||||
"mode": "<default|quick|no-gaps>",
|
||||
"slug": "<from brief>",
|
||||
"project_dir": "<project_dir>",
|
||||
"architecture_path": "<architecture_dir>/overview.md",
|
||||
"gaps_path": "<architecture_dir>/gaps.md | null>",
|
||||
"skills_catalog_size": <N>,
|
||||
"skills_consulted": <N>,
|
||||
"features_proposed": <N>,
|
||||
"gaps_identified": <N>,
|
||||
"critic_verdict": "<PASS|REVISE|BLOCK|SKIPPED>",
|
||||
"guardian_verdict": "<ALIGNED|CREEP|GAP|MIXED|SKIPPED>",
|
||||
"fallback_used": <true|false>
|
||||
}
|
||||
```
|
||||
|
||||
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:** <task>
|
||||
**Project:** <project_dir>
|
||||
**Architecture note:** <overview.md path>
|
||||
**Gaps draft:** <gaps.md path or "skipped (--no-gaps)">
|
||||
**Features proposed:** N (primary: N, secondary: N, fallback: N)
|
||||
**Gaps identified:** N
|
||||
**Review:** <critic_verdict> / <guardian_verdict>
|
||||
|
||||
### Primary features
|
||||
- <feature 1>: <one-line rationale>
|
||||
- <feature 2>: ...
|
||||
|
||||
### Top gaps (if any)
|
||||
- <gap 1>
|
||||
- <gap 2>
|
||||
|
||||
Next step: /ultraplan-local --project <project_dir>
|
||||
(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.
|
||||
167
plugins/ultraplan-local/agents/architecture-critic.md
Normal file
167
plugins/ultraplan-local/agents/architecture-critic.md
Normal file
|
|
@ -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.
|
||||
|
||||
<example>
|
||||
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."
|
||||
<commentary>
|
||||
architect-orchestrator spawns this agent alongside scope-guardian.
|
||||
</commentary>
|
||||
</example>
|
||||
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.
|
||||
154
plugins/ultraplan-local/agents/feature-matcher.md
Normal file
154
plugins/ultraplan-local/agents/feature-matcher.md
Normal file
|
|
@ -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.
|
||||
|
||||
<example>
|
||||
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."
|
||||
<commentary>
|
||||
architect-orchestrator spawns this agent in parallel with gap-identifier.
|
||||
</commentary>
|
||||
</example>
|
||||
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. **<feature_id>** (confidence: <high|med|low>)
|
||||
- Brief anchor: "<verbatim quote from brief section X>"
|
||||
- Supporting skill: <skill_name or "none — fallback hint">
|
||||
- Integration: <one sentence>
|
||||
|
||||
2. ...
|
||||
|
||||
### Secondary features
|
||||
...
|
||||
|
||||
### Fallback features
|
||||
...
|
||||
|
||||
### Feature composition notes
|
||||
- <point 1>
|
||||
- <point 2>
|
||||
|
||||
### Catalog metadata
|
||||
- Skills consulted: N
|
||||
- Fallback used: <true|false>
|
||||
- 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.
|
||||
161
plugins/ultraplan-local/agents/gap-identifier.md
Normal file
161
plugins/ultraplan-local/agents/gap-identifier.md
Normal file
|
|
@ -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.
|
||||
|
||||
<example>
|
||||
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."
|
||||
<commentary>
|
||||
architect-orchestrator spawns this agent alongside feature-matcher.
|
||||
</commentary>
|
||||
</example>
|
||||
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:<feature_id>` (use the taxonomy from SKILL.md)
|
||||
- Layer: `skill-layer:<reference|pattern|decision>`
|
||||
- Urgency: `priority:<low|med|high>` (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 — <feature> / <layer>
|
||||
- **Title**: <imperative title>
|
||||
- **Class**: A | B | C | D
|
||||
- **Priority**: low | med | high
|
||||
- **Description**: <2–4 sentences>
|
||||
- **Labels**: gap, origin:brief-trigger, cc-feature:<x>, skill-layer:<y>, priority:<z>
|
||||
- **Brief context**:
|
||||
> <quote block from brief>
|
||||
- **Proposed resolution**: <one sentence>
|
||||
|
||||
#### Gap 2 — ...
|
||||
|
||||
### Out-of-scope requirements
|
||||
- <requirement>: 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.
|
||||
|
|
@ -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
|
||||
|
|
|
|||
376
plugins/ultraplan-local/commands/ultra-cc-architect-local.md
Normal file
376
plugins/ultraplan-local/commands/ultra-cc-architect-local.md
Normal file
|
|
@ -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 <dir> [--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 <dir>`** (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 <dir> [--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: <from brief>
|
||||
slug: <from brief>
|
||||
created: <ISO date>
|
||||
source_brief: <relative path to brief.md>
|
||||
source_research: [<list of relative research paths>]
|
||||
skills_consulted: [<list of skill `name` values>]
|
||||
cc_features_proposed: [<list of feature_id values>]
|
||||
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 — <task>
|
||||
|
||||
These are issue-ready drafts. Copy to the project's git host manually
|
||||
when you decide a gap warrants tracking. No auto-creation.
|
||||
|
||||
---
|
||||
|
||||
<gap 1 full draft>
|
||||
|
||||
---
|
||||
|
||||
<gap 2>
|
||||
|
||||
...
|
||||
```
|
||||
|
||||
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": "<ISO-8601>",
|
||||
"task": "<brief task, first 100 chars>",
|
||||
"mode": "<default|quick|no-gaps|quick+no-gaps|foreground|foreground+quick|...>",
|
||||
"slug": "<from brief>",
|
||||
"project_dir": "<project_dir>",
|
||||
"architecture_path": "<architecture_dir>/overview.md",
|
||||
"gaps_path": "<architecture_dir>/gaps.md | null>",
|
||||
"skills_catalog_size": <N>,
|
||||
"skills_consulted": <N>,
|
||||
"features_proposed": <N>,
|
||||
"gaps_identified": <N>,
|
||||
"critic_verdict": "<PASS|REVISE|BLOCK|SKIPPED>",
|
||||
"guardian_verdict": "<ALIGNED|CREEP|GAP|MIXED|SKIPPED>",
|
||||
"fallback_used": <true|false>
|
||||
}
|
||||
```
|
||||
|
||||
Hvis `${CLAUDE_PLUGIN_DATA}` ikke er satt eller ikke skrivbar, skip
|
||||
stats silently.
|
||||
|
||||
**Summary til brukeren:**
|
||||
|
||||
```
|
||||
## Ultra-CC-Architect Complete
|
||||
|
||||
**Task:** <task>
|
||||
**Project:** <project_dir>
|
||||
**Architecture note:** <architecture_dir>/overview.md
|
||||
**Gaps draft:** <architecture_dir>/gaps.md | skipped (--no-gaps)
|
||||
**Features proposed:** N (primary: N, secondary: N, fallback: N)
|
||||
**Gaps identified:** N
|
||||
**Review:** <critic_verdict> / <guardian_verdict>
|
||||
|
||||
### Primary features
|
||||
- <feature 1>: <one-line rationale>
|
||||
- <feature 2>: ...
|
||||
|
||||
### Top gaps (if any)
|
||||
- <gap 1>
|
||||
- <gap 2>
|
||||
|
||||
Next step: /ultraplan-local --project <project_dir>
|
||||
(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.
|
||||
|
|
@ -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 <path>`** — 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`.
|
||||
|
|
|
|||
140
plugins/ultraplan-local/skills/cc-architect-catalog/SKILL.md
Normal file
140
plugins/ultraplan-local/skills/cc-architect-catalog/SKILL.md
Normal file
|
|
@ -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: <skill-id> # unique, kebab-case
|
||||
description: <one-line matcher hint> # used by feature-matcher
|
||||
layer: reference | pattern | decision
|
||||
cc_feature: <feature-id> # see table below
|
||||
source: <URL> # canonical upstream source
|
||||
concept: <short phrase> # 3–6 word concept handle
|
||||
last_verified: <YYYY-MM-DD> # when a human last checked against upstream
|
||||
ngram_overlap_score: null # reserved for skill-factory IP-hygiene
|
||||
review_status: approved | pending | auto-merged
|
||||
---
|
||||
```
|
||||
|
||||
`ngram_overlap_score` is reserved. This command respects it (will flag
|
||||
non-null values > threshold) but does not compute it. Skill-factory (a
|
||||
separate later process) populates that field.
|
||||
|
||||
`review_status: approved` is the default for seeds (approved by
|
||||
construction — handwritten, no third-party text copied). Future
|
||||
skill-factory output will start as `pending` (channel 2) or
|
||||
`auto-merged` (channel 1).
|
||||
|
||||
## Canonical `cc_feature` values
|
||||
|
||||
| Value | Coverage |
|
||||
|-------|----------|
|
||||
| `hooks` | Event hooks (UserPromptSubmit, PreToolUse, PostToolUse, Stop, Notification, SessionStart, etc.) |
|
||||
| `subagents` | Task-tool sub-agents, delegation patterns |
|
||||
| `skills` | Claude Code skill system (not Agent SDK skills) |
|
||||
| `output-styles` | Output style configuration |
|
||||
| `mcp` | Model Context Protocol servers and tools |
|
||||
| `plan-mode` | Built-in plan mode |
|
||||
| `worktrees` | Git worktree integration |
|
||||
| `background-agents` | `run_in_background`, Monitor, long-running agents |
|
||||
| `meta` | This manifest only — not a real feature |
|
||||
|
||||
If a future skill covers a feature not in this list, add the row above
|
||||
and surface the extension in the relevant CHANGELOG entry.
|
||||
|
||||
## 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:<layer>` and `cc-feature:<feature>`.
|
||||
|
||||
## Non-goals for this file
|
||||
|
||||
- No skill-factory logic. That is a separate later process.
|
||||
- No auto-discovery of new CC features.
|
||||
- No n-gram computation.
|
||||
- No triggering Claude Code auto-invocation (description deliberately
|
||||
says "not invoked directly").
|
||||
|
||||
## Modification rules
|
||||
|
||||
- Adding a new skill: create `<feature>-<layer>.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.
|
||||
|
|
@ -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.
|
||||
|
|
@ -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".
|
||||
|
|
@ -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.
|
||||
|
|
@ -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__<server-name>__<tool-name>`. 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.
|
||||
|
|
@ -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.
|
||||
|
|
@ -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.
|
||||
|
|
@ -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: <skill-name>
|
||||
description: <one-line trigger hint>
|
||||
---
|
||||
```
|
||||
|
||||
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 `/<skill-name>` 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.
|
||||
|
|
@ -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.
|
||||
|
|
@ -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: <when to invoke, include examples>
|
||||
model: sonnet
|
||||
tools: ["Read", "Grep", "Glob"]
|
||||
---
|
||||
|
||||
<system prompt content>
|
||||
```
|
||||
|
||||
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.
|
||||
|
|
@ -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.
|
||||
Loading…
Add table
Add a link
Reference in a new issue