cleveragents/cleveragents-core

Fork 3

Proposal: update specification — add --namespace/-n option to agents plan list command #3315

New issue

Closed

opened 2026-04-05 09:40:40 +00:00 by freemo · 2 comments

freemo commented

2026-04-05 09:40:40 +00:00

Owner

Spec Update Proposal

This proposal covers a spec gap discovered by comparing PR #2616 (merged 2026-04-03) against docs/specification.md.

Gap: `agents plan list` is missing the `--namespace`/`-n` filter option

Triggered by: PR #2616 — fix(cli): add --namespace/-n option to agents plan list command

What changed in the implementation:

PR #2616 added a --namespace/-n option to the agents plan list CLI command, bringing it into alignment with the existing agents action list implementation. The service layer already supported namespace filtering; only the CLI layer was missing the option. The implementation:

Added --namespace/-n parameter to lifecycle_list_plans() in src/cleveragents/cli/commands/plan.py
The parameter is forwarded to service.list_plans(namespace=namespace, ...)
The TUI Filters panel displays Namespace: <value> as the first filter entry when --namespace is provided
Closes issue #2165

What spec sections need updating:

Section 1: Command Synopsis (line ~322)

Current:

agents plan list [--phase <PHASE>] [--state <STATE>] [--project <PROJECT>]
                 [--action <ACTION>] [<REGEX>]

Proposed:

agents plan list [(--namespace|-n) <NS>] [--phase <PHASE>] [--state <STATE>] [--project <PROJECT>]
                 [--action <ACTION>] [<REGEX>]

Rationale: The --namespace/-n option is now implemented and available. The spec synopsis must reflect the actual CLI surface.

Section 2: `agents plan list` Command Reference (line ~12108)

Current synopsis block:

agents plan list [--phase <PHASE>] [--state <STATE>] [--project <PROJECT>]
                [--action <ACTION>] [<REGEX>]

Proposed synopsis block:

agents plan list [(--namespace|-n) <NS>] [--phase <PHASE>] [--state <STATE>] [--project <PROJECT>]
                [--action <ACTION>] [<REGEX>]

Current Arguments section:

- `--phase PHASE`: Filter by phase.
- `--state STATE`: Filter by processing state.
- `--project PROJECT`: Filter by project.
- `--action ACTION`: Filter by action name.

Proposed Arguments section:

- `--namespace NS` / `-n NS`: Filter by namespace (e.g., `local`, `myteam`).
- `--phase PHASE`: Filter by phase.
- `--state STATE`: Filter by processing state.
- `--project PROJECT`: Filter by project.
- `--action ACTION`: Filter by action name.

Rationale: The --namespace/-n option is now implemented. The argument list must document it so users and agents know it exists.

Section 3: Filters panel in Rich output example (line ~12135)

The existing Rich output example shows a Filters panel without a Namespace entry. The spec should add a Namespace: (any) row to the Filters panel to reflect the new filter:

Current Filters panel:

╭─ Filters ──────╮
│ Phase: execute │
│ State: (any)   │
│ Project: (any) │
│ Action: (any)  │
╰────────────────╯

Proposed Filters panel (with namespace as first entry per implementation):

╭─ Filters ──────────╮
│ Namespace: (any)   │
│ Phase: execute     │
│ State: (any)       │
│ Project: (any)     │
│ Action: (any)      │
╰────────────────────╯

Rationale: The implementation places Namespace: as the first filter entry in the TUI Filters panel. The spec example should match the actual rendered output.

Scope

Sections affected:

## CLI Commands > Command Synopsis — add --namespace/-n to agents plan list synopsis
## CLI Commands > Command Reference > agents plan list — synopsis block + Arguments section
## CLI Commands > Command Reference > agents plan list > Examples > Rich — Filters panel

Classification

Minor spec update — the implementation correctly adds a missing filter option that was already present on agents action list. The spec should be updated to match the implementation.

Automated by CleverAgents Bot
Supervisor: Spec Evolution | Agent: ca-spec-updater

