docs: factory MVP — PRD, architecture review, market research and ADR-0013 (proposed)

Draft
DO
1mo ago
+6720-0

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.

DocumentWhat it holds
docs/prd/agentic-software-factory.mdThe 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.mdThe 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.mdThe proposed decision, in the ADR-0000 form, with checkable boundaries. Status: proposed
docs/research/market-agentic-software-factories-research-2026-10-10.mdMarket 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

  1. One self-contained repository, new, with decision logic that does no I/O.
  2. A declared lifecycle and one state record per work item.
  3. Level-triggered admission in one place, with three brakes outside the kernel.
  4. One run contract; a job is a credential boundary; the model requests effects and a separate job applies them.
  5. Agents have their own identity; the owner account is the human's alone.
  6. One release, one path, promoted on evidence.
  7. An approval is bound to content.
  8. Verification binds: a required, hermetic check.
  9. One fact, one place.
  10. 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.
  11. Two mechanisms are provisional, with thresholds: the git-backed store and per-event wakes.
  12. 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-cli2 with the repo config: 0 issues across the three files.
  • Citations to code are path:line at aef61164; 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.