Agent Pipeline

Corgtex is developed by a fully autonomous three-agent pipeline. One human prompts each stage; no human reviews code. Safety comes from vendor separation (three different AI providers, none of which can paper over another’s mistakes) plus mechanical CI gates (Codex cannot merge a PR whose required checks are red). This page is the canonical spec. AGENTS.md at the repo root is the per-role quick reference loaded by each agent’s harness.

​

Roles

The human prompts each agent and can intervene with PR labels.

​

Handoff artifact

The single handoff artifact between all three agents is the plan contract in the pull request body.

• The format is fixed by /.agents/plan-template.md.
• The Planner writes it into the draft PR body, the Executor reads and updates it there, and the Reviewer diffs the final code against it.
• Before a PR exists, agents may keep a local copy at .agents/plans/<branch>.md; that directory is ignored and must not be committed.
• PR-body plans are intentionally retained in GitHub PR metadata. Keep them public-safe: no private keys, API tokens, passwords, raw credentials, secret values, or customer-private facts. Put sensitive context in an approved private system and reference it generically from the PR plan.
• scripts/check-plan.mjs enforces that (a) the PR body contains a valid plan, (b) changed files are a subset of the plan’s “Files to touch” section, and (c) the PR satisfies the selected risk tier.

​

Stage 1: Plan

The Planner (Claude):

1. Creates a new branch with a descriptive name.
2. Copies the template into the PR body and fills every section, including Risk tier.
3. Pushes the branch.
4. Opens a draft PR whose body is the plan.
5. Stops. Does not write implementation code.

​

Stage 2: Execute

The Executor (Gemini in Antigravity):

1. Verify branch: First action is to run git branch --show-current to ensure branch correctness, since multiple agents often run concurrently in the workspace. Checkout or create the correct branch first.
2. Context: Reads the PR body plan. If the PR does not exist yet, reads .agents/plans/<branch>.md.
3. Implements strictly within the plan’s “Files to touch” allowlist. Any scope change requires updating the PR body plan first.
4. Validates locally: Runs npm run check and whatever the plan’s test plan specifies. Waits for these commands to complete entirely and strictly ensures there are no lint or compilation errors before pushing.
5. Opens or updates the PR via gh pr create / gh pr edit. The PR description must explicitly include the risk tier, completed acceptance checklist, and visual proof links for frontend changes. Preferred visual proof links come from Corgtex Build Artifacts via node scripts/upload-build-artifacts.mjs.
6. Sets auto-merge: gh pr merge --auto --squash. This fires the merge once Codex approves and GitHub CI is green.
7. Respects the CI fix cap: 3 red-CI fix attempts, then labels the PR needs-replan and stops.

​

Stage 3: Review

The Reviewer (Codex) applies the checklist in .codex/review.md:

• Plan present in the PR body.
• scope-check passes (changed files ⊆ allowlist).
• Acceptance criteria all ticked and reflected in code.
• No forbidden-path changes without forbidden-path-approved.
• Diff within risk-tier caps unless large-change-approved.
• gitleaks green. No db push, no --no-verify, no removed force-dynamic.
• Tests added when domain code changed.
• Visual proof links present in the PR body for frontend changes. Corgtex Build Artifacts links are preferred; PR attachments, CI artifacts, or private proof links are acceptable fallbacks when Build Artifacts is unavailable.
• All required CI checks green.

Codex either approves (auto-merge fires) or requests changes (the Executor re-enters the fix loop).

​

Scope and caps

Mechanical, CI-enforced:

• File allowlist: changed files ⊆ plan’s “Files to touch”.
• Risk tiers: low is ≤ 1200 non-doc LOC and ≤ 50 files; standard is ≤ 800 non-doc LOC and ≤ 25 files; high is ≤ 400 non-doc LOC and ≤ 15 files.
• Size override: use large-change-approved only when the PR exceeds the selected risk-tier cap, with justification in the plan.
• Forbidden paths: deploy/**, .github/workflows/**, prisma/migrations/**, packages/domain/src/auth*.ts, apps/web/lib/auth.ts. Require forbidden-path-approved label plus justification.
• Forbidden-path risk: forbidden-path changes are evaluated against the high-risk cap unless large-change-approved is present.

​

Rollback

Post-deploy safety is the smoke-prod job in .github/workflows/ci.yml. If it fails on main, first check whether current production health recovered on the same failed SHA:

• If production is still unhealthy, .github/workflows/auto-revert.yml opens a revert PR labeled auto-revert, forbidden-path-approved, and large-change-approved.
• The workflow uses AUTO_REVERT_TOKEN, a repo secret backed by a bot or app token with contents, pull_requests, and workflow access, so the revert PR triggers normal pull_request CI.
• The Reviewer merges the revert immediately; the same gating applies (required checks green) but the plan-present / scope-check steps are relaxed for auto-revert-labeled PRs.
• The original PR is re-opened as draft with the failure logs attached. The Planner decides next steps.
• If production recovered on the failed SHA, rerun the trusted GitHub production smoke. Use a fix-forward window of up to one hour for smoke-script, deploy timing, or configuration recovery before rolling back.

Rule: rollback first when production remains red; fix forward briefly when production has already recovered on the failed SHA.

​

Human intervention

The human prompter controls the pipeline with PR labels:

• halt-agents — the Reviewer will not merge and the Executor will stop pushing. Use when something looks wrong and you need to think.
• force-merge — override the pipeline. Logged in the PR and in the daily digest. Rare. May be applied and executed by an agent when the human explicitly instructs it via prompt (see below).
• needs-replan — set by the Executor when stuck, or by the human. The Planner updates the PR body plan before handing work back.

​

Human-directed agent bypass

When a human explicitly instructs an agent (via prompt) to force-merge a PR:

1. The agent adds the force-merge label to the PR.
2. The agent adds a PR comment: ⚠️ Human-directed bypass: merged with --admin per explicit instruction.
3. The agent runs gh pr merge <number> --admin --squash.
4. This is logged in the daily digest alongside all other force-merge events.

Scope: This bypass covers branch protection (required reviews, status checks). It does not exempt the PR from secret scanning, prisma db push bans, or --no-verify.

​

Branch protection (required repo settings)

This PR cannot set these; a human with repo admin must configure them in GitHub → Settings → Branches → main:

• Require a pull request before merging: on.
• Require approvals: 1.
• Dismiss stale approvals: on.
• Require review from Code Owners: off (no human owners in this pipeline).
• Require approval of the most recent reviewable push: on.
• Require status checks to pass: on. Required checks:
  • Lint, Typecheck & Test
  • Database Sync
  • Build
  • Docs Validation
  • Plan Present
  • Scope Check
  • Secret Scan
  • Diff Size
• Require branches to be up to date: on.
• Require conversation resolution: on.
• Require merge queue: on (prevents two Executor PRs from racing).
• Do not allow bypassing the above settings (no admin bypass): off — allows repo admins and human-directed agents to use --admin when needed.
• Restrict who can push to matching branches: allow only the Reviewer (Codex GitHub App) and the merge queue.

​

Codex configuration (required app settings)

Configure Codex as a GitHub App on the repo with permission to:

• Read pull requests and repository contents.
• Submit reviews (approve / request changes).
• Merge pull requests (for auto-merge to fire under Codex’s identity).

Its review rules live in .codex/review.md.