feat(ultraplan-local)!: v2.4.0 — commands default to foreground

Remove background-transition phases from /ultraresearch-local,
/ultraplan-local, /ultra-cc-architect-local, /ultrabrief-local.
All four commands now run their full pipelines inline in main
context; --fg is retained as a no-op alias for backwards
compatibility.

The Claude Code harness does not expose the Agent tool to
sub-agents, so orchestrators launched with run_in_background:true
cannot spawn their documented swarms (docs-researcher,
community-researcher, architecture-mapper, plan-critic, etc.) and
silently degrade to single-context reasoning. Foreground execution
keeps the swarms intact.

Source: github.com/anthropics/claude-code/issues/19077
Confirmed empirically 2026-04-19.

BREAKING CHANGE: Default execution is foreground — the session
blocks until the brief/plan is ready. Use `claude -p` in a
separate terminal for long-running headless work.

plugins/ultraplan-local/commands/ultraresearch-local.md

@@ -39,8 +39,9 @@ Supported flags:
 3. `--external` — only external research. Skip codebase analysis agents.
    Set **scope = external**.
 
-4. `--fg` — foreground mode. Run all phases inline (blocking) instead of
-   launching the research-orchestrator in background. Set **execution = foreground**.
+4. `--fg` — accepted as a no-op alias for backwards compatibility. Execution
+   is always foreground as of v2.4.0. Set **execution = foreground** (the
+   only mode).
 
 5. `--project <dir>` — attach this research to an ultrabrief project folder.
    The brief will be written to `{dir}/research/{NN}-{slug}.md` (auto-incremented
@@ -54,12 +55,13 @@ Supported flags:
    Create `{dir}/research/` if it does not already exist.
 
 Flags can be combined:
-- `--local --fg` — local-only research, foreground
+- `--local` — local-only research
 - `--external --quick` — external-only, lightweight
 - `--project <dir> --external` — attach external research to a project
 - `--quick` alone implies both local and external (lightweight)
 
-Defaults: **scope = both**, **execution = background**, **project_dir = none**.
+Defaults: **scope = both**, **execution = foreground** (only mode as of
+v2.4.0), **project_dir = none**.
 
 After stripping flags, the remaining text is the **research question**.
 
@@ -74,14 +76,14 @@ Usage: /ultraresearch-local <research question>
        /ultraresearch-local --project <dir> [--external|--local|--quick|--fg] <research question>
 
 Modes:
-  default       Interview → background research (local + external) → brief
+  default       Interview → foreground research (local + external) → brief
   --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 (blocks session)
+  --fg          No-op alias (foreground is the only mode as of v2.4.0)
   --project     Write brief into an ultrabrief project folder (auto-indexed)
 
-Flags can be combined: --local --fg, --external --quick, --project <dir> --external
+Flags can be combined: --local, --external --quick, --project <dir> --external
 
 Examples:
   /ultraresearch-local Should we migrate from Express to Fastify?
@@ -96,7 +98,7 @@ Do not continue past this step if no question was provided.
 
 Report the detected mode:
 ```
-Mode: {default | quick}, Scope: {both | local | external}, Execution: {background | foreground}
+Mode: {default | quick}, Scope: {both | local | external}, Execution: foreground
 Project: {project_dir or "-"}
 Question: {research question}
 ```
@@ -168,50 +170,37 @@ Research dimensions identified:
 ...
 ```
 
-## Phase 3 — Background transition
+## Phase 3 — Slug and destination (foreground)
 
-**If execution = foreground or mode = quick:** Skip this phase. Continue inline.
+Generate a slug from the research question (first 3-4 meaningful words,
+lowercase, hyphens). Confirm the `brief_destination` computed in Phase 1.
 
-**If execution = background (default):**
-
-Generate a slug from the research question (first 3-4 meaningful words, lowercase,
-hyphens). Use the `brief_destination` computed in Phase 1.
-
-Launch the **research-orchestrator** agent with this prompt:
+Report to the user:
 
 ```
-Research question: {question}
-Dimensions: {list of dimensions from interview}
-Mode: {default | quick}
-Scope: {both | local | external}
-Project dir: {project_dir or "-"}
-Brief destination: {brief_destination}
-Plugin root: ${CLAUDE_PLUGIN_ROOT}
-```
-
-Launch via Agent tool with `run_in_background: true`.
-
-Then output to the user and **stop your response**:
-```
-Background research started via research-orchestrator.
+Research pipeline running in foreground.
 
   Question: {research question}
   Dimensions: {N} identified
   Scope: {both | local | external}
   Project: {project_dir or "-"}
-  Brief: {brief_destination}
-
-You will be notified when the research brief is ready.
-You can continue working on other tasks in the meantime.
+  Brief:   {brief_destination}
 ```
 
-Do not wait for the orchestrator. Do not continue to Phase 4.
-The research-orchestrator handles Phases 4 through 8 autonomously.
+Then continue to the next phase inline.
+
+> **Why foreground?** As of v2.4.0 the research-orchestrator is no longer
+> spawned as a background agent. The Claude Code harness does not expose the
+> Agent tool to sub-agents, so an orchestrator launched with
+> `run_in_background: true` cannot spawn the documented research swarm
+> (`docs-researcher`, `community-researcher`, etc.) and silently degrades to
+> single-context reasoning without WebSearch / Tavily / WebFetch / Gemini.
+> Running the phases inline in main context keeps the swarm intact. Use
+> `claude -p` in a separate terminal window for long-running headless work.
 
 ---
 
-**Everything below this line runs either in foreground mode, quick mode, or
-inside the background agent. The instructions are identical regardless of context.**
+**All remaining phases run inline in the main command context.**
 
 ---