@compozy/cli 0.1.8 → 0.1.10

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (2) hide show
  1. package/README.md +90 -10
  2. package/package.json +21 -26
package/README.md CHANGED
@@ -74,12 +74,13 @@ compozy setup # interactive — pick agents and skills
74
74
  compozy setup --all # install everything to every detected agent
75
75
  ```
76
76
 
77
- Execution runtimes are separate from skill installation. To run `compozy start` or `compozy fix-reviews`, install an ACP-capable runtime or adapter on `PATH` for the `--ide` you choose:
77
+ Execution runtimes are separate from skill installation. To run `compozy exec`, `compozy start`, or `compozy fix-reviews`, install an ACP-capable runtime or adapter on `PATH` for the `--ide` you choose:
78
78
 
79
79
  | Runtime | `--ide` flag | Expected ACP command |
80
80
  | ------------ | -------------- | -------------------------------- |
81
81
  | Claude Agent | `claude` | `claude-agent-acp` |
82
82
  | Codex CLI | `codex` | `codex-acp` |
83
+ | GitHub Copilot CLI | `copilot` | `copilot --acp` |
83
84
  | Cursor | `cursor-agent` | `cursor-agent acp` |
84
85
  | Droid | `droid` | `droid exec --output-format acp` |
85
86
  | OpenCode | `opencode` | `opencode acp` |
@@ -94,7 +95,9 @@ When the direct ACP command is not installed, Compozy can also fall back to supp
94
95
  <img src="imgs/how-it-works-flow.png" alt="Compozy workflow from setup to ship with markdown artifacts at each step" width="100%">
95
96
  </div>
96
97
 
97
- Every artifact is a plain markdown file in `.compozy/tasks/<name>/`. You can read, edit, or version-control any of them between steps.
98
+ Workflow artifacts stay in `.compozy/tasks/<name>/`. These are the PRDs, TechSpecs, ADRs, tasks, reviews, and memory files that you read and edit between steps.
99
+
100
+ `compozy start` and `compozy fix-reviews` write runtime artifacts under `.compozy/runs/<run-id>/`. `compozy exec` is ephemeral by default and only writes resumable artifacts when `--persist` is enabled.
98
101
 
99
102
  Task and review issue files use YAML frontmatter for parseable metadata such as `status`, `title`, `type`, `severity`, and `provider_ref`. Task workflow `_meta.md` files can be refreshed explicitly with `compozy sync`. Fully completed workflows can be moved out of the active task root with `compozy archive`. If you have an older project with XML-tagged artifacts, run `compozy migrate` once before using `start` or `fix-reviews`.
100
103
 
@@ -148,6 +151,9 @@ retry_backoff_multiplier = 1.5
148
151
  [start]
149
152
  include_completed = false
150
153
 
154
+ [exec]
155
+ output_format = "text"
156
+
151
157
  [tasks]
152
158
  types = ["frontend", "backend", "docs", "test", "infra", "refactor", "chore", "bugfix"]
153
159
 
@@ -163,6 +169,7 @@ provider = "coderabbit"
163
169
  Supported sections:
164
170
 
165
171
  - `[defaults]` for shared execution defaults such as `ide`, `model`, `reasoning_effort`, `access_mode`, `timeout`, `tail_lines`, `add_dirs`, `auto_commit`, `max_retries`, and `retry_backoff_multiplier`
172
+ - `[exec]` for `output_format` plus exec-specific runtime overrides such as `ide`, `model`, `reasoning_effort`, `access_mode`, `timeout`, `tail_lines`, `add_dirs`, `max_retries`, and `retry_backoff_multiplier`
166
173
  - `[start]` for `include_completed`
167
174
  - `[tasks]` for the allowed task `type` list used by `cy-create-tasks` and `compozy validate-tasks`
168
175
  - `[fix_reviews]` for `concurrent`, `batch_size`, and `include_resolved`
@@ -173,9 +180,51 @@ Notes:
173
180
  - `.compozy/config.toml` is optional. If it is absent, Compozy keeps the current built-in defaults.
174
181
  - `.compozy/tasks` remains the fixed workflow root in this version; the config file does not change the workflow root path.
175
182
  - Unknown keys and invalid value types are rejected during config loading.
176
- - `max_retries` applies to execution-stage ACP failures and inactivity timeouts for both `compozy start` and `compozy fix-reviews`.
183
+ - `max_retries` applies to execution-stage ACP failures and inactivity timeouts for `compozy exec`, `compozy start`, and `compozy fix-reviews`.
177
184
  - `retry_backoff_multiplier` only increases the next attempt timeout; retries restart immediately and do not add a sleep delay.
178
185
 
186
+ ## ⚡ Ad Hoc Exec
187
+
188
+ Use `compozy exec` when you want one prompt through the same ACP-backed execution stack without creating a full workflow first.
189
+
190
+ ```bash
191
+ compozy exec "Summarize the current repository changes"
192
+ compozy exec --prompt-file prompt.md
193
+ cat prompt.md | compozy exec --format json
194
+ compozy exec --persist "Review the latest changes"
195
+ compozy exec --run-id exec-20260405-120000-000000000 "Continue from the previous session"
196
+ ```
197
+
198
+ Prompt source rules are explicit:
199
+
200
+ - pass one positional prompt for short inline runs
201
+ - use `--prompt-file` for longer or reusable prompts
202
+ - pipe `stdin` only when neither of the above is provided
203
+ - ambiguous combinations are rejected instead of guessed
204
+
205
+ Output modes:
206
+
207
+ - `--format text` is headless by default and writes only the final assistant response to stdout
208
+ - `--format json` streams the lean JSONL contract to stdout and filters ACP metadata that is mostly useful for debugging
209
+ - `--format raw-json` streams the full raw JSONL event trace to stdout
210
+ - when `--persist` is enabled, `.compozy/runs/<run-id>/events.jsonl` always stores the full raw event stream regardless of the selected stdout format
211
+ - operational ACP/runtime logs stay silent by default; use `--verbose` when you want lifecycle logs on stderr
212
+ - `--tui` opts back into the Bubble Tea interface for interactive inspection
213
+ - `--persist` stores a resumable conversation under `.compozy/runs/<run-id>/`
214
+ - `--run-id` loads a previously persisted ACP session and appends a new turn
215
+
216
+ Persisted `exec` runs use this layout:
217
+
218
+ ```text
219
+ .compozy/runs/<run-id>/run.json
220
+ .compozy/runs/<run-id>/events.jsonl
221
+ .compozy/runs/<run-id>/turns/0001/prompt.md
222
+ .compozy/runs/<run-id>/turns/0001/response.txt
223
+ .compozy/runs/<run-id>/turns/0001/result.json
224
+ ```
225
+
226
+ `compozy exec` uses the same config merge rule as the rest of the CLI: `flags > [exec] > [defaults] > built-in defaults`.
227
+
179
228
  ## 🚀 Quick Start
180
229
 
181
230
  This walkthrough builds a feature called **user-auth** from idea to shipped code.
@@ -304,12 +353,13 @@ The `cy-workflow-memory` skill handles all of this automatically when referenced
304
353
 
305
354
  ### 🤖 Supported Agents
306
355
 
307
- **Execution** (`compozy start`, `compozy fix-reviews`) — ACP-capable runtimes that can run tasks:
356
+ **Execution** (`compozy exec`, `compozy start`, `compozy fix-reviews`) — ACP-capable runtimes that can run ad hoc prompts and task workflows:
308
357
 
309
358
  | Agent | `--ide` flag |
310
359
  | ----------- | -------------- |
311
360
  | Claude Code | `claude` |
312
361
  | Codex | `codex` |
362
+ | GitHub Copilot | `copilot` |
313
363
  | Cursor | `cursor-agent` |
314
364
  | Droid | `droid` |
315
365
  | OpenCode | `opencode` |
@@ -391,6 +441,35 @@ compozy archive [flags]
391
441
 
392
442
  </details>
393
443
 
444
+ <details>
445
+ <summary><code>compozy exec</code> — Execute one ad hoc prompt</summary>
446
+
447
+ ```bash
448
+ compozy exec [prompt] [flags]
449
+ ```
450
+
451
+ Provide exactly one prompt source: a positional prompt, `--prompt-file`, or `stdin`. When present, `.compozy/config.toml` can provide exec defaults through `[exec]` and shared runtime defaults through `[defaults]`.
452
+
453
+ `compozy exec` is headless and ephemeral by default. Use `--persist` to create `.compozy/runs/<run-id>/` for resumable sessions, `--run-id` to continue a persisted session, `--format json` for JSONL, and `--tui` to opt back into the interactive UI.
454
+
455
+ | Flag | Default | Description |
456
+ | ---------------------------- | ----------- | --------------------------------------------------------------------------- |
457
+ | `--ide` | `codex` | Runtime: `claude`, `codex`, `copilot`, `cursor-agent`, `droid`, `gemini`, `opencode`, `pi` |
458
+ | `--model` | _(per IDE)_ | Model override |
459
+ | `--prompt-file` | | Read prompt text from a file |
460
+ | `--format` | `text` | Output contract: `text` or `json` |
461
+ | `--reasoning-effort` | `medium` | `low`, `medium`, `high`, `xhigh` |
462
+ | `--access-mode` | `full` | `default` or `full` runtime access policy |
463
+ | `--timeout` | `10m` | Activity timeout per job |
464
+ | `--max-retries` | `0` | Retry execution-stage ACP failures or timeouts N times |
465
+ | `--retry-backoff-multiplier` | `1.5` | Multiplier applied to the next timeout after each retry |
466
+ | `--tail-lines` | `0` | Maximum log lines retained per job in UI (`0` = full history) |
467
+ | `--add-dir` | | Additional directories to allow (repeatable; currently `claude` and `codex` only) |
468
+ | `--auto-commit` | `false` | Include automatic commit instructions when the prompt asks for code changes |
469
+ | `--dry-run` | `false` | Preview prompts without executing |
470
+
471
+ </details>
472
+
394
473
  <details>
395
474
  <summary><code>compozy start</code> — Execute PRD task files</summary>
396
475
 
@@ -406,15 +485,15 @@ When present, `.compozy/config.toml` can provide defaults for runtime flags such
406
485
  | ---------------------------- | ----------- | ------------------------------------------------------------- |
407
486
  | `--name` | | Workflow name (`.compozy/tasks/<name>`) |
408
487
  | `--tasks-dir` | | Path to tasks directory |
409
- | `--ide` | `codex` | Agent: `claude`, `codex`, `cursor`, `droid`, `opencode`, `pi` |
488
+ | `--ide` | `codex` | Runtime: `claude`, `codex`, `copilot`, `cursor-agent`, `droid`, `gemini`, `opencode`, `pi` |
410
489
  | `--model` | _(per IDE)_ | Model override |
411
490
  | `--reasoning-effort` | `medium` | `low`, `medium`, `high`, `xhigh` |
412
491
  | `--access-mode` | `full` | `default` or `full` runtime access policy |
413
492
  | `--timeout` | `10m` | Activity timeout per job |
414
493
  | `--max-retries` | `0` | Retry execution-stage ACP failures or timeouts N times |
415
494
  | `--retry-backoff-multiplier` | `1.5` | Multiplier applied to the next timeout after each retry |
416
- | `--tail-lines` | `30` | Log lines shown per job in UI |
417
- | `--add-dir` | | Additional directories to allow (repeatable) |
495
+ | `--tail-lines` | `0` | Maximum log lines retained per job in UI (`0` = full history) |
496
+ | `--add-dir` | | Additional directories to allow (repeatable; currently `claude` and `codex` only) |
418
497
  | `--auto-commit` | `false` | Auto-commit after each task |
419
498
  | `--include-completed` | `false` | Re-run completed tasks |
420
499
  | `--dry-run` | `false` | Preview prompts without executing |
@@ -456,7 +535,7 @@ defaults such as `--concurrent`, `--batch-size`, and `--include-resolved`.
456
535
  | `--name` | | Workflow name |
457
536
  | `--round` | `0` | Round number (latest if omitted) |
458
537
  | `--reviews-dir` | | Override review directory path |
459
- | `--ide` | `codex` | Agent: `claude`, `codex`, `cursor`, `droid`, `opencode`, `pi` |
538
+ | `--ide` | `codex` | Runtime: `claude`, `codex`, `copilot`, `cursor-agent`, `droid`, `gemini`, `opencode`, `pi` |
460
539
  | `--model` | _(per IDE)_ | Model override |
461
540
  | `--batch-size` | `1` | Issues per batch |
462
541
  | `--concurrent` | `1` | Parallel batches |
@@ -466,8 +545,8 @@ defaults such as `--concurrent`, `--batch-size`, and `--include-resolved`.
466
545
  | `--timeout` | `10m` | Activity timeout per job |
467
546
  | `--max-retries` | `0` | Retry execution-stage ACP failures or timeouts N times |
468
547
  | `--retry-backoff-multiplier` | `1.5` | Multiplier applied to the next timeout after each retry |
469
- | `--tail-lines` | `30` | Log lines shown per job in UI |
470
- | `--add-dir` | | Additional directories to allow (repeatable) |
548
+ | `--tail-lines` | `0` | Maximum log lines retained per job in UI (`0` = full history) |
549
+ | `--add-dir` | | Additional directories to allow (repeatable; currently `claude` and `codex` only) |
471
550
  | `--auto-commit` | `false` | Auto-commit after each batch |
472
551
  | `--dry-run` | `false` | Preview prompts without executing |
473
552
 
@@ -529,6 +608,7 @@ internal/setup/ Bundled skill installer (agent detection, symlink/copy)
529
608
  internal/version/ Build metadata
530
609
  skills/ Bundled installable skills
531
610
  .compozy/config.toml Optional workspace defaults for CLI execution
611
+ .compozy/runs/ Runtime artifacts for persisted executions and resumable exec sessions
532
612
  .compozy/tasks/ Default workflow artifact root (PRDs, TechSpecs, tasks, ADRs, reviews)
533
613
  ```
