I want to build something and need help thinking it through before writing any code.
My rough idea: [describe your idea in 2–3 sentences]

Here is what I already know about it:
- The one thing it must do: [your one sentence]
- Who uses it: [yourself / a team / customers / the public]
- Interface I'm imagining: [dashboard / chat / map / form / report / other]
- Data it works with: [what it stores, reads, or connects to — or "not sure yet"]
- Core formula or logic (if any): [describe any calculation, scoring, or rule at the center]
- Things it must NOT do: [scope limits, complexity to avoid, trust boundaries]

Act as a requirements engineer. Use what I've shared as a starting point and interview
me to fill in everything else. Ask ONE question at a time and wait for my answer.

Cover anything not already addressed: specific features for the first working version;
what a successful outcome looks like concretely; data, privacy, and security implications;
external services or APIs needed; what "done" looks like for this first version.

When the interview is complete, update the Requirements section of CLAUDE.md with
everything we established. Note anything I should revisit as the project evolves.
Confirm when CLAUDE.md has been updated.

Read the requirements in CLAUDE.md.

Act as a software architect. Design the complete technical architecture for this system.
I am not a programmer — explain reasoning in plain language alongside technical terms.

Cover: the major components and what each does; how they connect and communicate; where
data is stored and why; technology choices with reasoning and alternatives considered;
the user's complete journey step by step; security and privacy — where sensitive data
lives and how it's protected; the biggest technical risks and how the design handles
them; what I will NOT be able to easily change once building starts.

At the end, present the 3–5 most significant design tradeoffs. For each: what you
chose, what you didn't, and why. I want to consciously agree before we proceed.
Then update the Architecture section of CLAUDE.md and confirm.

Read CLAUDE.md. Based on the requirements and architecture there:

Define the MVP — the smallest version that is genuinely useful and worth building first.
1. Propose what the MVP includes: specific features and components for the first version.
2. Propose what the MVP excludes: desirable features that should wait.
3. For anything uncertain, ask me directly — one item at a time.
4. Once we've agreed: update the MVP Scope section of CLAUDE.md with the final list —
   IN (one-line reason each), OUT (one-line reason each), and one sentence describing
   exactly what this MVP does. Confirm when done.

Read CLAUDE.md. Based on the requirements, architecture, and MVP scope there:

Create a phased Build Plan for implementing this MVP.
Each phase must: have a name and single clear goal; list the specific components being
built; define concrete done criteria — specific things I can test or observe, not vague
descriptions; note what must be true before this phase begins; flag risks specific to
this phase.

Order phases so Phase 1 is the smallest possible working skeleton; each subsequent
phase adds one discrete layer; no phase begins until the previous phase's done
criteria are fully met. Note any decisions I must make before each phase begins.

Update the Build Plan section of CLAUDE.md with the complete plan. Confirm when done.

Read CLAUDE.md. You have updated it with requirements, architecture, MVP scope, and
build plan during Steps 1–4. Now finalize it:

1. Add the Session Protocol section with this exact text:
   "Before every session: Read this file. Identify the current Build Plan phase.
   State today's goal in one sentence. Tell me if anything in this file looks wrong
   or out of date before we begin.
   During every session: Stay on the current Build Plan phase. Record failures in
   Debugging History immediately. Update CLAUDE.md directly — do not wait until the end.
   After every session: Update Current State, Build Plan status, What's Next, and
   add a Session Log entry."

2. Set the Current State section to reflect that nothing is built yet.

3. Mark Phase 1 of the Build Plan as the active phase.

4. Confirm CLAUDE.md is complete by telling me:
   — What this project does in one sentence
   — What Phase 1 is and what its done criteria are
   — Any sections still containing placeholder text that I need to fill in

The project is ready to build.

Read CLAUDE.md. If you cannot find it, stop and tell me before doing anything else.

Confirm:
1. What this project is in one sentence.
2. Which Build Plan phase we are currently in and its done criteria.
3. Any Critical Constraints relevant to today's work.
4. Today's goal: [YOUR ONE-SENTENCE GOAL FOR THIS SESSION]

Do not begin work until I confirm your understanding is correct.

Read CLAUDE.md. We are working on: [current phase name and goal]

Build the next component: [describe the specific thing being built this iteration]

When done:
1. Tell me what files you created or changed and what each one does.
2. Give me the exact terminal commands to start the app and test this — copy-paste
   ready, nothing assumed. Include any environment setup needed.
3. Tell me exactly what I should see or do to confirm it's working correctly.
4. Tell me what failure looks like so I know the difference.
5. Update Current State in CLAUDE.md to reflect what now works.

