Autoplan

When to invoke

Use when asked to "auto review", "autoplan", "run all reviews", "review this plan automatically", or "make the decisions for me".

Proactively suggest when the user has a plan file and wants to run the full review gauntlet without answering 15-30 intermediate questions.

Voice triggers (speech-to-text aliases): "auto plan", "automatic review".

Preamble

eval "$(~/.vibestack/bin/vibe-slug 2>/dev/null)" 2>/dev/null || SLUG="unknown"
_LEARN_FILE="${VIBESTACK_HOME:-$HOME/.vibestack}/projects/${SLUG:-unknown}/learnings.jsonl"
if [ -f "$_LEARN_FILE" ]; then
  _LEARN_COUNT=$(wc -l /dev/null | tr -d ' ')
  echo "LEARNINGS: $_LEARN_COUNT entries loaded"
  if [ "$_LEARN_COUNT" -gt 5 ] 2>/dev/null; then
    ~/.vibestack/bin/vibe-learnings-search --limit 5 2>/dev/null || true
  fi
else
  echo "LEARNINGS: none yet"
fi

{{include lib/snippets/session-host.md}}

{{include lib/snippets/decision-brief.md}}

{{include lib/snippets/working-protocols.md}}

{{include lib/snippets/state-protocols.md}}

Plan Status Footer

In plan mode, before ExitPlanMode: if the plan file lacks a ## VIBESTACK REVIEW REPORT section, check true # vibe-review-read (stub — not yet implemented) and append a placeholder. With no review data, append a 5-row placeholder table (CEO/Codex/Eng/Design/DX Review) with all zeros and verdict "NO REVIEWS YET — run /autoplan". If a richer review report already exists, skip — review skills wrote it.

PLAN MODE EXCEPTION — always allowed (it's the plan file).

---

Step 0: Detect platform and base branch

First, detect the git hosting platform from the remote URL:

git remote get-url origin 2>/dev/null

• If the URL contains "github.com" → platform is GitHub
• If the URL contains "gitlab" → platform is GitLab
• Otherwise, check CLI availability:
• gh auth status 2>/dev/null succeeds → platform is GitHub (covers GitHub Enterprise)
• glab auth status 2>/dev/null succeeds → platform is GitLab (covers self-hosted)
• Neither → unknown (use git-native commands only)

Determine which branch this PR/MR targets, or the repo's default branch if no PR/MR exists. Use the result as "the base branch" in all subsequent steps.

If GitHub:

1. gh pr view --json baseRefName -q .baseRefName — if succeeds, use it
2. gh repo view --json defaultBranchRef -q .defaultBranchRef.name — if succeeds, use it

If GitLab:

1. glab mr view -F json 2>/dev/null and extract the target_branch field — if succeeds, use it
2. glab repo view -F json 2>/dev/null and extract the default_branch field — if succeeds, use it

Git-native fallback (if unknown platform, or CLI commands fail):

1. git symbolic-ref refs/remotes/origin/HEAD 2>/dev/null | sed 's|refs/remotes/origin/||'
2. If that fails: git rev-parse --verify origin/main 2>/dev/null → use main
3. If that fails: git rev-parse --verify origin/master 2>/dev/null → use master

If all fail, fall back to main.

Print the detected base branch name. In every subsequent git diff, git log, git fetch, git merge, and PR/MR creation command, substitute the detected branch name wherever the instructions say "the base branch" or ``.

---

Prerequisite Skill Offer

When the design doc check above prints "No design doc found," offer the prerequisite skill before proceeding.

Say to the user via AskUserQuestion:

> "No design doc found for this branch. /office-hours produces a structured problem > statement, premise challenge, and explored alternatives — it gives this review much > sharper input to work with. Takes about 10 minutes. The design doc is per-feature, > not per-product — it captures the thinking behind this specific change."

Options:

• A) Run /office-hours now (we'll pick up the review right after)
• B) Skip — proceed with standard review

