'/%3e%3cpath%20d='m0%200-119.7-83.92%2091.32-65.6%20128.91%2079.56z'%20fill='%231d6075'%20stroke='%231d6075'%20stroke-width='0.8'%20stroke-linejoin='round'%20transform='matrix(1.33333%200%200%20-1.33333%20588.6%20492.05)'/%3e%3cpath%20d='m0%200%20113.06-90.6L320.45%2054.67l.46%20143.88z'%20fill='%2318505f'%20stroke='%2318505f'%20stroke-width='0.8'%20stroke-linejoin='round'%20transform='matrix(1.33333%200%200%20-1.33333%20278.27%20483.16)'/%3e%3cpath%20d='m0%200%20.34%20159.15-225.4-137.58L-83.84-66.9Z'%20fill='%23216b83'%20stroke='%23216b83'%20stroke-width='0.8'%20stroke-linejoin='round'%20transform='matrix(1.33333%200%200%20-1.33333%20390.91%20251.7)'/%3e%3cpath%20d='m0%200%20.34%20159.15%20236.09-134.2L95.2-63.54Z'%20fill='%23123e4b'%20stroke='%23123e4b'%20stroke-width='0.8'%20stroke-linejoin='round'%20transform='matrix(1.33333%200%200%20-1.33333%20390.91%20251.7)'/%3e%3c/svg%3e){kind=small}
Reference · Architecture
Architecture Guide
A single reference for how the software factory is structured, what each layer does and does not do, and how the work maps to an engagement.
Last updated 12 October 2026
Definitions
- Software factory
- Agents that write specifications, tests and code inside your repositories, under rules that require human review before anything merges.
- Spec is Law
- The accepted specification, not the model, holds autonomy. No implementation starts without an accepted specification and a failing test.
- The harness
- The Realized harness: commands, rules, subagents, hooks that check agent actions, and bootstrap scripts for Cursor. Releasing the harness publicly is under consideration.
- Engagement
- Our phased commercial work with a customer: Discovery Workshop, Bounded Pilot, Realization Engagement.
The four layers
| Layer | What it does | What it does not do |
|---|---|---|
| L1 Governance substrate | Policy checks and identity binding. Agents open draft pull requests; a person approves every merge. | It does not merge on its own. Rollback means reverting the merge. |
| L2 Bounded actuation | Typed, permissioned tool calls against systems of record. | It is designed to avoid free-form writes. |
| L3 Orchestration mesh | Coordinates subagents across the execution loop. Local runs are configured to run at most 8 subagents at once. | This setting covers local subagents only, not cloud agents. |
| L4 Models | Models you bring, from your own Cursor setup. | We ship no model or runtime and keep no credentials in the repository. |
Layer, loop and phase
Every loop step belongs to one layer. The Discovery Workshop scopes the loop, the Bounded Pilot runs it end to end for one workflow in one environment, and the Realization Engagement extends it to more workflows.
| Loop step | Layer | What happens | First run in |
|---|---|---|---|
| Spec | L1 Governance substrate | A person writes or approves the ticket and its acceptance criteria. | Discovery Workshop (scoped) |
| Tests first | L2 Bounded actuation | The agent writes failing tests from those criteria. | Bounded Pilot |
| Agent run | L2 Bounded actuation | A cloud agent opens a draft pull request, then commits work to it. | Bounded Pilot |
| Automated checks | L3 Orchestration mesh | The agent runs the tests before it pushes, and a code-review check runs on the change; findings are recorded on the pull request. | Bounded Pilot |
| QA | L3 Orchestration mesh | A QA agent checks the preview and records a ready or flag verdict on the pull request. | Bounded Pilot |
| Human approval | L1 Governance substrate | A person reviews and approves every merge. | Bounded Pilot |
Harness workflow
Specifications, work items and findings live in docs/ in your Git repository. Each acceptance criterion runs through Red → Green → Refactor in separate subagents, so the test is written before the code it checks.
Local subagents run in waves of at most 8. Agents open draft pull requests. A person approves every merge. Rollback means reverting the merge.
Where the work runs
In your own repositories and toolchain, using Cursor. Realized.dev hosts no runtime and no model. The audit trail is your Git history.
Cost model
You bring your own models. Model usage is billed to you directly by your model provider; we add no margin on tokens. Our fees are covered on the pricing page.
Where the numbers come from
| Number | Type | Source |
|---|---|---|
| 4 layers | Design | The architecture described on this page. |
| 8 subagents at once | Configured setting | Local runs are configured to run at most 8 subagents at once. It does not describe cloud agents. |
| 90 minutes | Fixed format | Length of the Discovery Workshop. |
Questions
- Can agents merge code?
- No. Agents open draft pull requests. A person approves every merge.
- How is a change rolled back?
- By reverting the merge in Git.
- Does Realized.dev host a model or runtime?
- No. The work runs in your repositories with Cursor and the models you bring.
- How many subagents run in parallel?
- Local runs are configured to run at most 8 subagents at once. This does not describe cloud agents.
- Who pays for model usage?
- You do, directly to your model provider. We add no margin on tokens.
- Is the harness open source?
- Releasing the harness publicly is under consideration.
- Where do specifications live?
- In docs/ in your Git repository, next to the work items and findings.
Want to see the loop on one of your workflows?
Book the 90-minute workshopSecurity & Deployment Reference