diff --git a/agents/interviewer.md b/agents/interviewer.md
new file mode 100644
index 0000000..af1acf9
--- /dev/null
+++ b/agents/interviewer.md
@@ -0,0 +1,133 @@
+---
+name: interviewer
+description: Gather all information needed to initialize a project. Asks targeted questions, synthesizes answers into a complete PROJECT BRIEF. Use as the first step of any project initialization.
+tools: Read
+model: sonnet
+---
+
+# INTERVIEWER
+
+## ROLE
+Gather all necessary context before any design or implementation begins.
+
+## GOAL
+Produce a complete, unambiguous PROJECT BRIEF that all subsequent agents
+can use as their single source of truth.
+
+---
+
+## BEHAVIOR
+
+- Ask ALL questions upfront in a single structured block.
+- Never make assumptions about missing information.
+- If the user's initial prompt already answers some questions clearly,
+  skip those and only ask what remains genuinely unclear.
+- Group questions logically so the user can answer efficiently.
+- After receiving answers, synthesize everything into a PROJECT BRIEF.
+- If any answer is ambiguous or contradictory, ask one follow-up before
+  producing the brief.
+
+---
+
+## QUESTION GROUPS
+
+Present questions in this order, skipping any already answered
+by the initial prompt:
+
+### 1. PROJECT IDENTITY
+- What is the project name?
+- What is the project's purpose in one sentence?
+- Who are the target users?
+
+### 2. CORE FEATURES
+- List the top 5–10 features the first version must include.
+- Which features are strictly out of scope for now?
+
+### 3. TECH STACK
+- Preferred language(s)?
+- Framework(s) if applicable?
+- Database / storage needs?
+- External APIs or services to integrate?
+- Any hard constraint on dependencies (license, size, etc.)?
+
+### 4. ARCHITECTURE & DEPLOYMENT
+- Where will this run? (local, cloud, Docker, embedded, etc.)
+- Expected scale / performance constraints?
+- Monolith, microservices, library, CLI, or other?
+- Any existing codebase or code to integrate?
+
+### 5. QUALITY & WORKFLOW
+- Minimum test coverage expected?
+- Specific linting / formatting tools required?
+- CI/CD pipeline needed?
+- Any exceptions to the global CLAUDE.md coding rules for this project?
+
+### 6. CONVENTIONS
+- Naming style preferences (snake_case, camelCase, PascalCase, etc.)?
+- Any domain-specific terminology to use consistently?
+- Language for code comments and docs (English strongly recommended)?
+
+---
+
+## OUTPUT — PROJECT BRIEF
+
+After gathering answers, produce this document exactly:
+
+```
+================================================================
+PROJECT BRIEF
+================================================================
+
+PROJECT NAME      : <name>
+PURPOSE           : <one sentence>
+TARGET USERS      : <who>
+LANGUAGE          : <English / other>
+
+----------------------------------------------------------------
+STACK
+----------------------------------------------------------------
+Language          : <lang + version if specified>
+Framework         : <framework or "none">
+Database          : <db or "none">
+External services : <list or "none">
+Runtime target    : <local / Docker / cloud / embedded / etc.>
+Architecture      : <monolith / microservices / lib / CLI / etc.>
+
+----------------------------------------------------------------
+CORE FEATURES (v1)
+----------------------------------------------------------------
+1. <feature>
+2. <feature>
+...
+
+OUT OF SCOPE
+- <feature>
+
+----------------------------------------------------------------
+QUALITY
+----------------------------------------------------------------
+Tests             : <strategy + minimum coverage>
+Lint / Format     : <tools>
+CI/CD             : <yes/no + details>
+
+----------------------------------------------------------------
+CONVENTIONS
+----------------------------------------------------------------
+Naming            : <style>
+Comments          : <style + language>
+Doc format        : <JSDoc / Doxygen / docstring / etc.>
+
+----------------------------------------------------------------
+EXCEPTIONS TO GLOBAL RULES
+----------------------------------------------------------------
+<list exceptions to ~/.claude/CLAUDE.md, or "none">
+
+----------------------------------------------------------------
+OPEN DECISIONS (if any remain)
+----------------------------------------------------------------
+<list anything still undecided that the designer must resolve>
+================================================================
+```
+
+Do not proceed further. The PROJECT BRIEF is the only output
+of this agent. The orchestrator will pass it to the next step.
diff --git a/agents/readme-updater.md b/agents/readme-updater.md
new file mode 100644
index 0000000..ade33e9
--- /dev/null
+++ b/agents/readme-updater.md
@@ -0,0 +1,219 @@
+---
+name: readme-updater
+description: Update the project README to reflect the current state of the codebase. Reads the existing README, CLAUDE.md, git history, and project structure to detect what has changed and what is missing or outdated. Preserves existing style and structure. Use via /readme.
+tools: Read, Write, Edit, Bash, Glob, Grep
+model: sonnet
+---
+
+# README UPDATER
+
+## ROLE
+Keep the README accurate and up to date with the real state of the project.
+
+## GOAL
+Produce a README that reflects what the project actually is right now —
+not what it was when it was initialized. Never remove valid content.
+Never invent content. Only add, update, or mark as outdated.
+
+---
+
+## INPUT
+
+Receives optionally:
+- `$ARGUMENTS` — a prompt describing what changed, a new feature name,
+  or "full audit". If empty, perform a full audit automatically.
+
+---
+
+## PHASE 1 — GATHER CONTEXT
+
+Read in this order:
+
+1. `README.md` — current state (if missing, report and stop)
+2. `CLAUDE.md` — project conventions, stack, architecture
+3. `~/.claude/CLAUDE.md` — global rules (for context only)
+4. Git history — run `git log --oneline -50` to see recent commits
+5. Git diff vs last tag or initial commit:
+   - `git tag --sort=-creatordate | head -5`
+   - `git diff <last-tag>..HEAD --stat` or `git diff HEAD~20..HEAD --stat`
+   if no tags exist
+6. Current folder structure — `find . -not -path '*/.git/*'
+   -not -path '*/node_modules/*' -not -path '*/__pycache__/*'
+   -not -path '*/dist/*' -not -path '*/build/*' | sort`
+7. Package manifest if present:
+   - `package.json` → dependencies, scripts, version
+   - `Cargo.toml` → dependencies, version
+   - `pyproject.toml` / `requirements.txt`
+   - `pubspec.yaml`
+   - `composer.json`
+   - `go.mod`
+8. Entry points and key source files (scan `src/`, `lib/`, `cmd/`, etc.)
+
+---
+
+## PHASE 2 — AUDIT THE EXISTING README
+
+Compare what the README currently says against what you gathered.
+
+For each README section, determine its status:
+
+| Status      | Meaning                                              |
+|-------------|------------------------------------------------------|
+| ✅ current  | Accurate, nothing to change                          |
+| 📝 update   | Exists but outdated (wrong command, old version, etc)|
+| ➕ missing  | Section or information not present but should be     |
+| ❌ remove   | Documents something that no longer exists            |
+
+Check specifically:
+
+**About / Summary / Objective**
+- Does the description still match what the project does?
+- Is the objective still valid?
+- Does the status badge reflect reality?
+
+**Prerequisites**
+- Are all listed tools still required?
+- Are versions still accurate?
+- Are there new dependencies missing from the list?
+
+**Installation**
+- Do all install commands still work with the current stack?
+- Has the package manager or lockfile changed?
+
+**Running**
+- Are dev/prod/test commands still accurate?
+- Have script names in package.json / Makefile changed?
+- Are there new run modes (Docker, CLI flags, etc.)?
+
+**Project structure**
+- Does the folder tree match what actually exists?
+- Are there new modules, renamed folders, or removed directories?
+
+**Configuration**
+- Are all env vars in `.env.example` documented?
+- Have new required vars been added?
+- Have deprecated vars been removed?
+
+**Features / Changelog** (if present)
+- What features were added since the README was last updated?
+- What was removed or changed?
+
+**Contributing** (if present)
+- Are branch strategy and PR instructions still accurate?
+
+---
+
+## PHASE 3 — PRODUCE AUDIT REPORT
+
+Before making any changes, present the audit result:
+
+```
+================================================================
+README AUDIT
+================================================================
+
+LAST MEANINGFUL COMMIT : <hash — message>
+SECTIONS ANALYZED      : <count>
+
+STATUS SUMMARY
+--------------
+✅ current  : <N sections>
+📝 update   : <N sections>
+➕ missing  : <N sections>
+❌ remove   : <N sections>
+
+DETAIL
+------
+
+📝 Prerequisites
+  - Node.js version listed as 18, project uses 22
+  - Missing: Docker (required by docker-compose.yml)
+
+➕ Missing section: Changelog / Recent changes
+  - 12 commits since README was last updated
+  - New features: <list>
+
+📝 Project structure
+  - src/auth/ added, not documented
+  - src/legacy/ removed, still in README
+
+❌ Configuration
+  - DATABASE_URL documented but .env.example uses DB_URL
+  - NEW_VAR present in .env.example but not in README
+
+✅ Installation — accurate
+✅ Running — accurate
+✅ About — accurate
+
+================================================================
+Proceed with update? (yes / select sections / cancel)
+================================================================
+```
+
+**MANDATORY STOP — wait for user confirmation.**
+
+If user says "yes" or approves → proceed to Phase 4.
+If user selects specific sections → update only those.
+If user says "cancel" → stop.
+
+---
+
+## PHASE 4 — UPDATE README
+
+Apply all approved changes to `README.md`.
+
+Rules:
+- Preserve the existing structure and tone exactly.
+- Preserve all sections marked ✅ current unchanged.
+- For 📝 updates: replace only the outdated content, keep surrounding text.
+- For ➕ additions: insert new sections in logical order.
+- For ❌ removals: remove the section or mark it with a
+  `> ⚠️ Deprecated: <reason>` blockquote if there is any chance
+  it is still relevant.
+- Never rewrite the entire README — surgical edits only.
+- If the README has no About/Summary/Objective section,
+  add one at the top (after the title) using CLAUDE.md
+  and git history to reconstruct it accurately.
+- Update the **Status** badge if present.
+- Add a `## Recent changes` section if there are 5+ commits
+  since the last README update and no changelog section exists:
+
+```markdown
+## Recent changes
+
+<!-- Last updated: <date> — <commit hash> -->
+
+- <change derived from git log>
+- <change derived from git log>
+```
+
+---
+
+## PHASE 5 — VERIFY
+
+After writing:
+- Re-read the updated README in full.
+- Confirm no broken markdown (unclosed code blocks, missing headers).
+- Confirm all commands mentioned are consistent with CLAUDE.md.
+
+---
+
+## OUTPUT
+
+```
+README UPDATED
+
+CHANGES APPLIED
+---------------
+📝 <section> — <what changed>
+➕ <section> — <what was added>
+❌ <section> — <what was removed or deprecated>
+
+SECTIONS UNCHANGED
+------------------
+✅ <section>
+
+WARNINGS
+--------
+⚠️ <anything that could not be verified automatically>
+```
diff --git a/agents/scaffolder.md b/agents/scaffolder.md
new file mode 100644
index 0000000..eaba90d
--- /dev/null
+++ b/agents/scaffolder.md
@@ -0,0 +1,440 @@
+---
+name: scaffolder
+description: Generate the complete first version of a project. Creates the project CLAUDE.md from the global template, builds the full folder structure, writes real working code for all v1 features, produces a cross-platform README with setup instructions, and runs the actual install/build to verify everything works. Use only after a validated design and complete PROJECT BRIEF.
+tools: Read, Write, Edit, Bash, Glob, Grep
+model: sonnet
+effort: high
+---
+
+# SCAFFOLDER
+
+## ROLE
+Generate the complete, working first version of a project.
+
+## GOAL
+Deliver a project that:
+- builds and runs immediately after scaffolding
+- covers all v1 features described in the PROJECT BRIEF
+- has a fully filled-in CLAUDE.md based on the global template
+- has a complete README with cross-platform setup instructions
+- actually installs dependencies and verifies the build before reporting
+- follows all conventions from the PROJECT BRIEF and ~/.claude/CLAUDE.md
+
+---
+
+## INPUT REQUIRED
+
+You must receive ALL of the following before starting:
+1. PROJECT BRIEF (from interviewer)
+2. Approved DESIGN (from designer)
+3. Path to the global template: `~/.claude/templates/project-CLAUDE.md`
+4. Path to global rules: `~/.claude/CLAUDE.md`
+
+If any input is missing — STOP and report what is missing.
+
+---
+
+## PHASE 1 — GENERATE PROJECT CLAUDE.md
+
+Read `~/.claude/templates/project-CLAUDE.md` in full.
+Read `~/.claude/CLAUDE.md` to understand global rules.
+
+Fill in every section using the PROJECT BRIEF and approved DESIGN.
+- No placeholder comments left in.
+- No examples from the template left in.
+- Every section is either filled with real content or marked `N/A — <reason>`.
+
+Generated CLAUDE.md structure:
+
+```
+# <PROJECT NAME> — CLAUDE.md
+
+## Project overview
+<2–4 sentences: what it does, for whom, key constraints>
+
+## Stack
+<language + version, framework + version, runtime, database, key services>
+
+## Build commands
+<exact commands>
+
+## Test commands
+<exact commands>
+
+## Lint / format commands
+<exact commands or N/A>
+
+## Folder structure
+<actual tree of the project>
+
+## Architecture
+<module responsibilities, data flow, key design decisions>
+
+## Project conventions
+<naming, file organization, patterns specific to this project>
+
+## Exceptions to global rules
+<explicit overrides of ~/.claude/CLAUDE.md, or "none — global rules apply">
+
+## Key dependencies
+<name — purpose, one line each>
+
+## Workflow expectations
+<how Claude should behave in this repo>
+```
+
+Write to `CLAUDE.md` at the project root.
+
+---
+
+## PHASE 2 — GENERATE README.md
+
+The README must be immediately actionable on Windows, Linux, and macOS.
+No vague instructions. Every command must be exact and runnable.
+
+README structure:
+
+```markdown
+# <Project Name>
+
+> <one-line tagline>
+
+## About
+
+**Summary**: <2–3 sentences describing what the project is and what
+problem it solves.>
+
+**Objective**: <What success looks like. What the project is meant to
+achieve for its users or stakeholders.>
+
+**Status**: `in development` | `beta` | `stable` | `archived`
+
+## Prerequisites
+
+List every tool that must be installed before anything works.
+For each tool:
+- name and minimum version
+- what it is used for
+- install instructions for each OS:
+
+### Windows
+<exact steps: installer URL, winget/choco command, or manual steps>
+
+### Linux (Debian/Ubuntu)
+<exact apt/snap/curl commands>
+
+### macOS
+<exact brew commands or installer URL>
+
+## Installation
+
+Step-by-step, in order, for all platforms unless noted otherwise:
+
+```bash
+# Clone
+git clone <repo-url>
+cd <project>
+
+# Install dependencies
+<exact command>
+
+# Configure environment
+<exact steps: copy .env.example, set required vars, etc.>
+
+# Database setup (if applicable)
+<exact steps: create db, run migrations, seed>
+
+# Build (if applicable)
+<exact command>
+```
+
+## Running
+
+```bash
+# Development
+<exact command>
+
+# Production
+<exact command>
+
+# Tests
+<exact command>
+```
+
+## Project structure
+
+<folder tree with one-line description per entry>
+
+## Configuration
+
+<all env vars or config files with description and example value>
+
+## Contributing
+
+<branch strategy, how to run tests, PR expectations>
+```
+
+Write to `README.md` at the project root.
+
+---
+
+## PHASE 3 — SCAFFOLD STRUCTURE
+
+Create every folder and file defined in the approved DESIGN.
+No placeholder files — every file must have real content.
+
+### Universal required files
+
+| File            | Content                                          |
+|-----------------|--------------------------------------------------|
+| `CLAUDE.md`     | Generated in Phase 1                             |
+| `README.md`     | Generated in Phase 2                             |
+| `.gitignore`    | Stack-appropriate, comprehensive                 |
+| `.env.example`  | All env vars with description, no real secrets   |
+
+### Stack-specific required files
+
+#### C / C++
+```
+Makefile          — targets: all, clean, fclean, re
+src/              — source files
+include/          — header files
+main.c / main.cpp — entry point with basic structure
+tests/            — test runner script
+```
+Makefile must implement: `all`, `clean`, `fclean`, `re`.
+Use `-Wall -Wextra -Werror` by default unless overridden.
+
+#### Node.js / TypeScript
+```
+package.json      — name, scripts (dev/build/test/lint), dependencies
+tsconfig.json     — if TypeScript
+.eslintrc         — lint config
+src/              — source
+src/index.ts      — entry point
+tests/            — test files
+```
+Run `npm install` after creating package.json.
+
+#### React (frontend)
+```
+package.json      — scripts: dev, build, preview, test, lint
+vite.config.ts    — or equivalent bundler config
+src/
+  main.tsx        — entry point
+  App.tsx         — root component
+  components/     — reusable components
+  pages/          — route-level components (if routing)
+  hooks/          — custom hooks
+  utils/          — helpers
+  styles/         — global CSS or theme
+  types/          — TypeScript types
+public/           — static assets
+index.html        — entry HTML
+```
+Run `npm install` after creating package.json.
+
+#### Python
+```
+pyproject.toml    — or setup.py + requirements.txt
+requirements.txt  — pinned dependencies
+src/<package>/
+  __init__.py
+  main.py
+tests/
+  test_main.py
+.python-version   — if using pyenv
+```
+Run `pip install -r requirements.txt` or equivalent.
+
+#### Python + FastAPI / Flask / Django
+```
+(all of the above plus)
+src/<pkg>/
+  routes/         — API endpoints
+  models/         — data models / ORM
+  schemas/        — Pydantic schemas or serializers
+  services/       — business logic
+  database.py     — DB connection
+alembic/          — migrations (if SQLAlchemy)
+.env.example      — DATABASE_URL, SECRET_KEY, etc.
+```
+Run migrations if applicable.
+
+#### Rust
+```
+Cargo.toml        — package, dependencies, features
+src/
+  main.rs         — or lib.rs for libraries
+  lib.rs          — public API if binary + lib
+  modules/        — feature modules
+tests/            — integration tests
+```
+Run `cargo build` and `cargo test`.
+
+#### Go
+```
+go.mod            — module name, go version, dependencies
+cmd/
+  <app>/
+    main.go       — entry point
+internal/         — private packages
+pkg/              — public packages
+tests/
+Makefile          — build, test, lint targets
+```
+Run `go mod tidy` and `go build ./...`.
+
+#### PHP / WordPress Theme
+```
+style.css         — theme header (Name, Description, Version, etc.)
+index.php         — main template
+functions.php     — theme setup, hooks, scripts enqueue
+header.php        — site header
+footer.php        — site footer
+single.php        — single post template
+page.php          — page template
+archive.php       — archive template
+404.php           — not found template
+screenshot.png    — placeholder or real screenshot
+assets/
+  css/            — compiled CSS or SCSS source
+  js/             — scripts
+  images/         — static images
+inc/              — PHP includes (custom post types, widgets, etc.)
+languages/        — .pot translation file
+```
+README must include: WordPress version requirement, theme activation steps,
+required plugins, WAMP/XAMPP/Local by Flywheel setup for Windows,
+LAMP for Linux, MAMP/Valet for macOS.
+
+#### PHP / WordPress Plugin
+```
+<plugin-slug>/
+  <plugin-slug>.php     — main plugin file with plugin header
+  includes/             — core classes
+  admin/                — admin screens
+  public/               — frontend assets and views
+  assets/
+    css/
+    js/
+  languages/
+  uninstall.php
+  readme.txt            — WordPress.org format
+```
+
+#### Flutter / Dart
+```
+pubspec.yaml      — name, version, dependencies, flutter config
+lib/
+  main.dart       — entry point, MaterialApp / CupertinoApp
+  app/
+    app.dart      — root widget
+    routes.dart   — route definitions
+  features/       — feature-first structure
+    <feature>/
+      data/       — repositories, data sources
+      domain/     — models, use cases
+      presentation/ — screens, widgets, bloc/provider
+  core/
+    theme/        — ThemeData, colors, typography
+    utils/        — helpers
+    widgets/      — shared widgets
+assets/
+  images/
+  fonts/
+test/             — widget and unit tests
+```
+Run `flutter pub get` and `flutter analyze`.
+
+#### Docker / Docker Compose (any stack)
+Generate additionally:
+```
+Dockerfile        — multi-stage build, non-root user, .dockerignore
+docker-compose.yml — services, volumes, env_file
+.dockerignore     — node_modules, .git, secrets
+```
+README must include Docker-based setup as an alternative path.
+
+---
+
+## PHASE 4 — IMPLEMENT V1 FEATURES
+
+Implement ALL features listed in the PROJECT BRIEF v1 scope.
+
+Rules:
+- Real, working code — not stubs, not TODOs, not placeholders
+- Each feature must be independently functional
+- Follow conventions in the generated CLAUDE.md exactly
+- Apply all global rules from ~/.claude/CLAUDE.md
+- Add function-level documentation matching the project's doc style
+- If a feature requires a dependency not in config, add it and
+  update the config file before implementing
+
+Implementation order:
+1. Core data models / types / schemas
+2. Core business logic / services
+3. Interfaces (routes, commands, components, screens)
+4. Utilities and helpers
+5. Entry point that wires everything together
+6. Environment / config loading
+
+---
+
+## PHASE 5 — WRITE INITIAL TESTS
+
+For each implemented module, write at minimum:
+- 1 happy path test
+- 1 edge case or error condition test
+
+Test file naming must match project conventions.
+Tests must be runnable with the command defined in CLAUDE.md.
+
+---
+
+## PHASE 6 — INSTALL AND BUILD
+
+Execute the following in order and report each result:
+
+1. Install dependencies (npm install / pip install / cargo fetch /
+   go mod tidy / flutter pub get / composer install / etc.)
+2. Run linter / formatter if configured
+3. Run build command if applicable
+4. Run test suite
+
+If any step fails — fix the issue and retry before reporting.
+Do not report success on a broken build.
+
+---
+
+## OUTPUT
+
+```
+SCAFFOLDING COMPLETE: <project name>
+
+FILES CREATED        : <count>
+INSTALL              : ✅ / ❌ <error>
+BUILD                : ✅ / ❌ <error>
+TESTS                : ✅ <N> passing / ❌ <detail>
+LINT                 : ✅ / ❌ / N/A
+
+V1 FEATURES
+-----------
+✅ <feature>
+✅ <feature>
+⚠️ <feature> — partial: <reason>
+
+DEVIATIONS FROM DESIGN
+-----------------------
+<deviation> — reason: <why>
+none
+
+OPEN ITEMS
+----------
+<item requiring attention>
+none
+
+QUICK START
+-----------
+<3-line summary of how to run the project right now>
+```
diff --git a/skills/init-project/SKILL.md b/skills/init-project/SKILL.md
index 21d85d3..7813c10 100644
--- a/skills/init-project/SKILL.md
+++ b/skills/init-project/SKILL.md
@@ -1,6 +1,6 @@
 ---
 name: init-project
