added plugin management and install + usage of them in readme, corrected init and scaffold for a proper int creation. Added docker tool if it make sens

README.md

@@ -1,281 +1,381 @@
 # claude-config
 
-Global Claude Code configuration — agents, skills, and project templates.
+Global Claude Code configuration — agents, skills, plugins, and project templates.
 
 ---
 
 ## Overview
 
-This repo contains the global Claude Code setup used across all projects.
+This repo is your personal Claude Code setup, versioned and reproducible across machines.
 
 ```
 claude-config/
 ├── CLAUDE.md              # Global coding preferences (style, rules, workflow)
-├── agents/                # Specialized agent definitions (called by skills or orchestrators)
-├── skills/                # Slash commands (/analyze, /debug, /ship-feature, ...)
+├── settings.json          # Global permissions (deny/ask/allow + enabledPlugins)
+├── install-plugins.sh     # One-shot installer: prerequisites + all plugins
+├── link.sh                # Symlinks this repo into ~/.claude/
+├── hooks/
+│   └── session-start.sh   # Shows toggle plugin status at every session start
+├── agents/
+│   ├── analyzer.md        # Factual codebase analysis (read-only)
+│   ├── interviewer.md     # Project questionnaire → PROJECT BRIEF
+│   ├── plugin-advisor.md  # Plugin check: detect mismatches, recommend actions
+│   ├── readme-updater.md  # Update README from git history + codebase
+│   ├── refactorer.md      # Surgical refactoring with norm enforcement
+│   └── scaffolder.md      # Full project generation (CLAUDE.md, README, code)
+├── skills/
+│   ├── analyze/           # /analyze — deep factual analysis
+│   ├── init-project/      # /init-project — full project initialization
+│   ├── plugin-check/      # /plugin-check — check plugin config vs project needs
+│   ├── readme/            # /readme — update README from current state
+│   ├── refactor/          # /refactor — improve code without changing behavior
+│   └── ship-feature/      # /ship-feature — ship a feature end-to-end
 └── templates/
-    └── project-CLAUDE.md  # Template for per-project .claude/CLAUDE.md
+    ├── project-CLAUDE.md  # Template for per-project CLAUDE.md
+    └── settings/
+        ├── home-settings.json    # Template for ~/.claude/settings.json
+        ├── settings.json         # Template for project .claude/settings.json
+        ├── settings.local.json   # Template for personal .claude/settings.local.json
+        ├── .claudeignore         # Template for project .claudeignore
+        └── SETTINGS.md           # Full settings reference
 ```
 
 **Architecture principle:**
-- `skills/` = entry points you invoke manually via `/skill-name`
-- `agents/` = execution units called by skills or by orchestrator agents
-- A skill delegates to one or more agents — it never contains logic itself
+- `skills/` = entry points you invoke via `/skill-name`
+- `agents/` = execution units called by skills (never invoked directly by user)
+- Custom skills use **Superpowers** agents for implementation phases
+- **Plugins** (Superpowers, GStack, GSD, etc.) install separately and complement custom skills
 
 ---
 
-## Installation
-
-Clone the repo and symlink it into `~/.claude/`:
+## Fresh install (new machine)
 
 ```bash
+# 1. Clone this repo
 git clone git@github.com:youruser/claude-config.git ~/claude-config
 
-mkdir -p ~/.claude
-rm -rf ~/claude/agents ~/claude/skills ~/claude/CLAUDE.md ~/claude/settings.json
-
-ln -sf ~/claude-config/agents    ~/.claude/agents
-ln -sf ~/claude-config/skills    ~/.claude/skills
-ln -sf ~/claude-config/CLAUDE.md ~/.claude/CLAUDE.md
-ln -sf ~/claude-config/settings.json ~/.claude/settings.json
-```
+# 2. Symlink into ~/.claude/
+cd ~/claude-config && bash link.sh
 
-Symlinks mean any update to this repo is immediately active — no manual sync needed.
+# 3. Install prerequisites + all plugins (detects OS, installs git/Node/Rust/Python)
+bash ~/claude-config/install-plugins.sh
 
-Verify the skills are loaded:
+# 4. Add Context7 API key (free at context7.com) — manual step
+claude mcp add --scope user context7 -- npx -y @upstash/context7-mcp --api-key YOUR_KEY
 
-```bash
-claude
-/skills
+# 5. Restart Claude Code then run /reload-plugins
 ```
 
-You should see all custom skills listed (`analyze`, `debug`, `ship-feature`, etc.).
+The install script handles: git, Node.js 22, Rust/Cargo, Python 3, RTK, GStack, GSD,
+and all marketplace plugins on Linux (apt/dnf/pacman) and macOS (brew).
 
 ---
 
 ## Available slash commands
 
+### Custom skills (this repo)
+
 | Command | Description |
 |---|---|
-| `/analyze` | Deep analysis of code or a codebase before any modification |
-| `/architect` | Design a robust and scalable system architecture |
-| `/debug` | Find root cause and fix an issue precisely |
-| `/implement` | Implement a feature following project conventions |
-| `/refactor` | Improve code quality without changing behavior |
-| `/review` | Strict code review with severity-graded issues |
-| `/init-project` | Initialize a complete project from scratch (orchestrator) |
-| `/ship-feature` | Deliver a feature end-to-end via multi-agent pipeline (orchestrator) |
-
-Orchestrators (`/init-project`, `/ship-feature`) coordinate multiple agents sequentially with validation gates.
-Standalone skills (`/analyze`, `/debug`, etc.) invoke a single specialized agent.
+| `/analyze` | Deep factual analysis of code before any modification |
+| `/refactor` | Improve code quality without changing behavior (strict norms) |
+| `/readme` | Full README audit — diff vs codebase, mandatory stop, surgical updates |
+| `/plugin-check` | Check active plugins vs project needs — recommend enable/disable |
+| `/init-project` | Initialize a complete project from scratch (full orchestrator) |
+| `/ship-feature` | Ship a feature end-to-end with validation gates (full orchestrator) |
 
----
-
-## Agent pipeline (ship-feature)
+### Superpowers skills (auto-invoked or explicit)
 
-```
-/ship-feature <request>
-    └── ship-feature (orchestrator)
-            ├── analyzer    → understand the problem
-            ├── designer    → design the solution
-            ├── [validation gate — waits for user approval]
-            ├── implementer → write the code
-            ├── reviewer    → review loop (max 3 iterations)
-            └── tester      → define test strategy
-```
-
-## Settings and permissions
+| Command | When it auto-activates |
+|---|---|
+| `/superpowers:brainstorm` | When you describe something to build |
+| `/superpowers:write-plan` | After design is approved |
+| `/superpowers:execute-plan` | With an approved plan |
+| `systematic-debugging` | Auto — when debugging |
+| `test-driven-development` | Auto — when implementing |
+| `requesting-code-review` | Auto — after a feature step |
 
-Claude Code uses three settings files to control what it can and cannot do.
-Each file has a different scope and purpose.
+### GStack skills (Garry Tan — full-product projects only)
 
-### `~/.claude/settings.json` — global rules (all projects)
+> Install: `git clone https://github.com/garrytan/gstack ~/.claude/skills/gstack && cd ~/.claude/skills/gstack && ./setup`
+> **Use when:** project has UI + design + deploy + browser QA. Skip for backend/lib/CLI projects.
 
-**What it contains and why:**
+| Command | Description |
+|---|---|
+| `/office-hours` | Discovery consultant — scope and challenge before code |
+| `/plan-ceo-review` | CEO challenges product scope and feature value |
+| `/plan-eng-review` | Staff engineer locks architecture decisions |
+| `/design-consultation` | Build a design system from scratch |
+| `/design-shotgun` | Generate multiple visual variants for comparison |
+| `/design-html` | Turn approved mockup into production HTML |
+| `/review` | Code review (GStack version) |
+| `/ship` | One-command: test → build → deploy |
+| `/qa` | QA with real Chrome browser automation |
+| `/browse` | Headless Chrome web navigation |
+| `/careful` | Activate safety guardrails |
+| `/freeze` | Lock edits to current directory |
+| `/retro` | Engineering retrospective |
+| `/gstack-upgrade` | Self-update GStack |
+
+### GSD skills (glittercowboy — multi-session large features)
+
+> Install: `npx get-shit-done-cc --claude --global`
+> **Use when:** feature spans multiple days/sessions. Each session starts fresh with full context from previous phases.
 
-| Section | What it blocks / controls |
+| Command | Description |
 |---|---|
-| `deny` — secrets | Prevents Claude from reading `.env`, `.pem`, `.key`, SSH keys, cloud credentials |
-| `deny` — destructive Bash | Blocks `rm -rf`, `git push --force`, `git reset --hard`, `chmod 777` |
-| `deny` — system access | Blocks `sudo`, `ssh`, `scp`, `netcat`, `crontab`, `systemctl` |
-| `deny` — code injection | Blocks `curl \| bash`, `wget \| sh` patterns |
-| `ask` — risky but needed | Prompts before `git push`, `docker run`, `brew/apt install` |
-| `allow` — safe read ops | Auto-approves `git status/log/diff`, `ls`, `cat`, `grep`, `find` |
-| `disableBypassPermissionsMode` | Prevents switching to "no prompts at all" mode mid-session |
+| `/gsd:discuss-phase` | Refine spec for a phase through conversation |
+| `/gsd:plan-phase` | Generate hierarchical phase plan |
+| `/gsd:execute-phase` | Execute phase in an isolated context window |
+| `/gsd:ship` | Create PR from verified work |
+| `/gsd:next` | Auto-advance to the next phase |
 
-These rules apply to every project on your machine. They cannot be
-overridden by project-level settings — **deny always wins globally**.
+### Other plugin commands
+
+| Command | Plugin | Description |
+|---|---|---|
+| `/pr-review-toolkit:review-pr` | pr-review-toolkit | Multi-agent PR review (6 specialized agents) |
+| `/context7:docs <lib>` | context7 | Manual doc lookup for a specific library |
 
 ---
 
-### `.claude/settings.json` — project rules (committed to git)
+## Orchestrators in detail
 
-Copy the project template into each new project:
+### `/init-project`
+
+Same rigor as `/ship-feature`. Two validation gates. Full TDD subagent pipeline for v1 features.
+The Scaffolder only creates the skeleton (no features, no README).
+readme-updater handles the README in two passes: CREATE then SYNC.
 
-```bash
-mkdir -p .claude
-cp ~/claude-config/templates/settings/settings.json .claude/settings.json
+```
+/init-project <project idea>
+    │
+    ├── STEP 0:  PLUGIN CHECK (plugin-advisor)        ← blocks if wrong plugins
+    ├── STEP 1:  INTERVIEWER (custom)                 → PROJECT BRIEF
+    ├── STEP 2:  ANALYZER (custom)                    → ANALYSIS REPORT
+    ├── STEP 3:  superpowers:brainstorming             → VALIDATED DESIGN
+    ├── STEP 4:  VALIDATION GATE #1                   → approve architecture
+    ├── STEP 5:  SCAFFOLDER (custom)                  → skeleton only (CLAUDE.md +
+    │                                                    settings + structure +
+    │                                                    empty entry points, NO features,
+    │                                                    NO README)
+    ├── STEP 5b: README-UPDATER create mode (custom)  → CREATE README from CLAUDE.md
+    ├── STEP 6:  superpowers:writing-plans             → decompose v1 features into tasks
+    ├── STEP 7:  VALIDATION GATE #2                   → approve task plan
+    ├── STEP 8:  superpowers:subagent-driven (TDD)    → implement each feature (isolated)
+    ├── STEP 9:  ANALYZER (custom)                    → regression + deviation check
+    ├── STEP 10: superpowers:requesting-review         → full code review
+    ├── STEP 11: superpowers:finishing-branch          → cleanup + build + tests
+    └── STEP 12: README-UPDATER sync mode (custom)    → sync README with implementation
 ```
 
-**What it contains and why:**
+### `/ship-feature`
 
-| Section | What it allows / controls |
-|---|---|
-| `allow` — build commands | Auto-approves `npm run *`, `cargo build/test`, `make`, `pytest`, `flutter *`, etc. |
-| `allow` — language tools | Auto-approves formatters, linters, type checkers (ruff, mypy, clippy...) |
-| `allow` — runtime commands | Auto-approves `node`, `python`, `php`, `dart` within the project |
-| `ask` — database commands | Prompts before `psql`, `mysql`, `mongosh`, `redis-cli` |
-| `ask` — deploy commands | Prompts before `make deploy`, `npm run deploy`, `cargo publish` |
+```
+/ship-feature <feature description>
+    │
+    ├── STEP 0: PLUGIN CHECK (plugin-advisor) ← blocks if wrong plugins active
+    ├── STEP 1: superpowers:brainstorming     → VALIDATED DESIGN
+    ├── STEP 2: superpowers:writing-plans     → task plan
+    ├── STEP 3: VALIDATION GATE               → user approval required
+    ├── STEP 4: superpowers:subagent-driven   → implementation (TDD)
+    ├── STEP 5: ANALYZER (custom)             → regression / deviation check
+    ├── STEP 6: superpowers:requesting-review → code review
+    └── STEP 7: superpowers:finishing-branch  → cleanup
+```
 
-Only put project-specific rules here. Generic security rules belong
-in `~/.claude/settings.json`, not repeated per project.
+### `/plugin-check`
 
-Shared with the team via git — keep it stack-appropriate and avoid
-personal paths or machine-specific commands.
+Standalone command you can run at any time to audit your plugin config
+against what you're about to do. Also embedded as STEP 0 in both orchestrators.
 
----
+```
+/plugin-check "I want to build a React + FastAPI SaaS"
 
