Reference Project

Agents across every role of the software lifecycle

The Reference Project shows a multi-tenant SaaS product serving several client brands, and the way of working that builds and runs it. That way of working covers the full software lifecycle: requirements, planning, implementation, testing, review, documentation, release and operation. For almost every role in it there are agents that do the work or carry most of it.

Each agent has one defined role and works to written procedures, and the same checks apply to its work on every change. That makes the result dependable: it does not rest on which agent, or which person, happened to do the work.

Click a box for what each part does and what the arrangement gives someone running delivery.

How the work is done

1One way of working for all six codebasesagent roles · written procedures · standing rules · automatic safety stops2Guidance inside each codebaseinstructions for agents · documentation written for agents · local procedures · checks3Deliveryautomatic testing and building · security scan · demo updates by itself · production started by a person4Tickets and the release recordthe backlog · processes, requirements, release record, runbooks

↓works on

The six codebases

the product’s core services

5Accounts and consentwho is on the platform, and what they agreed to6Business ruleswhat is offered, how it is sold, how it is paid7Filesupload · checking · storage

sign-in

8Sign-inone login for web, apps and services · a look per brand · a separate admin console

apps

9Web and mobile appsone web app for every brand · mobile apps · an embeddable version · operator documentation

operations

10Operations and security recordthe register of every service, environment and secret · runbooks · security and audit records

↓runs as

What runs in production

11Cloud hostingMicrosoft Azure · demo and production side by side · managed database · monitoring and alerts12AI inside the producttext · moderation · images · research13App stores and app updatesApp Store · Google Play · same-day updates · push notifications14Outside servicespayments · email · address lookup · bot protection · analytics

1. 1One way of working for all six codebases agent roles · written procedures · standing rules · automatic safety stops. The setup every codebase shares, built on Claude Code: agents defined as roles with a named job, written procedures for recurring work, a standing rule for which tests are worth writing, and automatic stops that refuse destructive commands. Because it is one setup, a rule changed here changes how the work is done in every codebase at once. Agents can read the production databases but not change them, and long, mechanical work runs unattended until a finish line stated in advance is met.
2. 2Guidance inside each codebase instructions for agents · documentation written for agents · local procedures · checks. Each codebase carries its own instructions for the agents, and the larger ones a documentation layer written for them, so a change starts from a map rather than from re-working out how the codebase fits together. In the largest codebase that map is itself checked: a change fails if the documentation cites a path or a command that no longer exists, so the guidance cannot drift out of date unnoticed. Procedures only one codebase can describe, such as setting up a new brand, live here too. Read on: CI and boundary enforcement
3. 3Delivery automatic testing and building · security scan · demo updates by itself · production started by a person. Every change is tested, built and scanned for known security weaknesses automatically, and the demo environment updates on its own, so a change can be seen running before anyone decides to release it. The production release is then a single step a person starts, with everything before it already done. The web and mobile apps go through the same stages, and a person starts their production release too. Read on: A Jira ticket resolved by an agent, with a human in the loop where it matters
4. 4Tickets and the release record the backlog · processes, requirements, release record, runbooks. The backlog and the team’s written record are within the agents’ reach. One procedure takes a ticket from analysis through implementation to review, so every ticket follows the same path whoever picks it up. A production release is written into the release record by the procedure that detected it, so the record of what shipped, and when, is kept as it happens rather than pieced together afterwards. Read on: A Jira ticket resolved by an agent, with a human in the loop where it matters
5. 5Accounts and consent who is on the platform, and what they agreed to. Holds who is on the platform and what each of them agreed to, along with every channel the platform sends messages through. Its interfaces are written down as agreements before any code exists, so work on either side of one starts from the agreement rather than from the other side’s code. The one agreement another service depends on is checked on every build, so a mismatch stops the build instead of surfacing once the two run together. Read on: CI and boundary enforcement
6. 6Business rules what is offered, how it is sold, how it is paid. Carries the product’s business rules, payments and invoicing included. Every rule that decides an outcome or a price is enforced in this one service, and the apps only show the result. A rule therefore changes in one place and every app and every brand follows it, and no two apps can disagree about what a customer owes.
7. 7Files upload · checking · storage. One job: accept an uploaded file, check that it is what it claims to be, store it and attach it to the record it belongs to. Every upload passes the same checks in this one place, whichever app it came through, so a file built to carry hidden code has one door to get past, not one per app. Files are kept in the main database, one system fewer to run, a simplicity the current scale allows.
8. 8Sign-in one login for web, apps and services · a look per brand · a separate admin console. One sign-in serves the web, the mobile apps and the services behind them, and a new sign-up is reported to the platform automatically. The thirteen brand looks are colour-and-logo layers over one shared design, so a new brand is a layer to add rather than a login to build and maintain. The console that can change someone’s identity sits at a separate address open only to approved networks: the part the public reaches cannot change who anyone is.
9. 9Web and mobile apps one web app for every brand · mobile apps · an embeddable version · operator documentation. One codebase holds the web app for every brand, the mobile apps, an embeddable version and operator documentation written from the code, all on 23 shared building blocks. A brand’s own mobile app is a theme and a configuration entry, not a new project, so every brand gets the same screens and the same fixes. Before a change here is recorded, 26 checks written for this codebase confirm that every screen exists in every app and every language is complete; a gap surfaces in seconds, not in a review comment. Read on: CI and boundary enforcement
10. 10Operations and security record the register of every service, environment and secret · runbooks · security and audit records. Not a service: the single record of every service, environment and secret, with the runbooks and procedures that operate them. A secret is recorded as a named reference and its value kept in a vault, so an environment can be set up without anyone reading one. Security questions are answered from records kept current: the known weaknesses in each codebase; who holds production admin access; and what a card-payment audit asks for, itself checked automatically. Erasing one person’s data is done by code from explicit inputs, never freehand by a model.
11. 11Cloud hosting Microsoft Azure · demo and production side by side · managed database · monitoring and alerts. Everything the product runs sits on one managed platform, a demo and a production environment side by side, with a managed database holding the data, so there is one place to watch. Monitoring records what the system does, and alerts fire on the conditions set for them, so a known failure reaches a person instead of waiting to be noticed.
12. 12AI inside the product text · moderation · images · research. The AI the product itself uses, separate from the AI that builds it: writing text, moderating content, generating images and research grounded in web search, through Microsoft’s and Google’s AI services. Only the business-rules service calls a model and the apps never do, so there is one place to see what the product sends to an AI service, and one place to change it.
13. 13App stores and app updates App Store · Google Play · same-day updates · push notifications. Both mobile apps reach users through the App Store and Google Play. A change that needs no new store version goes straight to installed apps once it is approved, so a fix reaches users the same day instead of after a store review. A remote setting tells an installed app when it must be updated, so an old version can be retired rather than kept working.
14. 14Outside services payments · email · address lookup · bot protection · analytics. What the platform uses rather than builds: payments through two providers, transactional email, address capture, bot protection on forms, and analytics that run only after the visitor consents. Buying these keeps the team’s own work on the rules that are specific to this product.