| name | research-and-plan |
| argument-hint | [output FILE] <broad goal description> |
| description | Decompose a broad goal into a sequence of executable sub-plans. Researches the domain, identifies sub-problems and dependencies, then produces a meta-plan where each phase delegates to /run-plan. Usage: /research-and-plan [output FILE] <description...> |
/research-and-plan [output FILE] <description...> — Meta-Plan Decomposer
Breaks broad goals into focused sub-plans, each drafted via /draft-plan
and executed via /run-plan. The output is a meta-plan file whose phases
are pure delegation — no drafting happens during execution.
Ultrathink throughout.
Arguments
- output FILE (optional) — meta-plan output path. Default:
plans/<SLUG>_META.md (slug from description).
- auto (optional) — skip the decomposition confirmation checkpoint.
Proceed directly to drafting after decomposition research. Used by
/research-and-go for fully autonomous operation.
- description (required) — everything after recognized keywords.
Detection: scan arguments for output + path, auto, and first
token ending .md. Everything else = description. auto is stripped
from the description.
Escalation from /draft-plan: If the invoking context mentions a
research file at /tmp/draft-plan-research-*.md, read it — that research
feeds Step 1 and avoids redundant exploration.
Step 1 — Decomposition Research
Three focused investigations. If a research file was passed from
/draft-plan, start from it — validate and extend rather than starting
from scratch.
1a. Domain survey — Dispatch Explore agents to map the scope: what the
goal encompasses, what exists already, natural sub-domains, shared
infrastructure needed across sub-problems.
1b. Dependency analysis — Build a dependency graph: which sub-problems
are independent (parallelizable), which are sequential, and whether shared
prerequisites exist (e.g., "generalize the port system" before new domains).
1c. Scope sizing — Estimate each sub-problem's size. If a sub-plan
would need 8+ phases, split further. Each must be completable by
/run-plan finish auto in one session. Mark in-scope vs. out-of-scope.
Present the decomposition:
Decomposition complete. I identified N sub-problems:
- Sub-problem A — [one-line description] (est. N phases)
- Sub-problem B — [one-line description] (est. M phases, depends on A)
...
Dependency graph: A -> B -> D, A -> C (independent of B)
In scope: [list]. Out of scope: [list].
Without auto: wait for user confirmation. They may reorder, drop,
merge, or add sub-problems. Do NOT proceed until confirmed.
With auto: present the decomposition for the record, then proceed
directly to Step 2. The user said auto — that's approval.
Step 2 — Draft All Sub-Plans
After user approval, draft each sub-plan by invoking /draft-plan.
Why /draft-plan must be invoked via the Skill tool, not the Agent tool
Subagents in Claude Code cannot dispatch further subagents. This is
documented at https://code.claude.com/docs/en/sub-agents and verifiable by
inspecting any subagent's tool list — they have no Agent/Task tool.
By Anthropic's design, sub-sub-agent dispatch is not supported.
/draft-plan internally dispatches Agent calls for parallel research
(Phase 1), reviewer + devil's advocate agents (Phase 3), and the refiner
(Phase 4). These dispatches require /draft-plan to be running in a
context that HAS the Agent tool — meaning a top-level context, not a
subagent.
The Skill tool is the recursion mechanism. When you (a top-level skill)
invoke Skill: { skill: "draft-plan", args: ... }, the Skill tool loads
/draft-plan's instructions INTO YOUR CONTEXT. You — still at top-level,
still with the Agent tool — execute /draft-plan's research, review,
and refine workflow as if its instructions were your own. The Agent
dispatches happen from your top-level context and work correctly.
If you instead Agent-dispatch a subagent to "run /draft-plan", the
dispatched subagent has no Agent tool. /draft-plan's internal
dispatches fail. The skill degrades to single-context inline drafting
with no adversarial review. The output is unreviewed and may fail.
This rule applies to /draft-plan because it has internal dispatches.
It does NOT mean "don't use the Agent tool generally" — /draft-plan
itself uses the Agent tool extensively for its sub-tasks. It means: to
invoke a skill that has internal dispatches, use the Skill tool, not the
Agent tool. The same rule applies to /run-plan, /research-and-plan,
/fix-issues, /verify-changes, and /add-block.
Past failure: This has been violated three separate times by agents
who interpreted the rule as "/draft-plan internally is forbidden from
using Agent" or who rationalized "I'll go faster by writing the plan
directly." Both interpretations are wrong. The result was unreviewed
plans with 10+ CRITICAL issues each, requiring full restarts.
Landing mode detection
Before dispatching /draft-plan agents, detect whether the original
goal/description text contains pr or direct as a distinct word. Use
the same pattern as Phase 3a, extended with sentence punctuation .!?
since this is prose-like goal text:
LANDING_ARG=""
if [[ "$GOAL" =~ (^|[[:space:]])[pP][rR]($|[[:space:]]|[.!?]) ]]; then
LANDING_ARG="pr"
elif [[ "$GOAL" =~ (^|[[:space:]])[dD][iI][rR][eE][cC][tT]($|[[:space:]]|[.!?]) ]]; then
LANDING_ARG="direct"
fi
Where $GOAL is the full description passed to /research-and-plan.
If LANDING_ARG is empty, no landing-mode suffix is added to the
/draft-plan invocation. This is a hint for generated plans — it does
NOT enforce landing behavior. The /run-plan argument always takes
precedence at execution time.
For each sub-problem:
- Determine the sub-plan output path:
plans/<SLUG>_<N>.md (or let the
user specify).
- If research from Step 1 was written to a file, pass that path to the
/draft-plan agent so it has the decomposition context.
- Dispatch:
/draft-plan output <path> <sub-problem description>
- If
LANDING_ARG is non-empty, append . Landing mode: <LANDING_ARG>
to the description so /draft-plan can embed the matching hint in
the generated plan. Example:
/draft-plan output plans/X.md rounds 2 <description>. Landing mode: pr
- If
LANDING_ARG is empty, omit the suffix entirely — do NOT pass
an empty Landing mode: token.
- Wait for each
/draft-plan batch to complete before dispatching the
next batch (see parallelism rules below).
Parallelism and resource limits: Dispatch at most 3 /draft-plan
agents concurrently. Wait for each batch to complete before the next.
While waiting, do NOT draft plans yourself — wait. The idle time is
the cost of not melting the container. Past failure: 11 parallel agents
caused load average 67, 54 test timeouts, and forced a full restart.
Draft in dependency order:
- Foundation plan first (alone — everything depends on it)
- Independent plans in batches of 3
- Dependent plans after their prerequisites complete
Dependent sub-plans must be drafted after their prerequisites so later
plans can reference earlier plans' actual content.
Staleness notes for dependent sub-plans. Sub-plans that depend on
earlier ones get this in their Dependencies section:
### Dependencies
- Plan A must be complete. **Note:** This plan was drafted before Plan A
was implemented. APIs and data structures referenced here are based on
Plan A's design, not actual code. `/run-plan` may refresh this plan
before execution.
This tells /run-plan to offer a plan refresh (interactive) or
auto-refresh (auto mode) before implementing — ensuring the plan reflects
actual code, not predictions.
Step 2b — Verify All Sub-Plans Were Properly Drafted
Before proceeding to cross-plan review, verify that each sub-plan
went through /draft-plan's adversarial process. Two checks:
Check 1 — Mechanical (grep)
for plan in plans/<SLUG>_*.md; do
if ! grep -q '## Plan Quality' "$plan" || ! grep -q '### Round History' "$plan"; then
echo "FAILED: $plan — missing adversarial review signature"
fi
done
If any plan fails, it was not drafted via /draft-plan. Stop and
re-draft it properly.
Check 2 — Verification agent
Dispatch a verification agent that reads every sub-plan file and checks:
## Plan Quality section exists with ### Round History table
- Round History has at least one round with non-zero findings —
real adversarial review almost always finds issues on round 1. A
table showing "0 issues | 0 issues" on round 1 is suspicious.
- The findings described in Round History reference specific content
from the plan (phase names, field names, design decisions) — not
generic boilerplate like "looks good, no issues found"
- The plan's phases have concrete work items and acceptance criteria —
not vague descriptions that suggest a rushed draft
The agent reports pass/fail per plan with evidence. Any plan that fails
must be re-drafted via /draft-plan before proceeding.
Do NOT proceed to Step 3 with unreviewed plans — the cross-plan
review cannot compensate for plans that were never individually reviewed.
Step 3 — Cross-Plan Consistency Review (converge until clean)
After all sub-plans are drafted and verified (Step 2b), review the full
set for cross-plan consistency. Individual sub-plans were reviewed by /draft-plan, but
cross-plan issues (shared schemas, naming collisions, directory conflicts,
storage model disagreements) only emerge when you look at all plans together.
Each round: dispatch 2+ review agents in parallel
Reviewer agent — cross-plan consistency:
- Do all sub-plans agree on shared data structures, schemas, field names?
- Are directory paths, ID prefixes, and namespaces consistent?
- Is the dependency ordering correct?
- Are there missing sub-problems? (Infrastructure, integration, glue?)
Devil's advocate agent — structural risks:
- Wrong split — would a different decomposition be simpler?
- Hidden coupling — shared assumptions that break if one plan changes?
- Missing glue — who integrates the sub-plans?
- Deferred complexity — hardest part buried in the last sub-plan?
After each round: apply fixes to the sub-plan files
This is the critical step that was previously missing. For every
finding that changes a sub-plan's assumptions, schemas, naming, or
structure — edit the actual sub-plan file. Do NOT just document
resolutions in the meta-plan. The sub-plan files are what /run-plan
reads; the meta-plan is an index, not a patch set.
Verify each fix was applied by reading the sub-plan file after editing.
Convergence
Continue rounds until no CRITICAL or MAJOR issues are found. Minor issues
may be noted for implementation-time resolution. Maximum 3 rounds — if
still finding MAJOR issues after 3 rounds, the decomposition itself may
need restructuring. Report to the user.
Step 4 — Write the Meta-Plan
After all sub-plans are drafted and the decomposition is reviewed, write
the meta-plan. Every phase is pure delegation — /run-plan executes
sub-plans, no /draft-plan during execution.
Meta-plan template
# Meta-Plan: <Title>
## Overview
[What this meta-plan accomplishes and the decomposition rationale]
## Decomposition
[Sub-problems identified, dependency graph, scope rationale]
## Sub-Plans
| Plan | Phases | Dependencies | Notes |
|------|--------|--------------|-------|
| [SUB_PLAN_A.md](SUB_PLAN_A.md) | N | None | |
| [SUB_PLAN_B.md](SUB_PLAN_B.md) | M | A | May need refresh after A |
## Progress Tracker
| Phase | Status | Commit | Notes |
|-------|--------|--------|-------|
| 1 — Implement: <sub-problem A> | ⬚ | | |
| 2 — Implement: <sub-problem B> | ⬚ | | |
## Phase N — Implement: <Sub-problem X>
### Goal
Execute the plan for <sub-problem X>.
### Execution: delegate /run-plan plans/<SUB_PLAN_X>.md finish auto
### Acceptance Criteria
- [ ] All phases in the sub-plan are marked Done
- [ ] All tests pass on main after landing
- [ ] Plan report exists with verification results
### Dependencies
[List prerequisite phases. Dependent sub-plans may auto-refresh.]
## Plan Quality
**Drafting process:** /research-and-plan with cross-plan consistency review
**Sub-plans:** Each drafted via /draft-plan with adversarial review
**Cross-plan review:** N rounds until no CRITICAL/MAJOR issues remain
Repeat the Phase N template for each sub-problem. First phase has
Dependencies: None. Dependent phases list their prerequisites and note
that the sub-plan may auto-refresh to reflect actual implementation.
Tracking — Standalone Invocation
If this skill was invoked directly (not via /research-and-go), create
tracking requirement files so that pipeline-aware tools can monitor progress.
This only applies when /research-and-go did not already create them.
After writing the meta-plan, check for an existing pipeline sentinel:
MAIN_ROOT=$(cd "$(git rev-parse --git-common-dir)/.." && pwd)
If the arguments do NOT contain parent=research-and-go (this is a standalone
invocation), create requirement files for each phase that delegates to
/run-plan:
mkdir -p "$MAIN_ROOT/.zskills/tracking"
for i in 1 2 ... N; do
printf 'skill=run-plan\nindex=%d\nrequiredBy=research-and-plan\ncreatedAt=%s\n' "$i" "$(date -Iseconds)" > "$MAIN_ROOT/.zskills/tracking/requires.run-plan.$i"
done
Replace 1 2 ... N with the actual phase indices from the meta-plan (one per
phase that uses delegate /run-plan). These files allow a subsequent
/run-plan invocation (or a monitoring tool) to know how many phases the
meta-plan expects and track which have been completed.
If the arguments contain parent=research-and-go, this was dispatched by
/research-and-go which already created the requirement files — do not
create duplicates.
Note: The existing 3-layer /draft-plan verification (Step 2b) is fully
preserved. Tracking supplements the verification process; it does not replace it.
Finalization
- Write the meta-plan to the output path.
- Update
plans/PLAN_INDEX.md if it exists (add a row to "Ready to Run").
If it doesn't exist, suggest /plans rebuild.
- Present the result:
Meta-plan written to plans/<FILE>.md with N sub-plans.
Sub-plans: [list with paths]
Execute with: /run-plan plans/<FILE>.md
Or with scheduling: /run-plan plans/<FILE>.md auto every 4h now
Key Rules
- Pure delegation in the meta-plan. Every phase uses
### Execution: delegate /run-plan. No delegate /draft-plan — all
drafting happens upfront in Step 2.
- User confirms the decomposition. Step 1 ends with a checkpoint.
Do not draft sub-plans until the user approves the split.
- Staleness notes on dependent sub-plans. Sub-plans drafted before
their dependencies are implemented get explicit warnings so
/run-plan
knows to refresh.
- Adversarial review targets the decomposition. Individual sub-plans
get their own review via
/draft-plan. Step 3 reviews the split itself.
- Respect constraints. No external solvers, no bundlers, no
dependencies without approval. These apply to every sub-plan.
- Each sub-plan must be session-completable. If a sub-plan needs 8+
phases, split it further.