Agent Ops CLI Helpers

A small reference implementation for pairing AI-agent operating instructions with deterministic local Python helpers.

The design principle is simple:

• Scripts gather repeatable evidence.
• Agent instructions keep judgment, synthesis, and writing decisions.
• Connectors and MCP-style tools stay responsible for authenticated or live external systems.

This repo is intentionally generic and sanitized. It does not include any private workspace content, customer data, live paths, API keys, or connector configuration.

What It Includes

Helper	Purpose	Mutation
audit_root.py	Checks whether a workspace root has only approved top-level entries	Read-only
audit_counts.py	Checks stated counts and status tokens from JSON rules	Read-only
audit_versions.py	Flags likely duplicate/version-sprawl filenames	Read-only
audit_empty.py	Flags empty or near-empty folders	Read-only
audit_large.py	Flags oversized files outside documented exceptions	Read-only
propagation_search.py	Searches configured destinations for a term and buckets results	Read-only
lint_style.py	Runs configurable writing-style checks	Read-only
scaffold_record.py	Creates a new six-file record from templates after preflight checks	Writes files by design

Quick Start

No third-party dependencies are required.

python -m unittest

Run the sample root audit:

python -m agent_ops_helpers.audit_root --root examples/sample-workspace --config examples/configs/audit_root.json

Run count checks:

python -m agent_ops_helpers.audit_counts --root examples/sample-workspace --config examples/configs/counts.json

Search configured propagation destinations:

python -m agent_ops_helpers.propagation_search --root examples/sample-workspace --config examples/configs/destinations.json "style guard"

Run the style linter:

python -m agent_ops_helpers.lint_style --rules examples/configs/style_rules.json --mode cold-outreach examples/sample-workspace/docs/system.md

Scaffold a new record in a temporary workspace:

python -m agent_ops_helpers.scaffold_record "Acme Logistics" acme-logistics --root examples/sample-workspace --template-dir examples/sample-workspace/templates/record-build

Why This Pattern Exists

Agent instructions are good at interpretation. They are less reliable at remembering every deterministic check every time.

These helpers extract the mechanical parts:

• count this
• search these folders
• verify this file shape
• create these files from templates
• flag banned language

The agent still decides what the evidence means.

Architecture

flowchart LR
    A["Agent instruction"] --> B["Read-only helper"]
    B --> C["Evidence report"]
    C --> D["Agent judgment"]
    D --> E["Small documented change"]
    E --> F["Propagation search"]

Loading

Exit Codes

Helpers use a consistent convention:

• 0: helper ran successfully, even if it found flags
• 1: lint-style policy violations
• 2: runtime or configuration failure

This allows scheduled tasks to distinguish "the audit found something" from "the audit could not run."

Portfolio Notes

This is a sanitized extraction of an operating pattern, not a private workspace export. The sample workspace and configs are fictional. They exist to show the structure and test the behavior.

See:

• Design Notes
• Security and Privacy