Init Project Structure#

Scaffold a brand-new project with the full structured methodology — slim CLAUDE.md, gitignored CLAUDE.local.md, docs/ tree, plans and recaps directories, plus top-level contract docs.

When to Use#

• Starting a new project from scratch
• User wants the plan/build/recap/document cycle working from day one
• Project needs formal contracts (TECHNICAL-DOCUMENTATION.md, FUNCTIONAL-SPECIFICATIONS.md)

When to Skip (Use slim-claude-md Instead)#

• Solo work, prototypes, libraries that don't need formal contracts
• Projects that just need slim memory without the plan/recap overhead

What This Skill Produces#

• CLAUDE.md — slim router (≤ 300 lines) with hard rules, branch topology, pointer index, common commands, today's state, contracts table, housekeeping protocol, session protocol
• CLAUDE.local.md — gitignored env file with section headers and <paste-here> placeholders
• .gitignore — entry for CLAUDE.local.md (creates .gitignore conservatively if absent)
• docs/ tree: architecture/, features/, plans/, recaps/, plus optional pipeline/ and scripts/
• docs/plans/README.md — explains the plan-as-contract convention
• TECHNICAL-DOCUMENTATION.md — top-level developer-onboarding contract with section scaffolding
• FUNCTIONAL-SPECIFICATIONS.md — top-level user-flow contract with section scaffolding
• docs/STATE-SNAPSHOT.md, docs/BUSINESS-CONTEXT.md, docs/TROUBLESHOOTING.md — empty stubs with headers

Composes with slim-claude-md#

This skill uses slim-claude-md templates as its foundation for CLAUDE.md and CLAUDE.local.md structure. Don't duplicate that work. Read templates from the slim-claude-md skill's references/ directory and substitute placeholders, then layer the contract-doc additions.

Resource Files#

FileWhen to readslim-claude-md/references/CLAUDE.md.templateAlways — base for project CLAUDE.mdslim-claude-md/references/CLAUDE.local.md.templateAlways — base for project CLAUDE.local.mdslim-claude-md/references/housekeeping-protocol.mdAlways — inlined into CLAUDE.mdreferences/CLAUDE-template-simple.mdWhen user picks 2-env topologyreferences/CLAUDE-template-full.mdWhen user picks 3-env topologyreferences/TECHNICAL-DOCUMENTATION-template.mdAlwaysreferences/FUNCTIONAL-SPECIFICATIONS-template.mdAlwaysreferences/docs-plans-README-template.mdAlways — written into docs/plans/README.md

---

Workflow#

1. Pre-flight checks#

bash

[ -f CLAUDE.md ] && wc -l CLAUDE.md && echo "WARNING: CLAUDE.md already exists" || echo "OK: no CLAUDE.md"
[ -f TECHNICAL-DOCUMENTATION.md ] && echo "WARNING: TECHNICAL-DOCUMENTATION.md already exists" || echo "OK"
[ -f FUNCTIONAL-SPECIFICATIONS.md ] && echo "WARNING: FUNCTIONAL-SPECIFICATIONS.md already exists" || echo "OK"
[ -d .git ] && echo "OK: git repo" || echo "WARNING: not a git repo yet"

If any of those exist, stop and ask the user whether to overwrite or abort. Never silently overwrite.

Important — detect existing-code projects with no CLAUDE.md: A project may have substantial code (1,000+ line files, existing API endpoints, working app) but no CLAUDE.md yet. In this case, the pre-flight check says "OK: no CLAUDE.md" but the project is NOT a greenfield startup. Check for existing code:

bash

# Detect if project has substantial existing code
find . -name "*.py" -o -name "*.js" -o -name "*.ts" -o -name "*.tsx" | head -5 | wc -l
# If >0, this is an EXISTING codebase that needs structure, not a new project

If existing code is detected, ask the user: "This project already has code. Do you want to (a) scaffold the methodology around the existing codebase, or (b) treat this as a fresh start and archive the old code?" Default to (a) — the methodology should organize what exists, not replace it.

If .git is missing, ask whether to git init first or abort.

2. Gather project facts (one batched question)#

Ask:

1. Project name (for H1 of CLAUDE.md and TECHNICAL-DOCUMENTATION.md title)

2. One-line description (for subtitle and FUNCTIONAL-SPECIFICATIONS.md intro)

3. Production URL (if any — leave blank if pre-launch)

4. Repo URL (GitHub/GitLab/etc.)

5. Topology — pick one of:

   • simple — 2 environments ( develop local → staging → main production)
   • full — 3 environments ( develop → staging → canary → main)
   • single-branch — solo project with just main (no separate env)

6. Hosting platform (Railway / Vercel / Fly / AWS / self-hosted / other)

7. Stack (e.g. "Next.js + Postgres + Redis" or "Python FastAPI + Postgres")

8. Does this project have a data pipeline or many scripts? (yes/no)

9. Does this project have a data pipeline or many scripts? (yes/no)

