research-and-go

/research-and-go <description> — Plan and Execute Everything

The full autonomous pipeline in one command. Decomposes a broad goal into focused sub-plans, drafts each with adversarial review, writes a meta-plan, and immediately executes it — all without pausing for approval.

Use when: you trust the pipeline and want end-to-end execution from a single description. For more control, use /research-and-plan (plan only) followed by /run-plan (execute).

Ultrathink throughout.

Preflight — top-level dispatch required

This skill Skill-loads /research-and-plan and /run-plan, which internally dispatch 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-go 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-go <description>
• Top-level Skill tool: Skill(skill="research-and-go", 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

/research-and-go <description>

• description (required) — the broad goal, in natural language. Same format as /research-and-plan.

Examples:

• /research-and-go Add physical modeling support for thermal and mechanical domains
• /research-and-go Implement all missing block diagram tool blocks from the gap analysis
• /research-and-go Close the runtime deployment parity gap

Step 0 — Tracking Setup

Before anything else, check whether another pipeline is already in progress.

On resume, also check step.* markers. Child /run-plan invocations emit per-phase step.<phase>.{implement,verify,report} markers under their own pipeline subdirs (convention documented at docs/tracking/TRACKING_NAMING.md:413-415). If you are resuming an existing pipeline (sentinel already exists), inspect those step.* markers across the child pipelines' subdirs to determine which sub-plan phase last made progress before re-dispatching — they are the authoritative per-phase progress signal.

MAIN_ROOT=$(cd "$(git rev-parse --git-common-dir)/.." && pwd)
mkdir -p "$MAIN_ROOT/.zskills/tracking"

Check for duplicate pipeline: Compute the scope slug first (see below), then check if $MAIN_ROOT/.zskills/tracking/research-and-go.$SCOPE/pipeline.research-and-go.$SCOPE exists (new subdir scheme — Phase 1 design doc Option B). If it does, STOP — this exact pipeline is already in progress. Read the file and report its contents. Do not proceed unless this is a deliberate re-run (see Re-run Handling below). Note: other research-and-go pipelines with DIFFERENT scopes are fine — they run in parallel without conflict.

Create the scoped sentinel:

Compose $SCOPE (model-layer). Set shell variable SCOPE to a kebab-case identifier matching ^[a-z0-9]+(-[a-z0-9]+)*$, ≤30 chars, a 3–5 word summary of the goal. Compose from $DESCRIPTION's essential verbs/nouns — not a verbatim prefix of the input. Multi-line descriptions compose the same way as single-line ones: distill the intent, don't splice lines.

if [ -f "${CLAUDE_PLUGIN_ROOT}/skills/update-zskills/scripts/zskills-resolve-config.sh" ]; then
  export CLAUDE_PLUGIN_ROOT="${CLAUDE_PLUGIN_ROOT}"
  . "${CLAUDE_PLUGIN_ROOT}/skills/update-zskills/scripts/zskills-resolve-config.sh"
else
  . "$CLAUDE_PROJECT_DIR/.claude/skills/update-zskills/scripts/zskills-resolve-config.sh"
fi
if [ -z "${SCOPE:-}" ]; then
  echo "ERROR: SCOPE not set — model-layer composition step skipped." >&2
  exit 5
fi
if ! [[ "$SCOPE" =~ ^[a-z0-9]+(-[a-z0-9]+)*$ ]] || [ ${#SCOPE} -gt 30 ]; then
  echo "ERROR: SCOPE must match ^[a-z0-9]+(-[a-z0-9]+)*\$ and be ≤30 chars (got '$SCOPE')." >&2
  exit 2
fi

PIPELINE_ID="research-and-go.$SCOPE"
PIPELINE_ID=$(bash "$ZSKILLS_SKILLS_ROOT/create-worktree/scripts/sanitize-pipeline-id.sh" "$PIPELINE_ID")
# Recover SCOPE after sanitization (strip the "research-and-go." prefix).
# Sanitization is idempotent on a validator-passing $SCOPE, but keep the
# recovery so any future change to the sanitizer cannot silently skew
# $SCOPE away from what $PIPELINE_ID encodes.
SCOPE="${PIPELINE_ID#research-and-go.}"
[ -n "$PIPELINE_ID" ] || { echo "tracking: empty PIPELINE_ID — refusing flat write" >&2; exit 1; }
mkdir -p "$MAIN_ROOT/.zskills/tracking/$PIPELINE_ID"
printf 'skill=research-and-go\ngoal=%s\nstartedAt=%s\n' "$DESCRIPTION" "$(date -Iseconds)" > "$MAIN_ROOT/.zskills/tracking/$PIPELINE_ID/pipeline.research-and-go.$SCOPE"

Where $DESCRIPTION is the broad goal passed to this command and $SCOPE is a model-composed short identifier used for tracking-dir scoping.

Declare pipeline ID for hook scoping:

echo "ZSKILLS_PIPELINE_ID=$PIPELINE_ID"

This echo is read by the tracking hook from the session transcript to scope marker checks to this pipeline only. It must happen before any git operation.

Pre-decide the meta-plan path so the final-verify marker can be written immediately (gate is in place from pipeline start):

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
  source "$CLAUDE_PROJECT_DIR/.claude/skills/update-zskills/scripts/zskills-paths.sh"
fi
SCOPE_UPPER=$(echo "$SCOPE" | tr 'a-z-' 'A-Z_')
META_PLAN_PATH="$ZSKILLS_PLANS_DIR/META_${SCOPE_UPPER}.md"
META_PLAN_SLUG=$(basename "$META_PLAN_PATH" .md | tr '[:upper:]_' '[:lower:]-')
# Convention matches /run-plan TRACKING_ID derivation
# (skills/run-plan/SKILL.md:388-398).

Lock down the final cross-branch verification requirement immediately. The pipeline will end with a top-level /verify-changes branch invocation that runs as a cron-fired turn after the meta-plan execution completes. By creating the requirement marker NOW (before any implementation), the hook will block any commit on main until this final verification has been fulfilled. The orchestrator cannot skip the final cross-branch check.

[ -n "$PIPELINE_ID" ] || { echo "tracking: empty PIPELINE_ID — refusing flat write" >&2; exit 1; }
printf 'skill=verify-changes\nscope=branch\nrequiredBy=research-and-go\nmeta_plan=%s\nmeta_plan_slug=%s\ncreatedAt=%s\n' \
  "$META_PLAN_PATH" "$META_PLAN_SLUG" "$(date -Iseconds)" \
  > "$MAIN_ROOT/.zskills/tracking/$PIPELINE_ID/requires.verify-changes.final.$META_PLAN_SLUG"

Known cross-pipeline read gap (PHASE-5-UPDATE): run-plan reads this requires.verify-changes.final.$META_PLAN_SLUG marker from a different pipeline's subdir (r&g's subdir, not run-plan's). The flat-path reads at skills/run-plan/SKILL.md:1176-1177 and 1365-1368 still need updating to the subdir scheme. Tracked for Phase 5 — not touched here.

The marker is named with the meta-plan slug to match the pipeline scope the meta-plan /run-plan will emit (run-plan.<META_PLAN_SLUG>). The hook's pipeline-scoping pattern (*.${PIPELINE_ID#*.} in hooks/block-unsafe-project.sh.template:250) enforces this marker on the meta-plan orchestrator's commits but NOT on sub-plan commits (sub-plans run under their own scopes). Note: hook enforcement is gated on CODE_FILES being non-empty (hook line 243); since the meta-plan's pipeline-completion commit is content-only, the hook is a backstop -- /run-plan Phase 5c does the orchestrator-level check that actually defers Phase 5b until the fulfillment marker exists.

Re-run Handling

If $MAIN_ROOT/.zskills/tracking/$PIPELINE_ID/pipeline.research-and-go.$SCOPE already exists and this is a deliberate re-run of the same goal:

1. Read the existing pipeline.research-and-go.$SCOPE to confirm the goal matches.
2. Check which requires.* and meta.* files already exist in $MAIN_ROOT/.zskills/tracking/$PIPELINE_ID/.
3. For each existing requires.* entry, check if a corresponding fulfilled.* file exists in the same subdir. Only create new requirement files for unfulfilled requirements. (meta.* files are metadata and are idempotent — just re-touch.)
4. Touch existing requires.* files to refresh their mtime (prevents staleness false positives).
5. Overwrite the pipeline.research-and-go.$SCOPE sentinel with a fresh timestamp.

Atomicity gate — Step 0 → Step 1 ships in ONE response

Do NOT split Step 0's last bash and Step 1's Skill call across separate responses — interrupt-resilience requires they ship together.

The moment Step 0's final bash block completes (sentinel written, pipeline ID echoed, requirement marker written, and — on re-run — staleness touches done), the very next tool call in the SAME assistant response MUST be the Skill invocation in Step 1 below. Do not end your turn between Step 0 and Step 1. Do not narrate "now I will invoke /research-and-plan" and stop — actually invoke it, in this same response. This atomicity is the only thing protecting the pipeline against a user interrupt (e.g., a permissions prompt) that arrives between turns and leaves a tracking sentinel with no follow-through.

Step 1 — Decompose and Draft

This step MUST execute in the same response as Step 0's last bash block (see Atomicity gate above).

Invoke /research-and-plan (via the Skill tool) with auto, parent=research-and-go, and the full description:

/research-and-plan output $META_PLAN_PATH auto parent=research-and-go <description>

This:

1. Dispatches research agents to survey the domain
2. Identifies sub-problems and dependencies
3. Sizes scope for each sub-plan
4. Skips the user confirmation checkpoint — auto flag.
5. Drafts each sub-plan via dispatched /draft-plan agents (each gets full adversarial review in its own context)
6. Writes the meta-plan with pure implementation phases

The meta-plan path is pre-decided by /research-and-go at Step 0 and passed to /research-and-plan via the output argument -- /research-and-plan writes the meta-plan to that path. Confirm the path was written successfully (file exists and is non-empty) before proceeding.

Step 1b — Lock Down Requirements

After /research-and-plan returns and before execution begins, create tracking requirement files for every sub-plan and the meta-plan itself. These files let any observer (or a re-run) know exactly what the pipeline expects to accomplish.

MAIN_ROOT=$(cd "$(git rev-parse --git-common-dir)/.." && pwd)

For each sub-plan index i (from 1 to N, where N is the number of sub-plans produced by /research-and-plan):

These integer markers are dispatch metadata, not enforcement (per Phase 1 design doc OQ1). The hook's enforcement globs only scan requires.*, fulfilled.*, and step.*. Using the meta.* prefix keeps them out of the scope-filter path by construction, making the metadata intent explicit in the marker basename.

for i in 1 2 ... N; do
  [ -n "$PIPELINE_ID" ] || { echo "tracking: empty PIPELINE_ID — refusing flat write" >&2; exit 1; }
  printf 'skill=draft-plan\nindex=%d\nrequiredBy=research-and-go\ncreatedAt=%s\n' "$i" "$(date -Iseconds)" > "$MAIN_ROOT/.zskills/tracking/$PIPELINE_ID/meta.draft-plan.$i"
  printf 'skill=run-plan\nindex=%d\nrequiredBy=research-and-go\ncreatedAt=%s\n' "$i" "$(date -Iseconds)" > "$MAIN_ROOT/.zskills/tracking/$PIPELINE_ID/meta.run-plan.$i"
done

Also create a metadata marker for the meta-plan execution itself:

[ -n "$PIPELINE_ID" ] || { echo "tracking: empty PIPELINE_ID — refusing flat write" >&2; exit 1; }
printf 'skill=run-plan\nid=meta\nrequiredBy=research-and-go\ncreatedAt=%s\n' "$(date -Iseconds)" > "$MAIN_ROOT/.zskills/tracking/$PIPELINE_ID/meta.run-plan.meta"

Replace 1 2 ... N with the actual sub-plan indices. The draft-plan metadata tracks the planning phase; the run-plan metadata tracks execution.

Pass tracking IDs to child skills: When dispatching /run-plan for each sub-plan, include the tracking index so child skills can mark their corresponding requirement as completed. For example, include tracking-index=3 in the dispatch prompt for sub-plan 3.

Step 2 — Execute

Landing mode detection

Before constructing the /run-plan invocation, detect whether the original $GOAL text contains pr or direct as a distinct word (same pattern as Phase 3a in /run-plan and /fix-issues, extended to recognize sentence punctuation .!? since this is prose-like goal text):

# Resolve $GOAL from the original description. /research-and-go's input
# is the broad goal text — orchestrators typically pass it as $ARGUMENTS
# or as $DESCRIPTION. Prefer existing $GOAL, then $DESCRIPTION, then
# $ARGUMENTS, so the regex below operates on a populated value.
GOAL="${GOAL:-${DESCRIPTION:-$ARGUMENTS}}"
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 original description passed to /research-and-go. If the goal text does not mention either keyword, LANDING_ARG stays empty and /run-plan falls back to its config default (normally cherry-pick). Do NOT pass a literal empty token to /run-plan — omit the argument entirely when LANDING_ARG="".

Construct the /run-plan cron prompt

Build the prompt conditionally to avoid empty-token confusion. The cron is one-shot (recurring: false). Chunked finish auto self-perpetuates via /run-plan Phase 5c -- each completed phase schedules the next turn. The user-facing every N argument on /run-plan is unaffected; this change only removes the hardcoded wrapper from /research-and-go's kickoff.

if [ -n "$LANDING_ARG" ]; then
  RUN_PROMPT="Run /run-plan $META_PLAN_PATH finish auto $LANDING_ARG"
else
  RUN_PROMPT="Run /run-plan $META_PLAN_PATH finish auto"
fi

Immediately run the resulting invocation -- conceptually:

/run-plan $META_PLAN_PATH finish auto [pr|direct]

Concrete examples:

• Goal "Add dark mode" -> /run-plan $META_PLAN_PATH finish auto
• Goal "Add thermal domain. PR." -> /run-plan $META_PLAN_PATH finish auto pr
• Goal "Refactor logs direct" -> /run-plan $META_PLAN_PATH finish auto direct

This executes all implementation phases sequentially -- each delegating to /run-plan on the corresponding sub-plan via chunked cron-fired turns. Full verification, testing, and landing at each phase.

Step 3 — Final cross-branch verification (scheduled by /run-plan, not here)

After the meta-plan's last sub-plan completes its last phase, /run-plan Phase 5c detects the requires.verify-changes.final.$META_PLAN_SLUG marker. It schedules:

1. A cron firing Run /verify-changes branch tracking-id=$META_PLAN_SLUG
2. A re-entry cron firing Run /run-plan $META_PLAN_PATH finish auto

The verify cron runs at top level (full Agent tool), performs cross-branch verification (git diff $(git merge-base origin/main HEAD)..HEAD), and on success writes fulfilled.verify-changes.final.$META_PLAN_SLUG. The re-entry cron then completes Phase 5b (mark plan complete) cleanly. The user sees the verify report as the final turn before the pipeline is truly complete.

Reference: scheduling logic lives in /run-plan Phase 5c (Phase A). This Step 3 is documentation only -- /research-and-go has already exited at the end of Step 2.

Pipeline Cleanup

Under chunked finish auto, /research-and-go Step 2 schedules a cron and exits -- Step 3 never runs in-session. Cleanup happens when the user (or a future automation) observes the pipeline is complete. Run the clear-tracking script — on the plugin install bash ${CLAUDE_PLUGIN_ROOT}/skills/update-zskills/scripts/clear-tracking.sh, or the legacy mirror path bash .claude/skills/update-zskills/scripts/clear-tracking.sh — (interactive) to wipe tracking. Do NOT auto-wipe -- requires.verify-changes.final.* and its fulfillment marker are pipeline-completion records that should survive until the user confirms the pipeline finished.

If the pipeline failed at any point, tracking is preserved for inspection and re-run. See Step 0 Re-run Handling for the resume protocol.

Key Rules

• No confirmation checkpoints. The user said go — that's blanket approval for decomposition, planning, and execution. Do not pause between steps.
• Failure still stops. If /run-plan hits the Failure Protocol (cherry-pick conflict, test failures after landing, verification fails after 2 cycles), it stops and reports. go means autonomous, not reckless.
• Sub-plan staleness refresh applies. If a later sub-plan depends on an earlier one, /run-plan auto-refreshes it via /draft-plan before execution (the staleness check in Phase 1 step 6).
• This is the top of the pipeline. The execution chain: /research-and-go → /research-and-plan → /draft-plan (×N) → /run-plan (meta) → /run-plan (×N sub-plans) → /verify-changes (×N) → /commit (×N landings).