claudeforge-cli 1.0.0 → 1.0.2

package/README.md

@@ -2,7 +2,7 @@
 
 > Forge production-ready AI agent projects — agents, slash commands, memory, CI/CD, and devcontainers in one command.
 
-[![npm version](https://img.shields.io/npm/v/claudeforge)](https://www.npmjs.com/package/claudeforge)
+[![npm version](https://img.shields.io/npm/v/claudeforge-cli)](https://www.npmjs.com/package/claudeforge-cli)
 [![PyPI version](https://img.shields.io/pypi/v/claudeforge)](https://pypi.org/project/claudeforge)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
 [![Node.js 18+](https://img.shields.io/badge/node-%3E%3D18-brightgreen)](https://nodejs.org)
@@ -12,6 +12,42 @@
 
 ---
 
+## Requirements
+
+> **Node.js 18+ is required regardless of how you install claudeforge.**
+> The CLI is built on Node.js — the pip package is a thin wrapper that delegates to it automatically.
+
+| Requirement | Version | Notes |
+|-------------|---------|-------|
+| Node.js | 18+ | Required for the CLI — install first |
+| npm | any | Included with Node.js |
+| Python | 3.8+ | Only needed if installing via pip |
+| Claude Code | latest | IDE extension for slash commands |
+
+### Install Node.js (if you don't have it)
+
+```bash
+# macOS
+brew install node
+
+# macOS / Linux — via nvm (recommended)
+curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash
+nvm install 20
+
+# Ubuntu / Debian
+curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
+sudo apt-get install -y nodejs
+
+# Windows — download installer from https://nodejs.org
+```
+
+Verify:
+```bash
+node --version   # should print v18 or higher
+```
+
+---
+
 ## Table of Contents
 
 - [What It Does](#what-it-does)
@@ -50,19 +86,29 @@
 
 ### via npm (recommended)
 
+Best if you already have Node.js installed.
+
 ```bash
-npm install -g claudeforge
+npm install -g claudeforge-cli
 ```
 
-### via pip
+### via pip / uv
+
+Best if you primarily work in Python environments. Node.js 18+ must still be installed on your system (see [Requirements](#requirements) above).
 
 ```bash
+# pip
 pip install claudeforge
+
+# uv (recommended — installs as a global CLI tool)
+uv tool install claudeforge
 ```
 
-> **pip users:** Node.js 18+ must be on your PATH. The pip package delegates to the Node.js CLI automatically.
+> **Important:** If using `uv`, use `uv tool install` — not `uv pip install`. The `pip` variant installs into a virtualenv and won't put `claudeforge` on your PATH.
 
-Verify installation:
+> The pip/uv package is a thin wrapper — when you run `claudeforge`, it locates Node.js on your PATH and delegates all commands to the Node.js CLI automatically.
+
+### Verify installation
 
 ```bash
 claudeforge --version
@@ -286,7 +332,8 @@ Run these in the Claude Code chat window in VS Code, JetBrains, or any Claude Co
 
 | Command | When to run | What it does |
 |---------|-------------|-------------|
-| `/setup-project "description"` | After `claudeforge init` | Fills in CLAUDE.md, settings, .env.example, .mcp.json, memory, generates 2–4 project-specific agents and commands, then documents every file it creates |
+| `/analyze-project` | Existing project, no description needed | Reads your actual codebase — code, patterns, conventions, git history — and generates the full Claude Code setup automatically |
+| `/setup-project "description"` | New project or when you want to describe it manually | Fills in CLAUDE.md, settings, .env.example, .mcp.json, memory, generates project-specific skills, agents, and commands |
 | `/scaffold-structure` | After `/setup-project` | Creates the actual `src/`, `tests/`, `cmd/` directory structure with real starter files for your stack |
 | `/project-health` | Weekly / after big changes | Audits your setup: checks CLAUDE.md completeness, hook coverage, memory fill level, and gives prioritized improvement suggestions |
 | `/memory-sync` | End of work session | Reviews the session and updates `memory/` files with preferences, decisions, and project context |
@@ -376,24 +423,46 @@ The CLI handles file scaffolding. The AI work happens inside the IDE where Claud
 
 ## Troubleshooting
 
-**`claudeforge: command not found`**
+**`claudeforge: command not found` after npm install**
 ```bash
-# npm
-npm install -g claudeforge
-# pip (ensure ~/.local/bin is on PATH)
-pip install claudeforge
+# Ensure npm global bin is on PATH
+export PATH="$(npm prefix -g)/bin:$PATH"
+# Add to ~/.zshrc or ~/.bashrc to persist
+```
+
+**`claudeforge: command not found` after pip install**
+```bash
+# Ensure pip user bin is on PATH
 export PATH="$HOME/.local/bin:$PATH"
+# Add to ~/.zshrc or ~/.bashrc to persist
 ```
 
-**pip install: `Node.js is required`**
+**`claudeforge: command not found` after `uv pip install`**
+
+`uv pip install` puts packages into a virtualenv, not on your PATH. Use `uv tool install` instead:
+```bash
+uv tool install claudeforge
+```
+
+**`Node.js is required but was not found on PATH`**
+
+This happens when installing via pip — Node.js must be installed separately.
+
 ```bash
 # macOS
 brew install node
-# Ubuntu/Debian
+
+# macOS / Linux — via nvm
+curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash
+nvm install 20
+
+# Ubuntu / Debian
 curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
 sudo apt-get install -y nodejs
 ```
 
+After installing Node.js, open a new terminal and retry.
+
 **`/setup-project` didn't generate anything**
 Make sure you ran `claudeforge init` first — the `.claude/commands/` directory must exist for slash commands to work.
 
@@ -415,17 +484,6 @@ Confirm you're running Claude Code (not just Copilot Chat). The `.claude/command
 
 ---
 
-## Requirements
-
-| Requirement | Version | Notes |
-|-------------|---------|-------|
-| Node.js | 18+ | Required for the CLI |
-| npm | any | Included with Node.js |
-| Python | 3.8+ | Only if installing via pip |
-| Claude Code | latest | IDE extension for slash commands |
-
----
-
 ## License
 
 MIT

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claudeforge-cli",
-  "version": "1.0.0",
+  "version": "1.0.2",
   "description": "Forge production-ready AI agent projects — agents, slash commands, memory, CI/CD, and devcontainers in one command",
   "bin": {
     "claudeforge": "bin/cli.js"

package/src/commands/init.js

@@ -36,6 +36,7 @@ const MANIFEST = [
   { type: 'file', src: 'claude/commands/review-pr.md.tpl',       dest: '.claude/commands/review-pr.md' },
   // AI setup & maintenance commands
   { type: 'file', src: 'claude/commands/setup-project.md.tpl',   dest: '.claude/commands/setup-project.md' },
+  { type: 'file', src: 'claude/commands/analyze-project.md.tpl', dest: '.claude/commands/analyze-project.md' },
   { type: 'file', src: 'claude/commands/memory-sync.md.tpl',     dest: '.claude/commands/memory-sync.md' },
   { type: 'file', src: 'claude/commands/project-health.md.tpl',  dest: '.claude/commands/project-health.md' },
   // Developer productivity commands

package/templates/claude/commands/analyze-project.md.tpl

@@ -0,0 +1,244 @@
+---
+description: Analyze an existing codebase and auto-generate the full Claude Code setup — CLAUDE.md, skills, agents, commands, and memory — by reading actual code, patterns, and conventions already in the project. No description required.
+allowed-tools: Read, Write, Edit, MultiEdit, Bash(git log:*), Bash(git diff:*), Bash(ls:*), Bash(find:*), Bash(cat:*), Bash(wc:*)
+---
+
+## Step 1 — Deep Codebase Scan
+
+Do not ask the user for a description. Read the codebase directly to infer everything.
+
+### 1a. Project identity
+
+!`ls -la`
+!`cat package.json 2>/dev/null || cat pyproject.toml 2>/dev/null || cat go.mod 2>/dev/null || cat Cargo.toml 2>/dev/null || echo "(no manifest found)"`
+!`cat README.md 2>/dev/null | head -60 || echo "(no README)"`
+
+### 1b. Full dependency map
+
+!`cat package.json 2>/dev/null`
+!`cat requirements.txt 2>/dev/null || cat pyproject.toml 2>/dev/null`
+!`cat go.mod 2>/dev/null`
+!`cat Cargo.toml 2>/dev/null`
+!`cat pom.xml 2>/dev/null | head -80`
+!`cat Gemfile 2>/dev/null`
+
+### 1c. Project structure
+
+!`find . -type f \( -name "*.js" -o -name "*.ts" -o -name "*.py" -o -name "*.go" -o -name "*.rs" -o -name "*.java" -o -name "*.rb" \) -not -path "*/node_modules/*" -not -path "*/.git/*" -not -path "*/dist/*" -not -path "*/__pycache__/*" -not -path "*/target/*" | head -80`
+!`find . -type d -not -path "*/node_modules/*" -not -path "*/.git/*" -not -path "*/__pycache__/*" -not -path "*/target/*" -not -path "*/dist/*" | head -40`
+
+### 1d. Read actual source code — infer real patterns
+
+Read the most representative files in each layer of the project. For each category below, find and read 2–3 real files:
+
+- **Entry points**: `main.py`, `index.ts`, `main.go`, `app.py`, `server.js`, etc.
+- **Route/controller layer**: files in `routes/`, `controllers/`, `handlers/`, `api/`, `pages/api/`
+- **Service/business logic layer**: files in `services/`, `lib/`, `internal/`, `core/`
+- **Data/database layer**: files in `models/`, `db/`, `prisma/`, `migrations/`, `schema/`
+- **UI components** (if frontend): files in `components/`, `pages/`, `views/`, `screens/`
+- **Tests**: files in `tests/`, `__tests__/`, `spec/`, `test/`
+- **Config**: `tsconfig.json`, `eslint.config.*`, `.prettierrc`, `pytest.ini`, `ruff.toml`, etc.
+
+Read enough code to answer:
+- What frameworks and libraries are actually used (not just listed in deps)?
+- How are files structured and named?
+- What patterns repeat across files (error handling, auth checks, response format, logging)?
+- What conventions are enforced (naming, imports, exports)?
+- How are tests written?
+
+### 1e. Git history — understand how the project evolved
+
+!`git log --oneline -20 2>/dev/null || echo "(no git history)"`
+!`git log --pretty=format:"%s" -50 2>/dev/null | sort | uniq -c | sort -rn | head -20`
+
+What do the commit messages reveal about the team's workflow and focus areas?
+
+### 1f. Existing CI/CD and infrastructure
+
+!`cat .github/workflows/*.yml 2>/dev/null | head -100 || echo "(no GitHub Actions)"`
+!`cat Dockerfile 2>/dev/null | head -40 || echo "(no Dockerfile)"`
+!`cat docker-compose.yml 2>/dev/null || echo "(no docker-compose)"`
+!`cat .env.example 2>/dev/null || cat .env.sample 2>/dev/null || echo "(no .env.example)"`
+
+---
+
+## Step 2 — Build a Mental Model of the Project
+
+Before writing any files, reason through what you found:
+
+1. **What does this project do?** — infer from code, not just README
+2. **What is the architecture?** — layers, boundaries, data flow
+3. **What are the distinct technical domains?** — each will become a skill
+4. **What conventions are already established?** — naming, patterns, idioms in real use
+5. **What are the high-risk areas?** — where bugs are costly (payments, auth, data, migrations)
+6. **What does the team care about?** — infer from commit patterns, test coverage, CI config
+7. **What is missing or inconsistent?** — patterns that are partially established but not enforced
+
+---
+
+## Step 3 — Generate the Full Claude Code Setup
+
+Using only what you observed — no assumptions, no generic advice — generate all files.
+
+### 3a. Write `CLAUDE.md`
+
+Write a complete `CLAUDE.md` based on the actual project:
+
+**Header**: Real project name and a one-line description inferred from the code.
+
+**Commands table**: Only commands that actually exist in the project (from `package.json` scripts, `Makefile`, CI config, etc.). Do not invent commands.
+
+**Architecture**: An accurate directory tree of the real project structure with a description of each folder's purpose — inferred from what files are actually there.
+
+**Code Style**: Conventions observed in the actual code — not generic guidelines. Examples:
+- "Functions use early return pattern — no nested if/else"
+- "All async functions are wrapped in the shared `tryCatch` utility from `lib/errors.ts`"
+- "Database queries always go through `src/db/client.ts` — never import Prisma directly"
+
+**Environment Variables**: Table built from `.env.example`, config files, and any `process.env` / `os.environ` references found in the code.
+
+**Gotchas**: Real non-obvious things found in the code — not generic stack gotchas. Look for comments like `// important`, `// NOTE`, `// FIXME`, `# WARNING`, unusual patterns, or workarounds.
+
+**Workflow**: How to use Claude Code slash commands and agents with this specific project.
+
+---
+
+### 3b. Update `.claude/settings.json`
+
+Read the current file, then add permissions for the commands and tools the project actually uses (from CI config, Makefile, package.json scripts).
+
+---
+
+### 3c. Write `.env.example` (if missing or incomplete)
+
+If `.env.example` is missing or sparse, generate a complete one from:
+- Existing `.env.example` / `.env.sample`
+- All `process.env.X`, `os.environ["X"]`, `viper.GetString("X")` references in the code
+- Any config files that reference environment variables
+
+---
+
+### 3d. Create Skills — One Per Observed Domain
+
+For each distinct technical domain found in the codebase, create a skill at `.claude/skills/<domain>/SKILL.md`.
+
+The skill must reflect **actual conventions in this codebase** — read from real code, not inferred from the framework name. For example:
+
+- If the project uses Express, read how routes are actually structured in this project, how middleware is applied, how errors are returned — and write that into the skill
+- If the project uses React, read how components are actually written here — hooks, prop patterns, styling approach, state management — and write that in
+- If the project uses PostgreSQL, read how queries are written — raw SQL vs ORM, transaction patterns, connection handling — and write that in
+
+Each skill must include:
+1. **What this domain covers** in this project — which files/folders
+2. **Naming and file conventions** — as actually observed
+3. **Key patterns** — with short code snippets taken or adapted from the real codebase
+4. **Integration points** — how this domain connects to others in this project
+5. **Gotchas** — non-obvious things found in the actual code
+
+`description` frontmatter: write as a precise trigger — when should Claude load this skill?
+
+Always create/update the base `project-conventions` skill with cross-cutting conventions observed across the whole codebase.
+
+---
+
+### 3e. Create Agents — Reviewers for High-Risk Domains
+
+Identify which domains in this project carry the most risk if done wrong. Only create reviewer agents for those.
+
+Reviewer checklists must be built from what you observed:
+- If the project has a custom auth pattern, the `security-auditor` checklist must check for that pattern
+- If the project uses a specific migration tool, the `db-reviewer` checklist must include migration-specific checks for that tool
+- If the project has payment logic, the `stripe-reviewer` (or equivalent) checklist must reflect the actual payment flow
+
+Always create:
+- `code-reviewer.md` — general review tailored to this project's conventions
+- `security-auditor.md` — security review tailored to the auth and data patterns in this code
+
+---
+
+### 3f. Create Slash Commands
+
+Create 2–4 slash commands for the workflows the team clearly uses (inferred from CI, Makefile, commit patterns):
+
+- If the project has a test suite → `/test`
+- If the project has migrations → `/migrate`
+- If the project deploys → `/deploy`
+- If the project has a linter/formatter → include in `/test` or as a step in `/commit`
+
+Each command must use `!` to pull live context (e.g., `!git diff`, `!npm test 2>&1`).
+
+---
+
+### 3g. Write `memory/project_ai_workflow.md`
+
+Document:
+- Which skill loads for which task
+- Which agent to invoke and when
+- Project-specific AI conventions based on what was found (e.g., "always read `src/schema.ts` before modifying any API types")
+- Any architectural decisions that Claude must respect
+
+---
+
+## Step 4 — Document Every File Generated
+
+Add headers to each file explaining what it is and how to customize it (same format as `/setup-project`).
+
+---
+
+## Step 5 — Write `SETUP_SUMMARY.md`
+
+```markdown
+# Claude Code Setup Summary
+
+Analyzed and generated by `/analyze-project` on [today's date].
+
+## What Was Observed
+
+- **Stack**: [detected stack]
+- **Architecture**: [brief description]
+- **Domains identified**: [list]
+- **High-risk areas**: [list]
+
+## What Was Generated
+
+| File | Based On |
+|------|---------|
+| `CLAUDE.md` | Actual project structure, commands, and code conventions |
+| Skills | Conventions observed in real source files per domain |
+| Agents | High-risk areas identified in the codebase |
+| Commands | Workflows found in CI, Makefile, package.json scripts |
+| `.env.example` | Environment references found throughout the codebase |
+
+## Skills Available
+
+| Skill | Loaded When |
+|-------|------------|
+| `project-conventions` | Always |
+| *(domain skills)* | See `.claude/skills/` |
+
+## Agents Available
+
+| Agent | Invoked When |
+|-------|-------------|
+| `code-reviewer` | Before every PR |
+| `security-auditor` | Auth, secrets, input handling |
+| *(domain reviewers)* | See `.claude/agents/` |
+
+## Next Steps
+
+1. Review `CLAUDE.md` — verify the commands table matches your actual workflow
+2. Skim the generated skills — adjust any conventions that were misread
+3. Run `/project-health` to audit the setup
+4. Delete this file once you've reviewed it
+```
+
+---
+
+## Step 6 — Final Summary
+
+Print what was generated:
+1. Every skill created — what domain it covers and its trigger condition
+2. Every agent created — what it reviews and when it triggers
+3. Every slash command created
+4. Any gaps found (e.g., missing `.env.example`, no tests detected, no CI config)
+5. Suggested next step

package/templates/claude/commands/setup-project.md.tpl

@@ -1,5 +1,5 @@
 ---
-description: AI-fill the complete Claude Code project configuration. Run after `claudeforge project "description"` — or run it directly with your project description as the argument. Generates CLAUDE.md, settings, agents, commands, memory, and more.
+description: AI-fill the complete Claude Code project configuration. Run after `claudeforge project "description"` — or run it directly with your project description as the argument. Generates CLAUDE.md, settings, skills, agents, commands, memory, and more.
 allowed-tools: Read, Write, Edit, MultiEdit, Bash(git status:*), Bash(git log:*), Bash(ls:*), Bash(find:*), Bash(cat:*), Bash(rm:*)
 ---
 
@@ -46,7 +46,7 @@ Write a complete `CLAUDE.md` that includes:
 
 **Gotchas**: 3–5 non-obvious things about this stack (e.g., "FastAPI route order matters — more specific routes must be declared before generic ones").
 
-**Workflow**: How to use `/commit`, `/review-pr`, and project-specific agents.
+**Workflow**: How to use `/commit`, `/review-pr`, and which skills and agents apply to this project.
 
 ### 2b. Update `.claude/settings.json`
 
@@ -84,37 +84,114 @@ Always keep `context7`. Add servers based on the stack:
 ### 2e. Rewrite `memory/project_ai_workflow.md`
 
 Write a complete, project-specific workflow document:
-- Which agents to use and when (be explicit: "use `api-reviewer` whenever adding a new endpoint")
+- Which skills load automatically and when (be explicit: "the `prisma` skill loads whenever writing database queries")
+- Which agents to use and when (be explicit: "use `security-auditor` whenever adding auth or payment logic")
 - Which slash commands map to which tasks
 - MCP servers available and how to invoke them
 - Project-specific AI conventions (e.g., "always read `src/db/schema.py` before writing queries")
 - Any architectural decisions that Claude should know and respect
 
-### 2f. Create 2–4 Specialized Agents
+---
+
+### 2f. Infer and Create Skills — Domain Specialists
+
+**Skills** live in `.claude/skills/` and are loaded as context *before* Claude writes code. They encode how to write code correctly for a specific domain in this project — like a senior developer's internal style guide baked into Claude's context.
+
+#### Step 1 — Identify the distinct technical domains in this project
+
+Read the project description and detected files. Extract every distinct technical concern that has its own patterns, conventions, or APIs. Each is a candidate for a skill. Think domain-by-domain:
+
+- "Next.js SaaS with Stripe, Prisma, and Clerk auth"
+  → domains: Next.js components/pages, Stripe payments, Prisma queries, Clerk authentication
+- "Go gRPC microservice with PostgreSQL and Redis"
+  → domains: gRPC service definitions, PostgreSQL queries, Redis caching
+- "React Native app with Firebase and Expo"
+  → domains: React Native screens/navigation, Firebase Firestore, Firebase Auth, Expo config
+- "Django REST API with Celery and S3"
+  → domains: Django REST endpoints, Celery tasks, S3 file handling
+- "Rust CLI tool for CSV parsing"
+  → domains: CLI argument parsing, CSV parsing/transformation, Rust error handling
+
+There is no fixed number — create as many skills as there are meaningful, distinct domains with non-obvious conventions. A simple project may need 2. A complex one may need 6.
+
+#### Step 2 — Create a SKILL.md for each domain
+
+Each skill lives at `.claude/skills/<domain-name>/SKILL.md`.
+
+Every skill file must have:
+
+```
+---
+description: "<precise trigger condition — when should Claude load this skill>"
+---
+```
+
+The `description` is the most important field. Write it as a specific trigger condition so Claude loads it at exactly the right moment:
+- Good: `"Load when writing or modifying any Stripe payment intent, webhook handler, or subscription logic"`
+- Bad: `"Stripe knowledge"`
+
+The skill body must read like a senior developer's internal guide for this domain in this specific project. Include:
+
+1. **Overview** — what this domain does in this project, which files/folders it lives in
+2. **Conventions** — naming patterns, file structure, how new files should be organized
+3. **Key patterns** — the specific way this project does things (e.g., "all Prisma queries go through `src/lib/db.ts`, never import PrismaClient directly")
+4. **Integration points** — how this domain connects to others (e.g., "Stripe webhooks call the same service layer as the REST API")
+5. **Common mistakes** — non-obvious pitfalls specific to this stack/version
+6. **Examples** — 1–2 short, concrete code snippets showing the right pattern for this project
+
+#### Step 3 — Always create the base `project-conventions` skill
+
+Update `.claude/skills/project-conventions/SKILL.md` with project-specific conventions:
+- Commit message format
+- PR conventions
+- General code style rules that apply across all domains
+- How to name files, variables, functions in this project
+
+---
+
+### 2g. Infer and Create Agents — Reviewers and Auditors
+
+**Agents** live in `.claude/agents/` and are invoked as focused subagents to *review, audit, or run a workflow* independently. They have tool access. Do not create agents for writing code — that is what skills are for.
+
+#### Step 1 — Identify domains that have non-obvious review risks
+
+Not every domain needs a reviewer agent. Only create one when a focused checklist genuinely adds value — e.g., database migrations (irreversible), payment flows (financial risk), auth logic (security risk), caching strategies (correctness risk).
+
+Examples by project type:
+- "Next.js SaaS with Stripe, Prisma, and Clerk" → `stripe-reviewer` (payment correctness), `db-reviewer` (migration safety)
+- "Go gRPC microservice with PostgreSQL and Redis" → `db-reviewer` (query performance), `api-reviewer` (gRPC contract safety)
+- "React Native app with Firebase" → `security-auditor` (Firebase rules, auth), `performance-reviewer` (React Native render performance)
+- "Django REST API with Celery" → `api-reviewer` (REST conventions), `db-reviewer` (ORM query safety)
+
+#### Step 2 — Create a reviewer agent for each high-risk domain
 
-Create agent files in `.claude/agents/`. Choose agents appropriate to the project type:
+Each agent file at `.claude/agents/<name>.md` must have:
 
-**For API/Backend projects:**
-- `api-reviewer.md` — Reviews new endpoints: checks REST conventions, input validation, auth, error responses, OpenAPI compliance
-- `db-reviewer.md` — Reviews database changes: checks query performance, migration safety, index coverage, N+1 risks
+```
+---
+description: "<precise trigger — when Claude should invoke this agent>"
+---
+```
 
-**For Frontend projects:**
-- `component-reviewer.md` — Reviews UI components: checks accessibility, responsive design, prop types, performance (memo, useMemo)
-- `ux-checker.md` — Reviews user-facing copy, loading states, error states, empty states
+The agent body must include:
+1. A focused role statement — what this agent reviews and why it matters
+2. A numbered checklist specific to this stack and domain
+3. A clear output format: severity rating per issue, actionable fix suggestion
 
-**For Data/ML projects:**
-- `data-validator.md` — Validates data pipelines: schema consistency, null handling, statistical reasonableness
-- `ml-reviewer.md` — Reviews model code: data leakage, correct train/val/test splits, metric definitions
+#### Step 3 — Always create these two agents regardless of project type
 
-**For all projects:**
-- `security-auditor.md` — Deep security review: focuses on auth flows, input sanitization, secrets management, dependency CVEs
+- `code-reviewer.md` — General code review across correctness, error handling, style, test coverage, and documentation. Invoked before every PR.
+- `security-auditor.md` — Reviews any code touching auth, secrets, input validation, or external APIs. No tool access restrictions.
 
-Each agent must have:
-- Accurate `description` frontmatter (this determines when Claude invokes it automatically)
-- A detailed system prompt with a numbered checklist specific to the project
-- A clear output format
+#### Rules for all agents
+
+- `description` must be a specific trigger condition, not a job title
+- Reviewer checklists must be tailored to the actual stack — not generic
+- Every agent must have a clear output format with severity levels
+
+---
 
-### 2g. Create 2–4 Slash Commands
+### 2h. Create 2–4 Slash Commands
 
 Create command files in `.claude/commands/` specific to this workflow:
 
@@ -126,7 +203,7 @@ Create command files in `.claude/commands/` specific to this workflow:
 
 Each command must use `!` dynamic context (e.g., `!git diff`, `!npm test 2>&1`) and have a clear `## Task` section.
 
-### 2h. Append `.gitignore` Tech-Stack Patterns
+### 2i. Append `.gitignore` Tech-Stack Patterns
 
 Append a labeled section with patterns for this stack. Examples:
 - Python: `__pycache__/`, `*.pyc`, `.pytest_cache/`, `.mypy_cache/`, `.ruff_cache/`, `dist/`, `*.egg-info/`
@@ -150,25 +227,30 @@ rm -f SETUP_CONTEXT.md
 
 After all files are written, go back and add a documentation header to each one so users know what they're looking at and what to customize.
 
-For each file written, prepend (or add at an appropriate location):
-
 **CLAUDE.md** — add at the top after the title:
 ```
 > **Setup status**: Generated by claudeforge. Update the Commands table with your actual
 > project commands after verifying them. Fill in the Gotchas section as you discover them.
 ```
 
-**`.claude/settings.json`** — add a `_readme` key (JSON doesn't support comments, use this):
+**`.claude/settings.json`** — add a `_readme` key:
 ```json
-"_readme": "Team-shared Claude Code settings. Personal overrides go in settings.local.json (gitignored). See .claude/README.md for the full reference."
+"_readme": "Team-shared Claude Code settings. Personal overrides go in settings.local.json (gitignored)."
+```
+
+**Each skill file** — after the frontmatter, add:
+```
+<!-- WHAT THIS IS: A skill that loads as context when Claude works in this domain.
+     HOW IT WORKS: Claude reads this automatically before writing code that matches the description.
+     HOW TO CUSTOMIZE: Update the patterns and examples below as your project evolves.
+     THINGS TO ADD: New conventions, discovered gotchas, team-specific patterns. -->
 ```
 
 **Each agent file** — after the frontmatter, add:
 ```
-<!-- WHAT THIS IS: A Claude sub-agent that specializes in [specific task].
+<!-- WHAT THIS IS: A reviewer agent Claude invokes to audit this domain.
      HOW TO INVOKE: Claude uses this automatically when the task matches the description.
-     HOW TO CUSTOMIZE: Edit the checklist items below to match your project's specific patterns.
-     THINGS TO ADD: Project-specific anti-patterns, naming conventions, architectural rules. -->
+     HOW TO CUSTOMIZE: Edit the checklist items to match your project's specific patterns. -->
 ```
 
 **Each command file** — after the frontmatter, add:
@@ -205,9 +287,29 @@ Generated by `/setup-project` on [today's date].
 | `.env.example` | Documents required env vars | Update with any new vars; never commit real values |
 | `.mcp.json` | MCP servers your team shares | Add connection strings to .env for any DB servers |
 | `memory/project_ai_workflow.md` | AI conventions for this project | Update as your workflow evolves; Claude reads this every session |
-| [agent files] | Specialized review agents | Customize checklists to add project-specific patterns |
+| [skill files] | Domain expertise loaded before writing code | Update conventions as the project evolves |
+| [agent files] | Specialized reviewer agents | Customize checklists to add project-specific patterns |
 | [command files] | Slash commands for your workflow | Edit the ## Task section to match your exact needs |
 
+## Skills Available
+
+Claude loads these automatically before writing code in each domain:
+
+| Skill | Loaded When |
+|-------|------------|
+| `project-conventions` | Always — applies to all code |
+| *(project-specific skills)* | See `.claude/skills/` for the full list |
+
+## Agents Available
+
+Claude invokes these automatically to review and audit:
+
+| Agent | Invoked When |
+|-------|-------------|
+| `code-reviewer` | After writing code, before PR |
+| `security-auditor` | Any auth, secrets, or input-handling code |
+| *(project-specific reviewers)* | See `.claude/agents/` for the full list |
+
 ## Slash Commands Available
 
 Run these in the Claude Code chat window:
@@ -223,15 +325,6 @@ Run these in the Claude Code chat window:
 | `/scaffold-structure` | Once — creates the src/, tests/, etc. directory structure |
 | [project commands] | See .claude/commands/ for project-specific commands |
 
-## Agents Available
-
-Claude uses these automatically based on what you're doing:
-
-| Agent | Invoked When |
-|-------|-------------|
-| `code-reviewer` | After writing code, before PR |
-| [project agents] | See .claude/agents/ for project-specific agents |
-
 ## Next Steps
 
 1. **Verify commands** in `CLAUDE.md` — run each one and confirm they work
@@ -247,7 +340,7 @@ Claude uses these automatically based on what you're doing:
 
 Print a clear summary of everything that was done:
 
-1. List every file written
+1. List every skill created with its trigger description
 2. List every agent created with its trigger description
 3. List every slash command created with its use case
 4. State the exact next step: "Run `/scaffold-structure` in Claude Code to create your project's directory structure"