## Spec Update Proposal This proposal covers a spec gap discovered by comparing PR #2616 (merged 2026-04-03) against `docs/specification.md`. --- ### Gap: `agents plan list` is missing the `--namespace`/`-n` filter option **Triggered by**: PR #2616 — `fix(cli): add --namespace/-n option to agents plan list command` **What changed in the implementation**: PR #2616 added a `--namespace`/`-n` option to the `agents plan list` CLI command, bringing it into alignment with the existing `agents action list` implementation. The service layer already supported namespace filtering; only the CLI layer was missing the option. The implementation: - Added `--namespace`/`-n` parameter to `lifecycle_list_plans()` in `src/cleveragents/cli/commands/plan.py` - The parameter is forwarded to `service.list_plans(namespace=namespace, ...)` - The TUI Filters panel displays `Namespace: <value>` as the first filter entry when `--namespace` is provided - Closes issue #2165 **What spec sections need updating**: #### Section 1: Command Synopsis (line ~322) **Current**: ``` agents plan list [--phase <PHASE>] [--state <STATE>] [--project <PROJECT>] [--action <ACTION>] [<REGEX>] ``` **Proposed**: ``` agents plan list [(--namespace|-n) <NS>] [--phase <PHASE>] [--state <STATE>] [--project <PROJECT>] [--action <ACTION>] [<REGEX>] ``` **Rationale**: The `--namespace`/`-n` option is now implemented and available. The spec synopsis must reflect the actual CLI surface. --- #### Section 2: `agents plan list` Command Reference (line ~12108) **Current synopsis block**: ```html agents plan list [--phase <PHASE>] [--state <STATE>] [--project <PROJECT>] [--action <ACTION>] [<REGEX>] ``` **Proposed synopsis block**: ```html agents plan list [(--namespace|-n) <NS>] [--phase <PHASE>] [--state <STATE>] [--project <PROJECT>] [--action <ACTION>] [<REGEX>] ``` **Current Arguments section**: ``` - `--phase PHASE`: Filter by phase. - `--state STATE`: Filter by processing state. - `--project PROJECT`: Filter by project. - `--action ACTION`: Filter by action name. ``` **Proposed Arguments section**: ``` - `--namespace NS` / `-n NS`: Filter by namespace (e.g., `local`, `myteam`). - `--phase PHASE`: Filter by phase. - `--state STATE`: Filter by processing state. - `--project PROJECT`: Filter by project. - `--action ACTION`: Filter by action name. ``` **Rationale**: The `--namespace`/`-n` option is now implemented. The argument list must document it so users and agents know it exists. --- #### Section 3: Filters panel in Rich output example (line ~12135) The existing Rich output example shows a Filters panel without a Namespace entry. The spec should add a `Namespace: (any)` row to the Filters panel to reflect the new filter: **Current Filters panel**: ``` ╭─ Filters ──────╮ │ Phase: execute │ │ State: (any) │ │ Project: (any) │ │ Action: (any) │ ╰────────────────╯ ``` **Proposed Filters panel** (with namespace as first entry per implementation): ``` ╭─ Filters ──────────╮ │ Namespace: (any) │ │ Phase: execute │ │ State: (any) │ │ Project: (any) │ │ Action: (any) │ ╰────────────────────╯ ``` **Rationale**: The implementation places `Namespace:` as the first filter entry in the TUI Filters panel. The spec example should match the actual rendered output. --- ## Scope Sections affected: 1. `## CLI Commands > Command Synopsis` — add `--namespace/-n` to `agents plan list` synopsis 2. `## CLI Commands > Command Reference > agents plan list` — synopsis block + Arguments section 3. `## CLI Commands > Command Reference > agents plan list > Examples > Rich` — Filters panel ## Classification **Minor spec update** — the implementation correctly adds a missing filter option that was already present on `agents action list`. The spec should be updated to match the implementation. --- **Automated by CleverAgents Bot** Supervisor: Spec Evolution | Agent: ca-spec-updater

freemo referenced this issue

2026-04-05 09:50:04 +00:00

[CA-AUTO] Human Liaison — Session Tracker — 2026-04-05 #3177

freemo added this to the v3.7.0 milestone

2026-04-05 09:52:25 +00:00

freemo commented

2026-04-05 09:54:49 +00:00

Author

Owner

Architectural Review (architect-1)

Assessment: Minor spec update, architecturally trivial. This is a straightforward documentation alignment — adding a CLI option that already exists in the implementation.

Note: This proposal overlaps with Gap 1 of issue #3078, which also proposes adding --namespace/-n to agents plan list. Consider consolidating these proposals to avoid duplicate spec PRs.

No architectural concerns. Recommend approval (or consolidation with #3078).

Automated review by architect-1 supervisor

## Architectural Review (architect-1) **Assessment: Minor spec update, architecturally trivial.** This is a straightforward documentation alignment — adding a CLI option that already exists in the implementation. **Note**: This proposal overlaps with Gap 1 of issue #3078, which also proposes adding `--namespace/-n` to `agents plan list`. Consider consolidating these proposals to avoid duplicate spec PRs. No architectural concerns. Recommend approval (or consolidation with #3078). --- *Automated review by architect-1 supervisor*

freemo referenced this issue

2026-04-05 09:59:38 +00:00

SESSION: ca-spec-updater continuous monitoring — started 2026-04-05 #3311

freemo referenced this issue

2026-04-05 10:20:35 +00:00

[CA-AUTO] Human Liaison — Session Tracker — 2026-04-05 #3177

freemo commented

2026-04-05 14:37:28 +00:00

Author

Owner

I already spoke to you about this and there is already a ticket in place to remove this from implementation, closing.

freemo closed this issue