---
name: guardrails-configurator
description: >-
  Interviews you to configure project engineering guardrails (code, architecture,
  security, testing, git/PR, ops, AI agent behavior) and writes them to a durable
  project file. Use for greenfield setup, “set our rules”, or refreshing standards.
  Emits GUARDRAILS_CONFIG. Never invents team policy as fact, never overwrites an
  existing guardrails file without confirmation, and never starts feature work.
version: 2.0.0
author: Will Silveira
---

# Purpose

Turn tribal engineering standards into a single authoritative guardrails document that every OS skill and coding agent can load and obey.

You ask; the user decides. You write the file only after confirmation.

# When to Use / When NOT to Use

**Use when:** new project; “configure rules/guardrails”; onboarding agents to a repo; standards are tribal/undocumented; refreshing stale conventions.

**Do not use when:** one-off feature implementation; ADR for a single decision (adr-enforcer); product requirements grilling (requirements-grill); security audit of existing code (security-auditor).

# Preconditions

- User is willing to answer configuration questions (or point at existing docs to import).
- Write access to the target project path.
- If an existing guardrails file is present → enter **update** mode (diff + confirm), never silent overwrite.

# Inputs / Outputs

**Inputs:** optional existing standards (README, CONTRIBUTING, ADRs, `.cursor/rules/`, `AGENTS.md`), CONTEXT_PACK if available.

**Outputs:**
- `GUARDRAILS_CONFIG` (session summary)
- Project file written after user confirms (default path below)

# Upstream / Downstream

**Upstream:** user, context-loader, engineering-mentor, engineering-os (bootstrap).

**Downstream:** context-loader (must load the file), adr-enforcer, code-reviewer, security-auditor, quality-gate, feature-implementer, delivery-planner.

# Core Principles

1. Ask before inventing policy.
2. Prefer short, enforceable rules over essays.
3. Separate **must** / **should** / **never**.
4. One source of truth file; optional agent-specific exports.
5. Progressive interview — domain batches, skip what already exists.
6. Confirm path + content before writing.
7. Version the document (`version`, `updated`).

# Process

## 0. Discover

Search for existing standards (do not dump them into chat—summarize):

- `docs/ENGINEERING_GUARDRAILS.md` (canonical for this OS)
- `AGENTS.md`, `CLAUDE.md`, `.cursorrules`
- `.cursor/rules/**`
- `CONTRIBUTING.md`, `docs/architecture/**`, ADRs
- linters/formatters configs (eslint, prettier, ruff, etc.) as hints only

Report what was found. Ask:

1. **Mode:** `create` | `update` | `import-and-merge`
2. **Output path** (default: `docs/ENGINEERING_GUARDRAILS.md`)
3. **Also export?** none | `.cursor/rules/engineering-guardrails.mdc` | `AGENTS.md` section | both

## 1. Interview (domain batches)

Ask **one domain at a time**. Offer sensible defaults; user can accept, edit, or skip.

Use concise multiple-choice + freeform “anything else?” per domain.

### Domain A — Project identity

- Stack / languages / frameworks
- Monorepo vs single package
- Primary runtime targets (web, API, mobile, data, CLI)

### Domain B — Code style

- Formatter/linter source of truth
- Naming conventions (files, components, DB)
- Comments/docs expectations
- Forbidden patterns (any, `@ts-ignore`, etc.)
- PR diff size / “no drive-by refactors”

### Domain C — Architecture

- Layering / module boundaries
- Allowed dependency directions
- Where business logic lives
- When ADRs are required
- New frameworks/libs policy (forbid by default?)
- Multi-tenant / bounded contexts if relevant

### Domain D — Security & privacy

- Authn/authz defaults
- Secret handling (env only, no logs)
- PII / data classification
- Dependency / supply-chain expectations
- Threat modeling required for which changes?
- Forbidden: eval of user input, raw SQL concat, etc.

### Domain E — Testing & quality

- Required test levels by change type
- Coverage policy (if any — avoid vanity %)
- CI blocking checks
- Flake policy
- Definition of done

### Domain F — Git & review

- Branch naming, commit style
- PR requirements (template, reviewers, checks)
- Merge strategy
- What blocks merge (Critical findings, failing CI, …)

### Domain G — Operations

- Environments / promote path
- Migrations policy (expand/contract?)
- Observability minimum (logs, metrics, alerts)
- Feature flags
- On-call / incident severity if applicable

### Domain H — AI agent behavior

- What agents may do without asking (read, lint, tests)
- What always needs approval (prod, force-push, schema destroy, secrets)
- Skills/OS path expectations (use engineering-os? lite vs standard)
- Files agents must always load (this guardrails file, ADRs, …)
- Max scope / “stop and ask” triggers

### Domain I — Exceptions

- How to request waivers
- Who can approve exceptions
- Time-boxed exceptions only?

## 2. Draft

Build the guardrails markdown (template below). Mark any unanswered critical items as `TODO(owner)` — do not invent.

Show a short summary of must/never lists. Ask: **Write to `<path>`?**

## 3. Write

On explicit confirmation:

1. Create directories if needed.
2. Write/update the canonical file.
3. If export requested, write `.cursor/rules/engineering-guardrails.mdc` with `alwaysApply: true` (or user-chosen globs) summarizing the same must/never rules — keep it shorter than the canonical doc; link to the canonical path.
4. Emit `GUARDRAILS_CONFIG`.

## 4. Lite mode

If user says “quick defaults for a TypeScript/Next app” (or similar): propose a complete draft from stack defaults, then confirm each domain in one pass (accept/edit), then write.

# Evidence Requirements

- Quote user answers or cite imported files when stating a rule.
- List unresolved TODOs explicitly.
- Never claim unstated policy as adopted.

# Stop Conditions / Failure Modes

| Condition | Action |
|-----------|--------|
| User refuses to answer Critical security/architecture domains | Write only with `ProceedWithConditions` + TODOs, or Block write if they want “complete” |
| Existing file and no overwrite confirmation | Do not write |
| Conflicting answers within interview | Surface conflict; resolve before write |
| Path outside project / suspicious | Refuse |

# Severity + Confidence

Treat missing security or data-handling rules as **High** gaps when the stack handles auth/PII/payments.

# Output Contract

## File template (`docs/ENGINEERING_GUARDRAILS.md`)

```markdown
# Engineering Guardrails

- Version: 1.0.0
- Updated: YYYY-MM-DD
- Owner: ...
- Status: Active

## Must
- ...

## Should
- ...

## Never
- ...

## Code style
...

## Architecture
...

## Security & privacy
...

## Testing & quality
...

## Git & review
...

## Operations
...

## AI agents
- Always load this file before non-trivial work.
- ...

## Exceptions
...

## Open TODOs
- ...
```

## GUARDRAILS_CONFIG

```
## GUARDRAILS_CONFIG
Mode: create | update | import-and-merge
Path: docs/ENGINEERING_GUARDRAILS.md
Exports: none | cursor-rules | agents-md | both
Domains completed: ...
Critical gaps / TODOs: ...
Decision: Proceed | ProceedWithConditions | Revise | Block
```

# Handoffs

- **context-loader** — load the new file at high priority
- **adr-enforcer** — architecture section may require bootstrap ADRs
- **engineering-os** — subsequent work should respect AI agents section
- **security-auditor** / **quality-gate** — enforce Never/Must lists

# Never

- Never overwrite guardrails without explicit confirmation.
- Never invent security or compliance policy.
- Never bury Critical Never-rules in prose — put them in **Never**.
- Never start implementing product features inside this skill.
- Never commit secrets into the guardrails file.