forgedev 1.1.0 → 1.2.0

package/README.md

@@ -16,6 +16,9 @@ npx forgedev init
 
 # Diagnose and optimize existing project
 npx forgedev doctor
+
+# Check for updates
+npx forgedev update
 ```
 
 ## Four Modes, Four Audiences
@@ -174,14 +177,52 @@ Every project includes:
 
 With Claude Code infrastructure enabled (default):
 
-- **CLAUDE.md** tailored to your stack
-- **Hooks** — auto-lint on edit, quality gate on stop
-- **Skills** — framework-specific knowledge
-- **Agents** — 5-agent verification chain
-- **Commands** — workflows, status, next, done, verify-all, audit-spec, audit-wiring, audit-security, pre-pr, run-uat, generate-prd, generate-uat, optimize-claude-md
+- **CLAUDE.md** tailored to your stack (with pitfalls and agents quick-reference)
+- **Hooks** — cross-platform Node.js `.mjs` hooks (auto-lint on edit, quality gate, protected file guard)
+- **17 Agents** — verification, development, review, and orchestration (see below)
+- **20 Commands** — daily workflow, verification, release, development, session management
+- **8 Skills** — framework-specific + universal knowledge
 - **UAT templates** — scenario packs and CSV checklists
 - **Prompt library** — the complete development prompt library
 
+## Agents (18)
+
+Every scaffolded project gets these agents in `.claude/agents/`:
+
+| Agent | Role | Access |
+|-------|------|--------|
+| `architect` | System design, data models, API contracts | Read-only |
+| `build-error-resolver` | Fix build/lint/type errors with minimal changes | Write |
+| `chief-of-staff` | Orchestrate multiple agents for complex tasks | Write |
+| `code-quality-reviewer` | Code quality review | Read-only |
+| `database-reviewer` | Query optimization, schema review, N+1 detection | Read-only |
+| `doc-updater` | Keep docs in sync with code changes | Write |
+| `docs-lookup` | Search framework docs for answers | Read-only |
+| `e2e-runner` | Generate and run Playwright E2E tests | Write |
+| `harness-optimizer` | Audit Claude Code setup, suggest optimizations | Read-only |
+| `loop-operator` | Autonomous improvement loops with stop conditions | Write |
+| `planner` | Create implementation plans before coding | Read-only |
+| `product-strategist` | Research competitors, evaluate maturity, recommend improvements | Read-only |
+| `production-readiness` | Production deployment readiness review | Read-only |
+| `refactor-cleaner` | Dead code removal, duplicate elimination | Write |
+| `security-reviewer` | Security audit | Read-only |
+| `spec-validator` | Validate implementation matches specification | Read-only |
+| `tdd-guide` | Enforce RED-GREEN-REFACTOR TDD cycle | Write |
+| `uat-validator` | QA validation of UAT scenarios | Read-only |
+
+## Skills (8)
+
+| Skill | Scope |
+|-------|-------|
+| `nextjs` | Next.js 15 App Router patterns |
+| `fastapi` | FastAPI + SQLAlchemy 2.0 + Pydantic v2 |
+| `playwright` | Playwright E2E testing |
+| `security-web` | Web application security |
+| `security-api` | API security |
+| `ai-prompts` | AI/LLM integration patterns |
+| `git-workflow` | Git branching, commits, PR workflow (universal) |
+| `testing-patterns` | Test pyramid, AAA pattern, mocking (universal) |
+
 ## Development
 
 ```bash
@@ -190,6 +231,7 @@ npm test                           # run unit tests
 node bin/devforge.js test-output   # manual smoke test (guided + developer)
 node bin/devforge.js init          # test init mode (from any project dir)
 node bin/devforge.js doctor        # test doctor mode (from any project dir)
