b2c-app-builder 0.221.39

package/knowledge/orchestration/compound-engineering-routing.md

@@ -0,0 +1,101 @@
+# Compound Engineering Routing
+
+Use this when choosing which Compound Engineering (CE) skill to invoke for a build stage: app implementation, backend/frontend edits, generated builder handoff, or a request to "build/refactor/fix the app" from a launch package. Production-readiness substance and mobile quality bars live in [`engineering-orchestration.md`](../engineering/engineering-orchestration.md); this file routes the CE loop itself.
+
+Compound Engineering is the default engineering operating system for this skill. Do not use a generic implementation checklist for non-trivial app work when CE skills are available.
+
+## Required Loop
+
+1. **Freshness**: run `ce-update` in Claude Code when available, or record the local CE skill inventory and latest-release check. The current upstream release source is `https://github.com/EveryInc/compound-engineering-plugin/releases`.
+2. **Product/requirements**: run `ce-brainstorm` when product shape, scope, user behavior, onboarding, paywall, or activation still has multiple defensible directions. If skipped, record why the source docs are already decisive.
+3. **Plan**: run `ce-plan` before non-trivial implementation. `engineering/ENGINEERING_PLAN.md` should identify `ce-plan` or an equivalent CE planning route as its source.
+4. **Work**: run `ce-work` for bounded implementation. Use `ce-worktree` when lanes need isolation, the main checkout is dirty, or parallel implementation would collide. Before `ce-worktree` on an Expo or React Native app, set `worktree.symlinkDirectories` to `["node_modules"]` in `settings.json`, so each worktree stops reinstalling `node_modules`.
+5. **Review**: run `ce-code-review` before treating non-trivial code changes as ready.
+6. **Test**: run `ce-test-browser` for web surfaces and `ce-test-xcode` for iOS/macOS surfaces when applicable. Use MobAI for serialized mobile-device E2E when available.
+7. **Proof**: run `ce-proof` or `ce-demo-reel` when the founder/reviewer needs visual or behavioral proof.
+
+Tiny doc edits, typo fixes, one-file copy changes, and repo-maintenance-only validator patches do not need the full CE loop. Record `route: not_needed` with a short reason when skipping CE for those cases.
+
+## State Contract
+
+Record the route in the Compound Engineering Routing section of
+`operations/ORCHESTRATION.md`. Business state holds the orchestration lane status
+and evidence pointer; it does not copy this route record:
+
+```yaml
+compound_engineering:
+  availability: "unknown" # available | unavailable | not_needed | unknown
+  route: "not_evaluated" # ce_full_pipeline | ce_plan_work | ce_fallback | not_needed | not_evaluated
+  latest_check:
+    status: "not_checked" # checked | ce_update_run | source_registry_refresh_run | unavailable_with_reason | not_needed | not_checked
+    checked_at: ""
+    installed_version: ""
+    latest_version: ""
+    source: ""
+  skills_considered: []
+  brainstorm_status: "not_evaluated" # used | skipped_with_reason | fallback_equivalent | blocked | not_needed | not_evaluated
+  plan_status: "not_evaluated"
+  work_status: "not_evaluated"
+  worktree_status: "not_evaluated"
+  review_status: "not_evaluated"
+  test_status: "not_evaluated"
+  proof_status: "not_evaluated"
+  fallback_reason: ""
+```
+
+For production-readiness claims, the route must show either:
+
+- CE is available and planning, work, review, testing, and proof are used or intentionally not needed with a reason.
+- CE is unavailable and the Standalone Engineering Loop (`engineering-orchestration.md` §1b) is recorded in `operations/ORCHESTRATION.md` and `engineering/ENGINEERING_PLAN.md` — plan, bounded slices, adversarial review, test, and proof with the same evidence bar. `check:compound-engineering` errors when CE is unavailable and `engineering/ENGINEERING_PLAN.md` does not record the loop.
+
+## Artifact Requirements
+
+`operations/ORCHESTRATION.md` must include:
+
+- Compound Engineering Routing
+- CE freshness check
+- CE skill inventory or unavailable route
+- ce-brainstorm decision
+- ce-plan source
+- ce-work or ce-worktree route
+- ce-code-review route
+- ce-test-browser, ce-test-xcode, MobAI, or equivalent E2E proof route
+- ce-proof or ce-demo-reel route
+- fallback reason if unavailable
+
+`engineering/ENGINEERING_PLAN.md` must include:
+
+- source docs and whether `ce-brainstorm` was used or intentionally skipped
+- `ce-plan` or equivalent planning source
+- `ce-work` execution route and `ce-worktree` decision
+- review, test, and proof gates before readiness
+
+`engineering/PRODUCTION_READINESS.md` must include:
+
+- implementation command/proof
+- CE review result or equivalent fallback
+- browser/device/build proof from CE or approved equivalent
+- remaining blockers and founder-only gates
+
+## Freshness
+
+The skill's source-freshness registry tracks the Compound Engineering plugin release page. During skill maintenance, run:
+
+```bash
+npm run check:source-freshness
+npm run refresh:source-freshness
+```
+
+During an app engineering run, prefer the runtime tool:
+
+```text
+ce-update
+```
+
+If `ce-update` is unavailable because the runtime is not Claude Code, record the local CE skills present and, when `gh` is available, check:
+
+```bash
+gh release list --repo EveryInc/compound-engineering-plugin --limit 5 --json tagName,publishedAt,isLatest
+```
+
+Do not block engineering solely because the latest-release check is unavailable. Instead, record `latest_check.status: unavailable_with_reason`, keep the route visible, and proceed with the installed CE skills or an explicit fallback.

package/knowledge/orchestration/dynamic-workflows.md

