Orchestrata Ultimate › Plans › build-factory-architecture

Build Factory — self-improving, pattern-based, TDD spec-build pipeline (2026-07-06)

Source: plans/build-factory-architecture.md at 8a2cb42ad · last changed 2026-07-27 · first committed 2026-07-06 · 168 lines.

Prose pending.

Plan text

Build Factory — self-improving, pattern-based, TDD spec-build pipeline (2026-07-06)

Dogfood Orchestrata to build Orchestrata. A self-improving factory that turns a spec into merged, traced, tested code using the project's own roles, tools, generators, and knowledge graph — augmenting each where it falls short.

Companion to swarm-plan-prioritized-2026-07-06.md (WHAT to build, by impact) and wiring-campaign-2026-07-06.md (unwired code). This doc is HOW the swarm builds — the repeatable machine.

Roles (external swarm now → internal volks as they're wired)

Bootstrapping: the external swarm builds the factory AND wires the internal volks. As PM/orchestrator/analyst/QA/context-manager/KG come online (swarm-plan P1/P2), build tasks progressively hand off to the real volks. The factory is both the tool and the first customer.

Pipeline (TDD-first)

1. Analyze — analyst reads requirements.md + framework; extracts every FR.
2. Design — Mermaid class-diagram CONTRACT with GoF patterns + @traces. 2b. Design review (DeepSeek) — before building, get an independent cross-vendor critique of the contract + scope calls: uv run python scripts/ask_openrouter.py --model deepseek/deepseek-v4-pro (NOT r1) with the recon + proposed plan. Fold in its build-order / scope-cut / risk findings. Cheap second opinion; catches shape errors (e.g. "LSP is stateful — wrong fit for one-shot execute") before code.
3. Test-plan (RED) — one test per FR, tests authored/scaffolded BEFORE code.
4. Skeleton — gen-skeleton (NEW) emits typed, traced stubs (NotImplementedError). 4b. PUSH master BEFORE spawning worktrees — Agent(isolation=worktree) branches off origin/master, NOT local HEAD. Any unpushed commit's EDITS to existing files are invisible to the builder (it silently works the pre-edit version). So: land + push the dependency commits first, THEN delegate edits; delegate NEW-file creation any time. Also: don't run a full gate while a worktree builder is doing uv run — the shared editable-install .pth flips between worktrees and contaminates the run (phantom ImportError/failures). See memory/worktree-base-is-origin-master.md.
5. Implement (GREEN) — builder fills bodies until the RED tests pass.
6. QA — run_tests.py (per-worker Neo4j/Redis, no-mock), tiered coverage.
7. Review + gates — check-traces, standards, RTM regen, adversarial review.
8. Improve — critic: uncovered FRs? pattern misuse? trace gaps? tool friction? → feeds the next iteration AND the factory's own backlog (self-improvement).

Design patterns (baked into skeletons + the factory itself)

• Abstract Base — Tool(ABC) with @abstractmethod execute; each tool subclasses.
• Command — execute(args) -> ToolResult is a Command; build steps are Commands.
• Factory — ToolRegistry / AgentFactory construct by key/spec.
• Singleton — ToolRegistry, the process-global Prolog engine, KG driver.
• Strategy — per-stereotype skeleton emitters; per-phase workflow behavior; pluggable tool backends (e.g. LSP transport).
• State — tool/session lifecycle; WorkflowState machine over the 8 phases.

Pattern-first determinism (the core bet)

Investing in the RIGHT patterns means the GENERATOR writes ~half the code deterministically — not the LLM — so we save time and avoid mistakes. For each recognized pattern gen-skeleton emits the scaffolding FULLY IMPLEMENTED and leaves only domain "leaves" marked # IMPLEMENT::

• Command (execute): arg parse/validate (from the Args dataclass), try/except → ToolResult wrapping, a config-gated tracer span — generated. Leaf = core op.
• Strategy: the Protocol + selection/injection wiring — generated. Leaf = each concrete strategy's core step.
• Factory + Singleton: registry registration + accessor — generated.
• Composition/DI __init__: wiring of injected components — generated. Skeletons come out ~50% real code, not empty stubs. Generator is trusted for boilerplate; the LLM writes only what it must.

Composition over inheritance

Tool is a thin Protocol (interface); BaseTool COMPOSES behavior via injected components (_executor, _validator, _tracer, _registry) — no deep hierarchy. gen-skeleton emits composition wiring + constructor DI, never inheritance chains past ONE ABC/Protocol boundary. Prefer HAS-A (delegate to a Strategy) over IS-A.

Configurable debugging & tracing (two distinct axes)

• Requirement tracing — @traces(spec,story,reqs) (static, for RTM/KG).
• Runtime tracing/debug — an injected Tracer bound to a TraceConfig (Singleton, env/config-driven: log level, spans on/off, sink). Generated code emits self._tracer.span(...)/logger gated by config — NEVER hard-coded prints. Closes SPEC-100's structured-tracing gap; toggleable per deploy/test.

Ground every design in the real codebase (AST, never guess)

Analyst/wirer MUST run symbols, refs, who-imports, call-graph, find-cycles, dead-params BEFORE designing/wiring: find components to COMPOSE/reuse (composition!), detect twins to consolidate (not duplicate), confirm the wiring seam, prove no cycles/dead params. gen-skeleton re-parses its own output (ast.parse) + runs check-traces to self-verify.

Tooling — existing (reuse) vs NEW (build)

Existing AST toolkit (scripts/serialize_codebase_ast.py): gen-volk, gen-protocol, gen-tests, interface, gen-dto/enum/serde/facade, diagram, add-trace, check-traces, refs, rename, standards, pattern.

NEW / augment:

• gen-skeleton (linchpin) — Mermaid classDiagram → typed, @traces'd Python skeletons. Uses Strategy (ToolEmitter / DataclassEmitter / ProtocolEmitter / EnumEmitter) + a Factory to select by <<stereotype>>. Emits a companion trace-map JSON. Convention below.
• gen-tool — spec+reqs → Tool subclass + registry registration + test scaffold (the no-diagram fast path; mirrors gen-volk).
• FR-coverage checker — requirements.md FRs ↔ skeleton methods ↔ tests (TDD gate).
• Mermaid-contract linter — validate a design diagram (reuse _validate_mermaid).
• trace-map → KG ingester — register skeleton artifacts + REQ→Artifact→Test edges.

Mermaid → skeleton convention (what gen-skeleton consumes; what analyst emits)

• <<Tool>>|<<dataclass>>|<<Protocol>>|<<enum>> → base class / decorator (Factory-selected emitter).
• %% traces spec= story= reqs= inside a class block → @traces(...) on the class (methods inherit unless a %% <method> traces reqs= line overrides).
• +/- → public / _-private. +m(p: T) Ret → typed method; +a: T → typed attribute (ctor field or dataclass field).
• A ..|> B → A(B) (extends/implements). Emit absolute imports (infer known bases), Google docstring stub, body raise NotImplementedError("<Class>.<m>: <spec> not yet implemented").

Skills / hooks / utils to add

• Skill .claude/skills/build-factory/ — invoke the whole pipeline on a target.
• Hook PostToolUse (src edits) → check-traces + standards (block trace-lies at write time — kills the audit's #1 systemic defect).
• Hook pre-merge → RTM regen (scoreboard never drifts).
• Util contract-linter + FR-coverage checker wired into the QA/gate phase.

Knowledge graph (augment minimally — schema mostly suffices)

Canonical labels already present: Project, Intent, PipelineRun, Decision, Artifact (+ merge keys via get_canonical_merge_keys). The factory:

• Design diagram, skeleton, impl module, test module → Artifact nodes.
• Rulings (D12, 012/023, A4, patterns chosen) → Decision nodes.
• Each build → PipelineRun; link REQ →SATISFIED_BY→ Artifact →VERIFIED_BY→ Test.
• Wire ContextInjector (009) so payload["task_context"] is CONSUMED (today produced-only) → every agent is auto-fed its REQ/context slice.
• Wire ContextFileManager (023) as the single goal/context store; migrate PM's raw context.json["goals"] I/O onto it (012-vs-023 ruling: 023 wins). Net new schema: an Artifact.kind ∈ {contract, skeleton, impl, test} convention + the REQ↔Artifact↔Test edges. No new labels required.

Self-improving loop

The workflow is versioned. Each run's Improve/critic phase emits concrete proposals (gen-skeleton gaps, missing patterns, agent-brief fixes, KG edges). Those become the factory's own backlog → applied → next version is faster/more deterministic. v0.1 = agent-translates diagram→skeleton; v0.2 = gen-skeleton deterministic; v0.3 = FR-coverage + KG ingestion gates; etc. The workflow works at every version and strictly improves.

Immediate sequence (queued with briefs)

1. gen-skeleton (builder, TDD, worktree) — the linchpin. (dispatched)
2. analyst agent (Fable) + factory workflow v0.1 (Design+Critique). (this turn)
3. Wire context — ContextFileManager (023) + ContextInjector (009) consumer (wirer).
4. KG — Artifact.kind + REQ↔Artifact↔Test edges + trace-map ingester (builder).
5. Hooks/skill/utils — trace/standards PostToolUse hook, FR-coverage checker, build-factory skill.
6. P0 safety fixes (swarm-plan) run in PARALLEL via direct builders — highest impact, don't wait on the factory.
7. First real target through the full factory: tool-subset (SPEC-072 → 065 → 063 → 069 → 064).

Related

• Plans
• Orchestrata Ultimate — project index
• Workflow
• Tasks