Founder OS Setup Wizard

Runs on: local-writes - creates or edits files in your OS folder; needs an agent with write access.

Already set up? Check this before anything else

This skill also fires on everyday questions like "what do I do" and "how does this work". On an install that is already set up, those are questions, not a request to start over. Read the install's state first, in this order (the same order /setup uses):

1. state/setup-progress.json exists and holds a record: setup was interrupted. Go to Resuming at the bottom of this file. Do not re-run anything.
2. state/setup-complete.json exists, or core/identity.md exists with neither marker: Founder OS is already set up here. Do NOT re-run setup and do not touch a file. Say in one line: "Founder OS is already set up in this folder." Then answer what they asked, or offer the menu ("say 'show me what you can do'"). Add one line: "If you really want to start over, say 'reset Founder OS'." Stop there.
3. Neither marker and no core/identity.md: a fresh install. Carry on with the surface check below.

Two signals skip step 2: the founder said "reset" (or the word reset came in with the request), or /setup passed a confirmed re-run. Then back up before anything is written or deleted:

• Copy core/, context/, cadence/, brain/, rules/ and CLAUDE.md into state/setup-backup-<YYYYMMDD-HHMM>/, using the local time. Use whichever Python spelling answers (python, python3, py -3), for example: python -c "import shutil,time,pathlib as p; d=p.Path('state')/('setup-backup-'+time.strftime('%Y%m%d-%H%M')); d.mkdir(parents=True,exist_ok=True); [shutil.copytree(n,d/n) for n in ('core','context','cadence','brain','rules') if p.Path(n).is_dir()]; p.Path('CLAUDE.md').is_file() and shutil.copy2('CLAUDE.md',d/'CLAUDE.md'); print(d)"
• Check the backup landed: list the folder and confirm core/identity.md is inside it. If it is not there, stop and say the backup failed. Never start a reset without a backup you have seen.
• Tell the founder in one plain sentence where it is: "I saved a copy of your current files in state/setup-backup-<stamp>/ before starting over." Then continue with the surface check.

Surface check - before Phase 0.0

Setup writes real files. Before you frame anything, confirm the surface you are on can write to the operator's OS folder:

• Claude Code (local, write access): full setup. Proceed normally.
• Any surface that cannot write to a folder on the founder's machine (claude.ai chat, Claude Code on the web, Cowork without a connected folder and the desktop app open, or any read-only surface): do NOT pretend setup ran. Say so in one sentence, then offer the honest path: "Setup writes files to a folder on your machine and this surface can't do that. I can still walk you through every question and draft each file here for you to paste in, or you can run this in Claude Code for full automation - your call." Then either draft-and-hand-off, or stop. Never claim a file was written, git was wired, or a hook was installed when it was not.

If you are unsure whether you can write, attempt one small write to the OS folder and check it landed. If it did not, you are on a degraded surface - take the path above.

You are running an interactive setup wizard that builds a complete operating environment for one person using Claude Code - a founder, or an employee running a role inside a company. Follow the phases IN ORDER. Ask ONE question at a time. Wait for the answer before moving on.

This file is the router. Each phase's full procedure lives in a references/ file. Load the reference for the phase you are in, when you reach it - not all at once. Carrying every phase's detail up front is exactly the context waste this product tells founders to avoid. The references hold the verbatim procedure; nothing about what setup produces changes - only when the detail loads.

Rules

• Ask ONE question at a time. Wait for the answer.
• When a step requires user input, show what you'll create BEFORE creating it. Get a "yes" or adjustment.
• When creating folders, check what already exists first. Don't overwrite. Don't duplicate.
• Keep CLAUDE.md files LEAN. Global under 80 lines. Company under 60. Project under 40. Bootloader under 120.
• Track everything skipped or deferred in a BACKLOG at the end of the setup.
• After each phase, show a quick status: what's done, what's next.
• If the user says "skip" or "later", log it and move on. Don't push back. The one exception is the adults-only question in Phase 0.A: it needs a clear yes before anything else, even when the user skips, says "just set it up", or dumps everything at once.

