@jhlee0619/codexloop 0.1.0

package/skills/cloop/SKILL.md

@@ -0,0 +1,177 @@
+---
+name: cloop
+description: Drive iterative improvement loops through the `cloop` shell command (CodexLoop). Use ONLY when the user's request explicitly contains one of `cloop`, `codexloop`, `CodexLoop`, or `CODEXLOOP` by name (case-insensitive match). Do NOT activate this skill for generic iterative phrasing like "iteratively fix X", "keep trying until tests pass", or "loop until it works". When activated, walk the user through goal clarification + plan approval BEFORE invoking `cloop start`.
+metadata:
+  short-description: Iterate with CodexLoop when the user asks for it by name
+---
+
+# CodexLoop (cloop)
+
+`cloop` is a shell command that drives Codex through strict evaluate →
+suggest → rank → apply → validate → record iterations until a goal is met,
+the loop converges, or a budget limit fires. It spawns its own `codex exec`
+child processes, so every iteration runs in an independent ephemeral Codex
+session with a fresh context window.
+
+## When to use this skill
+
+**Only** activate when the user's request explicitly contains one of these
+tokens (case-insensitive): `cloop`, `codexloop`, `CodexLoop`, or
+`CODEXLOOP`. Examples of valid triggers:
+
+- "Use cloop to fix the failing auth tests"
+- "codexloop this failing build"
+- "Run a CodexLoop on src/add.js"
+- "CODEXLOOP — fix the broken add test"
+- "cloop --max-iter 5 for the adds function"
+- "start cloop with goal X and budget 30 minutes"
+
+**Do NOT activate** for any of these:
+
+- "iteratively fix X" / "keep iterating on this"
+- "loop on this until tests pass"
+- "try a few approaches and pick the best one"
+- any iterative-task phrasing that does NOT name cloop
+
+If the user describes an iterative task WITHOUT naming cloop, you may
+**suggest** the tool by name ("you could use cloop for this — it's the
+iterative loop driver installed on this machine; run it with `cloop start`")
+and ask whether they want to use it. Never invoke cloop unilaterally.
+
+## Prerequisites
+
+Verify before proceeding:
+
+1. `cloop --version` succeeds (the shell wrapper is on PATH).
+2. `codex --version` succeeds.
+3. Current directory is a git repository (`git rev-parse --show-toplevel`).
+4. Working tree is clean (`git status --porcelain` is empty). If dirty, stop and tell the user to commit or stash.
+
+If `cloop` is missing, **do not try to install it yourself**. Tell the user:
+
+> "Install with `npm install -g @jhlee0619/codexloop` or run the one-liner:
+> `curl -fsSL https://raw.githubusercontent.com/jhlee0619/CodexLoop/main/install.sh | sh`"
+
+Then stop.
+
+## Workflow
+
+When activated, run the interview BEFORE calling `cloop start`. The
+interview mirrors the Claude Code `/cloop:start` flow so behavior is
+consistent across platforms.
+
+### Step 1 — goal capture and clarification
+
+Assemble the goal in this priority order:
+
+1. If the user's message already contains a clear one-sentence goal, use it as the seed.
+2. Otherwise read `TASK.md`, `GOAL.md`, `PRD.md`, or `AGENTS.md` from the repo root if any exist and offer the contents as a seed.
+3. Otherwise ask the user directly what they want to achieve.
+
+Rewrite the seed into **one concrete sentence** that names the files,
+symbols, or behaviors involved. Show the rewritten sentence back and ask
+the user to confirm or rephrase. Iterate once more if they rephrase.
+
+The final goal text is immutable — `cloop` hashes it on first iteration and
+asserts no drift across subsequent iterations, so get it right now.
+
+### Step 2 — plan assembly
+
+Walk these slots in order. For each, infer plausible values from the repo
+(read `package.json`, `Makefile`, `pyproject.toml`, `go.mod`, etc.) so the
+user only confirms or adjusts instead of typing from scratch.
+
+1. **Acceptance criteria** — 1–3 concrete, verifiable signals of success. Examples: "`npm test -- tests/auth` exits 0", "no new type errors introduced", "ESLint reports 0 errors". If the user cannot name any, default to `<testCmd> exits 0` once you have a test command.
+2. **Test command** (`--test-cmd`) — propose 2–3 candidates from the repo (npm scripts, Makefile targets, `node --test tests/`, `pytest`, `cargo test`, `go test ./...`). Ask the user to pick one or provide a custom command. Skippable only if the user explicitly says no tests.
+3. **Lint command** (`--lint-cmd`) — optional. Propose `npm run lint` / `eslint .` / `ruff check .` / `golangci-lint run` based on what you see.
+4. **Type command** (`--type-cmd`) — optional. Propose `npm run typecheck` / `tsc --noEmit` / `mypy .` / `go vet ./...`.
+5. **Budget** — defaults are `--max-iter 20 --max-time 1h --max-calls 200`. Ask only if the user hinted at a specific budget in their request.
+6. **Model + reasoning effort** — defaults are `gpt-5.4` / `xhigh` and are usually fine. Ask only if the user mentioned cost, speed, or a specific model.
+7. **Execution mode** — recommend `--wait` when the loop is short (max-iter ≤ 2) or `--dry-run`, otherwise recommend `--background`. Background spawns a detached Node worker via `spawnDetached({ detached: true, stdio: "ignore" }).unref()` that survives the current Codex session — closing Codex does NOT kill the worker. Foreground blocks the current shell turn until the loop exits.
+
+### Step 3 — approval
+
+Print the complete plan in one block and ask the user to approve it
+explicitly. Example format:
+
+```
+CodexLoop plan:
+  Goal:         fix src/add.js so all tests in tests/add.test.js pass
+  Acceptance criteria:
+    - node --test tests/ exits 0
+    - no test files are deleted or skipped
+  Test command: node --test tests/
+  Lint command: (skip)
+  Type command: (skip)
+  Budget:       5 iter / 30m / 200 calls
+  Model:        gpt-5.4 (xhigh reasoning)
+  Mode:         background
+```
+
+Then ask: **"Start the loop with this plan?"** with clear choices:
+
+- `Start loop`
+- `Edit the goal`
+- `Edit plan details`
+- `Cancel`
+
+Wait for an explicit answer. Never auto-approve. The one exception is when
+the user's original message already said something unambiguous like
+"…start the loop right away" or included `--yes` — in that case still
+print the plan summary but skip the confirmation dialog.
+
+### Step 4 — invoke cloop
+
+Build a single `cloop start` command with every confirmed flag. Quote
+strings with spaces. Include `--yes` so the runtime knows the approval
+step already happened.
+
+```bash
+cloop start --background --yes \
+  --goal "fix src/add.js so all tests in tests/add.test.js pass" \
+  --test-cmd "node --test tests/" \
+  --max-iter 5 \
+  --max-time 30m
+```
+
+Defaults are `--model gpt-5.4 --effort xhigh` — only pass them if the user
+chose something different.
+
+Run the command as a regular shell tool call. In background mode, `cloop`
+spawns its own detached Node worker and returns immediately with the
+`loopId`, `pid`, and log path. **Forward that output to the user verbatim**;
+do not paraphrase.
+
+Then tell the user:
+
+> "CodexLoop started in the background. Check progress with `cloop status`
+> or `cloop result`, and stop it with `cloop stop` if needed."
+
+## Related commands
+
+Offer these when relevant but do NOT run them without being asked:
+
+- `cloop status` — current loop state, iteration history, quality scores, budget consumption.
+- `cloop status --json` — same as above, JSON output.
+- `cloop result` — full iteration history with ranking breakdowns and validation results.
+- `cloop result --iteration N` — zoom in on a single iteration.
+- `cloop result --json` — JSON dump of `.loop/state.json` plus every iteration file.
+- `cloop stop` — SIGTERM the background worker (graceful shutdown at next iteration boundary).
+- `cloop stop --force` — SIGKILL. Only use on explicit second confirmation from the user.
+- `cloop iterate` — run exactly one iteration synchronously. Useful for step-through debugging or to advance a paused loop.
+- `cloop iterate --dry-run` — same but skip apply + validate.
+- `cloop model` — show the loop's current model + reasoning effort.
+- `cloop model <name>` — change the model (e.g. `cloop model gpt-5.4-mini`).
+- `cloop model --effort <level>` — change reasoning effort (one of `none`, `minimal`, `low`, `medium`, `high`, `xhigh`).
+- `cloop model --clear` — reset model + effort to the codex CLI default.
+- `cloop model --list` — list known model aliases and valid effort levels.
+
+## Hard rules
+
+1. **Never** invoke `cloop start` without explicit user approval in this session. Skipping step 3 is not allowed even if the user seems impatient.
+2. **Never** modify the confirmed goal text after step 3. `cloop` will detect drift via its goalHash check and refuse to run.
+3. **Never** use `cloop stop --force` without a second, explicit confirmation from the user. SIGKILL loses the in-flight iteration.
+4. **Never** run `cloop start` if the working tree is dirty. Tell the user to commit or stash.
+5. **Never** try to install `cloop` yourself. If it is missing, give the user install instructions and stop.
+6. **Never** `cloop start` a second loop in the same repo while one is already running. The runtime refuses anyway via the `.loop/loop.lock` advisory lock — respect it and tell the user to `cloop status` or `cloop stop` first.
+7. If the user says "stop" mid-loop without specifying force, call `cloop stop` (SIGTERM) and wait up to 60 seconds for graceful shutdown before even mentioning `--force`.