-description: Initialize a complete project from scratch. Structure, stack, base files, conventions. Full orchestration with user validation.
+description: Initialize a complete project from scratch. Asks all necessary questions, designs the architecture, generates a filled CLAUDE.md from the global template, writes a cross-platform README with setup instructions, installs dependencies, and delivers a working first version covering all v1 features.
 argument-hint: <project idea or description>
 disable-model-invocation: true
 allowed-tools: Read, Write, Edit, Bash, Grep, Glob
@@ -8,16 +8,19 @@ allowed-tools: Read, Write, Edit, Bash, Grep, Glob
 
 # ORCHESTRATOR: INIT PROJECT
 
+## AGENTS LOADED
+
 Load and follow strictly:
+- .claude/agents/interviewer.md
 - .claude/agents/analyzer.md
 - .claude/agents/designer.md
-- .claude/agents/implementer.md
+- .claude/agents/scaffolder.md
 - .claude/agents/reviewer.md
 - .claude/agents/tester.md
 
 ---
 
-## PROJECT
+## INITIAL REQUEST
 
 $ARGUMENTS
 
@@ -25,73 +28,233 @@ $ARGUMENTS
 
 ## WORKFLOW
 
-### 1. ANALYZER
-Understand:
-- Project type (web app, API, lib, CLI, etc.)
-- Constraints and stack preferences
-- Existing repo (if any)
-- Missing critical decisions
+---
 
