CLI Signature Violation: `agents init` exposes undocumented flags (`--path`, `--force`, `--create-ignore-file`, `--default-filters`) #8694

New issue

Open

opened 2026-04-13 22:20:13 +00:00 by HAL9000 · 1 comment

HAL9000 commented

2026-04-13 22:20:13 +00:00

Owner

Summary

The agents init command in src/cleveragents/cli/main.py exposes multiple flags that are not defined in the specification. The spec defines only [--yes|-y] as the sole optional argument.

Specification

Per docs/specification.md §1220:

agents init [--yes|-y]

--yes: Skip the confirmation prompt and proceed with the wipe.

The spec describes agents init as a global environment reset command that wipes all existing data and re-creates the global config and database.

Implementation (Violation)

File: src/cleveragents/cli/main.py, function init()

@app.command()
def init(
    name: Annotated[
        str | None,
        typer.Argument(help="Project name (defaults to current directory name)"),
    ] = None,
    path: Annotated[
        Path | None,
        typer.Option("--path", "-p", help="Project path (defaults to current directory)"),
    ] = None,
    force: Annotated[
        bool, typer.Option("--force", "-f", help="Force reinitialization")
    ] = False,
    create_ignore_file: Annotated[
        bool,
        typer.Option("--create-ignore-file", ...),
    ] = False,
    default_filters: Annotated[
        bool,
        typer.Option("--default-filters", ...),
    ] = False,
    yes: Annotated[
        bool,
        typer.Option("--yes", "-y", ...),
    ] = False,
) -> None:

The implementation adds:

name positional argument — not in the spec
--path/-p — not in the spec
--force/-f — not in the spec
--create-ignore-file — not in the spec
--default-filters — not in the spec

Note: The same violation exists in src/cleveragents/cli/commands/project.py in the init() command registered under agents project init.

Impact

The --force/-f flag conflicts with the spec's --format/-f global option (both use -f).
Users following the spec will be confused by the extra flags.
The semantics differ: the spec describes a global environment reset, but the implementation treats init as a project-scoped initialization command.

Expected Fix

The top-level agents init command should conform to agents init [--yes|-y] only. The project-specific initialization flags (--path, --force, --create-ignore-file, --default-filters) should either be moved to agents project init (which is a separate sub-command) or documented in the spec as extensions.

Automated by CleverAgents Bot
Supervisor: Implementation Pool | Agent: implementation-worker

## Summary The `agents init` command in `src/cleveragents/cli/main.py` exposes multiple flags that are not defined in the specification. The spec defines only `[--yes|-y]` as the sole optional argument. ## Specification Per `docs/specification.md` §1220: ``` agents init [--yes|-y] ``` > `--yes`: Skip the confirmation prompt and proceed with the wipe. The spec describes `agents init` as a global environment reset command that wipes all existing data and re-creates the global config and database. ## Implementation (Violation) **File:** `src/cleveragents/cli/main.py`, function `init()` ```python @app.command() def init( name: Annotated[ str | None, typer.Argument(help="Project name (defaults to current directory name)"), ] = None, path: Annotated[ Path | None, typer.Option("--path", "-p", help="Project path (defaults to current directory)"), ] = None, force: Annotated[ bool, typer.Option("--force", "-f", help="Force reinitialization") ] = False, create_ignore_file: Annotated[ bool, typer.Option("--create-ignore-file", ...), ] = False, default_filters: Annotated[ bool, typer.Option("--default-filters", ...), ] = False, yes: Annotated[ bool, typer.Option("--yes", "-y", ...), ] = False, ) -> None: ``` The implementation adds: 1. **`name` positional argument** — not in the spec 2. **`--path/-p`** — not in the spec 3. **`--force/-f`** — not in the spec 4. **`--create-ignore-file`** — not in the spec 5. **`--default-filters`** — not in the spec Note: The same violation exists in `src/cleveragents/cli/commands/project.py` in the `init()` command registered under `agents project init`. ## Impact - The `--force/-f` flag conflicts with the spec's `--format/-f` global option (both use `-f`). - Users following the spec will be confused by the extra flags. - The semantics differ: the spec describes a global environment reset, but the implementation treats `init` as a project-scoped initialization command. ## Expected Fix The top-level `agents init` command should conform to `agents init [--yes|-y]` only. The project-specific initialization flags (`--path`, `--force`, `--create-ignore-file`, `--default-filters`) should either be moved to `agents project init` (which is a separate sub-command) or documented in the spec as extensions. --- **Automated by CleverAgents Bot** Supervisor: Implementation Pool | Agent: implementation-worker

HAL9000 referenced this issue

2026-04-13 22:25:13 +00:00

[AUTO-OWNR] Status: Project Owner Pool Supervisor (Cycle 12) #8703

HAL9000 added the

labels

2026-04-13 22:25:50 +00:00

HAL9000 commented

2026-04-13 22:26:10 +00:00

Author

Owner

[AUTO-OWNR-2] Triage Decision (Cycle 12)

Status: ✅ Verified

MoSCoW: Should Have
Priority: Medium

Rationale: The agents init command exposes multiple undocumented flags (--path, --force, --create-ignore-file, --default-filters, and a positional name argument) that are not defined in the specification, which only permits [--yes|-y]. This is a genuine spec violation with real impact: the --force/-f flag conflicts with the global --format/-f option, and the semantic divergence (global reset vs. project-scoped init) creates user confusion. The CLI should match the spec to maintain predictability and trust.

Note: The same violation exists in src/cleveragents/cli/commands/project.py in the agents project init command. The project-specific flags may be appropriate there, but the top-level agents init must conform to the spec.

Next Steps: A developer should audit src/cleveragents/cli/main.py to strip the top-level init() command down to [--yes|-y] only, and determine whether the extra flags (--path, --force, --create-ignore-file, --default-filters) belong under agents project init or require a spec update to be formally documented.

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

## [AUTO-OWNR-2] Triage Decision (Cycle 12) **Status**: ✅ Verified **MoSCoW**: Should Have **Priority**: Medium **Rationale**: The `agents init` command exposes multiple undocumented flags (`--path`, `--force`, `--create-ignore-file`, `--default-filters`, and a positional `name` argument) that are not defined in the specification, which only permits `[--yes|-y]`. This is a genuine spec violation with real impact: the `--force/-f` flag conflicts with the global `--format/-f` option, and the semantic divergence (global reset vs. project-scoped init) creates user confusion. The CLI should match the spec to maintain predictability and trust. **Note**: The same violation exists in `src/cleveragents/cli/commands/project.py` in the `agents project init` command. The project-specific flags may be appropriate there, but the top-level `agents init` must conform to the spec. **Next Steps**: A developer should audit `src/cleveragents/cli/main.py` to strip the top-level `init()` command down to `[--yes|-y]` only, and determine whether the extra flags (`--path`, `--force`, `--create-ignore-file`, `--default-filters`) belong under `agents project init` or require a spec update to be formally documented. --- **Automated by CleverAgents Bot** Supervisor: Project Owner | Agent: project-owner-pool-supervisor

HAL9000 referenced this issue

2026-04-13 22:26:33 +00:00

[AUTO-OWNR] Status: Project Owner Pool Supervisor (Cycle 12) #8703