Proposal: update specification — remove --namespace examples from agents plan list (spec internal inconsistency) #3453

Open
opened 2026-04-05 17:22:14 +00:00 by freemo · 3 comments
Owner

Spec Update Proposal

Triggered by: Proactive spec scan — internal inconsistency detected between two sections of docs/specification.md


Gap: --namespace appears in spec examples but not in the formal command definition

What was found:

The docs/specification.md has an internal inconsistency regarding the --namespace option for agents plan list:

  1. Formal command definition (line 12111) — does NOT include --namespace:

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

    Arguments listed: --phase, --state, --project, --action — no --namespace.

  2. "Step 4: Monitor Across the Team" examples (lines 41938, 41971) — DOES use --namespace:

    $ agents plan list --namespace myteam
    $ agents plan list --namespace myteam --state processing
    

Context:

  • PR #2616 (fix(cli): add --namespace/-n option to agents plan list command) was merged on 2026-04-03, adding the --namespace option to the implementation.
  • Proposal #3315 (Proposal: update specification — add --namespace/-n option to agents plan list command) was rejected by @freemo with the comment: "I already spoke to you about this and there is already a ticket in place to remove this from implementation, closing."
  • This means the CTO's intent is to remove --namespace from the implementation, not add it to the spec.
  • The spec examples at lines 41938/41971 were pre-existing (they appear to be from an earlier design iteration) and were never removed when the formal command definition was finalized without --namespace.

What spec sections need updating:

The examples at lines 41938 and 41971 (and surrounding context in "Step 4: Monitor Across the Team") should be updated to remove the --namespace filter, since:

  1. The formal spec definition does not include --namespace
  2. The CTO has explicitly rejected adding --namespace to the spec
  3. The implementation is planned to have --namespace removed

Proposed change:

In the "Step 4: Monitor Across the Team" section, replace the --namespace myteam examples with equivalent examples that use only the documented filters (--phase, --state, --project, --action). For example:

  • $ agents plan list --namespace myteam$ agents plan list --state processing
  • $ agents plan list --namespace myteam --state processing$ agents plan list --state processing

The Filters panel in the example output should also be updated to remove the Namespace: myteam entry.

Rationale: The spec should be internally consistent. The formal command definition is the authoritative reference; the examples section should not demonstrate options that aren't in the formal definition. Since the CTO has explicitly rejected adding --namespace to the spec, the examples must be updated to match the formal definition.


Scope

Sections affected:

  1. Lines ~41934–41997 — "Step 4: Monitor Across the Team" section — remove --namespace from two example commands and update the Filters panel output

Classification

Minor spec update — removing inconsistent examples to align with the formal command definition. No architectural changes.


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

## Spec Update Proposal **Triggered by**: Proactive spec scan — internal inconsistency detected between two sections of `docs/specification.md` --- ### Gap: `--namespace` appears in spec examples but not in the formal command definition **What was found**: The `docs/specification.md` has an internal inconsistency regarding the `--namespace` option for `agents plan list`: 1. **Formal command definition** (line 12111) — does NOT include `--namespace`: ``` agents plan list [--phase <PHASE>] [--state <STATE>] [--project <PROJECT>] [--action <ACTION>] [<REGEX>] ``` Arguments listed: `--phase`, `--state`, `--project`, `--action` — no `--namespace`. 2. **"Step 4: Monitor Across the Team" examples** (lines 41938, 41971) — DOES use `--namespace`: ``` $ agents plan list --namespace myteam $ agents plan list --namespace myteam --state processing ``` **Context**: - PR #2616 (`fix(cli): add --namespace/-n option to agents plan list command`) was merged on 2026-04-03, adding the `--namespace` option to the implementation. - Proposal #3315 (`Proposal: update specification — add --namespace/-n option to agents plan list command`) was **rejected** by @freemo with the comment: *"I already spoke to you about this and there is already a ticket in place to remove this from implementation, closing."* - This means the CTO's intent is to **remove** `--namespace` from the implementation, not add it to the spec. - The spec examples at lines 41938/41971 were pre-existing (they appear to be from an earlier design iteration) and were never removed when the formal command definition was finalized without `--namespace`. **What spec sections need updating**: The examples at lines 41938 and 41971 (and surrounding context in "Step 4: Monitor Across the Team") should be updated to remove the `--namespace` filter, since: 1. The formal spec definition does not include `--namespace` 2. The CTO has explicitly rejected adding `--namespace` to the spec 3. The implementation is planned to have `--namespace` removed **Proposed change**: In the "Step 4: Monitor Across the Team" section, replace the `--namespace myteam` examples with equivalent examples that use only the documented filters (`--phase`, `--state`, `--project`, `--action`). For example: - `$ agents plan list --namespace myteam` → `$ agents plan list --state processing` - `$ agents plan list --namespace myteam --state processing` → `$ agents plan list --state processing` The Filters panel in the example output should also be updated to remove the `Namespace: myteam` entry. **Rationale**: The spec should be internally consistent. The formal command definition is the authoritative reference; the examples section should not demonstrate options that aren't in the formal definition. Since the CTO has explicitly rejected adding `--namespace` to the spec, the examples must be updated to match the formal definition. --- ## Scope Sections affected: 1. Lines ~41934–41997 — "Step 4: Monitor Across the Team" section — remove `--namespace` from two example commands and update the Filters panel output ## Classification **Minor spec update** — removing inconsistent examples to align with the formal command definition. No architectural changes. --- **Automated by CleverAgents Bot** Supervisor: Spec Evolution | Agent: ca-spec-updater
Author
Owner

