cleveragents/cleveragents-core

Fork 3

UAT: `agents plan use` JSON/YAML output missing spec-required fields — `inputs`, `actors`, `automation`, `context`, and `next_steps` keys absent #2956

New issue

Open

opened 2026-04-05 02:56:40 +00:00 by freemo · 3 comments

freemo commented

2026-04-05 02:56:40 +00:00

Owner

Metadata

Branch: fix/m6-plan-use-json-output-missing-fields
Commit Message: fix(cli): add missing inputs, actors, automation, context, next_steps to plan use JSON output
Milestone: v3.5.0
Parent Epic: #397

Background and Context

The spec (docs/specification.md §agents plan use) defines the JSON output for agents plan use --format json as a fully-enveloped response containing a data object with the following keys: plan_id, phase, action, project, automation_profile, attempt, inputs, actors, automation, context, and next_steps. The entire response must also be wrapped in the standard CLI envelope with command, status, exit_code, data, timing, and messages keys.

The current implementation in src/cleveragents/cli/commands/plan.py (use_action(), ~line 1705) calls _plan_spec_dict(plan) which returns a flat dict containing only the basic plan fields. It does not populate inputs, actors, automation, context, or next_steps, and the response is not wrapped in the required envelope structure.

Spec-required JSON output shape:

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

Current Behavior

Running agents plan use local/my-action my-project --format json outputs a flat plan dict produced by _plan_spec_dict(plan). The output:

Is not wrapped in the spec-required command/status/exit_code/data/timing/messages envelope.
Is missing the inputs key (arguments passed to the plan).
Is missing the actors key (strategy, execution, estimation actor references).
Is missing the automation key (profile, source, read_only fields).
Is missing the context key (resources, indexed_files, view, hot_token_budget).
Is missing the next_steps key (suggested follow-up commands with the actual plan ID).

Code location: src/cleveragents/cli/commands/plan.py, use_action() function (~line 1705).

Expected Behavior

Running agents plan use <action> <project> --format json should output a fully spec-compliant JSON object that:

Is wrapped in the standard CLI envelope (command, status, exit_code, data, timing, messages).
Includes inputs reflecting the --arg / -a key=value pairs passed on the CLI.
Includes actors with strategy, execution, and estimation keys reflecting the plan's configured actors (or null if not set).
Includes automation with profile (resolved profile name), source (e.g. "CLI flag", "action default", "global default"), and read_only (boolean).
Includes context with resources (count), indexed_files (count), view (current phase view name), and hot_token_budget (integer).
Includes next_steps as a list of suggested follow-up CLI commands using the actual plan ID (execute, status, tree).

The same fields must also be present in YAML output (--format yaml).

Acceptance Criteria

agents plan use <action> <project> --format json outputs a JSON object wrapped in the standard CLI envelope (command, status, exit_code, data, timing, messages)
The data object contains an inputs key reflecting all --arg/-a arguments passed on the CLI
The data object contains an actors key with strategy, execution, and estimation sub-keys reflecting the plan's configured actors (null if not configured)
The data object contains an automation key with profile, source, and read_only sub-keys
The data object contains a context key with resources, indexed_files, view, and hot_token_budget sub-keys
The data object contains a next_steps key listing agents plan execute, agents plan status, and agents plan tree commands with the actual plan ID
agents plan use <action> <project> --format yaml outputs the same fields in YAML format
Existing Behave/Robot tests for agents plan use are updated to assert the new fields
New Behave scenarios cover: default actors (null), explicit actor overrides, automation source variants (CLI flag, action default, global default)

Subtasks

Audit _plan_spec_dict(plan) in src/cleveragents/cli/commands/plan.py to understand what it currently returns
Extend use_action() (~line 1705) to build the full spec-compliant envelope and populate inputs, actors, automation, context, and next_steps
Implement helper to resolve automation.source (CLI flag vs. action default vs. global default)
Implement helper to build context dict (resource count, indexed file count, view name, hot token budget)
Implement next_steps list builder using the actual plan ID
Update YAML output path to include the same fields
Tests (Behave): Add/update scenarios for agents plan use --format json asserting all new fields
Tests (Behave): Add scenarios for --format yaml asserting the same fields in YAML output
Tests (Robot): Add/update integration test for agents plan use JSON output shape
Verify coverage >= 97% via nox -s coverage_report
Run nox (all default sessions), fix any errors

