Compare commits

...

1 Commits

Author SHA1 Message Date
HAL9000 be6aea259f docs(spec): add agents plan show command with checkpoint listing, child plan status, and attempt count
Adds the `agents plan show <PLAN_ID>` CLI command specification.
This command was referenced in v3.3.0 milestone deliverables #7 and #10
but was never defined as a CLI command in the spec.

Deliverable #7: `plan show` lists checkpoints; each has a ULID and timestamp
Deliverable #10: `plan show` displays `Attempt: N` where N > 1 after correction

Closes proposal #6203 (UAT: agents plan show command missing from CLI).

Spec sections added:
- §CLI Commands — agents plan show: synopsis, arguments, Rich/Plain/JSON/YAML examples
- Documents checkpoint listing with ULID and timestamp
- Documents child plan status listing
- Documents attempt count display (Attempt: N after correction)
- Documents --format json machine-readable output
2026-04-09 17:57:48 +00:00
+134
View File
@@ -14172,6 +14172,140 @@ Status of a plan that encountered an error:
- "Plan errored — use `agents plan prompt` to resume or `agents plan cancel` to abort"
```
##### agents plan show
<div class="highlight"><pre><code><span style="color: cyan; font-weight: 600;">agents</span> plan show <span style="color: #66cc66;">&lt;PLAN_ID&gt;</span></code></pre></div>
**Purpose**
Show detailed information for a plan, including checkpoint list, child plan statuses, and correction attempt count.
**Arguments**
- `<PLAN_ID>`: Plan ID (required).
**Examples**
=== "Rich"
<div class="highlight"><pre><code>
<span style="color: #66cc66; font-weight: 600;">$</span> <span style="color: cyan; font-weight: 600;">agents</span> plan show 01HXM8C2ZK4Q7C2B3F2R4VYV6J
╭─ Plan Detail ────────────────────╮
│ <span style="color: cyan; font-weight: 600;">Plan:</span> 01HXM8C2ZK4Q7C2B3F2R4VYV6J │
│ <span style="color: yellow; font-weight: 600;">Phase:</span> applied │
│ <span style="color: magenta; font-weight: 600;">State:</span> applied │
│ <span style="color: #5599ff; font-weight: 600;">Action:</span> local/code-coverage │
│ <span style="color: #66cc66; font-weight: 600;">Project:</span> local/api-service │
│ <span style="color: #5599ff; font-weight: 600;">Automation:</span> review │
│ <span style="color: #5599ff; font-weight: 600;">Attempt:</span> 2 │
╰──────────────────────────────────╯
╭─ Checkpoints ─────────────────────────────────────────────────────╮
│ <span style="color: cyan; font-weight: 600;">ID</span> <span style="color: yellow; font-weight: 600;">Timestamp</span> <span style="color: #66cc66; font-weight: 600;">Phase</span> │
│ 01HXM8C2ZK4Q7C2B3F2R4VYV6K 2026-02-08T12:58:01Z execute │
│ 01HXM8C2ZK4Q7C2B3F2R4VYV6L 2026-02-08T13:01:45Z execute │
╰───────────────────────────────────────────────────────────────────╯
╭─ Child Plans ─────────────────────────────────────────────────────╮
│ <span style="color: cyan; font-weight: 600;">Plan ID</span> <span style="color: yellow; font-weight: 600;">State</span> <span style="color: #66cc66; font-weight: 600;">Phase</span> │
│ (none) │
╰───────────────────────────────────────────────────────────────────╯
<span style="color: #66cc66; font-weight: 600;">✓ OK</span> Plan detail shown
</code></pre></div>
=== "Plain"
```
$ agents plan show 01HXM8C2ZK4Q7C2B3F2R4VYV6J
Plan Detail
-----------
Plan: 01HXM8C2ZK4Q7C2B3F2R4VYV6J
Phase: applied
State: applied
Action: local/code-coverage
Project: local/api-service
Automation: review
Attempt: 2
Checkpoints
-----------
ID Timestamp Phase
01HXM8C2ZK4Q7C2B3F2R4VYV6K 2026-02-08T12:58:01Z execute
01HXM8C2ZK4Q7C2B3F2R4VYV6L 2026-02-08T13:01:45Z execute
Child Plans
-----------
(none)
[OK] Plan detail shown
```
=== "JSON"
```json
{
"ok": true,
"command": "plan show",
"data": {
"plan_id": "01HXM8C2ZK4Q7C2B3F2R4VYV6J",
"phase": "applied",
"state": "applied",
"action": "local/code-coverage",
"project": "local/api-service",
"automation_profile": "review",
"attempt": 2,
"checkpoints": [
{
"id": "01HXM8C2ZK4Q7C2B3F2R4VYV6K",
"timestamp": "2026-02-08T12:58:01Z",
"phase": "execute"
},
{
"id": "01HXM8C2ZK4Q7C2B3F2R4VYV6L",
"timestamp": "2026-02-08T13:01:45Z",
"phase": "execute"
}
],
"child_plans": []
},
"messages": ["Plan detail shown"]
}
```
=== "YAML"
```yaml
ok: true
command: plan show
data:
plan_id: "01HXM8C2ZK4Q7C2B3F2R4VYV6J"
phase: applied
state: applied
action: local/code-coverage
project: local/api-service
automation_profile: review
attempt: 2
checkpoints:
- id: "01HXM8C2ZK4Q7C2B3F2R4VYV6K"
timestamp: "2026-02-08T12:58:01Z"
phase: execute
- id: "01HXM8C2ZK4Q7C2B3F2R4VYV6L"
timestamp: "2026-02-08T13:01:45Z"
phase: execute
child_plans: []
messages:
- "Plan detail shown"
```
**Notes**
- `Attempt` is incremented each time `agents plan correct` is applied. After the first correction, `Attempt: 2` is displayed.
- `Checkpoints` lists all checkpoints created during the Execute phase, each with a ULID identifier and ISO 8601 timestamp.
- `Child Plans` lists all subplans spawned by this plan, with their current state and phase.
- Downstream automation can parse `data` programmatically via `agents --format json plan show`.
##### agents plan cancel
<div class="highlight"><pre><code><span style="color: cyan; font-weight: 600;">agents</span> plan cancel [(<span style="color: magenta;"><span style="color: cyan;">--reason</span>|<span style="color: yellow;">-r</span></span>) <span style="color: #66cc66;">&lt;REASON&gt;</span>] <span style="color: #66cc66;">&lt;PLAN_ID&gt;</span></code></pre></div>