cleveragents/cleveragents-core

Fork 3

bug(cli): plan use --format json returns raw plan dict instead of spec-required JSON envelope #9445

New issue

Open

opened 2026-04-14 17:54:19 +00:00 by HAL9000 · 1 comment

HAL9000 commented

2026-04-14 17:54:19 +00:00

Owner

Metadata

Commit Message: bug(cli): plan use --format json returns raw plan dict instead of spec-required JSON envelope
Branch: bugfix/plan-use-json-envelope

Background and Context

The agents plan use --format json command returns a raw internal plan dictionary instead of the spec-required JSON envelope structure. This breaks downstream automation scripts that rely on the structured output format defined in the specification.

The root cause is in src/cleveragents/cli/commands/plan.py in the use_action function (line ~2239), where for non-rich formats the code does:

data = _plan_spec_dict(plan)
console.print(format_output(data, fmt))

This returns the internal plan representation using _plan_spec_dict() which has different field names and structure than what the spec requires. The spec requires a command: "plan use" envelope with data.inputs, data.actors, data.automation, data.context, data.next_steps fields.

Current Behavior

agents plan use local/code-coverage local/api-service --format json outputs:

{
  "plan_id": "01HXM8C2ZK4Q7C2B3F2R4VYV6J",
  "namespaced_name": "local/my-plan",
  "phase": "strategize",
  "processing_state": "queued",
  "state": "queued",
  "project_links": [...],
  "arguments": {},
  "automation_profile": null,
  "action_name": "local/code-coverage",
  ...
}

Expected Behavior

Per spec §agents plan use (lines ~12602-12644), the command must return a structured JSON envelope:

{
  "command": "plan use",
  "status": "ok",
  "exit_code": 0,
  "data": {
    "plan_id": "01HXM8C2ZK4Q7C2B3F2R4VYV6J",
    "phase": "strategize",
    "action": "local/code-coverage",
    "project": "local/api-service",
    "automation_profile": "trusted",
    "attempt": 1,
    "inputs": {
      "target_coverage_percent": 85,
      "automation_profile": "trusted"
    },
    "actors": {
      "strategy": "local/strategist",
      "execution": "local/executor",
      "estimation": null
    },
    "automation": {
      "profile": "trusted",
      "source": "CLI flag",
      "read_only": false
    },
    "context": {
      "resources": 2,
      "indexed_files": 347,
      "view": "strategize",
      "hot_token_budget": 12000
    },
    "next_steps": [
      "agents plan execute 01HXM8C2ZK4Q7C2B3F2R4VYV6J",
      "agents plan status 01HXM8C2ZK4Q7C2B3F2R4VYV6J",
      "agents plan tree 01HXM8C2ZK4Q7C2B3F2R4VYV6J"
    ]
  },
  "timing": { "started": "2026-02-09T14:30:00Z", "duration_ms": 95 },
  "messages": ["Plan created"]
}

Impact

Downstream automation scripts using agents --format json plan use will receive incorrect JSON structure
The next_steps field (containing the agents plan execute <id> command) is missing, breaking scripted workflows
The actors object showing strategy/execution/estimation actors is missing

Spec Reference

docs/specification.md §agents plan use (lines ~12602-12644)

Files Affected

src/cleveragents/cli/commands/plan.py — use_action function (lines ~2239-2241)

Acceptance Criteria

agents plan use <action> <project> --format json returns spec-required envelope with command: "plan use", status: "ok", exit_code: 0
data.next_steps contains agents plan execute <plan_id> as first item
data.actors contains strategy, execution, estimation fields
data.automation contains profile, source, read_only fields
Behave BDD test covers the JSON envelope structure
No regressions in existing tests
Coverage ≥97%

Subtasks

Build spec-compliant JSON envelope builder for plan use output
Include command: "plan use", status: "ok", exit_code: 0 envelope fields
Include data.plan_id, data.phase, data.action, data.project (first project link)
Include data.inputs (arguments + automation_profile)
Include data.actors (strategy, execution, estimation)
Include data.automation (profile, source, read_only)
Include data.next_steps with agents plan execute <id>, agents plan status <id>, agents plan tree <id>
Include timing and messages envelope fields
Add Behave BDD test scenario verifying JSON envelope structure for plan use --format json
Verify coverage remains ≥97%

Definition of Done

This issue is complete when:

agents plan use <action> <project> --format json returns spec-required envelope with command: "plan use", status: "ok", exit_code: 0
data.next_steps contains agents plan execute <plan_id> as first item
data.actors contains strategy, execution, estimation fields
data.automation contains profile, source, read_only fields
Behave BDD test covers the JSON envelope structure
No regressions in existing tests
Coverage ≥97%
A Git commit is created where the first line of the commit message matches the Commit Message in Metadata exactly, followed by a blank line, then additional lines providing relevant details about the implementation.
The commit is pushed to the remote on the branch matching the Branch in Metadata exactly.
The commit is submitted as a pull request to master, reviewed, and merged before this issue is marked done.

Automated by CleverAgents Bot
Agent: new-issue-creator

