Integration examples wanted — wrap your agent / CI / IDE plugin in Aegis and tell us where it broke

[wei9072]

Body

The four scripts in examples/ cover the core
library patterns (multi-turn pipeline, single-call gateway, custom
verifier, decision-trace consumption). They're deliberately
minimal — single-file, copy-runnable, no external integration.

The next layer of evidence the project needs is integration
examples — Aegis embedded inside something else. We'd like to
collect 3-5 of these as examples/integration/ so future readers
can see realistic shapes:

Wanted shapes

1. Wrap an existing AI coding agent. Aider, Claude Code,
   Cursor, custom orchestrators — anything that has its own
   plan-execute loop. Show how Aegis's gateway / pipeline plugs in
   as a control layer. Bonus points if the agent's behavior changes
   visibly when Aegis rejects a step.

2. Run as a CI gate. GitHub Actions / GitLab CI / Jenkins
   workflow that runs Aegis against an LLM-proposed PR diff before
   merging. Decision pattern → CI status check. Even a no-op skeleton
   is useful as a starting point.

3. MCP server. Aegis exposed as an MCP tool, so any
   MCP-supporting IDE (Claude Code, Cursor, etc.) can call it as a
   sandboxed code-modification layer. We've sketched this in the
   roadmap but no implementation yet.

4. Pre-commit / lint integration. No-LLM use of Aegis's
   structural checks (Ring0Enforcer, SignalLayer) as a
   pre-commit hook. Aegis already supports this via
   examples/02_gateway_single_call.py's underlying APIs but a
   dedicated example would help.

5. Your own domain. If you're trying to use Aegis for something
   that isn't code-gen — database migration, config rollout, RL
   policy iteration, etc. — share the integration even if it's
   half-finished. See
   docs/future_abstraction.md for
   how non-code domains map to Aegis's primitives.

How to contribute

• Quick & dirty — paste your script in this issue, even if it's
  rough. We'll figure out together whether it becomes an upstreamed
  example or stays as a reference.
• Polished — open a PR adding a directory under
  examples/integration/<your-shape>/ with a README explaining the
  what / why / how-to-run.

What we're NOT looking for

• Integrations that route Aegis output (verifier results, decision
  patterns) back into the LLM prompt as automatic retry hints.
  See the negative-space framing
  and docs/gap3_control_plane.md's
  Critical Principle — the system must reject degradation, not
  optimize toward goals via auto-retry.
• "I built a chatbot using Aegis" — Aegis isn't a chat surface, the
  CLI / API isn't designed for conversational loops.

Why this is open-call

Aegis V1 + V1.5 + V1.6 evidence (docs/v1_validation.md)
shows the decision system fires correctly across 5 model families
on 4 built-in scenarios. What we don't have evidence for is whether
the integration story works in real workflows. That's a question
only external users can answer.

If you build an integration and it surfaces friction (Rust build
issues, API gaps, missing documentation), that's exactly the
feedback we need. Open follow-up issues freely.

[Baijack-star]

This is a strong fit for the agent/MCP integration work I am doing.

I can take the MCP-server example shape if that would be useful: expose Aegis as a small MCP tool, add a copy-runnable examples/integration/mcp-server/ README, and include a smoke test that shows a client calling the tool and receiving a structured accept/reject decision.

I also run a small agent-native GTM/prototyping workflow, so I can document where the integration friction shows up rather than only dropping code. If that scope matches what you want in this issue, I can start with a minimal PR focused on the MCP example.

[wei9072]

This is a strong fit for the agent/MCP integration work I am doing.

I can take the MCP-server example shape if that would be useful: expose Aegis as a small MCP tool, add a copy-runnable examples/integration/mcp-server/ README, and include a smoke test that shows a client calling the tool and receiving a structured accept/reject decision.

I also run a small agent-native GTM/prototyping workflow, so I can document where the integration friction shows up rather than only dropping code. If that scope matches what you want in this issue, I can start with a minimal PR focused on the MCP example.

This is exactly the shape the issue is asking for — yes please, go ahead.

Three things to keep in mind so the PR lands cleanly:

1. The integration is the client side, not a new server. The
   aegis-mcp binary already serves validate_change over MCP
   stdio; the example's value is showing how a client (Claude
   Code, Cursor, your own orchestrator) mounts and calls it. No
   need to re-implement the server side.

2. The verdict is a stop signal, not a coaching prompt. When
   validate_change returns decision: BLOCK, the example should
   show the client halting / surfacing to the human / dropping
   the candidate edit — never feeding the reasons array back to
   the LLM as an automatic retry hint. The framing rationale is
   already in
   [docs/v1_validation.md#framing--what-aegis-actually-is](../v1_validation.md#framing--what-
   aegis-actually-is)
   and docs/gap3_control_plane.md's
   Critical Principle — worth a re-read before you wire the
   client's BLOCK handler.

3. Suggested layout: examples/integration/mcp-server/ with
   a README walking through "spawn aegis-mcp → call validate_change
   → branch on PASS/WARN/BLOCK", plus a smoke test that exercises
   one PASS case and one BLOCK case end-to-end. Friction notes are
   very welcome as part of the PR description (or a follow-up
   issue) — that's the second-most useful artifact after the code
   itself.

Minimal-PR scope you proposed sounds right. Open a draft PR
whenever you have something runnable; happy to review even rough
shapes early so we don't diverge on framing.

(FYI: there's V3 agent-side work in flight locally that uses the
same validate_change API as a built-in LocalAegisPredictor —
once that lands publicly we can cross-link from your example to
the in-tree client implementation as a reference.)

[Baijack-star]

Opened a draft PR with the minimal MCP client-side integration example here: #4

I kept the scope to the requested shape: spawn aegis-mcp, call validate_change, branch on PASS/BLOCK, and treat BLOCK as a halt/surface signal rather than feedback for an automatic retry prompt.

Local limitation: this machine does not have cargo, so I could only run Python compile and diff checks here; the smoke script itself is wired to run against cargo run --quiet --package aegis-mcp or an AEGIS_MCP_COMMAND binary.