claude-code-pilot 3.0.0 → 3.1.0

package/README.md

@@ -1,11 +1,6 @@
 # Claude Code Pilot
 
-Universal Claude Code configuration for **any project**. Bundles two complementary systems:
-
-- **GSD** (Get Shit Done) v1.22.4 — *Methodology*. Spec-driven development with fresh 200k contexts per task. Prevents context rot.
-- **ECC** (Everything Claude Code) v1.8.0 — *Toolbox*. Session persistence, continuous learning, verification, quality gates. Prevents knowledge loss.
-
-One command to install. `/setup` wizard auto-configures everything.
+Universal Claude Code configuration for any project. One-command install, auto-setup wizard, 101 commands, 51 agents, 87 skills.
 
 ## Install
 
@@ -13,117 +8,99 @@ One command to install. `/setup` wizard auto-configures everything.
 cd your-project
 npx claude-code-pilot
 claude
-> /setup
+> /ccp:setup
 ```
 
+The `/ccp:setup` wizard scans your codebase, generates a tailored `CLAUDE.md`, detects your language, and activates the matching rule set.
+
 ## The Workflow
 
 ```
-npx claude-code-pilot            ← install (once)
-claude → /setup                         ← wizard scans codebase, generates CLAUDE.md
+npx claude-code-pilot              <- install (once)
+claude -> /ccp:setup               <- wizard scans codebase, generates CLAUDE.md
 
 # Development
-/gsd:discuss-phase 1                    ← GSD: capture requirements
-/gsd:plan-phase 1                       ← GSD: atomic plans
-/checkpoint create "before-impl"        ← ECC: snapshot
-/gsd:execute-phase 1                    ← GSD: build with fresh contexts
-/verify                                 ← ECC: build → types → lint → tests → security
-/gsd:verify-work 1                      ← GSD: does it match the spec?
-/save-session                           ← ECC: persist for next session
-/learn                                  ← ECC: extract reusable patterns
+/ccp:discuss-phase 1               <- capture requirements
+/ccp:plan-phase 1                  <- atomic plans
+/ccp:checkpoint create "before"    <- snapshot
+/ccp:execute-phase 1               <- build with fresh contexts
+/ccp:verify                        <- build, types, lint, tests, security
+/ccp:verify-work 1                 <- does it match the spec?
+/ccp:save-session                  <- persist for next session
+/ccp:learn                         <- extract reusable patterns
 
 # Next session
