Skip to main content
Corgtex uses an autonomous three-agent pipeline for all development. The full specification is in Agent Pipeline. This page covers the PR-specific conventions that apply to every change.

​
Branching

  • One branch per plan. No overlapping scopes.
  • Descriptive names: feat/optimistic-finance, fix/login-crash, docs/agent-pipeline.
  • The plan contract lives in the PR body. Before the PR exists, agents may keep a local ignored copy at .agents/plans/<branch>.md.

​
The plan is the contract

Every PR is backed by a plan contract in the PR body. The plan is the handoff between Planner, Executor, and Reviewer, and it is enforced mechanically:
  • plan-present CI job fails if the PR body does not contain a valid plan.
  • scope-check CI job fails if any changed file is outside the plan’s “Files to touch” allowlist.
  • The PR body must state the risk tier.
  • The Reviewer (Codex) rejects PRs whose plan lacks ticked acceptance criteria.
Copy /.agents/plan-template.md to start. PR-body plans remain visible in GitHub PR metadata. That is acceptable for normal execution plans, but plans must stay public-safe: no private keys, API tokens, passwords, raw credentials, secret values, or customer-private facts. scripts/check-plan.mjs blocks obvious credential patterns in the PR body; sensitive context should live in an approved private system and be referenced only generically.

​
Opening the PR

The Executor opens the PR using gh pr create (installed via Homebrew; /opt/homebrew/bin/gh if not on PATH). The PR body:
  1. Contains the full plan contract.
  2. States the risk tier — low, standard, or high.
  3. Summarizes what shipped — one or two sentences, the “walkthrough.”
  4. Describes demo exposure for customer-visible product changes. Update scripts/seed-jnj-demo.mjs when safe seeded data is needed, or explain why the feature cannot be shown safely in the public demo.
  5. Links actual visual proof in the Visual Proof section for any change under apps/web/app/**, apps/web/components/**, or apps/web/lib/components/**. Prefer Corgtex Build Artifacts: capture proof under ignored .artifacts/, upload it with node scripts/upload-build-artifacts.mjs, and paste the emitted markdown links into the PR body. Use PR attachments, CI-uploaded artifacts, or another private artifact link only when Build Artifacts is unavailable. Do not commit generated screenshots or recordings.
Auto-merge is set by the Executor immediately (gh pr merge --auto --squash) so the PR merges as soon as the Reviewer approves and required checks are green.

​
CI gates

Every PR must pass:
  • check — lint, typecheck, Prisma validate.
  • test:unit / test:integration / test:all — Vitest unit and DB-backed integration coverage. test:integration uses docker-compose.test.yml.
  • db-sync — migration ↔ schema parity.
  • build — env -u DATABASE_URL npm run build (database-independent).
  • docs — public docs guard, mint validate, and broken-link check.
  • plan-present — PR body contains the plan contract.
  • scope-check — changed files ⊆ plan allowlist and policy checks pass.
  • gitleaks — no secrets in the diff.
  • diff-size — risk-tier caps: low ≤ 1200 non-doc LOC / 50 files, standard ≤ 800 / 25, high ≤ 400 / 15.
All of these are required by branch protection on main. The Reviewer cannot merge a PR whose required checks are red.

​
Public docs hygiene

The docs/ tree is only for the public documentation site. Private or client-specific notes, partner analysis, handoff docs, generated QA output, screenshots, recordings, Slack manifests, and agent plan files must stay out of docs/ and out of Git history. Keep local generated output under .artifacts/, and prefer Corgtex Build Artifacts for review proof links. Use PR attachments, CI artifacts, or private artifact links only when Build Artifacts is unavailable.

​
Labels

  • forbidden-path-approved — justification in the plan, required for changes to deploy/**, .github/workflows/**, prisma/migrations/**, packages/domain/src/auth*.ts, apps/web/lib/auth.ts.
  • large-change-approved — override for the selected risk-tier cap.
  • halt-agents — human stop; Reviewer will not merge, Executor will not push.
  • force-merge — human override, logged.
  • needs-replan — Executor is stuck; Planner picks up.
  • auto-revert — created by .github/workflows/auto-revert.yml after a failed smoke-prod.

​
Automated Document Updates

When a PR merges to main, our Mintlify AI workflow evaluates the diff to determine if documentation is now outdated. If so, it drafts a separate PR against the docs site through the same Planner → Executor → Reviewer pipeline described above.