Empirical analysis across thousands of public repositories confirms that coding agents struggle with vague, declarative instructions. Aspirational phrases like "write clean code", "don't break existing tests", or "inspect the codebase carefully" fail in production because LLMs cannot self-evaluate complexity, hallucinate caller relationships, and burn context tokens on blind directory crawling.
| Traditional Natural Language Rule | Agent Failure Mode | ripwire-rs Enforced Invariant |
|---|---|---|
| "Inspect code before editing" | Agent crawls grep/ls, loads 20 full files, exhausts prompt token budget. |
ripwire-rs . --for="<task>" |
| "Preserve caller compatibility" | Agent mutates a signature; callers break silently across unread files. | ripwire-rs . --edit-check="<sym>" |
| "Run relevant test suites" | Agent guesses test paths or runs monolithic slow test suites (timeouts). | ripwire-rs . --situ |
| "Keep functions small and cohesive" | Arbitrary 150-line heuristics flag clean tables while missing 80-line nested tangles. | ripwire-rs . --quality-delta |
| "Don't merge untested changes" | Agent writes new branches or endpoints without test coverage. | ripwire-rs . --test-gate (exit 4) |
When an agent is guided by ripwire-rs, every prompt transitions through an invariant, mathematical lifecycle:
Retrieve ranked AST declarations under token budget without reading files blindly.
ripwire-rs . --for="<task>"
Map direct callers and transitive dependents before mutating signatures or types.
ripwire-rs . --impact="<sym>"
Keep cyclomatic complexity cx < 5 on untested paths; zero non-local mutable state.
ripwire-rs . --nonlocal-state
Check callers, run affected tests, check co-change, and prove zero regressions vs HEAD.
ripwire-rs . --situ && --quality-delta
Partition parallel subagent tasks along Louvain communities to avoid overlap.
ripwire-rs . --plan-lanes=N --task="..."
Drop this template directly into your repository root (./AGENTS.md) or your global user configuration (~/.agents/AGENTS.md). It measures 73 lines, enforces strict metric bounds, and operates with zero duplicate tool calls:
# Engineering Standards & Static Verification Enforce quality and architectural discipline using `ripwire-rs`. Rely on deterministic static analysis metrics, call-graph data, and exit codes over speculative text inspection. ## 1. Task Orientation & Scoping - **Cold-Start Scoping**: Retrieve task-relevant signatures and declarations under token budget before reading files: `ripwire-rs . --for="<task description>"` - **Pattern Reuse**: Locate existing canonical implementations to imitate before creating new abstractions: `ripwire-rs . --exemplar="<kind or task>"` - **Pre-Edit Blast Radius**: Check transitive dependents before modifying or deleting signatures: `ripwire-rs . --impact="<symbol>"` (or `--safe-delete="<symbol>"`) ## 2. Code Quality & Structural Coupling Code quality is enforced automatically by `ripwire-rs` default quality bars (Cognitive Complexity <= 15, Nesting <= 4, Params <= 5, LOC <= 60). - **Change Risk (CRAP Ceiling)**: Any function modified or added with cyclomatic complexity `cx >= 5` (`ripwire-rs . --metrics`) MUST have test coverage. Keep flows linear or add tests. - **God Files & Cycles**: Prevent cyclic dependencies and high-instability coupling: `ripwire-rs . --deps` (inspect `<godfiles>`, `<cycles>`, and `instab=`) - **Local Reasoning**: Avoid functions requiring high external reasoning context: `ripwire-rs . --context-ratio` - **Minimal Diffs**: Make the smallest coherent change that solves the root problem. Never mix formatting or refactoring into functional diffs. ## 3. Architectural Boundaries - **Domain Core**: Business rules must be deterministic and I/O-free. Core functions must have zero non-local mutable state: `ripwire-rs . --nonlocal-state` - **Dependency Isolation**: Core domain logic must remain free of framework, ORM, and SDK types: `ripwire-rs . --external-surface` - **Thin Adapters & Layering**: Keep edge transport/storage adapters thin and coordination scripts swappable. If a repository defines layering rules (`rules.txt`), enforce them: `ripwire-rs . --arch=rules.txt` (exits 2 on violation) ## 4. Comment Policy - Default to zero comments. Add a comment only for a durable, non-derivable external constraint (protocol quirk, hardware race, upstream bug citation). Max two lines; never restate code. - Verify comment signal and prune echo comments: `ripwire-rs . --comment-coherence` ## 5. Mandatory Verification & Safety Gate Never mark a task complete without executing this verification sequence on the working tree: 1. **Contract Check**: Verify modified signatures did not break direct callers: `ripwire-rs . --edit-check="<symbol>"` 2. **Situational Awareness & Targeted Tests**: `ripwire-rs . --situ` - Check reported `co-change` files for forgotten companion edits. - Run ONLY the test files listed under `tests to run`. 3. **Quality & Test Gates**: Ensure zero regressions and zero untested blast radius: `ripwire-rs . --quality-delta` (must report `regressions="0"`) `ripwire-rs . --test-gate` (must not exit 4) ## 6. Technical Debt & Refactoring - **Maintenance Hotspots**: Refactor where churn intersects complexity: `ripwire-rs . --hotspots` - **Dead Code & Clones**: Prune zero-caller functions (`ripwire-rs . --dead-code`) and AST clones (`ripwire-rs . --clones --min-tokens=40`). - **Untested Seams**: Target cross-boundary call edges lacking tests: `ripwire-rs . --seams` ## 7. Multi-Agent & Parallel Work Delegation - **Community Slicing**: Partition parallel agent tasks along call-graph clusters: `ripwire-rs . --pack-task="<task>" --partition=<N>` - **Pre-Hoc Lane Planning**: Predict symbol collisions and optimal landing order: `ripwire-rs . --plan-lanes=<N> --task="<task>"` - **Branch Conflicts**: Scout cross-branch merge collisions: `ripwire-rs . --merge-scout="branch-a,branch-b"` ## 8. Commit & Safety Discipline - **Commit Format**: Conventional Commits (`type(scope): summary`). Append `Refs: <TICKET-ID>` if branch references an issue. - **Safety**: Never expose secrets. Never run destructive commands (`rm -rf`, `git reset --hard`, `git push --force`, `DROP TABLE`) without explicit user confirmation. - **Output**: Plain ASCII in generated repository artifacts. Concise, factual responses.
A common architectural question when deploying agents is whether AGENTS.md should invoke agent skills (e.g. skill://ripwire-rs-change-check) or direct CLI commands.
Placing explicit commands with flags in AGENTS.md produces zero-latency, immediate execution. On a 2-line bug fix, the agent runs the 3-step verification checklist in the same turn without burning thousands of tokens repeatedly loading 200-line skill manuals.
Installing the 17 skills via ripwire-rs --add-skills gives skill-aware agent runners detailed SOPs for complex investigations (cross-branch merge conflict trees, dark flag flipping, AST clone refactoring) on an on-demand basis.
The static verification sequence enforced in AGENTS.md is designed for exact 1:1 parity with remote continuous integration pipelines:
| Local Agent Gate (AGENTS.md) | Remote CI Gate (ripwire-rs-gate.yml) | Automated Guarantee |
|---|---|---|
| ripwire-rs . --edit-check="<sym>" | Pre-commit / PR Check | Proves zero broken 1-hop caller contracts. |
| ripwire-rs . --situ | $GITHUB_STEP_SUMMARY | Renders blast radius, affected tests, and co-change to PR summary. |
| ripwire-rs . --arch=rules.txt | Architecture Gate | Enforces module layering boundaries (exits code 2 on violation). |
| ripwire-rs . --test-gate | Test Reachability Gate | Blocks PR merge if changes leave untested blast radius (exits code 4). |
| ripwire-rs . --quality-delta | Quality Delta Gate | Blocks merge if CCX > 15, nesting > 4, or AST clones regressed. |
ripwire-rs operates as an offline, in-process static analysis engine designed for air-gapped environments:
Zero network sockets, zero telemetry, zero analytics SDKs, and zero phone-home routines. All AST parsing and graph traversals execute locally in-process.
Your proprietary code, symbol contracts, and git commit history are never transmitted externally or used for AI model training.
ripwire-rs does not make LLM calls; it purely emits structured XML/JSON context to stdout or stdio MCP for the agent harness you configure.
Built-in secret detection masks API keys, bearer tokens, and credentials from emitted code snippets before they reach prompts.