open/ktg-plugin-marketplace
1
0
Fork 0
Code Issues Pull requests Releases Wiki Activity Actions
ktg-plugin-marketplace/plugins/ultraplan-local/CLAUDE.md
Kjell Tore Guttormsen 7e2d9e151e feat(ultraplan-local): M1 — profile recommendation flow in ultrabrief 
Adds the profile recommendation step to /ultrabrief-local Phase 4. The
brief stays universal (same questions, same template); the new step is
purely a processing-decision layer that records which profile downstream
commands should apply.

What lands:
- agents/profile-recommender.md — new sonnet agent that scores available
  profiles against the finalized brief (keyword + NFR-signal matching,
  axis bumps, hallucination gate that forbids inventing profile names).
  Emits a fenced JSON block with ranked entries.
- templates/ultrabrief-template.md — frontmatter gains
  recommended_profile, profile_match, profile_rationale (default values
  applied when only `default` is available — true at M1).
- commands/ultrabrief-local.md — Phase 4 gains Step 4h with explicit
  branches: short-circuit when only `default` exists; AskUserQuestion
  confirmation when top score ≥ 0.7; explicit fallback message when below
  threshold; manual selection sub-question on user override. Persists the
  three frontmatter fields to brief.md after user confirmation. JSON
  parser failure falls back to `default` with `profile_match: fallback`
  rather than blocking — silent fallback is the worst outcome, but a
  *visible* fallback is acceptable.
- scripts/profile-loader.mjs — adds selectRecommendation(ranked, opts) +
  RECOMMENDATION_THRESHOLD=0.7 export. Single source of truth for the
  threshold logic so the command spec and the helper agree.
- scripts/profile-loader.test.mjs — 10 new tests for selectRecommendation
  (default-only, empty/malformed input, above/below threshold, custom
  threshold, max-by-score, missing fields). Total now 36/36.
- README.md / CLAUDE.md / marketplace landing — docs reflect M0 + M1
  shipped, M2 + M3 still pending.

In practice nothing changes for users at M1 because only `default` is
available — Step 4h takes the short-circuit path and writes
`profile_match: default-only`. M2 ships the additional profiles that
make the recommender meaningful.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
2026-04-30 14:21:54 +02:00

194 lines
16 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters

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