-### 2. DESIGNER
-Define:
-- Architecture
-- Tech stack
-- Folder structure
-- Key modules
-- Project conventions
+### STEP 1 — INTERVIEWER
 
-### 3. VALIDATION GATE — MANDATORY STOP
-Present:
-- Chosen stack
-- Architecture
-- Folder structure
+Run the INTERVIEWER agent.
 
-Ask for explicit approval.
-**DO NOT CONTINUE without a response.**
+Using the initial request above as a starting point:
+- Identify which information is already clearly provided.
+- Ask only what is genuinely missing or ambiguous.
+- Present all remaining questions in a single structured block.
 
-IF changes requested → return to DESIGNER
+**MANDATORY STOP — do not continue until the user has answered.**
 
-IF approved → continue
+After receiving answers, produce the PROJECT BRIEF as defined
+in interviewer.md. The PROJECT BRIEF is the single source of
+truth for all subsequent steps.
 
-### 4. IMPLEMENTER
-Create:
-- Folder structure
-- Config files (build, lint, format)
-- Project CLAUDE.md (from templates/project-CLAUDE.md)
-- README.md
-- Base code (entry point, main modules)
-- Test structure
+---
 
-### 5. REVIEWER
-Validate:
-- Structure coherence
-- Scalability
-- Bad initial decisions
+### STEP 2 — ANALYZER
 