534
614
 
package/package.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "@compozy/cli",
3
3
  "type": "module",
4
- "version": "0.1.8",
4
+ "version": "0.1.10",
5
5
  "description": "Compozy CLI",
6
6
  "scripts": {
7
7
  "postinstall": "node install.js",
@@ -27,69 +27,64 @@
27
27
  },
28
28
  "archives": {
29
29
  "darwin-arm64": {
30
- "name": "compozy_0.1.8_darwin_arm64.tar.gz",
31
- "url": "https://github.com/compozy/compozy/releases/download/v0.1.8/compozy_0.1.8_darwin_arm64.tar.gz",
30
+ "name": "compozy_0.1.10_darwin_arm64.tar.gz",
31
+ "url": "https://github.com/compozy/compozy/releases/download/v0.1.10/compozy_0.1.10_darwin_arm64.tar.gz",
32
32
  "bins": [
33
33
  "compozy"
34
34
  ],
35
35
  "format": "tar.gz",
36
36
  "checksum": {
37
37
  "algorithm": "sha256",
38
- "digest": "cb3e627c1cbfec6480071ffbf1bcb964916a7c7a53f859a737b3ac6acea963be"
39
- },
40
- "wrappedIn": "compozy_0.1.8_darwin_arm64"
38
+ "digest": "11775673564a54314065ea8307d5ce1f1b187f2322d7428b4bd5f5a97228f196"
39
+ }
41
40
  },
