research-and-plan

/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.

Preflight — top-level dispatch required

This skill internally dispatches reviewer + devil's-advocate + refiner sub-agents in parallel. It MUST run in a context that has the Agent (or Task) tool available.

Before doing any other work, verify your tool list contains Agent or Task. If neither is present, STOP and report:

ERROR: /research-and-plan requires top-level Agent dispatch capability. This invocation is running as a subagent (no Agent tool — verified by inspecting your tool list). Subagents cannot dispatch sub-subagents (Anthropic design — https://code.claude.com/docs/en/sub-agents).

Re-invoke as one of:

• User slash command: /research-and-plan <description...>
• Top-level Skill tool: Skill(skill="research-and-plan", args="<description...>")
• Inline orchestration by a top-level Claude that has Agent

Do NOT continue. Single-agent inline degradation produces rubber-stamp findings without the adversarial diversity this skill's value depends on. The CLAUDE.md memory anchor feedback_multi_agent_skills_top_level.md is the recurring failure mode this preflight catches.

Do not proceed past this preflight without Agent access.

Arguments

• output FILE (optional) — meta-plan output path. Default: $ZSKILLS_PLANS_DIR/<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:

1. Sub-problem A — [one-line description] (est. N phases)
2. 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.

For each sub-problem:

1. Determine the sub-plan output path: $ZSKILLS_PLANS_DIR/<SLUG>_<N>.md (or let the user specify).
2. If research from Step 1 was written to a file, pass that path to the /draft-plan agent so it has the decomposition context.
3. Dispatch: /draft-plan output <path> <sub-problem description>$AUTO_ARG
   • $AUTO_ARG propagation. If /research-and-plan itself was invoked with auto (i.e. you are running under /research-and-go or the user passed auto to /research-and-plan), thread that token into every /draft-plan dispatch so the child skill's AUTO_FLAG detection fires. Resolve once near the argument-detection block:

     AUTO_ARG=""
     if [[ "$ARGUMENTS" =~ (^|[[:space:]])auto($|[[:space:]]) ]]; then
       AUTO_ARG=" auto"
     fi
     

     Then append $AUTO_ARG to every /draft-plan dispatch string. Without this, /draft-plan's AUTO_FLAG stays 0, the child commits in its worktree and never dispatches /land-pr, and the sub-plan is stranded on a draft-plan/<slug> branch instead of landing on main. (Closure for #648; child-side fix was #581 / PR #642.)
4. After each /draft-plan invocation returns, report progress, then move to the next sub-plan (see serial-dispatch rule below).

Serial dispatch — no parallelism. Invoke /draft-plan once per sub-problem via the Skill tool. Each invocation runs the full multi-round review loop in your context before returning; this is intrinsically serial. Report progress between sub-plans. Do not Agent-dispatch (subagents lack the Agent tool, breaking /draft-plan's internal reviewer + devil's-advocate dispatch — see the Skill-tool MUST above).

Draft in dependency order:

1. Foundation plan first (everything depends on it)
2. Independent plans next, one at a time
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 "$ZSKILLS_PLANS_DIR"/<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:

1. ## Plan Quality section exists with ### Round History table
2. 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.
3. 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"
4. 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)