Milestone Triage Decision: Moved to Backlog

This issue has been moved out of v3.3.0 during aggressive milestone triage. While important for completeness, it does not directly relate to the core focus of Corrections + Subplans + Checkpoints.

Reasoning:

  • v3.3.0 focus: Essential corrections, subplan management, and checkpoint functionality
  • This issue: Infrastructure improvement not directly blocking core milestone functionality
  • Impact: System enhancement, not core corrections/subplans/checkpoints functionality

Will be addressed in a future milestone after core corrections, subplans, and checkpoints are stable.

**Milestone Triage Decision: Moved to Backlog** This issue has been moved out of v3.3.0 during aggressive milestone triage. While important for completeness, it does not directly relate to the core focus of Corrections + Subplans + Checkpoints. **Reasoning:** - v3.3.0 focus: Essential corrections, subplan management, and checkpoint functionality - This issue: Infrastructure improvement not directly blocking core milestone functionality - Impact: System enhancement, not core corrections/subplans/checkpoints functionality Will be addressed in a future milestone after core corrections, subplans, and checkpoints are stable.
Owner

Architect Guidance: Approved — Remove --namespace from plan list Examples

The --namespace option was removed from agents plan list as part of the namespace simplification. The spec examples still reference it, creating an internal inconsistency.

Recommendation: Remove --namespace from all plan list examples in the spec. Plans are filtered by their namespaced name prefix, not by a separate --namespace flag.


🤖 CleverAgents Bot (architect-1)

## Architect Guidance: Approved — Remove `--namespace` from `plan list` Examples The `--namespace` option was removed from `agents plan list` as part of the namespace simplification. The spec examples still reference it, creating an internal inconsistency. **Recommendation**: Remove `--namespace` from all `plan list` examples in the spec. Plans are filtered by their namespaced name prefix, not by a separate `--namespace` flag. --- *🤖 CleverAgents Bot (architect-1)*
Author
Owner

@HAL9000 the "--namespace" argument is redundant because it takes a REGEX, which can be used to match on or filter the namespace part with much richer fidelity than a separate argument. As such the argument isnt needed and should be removed, make the spec consistent and reflect the fact that the argument will not and should not be used.

Update the description of this ticket to include the feedback from this comment, once updated tag me letting me know so I can follow up with a final approval.

@HAL9000 the "--namespace" argument is redundant because it takes a REGEX, which can be used to match on or filter the namespace part with much richer fidelity than a separate argument. As such the argument isnt needed and should be removed, make the spec consistent and reflect the fact that the argument will not and should not be used. Update the description of this ticket to include the feedback from this comment, once updated tag me letting me know so I can follow up with a final approval.
Sign in to join this conversation.
No milestone
No project
No assignees
2 participants
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#3453
No description provided.