PRACTICAL GUIDE · 7 PRIMARY WORKFLOWS

When, Where, & Why to Use ripwire-rs

ripwire-rs is engineered around 7 high-impact workflows: from landing cold in a foreign codebase to surgical test execution, automated CI/CD PR verification, and multi-agent fleet orchestration.

1. Orientation & Scoping 2. Navigation & Blast Radius 3. Pre-Commit & PR Gates 4. Code Health & Auditing 5. Agent Context Delivery 6. CI / CD & PR Gates 7. Multi-Agent Orchestration
1. Orientation & Scoping: Landing Cold in a Repository
Scoping
When & Where
  • ▸First time inspecting or onboarding into an unfamiliar codebase.
  • ▸Starting a new issue or feature request.
  • ▸Feeding high-level, budget-bounded context to an AI coding agent without blowing prompt token limits.
Instructions & Commands
1 Architecture map of top 200 ranked symbols by Personalized PageRank
ripwire-rs . --top-k=200
2 File-by-file structural inventory showing top 3 symbols per file
ripwire-rs . --tree
3 Task-lens relevance ranking: retrieves ranked declarations relevant to a goal
ripwire-rs . --for="implement user authentication"
4 Export interactive, self-contained SVG/HTML call graph to open in browser
ripwire-rs . --html=graph.html --color-by=community
Why & Key Benefits
  • Zero Hallucinated Dependencies: Emits an in-context AST schema dictionary defining minified keys (t, n, sc, k, c).
  • Prompt Token Economy: Emits shown="K" truncation disclosures so models know absence in a top-slice does not mean absence in the repo.
  • Instantaneous Speed: Renders entire repository topologies in ~25 milliseconds.
3. Pre-Commit & PR Safety Gates: Zero Broken Contracts
Safety Gate
When & Where
  • ▸In local Git pre-commit hooks (.git/hooks/pre-commit).
  • ▸Before running git push or opening a pull request.
  • ▸In automated CI/CD pull request verification gates before merging code.
Instructions & Commands
1 Verify caller compatibility after modifying a symbol contract
ripwire-rs . --edit-check="symbol_name"
2 Transitive reachability mapping to affected test suites
ripwire-rs . --affected="src/lib.rs"
3 Pre-PR gate: names tests to run and untested blast radius (exits with code 4)
ripwire-rs . --test-gate
4 Canonical situ/v1 XML for working tree diff: blast radius, tests, co-change
ripwire-rs . --situ
5 Assess whether a symbol can be safely deleted without breaking callers
ripwire-rs . --safe-delete="Interner::len"
6 Measure code quality regressions against git HEAD across 10 facets
ripwire-rs . --quality-delta
Why & Key Benefits
  • Surgical Test Execution: Identifies the exact test files that transitively reach your changes, running a 5-second test subset instead of a 20-minute suite.
  • Contract Breakage Prevention: Catches parameter count changes and visibility regressions across all direct callers before you commit.
  • Fowler's Shotgun Surgery Protection: Surfaces companion files historically edited with your diff that you may have forgotten to update.
4. Code Health & Technical Debt Auditing
Architecture
When & Where
  • ▸During sprint refactoring cycles and technical debt burn-downs.
  • ▸Architectural reviews and modularity health checks.
  • ▸Eliminating dead code, near-miss duplicates, and unreferenced packages.
Instructions & Commands
1 Detect internal functions with zero incoming callers across the repository
ripwire-rs . --dead-code
2 Rank repository files by maintenance risk (churn * cognitive complexity)
ripwire-rs . --hotspots
3 Detect AST code clones and near-miss duplicates (Type-1, Type-2, Type-3)
ripwire-rs . --clones --min-tokens=40
4 Mine historical Git co-change coupling to identify hidden file coupling
ripwire-rs . --cochange
5 Partition call graph into cohesive modules via Louvain community detection
ripwire-rs . --communities
6 Discover symbols referenced in code but never defined (stdlib & external packages)
ripwire-rs . --external-surface
Why & Key Benefits
  • Data-Driven Focus: Prioritizes refactoring where maintenance churn intersects with elevated cognitive complexity.
  • Safe Dead-Code Pruning: Pinpoints zero-caller functions with mathematical certainty without manual grep sweeps.
  • Architectural Clarity: Detects tangled module boundaries and cyclic dependencies.
5. Deep Inspection & Agent Context Delivery
AI Context
When & Where
  • ▸Extracting exact function implementations for LLM prompts without token bloat.
  • ▸Debugging compiler error messages and stack traces against source definitions.
  • ▸Multi-query agent pipelines and native Model Context Protocol (MCP) tooling.
Instructions & Commands
1 Expand full source body of symbols and callee signatures in CDATA XML
ripwire-rs . --expand="Symbol::new"
2 Outline control-flow skeletons of symbols (loops, branches, declarations)
ripwire-rs . --outline="Interner::intern"
3 Pack source bodies of the top N highest PageRank symbols
ripwire-rs . --pack-top-n=5
4 Map compiler error / stack trace frames directly onto indexed symbols
ripwire-rs . --from-trace=error.log
5 Execute up to 16 heterogeneous sub-queries in a single turn
ripwire-rs . --batch=queries.txt
6 Structured JSON output for navigation queries
ripwire-rs . --callers="Interner::len" --json
7 Launch native stdio Model Context Protocol (MCP) server for coding agents
ripwire-rs mcp
8 Install 17 pre-packaged ripwire-rs agent skills to ~/.agents/skills (or custom path)
ripwire-rs --add-skills
Why & Key Benefits
  • Precision Context Bundles: Extracts only relevant symbol bodies into CDATA blocks, conserving prompt token budgets.
  • Batching Economy: ripwire-rs . --batch executes up to 16 queries in a single turn, eliminating agent tool-call round-trip latency.
  • Native Agent Protocol: 33 built-in MCP tools accessible over stdio for any MCP-compatible client or coding agent.
  • Instant Agent Skills: ripwire-rs --add-skills provisions 17 standardized skills and active manifest into ~/.agents/skills for zero-configuration onboarding.