Convergence is the orchestrator's judgment, not any agent's self-call. Do NOT accept "CONVERGED" or "no issues found" from the reviewer or devil's advocate as authoritative — count substantive findings yourself, and honor the user's rounds budget. Both agents are biased toward declaring their pass complete (the reviewer toward "looks fine," the devil's advocate toward plausibility over truth). This is a recurring failure mode in practice.

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

The orchestrator decides convergence after each round by counting substantive findings (CRITICAL or MAJOR severity) across both agents' reports — do not rubber-stamp a self-declared "CONVERGED" from either agent. Continue rounds until the orchestrator confirms no CRITICAL or MAJOR issues remain. Honor the user's rounds budget; only short- circuit before max rounds when CRITICAL/MAJOR findings are genuinely 0. 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.

Note: the CRITICAL/MAJOR severity threshold is intentional divergence from /draft-plan Phase 5 and /refine-plan Phase 4 (which use a flat "no substantive issues" criterion). /research-and-plan decomposes a broad goal into sub-plan stubs, where MINOR sub-plan-stub wording is correctly deferred to subsequent /draft-plan runs on each sub-plan. Do not "fix" this to match the other plan skills.

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 $ZSKILLS_PLANS_DIR/<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 metadata files for each phase that delegates to /run-plan. These are metadata, not enforcement (same OQ1 decision as research-and-go's integer markers), so they use the meta.* prefix — the hook's enforcement globs don't scan meta.*.

Construct the PIPELINE_ID for this standalone research-and-plan run (the meta-plan filename gives a stable, per-run scope):

# $META_PLAN_PATH is the output path where the meta-plan is (or will be)
# written — same value used as the `output FILE` argument / default
# (`$ZSKILLS_PLANS_DIR/<SLUG>_META.md`). Derive a stable slug from it.
# Resolve $META_PLAN_PATH from $ARGUMENTS if not already set by the
# parent skill (`/research-and-go` exports it; standalone invocations
# parse it from the `output FILE` positional argument or fall back to
# the canonical default).
if [ -z "${META_PLAN_PATH:-}" ]; then
  if [ -f "${CLAUDE_PLUGIN_ROOT}/skills/update-zskills/scripts/zskills-paths.sh" ]; then
    export CLAUDE_PLUGIN_ROOT="${CLAUDE_PLUGIN_ROOT}"
    . "${CLAUDE_PLUGIN_ROOT}/skills/update-zskills/scripts/zskills-paths.sh"
  else
    . "$CLAUDE_PROJECT_DIR/.claude/skills/update-zskills/scripts/zskills-paths.sh"
  fi
  # First `.md` token in $ARGUMENTS is the output path. If absent, fall
  # back to a timestamped default so the slug computation below produces
  # a stable, non-empty value rather than fail-closing the sanitiser.
  META_PLAN_PATH=""
  for tok in $ARGUMENTS; do
    case "$tok" in
      *.md) META_PLAN_PATH="$tok"; break ;;
    esac
  done
  : "${META_PLAN_PATH:=$ZSKILLS_PLANS_DIR/$(date +%Y%m%d-%H%M%S)_META.md}"
fi
META_PLAN_SLUG=$(basename "$META_PLAN_PATH" .md | tr '[:upper:]_' '[:lower:]-')
PIPELINE_ID="research-and-plan.$META_PLAN_SLUG"
PIPELINE_ID=$(bash "$ZSKILLS_SKILLS_ROOT/create-worktree/scripts/sanitize-pipeline-id.sh" "$PIPELINE_ID")
[ -n "$PIPELINE_ID" ] || { echo "tracking: empty PIPELINE_ID — refusing flat write" >&2; exit 1; }
mkdir -p "$MAIN_ROOT/.zskills/tracking/$PIPELINE_ID"
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/$PIPELINE_ID/meta.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

1. Write the meta-plan to the output path.
2. Plan index — do not touch. The plan index is regenerated from source-of-truth by /plans rebuild and auto-refreshed by /plans Mode: Show when the source has changed. No manual update needed here.
3. Present the result:

   Meta-plan written to $ZSKILLS_PLANS_DIR/<FILE>.md with N sub-plans. Sub-plans: [list with paths]

   Execute with: /run-plan $ZSKILLS_PLANS_DIR/<FILE>.md Or with scheduling: /run-plan $ZSKILLS_PLANS_DIR/<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.
• Convergence is the orchestrator's call based on counted CRITICAL/MAJOR findings across the reviewer + devil's advocate reports, not any agent's self-declaration. Run all budgeted rounds unless CRITICAL/MAJOR findings drop to 0.
• 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.