forgedev 1.1.3 → 1.2.0

package/README.md

@@ -185,7 +185,7 @@ With Claude Code infrastructure enabled (default):
 - **UAT templates** — scenario packs and CSV checklists
 - **Prompt library** — the complete development prompt library
 
-## Agents (17)
+## Agents (18)
 
 Every scaffolded project gets these agents in `.claude/agents/`:
 
@@ -202,6 +202,7 @@ Every scaffolded project gets these agents in `.claude/agents/`:
 | `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 |

package/bin/devforge.js

@@ -9,5 +9,6 @@ try {
     console.log('');
     process.exit(0);
   }
-  throw err;
+  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.