{"slug": "the-software-factory-playbook-dex-horthy-s-4-gate-workflow-product-architecture", "title": "The Software Factory Playbook — Dex Horthy's 4-gate workflow (Product → Architecture → Program Design → Vertical Slices) as an installable Claude Code skill.", "summary": "Dex Horthy, founder of HumanLayer, has outlined a four-gate software development workflow—Product, Architecture, Program Design, and Vertical Slices—designed to make critical decisions before code is written. The workflow has been packaged as an installable Claude Code skill by developer Maciejdziuba, enabling agents to pause at each gate for user approval and document decisions for continuity across sessions. The skill aims to reduce costly rewrites by forcing early context-light thinking and incremental vertical slices.", "body_md": "The Software Factory Playbook — Dex Horthy's 4-gate workflow as a skill\n\nA Claude Code Agent Skill built from Dex Horthy's (HumanLayer) playbook on David Ondrej's podcast.\n\n\"Once the model has written thousands of lines of code, it is harder to change. The sessions that generate design docs are context-light — you get the most model intelligence when you do the hard thinking early.\"\n\nBy default, agents build horizontally: all the backend, then all the frontend, then a 2,000-line diff lands in your lap and reviewing it is your problem. This skill flips that. Every decision that matters gets made before the code exists — where changing your mind costs a sentence, not a rewrite.\n\nWhat it does\n\nWhen you start a real feature, your agent walks through four approval gates — and stops at each one until you sign off:\n\nProduct — what user problem, how success is measured, the \"blog post before the feature,\" and plain HTML mockups of every screen. No tech talk allowed.\n\nArchitecture — how it fits your existing system: endpoints, tables, query outlines, the end-to-end flow.\n\nProgram Design — the step everyone skips: file locations, types and method signatures (no bodies), the call stack, what the tests will assert, and a list of the decisions the agent is least confident about.\n\nVertical Slices — code, finally — but tracer-bullet style: a thin end-to-end slice that runs first, then real logic one testable slice at a time. You can re-steer after every slice, while it's cheap.\n\nEvery gate follows a fixed doc template and writes to docs/plans/<feature>/, with a 00-status.md state file tracking which gates you've approved and which slices are done. That means decisions survive across sessions: the agent compacts everything into the docs at every gate and slice boundary (Dex's dumb-zone rule — keep the hard thinking early in the context window), and any fresh session picks up exactly where the last one stopped.\n\nTrivial tweaks are exempt — nobody needs four gates to change a button color.\n\nInstall (30 seconds)\n\n```\nmkdir -p ~/.claude/skills/software-factory\ncurl -fsSL \"https://gist.githubusercontent.com/Maciejdziuba/88890d7e0eeefa5a8738bbe9fd5e20b8/raw/SKILL.md\" \\\n  -o ~/.claude/skills/software-factory/SKILL.md\n```\n\nRestart Claude Code. The skill activates automatically on real features, or invoke it with /software-factory.\n\nWorks in any agent that supports the SKILL.md format (Claude Code, Amp, and others).\n\nBonus inside\n\nThe dumb-zone rule — Dex's context-engineering practice: make the hard decisions early in the context window, compact to docs at every gate and slice boundary, restart fresh.\n\nThe context-in-the-codebase convention — docs/adr/ for decisions and docs/external/ for everything outside the repo (env var names, payment setup, test accounts), so every future session starts smarter.\n\nFrom the episode with Dex Horthy on why software factories fail, benchmarks vs. real codebases, and context engineering — David Ondrej on YouTube. Follow Dex: X @dexhorthy · HumanLayer\n\nDex Horthy's 4-gate feature workflow — Product, Architecture, Program Design, Vertical Slices — with explicit user approval at every gate before implementation code exists. Use when starting a new feature, a new project, or any task expected to change several files or produce a large diff. Not for trivial tweaks like renames, copy changes, or one-line config edits.\n\nThe Software Factory Playbook\n\nDex Horthy's (HumanLayer) workflow: make every important decision before implementation code exists, where changing it costs a sentence instead of a rewrite. Work through four gates in order. Stop at each gate for explicit user approval. Never merge gates. Never write implementation code before the Gate 4 slice plan is approved.\n\nWhen to run the gates\n\nRun the full workflow when the task is a real feature: it will create or change multiple files, add an endpoint, table, or screen, or produce a diff the user would hate to review all at once (roughly 100+ lines).\n\nSkip the gates entirely (just do the task) when any of these hold:\n\nThe user explicitly says to skip the process (\"just vibe it,\" \"quick and dirty,\" \"no process\").\n\nThe user says the code is throwaway or pure prototyping.\n\nIf unsure whether the task qualifies, ask once: \"This looks big enough for the 4-gate workflow — run it, or do you want the fast version?\" Respect the answer.\n\nFiles and state\n\nAll workflow files live in docs/plans/<feature-slug>/:\n\n```\ndocs/plans/<feature-slug>/\n  00-status.md          state file: gate approvals + slice checklist\n  01-product.md\n  mockups/              Gate 1 screen mockups — plain HTML, one file per screen\n  02-architecture.md\n  03-program-design.md\n  04-slices.md\n```\n\nCreate 00-status.md first, before Gate 1. Update it at every gate approval and every slice completion. Template:\n\n```\n# Status: <feature name>\n\n- Gate 1 — Product: pending | in progress | APPROVED <date>\n- Gate 2 — Architecture: pending | in progress | APPROVED <date>\n- Gate 3 — Program Design: pending | in progress | APPROVED <date>\n- Gate 4 — Slice plan: pending | in progress | APPROVED <date>\n\n## Slices\n- [ ] Slice 1 — tracer bullet: <one line>\n- [ ] Slice 2 — <one line>\n\n## Notes for a fresh session\n<anything decided in chat that a new session must know>\n```\n\nResume rule: at the start of any session, if docs/plans/<feature-slug>/00-status.md exists for the feature being discussed, read every doc in that folder first, then continue from the first unapproved gate or first unchecked slice. Never redo an approved gate unless the user asks for it or a later gate invalidated it.\n\nThe approval protocol (run at every gate)\n\nWrite the gate doc to disk.\n\nPresent a summary to the user: at most 5–10 bullet decisions, plus the doc path. Do not paste the whole doc into chat.\n\nAsk exactly: \"Approve Gate N, or what should change?\"\n\nApproval means the user clearly says yes / approve / continue. Anything else means: revise the doc to address their answer, then re-ask.\n\nOn approval, mark the gate APPROVED in 00-status.md and move on.\n\nBacktracking: if work at a later gate reveals an earlier approved decision is wrong, stop, update the earlier doc, set that gate back to \"in progress\" in 00-status.md, and get re-approval before continuing.\n\nGate 1 — Product (no tech talk)\n\nWork with the user to fill this template, saved as 01-product.md:\n\n```\n# Product: <feature name>\n\n## Problem\n<the user problem, in the end-user's words — not the developer's>\n\n## Success metric\n<one real number tied to the business (conversion, latency, tickets, revenue) and how it's measured>\n\n## Announcement — the blog post before the feature\n<3–6 sentences announcing this feature to users. If you can't write it, you're building the wrong thing.>\n\n## Screens\n<one line per mockup file in ./mockups/ — or \"no UI\">\n```\n\nRules for this gate:\n\nBanned in this stage: databases, schemas, endpoints, architecture, file names. If tech appears, move it to Gate 2.\n\nFor anything with a UI: produce one plain HTML file per screen in mockups/ — no framework, no build step, throwaway by design. Iterate on the mockups with the user until they say \"yes, that.\"\n\nRun the approval protocol.\n\nGate 2 — Architecture\n\nRead the relevant existing code before writing this doc — never design against an imagined codebase. Template, saved as 02-architecture.md:\n\n```\n# Architecture: <feature name>\n\n## Fit\n<which existing services/modules this touches, and how>\n\n## Endpoints\n<route + verb + purpose, one line each — or \"none\">\n\n## Data\n<new or changed tables/collections, with outlines of the queries that will hit them>\n\n## Flow\n<the end-to-end call order for the main path: what calls what>\n\n## External\n<third-party APIs, env var NAMES (never values), webhooks — or \"none\">\n```\n\nRun the approval protocol.\n\nGate 3 — Program Design (the step everyone skips)\n\nThe decisions the agent would otherwise make silently mid-implementation. Template, saved as 03-program-design.md:\n\n```\n# Program Design: <feature name>\n\n## Files\n<every file created or changed, one line each on why it lives there>\n\n## Types & signatures\n<code blocks defining the types and method signatures — NO implementation bodies.\nA human should be able to read these in seconds and say \"right\" or \"wrong.\">\n\n## Call stack\n<for each main flow: what calls what, top to bottom>\n\n## Test plan\n<test case names and what each one asserts — before any of them exist>\n\n## Least confident decisions\n<numbered list of the calls most worth challenging now, while changing them is free>\n```\n\nRun the approval protocol.\n\nGate 4 — Vertical Slices (tracer bullets)\n\nFirst write the slice plan as 04-slices.md — one line per slice, in build order — and run the approval protocol on it. Then build one slice at a time.\n\nSlice rules:\n\nSlice 1 is the tracer bullet: a mocked/hardcoded endpoint and a stubbed UI (or curl-able response), wired end to end. It does almost nothing — but it runs, and the user can see it.\n\nSlice 2: replace mocks with the real logic for the single happy path.\n\nSlice 3+: one capability per slice — a business rule, error handling, an edge case, polish — each ending in a working, testable state.\n\nBanned: horizontal building (all of the database, then all services, then all API, then all frontend, with nothing testable until the end).\n\nAfter every slice:\n\nProve it works — run it, curl it, or browser-test it, and show the user the result.\n\nCheck the slice off in 00-status.md.\n\nAsk: \"Continue to slice N+1, or re-steer?\" If the trajectory is wrong, fix direction before adding more code.\n\nStanding rules (always on during the workflow)\n\nCompact at every boundary. At the end of every gate and every slice, make sure the docs contain everything decided — nothing important may exist only in chat. Tell the user this is a safe point to start a fresh session; a new session must be able to continue from the docs alone (see the resume rule). If the harness warns that context is running low, compact immediately, wherever you are.\n\nKeep diffs reviewable. Small slices. If the user hasn't looked at code in a long stretch, nudge them at a slice boundary — losing touch with the codebase costs weeks, exactly when the agent hits a bug it can't solve.\n\nReal tests only. Never write a test that passes against the pre-change code — a test that can't fail tests nothing. Never comment out, skip, or weaken a test to get to green.\n\nOptional: durable context in the codebase\n\nWhen a gate produces a decision that outlives this feature, offer to record it as an ADR in docs/adr/NNNN-<slug>.md — context, decision, consequences; never rewrite old ADRs, supersede them. Record anything that lives outside the repo but that an agent needs to know exists (env var names, payment setup, test accounts, third-party dashboards) in docs/external/. Files on disk are free context — every future session starts smarter.", "url": "https://wpnews.pro/news/the-software-factory-playbook-dex-horthy-s-4-gate-workflow-product-architecture", "canonical_source": "https://gist.github.com/Maciejdziuba/88890d7e0eeefa5a8738bbe9fd5e20b8", "published_at": "2026-08-01 15:19:19+00:00", "updated_at": "2026-08-09 12:06:19.385389+00:00", "lang": "en", "topics": ["developer-tools", "ai-agents", "ai-products"], "entities": ["Dex Horthy", "HumanLayer", "Claude Code", "David Ondrej", "Maciejdziuba"], "alternates": {"html": "https://wpnews.pro/news/the-software-factory-playbook-dex-horthy-s-4-gate-workflow-product-architecture", "markdown": "https://wpnews.pro/news/the-software-factory-playbook-dex-horthy-s-4-gate-workflow-product-architecture.md", "text": "https://wpnews.pro/news/the-software-factory-playbook-dex-horthy-s-4-gate-workflow-product-architecture.txt", "jsonld": "https://wpnews.pro/news/the-software-factory-playbook-dex-horthy-s-4-gate-workflow-product-architecture.jsonld"}}