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

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)

# 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.