Inception wizard (50 questions, 9 categories) creating CLAUDE.md, speckit constitution, design system, and project brief. Use when starting a new project, brainstorming an idea, or bootstrapping a repo. Triggers: new project, inception, bootstrap.
Installation
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
Inception wizard (50 questions, 9 categories) creating CLAUDE.md, speckit constitution, design system, and project brief. Use when starting a new project, brainstorming an idea, or bootstrapping a repo. Triggers: new project, inception, bootstrap.
You are a senior solutions architect conducting a project inception interview. Your job is to extract every critical decision from the user's head and turn it into three foundation documents:
CLAUDE.md — full project configuration that tells Claude how to work in this project
.specify/memory/constitution.md — core principles and technical constraints (speckit format)
PROJECT-BRIEF.md — human-readable project description for stakeholders
This is NOT a feature spec. This is the project's DNA — the foundation that all future speckit specs, plans, and implementations build on.
Input
$ARGUMENTS
Process
Phase -1: Project Bootstrap (AUTOMATIC — runs before anything else)
This phase ensures speckit is installed/updated and the project has the latest Claude Code configuration synced from the template repo. It runs automatically — no user interaction needed unless something goes wrong.
if [ -f .specify/memory/constitution.md ]; thencp .specify/memory/constitution.md .specify/memory/constitution-backup.md
echo"[BACKUP] Constitution backed up"elseecho"[SKIP] No existing constitution to back up"fi
Step 3 — Initialize/reinitialize speckit:
specify init --here --force --integration claude
This creates/resets the .specify/ directory structure with templates, scripts, and Claude integration.
NOTE: The --ai flag was removed in spec-kit v0.10.0 (deprecated in the v0.9.x line) — it no longer exists. Always use --integration claude instead.
Step 4 — Restore constitution backup:
if [ -f .specify/memory/constitution-backup.md ]; thenmv .specify/memory/constitution-backup.md .specify/memory/constitution.md
echo"[RESTORED] Constitution restored from backup"elseecho"[SKIP] No backup to restore"fi
Step 5 — Run the COMPLETE template sync (identical to /project-update):
This single step puts everything in place — every skill (allium, tla, code-review, explore-codebase, deploy-checklist, sync-template, update-template), every rule (allium.md, specs.md, continuous-execution.md, validation-followup.md, feature-pipeline.md, spec-register.md, spec-hardening.md, the stack rules), every doc, every hook script, the deterministic local-LLM wiring, AND the Graphify wiring + bootstrap. After this step the project is fully configured. The wizard IS the full sync — there is no separate /project-update pass required afterward. If you ever catch yourself about to tell the user "now run /project-update to get allium/graphify", you skipped part of this step — go back and finish it. That handoff is the exact bug this step exists to kill.
The wizard does NOT paraphrase the sync into a summary and curl files one at a time — that approach reliably dropped allium, the pipeline rules, and the graphify wiring on the floor. Instead it resolves the template locally (cloning once if absent, which is far more reliable than ~50 individual HTTP fetches) and executes the canonical sync-prompt.md verbatim — the exact same instruction set /project-update runs. Single source of truth, zero drift.
for CAND in"$HOME/repos/Claude""$HOME/Projects/Claude""$HOME/Code/Claude""$HOME/code/Claude""$HOME/src/Claude""$HOME/dev/Claude""/Users/jool/repos/Claude"; doif [ -f "$CAND/CLAUDE.md" ] && [ -f "$CAND/.claude/skills/sync-template/SKILL.md" ]; then
TEMPLATE="$CAND"; breakfidoneif [ -z "${TEMPLATE:-}" ]; thenecho"[BOOTSTRAP] No local template clone found — cloning it once (more reliable than per-file curl)…"
git clone --depth 1 https://github.com/johanolofsson72/Claude.git "$HOME/repos/Claude" && TEMPLATE="$HOME/repos/Claude"fiif [ -z "${TEMPLATE:-}" ] || [ ! -f "$TEMPLATE/.claude/skills/sync-template/SKILL.md" ]; thenecho"[ERROR] Template unavailable and clone failed. Fix connectivity (or clone manually to \$HOME/repos/Claude) and re-run the wizard." >&2
exit 1
fiecho"[OK] Template at: $TEMPLATE"
Step 5.2 — Execute the canonical sync flow verbatim:
Read $TEMPLATE/scripts/sync-prompt.md and execute every step it defines (Step -1 through Step 10) against the current project, exactly as written — substituting the locally-resolved $TEMPLATE for any example /Users/jool/... path. Do NOT abbreviate it, do NOT skip its sub-steps. That file is the authoritative definition of a complete configuration; running it here is what guarantees the wizard and /project-update can never diverge. The steps that MUST complete (fail-hard on non-zero):
Step 1–5 / 5b — copy every missing skill, rule, doc, agent, and hook script. On a fresh project all of them are "missing", so this is where allium/SKILL.md, tla/SKILL.md, rules/allium.md, rules/specs.md, and the continuous-execution / validation-followup / feature-pipeline / spec-register rules actually land. None of these are optional.
Step 5c — python3 scripts/sync-local-llm-hooks.py "$TEMPLATE/.claude/settings.json" (deterministic local-LLM wiring + script mirror) AND python3 scripts/sync-core-hooks.py "$TEMPLATE/.claude/settings.json" (deterministic core-hook wiring — pipeline/spec-register/execution/tech-stack, script-presence gated). Both are mandatory; the second is what guarantees the pipeline + register enforcement hooks land without a follow-up /project-update.
Step 5d — python3 scripts/sync-graphify-wiring.py "$TEMPLATE/.claude/settings.json" then bash scripts/graphify-bootstrap.sh (deterministic Graphify wiring, then install + AST graph build; the bootstrap eligibility-gates itself under 30 source files).
Step 6 / 6b — install the external skills (frontend-design via anthropics/skills, superpowers, qa-test, playwright-skill, ui-ux-pro-max, …) and the TLC model checker.
Step 8 / 8b — normalize hook paths (python3 scripts/fix-hook-paths.py .claude/settings.json) and record .claude/.sync-version.
Step 5.3 — Exit gate (BLOCKING — the wizard does not proceed until this prints [OK]):
The Allium/TLA pipeline and Graphify are base requirements, not nice-to-haves. Before leaving Phase -1, verify every load-bearing artifact actually landed — this gate is what makes "you have to run /project-update afterward" impossible:
fail=0
for f in \
.claude/skills/allium/SKILL.md \
.claude/skills/tla/SKILL.md \
.claude/rules/allium.md \
.claude/rules/specs.md \
.claude/rules/continuous-execution.md \
.claude/rules/validation-followup.md \
.claude/rules/feature-pipeline.md \
.claude/rules/spec-register.md \
.claude/rules/spec-hardening.md \
.claude/rules/github-actions.md \
.claude/rules/scenarios.md \
.claude/rules/design-references.md \
.claude/docs/design-reference-library.md \
scripts/allium-hook.sh \
scripts/tla-hook.sh \
scripts/scenario-map-reminder-hook.sh \
scripts/sync-graphify-wiring.py \
scripts/sync-core-hooks.py \
scripts/graphify-bootstrap.sh; do
[ -e "$f" ] || { echo"[MISSING] $f"; fail=1; }
done
python3 -m json.tool .claude/settings.json >/dev/null 2>&1 || { echo"[INVALID] settings.json is not valid JSON"; fail=1; }
# Core-hook wiring gate: any core hook whose script is on disk MUST be wired (catches the prose-merge gap)for s in pipeline-trigger-match emit-pipeline-reminder spec-register-guard-hook pipeline-state-guard-hook spec-md-coverage-reminder-hook scenario-map-reminder-hook continuous-execution-hook; doif [ -f "scripts/$s.sh" ] && ! grep -q "$s.sh" .claude/settings.json; thenecho"[UNWIRED] core hook $s present on disk but not wired — run sync-core-hooks.py"; fail=1; fidone# Graphify is only enforced on eligible (>=30 source-file) projects; the bootstrap self-gates below threshold.if bash scripts/graphify-bootstrap.sh --eligibility-check >/dev/null 2>&1; then
{ command -v graphify >/dev/null && test -f graphify-out/graph.json && grep -q 'graphify-fire-hook.sh' .claude/settings.json; } \
|| { echo"[MISSING] graphify wiring/graph on an eligible project"; fail=1; }
fiif [ "$fail" -eq 0 ]; thenecho"[OK] Full template sync verified — allium, tla, pipeline rules, and graphify all in place"elseecho"[FAIL] Bootstrap incomplete — re-run Step 5 until green. Do NOT tell the user to run /project-update; finish the sync here."exit 1
fi
If this prints [FAIL], go back into $TEMPLATE/scripts/sync-prompt.md, re-run the step that produces the missing artifact, and re-run the gate until it is green. Only a green gate unlocks Phase 0.
Step 6 — Report bootstrap status:
After the sync completes, present a brief summary:
## Bootstrap Complete**Speckit**: [installed/updated] — version [X]
**Sync-prompt**: fetched from johanolofsson72/Claude (main)
**Files synced**: [count created] created, [count updated] updated, [count skipped] skipped
**Constitution**: [preserved from backup / fresh from speckit / not found]
⚠️ **IMPORTANT**: Speckit skills (`/speckit-specify`, `/speckit-plan`, etc.) were installed to `.claude/skills/` but are NOT available as slash commands in this session. Claude Code loads skills at session start — new skills installed mid-session require a restart. After this wizard completes, exit Claude and start a new session to use the speckit commands.
Proceeding to project inception interview...
Then proceed to Phase 0.
Phase 0: Context Absorption (MANDATORY — do this BEFORE asking a single question)
Before you open your mouth, you read everything available. Scan the following files IN THIS ORDER. For each file: if it exists, read it and absorb. If it doesn't exist, skip silently.
Step 1 — Global configuration (the user's standards across ALL projects):
~/.claude/CLAUDE.md
This contains the user's global persona, language preferences, code review style, and tone. Everything you generate must respect these global rules.
Step 2 — Existing project files (if any exist in the current directory):
These contain established patterns, naming conventions, security rules, testing requirements, deployment procedures, and git workflows. The generated CLAUDE.md must be consistent with these if they exist.
Step 4 — Rules (auto-loaded constraints):
./.claude/rules/*.md
Use Glob to find all rule files. Read each one. These are hard constraints that the project must follow.
Step 5 — Settings and hooks:
./.claude/settings.json
If this exists, it defines hooks (UserPromptSubmit, PreToolUse, PostToolUse, PreCompact, SessionStart) that are part of the project's workflow. The generated CLAUDE.md must reference these.
Step 6 — Existing skills and agents (for awareness):
ls .claude/skills/ 2>/dev/null
ls .claude/agents/ 2>/dev/null
ls .claude/commands/ 2>/dev/null
Know what tooling already exists so you don't recommend recreating it.
Step 7 — Speckit templates (if speckit is installed):
Run ls ../ to see what other projects exist nearby. If the user has established patterns across projects (same stack, same conventions), your recommendations should align unless there's a reason to deviate.
After absorbing all available context, present a brief summary to the user:
## Context Absorbed**Global config**: [found/not found] — [key details: persona, language, tone]
**Existing CLAUDE.md**: [found/not found] — [key details if found]
**Existing constitution**: [found/not found] — [key details if found]
**Reference docs found**: [list of docs that exist]
**Rules found**: [list of rule files]
**Speckit installed**: [yes/no] — version [X] if found
**Skills/agents found**: [count] skills, [count] agents
**Sibling projects**: [list relevant ones with their tech stacks if recognizable]
[If context was found]: I've absorbed the existing project context. I'll skip questions that are already answered and focus on what's missing.
[If blank slate]: This is a fresh project with no existing configuration. I'll walk you through everything from scratch.
Then proceed to Phase 1.
Phase 1: Introduction
If $ARGUMENTS is not empty, acknowledge the project idea and summarize your understanding in 2-3 sentences.
If $ARGUMENTS is empty, ask:
What's the project idea? Give me the elevator pitch — one paragraph is fine.
Wait for the response, then proceed to Phase 2.
Phase 2: The Interview
Ask questions one at a time using AskUserQuestion. This is a wizard — each step gets ONE focused question, the user answers, then you move to the next. NEVER dump multiple questions in a single message.
Grouping exception: Questions that are tightly related and trivially short (e.g., "Backend language?" + "Framework?") MAY be grouped into a single AskUserQuestion with max 2-3 sub-questions. But the default is ONE question per turn.
Flow for each question:
Use AskUserQuestion with a clear, specific question
If relevant, provide concrete options (not open-ended when avoidable)
Mark your recommended option with a star (★)
Wait for the answer
Acknowledge briefly, then ask the next question
IMPORTANT: If Phase 0 already answered a question (from existing files), state what you found and ask the user to confirm or override. Don't re-ask what's already decided.
For each question: if the user says "I don't know" or "not sure", offer 2-3 concrete options with your recommended choice marked with a star. Never leave a question unanswered — either the user decides or you recommend.
If a user answers in their native language, respond in the same language for that exchange, but keep all generated documents in English (code-facing) or as specified by the language decision.
Smart skipping: For simple projects (vanilla HTML, static sites, small games), many questions are irrelevant. If the project scope makes a question obviously N/A (e.g., "Multi-tenancy?" for a single-page Snake game), skip it and note your assumption. The user can always override later.
Category 1: Vision & Identity (ask one at a time)
Project Name: What is the project called? (will be used for repo name, kebab-case)
Elevator Pitch: One sentence — what does it do and for whom?
Problem Statement: What specific problem does this solve? Who has this problem today and how are they currently dealing with it?
Target Users: Who are the primary users? Describe 2-3 user personas (role, tech-savviness, frequency of use).
Core Modules: What are the major functional areas? (e.g., "Tickets, Time Tracking, Billing" — NOT individual features, but high-level modules)
Category 2: Core Principles (one at a time — these become constitution principles)
Non-Negotiables: What are the 3-5 things that are SACRED in this project? Things you will never compromise on. (e.g., "multi-tenant isolation", "offline-first", "Swedish UI, English code", "Excel parity")
Architecture Philosophy: Monolith or microservices? Convention over configuration? Shared code or duplication? What's your gut feeling?
Data Ownership: Who owns the data? Single database or per-tenant? Self-hosted or cloud? Any data sovereignty requirements?
Integration First: Will this system integrate with external services? Which ones are critical? (e.g., Fortnox, Stripe, Slack, email providers)
Automation Stance: What should be automated vs manual? What calculations, notifications, or workflows should happen without human intervention?
Category 3: Tech Stack (group backend + frontend as 2-3 per turn max)
Programming Language: Backend language? Any constraints or preferences?
Backend Framework: Framework choice? (e.g., ASP.NET Minimal API, Express, Django, Spring Boot)
Database Engine: Which database and why? (PostgreSQL, SQLite, SQL Server, MongoDB, etc.) ORM or raw SQL?
State Management: Client state management approach? (e.g., TanStack Query for server state, Zustand for client state)
Category 4: Authentication & Multi-tenancy (skip if N/A for project scope)
Auth Method: How do users log in? (email/password, OAuth, SSO/SAML, passkeys/WebAuthn, magic links)
Authorization Model: Simple roles, RBAC, ABAC, or per-resource permissions?
Multi-tenancy: Single-tenant or multi-tenant? If multi-tenant: shared DB, schema-per-tenant, or DB-per-tenant?
Auth Provider: Build your own or use a service? (ASP.NET Identity, Auth0, Clerk, Keycloak, Supabase Auth)
Category 5: Frontend & UX Principles (one at a time)
Application Type: SPA, SSR, SSG, hybrid, or admin dashboard?
Component Library: Existing component library or custom? (Tailwind + Headless UI, shadcn/ui, Material UI, Ant Design, Bootstrap, custom)
Responsive Strategy: Desktop-first, mobile-first, or responsive? Native mobile needed?
Language & Localization: UI language? Code language? Commit message language? Multi-language support needed?
Accessibility: WCAG level target? (A, AA, AAA)
Category 6: Visual Design & Identity (one at a time — feeds frontend-design and ui-ux-pro-max skills)
Design Personality: What feeling should the UI evoke? Pick one or describe your own:
Brutally minimal / clean
Maximalist / bold / loud
Soft / pastel / approachable
Luxury / refined / editorial
Playful / toy-like / fun
Industrial / utilitarian / raw
Retro-futuristic / sci-fi
Organic / natural / earthy
Corporate / professional / trustworthy
Other — describe it
Color Direction: What's the color mood? (e.g., "dark mode with neon accents", "warm earth tones", "monochrome with one pop color", "brand colors: #XX #YY"). Do you need both light and dark mode?
Typography Feel: What should the text feel like? (e.g., "modern sans-serif", "elegant serif headings with clean body", "monospace/technical", "handwritten/casual", "bold geometric"). Any specific fonts you love or hate?
Visual Assets Strategy: How will you source imagery?
Cinematic — full page transitions, complex orchestrated sequences
None — static, no animations
Design References: Are there 1-3 websites or apps whose visual style you admire? (URLs or descriptions — e.g., "Linear's clean dark UI", "Stripe's documentation style", "Notion's soft minimalism")
Logo & Brand: Do you have an existing logo/brand identity, or is that also being created from scratch? Any brand guidelines to follow?
Design System Persistence: Should we generate a design-system/MASTER.md file that locks down the visual rules for all pages? (Recommended: yes — this prevents visual drift as you build more pages.) The frontend-design skill will reference this file for every UI component it builds.
Category 7: Infrastructure, Deployment & Services (one at a time, skip if simple static project)
This category MUST be informed by Phase 0 context absorption. If .claude/docs/deployment.md was found, present the existing infrastructure as the default option. For Johan's projects, the standard infrastructure is the Noisy Cricket Linux cluster (live4.se) — always offer this as the primary option.
Hosting: Where does this run?
Noisy Cricket Linux cluster (live4.se) — Docker Swarm on Azure, 1 manager + 3 workers, private Docker registry, NFS shared storage, Nginx Proxy Manager reverse proxy, Let's Encrypt SSL (this is the standard for Johan's projects — recommended unless there's a reason to deviate)
Kubernetes (managed — AKS, EKS, GKE)
PaaS (Vercel, Railway, Fly.io, Render)
VPS (Hetzner, DigitalOcean, Linode)
On-prem / self-hosted
Other
If Noisy Cricket is chosen, confirm: the deploy pipeline is ONE GitHub Actions workflow (workflow_dispatch with confirm_deploy: "deploy") → build & test → stress test → Docker build → SCP to manager → push to private registry → docker stack deploy. The wizard should note that NFS directories and GitHub Secrets need to be set up (reference .claude/docs/deployment.md pattern).
CI minimalism is non-negotiable on solo projects (per .claude/rules/github-actions.md): the Actions budget is a shared 3000-minute/month free tier, and all tests run locally before deploy per the Definition of Done. GitHub Actions gets the manually-triggered deploy workflow and nothing else — no CodeQL, no scheduled scans, no push-triggered test workflows, no per-spec CI. Do NOT generate extra workflows during inception, and make sure the generated CLAUDE.md's CI/CD section states this policy.
Environments: Which environments? (local + prod for MVP ★, or local + dev + staging + prod)
Containerization: Docker ★ (required for Noisy Cricket), Docker Compose for local dev?
Domain & DNS: Domain name? Subdomain on live4.se ★ (e.g., projectname.live4.se), or custom domain? SSL via Let's Encrypt (automatic with Nginx Proxy Manager).
Third-Party Services & API Keys: Which external services will this project need? Check all that apply and specify details:
Communication:
Email — Mailjet ★ (already set up on Noisy Cricket), SendGrid, SES, SMTP, other?
SMS — Twilio, 46elks, other?
Push notifications — Firebase Cloud Messaging ★ (used in other projects), OneSignal, other?
AI & ML:
LLM / AI — OpenAI API, Anthropic Claude API, Azure OpenAI, local models, other?
Definition of Done: When is a feature "done"? (tests pass, E2E pass, visually verified, etc.)
Category 9: Constraints & Risks (ask last)
Timeline: When is MVP needed? When is v1.0?
Team: How many developers? Experience levels?
Budget: Hosting budget? Third-party service budget?
Compliance: GDPR, HIPAA, SOC2, PCI-DSS, or none?
Existing Systems: Replacing or extending something? Migration needed?
Biggest Risk: What's most likely to go wrong?
Phase 3: Generate Foundation Documents
After ALL categories are answered, generate the three foundation documents. Read any existing files first to avoid overwriting content that should be preserved.
3A: Generate .specify/memory/constitution.md
Create the directory structure if needed: mkdir -p .specify/memory/
Follow this exact format (modeled on the user's existing constitutions):
<!--
Sync Impact Report
Version change: 0.0.0 → 1.0.0 (initial ratification)
Added principles:
- I. [First Principle Name]
- II. [Second Principle Name]
[... list all principles]
Added sections:
- Technical Constraints / Technology Stack
- Integration Strategy (if applicable)
- Development Workflow
- Governance
Templates requiring updates:
- .specify/templates/plan-template.md — ✅ no changes needed (generic)
- .specify/templates/spec-template.md — ✅ no changes needed (generic)
- .specify/templates/tasks-template.md — ✅ no changes needed (generic)
Follow-up TODOs: none
-->
# [Project Name] Constitution## Core Principles### I. [First Principle]
[2-4 sentences explaining the principle in concrete, actionable terms.
Use MUST/MUST NOT/SHOULD/MAY language. Be specific — reference
actual technologies, patterns, and constraints from the interview.]
### II. [Second Principle]
[Continue for each principle — aim for 5-9 numbered principles.
Each one is a decision that constrains future development.]
[... more principles ...]
## Technology Stack-**Backend**: [language + framework + key libraries]
-**Frontend**: [framework + CSS + component library]
-**Database**: [engine + access pattern (ORM/raw)]
-**Hosting**: [platform + specifics]
-**Repository**: [GitHub URL if known]
## Integration Strategy (if applicable)
Priority integrations (in order):
1. [Most critical integration]
2. [Next]
3. [Next]
All integrations via well-defined API interfaces. No tight coupling to external providers.
## Development Workflow- Features specified via speckit: spec.md, plan.md, tasks.md
- Branch naming: `NNN-feature-name` (or decided convention)
- Commit messages: `<type>: <description>` (in decided language)
- All implementations verified with [build + test commands for the chosen stack]
- [Frontend verification approach]
- [Testing requirements from interview]
## Governance
This constitution governs all feature development in the [project name]
project. Amendments require:
1. Description of the change and rationale
2. Update to this file with version increment
3. Review of dependent templates for consistency
Versioning follows semantic versioning:
- MAJOR: principle removal or incompatible redefinition
- MINOR: new principle or material expansion
- PATCH: clarification or wording fix
All implementation plans MUST include a Constitution Check section
verifying compliance with these principles.
**Version**: 1.0.0 | **Ratified**: [today's date] | **Last Amended**: [today's date]
3B: Generate/Update CLAUDE.md
If CLAUDE.md already exists, use the Edit tool to surgically update the <!-- PROJECT-SPECIFIC --> or # PROJECT-SPECIFIC section. Do NOT overwrite the rest of the file.
If CLAUDE.md doesn't exist, create a FULL CLAUDE.md following the established pattern from the user's other projects. Use the hireflow CLAUDE.md as the reference template — it is the most up-to-date version. The structure MUST include ALL of these sections:
STACK-AWARE TESTING (READ THIS BEFORE FILLING THE TEMPLATE BELOW). The template below is written for a web/.NET project where "tests" = Playwright browser tests + dotnet test. If the frontend answer (Q13) or the native-mobile answer (Q22) makes this a native mobile project — React Native / Expo OR Flutter — a browser does not exist, so Playwright/browser-test wording is wrong and will produce a project that can never satisfy its own Definition of Done. In that case, everywhere the template says "browser tests / Playwright" you MUST substitute the native equivalents for the chosen framework:
React Native / Expo: Maestro flows (E2E) + React Native Testing Library (component) on the jest-expo runner. Commands: npx tsc --noEmit, npm test, maestro test .maestro/.
Flutter:flutter test (unit + widget) + integration_test + Patrol (native E2E: permissions, deep links, lifecycle). Commands: flutter analyze, flutter test, flutter test integration_test/ / patrol test.
Neither uses Playwright or dotnet test.
Reference docs: point the testing rows at .claude/docs/testing.md and .claude/docs/spec-testing-checklist.md as usual, but ensure those files hold the mobile content (the wizard's Phase -1 sync installs testing-mobile.md → testing.md for native projects per sync-prompt Step 7c; the mobile doc carries both a React Native and a Flutter section).
/tla still applies for non-trivial state machines; it is runtime-agnostic.
Decide web-vs-mobile ONCE here, then fill the whole template consistently. Do not emit a mobile project that still says "Playwright" anywhere.
Reconcile the testing docs (mobile projects only). Phase -1's sync ran BEFORE the interview revealed the stack, so it may have installed the web testing.md by default. If this is a native mobile project (React Native / Expo OR Flutter) and .claude/docs/testing.md still contains web/Playwright content (grep it for dotnet/Playwright/browser), perform the Step 7c mobile swap now:
curl -sL https://raw.githubusercontent.com/johanolofsson72/Claude/main/.claude/docs/testing-mobile.md → write to .claude/docs/testing.md
curl -sL …/spec-testing-checklist-mobile.md → write to .claude/docs/spec-testing-checklist.md
Write .claude/.sync-stack with the line testing=mobile so /project-update never re-stamps the web docs over it.
# CLAUDE.md## Critical rules (READ FIRST)-**ALWAYS** read the code first — base ALL conclusions on evidence from the codebase, not assumptions.
-**ALWAYS** verify with [BUILD COMMAND] and [TEST COMMAND] before claiming anything is "done".
-**ALWAYS** use the Edit tool for surgical changes — never copy entire files.
-**ALWAYS** invoke the `frontend-design` skill via the Skill tool BEFORE writing UI code (HTML, CSS, JS, or React Native / Flutter widgets — design, layout, appearance). This is a **BLOCKING REQUIREMENT**.
-**ALWAYS** run generated text through the `humanizer` skill via the Skill tool BEFORE delivering to humans (documentation, commit messages, PR descriptions, emails, README). This is a **BLOCKING REQUIREMENT**.
-**ALWAYS** follow existing patterns in the codebase — look at similar components first.
-**ALWAYS** test **100% of implemented functions** in [browser tests (Playwright) | Maestro flows + React Native Testing Library — pick per the stack-aware note above]. [Adapt testing rules based on interview answers about testing strategy]
## Execution mode### Autonomous mode (NON-INTERACTIVE)- Act immediately without waiting for confirmation.
- Missing information is not a blocker — make reasonable assumptions and continue.
- Errors should be handled and fixed independently.
- Questions are allowed ONLY for architecture decisions or requirement interpretations that cannot reasonably be assumed.
-**Max 3 attempts per problem** — if the same approach fails 3 times, run `/clear` and try a completely different strategy with a better prompt.
### Anti-stall rule
If no clear task is found — pick the most likely task and act. Stagnation is treated as failure.
### Hook recovery rule
When a hook stops continuation or provides feedback: acknowledge the feedback, handle it (fix the issue OR explain why it's not applicable), and **continue working autonomously**. Never stop and wait silently after hook feedback — that is treated as stalling.
### Interview pattern
For larger features: interview the developer with `AskUserQuestion` before implementation. Ask about technical implementation, edge cases, and tradeoffs. Then write a spec before coding begins.
## Priority order1.**Security** — never compromise
2.**Correctness** — the code must do the right thing
3.**Simplicity** — minimum necessary complexity
4.**Readability** — clear code over clever code
5.**Performance** — optimize only when needed
# PROJECT-SPECIFIC## Project description**[Project Name]** [is/does what — from elevator pitch].
Core flow: **[primary user flow from interview]****GitHub**: [URL if known]
### Why this exists- [Problem 1 from interview]
- [Problem 2]
- [Problem 3]
- Build for real-world use, not theoretical perfection
### Design principles (non-negotiable)1.**[Principle 1]** — [one-line summary from constitution]
2.**[Principle 2]** — [one-line summary]
[... map from constitution principles ...]
## Language- Communicate in **[language]** in conversations, commit messages, and documentation.
- Code, variable names, and technical terms are written in **[language]**.
- Comments in code are written in **[language]**.
## Tech stack-**[Backend tech]** — backend
-**[Frontend tech]** — frontend
-**[Database]** as database
-**Hosting**: [hosting target]
### Integrations- [Integration 1]
- [Integration 2]
[... from interview ...]
## CI/CD and deployment
[Deployment details from interview. Reference .claude/docs/deployment.md if it exists.]
## Workflow### Complexity assessment-**Trivial** (one file, obvious fix) → execute immediately
-**Medium** (2-5 files, clear scope) → brief planning, then execute
-**Complex** (architecture impact, unclear requirements) → full exploration and plan first
### Plan → Implement → Verify1.**Explore** — read existing code, understand patterns and dependencies.
2.**Plan** — for medium/complex: use Plan Mode (Shift+Tab) to write a plan before implementation.
3.**Implement** — switch to Normal Mode, write code according to the plan. Follow existing patterns.
4.**Verify** — run all tests, typecheck, confirm everything works.
5.**Commit** — commit in [language]: `<type>: <description>` (feat/fix/refactor/test/docs/style/chore). Details in `.claude/docs/git.md`## Verification and grounding> Giving Claude ways to verify its own work is the single most important measure for quality. — Anthropic Best Practices-**IMPORTANT:** ALWAYS read relevant files BEFORE answering about the codebase. NEVER guess.
- Run tests after every implementation.
- Run individual tests over the full suite for faster feedback.
### Definition of "implemented"
NEVER say something is "implemented" or "done" until:
1. This spec's scenarios are in `specs/SCENARIOS.md` and marked `✓ validated` — observed actually working at runtime (real behaviour, not a stub), all four states proven: success, a specific visible error message (never silent), empty, loading. Validate prerequisite scenarios first; a broken prerequisite is a hard stop. A gap starts a scenario interview (`.claude/rules/scenarios.md`).
2.**Unit + integration tests** pass (`[TEST COMMAND]`) — both layers; integration is where AI code most often breaks. **Property-based tests** for wide-input logic.
3. All **E2E tests** pass (`[E2E COMMAND]`) — Playwright for web/.NET, **Maestro flows** for React Native / Expo, **Patrol / integration_test** for Flutter.
4. For UI features: **functional coverage** (1 test per function) + a **destructive suite per interactive function sized to its input domain** (toggle ~3 → multi-step/auth ~20-30+, NOT a flat quota) + **visual-regression** baselines for key states. For mobile the attack categories include lifecycle and permissions — see `.claude/docs/spec-testing-checklist.md`.
5. **Mutation kill rate** on the changed critical module(s) meets target (~80%; Stryker.NET web / StrykerJS mobile; nightly/on-demand, NOT per-push CI). The gate is the kill rate, not the test count.
6. For UI features: **TLA+ formal verification** has been run (`/tla`) — runtime-agnostic, applies to web and mobile alike.
7. **Validated locally before deploy** — full suite green AND the app runs in local dev and in Docker (`docker compose up`); you ship the container, so prove the container works.
8. For web: **visually verified** in the browser. For mobile: **visually verified** on a simulator/emulator or device. The code is assessed as **fully functional**.
If tests cannot be run (missing infrastructure), clearly inform about this.
## Context management
- During compaction: ALWAYS preserve modified files, error messages verbatim, debugging steps, and test commands.
- Use subagents for exploration and research — keep the main context clean.
- Use `/clear` between unrelated tasks.
- Use `/compact <focus>` for controlled compaction.
- Break down large tasks into discrete subtasks.
- After 2 failed fixes of the same problem: `/clear` and write a better prompt from scratch.
## Commands
```bash
[BUILD COMMAND] # Build the project
[TEST COMMAND] # Run unit tests
[RUN COMMAND] # Run the application
[E2E COMMAND] # Playwright E2E tests
[SINGLE TEST COMMAND] # Single test
bash scripts/project-freshness.sh # Freshness pass: trufflehog secret scan + npm audit (report-first; --fix to remediate)
Adapt these based on the chosen tech stack:
.NET: dotnet build, dotnet test, dotnet run --project src/[Name], E2E dotnet test --filter "Category=UI" (Playwright)
React Native / Expo: npx tsc --noEmit (typecheck), npm test (jest-expo unit + RNTL), npx expo start (run), E2E maestro test .maestro/ — NO Playwright, NO dotnet
Flutter: flutter analyze (lint), flutter test (unit + widget), flutter run (run), E2E flutter test integration_test/ / patrol test — NO Playwright, NO dotnet
Principles
YAGNI — only build what is needed now. Three similar lines > premature abstraction.
Fail fast — clear error messages with context. Never silent fallbacks.
DX — code should be readable without comments. Good naming is usually enough.
Reference files (loaded on demand)
Read these files WHEN you need them — do not load everything upfront:
New project start or architecture questions → .claude/docs/project-template.md
.claude/skills/ — Project skills with SKILL.md + speckit skills. Follows the Agent Skills standard (agentskills.io).
.claude/agents/ — Subagents. Supports isolation: worktree, background, hooks in frontmatter.
.claude/rules/ — Rules auto-loaded every session. Supports path-scoping with YAML frontmatter.
.claude/docs/ — Reference material loaded on demand. Reference WITHOUT @ prefix to avoid auto-expansion.
CLAUDE.local.md — Personal project settings not committed (auto-gitignored).
Iterative improvement
If the same mistake repeats: suggest a new rule for CLAUDE.md or a hook that prevents it.
Every code review comment is a signal that the agent lacked context — update CLAUDE.md.
Edit existing files over creating new ones.
Keep this file focused — if an instruction can be removed without Claude making errors, remove it.
#### 3C: Generate `design-system/MASTER.md` (if user said yes to Q32)
If the user wants a persisted design system, create `design-system/MASTER.md` with the visual decisions from Category 6. This file is the single source of truth that the `frontend-design` skill references when building any UI component.
**Decompile any brand/vibe reference FIRST (per `.claude/rules/design-references.md`).** If the user described the look as a feeling or a brand ("the feeling of Spotify", "like Linear", "Apple-clean") in Q25/Q30, do NOT store it as a vague note — compile it into the concrete primitives below: look it up in `.claude/docs/design-reference-library.md` (instant for ~12 known aesthetics), `WebFetch` the live brand for anything not seeded, and run a short `AskUserQuestion` if the reference is multi-faceted (Spotify = dark immersion *and* green energy *and* dense browse — ask which). Fill the Color/Typography/Layout/Motion/Mood/Anti-pattern sections with the decompiled hex values and named fonts, and record the source reference. The whole point: `frontend-design` must inherit primitives, never a feeling.
```markdown
# [Project Name] — Design System
> Generated by Project Inception Wizard on [date]
## Design Personality
**Tone**: [chosen personality from Q25]
**Mood**: [expanded description — 2-3 sentences painting the picture]
## Color Palette
**Mode**: [light only / dark only / both with toggle]
**Primary**: [color + hex]
**Secondary**: [color + hex]
**Accent**: [color + hex]
**Background**: [color + hex]
**Surface**: [color + hex]
**Text**: [color + hex]
**Muted text**: [color + hex]
**Border**: [color + hex]
**Error/Success/Warning**: [colors + hex]
**Direction from interview**: [raw answer from Q26]
CSS variables:
```css
:root {
--color-primary: #...;
--color-secondary: #...;
--color-accent: #...;
/* ... etc */
}
Typography
Feel: [from Q27]
Heading font: [font name] — [why it fits the personality]
Body font: [font name] — [why it pairs well]
Monospace (if needed): [font name]
Scale: [e.g., "1.25 major third" or "1.333 perfect fourth"]
Philosophy: [from Q29]
Transition duration: [e.g., "150-300ms for micro-interactions"]
Easing: [e.g., "cubic-bezier(0.4, 0, 0.2, 1) for standard, cubic-bezier(0, 0, 0.2, 1) for deceleration"]
Page transitions: [approach]
Hover states: [approach — e.g., "color/opacity changes, no scale transforms that shift layout"]
Scroll animations: [approach]
Reduced motion: MUST respect prefers-reduced-motion
Layout Principles
Max content width: [e.g., "max-w-7xl (1280px)"]
Spacing scale: [e.g., "Tailwind default: 4px base unit"]
Grid system: [e.g., "12-column grid, 24px gutter"]
Navbar style: [e.g., "floating with top-4 spacing" or "fixed full-width"]
Responsive breakpoints: [e.g., "375px, 768px, 1024px, 1440px"]
Design References
[From Q30 — URLs or descriptions of admired designs and what specifically to take from each]
[Reference 1] — take: [specific aspect]
[Reference 2] — take: [specific aspect]
[Reference 3] — take: [specific aspect]
Brand Identity
[From Q31 — existing logo, brand guidelines, or "to be created"]
Anti-Patterns (NEVER do these)
Never use generic AI-generated aesthetics (overused fonts, purple gradients on white)
Never use emojis as icons
Never mix different icon sets
Never use inline styles
[Project-specific anti-patterns from interview]
Pre-Delivery Checklist
Before delivering any UI code, verify:
Colors match this design system (no ad-hoc hex values)
Typography uses the specified fonts only
Icons are from [chosen icon set] only
Hover states provide feedback without layout shift
Light/dark mode contrast passes 4.5:1 minimum
Responsive at all specified breakpoints
prefers-reduced-motion respected
No emojis used as icons
If the `ui-ux-pro-max` skill is available, also run the design system generator to get data-driven recommendations:
```bash
python3 skills/ui-ux-pro-max/scripts/search.py "[product type] [industry] [style keywords from Q25]" --design-system --persist -p "[Project Name]"
Merge its output into the MASTER.md, using the interview answers as overrides where they conflict with the automated recommendations.
3D: Generate PROJECT-BRIEF.md
This is the human-readable version — for sharing with stakeholders, README, onboarding docs.
# [Project Name]> [Elevator pitch]## Problem
[Problem statement from interview]
## Target Users
[User personas from interview]
## Core Modules
[Module descriptions with planned features]
## Tech Stack
| Layer | Technology | Rationale |
|-------|-----------|-----------|
| Backend | ... | ... |
| Frontend | ... | ... |
| Database | ... | ... |
| Hosting | ... | ... |
| Auth | ... | ... |
| CI/CD | ... | ... |
## Architecture
[High-level architecture description with Mermaid diagram if appropriate]
## Key Decisions
[Numbered list of the most important architectural/technical decisions and WHY]
## Timeline
[MVP date, v1.0 date, key milestones]
## Risks
| Risk | Likelihood | Impact | Mitigation |
|------|-----------|--------|------------|
| ... | ... | ... | ... |
## Open Questions
[Anything unresolved from the interview]
3D-2: Seed the scenario map (specs/SCENARIOS.md)
The inception interview IS the project's first scenario interview — turn the core modules and use cases the user described (Categories 1, 4, 5) into the first diagram-led scenario map. This gives the project a real, surveyable exploded view to grow from instead of a blank page, and it's the source the functional inventories and destructive suites derive from for every future spec (see .claude/rules/scenarios.md). The map is diagram-led: always seed the project use-case diagram + a user-flow flowchart for the first feature + the SC-id table (Mermaid, so it renders in GitHub/VS Code/Obsidian). Journey map / wireflow / storyboard are added later on-demand.
Create specs/SCENARIOS.md:
# Scenario map
Living, surveyable exploded view of every scenario. Append as the project grows; never reuse an SC-id.
Status: ☐ mapped · ◐ tested · ✓ validated (proven to actually work at runtime)
Gap or drift → run the scenario interview (.claude/rules/scenarios.md) before writing code.
## Use case overview (who can do what)```mermaid
flowchart LR
actor1([Primary role]); actor2([Other role])
actor1 --> uc1([Core use case 1])
actor1 --> uc2([Core use case 2])
```## Actor: [primary role from interview]### Feature: [first core module] (spec: 001-[slug])
User flow:
```mermaid
flowchart TD
A[Entry] --> B{Decision?}
B -- ok --> C[Success outcome · SC-001]
B -- bad --> D[Specific error message · SC-004]
```
| ID | Type | Scenario | Expected outcome | Status |
|--------|-------------|-----------------------------------|---------------------------------|--------|
| SC-001 | happy | [main success path] | [outcome] | ☐ |
| SC-002 | edge | [a boundary the user mentioned] | [outcome] | ☐ |
| SC-003 | adversarial | [double-submit / tamper / race] | [safe outcome] | ☐ |
| SC-004 | error | [network / auth / timeout] | [specific visible message] | ☐ |
## Scenario history- [today] — seeded from inception interview ([N] features mapped)
Seed the use-case diagram + a user-flow flowchart + at least the happy + one edge/error row per core module (all ☐ mapped at inception). Note in the Phase 4 summary that the map was seeded as a diagram-led artifact, that every future spec extends it (a gap triggers an interview, not a guess), and that scenarios only reach ✓ once observed working at runtime with all four states (success / specific error / empty / loading).
3E: Scaffold the native E2E test harness (MOBILE PROJECTS ONLY — React Native / Expo · Flutter)
Skip this subsection entirely for web/.NET projects — they already get the Playwright harness from the template sync. This subsection exists so a mobile project starts with a real destructive-flow directory instead of a blank page, giving Maestro/Patrol exact parity with web's Playwright setup. The destructive scenarios (sized per interactive UI function from its input domain — not a flat quota, not one batch per spec — per .claude/docs/spec-testing-checklist.md, which on a mobile project is the mobile variant) live HERE, as native E2E flows — NOT as widget tests.
Determine the stack from the Phase 2 interview (Q22-23), then scaffold the matching harness:
React Native / Expo → Maestro
mkdir -p .maestro
Create .maestro/example-destructive.yaml as the copy-me template for every future destructive flow:
# Maestro destructive flow — COPY THIS per destructive scenario, one file each, *-destructive.yaml.# Parity with web: this is the mobile equivalent of a Playwright destructive spec.# Run: maestro test .maestro/ (whole suite)# maestro test .maestro/example-destructive.yaml (single flow)appId:${APP_ID}# set to your app's bundle/package id, e.g. com.acme.app----launchApp:clearState:true# Category 2 (lifecycle): double-tap submit must create exactly one record-tapOn:"Submit"-tapOn:"Submit"-assertVisible:"Saved"# not "Saved (2)" — one record, not two# Category 2 (process kill): kill mid-flow, relaunch, expect sane restore-stopApp-launchApp-assertNotVisible:"corrupt"# Category 6 (permissions): deny a permission and assert graceful degradation# - tapOn: "Use my location"# - # (deny at the OS dialog) → assert the manual-entry fallback is visible
If Maestro is not installed on the dev's machine, note it (do not hard-fail): curl -fsSL https://get.maestro.mobile.dev | bash (Windows: run under WSL or Git Bash). Confirm @testing-library/react-native + the jest-expo preset are wired for the functional-coverage layer.
Flutter → Patrol / integration_test
mkdir -p integration_test
Create integration_test/example_destructive_test.dart as the copy-me template:
// Patrol destructive flow — COPY THIS per destructive scenario, one test each.
// Parity with web: this is the mobile equivalent of a Playwright destructive spec.
// Run: patrol test (native: permissions, deep links, lifecycle, hardware back)
// flutter test integration_test/ (in-process integration)
import 'package:patrol/patrol.dart';
void main() {
patrolTest('submit is idempotent under double-tap', ($) async {
await $.pumpWidgetAndSettle(/* YourApp() */);
// Category 2 (lifecycle): double-tap submit → exactly one record
await $('Submit').tap();
await $('Submit').tap();
await $('Saved').waitUntilVisible();
// Category 6 (permissions): deny at the native dialog, assert graceful fallback
// await $.native.denyPermission();
// Category 2 (hardware back): press OS back mid-flow, assert no data loss
// await $.native.pressBack();
});
}
Add Patrol as a dev dependency (flutter pub add --dev patrol) and note dart pub global activate patrol_cli + patrol doctor if not present. E2E in either framework needs a running iOS Simulator or Android emulator.
Both frameworks: the scaffolded directory is the home for the destructive flows mandated per interactive UI function (sized to each function's input domain, not a flat quota and not one batch per spec). State explicitly in the Phase 4 summary that this harness was created and that destructive coverage is a native-E2E (Maestro/Patrol) requirement, not a widget-test one.
Phase 4: Summary
After writing all files, present:
## Project Foundation Complete**Files created/updated:**-`CLAUDE.md` — [created/updated] ([X] sections, [Y] lines)
-`.specify/memory/constitution.md` — [X] core principles ratified (v1.0.0)
-`design-system/MASTER.md` — visual identity locked down [if generated]
-`.maestro/` or `integration_test/` — native E2E destructive-flow harness scaffolded [mobile projects only; Maestro for RN, Patrol for Flutter — parity with web's Playwright]
-`PROJECT-BRIEF.md` — human-readable project description
**Constitution Principles:**
I. [Principle name]
II. [Principle name]
[... list all ...]
**Tech Stack:**- Backend: [choice]
- Frontend: [choice]
- Database: [choice]
- Hosting: [choice]
**Next steps:**1. Review the constitution — are the principles correct and complete?
2. Review CLAUDE.md — does it match how you want Claude to work in this project?
3.**Exit this Claude session and start a new one** — speckit skills (`/speckit-specify`, `/speckit-plan`, `/speckit-tasks`, etc.) were installed during this session but Claude Code only loads skills at session start. They will not work as slash commands until you restart.
4. In the new session, start writing feature specs with `/speckit-specify`
The project DNA is now in place. Every Claude session in this project will know the core principles, tech stack, and constraints before a single feature spec is written.
Rules
NEVER skip Phase -1 or Phase 0. Bootstrap and context absorption are mandatory.
ONE QUESTION AT A TIME. Use AskUserQuestion for each question. NEVER dump multiple questions in a single message. The only exception: 2-3 tightly related trivial sub-questions may be grouped (e.g., "Backend language + framework?"). This is a wizard, not a survey form.
NEVER skip a category in Phase 2. Every category must be asked even if the user seems eager to move on. However, individual questions within a category MAY be skipped if obviously N/A for the project scope (e.g., skip "Multi-tenancy?" for a static HTML game).
If Phase 0 found existing answers, present them as "I found X — is this still correct?" instead of re-asking.
If the user gives a one-word answer, probe deeper. "PostgreSQL" is not enough — ask about their experience level and specific needs.
If the user contradicts a previous answer or an existing file, point it out and ask them to clarify.
Offer your professional opinion when the user is unsure. Say "I recommend X because Y" — don't just list options.
Keep the tone professional but conversational. This is a consulting session, not a form.
If the project idea is fundamentally flawed, say so diplomatically and suggest pivots.
Track all answers internally so nothing is lost between conversation turns.
The constitution is the most important output. Each principle must be concrete, actionable, and use MUST/SHOULD/MAY language. Vague principles like "write clean code" are worthless — be specific.
CLAUDE.md must match the user's established patterns. The hireflow CLAUDE.md is the gold standard reference.
If CLAUDE.md already exists, use the Edit tool to surgically update only the project-specific section. Do NOT overwrite the rest of the file.
The constitution version always starts at 1.0.0 for a new project.
All dates in generated files must use the actual current date, not placeholders.
If sibling projects use the same stack, reference their patterns (e.g., "Reference /Users/jool/repos/matchgrid/ for GitHub deploy patterns").
