UAT: `agents repo index` and `agents repo status` CLI commands exist in code but are absent from the specification's CLI synopsis #4073

New issue

Open

opened 2026-04-06 09:56:32 +00:00 by freemo · 0 comments

freemo commented

2026-04-06 09:56:32 +00:00

Owner

Metadata

Branch: fix/spec-add-agents-repo-cli-synopsis
Commit Message: docs(spec): add agents repo index and agents repo status to CLI synopsis
Milestone: (none — routed to backlog per Milestone Scope Guard)
Parent Epic: #3374 (Epic: E2E Workflow Specification Tests & Code Review Tool Examples)

Background and Context

The agents repo command group is implemented in src/cleveragents/cli/commands/repo.py and registered in src/cleveragents/cli/main.py, but it does not appear anywhere in the specification's CLI Command Synopsis section (docs/specification.md).

The implemented commands are:

agents repo index <RESOURCE_NAME> [--full] [--timeout-seconds N] [--format json|text]
agents repo status <RESOURCE_NAME> [--format json|text]

These commands are wired to a RepoIndexingService backend and provide repository indexing functionality. They were introduced as part of issue #856 (feat(cli): repo indexing CLI functional) in milestone v3.6.0.

The specification's CLI synopsis (docs/specification.md, CLI Command Synopsis section, around lines 200–400) lists all supported commands including agents resource, agents plan, agents project, etc., but agents repo is completely absent.

This creates a spec-implementation gap: either:

The spec needs to be updated to include agents repo index and agents repo status commands, OR
The implementation is premature and the commands should not yet be exposed

The spec is the authoritative source of truth. All CLI commands must be documented in the spec's CLI synopsis.

Current Behavior

agents repo index and agents repo status are functional CLI commands that are not documented in the specification's CLI synopsis.

Code locations:

Implementation: src/cleveragents/cli/commands/repo.py
Registration: src/cleveragents/cli/main.py (line ~100: from cleveragents.cli.commands import ... repo ... and app.add_typer(repo.app, name="repo", ...))
Spec: docs/specification.md (CLI Command Synopsis section — agents repo is absent)

Expected Behavior

Per the spec's role as authoritative source of truth: all CLI commands must appear in the spec's CLI synopsis. If agents repo is a valid feature, it must appear in the spec with its full signature:

agents repo index <RESOURCE_NAME> [--full] [--timeout-seconds N] [--format json|text]
agents repo status <RESOURCE_NAME> [--format json|text]

Subtasks

Audit src/cleveragents/cli/commands/repo.py to confirm the exact signatures of agents repo index and agents repo status (all arguments, options, and defaults)
Determine resolution path: update spec to document the commands, OR remove the premature CLI exposure (decision for project owner)
If updating spec: add agents repo command group to the CLI Command Synopsis section in docs/specification.md with correct signatures, argument descriptions, and option descriptions
If removing premature exposure: unregister repo.app from src/cleveragents/cli/main.py and add a tracking issue for when the spec formally includes agents repo
Add/update Behave scenarios to validate agents repo index and agents repo status against the spec (once spec is updated)
Run nox (all default sessions), fix any errors
Verify coverage >= 97% via nox -s coverage_report

Definition of Done

This issue is complete when:

The spec and implementation are in alignment: agents repo index and agents repo status either both appear in the spec CLI synopsis OR are removed from the CLI
If spec updated: docs/specification.md CLI Command Synopsis section includes agents repo index and agents repo status with correct full signatures
If commands removed: repo.app is unregistered from src/cleveragents/cli/main.py and a follow-up tracking issue exists
Behave scenarios cover the resolved state
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
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

Implementation origin: Issue #856 (feat(cli): repo indexing CLI functional), milestone v3.6.0
Spec reference: docs/specification.md — CLI Command Synopsis section (search for agents repo — it is absent)
Architectural context: The RepoIndexingService backs the agents repo commands and provides repository indexing for large-project autonomy and context. The spec is the authoritative source of truth for all CLI commands.

Backlog note: This issue was discovered during autonomous operation
on milestone v3.6.0. It does not block milestone completion and has been
placed in the backlog for human review and future milestone assignment.

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