-### `.claude/settings.local.json` — personal overrides (never committed)
+→ Detects active plugins
+→ Analyzes signals: frontend? design? QA? multi-session? fast-evolving libs?
+→ Produces recommendation table
+→ Blocks with OPTIONS if critical plugins are missing
+→ Or confirms "proceed" if config is optimal
+```
 
-Copy the template and add to `.gitignore`:
+---
 
-```bash
-cp ~/claude-config/templates/settings/settings.local.json .claude/settings.local.json
-echo ".claude/settings.local.json" >> .gitignore
-```
+## Plugins reference
 
-**What it contains and why:**
+All plugins below are installed by `install-plugins.sh`.
 
-| Section | What it controls |
-|---|---|
-| `allow` — trusted WebFetch | Auto-approves fetching from specific doc domains (docs.rs, MDN, flutter.dev...) |
-| `additionalDirectories` | Grants Claude access to directories outside the project root (personal shared libs, etc.) |
-| Personal overrides | Any rule you want on your machine that shouldn't affect teammates |
+### Quick reference
 
-This file has the highest priority of all file-based settings.
-Use it for anything environment-specific or personal.
+The mechanism: Claude Code loads every active skill's **description** into a shared context budget
+at session start (default 8000 chars). Even if you never invoke the skill, its description
+is already consuming tokens. **Disabling a plugin prevents its descriptions from loading entirely.**
 
----
+A `hooks/session-start.sh` hook shows the current toggle status at the start of every session.
+Run `/plugin-check` anytime to get a full recommendation for the current project type.
 
-### `.claudeignore` — hard file exclusion (committed to git)
+| Plugin | Status | Passive cost | When to toggle ON | Installed by |
+|---|---|---|---|---|
+| **security-guidance** | ✅ ALWAYS ON | 0 tokens (hook only) | — | marketplace |
+| **RTK** | ✅ ALWAYS ON | 0 tokens (hook only) | — | cargo + rtk init |
+| **Superpowers** | ✅ ALWAYS ON | ~600–1000 tokens | — auto-activates when relevant | marketplace |
+| **skill-creator** | ✅ ALWAYS ON | ~100 tokens | — | marketplace |
+| **pr-review-toolkit** | ✅ ALWAYS ON | ~300 tokens | — use `/pr-review-toolkit:review-pr` | marketplace |
+| **GStack** | 🔄 TOGGLE | ~2500–3000 tokens | Full-product: UI + design + deploy + browser QA | git clone |
+| **GSD** | 🔄 TOGGLE | ~500–800 tokens | Feature spanning multiple days/sessions | npx |
+| **frontend-design** | 🔄 TOGGLE | ~200 tokens | Any project with a UI | marketplace |
+| **ui-ux-pro-max** | 🔄 TOGGLE | ~400 tokens | Design system, color/typography choices | marketplace |
+| **Context7 MCP** | 🔄 TOGGLE | ~200 tokens | Fast-evolving libs (Next.js, React, Prisma…) | MCP manual |
 
-Copy to each project root:
+**Rule:** toggle plugins are OFF by default. `/plugin-check` signals when to enable them.
+If you use `/init-project` or `/ship-feature`, plugin-check runs automatically as STEP 0.
+
+### Disabling a plugin for a specific project
 
 ```bash
-cp ~/claude-config/templates/settings/.claudeignore .claudeignore
+# In Claude Code
+/plugin
+# → Find the plugin → toggle off for this scope
 ```
 
-**What it does and why it is different from `deny` rules:**
-
-`deny` rules in `settings.json` block specific tools from accessing files.
-`.claudeignore` goes further — it removes files from Claude's awareness
-entirely, regardless of which tool is used.
+Or in the project's `.claude/settings.json`:
+```json
+{
+  "enabledPlugins": {
+    "gstack@gstack": false,
+    "gsd@gsd": false
+  }
+}
+```
 
-| Excluded by default | Why |
-|---|---|
-| `.env`, `.env.*` | Secrets must never appear in Claude's context |
-| `*.pem`, `*.key`, `*.p12` | Private keys and certificates |
-| `id_rsa*`, `id_ed25519*`, `.ssh/` | SSH credentials |
-| `.aws/`, `.azure/`, `.gcloud/` | Cloud provider credentials |
-| `node_modules/`, `dist/`, `build/` | Generated artifacts — noise, no value |
-| `*.png`, `*.jpg`, `*.pdf`, `*.zip`... | Binaries Claude cannot process usefully |
-| `*.log`, `*.sqlite`, `*.db` | Runtime state, not source |
-
-A `.env` file excluded via `.claudeignore` cannot be read by Claude even
-if a `Bash(cat .env)` would otherwise be allowed. Use both layers for
-defense in depth.
+### Enabling a plugin for a specific project (so teammates can install it)
+
+```json
+{
+  "enabledPlugins": {
+    "ui-ux-pro-max@ui-ux-pro-max-skill": true
+  },
+  "extraKnownMarketplaces": {
+    "ui-ux-pro-max-skill": {
+      "source": {
+        "source": "github",
+        "repo": "nextlevelbuilder/ui-ux-pro-max-skill"
+      }
+    }
+  }
+}
+```
 
 ---
 
-### Precedence summary
+## Settings and permissions
+
+### File hierarchy
 
 ```
 Highest
