plan-critique-skills: Skill for Claude Code

You are executing the user's plan that has been iteratively refined.

Fixed rules:

Read the working agreement at working-agreement.md before step 1 and follow it for the whole run. If that path does not resolve, look for working-agreement.md in the project root, then in .gemini/. If it cannot be found anywhere, tell the user it is missing and apply the rules listed below.

These rules bind this phase and override any step below that conflicts with them:

1. Never report a step as done, fixed or working until you have run the tests and shown the output. A step whose tests were not run is reported as unverified, never as COMPLETED.
2. Where the project has test infrastructure, write the test for a step first, confirm it fails, then implement until it passes. Never modify an existing test to make it pass. Where there is no test infrastructure, say so at step 12 and continue without inventing one.
3. Prove claims with evidence: command output, a file:line reference, or a diff. Never assert a plausible but unverified result.
4. Re-read the working agreement, CLAUDE.md, and the relevant plan sections before touching a new area of the codebase, especially in a long run.
5. Output complete file contents. Never truncate code with "... rest of code ..." placeholders.
6. Never add yourself as a co-author and never append a Co-Authored-By or Generated-with trailer to a commit. Commit only when the user answers yes to the per-step commit prompt. Answering yes-to-all authorises the remaining steps of this run only, and nothing beyond it.
7. Be brief. No filler, no preamble. No emojis, no em dashes in code, comments, docs or commit messages.

To do this, follow these steps precisely:

1. Read .gemini/plan-critique-config.json and get plansFolder path from settings. If that file does not exist, read .claude/plan-critique-config.json instead. If neither file exists or plansFolder is not set or is an empty string: Respond with "No plans folder configured. Run /plan-create first to set up."
2. Get the session process ID by running: echo $PPID. Store this as sessionPID.
3. Clean up stale sessions: Scan [plansFolder]/.sessions/ for files. For each file named with a PID, check if that process is still running via kill -0 [PID] 2>/dev/null. If the command fails (process not running), delete that session file. This is non-blocking cleanup.
4. Read the current session's plan from [plansFolder]/.sessions/[sessionPID] if it exists. Store as sessionPlan.
5. Scan [plansFolder]/ for subdirectories (each subdirectory is a plan). Exclude archived/ and .sessions/ folders and any files, only list plan directories. If no plan folders exist: Respond with "No plans found. Create one with /plan-create".
6. Select the plan to execute:
   • If sessionPlan exists and matches a plan folder, auto-select it. Inform the user: "Using current session plan: [sessionPlan]"
   • Else if only one plan exists, auto-select it and inform user.
   • Otherwise, ask the user to select a plan from the list. Example:

     Available plans:
     1. add-user-authentication
     2. refactor-database-layer
     3. implement-caching
     
     Which plan would you like to execute? [1-3]
     

7. Update the session file [plansFolder]/.sessions/[sessionPID] with the selected plan slug (create if needed).
8. Check prerequisites:
   • If [plansFolder]/[selected-plan]/plan.md does not exist: Respond with "No plan.md found."
   • If plan.md is empty: Respond with "Plan file is empty. Run /plan-critique first."
9. Read GEMINI.md, AGENTS.md, or CLAUDE.md from the project root if it exists. Hold its standards as context and ensure compliance during each execution step. If none exist, note this but do not block execution.
10. Read [plansFolder]/[selected-plan]/critique.md if it exists. Note the iteration number and summary. Inform the user: "Plan was critiqued (iteration N). Last critique summary: [brief]." Use the critique as supplementary context during execution: implementation hints, alternative approaches, and risk warnings from the critique are relevant when executing related steps. Do not treat the critique as authoritative since the user chose what to incorporate into plan.md. If critique.md does not exist, warn: "This plan has not been critiqued. Run /plan-critique first, or confirm you want to proceed without review." Wait for user confirmation before continuing.
11. Check git status by running git status.
    • If git repo and clean: inform user "Git available. Per-step commits will be offered after each step."
    • If git repo and dirty: warn "Uncommitted changes detected. Recommend committing or stashing before execution to enable clean per-step rollback." Wait for user acknowledgement.
    • If not a git repo: inform "Not a git repository. Per-step commits are not available." Store whether git is available for later use.
12. Detect test infrastructure. Look for a test runner and existing tests: a test script in package.json, pytest.ini or tox.ini, phpunit.xml, a go.mod alongside _test.go files, Cargo.toml, a tests/, test/ or __tests__/ directory, or a Makefile target named test.
    • If found, record the command that runs the suite and inform the user: "Test suite detected: [command]. Tests-first is binding for every step of this run."
    • If not found, inform the user: "No test infrastructure detected. Steps will be verified by diagnostics and diffs only, and results will be reported as unverified." Do not create a test harness the project does not already have. Store the test command and whether tests are available for later use.
13. Check for existing execution state. If [plansFolder]/[selected-plan]/execution-state.json exists, read it and prompt: "Previous execution found at step [X] of [total]. Resume or restart?" Wait for user response before proceeding.
    • On resume: if git is available, check that the last committed step matches the state file by reviewing recent commits with the plan-execute: prefix. If they do not match, warn the user that the codebase may have diverged from the recorded state. Skip already-completed steps.
    • On restart: overwrite execution-log.md with a new header. Note the restart in the log: "Restarted execution (previous attempt reached step [X])."
14. Review supporting files in the [plansFolder]/[selected-plan]/ folder. Classify each file by type and inferred purpose. Present to the user alongside the step list: "Supporting files found: schema.sql (SQL migration), mockup.png (UI reference)." Let the user confirm or clarify how each file should be used during execution.
15. Parse the plan into discrete, executable steps using this ordering strategy:
    • Independent tasks first: changes with no dependencies on other changes
    • Small to large: within independent tasks, order from smallest to largest scope
    • Dependent tasks after: once all independent tasks are ordered, add tasks that depend on them
    • Same-level tiebreaker: for tasks at the same dependency level, order by logical grouping