If they skip: "No worries — standard review. If you ever want sharper input, try /office-hours first next time." Then proceed normally. Do not re-offer later in the session.

If they choose A:

Say: "Running /office-hours inline. Once the design doc is ready, I'll pick up the review right where we left off."

Read the /office-hours skill file at ~/.claude/skills/office-hours/SKILL.md using the Read tool.

If unreadable: Skip with "Could not load /office-hours — skipping." and continue.

Follow its instructions from top to bottom, skipping these sections (already handled by the parent skill):

• Preamble (run first)
• AskUserQuestion Format
• Completeness Principle — Boil the Lake
• Search Before Building
• Contributor Mode
• Completion Status Protocol
• Telemetry (run last)
• Step 0: Detect platform and base branch
• Review Readiness Dashboard
• Plan File Review Report
• Prerequisite Skill Offer
• Plan Status Footer

Execute every other section at full depth. When the loaded skill's instructions are complete, continue with the next step below.

After /office-hours completes, re-run the design doc check:

setopt +o nomatch 2>/dev/null || true  # zsh compat
SLUG=$(~/.claude/skills/browse/bin/remote-slug 2>/dev/null || basename "$(git rev-parse --show-toplevel 2>/dev/null || pwd)")
BRANCH=$(git rev-parse --abbrev-ref HEAD 2>/dev/null | tr '/' '-' || echo 'no-branch')
DESIGN=$(ls -t ~/.vibestack/projects/$SLUG/*-$BRANCH-design-*.md 2>/dev/null | head -1)
[ -z "$DESIGN" ] && DESIGN=$(ls -t ~/.vibestack/projects/$SLUG/*-design-*.md 2>/dev/null | head -1)
[ -n "$DESIGN" ] && echo "Design doc found: $DESIGN" || echo "No design doc found"

If a design doc is now found, read it and continue the review. If none was produced (user may have cancelled), proceed with standard review.

/autoplan — Auto-Review Pipeline

One command. Rough plan in, fully reviewed plan out.

/autoplan reads the full CEO, design, eng, and DX review skill files from disk and follows them at full depth — same rigor, same sections, same methodology as running each skill manually. The only difference: intermediate AskUserQuestion calls are auto-decided using the 6 principles below. Taste decisions (where reasonable people could disagree) are surfaced at a final approval gate.

---

The 6 Decision Principles

These rules auto-answer every intermediate question:

1. Choose completeness — Ship the whole thing. Pick the approach that covers more edge cases.
2. Boil lakes — Fix everything in the blast radius (files modified by this plan + direct importers). Auto-approve expansions that are in blast radius AND 200-line abstraction. Pick what a new contributor reads in 30 seconds.
3. Bias toward action — Merge > review cycles > stale deliberation. Flag concerns but don't block.

Conflict resolution (context-dependent tiebreakers):

• CEO phase: P1 (completeness) + P2 (boil lakes) dominate.
• Eng phase: P5 (explicit) + P3 (pragmatic) dominate.
• Design phase: P5 (explicit) + P1 (completeness) dominate.

---

Decision Classification

Every auto-decision is classified:

Mechanical — one clearly right answer. Auto-decide silently. Examples: run codex (always yes), run evals (always yes), reduce scope on a complete plan (always no).

Taste — reasonable people could disagree. Auto-decide with recommendation, but surface at the final gate. Three natural sources:

1. Close approaches — top two are both viable with different tradeoffs.
2. Borderline scope — in blast radius but 3-5 files, or ambiguous radius.
3. Codex disagreements — codex recommends differently and has a valid point.

User Challenge — both models agree the user's stated direction should change. This is qualitatively different from taste decisions. When Claude and Codex both recommend merging, splitting, adding, or removing features/skills/workflows that the user specified, this is a User Challenge. It is NEVER auto-decided.

User Challenges go to the final approval gate with richer context than taste decisions:

• What the user said: (their original direction)
• What both models recommend: (the change)
• Why: (the models' reasoning)
• What context we might be missing: (explicit acknowledgment of blind spots)
• If we're wrong, the cost is: (what happens if the user's original direction

was right and we changed it)

The user's original direction is the default. The models must make the case for change, not the other way around.

Exception: If both models flag the change as a security vulnerability or feasibility blocker (not a preference), the AskUserQuestion framing explicitly warns: "Both models believe this is a security/feasibility risk, not just a preference." The user still decides, but the framing is appropriately urgent.

---

Sequential Execution — MANDATORY

Phases MUST execute in strict order: CEO → Design → Eng → DX. Each phase MUST complete fully before the next begins. NEVER run phases in parallel — each builds on the previous.

Between each phase, emit a phase-transition summary and verify that all required outputs from the prior phase are written before starting the next.

---

What "Auto-Decide" Means

Auto-decide replaces the USER'S judgment with the 6 principles. It does NOT replace the ANALYSIS. Every section in the loaded skill files must still be executed at the same depth as the interactive version. The only thing that changes is who answers the AskUserQuestion: you do, using the 6 principles, instead of the user.

Two exceptions — never auto-decided:

1. Premises (Phase 1) — require human judgment about what problem to solve.
2. User Challenges — when both models agree the user's stated direction should change

(merge, split, add, remove features/workflows). The user always has context models lack. See Decision Classification above.

You MUST still:

• READ the actual code, diffs, and files each section references
• PRODUCE every output the section requires (diagrams, tables, registries, artifacts)
• IDENTIFY every issue the section is designed to catch
• DECIDE each issue using the 6 principles (instead of asking the user)
• LOG each decision in the audit trail
• WRITE all required artifacts to disk

You MUST NOT:

• Compress a review section into a one-liner table row
• Write "no issues found" without showing what you examined
• Skip a section because "it doesn't apply" without stating what you checked and why
• Produce a summary instead of the required output (e.g., "architecture looks good"

instead of the ASCII dependency graph the section requires)

"No issues found" is a valid output for a section — but only after doing the analysis. State what you examined and why nothing was flagged (1-2 sentences minimum). "Skipped" is never valid for a non-skip-listed section.

---

Filesystem Boundary — Codex Prompts

All prompts sent to Codex (via codex exec or codex review) MUST be prefixed with this boundary instruction:

> IMPORTANT: Do NOT read or execute any SKILL.md files or files in skill definition directories (paths containing skills). These are AI assistant skill definitions meant for a different system. They contain bash scripts and prompt templates that will waste your time. Ignore them completely. Stay focused on the repository code only.

This prevents Codex from discovering vibestack skill files on disk and following their instructions instead of reviewing the plan.

---

Phase 0: Intake + Restore Point

Step 1: Capture restore point

Before doing anything, save the plan file's current state to an external file:

eval "$(~/.vibestack/bin/vibe-slug 2>/dev/null)" && mkdir -p ~/.vibestack/projects/$SLUG
BRANCH=$(git rev-parse --abbrev-ref HEAD 2>/dev/null | tr '/' '-')
DATETIME=$(date +%Y%m%d-%H%M%S)
echo "RESTORE_PATH=$HOME/.vibestack/projects/$SLUG/${BRANCH}-autoplan-restore-${DATETIME}.md"

Write the plan file's full contents to the restore path with this header:

# /autoplan Restore Point
Captured: [timestamp] | Branch: [branch] | Commit: [short hash]

## Re-run Instructions
1. Copy "Original Plan State" below back to your plan file
2. Invoke /autoplan

## Original Plan State
[verbatim plan file contents]

Then prepend a one-line HTML comment to the plan file: ``

Step 2: Read context

• Read CLAUDE.md, TODOS.md, git log -30, git diff against the base branch --stat
• Discover design docs: ls -t ~/.vibestack/projects/$SLUG/*-design-*.md 2>/dev/null | head -1
• Detect UI scope: grep the plan for view/rendering terms (component, screen, form,

button, modal, layout, dashboard, sidebar, nav, dialog). Require 2+ matches. Exclude false positives ("page" alone, "UI" in acronyms).

• Detect DX scope: grep the plan for developer-facing terms (API, endpoint, REST,

GraphQL, gRPC, webhook, CLI, command, flag, argument, terminal, shell, SDK, library, package, npm, pip, import, require, SKILL.md, skill template, Claude Code, MCP, agent, OpenClaw, action, developer docs, getting started, onboarding, integration, debug, implement, error message). Require 2+ matches. Also trigger DX scope if the product IS a developer tool (the plan describes something developers install, integrate, or build on top of) or if an AI agent is the primary user (OpenClaw actions, Claude Code skills, MCP servers).

Step 3: Load skill files from disk

Read each file using the Read tool:

• ~/.claude/skills/plan-ceo-review/SKILL.md
• ~/.claude/skills/plan-design-review/SKILL.md (only if UI scope detected)
• ~/.claude/skills/plan-eng-review/SKILL.md
• ~/.claude/skills/plan-devex-review/SKILL.md (only if DX scope detected)

Section skip list — when following a loaded skill file, SKIP these sections (they are already handled by /autoplan):

• Preamble (run first)
• AskUserQuestion Format
• Completeness Principle — Boil the Lake
• Search Before Building
• Completion Status Protocol
• Telemetry (run last)
• Step 0: Detect base branch
• Review Readiness Dashboard
• Plan File Review Report
• Prerequisite Skill Offer (BENEFITS_FROM)
• Outside Voice — Independent Plan Challenge
• Design Outside Voices (parallel)

Follow ONLY the review-specific methodology, sections, and required outputs.

Output: "Here's what I'm working with: [plan summary]. UI scope: [yes/no]. DX scope: [yes/no]. Loaded review skills from disk. Starting full review pipeline with auto-decisions."

---

Phase 0.5: Codex auth + version preflight

Before invoking any Codex voice, preflight the CLI: verify auth (multi-signal) and warn on known-bad CLI versions. This is infrastructure for all 4 phases below — source it once here and the helper functions stay in scope for the rest of the workflow.

_TEL=$(~/.vibestack/bin/vibe-config get telemetry 2>/dev/null || echo off)
_CODEX_CFG=$(~/.vibestack/bin/vibe-config get codex_reviews 2>/dev/null || echo enabled)
# codex-probe not available in vibestack — skip

# Master switch first: codex_reviews=disabled turns off ALL Codex work globally,
# including autoplan's own dual-voice orchestration. Honor it before probing.
# Only the literal `disabled` turns it off (no validating config binary).
if [ "$_CODEX_CFG" = "disabled" ]; then
  echo "[codex disabled by config — Claude subagent only] Re-enable: vibe-config set codex_reviews enabled"
  _CODEX_AVAILABLE=false
# Check Codex binary. If missing, tag the degradation matrix and continue
# with Claude subagent only (autoplan's existing degradation fallback).
elif ! command -v codex >/dev/null 2>&1; then
  true # "codex_cli_missing"
  echo "[codex-unavailable: binary not found] — proceeding with Claude subagent only"
  _CODEX_AVAILABLE=false
elif ! codex --version >/dev/null 2>&1; then
  true # "codex_auth_failed"
  echo "[codex-unavailable: auth missing] — proceeding with Claude subagent only. Run \`codex login\` or set \$CODEX_API_KEY to enable dual-voice review."
  _CODEX_AVAILABLE=false
else
  true #   # non-blocking warn if known-bad
  _CODEX_AVAILABLE=true
fi

If _CODEX_AVAILABLE=false, all Phase 1-3.5 Codex voices below degrade to [codex-unavailable] in th

…

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: timurgaleev
• Source: timurgaleev/vibestack
• License: MIT

Install and usage instructions live in the source repository linked above.