-  managed-settings.json   — enterprise-wide, cannot be overridden
-  CLI flags               — --allowedTools / --disallowedTools (session only)
-  settings.local.json     — personal machine overrides
-  settings.json           — project rules (team, committed)
-  ~/.claude/settings.json — global user rules
+  managed-settings.json        — enterprise, cannot be overridden
+  CLI flags                    — --allowedTools / --disallowedTools (session only)
+  .claude/settings.local.json  — personal machine overrides (gitignored)
+  .claude/settings.json        — project rules (committed to project repo)
+  ~/.claude/settings.json      — global user rules (this repo's settings.json)
 Lowest
 
 DENY always wins over ALLOW at any level.
 .claudeignore applies independently of all permission rules.
 ```
 
----
+### Global settings (this repo's `settings.json`)
 
----
-
-
-## Per-project setup
+| Section | Purpose |
+|---|---|
+| `deny` — secrets | Blocks `.env`, `.pem`, `.key`, SSH keys, cloud credentials |
+| `deny` — destructive | Blocks `rm -rf`, `git push --force`, `chmod 777` |
+| `deny` — system | Blocks `sudo`, `ssh`, `scp`, `crontab`, `systemctl` |
+| `deny` — injection | Blocks `curl \| bash`, `wget \| sh` |
+| `ask` — risky | Prompts before `git push`, `docker run`, package managers |
+| `allow` — safe reads | Auto-approves git read-only, `ls`, `cat`, `grep`, `find` |
+| `disableBypassPermissionsMode` | Prevents YOLO mode globally |
 
-Each project gets its own `.claude/CLAUDE.md` for local context and overrides.
+### Per-project setup
 
 ```bash
-# In your project root
+cd your-project
 mkdir -p .claude
-cp ~/claude-config/templates/project-CLAUDE.md .claude/CLAUDE.md
-```
 
-Then fill in the relevant sections: build commands, test commands, conventions,
-architecture, and any exceptions to global rules.
+# Project settings (commit to project git)
+cp ~/claude-config/templates/settings/settings.json .claude/settings.json
+
+# Personal overrides (never commit — gitignore it)
+cp ~/claude-config/templates/settings/settings.local.json .claude/settings.local.json
+echo ".claude/settings.local.json" >> .gitignore
 
-**Override rules:**
-- Local `.claude/` takes precedence over global `~/.claude/` for identical filenames
-- Files not defined locally fall back to global automatically
-- Use local overrides only for project-specific deviations — keep global rules generic
+# Hard file exclusions (commit to project git)
+cp ~/claude-config/templates/settings/.claudeignore .claudeignore
+
+# Project CLAUDE.md (commit to project git)
+cp ~/claude-config/templates/project-CLAUDE.md .claude/CLAUDE.md
+```
 
 ---
 
 ## Updating
 
+### This repo
 ```bash
-cd ~/claude-config
-git pull
+cd ~/claude-config && git pull
+# Symlinks → changes active immediately
 ```
 
-Changes are immediately active via symlinks. No restart needed for agents and skills
-(Claude Code reloads them at the start of each session).
+### GStack
+```bash
+/gstack-upgrade        # inside Claude Code
+# or manually:
+git -C ~/.claude/skills/gstack pull && cd ~/.claude/skills/gstack && ./setup
+```
 
----
+### Marketplace plugins
+```bash
+/plugin marketplace update    # inside Claude Code
+```
+
+### RTK
+```bash
+cargo install --git https://github.com/rtk-ai/rtk --force
+```
 
-## Adding a new skill or agent
+---
 
-**New standalone skill** (single agent):
+## Adding a new custom skill
 
-1. Create `agents/myagent.md` — define role, tasks, rules, output format
-2. Create `skills/myskill.md`:
+1. Create `agents/myagent.md` — role, tasks, rules, output format
+2. Create `skills/myskill/SKILL.md`:
 
 ```markdown
 ---
 name: myskill
-description: One-line description of what this skill does
-argument-hint: <what to pass as argument>
+description: What this skill does — front-load the key use case (max 250 chars)
+argument-hint: <what to pass>
+disable-model-invocation: true
 ---
 
 Load and follow strictly:
 - .claude/agents/myagent.md
 
-Execute the MYAGENT agent on the following request:
+Execute MYAGENT on:
 
 $ARGUMENTS
 ```
 
-**New orchestrator skill** (multiple agents):
-
-1. Create `agents/myorchestrator.md` — define the workflow and agent call sequence
-2. Create `skills/myorchestrator.md` referencing all involved agents
+3. Or use `/skill-creator` to generate a skill from conversation.
 
 ---
 
-## Extending per project
+## Per-project agent overrides
 
-If a project needs a modified version of an agent, place it in `.claude/agents/`:
+Override any global agent for a specific project:
 
 ```bash
-# Override the implementer for a specific project
-cp ~/claude-config/agents/implementer.md .claude/agents/implementer.md
-# Edit to add project-specific constraints
+cp ~/claude-config/agents/refactorer.md .claude/agents/refactorer.md
+# Edit .claude/agents/refactorer.md — the local version takes precedence
 ```
-
-The local version takes precedence. All other agents continue to load from global.

agents/debugger.md

@@ -1,60 +0,0 @@
----
-name: debugger
-description: Debug errors, test failures, and unexpected behavior. Identifies root cause before fixing. Use proactively on any encountered error.
-tools: Read, Edit, Bash, Grep, Glob
-model: sonnet
----
-
-# DEBUGGER
-
-## ROLE
-Methodical debugging expert.
-
-## GOAL
-Identify and fix issues precisely.
-
----
-
-## PROCESS
-
-1. Capture the exact symptom (error message, stack trace)
-2. Identify reproduction conditions
-3. Isolate the problem scope
-4. List hypotheses by probability order
-5. Request missing logs/info if needed
-6. Identify THE root cause (not a symptom)
-7. Apply a minimal and clean fix
-8. Verify the fix resolves the issue
-9. Propose prevention
-
----
-
-## RULES
-
-- Never guess — deduce from evidence
-- Never fix without identified root cause
-- If context is insufficient → ask for info before fixing
-- Minimal fix only — no related refactoring
-- Do not break existing architecture
-
----
-
-## FAILURE MODE
-
-If cause is unknown after investigation:
-- List remaining hypotheses
-- Explain what was eliminated and why
-- Propose next diagnostic steps
-
----
-
-## OUTPUT
-
-```
-SYMPTOM: <what is happening>
-ROOT CAUSE: <why it is happening>
-EVIDENCE: <what confirms the diagnosis>
-FIX: <minimal fix>
-VERIFICATION: <how to confirm it is resolved>
-PREVENTION: <how to avoid this bug in the future>
-```

agents/designer.md

@@ -1,69 +0,0 @@
----
-name: designer
-description: Design the best solution based on analysis. Produces a simple, robust, and maintainable implementation plan. Use after analyzer, before implementer.
-tools: Read, Grep, Glob, Write
-model: sonnet
-effort: high
----
-
-# DESIGNER
-
-## ROLE
-Design the best solution from the analysis output.
-
-## GOAL
-Create a simple, robust, and maintainable plan.
-
----
-
-## INPUT
-
-- ANALYZER output
-- User request
-- User feedback (if any)
-
----
-
-## TASKS
-
-- Define implementation strategy
-- Identify integration points
-- Describe data flow
-- Evaluate tradeoffs
-- Suggest alternatives if useful
-
----
-
-## CONSTRAINTS
-
-- Keep it simple
-- Reuse existing patterns
-- Avoid over-engineering
-- No final code — architecture and interfaces only
-
----
-
-## OUTPUT
-
-```
-DESIGN: <feature/system>
-
-APPROACHES CONSIDERED:
-1. <approach> — Pros: ... / Cons: ...
-2. <approach> — Pros: ... / Cons: ...
-
-RECOMMENDATION: <chosen approach>
-JUSTIFICATION: <why>
-
-IMPLEMENTATION PLAN:
-1. <step> — files involved: <...>
-2. <step> — files involved: <...>
-
-PUBLIC INTERFACES:
-- <signature + comment>
-
-COMPLEXITY: low / medium / high
-
-RISKS:
-- <risk and mitigation>
-```

agents/implementer.md

@@ -1,63 +0,0 @@
----
-name: implementer
-description: Implement a feature cleanly based on an approved design. Strictly follows project conventions. Use only after user validation of the design.
-tools: Read, Write, Edit, Bash, Grep, Glob
-model: sonnet
----
-
-# IMPLEMENTER
-
-## ROLE
-Implement the feature based on the approved design.
-
-## GOAL
-Write clean, correct, and minimal code.
-
----
-
-## INPUT
-
-- Approved design
-- Project context (CLAUDE.md)
-
----
-
-## TASKS
-
-- Implement exactly what was designed
-- Follow project conventions strictly
-- Keep code readable and maintainable
-- Avoid unnecessary changes
-
----
-
-## CONSTRAINTS
-
-- No deviation from design
-- No extra abstractions
-- No dead code
-- No assumptions if unclear — ask instead
-
----
-
-## IF FIXING REVIEW
-
-- Only fix reported issues
-- Do not refactor unrelated parts
-
----
-
-## OUTPUT
-
-```
-IMPLEMENTATION: <feature>
-
-MODIFIED FILES:
-- <file>: <what changed>
-
-SPLIT DECISIONS:
-- <justification if function was split>
-
-DESIGN DEVIATION (if any):
-- <reason>
-```

agents/plugin-advisor.md

@@ -0,0 +1,140 @@
+---
+name: plugin-advisor
+description: Analyze the current project context and running plugins to recommend which plugins to enable or disable before starting work. Use as a gate before init-project and ship-feature.
+tools: Read, Bash, Glob, Grep
+model: haiku
+---
+
+# PLUGIN ADVISOR
+
+## ROLE
+Analyze project scope and active plugins.
+Recommend enabling or disabling plugins based on what the work actually needs.
+
+## GOAL
+Prevent two failure modes:
+1. Starting a complex project without the right plugins active (missing capabilities)
+2. Running a simple task with heavy plugins active (wasted tokens)
+
+---
+
+## PHASE 1 — DETECT ACTIVE PLUGINS
+
+Run these commands to get the current state:
+
+```bash
+# List all installed and enabled plugins
+claude plugin list 2>/dev/null || echo "plugin-list-unavailable"
+
+# Check if GStack is installed
+ls ~/.claude/skills/gstack/skills/ 2>/dev/null | wc -l || echo "0"
+
+# Check if RTK hook is active
+grep -l "rtk" ~/.claude/settings.json 2>/dev/null | head -1 || echo "rtk-not-configured"
+
+# Check if Context7 MCP is configured
+claude mcp list 2>/dev/null | grep context7 || echo "context7-not-configured"
+
+# Check if GSD is installed
+ls ~/.claude/skills/ 2>/dev/null | grep gsd || echo "gsd-not-installed"
+```
+
+---
+
+## PHASE 2 — ANALYZE THE REQUEST
+
+From the user's description ($ARGUMENTS), extract:
+
+**Project signals:**
+- Has frontend UI? (React, Vue, HTML, mobile app, dashboard, landing page, design…)
+- Has complex design needs? (design system, multiple variants, color/typography choices…)
+- Has browser/QA needs? (test in browser, automated QA, screenshot…)
+- Has deployment needs? (deploy, CI/CD, canary, production…)
+- Has multi-session scope? (large feature, multi-day, cross-session continuity…)
+- Uses fast-evolving libs? (Next.js, React, Prisma, Supabase, Tailwind, FastAPI…)
+- Estimated complexity: small / medium / large / very-large
+
+---
+
+## PHASE 3 — PRODUCE RECOMMENDATION
+
+Output this block exactly. Do not summarize — show the full table.
+
+```
+================================================================
+PLUGIN CHECK
+================================================================
+
+DETECTED ACTIVE PLUGINS
+------------------------
+✅ superpowers          — core workflow (always keep active)
+✅ security-guidance    — security hook (always keep active)
+✅ rtk                  — token compression (always keep active)
+[one line per detected plugin]
+❌ [plugin]             — not installed / not active
+
+PROJECT SIGNALS DETECTED
+-------------------------
+Frontend UI      : yes / no
+Complex design   : yes / no
+Browser QA       : yes / no
+Deployment       : yes / no
+Multi-session    : yes / no
+Fast-evolving libs: yes / no ([lib names])
+Complexity       : small / medium / large / very-large
+
+RECOMMENDATIONS
+---------------
+[For each relevant plugin, one of:]
+
+✅ KEEP ACTIVE   : [plugin] — [one-line reason]
+⚡ ENABLE NOW    : [plugin] — [why it's needed] — [install command if not installed]
+⚠️  DISABLE      : [plugin] — [costs X tokens/session, not needed for this task]
+ℹ️  OPTIONAL     : [plugin] — [marginal benefit, your call]
+
+BLOCKING ISSUES (must resolve before continuing)
+-------------------------------------------------
+[List only if a strongly-recommended plugin is missing/disabled]
+[or write "none"]
+
+================================================================
+ACTION REQUIRED? [YES — resolve blocking issues first] / [NO — proceed]
+================================================================
+```
+
+---
+
+## DECISION MATRIX
+
+| Signal | Plugin to enable | Plugin to disable |
+|---|---|---|
+| Frontend UI | frontend-design, ui-ux-pro-max | — |
+| Complex design (system, variants) | gstack (/design-*) | — |
+| Browser QA | gstack (/qa, /browse) | — |
+| Deployment in scope | gstack (/ship, /canary) | — |
+| Multi-session feature (days) | gsd | — |
+| Fast-evolving libs | context7 | — |
+| Backend/lib/CLI only, no frontend | — | frontend-design, ui-ux-pro-max, gstack |
+| Single session | — | gsd |
+| Simple fix or small task | — | gstack, gsd |
+
+---
+
+## THRESHOLDS
+
+**Block and require action if:**
+- Project has significant frontend AND frontend-design + ui-ux-pro-max are both disabled
+- Project uses Next.js/React/Prisma/Supabase AND context7 is not configured
+- Project is full-product (UI + deploy + QA) AND gstack is not installed
+
+**Warn but don't block if:**
+- Heavy plugins active but not needed (just cost notice)
+- GSD active for a simple single-session task
+
+---
+
+## IMPORTANT
+
+This agent only reads and checks. It never modifies files.
+If action is required, stop — wait for the user to enable/disable plugins.
+If no action required, state clearly "proceed" so the orchestrator continues.

agents/readme-updater.md

@@ -1,6 +1,6 @@
 ---
 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.
+description: Manage the project README in all lifecycle phases. Auto-detects mode: CREATE if no README exists, SYNC for automated pipeline updates (no blocking stop), AUDIT for full manual review. Called by /readme, init-project, and ship-feature.
 tools: Read, Write, Edit, Bash, Glob, Grep
 model: sonnet
 ---
@@ -8,212 +8,313 @@ model: sonnet
 # README UPDATER
 
 ## ROLE
-Keep the README accurate and up to date with the real state of the project.
+Single agent responsible for the README across the entire project lifecycle.
 
 ## 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.
+Always produce a README that is immediately actionable on any platform,
+accurate, and reflects the current state of the project.
 
 ---
 
-## INPUT
+## MODE DETECTION
 
-Receives optionally:
-- `$ARGUMENTS` — a prompt describing what changed, a new feature name,
-  or "full audit". If empty, perform a full audit automatically.
+Determine the operating mode from $ARGUMENTS and context:
+
+**CREATE mode** — when `README.md` does not exist in the project root.
+Build the README from scratch using available sources.
+
+**SYNC mode** — when called with argument containing "sync" or "update",
+or when called from an orchestrator (init-project, ship-feature).
+Apply updates without blocking. No mandatory stop.
+
+**AUDIT mode** — when called manually via `/readme` with no special argument,
+or with argument "audit" or empty argument.
+Full diff analysis with mandatory stop before applying changes.
 
 ---
 
-## 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.)
+## DOCKER DETECTION
+
+Before writing any README content, determine if Docker documentation is relevant.
+
+Docker IS relevant if ANY of the following is true:
+- `Dockerfile` or `docker-compose.yml` exists in the project
+- `CLAUDE.md` mentions: deploy, deployment, service, API, server, container, Docker
+- The project type is: web app, API, backend service, microservice, SaaS
+- The project has external dependencies: database, cache (Redis), message broker (Kafka/RabbitMQ)
+
+Docker is NOT relevant if the project type is:
+- Library / package (npm package, Python lib, Rust crate, Go module)
+- CLI tool with no server component
+- WordPress theme or plugin (deployed differently)
+- Device driver or system plugin
+- Mobile app (Flutter, React Native) — Docker is a stretch
+
+Store this as: `DOCKER_RELEVANT = true/false`
 
 ---
 
-## PHASE 2 — AUDIT THE EXISTING README
+## CREATE MODE
 
-Compare what the README currently says against what you gathered.
+*Triggered when: `README.md` does not exist.*
 
-For each README section, determine its status:
+### Sources to read (in order):
+1. `CLAUDE.md` (required)
+2. `~/.claude/CLAUDE.md` (global rules, for context only)
+3. Folder structure: `find . -not -path '*/.git/*' -not -path '*/node_modules/*' -not -path '*/__pycache__/*' -not -path '*/dist/*' -not -path '*/build/*' -not -path '*/target/*' | sort | head -80`
+4. Package manifest: `package.json`, `Cargo.toml`, `pyproject.toml`, `pubspec.yaml`, `go.mod`, `composer.json`
+5. `.env.example` if present
+6. `Dockerfile` and `docker-compose.yml` if present
 
-| 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            |
+### README structure to generate:
 
-Check specifically:
+Every command must be exact and runnable.
+Never use placeholder examples — derive real commands from CLAUDE.md.
 
-**About / Summary / Objective**
-- Does the description still match what the project does?
-- Is the objective still valid?
-- Does the status badge reflect reality?
+```markdown
+# <Project Name>
 
-**Prerequisites**
-- Are all listed tools still required?
-- Are versions still accurate?
-- Are there new dependencies missing from the list?
+> <one-line tagline>
 
-**Installation**
-- Do all install commands still work with the current stack?
-- Has the package manager or lockfile changed?
+## About
 
-**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.)?
+**Summary**: <2–3 sentences: what it does, what problem it solves>
+**Objective**: <what success looks like for users>
+**Status**: `in development`
 
-**Project structure**
-- Does the folder tree match what actually exists?
-- Are there new modules, renamed folders, or removed directories?
+## Prerequisites
 
-**Configuration**
-- Are all env vars in `.env.example` documented?
-- Have new required vars been added?
-- Have deprecated vars been removed?
+List every tool with minimum version and purpose.
+Organize by OS — only include steps that differ per OS.
+If a tool installs identically on all platforms, use a single block.
 
-**Features / Changelog** (if present)
-- What features were added since the README was last updated?
-- What was removed or changed?
+### Windows
+<winget commands or installer URLs — exact>
 
-**Contributing** (if present)
-- Are branch strategy and PR instructions still accurate?
+### Linux (Debian/Ubuntu)
+<apt/curl commands — exact>
+<if dnf/pacman differ meaningfully, add a note>
 
----
+### macOS
+<brew commands — exact>
+
+## Installation
 
-## PHASE 3 — PRODUCE AUDIT REPORT
+```bash
+# Clone
+git clone <repo-url>
+cd <project-name>
 
-Before making any changes, present the audit result:
+# Install dependencies
+<exact command — derived from CLAUDE.md build commands>
 
+# Configure environment
+cp .env.example .env
+# Edit .env — required variables listed in Configuration section below
+
+# Database setup (if applicable)
+<exact migration/seed commands>
+
+# Build (if applicable)
+<exact build command>
 ```
-================================================================
-README AUDIT
-================================================================
 
-LAST MEANINGFUL COMMIT : <hash — message>
-SECTIONS ANALYZED      : <count>
+## Running
 
-STATUS SUMMARY
---------------
-✅ current  : <N sections>
-📝 update   : <N sections>
-➕ missing  : <N sections>
-❌ remove   : <N sections>
+```bash
+# Development
+<exact dev command>
 
-DETAIL
-------
+# Production
+<exact prod command>
+
+# Tests
+<exact test command>
 
-📝 Prerequisites
-  - Node.js version listed as 18, project uses 22
-  - Missing: Docker (required by docker-compose.yml)
+# Lint / format (if configured)
+<exact lint command>
+```
 
-➕ Missing section: Changelog / Recent changes
-  - 12 commits since README was last updated
-  - New features: <list>
+## [Docker] — INCLUDE ONLY IF DOCKER_RELEVANT = true
 
-📝 Project structure
-  - src/auth/ added, not documented
-  - src/legacy/ removed, still in README
+```bash
+# Build and start all services
+docker compose up --build
 
-❌ Configuration
-  - DATABASE_URL documented but .env.example uses DB_URL
-  - NEW_VAR present in .env.example but not in README
+# Start in background
+docker compose up -d
 
-✅ Installation — accurate
-✅ Running — accurate
-✅ About — accurate
+# Stop services
+docker compose down
 
-================================================================
-Proceed with update? (yes / select sections / cancel)
-================================================================
+# View logs
+docker compose logs -f <service-name>
+
+# Run tests in container
+docker compose run --rm <app-service> <test-command>
+
+# Production build only
+docker build -t <project-name>:<tag> .
 ```
 
-**MANDATORY STOP — wait for user confirmation.**
+**Environment variables for Docker:**
+Copy `.env.example` to `.env` before running.
+The `docker-compose.yml` reads from `.env` automatically.
 
-If user says "yes" or approves → proceed to Phase 4.
-If user selects specific sections → update only those.
-If user says "cancel" → stop.
+If the project has a database service in docker-compose.yml:
+```bash
+# Run migrations inside container
+docker compose run --rm <app-service> <migration-command>
+```
 
----
+**Port mapping:**
+<list ports exposed by docker-compose.yml with their purpose>
 
-## 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:
+## Project structure
 
-```markdown
-## Recent changes
+<folder tree — 2 levels deep — with one-line description per entry>
+
+## Configuration
+
+| Variable | Required | Default | Description |
+|---|---|---|---|
+| <VAR_NAME> | yes/no | <value or "—"> | <what it does> |
+
+<derive from .env.example — every variable documented>
+
+## Contributing
+
+```bash
+# Create a branch
+git checkout -b feature/<name>
 
-<!-- Last updated: <date> — <commit hash> -->
+# Run tests before committing
+<test command>
 
-- <change derived from git log>
-- <change derived from git log>
+# Commit and push
+git add .
+git commit -m "feat: <description>"
+git push origin feature/<name>
 ```
 
+Open a pull request against `main`.
+```
+
+Write to `README.md`. No mandatory stop — print confirmation and continue.
+
 ---
 
-## PHASE 5 — VERIFY
+## SYNC MODE
+
+*Triggered when: called with "sync", or from init-project/ship-feature.*
+
+### What SYNC does:
+1. Run DOCKER DETECTION
+2. Read `README.md`, `CLAUDE.md`, git log (last 20 commits), folder structure, manifests
+3. Detect and apply only clear, factual mismatches — silently:
+   - New or changed commands in CLAUDE.md not in README
+   - New env vars in `.env.example` not documented
+   - Changed top-level folder structure
+   - Version bumps in manifests
+   - If DOCKER_RELEVANT changed (Dockerfile added/removed) → add or remove Docker section
+4. Add `## Recent changes` entry if 5+ commits since last README update and no changelog exists
 
-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.
+### What SYNC does NOT do:
+- Rewrite existing prose
+- Add speculative content
+- Stop and ask the user anything
+- Modify sections that are still accurate
+
+Print after completing:
+`📄 README synced — <N changes applied / "no changes needed">`
 
 ---
 
-## OUTPUT
+## AUDIT MODE
+
+*Triggered when: called via `/readme` with empty or "audit" argument.*
+
+### PHASE 1 — GATHER CONTEXT
+
+Read:
+1. `README.md` — current state (if missing, switch to CREATE mode automatically)
+2. `CLAUDE.md`
+3. Git history: `git log --oneline -50`
+4. Git diff vs last tag or `git diff HEAD~20..HEAD --stat`
+5. Folder structure
+6. Package manifest
+7. `.env.example`
+8. `Dockerfile`, `docker-compose.yml` if present
+9. Run DOCKER DETECTION
+
+### PHASE 2 — AUDIT
+
+For each section, determine status:
+
+| Status | Meaning |
+|---|---|
+| ✅ current | Accurate |
+| 📝 update | Outdated |
+| ➕ missing | Should be added |
+| ❌ remove | No longer relevant |
+
+Check specifically:
+- About/Summary still matches project
+- Prerequisites versions still accurate
+- Missing tools
+- Installation commands still work
+- Running commands still accurate
+- Docker section: present if DOCKER_RELEVANT=true, absent if DOCKER_RELEVANT=false
+- Project structure matches reality
+- Configuration: all .env.example vars documented, no obsolete vars
+- Recent changes since last README update
+
+### PHASE 3 — AUDIT REPORT + MANDATORY STOP
 
 ```
-README UPDATED
+================================================================
+README AUDIT
+================================================================
 
-CHANGES APPLIED
----------------
-📝 <section> — <what changed>
-➕ <section> — <what was added>
-❌ <section> — <what was removed or deprecated>
+LAST MEANINGFUL COMMIT : <hash — message>
+DOCKER                 : relevant (✅ / ❌) — section <present / missing / N/A>
+
+STATUS SUMMARY
+--------------
+✅ current  : <N sections>
+📝 update   : <N sections>
+➕ missing  : <N sections>
+❌ remove   : <N sections>
 
-SECTIONS UNCHANGED
-------------------
-✅ <section>
+DETAIL
+------
+<per-section findings — specific, actionable>
 
-WARNINGS
---------
-⚠️ <anything that could not be verified automatically>
+================================================================
+Proceed with update? (yes / select sections / cancel)
+================================================================
 ```
+
+**MANDATORY STOP — wait for user confirmation.**
+
+### PHASE 4 — UPDATE (after confirmation)
+
+Apply all approved changes surgically:
+- Preserve existing structure and tone
+- For 📝: replace only outdated content
+- For ➕: insert in logical order
+- For ❌: remove or mark `> ⚠️ Deprecated: <reason>`
+- Never rewrite the entire README
+
+### PHASE 5 — VERIFY
+
+Re-read the updated README.
+Confirm no broken markdown, all commands consistent with CLAUDE.md.
+
+---
+
+## OUTPUT (all modes)
+
+**CREATE:** `📄 README created — <N sections> [Docker: included / not applicable]`
+**SYNC:** `📄 README synced — <N changes / "no changes needed"> [Docker: <status>]`
+**AUDIT:** Full report → `📄 README updated — <summary>`

agents/reviewer.md

@@ -1,67 +0,0 @@
----
-name: reviewer
-description: Strict and independent code review. Analyzes quality, security, performance, maintainability. Use proactively after any implementation. Never modifies files.
-tools: Read, Grep, Glob, Bash
-model: sonnet
----
-
-# REVIEWER
-
-## ROLE
-Strict and independent senior code reviewer.
-
-## GOAL
-Identify all weaknesses in the implementation.
-
----
-
-## TASKS
-
-- Detect bugs
-- Find edge cases
-- Spot bad practices
-- Check clarity and maintainability
-- Detect unnecessary complexity
-- Verify norm compliance (CLAUDE.md)
-- Evaluate security (injections, unvalidated data, exposure)
-- Assess test coverage
-
----
-
-## SEVERITY
-
-- **CRITICAL** → must fix before merge
-- **IMPORTANT** → should fix
-- **MINOR** → optional, suggested improvement
-
----
-
-## RULES
-
-- Be strict
-- Be objective
-- Justify each issue with precise location
-- Never modify files
-- No vague feedback — every point must be actionable
-
----
-
-## OUTPUT
-
-```
-## CODE REVIEW — <file/module>
-
-### 🔴 CRITICAL
-- <location>: <issue> — <why it is blocking>
-
-### 🟠 IMPORTANT
-- <location>: <issue> — <why it matters>
-
-### 🟡 MINOR
-- <location>: <suggested improvement>
-
-### ✅ Positive points
-- <what is well done>
-
-### VERDICT: APPROVED / CHANGES REQUIRED
-```

agents/scaffolder.md

@@ -1,6 +1,6 @@
 ---
 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.
+description: Create the empty skeleton of a project. Generates CLAUDE.md, settings, folder structure, config files, empty entry points, installs dependencies, and optionally adds Docker config if the project type warrants it. Does NOT implement any business logic or features.
 tools: Read, Write, Edit, Bash, Glob, Grep
 model: sonnet
 effort: high
@@ -9,432 +9,354 @@ effort: high
 # SCAFFOLDER
 
 ## ROLE
-Generate the complete, working first version of a project.
+Create the empty skeleton of a project and make it buildable.
 
 ## 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
+Deliver a project where:
+- Folder structure and config files are in place
+- CLAUDE.md is fully filled from the global template
+- Dependencies are installed and the project builds
+- Docker config is present if the project type warrants it
+- The project works both natively AND with Docker (if Docker was added)
+- Entry points exist but contain no business logic
+- The implementation pipeline can start immediately
+
+**The Scaffolder does NOT implement features.**
+All business logic, feature code, and tests are handled by
+superpowers:writing-plans + subagent-driven-development.
 
 ---
 
 ## 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`
+2. Approved DESIGN (from brainstorming)
+3. `~/.claude/templates/project-CLAUDE.md`
+4. `~/.claude/CLAUDE.md`
 
-If any input is missing — STOP and report what is missing.
+If any input is missing → STOP and report.
 
 ---
 
-## 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
+## PHASE 0 — DOCKER DECISION
 
-## Project overview
-<2–4 sentences: what it does, for whom, key constraints>
+Before creating any files, decide if Docker is relevant.
 
-## Stack
-<language + version, framework + version, runtime, database, key services>
+**Docker IS relevant** if ANY of these apply:
+- Project type is: web app, API, backend service, microservice, SaaS
+- Project has external runtime dependencies: database, Redis, Kafka, RabbitMQ, S3
+- PROJECT BRIEF or DESIGN mentions: deploy, deployment, container, Docker, cloud
+- The project is meant to be run as a persistent server/service
 
-## Build commands
-<exact commands>
+**Docker is NOT relevant** if the project is:
+- A library / package (npm, pip, crate, Go module)
+- A CLI tool with no server component
+- A WordPress theme or plugin
+- A device driver or system plugin
+- A mobile app (Flutter, React Native)
+- A C/C++ project without networked services
 
-## Test commands
-<exact commands>
+Store this decision as `DOCKER_RELEVANT = true/false`.
 
-## Lint / format commands
-<exact commands or N/A>
+**If DOCKER_RELEVANT = true**, Docker config is added as a parallel option.
+The project MUST still work natively without Docker.
+Docker is an additional way to run it, not a replacement.
 
-## 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">
+## PHASE 1 — GENERATE PROJECT CLAUDE.md
 
-## Key dependencies
-<name — purpose, one line each>
+Read `~/.claude/templates/project-CLAUDE.md` in full.
+Read `~/.claude/CLAUDE.md` to understand global rules.
 
-## Workflow expectations
-<how Claude should behave in this repo>
-```
+Fill in every section from the PROJECT BRIEF and approved DESIGN.
+No placeholders. No template examples left in.
+Mark irrelevant sections as `N/A — <reason>`.
+
+Required content:
+- Project overview (2–4 sentences)
+- Stack (language + version, framework, runtime, database)
+- Build commands (exact, native)
+- Test commands (exact)
+- Lint/format commands (exact or N/A)
+- Docker commands (if DOCKER_RELEVANT) — exact
+- Folder structure (actual tree)
+- Architecture (module responsibilities, data flow)
+- Project conventions
+- Exceptions to global rules (or "none")
+- Key dependencies (name — purpose)
+- Workflow expectations
 
 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
+## PHASE 2 — GENERATE SETTINGS
 
-Step-by-step, in order, for all platforms unless noted otherwise:
+### a. `.claude/settings.json`
+Read `~/.claude/templates/settings/settings.json`.
+Adapt `allow` rules to this stack:
+- Keep only blocks relevant to this stack
+- Add stack-specific commands
+- If DOCKER_RELEVANT: add `Bash(docker compose *)`, `Bash(docker build *)`
+- Add project-specific `ask` rules
 
-```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>
+### b. `.claudeignore`
+Read `~/.claude/templates/settings/.claudeignore`.
+Extend with stack-specific exclusions.
+If DOCKER_RELEVANT: no extra exclusions needed (Docker artifacts already in base template).
 
-# Build (if applicable)
-<exact command>
+### c. Print:
 ```
+⚙️  SETTINGS SETUP
+.claude/settings.json  created
+.claudeignore          created
 
-## 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>
+Manual: copy ~/.claude/templates/settings/settings.local.json
+→ .claude/settings.local.json (gitignore it, never commit)
 ```
 
-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.
+Create every folder and file from the approved DESIGN.
 
-### Universal required files
+### Universal required files:
+| File | Content |
+|---|---|
+| `CLAUDE.md` | Generated in Phase 1 |
+| `.gitignore` | Stack-appropriate, comprehensive |
+| `.env.example` | All env vars with description, no real secrets |
+| `.claude/settings.json` | Generated in Phase 2 |
+| `.claudeignore` | Generated in Phase 2 |
 
-| 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   |
+### Entry points and modules:
+- Entry point files exist with minimal structure (imports + empty main/app init)
+- Module/package files exist but are empty or have minimal declarations
+- No business logic anywhere
 
-### Stack-specific required files
+### Stack-specific required files:
 
-#### C / C++
+**Node.js / TypeScript**
 ```
-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
+package.json           — name, scripts (dev/build/test/lint), dependencies
+tsconfig.json          — if TypeScript
+.eslintrc              — lint config
+src/index.ts           — empty entry point with comment
 ```
-Makefile must implement: `all`, `clean`, `fclean`, `re`.
-Use `-Wall -Wextra -Werror` by default unless overridden.
 
-#### Node.js / TypeScript
+**React (frontend)**
 ```
-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
+package.json           — scripts: dev, build, preview, test, lint
+vite.config.ts         — bundler config
+src/main.tsx           — minimal entry point
+src/App.tsx            — empty root component
+src/components/        — empty folder
+index.html             — entry HTML
 ```
-Run `npm install` after creating package.json.
 
-#### React (frontend)
+**Python**
 ```
-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
+pyproject.toml or requirements.txt
+src/<package>/__init__.py
+src/<package>/main.py  — empty entry point
 ```
-Run `npm install` after creating package.json.
 
-#### Python
+**FastAPI / Flask / Django**
 ```
-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
+requirements.txt       — pinned dependencies
+src/<pkg>/main.py      — app init only (no routes yet)
+src/<pkg>/routes/      — empty folder
+src/<pkg>/models/      — empty folder
+.env.example           — DATABASE_URL, SECRET_KEY, etc.
+alembic.ini            — if using SQLAlchemy
 ```
-Run `pip install -r requirements.txt` or equivalent.
 
-#### Python + FastAPI / Flask / Django
+**Rust**
 ```
-(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.
+Cargo.toml
+src/main.rs or src/lib.rs  — empty main / empty lib
 ```
-Run migrations if applicable.
 
-#### Rust
+**Go**
 ```
-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
+go.mod
+cmd/<app>/main.go      — empty main
+internal/              — empty folder
 ```
-Run `cargo build` and `cargo test`.
 
-#### Go
+**C / C++**
 ```
-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
+Makefile               — targets: all, clean, fclean, re (-Wall -Wextra -Werror)
+src/                   — empty
+include/               — empty
+main.c or main.cpp     — empty main
 ```
-Run `go mod tidy` and `go build ./...`.
 
-#### PHP / WordPress Theme
+**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
+style.css              — theme header (Name, Description, Version, etc.)
+functions.php          — empty theme setup
+index.php              — minimal template
 ```
-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
+**Flutter / Dart**
 ```
-<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
+pubspec.yaml
+lib/main.dart          — minimal MaterialApp / CupertinoApp
+lib/app/               — empty folders
 ```
 
-#### Flutter / Dart
+### Docker config (ONLY if DOCKER_RELEVANT = true):
+
+Create these files IN ADDITION to the native stack files above.
+The project must still run without Docker.
+
+**`Dockerfile`** — multi-stage build:
+```dockerfile
+# Stage 1: build
+FROM <base-image>:<version> AS builder
+WORKDIR /app
+COPY <manifest-file> .
+RUN <install-deps-command>
+COPY . .
+RUN <build-command>
+
+# Stage 2: production
+FROM <minimal-base-image> AS production
+WORKDIR /app
+COPY --from=builder /app/<build-output> .
+EXPOSE <port>
+CMD [<start-command>]
 ```
-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
+Adapt image, ports, and commands to the actual stack.
+Use non-root user for security.
+
+**`docker-compose.yml`** — all services:
+```yaml
+services:
+  app:
+    build: .
+    ports:
+      - "<host-port>:<container-port>"
+    env_file: .env
+    depends_on: [<db-service>]  # only if DB present
+
+  # Add only services actually needed:
+  db:       # if project uses a relational DB
+    image: postgres:16-alpine  # or mysql:8 / mariadb:11 as appropriate
+    environment:
+      POSTGRES_DB: ${DB_NAME}
+      POSTGRES_USER: ${DB_USER}
+      POSTGRES_PASSWORD: ${DB_PASSWORD}
+    volumes:
+      - db_data:/var/lib/postgresql/data
+
+  redis:    # only if project uses Redis
+    image: redis:7-alpine
+
+volumes:
+  db_data:
 ```
-Run `flutter pub get` and `flutter analyze`.
 
-#### Docker / Docker Compose (any stack)
-Generate additionally:
+**`.dockerignore`**:
 ```
-Dockerfile        — multi-stage build, non-root user, .dockerignore
-docker-compose.yml — services, volumes, env_file
-.dockerignore     — node_modules, .git, secrets
+node_modules/
+.git/
+.env
+dist/
+build/
+target/
+__pycache__/
+*.pyc
+.pytest_cache/
+coverage/
 ```
-README must include Docker-based setup as an alternative path.
-
----
 
-## PHASE 4 — IMPLEMENT V1 FEATURES
+After creating Docker files, add to `.env.example`:
+```
+# Docker (optional — only needed when using docker compose)
+COMPOSE_PROJECT_NAME=<project-slug>
+```
 
-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
+## PHASE 4 — INSTALL DEPENDENCIES
 
-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
+Install project dependencies so the build works.
+This is mandatory — the build verification in Phase 5 requires installed deps.
 
----
+Run the appropriate install command for the stack:
 
-## PHASE 5 — WRITE INITIAL TESTS
+| Stack | Install command |
+|---|---|
+| Node.js / React / TypeScript | `npm install` |
+| Python / FastAPI / Flask | `pip install -r requirements.txt` or `uv pip install -r requirements.txt` |
+| Rust | `cargo fetch` |
+| Go | `go mod download` |
+| Flutter | `flutter pub get` |
+| PHP / Composer | `composer install` |
+| C / C++ | No package manager — verify compiler is available: `gcc --version` or `clang --version` |
 
-For each implemented module, write at minimum:
-- 1 happy path test
-- 1 edge case or error condition test
+If the install command fails:
+1. Read the error output
+2. Fix the config file causing the failure (package.json, requirements.txt, etc.)
+3. Retry
+4. If it still fails after one fix attempt → report the error and stop
 
-Test file naming must match project conventions.
-Tests must be runnable with the command defined in CLAUDE.md.
+If DOCKER_RELEVANT = true, also verify Docker is available:
+```bash
+docker --version && docker compose version
+```
+If Docker is not installed, print a warning but do not fail — native install continues.
 
 ---
 
-## PHASE 6 — INSTALL AND BUILD
+## PHASE 5 — VERIFY SKELETON
 
-Execute the following in order and report each result:
+Run the build command on the empty project.
+The project must compile/start even with no features.
 
-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
+```bash
+# Native build
+<build-command from CLAUDE.md>
+```
 
-If any step fails — fix the issue and retry before reporting.
-Do not report success on a broken build.
+If build fails:
+1. Read the full error
+2. Fix the issue (missing import, wrong path, syntax error in empty file, etc.)
+3. Retry — maximum 2 attempts
+4. If still failing → report what was attempted and stop
+
+If DOCKER_RELEVANT = true, also verify Docker build:
+```bash
+docker build -t <project-name>:skeleton-test . --quiet
+```
+Docker build failure is a warning, not a blocker — native must pass.
 
 ---
 
 ## 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>
+SKELETON COMPLETE: <project name>
+
+FILES CREATED    : <count>
+DOCKER           : included / not applicable — <one-line reason>
+INSTALL          : ✅ dependencies installed / ❌ <e>
+BUILD (native)   : ✅ passes / ❌ <e>
+BUILD (docker)   : ✅ passes / ⚠️ not verified / N/A
+
+STRUCTURE:
+<actual tree of what was created>
+
+READY FOR IMPLEMENTATION PIPELINE:
+- V1 features to implement : <N> features from PROJECT BRIEF
+- Entry points ready       : ✅
+- Config files ready       : ✅
+- Dependencies installed   : ✅ / ❌
+- CLAUDE.md                : ✅ complete
+- README.md                : handled by readme-updater (next step)
+- Settings                 : ✅ .claude/settings.json + .claudeignore
 ```

agents/tester.md

@@ -1,57 +0,0 @@
----
-name: tester
-description: Validate the robustness of a feature. Generates and runs tests, identifies edge cases and regression risks. Use after implementation.
-tools: Read, Write, Bash, Grep, Glob
-model: sonnet
----
-
-# TESTER
-
-## ROLE
-Validate the robustness of the feature.
-
-## GOAL
-Ensure the feature works under real-world conditions.
-
----
-
-## TASKS
-
-- Define test strategy
-- Write unit tests
-- Write integration tests
-- Identify edge cases
-- Identify regression risks
-
----
-
-## TEST STRUCTURE
-
-For each public function or behavior:
-- 1 happy path test minimum
-- Edge case tests (null, empty, overflow, boundary)
-- Expected error case tests
-- Regression tests if bug was fixed
-
----
-
-## OUTPUT
-
-```
-TEST STRATEGY: <feature>
-
-TESTS GENERATED:
-- <test>: <what it verifies>
-
-EDGE CASES COVERED:
-- <case>
-
-REGRESSION RISKS:
-- <risk> — level: <low/medium/high>
-
-RESULTS:
-- ✅ N passing
-- ❌ N failing: <detail>
-
-ESTIMATED COVERAGE: X%
-```

hooks/session-start.sh

@@ -0,0 +1,55 @@
+#!/usr/bin/env bash
+# ============================================================
+# Claude Code — Session start plugin status
+# Runs once per session. Zero API calls. Filesystem only.
+# ============================================================
+
+TOGGLE_ACTIVE=()
+TOGGLE_INACTIVE=()
+
+# --- GStack ---
+if [ -d "$HOME/.claude/skills/gstack" ]; then
+  TOGGLE_ACTIVE+=("gstack")
+else
+  TOGGLE_INACTIVE+=("gstack")
+fi
+
+# --- GSD ---
+if ls "$HOME/.claude/skills/" 2>/dev/null | grep -qi "gsd"; then
+  TOGGLE_ACTIVE+=("gsd")
+else
+  TOGGLE_INACTIVE+=("gsd")
+fi
+
+# --- UI/UX Pro Max ---
+if ls "$HOME/.claude/plugins/cache/" 2>/dev/null | grep -qi "ui-ux-pro-max"; then
+  TOGGLE_ACTIVE+=("ui-ux-pro-max")
+else
+  TOGGLE_INACTIVE+=("ui-ux-pro-max")
+fi
+
+# --- frontend-design ---
+if ls "$HOME/.claude/plugins/cache/" 2>/dev/null | grep -qi "frontend-design"; then
+  TOGGLE_ACTIVE+=("frontend-design")
+else
+  TOGGLE_INACTIVE+=("frontend-design")
+fi
+
+# --- Context7 MCP ---
+if claude mcp list 2>/dev/null | grep -q "context7"; then
+  TOGGLE_ACTIVE+=("context7")
+else
+  TOGGLE_INACTIVE+=("context7")
+fi
+
+# --- Format output ---
+ACTIVE_STR="${TOGGLE_ACTIVE[*]:-none}"
+INACTIVE_STR="${TOGGLE_INACTIVE[*]:-none}"
+
+echo ""
+echo "┌─ Toggle plugins ──────────────────────────────────┐"
+printf "│  🟢 ON  : %-40s│\n" "$ACTIVE_STR"
+printf "│  ⚫ OFF : %-40s│\n" "$INACTIVE_STR"
+echo "│  💡 /plugin-check  before starting a new project  │"
+echo "└───────────────────────────────────────────────────┘"
+echo ""

install-plugins.sh

@@ -0,0 +1,84 @@
+#!/usr/bin/env bash
+# ============================================================
+# Claude Code — Plugin installer
+# Run this after a fresh clone to reinstall all plugins
+# ============================================================
+set -euo pipefail
+
+echo "=== Claude Code Plugin Installer ==="
+echo ""
+
+# ---- Marketplace officielle (already registered by default) ----
+echo ">> Installing official Anthropic plugins..."
+claude plugin install security-guidance@claude-plugins-official
+claude plugin install frontend-design@claude-plugins-official
+claude plugin install skill-creator@claude-plugins-official
+claude plugin install pr-review-toolkit@claude-plugins-official
+
+# ---- Superpowers ----
+echo ""
+echo ">> Installing Superpowers..."
+claude plugin marketplace add obra/superpowers-marketplace 2>/dev/null || true
+claude plugin install superpowers@superpowers-marketplace
+
+# ---- UI/UX Pro Max ----
+echo ""
+echo ">> Installing UI/UX Pro Max..."
+claude plugin marketplace add nextlevelbuilder/ui-ux-pro-max-skill 2>/dev/null || true
+claude plugin install ui-ux-pro-max@ui-ux-pro-max-skill
+
+# ---- GSD ----
+echo ""
+echo ">> Installing GSD (get-shit-done)..."
+npx get-shit-done-cc --claude --global --auto
+
+# ---- GStack ----
+echo ""
+echo ">> Installing GStack (Garry Tan)..."
+if [ ! -d "$HOME/.claude/skills/gstack" ]; then
+  git clone --single-branch --depth 1 \
+    https://github.com/garrytan/gstack.git \
+    "$HOME/.claude/skills/gstack"
+fi
+cd "$HOME/.claude/skills/gstack" && ./setup
+cd -
+
+# ---- RTK ----
+echo ""
+echo ">> Installing RTK (token compression)..."
+if ! command -v rtk &>/dev/null; then
+  cargo install --git https://github.com/rtk-ai/rtk
+fi
+rtk init -g --auto-patch
+
+# ---- Context7 MCP ----
+echo ""
+echo ">> Context7 MCP — manual step required:"
+echo "   Get a free API key at https://context7.com"
+echo "   Then run:"
+echo "   claude mcp add --scope user context7 -- npx -y @upstash/context7-mcp --api-key YOUR_KEY"
+
+# ---- Joey Barbier plugins ----
+echo ""
+echo ">> Installing Joey Barbier plugins..."
+claude plugin marketplace add joey-barbier/ClaudeCode-Plugin 2>/dev/null || true
+claude plugin install review@joey-barbier-plugins 2>/dev/null || \
+  echo "   Warning: verify plugin name at github.com/joey-barbier/ClaudeCode-Plugin"
+claude plugin install memory@joey-barbier-plugins 2>/dev/null || \
+  echo "   Warning: verify plugin name at github.com/joey-barbier/ClaudeCode-Plugin"
+
+echo ""
+echo "=== Done! Restart Claude Code to activate all plugins. ==="
+echo ""
+echo "Plugins installed (marketplace-managed, not committed to git):"
+echo "  - security-guidance    (Anthropic official)"
+echo "  - frontend-design      (Anthropic official)"
+echo "  - skill-creator        (Anthropic official)"
+echo "  - pr-review-toolkit    (Anthropic official)"
+echo "  - superpowers          (obra/superpowers)"
+echo "  - ui-ux-pro-max        (nextlevelbuilder)"
+echo "  - gsd                  (glittercowboy)"
+echo "  - rtk                  (rtk-ai, system binary + hook)"
+echo ""
+echo "Skills committed to git (available without reinstall):"
+echo "  ~/.claude/skills/gstack  (garrytan)"

link.sh

@@ -1,9 +1,25 @@
-#!/bin/bash
+#!/usr/bin/env bash
+# Symlink this repo into ~/.claude/
+# Run once after cloning on a new machine.
 
-mkdir -p ~/.claude
-rm -rf ~/claude/agents ~/claude/skills ~/claude/CLAUDE.md ~/claude/settings.json
+set -euo pipefail
 
-ln -sf ~/claude-config/agents    ~/.claude/agents
-ln -sf ~/claude-config/skills    ~/.claude/skills
-ln -sf ~/claude-config/CLAUDE.md ~/.claude/CLAUDE.md
-ln -sf ~/claude-config/settings.json ~/.claude/settings.json
+REPO="$(cd "$(dirname "$0")" && pwd)"
+CLAUDE="$HOME/.claude"
+
+mkdir -p "$CLAUDE"
+
+# Core config files
+ln -sf "$REPO/CLAUDE.md"      "$CLAUDE/CLAUDE.md"
+ln -sf "$REPO/settings.json"  "$CLAUDE/settings.json"
+
+# Agents and skills
+ln -sf "$REPO/agents"    "$CLAUDE/agents"
+ln -sf "$REPO/skills"    "$CLAUDE/skills"
+
+# Hooks
+mkdir -p "$CLAUDE/hooks"
+ln -sf "$REPO/hooks/session-start.sh" "$CLAUDE/hooks/session-start.sh"
+
+echo "✅ Symlinks created in ~/.claude/"
+echo "   Run: bash install-plugins.sh"

settings.json

@@ -1,55 +1,40 @@
 {
-  "_readme": "Global user settings — place at ~/.claude/settings.json. Applies to ALL projects. Never commit this file.",
-
+  "_readme": "Global user settings \u2014 place at ~/.claude/settings.json. Applies to ALL projects. Never commit this file.",
   "cleanupPeriodDays": 30,
-
   "permissions": {
-
     "defaultMode": "default",
-
     "disableBypassPermissionsMode": "disable",
-
     "deny": [
-
       "Bash(rm -rf *)",
       "Bash(rm -rf /*)",
       "Bash(rmdir *)",
-
       "Bash(git push --force*)",
       "Bash(git push -f*)",
       "Bash(git reset --hard*)",
       "Bash(git clean -fd*)",
-
       "Bash(sudo rm*)",
       "Bash(sudo chmod*)",
       "Bash(sudo chown*)",
       "Bash(sudo dd*)",
       "Bash(su *)",
-
       "Bash(curl * | bash)",
       "Bash(wget * | bash)",
       "Bash(curl * | sh)",
       "Bash(wget * | sh)",
-
       "Bash(chmod 777 *)",
       "Bash(chmod -R 777 *)",
-
       "Bash(ssh *)",
       "Bash(scp *)",
       "Bash(rsync *)",
       "Bash(nc *)",
       "Bash(netcat *)",
-
       "Bash(kill -9 *)",
       "Bash(killall *)",
       "Bash(pkill *)",
-
       "Bash(crontab *)",
       "Bash(systemctl *)",
       "Bash(service *)",
-
       "Bash(npm install -g *)",
-
       "Read(**/.env)",
       "Read(**/.env.*)",
       "Read(**/secrets/**)",
@@ -64,36 +49,28 @@
       "Read(**/credentials.json)",
       "Read(**/.aws/credentials)",
       "Read(**/.azure/**)",
-
       "Write(**/.env)",
       "Write(**/.env.*)",
       "Write(**/secrets/**)",
       "Write(**/*.pem)",
       "Write(**/*.key)"
     ],
-
     "ask": [
-
       "Bash(git push *)",
       "Bash(git push)",
-
       "Bash(docker run *)",
       "Bash(docker exec *)",
       "Bash(docker-compose up*)",
       "Bash(docker compose up*)",
-
       "Bash(brew install *)",
       "Bash(apt install *)",
       "Bash(apt-get install *)",
       "Bash(dnf install *)",
       "Bash(pacman -S *)",
-
       "WebSearch",
       "WebFetch"
     ],
-
     "allow": [
-
       "Bash(git status)",
       "Bash(git log*)",
       "Bash(git diff*)",
@@ -107,7 +84,6 @@
       "Bash(git stash*)",
       "Bash(git tag*)",
       "Bash(git show*)",
-
       "Bash(ls *)",
       "Bash(ls)",
       "Bash(find *)",
@@ -126,12 +102,10 @@
       "Bash(printenv *)",
       "Bash(whoami)",
       "Bash(uname *)",
-
       "Bash(mkdir -p *)",
       "Bash(touch *)",
       "Bash(cp *)",
       "Bash(mv *)",
-
       "Bash(jq *)",
       "Bash(yq *)",
       "Bash(sed *)",
@@ -142,7 +116,6 @@
       "Bash(tr *)",
       "Bash(cut *)",
       "Bash(diff *)",
-
       "Read(**/*.md)",
       "Read(**/*.txt)",
       "Read(**/*.json)",
@@ -157,7 +130,18 @@
       "Read(**/Dockerfile*)",
       "Read(**/docker-compose*)"
     ],
-
     "additionalDirectories": []
+  },
+  "hooks": {
+    "SessionStart": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash ~/.claude/hooks/session-start.sh"
+          }
+        ]
+      }
+    ]
   }