@@ -0,0 +1,198 @@
+# Claude Dynamic Workflows For The Pre-Build Stages
+
+Use this when the current runtime is **Claude Code** and the work is a non-trivial _pre-build_ launch stage — research, competitor/social mining, 11-star, emotional design, analytics, paid UA, viral growth, launch narrative, localization market research, design exploration, naming/taste, spec hardening, or launch-readiness audits — and that stage is long-running, massively parallel, highly structured, or adversarial enough that one context window would degrade.
+
+This reference is the home for the **Claude-vs-Codex split** and for **Dynamic Workflows** guidance, for both agents driving the skill and humans running it. It does not replace `parallel-agent-orchestration.md` (subagents and worktrees) or `compound-engineering-routing.md` / `engineering-orchestration.md` (the build); it sits in front of them for the speced-but-not-yet-built phases.
+
+## The Claude-vs-Codex Split (A Recommendation, Not A Requirement)
+
+This is a **default bias and a recommendation, not a hard rule**. Either runtime can do any stage, and the founder decides. The skill's job is to make the recommendation visible — and especially to surface it to people who are running Codex on pre-build work — not to block, gate, or refuse work in whichever runtime is in front of you.
+
+The recommended division of labor:
+
+- **Claude is the better fit for research, product definition, design, and handoff.** Evidence gathering, category economics, social-language mining, 11-star and emotional design, analytics/attribution blueprints, paid UA and viral-growth plans, the launch narrative, localization market research, design exploration, and the build contracts (`PRODUCT.md`, `engineering/TECH_SPEC.md`, `state/LAUNCH_TRACE.md`, `engineering/ENGINEERING_PLAN.md`) benefit from research-heavy, taste-heavy, and adversarial verification. On a local Mac, Claude Code Desktop's in-app iOS Simulator pane can also support visual checks, flow walks, and bug reproduction while implementation happens elsewhere.
+- **Codex is the better fit for the core engineering build** once the spec is ready. Codex has its own in-app iOS Simulator loop (XcodeBuildMCP plus the `build-ios-apps` plugin), so the build side does not lose the see-the-app loop by staying in Codex; rung 0 exists in both runtimes and is never a reason to move a lane. The handoff bundle (`AGENTS.md`, `CLAUDE.md`, `APP_AGENTS.md`, `agents/`, `engineering/TECH_SPEC.md`, `engineering/ENGINEERING_PLAN.md`, `operations/ORCHESTRATION.md`) is what Codex (or Compound Engineering on Codex) consumes to write the app.
+
+When the founder leans this way, structure the run so Claude takes each pre-build stage to a locked, evidence-backed artifact, then hands a complete spec to Codex. Record which runtime is handling which lane in `operations/ORCHESTRATION.md` and `state/business-state.json` so a later session does not re-litigate it. But none of this is a gate: Claude can do small code edits, a founder can run the whole build under Claude, and a founder can run the whole pre-build under Codex if they choose — the skill recommends, then proceeds.
+
+As a cost note rather than a rule: a Claude Dynamic Workflow is usually wasted on the core engineering build (500-file migrations, codebase-wide refactors, the app implementation itself) — that work belongs to the Codex/CE route, so workflows on the Claude side typically stop at the spec. The Claude-side capability that extends past the spec is the simulator pane, not a workflow: a one-turn "run it and show me" is the cheapest thing in the whole ladder and should never be wrapped in a workflow.
+
+## Detect Codex And Recommend Claude For Pre-Build
+
+The highest-value moment for this recommendation is when someone is **running Codex (or any non-Claude-Code runtime) on a pre-build stage** — research, social mining, 11-star/emotional design, analytics, paid UA, viral growth, launch narrative, localization research, design/taste, naming, or spec hardening. Those are exactly the stages where Claude + Dynamic Workflows tends to help most, and the Codex user has no `ultracode` to reach for.
+
+**How to detect the runtime.** The agent generally knows which runtime it is; corroborate with concrete signals when unsure:
+
+- Dynamic Workflows are unavailable — `ultracode` does nothing, `/effort` has no `ultracode` option, `/workflows` and `/deep-research` are absent.
+- The session was invoked through the Codex app or `codex` CLI, or `AGENTS.md` is the active entrypoint while Claude Code-specific features are absent.
+- Runtime/environment markers indicate Codex rather than Claude Code.
+
+**What to do when detected (recommend once, never block):**
+
+1. Surface the recommendation **once**, plainly — not via AskUserQuestion, not as a founder-only gate. Say what and why: this pre-build stage tends to go better on Claude Code with Dynamic Workflows (per-agent isolation, adversarial verification, fan-out research), and Codex remains the stronger pick for the core build that follows.
+2. Give the concrete option: run this stage in Claude Code with `ultracode` (or `/deep-research`), or continue here in Codex — their call.
+3. **Continue the work in the current runtime regardless of the answer.** Do not pause, do not require approval, do not refuse. If they stay in Codex, run the same quality shapes (fan-out, adversarial verification, quarantine) as serial/parallel subagents or inline.
+4. Record that the recommendation was made in `state/business-state.json` so it is not repeated every turn. Make it once per pre-build phase or session, not on every message — no nagging.
+
+## What A Dynamic Workflow Is
+
+A Dynamic Workflow is a JavaScript orchestration script that **Claude writes for your specific task** and a background runtime executes. The script holds the loop, the branching, and the intermediate results in script variables, so only the final answer lands in Claude's context. It spawns and coordinates many subagents — each with its own context window, its own model, and its own isolation level.
+
+It solves three single-context failure modes structurally:
+
+- **Agentic laziness** — stopping after partial progress on a long multi-part task. Separate agents with focused goals each finish their slice.
+- **Self-preferential bias** — a model preferring its own output when it also judges it. A separate verifier agent that never saw the author's identity can't favor it.
+- **Goal drift** — losing fidelity to the original objective across many turns and compactions. The objective lives in code, not in a context window that gets summarized.
+
+Anthropic measured the self-preferential-bias failure directly. A bare, unharnessed run reported a game-editor task complete after 20 minutes with nothing working. The same task inside a harness with an independent evaluator ran 6 hours and finished correctly. An agent asked to grade its own work tends to praise it. A human reviewer often finds the same work mediocre. A standalone, skeptical evaluator catches this better than the generator critiquing itself.
+
+### When to reach for a workflow (vs. the alternatives)
+
+| Tool                                          | Who holds the plan   | Reach for it when                                                                                                                                       |
+| --------------------------------------------- | -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Inline (one orchestrator)                     | Claude, this turn    | A regular session would finish in a few minutes. Most stages.                                                                                           |
+| Subagents (`parallel-agent-orchestration.md`) | Claude, turn by turn | A handful of bounded independent audits per turn; results can fit in context.                                                                           |
+| Compound Engineering                          | CE skills, staged    | Non-trivial **engineering** work (the build) — brainstorm/plan/work/review/test/proof.                                                                  |
+| **Dynamic Workflow**                          | the script           | Dozens-to-hundreds of agents, a codified repeatable quality pattern (adversarial verification, tournament), or a run you want to read, rerun, and save. |
+
+Default to the smallest tool that fits. A workflow costs meaningfully more tokens than a normal session; reach for it only when a stage genuinely needs more compute, more parallelism, or a structural quality guarantee. If a normal Claude session would finish the stage in five minutes, do not wrap it in a workflow.
+
+## How To Run One (Humans And Agents)
+
+- **Trigger by keyword:** include `ultracode` in the prompt (e.g. `ultracode: mine 200 competitor reviews for the unmet-need wedge`). Asking in plain words ("use a workflow", "run a workflow") works too. Before Claude Code v2.1.160 the literal keyword was `workflow`; natural-language requests work in both.
+- **Trigger for the whole session:** `/effort ultracode` combines `xhigh` reasoning with automatic workflow planning for every substantive task. It lasts the session; drop back with `/effort high` for routine work.
+- **Approve the plan:** Claude shows the planned phases before running. Choose **Yes**, or **View raw script** / `Ctrl+G` to read it first. In `claude -p` and the Agent SDK there is no prompt — the run starts immediately under your configured permission rules, so set the tool allowlist deliberately.
+- **Watch:** run `/workflows`, select the run, and watch phases with per-phase agent counts, token totals, and elapsed time. Drill into any agent to read its prompt, tool calls, and result. `p` pauses/resumes, `x` stops an agent or the run.
+- **Bundled workflow:** `/deep-research <question>` is built in and is the fastest pre-build win — fan-out web searches, cross-check sources, vote on each claim, return a cited report with unsupported claims filtered out. Prefer it for category, competitor, and regulatory research.
+
+### Requirements and availability
+
+- Requires Claude Code **v2.1.154 or later**; Dynamic Workflows are in **research preview** on all paid plans, with Anthropic API access, and on Bedrock / Vertex AI / Microsoft Foundry. On Pro, enable the Dynamic workflows row in `/config`.
+- They can be turned off (`/config`, `"disableWorkflows": true` in settings, or `CLAUDE_CODE_DISABLE_WORKFLOWS=1`). When off, `ultracode` no longer triggers and bundled workflow commands disappear.
+- Refresh the official docs before changing any command, flag, or limit in this reference — this is a fast-moving preview feature (see Source Basis).
+
+## The Core API
+
+Three functions do most of the work; knowing them lets you read and nudge any workflow Claude writes.
+
+- `agent(prompt, { model, schema, isolation })` — spawn one subagent with its own context. Pick `model` per agent (`opus` for hard reasoning/synthesis, `sonnet` for the middle, `haiku` for cheap breadth). `schema` constrains the structured output. `isolation` is `worktree` (its own git checkout) or `remote` (no checkout) when an agent needs isolation.
+- `parallel(tasks)` — a **barrier**: fan out, then wait for everything before returning. Use when you need all results before the next step (e.g. synthesize after every reviewer returns).
+- `pipeline(items, stages)` — **streaming**: each item flows through every stage independently. Cheaper and faster when you do not need all results before acting.
+- `args` — a saved workflow reads its invocation input from the global `args` (structured data; call array/object methods directly). `undefined` if none passed.
+- `budget.remaining()` — checks tokens left; guard an open-ended loop with it before the 1,000-agent cap stops the run.
+- `phase(title)` — sets the progress label shown in `/workflows`.
+- `log(msg)` — emits a progress message during the run.
+
+Pick `parallel` vs `pipeline` by one question: _do I need all results before I can do anything next?_ Yes → `parallel`. No → `pipeline`.
+
+A saved workflow's `meta` export must sit first in the file, as a plain object literal. Never build it from a variable or a spread.
+
+### Limits the runtime enforces
+
+- Up to **16 concurrent agents** (fewer on low-CPU machines); **1,000 agents total** per run.
+- A single `parallel()` or `pipeline()` call accepts at most **4,096 items**; the runtime rejects a longer list with an error. Batch a loop-until-done pattern or a large fan-out above that count.
+- **No mid-run user input** — only agent permission prompts can pause a run. For founder sign-off between stages, run each stage as its own workflow.
+- The **script itself has no filesystem or shell access**; the agents read, write, and run commands, the script only coordinates them.
+- Runs are **resumable within the same Claude Code session** (completed agents return cached results); exiting Claude Code restarts the workflow fresh next session.
+- Never call `Date.now()` or `Math.random()` inside a workflow script; either call breaks the resume cache. Filter `parallel()` results with `.filter(Boolean)` before you return them.
+
+## The Six Patterns, Mapped To Pre-Build Stages
+
+1. **Classify-and-act** — a cheap classifier routes work before doing it. _Use for:_ deciding research depth per competitor, routing each surface to the right design treatment, triaging which localization markets deserve a full pass.
+2. **Fan-out-and-synthesize** — many independent slices in `parallel`, one Opus synthesis at the barrier. _Use for:_ one agent per competitor/review-cluster/keyword/endpoint, then a merged evidence ledger; per-surface 11-star or emotional-design audits merged into one map.
+3. **Adversarial verification** — pair each producing agent with a separate verifier that never saw who produced the work, checking it against a rubric or source. _Use for:_ every factual claim in `strategy/RESEARCH.md` verified against its source; a "why NOT to build this wedge" pass against the emerging spec; an ethics-guardrail skeptic against each emotional-design card; a copy-guardrail check against launch-narrative posts.
+4. **Generate-and-filter** — generate many options, then a verifier kills the weak ones; you see only the survivors. _Use for:_ names, taglines, paywall framings, onboarding hooks, ad angles, design directions — commit late, after every option is challenged.
+5. **Tournament** — pairwise comparison instead of absolute scoring (more reliable for taste). _Use for:_ ranking design directions, screenshot concepts, value props, market priority — anything taste-based or too large to sort in one prompt.
+6. **Loop-until-done** — keep spawning agents until a stop condition holds, for unknown-size work. _Use for:_ mining social language until no new themes appear; hunting spec gaps until a full pass returns zero; pair with `/goal` to force a hard completion ("don't stop until the evidence ledger has a source for every claim").
+
+Real stages compose 2-4 patterns. Pick by the failure mode: drift → fan-out; self-preference → adversarial verification; open-ended → loop-until-done; hard-to-score → tournament.
+
+**Loop-until-done needs a numeric stop-the-line rule.** After three failed attempts on one sub-goal, stop looping on it. Decompose the sub-goal into two or three smaller pieces. Collect the accumulated errors and fixes into one file. Retry the hardest piece with a stronger model when one is available. If it still fails, write a failure card and move on. Never leave a stuck sub-goal retrying inside an unattended loop.
+
+### Candidate Discipline
+
+Generation, selection, synthesis, majority vote, and verification each prove a different claim. Do not treat one as proof of another. Freeze the rubric before generation starts. A rubric you edit after a candidate appears creates a new experiment. Version it and rescore every candidate against the new version. A synthesis of two candidates is itself a new candidate. Give it a new identifier and verify it again before you use it. For a Generate-and-filter or Tournament run, start with three candidates. Raise the count to five only when candidates stay clearly different. Record the actual controls behind each verifier. A shared model, prompt template, or repository state is a correlation risk that fresh context alone does not remove.
+
+### Stage → workflow recipes
+
+- **Research-backed spec (Phase 1):** `/deep-research` or fan-out web/AppKittie/XPOZ searches → adversarial claim verification → synthesize the evidence ledger. Then a generate-and-filter pass on the wedge.
+- **11-star + emotional design:** fan-out one agent per surface/journey → tournament the magical-moment candidates → adversarial ethics-guardrail skeptic on each high-risk card.
+- **Analytics / attribution:** fan-out event-catalog drafting per funnel → adversarial verifier that each event has identity, attribution, and a QA probe.
+- **Paid UA / viral growth:** generate-and-filter creative angles and loop mechanics → adversarial "why this won't spread / won't pay back" pass.
+- **Launch narrative:** generate-and-filter post copy → adversarial 2026 copy-guardrail check (no hashtags/emojis, link in first reply).
+- **Localization market research:** classify-and-act per storefront → fan-out demand/difficulty pulls → tournament markets into Tier 1/2/3.
+- **Spec/handoff readiness:** loop-until-done gap hunt against the artifact contracts with `/goal`, so the bundle is complete before Codex starts.
+
+## Token Discipline
+
+Workflows balloon to 5-10x expected cost without controls. Always:
+
+- **Set an explicit budget** in the prompt ("use 10k tokens").
+- **Pair loop patterns with `/goal`** so the run iterates to a hard completion instead of stopping at the first soft one; use `/loop` only for genuinely recurring stages (weekly research refresh, continuous triage).
+- **Run a small slice first** (one directory, one market, a narrow question) to gauge spend before the full run; `/workflows` shows live per-agent token usage and you can stop without losing completed work.
+- **Route models per agent** — cheap models for breadth, Opus only where reasoning demands it. Check `/model` before a large run.
+- **Set `CLAUDE_CODE_ATTRIBUTION_HEADER=false`** for a high-volume subagent session. A unique per-session header otherwise forces a cache miss on the system prompt at every start. This is a documented workaround, not a permanent fix. Recheck it against current release notes before you rely on it.
+- **Watch cost, not only pass rate.** A controlled study found harness and orchestration-strategy choice can change token cost by up to 40 times. The same study found pass-rate gaps stayed under 8 percentage points. Judge an orchestration strategy by its cost, not only by whether it passed.
+
+## Quarantine Untrusted Input
+
+Much of the pre-build evidence base is **untrusted public content** — App Store/Play reviews, Reddit/TikTok/X posts (XPOZ and the social MCP tools), scraped competitor pages, support tickets, third-party API output. Any of it can carry prompt injection.
+
+Apply the **quarantine pattern**: the agents that _read_ untrusted content are read-only and barred from high-privilege actions (no edits, no provider mutations, no git, no posting). Separate actor agents that never see the raw content do the acting on the quarantined agents' structured output. A 30-line read-only reader agent costs almost nothing and removes an entire class of injection risk. If the input was not written by the founder or a trusted teammate, quarantine it.
+
+This pattern applies to any live loop that reads untrusted content before acting, not only pre-build research. The post-launch standing session in [`post-launch-operations.md`](../operations/post-launch-operations.md) reads support tickets, reviews, and webhook payloads. It needs the same quarantine: read-only reader agents, separate from any agent that sends email, posts publicly, or mutates records.
+
+## Save And Ship
+
+- When a run does what you wanted, press `s` in `/workflows` to save its script to `.claude/workflows/` (shared in the repo) or `~/.claude/workflows/` (personal). It then runs as `/<name>` and accepts `args`.
+- A saved workflow can ship as a **Skill**: bundle the JavaScript inside a Skill folder and reference it from `SKILL.md`. When packaging, prompt Claude to treat the workflow as a **template, not a script to run verbatim**, so it adapts the shape per task while keeping the structure — especially for flexible stages like deep verification and triage.
+- Reusable pre-build workflows that prove out across launches belong in this skill (saved under the skill, referenced here), not re-prompted every run.
+
+## State Contract
+
+When a stage runs as a workflow, record its execution plan in `operations/ORCHESTRATION.md` alongside the subagent assignments. Business state links this evidence from the orchestration lane:
+
+```yaml
+orchestration:
+  runtime_split:
+    current_runtime: "codex" # the runtime actually in use this session
+    recommended_prebuild: "claude" # recommendation, not a requirement
+    recommended_build: "codex"
+    prebuild_handled_by: "codex" # who is actually doing pre-build this run
+    build_handled_by: "codex"
+    recommendation_made: true # surfaced the Claude-for-pre-build tip this session/phase
+    rationale: "Recommendation surfaced; founder chose to continue in Codex for this stage."
+  workflows:
+    - stage: "research-backed-spec"
+      used: true # true | false
+      trigger: "ultracode" # ultracode | /effort ultracode | /deep-research | natural-language
+      patterns: ["fan-out", "adversarial-verification"]
+      token_budget: "10k"
+      goal: "Every claim in strategy/RESEARCH.md has a verified source."
+      saved_as: "" # /command name if saved, else ""
+      result_artifact: "strategy/RESEARCH.md"
+```
+
+If Dynamic Workflows are unavailable (runtime is not Claude Code, version below v2.1.154, disabled, or the founder declined), do **not** silently skip the quality pattern. Degrade to subagents (`parallel-agent-orchestration.md`) or an inline pass, and record `used: false` with the reason. The adversarial-verification and tournament _shapes_ still apply even when run as serial subagents — only the runtime changes.
+
+## Source Basis To Refresh
+
+Refresh these before changing any trigger, API name, flag, or limit above — this is a preview feature and the surface changes:
+
+- Claude Code dynamic workflows docs: `https://code.claude.com/docs/en/workflows`
+- Anthropic launch writeup: `https://claude.com/blog/introducing-dynamic-workflows-in-claude-code`
+- Claude Code subagents (the worker primitive): `https://code.claude.com/docs/en/sub-agents`
+- Anthropic harness design for long-running agents: `https://www.anthropic.com/engineering/harness-design-long-running-apps`
+
+## Done Rules
+
+A pre-build stage run through Dynamic Workflows is done only when:
+
+- the runtime in use, the recommended split, and who actually handled pre-build vs build are recorded in `operations/ORCHESTRATION.md` and `state/business-state.json`;
+- if the runtime is Codex (or another non-Claude-Code runtime) on a pre-build stage, the Claude-for-pre-build recommendation was surfaced once (plainly, not as a gate), recorded, and the work continued without blocking;
+- the workflow used a token budget, and any loop pattern was paired with `/goal`;
+- any agent that read untrusted public content was quarantined (read-only, no high-privilege actions);
+- producing agents and verifying agents were separate (no self-judging) where a quality gate was claimed;
+- the run's output landed in the stage's canonical artifact (e.g. `strategy/RESEARCH.md`, `11_STAR_EXPERIENCE.md`, `analytics/ANALYTICS.md`), not only in chat;
+- if workflows were unavailable, the fallback route and reason are recorded and the equivalent shape was run as subagents or inline;
+- the stage artifact is locked before the next stage or the Codex build depends on it.