+node bin/devforge.js update        # check for updates
 ```
 
 ## Project Structure
@@ -198,7 +240,7 @@ node bin/devforge.js doctor        # test doctor mode (from any project dir)
 devforge/
 ├── bin/devforge.js              # CLI entry point
 ├── src/
-│   ├── cli.js                   # Command router (new, init, doctor)
+│   ├── cli.js                   # Command router (new, init, doctor, update)
 │   ├── index.js                 # New project orchestrator (guided + developer)
 │   ├── guided.js                # Guided mode (description → stack)
 │   ├── prompts.js               # Interactive prompts (Inquirer.js)
@@ -211,6 +253,8 @@ devforge/
 │   ├── doctor.js                # Doctor mode orchestrator
 │   ├── doctor-checks.js         # Diagnostic check functions
 │   ├── doctor-prompts.js        # Fix prompt generators
+│   ├── update-check.js          # npm registry version check
+│   ├── update.js                # Update command handler
 │   └── utils.js                 # File ops, logging, colors
 ├── templates/                   # Scaffold templates by category
 │   ├── base/                    # Every project gets this
@@ -225,26 +269,55 @@ devforge/
 └── docs/                        # Reference documentation
 ```
 
-## Claude Code Commands
+## Claude Code Commands (20)
 
 After running `npx forgedev init`, these slash commands are available inside Claude Code:
 
+**Daily Workflow:**
+
 | Command | What It Does |
 |---------|-------------|
 | `/workflows` | Lists all available workflows |
 | `/status` | Project dashboard — tests, branch, changes |
 | `/next` | Figures out your next task |
 | `/done` | Verifies task completion |
+
+**Verification:**
+
+| Command | What It Does |
+|---------|-------------|
 | `/verify-all` | Runs lint, type check, tests, then launches reviewers |
+| `/full-audit` | Runs every audit and review agent in a single pass |
 | `/audit-spec` | Validates implementation against a spec/PRD |
 | `/audit-wiring` | Finds dead or unwired features |
 | `/audit-security` | Runs a security audit |
+| `/code-review` | Reviews uncommitted changes for security and quality |
+
+**Release:**
+
+| Command | What It Does |
+|---------|-------------|
 | `/pre-pr` | Runs the complete pre-PR checklist |
 | `/run-uat` | Executes UAT scenarios |
+
+**Development:**
+
+| Command | What It Does |
+|---------|-------------|
+| `/plan` | Invoke planner agent for implementation planning |
+| `/build-fix` | Incrementally fix build/lint/type errors |
+| `/tdd` | Enforce test-driven development cycle |
 | `/generate-prd` | Generates a PRD with Mermaid diagrams |
 | `/generate-uat` | Generates UAT scenarios from codebase |
 | `/optimize-claude-md` | Proposes splitting an oversized CLAUDE.md |
 