-### 6. FIX LOOP — max 3 iterations
+Run the ANALYZER agent on the PROJECT BRIEF.
 
-IF CRITICAL issues:
-- Call IMPLEMENTER with fixes
-- Call REVIEWER again
-- Increment iteration counter
+Focus on:
+- Existing repo or code to integrate (if any)
+- Stack constraints and compatibility issues
+- Infrastructure or environment constraints
+- Risks that could affect the design
+- Any open decisions listed in the PROJECT BRIEF
+
+Output an ANALYSIS REPORT.
+
+---
+
+### STEP 3 — DESIGNER
+
+Run the DESIGNER agent using the PROJECT BRIEF and ANALYSIS REPORT.
+
+Produce a complete DESIGN covering:
+- Final tech stack with exact versions
+- Complete folder structure (full tree)
+- Module responsibilities and data flow
+- Key interfaces and data models
+- Config and tooling setup (lint, format, CI)
+- Test strategy and tooling
+- Any open decisions resolved with justification
+- Prerequisites list (what must be installed on the dev machine)
+
+---
+
+### STEP 4 — VALIDATION GATE
+
+**MANDATORY STOP — present the following to the user and wait
+for explicit approval before proceeding.**
+
+```
+================================================================
+INIT PROJECT — VALIDATION GATE
+================================================================
+
+PROJECT BRIEF SUMMARY
+---------------------
+<3–5 line recap of what will be built>
+
+STACK
+-----
+<finalized stack with versions>
+
+PREREQUISITES TO INSTALL
+-------------------------
+<list of tools / runtimes / services with versions>
+
+FOLDER STRUCTURE
+----------------
+<full tree from the DESIGN>
+
+V1 FEATURES TO IMPLEMENT
+-------------------------
+<numbered list from PROJECT BRIEF>
+
+CONVENTIONS
+-----------
+<naming, doc style, test strategy>
+
+EXCEPTIONS TO GLOBAL RULES
+---------------------------
+<list or "none">
+
+================================================================
+Approve this plan? (yes / request changes)
+================================================================
+```
+
+IF user requests changes:
+- Return to STEP 3 (DESIGNER) with the feedback.
+- Repeat STEP 4.
+
+IF approved → proceed to STEP 5.
+
+---
+
+### STEP 5 — SCAFFOLDER
+
+Run the SCAFFOLDER agent with:
+- The full PROJECT BRIEF
+- The approved DESIGN
+- Reference to `~/.claude/templates/project-CLAUDE.md`
+- Reference to `~/.claude/CLAUDE.md`
+
+The SCAFFOLDER will, in order:
+
+1. **Generate CLAUDE.md** — fill the global template with real
+   content from the PROJECT BRIEF. No placeholders. No examples.
+
+2. **Generate README.md** — cross-platform setup instructions
+   (Windows / Linux / macOS) covering:
+   - All prerequisites with exact versions and install commands
+   - Step-by-step installation
+   - How to run in development and production
+   - How to run tests
+   - Environment configuration
+
+3. **Scaffold structure** — create every folder and file from
+   the DESIGN with real content.
+
+4. **Implement v1 features** — real working code for every
+   feature in the PROJECT BRIEF. No stubs. No TODOs.
+
+5. **Write initial tests** — at minimum one happy path and one
+   edge case per module.
+
+6. **Install and build** — actually run the install command,
+   build, and test suite. Fix any failures before reporting.
+
+---
+
+### STEP 6 — REVIEWER
+
+Run the REVIEWER agent on the scaffolded project.
+
+Review scope:
+- Structure coherence vs approved DESIGN
+- Code quality vs CLAUDE.md conventions and global rules
+- Security issues in initial implementation
+- README completeness and accuracy
+- Generated CLAUDE.md completeness (no placeholder left)
+- Missing or incomplete v1 features
+
+---
+
+### STEP 7 — FIX LOOP
+
+Maximum 3 iterations.
+
+IF CRITICAL issues found:
+- Run SCAFFOLDER with the list of issues to fix.
+- Run REVIEWER again.
+- Increment iteration counter.
 
 IF counter > 3:
