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
This commit is contained in:
bastien
parent
aaf7670b85
commit
b2df82d94d
482
README.md
482
README.md
@ -1,281 +1,381 @@
|
|||||||
# claude-config
|
# claude-config
|
||||||
|
|
||||||
Global Claude Code configuration — agents, skills, and project templates.
|
Global Claude Code configuration — agents, skills, plugins, and project templates.
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## Overview
|
## 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-config/
|
||||||
├── CLAUDE.md # Global coding preferences (style, rules, workflow)
|
├── CLAUDE.md # Global coding preferences (style, rules, workflow)
|
||||||
├── agents/ # Specialized agent definitions (called by skills or orchestrators)
|
├── settings.json # Global permissions (deny/ask/allow + enabledPlugins)
|
||||||
├── skills/ # Slash commands (/analyze, /debug, /ship-feature, ...)
|
├── 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/
|
└── 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:**
|
**Architecture principle:**
|
||||||
- `skills/` = entry points you invoke manually via `/skill-name`
|
- `skills/` = entry points you invoke via `/skill-name`
|
||||||
- `agents/` = execution units called by skills or by orchestrator agents
|
- `agents/` = execution units called by skills (never invoked directly by user)
|
||||||
- A skill delegates to one or more agents — it never contains logic itself
|
- Custom skills use **Superpowers** agents for implementation phases
|
||||||
|
- **Plugins** (Superpowers, GStack, GSD, etc.) install separately and complement custom skills
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## Installation
|
## Fresh install (new machine)
|
||||||
|
|
||||||
Clone the repo and symlink it into `~/.claude/`:
|
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
|
# 1. Clone this repo
|
||||||
git clone git@github.com:youruser/claude-config.git ~/claude-config
|
git clone git@github.com:youruser/claude-config.git ~/claude-config
|
||||||
|
|
||||||
mkdir -p ~/.claude
|
# 2. Symlink into ~/.claude/
|
||||||
rm -rf ~/claude/agents ~/claude/skills ~/claude/CLAUDE.md ~/claude/settings.json
|
cd ~/claude-config && bash link.sh
|
||||||
|
|
||||||
ln -sf ~/claude-config/agents ~/.claude/agents
|
# 3. Install prerequisites + all plugins (detects OS, installs git/Node/Rust/Python)
|
||||||
ln -sf ~/claude-config/skills ~/.claude/skills
|
bash ~/claude-config/install-plugins.sh
|
||||||
ln -sf ~/claude-config/CLAUDE.md ~/.claude/CLAUDE.md
|
|
||||||
ln -sf ~/claude-config/settings.json ~/.claude/settings.json
|
# 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
|
||||||
|
|
||||||
|
# 5. Restart Claude Code then run /reload-plugins
|
||||||
```
|
```
|
||||||
|
|
||||||
Symlinks mean any update to this repo is immediately active — no manual sync needed.
|
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).
|
||||||
Verify the skills are loaded:
|
|
||||||
|
|
||||||
```bash
|
|
||||||
claude
|
|
||||||
/skills
|
|
||||||
```
|
|
||||||
|
|
||||||
You should see all custom skills listed (`analyze`, `debug`, `ship-feature`, etc.).
|
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## Available slash commands
|
## Available slash commands
|
||||||
|
|
||||||
|
### Custom skills (this repo)
|
||||||
|
|
||||||
| Command | Description |
|
| Command | Description |
|
||||||
|---|---|
|
|---|---|
|
||||||
| `/analyze` | Deep analysis of code or a codebase before any modification |
|
| `/analyze` | Deep factual analysis of code before any modification |
|
||||||
| `/architect` | Design a robust and scalable system architecture |
|
| `/refactor` | Improve code quality without changing behavior (strict norms) |
|
||||||
| `/debug` | Find root cause and fix an issue precisely |
|
| `/readme` | Full README audit — diff vs codebase, mandatory stop, surgical updates |
|
||||||
| `/implement` | Implement a feature following project conventions |
|
| `/plugin-check` | Check active plugins vs project needs — recommend enable/disable |
|
||||||
| `/refactor` | Improve code quality without changing behavior |
|
| `/init-project` | Initialize a complete project from scratch (full orchestrator) |
|
||||||
| `/review` | Strict code review with severity-graded issues |
|
| `/ship-feature` | Ship a feature end-to-end with validation gates (full orchestrator) |
|
||||||
| `/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.
|
### Superpowers skills (auto-invoked or explicit)
|
||||||
Standalone skills (`/analyze`, `/debug`, etc.) invoke a single specialized agent.
|
|
||||||
|
| 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 |
|
||||||
|
|
||||||
|
### GStack skills (Garry Tan — full-product projects only)
|
||||||
|
|
||||||
|
> 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.
|
||||||
|
|
||||||
|
| 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.
|
||||||
|
|
||||||
|
| Command | Description |
|
||||||
|
|---|---|
|
||||||
|
| `/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 |
|
||||||
|
|
||||||
|
### 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 |
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## Agent pipeline (ship-feature)
|
## Orchestrators in detail
|
||||||
|
|
||||||
|
### `/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.
|
||||||
|
|
||||||
```
|
```
|
||||||
/ship-feature <request>
|
/init-project <project idea>
|
||||||
└── ship-feature (orchestrator)
|
│
|
||||||
├── analyzer → understand the problem
|
├── STEP 0: PLUGIN CHECK (plugin-advisor) ← blocks if wrong plugins
|
||||||
├── designer → design the solution
|
├── STEP 1: INTERVIEWER (custom) → PROJECT BRIEF
|
||||||
├── [validation gate — waits for user approval]
|
├── STEP 2: ANALYZER (custom) → ANALYSIS REPORT
|
||||||
├── implementer → write the code
|
├── STEP 3: superpowers:brainstorming → VALIDATED DESIGN
|
||||||
├── reviewer → review loop (max 3 iterations)
|
├── STEP 4: VALIDATION GATE #1 → approve architecture
|
||||||
└── tester → define test strategy
|
├── 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
|
||||||
```
|
```
|
||||||
|
|
||||||
|
### `/ship-feature`
|
||||||
|
|
||||||
|
```
|
||||||
|
/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
|
||||||
|
```
|
||||||
|
|
||||||
|
### `/plugin-check`
|
||||||
|
|
||||||
|
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"
|
||||||
|
|
||||||
|
→ 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
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Plugins reference
|
||||||
|
|
||||||
|
All plugins below are installed by `install-plugins.sh`.
|
||||||
|
|
||||||
|
### Quick reference
|
||||||
|
|
||||||
|
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.
|
||||||
|
|
||||||
|
| 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 |
|
||||||
|
|
||||||
|
**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
|
||||||
|
# In Claude Code
|
||||||
|
/plugin
|
||||||
|
# → Find the plugin → toggle off for this scope
|
||||||
|
```
|
||||||
|
|
||||||
|
Or in the project's `.claude/settings.json`:
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"enabledPlugins": {
|
||||||
|
"gstack@gstack": false,
|
||||||
|
"gsd@gsd": false
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### 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"
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
## Settings and permissions
|
## Settings and permissions
|
||||||
|
|
||||||
Claude Code uses three settings files to control what it can and cannot do.
|
### File hierarchy
|
||||||
Each file has a different scope and purpose.
|
|
||||||
|
|
||||||
### `~/.claude/settings.json` — global rules (all projects)
|
|
||||||
|
|
||||||
**What it contains and why:**
|
|
||||||
|
|
||||||
| Section | What it blocks / controls |
|
|
||||||
|---|---|
|
|
||||||
| `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 |
|
|
||||||
|
|
||||||
These rules apply to every project on your machine. They cannot be
|
|
||||||
overridden by project-level settings — **deny always wins globally**.
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
### `.claude/settings.json` — project rules (committed to git)
|
|
||||||
|
|
||||||
Copy the project template into each new project:
|
|
||||||
|
|
||||||
```bash
|
|
||||||
mkdir -p .claude
|
|
||||||
cp ~/claude-config/templates/settings/settings.json .claude/settings.json
|
|
||||||
```
|
|
||||||
|
|
||||||
**What it contains and why:**
|
|
||||||
|
|
||||||
| 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` |
|
|
||||||
|
|
||||||
Only put project-specific rules here. Generic security rules belong
|
|
||||||
in `~/.claude/settings.json`, not repeated per project.
|
|
||||||
|
|
||||||
Shared with the team via git — keep it stack-appropriate and avoid
|
|
||||||
personal paths or machine-specific commands.
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
### `.claude/settings.local.json` — personal overrides (never committed)
|
|
||||||
|
|
||||||
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
|
|
||||||
```
|
|
||||||
|
|
||||||
**What it contains and why:**
|
|
||||||
|
|
||||||
| 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 |
|
|
||||||
|
|
||||||
This file has the highest priority of all file-based settings.
|
|
||||||
Use it for anything environment-specific or personal.
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
### `.claudeignore` — hard file exclusion (committed to git)
|
|
||||||
|
|
||||||
Copy to each project root:
|
|
||||||
|
|
||||||
```bash
|
|
||||||
cp ~/claude-config/templates/settings/.claudeignore .claudeignore
|
|
||||||
```
|
|
||||||
|
|
||||||
**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.
|
|
||||||
|
|
||||||
| 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.
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
### Precedence summary
|
|
||||||
|
|
||||||
```
|
```
|
||||||
Highest
|
Highest
|
||||||
managed-settings.json — enterprise-wide, cannot be overridden
|
managed-settings.json — enterprise, cannot be overridden
|
||||||
CLI flags — --allowedTools / --disallowedTools (session only)
|
CLI flags — --allowedTools / --disallowedTools (session only)
|
||||||
settings.local.json — personal machine overrides
|
.claude/settings.local.json — personal machine overrides (gitignored)
|
||||||
settings.json — project rules (team, committed)
|
.claude/settings.json — project rules (committed to project repo)
|
||||||
~/.claude/settings.json — global user rules
|
~/.claude/settings.json — global user rules (this repo's settings.json)
|
||||||
Lowest
|
Lowest
|
||||||
|
|
||||||
DENY always wins over ALLOW at any level.
|
DENY always wins over ALLOW at any level.
|
||||||
.claudeignore applies independently of all permission rules.
|
.claudeignore applies independently of all permission rules.
|
||||||
```
|
```
|
||||||
|
|
||||||
---
|
### Global settings (this repo's `settings.json`)
|
||||||
|
|
||||||
---
|
| 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 |
|
||||||
|
|
||||||
|
### Per-project setup
|
||||||
## Per-project setup
|
|
||||||
|
|
||||||
Each project gets its own `.claude/CLAUDE.md` for local context and overrides.
|
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
# In your project root
|
cd your-project
|
||||||
mkdir -p .claude
|
mkdir -p .claude
|
||||||
|
|
||||||
|
# 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
|
||||||
|
|
||||||
|
# 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
|
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.
|
|
||||||
|
|
||||||
**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
|
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## Updating
|
## Updating
|
||||||
|
|
||||||
|
### This repo
|
||||||
```bash
|
```bash
|
||||||
cd ~/claude-config
|
cd ~/claude-config && git pull
|
||||||
git pull
|
# Symlinks → changes active immediately
|
||||||
```
|
```
|
||||||
|
|
||||||
Changes are immediately active via symlinks. No restart needed for agents and skills
|
### GStack
|
||||||
(Claude Code reloads them at the start of each session).
|
```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
|
## Adding a new custom skill
|
||||||
|
|
||||||
**New standalone skill** (single agent):
|
1. Create `agents/myagent.md` — role, tasks, rules, output format
|
||||||
|
2. Create `skills/myskill/SKILL.md`:
|
||||||
1. Create `agents/myagent.md` — define role, tasks, rules, output format
|
|
||||||
2. Create `skills/myskill.md`:
|
|
||||||
|
|
||||||
```markdown
|
```markdown
|
||||||
---
|
---
|
||||||
name: myskill
|
name: myskill
|
||||||
description: One-line description of what this skill does
|
description: What this skill does — front-load the key use case (max 250 chars)
|
||||||
argument-hint: <what to pass as argument>
|
argument-hint: <what to pass>
|
||||||
|
disable-model-invocation: true
|
||||||
---
|
---
|
||||||
|
|
||||||
Load and follow strictly:
|
Load and follow strictly:
|
||||||
- .claude/agents/myagent.md
|
- .claude/agents/myagent.md
|
||||||
|
|
||||||
Execute the MYAGENT agent on the following request:
|
Execute MYAGENT on:
|
||||||
|
|
||||||
$ARGUMENTS
|
$ARGUMENTS
|
||||||
```
|
```
|
||||||
|
|
||||||
**New orchestrator skill** (multiple agents):
|
3. Or use `/skill-creator` to generate a skill from conversation.
|
||||||
|
|
||||||
1. Create `agents/myorchestrator.md` — define the workflow and agent call sequence
|
|
||||||
2. Create `skills/myorchestrator.md` referencing all involved agents
|
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## 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
|
```bash
|
||||||
# Override the implementer for a specific project
|
cp ~/claude-config/agents/refactorer.md .claude/agents/refactorer.md
|
||||||
cp ~/claude-config/agents/implementer.md .claude/agents/implementer.md
|
# Edit .claude/agents/refactorer.md — the local version takes precedence
|
||||||
# Edit to add project-specific constraints
|
|
||||||
```
|
```
|
||||||
|
|
||||||
The local version takes precedence. All other agents continue to load from global.
|
|
||||||
@ -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>
|
|
||||||
```
|
|
||||||
@ -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>
|
|
||||||
```
|
|
||||||
@ -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>
|
|
||||||
```
|
|
||||||
140
agents/plugin-advisor.md
Normal file
140
agents/plugin-advisor.md
Normal file
@ -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.
|
||||||
@ -1,6 +1,6 @@
|
|||||||
---
|
---
|
||||||
name: readme-updater
|
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
|
tools: Read, Write, Edit, Bash, Glob, Grep
|
||||||
model: sonnet
|
model: sonnet
|
||||||
---
|
---
|
||||||
@ -8,104 +8,268 @@ model: sonnet
|
|||||||
# README UPDATER
|
# README UPDATER
|
||||||
|
|
||||||
## ROLE
|
## 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
|
## GOAL
|
||||||
Produce a README that reflects what the project actually is right now —
|
Always produce a README that is immediately actionable on any platform,
|
||||||
not what it was when it was initialized. Never remove valid content.
|
accurate, and reflects the current state of the project.
|
||||||
Never invent content. Only add, update, or mark as outdated.
|
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## INPUT
|
## MODE DETECTION
|
||||||
|
|
||||||
Receives optionally:
|
Determine the operating mode from $ARGUMENTS and context:
|
||||||
- `$ARGUMENTS` — a prompt describing what changed, a new feature name,
|
|
||||||
or "full audit". If empty, perform a full audit automatically.
|
**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
|
## DOCKER DETECTION
|
||||||
|
|
||||||
Read in this order:
|
Before writing any README content, determine if Docker documentation is relevant.
|
||||||
|
|
||||||
1. `README.md` — current state (if missing, report and stop)
|
Docker IS relevant if ANY of the following is true:
|
||||||
2. `CLAUDE.md` — project conventions, stack, architecture
|
- `Dockerfile` or `docker-compose.yml` exists in the project
|
||||||
3. `~/.claude/CLAUDE.md` — global rules (for context only)
|
- `CLAUDE.md` mentions: deploy, deployment, service, API, server, container, Docker
|
||||||
4. Git history — run `git log --oneline -50` to see recent commits
|
- The project type is: web app, API, backend service, microservice, SaaS
|
||||||
5. Git diff vs last tag or initial commit:
|
- The project has external dependencies: database, cache (Redis), message broker (Kafka/RabbitMQ)
|
||||||
- `git tag --sort=-creatordate | head -5`
|
|
||||||
- `git diff <last-tag>..HEAD --stat` or `git diff HEAD~20..HEAD --stat`
|
Docker is NOT relevant if the project type is:
|
||||||
if no tags exist
|
- Library / package (npm package, Python lib, Rust crate, Go module)
|
||||||
6. Current folder structure — `find . -not -path '*/.git/*'
|
- CLI tool with no server component
|
||||||
-not -path '*/node_modules/*' -not -path '*/__pycache__/*'
|
- WordPress theme or plugin (deployed differently)
|
||||||
-not -path '*/dist/*' -not -path '*/build/*' | sort`
|
- Device driver or system plugin
|
||||||
7. Package manifest if present:
|
- Mobile app (Flutter, React Native) — Docker is a stretch
|
||||||
- `package.json` → dependencies, scripts, version
|
|
||||||
- `Cargo.toml` → dependencies, version
|
Store this as: `DOCKER_RELEVANT = true/false`
|
||||||
- `pyproject.toml` / `requirements.txt`
|
|
||||||
- `pubspec.yaml`
|
|
||||||
- `composer.json`
|
|
||||||
- `go.mod`
|
|
||||||
8. Entry points and key source files (scan `src/`, `lib/`, `cmd/`, etc.)
|
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## PHASE 2 — AUDIT THE EXISTING README
|
## 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 |
|
### README structure to generate:
|
||||||
|-------------|------------------------------------------------------|
|
|
||||||
| ✅ current | Accurate, nothing to change |
|
Every command must be exact and runnable.
|
||||||
| 📝 update | Exists but outdated (wrong command, old version, etc)|
|
Never use placeholder examples — derive real commands from CLAUDE.md.
|
||||||
| ➕ missing | Section or information not present but should be |
|
|
||||||
| ❌ remove | Documents something that no longer exists |
|
```markdown
|
||||||
|
# <Project Name>
|
||||||
|
|
||||||
|
> <one-line tagline>
|
||||||
|
|
||||||
|
## About
|
||||||
|
|
||||||
|
**Summary**: <2–3 sentences: what it does, what problem it solves>
|
||||||
|
**Objective**: <what success looks like for users>
|
||||||
|
**Status**: `in development`
|
||||||
|
|
||||||
|
## Prerequisites
|
||||||
|
|
||||||
|
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.
|
||||||
|
|
||||||
|
### Windows
|
||||||
|
<winget commands or installer URLs — exact>
|
||||||
|
|
||||||
|
### Linux (Debian/Ubuntu)
|
||||||
|
<apt/curl commands — exact>
|
||||||
|
<if dnf/pacman differ meaningfully, add a note>
|
||||||
|
|
||||||
|
### macOS
|
||||||
|
<brew commands — exact>
|
||||||
|
|
||||||
|
## Installation
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# Clone
|
||||||
|
git clone <repo-url>
|
||||||
|
cd <project-name>
|
||||||
|
|
||||||
|
# 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>
|
||||||
|
```
|
||||||
|
|
||||||
|
## Running
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# Development
|
||||||
|
<exact dev command>
|
||||||
|
|
||||||
|
# Production
|
||||||
|
<exact prod command>
|
||||||
|
|
||||||
|
# Tests
|
||||||
|
<exact test command>
|
||||||
|
|
||||||
|
# Lint / format (if configured)
|
||||||
|
<exact lint command>
|
||||||
|
```
|
||||||
|
|
||||||
|
## [Docker] — INCLUDE ONLY IF DOCKER_RELEVANT = true
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# Build and start all services
|
||||||
|
docker compose up --build
|
||||||
|
|
||||||
|
# Start in background
|
||||||
|
docker compose up -d
|
||||||
|
|
||||||
|
# Stop services
|
||||||
|
docker compose down
|
||||||
|
|
||||||
|
# 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> .
|
||||||
|
```
|
||||||
|
|
||||||
|
**Environment variables for Docker:**
|
||||||
|
Copy `.env.example` to `.env` before running.
|
||||||
|
The `docker-compose.yml` reads from `.env` automatically.
|
||||||
|
|
||||||
|
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>
|
||||||
|
|
||||||
|
## Project structure
|
||||||
|
|
||||||
|
<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>
|
||||||
|
|
||||||
|
# Run tests before committing
|
||||||
|
<test command>
|
||||||
|
|
||||||
|
# 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.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 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
|
||||||
|
|
||||||
|
### 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">`
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 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:
|
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
|
||||||
|
|
||||||
**About / Summary / Objective**
|
### PHASE 3 — AUDIT REPORT + MANDATORY STOP
|
||||||
- Does the description still match what the project does?
|
|
||||||
- Is the objective still valid?
|
|
||||||
- Does the status badge reflect reality?
|
|
||||||
|
|
||||||
**Prerequisites**
|
|
||||||
- Are all listed tools still required?
|
|
||||||
- Are versions still accurate?
|
|
||||||
- Are there new dependencies missing from the list?
|
|
||||||
|
|
||||||
**Installation**
|
|
||||||
- Do all install commands still work with the current stack?
|
|
||||||
- Has the package manager or lockfile changed?
|
|
||||||
|
|
||||||
**Running**
|
|
||||||
- Are dev/prod/test commands still accurate?
|
|
||||||
- Have script names in package.json / Makefile changed?
|
|
||||||
- Are there new run modes (Docker, CLI flags, etc.)?
|
|
||||||
|
|
||||||
**Project structure**
|
|
||||||
- Does the folder tree match what actually exists?
|
|
||||||
- Are there new modules, renamed folders, or removed directories?
|
|
||||||
|
|
||||||
**Configuration**
|
|
||||||
- Are all env vars in `.env.example` documented?
|
|
||||||
- Have new required vars been added?
|
|
||||||
- Have deprecated vars been removed?
|
|
||||||
|
|
||||||
**Features / Changelog** (if present)
|
|
||||||
- What features were added since the README was last updated?
|
|
||||||
- What was removed or changed?
|
|
||||||
|
|
||||||
**Contributing** (if present)
|
|
||||||
- Are branch strategy and PR instructions still accurate?
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## PHASE 3 — PRODUCE AUDIT REPORT
|
|
||||||
|
|
||||||
Before making any changes, present the audit result:
|
|
||||||
|
|
||||||
```
|
```
|
||||||
================================================================
|
================================================================
|
||||||
@ -113,7 +277,7 @@ README AUDIT
|
|||||||
================================================================
|
================================================================
|
||||||
|
|
||||||
LAST MEANINGFUL COMMIT : <hash — message>
|
LAST MEANINGFUL COMMIT : <hash — message>
|
||||||
SECTIONS ANALYZED : <count>
|
DOCKER : relevant (✅ / ❌) — section <present / missing / N/A>
|
||||||
|
|
||||||
STATUS SUMMARY
|
STATUS SUMMARY
|
||||||
--------------
|
--------------
|
||||||
@ -124,26 +288,7 @@ STATUS SUMMARY
|
|||||||
|
|
||||||
DETAIL
|
DETAIL
|
||||||
------
|
------
|
||||||
|
<per-section findings — specific, actionable>
|
||||||
📝 Prerequisites
|
|
||||||
- Node.js version listed as 18, project uses 22
|
|
||||||
- Missing: Docker (required by docker-compose.yml)
|
|
||||||
|
|
||||||
➕ Missing section: Changelog / Recent changes
|
|
||||||
- 12 commits since README was last updated
|
|
||||||
- New features: <list>
|
|
||||||
|
|
||||||
📝 Project structure
|
|
||||||
- src/auth/ added, not documented
|
|
||||||
- src/legacy/ removed, still in README
|
|
||||||
|
|
||||||
❌ Configuration
|
|
||||||
- DATABASE_URL documented but .env.example uses DB_URL
|
|
||||||
- NEW_VAR present in .env.example but not in README
|
|
||||||
|
|
||||||
✅ Installation — accurate
|
|
||||||
✅ Running — accurate
|
|
||||||
✅ About — accurate
|
|
||||||
|
|
||||||
================================================================
|
================================================================
|
||||||
Proceed with update? (yes / select sections / cancel)
|
Proceed with update? (yes / select sections / cancel)
|
||||||
@ -152,68 +297,24 @@ Proceed with update? (yes / select sections / cancel)
|
|||||||
|
|
||||||
**MANDATORY STOP — wait for user confirmation.**
|
**MANDATORY STOP — wait for user confirmation.**
|
||||||
|
|
||||||
If user says "yes" or approves → proceed to Phase 4.
|
### PHASE 4 — UPDATE (after confirmation)
|
||||||
If user selects specific sections → update only those.
|
|
||||||
If user says "cancel" → stop.
|
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.
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## PHASE 4 — UPDATE README
|
## OUTPUT (all modes)
|
||||||
|
|
||||||
Apply all approved changes to `README.md`.
|
**CREATE:** `📄 README created — <N sections> [Docker: included / not applicable]`
|
||||||
|
**SYNC:** `📄 README synced — <N changes / "no changes needed"> [Docker: <status>]`
|
||||||
Rules:
|
**AUDIT:** Full report → `📄 README updated — <summary>`
|
||||||
- Preserve the existing structure and tone exactly.
|
|
||||||
- Preserve all sections marked ✅ current unchanged.
|
|
||||||
- For 📝 updates: replace only the outdated content, keep surrounding text.
|
|
||||||
- For ➕ additions: insert new sections in logical order.
|
|
||||||
- For ❌ removals: remove the section or mark it with a
|
|
||||||
`> ⚠️ Deprecated: <reason>` blockquote if there is any chance
|
|
||||||
it is still relevant.
|
|
||||||
- Never rewrite the entire README — surgical edits only.
|
|
||||||
- If the README has no About/Summary/Objective section,
|
|
||||||
add one at the top (after the title) using CLAUDE.md
|
|
||||||
and git history to reconstruct it accurately.
|
|
||||||
- Update the **Status** badge if present.
|
|
||||||
- Add a `## Recent changes` section if there are 5+ commits
|
|
||||||
since the last README update and no changelog section exists:
|
|
||||||
|
|
||||||
```markdown
|
|
||||||
## Recent changes
|
|
||||||
|
|
||||||
<!-- Last updated: <date> — <commit hash> -->
|
|
||||||
|
|
||||||
- <change derived from git log>
|
|
||||||
- <change derived from git log>
|
|
||||||
```
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## PHASE 5 — VERIFY
|
|
||||||
|
|
||||||
After writing:
|
|
||||||
- Re-read the updated README in full.
|
|
||||||
- Confirm no broken markdown (unclosed code blocks, missing headers).
|
|
||||||
- Confirm all commands mentioned are consistent with CLAUDE.md.
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## OUTPUT
|
|
||||||
|
|
||||||
```
|
|
||||||
README UPDATED
|
|
||||||
|
|
||||||
CHANGES APPLIED
|
|
||||||
---------------
|
|
||||||
📝 <section> — <what changed>
|
|
||||||
➕ <section> — <what was added>
|
|
||||||
❌ <section> — <what was removed or deprecated>
|
|
||||||
|
|
||||||
SECTIONS UNCHANGED
|
|
||||||
------------------
|
|
||||||
✅ <section>
|
|
||||||
|
|
||||||
WARNINGS
|
|
||||||
--------
|
|
||||||
⚠️ <anything that could not be verified automatically>
|
|
||||||
```
|
|
||||||
|
|||||||
@ -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
|
|
||||||
```
|
|
||||||
@ -1,6 +1,6 @@
|
|||||||
---
|
---
|
||||||
name: scaffolder
|
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
|
tools: Read, Write, Edit, Bash, Glob, Grep
|
||||||
model: sonnet
|
model: sonnet
|
||||||
effort: high
|
effort: high
|
||||||
@ -9,28 +9,58 @@ effort: high
|
|||||||
# SCAFFOLDER
|
# SCAFFOLDER
|
||||||
|
|
||||||
## ROLE
|
## ROLE
|
||||||
Generate the complete, working first version of a project.
|
Create the empty skeleton of a project and make it buildable.
|
||||||
|
|
||||||
## GOAL
|
## GOAL
|
||||||
Deliver a project that:
|
Deliver a project where:
|
||||||
- builds and runs immediately after scaffolding
|
- Folder structure and config files are in place
|
||||||
- covers all v1 features described in the PROJECT BRIEF
|
- CLAUDE.md is fully filled from the global template
|
||||||
- has a fully filled-in CLAUDE.md based on the global template
|
- Dependencies are installed and the project builds
|
||||||
- has a complete README with cross-platform setup instructions
|
- Docker config is present if the project type warrants it
|
||||||
- actually installs dependencies and verifies the build before reporting
|
- The project works both natively AND with Docker (if Docker was added)
|
||||||
- follows all conventions from the PROJECT BRIEF and ~/.claude/CLAUDE.md
|
- 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
|
## INPUT REQUIRED
|
||||||
|
|
||||||
You must receive ALL of the following before starting:
|
|
||||||
1. PROJECT BRIEF (from interviewer)
|
1. PROJECT BRIEF (from interviewer)
|
||||||
2. Approved DESIGN (from designer)
|
2. Approved DESIGN (from brainstorming)
|
||||||
3. Path to the global template: `~/.claude/templates/project-CLAUDE.md`
|
3. `~/.claude/templates/project-CLAUDE.md`
|
||||||
4. Path to global rules: `~/.claude/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 0 — DOCKER DECISION
|
||||||
|
|
||||||
|
Before creating any files, decide if Docker is relevant.
|
||||||
|
|
||||||
|
**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
|
||||||
|
|
||||||
|
**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
|
||||||
|
|
||||||
|
Store this decision as `DOCKER_RELEVANT = true/false`.
|
||||||
|
|
||||||
|
**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.
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
@ -39,402 +69,294 @@ If any input is missing — STOP and report what is missing.
|
|||||||
Read `~/.claude/templates/project-CLAUDE.md` in full.
|
Read `~/.claude/templates/project-CLAUDE.md` in full.
|
||||||
Read `~/.claude/CLAUDE.md` to understand global rules.
|
Read `~/.claude/CLAUDE.md` to understand global rules.
|
||||||
|
|
||||||
Fill in every section using the PROJECT BRIEF and approved DESIGN.
|
Fill in every section from the PROJECT BRIEF and approved DESIGN.
|
||||||
- No placeholder comments left in.
|
No placeholders. No template examples left in.
|
||||||
- No examples from the template left in.
|
Mark irrelevant sections as `N/A — <reason>`.
|
||||||
- Every section is either filled with real content or marked `N/A — <reason>`.
|
|
||||||
|
|
||||||
Generated CLAUDE.md structure:
|
Required content:
|
||||||
|
- Project overview (2–4 sentences)
|
||||||
```
|
- Stack (language + version, framework, runtime, database)
|
||||||
# <PROJECT NAME> — CLAUDE.md
|
- Build commands (exact, native)
|
||||||
|
- Test commands (exact)
|
||||||
## Project overview
|
- Lint/format commands (exact or N/A)
|
||||||
<2–4 sentences: what it does, for whom, key constraints>
|
- Docker commands (if DOCKER_RELEVANT) — exact
|
||||||
|
- Folder structure (actual tree)
|
||||||
## Stack
|
- Architecture (module responsibilities, data flow)
|
||||||
<language + version, framework + version, runtime, database, key services>
|
- Project conventions
|
||||||
|
- Exceptions to global rules (or "none")
|
||||||
## Build commands
|
- Key dependencies (name — purpose)
|
||||||
<exact commands>
|
- Workflow expectations
|
||||||
|
|
||||||
## Test commands
|
|
||||||
<exact commands>
|
|
||||||
|
|
||||||
## Lint / format commands
|
|
||||||
<exact commands or N/A>
|
|
||||||
|
|
||||||
## Folder structure
|
|
||||||
<actual tree of the project>
|
|
||||||
|
|
||||||
## Architecture
|
|
||||||
<module responsibilities, data flow, key design decisions>
|
|
||||||
|
|
||||||
## Project conventions
|
|
||||||
<naming, file organization, patterns specific to this project>
|
|
||||||
|
|
||||||
## Exceptions to global rules
|
|
||||||
<explicit overrides of ~/.claude/CLAUDE.md, or "none — global rules apply">
|
|
||||||
|
|
||||||
## Key dependencies
|
|
||||||
<name — purpose, one line each>
|
|
||||||
|
|
||||||
## Workflow expectations
|
|
||||||
<how Claude should behave in this repo>
|
|
||||||
```
|
|
||||||
|
|
||||||
Write to `CLAUDE.md` at the project root.
|
Write to `CLAUDE.md` at the project root.
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## PHASE 2 — GENERATE README.md
|
## PHASE 2 — GENERATE SETTINGS
|
||||||
|
|
||||||
The README must be immediately actionable on Windows, Linux, and macOS.
|
### a. `.claude/settings.json`
|
||||||
No vague instructions. Every command must be exact and runnable.
|
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
|
||||||
|
|
||||||
README structure:
|
### 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).
|
||||||
|
|
||||||
```markdown
|
### c. Print:
|
||||||
# <Project Name>
|
|
||||||
|
|
||||||
> <one-line tagline>
|
|
||||||
|
|
||||||
## About
|
|
||||||
|
|
||||||
**Summary**: <2–3 sentences describing what the project is and what
|
|
||||||
problem it solves.>
|
|
||||||
|
|
||||||
**Objective**: <What success looks like. What the project is meant to
|
|
||||||
achieve for its users or stakeholders.>
|
|
||||||
|
|
||||||
**Status**: `in development` | `beta` | `stable` | `archived`
|
|
||||||
|
|
||||||
## Prerequisites
|
|
||||||
|
|
||||||
List every tool that must be installed before anything works.
|
|
||||||
For each tool:
|
|
||||||
- name and minimum version
|
|
||||||
- what it is used for
|
|
||||||
- install instructions for each OS:
|
|
||||||
|
|
||||||
### Windows
|
|
||||||
<exact steps: installer URL, winget/choco command, or manual steps>
|
|
||||||
|
|
||||||
### Linux (Debian/Ubuntu)
|
|
||||||
<exact apt/snap/curl commands>
|
|
||||||
|
|
||||||
### macOS
|
|
||||||
<exact brew commands or installer URL>
|
|
||||||
|
|
||||||
## Installation
|
|
||||||
|
|
||||||
Step-by-step, in order, for all platforms unless noted otherwise:
|
|
||||||
|
|
||||||
```bash
|
|
||||||
# Clone
|
|
||||||
git clone <repo-url>
|
|
||||||
cd <project>
|
|
||||||
|
|
||||||
# Install dependencies
|
|
||||||
<exact command>
|
|
||||||
|
|
||||||
# Configure environment
|
|
||||||
<exact steps: copy .env.example, set required vars, etc.>
|
|
||||||
|
|
||||||
# Database setup (if applicable)
|
|
||||||
<exact steps: create db, run migrations, seed>
|
|
||||||
|
|
||||||
# Build (if applicable)
|
|
||||||
<exact command>
|
|
||||||
```
|
```
|
||||||
|
⚙️ SETTINGS SETUP
|
||||||
|
.claude/settings.json created
|
||||||
|
.claudeignore created
|
||||||
|
|
||||||
## Running
|
Manual: copy ~/.claude/templates/settings/settings.local.json
|
||||||
|
→ .claude/settings.local.json (gitignore it, never commit)
|
||||||
```bash
|
|
||||||
# Development
|
|
||||||
<exact command>
|
|
||||||
|
|
||||||
# Production
|
|
||||||
<exact command>
|
|
||||||
|
|
||||||
# Tests
|
|
||||||
<exact command>
|
|
||||||
```
|
```
|
||||||
|
|
||||||
## Project structure
|
|
||||||
|
|
||||||
<folder tree with one-line description per entry>
|
|
||||||
|
|
||||||
## Configuration
|
|
||||||
|
|
||||||
<all env vars or config files with description and example value>
|
|
||||||
|
|
||||||
## Contributing
|
|
||||||
|
|
||||||
<branch strategy, how to run tests, PR expectations>
|
|
||||||
```
|
|
||||||
|
|
||||||
Write to `README.md` at the project root.
|
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## PHASE 3 — SCAFFOLD STRUCTURE
|
## PHASE 3 — SCAFFOLD STRUCTURE
|
||||||
|
|
||||||
Create every folder and file defined in the approved DESIGN.
|
Create every folder and file from the approved DESIGN.
|
||||||
No placeholder files — every file must have real content.
|
|
||||||
|
|
||||||
### 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 |
|
### Entry points and modules:
|
||||||
|-----------------|--------------------------------------------------|
|
- Entry point files exist with minimal structure (imports + empty main/app init)
|
||||||
| `CLAUDE.md` | Generated in Phase 1 |
|
- Module/package files exist but are empty or have minimal declarations
|
||||||
| `README.md` | Generated in Phase 2 |
|
- No business logic anywhere
|
||||||
| `.gitignore` | Stack-appropriate, comprehensive |
|
|
||||||
| `.env.example` | All env vars with description, no real secrets |
|
|
||||||
|
|
||||||
### Stack-specific required files
|
### Stack-specific required files:
|
||||||
|
|
||||||
#### C / C++
|
**Node.js / TypeScript**
|
||||||
```
|
```
|
||||||
Makefile — targets: all, clean, fclean, re
|
package.json — name, scripts (dev/build/test/lint), dependencies
|
||||||
src/ — source files
|
tsconfig.json — if TypeScript
|
||||||
include/ — header files
|
.eslintrc — lint config
|
||||||
main.c / main.cpp — entry point with basic structure
|
src/index.ts — empty entry point with comment
|
||||||
tests/ — test runner script
|
|
||||||
```
|
|
||||||
Makefile must implement: `all`, `clean`, `fclean`, `re`.
|
|
||||||
Use `-Wall -Wextra -Werror` by default unless overridden.
|
|
||||||
|
|
||||||
#### Node.js / TypeScript
|
|
||||||
```
|
|
||||||
package.json — name, scripts (dev/build/test/lint), dependencies
|
|
||||||
tsconfig.json — if TypeScript
|
|
||||||
.eslintrc — lint config
|
|
||||||
src/ — source
|
|
||||||
src/index.ts — entry point
|
|
||||||
tests/ — test files
|
|
||||||
```
|
|
||||||
Run `npm install` after creating package.json.
|
|
||||||
|
|
||||||
#### React (frontend)
|
|
||||||
```
|
|
||||||
package.json — scripts: dev, build, preview, test, lint
|
|
||||||
vite.config.ts — or equivalent bundler config
|
|
||||||
src/
|
|
||||||
main.tsx — entry point
|
|
||||||
App.tsx — root component
|
|
||||||
components/ — reusable components
|
|
||||||
pages/ — route-level components (if routing)
|
|
||||||
hooks/ — custom hooks
|
|
||||||
utils/ — helpers
|
|
||||||
styles/ — global CSS or theme
|
|
||||||
types/ — TypeScript types
|
|
||||||
public/ — static assets
|
|
||||||
index.html — entry HTML
|
|
||||||
```
|
|
||||||
Run `npm install` after creating package.json.
|
|
||||||
|
|
||||||
#### Python
|
|
||||||
```
|
|
||||||
pyproject.toml — or setup.py + requirements.txt
|
|
||||||
requirements.txt — pinned dependencies
|
|
||||||
src/<package>/
|
|
||||||
__init__.py
|
|
||||||
main.py
|
|
||||||
tests/
|
|
||||||
test_main.py
|
|
||||||
.python-version — if using pyenv
|
|
||||||
```
|
|
||||||
Run `pip install -r requirements.txt` or equivalent.
|
|
||||||
|
|
||||||
#### Python + FastAPI / Flask / Django
|
|
||||||
```
|
|
||||||
(all of the above plus)
|
|
||||||
src/<pkg>/
|
|
||||||
routes/ — API endpoints
|
|
||||||
models/ — data models / ORM
|
|
||||||
schemas/ — Pydantic schemas or serializers
|
|
||||||
services/ — business logic
|
|
||||||
database.py — DB connection
|
|
||||||
alembic/ — migrations (if SQLAlchemy)
|
|
||||||
.env.example — DATABASE_URL, SECRET_KEY, etc.
|
|
||||||
```
|
|
||||||
Run migrations if applicable.
|
|
||||||
|
|
||||||
#### Rust
|
|
||||||
```
|
|
||||||
Cargo.toml — package, dependencies, features
|
|
||||||
src/
|
|
||||||
main.rs — or lib.rs for libraries
|
|
||||||
lib.rs — public API if binary + lib
|
|
||||||
modules/ — feature modules
|
|
||||||
tests/ — integration tests
|
|
||||||
```
|
|
||||||
Run `cargo build` and `cargo test`.
|
|
||||||
|
|
||||||
#### Go
|
|
||||||
```
|
|
||||||
go.mod — module name, go version, dependencies
|
|
||||||
cmd/
|
|
||||||
<app>/
|
|
||||||
main.go — entry point
|
|
||||||
internal/ — private packages
|
|
||||||
pkg/ — public packages
|
|
||||||
tests/
|
|
||||||
Makefile — build, test, lint targets
|
|
||||||
```
|
|
||||||
Run `go mod tidy` and `go build ./...`.
|
|
||||||
|
|
||||||
#### PHP / WordPress Theme
|
|
||||||
```
|
|
||||||
style.css — theme header (Name, Description, Version, etc.)
|
|
||||||
index.php — main template
|
|
||||||
functions.php — theme setup, hooks, scripts enqueue
|
|
||||||
header.php — site header
|
|
||||||
footer.php — site footer
|
|
||||||
single.php — single post template
|
|
||||||
page.php — page template
|
|
||||||
archive.php — archive template
|
|
||||||
404.php — not found template
|
|
||||||
screenshot.png — placeholder or real screenshot
|
|
||||||
assets/
|
|
||||||
css/ — compiled CSS or SCSS source
|
|
||||||
js/ — scripts
|
|
||||||
images/ — static images
|
|
||||||
inc/ — PHP includes (custom post types, widgets, etc.)
|
|
||||||
languages/ — .pot translation file
|
|
||||||
```
|
|
||||||
README must include: WordPress version requirement, theme activation steps,
|
|
||||||
required plugins, WAMP/XAMPP/Local by Flywheel setup for Windows,
|
|
||||||
LAMP for Linux, MAMP/Valet for macOS.
|
|
||||||
|
|
||||||
#### PHP / WordPress Plugin
|
|
||||||
```
|
|
||||||
<plugin-slug>/
|
|
||||||
<plugin-slug>.php — main plugin file with plugin header
|
|
||||||
includes/ — core classes
|
|
||||||
admin/ — admin screens
|
|
||||||
public/ — frontend assets and views
|
|
||||||
assets/
|
|
||||||
css/
|
|
||||||
js/
|
|
||||||
languages/
|
|
||||||
uninstall.php
|
|
||||||
readme.txt — WordPress.org format
|
|
||||||
```
|
```
|
||||||
|
|
||||||
#### Flutter / Dart
|
**React (frontend)**
|
||||||
```
|
```
|
||||||
pubspec.yaml — name, version, dependencies, flutter config
|
package.json — scripts: dev, build, preview, test, lint
|
||||||
lib/
|
vite.config.ts — bundler config
|
||||||
main.dart — entry point, MaterialApp / CupertinoApp
|
src/main.tsx — minimal entry point
|
||||||
app/
|
src/App.tsx — empty root component
|
||||||
app.dart — root widget
|
src/components/ — empty folder
|
||||||
routes.dart — route definitions
|
index.html — entry HTML
|
||||||
features/ — feature-first structure
|
|
||||||
<feature>/
|
|
||||||
data/ — repositories, data sources
|
|
||||||
domain/ — models, use cases
|
|
||||||
presentation/ — screens, widgets, bloc/provider
|
|
||||||
core/
|
|
||||||
theme/ — ThemeData, colors, typography
|
|
||||||
utils/ — helpers
|
|
||||||
widgets/ — shared widgets
|
|
||||||
assets/
|
|
||||||
images/
|
|
||||||
fonts/
|
|
||||||
test/ — widget and unit tests
|
|
||||||
```
|
```
|
||||||
Run `flutter pub get` and `flutter analyze`.
|
|
||||||
|
|
||||||
#### Docker / Docker Compose (any stack)
|
**Python**
|
||||||
Generate additionally:
|
|
||||||
```
|
```
|
||||||
Dockerfile — multi-stage build, non-root user, .dockerignore
|
pyproject.toml or requirements.txt
|
||||||
docker-compose.yml — services, volumes, env_file
|
src/<package>/__init__.py
|
||||||
.dockerignore — node_modules, .git, secrets
|
src/<package>/main.py — empty entry point
|
||||||
|
```
|
||||||
|
|
||||||
|
**FastAPI / Flask / Django**
|
||||||
|
```
|
||||||
|
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
|
||||||
|
```
|
||||||
|
|
||||||
|
**Rust**
|
||||||
|
```
|
||||||
|
Cargo.toml
|
||||||
|
src/main.rs or src/lib.rs — empty main / empty lib
|
||||||
|
```
|
||||||
|
|
||||||
|
**Go**
|
||||||
|
```
|
||||||
|
go.mod
|
||||||
|
cmd/<app>/main.go — empty main
|
||||||
|
internal/ — empty folder
|
||||||
|
```
|
||||||
|
|
||||||
|
**C / C++**
|
||||||
|
```
|
||||||
|
Makefile — targets: all, clean, fclean, re (-Wall -Wextra -Werror)
|
||||||
|
src/ — empty
|
||||||
|
include/ — empty
|
||||||
|
main.c or main.cpp — empty main
|
||||||
|
```
|
||||||
|
|
||||||
|
**PHP / WordPress Theme**
|
||||||
|
```
|
||||||
|
style.css — theme header (Name, Description, Version, etc.)
|
||||||
|
functions.php — empty theme setup
|
||||||
|
index.php — minimal template
|
||||||
|
```
|
||||||
|
|
||||||
|
**Flutter / Dart**
|
||||||
|
```
|
||||||
|
pubspec.yaml
|
||||||
|
lib/main.dart — minimal MaterialApp / CupertinoApp
|
||||||
|
lib/app/ — empty folders
|
||||||
|
```
|
||||||
|
|
||||||
|
### 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>]
|
||||||
|
```
|
||||||
|
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:
|
||||||
|
```
|
||||||
|
|
||||||
|
**`.dockerignore`**:
|
||||||
|
```
|
||||||
|
node_modules/
|
||||||
|
.git/
|
||||||
|
.env
|
||||||
|
dist/
|
||||||
|
build/
|
||||||
|
target/
|
||||||
|
__pycache__/
|
||||||
|
*.pyc
|
||||||
|
.pytest_cache/
|
||||||
|
coverage/
|
||||||
|
```
|
||||||
|
|
||||||
|
After creating Docker files, add to `.env.example`:
|
||||||
|
```
|
||||||
|
# Docker (optional — only needed when using docker compose)
|
||||||
|
COMPOSE_PROJECT_NAME=<project-slug>
|
||||||
```
|
```
|
||||||
README must include Docker-based setup as an alternative path.
|
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## PHASE 4 — IMPLEMENT V1 FEATURES
|
## PHASE 4 — INSTALL DEPENDENCIES
|
||||||
|
|
||||||
Implement ALL features listed in the PROJECT BRIEF v1 scope.
|
Install project dependencies so the build works.
|
||||||
|
This is mandatory — the build verification in Phase 5 requires installed deps.
|
||||||
|
|
||||||
Rules:
|
Run the appropriate install command for the stack:
|
||||||
- Real, working code — not stubs, not TODOs, not placeholders
|
|
||||||
- Each feature must be independently functional
|
|
||||||
- Follow conventions in the generated CLAUDE.md exactly
|
|
||||||
- Apply all global rules from ~/.claude/CLAUDE.md
|
|
||||||
- Add function-level documentation matching the project's doc style
|
|
||||||
- If a feature requires a dependency not in config, add it and
|
|
||||||
update the config file before implementing
|
|
||||||
|
|
||||||
Implementation order:
|
| Stack | Install command |
|
||||||
1. Core data models / types / schemas
|
|---|---|
|
||||||
2. Core business logic / services
|
| Node.js / React / TypeScript | `npm install` |
|
||||||
3. Interfaces (routes, commands, components, screens)
|
| Python / FastAPI / Flask | `pip install -r requirements.txt` or `uv pip install -r requirements.txt` |
|
||||||
4. Utilities and helpers
|
| Rust | `cargo fetch` |
|
||||||
5. Entry point that wires everything together
|
| Go | `go mod download` |
|
||||||
6. Environment / config loading
|
| Flutter | `flutter pub get` |
|
||||||
|
| PHP / Composer | `composer install` |
|
||||||
|
| C / C++ | No package manager — verify compiler is available: `gcc --version` or `clang --version` |
|
||||||
|
|
||||||
|
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
|
||||||
|
|
||||||
|
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 5 — WRITE INITIAL TESTS
|
## PHASE 5 — VERIFY SKELETON
|
||||||
|
|
||||||
For each implemented module, write at minimum:
|
Run the build command on the empty project.
|
||||||
- 1 happy path test
|
The project must compile/start even with no features.
|
||||||
- 1 edge case or error condition test
|
|
||||||
|
|
||||||
Test file naming must match project conventions.
|
```bash
|
||||||
Tests must be runnable with the command defined in CLAUDE.md.
|
# Native build
|
||||||
|
<build-command from CLAUDE.md>
|
||||||
|
```
|
||||||
|
|
||||||
---
|
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
|
||||||
|
|
||||||
## PHASE 6 — INSTALL AND BUILD
|
If DOCKER_RELEVANT = true, also verify Docker build:
|
||||||
|
```bash
|
||||||
Execute the following in order and report each result:
|
docker build -t <project-name>:skeleton-test . --quiet
|
||||||
|
```
|
||||||
1. Install dependencies (npm install / pip install / cargo fetch /
|
Docker build failure is a warning, not a blocker — native must pass.
|
||||||
go mod tidy / flutter pub get / composer install / etc.)
|
|
||||||
2. Run linter / formatter if configured
|
|
||||||
3. Run build command if applicable
|
|
||||||
4. Run test suite
|
|
||||||
|
|
||||||
If any step fails — fix the issue and retry before reporting.
|
|
||||||
Do not report success on a broken build.
|
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## OUTPUT
|
## OUTPUT
|
||||||
|
|
||||||
```
|
```
|
||||||
SCAFFOLDING COMPLETE: <project name>
|
SKELETON COMPLETE: <project name>
|
||||||
|
|
||||||
FILES CREATED : <count>
|
FILES CREATED : <count>
|
||||||
INSTALL : ✅ / ❌ <error>
|
DOCKER : included / not applicable — <one-line reason>
|
||||||
BUILD : ✅ / ❌ <error>
|
INSTALL : ✅ dependencies installed / ❌ <e>
|
||||||
TESTS : ✅ <N> passing / ❌ <detail>
|
BUILD (native) : ✅ passes / ❌ <e>
|
||||||
LINT : ✅ / ❌ / N/A
|
BUILD (docker) : ✅ passes / ⚠️ not verified / N/A
|
||||||
|
|
||||||
V1 FEATURES
|
STRUCTURE:
|
||||||
-----------
|
<actual tree of what was created>
|
||||||
✅ <feature>
|
|
||||||
✅ <feature>
|
|
||||||
⚠️ <feature> — partial: <reason>
|
|
||||||
|
|
||||||
DEVIATIONS FROM DESIGN
|
READY FOR IMPLEMENTATION PIPELINE:
|
||||||
-----------------------
|
- V1 features to implement : <N> features from PROJECT BRIEF
|
||||||
<deviation> — reason: <why>
|
- Entry points ready : ✅
|
||||||
none
|
- Config files ready : ✅
|
||||||
|
- Dependencies installed : ✅ / ❌
|
||||||
OPEN ITEMS
|
- CLAUDE.md : ✅ complete
|
||||||
----------
|
- README.md : handled by readme-updater (next step)
|
||||||
<item requiring attention>
|
- Settings : ✅ .claude/settings.json + .claudeignore
|
||||||
none
|
|
||||||
|
|
||||||
QUICK START
|
|
||||||
-----------
|
|
||||||
<3-line summary of how to run the project right now>
|
|
||||||
```
|
```
|
||||||
|
|||||||
@ -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%
|
|
||||||
```
|
|
||||||
55
hooks/session-start.sh
Normal file
55
hooks/session-start.sh
Normal file
@ -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 ""
|
||||||
84
install-plugins.sh
Normal file
84
install-plugins.sh
Normal file
@ -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)"
|
||||||
30
link.sh
30
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
|
set -euo pipefail
|
||||||
rm -rf ~/claude/agents ~/claude/skills ~/claude/CLAUDE.md ~/claude/settings.json
|
|
||||||
|
|
||||||
ln -sf ~/claude-config/agents ~/.claude/agents
|
REPO="$(cd "$(dirname "$0")" && pwd)"
|
||||||
ln -sf ~/claude-config/skills ~/.claude/skills
|
CLAUDE="$HOME/.claude"
|
||||||
ln -sf ~/claude-config/CLAUDE.md ~/.claude/CLAUDE.md
|
|
||||||
ln -sf ~/claude-config/settings.json ~/.claude/settings.json
|
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"
|
||||||
|
|||||||
@ -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,
|
"cleanupPeriodDays": 30,
|
||||||
|
|
||||||
"permissions": {
|
"permissions": {
|
||||||
|
|
||||||
"defaultMode": "default",
|
"defaultMode": "default",
|
||||||
|
|
||||||
"disableBypassPermissionsMode": "disable",
|
"disableBypassPermissionsMode": "disable",
|
||||||
|
|
||||||
"deny": [
|
"deny": [
|
||||||
|
|
||||||
"Bash(rm -rf *)",
|
"Bash(rm -rf *)",
|
||||||
"Bash(rm -rf /*)",
|
"Bash(rm -rf /*)",
|
||||||
"Bash(rmdir *)",
|
"Bash(rmdir *)",
|
||||||
|
|
||||||
"Bash(git push --force*)",
|
"Bash(git push --force*)",
|
||||||
"Bash(git push -f*)",
|
"Bash(git push -f*)",
|
||||||
"Bash(git reset --hard*)",
|
"Bash(git reset --hard*)",
|
||||||
"Bash(git clean -fd*)",
|
"Bash(git clean -fd*)",
|
||||||
|
|
||||||
"Bash(sudo rm*)",
|
"Bash(sudo rm*)",
|
||||||
"Bash(sudo chmod*)",
|
"Bash(sudo chmod*)",
|
||||||
"Bash(sudo chown*)",
|
"Bash(sudo chown*)",
|
||||||
"Bash(sudo dd*)",
|
"Bash(sudo dd*)",
|
||||||
"Bash(su *)",
|
"Bash(su *)",
|
||||||
|
|
||||||
"Bash(curl * | bash)",
|
"Bash(curl * | bash)",
|
||||||
"Bash(wget * | bash)",
|
"Bash(wget * | bash)",
|
||||||
"Bash(curl * | sh)",
|
"Bash(curl * | sh)",
|
||||||
"Bash(wget * | sh)",
|
"Bash(wget * | sh)",
|
||||||
|
|
||||||
"Bash(chmod 777 *)",
|
"Bash(chmod 777 *)",
|
||||||
"Bash(chmod -R 777 *)",
|
"Bash(chmod -R 777 *)",
|
||||||
|
|
||||||
"Bash(ssh *)",
|
"Bash(ssh *)",
|
||||||
"Bash(scp *)",
|
"Bash(scp *)",
|
||||||
"Bash(rsync *)",
|
"Bash(rsync *)",
|
||||||
"Bash(nc *)",
|
"Bash(nc *)",
|
||||||
"Bash(netcat *)",
|
"Bash(netcat *)",
|
||||||
|
|
||||||
"Bash(kill -9 *)",
|
"Bash(kill -9 *)",
|
||||||
"Bash(killall *)",
|
"Bash(killall *)",
|
||||||
"Bash(pkill *)",
|
"Bash(pkill *)",
|
||||||
|
|
||||||
"Bash(crontab *)",
|
"Bash(crontab *)",
|
||||||
"Bash(systemctl *)",
|
"Bash(systemctl *)",
|
||||||
"Bash(service *)",
|
"Bash(service *)",
|
||||||
|
|
||||||
"Bash(npm install -g *)",
|
"Bash(npm install -g *)",
|
||||||
|
|
||||||
"Read(**/.env)",
|
"Read(**/.env)",
|
||||||
"Read(**/.env.*)",
|
"Read(**/.env.*)",
|
||||||
"Read(**/secrets/**)",
|
"Read(**/secrets/**)",
|
||||||
@ -64,36 +49,28 @@
|
|||||||
"Read(**/credentials.json)",
|
"Read(**/credentials.json)",
|
||||||
"Read(**/.aws/credentials)",
|
"Read(**/.aws/credentials)",
|
||||||
"Read(**/.azure/**)",
|
"Read(**/.azure/**)",
|
||||||
|
|
||||||
"Write(**/.env)",
|
"Write(**/.env)",
|
||||||
"Write(**/.env.*)",
|
"Write(**/.env.*)",
|
||||||
"Write(**/secrets/**)",
|
"Write(**/secrets/**)",
|
||||||
"Write(**/*.pem)",
|
"Write(**/*.pem)",
|
||||||
"Write(**/*.key)"
|
"Write(**/*.key)"
|
||||||
],
|
],
|
||||||
|
|
||||||
"ask": [
|
"ask": [
|
||||||
|
|
||||||
"Bash(git push *)",
|
"Bash(git push *)",
|
||||||
"Bash(git push)",
|
"Bash(git push)",
|
||||||
|
|
||||||
"Bash(docker run *)",
|
"Bash(docker run *)",
|
||||||
"Bash(docker exec *)",
|
"Bash(docker exec *)",
|
||||||
"Bash(docker-compose up*)",
|
"Bash(docker-compose up*)",
|
||||||
"Bash(docker compose up*)",
|
"Bash(docker compose up*)",
|
||||||
|
|
||||||
"Bash(brew install *)",
|
"Bash(brew install *)",
|
||||||
"Bash(apt install *)",
|
"Bash(apt install *)",
|
||||||
"Bash(apt-get install *)",
|
"Bash(apt-get install *)",
|
||||||
"Bash(dnf install *)",
|
"Bash(dnf install *)",
|
||||||
"Bash(pacman -S *)",
|
"Bash(pacman -S *)",
|
||||||
|
|
||||||
"WebSearch",
|
"WebSearch",
|
||||||
"WebFetch"
|
"WebFetch"
|
||||||
],
|
],
|
||||||
|
|
||||||
"allow": [
|
"allow": [
|
||||||
|
|
||||||
"Bash(git status)",
|
"Bash(git status)",
|
||||||
"Bash(git log*)",
|
"Bash(git log*)",
|
||||||
"Bash(git diff*)",
|
"Bash(git diff*)",
|
||||||
@ -107,7 +84,6 @@
|
|||||||
"Bash(git stash*)",
|
"Bash(git stash*)",
|
||||||
"Bash(git tag*)",
|
"Bash(git tag*)",
|
||||||
"Bash(git show*)",
|
"Bash(git show*)",
|
||||||
|
|
||||||
"Bash(ls *)",
|
"Bash(ls *)",
|
||||||
"Bash(ls)",
|
"Bash(ls)",
|
||||||
"Bash(find *)",
|
"Bash(find *)",
|
||||||
@ -126,12 +102,10 @@
|
|||||||
"Bash(printenv *)",
|
"Bash(printenv *)",
|
||||||
"Bash(whoami)",
|
"Bash(whoami)",
|
||||||
"Bash(uname *)",
|
"Bash(uname *)",
|
||||||
|
|
||||||
"Bash(mkdir -p *)",
|
"Bash(mkdir -p *)",
|
||||||
"Bash(touch *)",
|
"Bash(touch *)",
|
||||||
"Bash(cp *)",
|
"Bash(cp *)",
|
||||||
"Bash(mv *)",
|
"Bash(mv *)",
|
||||||
|
|
||||||
"Bash(jq *)",
|
"Bash(jq *)",
|
||||||
"Bash(yq *)",
|
"Bash(yq *)",
|
||||||
"Bash(sed *)",
|
"Bash(sed *)",
|
||||||
@ -142,7 +116,6 @@
|
|||||||
"Bash(tr *)",
|
"Bash(tr *)",
|
||||||
"Bash(cut *)",
|
"Bash(cut *)",
|
||||||
"Bash(diff *)",
|
"Bash(diff *)",
|
||||||
|
|
||||||
"Read(**/*.md)",
|
"Read(**/*.md)",
|
||||||
"Read(**/*.txt)",
|
"Read(**/*.txt)",
|
||||||
"Read(**/*.json)",
|
"Read(**/*.json)",
|
||||||
@ -157,7 +130,18 @@
|
|||||||
"Read(**/Dockerfile*)",
|
"Read(**/Dockerfile*)",
|
||||||
"Read(**/docker-compose*)"
|
"Read(**/docker-compose*)"
|
||||||
],
|
],
|
||||||
|
|
||||||
"additionalDirectories": []
|
"additionalDirectories": []
|
||||||
|
},
|
||||||
|
"hooks": {
|
||||||
|
"SessionStart": [
|
||||||
|
{
|
||||||
|
"hooks": [
|
||||||
|
{
|
||||||
|
"type": "command",
|
||||||
|
"command": "bash ~/.claude/hooks/session-start.sh"
|
||||||
|
}
|
||||||
|
]
|
||||||
|
}
|
||||||
|
]
|
||||||
}
|
}
|
||||||
}
|
}
|
||||||
@ -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
|
|
||||||
@ -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
|
|
||||||
@ -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
|
|
||||||
@ -1,6 +1,6 @@
|
|||||||
---
|
---
|
||||||
name: init-project
|
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>
|
argument-hint: <project idea or description>
|
||||||
disable-model-invocation: true
|
disable-model-invocation: true
|
||||||
allowed-tools: Read, Write, Edit, Bash, Grep, Glob
|
allowed-tools: Read, Write, Edit, Bash, Grep, Glob
|
||||||
@ -8,15 +8,20 @@ allowed-tools: Read, Write, Edit, Bash, Grep, Glob
|
|||||||
|
|
||||||
# ORCHESTRATOR: INIT PROJECT
|
# ORCHESTRATOR: INIT PROJECT
|
||||||
|
|
||||||
## AGENTS LOADED
|
## AGENTS AND SKILLS LOADED
|
||||||
|
|
||||||
Load and follow strictly:
|
Custom agents (this config):
|
||||||
- .claude/agents/interviewer.md
|
- .claude/agents/plugin-advisor.md ← plugin configuration check
|
||||||
- .claude/agents/analyzer.md
|
- .claude/agents/interviewer.md ← project questionnaire
|
||||||
- .claude/agents/designer.md
|
- .claude/agents/analyzer.md ← risk/constraint analysis
|
||||||
- .claude/agents/scaffolder.md
|
- .claude/agents/scaffolder.md ← project skeleton (NO features, skeleton only)
|
||||||
- .claude/agents/reviewer.md
|
|
||||||
- .claude/agents/tester.md
|
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
|
### STEP 1 — INTERVIEWER
|
||||||
|
|
||||||
Run the INTERVIEWER agent.
|
Load and follow: `.claude/agents/interviewer.md`
|
||||||
|
|
||||||
Using the initial request above as a starting point:
|
Identify what is already provided in the initial request.
|
||||||
- Identify which information is already clearly provided.
|
Ask only what is genuinely missing. Single structured block of questions.
|
||||||
- Ask only what is genuinely missing or ambiguous.
|
|
||||||
- Present all remaining questions in a single structured block.
|
|
||||||
|
|
||||||
**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
|
Produce the PROJECT BRIEF. This is the single source of truth
|
||||||
in interviewer.md. The PROJECT BRIEF is the single source of
|
for all subsequent steps.
|
||||||
truth for all subsequent steps.
|
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
### STEP 2 — ANALYZER
|
### STEP 2 — ANALYZER
|
||||||
|
|
||||||
Run the ANALYZER agent on the PROJECT BRIEF.
|
Load and follow: `.claude/agents/analyzer.md`
|
||||||
|
|
||||||
Focus on:
|
Analyze the PROJECT BRIEF:
|
||||||
- Existing repo or code to integrate (if any)
|
- Existing repo or code to integrate
|
||||||
- Stack constraints and compatibility issues
|
- Stack constraints and compatibility issues
|
||||||
- Infrastructure or environment constraints
|
- Infrastructure constraints
|
||||||
- Risks that could affect the design
|
- 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
|
||||||
|
|
||||||
Run the DESIGNER agent using the PROJECT BRIEF and ANALYSIS REPORT.
|
Invoke skill: `superpowers:brainstorming`
|
||||||
|
|
||||||
|
Feed it the PROJECT BRIEF + ANALYSIS REPORT.
|
||||||
|
|
||||||
Produce a complete DESIGN covering:
|
Produce a complete DESIGN covering:
|
||||||
- Final tech stack with exact versions
|
- Finalized tech stack with exact versions
|
||||||
- Complete folder structure (full tree)
|
- Complete folder structure (full tree)
|
||||||
- Module responsibilities and data flow
|
- Module responsibilities and data flow
|
||||||
- Key interfaces and data models
|
- Key interfaces and data models (signatures only — no implementation)
|
||||||
- Config and tooling setup (lint, format, CI)
|
- Config and tooling setup
|
||||||
- Test strategy and tooling
|
- Test strategy
|
||||||
- Any open decisions resolved with justification
|
- 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
|
**MANDATORY STOP — present to the user and wait for approval.**
|
||||||
for explicit approval before proceeding.**
|
|
||||||
|
|
||||||
```
|
```
|
||||||
================================================================
|
================================================================
|
||||||
INIT PROJECT — VALIDATION GATE
|
INIT PROJECT — ARCHITECTURE VALIDATION
|
||||||
================================================================
|
================================================================
|
||||||
|
|
||||||
PROJECT BRIEF SUMMARY
|
PROJECT SUMMARY
|
||||||
---------------------
|
---------------
|
||||||
<3–5 line recap of what will be built>
|
<3–5 line recap of what will be built>
|
||||||
|
|
||||||
STACK
|
STACK
|
||||||
@ -106,7 +136,8 @@ FOLDER STRUCTURE
|
|||||||
|
|
||||||
V1 FEATURES TO IMPLEMENT
|
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
|
CONVENTIONS
|
||||||
-----------
|
-----------
|
||||||
@ -117,135 +148,172 @@ EXCEPTIONS TO GLOBAL RULES
|
|||||||
<list or "none">
|
<list or "none">
|
||||||
|
|
||||||
================================================================
|
================================================================
|
||||||
Approve this plan? (yes / request changes)
|
Approve this architecture? (yes / request changes)
|
||||||
================================================================
|
================================================================
|
||||||
```
|
```
|
||||||
|
|
||||||
IF user requests changes:
|
IF changes → return to STEP 3.
|
||||||
- Return to STEP 3 (DESIGNER) with the feedback.
|
IF approved → proceed.
|
||||||
- Repeat STEP 4.
|
|
||||||
|
|
||||||
IF approved → proceed to STEP 5.
|
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
### STEP 5 — SCAFFOLDER
|
### STEP 5 — SCAFFOLD SKELETON
|
||||||
|
|
||||||
Run the SCAFFOLDER agent with:
|
Load and follow: `.claude/agents/scaffolder.md`
|
||||||
- The full PROJECT BRIEF
|
|
||||||
- The approved DESIGN
|
|
||||||
- Reference to `~/.claude/templates/project-CLAUDE.md`
|
|
||||||
- Reference to `~/.claude/CLAUDE.md`
|
|
||||||
|
|
||||||
The SCAFFOLDER will, in order:
|
Pass to the scaffolder:
|
||||||
|
- Full PROJECT BRIEF
|
||||||
|
- Approved DESIGN
|
||||||
|
- `~/.claude/templates/project-CLAUDE.md`
|
||||||
|
- `~/.claude/CLAUDE.md`
|
||||||
|
|
||||||
1. **Generate CLAUDE.md** — fill the global template with real
|
The scaffolder creates:
|
||||||
content from the PROJECT BRIEF. No placeholders. No examples.
|
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`
|
||||||
|
|
||||||
2. **Generate README.md** — cross-platform setup instructions
|
**The scaffolder does NOT create the README and does NOT implement any features.**
|
||||||
(Windows / Linux / macOS) covering:
|
README is handled by readme-updater (STEP 5b).
|
||||||
- All prerequisites with exact versions and install commands
|
Features are handled by the implementation pipeline (STEPs 6–9).
|
||||||
- Step-by-step installation
|
|
||||||
- How to run in development and production
|
|
||||||
- How to run tests
|
|
||||||
- Environment configuration
|
|
||||||
|
|
||||||
3. **Generate Claude Code settings** — create `.claude/` with:
|
The scaffolder must verify: `git init` + build passes on empty project.
|
||||||
|
|
||||||
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`
|
|
||||||
|
|
||||||
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
|
|
||||||
|
|
||||||
c. After creating these files, print:
|
|
||||||
```
|
|
||||||
⚙️ SETTINGS SETUP
|
|
||||||
.claude/settings.json created — project-level permissions
|
|
||||||
.claudeignore created — file exclusions for Claude
|
|
||||||
|
|
||||||
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.
|
|
||||||
```
|
|
||||||
|
|
||||||
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.
|
|
||||||
|
|
||||||
6. **Write initial tests** — at minimum one happy path and one
|
|
||||||
edge case per module.
|
|
||||||
|
|
||||||
7. **Install and build** — actually run the install command,
|
|
||||||
build, and test suite. Fix any failures before reporting.
|
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
### STEP 6 — REVIEWER
|
### STEP 5b — CREATE README
|
||||||
|
|
||||||
Run the REVIEWER agent on the scaffolded project.
|
Load and follow: `.claude/agents/readme-updater.md`
|
||||||
|
|
||||||
Review scope:
|
Context: `README.md` does not exist yet → CREATE mode activates automatically.
|
||||||
- Structure coherence vs approved DESIGN
|
|
||||||
|
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`
|
||||||
|
|
||||||
|
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 7 — VALIDATION GATE #2 — IMPLEMENTATION PLAN
|
||||||
|
|
||||||
|
**MANDATORY STOP — present the plan to the user.**
|
||||||
|
|
||||||
|
```
|
||||||
|
================================================================
|
||||||
|
INIT PROJECT — IMPLEMENTATION PLAN VALIDATION
|
||||||
|
================================================================
|
||||||
|
|
||||||
|
SKELETON STATUS : ✅ build passes
|
||||||
|
V1 FEATURES : <N> features → <M> tasks
|
||||||
|
|
||||||
|
<numbered task list with file paths>
|
||||||
|
|
||||||
|
================================================================
|
||||||
|
Approve this plan and start implementation? (yes / request changes)
|
||||||
|
================================================================
|
||||||
|
```
|
||||||
|
|
||||||
|
IF changes → return to STEP 6.
|
||||||
|
IF approved → proceed.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### STEP 8 — IMPLEMENT V1 FEATURES
|
||||||
|
|
||||||
|
Invoke skill: `superpowers:subagent-driven-development`
|
||||||
|
|
||||||
|
Execute each task with isolated subagents.
|
||||||
|
Mandatory TDD: `superpowers:test-driven-development` applies.
|
||||||
|
Two-stage review per task: spec compliance → code quality.
|
||||||
|
|
||||||
|
Each subagent works on a clean context with:
|
||||||
|
- The task description
|
||||||
|
- Relevant file paths
|
||||||
|
- PROJECT BRIEF context
|
||||||
|
- CLAUDE.md conventions
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### STEP 9 — ANALYZE
|
||||||
|
|
||||||
|
Load and follow: `.claude/agents/analyzer.md`
|
||||||
|
|
||||||
|
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 10 — CODE REVIEW
|
||||||
|
|
||||||
|
Invoke skill: `superpowers:requesting-code-review`
|
||||||
|
|
||||||
|
Full review scope:
|
||||||
- Code quality vs CLAUDE.md conventions and global rules
|
- Code quality vs CLAUDE.md conventions and global rules
|
||||||
- Security issues in initial implementation
|
- Security issues
|
||||||
- README completeness and accuracy
|
|
||||||
- Generated CLAUDE.md completeness (no placeholder left)
|
|
||||||
- Missing or incomplete v1 features
|
- Missing or incomplete v1 features
|
||||||
|
- README accuracy
|
||||||
|
- Generated CLAUDE.md completeness (no placeholder remaining)
|
||||||
|
- Test coverage
|
||||||
|
|
||||||
|
Fix all CRITICAL issues before proceeding.
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
### STEP 7 — FIX LOOP
|
### STEP 11 — FINISH
|
||||||
|
|
||||||
Maximum 3 iterations.
|
Invoke skill: `superpowers:finishing-a-development-branch`
|
||||||
|
|
||||||
IF CRITICAL issues found:
|
Verify:
|
||||||
- Run SCAFFOLDER with the list of issues to fix.
|
- All tests pass
|
||||||
- Run REVIEWER again.
|
- Build is clean
|
||||||
- Increment iteration counter.
|
- No leftover scaffold placeholders
|
||||||
|
- Initial commit prepared
|
||||||
IF counter > 3:
|
|
||||||
- STOP.
|
|
||||||
- Present blocking issues to the user and ask how to proceed.
|
|
||||||
|
|
||||||
IF only IMPORTANT or MINOR issues:
|
|
||||||
- Proceed to STEP 8.
|
|
||||||
- List all remaining issues in the final output.
|
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
### STEP 8 — TESTER
|
### STEP 12 — SYNC README
|
||||||
|
|
||||||
Run the TESTER agent on the scaffolded project.
|
Load and follow: `.claude/agents/readme-updater.md`
|
||||||
|
|
||||||
Produce:
|
Context: call with argument "sync".
|
||||||
- Verification that existing tests cover v1 features
|
|
||||||
- Additional test cases for identified edge cases
|
SYNC mode — no stop required. The readme-updater:
|
||||||
- Regression risk assessment
|
- Detects any drift between README and the implemented code
|
||||||
- Confirmation that the test command in CLAUDE.md is correct
|
- Updates commands, env vars, folder structure if changed during implementation
|
||||||
|
- Adds a `## Recent changes` entry summarizing v1 features
|
||||||
|
- Prints one-line confirmation
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## RULES
|
## RULES
|
||||||
|
|
||||||
- Never skip the INTERVIEWER step.
|
- Never skip STEP 0 — plugin check is mandatory.
|
||||||
- Never start design or implementation with unanswered questions.
|
- Never skip STEP 1 — no assumptions about missing info.
|
||||||
- Never implement without explicit user approval of the DESIGN.
|
- Never implement without explicit user approval at STEP 4.
|
||||||
- The generated CLAUDE.md must be complete — no placeholders.
|
- Never implement without explicit user approval at STEP 7.
|
||||||
- The README must work on Windows, Linux, and macOS.
|
- The scaffolder only creates the skeleton — zero business logic.
|
||||||
- The first version must install, build, and run.
|
- All feature implementation goes through the subagent pipeline (STEP 8).
|
||||||
A broken scaffold is not acceptable output.
|
- Apply CLAUDE.md norms throughout.
|
||||||
- Keep agents isolated in their responsibilities.
|
- A broken skeleton or a broken build is not acceptable output.
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
@ -256,11 +324,10 @@ Produce:
|
|||||||
PROJECT INITIALIZED: <project name>
|
PROJECT INITIALIZED: <project name>
|
||||||
================================================================
|
================================================================
|
||||||
|
|
||||||
LOCATION : <project root path>
|
LOCATION : <project root>
|
||||||
STACK : <finalized stack>
|
STACK : <finalized stack>
|
||||||
INSTALL : ✅ / ❌ <error>
|
BUILD : ✅ / ❌ <e>
|
||||||
BUILD : ✅ / ❌ <error>
|
TESTS : ✅ <N> passing / ❌ <detail>
|
||||||
TESTS : ✅ <N> passing / ❌ <detail>
|
|
||||||
|
|
||||||
V1 FEATURES
|
V1 FEATURES
|
||||||
-----------
|
-----------
|
||||||
@ -270,19 +337,14 @@ V1 FEATURES
|
|||||||
|
|
||||||
REMAINING ISSUES
|
REMAINING ISSUES
|
||||||
----------------
|
----------------
|
||||||
<IMPORTANT and MINOR issues from reviewer, or "none">
|
<IMPORTANT and MINOR issues, or "none">
|
||||||
|
|
||||||
QUICK START
|
QUICK START
|
||||||
-----------
|
-----------
|
||||||
<exact commands to get the project running right now>
|
<exact commands to run the project right now>
|
||||||
|
|
||||||
NEXT STEPS
|
CLAUDE.md : ✅ complete
|
||||||
----------
|
README.md : ✅ created (STEP 5b) + synced (STEP 12)
|
||||||
1. <recommended first action>
|
SETTINGS : ✅ .claude/settings.json + .claudeignore generated
|
||||||
2. <recommended second action>
|
|
||||||
|
|
||||||
CLAUDE.md : ✅ complete
|
|
||||||
README.md : ✅ Windows / Linux / macOS
|
|
||||||
SETTINGS : ✅ .claude/settings.json + .claudeignore generated
|
|
||||||
================================================================
|
================================================================
|
||||||
```
|
```
|
||||||
|
|||||||
15
skills/plugin-check/SKILL.md
Normal file
15
skills/plugin-check/SKILL.md
Normal file
@ -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
|
||||||
@ -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
|
|
||||||
@ -1,6 +1,6 @@
|
|||||||
---
|
---
|
||||||
name: ship-feature
|
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>
|
argument-hint: <feature description>
|
||||||
disable-model-invocation: true
|
disable-model-invocation: true
|
||||||
allowed-tools: Read, Write, Edit, Bash, Grep, Glob
|
allowed-tools: Read, Write, Edit, Bash, Grep, Glob
|
||||||
@ -8,16 +8,22 @@ allowed-tools: Read, Write, Edit, Bash, Grep, Glob
|
|||||||
|
|
||||||
# ORCHESTRATOR: SHIP FEATURE
|
# ORCHESTRATOR: SHIP FEATURE
|
||||||
|
|
||||||
Load and follow strictly:
|
## AGENTS AND SKILLS LOADED
|
||||||
- .claude/agents/analyzer.md
|
|
||||||
- .claude/agents/designer.md
|
Custom agents (this config):
|
||||||
- .claude/agents/implementer.md
|
- .claude/agents/plugin-advisor.md ← plugin configuration check
|
||||||
- .claude/agents/reviewer.md
|
- .claude/agents/analyzer.md ← post-implementation verification
|
||||||
- .claude/agents/tester.md
|
|
||||||
|
Superpowers skills:
|
||||||
|
- superpowers:brainstorming
|
||||||
|
- superpowers:writing-plans
|
||||||
|
- superpowers:subagent-driven-development
|
||||||
|
- superpowers:requesting-code-review
|
||||||
|
- superpowers:finishing-a-development-branch
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## FEATURE
|
## FEATURE REQUEST
|
||||||
|
|
||||||
$ARGUMENTS
|
$ARGUMENTS
|
||||||
|
|
||||||
@ -25,61 +31,153 @@ $ARGUMENTS
|
|||||||
|
|
||||||
## WORKFLOW
|
## WORKFLOW
|
||||||
|
|
||||||
### 1. ANALYZER
|
---
|
||||||
Analyze the existing context relevant to the feature.
|
|
||||||
|
|
||||||
### 2. DESIGNER
|
### STEP 0 — PLUGIN CHECK (mandatory gate)
|
||||||
Design the solution based on the analysis.
|
|
||||||
|
|
||||||
### 3. VALIDATION GATE — MANDATORY STOP
|
Load and follow: `.claude/agents/plugin-advisor.md`
|
||||||
- Present the design clearly to the user
|
|
||||||
- Ask for explicit approval
|
|
||||||
- **DO NOT CONTINUE without a response**
|
|
||||||
|
|
||||||
IF changes requested:
|
Feed it the feature request above as context for signal detection.
|
||||||
- Call DESIGNER with feedback
|
|
||||||
- Repeat validation
|
|
||||||
|
|
||||||
IF approved → continue
|
The advisor will:
|
||||||
|
1. Detect which plugins are currently active
|
||||||
|
2. Analyze the feature description for signals
|
||||||
|
3. Produce a recommendation table
|
||||||
|
|
||||||
### 4. IMPLEMENTER
|
**If the advisor output says `ACTION REQUIRED: YES`:**
|
||||||
Implement according to the validated design.
|
|
||||||
|
|
||||||
### 5. REVIEWER
|
Print this block and STOP COMPLETELY:
|
||||||
Strict review of the produced code.
|
|
||||||
|
|
||||||
### 6. FIX LOOP — max 3 iterations
|
```
|
||||||
|
================================================================
|
||||||
|
⚠️ PLUGIN CHECK — ACTION REQUIRED
|
||||||
|
================================================================
|
||||||
|
|
||||||
IF CRITICAL issues:
|
[paste the full RECOMMENDATIONS block from the advisor]
|
||||||
- Call IMPLEMENTER with fixes
|
|
||||||
- Call REVIEWER again
|
|
||||||
- Increment iteration counter
|
|
||||||
|
|
||||||
IF counter > 3:
|
----------------------------------------------------------------
|
||||||
- STOP
|
Options:
|
||||||
- Escalate to user with blocking issues
|
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 only IMPORTANT or MINOR issues:
|
Wait for user response.
|
||||||
- Continue but list them in final output
|
- If user re-runs `/ship-feature` → start from STEP 0 again
|
||||||
|
- If user types "force" → note missing plugins and continue to STEP 1
|
||||||
|
|
||||||
### 7. TESTER
|
**If the advisor output says `ACTION REQUIRED: NO`:**
|
||||||
Generate and run tests for the feature.
|
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.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### STEP 3 — VALIDATION GATE
|
||||||
|
|
||||||
|
**MANDATORY STOP — present the plan to the user.**
|
||||||
|
|
||||||
|
```
|
||||||
|
================================================================
|
||||||
|
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.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### STEP 8 — SYNC README
|
||||||
|
|
||||||
|
Load and follow: `.claude/agents/readme-updater.md`
|
||||||
|
|
||||||
|
Context: call with argument "sync".
|
||||||
|
|
||||||
|
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
|
## RULES
|
||||||
|
|
||||||
- Never skip analysis
|
- Never skip STEP 0 — plugin check is mandatory.
|
||||||
- Never skip validation
|
- Never skip brainstorming.
|
||||||
- Never implement without approval
|
- Never implement without explicit user approval of the plan.
|
||||||
- Keep agents isolated in their responsibilities
|
- Keep subagents isolated — no shared context between tasks.
|
||||||
- Enforce CLAUDE.md norms strictly
|
- Apply CLAUDE.md norms throughout.
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## FINAL OUTPUT
|
## FINAL OUTPUT
|
||||||
|
|
||||||
- Validated design
|
```
|
||||||
- Final implementation
|
================================================================
|
||||||
- Review summary
|
FEATURE SHIPPED: <name>
|
||||||
- Test plan and results
|
================================================================
|
||||||
|
TASKS COMPLETED : <N>/<N>
|
||||||
|
TESTS : ✅ passing / ❌ <detail>
|
||||||
|
REVIEW : APPROVED / CHANGES REQUIRED
|
||||||
|
|
||||||
|
REMAINING ISSUES (IMPORTANT/MINOR):
|
||||||
|
- <issue or "none">
|
||||||
|
================================================================
|
||||||
|
```
|
||||||
|
|||||||
Loading…
Reference in New Issue
Block a user