10. Does this project depend on data from another project? (yes/no) — If yes, specify the source project path and access pattern (e.g., "read-only Postgres role on same instance as ~/Projects/other-repo"). The CLAUDE.md will get a "Data source" section and a hard rule about read-only access.

If the user wants defaults: simple topology, Railway hosting, generic Postgres stack, no pipeline, no scripts directory, no cross-repo dependency.

3. Create directory structure#

bash

mkdir -p docs/architecture docs/features docs/plans docs/recaps
# Conditionally:
mkdir -p docs/pipeline docs/scripts   # only if yes to pipeline/scripts

Multi-app projects (API + mobile client): If the project has both a backend API and a mobile (or separate frontend) app, organize them under apps/:

text

apps/api/           # Express / FastAPI / whatever backend
apps/mobile/        # React Native / Flutter mobile app

In this case, the methodology scaffolding (CLAUDE.md, docs/, contracts) lives at the repo root. Each app has its own package.json and dependency management. Do NOT use npm workspaces for the methodology files — the methodology is repo-level, not per-app. Workspaces can be added later if the apps share code.

Native mobile apps (no production URL): When the project has no web frontend, leave {{PRODUCTION_URL}} blank in the templates. The CLAUDE.md subtitle should not include a production URL line. The TECHNICAL-DOCUMENTATION.md should note "N/A — mobile app" in the deployment section.

4. Write CLAUDE.md#

• Read slim-claude-md/references/CLAUDE.md.template as base.
• Read references/CLAUDE-template-simple.md or references/CLAUDE-template-full.md (or skip for single-branch) for topology-specific rules.
• Substitute placeholders: {{PROJECT_NAME}}, {{ONE_LINE_DESCRIPTION}}, {{PRODUCTION_URL}}, {{REPO_URL}}, {{DEFAULT_BRANCH}}, branch table rows.
• Inline housekeeping protocol from slim-claude-md/references/housekeeping-protocol.md.
• Cross-repo dependency: If the project depends on another project's data (question #9), add a "Data source" section after "Common commands" documenting the dependency, the access pattern (read-only), and a hard rule prohibiting schema changes or writes to that database. Reference the source project's CLAUDE.local.md for connection strings.
• Write to project root.
• Must be ≤ 300 lines. If it overshoots, the topology-specific rules block is too verbose — trim.

5. Write CLAUDE.local.md#

• Read slim-claude-md/references/CLAUDE.local.md.template.
• Substitute branch/env structure based on topology pick.
• Leave actual secrets as <paste-here> — never invent values.
• Write to project root.

6. Update .gitignore#

Add CLAUDE.local.md to .gitignore. If .gitignore doesn't exist, create it with that line plus standard ignores for the project's stack ( node_modules/, .next/, __pycache__/, target/, etc.) — but be conservative and tell the user what was added.

