338 lines
13 KiB
Markdown
338 lines
13 KiB
Markdown
# ultraplan-local Roadmap
|
|
|
|
## Vision
|
|
|
|
ultraplan-local is a **deep planning specialist**. It does one thing: creates
|
|
plans so thorough they can be implemented without questions.
|
|
|
|
**The plan is the product.** Everything else exists to make the plan better.
|
|
|
|
### What we ARE
|
|
- The most thorough planning process available as a Claude Code plugin
|
|
- Autonomous: gathers all information itself, needs no human help along the way
|
|
- Plans that stand on their own — implementable by someone who has never seen the codebase
|
|
|
|
### What we are NOT
|
|
- Not a project engine (that's Harness)
|
|
- Not a behavior framework (that's Superpowers)
|
|
- Not an execution engine, team manager, or issue tracker
|
|
- Not optimized for infrastructure-as-code (Terraform, Helm, Pulumi) — the agents
|
|
are designed for application code. IaC projects get a result, but agents like
|
|
architecture-mapper and test-strategist provide less value there.
|
|
|
|
### Quality Goals
|
|
A plan from ultraplan-local should:
|
|
1. Be implementable without asking questions
|
|
2. Have testable verification criteria for each step
|
|
3. Contain no placeholders, TBDs, or vague instructions
|
|
4. Include TDD structure where the project uses tests
|
|
5. Have a quantitative assessment of its own quality (score A-D)
|
|
|
|
---
|
|
|
|
## v0.4.0 — Information-Complete and Plan Quality (DONE)
|
|
|
|
Completed 2026-04-06. See [CHANGELOG.md](../CHANGELOG.md) for details.
|
|
|
|
**Delivered:**
|
|
- 3 new agents: task-finder, git-historian, spec-reviewer
|
|
- All agents run for all codebase sizes (turns scale, not agent count)
|
|
- No-placeholder rule in plan-critic (TBD/TODO = blocker)
|
|
- Quantitative plan scoring (A-D grades, 5 weighted dimensions)
|
|
- `[ASSUMPTION]` marking with threshold warning (>3 = warning)
|
|
- Spec-reviewer as new phase before exploration
|
|
|
|
---
|
|
|
|
## v1.0.0 — Production-Ready Plugin
|
|
|
|
Two pillars: (1) features that close real user friction, and (2) repo infrastructure
|
|
for a credible open-source project.
|
|
|
|
Each feature item has a **Rationale** tracing back to a role simulation
|
|
or research finding.
|
|
|
|
### Pillar 1: Plugin Features
|
|
|
|
#### 1. `--quick` mode
|
|
|
|
New mode that skips the exploration phase. Plans directly from interview plus
|
|
minimal file checking (Glob/Grep to verify file paths mentioned in the conversation).
|
|
|
|
```
|
|
/ultraplan-local --quick Add rate limiting to the API
|
|
```
|
|
|
|
Flow: interview → spec → plan (without agent swarm) → adversarial review → done.
|
|
|
|
Useful when:
|
|
- The developer knows the code well and needs structure, not mapping
|
|
- The codebase is small and simple
|
|
- The time/cost of full exploration isn't worth it
|
|
|
|
**Rationale:** Solo developer simulation revealed that 6 agents on 12 files feels
|
|
like overkill when the developer already knows the code. git-historian provides zero
|
|
value for solo projects with short history.
|
|
|
|
**Changes:** `commands/ultraplan-local.md` (new mode parsing), `agents/planning-orchestrator.md`
|
|
(new quick path that skips Phase 2).
|
|
|
|
#### 2. `--export pr` for shareable plan output
|
|
|
|
Generates a PR-ready summary from an existing plan:
|
|
|
|
```
|
|
/ultraplan-local --export pr .claude/plans/ultraplan-2026-04-06-rate-limiting.md
|
|
```
|
|
|
|
Output: a markdown block formatted as a PR description (Summary, Changes, Test plan)
|
|
that can be copied directly into a PR.
|
|
|
|
Possible export formats:
|
|
- `pr` — PR description with summary and test plan
|
|
- `issue` — issue comment with plan summary
|
|
- `markdown` — clean plan without internal metadata (score, revisions)
|
|
|
|
**Rationale:** OSS contributor simulation showed that the plan is a local file with no
|
|
easy way to share. The user wanted to share with a maintainer for approval before
|
|
implementation.
|
|
|
|
**Changes:** `commands/ultraplan-local.md` (new `--export` mode parsing and output format).
|
|
|
|
#### 3. task-finder categorization
|
|
|
|
Update the task-finder agent to categorize findings into three levels:
|
|
|
|
| Category | Meaning | Example |
|
|
|----------|---------|---------|
|
|
| **Must-change** | Files that must be modified to implement the task | `src/auth/middleware.ts` |
|
|
| **Must-respect** | Interfaces and contracts that must be honored | `src/types/auth.d.ts` |
|
|
| **Reference** | Useful context, but no changes needed | `src/utils/jwt.ts` |
|
|
|
|
**Rationale:** Senior engineer simulation (2000+ files) revealed that task-finder
|
|
reported 47 files in a flat list. Without prioritization, it's useless for
|
|
planning.
|
|
|
|
**Changes:** `agents/task-finder.md` (updated output format and instructions).
|
|
|
|
#### 4. Adaptive interview depth
|
|
|
|
The interview adapts to the user's response depth:
|
|
|
|
- **Detailed answers** (>2 sentences, technical language): ask fewer, more targeted questions.
|
|
Assume the user is senior and knows what they want.
|
|
- **Short/uncertain answers** (<1 sentence, "don't know"): ask simpler questions, offer
|
|
alternatives instead of open-ended questions. For bugs: focus on reproduction
|
|
("What do you see?" / "What did you expect?") instead of technical requirements.
|
|
|
|
**Rationale:** Junior developer simulation showed that the interview assumes the user
|
|
understands the problem. The junior didn't know enough to answer open-ended questions well,
|
|
resulting in a thin spec and a C-grade plan.
|
|
|
|
**Changes:** `commands/ultraplan-local.md` (updated Phase 2 interview instructions).
|
|
|
|
#### 5. Complete `plugin.json` metadata
|
|
|
|
Add missing fields for marketplace readiness:
|
|
|
|
```json
|
|
{
|
|
"name": "ultraplan-local",
|
|
"version": "1.0.0",
|
|
"description": "...",
|
|
"author": "Kjell Tore Guttormsen",
|
|
"homepage": "https://git.fromaitochitta.com/open/ultraplan-local",
|
|
"repository": "https://git.fromaitochitta.com/open/ultraplan-local.git",
|
|
"license": "MIT",
|
|
"keywords": ["planning", "implementation", "agents", "adversarial-review"]
|
|
}
|
|
```
|
|
|
|
**Rationale:** Plugin ecosystem research showed that `plugin.json` is missing 5 of
|
|
the fields that marketplace and discovery tools use. Highest leverage gap for
|
|
distribution.
|
|
|
|
**Changes:** `.claude-plugin/plugin.json`.
|
|
|
|
#### 6. Documented IaC limitation in README
|
|
|
|
Add a section in README under "When to use" that explicitly states that
|
|
ultraplan-local is designed for application code, and that IaC projects
|
|
(Terraform, Helm, Pulumi, CDK) get reduced value from the exploration agents.
|
|
|
|
**Rationale:** DevOps simulation showed that architecture-mapper looks for
|
|
src/lib/controllers (irrelevant for Terraform), test-strategist doesn't know
|
|
infra testing tools, and the plan misses Terraform-specific steps like state locking.
|
|
|
|
**Changes:** `README.md` (new section in the "When to use" section).
|
|
|
|
### Pillar 2: Repo Infrastructure
|
|
|
|
#### 7. Forgejo issue templates
|
|
|
|
Create `.forgejo/ISSUE_TEMPLATE/` with two YAML templates:
|
|
|
|
**`bug_report.yaml`:**
|
|
- Plugin version (required)
|
|
- Claude Code version
|
|
- Reproduction steps
|
|
- Expected vs actual behavior
|
|
- Auto-label: `type: bug`
|
|
|
|
**`feature_request.yaml`:**
|
|
- Problem description
|
|
- Proposed solution
|
|
- Alternatives considered
|
|
- Auto-label: `type: enhancement`
|
|
|
|
**Rationale:** Forgejo audit showed no `.gitea/` or `.forgejo/` infrastructure.
|
|
Standard for an open-source project that accepts issues.
|
|
|
|
#### 8. Label set in Forgejo
|
|
|
|
Create via Forgejo API or UI:
|
|
|
|
| Label | Color | Use |
|
|
|-------|-------|-----|
|
|
| `type: bug` | red | Something is broken |
|
|
| `type: enhancement` | blue | New feature or improvement |
|
|
| `type: docs` | green | Documentation only |
|
|
| `status: confirmed` | yellow | Verified/accepted |
|
|
| `status: wontfix` | gray | Closed without action |
|
|
| `good first issue` | purple | Low complexity, well scoped |
|
|
|
|
**Rationale:** No labels exist. Necessary for triage.
|
|
|
|
#### 9. Forgejo Release for v1.0.0
|
|
|
|
Create a Release object (not just a git tag) with CHANGELOG content attached.
|
|
Use `v1.0.0` as the tag name.
|
|
|
|
**Rationale:** Repo audit showed that commits exist but no Release objects.
|
|
Releases are the first thing users see on a Forgejo project.
|
|
|
|
#### 10. README badges
|
|
|
|
Add badges to README:
|
|
|
|
```markdown
|
|
|
|
|
|
|
|
```
|
|
|
|
**Rationale:** Quality signal on first visit. Standard for open source.
|
|
|
|
#### 11. CONTRIBUTING.md tailored for solo project
|
|
|
|
Rewrite to be honest about the contribution model:
|
|
- "This is a solo project. Issues are welcome. PRs are considered but not expected."
|
|
- Remove section about PR workflow
|
|
- Keep: how to report bugs, suggest improvements
|
|
|
|
**Rationale:** Current CONTRIBUTING.md implies that PRs are welcome, but
|
|
the project is marked as solo. Dishonest signaling.
|
|
|
|
---
|
|
|
|
## v1.3.0 — Session-Aware Parallel Execution (DONE)
|
|
|
|
Completed 2026-04-06. See [CHANGELOG.md](../CHANGELOG.md) for details.
|
|
|
|
**Delivered:**
|
|
- `/ultraexecute-local` auto-detects `## Execution Strategy` in plans
|
|
- Multi-session parallel orchestration via `claude -p` per wave
|
|
- `--fg` flag: force sequential execution, ignore Execution Strategy
|
|
- `--session N` flag: execute only session N (used by child processes)
|
|
- Phase 2.5 (Execution strategy decision) and Phase 2.6 (Multi-session orchestration)
|
|
- Execution Strategy section in plan template (sessions, waves, scope fences)
|
|
- planning-orchestrator generates Execution Strategy for plans with > 5 steps
|
|
- File overlap analysis to group steps into sessions and waves
|
|
|
|
---
|
|
|
|
## v1.2.0 — Disciplined Plan Executor (DONE)
|
|
|
|
Completed 2026-04-06. See [CHANGELOG.md](../CHANGELOG.md) for details.
|
|
|
|
**Delivered:**
|
|
- `/ultraexecute-local` command: 9-phase workflow for disciplined plan execution
|
|
- 4 modes: execute, --resume, --dry-run, --step N
|
|
- Per-step protocol: implement → verify → on-failure → checkpoint
|
|
- Progress file for crash recovery and resume
|
|
- Entry/exit condition checking for session specs
|
|
- Scope fence enforcement (never-touch protection)
|
|
- JSON summary block for headless log parsing
|
|
- Stats tracking to ultraexecute-stats.jsonl
|
|
- Positioning: Harness = project engine, Kiur = TDD, Ultraexecute = plan executor
|
|
|
|
---
|
|
|
|
## v1.1.0 — Headless Multi-Session Execution (DONE)
|
|
|
|
Completed 2026-04-06. See [CHANGELOG.md](../CHANGELOG.md) for details.
|
|
|
|
**Delivered:**
|
|
- `--decompose` mode: splits plan into self-contained headless sessions
|
|
- `--export headless` format: shortcut to decompose
|
|
- session-decomposer agent: analyzes step dependencies, groups into sessions, generates dependency graph + launch script
|
|
- Session spec template with scope fences, entry/exit conditions, failure handling
|
|
- Failure recovery per step in plan template: On failure + Checkpoint
|
|
- Headless readiness as new dimension in plan-critic (9 dimensions, rebalanced weights)
|
|
|
|
---
|
|
|
|
## Future (after v1.1, unprioritized)
|
|
|
|
Based on competitive analysis and simulations. Each item has a rationale
|
|
for why it's not in v1.0.
|
|
|
|
| Feature | Source | Why not v1.0 |
|
|
|---------|--------|--------------|
|
|
| Plan auto-update during execution | Windsurf differentiator | Major architecture change — the plan is currently static after generation. Requires hooks that observe execution and update the plan file. Windsurf spent months on this. |
|
|
| Issue integration (`--issue #42`) | OSS contributor simulation | Tracker-dependent (Linear, Forgejo, GitHub, Jira). Too ambitious for first stable release. |
|
|
| Plan diff on re-planning | Senior engineer simulation | Useful but not a blocker. Can be solved with `diff` on two plan files manually. |
|
|
| Cost estimate in plan summary | Senior engineer simulation | Requires reliable token counting. Claude Code API doesn't expose this directly. |
|
|
| IDE sidebar for plan | Windsurf differentiator | Requires VS Code extension — entirely different technology stack. |
|
|
| IaC-adapted agents | DevOps simulation | Niche need. Solved with documented limitation in v1.0. |
|
|
| Bug mode (`--bug`) | Junior simulation | Can be partially solved with adaptive interview (v1.0 item 4). Dedicated mode is overkill for first release. |
|
|
| Solution memory | Roadmap v0.4.0 future | Secondary — plan quality should stand on its own without history. |
|
|
|
|
---
|
|
|
|
## Competitive Position
|
|
|
|
### What ultraplan-local has that nobody else does
|
|
|
|
| Feature | Copilot Workspace | Cursor | Windsurf | ultraplan-local |
|
|
|---------|-------------------|--------|----------|----------------|
|
|
| Adversarial review (plan-critic + scope-guardian) | No | No | No | **Yes** |
|
|
| Quantitative plan scoring (A-D) | No | No | No | **Yes** |
|
|
| No-placeholder enforcement (hard blocker) | No | No | No | **Yes** |
|
|
| `[ASSUMPTION]` marking with threshold warning | No | No | No | **Yes** |
|
|
| Spec-driven headless mode (`--spec`) | No | No | No | **Yes** |
|
|
| TDD-structured steps (RED-GREEN-REFACTOR) | No | No | No | **Yes** |
|
|
| Full interview phase for requirements gathering | No | No | Partial | **Yes** |
|
|
| 12 specialized agents | No | No | No | **Yes** |
|
|
| Session decomposition into headless sessions | No | No | No | **Yes** |
|
|
| Failure recovery per step (On failure/Checkpoint) | No | No | No | **Yes** |
|
|
| Parallel wave-based execution (`launch.sh`) | No | No | No | **Yes** |
|
|
|
|
### Known gaps vs competitors
|
|
|
|
| Gap | Who has it | Status |
|
|
|-----|-----------|--------|
|
|
| Plan updates during execution | Windsurf | Future — major architecture change |
|
|
| PR-native output | Copilot Workspace | v1.0 — `--export pr` |
|
|
| Issue integration | Copilot Workspace | Future — tracker-dependent |
|
|
| Sandbox execution during planning | Cursor | Out of scope — different architecture |
|
|
| IDE sidebar | Windsurf | Future — requires VS Code extension |
|
|
|
|
---
|
|
|
|
## Compatibility
|
|
|
|
- **Harness users**: Plans from ultraplan are detailed enough to
|
|
manually decompose into Harness feature_list.json
|
|
- **Superpowers users**: TDD task structure matches Superpowers'
|
|
plan format. Plans are compatible with the `executing-plans` skill.
|