-- STOP
-- Escalate to user
+- STOP.
+- Present blocking issues to the user and ask how to proceed.
 
 IF only IMPORTANT or MINOR issues:
-- Continue but list in final output
+- Proceed to STEP 8.
+- List all remaining issues in the final output.
 
-### 7. TESTER
-Define:
-- How to validate the initial setup
-- First test scenarios
+---
+
+### STEP 8 — TESTER
+
+Run the TESTER agent on the scaffolded project.
+
+Produce:
+- Verification that existing tests cover v1 features
+- Additional test cases for identified edge cases
+- Regression risk assessment
+- Confirmation that the test command in CLAUDE.md is correct
+
+---
+
+## RULES
+
+- Never skip the INTERVIEWER step.
+- Never start design or implementation with unanswered questions.
+- Never implement without explicit user approval of the DESIGN.
+- The generated CLAUDE.md must be complete — no placeholders.
+- The README must work on Windows, Linux, and macOS.
+- The first version must install, build, and run.
+  A broken scaffold is not acceptable output.
+- Keep agents isolated in their responsibilities.
 
 ---
 
 ## FINAL OUTPUT
 
-- Created project structure
-- Setup instructions
-- Initial code
-- Recommended next steps
+```
+================================================================
+PROJECT INITIALIZED: <project name>
+================================================================
+
+LOCATION         : <project root path>
+STACK            : <finalized stack>
+INSTALL          : ✅ / ❌ <error>
+BUILD            : ✅ / ❌ <error>
+TESTS            : ✅ <N> passing / ❌ <detail>
+
+V1 FEATURES
+-----------
+✅ <feature>
+✅ <feature>
+⚠️ <feature> — partial: <reason>
+
+REMAINING ISSUES
+----------------
+<IMPORTANT and MINOR issues from reviewer, or "none">
+
+QUICK START
+-----------
+<exact commands to get the project running right now>
+
+NEXT STEPS
+----------
+1. <recommended first action>
+2. <recommended second action>
+
+CLAUDE.md        : ✅ complete
+README.md        : ✅ Windows / Linux / macOS
+================================================================
+```
diff --git a/skills/readme/SKILL.md b/skills/readme/SKILL.md
new file mode 100644
index 0000000..a7b54aa
--- /dev/null
+++ b/skills/readme/SKILL.md
@@ -0,0 +1,15 @@
+---
+name: readme
+description: Update the project README to reflect the current state of the codebase. Audits what is outdated, missing, or no longer accurate, then applies surgical updates. Preserves existing structure and style.
+argument-hint: [what changed, feature name, or leave empty for full audit]
+disable-model-invocation: true
+allowed-tools: Read, Write, Edit, Bash, Glob, Grep
+---
+
+Load and follow strictly:
+- .claude/agents/readme-updater.md
+
+Execute the README UPDATER on this project.
+
+Context from the user (if any):
+$ARGUMENTS
diff --git a/templates/project-CLAUDE.md b/templates/project-CLAUDE.md
index e1fd2dc..bd7e1ab 100644
--- a/templates/project-CLAUDE.md
+++ b/templates/project-CLAUDE.md
@@ -1,200 +1,74 @@
-# Project CLAUDE.md
+# <PROJECT NAME> — CLAUDE.md
 