42
41
  "darwin-x64": {
43
- "name": "compozy_0.1.8_darwin_x86_64.tar.gz",
44
- "url": "https://github.com/compozy/compozy/releases/download/v0.1.8/compozy_0.1.8_darwin_x86_64.tar.gz",
42
+ "name": "compozy_0.1.10_darwin_x86_64.tar.gz",
43
+ "url": "https://github.com/compozy/compozy/releases/download/v0.1.10/compozy_0.1.10_darwin_x86_64.tar.gz",
45
44
  "bins": [
46
45
  "compozy"
47
46
  ],
48
47
  "format": "tar.gz",
49
48
  "checksum": {
50
49
  "algorithm": "sha256",
51
- "digest": "e84f18fe1747696908bbbce0c1269b6f13a985bc52339ef9dc65767aa3925c8f"
52
- },
53
- "wrappedIn": "compozy_0.1.8_darwin_x86_64"
50
+ "digest": "cacb8818efccc7f03e53d584747056ce1e682c6f78221a05ba67769d6a603204"
51
+ }
54
52
  },
55
53
  "linux-arm64": {
56
- "name": "compozy_0.1.8_linux_arm64.tar.gz",
57
- "url": "https://github.com/compozy/compozy/releases/download/v0.1.8/compozy_0.1.8_linux_arm64.tar.gz",
54
+ "name": "compozy_0.1.10_linux_arm64.tar.gz",
55
+ "url": "https://github.com/compozy/compozy/releases/download/v0.1.10/compozy_0.1.10_linux_arm64.tar.gz",
58
56
  "bins": [
59
57
  "compozy"
60
58
  ],
61
59
  "format": "tar.gz",
62
60
  "checksum": {
63
61
  "algorithm": "sha256",
64
- "digest": "fde00e9c42ab684503599c1d7d5775d46bb703b075601aba458f0846ab2b96fe"
65
- },
66
- "wrappedIn": "compozy_0.1.8_linux_arm64"
62
+ "digest": "a89a221bb2385456d6de1a7830c7023d6d9c94cb0be9dc4c02d3fe801f198e4f"
63
+ }
67
64
  },
