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

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>

README.md

@@ -80,6 +80,8 @@ Five core commands plus an authoring command, one pipeline with clear division o
 
 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.4.0 (breaking, default behavior) removes background mode from `/ultraplan-local`, `/ultraresearch-local`, `/ultra-cc-architect-local`, and `/ultrabrief-local` auto-mode. The commands now run foreground in the main context because the harness does not expose the Agent tool to sub-agents — background orchestrators silently degraded the swarm to inline reasoning without external research tools. The `--fg` flag is preserved as a no-op alias for backward compatibility. Source: github.com/anthropics/claude-code/issues/19077.
+
 v2.3 (non-breaking) ships the skill-factory Fase 1 MVP: `/ultra-skill-author-local` plus four supporting agents (1 opus orchestrator + 3 sonnet workers) and `scripts/ngram-overlap.mjs` (pure Node stdlib, word-5-gram containment + longest-run secondary signal, calibrated against three source/draft fixture pairs). Catalog growth is now tractable without touching the architect's hallucination gate. Non-goals stay explicit: no automation, no batch, no decision-layer skills, no remote sources — manual `mv` from `.drafts/` to catalog root is the promotion mechanism. v2.3.1 adds a qualified-slug convention (`<cc_feature>[-<qualifier>]-<layer>.md`) so one feature can host multiple named patterns at different abstraction levels without displacing the baseline — resolved a collision surfaced in v2.3.0 dogfood. v2.3.2 closes the UX gap: `skill-drafter` now reads `{catalog_root}/<slug>.md` before writing and surfaces a collision warning in its confirmation output with a suggested qualified slug, so users see the overwrite risk before running `mv` — not after.
 
 v2.2 (non-breaking) adds the optional `/ultra-cc-architect-local` step between research and planning. The architect phase is backed by a versioned catalog skill (`cc-architect-catalog`) with 10 seed entries across three layers (reference, pattern, decision). Gaps are captured as issue-ready drafts so the catalog grows from real usage rather than speculation. `/ultraplan-local` auto-discovers the architecture note — existing pipelines keep working unchanged.

plugins/ultraplan-local/CHANGELOG.md

@@ -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

plugins/ultraplan-local/CLAUDE.md

@@ -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.
 

plugins/ultraplan-local/README.md

@@ -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