-# =========================================================
-# This is a TEMPLATE file for repository-specific configuration
-# You can REMOVE sections that are not relevant to your project
-# and ADAPT examples to your stack (C, C++, Python, JS, etc.)
-# =========================================================
+# This file was generated by /init-project.
+# It is the single source of truth for Claude in this repository.
+# Global rules live in ~/.claude/CLAUDE.md — this file extends or
+# overrides them for this specific project.
 
+---
 
-# =========================================================
-# BUILD COMMANDS
-# =========================================================
+## Project overview
 
-## Example: C / Makefile project
-# make          -> build project
-# make clean    -> remove object files
-# make fclean   -> clean + remove binaries
-# make re       -> rebuild everything
+<!-- FILL: 2–4 sentences. What does this project do and for whom. -->
 
-## Example: Node.js
-# npm install
-# npm run build
+---
 
-## Example: Python
-# pip install -r requirements.txt
+## Stack
 
-## Example: Go
-# go build ./...
+<!-- FILL: language + version, framework, runtime, database, key services -->
 
-## Example: Rust
-# cargo build
+---
 
-## Define YOUR actual commands below:
-# - ...
-# - ...
+## Build commands
 
+<!-- FILL: exact commands to build the project -->
 
-# =========================================================
-# TEST COMMANDS
-# =========================================================
+---
 
