mirror of
https://github.com/garrytan/gstack.git
synced 2026-07-07 00:27:56 +02:00
feat: /autoplan — auto-review pipeline (v0.10.0.0) (#327)
* feat: /autoplan skill — auto-review pipeline with decision audit trail Thin orchestrator that reads CEO, design, and eng review skills from disk and runs them at full depth with auto-decisions using 6 encoded principles. Surfaces taste decisions at a final approval gate. * chore: wire /autoplan into routing, touchfiles, and validation tests * chore: bump version and changelog (v0.10.0.0) Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> --------- Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>
This commit is contained in:
Garry Tan
@@ -0,0 +1,288 @@
|
||||
---
|
||||
name: autoplan
|
||||
version: 1.0.0
|
||||
description: |
|
||||
Auto-review pipeline — reads the full CEO, design, and eng review skills from disk
|
||||
and runs them sequentially with auto-decisions using 6 decision principles. Surfaces
|
||||
taste decisions (close approaches, borderline scope, codex disagreements) at a final
|
||||
approval gate. One command, fully reviewed plan out.
|
||||
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.
|
||||
benefits-from: [office-hours]
|
||||
allowed-tools:
|
||||
- Bash
|
||||
- Read
|
||||
- Write
|
||||
- Edit
|
||||
- Glob
|
||||
- Grep
|
||||
- WebSearch
|
||||
- AskUserQuestion
|
||||
---
|
||||
|
||||
{{PREAMBLE}}
|
||||
|
||||
{{BASE_BRANCH_DETECT}}
|
||||
|
||||
{{BENEFITS_FROM}}
|
||||
|
||||
# /autoplan — Auto-Review Pipeline
|
||||
|
||||
One command. Rough plan in, fully reviewed plan out.
|
||||
|
||||
/autoplan reads the full CEO, design, and eng 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 < 1 day CC effort (< 5 files, no new infra).
|
||||
3. **Pragmatic** — If two options fix the same thing, pick the cleaner one. 5 seconds choosing, not 5 minutes.
|
||||
4. **DRY** — Duplicates existing functionality? Reject. Reuse what exists.
|
||||
5. **Explicit over clever** — 10-line obvious fix > 200-line abstraction. Pick what a new contributor reads in 30 seconds.
|
||||
6. **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.
|
||||
|
||||
---
|
||||
|
||||
## Phase 0: Intake + Restore Point
|
||||
|
||||
### Step 1: Capture restore point
|
||||
|
||||
Before doing anything, save the plan file's current state to an external file:
|
||||
|
||||
```bash
|
||||
source <(~/.claude/skills/gstack/bin/gstack-slug 2>/dev/null) && mkdir -p ~/.gstack/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/.gstack/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:
|
||||
`<!-- /autoplan restore point: [RESTORE_PATH] -->`
|
||||
|
||||
### Step 2: Read context
|
||||
|
||||
- Read CLAUDE.md, TODOS.md, git log -30, git diff against the base branch --stat
|
||||
- Discover design docs: `ls -t ~/.gstack/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).
|
||||
|
||||
### Step 3: Load skill files from disk
|
||||
|
||||
Read each file using the Read tool:
|
||||
- `~/.claude/skills/gstack/plan-ceo-review/SKILL.md`
|
||||
- `~/.claude/skills/gstack/plan-design-review/SKILL.md` (only if UI scope detected)
|
||||
- `~/.claude/skills/gstack/plan-eng-review/SKILL.md`
|
||||
|
||||
**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
|
||||
- Contributor Mode
|
||||
- Completion Status Protocol
|
||||
- Telemetry (run last)
|
||||
- Step 0: Detect base branch
|
||||
- Review Readiness Dashboard
|
||||
- Plan File Review Report
|
||||
- Prerequisite Skill Offer (BENEFITS_FROM)
|
||||
|
||||
Follow ONLY the review-specific methodology, sections, and required outputs.
|
||||
|
||||
Output: "Here's what I'm working with: [plan summary]. UI scope: [yes/no].
|
||||
Loaded review skills from disk. Starting full review pipeline with auto-decisions."
|
||||
|
||||
---
|
||||
|
||||
## Phase 1: CEO Review (Strategy & Scope)
|
||||
|
||||
Follow plan-ceo-review/SKILL.md — all sections, full depth.
|
||||
Override: every AskUserQuestion → auto-decide using the 6 principles.
|
||||
|
||||
**Override rules:**
|
||||
- Mode selection: SELECTIVE EXPANSION
|
||||
- Premises: accept reasonable ones (P6), challenge only clearly wrong ones
|
||||
- **GATE: Present premises to user for confirmation** — this is the ONE AskUserQuestion
|
||||
that is NOT auto-decided. Premises require human judgment.
|
||||
- Alternatives: pick highest completeness (P1). If tied, pick simplest (P5).
|
||||
If top 2 are close → mark TASTE DECISION.
|
||||
- Scope expansion: in blast radius + <1d CC → approve (P2). Outside → defer to TODOS.md (P3).
|
||||
Duplicates → reject (P4). Borderline (3-5 files) → mark TASTE DECISION.
|
||||
- All 10 review sections: run fully, auto-decide each issue, log every decision.
|
||||
|
||||
---
|
||||
|
||||
## Phase 2: Design Review (conditional — skip if no UI scope)
|
||||
|
||||
Follow plan-design-review/SKILL.md — all 7 dimensions, full depth.
|
||||
Override: every AskUserQuestion → auto-decide using the 6 principles.
|
||||
|
||||
**Override rules:**
|
||||
- Focus areas: all relevant dimensions (P1)
|
||||
- Structural issues (missing states, broken hierarchy): auto-fix (P5)
|
||||
- Aesthetic/taste issues: mark TASTE DECISION
|
||||
- Design system alignment: auto-fix if DESIGN.md exists and fix is obvious
|
||||
|
||||
---
|
||||
|
||||
## Phase 3: Eng Review + Codex
|
||||
|
||||
Follow plan-eng-review/SKILL.md — all sections, full depth.
|
||||
Override: every AskUserQuestion → auto-decide using the 6 principles.
|
||||
|
||||
**Override rules:**
|
||||
- Scope challenge: never reduce (P2)
|
||||
- Codex review: always run if available (P6)
|
||||
Command: `codex exec "Review this plan for architectural issues, missing edge cases, and hidden complexity. Be adversarial. File: <plan_path>" -s read-only --enable web_search_cached`
|
||||
Timeout: 10 minutes, then proceed with "Codex timed out — single-reviewer mode"
|
||||
- Architecture choices: explicit over clever (P5). If codex disagrees with valid reason → TASTE DECISION.
|
||||
- Evals: always include all relevant suites (P1)
|
||||
- Test plan: generate artifact at `~/.gstack/projects/$SLUG/{user}-{branch}-test-plan-{datetime}.md`
|
||||
- TODOS.md: collect all deferred scope expansions from Phase 1, auto-write
|
||||
|
||||
---
|
||||
|
||||
## Decision Audit Trail
|
||||
|
||||
After each auto-decision, append a row to the plan file using Edit:
|
||||
|
||||
```markdown
|
||||
<!-- AUTONOMOUS DECISION LOG -->
|
||||
## Decision Audit Trail
|
||||
|
||||
| # | Phase | Decision | Principle | Rationale | Rejected |
|
||||
|---|-------|----------|-----------|-----------|----------|
|
||||
```
|
||||
|
||||
Write one row per decision incrementally (via Edit). This keeps the audit on disk,
|
||||
not accumulated in conversation context.
|
||||
|
||||
---
|
||||
|
||||
## Phase 4: Final Approval Gate
|
||||
|
||||
**STOP here and present the final state to the user.**
|
||||
|
||||
Present as a message, then use AskUserQuestion:
|
||||
|
||||
```
|
||||
## /autoplan Review Complete
|
||||
|
||||
### Plan Summary
|
||||
[1-3 sentence summary]
|
||||
|
||||
### Decisions Made: [N] total ([M] auto-decided, [K] choices for you)
|
||||
|
||||
### Your Choices (taste decisions)
|
||||
[For each taste decision:]
|
||||
**Choice [N]: [title]** (from [phase])
|
||||
I recommend [X] — [principle]. But [Y] is also viable:
|
||||
[1-sentence downstream impact if you pick Y]
|
||||
|
||||
### Auto-Decided: [M] decisions [see Decision Audit Trail in plan file]
|
||||
|
||||
### Review Scores
|
||||
- CEO: [summary]
|
||||
- Design: [summary or "skipped, no UI scope"]
|
||||
- Eng: [summary]
|
||||
- Codex: [summary or "unavailable"]
|
||||
|
||||
### Deferred to TODOS.md
|
||||
[Items auto-deferred with reasons]
|
||||
```
|
||||
|
||||
**Cognitive load management:**
|
||||
- 0 taste decisions: skip "Your Choices" section
|
||||
- 1-7 taste decisions: flat list
|
||||
- 8+: group by phase. Add warning: "This plan had unusually high ambiguity ([N] taste decisions). Review carefully."
|
||||
|
||||
AskUserQuestion options:
|
||||
- A) Approve as-is (accept all recommendations)
|
||||
- B) Approve with overrides (specify which taste decisions to change)
|
||||
- C) Interrogate (ask about any specific decision)
|
||||
- D) Revise (the plan itself needs changes)
|
||||
- E) Reject (start over)
|
||||
|
||||
**Option handling:**
|
||||
- A: mark APPROVED, write review logs, suggest /ship
|
||||
- B: ask which overrides, apply, re-present gate
|
||||
- C: answer freeform, re-present gate
|
||||
- D: make changes, re-run affected phases (scope→1B, design→2, test plan→3, arch→3). Max 3 cycles.
|
||||
- E: start over
|
||||
|
||||
---
|
||||
|
||||
## Completion: Write Review Logs
|
||||
|
||||
On approval, write 3 separate review log entries so /ship's dashboard recognizes them:
|
||||
|
||||
```bash
|
||||
COMMIT=$(git rev-parse --short HEAD 2>/dev/null)
|
||||
TIMESTAMP=$(date -u +%Y-%m-%dT%H:%M:%SZ)
|
||||
|
||||
~/.claude/skills/gstack/bin/gstack-review-log '{"skill":"plan-ceo-review","timestamp":"'"$TIMESTAMP"'","status":"clean","unresolved":0,"critical_gaps":0,"mode":"SELECTIVE_EXPANSION","via":"autoplan","commit":"'"$COMMIT"'"}'
|
||||
|
||||
~/.claude/skills/gstack/bin/gstack-review-log '{"skill":"plan-eng-review","timestamp":"'"$TIMESTAMP"'","status":"clean","unresolved":0,"critical_gaps":0,"issues_found":0,"mode":"FULL_REVIEW","via":"autoplan","commit":"'"$COMMIT"'"}'
|
||||
```
|
||||
|
||||
If Phase 2 ran (UI scope):
|
||||
```bash
|
||||
~/.claude/skills/gstack/bin/gstack-review-log '{"skill":"plan-design-review","timestamp":"'"$TIMESTAMP"'","status":"clean","unresolved":0,"via":"autoplan","commit":"'"$COMMIT"'"}'
|
||||
```
|
||||
|
||||
Replace field values with actual counts from the review.
|
||||
|
||||
Suggest next step: `/ship` when ready to create the PR.
|
||||
|
||||
---
|
||||
|
||||
## Important Rules
|
||||
|
||||
- **Never abort.** The user chose /autoplan. Respect that choice. Surface all taste decisions, never redirect to interactive review.
|
||||
- **Premises are the one gate.** The only non-auto-decided AskUserQuestion is the premise confirmation in Phase 1.
|
||||
- **Log every decision.** No silent auto-decisions. Every choice gets a row in the audit trail.
|
||||
- **Full depth.** Do not compress or skip sections from the loaded skill files (except the skip list in Phase 0).
|
||||
- **Sequential order.** CEO → Design → Eng. Each phase builds on the last.
|
||||
Reference in New Issue
Block a user