Agent Setup and Configuration

Agent Setup & Configuration

Status: Complete · [Contributions Welcome ✍️] — share your .cursorrules and persona prompts. The practical wiring behind the Digital Org Chart.

Principles need plumbing. This page is the copy‑paste starting point: repo scaffold, the .cursorrules that encode your guardrails, persona prompt templates, and how to wire the Guardian sandbox and the self‑healing loop.

---

1 · Repo scaffold

The AI‑hygiene layout, ready to clone:

📂 project/
├── 📄 .cursorrules            # system-wide LLM guardrails (below)
├── 📁 specs/                  # source of truth — one file per bounded context
│   └── 📄 <slice>.md
├── 📁 src/
│   └── 📁 features/
│       └── 📁 <slice>/        # one bounded context
│           ├── schema.sql
│           ├── routes.ts
│           └── view.tsx
├── 📁 tests/                  # Guardian's domain
└── 📄 README.md

---

2 · The .cursorrules template

Drop this at the repo root. It encodes the non‑negotiables once so you never re‑type them:

# === SAE GUARDRAILS ===

## Source of truth
- specs/<slice>.md is authoritative. If code and spec disagree, the spec wins.
  Flag the conflict; never silently diverge.
- Do not change behaviour without a corresponding spec change.

## Bounded contexts
- Work only inside src/features/<slice>/. Never read or modify another
  context's internals — use an explicit contract (event, shared type, or API).

## File hygiene
- Single responsibility per file. Soft ceiling ~100 lines.
- Prefer cohesion over hitting a line count; do not fragment tightly-coupled logic.

## Vertical slices
- Generate schema + API + state + UI together, driven by one spec.

## Security
- Never output secrets. Read them from env/secret store only.
- Validate and sanitize all external input.
- Enforce the authZ rules named in the spec; never assume they exist.
- Do not add dependencies without flagging them for review.

## Irreversibles (require explicit human approval — never auto-apply)
- auth changes, payment logic, data deletion, schema drops, external sends.

## Output discipline
- Change only what the task requires. Flag any unrequested change.
- After a change, state what you altered and which spec section it maps to.

Adapt the language/framework specifics, but keep the five sections — they map directly to the five non‑negotiables.

---

3 · Persona prompt templates

The same model can play all three roles in separate sessions. The separation is what matters — see one persona, one job.

Engineer

You are the Engineer. Read specs/<slice>.md and the files in
src/features/<slice>/ only. Implement the vertical slice to satisfy the
spec, honouring every edge case. Obey .cursorrules. Generate the structure
first for my review, then the implementation. After, list what you changed
and the spec section each change maps to.

Visualizer

You are the Visualizer. From the UI section of specs/<slice>.md, produce
clean, semantic, accessible components. Use the project's design tokens.
No business logic — emit only the view layer and the props/contract it
needs from the Engineer.

Guardian (run in a FRESH context — no memory of how the code was written)

You are QA. Your job is to BREAK the <slice> slice, not approve it.
Assume it is wrong and find why. Write integration tests for every edge
case in specs/<slice>.md, PLUS hostile inputs the spec didn't mention
(injection, oversized payloads, concurrency, auth bypass, degraded
dependencies). Default to "broken" when uncertain. Report every failure.

---

4 · The Guardian sandbox

The Guardian runs continuously and adversarially, isolated from production:

• A containerized environment with no prod credentials and least‑privilege access.
• Runs the spec's acceptance criteria as tests on every change.
• Seeded with hostile fixtures (malformed payloads, boundary values, concurrent writes).
• Its findings re‑enter the loop at Reconcile — fixes flow through the spec.

The cardinal rule: the context that wrote the code must not be the context that judges it. Spin up the Guardian fresh.

---

5 · Wiring the self‑healing loop

To make Module 5's feedback circle real:

1. Capture — structured logging + error/exception tracking in production.
2. Route — on an exception, ship the stack trace + payload into an agent context.
3. Diagnose — the agent cross‑references trace ↔ codebase, drafts a spec amendment (root cause).
4. Gate — you review the amendment. Irreversible‑touching fixes are never auto‑applied.
5. Re‑run — approved amendment re‑enters the lifecycle at Spec; the Zero‑Ops pipeline ships it.

---

6 · Model selection

Match the model tier to the Context Entropy of the task — frontier models for high‑entropy architecture and adversarial review, faster/cheaper tiers for low‑entropy mechanical edits. Track the effect on cost per change. Default to the most capable model when a change touches a high‑blast‑radius area, regardless of entropy.

Reality check. Tooling is the easy 20% — copy these templates and you're running in an hour. The hard 80% is the judgment: knowing when the agent is confidently wrong, when a "low‑entropy" change is high‑stakes, and when to stop and spec instead of generate. Configuration removes friction; it does not remove the need for an operator who can actually evaluate the output. See When NOT to Use SAE.

---

See also: Operator Techniques · Best Practices · Approved Zero‑Ops Tooling List · Getting Started.