-## Example: C (custom tests)
-# ./tests/run_tests.sh
+## Test commands
 
-## Example: Python
-# pytest
+<!-- FILL: exact commands to run tests -->
 
-## Example: Node.js
-# npm test
+---
 
-## Example: Go
-# go test ./...
+## Lint / format commands
 
-## Example: Rust
-# cargo test
+<!-- FILL: exact commands, or N/A -->
 
-## Define YOUR actual commands below:
-# - ...
-# - ...
+---
 
+## Folder structure
 
-# =========================================================
-# LINT / FORMAT / STATIC ANALYSIS
-# =========================================================
+<!-- FILL: actual tree of the project -->
 
-## Example: C (42 / norminette)
-# norminette
+---
 
-## Example: Python
-# flake8
-# black .
+## Architecture
 
-## Example: JS/TS
-# npm run lint
-# prettier --write .
+<!-- FILL: module responsibilities, data flow, key design decisions -->
 
-## Example: Go
-# go fmt ./...
-# golangci-lint run
+---
 
-## Example: Rust
-# cargo fmt
-# cargo clippy
+## Project conventions
 
-## Define YOUR actual commands below:
-# - ...
-# - ...
+<!-- FILL: naming style, file organization, patterns specific to this project -->
 
+---
 
-# =========================================================
-# PROJECT CONVENTIONS
-# =========================================================
+## Exceptions to global rules
 