## Metadata - **Commit Message**: `bug(cli): plan use --format json returns raw plan dict instead of spec-required JSON envelope` - **Branch**: `bugfix/plan-use-json-envelope` ## Background and Context The `agents plan use --format json` command returns a raw internal plan dictionary instead of the spec-required JSON envelope structure. This breaks downstream automation scripts that rely on the structured output format defined in the specification. The root cause is in `src/cleveragents/cli/commands/plan.py` in the `use_action` function (line ~2239), where for non-rich formats the code does: ```python data = _plan_spec_dict(plan) console.print(format_output(data, fmt)) ``` This returns the internal plan representation using `_plan_spec_dict()` which has different field names and structure than what the spec requires. The spec requires a `command: "plan use"` envelope with `data.inputs`, `data.actors`, `data.automation`, `data.context`, `data.next_steps` fields. ## Current Behavior `agents plan use local/code-coverage local/api-service --format json` outputs: ```json { "plan_id": "01HXM8C2ZK4Q7C2B3F2R4VYV6J", "namespaced_name": "local/my-plan", "phase": "strategize", "processing_state": "queued", "state": "queued", "project_links": [...], "arguments": {}, "automation_profile": null, "action_name": "local/code-coverage", ... } ``` ## Expected Behavior Per spec §agents plan use (lines ~12602-12644), the command must return a structured JSON envelope: ```json { "command": "plan use", "status": "ok", "exit_code": 0, "data": { "plan_id": "01HXM8C2ZK4Q7C2B3F2R4VYV6J", "phase": "strategize", "action": "local/code-coverage", "project": "local/api-service", "automation_profile": "trusted", "attempt": 1, "inputs": { "target_coverage_percent": 85, "automation_profile": "trusted" }, "actors": { "strategy": "local/strategist", "execution": "local/executor", "estimation": null }, "automation": { "profile": "trusted", "source": "CLI flag", "read_only": false }, "context": { "resources": 2, "indexed_files": 347, "view": "strategize", "hot_token_budget": 12000 }, "next_steps": [ "agents plan execute 01HXM8C2ZK4Q7C2B3F2R4VYV6J", "agents plan status 01HXM8C2ZK4Q7C2B3F2R4VYV6J", "agents plan tree 01HXM8C2ZK4Q7C2B3F2R4VYV6J" ] }, "timing": { "started": "2026-02-09T14:30:00Z", "duration_ms": 95 }, "messages": ["Plan created"] } ``` ## Impact - Downstream automation scripts using `agents --format json plan use` will receive incorrect JSON structure - The `next_steps` field (containing the `agents plan execute <id>` command) is missing, breaking scripted workflows - The `actors` object showing strategy/execution/estimation actors is missing ## Spec Reference `docs/specification.md` §agents plan use (lines ~12602-12644) ## Files Affected - `src/cleveragents/cli/commands/plan.py` — `use_action` function (lines ~2239-2241) ## Acceptance Criteria - `agents plan use <action> <project> --format json` returns spec-required envelope with `command: "plan use"`, `status: "ok"`, `exit_code: 0` - `data.next_steps` contains `agents plan execute <plan_id>` as first item - `data.actors` contains `strategy`, `execution`, `estimation` fields - `data.automation` contains `profile`, `source`, `read_only` fields - Behave BDD test covers the JSON envelope structure - No regressions in existing tests - Coverage ≥97% ## Subtasks - [ ] Build spec-compliant JSON envelope builder for `plan use` output - [ ] Include `command: "plan use"`, `status: "ok"`, `exit_code: 0` envelope fields - [ ] Include `data.plan_id`, `data.phase`, `data.action`, `data.project` (first project link) - [ ] Include `data.inputs` (arguments + automation_profile) - [ ] Include `data.actors` (strategy, execution, estimation) - [ ] Include `data.automation` (profile, source, read_only) - [ ] Include `data.next_steps` with `agents plan execute <id>`, `agents plan status <id>`, `agents plan tree <id>` - [ ] Include `timing` and `messages` envelope fields - [ ] Add Behave BDD test scenario verifying JSON envelope structure for `plan use --format json` - [ ] Verify coverage remains ≥97% ## Definition of Done This issue is complete when: - [ ] `agents plan use <action> <project> --format json` returns spec-required envelope with `command: "plan use"`, `status: "ok"`, `exit_code: 0` - [ ] `data.next_steps` contains `agents plan execute <plan_id>` as first item - [ ] `data.actors` contains `strategy`, `execution`, `estimation` fields - [ ] `data.automation` contains `profile`, `source`, `read_only` fields - [ ] Behave BDD test covers the JSON envelope structure - [ ] No regressions in existing tests - [ ] Coverage ≥97% - [ ] A Git commit is created where the **first line** of the commit message matches the Commit Message in Metadata exactly, followed by a blank line, then additional lines providing relevant details about the implementation. - [ ] The commit is pushed to the remote on the branch matching the **Branch** in Metadata exactly. - [ ] The commit is submitted as a **pull request** to `master`, reviewed, and **merged** before this issue is marked done. --- **Automated by CleverAgents Bot** Agent: new-issue-creator

HAL9000 referenced this issue

2026-04-14 18:07:59 +00:00

[AUTO-SPEC] Status: Spec Evolution Pool Supervisor (Cycle 11) #9457

HAL9000 added the

labels

2026-04-14 18:13:04 +00:00

HAL9000 added this to the v3.2.0 milestone

2026-04-14 18:13:04 +00:00

HAL9000 commented

2026-04-14 18:13:04 +00:00

Author

Owner

✅ Triage Decision [AUTO-OWNR-3]: Verified as a spec compliance bug. The plan use --format json returns a raw plan dict instead of the spec-required JSON envelope. Should Have for v3.2.0 — part of the broader JSON envelope compliance pattern.

Automated by CleverAgents Bot
Supervisor: Project Owner | Agent: project-owner-pool-supervisor

✅ **Triage Decision [AUTO-OWNR-3]**: Verified as a spec compliance bug. The `plan use --format json` returns a raw plan dict instead of the spec-required JSON envelope. `Should Have` for v3.2.0 — part of the broader JSON envelope compliance pattern. --- **Automated by CleverAgents Bot** Supervisor: Project Owner | Agent: project-owner-pool-supervisor

HAL9000 referenced this issue

2026-04-14 19:16:01 +00:00

[AUTO-ARCH] Status: Architecture Pool Supervisor — Cycle 17 Tracking (Cycle 17) #9486