Repository instructions should tell an agent how to run the project, which checks define completion, which actions require a person, and where responsibility changes across the tree.
Required commands: install, build, test, lint, type-check, and start
The first section should state the supported runtime, package manager, installation command, development command, and the shortest reliable validation sequence. Commands should be copied from working automation when possible. A repository that says only 'run the tests' still leaves the agent to choose a command, a working directory, and a service dependency, which makes two otherwise identical runs diverge.
Include the expected clean state and any fixtures or local services required for tests. Secrets should appear as variable names and provisioning instructions, never as values committed to the repository. If one test suite is slow, identify the fast checks that run during a task and the full checks required before handback.
Path ownership, prohibited actions, and approval roles
GitHub supports repository-wide instructions, path-specific instructions, and nested AGENTS.md files, so a large repository can put rules close to the code they govern. The closest file should explain the module's vocabulary, public interfaces, test command, and files that another team owns. This reduces the chance that a local change quietly rewrites a contract used elsewhere.
The instruction set should name actions that stop for human approval: changing production data, rotating credentials, modifying billing, weakening an access rule, publishing a package, merging a branch, or contacting a third party. A prohibition without an escalation path merely creates a dead end, so each stop should name the role that decides and the evidence that person needs.
Completion evidence: checks, diff, manual review, and open uncertainty
Completion should point to observable results. For a code change, that usually includes the affected tests, type and lint checks, a clean diff, and a concise explanation of what remains unverified. Screenshots or manual checks can supplement those results when the behavior is visual, but they should not replace a deterministic check that already exists.
Coding Agent Repository Pilot reviews repository instructions as part of a supervised pilot operated by Reality Contact, LLC. The service prepares and tests the instruction set; the customer retains authority over access, code review, merges, security decisions, and deployment.
Where the service stops
Reality Contact, LLC configures and measures the supervised pilot, but does not approve production changes, replace the buyer's security or legal review, manage employees, or allow an agent to merge outside the written controls. The buyer reviews the evidence, decides which task classes the repository controls support, and retains responsibility for accounts, permissions, merges, and deployment. This is technical implementation and review support; it does not replace the customer's security, legal, employment, procurement, or production-change review. We do not promise productivity, defect reduction, autonomous operation, successful deployment, or approval of any task class.
Sources: GitHub guide to repository and path-specific custom instructions; GitHub documentation for deployment environments and approval rules.