Mergepath

Reference implementation of the AI Agent Tooling Standard.

The goal is to allow multiple AI coding agents and development tools to operate consistently without configuration drift. See BRAND.md for the umbrella vocabulary (Playground, Cockpit, Tiebreaker, Checks) and naming history.

For AI Agents

Read these files in order before taking any action:

AGENTS.md — behavioral instructions and operating rules
rules/repo_rules.md — binding structural constraints
Relevant specs/ files — intended behavior
.ai_context.md — supplemental system context

Code Review Policy

Every change in this repository goes through the policy in REVIEW_POLICY.md, including a self-peer review by the authoring agent's reviewer identity and, for changes that cross the threshold or touch protected paths, automated external review via the OpenAI Codex GitHub app (Phase 4a) or a manual CLI fallback (Phase 4b).

Key Files

File	Purpose
`AGENTS.md`	Instructions for AI agents
`DEPLOYMENT.md`	Build and deployment
`CONTRIBUTING.md`	Development workflow
`.ai_context.md`	High-level system context
`BRAND.md`	Mergepath umbrella vocabulary (surfaces, reserved names, naming history)
`mergepath/playground/index.html`	Mergepath Playground — tune the review policy and replay recent PRs against the draft
`scripts/policy-sim.sh`	Bakes real `gh` PR data into a temp copy of the Mergepath Playground for local replay
`.mergepath-sync.yml`	Propagation manifest for synced canonical, kit, and templated surfaces
`.github/ISSUE_TEMPLATE/`	Synced issue-template kit; consumers may add product-specific templates
`.github/pull_request_template.md`	Synced canonical pull-request template
`ai_agent_tooling_standard.md`	Full repository standard (reference)

Firebase Auth Template

This template includes the canonical Google Cloud and Firebase helper scripts for this account:

scripts/gcloud/gcloud installs a local wrapper so ordinary gcloud commands can use 1Password-backed or explicit source credentials without a routine interactive gcloud auth login, while attributing quota to the resolved target project from explicit flags, the repo's .firebaserc, or the active gcloud config.
scripts/firebase/op-firebase-setup creates a per-project firebase-deployer@{project-id}.iam.gserviceaccount.com, grants deploy roles, and configures impersonation.
scripts/firebase/op-firebase-deploy resolves a source credential per the canonical precedence (project Firebase-vault SA key first, with shared 1Password ADC and impersonation as fallbacks) and runs firebase deploy with the target project stamped in as the quota project.

The canonical source-credential precedence is documented in DEPLOYMENT.md § Deploy credential precedence (canonical). The default day-to-day credential — interactive and CI — is the per-project Firebase-vault SA key (op://Firebase/{project-id} — Firebase Deployer SA Key), with the shared 1Password ADC as a fallback and an explicit GOOGLE_APPLICATION_CREDENTIALS as the highest-priority override.

This 1Password-first deploy-auth model is intentional. Do not revert template-derived repos to deploy-key-on-disk or routine firebase login-based guidance unless a human explicitly requests that change.

See DEPLOYMENT.md for the full bootstrap and deploy flow.

Directory Structure

Directory	Purpose
`rules/`	Binding repository constraints
`specs/`	Intended system behavior
`plans/`	Execution and migration plans
`mergepath/`	Mergepath Playground and reserved slots for future Mergepath surfaces (see `BRAND.md`)
`tests/`	Automated validation
`src/`	Application code
`functions/`	Backend handlers
`scripts/`	Build, CI, and automation tooling
`docs/`	Architecture and design documentation
`dist/`	Generated build artifacts (do not edit manually)