Build compact agent references from CLI help

Why use this

1. Command-line help can be too broad for an agent that needs a small, reliable action reference. Summarizing it aggressively can also remove flags, prerequisites or warnings that distinguish a harmless query from a state-changing command.

2. This job could produce compact references that preserve command identity and action boundaries. A versioned help inventory would make it easier to spot stale entries before an agent relies on a shorthand description.

Why an agent / simpler alternative

Useful judgment

Organize nested help text and distinguish read-only discovery from consequential operations.

Simpler alternative

Use the CLI’s native help or generated reference when the command surface is already manageable.

Unsuitable when

Help discovery requires authentication, executes operations or exposes secrets.

Proposed inputs

1. Name

   Authorized help snapshots

   Owner

   Tool owner

   Minimum scope

   CLI name, version and selected root/subcommand help text

   Quality check

   Confirm text is documentation and retain original command paths.

2. Name

   Reference conventions

   Owner

   Maintainer

   Minimum scope

   Desired fields, scope, warnings and update policy

   Quality check

   Require explicit marking of writes, permissions and unresolved prerequisites.

Access and setup — proposed or unknown

Proposed minimum

1. Parse supplied help text into local draft references; do not execute listed operations.

Compatibility unknowns

1. Unknown: CLI versions, help-tree completeness and plugin-format compatibility.

External actions requiring approval

1. Installing CLIs, authenticating accounts, running commands or publishing shared plugins.

Expected deliverable and review checks

Proposed artifact

Compact command reference with version, exact syntax, purpose, required inputs and consequence labels.

Critical checks

1. Nested commands retain their complete paths and mandatory flags.

2. Examples do not silently supply credentials, targets or permission to act.

Missing output evidence

No new run or output inspection in this editorial layer; see linked source-specific limits.

Failure signals and proposed responses

1. Signal

   Two subcommands share a name under different parent groups.

   Why it matters

   A shortened reference may invoke the wrong operation.

   Proposed response

   Preserve the full command path and distinguish the contexts explicitly.

2. Signal

   A help summary omits a force or destructive flag warning.

   Why it matters

   Later use may appear safer than the underlying command is.

   Proposed response

   Keep material warnings beside the action and classify it for separate approval.

Effort and cost — unknown

Setup work

1. Define a minimal reference schema and version provenance.

Ongoing review

1. Review changed help output and retire outdated entries.

Unknowns

1. Unknown: documentation completeness, update effort and compatibility with later CLI releases.

First check — proposed, unexecuted

Status

proposed_unexecuted

Synthetic fixture

Synthetic help trees contain duplicate leaf names, a required target flag and a destructive option.

Acceptance checks

1. Each reference keeps the complete path and prerequisites.

2. The destructive action remains clearly labelled and unexecuted.

Stop conditions

1. Help retrieval triggers login, side effects or access outside the agreed scope.

Limits

1. A compact reference aids discovery; it does not establish command safety, current access or authorization to execute.