| name | run-factory |
| description | Execute a deliverable factory end-to-end on one prospect signal, or a batch of them — intake, digest, parallel cited research lanes, weakness hunt, synthesis, adversarial citation audit, then fan out the winning artifacts (dashboard, bid, deck, demo, copy). Use when the user pastes a prospect signal (text, email, call note), says "run the factory", "new prospect", "bid package for X", "full pipeline on this lead", "portfolio run" or "run these N leads", "resume the run", or names a registered factory to execute. This is the flagship orchestration harness of signal-forge. |
Run-factory — the execution harness
This skill is a stage machine, not a narrative. It runs one factory over one signal (or a queue of signals) as a sequence of stages, each with a typed input, a typed output on disk, and a blocking predicate that must evaluate true before the next stage starts. The orchestrator holds little in context; every dossier and artifact lives on disk. A fresh session can resume any run from its ledger. This is what lets the factory run at scale for many clients at once.
Default factory: the bid-package seed at ../forge/references/factory-bid-package-v0.3.md. If the use case has its own factory in FACTORY/factories/, execute that one. If neither fits, invoke the forge skill first, then return here.
Binding law (restated because it is load-bearing here): evidence is sourced-or-flagged and audited before shipment (../forge/references/evidence-rules.md); flow is one-directional research→SYNTHESIS→artifact; refined input regenerates artifacts and never hand-patches them; client-facing language is plain; every offer is a tells↔scope↔price bijection (../forge/references/meta-meta-map.md). Design law for every artifact: ../forge/references/design-rigor.md. A stage that would violate one of these does not run — it blocks and escalates.
The loop every stage runs
Frame (state the stage's inputs + blocking predicate) → Do (execute, orchestrator or spawned agent) → Review (check the output against this stage's acceptance checklist) → Capture (write the output to its path, tick the RUN.md ledger, mint atoms where the stage produced reusable knowledge into FACTORY/atoms.md). No stage is "done" on vibes; done means its predicate is checked and its ledger line is ticked.
State: typed slots the harness carries
Input slots (filled at Stage 0 from the signal; UNKNOWN is legal, never invented) and derived slots (pipeline products, in order) are defined by the factory — see ../forge/references/factory-schema.md §2–3. The harness additionally tracks per-run run-state: SLUG (yyyy-mm-slug), STAGE (current), BLOCKERS (open predicate failures), LANES (spawned/returned/failed), AUDIT_STATUS (pending/passed with adjustments applied). Run-state lives in prospects/<slug>/RUN.md, never only in context.
The stage machine
Each stage's inputs, outputs, executor, and blocking predicate are specified in full in references/orchestration-protocol.md (the executable spec). Summary:
| # | Stage | Output (on disk) | Executor | Blocking predicate to advance |
|---|
| 0 | Intake | 00-intake-digest.md (slots + ## atoms consulted) | orchestrator | Signal quoted verbatim; every slot assigned or UNKNOWN; every AMBIGUITY listed with readings; FACTORY/INDEX.md queried by VERTICAL + use-case/stage tags and an ## atoms consulted block written to the digest (the block MUST exist; it is empty only when INDEX is empty or has no matching atoms) |
| 1 | Digest | 00-intake-digest.md (+5 angles, questions) | orchestrator | 5 angles written; research questions derived from them |
| 2 | Research + hunt | 01-research/<lane>.md, tells-dossier.md | parallel subagents | Every lane returned a dossier + ≤600-word summary, cited+dated; hunt returned ≥2 live wedges or explicit none |
| 3 | Synthesis | 01-research/SYNTHESIS.md, UNKNOWNS.md, NEEDS.md | orchestrator | Thesis + numbers table (each entry source-tagged/dated) + gates + cost floor + 3 pricing shapes above floor; unknowns triaged |
| 3b | Citation audit | 01-research/CITATIONS.md | fresh auditor | Every load-bearing claim has a verdict; all ADJUSTED/UNVERIFIED corrections regenerated into SYNTHESIS |
| 4 | Design DNA | design/tokens.css, design/palette.md | design-dna skill | Tokens emitted; every FG/BG pair passes WCAG AA (or CETI fallback logged) |
| 5 | Artifact fan-out | 02-dashboard/ … 07-copy/ | parallel artifact skills | Each artifact passes its acceptance checklist (references/orchestration-protocol.md) + design-rigor QA ladder |
| 6 | DONE + learning | updated FACTORY/atoms.md | orchestrator | Factory DONE predicate true; ≥1 atom minted; report delivered |
The one rule that makes it a machine: every blocking predicate is checked, not assumed. Read the output file, evaluate the predicate against it, tick RUN.md. If it fails, the stage stays open — you retry, escalate, or block. You never advance on the belief that a stage "probably passed."
Parallelism (what fans out, what is strictly sequential)
Stages 0→1→3→3b→4 are sequential — each consumes the prior's output. Stage 2 fans out (one subagent per research lane + the hunt sweep, all in a single message). Stage 5 fans out (artifacts are independent projections of SYNTHESIS, so they build concurrently). The dependency and the reason for each edge are in references/orchestration-protocol.md §parallelism. Do not parallelize across a sequential edge; do not serialize a fan-out.
Refusal conditions (the machine stops rather than shipping bad work)
- Refuse Stage-5 artifact fan-out until Stage-3b has passed and all ADJUSTED/UNVERIFIED corrections are regenerated into SYNTHESIS. No artifact is built on unaudited numbers.
- Refuse to advance any stage whose blocking predicate is unchecked or failing. Log the blocker in RUN.md.
- Refuse to hand-patch a shipped artifact after a slot fills or an ambiguity resolves — regenerate from the updated SYNTHESIS instead.
- Refuse to let a subagent synthesize across lanes, or to let a lane researcher also serve as the Stage-3b auditor (researcher and auditor are never the same agent).
- Refuse to invent any client-facing fact. Unknowns go to the ledger and up the auto-triage ladder before they reach a human.
Resume protocol (statelessness across sessions)
Any session, with no prior context, can pick up a run:
- Read
prospects/<slug>/RUN.md — it names the current STAGE, open BLOCKERS, and per-lane status.
- Re-verify the last-ticked stage's blocking predicate against its output file — do not trust the tick; confirm the file satisfies the predicate (a crashed session may have ticked before writing). If it fails, reopen that stage.
- Continue from the first unsatisfied predicate. Never restart completed stages; never skip an unchecked one.
The RUN.md format is specified in references/orchestration-protocol.md §ledger.
Portfolio mode (many signals at once)
When the user pastes several signals or says "portfolio run / run these N leads": each signal gets its own isolated prospects/<slug>/ run and its own RUN.md; a top-level PORTFOLIO.md tracks every run's stage, blocking item, and next action. Client data is strictly per-run; only vertical priors, template caches, and house tokens are shared. Research-heavy stages stagger to respect concurrency ceilings; artifact fan-out saturates. Full batch protocol, queue format, concurrency ceilings, and cross-run learning flush: references/scale-playbook.md.
Refinement after shipment
When the user supplies new information (a slot fills, an ambiguity resolves): update Stage 0, regenerate downstream from the updated SYNTHESIS, re-run Stage-3b on any changed load-bearing claim — never hand-patch. Log the refinement in the changelog block inside 00-intake-digest.md and route qualified feedback through mint-atoms (which traces each correction to the factory line that allowed it — the feedback-to-line hook).
DONE predicate
A run is DONE when the factory's DONE predicate holds (factory-schema.md §7): all contracted files exist · gates identified · citations independently audited and corrections applied · three pricing shapes priced above a computed floor with contractually defined billable units · sign-here bijection holds across bid/deck/dashboard · unknowns triaged and residual questions listed for the human · the ## atoms consulted block written at Stage-0 intake is present · ≥1 atom minted. RUN.md's every stage line is ticked. Then report: what shipped, the live wedges, open questions for the human, atoms minted.
References
references/orchestration-protocol.md — the stage machine as executable spec: full stage table (inputs · outputs · predicate · executor), parallelism map with rationale, context-budget rules, failure/retry policy, and the RUN.md ledger format.references/subagent-prompts.md — verbatim, typed-slot prompt templates for the research-lane subagent, the Stage-3b adversarial auditor, and the artifact-builder handoff packets.references/scale-playbook.md — portfolio mode: queue file, per-run isolation, shared-asset policy, concurrency ceilings, PORTFOLIO.md ledger, cross-run learning flush, and per-run cost accounting.- Shared law:
../forge/references/evidence-rules.md · meta-meta-map.md · design-rigor.md · factory-schema.md · factory-bid-package-v0.3.md.
