A portable architecture for specifying a product once, then driving implementation with an owner-chosen orchestrator, authorized executors, and deterministic tickets that stay honest as the code changes.
This repository is not an app. It is the contract between:
- a comprehensive Product Requirements Document
- the factory that will build from it (TUI, models, skills, compute, tracker)
- the Linear / Jira / GitHub / markdown tickets a coding agent actually receives
It is designed so Claude Code, Codex, Grok Build, Cursor, Pi, or a human can all play orchestrator or implementer without the PRD becoming a vendor prompt dump.
Status. v3.4 is on main. The 14-section PRD audit is frozen. Factory/ticket contract is the Claude+Codex+Grok consensus pass.
The PRD is the product. The factory is a user choice. A ticket is one frozen, provable outcome.
- Handing the full PRD to an implementation model is how scope explodes.
- Naming a TUI without proving it can produce evidence is how factories fake rigor.
- Writing forty identical max-prescription tickets is ceremony, not control.
- Never replanning the backlog is waterfall with extra YAML.
- Rewriting in-progress tickets underfoot is chaos.
The list of tickets may change. The ticket currently being executed may not, except by cancel-and-replace.
The PRD governs behavior. The frozen ticket governs execution. The graph only retrieves.
- Behavior authority: decisions → PRD → versioned contracts. A ticket may narrow these, never override them.
- Execution authority: frozen ticket + revision-pinned links/addenda. Any TUI continues the same issue.
closure.actor(owner or authorized-automation) is the only closer. - Retrieval: TUI-neutral knowledge graph. Not a second backlog. Not Claude-only or Codex-only memory.
- HARNESS vs executor. HARNESS is the cockpit product.
execution.executoris the worker runtime on one ticket.HARNESS-001…006are factory enablement ids. - Yellow-zone depth goes in versioned addenda. Red zone: split the ticket.
AGENTS.mdandCLAUDE.mdstay short and in lockstep. NoTODO.md/PLAN.md/NOTES.md.
Approved PRD
│
▼
Owner picks ORCHESTRATOR ← driving TUI + model (user-defined)
│
▼
Refresh RESOURCE CATALOG ← living SOTA universe (not permission)
│
▼
Owner DOWNSELECT ← FACTORY.md, blast-radius limit
│
▼
Harness-prep tickets ← prove the factory, including calibration
│
▼
Orchestrator authors ticket pack ← intensity + waves + exact prompts
│
▼
Human review + semantic pack gate
│
▼
Sync to Linear / Jira / GitHub / markdown
│
▼
Implementer runs ONE frozen ticket
│
▼
Independent verifier accepts evidence
│
▼
Orchestrator REPLANS the backlog ← living tickets
| You | Use this |
|---|---|
| Product / tech lead writing a serious PRD | PRD-TEMPLATE.md |
| Owner choosing “what drives development” | FACTORY.example.md + process §3 |
| Orchestrator TUI decomposing work | TICKET-DEVELOPMENT-PROCESS.md |
| Implementer TUI executing one issue | LINEAR-TICKET-TEMPLATE.md + HARNESS-PROFILES.md |
| Someone closing a ticket | §14 results-proven analysis + independent verifier |
| CI / another agent checking the pack | scripts/validate_*.py |
If you want a weekend clone of a toy app, this is too much. If you want multiple TUIs to build the same product without drifting, this is the point.
This repository is the SOFTWARE contract. That is the impetus for how the PRD is authored: comprehensive enough to be the product, decomposed enough that any TUI can execute one frozen ticket, portable enough that the driving TUI can change.
It is one of three layers. They are separate products. This repo is not the other two.
| Layer | Owns | Produces | This repo? |
|---|---|---|---|
| PRODUCT | Desirability, problem evidence, intended value, go/no-go | Versioned product brief | Boundary only: PRODUCT-BRIEF-TEMPLATE.md |
| SOFTWARE | Behavior, architecture, SDD/TDD, acceptance, decomposition | Approved PRD + immutable ticket pack | Yes. This repository. |
| HARNESS | Cockpit / control plane: which TUI drives the others | Capability routing and evidence transport | No. Consumes FACTORY.md + tickets |
| FACTORY | Owner-approved join of SOFTWARE and executors | Versioned program manifest | Record only: FACTORY.md — not a fourth company product |
Invariant: Product decides why and what is worth building. Software specifies exactly what must be built and proven. The executor (ticket field) is how an authorized runtime executes it. HARNESS (product) is the cockpit that can drive those executors. A frozen ticket is the Software-to-executor execution envelope.
Why the PRD is written this way, given that split:
- PRODUCT must not leak into tickets. Discovery artifacts are not execution units. Building the wrong thing with SDD/TDD is still the wrong thing.
- SOFTWARE must not choose a vendor. If the PRD named Claude vs Codex vs Grok Build, it would stop being a product spec and become a prompt dump. Orchestrator and executor are factory choices, recorded after the PRD is approved.
- HARNESS must not own the spec. If each TUI kept its own notes, TODO lists, and memory, tickets would not be interoperable. The frozen ticket + revision-pinned links + listed addenda govern the execution assignment (behavior authority stays with the PRD and decisions); a TUI-neutral graph is optional retrieval;
AGENTS.md/CLAUDE.mdstay short. - The factory sits between SOFTWARE and HARNESS. Owner picks the orchestrator, downselects resources, resolves capabilities, proves the factory (HARNESS-001…006), then the orchestrator authors tickets. Swap the cockpit later without rewriting the PRD.
Words in this repo mean the layers above, not a company brand. Company products, if any, live in their own repositories.
| File | Layer | Job |
|---|---|---|
PRODUCT-BRIEF-TEMPLATE.md |
PRODUCT → SOFTWARE | Versioned brief: problem, value, go/no-go |
PRD-TEMPLATE.md |
SOFTWARE spec | 14-section architect-audit PRD + appendices B–D |
TICKET-DEVELOPMENT-PROCESS.md |
Factory process | Orchestrator, catalog, prep, intensity, replan |
FACTORY.example.md |
Program record | Copy to FACTORY.md: driving TUI + downselect |
RESOURCE-CATALOG.example.md |
Universe | Dated SOTA capabilities. Not permission. |
HARNESS-PROFILES.md |
Executor runtimes | What Grok Build / Claude / Codex / Cursor / Pi / human can prove |
HARNESS-PREP-TICKET-TEMPLATE.md |
Prep tickets | Factory-enabling work that blocks product tickets |
LINEAR-TICKET-TEMPLATE.md |
Dev tickets | SDD + TDD + execution envelope + results-proven close |
SYNC-MANIFEST.example.md |
Tracker adapter | temp_id ↔ tracker_id + digests; drift = cancel-and-replace |
AGENTS.example.md |
Repo overlay | Short: two-axis authority; graph is retrieval |
CLAUDE.example.md |
Repo overlay | Lockstep with AGENTS.md; no Claude-only notes |
AGENTS.grok-build.example.md |
Repo overlay | Chat + preview user; agent-run QA |
examples/TKT-EXAMPLE.md |
Calibration | Density target for one Grok Build standard ticket |
examples/TKT-LITE-EXAMPLE.md |
Calibration | Intensity=lite contract (no SDD cathedral) |
examples/ticket-pack/ |
Calibration | Full mini-pack the semantic validator must pass |
examples/addenda/TEMPLATE.md |
Yellow-zone depth | Markdown addendum linked from a ticket, embedded on tracker sync |
scripts/validate_prd.py |
Gate 1 | PRD structure (14 IDs, diagrams, FR blocks) |
scripts/validate_ticket.py |
Gate 2–4 | Ticket headings, execution YAML, process doc |
scripts/validate_ticket_pack.py |
Gate 5 | Prep wave, catalog subset, disjoint waves, acyclic graph |
Passing an earlier gate never implies a later one.
| # | Gate | Passes when |
|---|---|---|
| 1 | PRD audit | All 14 section IDs, 3 diagrams, FR/NFR/acceptance/cost/out-of-scope |
| 2 | Decomposition | Every SHALL maps to a vertical ticket; graph is acyclic; no §14 leakage |
| 3 | Factory | Owner chose orchestrator; catalog downselected; HARNESS-001…006 accepted, including calibration |
| 4 | Execution | Each implementation ticket names executor, model, skills, retrieval mode, prompt, verifier; required capabilities resolve in FACTORY.md; unused fields are n/a |
| 5 | Delivery | RED→GREEN evidence, render/interaction/production-build proof for UI, write set honored, verifier accepted, orchestrator replanned backlog |
HTTP 200 is not done. “Tests passed” from the implementer is not close. A skipped check is not run.
| Role | Authority | Must not |
|---|---|---|
| Owner (human) | Chooses orchestrator, approves downselect and tracker writes | Let a model take irreversible calls |
| Orchestrator (one TUI + model) | Decompose, assign, schedule waves, replan backlog | Implement every ticket; edit in-progress work; mark done |
| Implementer | Execute one approved ticket | Close the issue; dump the full PRD into context |
| Verifier | Accept/reject the evidence pack | Be the same model class as the implementer |
| Auditor (optional) | Sample factory drift, cost, security | Secretly become the orchestrator |
The orchestrator is the driving force of development. That is a user-defined option, recorded in FACTORY.md. It is not inferred from whoever coded the first slice.
Keep these IDs. They are the architect-audit contract.
| ID | Section |
|---|---|
§00 |
Front matter (direction, stack, model-diversity roles) |
01-vision |
Problem, personas, anti-persona, metric + baseline |
02-stakeholders |
Role / human / authority |
03-glossary |
Project-specific meanings |
04-user-personas |
Concrete flows and anti-personas |
05-functional-requirements |
Per-FR Gherkin, budgets, security, eval, observability |
06-non-functional-requirements |
Cross-cutting + verifying tests |
07-ui-ux |
Flows and states, or “no UI” |
08-system-architecture |
Stack pins, brownfield map, architecture diagram |
09-data-model |
Schemas, lifecycle, evolution |
10-integration-surface |
Externals + data-flow + integration-surface |
11-operational-concerns |
Deploy, verify commands, rollout/rollback |
12-acceptance-scenarios |
Protected Gherkin + traceability ledger |
13-cost-envelope |
Burn ceiling |
14-out-of-scope |
Explicit anti-requirements |
Appendices (not audit sections): A checklist, B Linear/ticket decomposition, C executor assignment, D orchestrator / prep / living tickets.
The PRD does not choose Claude vs Codex vs Grok Build. That would make the product spec unportable.
Anti-overkill rule. Do not paste the universe into a ticket.
RESOURCE-CATALOG.md what exists in the world (dated, researched)
↓ owner
FACTORY.md downselect what THIS program is allowed to use
↓ orchestrator
one ticket catalog_ids what THIS outcome actually uses
Catalog rows expire after 90 days unverified. Assigning a blocked or non-downselected RES-* id fails the pack validator.
TUIs, models, skills, hooks, memory, compute, network, trackers, and third-party QA tools are catalog classes. Hooks that only exist in Claude Code are not assigned to Codex. Memory graphs are optional; most slices should not depend on one being warm.
Default set; delete only with n/a — reason.
| ID | Outcome |
|---|---|
| HARNESS-001 | Orchestrator recorded |
| HARNESS-002 | Catalog refreshed; downselect owner-approved |
| HARNESS-003 | Named skills/hooks actually load |
| HARNESS-004 | Compute + network proven in the real environment |
| HARNESS-005 | Tracker project or markdown pack path exists |
| HARNESS-006 | Calibration slice through implementer + verifier |
If HARNESS-006 fails, stop. Do not author forty product tickets on a factory that cannot add a note to a list.
Each executable ticket is custom to the software, not a clone of the max template.
Intensity (escalate; do not start at max):
| Band | When | Required |
|---|---|---|
lite |
Docs, copy, obvious bug | Outcome, write set, one proof, DoD |
standard |
Default vertical slice | Full ticket template; unused fields n/a — reason |
strict |
Auth, data, money, secrets, public contract, irreversible migration | Standard + auditor + rollout proof |
Mix the orchestrator must consider, and may omit:
Executor · pinned vendor.model · effort/latency/token budget (n/a if the executor has no knob) · skills in load order · hooks · retrieval mode · exact prompt · tests + evidence actor · wave + disjoint write set · verifier · close qualifications.
Some tickets need less. Some need more (device farm, legal, formal eval) — add a named catalog resource; do not invent a side channel.
Parents are planning containers (executor: none). Never give a parent to an implementer while children are undefined.
Waves, not vibes.
- Shared contract first (schema, routes, tokens, layout, public interfaces).
- A wave is tickets whose write sets do not overlap.
- Two tickets that touch the same file are sequential.
- Parent/sub-issue is containment.
blocked_byis ordering. - The pack README publishes the wave map.
validate_ticket_pack.py fails the pack when two product tickets in the same wave have overlapping write-set globs (src/components/notes/** overlaps src/components/notes/NoteEditor.tsx).
After every accepted close, and on any finding that invalidates an assumption, the orchestrator re-reads the backlog.
| May rewrite | Must not touch without owner |
|---|---|
| Backlog (not started) | In-progress outcome / write set / acceptance |
| Split, drop, re-intensity | Done work (reopen only as a new ticket) |
| Reassign executor when proof failed | PRD scope, secrets, production, new recurring cost |
In-progress freeze: cancel-and-replace, do not edit underfoot. Record: examples/replan/TEMPLATE.md.
Phrase to keep: a non-deterministic list of deterministic tickets.
Generation always happens in markdown. Creating issues is an authorized external write.
| Tracker | Containment | Sequencing |
|---|---|---|
| Linear | parent / sub-issue | blocked by |
| Jira | epic / parent | “is blocked by” |
| GitHub Issues | issue + task list | body links until native blocking exists |
| Markdown pack | directory + README | YAML blocked_by |
Corp-SSH / air-gap programs stay on the markdown pack.
Pick the TUI that can prove the outcome.
| ID | User sees | Assign when |
|---|---|---|
grok-build |
Chat + live preview, no shell | Previewable web slice; agent is the only operator |
claude-code |
Local TUI + checkout | Skills/hooks, local toolchains, repo surgery |
codex |
Codex CLI / IDE | One approved issue, GPT-class implementer |
cursor |
IDE pair | Human accepting diffs interactively |
pi |
Local TUI | Only if downselected and installed |
human |
Judgment | Access-gated, irreversible, legal, hardware |
none |
— | Parent / planning container |
Grok Build specifics that break tickets written for a local developer: never ask the user to run commands; desktop + mobile render proof; production-build smoke vs dev baseline; auth/DB off unless a SHALL names them; no invented imagine_* tools.
- Copy the templates into the product repo (paths preserved).
- Draft and approve the PRD.
python scripts/validate_prd.py --strict docs/prd/app.md - Owner fills
FACTORY.md(orchestrator + downselect). Refresh the catalog first. - Close HARNESS-001…006. Calibration must pass.
- Orchestrator writes
work/ticket-pack/with waves and intensity. python scripts/validate_ticket_pack.py work/ticket-pack --factory FACTORY.md- Human review. Tracker sync only if authorized.
- Implementer gets one issue + linked contracts + the literal
exact_prompt. - Verifier accepts or rejects. Implementer does not close.
- Orchestrator writes a replan record. Backlog updates. Next wave.
# PRD structure (canonical template should PASS; --strict fails placeholders)
python scripts/validate_prd.py PRD-TEMPLATE.md
python scripts/validate_prd.py --strict docs/prd/approved.md
# Ticket shape, executor profiles, process doc, factory record
# (--stage sync|execute|close escalates envelope requirements)
python scripts/validate_ticket.py LINEAR-TICKET-TEMPLATE.md examples/TKT-EXAMPLE.md examples/TKT-LITE-EXAMPLE.md \
--profiles HARNESS-PROFILES.md \
--process TICKET-DEVELOPMENT-PROCESS.md \
--factory FACTORY.example.md \
--agents AGENTS.example.md \
--claude CLAUDE.example.md
# Semantic pack gates (prep wave, catalog subset, capability resolution,
# retrieval mode, disjoint waves, cycles)
python scripts/validate_ticket_pack.py examples/ticket-pack \
--factory examples/ticket-pack/FACTORY.md
python -m unittest discover -s tests -vThe pack validator will not catch a horizontal ticket or a mushy outcome. That remains a human (or orchestrator) review against Appendix B.
Author PRD
Read PRD-TEMPLATE.md and the evidence in <paths>.
Draft or revise the PRD while preserving all section and diagram IDs.
Report blocking decisions instead of inventing facts.
Do not implement product code. Do not write to the issue tracker.
Select orchestrator + factory
Read TICKET-DEVELOPMENT-PROCESS.md and FACTORY.example.md.
Record the owner-chosen orchestrator and downselect in FACTORY.md.
Refresh RESOURCE-CATALOG rows you intend to approve.
Do not author product tickets yet.
Harness prep
Execute the HARNESS-001..006 wave using HARNESS-PREP-TICKET-TEMPLATE.md.
Produce evidence. Run a calibration slice.
Do not implement product FRs until prep.status is accepted.
Author the pack
Read the approved PRD, LINEAR-TICKET-TEMPLATE.md, HARNESS-PROFILES.md, and FACTORY.md.
Write a draft pack under work/ticket-pack with parents, vertical slices, waves,
intensity, execution mix from the downselect, and exact prompts.
Report coverage gaps, cycles, and tickets this orchestrator cannot prove.
Do not implement code. Do not write to Linear/Jira/GitHub.
Implement one ticket
Implement <ID> using only its stated scope, linked contracts, and exact_prompt.
Load named skills first. Honor retrieval_mode (direct-links: pinned links only; shared-graph: cited retrieval); do not paste the PRD.
Do not write TUI-local TODO/PLAN/NOTES or expand AGENTS.md/CLAUDE.md.
Follow SDD and TDD RED → GREEN → REFACTOR.
You are the evidence actor. Do not expand from the PRD. Do not close the issue.
Verify
Verify <ID> as an independent verifier.
Use only the ticket, contracts, diff, and evidence pack.
Accept or reject with the exact failing gate. Do not implement.
Replan
The just-closed ticket is <ID>. Read the remaining backlog against the current repo.
Rewrite backlog tickets that are now wrong. Do not edit in-progress tickets.
Write examples/replan/TEMPLATE.md. Ask the owner before scope/cost/security/tracker writes.
- Product behavior living only in a ticket (that is a PRD amendment)
- Factory permission inferred from “the catalog exists”
- Max-prescription theater on lite work (and a validator that enforces it)
- Treating
capability_tieras verifier independence - Calling the worker TUI "HARNESS" (that word is the cockpit product; the ticket field is
executor) - Marking skipped checks as passed
- Asking a Grok Build user to run terminal commands
- Silent extra files outside the write set
- Replanning by editing the ticket someone is executing
- TUI-local TODO/PLAN/NOTES/recap files, or growing
AGENTS.md/CLAUDE.mdinto a second backlog - Treating Claude-only or Codex-only memory as the shared knowledge graph
v3.3 is the Grok+Codex consensus pass on the v3.2.3 draft. Frozen: 14-section PRD audit. Living: factory/ticket contract.
| Question | Vote |
|---|---|
| Intensity bands | Keep lite / standard / strict. Validator branches by band. |
| Calibration | Two-stage: synthetic plumbing (notes example) then first real product slice before scaling the pack. |
| Orchestrator as implementer | Allowed for calibration and lite with a fresh verifier context. strict requires a separate execution identity. |
| Tracker | Markdown canonical. Linear/Jira/GitHub are adapters + SYNC-MANIFEST. Drift = cancel-and-replace. |
| Ground truth | Two axes. PRD/decisions = behavior. Frozen ticket = execution. Graph = retrieval. |
| Naming | HARNESS = cockpit product. execution.executor = worker. FACTORY = join record, not a fourth product. |
| Close | closure.actor: owner or authorized-automation. |
| Capability resolution | v3.4: tickets' required_capabilities must resolve through owner-approved FACTORY.md capability_resolution to a downselected resource, the assigned executor, and accepted prep evidence. |
| Retrieval | v3.4: explicit retrieval_mode: direct-links \| shared-graph. Graph is optional; direct-links programs never fail for lacking one. |
| Freeze | v3.4: freeze.pins pin PRD, decisions, contracts, factory, executor-profile, addenda revisions + exact-prompt digest — markdown-only programs get the same immutability as tracker-synced ones. |
| Stages | v3.4: validate_ticket.py --stage draft\|sync\|execute\|close; invalid intensity fails instead of defaulting. |
| Product Brief | v3.4: PRD §00 and FACTORY pin source.product_brief; strict validation refuses missing/mutable/non-go briefs. |
v3.4 is the Claude Code adjudication pass on v3.3. Grok Build accepts it: same safety properties, two implementation choices kept (pack validator stays unconditional; catalog provides: is advertisement, capability_resolution is permission). Templates are contract truth; this README is narrative truth.
v3 PRD audit IDs come from turbobeest/dark-software-factories. v3.1 added Linear SDD/TDD decomposition. v3.2 added executor assignment, Grok Build as a first-class runtime, orchestrator/factory process, and the semantic pack validator. v3.3 was the Grok+Codex consensus (two-axis authority, executor vs HARNESS). v3.4 is the Claude Code adjudication: machine-verifiable capability resolution, explicit retrieval mode, complete freeze pins, Product Brief wiring, and stage-aware validation.
Do not overwrite PRD-TEMPLATE.md blindly from upstream. Preserve 01-vision … 14-out-of-scope and the three diagram ids.