# ultraplan-local
Deep implementation planning and research with an explicit brief step, specialized agent swarms, external research, CC-feature matching, adversarial review, session decomposition, disciplined execution, and headless support. A local alternative to Anthropic's Ultraplan.
**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
| Command | Description | Model |
|---------|-------------|-------|
| `/ultrabrief-local` | Brief — interactive interview produces a task brief with explicit research plan; optionally orchestrates the pipeline | opus |
| `/ultraresearch-local` | Research — deep local + external research, produces structured research brief | opus |
| `/ultra-cc-architect-local` | Architect *(optional, v2.2)* — match brief+research against Claude Code features; produce architecture note with gaps. Requires `--project` | opus |
| `/ultraplan-local` | Plan — brief-reviewer, explore, plan, review. Requires `--brief` or `--project`. Auto-discovers `architecture/overview.md` if present | opus |
| `/ultraexecute-local` | Execute — disciplined plan/session-spec executor with failure recovery | opus |
| `/ultra-skill-author-local` | Authoring *(v2.3, skill-factory Fase 1)* — generate one cc-architect-catalog draft from a local source with IP-hygiene | opus |
### /ultrabrief-local modes
| Flag | Behavior |
|------|----------|
| _(default)_ | Dynamic interview until quality gates pass → brief.md with research plan |
| `--quick` | Compact start; still escalates if required sections are weak or the brief-review gate fails → brief.md with research plan |
Always interactive. Phase 3 is a section-driven completeness loop (no hard cap on question count); Phase 4 runs a `brief-reviewer` stop-gate with max 3 review iterations. After writing the brief, asks the user to choose manual (print commands) or auto (Claude runs research + plan in foreground).
### /ultraresearch-local modes
| Flag | Behavior |
|------|----------|
| _(default)_ | Interview + research (local + external) + synthesis + brief (foreground) |
| `--project <dir>` | Write brief to `{dir}/research/{NN}-{slug}.md` (auto-incremented) |
| `--quick` | Interview (short) + inline research (no agent swarm) |
| `--local` | Only codebase analysis agents (skip external + Gemini) |
| `--external` | Only external research agents (skip codebase analysis) |
| `--fg` | No-op alias (foreground is default since v2.4.0) |
Flags combine: `--project <dir> --local`, `--external --quick`.
### /ultra-cc-architect-local modes *(optional, v2.2)*
| Flag | Behavior |
|------|----------|
| `--project <dir>` | **Required** — read `{dir}/brief.md` and `{dir}/research/*.md`, write `{dir}/architecture/overview.md` + `{dir}/architecture/gaps.md` |
| `--fg` | No-op alias (foreground is default since v2.4.0) |
| `--quick` | Skip adversarial review (architecture-critic) |
| `--no-gaps` | Skip gap-identifier; overview.md only |
Architect sits between `/ultraresearch-local` and `/ultraplan-local`. It matches the task brief + research against available Claude Code features (Hooks, Subagents, Skills, Output Styles, MCP, Plan Mode, Worktrees, Background Agents) using a seeded catalog skill, and produces a proposed feature set with brief-anchored rationale plus explicit gaps (missing reference, pattern, decision, or outside-CC-scope).
### /ultraplan-local modes
| Flag | Behavior |
|------|----------|
| `--project <dir>` | **Required path A** — read `{dir}/brief.md`, auto-discover `{dir}/research/*.md`, write `{dir}/plan.md` |
| `--brief <path>` | **Required path B** — plan from a specific brief file; write to `.claude/plans/ultraplan-{date}-{slug}.md` |
| `--research <brief> [brief2]` | Enrich with extra research briefs beyond what is in `{project_dir}/research/` |
| `--fg` | No-op alias (foreground is default since v2.4.0) |
| `--quick` | Plan directly (no agent swarm) |
| `--export <pr\|issue\|markdown\|headless> <plan>` | Generate shareable output from existing plan |
| `--decompose <plan>` | Split plan into self-contained headless sessions |
**Breaking change (v2.0):** one of `--brief` or `--project` is required. There is no interview inside `/ultraplan-local`. The `--spec` flag has been removed — use `/ultrabrief-local` to produce a brief instead.
### /ultraexecute-local modes
| Flag | Behavior |
|------|----------|
| _(default)_ | Execute plan — auto-detects Execution Strategy for multi-session |
| `--project <dir>` | Read `{dir}/plan.md`, write `{dir}/progress.json` |
| `--resume` | Resume from last progress checkpoint |
| `--dry-run` | Validate plan structure without executing |
| `--validate` | Schema-only check — parse steps + manifests, report `READY \| FAIL`, no execution |
| `--step N` | Execute only step N |
| `--fg` | Force foreground — run all steps sequentially, ignore Execution Strategy |
| `--session N` | Execute only session N from plan's Execution Strategy |
## Agents
| Agent | Model | Role |
|-------|-------|------|
| planning-orchestrator | opus | Inline reference documentation for the planning pipeline workflow (brief-driven) |
| research-orchestrator | opus | Inline reference documentation for the research pipeline workflow |
| architecture-mapper | sonnet | Codebase structure, tech stack, patterns |
| dependency-tracer | sonnet | Import chains, data flow, side effects |
| task-finder | sonnet | Task-relevant files, functions, reuse candidates |
| risk-assessor | sonnet | Risks, edge cases, failure modes |
| test-strategist | sonnet | Test patterns, coverage gaps, strategy |
| git-historian | sonnet | Recent changes, ownership, hot files |
| research-scout | sonnet | External docs for unfamiliar tech (conditional, planning only) |
| convention-scanner | sonnet | Coding conventions: naming, style, error handling, test patterns |
| brief-reviewer | sonnet | Task brief quality (5 dimensions: completeness, consistency, testability, scope clarity, research plan validity) |
| profile-recommender | sonnet | Match finalized brief against available profiles; ranked JSON output with brief-anchored rationale (M1+) |
| plan-critic | sonnet | Adversarial plan review (9 dimensions) |
| scope-guardian | sonnet | Scope alignment (creep + gaps) |
| session-decomposer | sonnet | Splits plans into headless sessions with dependency graph |
| architect-orchestrator | opus | Inline reference documentation for the architecture phase workflow (feature-matcher + gap-identifier + critic) |
| feature-matcher | sonnet | Match brief+research to CC features using catalog; brief-anchored rationale + fallback ranking |
| gap-identifier | sonnet | Detect catalog/pattern/decision/outside-CC-scope gaps; emit issue-ready drafts |
| architecture-critic | sonnet | Adversarial review of architecture note (hallucination gate, brief-anchor integrity, gap honesty) |
| docs-researcher | sonnet | Official documentation, RFCs, vendor docs (Tavily, MS Learn) |
| community-researcher | sonnet | Community experience: issues, blogs, discussions |
| security-researcher | sonnet | CVEs, audit history, supply chain risks |
| contrarian-researcher | sonnet | Counter-evidence, overlooked alternatives |
| gemini-bridge | sonnet | Gemini Deep Research second opinion (conditional) |
## Architecture
**Brief:** 7-phase workflow: Parse mode → Create project dir → Phase 3 completeness loop (section-driven, no question cap) → Phase 4 draft/review/revise with `brief-reviewer` as stop-gate (max 3 iterations; gate = all dimensions ≥ 4 and research plan = 5) → Finalize (`brief.md` on pass, or `brief_quality: partial` on cap/force-stop) → Manual/auto opt-in → Stats. Always interactive. Auto mode runs research + plan inline in the main context (v2.4.0).
**Research:** Foreground workflow (v2.4.0): Parse mode → Interview → Parallel research swarm (5 local + 4 external + 1 bridge, spawned from main context) → Follow-ups → Triangulation → Synthesis + brief → Stats. With `--project`, writes to `{dir}/research/NN-slug.md`.
**Architect (v2.2, optional):** Foreground workflow (v2.4.0): Parse mode (`--project` required) → Read inputs + audit catalog skill → Parallel `feature-matcher` + `gap-identifier` (spawned from main context) → Synthesize `overview.md` (6 sections + YAML frontmatter) → Adversarial review via `architecture-critic` (skipped in `--quick`; hallucination gate is BLOCKER) → Write `gaps.md` + stats → Present summary. With `--project`, writes `{dir}/architecture/overview.md` and `{dir}/architecture/gaps.md`. Additive — downstream `/ultraplan-local` auto-discovers the note if present.
**Plan:** Foreground workflow (v2.4.0): Parse mode (validate brief input) → Codebase sizing → Brief review (`brief-reviewer`) → Parallel exploration (6-8 agents, spawned from main context) → Deep-dives → Synthesis (with architecture-note cross-reference if present) → Planning → Adversarial review (`plan-critic` + `scope-guardian`) → Present/refine → Handoff. With `--project`, writes to `{dir}/plan.md` and auto-detects `{dir}/architecture/overview.md`.
**Decompose:** Parse plan → Analyze step dependencies → Group into sessions → Identify parallel waves → Generate session specs + dependency graph + launch script.
**Execute:** Parse plan → Security scan (Phase 2.4) → Detect Execution Strategy → Single-session (step loop) or multi-session (parallel waves via `claude -p` with scoped `--allowedTools`) → Phase 7.5 manifest audit → Phase 7.6 bounded recovery (if partial) → Report. With `--project`, reads `{dir}/plan.md` and writes `{dir}/progress.json`.
**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.
**Profiles (M0/M1 — foundation + recommendation):** Profiles describe
which exploration/review agents, catalog filter, and adversarial regime
ultraplan-local should use. They live as `profiles/*.yaml` and are loaded
by `scripts/profile-loader.mjs` (null-deps Node, limited-subset YAML
parser, agent cross-validation). M0 ships only `default.yaml`, which
captures today's hardcoded Phase 5/9 agent set verbatim — so existing
flows are unchanged. Phase 1 of `/ultraplan-local` resolves a profile in
the order `--profile flag → brief frontmatter recommended_profile →
default fallback` and reports `Profile: {name} (source: ...)` in the mode
banner.
M1 adds the recommendation flow: `/ultrabrief-local` Phase 4 gains
Step 4h, which spawns the new `profile-recommender` agent (sonnet,
single-shot, brief-anchored scoring) and writes
`recommended_profile`/`profile_match`/`profile_rationale` to the brief
frontmatter. The threshold is `RECOMMENDATION_THRESHOLD = 0.7` (exported
from the loader); below that, the orchestrator surfaces an explicit
fallback message and offers manual selection via AskUserQuestion. When
only `default` is available, Step 4h short-circuits without asking.
The brief itself stays universal — Step 4h does not change which
questions are asked, only which downstream profile applies. Future
milestones: M2 ships more built-in profiles + replaces the hardcoded
agent table; M3 adds user-extensible profiles under
`.claude/ultraplan-profiles/`.
**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/`.
**Slug convention (v2.3.1):** catalog files follow `<cc_feature>[-<qualifier>]-<layer>.md`.
- **Unqualified slugs** (e.g., `hooks-pattern.md`) are the canonical baseline — one per `(feature, layer)` pair, covering generic shapes and decision-heuristics for the feature.
- **Qualified slugs** (e.g., `hooks-observability-pattern.md`) cover specific named sub-patterns. Zero-or-more per `(feature, layer)` pair. The qualifier MUST be kebab-case and descriptive (`observability`, `migration`, `multi-tenant`).
- **Matcher logic:** `feature-matcher` builds `cc_feature → {layer → [skills]}` and prefers the unqualified baseline when the brief does not specifically justify a variant. Multiple skills can be proposed together when they cover non-overlapping aspects of the same feature.
- **Critic enforcement:** `architecture-critic` verifies every cited `supporting_skill` name exists as a real file in the catalog (blocker severity). The `cc_feature` hallucination gate is unchanged — still validates against the taxonomy, not slugs.
- **Collision handling:** skill-factory drafts that would overwrite an approved slug are a hard error. Resolution is either to qualify the new slug or revise the existing baseline.
- **Drafter collision hint (v2.3.2):** `skill-drafter` reads `{catalog_root}/<slug>.md` before writing, and prepends a warning block to its confirmation output when an existing skill would be overwritten during manual `mv` promotion. The warning cites the existing file's `review_status` and suggests a qualified slug derived from the `concept` handle. The draft is still written to `.drafts/<slug>.md` — the check is a hint, not a block.
Seeds v2.3.1: 11 skills across 8 features — one qualified pattern (`hooks-observability-pattern.md`, promoted from `ai-psychosis/README.md`, ngram-overlap 0.01, approved). Decision-layer intentionally empty pending skill-factory Fase 2.
## State
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`)
Legacy paths (still work without `--project`):
- Research briefs: `.claude/research/ultraresearch-{date}-{slug}.md`
- Plans: `.claude/plans/ultraplan-{date}-{slug}.md`
- Sessions: `.claude/ultraplan-sessions/{slug}/session-*.md`
- Launch scripts: `.claude/ultraplan-sessions/{slug}/launch.sh`
- Progress: `{plan-dir}/.ultraexecute-progress-{slug}.json`
Stats:
- Brief stats: `${CLAUDE_PLUGIN_DATA}/ultrabrief-stats.jsonl`
- 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, 0–N research briefs, and 0 or 1 architecture note.
Reference in a new issue View git blame Copy permalink