Software Factory Guide to Agent-Ready Repos for AI Coding

Anyone who has used agents to write production code will recognise the problems: broken environments, ignored instructions, and changes that stray from the agreed plan. Reviewing the result can take more effort than expected.

A software factory gives that work a consistent set of rules and checks. The repository holds the product requirements, coding standards and tests. When an agent breaks a rule, the tools flag it early so the agent can fix it.

I want that feedback to do more of the routine work that otherwise falls to an engineer reviewing a pull request. People still decide what the product should do and whether a change is ready to merge. The repository should give them clear evidence for that decision.

That is the approach behind the bulletproof repository.

What the factory accepts

Work starts with an issue that describes the intended change. It draws on a product requirements document (PRD), which explains how the feature should behave, and a North Star, which sets the product's direction.

A person can write the issue, or develop it through a conversation with an agent. The repository applies the same standards whichever model, agent tool or workflow the team uses. Each issue needs to describe the intended result clearly enough for a reviewer to check it.

For example, "Make the homepage faster" needs a measurable target before work can start. The issue stays in a visible queue while that requirement is clarified. Each issue must also identify any conflict with an existing PRD. A change to agreed behaviour needs a proposed PRD update and human approval.

The North Star and the PRDs

On a new project, the North Star gives the team a shared direction. It lives in the repository and is versioned alongside the code. When the product's direction changes, the team updates it first, records the change and gets human approval. Each pull request can then be checked against a known version of the product's goals. PRDs describe the behaviour of individual features in more detail.

In enterprise codebases, I've seen a useful practice emerge: teams commit PRDs alongside the features they describe. The PRD records how the product should behave; the code and tests show how closely it meets that requirement.

A change that conflicts with a PRD needs a product decision. The team discusses the difference and approves an updated PRD or an explicit exception before, or alongside, the code change.

Versioning these documents gives reviewers a record of how requirements have changed. Reviewers still need to check that the code follows the current approved PRD, including changes agreed while the pull request was open.

The template keeps each PRD small. It states the intent, describes behaviour a user can observe, and links to the end-to-end test intended to prove it:

An automated documentation check verifies that each PRD promise links to an existing test title. A reviewer still needs to establish that the test proves the behaviour described.

An architecture decision record (ADR) explains why the team chose a particular design. Keeping it alongside the code gives future contributors a place to find the reasoning and update it as the design changes.

Each ADR records the decision, its reasoning and its consequences:

The agent-ready repository

The repository holds the standards and checks that guide the agent's work. Naming conventions, dependency restrictions and architectural boundaries become lint rules, type constraints and automated tests. These tools flag violations while the agent is still working.

Pre-commit checks run before a change enters version control. In supported agent sessions, an additional hook blocks common attempts to skip them, including --no-verify and disabling Husky. Continuous integration (CI) repeats the checks on a clean checkout before merge. This gives the agent a chance to fix routine mistakes before a person reviews the change.

In the template, each folder has a role. The rules below define which roles may import code from each other:

// .fallowrc.jsonc
"boundaries": {
  "zones": [
    { "name": "web-routes",     "patterns": ["apps/web/src/routes/*/**"] },
    { "name": "web-features",   "patterns": ["apps/web/src/features/*/**"] },
    { "name": "web-api-client", "patterns": ["apps/web/src/api-client/**"] },
    { "name": "ui",             "patterns": ["packages/ui/src/**"] }
  ],
  "rules": [
    // A route composes a page from features, the api client and the ui kit.
    { "from": "web-routes",   "allow": ["web-features", "web-api-client", "ui"] },
    // A feature is shared code that routes compose. One feature never imports another.
    { "from": "web-features", "allow": ["web-api-client", "ui"] },
    // UI primitives import no other role.
    { "from": "ui",           "allow": [] }
  ]
}

These rules keep the layers separate. A route can assemble features, the API client and UI components. A UI component that imports the API client fails the architecture check. The same check rejects imports between feature folders, so each feature keeps a clear boundary.

The pre-commit hook runs these checks in the agent's working copy:

# .husky/pre-commit
pnpm typecheck
pnpm exec biome check --error-on-warnings --staged
pnpm fallow:audit        # boundaries, dead code, cycles, complexity
pnpm secret-scan

The linter ignores inline lint-disable comments, and warnings fail the gate. The agent must address both warnings and errors before the change can pass.

The rules also help with migrations. When a new convention is encoded in a lint rule, the check identifies code that needs to change. An agent can work through those findings and rerun the checks after each fix.

These examples come from the bulletproof repository, where I keep developing this approach. Suggestions, issues and focused pull requests are welcome.

Documents still hold the context that needs human judgement: product goals, acceptance criteria and the reasoning behind trade-offs. Reference material such as API documentation, component inventories and structural diagrams can be generated from the code so it stays in step with the implementation.

Together, these rules give agents consistent feedback and help them produce changes that fit the codebase.

Verification in layers

Verification checks a change at several levels, from individual functions through integration, component and contract tests to end-to-end user behaviour. Each level answers a different question. A failing unit test can explain a fault inside a function; an end-to-end test shows how that fault affects the user.

For services and endpoints, contract tests check the agreement between a service and its callers. Pact is one tool for this. Behaviour-driven end-to-end tests check the wider flow.

Types add another check where both sides share a language. The web app imports the API's types, so an incompatible interface change produces a build error. Contract tests also check agreements across language boundaries. Together, these checks help a team change the implementation while preserving the behaviour people rely on.

The final review checks the change against the approved North Star and PRDs. Any agreed change to product behaviour belongs in the documents alongside the code.

Merge confidence

People remain responsible for approving and merging pull requests. The factory should give them enough evidence to make that decision with less routine checking.

At review time, the evidence should show what changed, which parts of the system could be affected, and what risk remains. It should include:

• End-to-end and contract tests covering the affected behaviour.
• Assertions that check the feature against its PRD.
• Style checks and visual regression evidence for visible changes.
• Screenshots, videos and preview deployments for UI work.
• Passing type, lint and architecture checks.
• A clear account of gaps in contract or behavioural test coverage.

The template also protects the checks themselves. It keeps a versioned list of required checks and fails CI if a workflow weakens one. That includes allowing a required check to fail with continue-on-error, skipping it with an if: condition, or hiding its exit code with || true.

Tests provide useful evidence when they check the behaviour the product requires. The review should make clear what they cover and where coverage needs more work.

For a low-risk change, passing checks and evidence tied to the PRD can give a reviewer enough confidence to approve without repeating the tests locally. That also depends on the change fitting the architecture and any PRD conflicts being resolved. High-risk changes still need manual checks. Preview deployments help reviewers explore the result alongside the test evidence.

These checks give the reviewer evidence to judge whether a change is ready to merge. The review should also make clear what still needs checking. Gaps in coverage, unclear requirements or changes that affect much of the system should hold up approval or be explicitly flagged for a decision.

Closing

A useful software factory makes a change easier to review. The requirements describe the intended behaviour, the tools check the agreed standards, and the tests give the reviewer evidence to assess.

People continue to set the direction and approve the result. Better checks give them more time for the decisions that need their judgement.

This could also make it practical for product managers, designers and engineering leaders to open pull requests within the same controls. I would judge its success by what happens to the engineers reviewing those changes: they should spend less time correcting routine mistakes and more time deciding whether the product does what it should.