Pitfall — workspace version conflicts from scaffold boilerplate. When scaffolding from create-turbo or similar generators, inspect every packages/*/package.json for version conflicts before writing the workspaces array as "packages/*". A scaffolded packages/ui/ may declare "react": "^19.2.0" which will conflict with your project's React 18 pin during npm ci. Even if the package is never imported, npm resolves ALL workspace packages' dependencies. Fix by either:

1. Deleting unused scaffold packages: rm -rf packages/ui

2. Explicitly listing workspace packages instead of using a wildcard: json

   "workspaces": [
     "apps/*",
     "packages/eslint-config",
     "packages/typescript-config"
   ]
   
   

   NOT "packages/*" — that picks up every directory in packages/, even scaffold boilerplate you'll never use.

After any workspace change, delete node_modules + package-lock.json and regenerate fresh. Then run the build locally before committing — npm ci is stricter than npm install about lockfile consistency. The project may already have a .gitignore (e.g., Python, Node, generated by a framework). Use read_file or cat to inspect it first, then append the CLAUDE.local.md line at the end. Do not blindly overwrite an existing .gitignore — you'll lose important exclusions. If the file already contains CLAUDE.local.md, skip this step.

Pitfall — patch vs. overwrite. When appending to an existing .gitignore, use patch (find the last line, append after it) rather than write_file. A full overwrite will destroy framework-generated exclusions (e.g., Python's __pycache__/, Node's node_modules/, generated docs). If you must use write_file, first read the entire file and include all existing content.

7. Write TECHNICAL-DOCUMENTATION.md#

Read references/TECHNICAL-DOCUMENTATION-template.md, substitute project facts, write to project root. The template includes section scaffolding (Tech Stack, Architecture, Database Schema, API Reference, Auth, Scripts, Deployment) so the user fills in as the project grows. Each section is intentionally short and references the matching docs/ file.

Note on stateless projects: If the project has no database (e.g., file-upload dashboards, static sites), the template's "Database Schema" section will say "N/A — stateless". This is correct — don't try to invent a schema.

8. Write FUNCTIONAL-SPECIFICATIONS.md#

Read references/FUNCTIONAL-SPECIFICATIONS-template.md, substitute project facts, write to project root. Includes section scaffolding (Authentication, User Flows, Features, Admin, Edge Cases) with the same short-and-link approach.

9. Write docs/plans/README.md#

Read references/docs-plans-README-template.md, write to docs/plans/README.md. Explains the plan-as-contract convention, the ISO date filename format ( YYYY-MM-DD-<slug>.md), plan template structure, and how to use draft-feature-plan.

10. Write empty stubs#

Create placeholder files so docs/ tree pointers in CLAUDE.md aren't broken:

• docs/STATE-SNAPSHOT.md — with header explaining it's empty until project has data
• docs/BUSINESS-CONTEXT.md — placeholder sections for founder context, target market, revenue model
• docs/TROUBLESHOOTING.md — placeholder header
• docs/architecture/overview.md — placeholder pointing at project stack and CLAUDE.md
• .gitkeep files in empty docs/features/, docs/recaps/, docs/plans/

Pitfall — stale docs/recaps/SESSION-RECAP-YYYY-MM-DD.md pointer: The base CLAUDE.md.template contains a literal placeholder path docs/recaps/SESSION-RECAP-YYYY-MM-DD.md in its "Where to find things" section. After you write the real CLAUDE.md, grep its pointers and confirm each exists. If this placeholder appears, either (a) remove it from the template before writing, or (b) note it as an expected MISS during verification — it is a template artifact, not a required file.

Pitfall — docs/scripts/README.md for projects with standalone scripts: If the project has scripts in the repo root (e.g., .py files alongside run.py), create docs/scripts/README.md with a table cataloging them. The user may not have mentioned "scripts" in the initial questions but the files are present. This prevents a broken pointer in CLAUDE.md's "Scripts" section.

11. Verify#

bash

wc -l CLAUDE.md                           # should be ≤ 300
git check-ignore -v CLAUDE.local.md       # should match .gitignore line
git status --short                        # CLAUDE.local.md must NOT appear
ls TECHNICAL-DOCUMENTATION.md FUNCTIONAL-SPECIFICATIONS.md
ls docs/plans/README.md

# Walk every docs/ pointer in new CLAUDE.md:
for f in $(grep -oE 'docs/[a-zA-Z0-9_/.-]+\.md' CLAUDE.md); do
  [ -e "$f" ] && echo "OK   $f" || echo "MISS $f"
done

Expected MISS: docs/recaps/SESSION-RECAP-YYYY-MM-DD.md is a literal template placeholder, not a real file. All other MISS lines indicate a bug — fix before handing off.

12. Hand off#

Tell the user:

• "Project structure scaffolded. CLAUDE.local.md is gitignored and has placeholder sections — fill in actual credentials before any DB or API work."
• "TECHNICAL-DOCUMENTATION.md and FUNCTIONAL-SPECIFICATIONS.md are scaffolded with empty sections. Update them as features ship — the recap workflow will prompt for it."
• "Plans live in docs/plans/ with ISO date filenames. Use /plan-feature (or draft-feature-plan skill) before significant work."
• "Recaps live in docs/recaps/ with ISO date filenames. Use /recap (or write-session-recap skill) at the end of each session."
• "Don't commit yet — review the scaffold first."

Do NOT commit. The user owns the first commit on a new project.

---

Things to Avoid#

1. Do not invent project facts. If the user doesn't answer a question, use the documented default.
2. Do not write any real secrets in any tracked file. CLAUDE.local.md only, and it must be gitignored before writing.
3. Do not pre-fill TECHNICAL-DOCUMENTATION.md or FUNCTIONAL-SPECIFICATIONS.md with hypothetical content. Leave sections as scaffolding with <add-when-implemented> markers.
4. Do not create docs/pipeline/ or docs/scripts/ unless the user said the project has those.
5. Do not set up hooks, GitHub Actions, or CI. Out of scope.
6. Do not commit or push. Always.
7. Do not assume the project is a specific stack. Read the user's stack answer and adapt headers accordingly. A Python FastAPI project shouldn't get prisma migrate commands.

Verification Checklist#

• CLAUDE.md written at project root, ≤ 300 lines
• CLAUDE.local.md written at project root, gitignored
• git check-ignore -v CLAUDE.local.md matches .gitignore line
• git status --short does NOT show CLAUDE.local.md
• docs/ tree created: architecture/, features/, plans/, recaps/
• docs/pipeline/ and docs/scripts/ only if user confirmed
• TECHNICAL-DOCUMENTATION.md written at project root
• FUNCTIONAL-SPECIFICATIONS.md written at project root
• docs/plans/README.md written
• All docs/ pointers in CLAUDE.md resolve to existing files
• Empty stubs created: STATE-SNAPSHOT.md, BUSINESS-CONTEXT.md, TROUBLESHOOTING.md, architecture/overview.md
• .gitkeep files in empty directories
• If cross-repo dependency: CLAUDE.md has "Data source" section with read-only hard rule, and CLAUDE.local.md has placeholder for the source's connection string reference
• If cross-repo dependency: CLAUDE.md has "Data source" section with read-only hard rule, and CLAUDE.local.md has <!-- reference-source-here --> placeholder