# Engineering Standards

> The standards an AI Pod builds against: how specs get written, how validation is designed before the build, and the twelve systems an agent reaches.

Source: https://www.koombea.com/ai-pods/standards/

---

## A project is twelve systems, not one codebase

Most diagrams of software delivery draw phases. Phases are not the problem. The
problem is that the information an agent needs is scattered across a dozen
systems, and an agent is only as useful as the ones it can actually reach.

Each system below has a defined access pattern. Retrieval means the agent
queries an index rather than reading raw files. Protocol means a structured
connection to a service. Filesystem and command line mean direct access. One
system is closed entirely.

| System | What lives in it | How an agent reaches it |
| --- | --- | --- |
| Documentation | Project handbook, product vision, technical solution, decisions, and the domain knowledge that explains how the client's business works | Retrieval |
| Specification | Specs, acceptance criteria, backlog, prioritization, and delivery state | Command line or protocol |
| Design | Wireframes, interfaces, interaction flows, tokens, and component documentation | Protocol or command line |
| Development | Source code, configuration, branch rules, and the committed context file every agent reads at the start of a session | Filesystem and command line |
| Validation | Test scenarios per acceptance criterion, coverage, and the traceability between them | Filesystem and command line |
| Delivery | The pipeline that builds and deploys, and the distribution that ships releases | Command line |
| Infrastructure | Environments, infrastructure as code, and the rules that provision and constrain agents | Command line |
| Observability | Error tracking, performance, structured logging, health checks, alert routing, and agent telemetry | Command line or protocol |
| Communication | Channels, notifications, system events, and scheduling | Protocol or command line |
| Governance | AI usage policy, client disclosure, data classification, tool vetting, and the agent identity and permission model | Retrieval and filesystem |
| Account | Contracts, budget, delivery metrics, and escalations. Role-gated, not open to the team by default | Retrieval, restricted |
| Secrets | API keys, credentials, environment variables, and signing certificates | No access |

### Domain knowledge is the one most often missing

If a client's business is specialized, and in health services, payments, or
industrial work it always is, an agent without that context produces confident
wrong answers. Any document explaining how the business actually works belongs
in the documentation system, whoever wrote it.

## The system an agent never reaches

Secrets is human-only. Not restricted, not logged, not role-gated. Closed.

An agent references a variable name and never sees a value. That rule is the
reason the system exists as its own domain rather than as a folder inside
infrastructure: its job is to define how credentials are named, where they live,
and how they are injected, so that none of them can arrive in a prompt.

Access patterns are easy to write down and easy to quietly widen. This is the
one that never widens.

## What the standards cover

Six standards cover the twelve systems.

| Standard | Covers |
| --- | --- |
| Specification | What gets built, and how completely it is described before it is built |
| Validation | What proves the build matches the spec, designed before the build starts |
| Delivery | The quality gates a change passes before it reaches production |
| Development | The build loop, and what belongs in the repository before an agent works in it |
| Observability | The layers that turn a silent runtime failure into a signal |
| Design | How design decisions survive the trip into code |

## Where you stand

Knowing the standards is not the same as knowing your own position against them.
The [AI readiness audit](https://www.koombea.com/ai-pods/ai-readiness-audit/) scores four dimensions on
evidence, tags every finding by how strongly it is supported, and returns a
ranked gap list. It is the same procedure we run on our own projects.