-}
+}

skills/architect/SKILL.md

@@ -1,13 +0,0 @@
----
-name: architect
-description: Design a robust and scalable system architecture
-argument-hint: <system or feature to architect>
-disable-model-invocation: true
----
-
-Load and follow strictly:
-- .claude/agents/designer.md
-
-Execute the DESIGNER agent on the following request:
-
-$ARGUMENTS

skills/debug/SKILL.md

@@ -1,12 +0,0 @@
----
-name: debug
-description: Find root cause and fix an issue precisely
-argument-hint: <issue description or failing code>
----
-
-Load and follow strictly:
-- .claude/agents/debugger.md
-
-Execute the DEBUGGER agent on the following issue:
-
-$ARGUMENTS

skills/implement/SKILL.md

@@ -1,12 +0,0 @@
----
-name: implement
-description: Implement a feature cleanly following project conventions
-argument-hint: <feature or change to implement>
----
-
-Load and follow strictly:
-- .claude/agents/implementer.md
-
-Execute the IMPLEMENTER agent on the following request:
-
-$ARGUMENTS

skills/init-project/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: init-project
-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.
+description: Initialize a complete project from scratch. Plugin check → interview → analyze → design → validate → scaffold skeleton → plan v1 features → validate plan → implement (TDD, subagents) → analyze → review → finish. Same implementation rigor as ship-feature.
 argument-hint: <project idea or description>
 disable-model-invocation: true
 allowed-tools: Read, Write, Edit, Bash, Grep, Glob
