diff --git a/plugins/ultraplan-local/commands/ultra-cc-architect-local.md b/plugins/ultraplan-local/commands/ultra-cc-architect-local.md index c67630c..ce54323 100644 --- a/plugins/ultraplan-local/commands/ultra-cc-architect-local.md +++ b/plugins/ultraplan-local/commands/ultra-cc-architect-local.md @@ -48,8 +48,9 @@ Parse `$ARGUMENTS` for flags. Ordered precedence: Sett **architecture_dir = {dir}/architecture/** — opprettes i Phase 2 hvis den mangler. -2. **`--fg`** — foreground. Alle faser inline. Default er background - via `architect-orchestrator`. Sett **execution = foreground**. +2. **`--fg`** — no-op alias beholdt for bakoverkompatibilitet. Alle faser + 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 **mode = quick**. @@ -66,8 +67,8 @@ Usage: /ultra-cc-architect-local --project [--fg] [--quick] [--no-gaps] A project directory is required. Run /ultrabrief-local first to create one. Modes: - default Background via architect-orchestrator → overview.md + gaps.md - --fg All phases in foreground (blocks session) + default Foreground pipeline → overview.md + gaps.md + --fg No-op alias (foreground is the only mode as of v2.4.0) --quick Skip adversarial review (no architecture-critic pass) --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 ``` -Mode: {default | foreground}{, quick}{, no-gaps} +Mode: foreground{, quick}{, no-gaps} Project: {project_dir} Brief: {brief_path} ({brief_quality}) Research: {N} files detected ``` -## Phase 2 — Background transition - -**Hvis execution = foreground:** hopp over denne fasen. Fortsett inline -fra Phase 3. - -**Hvis execution = default (background):** +## Phase 2 — Forbered output-mappe (foreground) Opprett `{architecture_dir}` hvis den ikke eksisterer (`mkdir -p`). -Launch the **architect-orchestrator** agent with this prompt: +Rapporter til brukeren: ``` -Brief file: {brief_path} -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. +Architecture pipeline running in foreground. Project: {project_dir} Brief: {brief_path} Research: {N} briefs 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. -architect-orchestrator håndterer Phase 3–7 autonomt. +Fortsett deretter inline til neste fase. + +> **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 -background-agenten. Instruksjonene er identiske uavhengig av kontekst.** +**Alle resterende faser kjører inline i hovedkommandoens kontekst.** --- diff --git a/plugins/ultraplan-local/commands/ultrabrief-local.md b/plugins/ultraplan-local/commands/ultrabrief-local.md index c950bc1..89c29ac 100644 --- a/plugins/ultraplan-local/commands/ultrabrief-local.md +++ b/plugins/ultraplan-local/commands/ultrabrief-local.md @@ -479,7 +479,7 @@ Ask the user via `AskUserQuestion`: | Option | Description | |--------|-------------| | **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) @@ -516,62 +516,50 @@ Proceed to Phase 6. **Runs only when user opted into auto mode.** -### Step 6a — Billing safety check +### Step 6a — Confirm proceed -Run via Bash: -```bash -echo "${ANTHROPIC_API_KEY:+SET}" -``` +Tell the user auto mode will run in foreground and block the session, then +confirm via `AskUserQuestion`: -If `SET`, warn via `AskUserQuestion`: - -**Question:** "`ANTHROPIC_API_KEY` is set. Running {N} parallel research -jobs in background will bill your API account (not your Claude -subscription). Continue?" +**Question:** "Auto mode runs {N} research topic(s) sequentially and then +the plan — all in foreground. This session blocks until the plan is ready. +Continue?" | Option | Action | |--------|--------| -| **Continue — API billing** | Proceed. | -| **Switch to sequential** | Run topics one at a time in foreground instead of parallel background. Stays on subscription for this session. | +| **Continue — auto** | Proceed. | | **Cancel — do manual** | Revert to manual path (print commands, 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. -For each research topic (index i = 1 .. N): - -Launch the **research-orchestrator** agent with this prompt: +For each research topic (index i = 1 .. N), invoke `/ultraresearch-local` +inline in this main-context session: ``` -Research question: {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} +/ultraresearch-local --project {PROJECT_DIR} {--external | --local | (none)} "{topic i question}" ``` -Where `{NN}` is zero-padded index (`01`, `02`, ...) and `{topic-slug}` is -the topic title slugified. +Pass the scope flag that matches the topic's scope hint. Wait for each +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 -in parallel via a single message with multiple Agent tool calls, all -`run_in_background: true`. **Do not wait** in the same message — return -control. You will be notified when each completes. +> **Why sequential inline instead of parallel background?** Background +> orchestrator-agents cannot spawn the research swarm — the Claude Code +> harness does not expose the Agent tool to sub-agents, so a background +> 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 -at a time, foreground (no `run_in_background`), wait for completion, then -launch the next. +### Step 6c — Verify all briefs landed -### Step 6c — Wait for all research to complete - -Wait for all research agent notifications. When all {N} have completed, -verify each research brief file exists: +After the last topic completes, verify each research brief file exists: ```bash ls -1 {PROJECT_DIR}/research/*.md | wc -l @@ -582,24 +570,17 @@ proceed (retry, skip missing topic, cancel). 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 -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. +/ultraplan-local --project {PROJECT_DIR} ``` -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 @@ -618,7 +599,7 @@ When the planning-orchestrator finishes, present: | Step | Status | |------|--------| | 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}) | Next: diff --git a/plugins/ultraplan-local/commands/ultraplan-local.md b/plugins/ultraplan-local/commands/ultraplan-local.md index 2d74787..c7ed18a 100644 --- a/plugins/ultraplan-local/commands/ultraplan-local.md +++ b/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 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} diff --git a/plugins/ultraplan-local/commands/ultraresearch-local.md b/plugins/ultraplan-local/commands/ultraresearch-local.md index dfe8e4e..73e82b8 100644 --- a/plugins/ultraplan-local/commands/ultraresearch-local.md +++ b/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 ` — 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 --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 /ultraresearch-local --project [--external|--local|--quick|--fg] 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 --external +Flags can be combined: --local, --external --quick, --project --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.** ---