Handling Real Human Input

People don't answer questions like a form. They ramble, go on tangents, answer three questions at once, skip ahead, circle back, and think out loud. This is expected. Handle it:

• If they answer multiple questions in one response: Extract all the answers. Mark those questions as answered. Move to the next unanswered question. Don't re-ask what they already told you.
• If they go on a tangent: Extract anything useful from the tangent (business context, priorities, pain points, tool preferences). Log it. Gently return to the current question without making them feel corrected.
• If they skip a question: Move on. Come back to it later if the answer becomes important for file generation. If it never matters, leave it blank.
• If they give a partial answer: Use what you got. Only ask for the specific missing piece, not the whole question again.
• If they contradict themselves: Use the most recent answer. Don't flag contradictions unless they materially affect the setup.
• If they dump everything at once: Great. Parse it all, map answers to phases, and skip ahead to wherever you have enough info to start building. Show them what you captured and what's still missing.
• Never ask the user to be more structured. Adapt to them. That's the whole point of this system.

Before you write any file

Setup writes from templates/, which ships at the install root (resolved by install method: Plugin folder, git-clone repo root, or curl install root). Read each template before you generate the personalized version. The full path-resolution rule and the complete template file list live at the top of references/identity-and-global.md - read it before Phase 1.

If the user passed "reset": make the backup described at the top of this file first, then scan for an existing Founder OS folder, confirm they want to reconfigure, then re-run discovery.

Phase map - load the reference when you reach the phase

Run the phases in order. When you reach a phase, read its reference file for the full procedure, then execute it. Load only the phase you are in.

After every phase

Show a quick status: what is done, what is next. Track anything skipped or deferred in the backlog (core/setup-backlog.md), not scattered across other files. The backlog is shown and saved in Phase 6.3.

Write the resume marker (mandatory, same moment as the status). Setup takes 15 to 20 minutes and sessions get closed mid-way. Before these markers, an interrupted setup reopened as an ordinary session with no explanation, because the launchers branched on core/identity.md - written when setup builds your folders in Phase 2.2, long before setup is actually done. Two files fix that:

• The moment setup starts, before Phase 1 writes anything, delete state/setup-complete.json if it is there. A re-run is an unfinished setup from that instant on, and leaving the old completion marker in place means both markers exist together, completion wins the tie, and an interrupted re-run reopens as an ordinary session with no explanation - the precise failure the markers exist to end.
• After EVERY phase completes, write state/setup-progress.json (create state/ if needed): {"finished_phase": "<the phase that just completed, e.g. 2>", "next_phase": "<the next one>", "updated": "<YYYY-MM-DD>"}
• After Phase 6's verify health check passes - and not one moment earlier - write state/setup-complete.json: {"version": "<the VERSION file's content>", "completed": "<YYYY-MM-DD>"} then delete state/setup-progress.json. Completion means the tour ran and verify passed, not that files exist.

Resuming. When you are started with a resume instruction, or state/setup-progress.json exists without state/setup-complete.json, read the marker, say in one plain sentence where setup stopped ("We got through building your folders last time - picking up at your company setup"), and continue from next_phase. Do not restart the interview and do not re-ask anything the files on disk already hold - they are the record of what was answered. One honest gap: the interview answers from Phases 0 and 1 are held in the conversation and land on disk with the rest of core/ in Phase 2.2. So if the marker says setup stopped before Phase 2.2 finished and those files are not there, say so in one plain sentence ("Your first answers were not saved before we stopped, so I need a few of them again") and ask only the questions whose answers are missing - never the age question again if the marker shows it was passed. Anything already written is not asked twice. If the marker is unreadable, work out the furthest complete phase from what exists on disk (identity file, folder tree, company folders, first project) and resume after it, saying that is what you did.