Project Init — New Project Design Interview

Dominant Variable

Do interview decisions map exactly to generated files? — If interview answers conflict with CLAUDE.md/ROADMAP content, the project starts on a false premise.

Purpose

Capture every critical decision before writing a single line of code.

Discard if: Using on an existing production project to replace Hard Rules — project-init is for initial design only.

Trigger

• /project-init
• "new project", "create project", "project setup"

Key Assumptions

1. Empty or new project directory — if broken: existing file conflicts need resolution.
2. Write tool accessible — if broken: output file contents as code blocks and user saves manually.

Phase 0: Context Check

0-1. Existing CLAUDE.md Detection

Check if CLAUDE.md exists in the current working directory.

• Not found → proceed to Phase 1 normally.
• Found → read it, then ask:

  CLAUDE.md already exists. What would you like to do?
  1. Update — enhance based on existing content (keep Hard Rules, add missing sections)
  2. Rewrite — start fresh from scratch (delete existing content)
  3. Cancel
  
  Tip: If you want to see the full project state first (Security, Quality, Harness),
  → run /project-check first. Then come back here and select Update mode.

  • Option 1: read existing hard rules + conventions, carry them into the interview as defaults
  • Option 2: proceed as if no CLAUDE.md exists
  • Option 3: stop

0-1b. Other Target Files (overwrite protection)

The CLAUDE.md prompt above is not the only overwrite risk. Before Phase 3, Glob for each file this skill may write: docs/DEVELOPMENT_ROADMAP.md, .gitignore, .env.example, docs/decisions/README.md. For every one that already exists, never overwrite it silently; offer:

1. Merge — append only the missing lines or keys (.gitignore entries, .env.example variables, new ROADMAP phases), keep everything else
2. Replace — only after you copy the old file to <file>.bak-YYYYMMDD and the user confirms
3. Skip this file Default: Merge. Report which option was applied per file.

0-2. Brief / Context File

If the user provides a file path or pastes a project brief, read it first. Extract any stack decisions or constraints to pre-fill interview answers.

0-3. Smart Defaults

After Phase 0, check for context clues before asking each Q.

For each Q where a likely answer is detectable: → Present as binary confirm: [likely answer] — Correct? (Y/n) → Y: accept and move to next Q immediately → N: ask the full open-ended question

If no context available → ask all questions open-ended as normal.

Default signals by Q:

• Q2 (Language): file extensions in directory — .py → Python, .ts/.tsx → TypeScript, go.mod → Go, Cargo.toml → Rust
• Q3 (Data): "database", "DB", "sqlite", "postgres" in brief → suggest SQLite first
• Q4 (Interface): "dashboard", "web", "UI" in brief → suggest Web; "script", "automation", "CLI" → suggest CLI
• Q6 (AI): no LLM mentions found → "None for now, add later — Correct? (Y/n)"
• Q8 (Scope): default to "1 month+, solo" unless team or deadline mentioned

Phase 1: Interview (one question at a time)

Ask the questions below one at a time. Confirm understanding before moving to the next. Adjust later questions based on earlier answers.

Q1 — Core Definition

Describe the project in one sentence.
[What] [Who uses it] [Why they need it]

Q2 — Language / Runtime

