docs: factory MVP — PRD, architecture review, market research and ADR-0013 (proposed)
What this is
Four documents that treat the current agentic factory as a proof of concept and define the production MVP. Documentation only: no workflow, script or prompt changes.
| Document | What it holds |
|---|---|
docs/prd/agentic-software-factory.md | The requirements: 73 functional requirements, 14 non-functional targets with POC baselines, 11 constraints, a build-versus-adopt table, exit criteria from POC to production |
docs/architecture/factory-mvp-architecture-review.md | The evidence and the reasoning: current-state findings, root causes, options analysis, comparison with other systems, an adversarial review, the convergence hypothesis, reviewer surfaces, where a Lens should run, and how it is built |
docs/architecture/adr/0013-factory-mvp-reference-architecture.md | The proposed decision, in the ADR-0000 form, with checkable boundaries. Status: proposed |
docs/research/market-agentic-software-factories-research-2026-10-10.md | Market research: what the market offers, the solo builder as a customer, a competitive teardown, and what it means for the PRD |
Why
The POC proved every function of the factory and has stopped converging. Measured on 2026-10-10 at commit aef61164:
- At least 44,968 workflow runs in seven days in this repo for 30 merged pull requests.
- Merges per week flat since August while median time to merge rose from about 1 hour to 12–22 hours.
- No open pull request in the org holds an approval; about a third of recent merges had no standing approval.
- Eight fixes moved a failure somewhere else instead of removing it (review §2.4).
Seven structural causes explain the eleven recurring failure classes (review §4).
What ADR-0013 proposes
- One self-contained repository, new, with decision logic that does no I/O.
- A declared lifecycle and one state record per work item.
- Level-triggered admission in one place, with three brakes outside the kernel.
- One run contract; a job is a credential boundary; the model requests effects and a separate job applies them.
- Agents have their own identity; the owner account is the human's alone.
- One release, one path, promoted on evidence.
- An approval is bound to content.
- Verification binds: a required, hermetic check.
- One fact, one place.
- Migration: built greenfield, cut over as a strangler through this repo's channel tags, with a budget and a stopping rule set before anything runs.
- Two mechanisms are provisional, with thresholds: the git-backed store and per-event wakes.
- Lenses report through one contract; convergence is decided, not discussed.
It supersedes nothing on acceptance. It names nine follow-on ADRs, each landing with the migration step that makes it true.
A note on the ADR number
This record was opened as ADR-0012. While the PR was in review, ADR-0012 was assigned on main to the maintainer comment gate's exemption set, so the factory MVP record is now ADR-0013. The ADR's Context says how the two relate.
What it does not claim
The adversarial review (review §14) found that this architecture removes waste under the machine limits and does not raise the two ceilings that bind: the maintainer's attention, and how often a change is right the first time. Both documents say so.
How to read it
- Ten minutes: review §1 (summary), then ADR-0013.
- To challenge it: review §14 (the ceiling, where it fails first) and §13 (what other systems chose differently).
- To decide scope: PRD §11 (open questions) and §10.3 (exit criteria).
Decisions this needs from the maintainer
Listed in PRD §11. The ones that shape everything else:
- Do agents move off the owner account (OQ-2)?
- Is the POC frozen for features while it is replaced, and what may the migration cost (OQ-9)? ADR-0013 is not in force until a dated limit, a POC defect policy and a kill criterion are written.
- Which outside reviewers are removed now (OQ-13)?
Decided so far
- Where it is built (2026-10-10): in a new repository, cut over through this repo's existing channel tags one intent and one ring at a time. Not in place, and not a rename or one-step swap, because GitHub Actions does not redirect reusable-workflow references. Review §18; ADR-0013 decisions 1 and 10.
- Sourcing (2026-10-10): the market research found the workers are a commodity and the line around them is not, so the PRD now says the Factory builds the control plane and adopts workers and reviewers through its contracts. Market research §4.3; PRD §10.4, FR-72.
- Third-party reviewers (2026-10-10): integrated through a structured contract; comment bodies gate nothing. Review §15.5 and §16; ADR-0013 decision 12.
Verification
markdownlint-cli2with the repo config: 0 issues across the three files.- Citations to code are
path:lineataef61164; the highest-consequence ones were re-checked by hand, and the branch ruleset was read live. - Platform claims were read from vendor documentation on 2026-10-10; review §11 and §16.7 list what could not be verified.
Not in this PR
Fifteen defects found in passing (review §12) are listed but not fixed here.
🤖 Generated with Claude Code
Problem
See the linked issue.
Risk
Low — documentation/configuration only; no runtime code paths change.
Test plan
No test files were added or updated. Verification: bash scripts/dev-lead-lint.sh (shellcheck --severity=warning) ran pre-commit; the existing CI (bats + lint) guards the change.
Rollback
Revert this PR. No non-revertible side effects (no tags, migrations, or external state).
Monitoring
n/a — no runtime effect; documentation/configuration only.