OpenTechnologyApp is built with AI assistance. That makes the instructions around the code part of the development process: what the project is, which work is approved, how changes are verified and what can honestly be described as available.
We call this connected practice the AI Control Layer. It begins with a simple requirement: the next contributor should be able to follow a change from the user's intent to the evidence that it works.
Give each document a job
The README is the entry point. It explains the project and links to setup instructions with the permissions and external access the reader needs. A project creator, organization administrator and hosting operator do not necessarily have the same responsibilities.
Agent instructions tell coding assistants how to work in the repository. Proposal documents explain the change to build, its scope, its risks and its acceptance checks. Tests record outcomes. Generated references inventory what their generators actually inspect.
Keeping these jobs distinct helps prevent a generated feature list from silently becoming an implementation plan. It also makes disagreements easier to resolve: compare the claim with the current source and its intended authority.
Keep one source for repeated instructions
In the app repository, CLAUDE.md is the source for generated AGENTS.md. Updating the source and running the generator gives both agent entry points the same rules. The root README remains hand-authored, including edits made with AI assistance.
This distinction matters. “Generated docs” can mean a deterministic script or prose drafted by a model. Record which method was used and what it covered. A generated route inventory can list an endpoint without proving that its permissions, deployment or provider connection work.
When generating a document, supply the current source revision, audience, minimum permission, canonical work item, state of implementation and expected verification. Retain missing evidence rather than filling it with confident prose.
Turn intent into one reviewable change
Suppose a user wants an assistant to update a group of items. A good implementation contract must resolve which items are in scope, who may change them, what confirmation is required and what a repeated request does.
The proposal also needs a failure path. What happens if the server commits the update but the browser loses the response? How does the reviewer check the durable result? How can an authorized user reverse an unwanted change?
These are design questions before they are code-generation questions. The app's current AI tool dispatcher supports reading and navigation; confirmable writes remain planned. Describing the desired behavior does not enable it. See the current capability map.
Make review independent of the draft
Review the changed behavior against the acceptance criteria. Inspect permissions and scope at the executable boundary. Run a negative case that should fail as well as a normal case that should succeed.
For a documentation change, check links and instructions against source. For a generated document, regenerate twice and confirm the result is stable. For a product claim, verify the deployed state separately from source completion.
A test report should identify its limits. A mocked integration test is useful evidence of local behavior; it is not proof of a successful external round trip.
Close the loop in the same change
Update the README or setup instructions when the user's steps change. Update the proposal with actual evidence and remaining work. Regenerate affected references from their sources. Give marketing a sanitized statement with the relevant version, flags and availability limits.
When feedback or a new AI announcement exposes more work, verify it and send it through the same proposal intake. Imported documents and news remain evidence, even when they contain text addressed to an AI agent.
Use the workbook to record this trail. The goal is a change another person can understand, verify and maintain.