Stop. Today's goal is: [restate the one-sentence goal]
Current Build Plan phase: [phase name]

What you just proposed touches [describe what drifted]. That is not in scope today.

Either: redo your proposal to achieve today's goal without touching out-of-scope
components — or make the case for why these two things genuinely can't be separated
so I can decide whether to expand scope deliberately.
Do not make the change silently. Present the option and wait.

Before writing any code for this integration, go to: [official documentation URL]
Read the current implementation guide for [specific feature].

Find and report: current authentication method; exact endpoints needed; required
request format and parameters; response format and how to handle it; rate limits
or quotas; any recent breaking changes or deprecated patterns.

If anything conflicts with what you might assume from older knowledge, flag it.
Only write code after I confirm your understanding of the current docs.

This session is ending. Update CLAUDE.md directly with the following:

1. CURRENT STATE — what is now confirmed working; what is broken or newly discovered
   to be broken; what is still unknown.
2. BUILD PLAN — mark the current phase Complete if done criteria were met and activate
   the next phase. If not complete, note what remains and any blockers.
3. DEBUGGING HISTORY — add a row for anything that failed this session: what was
   tried, what happened, root cause if known.
4. LOCKED DESIGN DECISIONS — add any new architectural decisions made today with
   their reasoning.
5. WHAT'S NEXT — the first thing the next session should do.
6. SESSION LOG — add an entry for today:
   Phase / Attempted / Succeeded / Failed / New constraints / Plan changes.

Write all updates to CLAUDE.md now. Confirm when done.

Stop all changes. This session has gone off the rails.
Without making any further modifications:

1. List every change made to the codebase in this session, in order.
2. Identify what you believe is currently broken and your best theory why.
3. Identify the last point in this session where everything was working.
4. Propose the minimum rollback needed to return to that working state — not to
   fix everything, just to reach stable ground.

Once I confirm the rollback, I'll decide whether to continue or end the session
and capture what we learned.

I'm not sure what to do next. Do not write any code.
Read CLAUDE.md and review the current project state.

Give me an honest assessment:
1. What is the highest-priority broken thing right now?
2. What is the highest-value next thing to build, assuming nothing is broken?
3. Is there anything I'm ignoring that will become a serious problem later?
4. Is the Build Plan sequence still correct, or should it be reordered?

Be direct. If I should slow down or consolidate before building more, say so.

This is a consolidation session. We are not building anything.
Goal: make CLAUDE.md accurately reflect the current state of the project.

Read CLAUDE.md and examine all files in this project folder.

1. ARCHITECTURE AUDIT — does the Architecture Overview match what was actually
   built, or has it drifted? Identify gaps.
2. BUILD PLAN AUDIT — which phases are genuinely complete? Which are partial?
   Should the sequence be reordered given what we now know?
3. CONSTRAINTS AUDIT — are there rules in the code not yet documented in
   Critical Constraints or Locked Decisions?
4. CURRENT STATE — produce an accurate Current State based on reality, not intent.
5. WHAT'S NEXT — propose a clean priority list for the next phase.

Output the revised CLAUDE.md sections. I will review and apply them.

Create a file called CLAUDE.md in this project folder using the template on the
following page of the Playbook. Copy the entire template block and include it
after this instruction.

For every [bracketed section]: leave the placeholder text exactly as written —
we will fill it in during Steps 1–4 of the Playbook.

Set up the file now. Confirm the path when done.

Assign port numbers for this project so they don't conflict with my other projects.
My other projects use these ports: [list ports already in use, or "none yet"]

Pick an available port for:
- The frontend (the UI I open in a browser)
- The backend API server
- Any database, if applicable

Use these ports consistently throughout the project. Update CLAUDE.md under
"Running the Project" with the local URLs. Never change these ports without
updating CLAUDE.md and telling me.

Set up environment variable handling for this project.

1. Create a .env file in the project root with placeholder entries for
   every API key or secret this project will need:
   [list the services: e.g., OpenAI, Stripe, database, etc.]

2. Create a .env.example file with the same keys but empty values —
   this is safe to commit and shows collaborators what keys are needed.

3. Ensure .env is in .gitignore so it can never be accidentally committed.

4. Configure the application to read these values from the environment,
   never hardcoded in source files.

5. Add the variable names (not values) to CLAUDE.md under "Running the Project."

I have multiple projects and need to organize them cleanly.

Projects: [list each project and what it does in one line]
Parent folder: [e.g., ~/projects/ or ~/Documents/dev/]

For each project:
1. Create its folder under the parent if it doesn't exist.
2. Create a minimal CLAUDE.md stub with the project name and a one-sentence description.
3. Create a .env placeholder and .gitignore.
4. Assign a unique port range (frontend + backend) that doesn't conflict across projects.

