Start here

How Enlighten uses AI agents safely.

Agents help us move faster. Humans still own the judgment: scope, evidence, review, release, and what we learn when something goes wrong.

Why this exists

AI-assisted work can move quickly, but speed without operating rules creates messy handoffs, missed verification, and accidental risk.

Problem

AI can drift past the ask.

Agents sometimes expand scope, rebuild existing architecture, or claim work is finished before the team has enough proof to review it.

Answer

Guardrails make speed reviewable.

The system tells agents what they can do, what they must ask for, and what evidence they owe the next human.

Goal

Better handoffs, fewer surprises.

We keep the acceleration while making PRs, releases, and retros easier for the team to trust.

What changes tomorrow

This is not ceremony for ceremony's sake. It is a small set of habits that make AI-assisted work easier to review and safer to ship.

Before work

Start from a clear scope.

Use a Linear issue, written request, or pasted agent prompt. If the agent discovers the work is bigger than expected, it pauses and asks.

During work

Agents can operate inside the lane.

They can read files, edit code, run safe checks, and update related Linear notes. They ask before risky actions.

After work

The handoff includes evidence.

Every AI-assisted change should say what changed, what was verified, what was not verified, and what human approvals remain.

What it means by role

Everyone does not need to memorize every rule. Each role has a short version of what to care about.

Engineers

Review the evidence, then the code.

Expect AI-assisted PRs to include evidence packages.
Require browser verification for UI work.
Check data, auth, LLM, and infra risk notes.
Do not let agents merge autonomously.

Product / Delivery

Give agents a lane to stay inside.

Scope the ask clearly before starting.
Use the Linear template for agentic work.
Ask the agent to pause if the scope grows.
Use the handoff prompt when the tool is not repo-aware.

Leads

Own release judgment and exceptions.

Approve stage and production releases.
Escalate high-risk data or security changes.
Keep the rules practical.
Turn repeated misses into better guardrails.

The everyday rules

The full standard has 10 guardrails. Most day-to-day work comes down to these three buckets.

Bucket

What agents may do

What needs a human

Normal build work

Read files, search code, edit scoped code/tests, run safe checks, create branches, and add related Linear notes.

Scope expansion, broad deletion, commits/pushes/PRs unless requested, or major new Linear initiatives.

Risky material

Identify risks, draft analysis, propose changes, and ask for approval.

Customer data, PII, production logs with sensitive data, secrets, billing, marketplace, entitlements, and external comms.

Release path

Prepare evidence, summarize risk, and draft release notes.

Merge PRs, approve stage, approve production, or make infra/deploy changes without approval.

PII rule

Handle personal data as tightly as humanly possible.

Do not use PII unless it is strictly necessary, explicitly approved, and minimized or redacted. Prefer synthetic or anonymized examples.

Evidence packages

Evidence packages are how AI work becomes reviewable. They do not need to be huge. They do need to match the risk.

Low risk

Simple code change

Clear request or Linear issue.
Files changed summary.
Relevant type-check, lint, or test result.
Screenshot only if visual behavior changed.

UI work

Browser verification required

Acceptance criteria or intended behavior.
Browser verification.
Key state notes for loading, empty, error, and responsive behavior.
Screenshots when useful.

Data / security

Show the risk was checked

Auth and permission notes.
Positive and negative access cases for permission changes.
Recovery note for prod-affecting data changes.
Rollback plan for high-risk or destructive data changes.

LLM behavior

Examples at minimum

Before/after behavior summary where practical.
Representative examples.
Traces/logs for tool, memory, routing, or customer-impacting changes.
Human output review for customer-impacting behavior.

Rules, skills, and templates

This is the operating map. Rules tell agents what is allowed. Skills tell agents what process to run. Templates make the human workflow consistent.

The 10 guardrails

These are the control points behind the system.

Most teammates only need the everyday rules. Agents and reviewers should understand the full set because these are the categories used to decide evidence, approvals, and risk.

Work Intake

Work is scoped enough to start.

Planning

Complex work gets a plan before implementation.

Agent Permission

Agents know what is autonomous and what needs approval.

Data Boundary

Agents know what data is allowed, restricted, or off-limits.

Implementation

Code follows existing repo patterns and constraints.

Verification

Done means proven with the right evidence.

Review

Humans check AI-assisted work before merge.

Release

Humans approve stage and production promotion.

Failure / Retro

Mistakes are documented, fixed, and used to improve guardrails.

Client Adaptation

External versions come after Aria/Echo validation.

