445 lines
19 KiB
Markdown
445 lines
19 KiB
Markdown
---
|
|
name: autoplan
|
|
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 approac"
|
|
---
|
|
|
|
---
|
|
|
|
## 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 question:
|
|
|
|
> "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 from disk using the Read tool:
|
|
`${GSTACK_OPENCODE_DIR}/office-hours/SKILL.md`
|
|
|
|
Follow it inline, **skipping these sections** (already handled by the parent skill):
|
|
- Preamble (run first)
|
|
- question Format
|
|
- Completeness Principle — Boil the Lake
|
|
- Search Before Building
|
|
- Contributor Mode
|
|
- Completion Status Protocol
|
|
- Telemetry (run last)
|
|
|
|
If the Read fails (file not found), say:
|
|
"Could not load /office-hours — proceeding with standard review."
|
|
|
|
After /office-hours completes, re-run the design doc check:
|
|
```bash
|
|
SLUG=$(${GSTACK_OPENCODE_DIR}/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 ~/.gstack/projects/$SLUG/*-$BRANCH-design-*.md 2>/dev/null | head -1)
|
|
[ -z "$DESIGN" ] && DESIGN=$(ls -t ~/.gstack/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, 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 question 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.
|
|
|
|
---
|
|
|
|
## 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
|
|
question: you do, using the 6 principles, instead of the user.
|
|
|
|
**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.
|
|
|
|
---
|
|
|
|
## 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
|
|
eval "$(${GSTACK_OPENCODE_DIR}/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:
|
|
- `${GSTACK_OPENCODE_DIR}/plan-ceo-review/SKILL.md`
|
|
- `${GSTACK_OPENCODE_DIR}/plan-design-review/SKILL.md` (only if UI scope detected)
|
|
- `${GSTACK_OPENCODE_DIR}/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)
|
|
- question 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 question → 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 question
|
|
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.
|
|
|
|
**Required execution checklist (CEO):**
|
|
|
|
Step 0 (0A-0F) — run each sub-step and produce:
|
|
- 0A: Premise challenge with specific premises named and evaluated
|
|
- 0B: Existing code leverage map (sub-problems → existing code)
|
|
- 0C: Dream state diagram (CURRENT → THIS PLAN → 12-MONTH IDEAL)
|
|
- 0C-bis: Implementation alternatives table (2-3 approaches with effort/risk/pros/cons)
|
|
- 0D: Mode-specific analysis with scope decisions logged
|
|
- 0E: Temporal interrogation (HOUR 1 → HOUR 6+)
|
|
- 0F: Mode selection confirmation
|
|
|
|
Sections 1-10 — for EACH section, run the evaluation criteria from the loaded skill file:
|
|
- Sections WITH findings: full analysis, auto-decide each issue, log to audit trail
|
|
- Sections with NO findings: 1-2 sentences stating what was examined and why nothing
|
|
was flagged. NEVER compress a section to just its name in a table row.
|
|
- Section 11 (Design): run only if UI scope was detected in Phase 0
|
|
|
|
**Mandatory outputs from Phase 1:**
|
|
- "NOT in scope" section with deferred items and rationale
|
|
- "What already exists" section mapping sub-problems to existing code
|
|
- Error & Rescue Registry table (from Section 2)
|
|
- Failure Modes Registry table (from review sections)
|
|
- Dream state delta (where this plan leaves us vs 12-month ideal)
|
|
- Completion Summary (the full summary table from the CEO skill)
|
|
|
|
---
|
|
|
|
## Phase 2: Design Review (conditional — skip if no UI scope)
|
|
|
|
Follow plan-design-review/SKILL.md — all 7 dimensions, full depth.
|
|
Override: every question → 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 question → 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
|
|
|
|
**Required execution checklist (Eng):**
|
|
|
|
1. Step 0 (Scope Challenge): Read actual code referenced by the plan. Map each
|
|
sub-problem to existing code. Run the complexity check. Produce concrete findings.
|
|
|
|
2. Step 0.5 (Codex): Run if available. Present full output under CODEX SAYS header.
|
|
|
|
3. Section 1 (Architecture): Produce ASCII dependency graph showing new components
|
|
and their relationships to existing ones. Evaluate coupling, scaling, security.
|
|
|
|
4. Section 2 (Code Quality): Identify DRY violations, naming issues, complexity.
|
|
Reference specific files and patterns. Auto-decide each finding.
|
|
|
|
5. **Section 3 (Test Review) — NEVER SKIP OR COMPRESS.**
|
|
This section requires reading actual code, not summarizing from memory.
|
|
- Read the diff or the plan's affected files
|
|
- Build the test diagram: list every NEW UX flow, data flow, codepath, and branch
|
|
- For EACH item in the diagram: what type of test covers it? Does one exist? Gaps?
|
|
- For LLM/prompt changes: which eval suites must run?
|
|
- Auto-deciding test gaps means: identify the gap → decide whether to add a test
|
|
or defer (with rationale and principle) → log the decision. It does NOT mean
|
|
skipping the analysis.
|
|
- Write the test plan artifact to disk
|
|
|
|
6. Section 4 (Performance): Evaluate N+1 queries, memory, caching, slow paths.
|
|
|
|
**Mandatory outputs from Phase 3:**
|
|
- "NOT in scope" section
|
|
- "What already exists" section
|
|
- Architecture ASCII diagram (Section 1)
|
|
- Test diagram mapping codepaths to coverage (Section 3)
|
|
- Test plan artifact written to disk (Section 3)
|
|
- Failure modes registry with critical gap flags
|
|
- Completion Summary (the full summary from the Eng skill)
|
|
- TODOS.md updates (collected from all phases)
|
|
|
|
---
|
|
|
|
## 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.
|
|
|
|
---
|
|
|
|
## Pre-Gate Verification
|
|
|
|
Before presenting the Final Approval Gate, verify that required outputs were actually
|
|
produced. Check the plan file and conversation for each item.
|
|
|
|
**Phase 1 (CEO) outputs:**
|
|
- [ ] Premise challenge with specific premises named (not just "premises accepted")
|
|
- [ ] All applicable review sections have findings OR explicit "examined X, nothing flagged"
|
|
- [ ] Error & Rescue Registry table produced (or noted N/A with reason)
|
|
- [ ] Failure Modes Registry table produced (or noted N/A with reason)
|
|
- [ ] "NOT in scope" section written
|
|
- [ ] "What already exists" section written
|
|
- [ ] Dream state delta written
|
|
- [ ] Completion Summary produced
|
|
|
|
**Phase 2 (Design) outputs — only if UI scope detected:**
|
|
- [ ] All 7 dimensions evaluated with scores
|
|
- [ ] Issues identified and auto-decided
|
|
|
|
**Phase 3 (Eng) outputs:**
|
|
- [ ] Scope challenge with actual code analysis (not just "scope is fine")
|
|
- [ ] Architecture ASCII diagram produced
|
|
- [ ] Test diagram mapping codepaths to test coverage
|
|
- [ ] Test plan artifact written to disk at ~/.gstack/projects/$SLUG/
|
|
- [ ] "NOT in scope" section written
|
|
- [ ] "What already exists" section written
|
|
- [ ] Failure modes registry with critical gap assessment
|
|
- [ ] Completion Summary produced
|
|
|
|
**Audit trail:**
|
|
- [ ] Decision Audit Trail has at least one row per auto-decision (not empty)
|
|
|
|
If ANY checkbox above is missing, go back and produce the missing output. Max 2
|
|
attempts — if still missing after retrying twice, proceed to the gate with a warning
|
|
noting which items are incomplete. Do not loop indefinitely.
|
|
|
|
---
|
|
|
|
## Phase 4: Final Approval Gate
|
|
|
|
**STOP here and present the final state to the user.**
|
|
|
|
Present as a message, then use question:
|
|
|
|
```
|
|
## /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."
|
|
|
|
question 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)
|
|
|
|
${GSTACK_OPENCODE_DIR}/bin/gstack-review-log '{"skill":"plan-ceo-review","timestamp":"'"$TIMESTAMP"'","status":"clean","unresolved":0,"critical_gaps":0,"mode":"SELECTIVE_EXPANSION","via":"autoplan","commit":"'"$COMMIT"'"}'
|
|
|
|
${GSTACK_OPENCODE_DIR}/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
|
|
${GSTACK_OPENCODE_DIR}/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 question 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 means full depth.** Do not compress or skip sections from the loaded skill files (except the skip list in Phase 0). "Full depth" means: read the code the section asks you to read, produce the outputs the section requires, identify every issue, and decide each one. A one-sentence summary of a section is not "full depth" — it is a skip. If you catch yourself writing fewer than 3 sentences for any review section, you are likely compressing.
|
|
- **Artifacts are deliverables.** Test plan artifact, failure modes registry, error/rescue table, ASCII diagrams — these must exist on disk or in the plan file when the review completes. If they don't exist, the review is incomplete.
|
|
- **Sequential order.** CEO → Design → Eng. Each phase builds on the last.
|