open/voyage
1
0
Fork 0
Code Issues Releases 1 Activity

feat(ultraplan-local): v1.6.0 — /ultraresearch-local deep research command

Browse source 
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 2026-04-08 08:58:35 +02:00
commit 4679f4556d
38 changed files with 6708 additions and 0 deletions
Download patch file Download diff file Expand all files Collapse all files

144
templates/headless-launch-template.md Normal file
View file

@ -0,0 +1,144 @@
# Headless Launch Script Template
This template is used by the session-decomposer agent to generate a launch script
for headless execution of decomposed sessions.
## Template
```bash
#!/usr/bin/env bash
# Headless launch script — generated by ultraplan-local
# Master plan: {plan_path}
# Generated: {date}
# Sessions: {total_sessions} ({parallel_count} parallel, {sequential_count} sequential)
set -euo pipefail
# Prevent accidental API billing — remove this line if you intend to use API credits
unset ANTHROPIC_API_KEY
REPO_ROOT="$(git rev-parse --show-toplevel)"
PLAN_DIR="{session_dir}"
LOG_DIR="{session_dir}/logs"
WORKTREE_BASE="{session_dir}/worktrees"
mkdir -p "$LOG_DIR" "$WORKTREE_BASE"
# Cleanup trap — always remove worktrees on exit (success or failure)
cleanup_worktrees() {
echo ""
echo "=== Cleaning up worktrees ==="
cd "$REPO_ROOT"
for wt in "$WORKTREE_BASE"/session-*; do
[ -d "$wt" ] && git worktree remove "$wt" --force 2>/dev/null && echo "Removed: $wt"
done
git worktree prune
git branch --list "ultraplan/{slug}/*" | while read b; do
git branch -D "$b" 2>/dev/null
done
rmdir "$WORKTREE_BASE" 2>/dev/null
echo "Cleanup complete."
}
trap cleanup_worktrees EXIT
# Pre-flight: verify clean working tree
if [ -n "$(git status --porcelain)" ]; then
echo "ERROR: Working tree is not clean. Commit or stash changes before parallel execution."
git status --short
exit 1
fi
echo "=== Ultraplan Headless Execution (Worktree-Isolated) ==="
echo "Plan: {plan_path}"
echo "Sessions: {total_sessions}"
echo "Repo root: $REPO_ROOT"
echo ""
# --- Wave {N}: Parallel sessions (no dependencies) ---
echo "--- Wave {N}: {description} ---"
{# For each parallel session in this wave, create worktree: }
git worktree add -b "ultraplan/{slug}/session-{n}" "$WORKTREE_BASE/session-{n}" HEAD
echo "Worktree created: session-{n} (branch: ultraplan/{slug}/session-{n})"
{# Launch session in its worktree: }
cd "$WORKTREE_BASE/session-{n}" && claude -p "$(cat "$PLAN_DIR/session-{n}-{slug}.md")" \
--dangerously-skip-permissions \
> "$LOG_DIR/session-{n}.log" 2>&1 &
PID_{n}=$!
cd "$REPO_ROOT"
echo "Started session {n}: {title} (PID $PID_{n})"
{# After all parallel sessions in this wave: }
echo "Waiting for Wave {N} to complete..."
wait $PID_{n1} $PID_{n2}
echo "Wave {N} complete."
echo ""
# --- Merge wave results (sequential) ---
echo "--- Merging Wave {N} ---"
cd "$REPO_ROOT"
{# For each session in the wave, merge its branch: }
git merge --no-ff "ultraplan/{slug}/session-{n}" \
-m "merge: ultraplan session {n} — {title}"
if [ $? -ne 0 ]; then
echo "MERGE CONFLICT: session {n}. Conflicting files:"
git diff --name-only --diff-filter=U
git merge --abort
echo "Aborting. Earlier sessions in this wave are already merged."
exit 1
fi
git worktree remove "$WORKTREE_BASE/session-{n}" --force
git branch -d "ultraplan/{slug}/session-{n}"
echo "Merged and cleaned: session {n}"
git worktree prune
# --- Verify wave results ---
echo "--- Verifying Wave {N} ---"
{# For each session in the wave, run its exit condition commands }
{verify_commands}
# --- Wave {N+1}: Sequential sessions (depends on previous wave) ---
{# Repeat wave pattern for dependent sessions }
echo ""
echo "=== All sessions complete ==="
echo "Review logs in $LOG_DIR/"
echo "Run final verification: {final_verify_command}"
```
## Rules for the session-decomposer
When generating a launch script from this template:
1. **Group sessions into waves** by dependency. Sessions with no dependencies
or whose dependencies are all in earlier waves can run in the same wave.
2. **Each wave waits for completion** before the next wave starts.
3. **Verification runs after each wave** — if verification fails, the script
stops and reports which session failed.
4. **Log each session** to a separate file for debugging.
5. **Use `claude -p`** with the session spec file as the prompt.
6. **Use `--dangerously-skip-permissions`** rather than `--allowedTools` — the
executor needs flexible tool access and enumerating every tool is fragile.
7. **Final verification** at the end runs the master plan's verification section.
8. **Never include secrets** in the generated script.
9. **Wave verification must be independent.** After each wave completes, run
verification commands fresh via Bash — never parse session log files as proof
of success. Log files contain executor self-reporting, not ground truth. The
command's exit code is the only authoritative verification signal.
10. **Billing preamble.** Prepend `unset ANTHROPIC_API_KEY` with a comment at
the top of the script to prevent accidental API billing. Users who intend
to use API credits can remove this line.
11. **Worktree isolation is mandatory.** Every parallel wave MUST use git
worktrees. Each session gets its own worktree and branch. Never launch
parallel `claude -p` sessions in the same working directory.
12. **Cleanup trap on EXIT.** The generated script MUST include a `trap` on
EXIT that removes all worktrees (`git worktree remove --force`) and prunes
branches, even if the script fails or is interrupted.
13. **Sequential merge after each wave.** After all sessions in a wave complete,
merge their branches back to the main branch one at a time. Abort on merge
conflict — do not force-resolve.
14. **Clean working tree before worktrees.** Add a `git status --porcelain`
check at the top of the script. Fail if the working tree is dirty.
15. **Absolute paths for logs.** Log file paths must be absolute (resolved from
`$REPO_ROOT`), not relative to any worktree.