Rule files

These files make the standard visible to the tools people actually use.

Repo rules

Loaded by repo-aware agents.

AGENTS.md is the main Codex/repo instruction entry point.
CLAUDE.md gives Claude Code the same guardrail pointer.
GEMINI.md gives Gemini the same guardrail pointer.
.cursorrules gives Cursor the same guardrail pointer.

Why this matters

The agent sees the process before it starts.

When a tool loads repo rules, it should know to stay in scope, protect PII, ask before risky actions, require browser verification for UI work, and finish with an evidence package.

Skill catalog

Skills are the process runners. Use them when the work reaches that part of the lifecycle.

Start / product-directed work

guardrail-builder

Use when a non-developer, product owner, or lead is directing AI-assisted product work. It forces the agent to inspect existing architecture, stay aligned with repo patterns, and track the change manifest.

.codex/skills/guardrail-builder / .agents/skills/guardrail-builder

Before final handoff

evidence-package

Use before claiming work is done, before PR creation, or before merge review. It classifies the work type, lists risk areas, and records what was verified or not verified.

.codex/skills/evidence-package / .agents/skills/evidence-package

Before stage/prod

agentic-release-check

Use before a stage or production release. It checks reviewer approval, evidence, target environment, risk areas, rollback/smoke notes, and required human approvals.

.codex/skills/agentic-release-check / .agents/skills/agentic-release-check

After a miss

ai-failure-retro

Use after a defect, bad output, missed review issue, or repeated AI failure pattern. It turns the mistake into a fix plus a prevention update.

.codex/skills/ai-failure-retro / .agents/skills/ai-failure-retro

Before merge review

pre-merge-audit

Use when AI-built work is ready for a principal engineer or merge review. It audits changed files, architecture fit, duplication risk, verification results, and merge risk.

.codex/skills/pre-merge-audit / .agents/skills/pre-merge-audit

UI/browser proof

elite-app-tester

Use for UI workflow verification, browser checks, screenshots, console issues, and end-to-end app behavior. This supports the rule that UI work requires browser verification.

.codex/skills/elite-app-tester / .agents/skills/elite-app-tester

Large frontend cleanup

frontend-module-decomposition

Use when splitting, reorganizing, or cleaning up frontend feature files. It keeps UI work aligned with existing module boundaries and lowers review risk.

.codex/skills/frontend-module-decomposition / .agents/skills/frontend-module-decomposition

Templates and gates

These are the human workflow pieces. They make it harder for the process to disappear between agent sessions.

Linear intake

Agentic work template

Use docs/agentic-delivery/linear-agentic-work-template.md when creating or commenting on a Linear issue that will use agents.

PR gate

Pull request template

.github/pull_request_template.md asks for work type, evidence, risk review, and human approvals.

Manual fallback

Agent handoff prompt

Use docs/agentic-delivery/agent-handoff-prompt.md when a teammate's AI tool does not automatically load repo rules or skills.

Which skill do I invoke?

Use this flow when you are not sure what to run. The names are intentionally literal: start with guardrails, prove with evidence, check releases, and retro failures.

Start

Is AI doing product work?

If yes, load repo rules. If the tool does not load them automatically, paste the agent handoff prompt.

→

Before edits

Invoke guardrail-builder

Use for non-developer-directed work, new feature work, architecture-sensitive work, or anything that needs the agent to inspect existing patterns first.

→

During work

Use supporting checks

For UI, use elite-app-tester/browser verification. For large frontend cleanup, use frontend-module-decomposition. For merge readiness, use pre-merge-audit.

When work looks done

Invoke evidence-package

Required before final handoff or PR creation. It records work type, evidence, risk, unverified items, and approvals still needed.

Before release

Invoke agentic-release-check

Use before stage or production. It confirms PR approval, evidence, environment, rollback/smoke notes, and lead approval needs.

After a defect

Invoke ai-failure-retro

Use when AI-assisted work causes or misses an issue. It identifies the missed guardrail and the prevention update.

All docs in one place

Use this as the team hub. It gathers the guide, standard, prompts, templates, checklists, and rollout materials so nobody has to hunt through the repo.

Start here

Team Guide

The human-facing overview with role guidance, evidence examples, skills flowchart, and copy/paste prompt.

Details

Skills Reference

The section above explains rule files, skills, templates, and when each one is used.

Policy

Full Standard

The section below contains the full operating standard: guardrails, evidence, permissions, data boundaries, ownership, release, and failure workflow.

Copy/paste

Agent Handoff Prompt