## Metadata - **Branch**: `fix/spec-add-agents-repo-cli-synopsis` - **Commit Message**: `docs(spec): add agents repo index and agents repo status to CLI synopsis` - **Milestone**: *(none — routed to backlog per Milestone Scope Guard)* - **Parent Epic**: #3374 (Epic: E2E Workflow Specification Tests & Code Review Tool Examples) ## Background and Context The `agents repo` command group is implemented in `src/cleveragents/cli/commands/repo.py` and registered in `src/cleveragents/cli/main.py`, but it does **not** appear anywhere in the specification's CLI Command Synopsis section (`docs/specification.md`). The implemented commands are: - `agents repo index <RESOURCE_NAME> [--full] [--timeout-seconds N] [--format json|text]` - `agents repo status <RESOURCE_NAME> [--format json|text]` These commands are wired to a `RepoIndexingService` backend and provide repository indexing functionality. They were introduced as part of issue #856 (`feat(cli): repo indexing CLI functional`) in milestone v3.6.0. The specification's CLI synopsis (`docs/specification.md`, CLI Command Synopsis section, around lines 200–400) lists all supported commands including `agents resource`, `agents plan`, `agents project`, etc., but `agents repo` is **completely absent**. This creates a spec-implementation gap: either: 1. The spec needs to be updated to include `agents repo index` and `agents repo status` commands, OR 2. The implementation is premature and the commands should not yet be exposed The spec is the authoritative source of truth. All CLI commands must be documented in the spec's CLI synopsis. ## Current Behavior `agents repo index` and `agents repo status` are functional CLI commands that are **not** documented in the specification's CLI synopsis. **Code locations:** - Implementation: `src/cleveragents/cli/commands/repo.py` - Registration: `src/cleveragents/cli/main.py` (line ~100: `from cleveragents.cli.commands import ... repo ...` and `app.add_typer(repo.app, name="repo", ...)`) - Spec: `docs/specification.md` (CLI Command Synopsis section — `agents repo` is absent) ## Expected Behavior Per the spec's role as authoritative source of truth: all CLI commands must appear in the spec's CLI synopsis. If `agents repo` is a valid feature, it must appear in the spec with its full signature: ``` agents repo index <RESOURCE_NAME> [--full] [--timeout-seconds N] [--format json|text] agents repo status <RESOURCE_NAME> [--format json|text] ``` ## Subtasks - [ ] Audit `src/cleveragents/cli/commands/repo.py` to confirm the exact signatures of `agents repo index` and `agents repo status` (all arguments, options, and defaults) - [ ] Determine resolution path: update spec to document the commands, OR remove the premature CLI exposure (decision for project owner) - [ ] If updating spec: add `agents repo` command group to the CLI Command Synopsis section in `docs/specification.md` with correct signatures, argument descriptions, and option descriptions - [ ] If removing premature exposure: unregister `repo.app` from `src/cleveragents/cli/main.py` and add a tracking issue for when the spec formally includes `agents repo` - [ ] Add/update Behave scenarios to validate `agents repo index` and `agents repo status` against the spec (once spec is updated) - [ ] Run `nox` (all default sessions), fix any errors - [ ] Verify coverage >= 97% via `nox -s coverage_report` ## Definition of Done This issue is complete when: - [ ] The spec and implementation are in alignment: `agents repo index` and `agents repo status` either both appear in the spec CLI synopsis OR are removed from the CLI - [ ] If spec updated: `docs/specification.md` CLI Command Synopsis section includes `agents repo index` and `agents repo status` with correct full signatures - [ ] If commands removed: `repo.app` is unregistered from `src/cleveragents/cli/main.py` and a follow-up tracking issue exists - [ ] Behave scenarios cover the resolved state - [ ] 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 - [ ] 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 - **Implementation origin**: Issue #856 (`feat(cli): repo indexing CLI functional`), milestone v3.6.0 - **Spec reference**: `docs/specification.md` — CLI Command Synopsis section (search for `agents repo` — it is absent) - **Architectural context**: The `RepoIndexingService` backs the `agents repo` commands and provides repository indexing for large-project autonomy and context. The spec is the authoritative source of truth for all CLI commands. > **Backlog note:** This issue was discovered during autonomous operation > on milestone v3.6.0. It does not block milestone completion and has been > placed in the backlog for human review and future milestone assignment. --- **Automated by CleverAgents Bot** Supervisor: UAT Testing | Agent: ca-uat-tester

freemo added a new dependency

2026-04-06 09:56:55 +00:00

#3374 Epic: E2E Workflow Specification Tests & Code Review Tool Examples

freemo referenced this issue

2026-04-06 09:57:30 +00:00

[Automated] CleverAgents Build Session - 2026-04-06 #3775

freemo referenced this issue

2026-04-06 10:15:25 +00:00

[Automated] CleverAgents Build Session - 2026-04-06 #3775