open/ktg-plugin-marketplace
1
0
Fork 0
Code Issues Pull requests Releases Wiki Activity Actions

feat(ultraplan-local)!: v2.4.0 — docs update

Browse source 
Add v2.4.0 CHANGELOG entry documenting the background-mode removal
rationale (harness does not expose Agent tool to sub-agents per
github.com/anthropics/claude-code/issues/19077). Update plugin CLAUDE.md
architecture sections to drop background-transition phases and redefine
the three orchestrator agents as inline reference. Update plugin README
mode tables for /ultraresearch-local, /ultra-cc-architect-local,
/ultraplan-local — --fg is now a no-op alias. Update marketplace root
README with a v2.4.0 paragraph above the v2.3 changelog summary.

Closes the docs portion of the v2.4.0 rollout. Version-sync follows in
the next commit.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
This commit is contained in:
Kjell Tore Guttormsen 2026-04-19 21:39:23 +02:00
commit 23544c79fb
4 changed files with 77 additions and 20 deletions
Download patch file Download diff file Expand all files Collapse all files

53
plugins/ultraplan-local/CHANGELOG.md
View file

@ -4,6 +4,59 @@ 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.4.0] - 2026-04-19
### Breaking change — background mode removed
Default mode for `/ultraplan-local`, `/ultraresearch-local`,
`/ultra-cc-architect-local`, and auto-mode in `/ultrabrief-local` is now
foreground. The command blocks the session until the brief/plan is ready.
### Why
Background mode promised a swarm of specialized agents (docs-researcher,
community-researcher, architecture-mapper, plan-critic, feature-matcher,
gap-identifier, …) spawned by a background orchestrator. It did not work:
the Claude Code harness does not expose the Agent tool to sub-agents
(including ones run with `run_in_background: true`). The orchestrator
silently degraded to inline reasoning in a single Opus context, without
WebSearch, Tavily, WebFetch, or Gemini. Briefs were tagged "high confidence"
but were built on guesses from training data.
Source: github.com/anthropics/claude-code/issues/19077
Empirically confirmed in a plugin investigation on 2026-04-19: a probe
sub-agent reported its exposed tools as `Bash, Edit, Glob, Grep, Read,
Skill, ToolSearch, Write`. The Agent tool was not present, active or
deferred. Foreground execution from the main context spawns sub-agents
correctly (docs-researcher with Tavily intact).
### What changes
- Default execution: foreground for all four commands.
- `--fg` flag is preserved as a no-op alias (backward compatibility).
- Orchestrator agent files (`agents/research-orchestrator.md`,
`agents/planning-orchestrator.md`, `agents/architect-orchestrator.md`)
are redefined from "background executor" to "inline reference" — the
command markdown itself runs the phases in the main context where the
Agent tool is available.
- `ultrabrief-local` auto-mode now runs research sequentially inline
instead of parallel background. The ANTHROPIC_API_KEY billing check
is removed (irrelevant for foreground runs on subscription).
- `skills/cc-architect-catalog/background-agents-reference.md` has been
corrected: Shape A (orchestrator handoff) is now documented as an
anti-pattern, nested spawn from a sub-agent is NOT SUPPORTED.
### For headless/long-running runs
Use `claude -p` in a separate terminal window. Each headless session has
its own main context with the Agent tool, so the swarm works correctly.
### Migration
No code changes required for users. Scripts or documentation that assume
background execution must be updated — the commands now block until done.
## [2.3.2] - 2026-04-18
### Fixed — skill-drafter slug-collision hint

24
plugins/ultraplan-local/CLAUDE.md
View file