Produce a summary table showing: project name, folder path, frontend port,
backend port. I'll refer to this when starting sessions.

Set up git version control for this project.

1. Initialize a git repository if one doesn't exist.
2. Create a .gitignore that excludes: node_modules, .env, any file containing
   API keys or secrets, build output folders (dist/, build/, __pycache__/),
   log files, and OS files (.DS_Store, Thumbs.db).
3. Make an initial commit of all current project files with the message:
   "Initial commit — [project name] project scaffold"
4. Confirm the repository is initialized and the first commit is recorded.

From this point forward: after every working session, commit all changes
with a clear descriptive message summarizing what was built or fixed.

Push this project to GitHub for cloud backup.

My GitHub username: [your username]
Repository name: [project-name — lowercase, hyphens not spaces]
Visibility: [private (recommended) or public]

1. Guide me through creating the repository on github.com if it doesn't exist.
2. Add the GitHub remote to this local repository.
3. Push the current branch and all commits.
4. Confirm the push succeeded.

From this point forward: after every local commit, also push to GitHub so
the cloud backup stays current.

Commit all changes from this session and push to GitHub.

Write a commit message that clearly describes what was built or changed today.
Format: "[type]: [description]"
Types: feat (new feature), fix (bug fix), refactor (restructure), docs (documentation)
Example: "feat: add audio playback controls to interview screen"

1. Stage all changed files.
2. Commit with the descriptive message.
3. Push to GitHub.
4. Confirm the commit hash and what files were included.

Something from this session has broken the project and I want to roll back.

1. Show me the last 10 commits with their messages and dates.
2. Identify which commit is most likely the last working state based on
   the session log and what we attempted today.
3. Tell me exactly what will be lost if I roll back to that commit.
4. If I confirm, perform the rollback.

Do not roll back until I explicitly confirm after seeing what will be lost.

Perform an objective audit of this codebase. Do not write any code or make any changes.

Examine every file and report findings under four categories:

1. SECURITY
   — Hardcoded API keys, passwords, or secrets anywhere in source files
   — User inputs that are passed to a database or shell without validation
   — Endpoints or routes that are accessible without authentication and shouldn't be
   — Sensitive data stored or transmitted without encryption
   — Dependencies with known vulnerabilities

2. ARCHITECTURAL WEAKNESSES
   — Components that do too many unrelated things (should be split)
   — Missing error handling — places where a failure will silently break something
   — Assumptions that will fail under real-world conditions (e.g., assumes fast network,
     assumes single user, assumes data always exists)
   — Circular dependencies or tight coupling that makes future changes risky

3. BLOAT & DEAD CODE
   — Functions, files, or routes that are defined but never called
   — Duplicate logic that exists in more than one place
   — Dependencies installed but not used
   — Over-engineered solutions for simple problems

4. TECHNICAL DEBT
   — Shortcuts taken that will cause problems at scale or with more users
   — Places where error messages are swallowed instead of surfaced
   — TODO comments or placeholder logic still in production paths
   — Inconsistent patterns that will confuse future development

For each finding: name the file and line, describe the problem, rate severity
(Critical / High / Medium / Low), and recommend the fix.
Order by severity. Be direct and specific. Do not soften findings.

Audit this project for unnecessary cost and dependency risk. Do not make any changes.

1. DEPENDENCIES — list every external library or package installed.
   For each: what is it used for, is it still actively maintained, could it be
   replaced with a simpler built-in alternative?

2. API CALL EFFICIENCY — identify every place an external API is called.
   For each: how often does it get called, could results be cached, is the
   same data fetched multiple times when once would suffice?

3. ESTIMATED COSTS — for any paid API (AI models, cloud services, payment
   processors), estimate the cost per user action and per month at 100 users
   and at 1,000 users. Flag anything that will scale expensively.

4. SINGLE POINTS OF FAILURE — identify any external dependency where if the
   service goes down, the entire application stops working. Note whether a
   fallback exists.

Report findings with severity and recommended action. Do not fix anything yet.

Based on the audit we just completed, update CLAUDE.md as follows:

1. Add a new section "Known Issues — Audit Findings" listing every issue we decided
   to fix, with severity and the agreed fix approach.

2. Insert the Critical and High severity fixes as the top items in What's Next,
   ahead of any feature work. Security issues are never deferred.

3. Add any new Critical Constraints discovered during the audit — things that must
   never be done in future development.

4. Update the Build Plan to include an "Audit Remediation" phase before the next
   feature phase, covering the Critical and High items.

Output the updated CLAUDE.md sections.