Definition of Done

This issue is complete when:

All subtasks above are completed and checked off.
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.
All nox stages pass.
Coverage >= 97%.

Supporting Information

Code location: src/cleveragents/cli/commands/plan.py, use_action() function (~line 1705), calls _plan_spec_dict(plan)
Spec reference: docs/specification.md §agents plan use — JSON output format
Parent Epic: #397 (Epic: Server & Autonomy Infrastructure)
Discovered during: UAT testing of agents plan use --format json output compliance

Automated by CleverAgents Bot
Supervisor: UAT Testing | Agent: ca-uat-tester

## Metadata - **Branch**: `fix/m6-plan-use-json-output-missing-fields` - **Commit Message**: `fix(cli): add missing inputs, actors, automation, context, next_steps to plan use JSON output` - **Milestone**: v3.5.0 - **Parent Epic**: #397 ## Background and Context The spec (`docs/specification.md` §`agents plan use`) defines the JSON output for `agents plan use --format json` as a fully-enveloped response containing a `data` object with the following keys: `plan_id`, `phase`, `action`, `project`, `automation_profile`, `attempt`, `inputs`, `actors`, `automation`, `context`, and `next_steps`. The entire response must also be wrapped in the standard CLI envelope with `command`, `status`, `exit_code`, `data`, `timing`, and `messages` keys. The current implementation in `src/cleveragents/cli/commands/plan.py` (`use_action()`, ~line 1705) calls `_plan_spec_dict(plan)` which returns a flat dict containing only the basic plan fields. It does not populate `inputs`, `actors`, `automation`, `context`, or `next_steps`, and the response is not wrapped in the required envelope structure. **Spec-required JSON output shape:** ```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"] } ``` ## Current Behavior Running `agents plan use local/my-action my-project --format json` outputs a flat plan dict produced by `_plan_spec_dict(plan)`. The output: - Is **not** wrapped in the spec-required `command`/`status`/`exit_code`/`data`/`timing`/`messages` envelope. - Is **missing** the `inputs` key (arguments passed to the plan). - Is **missing** the `actors` key (`strategy`, `execution`, `estimation` actor references). - Is **missing** the `automation` key (`profile`, `source`, `read_only` fields). - Is **missing** the `context` key (`resources`, `indexed_files`, `view`, `hot_token_budget`). - Is **missing** the `next_steps` key (suggested follow-up commands with the actual plan ID). **Code location:** `src/cleveragents/cli/commands/plan.py`, `use_action()` function (~line 1705). ## Expected Behavior Running `agents plan use <action> <project> --format json` should output a fully spec-compliant JSON object that: 1. Is wrapped in the standard CLI envelope (`command`, `status`, `exit_code`, `data`, `timing`, `messages`). 2. Includes `inputs` reflecting the `--arg` / `-a` key=value pairs passed on the CLI. 3. Includes `actors` with `strategy`, `execution`, and `estimation` keys reflecting the plan's configured actors (or `null` if not set). 4. Includes `automation` with `profile` (resolved profile name), `source` (e.g. `"CLI flag"`, `"action default"`, `"global default"`), and `read_only` (boolean). 5. Includes `context` with `resources` (count), `indexed_files` (count), `view` (current phase view name), and `hot_token_budget` (integer). 6. Includes `next_steps` as a list of suggested follow-up CLI commands using the actual plan ID (execute, status, tree). The same fields must also be present in YAML output (`--format yaml`). ## Acceptance Criteria - [ ] `agents plan use <action> <project> --format json` outputs a JSON object wrapped in the standard CLI envelope (`command`, `status`, `exit_code`, `data`, `timing`, `messages`) - [ ] The `data` object contains an `inputs` key reflecting all `--arg`/`-a` arguments passed on the CLI - [ ] The `data` object contains an `actors` key with `strategy`, `execution`, and `estimation` sub-keys reflecting the plan's configured actors (null if not configured) - [ ] The `data` object contains an `automation` key with `profile`, `source`, and `read_only` sub-keys - [ ] The `data` object contains a `context` key with `resources`, `indexed_files`, `view`, and `hot_token_budget` sub-keys - [ ] The `data` object contains a `next_steps` key listing `agents plan execute`, `agents plan status`, and `agents plan tree` commands with the actual plan ID - [ ] `agents plan use <action> <project> --format yaml` outputs the same fields in YAML format - [ ] Existing Behave/Robot tests for `agents plan use` are updated to assert the new fields - [ ] New Behave scenarios cover: default actors (null), explicit actor overrides, automation source variants (CLI flag, action default, global default) ## Subtasks - [ ] Audit `_plan_spec_dict(plan)` in `src/cleveragents/cli/commands/plan.py` to understand what it currently returns - [ ] Extend `use_action()` (~line 1705) to build the full spec-compliant envelope and populate `inputs`, `actors`, `automation`, `context`, and `next_steps` - [ ] Implement helper to resolve `automation.source` (CLI flag vs. action default vs. global default) - [ ] Implement helper to build `context` dict (resource count, indexed file count, view name, hot token budget) - [ ] Implement `next_steps` list builder using the actual plan ID - [ ] Update YAML output path to include the same fields - [ ] Tests (Behave): Add/update scenarios for `agents plan use --format json` asserting all new fields - [ ] Tests (Behave): Add scenarios for `--format yaml` asserting the same fields in YAML output - [ ] Tests (Robot): Add/update integration test for `agents plan use` JSON output shape - [ ] Verify coverage >= 97% via `nox -s coverage_report` - [ ] Run `nox` (all default sessions), fix any errors ## Definition of Done This issue is complete when: - All subtasks above are completed and checked off. - 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. - All nox stages pass. - Coverage >= 97%. ## Supporting Information - **Code location**: `src/cleveragents/cli/commands/plan.py`, `use_action()` function (~line 1705), calls `_plan_spec_dict(plan)` - **Spec reference**: `docs/specification.md` §`agents plan use` — JSON output format - **Parent Epic**: #397 (Epic: Server & Autonomy Infrastructure) - **Discovered during**: UAT testing of `agents plan use --format json` output compliance --- **Automated by CleverAgents Bot** Supervisor: UAT Testing | Agent: ca-uat-tester