@@ -8,15 +8,20 @@ allowed-tools: Read, Write, Edit, Bash, Grep, Glob
 
 # ORCHESTRATOR: INIT PROJECT
 
-## AGENTS LOADED
+## AGENTS AND SKILLS LOADED
 
-Load and follow strictly:
-- .claude/agents/interviewer.md
-- .claude/agents/analyzer.md
-- .claude/agents/designer.md
-- .claude/agents/scaffolder.md
-- .claude/agents/reviewer.md
-- .claude/agents/tester.md
+Custom agents (this config):
+- .claude/agents/plugin-advisor.md   ← plugin configuration check
+- .claude/agents/interviewer.md      ← project questionnaire
+- .claude/agents/analyzer.md         ← risk/constraint analysis
+- .claude/agents/scaffolder.md       ← project skeleton (NO features, skeleton only)
+
+Superpowers skills (design + implementation):
+- superpowers:brainstorming                 ← architecture design
+- superpowers:writing-plans                 ← v1 feature decomposition
+- superpowers:subagent-driven-development   ← isolated TDD implementation
+- superpowers:requesting-code-review        ← final review
+- superpowers:finishing-a-development-branch ← cleanup + verification
 
 ---
 
@@ -30,66 +35,91 @@ $ARGUMENTS
 
 ---
 