68
65
  "linux-x64": {
69
- "name": "compozy_0.1.8_linux_x86_64.tar.gz",
70
- "url": "https://github.com/compozy/compozy/releases/download/v0.1.8/compozy_0.1.8_linux_x86_64.tar.gz",
66
+ "name": "compozy_0.1.10_linux_x86_64.tar.gz",
67
+ "url": "https://github.com/compozy/compozy/releases/download/v0.1.10/compozy_0.1.10_linux_x86_64.tar.gz",
71
68
  "bins": [
72
69
  "compozy"
73
70
  ],
74
71
  "format": "tar.gz",
75
72
  "checksum": {
76
73
  "algorithm": "sha256",
77
- "digest": "4149037d08b67c8f6018c61a57bc1397b82ee474d1b42c2904e13bedfcae80be"
78
- },
79
- "wrappedIn": "compozy_0.1.8_linux_x86_64"
74
+ "digest": "3915ad13f8ebd5d0176927130878f77fe87302989dcbbcfdf3e560b86dd75c19"
75
+ }
80
76
  },
81
77
  "win32-x64": {
82
- "name": "compozy_0.1.8_windows_x86_64.zip",
83
- "url": "https://github.com/compozy/compozy/releases/download/v0.1.8/compozy_0.1.8_windows_x86_64.zip",
78
+ "name": "compozy_0.1.10_windows_x86_64.zip",
79
+ "url": "https://github.com/compozy/compozy/releases/download/v0.1.10/compozy_0.1.10_windows_x86_64.zip",
84
80
  "bins": [
85
81
  "compozy.exe"
86
82
  ],
87
83
  "format": "zip",
88
84
  "checksum": {
89
85
  "algorithm": "sha256",
90
- "digest": "4f7bd78520c4191de62969a0d91281597e8effa4bc09a8ac534d99d9447de088"
91
- },
92
- "wrappedIn": "compozy_0.1.8_windows_x86_64"
86
+ "digest": "72f4d3ce6caa32aca4fb09f5a5803968de6a514553266cfe0948ca370d51dd00"
87
+ }
93
88
  }
94
89
  }
95
90
  }