@ -28,21 +28,21 @@ Always interactive. Phase 3 is a section-driven completeness loop (no hard cap o
| Flag | Behavior |
|------|----------|
| _(default)_ | Interview + background research (local + external) + synthesis + brief |
| _(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` | All phases in foreground (blocking) |
| `--fg` | No-op alias (foreground is default since v2.4.0) |
Flags combine: `--project <dir> --local --fg`, `--external --quick`.
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` | All phases in foreground (blocking) |
| `--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 |
@ -55,7 +55,7 @@ Architect sits between `/ultraresearch-local` and `/ultraplan-local`. It matches
| `--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` | All phases in foreground (blocking) |
| `--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 |
@ -79,8 +79,8 @@ Architect sits between `/ultraresearch-local` and `/ultraplan-local`. It matches
| Agent | Model | Role |
|-------|-------|------|
| planning-orchestrator | opus | Runs full planning pipeline as background task (brief-driven) |
| research-orchestrator | opus | Runs full research pipeline as background task |
| 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 |
@ -93,7 +93,7 @@ Architect sits between `/ultraresearch-local` and `/ultraplan-local`. It matches
| plan-critic | sonnet | Adversarial plan review (9 dimensions) |
| scope-guardian | sonnet | Scope alignment (creep + gaps) |
| session-decomposer | sonnet | Splits plans into headless sessions with dependency graph |
| architect-orchestrator | opus | Runs architecture phase as background task (feature-matcher + gap-identifier + critic) |
| 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) |
@ -105,13 +105,13 @@ Architect sits between `/ultraresearch-local` and `/ultraplan-local`. It matches
## 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 blocks foreground until plan is ready.
**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:** 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`.
**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):** 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.
**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:** 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`.
**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.

18
plugins/ultraplan-local/README.md
View file

@ -71,7 +71,9 @@ claude plugin marketplace add https://git.fromaitochitta.com/open/ktg-plugin-mar
/ultraexecute-local --project .claude/projects/2026-04-18-jwt-auth
```
Or opt into auto-mode in `/ultrabrief-local` — it will launch research and planning for you in foreground, and return when `plan.md` is ready.
Or opt into auto-mode in `/ultrabrief-local` — it will run research and planning sequentially inline in the main context, and return when `plan.md` is ready.
> **v2.4.0 — background mode removed.** All four orchestrator commands now run foreground in the main context. The `--fg` flag is preserved as a no-op alias for backward compatibility. Background mode silently degraded the agent swarm (the harness does not expose the Agent tool to sub-agents) — see [CHANGELOG](CHANGELOG.md) for the full rationale.
## When to use it
@ -159,14 +161,14 @@ Output:
| Mode | Usage | Behavior |
|------|-------|----------|
| **Default** | `/ultraresearch-local <question>` | Interview + background research (local + external + Gemini) |
| **Default** | `/ultraresearch-local <question>` | Interview + research swarm (local + external + Gemini), foreground |
| **Project** | `/ultraresearch-local --project <dir> <question>` | Write brief into `{dir}/research/NN-slug.md` |
| **Quick** | `/ultraresearch-local --quick <question>` | Interview (short) + inline research, no agent swarm |
| **Local** | `/ultraresearch-local --local <question>` | Only codebase analysis agents (skip external + Gemini) |
| **External** | `/ultraresearch-local --external <question>` | Only external research agents (skip codebase analysis) |
| **Foreground** | `/ultraresearch-local --fg <question>` | All phases in foreground (blocking) |
| **Foreground** | `/ultraresearch-local --fg <question>` | No-op alias (foreground is default since v2.4.0) |
Flags combine: `--project <dir> --external --fg`.
Flags combine: `--project <dir> --external`.
### Research agents
@ -211,7 +213,7 @@ Downstream: `/ultraplan-local` auto-discovers `architecture/overview.md` in proj
| 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`. |
| `--fg` | No-op alias (foreground is default since v2.4.0). |
| `--quick` | Skip adversarial review (no `architecture-critic` pass). |
| `--no-gaps` | Do not write `gaps.md` (gap-section remains inside `overview.md`). |
@ -262,7 +264,7 @@ Output:
| **Project** | `/ultraplan-local --project <dir>` | Read `{dir}/brief.md` + auto-discover `{dir}/research/*.md`, write `{dir}/plan.md` |
| **Brief** | `/ultraplan-local --brief <path>` | Plan from a specific brief file |
| **Research-enriched** | `/ultraplan-local --project <dir> --research <brief>` | Add extra research briefs beyond what is in `research/` |
| **Foreground** | `/ultraplan-local --project <dir> --fg` | All phases in foreground (blocking) |
| **Foreground** | `/ultraplan-local --project <dir> --fg` | No-op alias (foreground is default since v2.4.0) |
| **Quick** | `/ultraplan-local --project <dir> --quick` | No agent swarm, lightweight scan only |
| **Decompose** | `/ultraplan-local --decompose plan.md` | Split plan into headless session specs |
| **Export** | `/ultraplan-local --export pr plan.md` | PR description, issue comment, or clean markdown |
@ -608,8 +610,8 @@ ultraplan-local/
│ ├── research-scout.md # External research (planning)
│ ├── session-decomposer.md # Plan → headless session specs
│ ├── convention-scanner.md # Coding conventions and patterns
│ ├── planning-orchestrator.md # Background planning pipeline (brief-driven)
│ ├── research-orchestrator.md # Background research pipeline
│ ├── planning-orchestrator.md # Inline reference for the planning pipeline (brief-driven)
│ ├── research-orchestrator.md # Inline reference for the research pipeline
│ ├── docs-researcher.md # Official docs, RFCs, vendor docs
│ ├── community-researcher.md # Real-world experience, issues, blogs
│ ├── security-researcher.md # CVEs, audit history, supply chain