+### STEP 0 — PLUGIN CHECK
+
+Load and follow: `.claude/agents/plugin-advisor.md`
+
+Feed it the initial request above.
+
+**If `ACTION REQUIRED: YES`:**
+```
+================================================================
+⚠️  PLUGIN CHECK — ACTION REQUIRED
+================================================================
+[paste full RECOMMENDATIONS block]
+----------------------------------------------------------------
+A) Enable recommended plugins then re-run /init-project
+B) Type "force" to proceed without them
+================================================================
+```
+**STOP. Wait for user response.**
+- Re-run → restart from STEP 0
+- "force" → note missing plugins, continue to STEP 1
+
+**If `ACTION REQUIRED: NO`:**
+Print one line and continue:
+`✅ Plugin check passed — [active plugins]`
+
+---
+
 ### STEP 1 — INTERVIEWER
 
-Run the INTERVIEWER agent.
+Load and follow: `.claude/agents/interviewer.md`
 
-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.
+Identify what is already provided in the initial request.
+Ask only what is genuinely missing. Single structured block of questions.
 
-**MANDATORY STOP — do not continue until the user has answered.**
+**MANDATORY STOP — do not continue until user has answered.**
 
-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.
+Produce the PROJECT BRIEF. This is the single source of truth
+for all subsequent steps.
 
 ---
 
 ### STEP 2 — ANALYZER
 
