UAT: `agents plan use` uses wrong JSON output format — missing spec-required `actors`, `automation`, `context`, `next_steps` fields #3804

New issue

Open

opened 2026-04-06 06:27:55 +00:00 by freemo · 0 comments

freemo commented

2026-04-06 06:27:55 +00:00

Owner

Metadata

Branch: fix/plan-use-json-output-format
Commit Message: fix(cli): use spec-required output structure for agents plan use non-rich output formats
Milestone: Backlog (see note below)
Parent Epic: #397

Backlog note: This issue was discovered during autonomous operation
on milestone v3.3.0. It does not block milestone completion and has been
placed in the backlog for human review and future milestone assignment.

Note on parent epic: This issue is linked to #397 ("Epic: Server & Autonomy Infrastructure"), which covers output rendering and CLI polish for plan lifecycle commands — consistent with the similar issue #3792 (agents plan execute wrong JSON format).

Bug Description

The agents plan use command uses _plan_spec_dict(plan) for non-rich output formats (JSON, YAML, plain, table), but the specification (§agents plan use) requires a completely different output structure with actors, automation, context, and next_steps fields.

Expected Behavior (from spec §agents plan use)

The JSON output must follow this structure:

{
  "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"]
}

Actual Behavior

The command uses _plan_spec_dict(plan) which returns a flat plan model dict with fields like plan_id, namespaced_name, phase, processing_state, state, project_links, arguments, automation_profile, action_name, etc. This does not match the spec-required structure.

Key missing fields:

"command": "plan use" envelope
"actors" object with strategy, execution, estimation
"automation" object with profile, source, read_only
"context" object with resources, indexed_files, view, hot_token_budget
"next_steps" array with suggested follow-up commands
"messages": ["Plan created"]

Code Location

src/cleveragents/cli/commands/plan.py lines ~1839-1841 (in use_action function):

if fmt != OutputFormat.RICH.value:
    data = _plan_spec_dict(plan)  # BUG: should use spec-required format
    console.print(format_output(data, fmt))

Impact

Any tooling, scripts, or integrations that parse agents plan use --format json output will receive incorrect data
The spec-required actors, automation, context, and next_steps fields are absent
Users cannot programmatically extract the suggested next steps after plan creation

Steps to Reproduce

Create an action: agents action create --config my-action.yaml
Run agents plan use local/my-action local/my-project --format json
Observe output uses plan model fields instead of spec-required use envelope

Subtasks

Create a _use_output_dict(plan, automation_profile_source, context_info) helper function
Replace _plan_spec_dict(plan) with the new helper in the use_action CLI command
Include actors, automation, context, next_steps in the output
Add BDD test (Behave) verifying the JSON output structure matches the spec
Verify YAML and plain formats also match spec
Run nox -s coverage_report, verify coverage >= 97%
Run nox (all default sessions), fix any errors

Definition of Done

This issue is complete when:

All subtasks above are completed and checked off.
agents plan use --format json output matches spec §agents plan use JSON example exactly (including actors, automation, context, next_steps fields).
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.
BDD test coverage >= 97% maintained.
All nox stages pass.

Automated by CleverAgents Bot
Supervisor: UAT Testing | Agent: ca-new-issue-creator

## Metadata - **Branch**: `fix/plan-use-json-output-format` - **Commit Message**: `fix(cli): use spec-required output structure for agents plan use non-rich output formats` - **Milestone**: Backlog (see note below) - **Parent Epic**: #397 > **Backlog note:** This issue was discovered during autonomous operation > on milestone v3.3.0. It does not block milestone completion and has been > placed in the backlog for human review and future milestone assignment. > **Note on parent epic:** This issue is linked to #397 ("Epic: Server & Autonomy Infrastructure"), which covers output rendering and CLI polish for plan lifecycle commands — consistent with the similar issue #3792 (`agents plan execute` wrong JSON format). ## Bug Description The `agents plan use` command uses `_plan_spec_dict(plan)` for non-rich output formats (JSON, YAML, plain, table), but the specification (§agents plan use) requires a completely different output structure with `actors`, `automation`, `context`, and `next_steps` fields. ### Expected Behavior (from spec §agents plan use) The JSON output must follow this structure: ```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"] } ``` ### Actual Behavior The command uses `_plan_spec_dict(plan)` which returns a flat plan model dict with fields like `plan_id`, `namespaced_name`, `phase`, `processing_state`, `state`, `project_links`, `arguments`, `automation_profile`, `action_name`, etc. This does **not** match the spec-required structure. Key missing fields: - `"command": "plan use"` envelope - `"actors"` object with `strategy`, `execution`, `estimation` - `"automation"` object with `profile`, `source`, `read_only` - `"context"` object with `resources`, `indexed_files`, `view`, `hot_token_budget` - `"next_steps"` array with suggested follow-up commands - `"messages": ["Plan created"]` ### Code Location `src/cleveragents/cli/commands/plan.py` lines ~1839-1841 (in `use_action` function): ```python if fmt != OutputFormat.RICH.value: data = _plan_spec_dict(plan) # BUG: should use spec-required format console.print(format_output(data, fmt)) ``` ### Impact - Any tooling, scripts, or integrations that parse `agents plan use --format json` output will receive incorrect data - The spec-required `actors`, `automation`, `context`, and `next_steps` fields are absent - Users cannot programmatically extract the suggested next steps after plan creation ### Steps to Reproduce 1. Create an action: `agents action create --config my-action.yaml` 2. Run `agents plan use local/my-action local/my-project --format json` 3. Observe output uses plan model fields instead of spec-required use envelope ## Subtasks - [ ] Create a `_use_output_dict(plan, automation_profile_source, context_info)` helper function - [ ] Replace `_plan_spec_dict(plan)` with the new helper in the `use_action` CLI command - [ ] Include `actors`, `automation`, `context`, `next_steps` in the output - [ ] Add BDD test (Behave) verifying the JSON output structure matches the spec - [ ] Verify YAML and plain formats also match spec - [ ] Run `nox -s coverage_report`, verify coverage >= 97% - [ ] Run `nox` (all default sessions), fix any errors ## Definition of Done This issue is complete when: - All subtasks above are completed and checked off. - `agents plan use --format json` output matches spec §agents plan use JSON example exactly (including `actors`, `automation`, `context`, `next_steps` fields). - 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. - BDD test coverage >= 97% maintained. - All nox stages pass. --- **Automated by CleverAgents Bot** Supervisor: UAT Testing | Agent: ca-new-issue-creator

freemo added a new dependency

2026-04-06 06:28:13 +00:00

#397 Epic: Server & Autonomy Infrastructure

freemo added the

Points

label

2026-04-06 06:29:53 +00:00

freemo referenced this issue

2026-04-06 06:30:26 +00:00

[Automated] CleverAgents Build Session - 2026-04-06 #3775

freemo referenced this issue

2026-04-06 06:41:50 +00:00