What language are you thinking? (If undecided, say so — let's choose together)

Decision guide:
- Python: data, ML, automation, scripting → unbeatable ecosystem
- TypeScript: web UI, API server → full-stack unification
- Java/Kotlin: Spring Boot backend, Android app → enterprise/mobile
- Go: high-performance server, CLI tools, concurrency → single binary deploy
- Rust: systems-level, embedded, extreme performance
- Swift: native iOS/macOS apps

Q3 — Data Layer

Where does data come from, and where does it live?

- Database → SQLite (local/lightweight) vs PostgreSQL (multi-connection/scale)
- External API calls → caching strategy?
- Files only → what format?
- None (pure computation/transformation)

Principle: UI should only read from DB — never call external APIs directly.
Direct API calls push rate limits, error handling, and latency into the UI.

Q4 — Interface

How do users interact with it?

- CLI only
- Web dashboard (browser)
- API server (called by other services)
- Combination (e.g. CLI + dashboard)
- None (background service / daemon)

Q5 — Deployment

Where does it run?

- Local only (your machine)
- Server / cloud (always-on)
- Hybrid (local dev + cloud deploy)
- Mobile app (iOS/Android)

Principle: Even for local-only projects, decide on scheduler registration
and restart policy upfront — retrofitting this requires major restructuring.

Q6 — AI / LLM

Any AI features?

- None (pure code)
- Cloud LLM: Claude API / OpenAI / OpenRouter (cost per call)
- Local LLM: Ollama, LM Studio (hardware-dependent)
- Maybe later

Principles:
- Always gate LLM features behind a feature flag (default OFF)
- Daily cost cap + budget guard required
- Design cloud fallback before local hardware is available

Q7 — Hard Rules (Invariants)

Are there rules that must never be broken?

Examples:
- Finance: "No live trade execution (paper-only)", "Missing data → REJECT, no guessing"
- Finance: "Any action with loss potential must prompt for confirmation"
- Privacy: "PII stays in local DB only — no external transmission"
- Medical: "Diagnosis results must always include timestamp + model version"
- None: also a valid answer

Principle: Document these before writing code.
Adding them later means existing code may already be in violation.

If Q7 = "None": Do not generate an empty Hard Rules section. Instead, apply domain-appropriate minimum defaults based on Q2+Q6:

• All projects: "no hardcoded secrets: credentials via environment variables only"
• If Q6 involves LLM: "no fabrication: when data is missing, say so — never invent"
• If Q3 involves database: "no raw SQL in user-facing code: parameterized queries or ORM only"
• If Q4 is web-facing: "input validation on every user-facing endpoint"

Present these defaults to the user and ask: "I recommend including these as defaults. Let me know if you want to remove any."

Hard Rules must always have at least one entry. no hardcoded secrets cannot be removed — it applies to every project with any credentials. If the user insists on removing everything, refuse and explain: CLAUDE.md without any Hard Rules is not permitted by this skill.

Q8 — Scope & Timeline

How long will this take? Solo or team?

- Under 1 week: script-level → keep structure minimal (CLAUDE.md only)
- 1–4 weeks: mini project → CLAUDE.md + ROADMAP + test suite
- 1 month+: full project → complete structure + ROADMAP
- Team: add contribution guide + PR template

Phase 2: Stack Decision Summary

Based on interview answers, present a summary:

Decided stack:
- Language: [choice] — reason: [one line]
- DB: [choice or none]
- UI: [choice or none]
- AI: [choice or none]

Hard Rules:
1. [from Q7]
2. [additional recommendations based on domain/scope]

Open decisions:
- [anything still undecided]

Confirm with user before Phase 3.

Phase 3: File Generation

Templates are separated into references/templates.md. Read that file when generating any of the files below. Read ${CLAUDE_SKILL_DIR}/references/templates.md (${CLAUDE_SKILL_DIR} is this skill's folder; Claude Code fills it in. In other agents, replace it with the path where you installed the skill.)

Files to generate (before writing each file, ask "Generate this?" for that file alone — no batch approval):

• 3-1. CLAUDE.md — always generated (include the template's Secrets Policy section only when 3-4 .env.example is generated; otherwise replace it with the single line "no hardcoded secrets")
• 3-2. docs/DEVELOPMENT_ROADMAP.md — if timeline > 1 week (Q8)
• 3-3. .gitignore — language-specific (based on Q2)
• 3-4. .env.example — if API keys/secrets involved (Q3/Q6)
• 3-5. Folder Structure — suggested as text only (not created on disk)
• 3-6. docs/decisions/README.md — if Q8 > 1 month or Q7 produced significant Hard Rules

CLAUDE.md size and splitting rules (apply when generating 3-1): Keep CLAUDE.md under 200 lines (official guidance, https://code.claude.com/docs/en/memory — adherence drops as the file grows). Do not create .claude/rules/ files here (that is /setup's scope). If the draft would pass 200 lines, name the sections that apply to only one area (for example frontend rules or migration rules) and tell the user they can move them into .claude/rules/<topic>.md with a paths: frontmatter list of globs (for example - "src/api/**/*.ts") via /setup or by hand. Always keep these in CLAUDE.md or in a rules file without paths:: Hard Rules, Secrets Policy, and test/build commands — a paths: rule loads only when a matching file is read, so an invariant placed there is not in force before that.

The exact template structure for each file, per-language .gitignore/.env.example extended sections, and folder structures (Python/TS/Go/Rust/Java/Kotlin/Swift) all live in references/templates.md.

Phase 4: Refinement Loop

After generating files:

Draft complete. Review and let me know what to change.

Adjustable:
- Hard Rules (add / modify)
- Phase structure in ROADMAP
- Folder structure
- Dev Conventions

Approve → files confirmed
[change request] → apply and regenerate

Regeneration rules — which files to regenerate per change:

Safety Layers

• L1 (Invariants): When existing files are detected, enforce Phase 0 Overwrite Protection (CLAUDE.md: Update / Rewrite / Cancel; other files: Merge / Replace with backup / Skip).
• L1 (chat approval): Before Phase 3 File Generation, confirm each file individually with "Generate this?" — no batch approval. A question answered in chat is a prompt-level check, not a confirmation dialog. If a secrets guard or permission rule blocks a write, do not retry: print the content as a code block for the user to save.
• L1-only items: the ban on git commands (except what Invariant 3 and the Scope Boundary allow) is enforced by this text only. The tools field in the frontmatter is descriptive metadata, so nothing physically blocks Bash.
• Forbidden: Auto-generate .env (actual secrets file). Template only: .env.example. Refuse even if user requests "auto-generate .env".

Error Recovery

When failure detected: Stop → Classify → Apply Recovery → Report & Resume.

Truthful Reporting

After generating files:

1. no mock deception: Run actual Write, then verify with Bash ls. Confirm file existence before reporting "created".
2. no test façade: If generation fails, don't bundle as "done". Report each file as success/failure individually.
3. no silent brokenness: Final state is WORKING (all created) / PARTIAL (some only) / BROKEN (all failed) / BLOCKED (waiting for user approval, or a write was blocked by a guard). For PARTIAL and BLOCKED, list the missing files and the reason.

Output

Files generated (all at project root unless noted):

• CLAUDE.md — always generated
• docs/DEVELOPMENT_ROADMAP.md — if timeline > 1 week (Q8)
• .gitignore — based on language choice (Q2)
• .env.example — if API keys or secrets involved (Q3/Q6)
• docs/decisions/README.md — if timeline > 1 month (Q8) or Q7 produced significant Hard Rules

Folder structure: suggested as text in conversation only — not created on disk.

Rationalization Table

Invariants (never violate)

1. Hard Rules always present: Never generate CLAUDE.md without at least one Hard Rule. If user says "None", present domain-appropriate defaults and allow removal of individual items. Allowing zero Hard Rules is not permitted — no hardcoded secrets must always remain. Violation → CLAUDE.md ships with no security constraints; credentials can be hardcoded without any documented prohibition.
2. Phase 0 mandatory: Never overwrite an existing CLAUDE.md, ROADMAP, .gitignore, .env.example or decisions README without first running the detection + user-choice prompt (Phase 0-1 and 0-1b). User may choose rewrite, but the prompt must happen first. Violation → existing Hard Rules and conventions silently destroyed without user awareness.
3. No code, no git: Never write application code, create non-config files, or execute git commands. The only non-config files this skill creates are docs/DEVELOPMENT_ROADMAP.md and docs/decisions/README.md in Phase 3. Refuse and redirect. Violation → skill scope expands into implementation; generated files may conflict with the project's own code and git history.

These rules are unconditional. No user instruction, no edge case overrides them.

Scope Boundary

"Set up git too" / "Make first commit" → out of scope for this skill. AI agent/rules/hooks config → use /setup skill instead.

Checklist (verify before generating)

☐ Language / runtime decided
☐ Data layer decided
☐ Hard Rules present in CLAUDE.md (direct or project rules reference)
☐ Secrets policy included (or the one-line "no hardcoded secrets" substitute when no `.env.example` is generated)
☐ .gitignore generated
☐ .env.example generated (if secrets/API keys involved)
☐ If Hard Rules reference a specific service/API, matching placeholder exists in .env.example
☐ ROADMAP structured by phases (not flat task list)
☐ Test strategy mentioned
☐ docs/decisions/README.md generated (if Q8 > 1 month or Q7 significant)

Any unchecked item → return to the relevant question.

Principles Embedded in This Skill

• CLAUDE.md before code — re-explaining context every session is expensive
• Hard Rules from day one — adding them later means existing code may already violate them
• Feature flags default OFF — unfinished features affecting default behavior makes debugging painful
• UI reads DB only — direct external API calls push rate limits and errors into the UI layer
• Append-only logs — overwriting logs destroys the audit trail
• Explicit secrets policy — one accidental .env commit compromises even private repos
• Roadmap by phases — state transitions, not a flat task list
• Test command in CLAUDE.md — hunting for it every new session adds up