freemo added this to the v3.5.0 milestone

2026-04-05 02:56:49 +00:00

freemo added a new dependency

2026-04-05 02:57:11 +00:00

#397 Epic: Server & Autonomy Infrastructure

freemo commented

2026-04-05 03:01:11 +00:00

Author

Owner

Issue triaged by project owner:

State: Verified
Priority: Confirmed
MoSCoW: Should Have

Valid finding verified during batch triage.

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

Issue triaged by project owner: - **State**: Verified - **Priority**: Confirmed - **MoSCoW**: Should Have Valid finding verified during batch triage. --- **Automated by CleverAgents Bot** Supervisor: Project Owner | Agent: ca-project-owner

freemo referenced this issue

2026-04-05 06:15:22 +00:00

[CA-AUTO] UAT Pool Supervisor — v3.2.0–v3.7.0 — Session Tracker #3094

freemo commented

2026-04-06 18:45:59 +00:00

Author

Owner

Milestone Triage Decision: Moved to Backlog

This CLI output formatting issue has been moved out of v3.5.0 during aggressive milestone triage. While important for spec compliance, it does not block core autonomy hardening functionality.

Reasoning:

v3.5.0 focus: Essential autonomy hardening (guard enforcement, A2A facade, plan lifecycle)
This issue: CLI output formatting (plan use missing fields) - spec compliance
Impact: UX consistency, not functional capability

Will be addressed in a future milestone focused on CLI polish and spec compliance.

**Milestone Triage Decision: Moved to Backlog** This CLI output formatting issue has been moved out of v3.5.0 during aggressive milestone triage. While important for spec compliance, it does not block core autonomy hardening functionality. **Reasoning:** - v3.5.0 focus: Essential autonomy hardening (guard enforcement, A2A facade, plan lifecycle) - This issue: CLI output formatting (`plan use` missing fields) - spec compliance - Impact: UX consistency, not functional capability Will be addressed in a future milestone focused on CLI polish and spec compliance.

freemo commented

2026-04-06 22:44:13 +00:00

Author

Owner

This issue has been moved to the backlog as part of an aggressive grooming of the v3.5.0 milestone. It has been deemed non-critical for the minimal viability of the milestone and will be addressed in a future release.