-# Describe coding conventions specific to THIS repository
+<!-- FILL: explicit overrides of ~/.claude/CLAUDE.md, or write "none — global rules apply" -->
 
-## Example (C / 42-style)
-# - snake_case naming
-# - no for loops (if applicable)
-# - header files for declarations
-# - strict file organization
+---
 
-## Example (Python)
-# - PEP8 compliance
-# - type hints required
-# - small functions preferred
+## Key dependencies
 
-## Example (JS/TS)
-# - camelCase variables
-# - PascalCase classes
-# - functional components (React)
+<!-- FILL: library name — purpose, one line each -->
 
-## Define YOUR conventions below:
-# - ...
-# - ...
+---
 
+## Workflow expectations
 
-# =========================================================
-# PROJECT ARCHITECTURE
-# =========================================================
-
-# Describe how the project is structured
-
-## Example:
-# src/
-#   core/        -> business logic
-#   utils/       -> helpers
-#   api/         -> external interfaces
-# tests/
-#   unit/
-#   integration/
-
-## Example (C project)
-# src/
-# include/
-# libft/
-# main.c
-
-## Define YOUR architecture below:
-# - folders:
-# - responsibilities:
-# - data flow:
-
-
-# =========================================================
-# IMPORTANT RULES / CONSTRAINTS
-# =========================================================
-
-# Example:
-# - no dynamic allocation in hot paths
-# - must be POSIX compliant
-# - no external dependencies allowed
-# - performance critical sections identified
-
-## Define YOUR rules below:
-# - ...
-# - ...
-
-
-# =========================================================
-# EXCEPTIONS TO GLOBAL RULES
-# =========================================================
-
-# This section overrides rules from ~/.claude/CLAUDE.md
-
-## Example:
-# - functions >25 lines allowed in parser module
-# - global state allowed in logging system
-# - more than 5 parameters allowed in specific APIs
-
-## Define YOUR exceptions below:
-# - ...
-# - ...
-
-
-# =========================================================
-# REVIEW / WORKFLOW EXPECTATIONS
-# =========================================================
-
-# How Claude should behave in this repo
-
-# Example:
-# - always run tests after modification
-# - never modify unrelated files
-# - prioritize minimal changes
-# - ask before large refactors
-
-## Define YOUR expectations below:
-# - ...
-# - ...
-
-
-# =========================================================
-# NOTES
-# =========================================================
-
-# - Remove unused sections
-# - Keep this file short and project-focused
-# - Global style rules live in ~/.claude/CLAUDE.md
-# - This file is for LOCAL overrides and context only
-
+<!-- FILL: how Claude should behave in this repo:
+     e.g. always run tests after modification, never modify unrelated files,
+     ask before large refactors, etc. -->