-/resume-session                         ← ECC: load previous context
-/evolve                                 ← ECC: promote instincts → skills
-/kit:update                             ← update everything
+/ccp:resume-session                <- load previous context
+/ccp:evolve                        <- promote instincts to skills
+/ccp:update                        <- update everything
 ```
 
-## What's Included (254 files after install)
+## What's Included (~494 files after install)
+
+| Category | Count | Description |
+|----------|-------|-------------|
+| `/ccp:` commands | 101 | Development lifecycle, quality gates, session management, learning |
+| Agents | 51 | Planning, execution, review, testing, security, documentation |
+| Skill packs | 87 | Continuous learning, verification, strategic compaction, and more |
+| Hooks | 15 | 14 event + 1 statusLine: safety guards, context management, notifications, session persistence |
+| Common rules | 10 | Always active (coding style, security, testing, performance, etc.) |
+| Chinese language rules | 11 | Always active (zh/ translations of common rules) |
+| Language-specific rule sets | 11 | Activated by `/ccp:setup` (see Language Rules below) |
+| Context modes | 3 | dev, research, review |
+| Reference examples | 6 | CLAUDE.md examples for different project types |
+
+### Command Highlights
 
-### GSD — Methodology (32 commands, 12 agents)
-| Command | What |
-|---------|------|
-| `/gsd:new-project` | Initialize with roadmap and milestones |
-| `/gsd:discuss-phase N` | Capture requirements |
-| `/gsd:plan-phase N` | Atomic plans (max 3 tasks per subagent) |
-| `/gsd:execute-phase N` | Build in fresh 200k contexts |
-| `/gsd:verify-work N` | Goal-backward verification |
-| `/gsd:quick "task"` | Same quality, lighter process |
-| `/gsd:progress` | Milestone progress |
-| `/gsd:help` | All 32 commands |
-
-12 specialized subagents: executor, planner, verifier, debugger, codebase-mapper, roadmapper, etc.
-
-### ECC — Toolbox (9 commands, 6 agents, 3 skills)
 | Command | What |
 |---------|------|
-| `/verify` | 6-phase quality check (build, types, lint, tests, security, diff) |
-| `/checkpoint` | Git-backed snapshots with before/after comparison |
-| `/save-session` | Persist what worked, what didn't, exact next step |
-| `/resume-session` | Load previous session context |
-| `/learn` | Extract reusable patterns from session |
-| `/evolve` | Promote learned instincts into skills/commands/agents |
-| `/quality-gate` | On-demand quality pipeline |
-| `/model-route` | Recommend model tier (Haiku/Sonnet/Opus) |
-| `/sessions` | List, load, alias saved sessions |
-
-6 agents: architect, code-reviewer, security-reviewer, tdd-guide, e2e-runner, doc-updater.
-
-3 skills: continuous-learning-v2 (instinct system), strategic-compact, verification-loop.
-
-### Kit — Infrastructure
-| Feature | What |
-|---------|------|
-| `/setup` wizard | Scans codebase, generates CLAUDE.md, installs language rules |
-| `/setup:refresh` | Updates config after project changes |
-| `/kit:update` | Updates kit + GSD + ECC |
-| Safety hooks | Blocks rm -rf, DROP TABLE, push --force; protects .env/lock files |
-| Notifications | Desktop alerts (task complete, idle, permission needed) |
-| Context modes | dev.md, research.md, review.md |
-| Language rules | 9 common + 7 language-specific sets (activated by /setup) |
-
-## How GSD and ECC Work Together
-
-| | GSD | ECC |
-|---|---|---|
-| **Purpose** | Structure *how* to work | Ensure *quality* of work |
-| **Core** | Phases, milestones, subagents | Verification, learning, persistence |
-| **Verification** | "Does it match the spec?" | "Is it production-ready?" |
-| **Context** | Fresh 200k per task | Strategic compact, pre-compact save |
-| **Knowledge** | Plans in files | Instincts that evolve into skills |
-| **Persistence** | Atomic commits | Session files with full context |
-
-## Hooks (13 total)
-
-| Hook | Event | Source |
-|------|-------|--------|
-| Command blocker | PreToolUse:Bash | Kit |
-| File protection | PreToolUse:Write\|Edit | Kit |
-| Context monitor | PostToolUse | GSD |
-| GSD update check | SessionStart | GSD |
-| Kit update check | SessionStart | Kit |
-| Session loader | SessionStart | ECC |
-| Session saver | Stop | ECC |
-| Pre-compact save | PreCompact | ECC |
-| Strategic compact | PreToolUse:Edit\|Write | ECC |
-| Task completed | Stop | Kit |
-| Idle prompt | Notification | Kit |
-| Permission needed | Notification | Kit |
-| Statusline | Always | GSD |
+| `/ccp:setup` | Wizard: scan codebase, generate CLAUDE.md, activate language rules |
+| `/ccp:discuss-phase N` | Capture requirements for a development phase |
+| `/ccp:plan-phase N` | Create atomic plans (max 3 tasks per subagent) |
+| `/ccp:execute-phase N` | Build in fresh 200k contexts, preventing context rot |
+| `/ccp:verify` | 6-phase quality check: build, types, lint, tests, security, diff |
+| `/ccp:checkpoint` | Git-backed snapshots with before/after comparison |
+| `/ccp:save-session` | Persist what worked, what didn't, exact next step |
+| `/ccp:resume-session` | Load previous session context |
+| `/ccp:learn` | Extract reusable patterns from session |
+| `/ccp:evolve` | Promote learned instincts into skills, commands, or agents |
+
+Run `/ccp:help` for the full list of all 101 commands.
+
+## Hooks (15 total)
+
+14 event hooks and 1 statusLine, all registered automatically during install.
+
+| Hook | Event | Description |
+|------|-------|-------------|
+| Command blocker | PreToolUse:Bash | Blocks dangerous commands (rm -rf, DROP TABLE, push --force) |
+| File protection | PreToolUse:Write/Edit | Protects .env, lock files, and other sensitive files |
+| Context monitor | PostToolUse | Tracks context window usage |
+| Update check | SessionStart | Checks npm for new CCP versions |
+| Session loader | SessionStart | Loads previous session context |
+| Session saver | Stop | Persists session state on exit |
+| Pre-compact save | PreCompact | Saves context before compaction |
+| Strategic compact | PreToolUse:Edit/Write | Manages context strategically |
+| Task completed | Stop | Desktop notification on task completion |
+| Idle prompt | Notification | Desktop alert when idle |
+| Permission needed | Notification | Desktop alert when permission required |
+| Auto-format | PostToolUse:Write/Edit | Formats code after writes |
+| Agent shield | PreToolUse | Agent safety guardrails |
+| Quality gate | Stop | Final quality verification |
+| Statusline | Always | Shows project status in Claude Code status bar |
 
 ## Language Rules
 
-The installer copies 9 common rules (always active) and 7 language-specific rule sets into `available-rules/`. The `/setup` wizard detects your language and activates the matching set.
+10 common rules are always active. 11 language-specific rule sets are available in `available-rules/` and activated by the `/ccp:setup` wizard when it detects your project language.
 
-Available: TypeScript, Python, Go, Swift, Kotlin, PHP, Perl.
+Available language rule sets: TypeScript, Python, Go, Swift, Kotlin, PHP, Perl, Java, C++, C#, Rust.
 
 ## Self-Updating
 
-On every session start, the kit checks npm for new versions. When available, the agent sees: *"⬆️ Pilot update available. Run /kit:update."*
+On every session start, CCP checks npm for new versions. When available, the agent sees a notification prompting an update.
 
 ```bash
 # From Claude Code:
