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

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

Browse source 
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.
This commit is contained in:
Kjell Tore Guttormsen 2026-04-19 21:23:02 +02:00
commit 4bba65cddf
4 changed files with 105 additions and 173 deletions
Download patch file Download diff file Expand all files Collapse all files

59
plugins/ultraplan-local/commands/ultra-cc-architect-local.md
View file

@ -48,8 +48,9 @@ Parse `$ARGUMENTS` for flags. Ordered precedence:
Sett **architecture_dir = {dir}/architecture/** — opprettes i Sett **architecture_dir = {dir}/architecture/** — opprettes i
Phase 2 hvis den mangler. Phase 2 hvis den mangler.
2. **`--fg`** — foreground. Alle faser inline. Default er background 2. **`--fg`** — no-op alias beholdt for bakoverkompatibilitet. Alle faser
via `architect-orchestrator`. Sett **execution = foreground**. kjører alltid inline i main-kontekst som av v2.4.0. Sett
**execution = foreground** (eneste modus).
3. **`--quick`** — hopp over Phase 6 (adversarial review). Sett 3. **`--quick`** — hopp over Phase 6 (adversarial review). Sett
**mode = quick**. **mode = quick**.
@ -66,8 +67,8 @@ Usage: /ultra-cc-architect-local --project <dir> [--fg] [--quick] [--no-gaps]
A project directory is required. Run /ultrabrief-local first to create one. A project directory is required. Run /ultrabrief-local first to create one.
Modes: Modes:
default Background via architect-orchestrator → overview.md + gaps.md default Foreground pipeline → overview.md + gaps.md
--fg All phases in foreground (blocks session) --fg No-op alias (foreground is the only mode as of v2.4.0)
--quick Skip adversarial review (no architecture-critic pass) --quick Skip adversarial review (no architecture-critic pass)
--no-gaps Do not write gaps.md (gap-section stays inside overview.md) --no-gaps Do not write gaps.md (gap-section stays inside overview.md)
@ -101,61 +102,41 @@ Glob `{project_dir}/research/*.md`. Lagre liste som
### Rapporter detektert modus ### Rapporter detektert modus
``` ```
Mode: {default | foreground}{, quick}{, no-gaps} Mode: foreground{, quick}{, no-gaps}
Project: {project_dir} Project: {project_dir}
Brief: {brief_path} ({brief_quality}) Brief: {brief_path} ({brief_quality})
Research: {N} files detected Research: {N} files detected
``` ```
## Phase 2 — Background transition ## Phase 2 — Forbered output-mappe (foreground)
**Hvis execution = foreground:** hopp over denne fasen. Fortsett inline
fra Phase 3.
**Hvis execution = default (background):**
Opprett `{architecture_dir}` hvis den ikke eksisterer (`mkdir -p`). Opprett `{architecture_dir}` hvis den ikke eksisterer (`mkdir -p`).
Launch the **architect-orchestrator** agent with this prompt: Rapporter til brukeren:
``` ```
Brief file: {brief_path} Architecture pipeline running in foreground.
Project dir: {project_dir}
Architecture dir: {architecture_dir}
Research briefs: {comma-separated research_paths, or "none"}
Skill catalog root: ${CLAUDE_PLUGIN_ROOT}/skills/cc-architect-catalog
Plugin root: ${CLAUDE_PLUGIN_ROOT}
Mode: {default | quick}{, no-gaps if set}
Read the brief and every research brief. Execute your full workflow.
Write overview.md to the architecture dir. Write gaps.md unless mode
includes no-gaps.
```
Launch via Agent-tool med `run_in_background: true`, `subagent_type:
architect-orchestrator`.
Deretter output til bruker og **stopp ditt svar**:
```
Background architecture run started via architect-orchestrator.
Project: {project_dir} Project: {project_dir}
Brief: {brief_path} Brief: {brief_path}
Research: {N} briefs Research: {N} briefs
Output: {architecture_dir}/overview.md (+ gaps.md) Output: {architecture_dir}/overview.md (+ gaps.md)
You will be notified when the architecture note is ready.
You can continue working on other tasks in the meantime.
``` ```
Ikke vent på orchestratoren. Ikke fortsett til Phase 3. Fortsett deretter inline til neste fase.
architect-orchestrator håndterer Phase 3–7 autonomt.
> **Hvorfor foreground?** Som av v2.4.0 spawnes `architect-orchestrator`
> ikke lenger som en background-agent. Claude Code-harnessen eksponerer
> ikke Agent-tool til sub-agenter, så en orchestrator startet med
> `run_in_background: true` kan ikke spawne `feature-matcher` /
> `gap-identifier` / `architecture-critic`-swarm og degraderer stille til
> enkelt-kontekst-resonnering. Å kjøre fasene inline i main-kontekst holder
> swarm-en intakt. Bruk `claude -p` i et separat terminal-vindu for
> langvarige headless-kjøringer.
--- ---
**Alt under denne linjen kjører enten i foreground-modus eller inne i **Alle resterende faser kjører inline i hovedkommandoens kontekst.**
background-agenten. Instruksjonene er identiske uavhengig av kontekst.**
--- ---

85
plugins/ultraplan-local/commands/ultrabrief-local.md
View file

@ -479,7 +479,7 @@ Ask the user via `AskUserQuestion`:
| Option | Description | | Option | Description |
|--------|-------------| |--------|-------------|
| **Manual (default)** | Print the commands. You run `/ultraresearch-local` and `/ultraplan-local` yourself, choosing depth per topic. | | **Manual (default)** | Print the commands. You run `/ultraresearch-local` and `/ultraplan-local` yourself, choosing depth per topic. |
| **Auto (managed by Claude Code)** | I run all {N} research topics in parallel, then automatically trigger `/ultraplan-local` when research completes. Foreground — this session blocks until the plan is ready. | | **Auto (managed by Claude Code)** | I run all {N} research topics sequentially in foreground, then automatically trigger `/ultraplan-local` when research completes. This session blocks until the plan is ready. |
### Manual path (default) ### Manual path (default)
@ -516,62 +516,50 @@ Proceed to Phase 6.
**Runs only when user opted into auto mode.** **Runs only when user opted into auto mode.**
### Step 6a — Billing safety check ### Step 6a — Confirm proceed
Run via Bash: Tell the user auto mode will run in foreground and block the session, then
```bash confirm via `AskUserQuestion`:
echo "${ANTHROPIC_API_KEY:+SET}"
```
If `SET`, warn via `AskUserQuestion`: **Question:** "Auto mode runs {N} research topic(s) sequentially and then
the plan — all in foreground. This session blocks until the plan is ready.
**Question:** "`ANTHROPIC_API_KEY` is set. Running {N} parallel research Continue?"
jobs in background will bill your API account (not your Claude
subscription). Continue?"
| Option | Action | | Option | Action |
|--------|--------| |--------|--------|
| **Continue — API billing** | Proceed. | | **Continue — auto** | Proceed. |
| **Switch to sequential** | Run topics one at a time in foreground instead of parallel background. Stays on subscription for this session. |
| **Cancel — do manual** | Revert to manual path (print commands, stop). | | **Cancel — do manual** | Revert to manual path (print commands, stop). |
If cancelled → fall back to manual path output and stop. If cancelled → fall back to manual path output and stop.
If sequential → note and proceed (Step 6b runs foreground, one at a time).
If continue → proceed with parallel background.
### Step 6b — Launch research jobs ### Step 6b — Run research topics sequentially (inline)
Set `research_status: in_progress` in the brief's frontmatter. Set `research_status: in_progress` in the brief's frontmatter.
For each research topic (index i = 1 .. N): For each research topic (index i = 1 .. N), invoke `/ultraresearch-local`
inline in this main-context session:
Launch the **research-orchestrator** agent with this prompt:
``` ```
Research question: {topic i question} /ultraresearch-local --project {PROJECT_DIR} {--external | --local | (none)} "{topic i question}"
Dimensions: {infer 3-5 dimensions from topic confidence + cost hints}
Mode: {default if cost=standard or deep; quick if cost=quick}
Scope: {topic i scope hint: local | external | both}
Brief destination: {PROJECT_DIR}/research/{NN}-{topic-slug}.md
Plugin root: ${CLAUDE_PLUGIN_ROOT}
``` ```
Where `{NN}` is zero-padded index (`01`, `02`, ...) and `{topic-slug}` is Pass the scope flag that matches the topic's scope hint. Wait for each
the topic title slugified. invocation to finish writing the research brief at
`{PROJECT_DIR}/research/{NN}-{topic-slug}.md` before moving to the next
topic.
**Parallel (default auto path):** launch all N research-orchestrator agents > **Why sequential inline instead of parallel background?** Background
in parallel via a single message with multiple Agent tool calls, all > orchestrator-agents cannot spawn the research swarm — the Claude Code
`run_in_background: true`. **Do not wait** in the same message — return > harness does not expose the Agent tool to sub-agents, so a background
control. You will be notified when each completes. > run silently degrades to single-context reasoning without WebSearch /
> Tavily / WebFetch / Gemini (see v2.4.0 release notes). Running each
> research pass inline in main context keeps the swarm intact. For true
> parallel execution, use `claude -p` invocations in separate terminal
> windows.
**Sequential (if user chose sequential):** launch one research-orchestrator ### Step 6c — Verify all briefs landed
at a time, foreground (no `run_in_background`), wait for completion, then
launch the next.
### Step 6c — Wait for all research to complete After the last topic completes, verify each research brief file exists:
Wait for all research agent notifications. When all {N} have completed,
verify each research brief file exists:
```bash ```bash
ls -1 {PROJECT_DIR}/research/*.md | wc -l ls -1 {PROJECT_DIR}/research/*.md | wc -l
@ -582,24 +570,17 @@ proceed (retry, skip missing topic, cancel).
Update brief frontmatter: `research_status: complete`. Update brief frontmatter: `research_status: complete`.
### Step 6d — Auto-trigger planning ### Step 6d — Auto-trigger planning (inline foreground)
Launch the **planning-orchestrator** agent with this prompt: Invoke the planning command inline in this session:
``` ```
Brief file: {PROJECT_DIR}/brief.md /ultraplan-local --project {PROJECT_DIR}
Project dir: {PROJECT_DIR}
Task: {task description from brief}
Mode: default
Plan destination: {PROJECT_DIR}/plan.md
Plugin root: ${CLAUDE_PLUGIN_ROOT}
Research briefs: {list of {PROJECT_DIR}/research/*.md files}
Read the brief file and every research brief. Execute your full planning
workflow. Write the plan to the destination path.
``` ```
Launch foreground (wait for completion — user asked for full auto). The planning pipeline runs all phases (exploration, synthesis, review) in
main context. Wait for the plan to be written to `{PROJECT_DIR}/plan.md`
before continuing.
### Step 6e — Report completion ### Step 6e — Report completion
@ -618,7 +599,7 @@ When the planning-orchestrator finishes, present:
| Step | Status | | Step | Status |
|------|--------| |------|--------|
| Brief | Complete ({interview_turns} interview turns) | | Brief | Complete ({interview_turns} interview turns) |
| Research | Complete ({N} topics, {P} parallel / {S} sequential) | | Research | Complete ({N} topics, sequential foreground) |
| Plan | Complete ({steps} steps, critic: {verdict}) | | Plan | Complete ({steps} steps, critic: {verdict}) |
Next: Next:

69
plugins/ultraplan-local/commands/ultraplan-local.md
View file

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

65
plugins/ultraplan-local/commands/ultraresearch-local.md
View file

@ -39,8 +39,9 @@ Supported flags:
3. `--external` — only external research. Skip codebase analysis agents. 3. `--external` — only external research. Skip codebase analysis agents.
Set **scope = external**. Set **scope = external**.
4. `--fg` — foreground mode. Run all phases inline (blocking) instead of 4. `--fg` — accepted as a no-op alias for backwards compatibility. Execution
launching the research-orchestrator in background. Set **execution = foreground**. 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. 5. `--project <dir>` — attach this research to an ultrabrief project folder.
The brief will be written to `{dir}/research/{NN}-{slug}.md` (auto-incremented 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. Create `{dir}/research/` if it does not already exist.
Flags can be combined: Flags can be combined:
- `--local --fg` — local-only research, foreground - `--local` — local-only research
- `--external --quick` — external-only, lightweight - `--external --quick` — external-only, lightweight
- `--project <dir> --external` — attach external research to a project - `--project <dir> --external` — attach external research to a project
- `--quick` alone implies both local and external (lightweight) - `--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**. 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> /ultraresearch-local --project <dir> [--external|--local|--quick|--fg] <research question>
Modes: Modes:
default Interview → background research (local + external) → brief default Interview → foreground research (local + external) → brief
--quick Interview (short) → inline research (no agent swarm) --quick Interview (short) → inline research (no agent swarm)
--local Only codebase analysis agents (skip external + Gemini) --local Only codebase analysis agents (skip external + Gemini)
--external Only external research agents (skip codebase analysis) --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) --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: Examples:
/ultraresearch-local Should we migrate from Express to Fastify? /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: 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 "-"} Project: {project_dir or "-"}
Question: {research question} 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):** Report to the user:
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:
``` ```
Research question: {question} Research pipeline running in foreground.
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.
Question: {research question} Question: {research question}
Dimensions: {N} identified Dimensions: {N} identified
Scope: {both | local | external} Scope: {both | local | external}
Project: {project_dir or "-"} Project: {project_dir or "-"}
Brief: {brief_destination} Brief: {brief_destination}
You will be notified when the research brief is ready.
You can continue working on other tasks in the meantime.
``` ```
Do not wait for the orchestrator. Do not continue to Phase 4. Then continue to the next phase inline.
The research-orchestrator handles Phases 4 through 8 autonomously.
> **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 **All remaining phases run inline in the main command context.**
inside the background agent. The instructions are identical regardless of context.**
--- ---