From ff598707a697f748eed00ade122f9ef93eb0bd05 Mon Sep 17 00:00:00 2001 From: Helix Date: Mon, 23 Feb 2026 17:07:15 -0800 Subject: [PATCH] docs: add --json-stream to commit, finish, and rebase patterns MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Update all skill docs to reflect upstream v0.10.0 adding --json-stream support to commit, finish, and rebase commands: - SKILL.md: update finish/commit examples with --json-stream + background, expand safety rule #2 and Important note to cover all extended commands - non-interactive-patterns.md: add 'Background Commands — Extended Operations' section for commit/finish/rebase, move rebase out of 'Foreground Only', add autonomous rebase pattern, update JSON Output table - development-commands.md: add --json-stream flag to commit and rebase tables, update examples to use background mode - core-workflow.md: add --json-stream flag to finish table, update examples Refs #3 --- openclaw-skill/SKILL.md | 10 +++-- openclaw-skill/references/core-workflow.md | 7 ++-- .../references/development-commands.md | 12 +++--- .../references/non-interactive-patterns.md | 42 +++++++++++++++---- 4 files changed, 52 insertions(+), 19 deletions(-) diff --git a/openclaw-skill/SKILL.md b/openclaw-skill/SKILL.md index fe9b7113..c38ca58a 100644 --- a/openclaw-skill/SKILL.md +++ b/openclaw-skill/SKILL.md @@ -105,7 +105,8 @@ For anything non-trivial, use the **plan → review → start → spin** workflo 5. **Finish:** Merge and clean up ```bash - bash pty:true command:"il finish --force --cleanup --no-browser --json" + bash pty:true background:true command:"il finish --force --cleanup --no-browser --json --json-stream" + # Monitor: process action:poll sessionId:XXX ``` ### Small Changes (single issue, quick fix) @@ -130,7 +131,8 @@ bash pty:true command:"il list --json" ### Commit with AI-generated message ```bash -bash pty:true command:"il commit --no-review --json" +bash pty:true background:true command:"il commit --no-review --json --json-stream" +# Monitor: process action:poll sessionId:XXX ``` ## Ideation and Planning @@ -145,7 +147,7 @@ bash pty:true background:true command:"il plan --yolo --print --json-stream" `il plan` launches an autonomous AI planning session that reads the codebase and creates structured issues with dependencies. Always prefer this over manually creating issues. -**Important:** Both `plan` and `spin` should always be run in **background mode** (`background:true`) with `--print --json-stream`. These commands can run for several minutes (especially with Opus) as they analyze the codebase, and foreground timeouts will kill them. The `--json-stream` flag ensures incremental output is visible via `process action:poll`. +**Important:** Commands that can run for extended periods — `plan`, `spin`, `commit`, `finish`, and `rebase` — should be run in **background mode** (`background:true`) with `--json-stream` (and `--print` for plan/spin). The `--json-stream` flag streams JSONL incrementally so you can monitor progress via `process action:poll`. Without it, you get zero visibility until the command completes. ## References @@ -159,7 +161,7 @@ bash pty:true background:true command:"il plan --yolo --print --json-stream" ## Safety Rules 1. **Always use `pty:true`** for every iloom command. -2. **Use `background:true`** for commands that launch Claude: `start`, `spin`, `plan`. +2. **Use `background:true`** for commands that launch Claude or run extended operations: `start`, `spin`, `plan`, `commit`, `finish`, `rebase`. 3. **Never run `il finish` without `--force`** in autonomous mode — it will hang on confirmation prompts. 4. **Always pass explicit flags** to avoid interactive prompts. See `{baseDir}/references/non-interactive-patterns.md` for the complete decision bypass map. 5. **Use `--json`** when you need to parse command output programmatically. diff --git a/openclaw-skill/references/core-workflow.md b/openclaw-skill/references/core-workflow.md index 1829c1ff..20e53a7a 100644 --- a/openclaw-skill/references/core-workflow.md +++ b/openclaw-skill/references/core-workflow.md @@ -129,18 +129,19 @@ Validate, commit, merge, and clean up a loom workspace. | `--no-browser` | boolean | `false` | Skip opening PR in browser | | `--cleanup` / `--no-cleanup` | boolean | — | Explicit cleanup decision (skips prompt) | | `--json` | boolean | `false` | Output result as JSON | +| `--json-stream` | boolean | `false` | Stream JSONL progress output | ### Examples ```bash -# Fully autonomous finish from within a loom directory -bash pty:true command:"il finish --force --cleanup --no-browser --json" +# Fully autonomous finish from within a loom directory (background recommended — can take 1-2+ min) +bash pty:true background:true command:"il finish --force --cleanup --no-browser --json --json-stream" # Dry run to preview what would happen bash pty:true command:"il finish --dry-run" # Finish a specific issue -bash pty:true command:"il finish 42 --force --cleanup --no-browser --json" +bash pty:true background:true command:"il finish 42 --force --cleanup --no-browser --json --json-stream" ``` ### Interactive Prompts and Bypasses diff --git a/openclaw-skill/references/development-commands.md b/openclaw-skill/references/development-commands.md index 4b07ad12..6bfd6625 100644 --- a/openclaw-skill/references/development-commands.md +++ b/openclaw-skill/references/development-commands.md @@ -54,13 +54,14 @@ Commit all uncommitted files with issue reference trailer. | `--fixes` | boolean | `false` | Use "Fixes #N" trailer instead of "Refs #N" | | `--no-review` | boolean | `false` | Skip commit message review prompt | | `--json` | boolean | `false` | Output result as JSON (implies `--no-review`) | +| `--json-stream` | boolean | `false` | Stream JSONL progress output | | `--wip-commit` | boolean | `false` | Quick WIP commit: skip validations and pre-commit hooks | ### Examples ```bash -# Non-interactive commit with AI-generated message -bash pty:true command:"il commit --no-review --json" +# Non-interactive commit with AI-generated message (background recommended — Claude generates message) +bash pty:true background:true command:"il commit --no-review --json --json-stream" # Commit with custom message bash pty:true command:"il commit -m 'fix: resolve auth timeout' --json" @@ -103,12 +104,13 @@ Rebase current loom branch on main with AI-assisted conflict resolution. |------|------|---------|-------------| | `-f, --force` | boolean | `false` | Force rebase even in edge cases | | `-n, --dry-run` | boolean | `false` | Simulate rebase without changes | +| `--json-stream` | boolean | `false` | Stream JSONL progress output | ### Examples ```bash -# Rebase with force (skip edge case checks) -bash pty:true command:"il rebase --force" +# Rebase with force and progress streaming (background recommended — Claude may resolve conflicts) +bash pty:true background:true command:"il rebase --force --json-stream" # Dry run bash pty:true command:"il rebase --dry-run" @@ -119,7 +121,7 @@ bash pty:true command:"il rebase --dry-run" - Detects uncommitted changes and throws if found (commit first) - Claude assists with conflict resolution if conflicts arise - Post-rebase: installs dependencies and runs build (non-blocking) -- No JSON output mode +- Use `--json-stream` for incremental progress visibility --- diff --git a/openclaw-skill/references/non-interactive-patterns.md b/openclaw-skill/references/non-interactive-patterns.md index faa37be1..7966a9ed 100644 --- a/openclaw-skill/references/non-interactive-patterns.md +++ b/openclaw-skill/references/non-interactive-patterns.md @@ -36,6 +36,21 @@ These commands launch Claude Code and run for extended periods. **Always run in - Without `--json-stream`, `--print` buffers ALL output until completion (no visibility into what Claude is doing) - These commands can easily run 3-10+ minutes with Opus analyzing a codebase — foreground timeouts will kill them +### Background Commands — Extended Operations + +These commands use Claude for message generation, conflict resolution, or merge validation and support `--json-stream` for progress monitoring: + +| Command | Recommended Invocation | +|---------|----------------------| +| `il commit` | `bash pty:true background:true command:"il commit --no-review --json --json-stream"` | +| `il finish` | `bash pty:true background:true command:"il finish --force --cleanup --no-browser --json --json-stream"` | +| `il rebase` | `bash pty:true background:true command:"il rebase --force --json-stream"` | + +**Why `--json-stream` for these commands?** +- `commit` uses Claude to generate commit messages — can take 10-30s +- `finish` validates, commits, merges, and may trigger builds — can take 1-2+ minutes +- `rebase` may invoke Claude for conflict resolution — duration is unpredictable + ### Foreground Commands (no `background:true`) These commands complete quickly and return structured output: @@ -43,8 +58,6 @@ These commands complete quickly and return structured output: | Command | Recommended Invocation | |---------|----------------------| | `il list` | `bash pty:true command:"il list --json"` | -| `il commit` | `bash pty:true command:"il commit --no-review --json"` | -| `il finish` | `bash pty:true command:"il finish --force --cleanup --no-browser --json"` | | `il cleanup` | `bash pty:true command:"il cleanup --issue 42 --force --json"` | | `il build` | `bash pty:true command:"il build"` | | `il test` | `bash pty:true command:"il test"` | @@ -61,7 +74,6 @@ These commands complete quickly and return structured output: | Command | Note | |---------|------| | `il init` | Interactive wizard, must run foreground. **Not recommended for AI agents** — use manual setup instead (see `{baseDir}/references/initialization.md`) | -| `il rebase` | May need Claude for conflict resolution | | `il shell` | Opens interactive subshell | --- @@ -134,13 +146,16 @@ bash pty:true background:true command:"il start --yolo --no-code --no-te ### Full Autonomous Finish (merge and cleanup) ```bash -bash pty:true command:"il finish --force --cleanup --no-browser --json" +bash pty:true background:true command:"il finish --force --cleanup --no-browser --json --json-stream" +# Monitor: process action:poll sessionId:XXX ``` - `--force`: skip all confirmations - `--cleanup`: auto-cleanup worktree - `--no-browser`: don't open browser - `--json`: structured output +- `--json-stream`: stream progress incrementally +- `background:true`: finish can take 1-2+ minutes (commit, merge, build verification) ### Headless Planning @@ -158,11 +173,23 @@ bash pty:true background:true command:"il plan --yolo --print --json-stream" ### Non-Interactive Commit ```bash -bash pty:true command:"il commit --no-review --json" +bash pty:true background:true command:"il commit --no-review --json --json-stream" +# Monitor: process action:poll sessionId:XXX ``` - `--no-review`: skip message review - `--json`: structured output (also implies `--no-review`) +- `--json-stream`: stream progress (Claude generates commit message) + +### Non-Interactive Rebase + +```bash +bash pty:true background:true command:"il rebase --force --json-stream" +# Monitor: process action:poll sessionId:XXX +``` + +- `--force`: force rebase even in edge cases +- `--json-stream`: stream progress (Claude assists with conflict resolution if needed) ### Quick Cleanup @@ -182,10 +209,10 @@ Commands that support `--json` for machine-parseable output: | Command | JSON Flag | Notes | |---------|-----------|-------| | `il start` | `--json` | Returns workspace metadata | -| `il finish` | `--json` | Returns operation results | +| `il finish` | `--json`, `--json-stream` | Returns operation results. `--json-stream` for progress | | `il cleanup` | `--json` | Returns cleanup results | | `il list` | `--json` | Returns array of loom objects | -| `il commit` | `--json` | Returns commit details (implies `--no-review`) | +| `il commit` | `--json`, `--json-stream` | Returns commit details (implies `--no-review`). `--json-stream` for progress | | `il issues` | `--json` | Returns array of issues/PRs | | `il add-issue` | `--json` | Returns created issue | | `il enhance` | `--json` | Returns enhancement result | @@ -193,6 +220,7 @@ Commands that support `--json` for machine-parseable output: | `il recap` | `--json` | Returns recap data | | `il dev-server` | `--json` | Returns server status | | `il projects` | `--json` | Returns project list | +| `il rebase` | `--json-stream` | Stream progress during rebase | | `il plan` | `--json` | Returns planning result (requires `--print`) | | `il spin` | `--json` | Returns result (requires `--print`) |