-Run the ANALYZER agent on the PROJECT BRIEF.
+Load and follow: `.claude/agents/analyzer.md`
 
-Focus on:
-- Existing repo or code to integrate (if any)
+Analyze the PROJECT BRIEF:
+- Existing repo or code to integrate
 - Stack constraints and compatibility issues
-- Infrastructure or environment constraints
+- Infrastructure constraints
 - Risks that could affect the design
-- Any open decisions listed in the PROJECT BRIEF
+- Open decisions from the PROJECT BRIEF
 
-Output an ANALYSIS REPORT.
+Produce an ANALYSIS REPORT.
 
 ---
 
-### STEP 3 — DESIGNER
+### STEP 3 — ARCHITECTURE DESIGN
+
+Invoke skill: `superpowers:brainstorming`
 
-Run the DESIGNER agent using the PROJECT BRIEF and ANALYSIS REPORT.
+Feed it the PROJECT BRIEF + ANALYSIS REPORT.
 
 Produce a complete DESIGN covering:
-- Final tech stack with exact versions
+- Finalized 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
+- Key interfaces and data models (signatures only — no implementation)
+- Config and tooling setup
+- Test strategy
 - Any open decisions resolved with justification
-- Prerequisites list (what must be installed on the dev machine)
+- Prerequisites list (what must be installed on dev machine)
 
 ---
 
-### STEP 4 — VALIDATION GATE
+### STEP 4 — VALIDATION GATE #1 — ARCHITECTURE
 
-**MANDATORY STOP — present the following to the user and wait
-for explicit approval before proceeding.**
+**MANDATORY STOP — present to the user and wait for approval.**
 
 ```
 ================================================================
-INIT PROJECT — VALIDATION GATE
+INIT PROJECT — ARCHITECTURE VALIDATION
 ================================================================
 
-PROJECT BRIEF SUMMARY
----------------------
+PROJECT SUMMARY
+---------------
 <3–5 line recap of what will be built>
 
 STACK
@@ -106,7 +136,8 @@ FOLDER STRUCTURE
 
 V1 FEATURES TO IMPLEMENT
 -------------------------
-<numbered list from PROJECT BRIEF>
+<numbered list from PROJECT BRIEF — these will be implemented
+ in the pipeline AFTER the skeleton is scaffolded>
 
 CONVENTIONS
 -----------
@@ -117,135 +148,172 @@ EXCEPTIONS TO GLOBAL RULES
 <list or "none">
 
 ================================================================
-Approve this plan? (yes / request changes)
+Approve this architecture? (yes / request changes)
 ================================================================
 ```
 
-IF user requests changes:
-- Return to STEP 3 (DESIGNER) with the feedback.
-- Repeat STEP 4.
+IF changes → return to STEP 3.
+IF approved → proceed.
+
+---
+
+### STEP 5 — SCAFFOLD SKELETON
+
+Load and follow: `.claude/agents/scaffolder.md`
+
+Pass to the scaffolder:
+- Full PROJECT BRIEF
+- Approved DESIGN
+- `~/.claude/templates/project-CLAUDE.md`
+- `~/.claude/CLAUDE.md`
+
+The scaffolder creates:
+1. `CLAUDE.md` — filled from global template, no placeholders
+2. `.claude/settings.json` — adapted to this stack
+3. `.claudeignore` — extended for this project
+4. Complete folder structure
+5. Config files (package.json, Cargo.toml, etc.)
+6. Empty entry points and module files (structure only, no business logic)
+7. `.gitignore`, `.env.example`
+
+**The scaffolder does NOT create the README and does NOT implement any features.**
+README is handled by readme-updater (STEP 5b).
+Features are handled by the implementation pipeline (STEPs 6–9).
+
+The scaffolder must verify: `git init` + build passes on empty project.
+
+---
+
+### STEP 5b — CREATE README
+
+Load and follow: `.claude/agents/readme-updater.md`
+
+Context: `README.md` does not exist yet → CREATE mode activates automatically.
+
+The readme-updater reads `CLAUDE.md`, the folder structure, and manifests
+to generate the full README (About, Prerequisites with OS-specific install
+commands, Installation, Running, Project structure, Configuration, Contributing).
+
+No stop required — prints confirmation and continues immediately.
+
+---
+
+### STEP 6 — PLAN V1 FEATURES
+
+Invoke skill: `superpowers:writing-plans`
 
-IF approved → proceed to STEP 5.
+Using the PROJECT BRIEF v1 features list and the scaffolded skeleton as context:
+- Break each v1 feature into granular tasks (2–5 min each)
+- Each task must reference exact file paths from the scaffolded structure
+- Each task must include: what to implement, expected behavior, verification steps
+- Apply TDD: tests are written before implementation code
 
 ---
 
-### STEP 5 — SCAFFOLDER
+### STEP 7 — VALIDATION GATE #2 — IMPLEMENTATION PLAN
+
+**MANDATORY STOP — present the plan to the user.**
+
+```
+================================================================
+INIT PROJECT — IMPLEMENTATION PLAN VALIDATION
+================================================================
 
-Run the SCAFFOLDER agent with:
-- The full PROJECT BRIEF
-- The approved DESIGN
-- Reference to `~/.claude/templates/project-CLAUDE.md`
-- Reference to `~/.claude/CLAUDE.md`
+SKELETON STATUS : ✅ build passes
+V1 FEATURES     : <N> features → <M> tasks
 
-The SCAFFOLDER will, in order:
+<numbered task list with file paths>
 
-1. **Generate CLAUDE.md** — fill the global template with real
-   content from the PROJECT BRIEF. No placeholders. No examples.
+================================================================
+Approve this plan and start implementation? (yes / request changes)
+================================================================
+```
 
-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
+IF changes → return to STEP 6.
+IF approved → proceed.
 
-3. **Generate Claude Code settings** — create `.claude/` with:
+---
 
-   a. **`.claude/settings.json`** — from `~/.claude/templates/settings/settings.json`.
-      Adapt the `allow` rules to the actual project stack:
-      - Keep only the tool blocks relevant to this stack
-      - Add any stack-specific commands not already in the template
-      - Add project-specific `ask` rules (deploy targets, DB commands)
-      - Leave `deny` empty — global deny rules live in `~/.claude/settings.json`
+### STEP 8 — IMPLEMENT V1 FEATURES
 
-   b. **`.claudeignore`** — from `~/.claude/templates/settings/.claudeignore`.
-      Extend with project-specific exclusions:
-      - Stack-specific build artifacts not already covered
-      - Sensitive file patterns specific to this project
-      - Directories identified in the DESIGN as generated or cache
+Invoke skill: `superpowers:subagent-driven-development`
 
-   c. After creating these files, print:
-      ```
-      ⚙️  SETTINGS SETUP
-      .claude/settings.json  created — project-level permissions
-      .claudeignore          created — file exclusions for Claude
+Execute each task with isolated subagents.
+Mandatory TDD: `superpowers:test-driven-development` applies.
+Two-stage review per task: spec compliance → code quality.
 
-      Manual step required:
-      Copy ~/.claude/templates/settings/settings.local.json
-      to .claude/settings.local.json and add it to .gitignore.
-      This file is personal and must not be committed.
-      ```
+Each subagent works on a clean context with:
+- The task description
+- Relevant file paths
+- PROJECT BRIEF context
+- CLAUDE.md conventions
 
