|
1 | | -# Orchestration Domains |
2 | | - |
3 | | -Productized workflow playbooks for recurring heavy-task domains. Each playbook |
4 | | -composes the existing primitives — profiles, review lifecycle, actionable |
5 | | -checkpoints, bounded repair, and the pause-first replan protocol — into a |
6 | | -repeatable graph shape. Resolve every role below as a capability slot per Role |
7 | | -Resolution: prefer a configured agent whose contract matches (an explore-style |
8 | | -scout, a reasoner-style logic prober, a review-style verdict gate, a |
9 | | -verify-style test runner), fall back to `explore`, `build`, or `general`. |
10 | | - |
11 | | -Every playbook is a mix of the two accuracy axes from the Tiered Orchestration |
12 | | -Doctrine — **breadth** (concurrent independent slices, standard tier) and |
13 | | -**depth** (verdict-gated iteration, advanced-tier judge) — at a different |
14 | | -ratio. Each heading names its ratio. Place decomposition, gate, verification, |
15 | | -and arbitration nodes on the advanced tier (`required: true` or a |
16 | | -`review`/`review-*` worker); leave the fan-out volume on the standard tier. |
17 | | - |
18 | | -## The Simulated Audit Loop |
19 | | - |
20 | | -Iteration in a DAG is NOT a cyclic edge and NOT a harness loop. It is a |
21 | | -verdict-driven replan wave — the depth axis in its pure form: |
22 | | - |
23 | | -1. An audit node declares `output_schema` with a normalized `verdict` and |
24 | | - `report_to_parent: true`. |
25 | | -2. On `REJECT` or `REVISE`, the wake delivers findings to the parent. Per the |
26 | | - Verdict Disposal Contract the parent MUST act in that turn: it issues |
27 | | - `control(pause)`, then `control(replan)` appending a correction node and a |
28 | | - NEW audit node under NEW ids (terminal nodes are immutable), wires |
29 | | - `depends_on` forward, then `control(resume)`. If the audit node was the |
30 | | - terminal leaf, `extend` a fresh audit wave instead. |
31 | | -3. Repeat until the audit returns `ACCEPT`. The loop is bounded by |
32 | | - `max_node_replan_attempts` and `max_total_nodes` — on ceiling breach stop |
33 | | - with `BLOCKED` and report the residual findings instead of retrying the |
34 | | - identical plan. |
35 | | - |
36 | | -Every playbook below that says "audit loop" means exactly this mechanism. |
37 | | - |
38 | | -## Playbook: Deep Review |
39 | | - |
40 | | -Ratio: breadth then depth. Multi-role adversarial review of whether a code |
41 | | -structure or design is sound, scaled by the Depth Ladder. |
42 | | - |
43 | | -- **Breadth wave** — fan out 3+ reviewers with genuinely conflicting mandates: |
44 | | - a prosecutor (argues the structure is wrong — coupling, hidden invariants, |
45 | | - failure modes), a defender (argues the current shape is justified — |
46 | | - constraints, history, cost of change), and dimension specialists |
47 | | - (architecture, correctness, testability) as scope demands. Every reviewer |
48 | | - MUST cite file:line evidence and list what it could not confirm as |
49 | | - `unverified_claims`. |
50 | | -- **Verification wave (mandatory for module scope and larger)** — one or more |
51 | | - verify-style nodes check the disputed and `unverified_claims` items against |
52 | | - the actual code before any verdict. This is what separates a review from a |
53 | | - poll of opinions; skipping it lets an unproven assertion become a finding. |
54 | | -- **Arbitration (advanced tier)** — fan in to one arbiter that rules |
55 | | - finding-by-finding on the VERIFIED evidence, not merely concatenating |
56 | | - reviews, and emits the actionable checkpoint shape (`verdict`, `findings`, |
57 | | - `required_actions`, `next_action`). |
58 | | -- Pre-implementation structure reviews are `design` phase. Reviewing an actual |
59 | | - change requires the diff-phase hard contract: |
60 | | - `implementation → verification(PASS) → diff review` with fingerprint echo. |
61 | | -- **Depth wave** — on `REVISE`/`REJECT`, drive corrections and concurrent |
62 | | - deep-dives into the confirmed problem areas through the audit loop. The |
63 | | - arbiter's report is the start of this wave, never the end of the task. |
64 | | - |
65 | | -## Playbook: Deep Speculation |
66 | | - |
67 | | -Ratio: breadth of parallel probes, then depth through the revision loop. |
68 | | -Prophesy a whole design document — stress-test it end to end and emit an |
69 | | -automated verdict with zero human gates in the middle. |
70 | | - |
71 | | -- Internalized grill method, run as graph roles instead of user Q&A: parallel |
72 | | - nodes over the same document — a logic simulator (walk the described system, |
73 | | - surface contradictions and boundary gaps), an adversarial interrogator |
74 | | - (produce the hardest material questions: hidden assumptions, falsifiers, |
75 | | - failure modes, evidence quality), and an alternatives prober (steelman one |
76 | | - competing shape). |
77 | | -- A responder node answers the interrogation strictly from the document plus |
78 | | - codebase evidence, marking each question ANSWERED / GAP / CONTRADICTION. |
79 | | -- An arbiter synthesizes everything into a structured prophecy: verdict, |
80 | | - ranked risks, unresolved gaps, and a concrete revision list — then the audit |
81 | | - loop applies revisions and re-speculates until ACCEPT. |
82 | | -- Fully automated: no admission QA rounds with the user mid-flight. Reserve |
83 | | - interactive `GRILL` admission for before the workflow starts. |
84 | | - |
85 | | -## Playbook: Large Engineering |
86 | | - |
87 | | -Ratio: iterated breadth and depth — parallel packages, each gated, plus a |
88 | | -final audited review. Turn an execution document (todo list, work ledger, or |
89 | | -spec) into audited, parallel-safe delivery. |
90 | | - |
91 | | -1. **Deep analysis** — scout nodes map the affected surface; an analyst node |
92 | | - decomposes the document into work packages with explicit dependency edges |
93 | | - and disjoint write sets (the tickets: each package states its blocking |
94 | | - edges, not a bare list). |
95 | | -2. **Orchestrate** — compile the packages into a graph: independent packages |
96 | | - fan out in parallel, dependent ones serialize, propose-then-assemble where |
97 | | - write sets may overlap. |
98 | | -3. **Audit the plan** — a plan-audit node checks the decomposition itself: |
99 | | - missing edges, false parallelism, unstated assumptions, acceptance criteria |
100 | | - per package. `REJECT` re-orchestrates via the audit loop until the plan |
101 | | - passes. |
102 | | -4. **Execute** — run the audited graph with the develop-profile phases each |
103 | | - package still needs; verification consumes each implementation before any |
104 | | - diff review. |
105 | | -5. **Final adversarial review** — the Deep Review playbook over the assembled |
106 | | - result, with its own audit loop. |
107 | | -6. **Deliverable** — a final assembler emits the outcome report: shipped |
108 | | - packages, evidence, residual risks. |
109 | | - |
110 | | -## Playbook: Solution Bake-off |
111 | | - |
112 | | -Ratio: pure breadth — N samples of the same goal, one advanced-tier judge. |
113 | | -N competing approaches implemented or prototyped in parallel against the same |
114 | | -acceptance criteria; a verify-style node exercises each candidate; one arbiter |
115 | | -picks the winner on evidence and records why the losers lost. |
116 | | - |
117 | | -## Playbook: Root-Cause Diagnosis |
118 | | - |
119 | | -Ratio: breadth of hypotheses first, then depth on the leading survivor. |
120 | | -Fan out one node per plausible hypothesis, each tasked to falsify its own |
121 | | -hypothesis with concrete evidence; an arbiter eliminates, ranks survivors, and |
122 | | -either declares the root cause or replans a deeper probe wave on the leading |
123 | | -survivor. |
124 | | - |
125 | | -## Playbook: Audit Sweeps |
126 | | - |
127 | | -Ratio: pure breadth per sweep cell, with the audit loop supplying depth on |
128 | | -hits. The same fan-out/arbiter/audit-loop shape covers recurring sweep |
129 | | -domains: security surface audit (per-surface reviewers: input handling, |
130 | | -authz, secrets, dependencies), regression matrix fan-out (one verify node per |
131 | | -axis cell), and docs-code drift audit (per-document checkers comparing claims |
132 | | -against the code, with fix waves through the audit loop). |
133 | | - |
134 | | -## Choosing and Combining |
135 | | - |
136 | | -Playbooks compose inside one live DAG: Large Engineering embeds Deep Review at |
137 | | -its gate; Deep Speculation can front-load any of them. Selection still obeys |
138 | | -Execution Mode Selection and the Depth Ladder — its wave count meets the |
139 | | -ladder's minimum for the target size, and explicit user constraints always |
140 | | -override the playbook shape. |
| 1 | +# Cross-domain Workflow Composition |
| 2 | + |
| 3 | +The resident Orchestration Router and the live workflow library own route and |
| 4 | +`full`/`lite` selection. This guide resolves only requests where several domain |
| 5 | +references appear relevant. Keep one primary reference and one workflow. |
| 6 | + |
| 7 | +## Pick the backbone by the final artifact |
| 8 | + |
| 9 | +- The requested deliverable is a product decision: keep product planning as |
| 10 | + the backbone; technical feasibility is evidence, not a second design route. |
| 11 | +- The requested deliverable is an implementation-ready design: keep technical |
| 12 | + design as the backbone; product context supplies constraints. |
| 13 | +- The requested deliverable is changed code: keep project development as the |
| 14 | + backbone unless an unknown defect first requires causal diagnosis. |
| 15 | +- The requested deliverable is a defect repair: keep debug and repair as the |
| 16 | + backbone; the repair, regression proof, and review stay in that graph. |
| 17 | +- The requested deliverable is a verdict: use code review for a pinned |
| 18 | + implementation change, security or performance audit for those evidence |
| 19 | + domains, and technical design when the object is a proposed system or |
| 20 | + migration. |
| 21 | + |
| 22 | +Security, performance, and review are secondary assurance when the requested |
| 23 | +artifact remains implementation or repair. They become primary only when the |
| 24 | +requested artifact is their report or verdict. A secondary concern is never a |
| 25 | +second workflow for the same objective. |
| 26 | + |
| 27 | +## Add the smallest assurance slice |
| 28 | + |
| 29 | +Read the primary reference first. Read a secondary reference only to identify |
| 30 | +the minimum evidence lane or gate that changes acceptance. Put those blocks in |
| 31 | +one task-local YAML and retarget every copied instruction to the same scope and |
| 32 | +acceptance criteria. Do not append a complete second reference. |
| 33 | + |
| 34 | +- A security-sensitive feature keeps the development backbone and adds scoped |
| 35 | + threat, authorization, secret, or supply-chain checks before final review. |
| 36 | +- A security defect keeps the debug backbone and adds exploitability and |
| 37 | + boundary verification around the causal repair. |
| 38 | +- A performance repair keeps the debug or development backbone and adds a |
| 39 | + repeatable baseline plus before/after measurement. |
| 40 | +- A review of a dependency or release change keeps the review backbone and adds |
| 41 | + only the relevant upstream provenance and reachability evidence. |
| 42 | + |
| 43 | +Reuse one exploration result across consumers. Keep one verification fan-in |
| 44 | +for the final implementation fingerprint and one final review or synthesis; |
| 45 | +duplicate explore, verify, and verdict blocks are evidence drift, not extra |
| 46 | +assurance. Unordered writers still share one workspace, so give them disjoint |
| 47 | +write sets or serialize them with real dependencies. |
| 48 | + |
| 49 | +## Preserve lifecycle contracts |
| 50 | + |
| 51 | +Composition does not redefine block fields, verdicts, repair, or recovery. |
| 52 | +Load `guide(topic="blocks")` for YAML shapes and block semantics, and |
| 53 | +`guide(topic="policy")` for admission, verdict disposal, pause-first replan, |
| 54 | +and bounded repair. A non-ACCEPT verdict remains actionable in the same wake |
| 55 | +turn; do not invent a domain-specific retry loop. |
0 commit comments