195
templates/plan-template.md Normal file
View file

@ -0,0 +1,195 @@
# {Task Title}
> **Plan quality: {grade}** ({score}/100) — {APPROVE | APPROVE_WITH_NOTES | REVISE | REPLAN}
>
> Generated by ultraplan-local v{version} on {YYYY-MM-DD}
## Context
Why this change is needed. The problem or need it addresses, what prompted it,
and the intended outcome. Reference the spec file if one was used.
## Architecture Diagram
```mermaid
graph TD
subgraph "Changes in this plan"
%% C4-style component diagram showing what the plan touches
%% Highlight modified components, new components, and connections
end
```
*Replace with actual Mermaid diagram showing the components this plan modifies,
their relationships, and the data flow between them.*
## Codebase Analysis
- **Tech stack:** {languages, frameworks, build tools}
- **Key patterns:** {architecture patterns, conventions observed}
- **Relevant files:** {paths to files that will be read or modified}
- **Reusable code:** {existing functions, utilities, abstractions to leverage}
- **External tech (researched):** {technologies that were looked up via research-scout}
- **Recent git activity:** {relevant recent commits, active branches, code ownership}
## Research Sources
*Omit this section when no external research was conducted.*
| Technology | Source | Key Findings | Confidence |
|-----------|--------|--------------|------------|
| {name} | {URL} | {summary} | {high/med/low} |
## Implementation Plan
Each step targets 1–2 files and one focused change. Steps follow TDD structure
when the project has tests.
### Step 1: {description}
- **Files:** `path/to/file.ts`
- **Changes:** {exactly what to modify — no placeholders, no "update as needed"}
- **Reuses:** {existing function/pattern from codebase, with file path}
- **Test first:**
- File: `path/to/test.ts` *(existing | new)*
- Verifies: {what the test checks}
- Pattern: `path/to/existing-test.ts` *(follow this style)*
- **Verify:** `{exact command}` → expected: `{output}`
- **On failure:** {revert | retry | skip | escalate} — {specific instructions}
- **Checkpoint:** `git commit -m "{conventional commit message}"`
### Step 2: {description}
- **Files:** `path/to/file.ts`
- **Changes:** {exactly what to modify}
- **Reuses:** {existing function/pattern}
- **Test first:**
- File: `path/to/test.ts` *(existing | new)*
- Verifies: {what the test checks}
- Pattern: `path/to/existing-test.ts`
- **Verify:** `{exact command}` → expected: `{output}`
- **On failure:** {revert | retry | skip | escalate} — {specific instructions}
- **Checkpoint:** `git commit -m "{conventional commit message}"`
*For projects without tests: omit "Test first" and keep "Verify" with a
concrete command (e.g., run the app, check output, curl an endpoint).*
### Failure recovery rules
- **On failure: revert** — undo this step's changes (`git checkout -- {files}`), do NOT proceed
- **On failure: retry** — attempt once more with the alternative approach described, then revert if still failing
- **On failure: skip** — this step is non-critical; continue to next step and note the skip
- **On failure: escalate** — stop execution entirely; the issue requires human judgment
- **Checkpoint** — after each step succeeds, commit changes so subsequent failures cannot corrupt completed work
## Alternatives Considered
| Approach | Pros | Cons | Why rejected |
|----------|------|------|--------------|
| {name} | ... | ... | ... |
## Test Strategy
- **Framework:** {test framework and runner}
- **Existing patterns:** {how tests are structured in this codebase}
- **New tests in this plan:** {N} tests across {N} steps
### Tests to write
| Type | File | Verifies | Model test |
|------|------|----------|------------|
| Unit | `path/to/test` | {what it tests} | `path/to/existing-test` |
*For projects without tests: describe manual verification approach instead.*
## Risks and Mitigations
| Priority | Risk | Location | Impact | Mitigation |
|----------|------|----------|--------|------------|
| {Critical/High/Medium/Low} | {description} | `file:line` | {what happens} | {how to handle} |
## Assumptions
*Things the planner could not verify from codebase or research. Each assumption
is a risk — review before executing.*
| # | Assumption | Why unverifiable | Impact if wrong |
|---|-----------|-----------------|-----------------|
| 1 | {what we assumed} | {why we couldn't check} | {what breaks} |
*If this list has 3+ items, the plan may need additional investigation
before execution.*
## Verification
End-to-end checks that prove the plan was implemented correctly.
- [ ] `{exact command}` → expected: `{exact output or behavior}`
- [ ] `{exact command}` → expected: `{exact output or behavior}`
## Estimated Scope
- **Files to modify:** {N}
- **Files to create:** {N}
- **Complexity:** {low | medium | high}
## Execution Strategy
*Include this section when the plan has more than 5 implementation steps.
Omit for small plans (≤ 5 steps) — ultraexecute will run them sequentially
in a single session.*
*The execution strategy groups steps into sessions and organizes sessions
into waves. Sessions in the same wave can run in parallel. Sessions in
later waves depend on earlier waves completing first.*
### Session 1: {title}
- **Steps:** {step numbers, e.g., 1, 2, 3}
- **Wave:** {wave number}
- **Depends on:** {session numbers, or "none"}
- **Scope fence:**
- Touch: {files this session may modify}
- Never touch: {files reserved for other sessions}
### Session 2: {title}
- **Steps:** {step numbers}
- **Wave:** {wave number}
- **Depends on:** {session numbers, or "none"}
- **Scope fence:**
- Touch: {files}
- Never touch: {files}
### Execution Order
- **Wave 1:** {session list} (parallel)
- **Wave 2:** {session list} (after Wave 1)
### Grouping rules applied
- Steps sharing files → same session
- Steps in independent modules → separate sessions (parallelizable)
- 3–5 steps per session (target)
- Sessions ordered by dependency, waves by independence
## Plan Quality Score
| Dimension | Weight | Score | Notes |
|-----------|--------|-------|-------|
| Structural integrity | 0.15 | {0–100} | {step ordering, dependencies} |
| Step quality | 0.20 | {0–100} | {granularity, specificity, TDD} |
| Coverage completeness | 0.20 | {0–100} | {spec → steps, no gaps} |
| Specification quality | 0.15 | {0–100} | {no placeholders, clear criteria} |
| Risk & pre-mortem | 0.15 | {0–100} | {failure modes addressed} |
| Headless readiness | 0.15 | {0–100} | {On failure + Checkpoint per step} |
| **Weighted total** | **1.00** | **{score}** | **Grade: {A/B/C/D}** |
**Adversarial review:**
- **Plan critic:** {verdict — findings count by severity, key issues}
- **Scope guardian:** {verdict — ALIGNED / CREEP / GAP / MIXED}
## Revisions
*Added by adversarial review. Omit if no revisions were needed.*
| # | Finding | Severity | Resolution |
|---|---------|----------|------------|
| 1 | {what was wrong} | {blocker/major/minor} | {how it was fixed} |

122
templates/research-brief-template.md Normal file
View file

@ -0,0 +1,122 @@
---
type: ultraresearch-brief
created: {YYYY-MM-DD}
question: "{research question}"
confidence: {0.0-1.0}
dimensions: {N}
mcp_servers_used: [{list}]
local_agents_used: [{list}]
external_agents_used: [{list}]
---
# {Research Question Title}
> Generated by ultraresearch-local v{version} on {YYYY-MM-DD}
## Research Question
{The full research question as clarified during interview.}
## Executive Summary
{3 sentences maximum. The answer, the confidence level, and the key caveat.}
## Dimensions
*Each dimension represents one facet of the research question, explored by both
local and external agents. Confidence is rated per dimension.*
### {Dimension Name} -- Confidence: {high | medium | low | contradictory}
**Local findings:**
- {Finding with source citation (file path or agent name)}
**External findings:**
- {Finding with source citation (URL)}
**Contradictions:**
- {If local and external disagree, explain both sides with evidence.
Omit this sub-section if no contradictions exist for this dimension.}
*Repeat for each dimension.*
## Local Context
*Findings from codebase analysis agents. Omit sub-sections where no relevant
findings exist.*
### Architecture
{Architecture patterns, tech stack, relevant components from architecture-mapper}
### Dependencies
{Import chains, data flow, external integrations from dependency-tracer}
### Conventions
{Coding patterns, naming, test conventions from convention-scanner}
### History
{Recent changes, code ownership, hot files from git-historian}
## External Knowledge
*Findings from external research agents. Omit sub-sections where no relevant
findings exist.*
### Best Practice
{Official documentation, recommended patterns from docs-researcher}
### Alternatives
{Other approaches, competing solutions from community-researcher + contrarian-researcher}
### Security
{CVEs, audit history, supply chain risks from security-researcher}
### Known Issues
{Common pitfalls, gotchas, real-world problems from community-researcher}
## Gemini Second Opinion
*Independent research result from Gemini Deep Research. Provides a second
perspective for triangulation. Omit this section if gemini-bridge was not used
or was unavailable.*
{Gemini findings reformatted into key findings, sources cited, and areas of
agreement/disagreement with other agents.}
## Synthesis
*Cross-cutting insights that emerge from combining local and external knowledge.
This is NOT a summary of the sections above. It is NEW insight from triangulation
-- things that only become visible when local context meets external knowledge.*
{Example: "The codebase uses pattern X (local), but best practice has shifted to
pattern Y (external). However, our dependency on Z (local) makes a direct migration
impractical -- a hybrid approach using Y for new code while maintaining X for
existing modules is the pragmatic path."}
## Open Questions
*Things that remain unresolved after research. Each is a candidate for follow-up
research or an assumption to carry forward.*
- {Question 1 -- why it remains open}
- {Question 2 -- why it remains open}
## Recommendation
*If the research was decision-relevant, provide a concrete recommendation with
reasoning. If the research was exploratory (understanding, not deciding), omit
this section entirely.*
{Recommendation with rationale, citing specific findings from above.}
## Sources
| # | Source | Type | Quality | Used in |
|---|--------|------|---------|---------|
| 1 | {URL or codebase path} | {official / community / codebase / gemini} | {high / medium / low} | {dimension name} |
*Quality assessment:*
- **high** — official documentation, verified codebase analysis, peer-reviewed
- **medium** — reputable community source, well-maintained blog, established project
- **low** — unverified, outdated (>1 year), single-source claim, opinion piece

65
templates/session-spec-template.md Normal file
View file

@ -0,0 +1,65 @@
# Session {N}: {title}
> From master plan: {plan file path}
> Session {N} of {total sessions}
## Context
{Why this session exists. What it accomplishes within the larger plan.
Include enough background that an executor with no prior context can understand
the purpose and make judgment calls.}
## Dependencies
- **Depends on:** {Session M | "none — can run in parallel"}
- **Blocks:** {Session P | "none"}
- **Entry condition:** {what must be true before this session starts — e.g., "Session 2 committed and tests pass"}
## Scope Fence
- **Touch:** {explicit list of files this session may create or modify}
- **Never touch:** {files that belong to other sessions — hard boundary}
## Steps
### Step 1: {description}
- **Files:** `{path}`
- **Changes:** {exactly what to modify}
- **Reuses:** {existing function/pattern, with file path}
- **Test first:** {test file, what it verifies, pattern to follow}
- **Verify:** `{exact command}` → expected: `{output}`
- **On failure:** {revert | retry | skip | escalate} — {specific instructions}
- **Checkpoint:** `git commit -m "{message}"`
### Step 2: {description}
{same structure as Step 1}
## Exit Condition
All of these must pass before this session is considered complete:
- [ ] `{verification command}` → expected: `{output}`
- [ ] `{verification command}` → expected: `{output}`
- [ ] All changes committed with descriptive messages
- [ ] No uncommitted changes remain (`git status` clean)
## Failure Handling
- If ANY step fails after retry: **stop execution**. Do NOT proceed to later steps.
- Commit whatever was completed successfully before stopping.
- Report which step failed, the error message, and what was attempted.
## Handoff State
{What the next session (or final verification) needs to know about this session's
output. Include: new files created, exports added, configuration changed, APIs
introduced. This section bridges sessions — it's the "baton" in a relay race.}
## Metadata
- **Master plan:** `{plan file path}`
- **Steps from plan:** {step N}–{step M}
- **Estimated complexity:** {low | medium | high}
- **Model recommendation:** {opus | sonnet} — {rationale}

64
templates/spec-template.md Normal file
View file

@ -0,0 +1,64 @@
# Task: {title}
## Goal
What success looks like. One clear paragraph.
## Non-Goals
What is explicitly out of scope for this task.
- {non-goal 1}
- {non-goal 2}
## Constraints
Technical, time, or resource limitations.
- {constraint 1}
- {constraint 2}
## Preferences
Preferred patterns, frameworks, libraries, or approaches.
- {preference 1}
- {preference 2}
## Non-Functional Requirements
Performance, security, accessibility, scalability, or other quality attributes.
- {NFR 1}
- {NFR 2}
## Success Criteria
Falsifiable conditions that define "done". Each must be checkable by running a
command or observing a specific system behavior.
- {criterion — e.g., "All existing tests pass: `npm test` exits 0"}
- {criterion — e.g., "New endpoint returns 200: `curl -s localhost:3000/api/health | jq .status` → "ok""}
- {criterion — e.g., "No TypeScript errors: `npx tsc --noEmit` exits 0"}
Do NOT write vague criteria:
- "It should work" (not testable)
- "The feature is implemented" (not falsifiable)
- "Performance is acceptable" (no baseline given)
## Prior Attempts
What has been tried before and what happened. Leave blank if this is a fresh task.
## Open Questions
Unresolved items that may affect the plan. Flag these as assumptions if proceeding
without answers.
- {question 1}
## Metadata
- **Created:** {YYYY-MM-DD}
- **Mode:** {interview | manual}
- **Source:** {ultraplan interview | user-provided}