feat(ultraplan-local): v1.6.0 — /ultraresearch-local deep research command
Add /ultraresearch-local for structured research combining local codebase analysis with external knowledge via parallel agent swarms. Produces research briefs with triangulation, confidence ratings, and source quality assessment. New command: /ultraresearch-local with modes --quick, --local, --external, --fg. New agents: research-orchestrator (opus), docs-researcher, community-researcher, security-researcher, contrarian-researcher, gemini-bridge (all sonnet). New template: research-brief-template.md. Integration: --research flag in /ultraplan-local accepts pre-built research briefs (up to 3), enriches the interview and exploration phases. Planning orchestrator cross-references brief findings during synthesis. Design principle: Context Engineering — right information to right agent at right time. Research briefs are structured artifacts in the pipeline: ultraresearch → brief → ultraplan --research → plan → ultraexecute. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
This commit is contained in:
Kjell Tore Guttormsen
parent
026975cfe5
commit
5be9c8e47c
27 changed files with 1723 additions and 73 deletions
|
|
@ -49,7 +49,22 @@ Parse `$ARGUMENTS` for mode flags:
|
|||
Error: plan file not found: {path}
|
||||
```
|
||||
|
||||
6. Otherwise: the entire argument string is the task description.
|
||||
6. If arguments contain `--research `: extract file path(s) after `--research`.
|
||||
Collect paths until encountering another `--` flag or a token that does not
|
||||
look like a file path (no `/` or `.md` extension). Maximum 3 briefs.
|
||||
Set **has_research_brief = true**. Validate each path exists — if any is
|
||||
missing, report and stop:
|
||||
```
|
||||
Error: research brief not found: {path}
|
||||
```
|
||||
The `--research` flag can combine with other flags:
|
||||
- `--research brief.md <task>` — default mode with research brief
|
||||
- `--research brief.md --fg <task>` — foreground with research brief
|
||||
- `--research brief.md --spec spec.md` — spec-driven with research brief
|
||||
Remove `--research` and its paths from the argument string before
|
||||
applying the other flag checks above.
|
||||
|
||||
7. Otherwise: the entire argument string is the task description.
|
||||
Set **mode = default**.
|
||||
|
||||
If no task description and no spec file, output usage and stop:
|
||||
|
|
@ -57,6 +72,7 @@ If no task description and no spec file, output usage and stop:
|
|||
```
|
||||
Usage: /ultraplan-local <task description>
|
||||
/ultraplan-local --spec <path-to-spec.md>
|
||||
/ultraplan-local --research <brief.md> [brief2.md] <task description>
|
||||
/ultraplan-local --fg <task description>
|
||||
/ultraplan-local --quick <task description>
|
||||
/ultraplan-local --export <pr|issue|markdown|headless> <plan-path>
|
||||
|
|
@ -65,14 +81,21 @@ Usage: /ultraplan-local <task description>
|
|||
Modes:
|
||||
default Interview (interactive) → background planning → notify when done
|
||||
--spec Skip interview, use provided spec → background planning
|
||||
--research Enrich planning with pre-built research brief(s) (up to 3)
|
||||
--fg All phases in foreground (blocks session)
|
||||
--quick Interview → plan directly (no agent swarm) → adversarial review
|
||||
--export Generate shareable output from an existing plan (no new planning)
|
||||
--decompose Split an existing plan into self-contained headless sessions
|
||||
|
||||
--research can combine with other flags:
|
||||
--research brief.md <task> Default mode + research context
|
||||
--research brief.md --fg <task> Foreground + research context
|
||||
--research brief.md --spec spec.md Spec-driven + research context
|
||||
|
||||
Examples:
|
||||
/ultraplan-local Add user authentication with JWT tokens
|
||||
/ultraplan-local --spec .claude/ultraplan-spec-2026-04-05-jwt-auth.md
|
||||
/ultraplan-local --research .claude/research/ultraresearch-2026-04-08-oauth2.md Implement OAuth2 auth
|
||||
/ultraplan-local --fg Refactor the database layer to use connection pooling
|
||||
/ultraplan-local --quick Add rate limiting to the API
|
||||
/ultraplan-local --export pr .claude/plans/ultraplan-2026-04-06-rate-limiting.md
|
||||
|
|
@ -235,6 +258,21 @@ Then **stop**. Do not continue to Phase 2 or any subsequent phase.
|
|||
|
||||
**Skip this phase entirely if mode = spec-driven.** Proceed to Phase 3.
|
||||
|
||||
### Research-enriched interview
|
||||
|
||||
If **has_research_brief = true**: read each research brief file before starting the
|
||||
interview. Then adjust the interview:
|
||||
|
||||
1. Tell the user: "I've read {N} research brief(s). The interview will focus on
|
||||
decisions and implementation details — skipping topics already covered."
|
||||
2. Skip questions about technologies, patterns, or approaches already researched.
|
||||
3. Focus on: implementation preferences, non-functional requirements, scope decisions.
|
||||
4. Reference brief findings in questions where relevant:
|
||||
> "The research brief found that {finding}. Does this affect your approach?"
|
||||
> "The brief identified {risk}. Should the plan account for this?"
|
||||
|
||||
If **has_research_brief = false**: proceed with the standard interview below.
|
||||
|
||||
Use `AskUserQuestion` to interview the user about the task. Ask **one question at
|
||||
a time** — never dump all questions at once. Follow up based on answers.
|
||||
|
||||
|
|
@ -312,6 +350,7 @@ Task: {task description}
|
|||
Mode: {default | spec | quick}
|
||||
Plan destination: .claude/plans/ultraplan-{YYYY-MM-DD}-{slug}.md
|
||||
Plugin root: ${CLAUDE_PLUGIN_ROOT}
|
||||
Research briefs: {path1, path2, ...} ← include ONLY if has_research_brief = true
|
||||
|
||||
Read the spec file and execute your full planning workflow.
|
||||
Write the plan to the destination path.
|
||||
|
|
|
|||
393
plugins/ultraplan-local/commands/ultraresearch-local.md
Normal file
393
plugins/ultraplan-local/commands/ultraresearch-local.md
Normal file
|
|
@ -0,0 +1,393 @@
|
|||
---
|
||||
name: ultraresearch-local
|
||||
description: Deep research combining local codebase analysis with external knowledge, producing structured research briefs with triangulation and confidence ratings
|
||||
argument-hint: "[--quick | --local | --external | --fg] <research question>"
|
||||
model: opus
|
||||
allowed-tools: Agent, Read, Glob, Grep, Write, Edit, Bash, AskUserQuestion, WebSearch, WebFetch, mcp__tavily__tavily_search, mcp__tavily__tavily_research
|
||||
---
|
||||
|
||||
# Ultraresearch Local v1.0
|
||||
|
||||
Deep, multi-phase research that combines local codebase analysis with external
|
||||
knowledge. Uses specialized agent swarms to investigate multiple dimensions in
|
||||
parallel, then triangulates findings to produce insights that neither local nor
|
||||
external research could provide alone.
|
||||
|
||||
**Design principle: Context Engineering** — build the right context by orchestrating
|
||||
specialized agents, each seeing only what they need. The value is in triangulation
|
||||
(cross-checking local vs. external) and synthesis (insights from combining both).
|
||||
|
||||
**Pipeline integration:** Research briefs feed into ultraplan via `--research`:
|
||||
```
|
||||
/ultraresearch-local <question> → brief → /ultraplan-local --research <brief> <task>
|
||||
```
|
||||
|
||||
## Phase 1 — Parse mode and validate input
|
||||
|
||||
Parse `$ARGUMENTS` for mode flags. Flags can appear in any order before the
|
||||
research question. Collect all flags first, then treat the remainder as the
|
||||
research question.
|
||||
|
||||
Supported flags:
|
||||
|
||||
1. `--quick` — lightweight research, no agent swarm. The command itself does
|
||||
3-5 targeted searches inline. Set **mode = quick**.
|
||||
|
||||
2. `--local` — only codebase research. Skip external agents and gemini bridge.
|
||||
Set **scope = local**.
|
||||
|
||||
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**.
|
||||
|
||||
Flags can be combined:
|
||||
- `--local --fg` — local-only research, foreground
|
||||
- `--external --quick` — external-only, lightweight
|
||||
- `--quick` alone implies both local and external (lightweight)
|
||||
|
||||
Defaults: **scope = both**, **execution = background**.
|
||||
|
||||
After stripping flags, the remaining text is the **research question**.
|
||||
|
||||
If no research question is provided, output usage and stop:
|
||||
|
||||
```
|
||||
Usage: /ultraresearch-local <research question>
|
||||
/ultraresearch-local --quick <research question>
|
||||
/ultraresearch-local --local <research question>
|
||||
/ultraresearch-local --external <research question>
|
||||
/ultraresearch-local --fg <research question>
|
||||
|
||||
Modes:
|
||||
default Interview → background 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)
|
||||
|
||||
Flags can be combined: --local --fg, --external --quick
|
||||
|
||||
Examples:
|
||||
/ultraresearch-local Should we migrate from Express to Fastify?
|
||||
/ultraresearch-local --quick What auth libraries are popular for Node.js?
|
||||
/ultraresearch-local --local How is error handling structured in this codebase?
|
||||
/ultraresearch-local --external What are the security implications of using Redis for sessions?
|
||||
/ultraresearch-local --fg --local What patterns does this codebase use for database access?
|
||||
```
|
||||
|
||||
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}
|
||||
Question: {research question}
|
||||
```
|
||||
|
||||
## Phase 2 — Research interview
|
||||
|
||||
Use `AskUserQuestion` to clarify the research question. Ask **one question at a time**.
|
||||
|
||||
The interview is shorter than ultraplan's (2-4 questions, not 3-8) because research
|
||||
is more focused than planning.
|
||||
|
||||
### Interview flow
|
||||
|
||||
**Start with the research question itself.** If the user provided a clear, specific
|
||||
question, you may skip directly to follow-ups.
|
||||
|
||||
**Core questions (pick 2-4 based on clarity of initial question):**
|
||||
|
||||
1. **Decision context:** "What decision does this research feed? Are you evaluating
|
||||
options, investigating feasibility, or building understanding?"
|
||||
*Skip if the question itself makes this obvious.*
|
||||
|
||||
2. **Dimensions:** "Are there specific aspects you care about most? (e.g., performance,
|
||||
security, migration cost, team learning curve)"
|
||||
*Skip if the question is narrow enough that dimensions are obvious.*
|
||||
|
||||
3. **Prior knowledge:** "What do you already know about this topic? What have you
|
||||
tried or ruled out?"
|
||||
*Always useful — prevents redundant research.*
|
||||
|
||||
4. **Constraints:** "Are there constraints that should guide the research?
|
||||
(e.g., must be open-source, must support X, budget limitations)"
|
||||
*Skip if no constraints are apparent.*
|
||||
|
||||
**Rules:**
|
||||
- If the user says "just research it", "skip", or similar — stop interviewing.
|
||||
Use the research question as-is.
|
||||
- For `--quick` mode: ask 1-2 questions maximum.
|
||||
- Never ask about things you can discover from the codebase.
|
||||
|
||||
### Determine research dimensions
|
||||
|
||||
Based on the interview, identify 3-8 research dimensions. These are the facets
|
||||
of the question that will be investigated in parallel. Examples:
|
||||
|
||||
- "Should we use Redis?" → dimensions: performance, reliability, operational
|
||||
complexity, security, cost, team familiarity
|
||||
- "How should we handle auth?" → dimensions: standards compliance, implementation
|
||||
complexity, library ecosystem, security posture, scalability
|
||||
|
||||
Report dimensions:
|
||||
```
|
||||
Research dimensions identified:
|
||||
1. {Dimension 1}
|
||||
2. {Dimension 2}
|
||||
...
|
||||
```
|
||||
|
||||
## Phase 3 — Background transition
|
||||
|
||||
**If execution = foreground or mode = quick:** Skip this phase. Continue inline.
|
||||
|
||||
**If execution = background (default):**
|
||||
|
||||
Generate a slug from the research question (first 3-4 meaningful words, lowercase,
|
||||
hyphens).
|
||||
|
||||
Launch the **research-orchestrator** agent with this prompt:
|
||||
|
||||
```
|
||||
Research question: {question}
|
||||
Dimensions: {list of dimensions from interview}
|
||||
Mode: {default | quick}
|
||||
Scope: {both | local | external}
|
||||
Brief destination: .claude/research/ultraresearch-{YYYY-MM-DD}-{slug}.md
|
||||
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}
|
||||
Dimensions: {N} identified
|
||||
Scope: {both | local | external}
|
||||
Brief: .claude/research/ultraresearch-{date}-{slug}.md
|
||||
|
||||
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.
|
||||
The research-orchestrator handles Phases 4 through 8 autonomously.
|
||||
|
||||
---
|
||||
|
||||
**Everything below this line runs either in foreground mode, quick mode, or
|
||||
inside the background agent. The instructions are identical regardless of context.**
|
||||
|
||||
---
|
||||
|
||||
## Phase 3.5 — Quick mode (inline research)
|
||||
|
||||
**Skip this phase entirely unless mode = quick.**
|
||||
|
||||
For quick mode, do NOT launch an agent swarm. Instead, do lightweight research
|
||||
directly using available tools.
|
||||
|
||||
### Quick local research (if scope includes local)
|
||||
|
||||
- `Glob` for files matching key terms from the research question (up to 3 patterns)
|
||||
- `Grep` for relevant definitions, patterns, or usage (up to 5 patterns)
|
||||
- Read the 2-3 most relevant files found
|
||||
|
||||
### Quick external research (if scope includes external)
|
||||
|
||||
Use available search tools directly (in this priority order):
|
||||
1. `mcp__tavily__tavily_search` — if available, use for 2-3 targeted queries
|
||||
2. `WebSearch` — fallback for 2-3 targeted queries
|
||||
3. `WebFetch` — fetch 1-2 specific pages if URLs were found
|
||||
|
||||
### Quick synthesis
|
||||
|
||||
Synthesize findings inline. Write a lightweight research brief to the destination
|
||||
path, following the research-brief-template but with shorter sections and fewer
|
||||
dimensions.
|
||||
|
||||
Skip to Phase 8 (stats tracking) after writing the brief.
|
||||
|
||||
## Phase 4 — Parallel research (agent swarm)
|
||||
|
||||
**Determine which agents to launch based on scope:**
|
||||
|
||||
### Local agents (scope = both or local)
|
||||
|
||||
Reuse existing plugin agents with research-focused prompts. These agents are
|
||||
designed for planning, but work equally well for research when prompted differently.
|
||||
|
||||
| Agent | Purpose in research context |
|
||||
|-------|----------------------------|
|
||||
| `architecture-mapper` | How the architecture relates to the research question |
|
||||
| `dependency-tracer` | Dependencies and integrations relevant to the topic |
|
||||
| `task-finder` | Existing code that relates to the research question |
|
||||
| `git-historian` | Recent changes and ownership relevant to the topic |
|
||||
| `convention-scanner` | Coding patterns relevant to evaluating options |
|
||||
|
||||
For each local agent, prompt with the research question, NOT a task description:
|
||||
|
||||
- architecture-mapper: "Analyze the architecture relevant to this research question:
|
||||
{question}. Focus on how {topic} relates to current patterns and constraints."
|
||||
- dependency-tracer: "Trace dependencies relevant to this research question: {question}.
|
||||
Identify which modules would be affected by {topic}."
|
||||
- task-finder: "Find existing code relevant to this research question: {question}.
|
||||
Look for prior implementations, patterns, or utilities related to {topic}."
|
||||
- git-historian: "Analyze git history relevant to this research question: {question}.
|
||||
Who owns the relevant code? What has changed recently in related areas?"
|
||||
- convention-scanner: "Discover coding conventions relevant to evaluating {question}.
|
||||
What patterns would a solution need to follow?"
|
||||
|
||||
### External agents (scope = both or external)
|
||||
|
||||
Launch the new research-specialized agents:
|
||||
|
||||
| Agent | Purpose |
|
||||
|-------|---------|
|
||||
| `docs-researcher` | Official documentation, RFCs, vendor docs |
|
||||
| `community-researcher` | Real-world experience, issues, blog posts |
|
||||
| `security-researcher` | CVEs, audit history, supply chain risks |
|
||||
| `contrarian-researcher` | Counter-evidence, overlooked alternatives |
|
||||
|
||||
For each external agent, pass: the research question, specific dimensions to
|
||||
investigate, and any context from the interview.
|
||||
|
||||
### Bridge agent (scope = both or external, if enabled)
|
||||
|
||||
Launch `gemini-bridge` with the research question. Do NOT include findings from
|
||||
other agents — the value of Gemini is independence.
|
||||
|
||||
### Launch rules
|
||||
|
||||
- Launch ALL selected agents **in parallel** in a single message
|
||||
- Use model: "sonnet" for all sub-agents (the orchestrator runs on Opus)
|
||||
- Scale maxTurns by codebase size for local agents (same as ultraplan):
|
||||
small = halved, medium/large = default
|
||||
- convention-scanner: medium+ codebases only (50+ files)
|
||||
|
||||
## Phase 5 — Targeted follow-ups
|
||||
|
||||
Review all agent results. Identify knowledge gaps — areas where findings are
|
||||
thin, contradictory, or missing.
|
||||
|
||||
For each significant gap, launch a targeted follow-up agent (model: "sonnet")
|
||||
with a narrow, specific brief. Maximum 2 follow-ups.
|
||||
|
||||
If no gaps exist, skip: "Initial research sufficient — no follow-ups needed."
|
||||
|
||||
## Phase 6 — Triangulation
|
||||
|
||||
This is the KEY phase that makes ultraresearch more than aggregation.
|
||||
|
||||
For each research dimension:
|
||||
|
||||
1. **Collect** — gather relevant findings from local AND external agents
|
||||
2. **Compare** — do local findings agree with external findings?
|
||||
3. **Flag contradictions** — where they disagree, present both sides with evidence
|
||||
4. **Cross-validate** — use codebase facts to validate external claims:
|
||||
- External says "library X is fast" → local shows the codebase already uses
|
||||
a similar pattern that could benchmark against
|
||||
- External says "pattern Y is best practice" → local shows the codebase uses
|
||||
pattern Z which conflicts
|
||||
5. **Rate confidence** per dimension:
|
||||
- **high** — multiple authoritative sources agree, local evidence confirms
|
||||
- **medium** — good sources but limited cross-validation
|
||||
- **low** — single source, limited evidence
|
||||
- **contradictory** — credible sources actively disagree
|
||||
|
||||
Compute overall confidence as a weighted average (0.0-1.0) based on dimension
|
||||
confidence levels and their relative importance.
|
||||
|
||||
## Phase 7 — Synthesis and brief writing
|
||||
|
||||
Read the research brief template:
|
||||
@${CLAUDE_PLUGIN_ROOT}/templates/research-brief-template.md
|
||||
|
||||
Write the research brief following the template. Key rules:
|
||||
|
||||
1. **Executive Summary** — 3 sentences. Answer, confidence, key caveat.
|
||||
2. **Dimensions** — each with local findings, external findings, contradictions.
|
||||
3. **Synthesis** — NOT a summary. NEW insights from triangulation.
|
||||
4. **Open Questions** — what remains unresolved and why.
|
||||
5. **Recommendation** — only if decision-relevant. Omit for exploratory research.
|
||||
6. **Sources** — every claim traced to URL or codebase path.
|
||||
|
||||
Generate the slug from the research question (first 3-4 meaningful words).
|
||||
Write the brief to: `.claude/research/ultraresearch-{YYYY-MM-DD}-{slug}.md`
|
||||
Create the `.claude/research/` directory if needed.
|
||||
|
||||
## Phase 8 — Present and track
|
||||
|
||||
Present a summary to the user:
|
||||
|
||||
```
|
||||
## Ultraresearch Complete
|
||||
|
||||
**Question:** {research question}
|
||||
**Mode:** {default | quick}, Scope: {both | local | external}
|
||||
**Brief:** .claude/research/ultraresearch-{date}-{slug}.md
|
||||
**Confidence:** {overall confidence 0.0-1.0}
|
||||
**Dimensions:** {N} researched
|
||||
**Agents:** {N} local + {N} external + {gemini: used | unavailable | skipped}
|
||||
|
||||
### Key Findings
|
||||
- {Finding 1}
|
||||
- {Finding 2}
|
||||
- {Finding 3}
|
||||
|
||||
### Contradictions Found
|
||||
- {Contradiction 1, or "None — findings are consistent across sources."}
|
||||
|
||||
### Open Questions
|
||||
- {Question 1, or "None — all dimensions adequately covered."}
|
||||
|
||||
You can:
|
||||
- Read the full brief at {brief path}
|
||||
- Feed into planning: `/ultraplan-local --research {brief path} <task>`
|
||||
- Ask follow-up questions about specific findings
|
||||
```
|
||||
|
||||
### Stats tracking
|
||||
|
||||
Write a session record to `${CLAUDE_PLUGIN_DATA}/ultraresearch-stats.jsonl`
|
||||
(create the file if it does not exist).
|
||||
|
||||
Record format (one JSON line):
|
||||
```json
|
||||
{
|
||||
"ts": "{ISO-8601 timestamp}",
|
||||
"question": "{research question (first 100 chars)}",
|
||||
"mode": "{default|quick}",
|
||||
"scope": "{both|local|external}",
|
||||
"slug": "{brief slug}",
|
||||
"dimensions": {N},
|
||||
"agents_local": {N},
|
||||
"agents_external": {N},
|
||||
"gemini_used": {true|false},
|
||||
"confidence": {0.0-1.0},
|
||||
"contradictions": {N},
|
||||
"open_questions": {N}
|
||||
}
|
||||
```
|
||||
|
||||
If `${CLAUDE_PLUGIN_DATA}` is not set or not writable, skip tracking silently.
|
||||
|
||||
## Hard rules
|
||||
|
||||
- **No planning:** This command produces research briefs, not implementation plans.
|
||||
If the user asks to plan, direct them to `/ultraplan-local --research <brief>`.
|
||||
- **Sources required:** Every claim must cite a source. No unsourced findings.
|
||||
- **Independence:** Do not pre-bias external agents with local findings or vice versa.
|
||||
Triangulate AFTER independent research.
|
||||
- **Graceful degradation:** If MCP tools are unavailable (Tavily, Gemini, MS Learn),
|
||||
proceed with available tools and note limitations in brief metadata.
|
||||
- **Cost:** Sonnet for all sub-agents. Opus only in the main command/orchestrator.
|
||||
- **Privacy:** Never log secrets, tokens, or credentials.
|
||||
- **Honesty:** If the question is trivially answerable, say so. Don't inflate research.
|
||||
- **Scope of codebase:** Only analyze the current working directory for local research.
|
||||
- **Research transparency:** Clearly distinguish local findings from external findings.
|
||||
Never blend them without attribution.
|
||||
Loading…
Add table
Add a link
Reference in a new issue