6. Continuous Integration (CI) Workflows & Automated PR Gates
CI / CD
When & Where
  • ▸Automated GitHub Actions (.github/workflows/), GitLab CI, or Jenkins pipelines.
  • ▸Enforcing pull request quality standards and preventing regressions before merge.
  • ▸Validating 1:1 behavioral parity against upstream specifications.
Instructions & Commands
1 PR Situational Awareness: canonical situ/v1 XML with blast radius, reaching tests, and co-change
ripwire-rs . --situ
2 Architectural Boundary Gate: enforces module layering rules (exits code 2 on violation)
ripwire-rs . --arch=rules.txt
3 Test Reachability Gate: blocks merge if changes leave untested blast radius (exits 4)
ripwire-rs . --test-gate
4 Quality Regression Gate: blocks merge if complexity, nesting, or AST clones regress vs base
ripwire-rs . --quality-delta
CI Pipeline Recipe · GitHub Actions Example

Add this workflow file to .github/workflows/ripwire-rs-gate.yml to enforce the 4 static verification gates on every PR, post situational awareness to the review UI, and block untested code before merge.

.github/workflows/ripwire-rs-gate.yml 
name: ripwire-rs PR Safety Gates
on:
  pull_request:
    branches: [main, master]

jobs:
  ripwire-rs-gate:
    name: Architecture, Quality & Safety Gates
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Install ripwire-rs CLI
        run: cargo install ripwire-rs

      # 1. Post Situational Awareness directly to GitHub PR Summary
      - name: Generate PR Situational Awareness Report
        run: |
          echo "### ripwire-rs Situational Awareness" >> $GITHUB_STEP_SUMMARY
          echo '```' >> $GITHUB_STEP_SUMMARY
          ripwire-rs . --situ >> $GITHUB_STEP_SUMMARY
          echo '```' >> $GITHUB_STEP_SUMMARY

      # 2. Architectural Boundary Gate (if rules.txt exists)
      - name: Enforce Architecture Layering Rules
        run: |
          if [ -f rules.txt ]; then
            ripwire-rs . --arch=rules.txt
          fi

      # 3. Test Reachability Gate (exits code 4 on untested blast radius)
      - name: Run Test Reachability Gate
        run: ripwire-rs . --test-gate

      # 4. Quality Delta Regression Gate (exits non-zero on regressions vs base branch)
      - name: Run Quality Regression Delta Gate
        run: ripwire-rs . --quality-delta

      # 5. Run Test Suite
      - name: Run Tests
        run: cargo test --all
Why & Key Benefits
  • Automated Merge Blocking: Fails PR jobs automatically (exit code 4 on ripwire-rs . --test-gate or non-zero on ripwire-rs . --quality-delta) before untested code or architectural rot merges.
  • Sub-50ms Execution: Fast in-memory static analysis executes in milliseconds, eliminating slow CI runner bottlenecks.
  • Architectural Boundary Enforcement: ripwire-rs . --arch=rules.txt enforces layering rules and prevents circular module dependencies.
  • Zero Configuration: Reads native git repository history, remotes, and branch merge bases automatically.
7. Multi-Agent Fleet Orchestration: Parallel Worktrees & Subagent Slicing
Orchestration
When & Where
  • ▸Fanning a multi-symbol feature or wave refactor out across N parallel coding agents or isolated git worktrees.
  • ▸Eliminating duplicate orientation spend where every spawned subagent re-discovers the same repository map from scratch.
  • ▸Predicting symbol conflicts, same-file risks, and contract-touch dependencies before writing code or landing branches.
  • ▸Handing off in-flight session state and persistent symbol gotchas between contexts that never met.
Commands
1 Community-Carved Context Fan-Out: 1 shared core + N minimally-overlapping subagent bundles
ripwire-rs . --pack-task="refactor serialization" --partition=4
2 Pre-Hoc Worktree Lane Planner: predict pairwise conflicts, contract touches, and landing order
ripwire-rs . --plan-lanes=3 --task="refactor serialization"
3 Explicit Brief Lane Planner: rank one non-blank task line per lane from a brief file
ripwire-rs . --plan-lanes --brief=lanes.txt
4 Cross-Branch Merge Scout: detect symbol overlaps across concurrent branches and order landings
ripwire-rs . --merge-scout="feat/auth,feat/billing"
5 Deterministic Intent Router & Closed-Claim Verifier: route tasks or verify 6-shape code claims
ripwire-rs . --help-task="plan the new feature" && ripwire-rs . --verify="calls(main,run_cli)"
6 Session Handoff & Persistent Symbol Notes: pass verified diff state and gotchas to the next agent
ripwire-rs . --handoff && ripwire-rs . --notes
Why & Key Benefits
  • Louvain Community Slicing: --pack-task --partition=N groups symbols by call-graph communities (with file fallback for edgeless data types) and reports Jaccard overlap (overlap_mean, overlap_max, core_overlap) so parallel agents work on genuinely disjoint modules.
  • Pre-Hoc Collision & Contract-Touch Oracle: --plan-lanes separates direct symbol conflicts, same_file_risk, and contract_touch (a claim inside another lane's blast radius) and computes a greedy fewest-conflicts-first landing_order.
  • Epistemic Honesty: --help-task inspects live repository facts and abstains when evidence is thin; --verify proves or refutes 6 closed claim shapes with inline witness rows.
  • Autonomous Agent Governance: Learn how to embed these verification workflows directly into your agent instructions in the AGENTS.md Guide.