Docs Kit
Templates, generators, and checklists that scaffold your project docs and execution scripts. Use this page when you are setting up a new project or adding structure to an existing one.
How this differs from Activator
The Docs Kit gives you the raw materials: doc templates, generator prompts, and checklists. The Activator runs production scripts that produce verified commits. Start with the Start page if you are new.
Key idea
The three scripts I start with
These are the three blocks I paste at the beginning of every project. The first one goes into ChatGPT. The second goes into Claude. The third is what I expect back when the work is done.
1. Operator Mode activator (ChatGPT)
Paste this into your first ChatGPT session. It sets the ground rules for planning and architecture.
You are operating in AI Founder OS Operator Mode. Your job is to plan, not build. You produce structured task briefs that a coding agent (Claude) will execute. Rules: 1. Every task brief must name the exact files the agent may touch. 2. Every task brief must include a verification step (npm run build, npx tsc --noEmit, or both). 3. Every task brief must specify the commit message format: type(scope): description. 4. Never include code in a task brief. Describe what the code should do. 5. If a task touches more than 3 files, split it into smaller tasks. 6. Each task must be completable in a single commit. 7. If requirements are ambiguous, stop and ask before producing the brief. Output format: TASK: [name] GOAL: [one sentence] HOTSPOT: [file list] DO NOT TOUCH: [file list] REQUIREMENTS: [numbered list] VERIFICATION: [commands] COMMIT: type(scope): description
2. Claude task script (single task, single hotspot)
Paste this into Claude with the blanks filled in from your ChatGPT plan. One task, one commit, one hotspot.
CLAUDE AGENT: [Task Name] Repo: [owner/repo] (Next.js App Router + Tailwind + Clerk) Branch: main GOAL [One sentence. What does "done" look like?] HOTSPOT (files you may edit) - app/[route]/page.tsx DO NOT TOUCH - layout.tsx - any app/api/* - package.json REQUIREMENTS 1. [specific, testable requirement] 2. [specific, testable requirement] 3. [specific, testable requirement] REPO GUARDRAILS - Confirm pwd, remote, branch, and clean working tree before editing. - No new dependencies. - No layout or auth changes. - No "bonus" improvements outside the requirements. VERIFICATION npx tsc --noEmit npm run build COMMIT feat([scope]): [description] OUTPUT Return a HANDOFF PACKET (see template below).
3. Handoff Packet template
This is the exact format you want pasted back at the end of every task. No exceptions.
HANDOFF PACKET ======================================== Summary: - [what changed, 1-3 bullets] Files changed: - [path/to/file.tsx] (new | modified) Verification: npx tsc --noEmit: passed, 0 errors npm run build: passed, 0 errors Commit: [hash] [message] git show --stat HEAD [paste output here] git show --name-only HEAD [paste output here]
Plan in ChatGPT. Execute with Claude. Prove before shipping.
Parallel build setup (3 agents)
When you have three Claude agents running at the same time, you need hard boundaries. No shared files. No overlapping diffs. If two agents touch the same file, one of them will lose work.
Concurrency guardrail block
Paste this at the top of every agent prompt when running more than one agent at a time.
CONCURRENCY MODE: 3 AGENTS Rules: 1. You own your hotspot files. Do not edit anything outside your hotspot. 2. Do not run git add -A. Stage only your hotspot files by name. 3. Do not modify package.json, layout.tsx, middleware.ts, or any shared config. 4. If your task requires a file owned by another agent, stop and report the conflict. 5. Always verify git diff --name-only --cached before committing. 6. If the working tree is not clean when you start, stop and report. Violation of any rule means the task fails. Start over.
Hotspot registry convention
Before you launch agents, write out who owns what. This is the registry format. Every agent gets a copy.
HOTSPOT REGISTRY ======================================== Agent A: - app/toolkit/page.tsx - app/components/DocsKitCard.tsx Agent B: - app/modules/1/page.tsx - app/modules/2/page.tsx Agent C: - app/start/page.tsx - app/components/StartDiagram.tsx Shared (no agent may edit): - app/layout.tsx - middleware.ts - package.json - next.config.ts Conflict resolution: If two agents need the same file, serialize. One agent finishes and pushes. The other pulls and then starts.
Example assignment pattern
A real three-agent split with no overlapping files. Each agent gets its own task, its own files, and its own commit.
PARALLEL TASK ASSIGNMENT
========================================
Agent A: Docs Kit page update
Hotspot: app/toolkit/page.tsx
Commit: feat(toolkit): add starter scripts section
Verify: npx tsc --noEmit && npm run build
Agent B: Module 3 rewrite
Hotspot: app/modules/3/page.tsx
Commit: feat(modules): rewrite module 3 content
Verify: npx tsc --noEmit && npm run build
Agent C: Dashboard nav overhaul
Hotspot: app/dashboard/page.tsx
Commit: feat(dashboard): update navigation layout
Verify: npx tsc --noEmit && npm run build
Execution order:
1. All three agents start at the same time.
2. Each agent confirms clean working tree before editing.
3. Each agent commits and pushes independently.
4. If push fails (remote has new commits), pull --rebase and retry.
5. After all three finish, verify the combined build:
git pull origin main
npx tsc --noEmit
npm run buildDocs that make AI reliable
Without docs in the repo, an AI agent starts every session by guessing. It guesses your stack, your conventions, your file layout, and your rules. Most of the rework people blame on AI is actually caused by missing context.
When the agent reads CLAUDE.md and INVARIANTS.md before touching code, it knows your build commands, your commit format, and your non-negotiable rules. No guessing means fewer mistakes to clean up.
STATE_OF_THE_APP.md tells the agent what exists and what is in progress. FINDINGS_LOG.md tells it what has been tried and what failed. Together, they prevent the agent from re-solving problems or creating conflicts with work that is already done.
HOTSPOTS.md and CONCURRENCY.md divide the codebase into non-overlapping zones. Each agent knows what it owns and what it cannot touch. Without this, two agents editing the same file will produce merge conflicts or silent overwrites.
Universal docs generator prompt
Paste this into ChatGPT. It works for any stack: web, mobile, backend, fullstack, monorepo, or multi-repo. Answer the questions and it produces a complete docs folder you can commit directly.
You are a project documentation generator for AI-assisted development.
Your job is to ask me a short set of questions, then produce a complete
set of markdown files I can commit directly to my repo.
Step 1: Ask me these questions (and only these)
1. Project name
2. One-sentence description
3. Repos (list every repo, mark which is frontend, backend, shared, etc.)
4. Frontend stack: language, framework, styling, key libraries
5. Backend stack (if any): language, framework, ORM, key libraries
6. Deploy target for each repo (Vercel, Render, Railway, AWS, Fly, etc.)
7. Mobile targets (if any): iOS, Android, React Native, Flutter, Expo, etc.
8. Auth approach (Clerk, NextAuth, Supabase Auth, Firebase Auth, custom, none)
9. Data layer (Postgres, Supabase, PlanetScale, SQLite, Firestore, none)
10. Current primary goal (what you are building right now)
11. Non-negotiables (budget, timeline, no new deps, specific rules)
12. Verification commands used in your stack (e.g. npx tsc --noEmit, pytest, go test)
Wait for my answers before generating anything.
Step 2: Generate these files
Produce each file below with full contents tailored to my answers.
Every file must be plain markdown, under 40 lines, and ready to commit.
docs/CLAUDE.md
Project name, repo URLs, stack summary.
Execution rules: one task per commit, minimal diff, confirm repo
state before editing, return a HANDOFF PACKET when done.
Verification commands for this specific stack.
Pointers to the other docs files.
docs/PROJECT_CONTEXT.md
Repos (all of them, with labels), stack per repo, deploy targets,
auth, data layer, team shape. If there are mobile targets, list
platform and toolchain. Facts only, no opinions.
docs/STACK.md
Full stack breakdown per repo: language version, framework version,
key libraries with purpose, package manager, runtime. If mobile,
include device targets, minimum OS versions, and build tools.
docs/ARCHITECTURE.md
High-level folder structure per repo. What lives where.
Conventions (app router vs pages, API route patterns, shared libs).
If multi-repo, explain how they connect.
docs/INVARIANTS.md
Rules that prevent regressions. Auth rules, routing rules, data
rules, proof rules. Include: build and typecheck must pass before
commit. No file edits outside declared hotspot. No new dependencies
without approval.
docs/HOTSPOTS.md
Default hotspot boundaries for single-agent and multi-agent work.
List shared files that no agent may edit without approval.
Staging rule: never git add -A, stage only named files.
docs/VERIFICATION.md
Every verification command for this stack, grouped by type:
typecheck, build, test, lint. Add the rule: all commands must
pass with zero errors before committing. If mobile, include
device build and simulator commands.
docs/HANDOFF_PACKET.md
Template for the handoff format. Sections: summary, files changed,
verification commands and results, commit hash and message,
git show --stat HEAD, git show --name-only HEAD. Include one
filled-in example.
docs/RELEASE_CHECKLIST.md
Pre-release checklist for this stack. Environment variables,
secrets, build command, deploy command, rollback steps, post-deploy
smoke test. If mobile, include app store submission steps and
signing requirements.
Step 3: Suggest file placement
Recommend whether to use a docs/ folder at the repo root or keep
files in the root itself. If there are multiple repos, say which
docs go where. Two sentences maximum.
Step 4: Output format
For each file, output:
Filename: docs/FILENAME.md
(full file contents in a code block)
Output each file separately. No commentary between files.This prompt produces nine files. You can skip any that do not apply (for example, RELEASE_CHECKLIST.md if you are not deploying yet). The important ones to start with are CLAUDE.md, INVARIANTS.md, and VERIFICATION.md.
Docs are the single source of truth. Hotspots keep agents from breaking them.
Docs quality bar
- Docs must be specific. Every file should reference your actual stack, your actual repo, and your actual commands. Generic docs are the same as no docs.
- Docs must have verification. VERIFICATION.md must list the exact commands that prove a change works. If the docs do not say how to verify, agents will skip verification.
- Docs must name hotspots. HOTSPOTS.md must list which files each agent can edit and which files are off limits. Without explicit boundaries, agents wander into shared files and create conflicts.
Project docs kit (universal)
These docs are not for humans. They are for AI agents. Six markdown files live in your repo and tell every model what your project is, what the rules are, and what state things are in. They work with any stack, any language, any framework. Write them by hand using the templates below, or use the generator prompt to produce a set customized to your project.
The six files
- CLAUDE.md Execution rules, build commands, pointers to other docs
- PROJECT_CONTEXT.md Stack, repos, team shape, deploy target
- INVARIANTS.md Rules that prevent regressions
- STATE_OF_THE_APP.md What works, what is broken, what is next
- FINDINGS_LOG.md Decisions, dead ends, things not to repeat
- CONCURRENCY.md Hotspot registry and conflict rules for parallel agents
Docs kit structure
Docs kit generator prompt
Paste this into ChatGPT. Answer the questions it asks and it will produce a complete docs set tailored to your project. Commit the output to your repo and every future agent session starts with accurate context.
You are a project documentation generator for AI-assisted development. Ask me these questions one at a time, then generate my docs: 1. App name 2. Stack type: web, mobile, backend, or fullstack 3. Primary language (TypeScript, Python, Go, etc.) 4. Framework (Next.js, Django, FastAPI, Rails, etc.) 5. Deployment target (Vercel, Railway, AWS, self-hosted, etc.) 6. Auth provider (Clerk, NextAuth, Supabase Auth, none, etc.) 7. Database (Postgres, Supabase, PlanetScale, SQLite, none, etc.) 8. Payment provider (Stripe, Lemon Squeezy, none) 9. Team size and workflow (solo, 2-person, multi-agent, etc.) Wait for my answers before generating anything. Once I answer, produce these files: CLAUDE.md Project name, repo URL, stack summary. Execution rules: one task per commit, minimal diff, confirm repo state before editing, return a HANDOFF PACKET when done. Verification commands for this stack. Pointers to the other docs files. INVARIANTS.md Non-negotiable rules for this project. Auth rules (do not change auth unless the task says to). Routing rules (app router only, no pages router, etc.). Data rules (all state changes through defined API routes, etc.). Proof rules (build and typecheck must pass before commit). Hotspot discipline (only edit declared files, verify staging). STATE_OF_THE_APP.md Current priorities, what works, what is in progress. Known failures and flaky behavior. Active hotspots (files being edited right now). Blockers. FINDINGS_LOG.md Date-stamped entries. Each entry: finding title, context, detail, resolution, affected files. API_CONTRACTS.md (only if the project has backend API routes) List each route: method, path, request shape, response shape, auth requirements, error codes. DEPLOY_PLAYBOOK.md Environment variables needed. Build command. Deploy command or platform config. Rollback steps. Post-deploy smoke test (which URL to hit, what to check). HANDOFF_PACKET_TEMPLATE.txt Plain text template with sections: Task name, date, agent. Summary (1-3 bullets). Files changed. Verification commands and results. Commit hash and message. git show --stat HEAD output. git show --name-only HEAD output. Notes for the next person. Rules for the generated docs: - Keep every file under 40 lines. Short and scannable. - Use the actual stack, language, and tools from my answers. - Do not add generic advice. Every line should be specific. - No arrows or heavy punctuation in the text. - Output each file separately with its filename as a heading.
CLAUDE.md
The first file Claude reads when it opens your repo. It sets the execution rules and points to context.
# CLAUDE.md PROJECT NAME: [your project] REPOS: [owner/repo] STACK: [language, framework, styling, auth, payments, hosting] ## Execution rules - Read INVARIANTS.md before every task. - Read STATE_OF_THE_APP.md for current project state. - Confirm pwd, remote, branch, and clean tree before editing. - One task per commit. No bonus improvements. - Minimal diff only. Do not refactor unrelated code. - Every task ends with a HANDOFF PACKET. VERIFICATION COMMANDS: [e.g. npx tsc --noEmit] [e.g. npm run build] ## Context files - docs/INVARIANTS.md - docs/STATE_OF_THE_APP.md - docs/FINDINGS_LOG.md - docs/CONCURRENCY.md (if running multiple agents)
PROJECT_CONTEXT.md
The facts about your project that do not change often. Stack, repos, who works on it, where it deploys.
# Project Context APP NAME: [your app] REPOS: - [owner/repo] (primary) - [owner/repo-api] (if separate backend) STACK: Language: [e.g. TypeScript] Framework: [e.g. Next.js App Router] Styling: [e.g. Tailwind CSS] Auth: [e.g. Clerk, NextAuth, Supabase Auth] Payments: [e.g. Stripe, none] Database: [e.g. Postgres via Supabase, none] Hosting: [e.g. Vercel, Railway, self-hosted] TEAM: [solo / 2-person / multi-agent] Typical agent count: [1-3] REPO SHAPE: Monorepo: [yes/no] Primary branch: main
INVARIANTS.md
Rules that never change. If an agent breaks one of these, the task fails.
# Invariants NON NEGOTIABLES: - [e.g. npx tsc --noEmit must pass before every commit] - [e.g. npm run build must pass before every push] - No new dependencies without explicit approval. - No changes to auth, middleware, or payment logic unless the task requires it. - No file edits outside the declared hotspot. AUTH RULES: - [e.g. All protected routes go through Clerk middleware] - [e.g. Never expose user tokens in client components] ROUTING RULES: - [e.g. App Router only, no Pages Router] - [e.g. All API routes return JSON] DATA RULES: - [e.g. All state changes go through API routes, not direct DB calls from components] - [e.g. Stripe webhooks are the source of truth for payment state] PROOF RULES: - Every task produces a HANDOFF PACKET. No exceptions. - Commit format: type(scope): description - git add only declared hotspot files. Never git add -A. - Verify with git diff --name-only --cached before committing.
STATE_OF_THE_APP.md
A living snapshot. Update it after every meaningful change so the next session starts with real context instead of guessing.
# State of the App Last updated: YYYY-MM-DD Branch: main Last commit: [hash] [message] CURRENT PRIORITY: [one sentence: what should be done next] ## What works - [route or feature that is live and verified] - [route or feature that is live and verified] ## What is in progress - [feature]: [status, who is working on it] KNOWN FAILURES: - [failing test, broken route, or flaky behavior] HOTSPOTS: - [files currently being edited or recently changed] ## Blockers - [anything preventing progress]
FINDINGS_LOG.md
A running log of things you discover while building. Bugs, workarounds, dead ends. Write it down so you do not solve the same problem twice.
# Findings Log ## YYYY-MM-DD: [short title] CONTEXT: [what you were doing when you found it] DETAIL: [what happened vs. what you expected] ROOT CAUSE: [why it happened, if known] FIX: [what you did about it, or "unresolved"] PROOF: [build output, test result, or commit hash] AFFECTED FILES: [list] ## YYYY-MM-DD: [short title] CONTEXT: DETAIL: ROOT CAUSE: FIX: PROOF: AFFECTED FILES:
CONCURRENCY.md
Use this when you have more than one agent working at the same time. Every agent gets a copy so there are no surprises.
# Concurrency HOTSPOT REGISTRY: Agent A: [file list] Agent B: [file list] Agent C: [file list] SHARED FILES (no agent may edit): - [e.g. layout.tsx] - [e.g. middleware.ts] - [e.g. package.json] NO-OVERLAP RULE: If two agents need the same file, serialize the work. One agent finishes and pushes. The other pulls, then starts. STAGING RULE: Do not run git add -A. Stage only your hotspot files by name. Verify with git diff --name-only --cached before committing. CONFLICT PROTOCOL: If your task requires a file owned by another agent, stop and report the conflict. Do not proceed.
How to adopt this in 10 minutes
- 1. Create a docs folder at the root of your repo. Or put the files in the repo root if you prefer a flat layout. Either way works.
- 2. Add these files using the templates above, or paste the generator prompt into ChatGPT to get a version customized to your stack.
- 3. Fill in your current state in STATE_OF_THE_APP.md. List what works, what is broken, and what you plan to do next.
- 4. Enforce handoffs by requiring every task (human or AI) to end with a completed HANDOFF PACKET. No packet, no merge.
How these evolve
These files are not static. They change as your project changes. Here is how each one grows over time.
- Rules become invariants. When you notice the same mistake happening twice, write the rule that prevents it. Put it in INVARIANTS.md and it stops happening.
- Repeated bugs become checklists. If something keeps breaking after a certain kind of change, turn the fix sequence into a checklist in FINDINGS_LOG.md so the next agent (or future-you) runs through it automatically.
- Hotspots grow as the app grows. Your CONCURRENCY.md file starts with three or four files per agent. After a month, each agent might own a dozen. Update the registry every time you add significant new files.
- State gets updated every time you ship. After every meaningful commit, spend 30 seconds updating STATE_OF_THE_APP.md. The next session starts clean instead of with a stale context window.
- Project context rarely changes. PROJECT_CONTEXT.md only needs updates when you add a new repo, change your deploy target, or switch a major dependency. Maybe once a month.
The docs you use after 30 days of building should look different from the ones you started with. That means the system is working.
Operator Mode
Paste this into your first session. It sets the ground rules so the AI knows how you expect it to work. New here? The start page walks through setup and your first two scripts.
The operator loop
This is the loop you repeat for every feature.
Core Activation Script
You are operating in AI Founder OS mode. Follow these rules: Never write code without a defined file target. All changes must be minimal diff. Every task must produce a HANDOFF PACKET. All git proofs must include: git show --stat HEAD git show --name-only HEAD Never modify files outside the defined hotspot. If requirements are unclear, stop and ask. Output must be copy-safe and plain text. Before executing any task: Confirm repo path Confirm branch Confirm working tree state Discipline over speed.
Works with ChatGPT, Claude, and most other models. Just paste it at the start of a session.
Multi-Agent Guardrail Script
MULTI-AGENT MODE ENABLED Rules: Each agent owns a hotspot. No cross-file edits. One issue per agent. No "bonus" improvements. Each agent must include: Summary Files changed Verification commands run git show --stat HEAD git show --name-only HEAD If another agent modifies a shared file, stop and reconcile before continuing. No silent conflicts. No overlapping diffs. No hidden edits.
Useful when you have two agents working at the same time, or any refactor that touches more than a few files.
Continuity Packet Templates
When you come back to a project after a break, or hand it off to someone else, you need context. These templates capture where things stand so you can pick up without guessing.
CONTINUITY PACKET: [Project Name] ======================================== Date: YYYY-MM-DD Branch: main Last Commit: <hash> <message> ## Current State - Route structure: ... - Auth: Clerk (middleware.ts) - Payments: Stripe (webhook verified) ## Blockers - [ ] ... ## Next Actions 1. ... 2. ... 3. ...
Claude Execution Prompt Templates
These are the prompts I actually reuse. Fill in the blanks, paste into Claude, and you get scoped diffs back.
CLAUDE AGENT: [Task Name] You are Claude Opus. Repo: [repo] (Next.js App Router + Tailwind + Clerk). GOAL [1-sentence objective] FILES YOU MAY TOUCH - app/[route]/page.tsx - app/components/[Component].tsx DO NOT TOUCH - layout.tsx (unless noted) - any app/api/* - package.json REQUIREMENTS 1. ... 2. ... 3. ... VERIFICATION npm run build must pass. COMMIT feat([scope]): [description] OUTPUT Return HANDOFF PACKET with git show --stat HEAD.
Verification Checklists
Short checklists to run before you commit. They catch the kind of mistakes that pile up quietly if you skip them.
Repo & Release Guardrails
Some conventions that help once you have multiple branches or more than one agent working in the same repo.
REPO GUARDRAILS ======================================== Branch: feat/[scope]-[slug] Commit: type(scope): description PR: Requires build pass + 1 review PRE-PUSH HOOK npm run build && echo "Gate passed" HOTSPOT REGISTRY (concurrent agents) Agent 1: app/page.tsx, app/components/* Agent 2: app/api/*, lib/* Conflict? Serialize. Never parallel-write. RELEASE CHECKLIST [ ] .env.local matches .env.example [ ] Secrets rotated if leaked [ ] Rollback plan documented
Debug Playbooks
When something breaks, the instinct is to start rewriting. These keep you focused on finding the actual cause first.
Model Selection Guide
Not every task needs the strongest model. Cheaper ones handle simple work just fine. Here is a rough guide.
HANDOFF Packet
A short packet you produce at the end of each task. It proves what changed, that the build passed, and makes it easy to pick up later.
HANDOFF PACKET ======================================== pwd: /path/to/repo git remote -v: origin git@github.com:org/repo.git git branch: main git status --short: (clean) Summary: - [what changed, 1-3 bullets] Files changed: - path/to/file.tsx (new | modified) Verification: npm run build: passed, 0 errors git show --stat HEAD: path/to/file.tsx | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) git show --name-only HEAD: path/to/file.tsx
Shipping task script
When you are ready to deploy, use this as your Claude execution script. It enforces the same discipline as your feature scripts but adds release-specific proof lines.
CLAUDE TASK: Ship [feature/fix] to production Repo: [owner/repo] Branch: main Deploy target: [Vercel / TestFlight / Railway / other] HOTSPOT (files you may edit) - [file list] DO NOT TOUCH - layout.tsx - middleware.ts - package.json (unless adding a required dep) PRE-DEPLOY CHECKLIST 1. All env vars confirmed in deploy target settings 2. npx tsc --noEmit passes 3. npm run build passes 4. Preview deploy verified (or TestFlight installed on real device) REQUIREMENTS 1. One issue per commit 2. Minimal diff only 3. [specific requirement] 4. [specific requirement] VERIFICATION npx tsc --noEmit npm run build [any smoke test command] RELEASE PROOF After deploy completes, confirm: - Production URL responds with 200 - Auth flow works end to end - No console errors on first load COMMIT feat([scope]): [description] OUTPUT Return HANDOFF PACKET with: Summary Files changed Verification results Release proof (URL checked, status code) git show --stat HEAD git show --name-only HEAD
TEXTSAFE Output Mode
Add this to the end of a prompt when you want plain text output with no markdown formatting.
OUTPUT (TEXTSAFE, NO MARKDOWN) Return HANDOFF PACKET with: pwd git remote -v git branch --show-current git status --short Summary Files changed Verification results Paste literal: git show --stat HEAD git show --name-only HEAD