+**Session:**
+
+| Command | What It Does |
+|---------|-------------|
+| `/save-session` | Save work context for later resumption |
+| `/resume-session` | Load saved session and continue where you left off |
+
 ## Install
 
 ```bash

package/bin/devforge.js

@@ -1,4 +1,14 @@
 #!/usr/bin/env node
 import { parseCommand } from '../src/cli.js';
 
-parseCommand(process.argv.slice(2));
+try {
+  await parseCommand(process.argv.slice(2));
+} catch (err) {
+  // Graceful exit on Ctrl+C / prompt cancellation
+  if (err?.name === 'ExitPromptError' || err?.code === 'ERR_USE_AFTER_CLOSE') {
+    console.log('');
+    process.exit(0);
+  }
+  console.error(`\x1b[31mError: ${err.message || err}\x1b[0m`);
+  process.exit(1);
+}

package/docs/00-README.md

@@ -0,0 +1,310 @@
+# Claude Code Mastery Kit
+## README — How to Use These Documents
+
+---
+
+## What Is This?
+
+A complete system for getting production-grade code out of Claude Code (and any
+AI coding agent) without the back-and-forth, regressions, and "are you sure?"
+cycles that waste time and tokens.
+
+It works in **Claude Code CLI**, **VS Code** (official extension), **Cursor**,
+and **Windsurf** — anywhere Claude Code runs.
+
+---
+
+## Documents in This Kit
+
+| # | Document | Universal? | Purpose |
+|---|----------|-----------|---------|
+| 1 | `universal-prompt-library.md` | ✅ YES | Every prompt you need from idea to production — 6 flows, utility prompts, Mermaid workflow diagram |
+| 2 | `multi-agent-verification.md` | ⚠️ TEMPLATE | 5 specialized read-only agents that check each other's work — needs customization per project |
+| 3 | `claude-code-mastery-playbook.md` | ⚠️ TEMPLATE | How to structure CLAUDE.md, hooks, skills, and directory scoping — needs customization per project |
+| 4 | `errata-and-verification-checklist.md` | ✅ YES | Known issues, corrections, and step-by-step testing checklist |
+| 5 | This file (`README.md`) | ✅ YES | How to use everything |
+
+**✅ Universal** = use as-is on any project, any stack, any team size.
+**⚠️ Template** = the architecture and patterns are universal, but the specific
+checklists, hook commands, and agent rules contain example content (marked with
+`[CUSTOMIZE]` tags) that you replace with your project's actual commands,
+patterns, and rules.
+
+---
+
+## Quick Start (5 Minutes)
+
+### If you're starting a NEW project:
+
+1. Open `universal-prompt-library.md`
+2. Go to **Flow 1: NEW PROJECT**
+3. Copy-paste Step 1.1 into Claude Code with your idea
+4. Follow each step in sequence
+
+### If you're adding a feature to an EXISTING project:
+
+1. Open `universal-prompt-library.md`
+2. Go to **Flow 2: NEW FEATURE**
+3. Start at Step 2.1
+
+### If you're fixing a bug:
+
+1. **Flow 3: BUG FIX** — start at Step 3.1
+
+### If you're joining someone else's project:
+
+1. **Flow 5: PROJECT ONBOARDING** — start at Step 5.1
+
+### If you want the full infrastructure (hooks, agents, skills):
+
+1. Read `errata-and-verification-checklist.md` FIRST (known issues)
+2. Follow the 2-week rollout plan at the bottom of that document
+3. Use `claude-code-mastery-playbook.md` as your architecture guide
+4. Use `multi-agent-verification.md` to set up your review agents
+
+---
+
+## How Each Document Fits Together
+
+```
+┌─────────────────────────────────────────────────┐
+│  universal-prompt-library.md                     │
+│  Your daily driver. Open this every session.     │
+│  Contains: every prompt for every situation.     │
+│                                                  │
+│  Flow 1: New Project                             │
+│  Flow 2: New Feature ←── most used               │
+│  Flow 3: Bug Fix                                 │
+│  Flow 4: Cleanup / Refactor                      │
+│  Flow 5: Join Existing Project                   │
+│  Flow 6: Audit / Validate                        │
+│  + Utility prompts (lost? pre-PR? explain code?) │
+└───────────────────┬─────────────────────────────┘
+                    │
+                    │ Step 1.4 of Flow 1 says
+                    │ "set up hooks, skills, agents"
+                    ▼
+┌─────────────────────────────────────────────────┐
+│  claude-code-mastery-playbook.md                 │
+│  Your architecture guide. Read once, set up,     │
+│  then reference when tweaking.                   │
+│                                                  │
+│  - How to structure CLAUDE.md (lean, ~150 lines) │
+│  - How to create Skills (on-demand knowledge)    │
+│  - How to create Hooks (deterministic gates)     │
+│  - How to scope CLAUDE.md per directory           │
+│  - AI prompt quality standards                   │
+│  - Frontend/backend separation patterns          │
+└───────────────────┬─────────────────────────────┘
+                    │
+                    │ Playbook references agents
+                    │ for verification
+                    ▼
+┌─────────────────────────────────────────────────┐
+│  multi-agent-verification.md                     │
+│  Your review team. Set up once, use on demand.   │
+│                                                  │
+│  5 read-only agents:                             │
+│  1. Code Quality Reviewer                        │
+│  2. Security Reviewer                            │
+│  3. Spec Compliance Validator                    │
+│  4. AI Output Quality Auditor                    │
+│  5. Production Readiness Checker                 │
+│                                                  │
+│  + How to chain them (sequential or parallel)    │
+│  + Claude Code Review (managed PR reviews)       │
+└───────────────────┬─────────────────────────────┘
+                    │
+                    │ Before trusting ANY of this
+                    ▼
+┌─────────────────────────────────────────────────┐
+│  errata-and-verification-checklist.md            │
+│  Read this BEFORE implementing hooks or agents.  │
+│                                                  │
+│  - Known errors and corrections                  │
+│  - Step-by-step testing for each component       │
+│  - 2-week rollout plan                           │
+│  - What needs YOUR customization                 │
+└─────────────────────────────────────────────────┘
+```
+
+---
+
+## Customization Guide (Making Templates Work for Your Project)
+
+### Step 1: Customize the Playbook
+
+Open `claude-code-mastery-playbook.md` and replace:
+
+| Find | Replace With |
+|------|-------------|
+| Example lint commands (`npx eslint`, `ruff check`, etc.) | Your project's actual lint commands |
+| Example type check commands (`npx tsc --noEmit`, `npx pyright`) | Your project's actual type check commands |
+| Example test commands (`npx vitest run`, `npm run e2e`) | Your project's actual test commands |
+| Example tech stack references | Your actual tech stack |
+| Example skill names and content | Skills relevant to your project's domain |
+| Protected file patterns (`.env`, `migrations/`) | Your project's actual protected paths |
+
+### Step 2: Customize the Agents
+
+Open `multi-agent-verification.md` and for each agent:
+
+| Agent | What to Customize |
+|-------|-------------------|
+| Code Quality Reviewer | Your language-specific patterns, naming conventions, architecture rules |
+| Security Reviewer | Your auth middleware names, input sanitization helpers, security patterns |
+| Spec Validator | Your spec file locations and format |
+| AI Quality Auditor | Your AI service file paths, prompt patterns, and quality standards |
+| Production Readiness | Your deployment platform, env var conventions, infrastructure patterns |
+
+**If your project doesn't use AI features**, you can skip the AI Quality Auditor agent entirely.
+
+**If your project is frontend-only**, simplify the Security Reviewer to focus
+on XSS, CSRF, and client-side storage patterns instead of backend auth.
+
+### Step 3: Create Your Hooks
+
+The hook scripts need your project's actual commands. Use the templates in the
+playbook as a starting point, but test each one manually before relying on it.
+See the errata document for the step-by-step testing process.
+
+---
+
+## For Teams: How to Share This
+
+### Option A: Drop into your repo (recommended)
+
+```
+your-project/
+├── .claude/
+│   ├── settings.json          # Hooks config
+│   ├── hooks/                 # Hook scripts
+│   │   ├── protect-files.sh
+│   │   ├── post-edit.sh
+│   │   └── stop-quality-gate.sh
+│   ├── agents/                # Subagent definitions
+│   │   ├── code-quality-reviewer.md
+│   │   ├── security-reviewer.md
+│   │   ├── spec-validator.md
+│   │   └── production-readiness.md
+│   ├── skills/                # On-demand knowledge
+│   │   ├── testing/SKILL.md
+│   │   ├── frontend/SKILL.md
+│   │   ├── backend/SKILL.md
+│   │   └── security/SKILL.md
+│   └── commands/              # Slash commands
+│       ├── verify-all.md
+│       ├── audit-spec.md
+│       ├── audit-wiring.md
+│       └── pre-pr.md
+├── CLAUDE.md                  # Root project rules (~150 lines)
+├── backend/CLAUDE.md          # Backend-scoped rules
+├── src/CLAUDE.md              # Frontend-scoped rules (or frontend/)
+├── e2e/CLAUDE.md              # Test-scoped rules (or tests/)
+└── docs/
+    ├── prompt-library.md      # This kit's universal prompt library
+    └── plans/                 # Feature plans written during Plan Mode
+```
+
+Commit everything except `settings.local.json` (personal overrides, gitignored).
+
+Every developer on the team gets the same hooks, agents, skills, and commands
+automatically. When someone runs Claude Code in this repo, they get the full
+infrastructure.
+
+### Option B: Global setup (for personal use across all projects)
+
+```
+~/.claude/
+├── CLAUDE.md              # Your personal global rules
+├── settings.json          # Global hooks (protect .env everywhere)
+├── agents/                # Agents available in all projects
+│   └── code-quality-reviewer.md
+└── skills/                # Skills available in all projects
+```
+
+Project-level files override global files when both exist.
+
+### Option C: Share as a template repo
+
+Create a GitHub template repository with the full `.claude/` structure.
+When starting a new project: "Use this template" → customize for the
+specific project.
+
+---
+
+## FAQ
+
+### Does this work in VS Code?
+
+Yes. The official Claude Code VS Code extension reads the same `.claude/`
+directory, CLAUDE.md files, hooks, skills, agents, and commands as the CLI.
+Install from the VS Code marketplace (search "Claude Code" by Anthropic).
+
+### Does this work in Cursor / Windsurf?
+
+Yes for CLAUDE.md and hooks. Subagents and skills are Claude Code-specific
+features — they work in Cursor/Windsurf only through the Claude Code extension,
+not through those editors' native AI features.
+
+### Do I need a Team or Enterprise plan?
+
+No. Hooks, subagents, skills, commands, and directory-scoped CLAUDE.md all
+work on Pro and Max plans. Claude Code Review (the managed PR reviewer) requires
+Team or Enterprise.
+
+### How much does the agent chain cost in tokens?
+
+Running all 5 review agents sequentially costs roughly 50-80K tokens total.
+On a Max plan with 5x usage, that's fine for every feature. On a Pro plan,
+you might want to run agents only before PRs, not after every task.
+
+### What if my project doesn't use Python/FastAPI?
+
+The patterns are universal — the specific commands are examples. Replace:
+- `ruff check` → your linter (e.g., `cargo clippy`, `go vet`, `rubocop`)
+- `npx pyright` → your type checker (e.g., `mypy`, `cargo check`)
+- `npx tsc --noEmit` → whatever applies to your frontend
+- Security agent checklist → your framework's auth patterns
+
+### What if I'm a solo developer?
+
+Use the sequential agent chain (Option A in the multi-agent doc) and run it
+before PRs. Skip agent teams — they're for when you need parallel speed on
+larger changes.
+
+### Can I use this with other AI coding tools (Copilot, Aider, etc.)?
+
+The prompt library (Flow 1-6) works with any AI coding tool — they're just
+well-structured prompts. The hooks, agents, and skills are Claude Code-specific
+features. The CLAUDE.md concept has equivalents in other tools (AGENTS.md for
+OpenCode/Aider, .cursorrules for Cursor).
+
+---
+
+## What's NOT in This Kit (And Where to Find It)
+
+| Need | Where |
+|------|-------|
+| CI/CD pipeline integration | Claude Code GitHub Actions: `anthropics/claude-code-action` |
+| Managed PR reviews | Claude Code Review (Team/Enterprise): `code.claude.com/docs/en/code-review` |
+| Security scanning | Claude Code Security (Team/Enterprise): `anthropic.com/news/claude-code-security` |
+| MCP server setup | `code.claude.com/docs/en/mcp` |
+| Plugin marketplace | `/plugins` command in Claude Code |
+| Advanced multi-agent orchestration | Gas Town, Multiclaude, or Claude Code Agent Teams (experimental) |
+
+---
+
+## Contributing / Improving This Kit
+
+These documents are living — they should evolve as Claude Code evolves and as
+you discover what works for your projects.
+
+**After every project:** Ask yourself:
+- Did any prompt consistently need tweaking? → Update the prompt library.
+- Did any hook fail or need adjustment? → Update the hook and errata.
+- Did an agent miss something important? → Add it to the agent's checklist.
+- Did a new pattern emerge? → Add it as a skill.
+
+**Version your `.claude/` directory** the same way you version your code.
+Review it in PRs. It compounds in value over time.