SaaS Pipeline — Orchestrator

Pipeline of phases, never assumes the user is a developer, always free/self-hosted except the VPS + domain. Phases are separate skill files so each loads only what it needs — this file only routes, it does not do phase work.

Why split

• Phase 1: needs GitHub data + user back-and-forth. Not Coolify/SSH.
• Phase 2: needs the boilerplate's file tree + Phase 1's answers. Not deployment details.
• Phase 2.5 (redesign, optional): needs the scaffolded code, a design engine, and vision. Not deployment details either.
• Phase 3: needs SSH/Coolify/domain. Not which boilerplate or what it looks like.
• Phase 4: runs in a brand-new session, weeks later, zero conversation memory. Only has the status file.
• Phase 5 (kaviar): runs after a session that had problems. Needs the session log and the lesson files — not the project.

The status file — backbone of everything

PIPELINE_STATUS.md at project root. Every phase reads/writes it. Schema + rules: shared/references/status-file-schema.md — read that before anything else. It is written in note form and validated with shared/scripts/note_lint.cjs --status PIPELINE_STATUS.md.

Step 0 — always first

1. PIPELINE_STATUS.md exists? → git pull first if there's any chance another session/harness touched this repo since last local access (the status file's whole value is being a trustworthy source of truth — reading a stale local copy defeats that). Then read it, resume from current_phase, don't re-ask answered questions, summarize back in 1-2 lines. Doesn't exist? → new project, Phase 1.
2. Check needed reference/skill files are present (shared/references/dynamic-skill-discovery.md) — matters most before Phase 3 (Coolify) and Phase 2.5 (design engine + vision).
3. Before Phase 2.5, run node shared/scripts/setup_harness.cjs --check: it reports whether vision, screenshot paths and the scope hook are actually wired. Do not promise visual verification without it.

Routing

02b-redesign isn't strictly sequential — commonly right after Phase 2, also invocable later against a live app. Route on intent (visual vs. functional), not strictly on phase.

Non-negotiable constraints (all phases)

1. Free only, except VPS + domain. No Vercel, no managed Postgres, no paid auth vendor, no paid email past free tier — unless the user explicitly opts in. Every boilerplate in the registry defaults something to paid — Phase 1/2 must surface and fix this, not just note it. See shared/references/free-stack-swaps.md.
2. User is likely not a developer. Plain-language before any technical ask (shared/references/plain-language-glossary.md). For anything the user must go get themselves (GitHub account, VPS, domain, SSH key) — point to shared/references/user-setup-guides.md rather than improvising an explanation.
3. User provides secrets/access/purchases — agent does the rest. No hand-editing config, no manual terminal commands, unless truly unavoidable.
4. Real git history, not a dump commit (shared/references/git-hygiene.md).
5. Minimal footprint — only wire up what's asked. Strip the rest (Phase 2).
6. Verify tools before building — check Node/Docker/git are actually present before scaffolding, don't discover a gap mid-task (shared/references/environment-check.md).
7. Features get verified, not assumed. Phase 2 doesn't declare done until every must_have_feature is confirmed working against FEATURE_BLUEPRINT.md — "the app boots" is not the bar.
8. Redesign never touches production/security, and this is enforced, not just stated. Two tiers on this harness: a real PreToolUse hook (shared/scripts/install_scope_hook.cjs) plus the mandatory git-diff gate (02b-redesign/scripts/check_redesign_scope.sh). Both read the same scope-policy.json. See 02b-redesign/references/enforcement.md.
9. Post-launch changes go through a branch + CI gate, never a direct push to main. Coolify auto-deploys on every push to main — a direct commit post-launch is an immediate, ungated production deploy (shared/references/ci-and-branching.md).
10. Nothing is claimed that was not measured. Prices, savings percentages, "the model can't see images", "this is enforced" — each one is either verified with a command or marked unknown. The pipeline's own reference files have been wrong before and were corrected; a confident sentence costs more than a checked one.
11. Claims about the harness are re-verified, not inherited. This file and its references name exact versions and behaviours. When something looks different, check the version first (dsh -V, package READMEs) before believing an instruction.

