feat(cli): add action and plan CLI extensions #325

Closed
opened 2026-02-22 23:41:18 +00:00 by freemo · 3 comments
Owner

Metadata

  • Commit Message: feat(cli): add action and plan CLI extensions
  • Branch: feature/m4-cli-extensions

Background

plan use accepts --automation-profile and --invariant flags, persisting them to plan metadata. Actor override flags (--strategy-actor, --execution-actor, --estimation-actor, --invariant-actor) validate namespaced names. plan status/list output includes automation profile and invariants when present.

Acceptance Criteria

  • Add --automation-profile and --invariant flags to plan use and persist to plan metadata.
  • Add actor override flags (--strategy-actor, --execution-actor, --estimation-actor, --invariant-actor) with namespaced validation.
  • Update plan status/list output to include automation_profile + invariants when present.
  • Extend action show output with optional actors, invariants, and inputs_schema when present.
  • Update docs/reference/plan_cli.md and docs/reference/action_cli.md with extended flags + examples.

Definition of Done

This issue is complete when:

  • All subtasks below 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 body should be appropriate in size for a commit message and relatively
    complete in describing what was done.
  • 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.

Subtasks

  • Add --automation-profile and --invariant flags to plan use and persist to plan metadata.
  • Add actor override flags (--strategy-actor, --execution-actor, --estimation-actor, --invariant-actor) with namespaced validation.
  • Update plan status/list output to include automation_profile + invariants when present.
  • Extend action show output with optional actors, invariants, and inputs_schema when present.
  • Update docs/reference/plan_cli.md and docs/reference/action_cli.md with extended flags + examples.
  • Tests (Behave): Add scenarios for automation_profile/invariant flags and actor override validation.
  • Tests (Robot): Add Robot flow for plan use with invariants + automation profile.
  • Tests (ASV): Add benchmarks/cli_extensions_bench.py for parsing overhead.
  • Verify coverage >=97% via nox -s coverage_report. If coverage is <97% then review the current unit test coverage report at build/coverage.xml and use it to write new Behave based unit tests to improve code coverage. Specifically, write Behave style unit tests that are descriptively named and specifically improves coverage on whichever file has the most uncovered lines by writing tests that will target the uncovered lines in the report. Once that is done rerun nox -s coverage_report to verify all tests pass and coverage is above >=97%. Only mark this as complete once coverage is >=97%, if not repeat this task as many times as is needed until coverage reaches >=97%.
  • Run nox (all default sessions, including benchmark), fix any errors if needed ensuring nox passes.

Section: ### Section 13: Additional CLI Commands & UX [Days 10-14]
Status: Open

## Metadata - **Commit Message**: `feat(cli): add action and plan CLI extensions` - **Branch**: `feature/m4-cli-extensions` ## Background `plan use` accepts `--automation-profile` and `--invariant` flags, persisting them to plan metadata. Actor override flags (`--strategy-actor`, `--execution-actor`, `--estimation-actor`, `--invariant-actor`) validate namespaced names. `plan status/list` output includes automation profile and invariants when present. ## Acceptance Criteria - [ ] Add `--automation-profile` and `--invariant` flags to `plan use` and persist to plan metadata. - [ ] Add actor override flags (`--strategy-actor`, `--execution-actor`, `--estimation-actor`, `--invariant-actor`) with namespaced validation. - [ ] Update `plan status/list` output to include automation_profile + invariants when present. - [ ] Extend `action show` output with optional actors, invariants, and inputs_schema when present. - [ ] Update `docs/reference/plan_cli.md` and `docs/reference/action_cli.md` with extended flags + examples. ## Definition of Done This issue is complete when: - All subtasks below 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 body should be appropriate in size for a commit message and relatively complete in describing what was done. - 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. ## Subtasks - [ ] Add `--automation-profile` and `--invariant` flags to `plan use` and persist to plan metadata. - [ ] Add actor override flags (`--strategy-actor`, `--execution-actor`, `--estimation-actor`, `--invariant-actor`) with namespaced validation. - [ ] Update `plan status/list` output to include automation_profile + invariants when present. - [ ] Extend `action show` output with optional actors, invariants, and inputs_schema when present. - [ ] Update `docs/reference/plan_cli.md` and `docs/reference/action_cli.md` with extended flags + examples. - [ ] Tests (Behave): Add scenarios for automation_profile/invariant flags and actor override validation. - [ ] Tests (Robot): Add Robot flow for `plan use` with invariants + automation profile. - [ ] Tests (ASV): Add `benchmarks/cli_extensions_bench.py` for parsing overhead. - [ ] Verify coverage >=97% via `nox -s coverage_report`. If coverage is <97% then review the current unit test coverage report at `build/coverage.xml` and use it to write new Behave based unit tests to improve code coverage. Specifically, write Behave style unit tests that are descriptively named and specifically improves coverage on whichever file has the most uncovered lines by writing tests that will target the uncovered lines in the report. Once that is done rerun `nox -s coverage_report` to verify all tests pass and coverage is above >=97%. Only mark this as complete once coverage is >=97%, if not repeat this task as many times as is needed until coverage reaches >=97%. - [ ] Run `nox` (all default sessions, including benchmark), fix any errors if needed ensuring nox passes. **Section**: ### Section 13: Additional CLI Commands & UX [Days 10-14] **Status**: Open
freemo added this to the (deleted) milestone 2026-02-22 23:41:18 +00:00
freemo self-assigned this 2026-02-22 23:41:18 +00:00
freemo modified the milestone from (deleted) to v3.1.0 2026-02-23 00:07:06 +00:00
Author
Owner

Expected completion (Day 15 rebaseline): Day 26 / 2026-03-06

