stella-ops.org/git.stella-ops.org
1
0
Fork 0
Code Issues Pull Requests Actions 2 Releases Wiki Activity
Files
fa4a98dfef353e6065bb8daaa43c05943205fd49
git.stella-ops.org/docs/modules/cli/AGENTS.md

3.6 KiB
Raw Blame History

CLI agent guide

Mission

The stella CLI is the operator-facing Swiss army knife for scans, exports, policy management, offline kit operations, and automation scripting.

Active Work: CLI Consolidation (v2.x → v3.0)

The CLI is undergoing a major consolidation to improve discoverability and consistency. See:

  • Advisory: docs-archived/product/advisories/CLI_CONSOLIDATION_PROPOSAL.md
  • Command Mapping: docs-archived/product/advisories/CLI_COMMAND_MAPPING.md
  • Migration Guide: docs/modules/cli/guides/migration-v3.md

Consolidation Sprints

Sprint Scope Status
SPRINT_20260118_010_CLI_consolidation_foundation Routing infrastructure, deprecation system DONE
SPRINT_20260118_011_CLI_settings_consolidation stella config unified settings DONE
SPRINT_20260118_012_CLI_verification_consolidation stella verify unified verification DONE
SPRINT_20260118_013_CLI_scanning_consolidation stella scan unified scanning DONE
SPRINT_20260118_014_CLI_evidence_remaining_consolidation Evidence, reachability, SBOM, crypto, etc. TODO

Key Changes

  • 81+ → 18 top-level commands for discoverability
  • Unified settings under stella config (notify, feeds, registry, integrations)
  • Unified verification under stella verify (attestation, vex, patch, sbom)
  • Compound commands split (scangraph → scan graph)
  • Backward compatibility via deprecated aliases

Implementation Priorities

  1. Foundation (routing, deprecation) must complete first
  2. Sprints 011-014 can run in parallel after foundation
  3. All old commands kept as deprecated aliases until v3.0
  4. Tests must verify both old and new paths

Key docs

How to get started

  1. Open sprint file /docs/implplan/SPRINT_*.md and locate the stories referencing this module.
  2. Review ./TASKS.md for local follow-ups and confirm status transitions (TODO → DOING → DONE/BLOCKED).
  3. Read the architecture and README for domain context before editing code or docs.
  4. Coordinate cross-module changes in the main /AGENTS.md description and through the sprint plan.

Guardrails

  • Honour the Aggregation-Only Contract where applicable (see ../../aoc/aggregation-only-contract.md).
  • Preserve determinism: sort outputs, normalise timestamps (UTC ISO-8601), and avoid machine-specific artefacts.
  • Keep Offline Kit parity in mind—document air-gapped workflows for any new feature.
  • Update runbooks/observability assets when operational characteristics change.
  • Advisory commands must default to read-only and display evidence refs with citations.

Required Reading

  • docs/modules/cli/README.md
  • docs/modules/cli/architecture.md
  • docs/modules/cli/implementation_plan.md
  • docs/modules/platform/architecture-overview.md

Working Agreement

    1. Update task status to DOING/DONE in both correspoding sprint file /docs/implplan/SPRINT_*.md and the local TASKS.md when you start or finish work.
    1. Review this charter and the Required Reading documents before coding; confirm prerequisites are met.
    1. Keep changes deterministic (stable ordering, timestamps, hashes) and align with offline/air-gap expectations.
    1. Coordinate doc updates, tests, and cross-guild communication whenever contracts or workflows change.
    1. Revert to TODO if you pause the task without shipping changes; leave notes in commit/PR descriptions for context.