project-wizard

name	project-wizard
description	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.
argument-hint	[brief project idea description]
disable-model-invocation	true
allowed-tools	Read, Write, Edit, Bash, AskUserQuestion, Glob, Grep

Project Inception Wizard

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:

1. CLAUDE.md — full project configuration that tells Claude how to work in this project
2. .specify/memory/constitution.md — core principles and technical constraints (speckit format)
3. 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.

Step 1 — Install/update speckit CLI:

uv tool install specify-cli --force --from git+https://github.com/github/spec-kit.git

If uv is not installed, tell the user to install it first (curl -LsSf https://astral.sh/uv/install.sh | sh) and stop.

Step 2 — Backup existing constitution (if present):

if [ -f .specify/memory/constitution.md ]; then
  cp .specify/memory/constitution.md .specify/memory/constitution-backup.md
  echo "[BACKUP] Constitution backed up"
else
  echo "[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 is deprecated since speckit v0.7.x. Always use --integration claude instead.

Step 4 — Restore constitution backup:

if [ -f .specify/memory/constitution-backup.md ]; then
  mv .specify/memory/constitution-backup.md .specify/memory/constitution.md
  echo "[RESTORED] Constitution restored from backup"
else
  echo "[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, 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.

Step 5.1 — Resolve $TEMPLATE (local clone preferred, clone-once fallback):

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"; do
  if [ -f "$CAND/CLAUDE.md" ] && [ -f "$CAND/.claude/skills/sync-template/SKILL.md" ]; then
    TEMPLATE="$CAND"; break
  fi
done

if [ -z "${TEMPLATE:-}" ]; then
  echo "[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"
fi

if [ -z "${TEMPLATE:-}" ] || [ ! -f "$TEMPLATE/.claude/skills/sync-template/SKILL.md" ]; then
  echo "[ERROR] Template unavailable and clone failed. Fix connectivity (or clone manually to \$HOME/repos/Claude) and re-run the wizard." >&2
  exit 1
fi
echo "[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):

1. 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.
2. 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.
3. 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).
4. 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.
5. 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 \
  scripts/allium-hook.sh \
  scripts/tla-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 continuous-execution-hook; do
  if [ -f "scripts/$s.sh" ] && ! grep -q "$s.sh" .claude/settings.json; then echo "[UNWIRED] core hook $s present on disk but not wired — run sync-core-hooks.py"; fail=1; fi
done
# 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; }
fi
if [ "$fail" -eq 0 ]; then
  echo "[OK] Full template sync verified — allium, tla, pipeline rules, and graphify all in place"
else
  echo "[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):

./CLAUDE.md
./CLAUDE.local.md
./.specify/memory/constitution.md
./.specify/init-options.json

If any of these exist, this is NOT a blank-slate project. Adapt your questions — skip what's already decided, probe what's missing or unclear.

Step 3 — Reference documentation (read ALL that exist):

./.claude/docs/project-template.md
./.claude/docs/conventions.md
./.claude/docs/security.md
./.claude/docs/testing.md
./.claude/docs/spec-testing-checklist.md
./.claude/docs/deployment.md
./.claude/docs/git.md
./.claude/docs/workflows.md
./.claude/docs/agents-templates.md
./.claude/docs/skills.md
./.claude/docs/stress-testing.md

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):

./.specify/templates/constitution-template.md
./.specify/templates/spec-template.md
./.specify/templates/plan-template.md
./.specify/templates/tasks-template.md

If these exist, the constitution you generate must follow the template format.

Step 8 — Existing design system:

