From 998df93be58163c9bdcc3522283da3718a8a7bc3 Mon Sep 17 00:00:00 2001 From: droidnoob Date: Fri, 29 May 2026 23:48:31 +0530 Subject: [PATCH] docs(slash): split /hew:auto from /hew:loop semantics (hew-6n0v) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit /hew:auto is the in-conversation, epic-scoped driver — walks the children of one active epic via /hew:next per task, one continuous transcript, mid-loop steering. /hew:loop remains the subprocess driver (`hew loop run`) for cache-warm, on-disk-logged iters. Updates auto.md (rewrite), CLAUDE.md, docs/COMMANDS.md, docs/LOOP.md, and skills/core/hew-execute.md Step 10 cross-ref. The .claude/ install snapshot will refresh at next release per CLAUDE.md step 3. Co-Authored-By: Claude Opus 4.7 (1M context) --- CLAUDE.md | 2 +- commands/auto.md | 64 +++++++++++++++++++++++++++----------- docs/COMMANDS.md | 10 +++--- docs/LOOP.md | 4 +-- skills/core/hew-execute.md | 11 +++++-- 5 files changed, 63 insertions(+), 28 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index 38f0a40..d6f4b26 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -116,7 +116,7 @@ hew loop cancel # touch stop-file on latest run Each iter is a fresh `claude -p` (or `codex exec`) subprocess; the skill body + memory primer prefix is byte-stable across iters so the prompt cache hits (check `prompt_prefix_hash` in `.hew/loop//iter-NNN.json`). `--fallback-runtime` is primary-sticky with a configurable cooldown (`--fallback-cooldown-iters`, default 3) — see [docs/LOOP.md](./docs/LOOP.md#fallback-runtime) for the worked example. -`/hew:auto` now points at `hew loop run --until-empty`. The in-conversation walk is still reachable via `/hew:work`. Full guide: [docs/LOOP.md](./docs/LOOP.md). +`/hew:loop` drives this subprocess loop. `/hew:auto` is the in-conversation, epic-scoped walk — one session, one epic, mid-loop steering. Full guide: [docs/LOOP.md](./docs/LOOP.md). ### Statusline diff --git a/commands/auto.md b/commands/auto.md index 204f9e2..5817c4e 100644 --- a/commands/auto.md +++ b/commands/auto.md @@ -1,30 +1,58 @@ --- -description: Autonomously drain the queue via the process-level loop (`hew loop run --until-empty`). +description: Drive the loop in-conversation, walking the children of one active epic. --- -Run the autonomous outer loop until the ready queue drains: +In-conversation, epic-scoped driver. `/hew:auto` stays inside the +current Claude session and walks the children of one active epic in +dependency order — one continuous transcript, full mid-loop steering. + +This is **not** the subprocess loop. For fresh-context-per-iter with +prompt-cache hits, hard caps, and per-iter logs on disk, use +[`/hew:loop`](./loop.md) (`hew loop run`). + +## Pick the active epic + +If the user named one in the prompt, use it. Otherwise: ```sh -hew loop run --until-empty +hew epic list # open epics +hew epic tree # children + dep order for the chosen epic ``` -`--until-empty` is on by default — stop signals fire when the queue -hits zero, when a budget caps, when the operator touches the stop-file, -or on a runtime error. Use `--max-iter N` to bound the run, `--strict` -(default) to promote craft warnings to failures, `--budget-tokens N` / -`--budget-wall ` for hard caps. +If exactly one open epic exists, pick it. If several, ask the user once +which to drive. Never default to the full `bd ready` set — that's the +subprocess loop's job. + +## The walk + +Until the active epic has no open children: + +1. From `hew epic tree `, pick the next unblocked child + (lowest-id ties break by creation order). Skip closed/in_progress + children belonging to another assignee. +2. Tail-call `/hew:next` for that task. `/hew:next` claims, runs the + full `hew-execute` loop (read → code → tests → `hew-guard` → close + → commit → optional `hew remember`), and returns. +3. Loop. The session stays focused on one epic at a time; cross-epic + work needs an explicit re-invocation. + +Stop when: -Per-iter logs land in `.hew/loop//iter-NNN.json`. Inspect with -`hew loop list`, `hew loop logs --tail 5`, `hew loop cancel`. +- All children of the active epic are closed → run `/hew:verify`, + then offer to close the epic and report done. +- A Rule-4 architectural change blocks progress → surface to the + user and wait. +- The user interrupts. -For the in-conversation walk through the workflow (older `/hew:auto` -behavior — useful when you want to drive iters from inside one Claude -session rather than spawning fresh subprocesses), call `/hew:work` and -let it tail-call `/hew:next` until either: +Honor every `hew-execute` rule along the way (guard before close, +deviation tags in close reasons, atomic commits, branching contract). -- `hew status` ready list is empty (call `/hew:verify`, then report done), or -- a Rule-4 architectural change blocks you (stop, surface, wait). +## When to reach for `/hew:loop` instead -Honor all guard / deviation / convention rules; atomic commits per task. +- You want each task in a fresh context window with a cache-warm + prefix. +- You want hard caps (token / wall-clock / max-iter) and per-iter + logs to disk. +- You're draining the global ready queue, not focusing one epic. -See `docs/LOOP.md` for the full design. +See [`docs/LOOP.md`](../docs/LOOP.md) for the full design. diff --git a/docs/COMMANDS.md b/docs/COMMANDS.md index 8ccb2cb..49b6276 100644 --- a/docs/COMMANDS.md +++ b/docs/COMMANDS.md @@ -40,11 +40,13 @@ Fast mode: one task, no plan/decompose overhead. ### `/hew:auto` -Run plan → decompose → execute → verify autonomously. Now a thin -pointer at `hew loop run --until-empty` — the in-conversation walk is -still reachable via `/hew:work`. +In-conversation, epic-scoped driver. Walks the children of one active +epic in dependency order, tail-calling `/hew:next` per task, in a +single Claude session. For the subprocess loop that drains the global +ready queue with cache-warm prefixes and on-disk per-iter logs, use +`/hew:loop`. -- Use when: you trust the agent to drive end-to-end without pause +- Use when: you want one session focused on one epic with mid-loop steering ### `/hew:loop` diff --git a/docs/LOOP.md b/docs/LOOP.md index c41a349..c11ae66 100644 --- a/docs/LOOP.md +++ b/docs/LOOP.md @@ -256,8 +256,8 @@ Outstanding bugs discovered by the run: ## Related - `commands/loop.md` — the `/hew:loop` slash body. -- `commands/auto.md` — the `/hew:auto` slash, now a thin pointer at - `hew loop run --until-empty`. +- `commands/auto.md` — the `/hew:auto` slash: in-conversation, + epic-scoped walk (one session, one epic, mid-loop steering). - `hew_core::runner` — pure precedence logic for stop signals. - `hew_core::prompt` — cache-disciplined assembler. - `hew_core::runtime` — Claude Code spawner. diff --git a/skills/core/hew-execute.md b/skills/core/hew-execute.md index 06fffc7..0c3b0db 100644 --- a/skills/core/hew-execute.md +++ b/skills/core/hew-execute.md @@ -457,9 +457,14 @@ it out. Future-you saves the lookup time. Run `hew prime execute` again. Pick the next ready task. Continue. -If the user said "do this one task," stop after closing it. If "keep going" -or `/hew:auto`, loop until `hew prime execute` shows no ready tasks (then call `hew-verify`) or -a Rule-4 architectural decision blocks you (then surface and stop). +If the user said "do this one task," stop after closing it. If "keep going," +loop until `hew prime execute` shows no ready tasks (then call `hew-verify`) +or a Rule-4 architectural decision blocks you (then surface and stop). + +If invoked via `/hew:auto`, the walk is scoped to the children of one +active epic (`hew epic tree `), not the global `bd ready` set — +finish the epic, run `/hew:verify`, then stop. For the subprocess loop +that drains the global queue with cache-warm prefixes, see `/hew:loop`. ### Step 10a — review picker (optional, config-gated)