Agent Platform Runbook

Use this runbook when you want platform-consistent execution across external coding agents.

Goal

Run one deterministic flow regardless of agent frontend:

• generate a spec package
• execute in a local or hosted coding agent
• enforce Omar loop until `P0-P2` are clear and gates are green

Operator checklist

1. create a GitHub repository and default branch protection
2. clone locally and add spec artifacts at repo root (`spec_sheet.md`, `builder_prompt.md`, optional `playbook.md`)
3. configure your agent runtime permissions:

• Codex CLI: enable command execution and git operations for the workspace
• Claude Code / Cursor-style agents: set permission profile to allow local commands and branch commits only

1. start in read-only audit mode for baseline findings
2. switch to gated edit/autonomous mode only after approval policy is active
3. execute Omar loop (`scan -> patch -> test -> rescan`) and stop only on clean gates or explicit budget/policy exits
4. checkpoint via branch + PR, never direct push to protected branch

Platform setup shortcuts

• Codex CLI:
• authenticate once with your provider key
• allow workspace command execution
• allow branch commits; keep protected branches write-blocked
• Claude Code:
• enable command execution and git in local workspace settings
• keep push/PR as approval-gated operations
• Cursor / Copilot / Augment / Replit / Lovable:
• allow local terminal and branch commits
• disable direct push to protected branch
• keep Omar gate as required status check on PRs

Agent settings snippets (optional)

Use these as starting points inside your local repo settings files.

```json

// .claude/settings.json

{

"permissions": {

"allow": ["Bash(*)", "Read(*)", "Write(*)"],

"deny": ["Bash(git push main)", "Bash(git push master)"]

}

}

```

```json

// .cursor/rules/runtime.json

{

"policy": "branch_only",

"required_checks": ["lint", "typecheck", "tests", "build", "Omar Gate"]

}

```

```md

<!-- .github/copilot-instructions.md -->

• keep changes scoped to active phase
• never bypass Omar loop for P0-P2 findings
• no direct pushes to protected branches

```

Spec package convention

Use these artifact names at repo root so every agent can follow the same contract:

• `spec_sheet.md`
• `builder_prompt.md`
• `omar_gate.yml`
• `playbook.md` (optional but recommended)

Suggested command sequence

1. `git checkout -b feat/<scope>`
2. implement phase scope only
3. run local quality gates (`lint`, `typecheck`, `tests`, `build`)
4. open PR and wait for Omar scan
5. fix every `P0-P2` finding
6. rerun checks and merge only on clean gate

Omar loop checklist (operator view)

1. open PR and stream required checks
2. wait for Omar findings
3. remediate all P0-P2 findings
4. rerun checks from clean head
5. merge only when all required checks are green
6. capture run IDs and evidence links for audit trail

Spec continuity for add-feature work

• keep a stable base spec hash as the invariant policy contract
• add feature-delta specs for each scoped enhancement
• evaluate both at review time:
• base spec enforces non-regression constraints
• delta spec enforces feature acceptance criteria
• if constraints conflict, fail closed and require reconciled spec update

Demo-safe evidence pack

• run timeline with approvals
• deterministic stop reason
• evidence export with integrity chain head
• compare-window KPI snapshot (TTC, closure rate, reproducibility)

This runbook is product-safe for customer operations and technical diligence without exposing private orchestration internals.

Structured Answers