./design-system/MASTER.md
./design-system/pages/*.md

If a design system already exists, the visual design questions can be shortened — just confirm the existing direction.

Step 9 — Sibling projects (for pattern reference):

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:

1. Use AskUserQuestion with a clear, specific question
2. If relevant, provide concrete options (not open-ended when avoidable)
3. Mark your recommended option with a star (★)
4. Wait for the answer
5. 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)

1. Project Name: What is the project called? (will be used for repo name, kebab-case)
2. Elevator Pitch: One sentence — what does it do and for whom?
3. Problem Statement: What specific problem does this solve? Who has this problem today and how are they currently dealing with it?
4. Target Users: Who are the primary users? Describe 2-3 user personas (role, tech-savviness, frequency of use).
5. 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)

6. 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")
7. Architecture Philosophy: Monolith or microservices? Convention over configuration? Shared code or duplication? What's your gut feeling?
8. Data Ownership: Who owns the data? Single database or per-tenant? Self-hosted or cloud? Any data sovereignty requirements?
9. Integration First: Will this system integrate with external services? Which ones are critical? (e.g., Fortnox, Stripe, Slack, email providers)
10. 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)

11. Programming Language: Backend language? Any constraints or preferences?
12. Backend Framework: Framework choice? (e.g., ASP.NET Minimal API, Express, Django, Spring Boot)
13. Frontend Stack: Frontend framework + CSS approach + component library? (e.g., React + Tailwind + shadcn/ui)
14. Database Engine: Which database and why? (PostgreSQL, SQLite, SQL Server, MongoDB, etc.) ORM or raw SQL?
15. 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)

16. Auth Method: How do users log in? (email/password, OAuth, SSO/SAML, passkeys/WebAuthn, magic links)
17. Authorization Model: Simple roles, RBAC, ABAC, or per-resource permissions?
18. Multi-tenancy: Single-tenant or multi-tenant? If multi-tenant: shared DB, schema-per-tenant, or DB-per-tenant?
19. 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)

20. Application Type: SPA, SSR, SSG, hybrid, or admin dashboard?
21. Component Library: Existing component library or custom? (Tailwind + Headless UI, shadcn/ui, Material UI, Ant Design, Bootstrap, custom)
22. Responsive Strategy: Desktop-first, mobile-first, or responsive? Native mobile needed?
23. Language & Localization: UI language? Code language? Commit message language? Multi-language support needed?
24. 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)

25. 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
26. 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?
27. 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?
28. Visual Assets Strategy: How will you source imagery?
    • Stock photos (Unsplash, Pexels, paid stock)
    • Custom illustrations (hand-drawn, vector, isometric)
    • Icons only (Heroicons, Lucide, Phosphor, custom SVG)
    • AI-generated imagery
    • Photography (original/branded)
    • Abstract/geometric patterns and textures
    • Mixed approach — describe it
29. Animation Philosophy: How should the UI move?
    • Minimal — transitions only, no flashy stuff
    • Subtle — micro-interactions, smooth page transitions, hover feedback
    • Rich — scroll-triggered animations, staggered reveals, parallax
    • Cinematic — full page transitions, complex orchestrated sequences
    • None — static, no animations
30. 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")
31. Logo & Brand: Do you have an existing logo/brand identity, or is that also being created from scratch? Any brand guidelines to follow?
32. 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.

33. 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 GitHub Actions → 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).

34. CI/CD: Pipeline tool? (GitHub Actions ★ recommended for Noisy Cricket, GitLab CI, Azure DevOps)

35. Environments: Which environments? (local + prod for MVP ★, or local + dev + staging + prod)

36. Containerization: Docker ★ (required for Noisy Cricket), Docker Compose for local dev?

37. 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).

38. 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?
    • Embeddings / Vector search — OpenAI embeddings, Pinecone, Qdrant, pgvector, other?
    • Image generation — DALL-E, Stable Diffusion, other?

    Payments & Billing:

    • Payments — Stripe, Klarna, Swish, other?
    • Invoicing — Fortnox API ★ (used in ticket project), other?

    Authentication (external):

    • BankID — BankSignering.se API (used in hireflow)?
    • OAuth providers — Google, Microsoft, GitHub, LinkedIn?

    Storage & CDN:

    • File storage — Local NFS ★ (Noisy Cricket default), Azure Blob, S3, Cloudflare R2?
    • CDN — Cloudflare, Azure CDN, none for MVP?

    Monitoring & Analytics:

    • Analytics — Plausible, Umami, Google Analytics, PostHog?
    • Uptime monitoring — UptimeRobot, Better Stack, Pingdom?

    Other:

    • Maps — Google Maps, Mapbox, OpenStreetMap?
    • Calendar — Google Calendar API, Microsoft Graph?
    • Social — LinkedIn API, Slack API, Discord?
    • Other: _____

    For each selected service, note: is this needed for MVP or v1.0+? This determines which GitHub Secrets need to be configured at deploy time.

39. Secrets Management: How will API keys and secrets be managed?

    • GitHub Secrets for CI/CD ★ (standard for Noisy Cricket)
    • Environment variables in appsettings.Production.json
    • Azure Key Vault / AWS Secrets Manager
    • .env files (local dev only)
    • Other

Category 8: Quality & Workflow (one at a time)

40. Testing Strategy: Unit, integration, E2E? Minimum bar for MVP?
41. Monitoring: Logging, metrics, error tracking? (Sentry, Datadog, Grafana, Application Insights)
42. Backup Strategy: Database backups? RPO/RTO requirements?
43. Git Workflow: Branch naming convention? Commit message format? PR process?
44. Definition of Done: When is a feature "done"? (tests pass, E2E pass, visually verified, etc.)

Category 9: Constraints & Risks (ask last)

45. Timeline: When is MVP needed? When is v1.0?
46. Team: How many developers? Experience levels?
47. Budget: Hosting budget? Third-party service budget?
48. Compliance: GDPR, HIPAA, SOC2, PCI-DSS, or none?
49. Existing Systems: Replacing or extending something? Migration needed?
50. 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:

# 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, 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). [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 order

1. **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 → Verify

1. **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. All **unit tests** pass (`[TEST COMMAND]`).
2. All **E2E tests in Playwright** pass (`[E2E COMMAND]`).
3. For UI features: **functional coverage tests** + **destructive tests** (8+ scenarios, 6 attack categories).
4. For UI features: **TLA+ formal verification** has been run (`/tla`).
5. For web projects: **visually verified** in the browser.
6. The code is assessed as **100% 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

Adapt these based on the chosen tech stack:

• .NET: dotnet build, dotnet test, dotnet run --project src/[Name]
• Node.js: npm run build, npm test, npm run dev
• Python: python -m build, pytest, python manage.py runserver
• Go: go build ./..., go test ./..., go run .

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
• Code style, naming, forbidden patterns → .claude/docs/conventions.md
• Security questions (SQL injection, XSS, secrets) → .claude/docs/security.md
• Git commit/branch/PR → .claude/docs/git.md
• Hooks, subagents, plugins, sessions → .claude/docs/workflows.md
• Creating new agents → .claude/docs/agents-templates.md
• Skills, SKILL.md format, Agent Skills standard → .claude/docs/skills.md
• Tests (xUnit, Playwright) → .claude/docs/testing.md
• Spec testing checklist (destructive tests) → .claude/docs/spec-testing-checklist.md
• Deploy, Docker, CI/CD → .claude/docs/deployment.md
• Stress testing (pre-deploy) → .claude/docs/stress-testing.md

File organization

• scripts/ — Hook scripts (tla-hook.sh, allium-hook.sh, test-coverage-hook.sh, tlc-cleanup.sh).
• .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.

```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"]

Google Fonts import (if applicable):

<link href="https://fonts.googleapis.com/css2?family=...&display=swap" rel="stylesheet">

Anti-patterns: NEVER use [list fonts the user hates or generic AI defaults like Inter, Roboto, Arial]

Visual Assets

Strategy: [from Q28] Icon set: [chosen icon library — e.g., Lucide, Heroicons, Phosphor] Photo sources: [if applicable — Unsplash, branded photography, etc.] Illustration style: [if applicable — hand-drawn, vector, isometric, etc.]

Rules:

• NEVER use emojis as UI icons — always use SVG from [chosen icon set]
• [Stock photo rules — e.g., "prefer diverse, natural-looking people, no cheesy corporate handshakes"]
• [Illustration rules if applicable]

Animation & Motion

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]

1. [Reference 1] — take: [specific aspect]
2. [Reference 2] — take: [specific aspect]
3. [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]

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]
- `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

1. NEVER skip Phase -1 or Phase 0. Bootstrap and context absorption are mandatory.
2. 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.
3. 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).
4. If Phase 0 found existing answers, present them as "I found X — is this still correct?" instead of re-asking.
5. If the user gives a one-word answer, probe deeper. "PostgreSQL" is not enough — ask about their experience level and specific needs.
6. If the user contradicts a previous answer or an existing file, point it out and ask them to clarify.
7. Offer your professional opinion when the user is unsure. Say "I recommend X because Y" — don't just list options.
8. Keep the tone professional but conversational. This is a consulting session, not a form.
9. If the project idea is fundamentally flawed, say so diplomatically and suggest pivots.
10. Track all answers internally so nothing is lost between conversation turns.
11. 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.
12. CLAUDE.md must match the user's established patterns. The hireflow CLAUDE.md is the gold standard reference.
13. 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.
14. The constitution version always starts at 1.0.0 for a new project.
15. All dates in generated files must use the actual current date, not placeholders.
16. If sibling projects use the same stack, reference their patterns (e.g., "Reference /Users/jool/repos/matchgrid/ for GitHub deploy patterns").