package/knowledge/orchestration/full-launch-program.md

@@ -0,0 +1,179 @@
+# Full Launch Program: One Loadable Mandate For An End-To-End Consumer Delivery
+
+Use this reference when a founder asks for a complete consumer delivery: app, full web funnel, store packet, analytics, trust, revenue, and growth artifacts, carried to the point where the founder can open App Store Connect and click Submit for Review. It is the contract behind `workflow.orchestration.full-launch-program` and `workflow.orchestration.full-launch-closeout`.
+
+The program replaces a pasted launch prompt. The founder supplies a short mandate. The catalog supplies the graph. `b2c_plan` sequences the nodes. The gates and the review ledger decide what is done.
+
+## Contents
+
+- What The Program Is
+- The Mandate Record
+- Start Path
+- Phase Path
+- Design-Critical Waves
+- Reference Before Create
+- Words Contract
+- The Craft Bar
+- Full Web Funnel
+- Definition Of Done
+- Founder Decisions
+- Handoff Every Turn
+
+## What The Program Is
+
+The program is a top-level node with two ends:
+
+- `workflow.orchestration.full-launch-program` opens the program. Creation records the founder brief in `operations/FOUNDER_BRIEF.md` and a short program view in `operations/LAUNCH_PROGRAM.md`, sets `project.launchScope` to `full` through the reducer, and dispatches the orient work.
+- `workflow.orchestration.full-launch-closeout` closes the program. It depends on the store, trust, engineering, and growth terminal nodes and runs the definition-of-done gates.
+
+Between the two ends, the existing catalog nodes do the work. The program adds no second router, catalog, planner, or state store. It adds the mandate, the isolated-review edges, the reference-pack edge, and the closeout gates.
+
+The `full` launch profile parks no lane. Every lane ends `done`, `blocked` with a founder action, or `deferred` with a dated reason the founder accepted.
+
+## The Mandate Record
+
+Open `operations/FOUNDER_BRIEF.md` at program start. That file is the canonical founder brief. Write `operations/LAUNCH_PROGRAM.md` as the derived mandate record: quote a bounded founder-constraint slice (constraints, targets, authority, selected-app facts) with provenance (artifact and digest), then the program fields below. Keep the derived record short. Do not dump the full brief into every worker. Do not treat `LAUNCH_PROGRAM.md` as the source or the only mandate owner.
+
+| Field                | Content                                                                                                                                                                                 |
+| -------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Program              | `workflow.orchestration.full-launch-program`, catalog version, start date                                                                                                               |
+| Outcome              | One sentence. Example: iOS app, full web funnel, and store packet at the stated craft bar, Submit-for-Review ready.                                                                     |
+| Stop line            | The exact action the founder performs. Default: the founder clicks Submit for Review.                                                                                                   |
+| Launch scope         | `full`, recorded through the reducer with a dated founder reason when it changes an existing scope                                                                                      |
+| Start classification | greenfield idea, delegated build, or brownfield overhaul                                                                                                                                |
+| Workspace facts      | business workspace path and registration status; app repository path, stack, scheme, bundle identifier, team, secrets project, provider projects of record, forbidden provider projects |
+| Craft references     | live mechanic references and the design-evidence sources in use; mechanics transfer, identity never does                                                                                |
+| Spend ceiling        | the founder's number; default is quality-first inside the ceiling, stop and ask at 80 percent                                                                                           |
+| Autonomy mode        | the recorded mode and any standing envelopes                                                                                                                                            |
+| Founder-only actions | Submit for Review, production release, certificates, prices, spend without a ceiling, legal as final, public posts, live domain deploy                                                  |
+| Review policy        | `reference.orchestration.isolated-review` applies to every surface                                                                                                                      |
+
+Workspace-specific identities belong here and in reducer-owned state, never in catalog knowledge.
+
+## Start Path
+
+1. For a new business, create and register the planning workspace together: `b2c business-create --workspace my-app --directory ./my-app --name "Working name" --hypothesis "A short product hypothesis" --mandate-file ./brief.md --json`. Direct `--mandate` remains valid for short requests. Select an absent or empty directory; do not add files or register it first. The command records the founder brief in `operations/FOUNDER_BRIEF.md`. For an existing registered workspace, resume it. For an existing unregistered scaffold, use `b2c workspaces register <id> <path>`. Inspect an existing app before installing a scaffold; preserve its files. Never create a second workspace or re-scaffold an existing one.
+2. Run `workflow.orchestration.session-continuity-resume`. Read the durable artifacts before new work. Chat memory is not state.
+3. Run `workflow.orchestration.orient-scaffold-and-state-cockpit-upkeep`. Write `operations/ORCHESTRATION.md` with the `## Review Ledger` section before any broad dispatch.
+4. Present one start-of-workflow tool-intake AskUserQuestion from `reference.operations.paid-tool-routing` for the tools on the `research-backed-spec` compiled graph. Fold it into a pending readiness gate. Do not open a second tool gate. Do not substitute a generic fallback and call it equivalent. App Store Connect API auth and a live `asc apps list` receipt stay required; they are not optional research tools. Deferred AppKittie, XPOZ, Firecrawl, or paid ASO continue as labeled fallback.
+5. Record API-key health and Apple web-session health as two proofs. A healthy API key is not "ASC connected." Refuse an `asc web auth login` handoff unless the winning `asc` is `>= 5.1.0`. Do not write a signing blocker until `asc certificates list` has been read.
+6. Classify the start. A brownfield overhaul runs research in audit-and-gap-fill mode: keep, refresh, or redo each existing artifact with a dated reason. It does not silently restart. Do not dispatch `research-backed-spec` until `workflow.operations.live-app-store-portfolio` has succeeded.
+
+## Phase Path
+
+Parallelize inside a gate. Do not skip a gate. Node IDs are catalog IDs; `b2c_workflow` loads each one.
+
+| Phase                   | Nodes                                                                                                                                                                                                                                                                                                                                                                                                                          | Founder gate                                                                      |
+| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------- |
+| 0 Orient                | `session-continuity-resume`, `orient-scaffold-and-state-cockpit-upkeep`, `founder-zero-operator-bootstrap`, `secrets-baseline-and-routing`, `paid-tool-routing-and-fallback`, `live-app-store-portfolio`, `agent-operations-ledger`, `repository-profile-contract`                                                                                                                                                               | workspace register, spend ceiling, autonomy mode, Apple API auth for the apps list |
+| 1 Research to Go        | `research-backed-spec` after the live portfolio receipt and paid-tool intake succeed, then `spec-red-team-audit` in a fresh context                                                                                                                                                                                                                                                                                            | Go, Pivot, or Kill. Kill or Pivot is success. No design or build spend before Go. |
+| 1b to 1g                | `analytics-and-attribution-blueprint`, `11-star-experience`, `emotional-experience-design-producer` then `emotional-design-audit-auditor`, `writing-quality-no-slop`, `launch-trace-and-build-contracts`, `security-architecture-and-release-gate`, `generative-ai-safety` when a generated preview ships, `paid-user-acquisition-system`, `viral-growth-loop`, `localization-market-research`, `launch-narrative-and-cadence` | none                                                                              |
+| 2 Design                | `reference-pack-librarian`, `brand-definition`, `design-room`, then `design-system-audit`; `ux-patterns-refero`, `premium-mobile-craft`, `token-promotion`, `content-assets-remotion-generated-visuals`; the onboarding graph `onb-00` through `onb-22` with `onb-20` in a different context than `onb-18`                                                                                                                     | brand and taste on the landing story and the onboarding first screens             |
+| 2 to 4 Funnel           | `geo-seo-public-visibility` before the first public-page edit, `pre-launch-funnel-landing-waitlist`, then `landing-funnel-audit`, `copy-review-audit`, `resend-email-ops`, `landing-funnel-publication-and-live-proof`                                                                                                                                                                                                         | live domain deploy                                                                |
+| 3 Store                 | `app-store-listing-prep-packet`, `store-screenshots-production` after the copy review, `apple-store-media-standing-envelope`, `apple-store-metadata-standing-envelope`, `apple-testflight-standing-envelope`, `mobai-device-automation-and-demo-videos`, `apple-app-store-requirements-privacy-manifest`, `aso-and-store-ops`, `marketplace-regional-compliance`, `store-console-workflow`, `apple-signing-and-release-readiness`, `privacy-and-terms`, `asc-cli-automation`                                                                          | legal identity, Apple agreements, TestFlight versus submit envelope               |
+| 3b Revenue              | `revenue-monetization`; `experimentation` only after a paywall ships                                                                                                                                                                                                                                                                                                                                                           | pricing                                                                           |
+| 5 Engineering           | `engineering-orchestration-ce-production-readiness`, `backend-data-contract`, `native-ios-proof-route-ladder`, `accessibility-common-task-proof`, `app-quality-and-vitals`, `source-change-manifest` after each accepted slice, `security-architecture-and-release-gate` before upload, `provider-proof-verification`                                                                                                          | none                                                                              |
+| 6 Growth and operations | `ugc-creator-engine`, `fastlane-growth-ops`, `post-launch-operations`, `support-queue-operations`, `retention-intervention`, `launchbench-failure-cards-coverage-audit`                                                                                                                                                                                                                                                        | ad spend, public posts                                                            |
+| Close                   | `full-launch-closeout`                                                                                                                                                                                                                                                                                                                                                                                                         | Submit for Review                                                                 |
+
+`workflow.process.change-cascade` runs after every accepted design, copy, product, or price change. The copy deck, store fields, landing, email, and marketing context are cascade surfaces.
+
+First step after the stop line: `workflow.store.app-review-observe`, then `remediate`, then `resubmit`.
+
+## Design-Critical Waves
+
+After Go and before engineering becomes the critical path, run these waves. Keep each wave at five agents or fewer. Reconcile state between waves.
+
+1. Reference librarians. Quarantined and read-only. Output: structured reference packs and frozen rubrics under `design/reference-packs/` and `design/reviews/rubrics/`.
+2. Producers. Design-guru for the Design Room and the landing story map. Product-leader for onboarding evidence including `ONB-08`. Copy-specialist for the copy brief and deck. Producers consume the packs. They do not scrape live sites.
+3. Auditors in fresh contexts. Emotional auditor, `ONB-20`, design-system audit, motion-contract review. The design-system audit records its structured delegated Taste Gate decision beside its findings only when the current run carries the reducer-audited `decision.design.taste.delegation: approved` founder decision.
+4. Orchestrator integration, then the recorded Taste Gate decision on the landing and onboarding first screens. The founder or owner decides directly in `DESIGN.md` and binds the exact candidate through `b2c approve --design-taste`; a delegated design-system audit decides in its current engine-bound findings artifact. When the founder retains taste authority, the audit waits for that direct decision.
+
+Engineering is not the critical path until the landing story map and the onboarding first-value screens hold a Design Room direction and an isolated auditor pass the founder can still reject.
+
+## Reference Before Create
+
+No generated image, no native animation, no landing motion choreography, no icon, and no empty-state art until a dated reference pack exists for that surface. The task picks the sources through the `reference.design.design-evidence-stack` router. Taste does not.
+
+Every shipped animation has a motion register row: surface, user job, reference shot or flow IDs, adopted principle, token, haptic, interruption, reduced-motion twin, and frame budget. No row, no motion. A static legal or support page is not an animation. `check:motion-contract` is the gate.
+
+## Words Contract
+
+Copy is one shared input. It gets a contract and gates, not per-screen improvisation.
+
+- `product/copy/COPY_BRIEF.md`: promise, message hierarchy, voice and tone, voice benchmarks, voice-of-customer phrase bank, and the claims ledger. Freeze it before any surface copy.
+- `product/copy/COPY_DECK.md`: every user-facing string as one keyed row with locale tier and allowed terms. Deck keys are the String Catalog keys. A screen with no deck row stops the builder.
+- `product/copy/COPY_REVIEW.md`: auditor findings per surface, versioned against the rubric.
+- String freeze before store screenshots and translations. Late edits go through the change cascade.
+
+`workflow.words.copy-review-audit` is the isolated auditor. `check:app-copy` and `check:founder-copy` are the mechanical gates.
+
+## The Craft Bar
+
+Phase numbers are sequence, not permission to look unfinished. Everything that ships is designed and built at the stated bar. A surface meets the bar only when all twelve hold:
+
+1. Three real concepts before convergence, not three tints of one idea.
+2. Objects have physical presence: layers, anchors, overlap, shadow, settle. Nothing floats without a reason.
+3. Motion explains structure. A slow fade is not the default response to every change.
+4. Mobile is recomposed, not shrunk.
+5. Each medium is native. A story supports reading. A walkthrough supports action. A video supports time, captions, and progress.
+6. Restraint. Quiet space around the important thing.
+7. Micro-interactions are specified with feedback, interruption, completion, spring, and a reduced-motion twin.
+8. Quality facets are named per surface and compared to the current industry standard: meet, exceed, or deliberately break with a reason.
+9. Every visual traces to an audience fact in `strategy/RESEARCH.md`.
+10. Edge states exist: empty, loading, error, offline, reduced motion, Save-Data, and no-JS on the web.
+11. Cross-surface coherence: app, landing, funnel pages, screenshots, email, ads, and store metadata share tokens, nouns, and object language.
+12. Honest. Claims match what the build does today. Generated art never impersonates the product.
+
+The generic default fails even when it is pixel-neat. `reference.design.vibecoded-tells` names the tells. `check:audience-identity` enforces the shared object language.
+
+## Full Web Funnel
+
+Model every funnel URL in `studio/seed/business.json` as a Design Room surface with shared token references: landing, waitlist, web-to-app worksheet, support, privacy, terms, account deletion, and any referral, campaign, or purchase page the monetization cut creates. Run GEO/SEO before the first public-page edit so the baseline is dated. Audit each public page against the techniques that page actually selected or implemented: semantic content, accessibility, and working links for a static legal page; conversion structure for a conversion landing; scrollytelling, CRO, and vibecode only when that job is selected or the source already implements it. Do not invent scroll choreography or conversion experiments for a support or privacy page.
+
+## Definition Of Done
+
+The founder can sit down and submit when every row holds.
+
+| Item                                                                                                                                                                                 | Evidence                                                                                                                                                                                                          |
+| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Research audited and red-teamed in a fresh context; founder Go recorded                                                                                                              | `strategy/RED_TEAM_FINDINGS.md`; `check:research-workflow-output`                                                                                                                                                 |
+| `PRODUCT.md` accepted with the north-star metric and the first-value surface; emotional design plus its isolated audit                                                               | `check:product-md`; `check:emotional-design`                                                                                                                                                                      |
+| `DESIGN.md` accepted with design.md lint clean and no diff regression; Design Room; token promotion; isolated design-system audit; object map in every surface                       | `check:design-md`, `check:design-room`, `check:token-promotion`, `check:design-worthiness`, `check:audience-identity`; `design/reviews/DESIGN_SYSTEM_REVIEW.md`                                                   |
+| Words: frozen brief, complete deck, isolated review per surface, string freeze dated before screenshots                                                                              | `check:app-copy`, `check:founder-copy`; `product/copy/COPY_REVIEW.md`                                                                                                                                             |
+| Website and funnel: story map, semantic no-JS page, measured scrollytelling when selected or implemented, mobile composition, every modeled URL, CRO when the page has a conversion job, GEO/SEO baseline and post-change, email routes tested | `check:scrollytelling`, `check:landing-funnel`, `check:vibecoded-tells`, `check:email`; `growth/CRO_AUDIT.md` when a conversion job exists; `GEO_SEO.md` |
+| Onboarding graph implemented; `ONB-08` motion research scoped to selected surfaces; `ONB-18` prototype with every state; `ONB-20` by a different agent                                                    | `check:onboarding-graph-complete`, `check:onboarding-evidence-onb-08`, `check:onboarding-evidence-onb-20`                                                                                                         |
+| Motion register complete                                                                                                                                                             | `check:motion-contract`                                                                                                                                                                                           |
+| App builds, tests, accessibility, quality and vitals, security, privacy manifest, required-reason APIs; readiness has device evidence for every declared platform                    | `check:security`, `check:secrets`, `check:apple-requirements`, `check:readiness-coverage`; iOS: `check:native-ios`; Android: `check:mobai-proof` and `check:native-android`; mixed: all three native proof checks |
+| Listing packet, keywords, truthful screenshots, App Preview and demo video, What's New, review notes, age rating, privacy answers, regional compliance                               | `check:store-console`, `check:aso-evidence`, `check:store-screenshots`, `check:app-review-contract`                                                                                                               |
+| Archive whose Info.plist matches the store version and build; upload when the envelope allows                                                                                        | `check:apple-release-readiness`                                                                                                                                                                                   |
+| Store console click path ending at Submit for Review                                                                                                                                 | `check:app-review-contract`                                                                                                                                                                                       |
+| Support, privacy, terms, and deletion URLs work; legal questions answered; legal text approved                                                                                       | `check:privacy`; `LEGAL_REVIEW.md`                                                                                                                                                                                |
+| Launch narrative, paid UA, viral, UGC contracts, and post-launch operations skeleton each done or dated-deferred                                                                     | `check:paid-ua`, `check:post-launch`                                                                                                                                                                              |
+| Every lane done, blocked with a founder action, or deferred with a reason; every external pack recorded in `strategy/TOOL_DECISIONS.md`                                              | `check:lane-coverage`                                                                                                                                                                                             |
+| Handoff: what the founder clicks, in order, and the one remaining founder action                                                                                                     | `check:founder-copy`                                                                                                                                                                                              |
+| Review ledger complete: every producer-to-auditor pair, rubric version, verdict, and artifact                                                                                        | `check:orchestration`                                                                                                                                                                                             |
+
+A store-ready binary with a generic landing, a carousel onboarding, unaudited copy, or a self-reviewed design is not done.
+
+## Founder Decisions
+
+Use the founder-zero contract: two or three choices, one recommendation, consequences, a defer path, and a revisit trigger, in plain language.
+
+The user's authorization to create or adopt a local workspace covers its registration. Pause when that authorization does not cover the target or registration, or when it would affect a different existing business.
+
+Pause for: paid-tool access or spend, Go/Pivot/Kill, brand and taste, pricing, legal identity, Apple enrollment and agreements, the TestFlight versus submit envelope, and the live domain deploy.
+
+The agent never submits for review, releases to production, enrolls or rotates certificates, sets prices, spends without a ceiling, publishes legal text as final, or copies another app's secrets.
+
+## Handoff Every Turn
+
+Report what changed, the evidence, the next parallel wave, the serialized critical path, and the one decision only the founder can make.
+
+## Design Delivery Loop
+
+One founder mandate includes the internal research, production, independent critique, repair, and verification rounds needed for the complete accepted design. Never substitute a partial product or a generic first draft to finish a round. Keep product scope in `product.yaml` and global design authority in `DESIGN.md`.
+
+Use `reference.design.consumer-craft-benchmarks` to derive product-specific visual and interaction criteria. Freeze each surface rubric and its inspected references before production. The prebuild design-system audit validates the direction. After implementation, `workflow.design.implementation-craft-audit` inspects the actual native app and the landing page at phone and desktop sizes. It produces the exact-artifact evidence defined by `reference.design.design-acceptance` and runs `check:design-acceptance`.
+
+Every required surface and state must meet every agreed floor. A strong landing page cannot compensate for a weak mobile app. An image path or a design document cannot substitute for the rendered interface and exercised interactions. Rejected findings return to the responsible producer for a bounded repair and a fresh independent review. A changed candidate or rubric invalidates the earlier acceptance. Retain the best accepted candidate while comparing repairs; do not assume a later attempt is better.