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/ultraplan-local.md

@@ -85,8 +85,8 @@ Parse `$ARGUMENTS` for mode flags. Order of precedence:
    When combined with `--project`, the explicit `--research` briefs are
    appended to the auto-discovered ones (deduplicated by path).
 
-6. **`--fg`** — set **mode = foreground**. All phases run in this session
-   (no background handoff).
+6. **`--fg`** — accepted as a no-op alias for backwards compatibility. All
+   phases always run in the main session as of v2.4.0.
 
 7. **`--quick`** — set **mode = quick**. Skip agent swarm; use lightweight
    Glob/Grep scan and go directly to planning + adversarial review.
@@ -106,10 +106,10 @@ Usage: /ultraplan-local --brief <path-to-brief.md>
 A brief is required. Produce one with /ultrabrief-local first.
 
 Modes:
-  --brief       Plan from a brief file (background unless --fg)
+  --brief       Plan from a brief file (foreground, v2.4.0+)
   --project     Plan from a project directory (brief.md + research/ auto-resolved)
   --research    Add up to 3 extra research briefs as planning context
-  --fg          All phases in foreground (blocks session)
+  --fg          No-op alias (foreground is the only mode as of v2.4.0)
   --quick       Skip exploration agent swarm; plan directly
   --export      Generate shareable output from an existing plan (no new planning)
   --decompose   Split an existing plan into self-contained headless sessions
@@ -146,7 +146,7 @@ If `research_status == pending` and `research_topics > 0`:
 
 Report the detected mode:
 ```
-Mode:    {background | foreground | quick | export | decompose}
+Mode:    {foreground | quick | export | decompose}
 Brief:   {brief_path}
 Project: {project_dir or "-"}
 Research: {N local briefs, M extra via --research}
@@ -301,11 +301,7 @@ The interview phase has moved to `/ultrabrief-local`. This command no
 longer asks the user any requirements questions — the brief is the
 authoritative input.
 
-## Phase 3 — Background transition
-
-**If mode = foreground or quick:** Skip this phase. Continue to Phase 4 inline.
-
-**If mode = default (background):**
+## Phase 3 — Destination and context recap (foreground)
 
 Determine the plan destination path:
 - If `project_dir` is set (from `--project` or the brief's `project_dir`
@@ -317,48 +313,32 @@ Determine the plan destination path:
 Collect all research briefs (from `--research` flag and auto-discovered
 `{project_dir}/research/*.md`).
 
-Launch the **planning-orchestrator** agent with this prompt:
+Report to the user:
 
 ```
-Brief file: {brief_path}
-Project dir: {project_dir or "-"}
-Task: {task from brief frontmatter}
-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. 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`.
-The agent runs autonomously while you continue working — you will be notified
-when the plan is ready.
-
-Then output to the user and **stop your response**:
-
-```
-Background planning started via planning-orchestrator.
+Planning pipeline running in foreground.
 
   Brief:   {brief_path}
   Project: {project_dir or "-"}
   Plan:    {plan destination}
-
-You will be notified when the plan is ready.
-You can continue working on other tasks in the meantime.
+  Research briefs: {N}
+  Architecture note: {present | none}
 ```
 
-Do not wait for the orchestrator. Do not continue to Phase 4.
-The planning-orchestrator handles Phases 4 through 10 autonomously.
+Then continue to the next phase inline.
+
+> **Why foreground?** As of v2.4.0 the planning-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 exploration swarm
+> (`architecture-mapper`, `task-finder`, `plan-critic`, etc.) and silently
+> degrades to single-context reasoning. 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 or inside the
-background agent. The instructions are identical regardless of context.**
+**All remaining phases run inline in the main command context.**
 
 ---
 
@@ -390,8 +370,9 @@ consistency, testability, scope clarity, and research-plan validity."
 Handle the verdict:
 - **PROCEED** — continue to Phase 5.
 - **PROCEED_WITH_RISKS** — continue, carry flagged risks as `[ASSUMPTION]` in the plan.
-- **REVISE** — in foreground mode, present findings and ask the user for clarification.
-  In background mode, carry all findings as `[ASSUMPTION]` entries.
+- **REVISE** — present findings and ask the user for clarification
+  (foreground is the only mode). If the user force-stops, carry outstanding
+  findings as `[ASSUMPTION]` entries.
 
 ## Phase 5 — Parallel exploration (specialized agents + research)
 
@@ -606,7 +587,7 @@ Present a summary to the user:
 ## Ultraplan Complete
 
 **Task:** {task description}
-**Mode:** {background | foreground | quick}
+**Mode:** {foreground | quick}
 **Brief:** {brief_path}
 **Project:** {project_dir or "-"}
 **Plan:** {plan_path}