**Expected completion (Day 15 rebaseline):** Day 26 / 2026-03-06
freemo added the due date 2026-02-19 2026-02-23 18:41:52 +00:00
Author
Owner

Implementation Notes — CLI1.alpha: Plan/Action CLI Extensions

  • 2026-02-23 [Jeff]: Implemented CLI1.alpha. Key changes:
    • Added validate_namespaced_actor() to plan.py for strict namespace/name validation on actor override flags (--strategy-actor, --execution-actor, --estimation-actor, --invariant-actor)
    • Updated _plan_spec_dict() to include estimation_actor, invariant_actor, and invariants fields in all output formats (json, yaml, plain, table)
    • Updated _print_lifecycle_plan() rich panel to display invariants with source provenance tags
    • Updated plan_status summary table to include Profile and Invariants columns
    • Updated lifecycle_list_plans table to include Profile and Invariants columns
    • Extended action.py _action_spec_dict() to conditionally include estimation_actor, invariant_actor, and inputs_schema fields
    • Extended _print_action() rich panel to display estimation actor, invariant actor, invariants list, inputs_schema, and automation_profile
    • --automation-profile flag on plan use validates against BUILTIN_PROFILES and persists to plan metadata
    • --invariant flags on plan use are passed through to PlanLifecycleService.use_action() as PlanInvariant objects with InvariantSource.PLAN
    • Created docs/reference/plan_cli.md and docs/reference/action_cli.md reference documentation
    • Created features/cli_extensions.feature with 25 Behave scenarios covering all new functionality
    • Created features/steps/cli_extensions_steps.py with all step definitions
    • Created robot/cli_extensions.robot with 5 Robot Framework integration tests
    • Created benchmarks/cli_extensions_bench.py with 6 ASV benchmark suites

(Migrated from docs/implementation-notes.md)

## Implementation Notes — CLI1.alpha: Plan/Action CLI Extensions - **2026-02-23** [Jeff]: Implemented CLI1.alpha. Key changes: - Added `validate_namespaced_actor()` to `plan.py` for strict `namespace/name` validation on actor override flags (`--strategy-actor`, `--execution-actor`, `--estimation-actor`, `--invariant-actor`) - Updated `_plan_spec_dict()` to include `estimation_actor`, `invariant_actor`, and `invariants` fields in all output formats (json, yaml, plain, table) - Updated `_print_lifecycle_plan()` rich panel to display invariants with source provenance tags - Updated `plan_status` summary table to include Profile and Invariants columns - Updated `lifecycle_list_plans` table to include Profile and Invariants columns - Extended `action.py` `_action_spec_dict()` to conditionally include `estimation_actor`, `invariant_actor`, and `inputs_schema` fields - Extended `_print_action()` rich panel to display estimation actor, invariant actor, invariants list, inputs_schema, and automation_profile - `--automation-profile` flag on `plan use` validates against `BUILTIN_PROFILES` and persists to plan metadata - `--invariant` flags on `plan use` are passed through to `PlanLifecycleService.use_action()` as `PlanInvariant` objects with `InvariantSource.PLAN` - Created `docs/reference/plan_cli.md` and `docs/reference/action_cli.md` reference documentation - Created `features/cli_extensions.feature` with 25 Behave scenarios covering all new functionality - Created `features/steps/cli_extensions_steps.py` with all step definitions - Created `robot/cli_extensions.robot` with 5 Robot Framework integration tests - Created `benchmarks/cli_extensions_bench.py` with 6 ASV benchmark suites *(Migrated from `docs/implementation-notes.md`)*
Author
Owner

Implementation Notes

Design Decisions

  • The core CLI extension code (plan use flags, action show output, docs) was already implemented on master through prior incremental commits.
  • This commit adds 4 additional Behave test scenarios to improve coverage of edge cases: single plan status with invariants, single plan status with automation profile, action show with automation profile, and action show JSON without invariant_actor.
  • All extended flags (--automation-profile, --invariant, --strategy-actor, --execution-actor, --estimation-actor, --invariant-actor) are operational and wire through to plan metadata.
  • validate_namespaced_actor() validates the namespace/name format for actor override flags.

Quality Gates

Full nox suite passed:

  • lint: PASS
  • typecheck: PASS (0 errors)
  • unit_tests: PASS (5544 scenarios, 0 failed)
  • integration_tests: PASS (652 tests, 0 failed)
  • coverage: 97% (meets threshold)
  • All other sessions (format, security_scan, dead_code, build, docs, benchmark): PASS

PR

PR #413 from feature/m4-cli-extensions to master.

## Implementation Notes ### Design Decisions - The core CLI extension code (plan use flags, action show output, docs) was already implemented on master through prior incremental commits. - This commit adds 4 additional Behave test scenarios to improve coverage of edge cases: single plan status with invariants, single plan status with automation profile, action show with automation profile, and action show JSON without invariant_actor. - All extended flags (`--automation-profile`, `--invariant`, `--strategy-actor`, `--execution-actor`, `--estimation-actor`, `--invariant-actor`) are operational and wire through to plan metadata. - `validate_namespaced_actor()` validates the `namespace/name` format for actor override flags. ### Quality Gates Full nox suite passed: - lint: PASS - typecheck: PASS (0 errors) - unit_tests: PASS (5544 scenarios, 0 failed) - integration_tests: PASS (652 tests, 0 failed) - coverage: 97% (meets threshold) - All other sessions (format, security_scan, dead_code, build, docs, benchmark): PASS ### PR PR #413 from `feature/m4-cli-extensions` to `master`.
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".

2026-02-19

Blocks
#364 Epic: Additional CLI Commands & UX
cleveragents/cleveragents-core
Depends on
Reference
cleveragents/cleveragents-core#325
No description provided.