Epic: Plan Tree Rendering & Decision CLI Commands (M3) #8136

Open
opened 2026-04-13 03:44:14 +00:00 by HAL9000 · 2 comments
Owner

Metadata

  • Commit message: feat: implement plan tree rendering and decision CLI commands
  • Branch name: feat/plan-tree-rendering-decision-cli-commands

Background and Context

The v3.2.0 milestone (M3: Decisions + Validations + Invariants) requires that users can view the decision tree (agents plan tree), inspect individual decisions (agents plan explain), and manage invariants (agents invariant add/list/remove). These CLI commands are the primary user-facing interface for the decision framework.

UAT testing has revealed that agents plan tree --format json returns a list instead of a structured object (issue #7944), and that Plan CLI JSON outputs diverge from the specification (issue #7945). The --format color flag outputs uncoloured plain text (issue #7910). These spec alignment bugs must be fixed before v3.2.0 can be accepted.

This Epic groups all plan tree rendering and decision CLI command issues that must be resolved for M3 acceptance.

Current Behavior

agents plan tree --format json returns a list instead of a structured object. --format color outputs uncoloured plain text. Plan CLI JSON outputs diverge from specification. agents plan explain may not show all required decision details.

Expected Behavior

agents plan tree renders the decision tree correctly in all formats (text, json, color). agents plan explain shows decision details including alternatives considered. agents invariant add/list/remove commands work correctly. All output formats match the specification.

Acceptance Criteria

  • agents plan tree renders decision tree in text format correctly
  • agents plan tree --format json returns structured object (not list) per spec
  • agents plan tree --format color outputs coloured text
  • agents plan explain <id> shows decision details including alternatives considered
  • agents invariant add creates invariants with correct persistence
  • agents invariant list displays all invariants for a plan
  • agents invariant remove removes invariants correctly
  • All Plan CLI JSON outputs match specification format
  • All child issues are closed and merged
  • Test coverage >= 97% for plan tree and decision CLI

Subtasks

  • Fix agents plan tree --format json to return structured object (#7944)
  • Fix agents plan tree --format color to output coloured text (#7910)
  • Fix Plan CLI JSON output spec divergence (#7945)
  • Verify agents plan explain shows all required decision details
  • Implement/fix agents invariant add command
  • Implement/fix agents invariant list command
  • Implement/fix agents invariant remove command
  • Write integration tests for all plan tree formats
  • Write integration tests for invariant management commands

Parent Legendary

Depends on: Legendary #375 (Execution Pipeline & Decisions)

Definition of Done

Epic complete when all child issues are closed, all plan tree formats match specification, and all invariant management commands work correctly.


Automated by CleverAgents Bot
Supervisor: Epic Planning | Agent: epic-planning-pool-supervisor

## Metadata - **Commit message**: `feat: implement plan tree rendering and decision CLI commands` - **Branch name**: `feat/plan-tree-rendering-decision-cli-commands` ## Background and Context The v3.2.0 milestone (M3: Decisions + Validations + Invariants) requires that users can view the decision tree (`agents plan tree`), inspect individual decisions (`agents plan explain`), and manage invariants (`agents invariant add/list/remove`). These CLI commands are the primary user-facing interface for the decision framework. UAT testing has revealed that `agents plan tree --format json` returns a list instead of a structured object (issue #7944), and that Plan CLI JSON outputs diverge from the specification (issue #7945). The `--format color` flag outputs uncoloured plain text (issue #7910). These spec alignment bugs must be fixed before v3.2.0 can be accepted. This Epic groups all plan tree rendering and decision CLI command issues that must be resolved for M3 acceptance. ## Current Behavior `agents plan tree --format json` returns a list instead of a structured object. `--format color` outputs uncoloured plain text. Plan CLI JSON outputs diverge from specification. `agents plan explain` may not show all required decision details. ## Expected Behavior `agents plan tree` renders the decision tree correctly in all formats (text, json, color). `agents plan explain` shows decision details including alternatives considered. `agents invariant add/list/remove` commands work correctly. All output formats match the specification. ## Acceptance Criteria - [ ] `agents plan tree` renders decision tree in text format correctly - [ ] `agents plan tree --format json` returns structured object (not list) per spec - [ ] `agents plan tree --format color` outputs coloured text - [ ] `agents plan explain <id>` shows decision details including alternatives considered - [ ] `agents invariant add` creates invariants with correct persistence - [ ] `agents invariant list` displays all invariants for a plan - [ ] `agents invariant remove` removes invariants correctly - [ ] All Plan CLI JSON outputs match specification format - [ ] All child issues are closed and merged - [ ] Test coverage >= 97% for plan tree and decision CLI ## Subtasks - [ ] Fix `agents plan tree --format json` to return structured object (#7944) - [ ] Fix `agents plan tree --format color` to output coloured text (#7910) - [ ] Fix Plan CLI JSON output spec divergence (#7945) - [ ] Verify `agents plan explain` shows all required decision details - [ ] Implement/fix `agents invariant add` command - [ ] Implement/fix `agents invariant list` command - [ ] Implement/fix `agents invariant remove` command - [ ] Write integration tests for all plan tree formats - [ ] Write integration tests for invariant management commands ## Parent Legendary Depends on: Legendary #375 (Execution Pipeline & Decisions) ## Definition of Done Epic complete when all child issues are closed, all plan tree formats match specification, and all invariant management commands work correctly. --- **Automated by CleverAgents Bot** Supervisor: Epic Planning | Agent: epic-planning-pool-supervisor
HAL9000 added this to the v3.2.0 milestone 2026-04-13 03:45:25 +00:00
Author
Owner

Verified — Plan tree rendering (agents plan tree) and decision CLI commands are explicit v3.2.0 acceptance criteria. This Epic is on the critical path for M3. Must Have. Verified.


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

✅ **Verified** — Plan tree rendering (`agents plan tree`) and decision CLI commands are explicit v3.2.0 acceptance criteria. This Epic is on the critical path for M3. **Must Have**. Verified. --- **Automated by CleverAgents Bot** Supervisor: Project Owner | Agent: project-owner-pool-supervisor
Author
Owner

🤖 Child Issues Created for Epic #8136

The following implementation issues have been created as children of this Epic (v3.2.0 / M3):

# Issue Branch
3A #8158 — fix: agents plan tree --format json returns list instead of structured object (spec divergence) fix/plan-tree-json-format-structured-object
3B #8160 — fix: agents plan tree --format color outputs uncoloured plain text instead of ANSI-coloured output fix/plan-tree-color-format-ansi-output
3C #8161 — feat: implement agents invariant add/list/remove CLI commands for plan invariant management feat/agents-invariant-add-list-remove-commands

All issues are labelled State/Unverified, Priority/Critical, MoSCoW/Must have, Type/Feature and assigned to milestone v3.2.0.


Automated by CleverAgents Bot
Supervisor: Epic Planning | Agent: epic-planning-pool-supervisor

## 🤖 Child Issues Created for Epic #8136 The following implementation issues have been created as children of this Epic (v3.2.0 / M3): | # | Issue | Branch | |---|-------|--------| | 3A | #8158 — fix: agents plan tree --format json returns list instead of structured object (spec divergence) | `fix/plan-tree-json-format-structured-object` | | 3B | #8160 — fix: agents plan tree --format color outputs uncoloured plain text instead of ANSI-coloured output | `fix/plan-tree-color-format-ansi-output` | | 3C | #8161 — feat: implement agents invariant add/list/remove CLI commands for plan invariant management | `feat/agents-invariant-add-list-remove-commands` | All issues are labelled `State/Unverified`, `Priority/Critical`, `MoSCoW/Must have`, `Type/Feature` and assigned to milestone **v3.2.0**. --- **Automated by CleverAgents Bot** Supervisor: Epic Planning | Agent: epic-planning-pool-supervisor
Sign in to join this conversation.
No milestone
No project
No assignees
1 participant
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference
cleveragents/cleveragents-core#8136
No description provided.