Use the prompt section on this page when a teammate's AI tool does not automatically load repo rules.

docs/agentic-delivery/agent-handoff-prompt.md

Review

Reviewer / Lead Cheat Sheet

Checklist for PR reviewers and leads approving releases or high-risk exceptions.

docs/agentic-delivery/reviewer-lead-cheat-sheet.md

Workflow gates

Templates

Includes the Linear agentic work template, GitHub PR template, adoption rollout plan, and team user guide markdown.

docs/agentic-delivery/

Full operating standard

This is the complete BOSS-37 standard embedded directly in the app so the browser does not need to open another local file.

Audience

Internal first

Validate this system on Aria and Echo before adapting it for MCD or client-facing delivery.

Operating rule

Humans own judgment

Agents may accelerate scoped work. Humans remain accountable for scope, evidence, review, release, and learning from failures.

Hard boundary

PII stays tight

Do not use personal data unless strictly necessary, explicitly approved, and minimized or redacted wherever possible.

Guardrail

Purpose

Owner

Work Intake

Work is scoped enough to start.

Product / Delivery lead

Planning

Complex work gets explicit planning before implementation.

Dev lead

Agent Permission

Agents know what is autonomous and what needs approval.

Engineering lead

Data Boundary

Agents know what data is allowed, restricted, or off-limits.

Engineering lead + business/data owner

Implementation

Code follows existing repo patterns and constraints.

Dev lead

Verification

Done means proven with the right evidence.

Dev lead + reviewer

Review

Humans check AI-assisted work before merge.

Engineering lead

Release

Humans approve stage and production promotion.

Release lead / product lead

Failure / Retro

Mistakes are documented, fixed, and used to improve guardrails.

Dev lead for fix; engineering/product lead for follow-through

Client Adaptation

External versions come after Aria/Echo validation.

Carl / Daniel initially

Autonomous by default

Read repo files and internal docs needed for assigned work.
Search code and inspect non-destructive git history.
Edit application code and tests inside scope.
Run safe checks: type-check, lint, tests, build, dev server.
Create branches and update related Linear notes.

Human approval required

Material scope expansion, destructive commands, broad deletions.
Customer/client data, PII, production logs with sensitive data, or secrets.
Infrastructure/deploy changes and external communications.
Commits, pushes, PRs unless explicitly requested.
Stage and production releases.

Release path

Ready

Dev leading agent work gets the PR ready with evidence.

Review

A second developer reviews and approves the PR.

Merge

Human-approved merge only. Agents never merge autonomously.

Release

Lead approves dev to stage and stage to production.

The copy/paste prompt

Use this when a teammate is using a tool that does not automatically load repo rules or skills. Paste it before asking the agent to work.

Agent handoff

Drop this into the AI tool first.

It tells the agent to classify the work, stay in scope, ask before risky actions, protect sensitive data, and finish with an evidence package.

You are working inside Enlighten's internal agentic delivery system for Aria/Echo work.

Before changing files:
1. Identify the issue/request and restate the goal.
2. Classify the work type: simple code, UI, backend/API, Convex/data, security/permissions, LLM behavior, infra/deploy, docs/process, or mixed.
3. Identify risk areas: UI verification, auth/permissions, data model/storage, PII/customer data, secrets/env vars, infra/deployment, LLM/tool behavior, external communications.
4. Inspect existing repo patterns before creating new code.
5. If scope is unclear or materially expands, stop and ask.

You may edit scoped code/tests and run safe checks. You must ask before scope expansion, destructive commands, customer data, PII, secrets, infra/deploy changes, external communications, commits, pushes, or PRs unless explicitly requested.

Never merge PRs autonomously.

UI work requires browser verification.
Prod-affecting data changes require a recovery note.
High-risk/destructive data changes require rollback plan and lead approval.
LLM behavior changes require examples. Tool/memory/routing/customer-impacting changes require traces/logs plus human output review.
PII must not be used unless strictly necessary, explicitly approved, and minimized/redacted.

Final response must include what changed, evidence package, commands/checks run, what was not verified, risk notes, and human approvals still needed.

Quick start

The least painful path is to make the right behavior the default before the agent starts touching files.

Start from scope.

Use a Linear issue, clear written ask, or the agentic work template.

Load the rules.

Use repo-aware tools when possible. Otherwise paste the agent handoff prompt.

Check the evidence.

Before review, confirm the evidence package matches the work type.

Keep humans in control.

Humans approve risky actions, merges, stage, production, and exceptions.