--- name: bootstrap-agentic-os description: Interview the user about a project, then create the scaffolding for an agentic operating system around it — CLAUDE.md, CONTEXT.md, .claude/start-session.md, .claude/wrap-session.md, and a sensible .claude/settings.json permission scheme. Use when the user runs /bootstrap-agentic-os or asks to set up agentic-OS scaffolding, session lifecycle docs, or CLAUDE.md + CONTEXT.md structure in a project. --- # Bootstrap agentic OS This skill sets up the scaffolding that makes Claude Code useful across many sessions on a single project: a session lifecycle (start + wrap), a separation between stable reference (CLAUDE.md) and running state (CONTEXT.md), and a sensible permission scheme. The skill **interviews the user** to gather real project details, then writes substantive files based on the answers — not empty templates. --- ## Step 1 — Confirm and detect 1. Confirm the working directory is the project root. Good signals: presence of `.git/`, `README.md`, `package.json`, `pyproject.toml`, `Cargo.toml`, `go.mod`. If unclear, ask the user before proceeding. 2. Check for existing files this skill would write: - `CLAUDE.md` - `CONTEXT.md` - `.claude/start-session.md` - `.claude/wrap-session.md` - `.claude/settings.json` If any exist, STOP and ask the user how to proceed: - **Overwrite** (show them what would change first) - **Merge / append** (read the existing file, run the interview, propose additions, confirm before writing) - **Abort** Do not clobber existing files silently. 3. Detect what's free before asking — don't ask things you can find out: - `git remote -v` (repo URL, visibility hint) - `package.json` / `pyproject.toml` / `Cargo.toml` / `go.mod` (language, framework) - One `ls` at root (directory layout) - `README.md` if present (existing self-description — may seed the "what we're building" section) --- ## Step 2 — Interview Ask in conversational clusters, not one question at a time. Wait for each cluster's answer before moving on. Skip questions you can answer from detection. If a cluster only has one applicable question, ask just that one. Use plain conversational questions. Don't use AskUserQuestion's structured-choice format unless the question is genuinely multiple-choice. ### Cluster 1 — What this is - What's the project called? - In 1–3 sentences, what is it? (What you're building, who it's for, what makes it distinctive.) ### Cluster 2 — Where you are - What's the build target right now? (e.g., exploration, prototype, MVP, closed beta, full launch, open-ended hobby project) — and what's explicitly *out* of scope for now? - What's the immediate next thing to get working? (This becomes "current focus" in CONTEXT.md.) ### Cluster 3 — Stack and structure (skip what was detected) - Frontend / backend / database / hosting choices that are made? - Anything else in the stack that matters but isn't visible in the filesystem (deploy targets, third-party services, planned-but-not-yet-installed dependencies)? - **Is there a dev server or main run command?** If yes: what is it, and what ports does it use? (Determines whether start-session.md and wrap-session.md include server-check / server-stop steps.) ### Cluster 4 — Source materials - Are there existing design docs, specs, or reference materials this project should treat as authoritative? Where do they live (folder paths)? - Is there a single document that captures the strategic plan or vision? (Becomes a "read this when context on a decision is needed" pointer in CLAUDE.md.) ### Cluster 5 — How you work (always ask) - How do you want me to treat you in build sessions? (Examples: "I'm not a coder — explain things in plain language and don't run setup commands without confirming"; "I'm a software engineer — skip basic explanations"; "Somewhere in between — flag non-obvious stuff but assume technical fluency".) This becomes the meta-rule at the top of `.claude/start-session.md` and `.claude/wrap-session.md`. ### Cluster 6 — Conventions and constraints (optional) - Any build patterns or constraints worth recording up front? (e.g., "no real money in this demo", "everything goes through abstraction X", "deploy portability matters") - Any decisions already settled that future sessions should know about? If the user says "nothing yet" to cluster 6, skip it — these sections build up over time. --- ## Step 3 — Generate files Use interview answers to write **substantive** content. Don't write empty placeholder sections. Only include sections that have real content. Create the `.claude/` directory first if it doesn't exist. ### `CLAUDE.md` Project reference manual. Lead with what's being built. Always include: - Header: one-line "this file is the project's reference manual" framing + pointer to `CONTEXT.md` (explain the split: CLAUDE.md is stable reference, CONTEXT.md is running state). - "What we're building" section (from cluster 1 — substantive paragraphs, not bullets). - "Tech stack" section (from detection + cluster 3 — including the dev server / run command if any). - "Process and project conventions" section — always include. Covers: - Permission scheme: `.claude/settings.json` (committed broad allowlist), `.claude/settings.local.json` (gitignored, per-action approvals). - Per-session orientation pattern: at session start, read CONTEXT.md, state focus / dependencies / what this might affect; see `.claude/start-session.md`. - Per-session documentation pattern: at session end, update CONTEXT.md with what was built, what's tested, what's left, decisions settled; see `.claude/wrap-session.md`. Conditionally include (only if there's content from the interview): - "Build target and scope" (from cluster 2 — what's in / out). - "Project structure" — only if directory layout is non-trivial; otherwise omit until it grows. - "Source of truth" table (from cluster 4 — if user named authoritative docs, build a small markdown table mapping each behavior layer / domain to its source file). - "Design documents" section (from cluster 4 — short list with one-line descriptions). - "Key decisions and patterns" section (from cluster 6). ### `CONTEXT.md` Running log. Initial content: ```markdown # CONTEXT.md Running log of where the build is. Read at session start; update at session end. CLAUDE.md is the stable reference manual; CONTEXT.md is the moving picture. ## Where we are right now [Current focus from cluster 2 — what's the immediate next thing.] ## What's built [Empty or "scaffolding only" for a fresh project. Updated each session.] ## What's left [The immediate next thing + anything else the user named in cluster 2 as in-scope.] ## Open decisions [Anything the user surfaced but didn't settle. If nothing, omit this section.] ## Last session — bootstrap - **Built:** Agentic OS scaffolding — CLAUDE.md, CONTEXT.md, .claude/start-session.md, .claude/wrap-session.md, .claude/settings.json, .gitignore entry for .claude/settings.local.json. - **Tested:** N/A — scaffolding only. - **Next:** Review the generated CLAUDE.md and CONTEXT.md. Adjust anything that doesn't match how I think about the project. Make first commit when ready. - **Decisions settled:** None this session beyond the scaffolding itself. ``` ### `.claude/start-session.md` Use the content below. Substitute `{USER_SKILL_FRAMING}` with the line from cluster 5. If cluster 3 surfaced a dev server / run command, include the **server check** block in step 2; otherwise omit it. ```markdown # Session start Start this work session by orienting yourself, then check with me before acting. Walk through the steps in order. After orienting, give me a brief status report and wait for me to tell you what to work on. Don't start changing code or running setup commands until I've confirmed direction. ## Meta-rules - {USER_SKILL_FRAMING} - If you encounter unfamiliar state (open merges, conflicts, detached HEAD, files you don't recognize, processes already running, missing setup files) — surface it clearly and ask how I want to handle it. Don't try to fix things silently. - Don't start servers, install dependencies, or run any setup commands without confirming first. ## 1. Read the orientation docs - `CONTEXT.md` from the repo root — the running log of build state. (CLAUDE.md loads automatically — no need to read it explicitly.) ## 2. Check current state (in parallel) - `git log --oneline -10` (recent commit history) - `git status` (no `-uall`) (uncommitted state) - `git branch --show-current` and `git worktree list` (where we are) - `git log origin/main..main --oneline` (any commits sitting unpushed from last session) [CONDITIONAL: if dev server exists, add:] - `lsof -i :{PORT} -P -n` (is the dev server running?) ## 3. Spot-check for unusual state Flag anything that needs attention before we start: - Uncommitted changes from a previous session (working tree not clean) - Open git operations in progress (merge, rebase, conflicts) - Detached HEAD or branch state you don't recognize [CONDITIONAL: if dev server exists, add:] - Dev server running unexpectedly - Any mismatch between what CONTEXT.md says is "done" and what's actually in the code If any of these turn up, surface them clearly and ask how I want to handle them. ## 4. Status report Give me a short report (6–10 lines): - Where we are: current branch, in a worktree or in the main repo - What was last done: the most recent commit + a one-line plain-English summary based on CONTEXT.md's current state - What's on deck: what CONTEXT.md says is "in progress" or queued next - Backup status: are there unpushed commits? Mention but don't push. - Anything unusual flagged in step 3 - Your read of what we'd most naturally work on next, based on CONTEXT.md, framed as a suggestion I can redirect ## 5. Wait for direction Tell me what you'd suggest working on next, then wait. I might want to follow the suggestion or do something completely different. Don't start writing code, installing things, or starting servers until I've confirmed. If I say "let's go" or similar without naming a task, treat that as confirmation of your suggestion. ``` ### `.claude/wrap-session.md` Use the content below. Substitute `{USER_SKILL_FRAMING}` as above. If cluster 3 surfaced a dev server, include the "Stop the dev server" step (number it appropriately — between cleanup and final state report); otherwise omit it. ```markdown # Session wrap End this work session cleanly. Goals: working tree clean and safe, CONTEXT.md and CLAUDE.md reflect what was done, and if we're in a worktree, the work is merged back to main. Walk through the steps in order. At each decision point, propose what you'd do and confirm with me before acting. Don't push to any remote unless I explicitly ask. ## Meta-rules - {USER_SKILL_FRAMING} - If you encounter unfamiliar git state (merge in progress, rebase in progress, detached HEAD, conflicts, branches you don't recognize) — STOP and ask. Don't try to fix it autonomously. - Never run destructive git commands (reset --hard, push --force, branch -D, clean -f) unless I explicitly ask. ## 1. Orient Run in parallel: - `git status` (no `-uall`) and `git log --oneline -8` - `git branch --show-current` and `git worktree list` - `git remote -v` (for the backup-status check at the end) [CONDITIONAL: if dev server exists, add:] - `lsof -i :{PORT} -P -n` (dev server check) Read CONTEXT.md and CLAUDE.md so you know what each doc currently claims. Tell me in 3–6 lines: branch, what's uncommitted, whether we're in a worktree, [if dev server: whether it's running,] and whether anything looks unusual or unsafe to proceed without me. ## 2. Update CONTEXT.md and CLAUDE.md CONTEXT.md tracks where we are in the build (almost always updates). CLAUDE.md is the project's reference manual — what we're building, the tech stack, key decisions and patterns. It updates whenever this session changed those facts (more often than you'd think). Capture for CONTEXT.md: - **What was built this session** — concrete: which files added or changed, which pieces completed or partially completed. - **What was tested and works (and how)** — be specific. "I clicked through X and confirmed Y" is useful. "It works" is not. Mark untested pieces explicitly as untested. - **What's left for next session** — the next concrete thing the session picking this up should focus on. Practical, not aspirational. - **Any decisions that came up that we settled, with the reason** — decisions made mid-session that don't yet appear in CLAUDE.md. These often get lost; capture them here. If a decision is big enough that it should also be in CLAUDE.md, flag it so the CLAUDE.md walk below picks it up. For CLAUDE.md — walk each section and update if today's work outpaced it. Show me the proposed edits to both files. Wait for confirmation before writing. ## 3. Pre-commit safety review and commit If the working tree is already clean, skip this step. ### 3a. Safety scan Run the checks below before staging anything. The first three are STOP conditions — if any fails, halt and report; do not commit until I've decided how to proceed. **Repository visibility.** Run `gh repo view --json visibility` if the gh CLI is available; otherwise read `git remote -v` and tell me the remote URL so I can verify visibility manually. If the repo is PUBLIC and this is a private project, STOP and tell me. **Sensitive files in tracked set.** Run `git ls-files | grep -iE "(\.env|secret|credential|api[_-]?key)"`. If anything matches, STOP — git is tracking files that look sensitive. **Untracked but substantive content.** Run `git ls-files --others --exclude-standard`. Anything left is on disk but not tracked. STOP and ask if you see substantive-looking content (`.md`, `.docx`, `.xlsx`, `.pdf`, etc.) that wasn't part of this session's work. Then review every changed and new file in this session's diff. Flag and ask before proceeding if you find: - Secrets in the diff content (API keys, passwords, tokens, .env contents) - Unusually large files (>1MB), especially binaries - Debug code — stray console.log / print() / "TEMP DEBUG" markers - Files that don't seem related to the session's work ### 3b. Commit Propose commits, titled in the existing style — match the recent commit message style you see in `git log`. Stage files explicitly by name. Never `git add -A` or `git add .`. Use HEREDOC for messages. Wait for confirmation before committing. ## 4. Merge to main (skip if already on `main`) If the current branch is not `main`, the work needs to merge into main. Verify it's a clean fast-forward: - `git log --oneline main..HEAD` should show the new commits - `git log --oneline HEAD..main` should be empty If `HEAD..main` is NOT empty, STOP — main has moved forward and a non-trivial merge is needed. Otherwise propose the fast-forward merge. Wait for confirmation. Then: - `git worktree prune` for stale worktree entries - `git branch --merged main` — ask whether to delete any merged branches ## 5. Clean up redundant files Look at the diff for things this session may have left behind: - Debug logs (added console.log, print, "TEMP DEBUG" markers) - Duplicate assets - Temp files in the repo (scratch.md, test.txt, output.log) - Dead code (functions or imports added but no longer referenced) List candidates with one-line "why this looks redundant" explanations. Ask before deleting. [CONDITIONAL: if dev server exists, insert here as step 6:] ## 6. Stop the dev server Kill any processes on port {PORT} (and any other dev-related ports). Also kill orphan parent processes (e.g., `concurrently`, `node --watch`) — these don't always die when their children do. Verify with `lsof` and `ps aux | grep` afterward that nothing is left. ## {6 or 7}. Final state report Tell me: - Latest commit hash and title on main - Working tree status — clean, or what's intentionally left untracked, with one-line explanations for anything left [CONDITIONAL: if dev server:] - Dev server confirmed down (port {PORT} free, no orphan processes) - **Backup status**: is main's latest commit pushed to the remote? Run `git log origin/main..main --oneline` — if non-empty, your work currently only lives on this laptop and would be lost if the laptop dies. Surface this and ask whether I want to push (but DON'T push unless I say yes). - Two-sentence summary of where the next session picks up. **If I say yes to pushing**: before actually running `git push`, show me the review: - `git log origin/main..main --oneline` — the commits about to be pushed - `git diff origin/main..main --stat` — which files those commits touched Wait for me to confirm a second time after seeing the review. Then push. ``` ### `.claude/settings.json` Write this exact content: ```json { "permissions": { "allow": [ "Read", "Edit", "Write", "Bash(git status:*)", "Bash(git diff:*)", "Bash(git log:*)", "Bash(git add:*)", "Bash(git commit:*)", "Bash(git branch:*)", "Bash(git show:*)", "Bash(git remote:*)", "Bash(git worktree:*)", "Bash(git ls-files:*)", "Bash(ls:*)", "Bash(grep:*)", "Bash(find:*)", "Bash(mkdir:*)", "Bash(pwd:*)", "Bash(lsof:*)" ] } } ``` ### `.gitignore` Append `.claude/settings.local.json` if not already present. If `.gitignore` doesn't exist, create it with that single line. Don't add anything else — the user's stack determines the rest. --- ## Step 4 — Wrap up Tell the user, in plain language: - **What was created**, listed with relative paths (CLAUDE.md, CONTEXT.md, .claude/start-session.md, .claude/wrap-session.md, .claude/settings.json, .gitignore updated). - **What to review first**: CLAUDE.md and CONTEXT.md. These are substantive, generated from the interview — worth reading and adjusting anything that doesn't match how the user thinks about the project. - **What to do next**: - Review the generated files. - Make the first commit when ready (the skill does NOT commit on the user's behalf). - From the next session forward: at session start, follow `.claude/start-session.md`; at session end, follow `.claude/wrap-session.md`. Do **not** run any git commands. Do **not** make any commits. Leave the working tree in a state the user can inspect and commit themselves. --- ## Notes on running the skill - This skill is invocation-time interactive — wait for user answers, don't fabricate them. - If the user gives a one-word answer where context is needed, ask one focused follow-up rather than guessing. - Resist over-engineering the generated CLAUDE.md. Sections build up over time — don't pre-create empty placeholder sections "for later". - The standard content of `start-session.md`, `wrap-session.md`, and `settings.json` is identical across projects except for the `{USER_SKILL_FRAMING}` substitution and the dev-server conditional. Only `CLAUDE.md` and `CONTEXT.md` are personalized from the interview. - If the user has an existing `README.md` with strong self-description, use it to seed the "what we're building" section but still confirm with the user before writing — README text is often outdated.