Git & PR Review Process

Relevant source files

The following files were used as context for generating this wiki page:

• AGENTS.md
• INDEX.md
• pkg/convex/projects.ts
• pkg/convex/project_variables.ts
• pkg/convex/project_stages.ts

The Git and Pull Request (PR) review process in the Barekey project is designed to facilitate autonomous development by AI agents while maintaining high code quality through automated reviews and structured workflows. It emphasizes frequent commits, clear branch naming, and a lifecycle that integrates the GitHub CLI (gh) with the Codex review system.

This process ensures that feature development remains visible and that critical areas—such as encryption and Data Encryption Key (DEK) lifecycles—receive appropriate scrutiny before merging.

Sources: AGENTS.md:104-124, INDEX.md:46-77

Development Workflow

Barekey utilizes a feature-branch workflow where all changes are isolated before being integrated into the main codebase. Direct commits to the main branch are strictly prohibited.

Branching and Commits

Developers and agents must create a new branch for every task using the prefix feat/ followed by a descriptive task name. Commits should be frequent and include descriptive messages to provide a clear history of the work performed. Regular pushing to the remote repository is required to ensure PR progress is visible to the team and Codex reviewers.

Sources: AGENTS.md:118-120, INDEX.md:46-49

GitHub CLI Integration

The GitHub CLI (gh) is the primary interface for managing the development lifecycle. It is used for issue tracking, PR creation, and communication.

Command	Purpose
gh issue list	Browse open tasks before starting work.
gh pr create --fill	Open a PR from the current feature branch.
gh pr comment --body "@codex review"	Trigger an automated Codex review.
gh pr view --comments	Check for feedback from Codex or humans.
gh pr merge --squash --delete-branch	Finalize and integrate changes.

Sources: INDEX.md:83-108

Pull Request Lifecycle

The project follows a "Full Cycle" approach where agents and developers are expected to manage the PR from creation to merge autonomously, provided specific safety criteria are met.

The PR Process Flow

The following diagram illustrates the standard lifecycle of a Pull Request within the project:

Autonomous Merging Constraints

While autonomous merging is encouraged to maintain velocity, certain conditions require a "Hold" for human intervention. Merging must not occur if:

• The PR touches encryption logic or the DEK lifecycle.
• The feature depends on another unmerged feature.
• Codex raises concerns that cannot be resolved with high confidence.
• The task description explicitly requires human sign-off.

Sources: INDEX.md:69-77

PR Review with Codex

Codex is utilized as an automated reviewer that provides feedback via GitHub comments.

Review Guidelines

• Non-Blocking: Developers should not stop work or wait for a review after every push. They are encouraged to continue implementing features while Codex processes the changes.
• Intermittent Resolution: Review comments should be checked periodically. Valid issues must be addressed in follow-up commits.
• Explanation: If a developer disagrees with a Codex suggestion, they should respond to the comment using gh pr comment to explain the architectural decision rather than making a change.

Sources: AGENTS.md:109-116, INDEX.md:107-108

Merge Strategies

The project prefers the squash merge strategy to keep the main branch history clean and concise.

# Preferred: keeps history clean
gh pr merge --squash --delete-branch

# For large multi-commit PRs where history is relevant
gh pr merge --merge --delete-branch

# Use when waiting for CI checks to pass
gh pr merge --auto --squash

Sources: INDEX.md:79-82

Code Quality and Documentation

The review process is supported by strict TypeScript rules and a specific commenting philosophy designed for "inter-agent communication."

Documentation Standards

Comments are treated as context for the next developer or agent. Self-evident code should never be commented, while non-obvious decisions, encryption logic, and ab_roll probability logic must always be documented using JSDoc for functions.

Sources: INDEX.md:125-155

Backend Verification

Before a PR is considered ready for review, any changes to the backend (Convex) must be verified:

1. Deployment: Run npx convex deploy to ensure code compiles and deploys to the dev environment.
2. Logs: Tail live logs using npx convex logs to verify runtime behavior.
3. Data Integrity: Check the Convex dashboard or use npx convex data to ensure schema migrations did not break existing records.

Sources: INDEX.md:110-123, pkg/convex/projects.ts, pkg/convex/project_variables.ts, pkg/convex/project_stages.ts

The Git & PR Review Process ensures a balance between speed and safety, utilizing automation to handle routine quality checks while reserving human oversight for high-risk security components.