Skip to main content

Repository Best Practices

ProPR opens pull requests. Unless a repository declares validation commands in .propr/workflow.yml, ProPR does not run your test suite or linters before committing, and its execution flow has no validation phase — agent output is committed and pushed. Even with workflow validation configured, results are reported in the completion summary but do not block the commit, so your CI is the layer that catches regressions and enforces merge requirements. A repository set up with strong CI and good hygiene gets safer, more autonomous results from ProPR; one without it relies entirely on human review to catch problems.

These practices are about preparing a repository so ProPR's automation works with you. None of them are enforced by ProPR — they are the conditions under which it performs best.

Make CI The Quality Gate​

Run lint, type checks, tests, and the build on every pull request through GitHub Actions (or your CI of choice). Because ProPR commits agent changes without validating them itself — or, when workflow validation commands are configured, reports their results without gating the commit — CI is what verifies an agent-generated PR actually works.

Two ProPR features consume CI results directly, so CI is not just a reviewer aid — it changes how automation behaves:

  • Auto-merge (--auto-merge, or the auto-merge label) enables GitHub's native auto-merge, which holds the merge until all required status checks and approvals pass. This is only as safe as your branch protection: if no checks are marked required, auto-merge can merge as soon as the PR is mergeable. Define required status checks in branch protection so auto-merge waits for them. See --auto-merge and Planner Studio.
  • /ultrafix waits for passing checks before each re-review and resumes when a check_run completes. Fast, reliable CI means tighter cleanup loops; slow or flaky CI stalls them. Note that a commit with no check runs is treated as ready, so /ultrafix only benefits from CI when checks actually exist. See /ultrafix.

Practical implications: keep CI fast (loops and merges wait on it) and deterministic — flaky tests stall /ultrafix, block auto-merge, and can send fix loops chasing failures that aren't real.

Keep A Human Gate Where You Want One​

Auto-merge removes the human from the loop once checks pass, which is appropriate for low-risk paths but not for everything. To keep a person in the loop on sensitive areas, add a CODEOWNERS file and require code-owner approval in branch protection. Required reviews are enforced by GitHub the same way required checks are, so auto-merge waits for them too — letting you mix hands-off merging for routine changes with mandatory human sign-off on the parts that matter.

ProPR adds its own guard on top: list sensitive paths under auto_merge.protected_paths in .propr/workflow.yml (for example CI workflows, database migrations and dependency manifests). ProPR then never arms auto-merge for a PR that touches them; it comments on the PR and leaves the merge to a person. The policy is read from the PR's base branch, .propr and .propr/** are always protected, and any doubt (an unreadable policy, a diff GitHub cannot list) means auto-merge is not armed. Branch protection and code owners remain the authoritative merge controls; the policy only decides whether ProPR asks GitHub to merge automatically.

Harden Your CI​

Agent-generated PRs run through the same pipelines as any other, so the usual supply-chain hygiene applies — and matters more when PRs are opened automatically:

  • Grant the workflow GITHUB_TOKEN the least privilege it needs (permissions: scoped per workflow/job; default to contents: read).
  • Pin third-party actions to a full commit SHA rather than a moving tag.
  • Be deliberate about pull_request_target and workflows that expose secrets to PR-triggered runs.
  • Keep secrets out of logs and out of the agent's reach; never echo them in CI output.

Keep Changes Reviewable​

Lint rules that cap file length, function size, and cyclomatic complexity keep diffs small and focused. This helps two audiences at once: human reviewers, and the agent — smaller, well-scoped files give it tighter context to reason over and reduce the chance it edits the wrong layer.

ProPR does not measure or enforce complexity, and it indexes large files like any other. But repository knowledge degrades when structure is unclear: plans miss important files, agents change the wrong layer, and suggestions get generic (see Repository Knowledge). Clear module boundaries and small files improve both planning and review.

Scope work small

Broad tasks produce PRs that stall in review. Prefer smaller issues that produce focused PRs — see Work Splitting and Planning. When PRs keep needing heavy rework, the scope of the issues is the first thing to fix; the Metrics page shows where time and cost concentrate.

Match The Agent Environment To CI​

Agents run in isolated execution containers. Use .propr/setup.sh (scaffolded by propr init) to install the dependencies and task-specific tooling the agent needs, so it can build and run the project the same way CI does. Keeping the agent environment and CI aligned means changes that look right in the run also pass the pipeline, and it lets /fix repair environment problems in scope. See ProPR CLI.

Document Conventions​

ProPR's planning and review draw on repository knowledge. A clear README, a CONTRIBUTING guide, and documented build/test conventions help it produce accurate plans and on-target changes instead of generic ones. If you keep agent-specific guidance, put it where the agent will use it rather than relying on it to infer conventions. See Repository Knowledge.

Checklist​

  • Required status checks (lint, type check, tests, build) configured in branch protection
  • CI is fast and free of flaky tests
  • CODEOWNERS + required reviews where human sign-off should gate merges
  • Workflow GITHUB_TOKEN scoped to least privilege; third-party actions pinned to SHAs; secrets kept out of logs
  • Lint rules cap file size and complexity to keep diffs reviewable
  • .propr/setup.sh installs the same dependencies CI uses
  • Issues are scoped small enough to produce focused PRs
  • Conventions documented in README/CONTRIBUTING

For how ProPR reviews PRs and what "good" looks like, see PR Comment Commands and Execution Safety.

Version workflow policy​

Commit an optional .propr/workflow.yml to keep lifecycle hooks, prompt instructions, validation commands, preview guidance and repository concurrency limits under review with the code. Run propr init to scaffold a commented example. Existing .propr/setup.sh repositories continue working unchanged.

ProPR loads policy and instructions from one revision of the task's base branch for each implementation or follow-up. The task timeline records that revision. Use an instruction file such as .propr/instructions.md for longer guidance, and repeatable validation commands for checks whose results should appear in completion comments. Hooks run only inside the agent container; repository policy cannot raise instance limits or change container permissions.