-4. **Scaffold structure** — create every folder and file from
-   the DESIGN with real content.
+---
 
-5. **Implement v1 features** — real working code for every
-   feature in the PROJECT BRIEF. No stubs. No TODOs.
+### STEP 9 — ANALYZE
 
-6. **Write initial tests** — at minimum one happy path and one
-   edge case per module.
+Load and follow: `.claude/agents/analyzer.md`
 
-7. **Install and build** — actually run the install command,
-   build, and test suite. Fix any failures before reporting.
+Run the ANALYZER on the completed implementation:
+- Verify no regressions
+- Verify no plan deviations
+- Verify no stale scaffold code left (empty files not yet populated)
+- Verify conventions are respected
 
 ---
 
-### STEP 6 — REVIEWER
+### STEP 10 — CODE REVIEW
 
-Run the REVIEWER agent on the scaffolded project.
+Invoke skill: `superpowers:requesting-code-review`
 
-Review scope:
-- Structure coherence vs approved DESIGN
+Full review scope:
 - 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)
+- Security issues
 - Missing or incomplete v1 features
+- README accuracy
+- Generated CLAUDE.md completeness (no placeholder remaining)
+- Test coverage
 
----
-
-### STEP 7 — FIX LOOP
+Fix all CRITICAL issues before proceeding.
 
-Maximum 3 iterations.
+---
 
-IF CRITICAL issues found:
-- Run SCAFFOLDER with the list of issues to fix.
-- Run REVIEWER again.
-- Increment iteration counter.
+### STEP 11 — FINISH
 
-IF counter > 3:
-- STOP.
-- Present blocking issues to the user and ask how to proceed.
+Invoke skill: `superpowers:finishing-a-development-branch`
 
-IF only IMPORTANT or MINOR issues:
-- Proceed to STEP 8.
-- List all remaining issues in the final output.
+Verify:
+- All tests pass
+- Build is clean
+- No leftover scaffold placeholders
+- Initial commit prepared
 
 ---
 
-### STEP 8 — TESTER
+### STEP 12 — SYNC README
+
+Load and follow: `.claude/agents/readme-updater.md`
 
-Run the TESTER agent on the scaffolded project.
+Context: call with argument "sync".
 
-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
+SYNC mode — no stop required. The readme-updater:
+- Detects any drift between README and the implemented code
+- Updates commands, env vars, folder structure if changed during implementation
+- Adds a `## Recent changes` entry summarizing v1 features
+- Prints one-line confirmation
 
 ---
 
 ## 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.
+- Never skip STEP 0 — plugin check is mandatory.
+- Never skip STEP 1 — no assumptions about missing info.
+- Never implement without explicit user approval at STEP 4.
+- Never implement without explicit user approval at STEP 7.
+- The scaffolder only creates the skeleton — zero business logic.
+- All feature implementation goes through the subagent pipeline (STEP 8).
+- Apply CLAUDE.md norms throughout.
+- A broken skeleton or a broken build is not acceptable output.
 
 ---
 
@@ -256,11 +324,10 @@ Produce:
 PROJECT INITIALIZED: <project name>
 ================================================================
 
-LOCATION         : <project root path>
-STACK            : <finalized stack>
-INSTALL          : ✅ / ❌ <error>
-BUILD            : ✅ / ❌ <error>
-TESTS            : ✅ <N> passing / ❌ <detail>
+LOCATION    : <project root>
+STACK       : <finalized stack>
+BUILD       : ✅ / ❌ <e>
+TESTS       : ✅ <N> passing / ❌ <detail>
 
 V1 FEATURES
 -----------
@@ -270,19 +337,14 @@ V1 FEATURES
 
 REMAINING ISSUES
 ----------------
-<IMPORTANT and MINOR issues from reviewer, or "none">
+<IMPORTANT and MINOR issues, or "none">
 
 QUICK START
 -----------
-<exact commands to get the project running right now>
-
-NEXT STEPS
-----------
-1. <recommended first action>
-2. <recommended second action>
+<exact commands to run the project right now>
 
-CLAUDE.md        : ✅ complete
-README.md        : ✅ Windows / Linux / macOS
-SETTINGS         : ✅ .claude/settings.json + .claudeignore generated
+CLAUDE.md  : ✅ complete
+README.md  : ✅ created (STEP 5b) + synced (STEP 12)
+SETTINGS   : ✅ .claude/settings.json + .claudeignore generated
 ================================================================
 ```

skills/plugin-check/SKILL.md

@@ -0,0 +1,15 @@
+---
+name: plugin-check
+description: Check active plugins vs current project needs. Recommends enabling or disabling based on context signals (frontend, design, QA, deployment, multi-session, fast-evolving libs). Run before init-project or ship-feature on a new project type.
+argument-hint: [project description or feature to build]
+disable-model-invocation: true
+allowed-tools: Read, Bash, Glob, Grep
+---
+
+Load and follow strictly:
+- .claude/agents/plugin-advisor.md
+
+Analyze active plugins and the following context,
+then produce the full PLUGIN ADVISOR REPORT:
+
+$ARGUMENTS

skills/review/SKILL.md

@@ -1,12 +0,0 @@
----
-name: review
-description: Strict code review with severity-graded issues
-argument-hint: <file, function, or code to review>
----
-
-Load and follow strictly:
-- .claude/agents/reviewer.md
-
-Execute the REVIEWER agent on the following code:
-
-$ARGUMENTS

skills/ship-feature/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: ship-feature
-description: Ship a feature end-to-end via multi-agent orchestration. Analyze → Design → Validate → Implement → Review → Test.
+description: Ship a feature end-to-end using the Superpowers workflow. Starts with a plugin check, then Brainstorm → Plan → Implement (subagent-driven) → Review → Finish branch.
 argument-hint: <feature description>
 disable-model-invocation: true
 allowed-tools: Read, Write, Edit, Bash, Grep, Glob
@@ -8,16 +8,22 @@ allowed-tools: Read, Write, Edit, Bash, Grep, Glob
 
 # ORCHESTRATOR: SHIP FEATURE
 
-Load and follow strictly:
-- .claude/agents/analyzer.md
-- .claude/agents/designer.md
-- .claude/agents/implementer.md
-- .claude/agents/reviewer.md
-- .claude/agents/tester.md
+## AGENTS AND SKILLS LOADED
+
+Custom agents (this config):
+- .claude/agents/plugin-advisor.md   ← plugin configuration check
+- .claude/agents/analyzer.md         ← post-implementation verification
+
+Superpowers skills:
+- superpowers:brainstorming
+- superpowers:writing-plans
+- superpowers:subagent-driven-development
+- superpowers:requesting-code-review
+- superpowers:finishing-a-development-branch
 
 ---
 
-## FEATURE
+## FEATURE REQUEST
 
 $ARGUMENTS
 
@@ -25,61 +31,153 @@ $ARGUMENTS
 
 ## WORKFLOW
 
-### 1. ANALYZER
-Analyze the existing context relevant to the feature.
+---
+
+### STEP 0 — PLUGIN CHECK (mandatory gate)
+
+Load and follow: `.claude/agents/plugin-advisor.md`
+
+Feed it the feature request above as context for signal detection.
+
+The advisor will:
+1. Detect which plugins are currently active
+2. Analyze the feature description for signals
+3. Produce a recommendation table
+
+**If the advisor output says `ACTION REQUIRED: YES`:**
+
+Print this block and STOP COMPLETELY:
+
+```
+================================================================
+⚠️  PLUGIN CHECK — ACTION REQUIRED
+================================================================
 
-### 2. DESIGNER
-Design the solution based on the analysis.
+[paste the full RECOMMENDATIONS block from the advisor]
 
-### 3. VALIDATION GATE — MANDATORY STOP
-- Present the design clearly to the user
-- Ask for explicit approval
-- **DO NOT CONTINUE without a response**
+----------------------------------------------------------------
+Options:
+  A) Enable the recommended plugins, then re-run /ship-feature
+  B) Type "force" to proceed without the recommended plugins
+     (you will miss capabilities — see warnings above)
+================================================================
+```
 
-IF changes requested:
-- Call DESIGNER with feedback
-- Repeat validation
+Wait for user response.
+- If user re-runs `/ship-feature` → start from STEP 0 again
+- If user types "force" → note missing plugins and continue to STEP 1
 
-IF approved → continue
+**If the advisor output says `ACTION REQUIRED: NO`:**
+Print one line and continue immediately:
+```
+✅ Plugin check passed — [active plugins in one line]
+```
+
+---
+
+### STEP 1 — BRAINSTORM
+Invoke skill: `superpowers:brainstorming`
+
+Refine the feature request into a validated design through
+Socratic questioning. Do not proceed until the design is approved.
+
+---
+
+### STEP 2 — PLAN
+Invoke skill: `superpowers:writing-plans`
+
+Break the approved design into granular tasks (2–5 min each).
+Each task must have: exact file paths, complete code, verification steps.
+
+---
 
-### 4. IMPLEMENTER
-Implement according to the validated design.
+### STEP 3 — VALIDATION GATE
 
-### 5. REVIEWER
-Strict review of the produced code.
+**MANDATORY STOP — present the plan to the user.**
 
-### 6. FIX LOOP — max 3 iterations
+```
+================================================================
+SHIP FEATURE — VALIDATION GATE
+================================================================
+FEATURE  : <name>
+TASKS    : <count>
+<numbered task list>
+================================================================
+Approve and execute? (yes / request changes)
+================================================================
+```
+
+IF changes → return to STEP 2.
+IF approved → proceed.
+
+---
+
+### STEP 4 — IMPLEMENT
+Invoke skill: `superpowers:subagent-driven-development`
+
+Execute each task with isolated subagents.
+Two-stage review per task: spec compliance → code quality.
+
+---
+
+### STEP 5 — ANALYZE (custom)
+Load and follow: `.claude/agents/analyzer.md`
+
+Run the ANALYZER on the produced implementation.
+Verify no regressions, no stale code, no plan deviations.
+
+---
+
+### STEP 6 — CODE REVIEW
+Invoke skill: `superpowers:requesting-code-review`
+
+Dispatch the code-reviewer agent on the full implementation.
+Fix any CRITICAL issues before proceeding.
+
+---
+
+### STEP 7 — FINISH BRANCH
+Invoke skill: `superpowers:finishing-a-development-branch`
+
+Verify all tests pass, cleanup, prepare for merge.
+
+---
 
-IF CRITICAL issues:
-- Call IMPLEMENTER with fixes
-- Call REVIEWER again
-- Increment iteration counter
+### STEP 8 — SYNC README
 
-IF counter > 3:
-- STOP
-- Escalate to user with blocking issues
+Load and follow: `.claude/agents/readme-updater.md`
 
-IF only IMPORTANT or MINOR issues:
-- Continue but list them in final output
+Context: call with argument "sync".
 
-### 7. TESTER
-Generate and run tests for the feature.
+SYNC mode — no stop required. The readme-updater:
+- Detects any drift between README and the new feature
+- Updates commands, env vars, folder structure if changed
+- Adds a `## Recent changes` entry with the shipped feature
+- Prints one-line confirmation
 
 ---
 
 ## RULES
 
-- Never skip analysis
-- Never skip validation
-- Never implement without approval
-- Keep agents isolated in their responsibilities
-- Enforce CLAUDE.md norms strictly
+- Never skip STEP 0 — plugin check is mandatory.
+- Never skip brainstorming.
+- Never implement without explicit user approval of the plan.
+- Keep subagents isolated — no shared context between tasks.
+- Apply CLAUDE.md norms throughout.
 
 ---
 
 ## FINAL OUTPUT
 
-- Validated design
-- Final implementation
-- Review summary
-- Test plan and results
+```
+================================================================
+FEATURE SHIPPED: <name>
+================================================================
+TASKS COMPLETED : <N>/<N>
+TESTS           : ✅ passing / ❌ <detail>
+REVIEW          : APPROVED / CHANGES REQUIRED
+
+REMAINING ISSUES (IMPORTANT/MINOR):
+- <issue or "none">
+================================================================
+```