Token/tool-call discipline

• Prefer a deterministic script over AI re-derivation, every time one exists. Codebase structure → Repomix (shared/references/repomix-usage.md). Environment readiness → check_environment.sh. Boilerplate freshness → check_github_freshness.py. Redesign scope → check_redesign_scope.sh + the hook. Design context/tokens/routes → design_context.cjs. Design coherence → design_gate.cjs. Session failures → session_retro.cjs. Instruction artifacts → note_lint.cjs. Harness readiness → setup_harness.cjs --check.
• Then write notes, not prose (shared/references/note-style.md): one fact per line, exact values verbatim, target 2-3x compression, delete before rewriting. It is a focus and context-window win, not a cost win — say so rather than implying a saving.
• Output is the expensive bucket (4x a cache miss, no cache discount). Terse replies, no re-narration of tool output, low effort on mechanical steps.
• Skip the GitHub freshness re-check if last_checked is <30 days old.
• Skip web search for anything already answered in a bundled reference file.
• Cache Repomix output against the repo's HEAD SHA (repomix_cache_sha) — don't re-run on an unchanged repo.
• Point to reference files for repeat explanations instead of regenerating the same prose.
• Never claim a change saves money without measuring it. shared/references/cache-and-cost.md holds the verified DeepSeek economics (a hit is 50x cheaper than a miss, peak is 2x off-peak, output is 4x a miss) and the levers ranked by real impact; node shared/scripts/cache_audit.cjs "<sessions dir>" prints a workspace's actual hit rate, bill and peak/off-peak split from the harness's own logs, with no plugin and no API calls. Measured here: prefix caching was already at 99.4% and the biggest controllable lever was scheduling, not trimming — 74% of the spend landed in DeepSeek's peak window. Dropping 18 skills from the catalog measured ~0.4% of the bill, so isolation changes are focus, not savings.

Delegation discipline (subagents, models, ledger)

Applies whenever work is handed to a subagent or a workflow — phases 2, 2.5 and 4 all do.

• Name the model on every dispatch. An omitted model inherits the session's, which is the most expensive one available. Mechanical work — search, extract, format, run a script and report — goes to deepseek-flash; judgement, review, and anything that decides what "correct" means stays on the session model. Measured caveat from the public study of this pattern: the cheapest tier takes 2–3x the turns on multi-step work and ends up costing more, so Flash is the floor for anything beyond a single step, not the target.
• The implementer never reviews its own work. A task that matters gets a separate reviewer with fresh context and two distinct verdicts: does it match the spec (the blueprint row or the user's request, quoted verbatim), and is the result any good. Self-review is not a substitute.
• One fix dispatch per review wave, carrying the whole findings list — not one fixer per finding, which rebuilds context and re-runs the suite for each.
• Keep a ledger for anything longer than three steps. docs/pipeline/LEDGER.md, committed, one line per finished task: Task 3: complete (commits a1b2c3d..d4e5f6a). Context does not survive compaction, and a session that trusts its memory re-dispatches finished work — the most expensive failure observed in this pattern. On resume, read the ledger and git log before deciding anything is undone.
• Rulings, not stalls. A running plan does not stop for questions it can answer: decide, record the decision in the ledger with what it costs if wrong, and continue. Stop only for an irreversible action, a security-sensitive one, a side effect outside the repo, or a plan so broken that every path forward is a guess.

The phases above are instructions, and instructions rot. After any session where something went wrong twice, or when the user says "kaviar":

1. node 05-kaviar/scripts/session_retro.cjs → evidence from the session log, not memory.
2. At most three lessons, each generalisable and evidenced → lessons.cjs add (repeats reinforce instead of duplicating).
3. Promotion into a SKILL.md only with the user's approval (lessons.cjs apply ... --approved), then validated with install-skill.cjs --check-only and note_lint.cjs.

Corrections found this way are welcome and expected in these files — a reference that is wrong is worse than one that says unknown.