-/kit:update
+/ccp:update
 
 # From terminal:
 npx claude-code-pilot@latest --update
@@ -145,7 +122,9 @@ npx claude-code-pilot [options]
 
 ## Credits
 
-- **GSD** by [TÂCHES](https://github.com/glittercowboy/get-shit-done) (MIT)
-- **ECC** by [Affaan Mustafa](https://github.com/affaan-m/everything-claude-code) (MIT)
-- **find-skills** by [Vercel Labs](https://github.com/vercel-labs/skills)
-- **Context7** by [Upstash](https://github.com/upstash/context7)
+Built on the shoulders of:
+
+- **GSD** by [TACHES](https://github.com/glittercowboy/get-shit-done) (MIT) -- spec-driven development methodology
+- **ECC** by [Affaan Mustafa](https://github.com/affaan-m/everything-claude-code) (MIT) -- session persistence and learning toolbox
+- **find-skills** by [Vercel Labs](https://github.com/vercel-labs/skills) -- skill discovery
+- **Context7** by [Upstash](https://github.com/upstash/context7) -- documentation context

package/bin/install.js

@@ -46,20 +46,20 @@ const pathPrefix = isGlobal ? `${targetDir.replace(/\\/g, '/')}/` : './.claude/'
 const projectRoot = isGlobal ? os.homedir() : process.cwd();
 
 // --- Templates ---
-const BOOTSTRAP_MARKER = "Run `/setup` to auto-configure";
+const BOOTSTRAP_MARKER = "Run `/ccp:setup` to auto-configure";
 
 const BOOTSTRAP_TEMPLATE = `# Project Agent Guide
 
-> **First time?** Run \`/setup\` to auto-configure this project.
+> **First time?** Run \`/ccp:setup\` to auto-configure this project.
 > **Update?** Run \`/ccp:update\` to get the latest version.
 
-This file will be generated by \`/setup\` with project-specific details.
+This file will be generated by \`/ccp:setup\` with project-specific details.
 
 ## Claude Code Pilot
 
 Spec-driven development with fresh 200k contexts per task:
 
-- \`/setup\` -- Auto-configure this project
+- \`/ccp:setup\` -- Auto-configure this project
 - \`/ccp:new-project\` -- Initialize with roadmap and milestones
 - \`/ccp:quick "task"\` -- Lightweight mode for small tasks
 - \`/ccp:discuss-phase N\` -- Capture requirements
@@ -69,10 +69,10 @@ Spec-driven development with fresh 200k contexts per task:
 
 ## Utilities
 
-- \`/verify\` -- Multi-phase verification (build, types, lint, tests, security)
-- \`/checkpoint create "name"\` -- Git-backed snapshots
-- \`/save-session\` -- Persist session state
-- \`/learn\` -- Extract reusable patterns
+- \`/ccp:verify\` -- Multi-phase verification (build, types, lint, tests, security)
+- \`/ccp:checkpoint create "name"\` -- Git-backed snapshots
+- \`/ccp:save-session\` -- Persist session state
+- \`/ccp:learn\` -- Extract reusable patterns
 
 ## Before ANY Work
 
@@ -409,7 +409,7 @@ function install() {
   ${fileCount} files, ${hookCount} hooks, ${totalAgents} agents
 
   Next:
-    ${cyan}/setup${reset}            -- auto-configure this project
+    ${cyan}/ccp:setup${reset}        -- auto-configure this project
 
   Build:
     ${cyan}/ccp:new-project${reset}  -- initialize with roadmap
@@ -418,10 +418,10 @@ function install() {
     ${cyan}/ccp:help${reset}         -- all commands
 
   Utilities:
-    ${cyan}/save-session${reset}     -- persist session state
-    ${cyan}/verify${reset}           -- multi-phase verification
-    ${cyan}/checkpoint create "v1"${reset} -- git-backed snapshot
-    ${cyan}/learn${reset}            -- extract reusable patterns
+    ${cyan}/ccp:save-session${reset} -- persist session state
+    ${cyan}/ccp:verify${reset}       -- multi-phase verification
+    ${cyan}/ccp:checkpoint create "v1"${reset} -- git-backed snapshot
+    ${cyan}/ccp:learn${reset}        -- extract reusable patterns
 `);
 }
 

package/manifest.json

@@ -1,5 +1,5 @@
 {
-  "version": "3.0.0",
+  "version": "3.1.0",
   "external": {
     "find-skills": {
       "install": "npx skills add https://github.com/vercel-labs/skills --skill find-skills -g -a claude-code -y",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-code-pilot",
-  "version": "3.0.0",
+  "version": "3.1.0",
   "description": "Claude Code Pilot -- universal AI coding companion with spec-driven development, session persistence, and auto-setup.",
   "bin": {
     "claude-code-pilot": "bin/install.js"

package/src/agents/doc-updater.md

@@ -1,6 +1,6 @@
 ---
 name: doc-updater
-description: Documentation and codemap specialist. Use PROACTIVELY for updating codemaps and documentation. Runs /update-codemaps and /update-docs, generates docs/CODEMAPS/*, updates READMEs and guides.
+description: Documentation and codemap specialist. Use PROACTIVELY for updating codemaps and documentation. Runs /ccp:update-codemaps and /ccp:update-docs, generates docs/CODEMAPS/*, updates READMEs and guides.
 tools: ["Read", "Write", "Edit", "Bash", "Grep", "Glob"]
 model: haiku
 ---

package/src/agents/gan-evaluator.md

@@ -0,0 +1,209 @@
+---
+name: gan-evaluator
+description: "GAN Harness — Evaluator agent. Tests the live running application via Playwright, scores against rubric, and provides actionable feedback to the Generator."
+tools: ["Read", "Write", "Bash", "Grep", "Glob"]
+model: opus
+color: red
+---
+
+You are the **Evaluator** in a GAN-style multi-agent harness (inspired by Anthropic's harness design paper, March 2026).
+
+## Your Role
+
+You are the QA Engineer and Design Critic. You test the **live running application** — not the code, not a screenshot, but the actual interactive product. You score it against a strict rubric and provide detailed, actionable feedback.
+
+## Core Principle: Be Ruthlessly Strict
+
+> You are NOT here to be encouraging. You are here to find every flaw, every shortcut, every sign of mediocrity. A passing score must mean the app is genuinely good — not "good for an AI."
+
+**Your natural tendency is to be generous.** Fight it. Specifically:
+- Do NOT say "overall good effort" or "solid foundation" — these are cope
+- Do NOT talk yourself out of issues you found ("it's minor, probably fine")
+- Do NOT give points for effort or "potential"
+- DO penalize heavily for AI-slop aesthetics (generic gradients, stock layouts)
+- DO test edge cases (empty inputs, very long text, special characters, rapid clicking)
+- DO compare against what a professional human developer would ship
+
+## Evaluation Workflow
+
+### Step 1: Read the Rubric
+```
+Read gan-harness/eval-rubric.md for project-specific criteria
+Read gan-harness/spec.md for feature requirements
+Read gan-harness/generator-state.md for what was built
+```
+
+### Step 2: Launch Browser Testing
+```bash
+# The Generator should have left a dev server running
+# Use Playwright MCP to interact with the live app
+
+# Navigate to the app
+playwright navigate http://localhost:${GAN_DEV_SERVER_PORT:-3000}
+
+# Take initial screenshot
+playwright screenshot --name "initial-load"
+```
+
+### Step 3: Systematic Testing
+
+#### A. First Impression (30 seconds)
+- Does the page load without errors?
+- What's the immediate visual impression?
+- Does it feel like a real product or a tutorial project?
+- Is there a clear visual hierarchy?
+
+#### B. Feature Walk-Through
+For each feature in the spec:
+```
+1. Navigate to the feature
+2. Test the happy path (normal usage)
+3. Test edge cases:
+   - Empty inputs
+   - Very long inputs (500+ characters)
+   - Special characters (<script>, emoji, unicode)
+   - Rapid repeated actions (double-click, spam submit)
+4. Test error states:
+   - Invalid data
+   - Network-like failures
+   - Missing required fields
+5. Screenshot each state
+```
+
+#### C. Design Audit
+```
+1. Check color consistency across all pages
+2. Verify typography hierarchy (headings, body, captions)
+3. Test responsive: resize to 375px, 768px, 1440px
+4. Check spacing consistency (padding, margins)
+5. Look for:
+   - AI-slop indicators (generic gradients, stock patterns)
+   - Alignment issues
+   - Orphaned elements
+   - Inconsistent border radiuses
+   - Missing hover/focus/active states
+```
+
+#### D. Interaction Quality
+```
+1. Test all clickable elements
+2. Check keyboard navigation (Tab, Enter, Escape)
+3. Verify loading states exist (not instant renders)
+4. Check transitions/animations (smooth? purposeful?)
+5. Test form validation (inline? on submit? real-time?)
+```
+
+### Step 4: Score
+
+Score each criterion on a 1-10 scale. Use the rubric in `gan-harness/eval-rubric.md`.
+
+**Scoring calibration:**
+- 1-3: Broken, embarrassing, would not show to anyone
+- 4-5: Functional but clearly AI-generated, tutorial-quality
+- 6: Decent but unremarkable, missing polish
+- 7: Good — a junior developer's solid work
+- 8: Very good — professional quality, some rough edges
+- 9: Excellent — senior developer quality, polished
+- 10: Exceptional — could ship as a real product
+
+**Weighted score formula:**
+```
+weighted = (design * 0.3) + (originality * 0.2) + (craft * 0.3) + (functionality * 0.2)
+```
+
+### Step 5: Write Feedback
+
+Write feedback to `gan-harness/feedback/feedback-NNN.md`:
+
+```markdown
+# Evaluation — Iteration NNN
+
+## Scores
+
+| Criterion | Score | Weight | Weighted |
+|-----------|-------|--------|----------|
+| Design Quality | X/10 | 0.3 | X.X |
+| Originality | X/10 | 0.2 | X.X |
+| Craft | X/10 | 0.3 | X.X |
+| Functionality | X/10 | 0.2 | X.X |
+| **TOTAL** | | | **X.X/10** |
+
+## Verdict: PASS / FAIL (threshold: 7.0)
+
+## Critical Issues (must fix)
+1. [Issue]: [What's wrong] → [How to fix]
+2. [Issue]: [What's wrong] → [How to fix]
+
+## Major Issues (should fix)
+1. [Issue]: [What's wrong] → [How to fix]
+
+## Minor Issues (nice to fix)
+1. [Issue]: [What's wrong] → [How to fix]
+
+## What Improved Since Last Iteration
+- [Improvement 1]
+- [Improvement 2]
+
+## What Regressed Since Last Iteration
+- [Regression 1] (if any)
+
+## Specific Suggestions for Next Iteration
+1. [Concrete, actionable suggestion]
+2. [Concrete, actionable suggestion]
+
+## Screenshots
+- [Description of what was captured and key observations]
+```
+
+## Feedback Quality Rules
+
+1. **Every issue must have a "how to fix"** — Don't just say "design is generic." Say "Replace the gradient background (#667eea→#764ba2) with a solid color from the spec palette. Add a subtle texture or pattern for depth."
+
+2. **Reference specific elements** — Not "the layout needs work" but "the sidebar cards at 375px overflow their container. Set `max-width: 100%` and add `overflow: hidden`."
+
+3. **Quantify when possible** — "The CLS score is 0.15 (should be <0.1)" or "3 out of 7 features have no error state handling."
+
+4. **Compare to spec** — "Spec requires drag-and-drop reordering (Feature #4). Currently not implemented."
+
+5. **Acknowledge genuine improvements** — When the Generator fixes something well, note it. This calibrates the feedback loop.
+
+## Browser Testing Commands
+
+Use Playwright MCP or direct browser automation:
+
+```bash
+# Navigate
+npx playwright test --headed --browser=chromium
+
+# Or via MCP tools if available:
+# mcp__playwright__navigate { url: "http://localhost:3000" }
+# mcp__playwright__click { selector: "button.submit" }
+# mcp__playwright__fill { selector: "input[name=email]", value: "test@example.com" }
+# mcp__playwright__screenshot { name: "after-submit" }
+```
+
+If Playwright MCP is not available, fall back to:
+1. `curl` for API testing
+2. Build output analysis
+3. Screenshot via headless browser
+4. Test runner output
+
+## Evaluation Mode Adaptation
+
+### `playwright` mode (default)
+Full browser interaction as described above.
+
+### `screenshot` mode
+Take screenshots only, analyze visually. Less thorough but works without MCP.
+
+### `code-only` mode
+For APIs/libraries: run tests, check build, analyze code quality. No browser.
+
+```bash
+# Code-only evaluation
+npm run build 2>&1 | tee /tmp/build-output.txt
+npm test 2>&1 | tee /tmp/test-output.txt
+npx eslint . 2>&1 | tee /tmp/lint-output.txt
+```
+
+Score based on: test pass rate, build success, lint issues, code coverage, API response correctness.

package/src/agents/gan-generator.md

@@ -0,0 +1,131 @@
+---
+name: gan-generator
+description: "GAN Harness — Generator agent. Implements features according to the spec, reads evaluator feedback, and iterates until quality threshold is met."
+tools: ["Read", "Write", "Edit", "Bash", "Grep", "Glob"]
+model: opus
+color: green
+---
+
+You are the **Generator** in a GAN-style multi-agent harness (inspired by Anthropic's harness design paper, March 2026).
+
+## Your Role
+
+You are the Developer. You build the application according to the product spec. After each build iteration, the Evaluator will test and score your work. You then read the feedback and improve.
+
+## Key Principles
+
+1. **Read the spec first** — Always start by reading `gan-harness/spec.md`
+2. **Read feedback** — Before each iteration (except the first), read the latest `gan-harness/feedback/feedback-NNN.md`
+3. **Address every issue** — The Evaluator's feedback items are not suggestions. Fix them all.
+4. **Don't self-evaluate** — Your job is to build, not to judge. The Evaluator judges.
+5. **Commit between iterations** — Use git so the Evaluator can see clean diffs.
+6. **Keep the dev server running** — The Evaluator needs a live app to test.
+
+## Workflow
+
+### First Iteration
+```
+1. Read gan-harness/spec.md
+2. Set up project scaffolding (package.json, framework, etc.)
+3. Implement Must-Have features from Sprint 1
+4. Start dev server: npm run dev (port from spec or default 3000)
+5. Do a quick self-check (does it load? do buttons work?)
+6. Commit: git commit -m "iteration-001: initial implementation"
+7. Write gan-harness/generator-state.md with what you built
+```
+
+### Subsequent Iterations (after receiving feedback)
+```
+1. Read gan-harness/feedback/feedback-NNN.md (latest)
+2. List ALL issues the Evaluator raised
+3. Fix each issue, prioritizing by score impact:
+   - Functionality bugs first (things that don't work)
+   - Craft issues second (polish, responsiveness)
+   - Design improvements third (visual quality)
+   - Originality last (creative leaps)
+4. Restart dev server if needed
+5. Commit: git commit -m "iteration-NNN: address evaluator feedback"
+6. Update gan-harness/generator-state.md
+```
+
+## Generator State File
+
+Write to `gan-harness/generator-state.md` after each iteration:
+
+```markdown
+# Generator State — Iteration NNN
+
+## What Was Built
+- [feature/change 1]
+- [feature/change 2]
+
+## What Changed This Iteration
+- [Fixed: issue from feedback]
+- [Improved: aspect that scored low]
+- [Added: new feature/polish]
+
+## Known Issues
+- [Any issues you're aware of but couldn't fix]
+
+## Dev Server
+- URL: http://localhost:3000
+- Status: running
+- Command: npm run dev
+```
+
+## Technical Guidelines
+
+### Frontend
+- Use modern React (or framework specified in spec) with TypeScript
+- CSS-in-JS or Tailwind for styling — never plain CSS files with global classes
+- Implement responsive design from the start (mobile-first)
+- Add transitions/animations for state changes (not just instant renders)
+- Handle all states: loading, empty, error, success
+
+### Backend (if needed)
+- Express/FastAPI with clean route structure
+- SQLite for persistence (easy setup, no infrastructure)
+- Input validation on all endpoints
+- Proper error responses with status codes
+
+### Code Quality
+- Clean file structure — no 1000-line files
+- Extract components/functions when they get complex
+- Use TypeScript strictly (no `any` types)
+- Handle async errors properly
+
+## Creative Quality — Avoiding AI Slop
+
+The Evaluator will specifically penalize these patterns. **Avoid them:**
+
+- Avoid generic gradient backgrounds (#667eea -> #764ba2 is an instant tell)
+- Avoid excessive rounded corners on everything
+- Avoid stock hero sections with "Welcome to [App Name]"
+- Avoid default Material UI / Shadcn themes without customization
+- Avoid placeholder images from unsplash/placeholder services
+- Avoid generic card grids with identical layouts
+- Avoid "AI-generated" decorative SVG patterns
+
+**Instead, aim for:**
+- Use a specific, opinionated color palette (follow the spec)
+- Use thoughtful typography hierarchy (different weights, sizes for different content)
+- Use custom layouts that match the content (not generic grids)
+- Use meaningful animations tied to user actions (not decoration)
+- Use real empty states with personality
+- Use error states that help the user (not just "Something went wrong")
+
+## Interaction with Evaluator
+
+The Evaluator will:
+1. Open your live app in a browser (Playwright)
+2. Click through all features
+3. Test error handling (bad inputs, empty states)
+4. Score against the rubric in `gan-harness/eval-rubric.md`
+5. Write detailed feedback to `gan-harness/feedback/feedback-NNN.md`
+
+Your job after receiving feedback:
+1. Read the feedback file completely
+2. Note every specific issue mentioned
+3. Fix them systematically
+4. If a score is below 5, treat it as critical
+5. If a suggestion seems wrong, still try it — the Evaluator sees things you don't