claudeforge-cli 1.0.0

package/templates/.gitignore.tpl

@@ -0,0 +1,40 @@
+# ── Claude Code — personal / local files (not team-shared) ──────────────────
+.claude/settings.local.json
+CLAUDE.local.md
+
+# Claude Code — runtime artifacts
+.claude/backups/
+.claude/cache/
+.claude/debug/
+.claude/history.jsonl
+
+# ── MCP servers ──────────────────────────────────────────────────────────────
+# .mcp.json is committed (team-shared server config)
+.mcp.local.json
+
+# ── Environment & secrets ────────────────────────────────────────────────────
+.env
+.env.local
+.env.*.local
+
+# ── Memory — personal files are gitignored, project files are shared ─────────
+memory/user_profile.md
+
+# ── OS artifacts ─────────────────────────────────────────────────────────────
+.DS_Store
+Thumbs.db
+Desktop.ini
+
+# ── Node ──────────────────────────────────────────────────────────────────────
+node_modules/
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+*.log
+
+# ── Build output ──────────────────────────────────────────────────────────────
+dist/
+build/
+out/
+.next/
+.nuxt/

package/templates/CLAUDE.local.md.tpl

@@ -0,0 +1,32 @@
+# Local Claude Context
+
+> This file is **gitignored** — add personal context that should NOT be shared with the team.
+> Complement `CLAUDE.md` (team-shared) with your own preferences and local environment notes.
+
+---
+
+## My Preferences
+
+> Examples — replace with your actual preferences.
+
+- [ ] I prefer terse responses — skip trailing summaries after completing tasks
+- [ ] Always show the git diff before committing so I can review
+- [ ] Explain *why* before making architectural changes
+
+---
+
+## Local Environment
+
+> Document anything about your local setup that differs from the team default.
+
+- [ ] e.g., "Local DB runs on port 5433 (not 5432) — already in my .env"
+- [ ] e.g., "I use nvm — run `nvm use` before any node commands"
+- [ ] e.g., "Docker Desktop is aliased as `d` in my shell"
+
+---
+
+## Personal Notes
+
+> Scratch space for things you want Claude to know about your current work,
+> but that don't belong in the shared project memory.
+

package/templates/CLAUDE.md.tpl

@@ -0,0 +1,112 @@
+# [Project Name]
+
+> One-line description of what this project does.
+
+---
+
+## Commands
+
+Replace these with your project's actual commands.
+
+| Command | Description |
+|---------|-------------|
+| `npm install` | Install dependencies |
+| `npm run dev` | Start development server |
+| `npm run build` | Production build |
+| `npm test` | Run test suite |
+| `npm run lint` | Lint and type-check |
+
+---
+
+## Architecture
+
+```
+<project-root>/
+  src/          # Application source code
+  tests/        # Test files
+  .claude/      # Claude Code configuration (agents, commands, hooks, skills)
+  memory/       # Persistent project memory for Claude
+  .mcp.json     # MCP server configuration (team-shared)
+  CLAUDE.md     # This file — Claude's project context
+```
+
+> Update this tree to reflect the actual structure after scaffolding.
+
+---
+
+## Key Files
+
+| File | Purpose |
+|------|---------|
+| `CLAUDE.md` | This file — project context loaded by Claude automatically |
+| `CLAUDE.local.md` | Personal context (gitignored) |
+| `.claude/settings.json` | Claude Code permissions, model, and hooks (team-shared) |
+| `.claude/settings.local.json` | Personal Claude settings override (gitignored) |
+| `.mcp.json` | MCP server definitions (team-shared) |
+| `memory/MEMORY.md` | Index of persistent memory files |
+
+---
+
+## Code Style
+
+> Add your project's conventions here. Claude reads this before writing code.
+
+- [ ] Language and version (e.g., TypeScript 5.x, Python 3.12)
+- [ ] Formatter and rules (e.g., Prettier with 2-space indent, ESLint)
+- [ ] Naming conventions (e.g., `camelCase` functions, `PascalCase` components)
+- [ ] Import style (e.g., named exports only, no default exports)
+- [ ] Test framework and patterns (e.g., Vitest, co-located `*.test.ts`)
+
+---
+
+## Environment Variables
+
+Required variables (see `.env.example` for the full list):
+
+| Variable | Description |
+|----------|-------------|
+| `NODE_ENV` | `development` or `production` |
+
+Copy `.env.example` → `.env` and fill in values before running locally.
+
+---
+
+## Claude Workflow
+
+### Slash Commands
+
+| Command | When to use |
+|---------|------------|
+| `/commit` | After completing a feature — stages and commits with conventional message |
+| `/review-pr` | Before opening a PR — reviews the diff and flags issues |
+
+### Agents
+
+| Agent | When to use |
+|-------|------------|
+| `code-reviewer` | After implementing a feature, before creating a PR |
+
+### Memory
+
+Claude maintains persistent memory in `memory/`. Tell Claude to "remember" facts
+and it will update the appropriate file. These persist across sessions.
+
+---
+
+## Gotchas
+
+> Non-obvious things that cause issues. Add them as you discover them.
+
+- [ ] Add known pitfalls here
+- [ ] e.g., "Service X requires VPN — requests silently fail without it"
+- [ ] e.g., "Always run migrations before starting the dev server"
+
+---
+
+## Resources
+
+> Links to internal docs, design docs, runbooks, etc.
+
+- [ ] Architecture decision records (ADRs)
+- [ ] API documentation
+- [ ] Deployment runbook

package/templates/claude/README.md.tpl

@@ -0,0 +1,94 @@
+# .claude/ — Claude Code Configuration
+
+This directory configures Claude Code for this project.
+It is **team-shared** (committed to git), except for `settings.local.json`.
+
+---
+
+## Directory Structure
+
+| Path | Purpose |
+|------|---------|
+| `settings.json` | Team settings: model, permissions, hooks |
+| `settings.local.json` | Personal overrides — **gitignored, never commit** |
+| `agents/` | Sub-agent definitions (`.md` files invoked via the Agent tool) |
+| `commands/` | Slash command scripts — invoke with `/command-name` in Claude Code |
+| `hooks/` | Shell scripts run automatically on tool events (PreToolUse, PostToolUse) |
+| `rules/` | Reusable rule files referenced by agents or hooks |
+| `skills/` | Skill definitions — each skill is a subdirectory containing `SKILL.md` |
+
+---
+
+## Settings Priority
+
+Claude Code merges settings in this order (later wins):
+
+1. **Global** — `~/.claude/settings.json`
+2. **Project shared** — `.claude/settings.json` ← this file
+3. **Project local** — `.claude/settings.local.json` ← personal overrides (gitignored)
+
+---
+
+## Adding Slash Commands
+
+Create a `.md` file in `commands/` with optional YAML frontmatter:
+
+```markdown
+---
+description: What this command does (shown in the command palette)
+allowed-tools: Bash(git:*), Read, Edit
+---
+
+Instructions for Claude when this command is invoked...
+```
+
+Invoke with `/command-name` in the Claude Code chat.
+
+---
+
+## Adding Sub-Agents
+
+Create a `.md` file in `agents/` with YAML frontmatter:
+
+```markdown
+---
+name: my-agent
+description: When Claude should use this agent and what it does — be specific
+model: sonnet
+color: blue
+---
+
+Agent system prompt here...
+```
+
+Claude will automatically invoke agents when their description matches the task.
+
+---
+
+## Adding Skills
+
+Create `skills/<skill-name>/SKILL.md` with frontmatter:
+
+```markdown
+---
+name: skill-name
+description: Specific trigger condition — when should Claude invoke this skill?
+user-invocable: true
+---
+
+Skill instructions...
+```
+
+---
+
+## Hook Scripts
+
+Hook scripts in `hooks/` receive a JSON blob on `stdin` describing the tool event
+and can output JSON to `stdout` to influence Claude's behavior:
+
+- `{"decision": "block", "reason": "..."}` — prevents the tool from running
+- `{"decision": "warn", "reason": "..."}` — shows a warning but allows the tool
+- `{"systemMessage": "..."}` — injects a message into Claude's context (PostToolUse)
+- Empty output — allows the tool to proceed normally
+
+See [Claude Code Hooks documentation](https://docs.anthropic.com/en/docs/claude-code/hooks) for the full schema.

package/templates/claude/agents/code-reviewer.md.tpl

@@ -0,0 +1,142 @@
+---
+name: code-reviewer
+description: Use this agent to review recently written or modified code. Invoke proactively after implementing any feature, fixing a bug, or before opening a pull request. Pass specific files to review, or it defaults to all unstaged changes. The agent checks correctness, security, performance, test coverage, style, and documentation — and gives actionable fixes, not just observations.
+model: sonnet
+color: green
+---
+
+You are a senior code reviewer. Your job is to catch real problems before they reach production. You review code the way a staff engineer at a high-quality team would: methodically, specifically, and without ego.
+
+## Default Scope
+
+Review `git diff HEAD` (all unstaged changes) unless the caller specifies particular files, a commit range, or a PR branch.
+
+---
+
+## Review Process
+
+**Step 1 — Orient yourself**
+Before reviewing, read:
+1. `CLAUDE.md` — project conventions, stack, style rules
+2. The surrounding context of each changed file (not just the diff)
+3. Any test files related to the changed code
+
+**Step 2 — Check each category below**
+Work through every category systematically. Do not skip categories even if the change looks small.
+
+**Step 3 — Report findings**
+Use the output format below. Every issue must have a file, line, and a concrete fix — not just an observation.
+
+---
+
+## Category 1 — Correctness
+
+- [ ] Does the logic match the intended behavior? Trace the happy path manually.
+- [ ] Are all edge cases handled? (empty input, null/nil/None, zero, negative numbers, empty arrays/maps)
+- [ ] Off-by-one errors in loops, slices, pagination, or index arithmetic
+- [ ] Incorrect operator precedence or boolean logic (`&&` vs `||`, `==` vs `===`)
+- [ ] Mutation of shared state that should be immutable
+- [ ] Incorrect handling of async/concurrent operations (missing await, race conditions)
+- [ ] Wrong return type or missing return in a code path
+- [ ] Shadowed variables or unintended variable reuse
+
+## Category 2 — Security
+
+- [ ] Hardcoded secrets, API keys, tokens, or passwords in any form (including base64)
+- [ ] User input passed to shell commands, SQL queries, or template engines without sanitization
+- [ ] SQL injection risk — string concatenation into queries instead of parameterized queries
+- [ ] Path traversal — user-controlled file paths not validated against a safe root
+- [ ] Insecure deserialization (pickle, eval, exec, fromCharCode patterns)
+- [ ] SSRF risk — URLs constructed from user input that hit internal services
+- [ ] Missing authentication or authorization checks on sensitive endpoints
+- [ ] Sensitive data (PII, tokens) logged to stdout or error messages
+- [ ] Dependencies with known CVEs introduced in this change
+
+## Category 3 — Error Handling & Reliability
+
+- [ ] Errors swallowed silently (`catch (_) {}`, bare `except:`, empty catch blocks)
+- [ ] Missing error propagation — callers can't know an operation failed
+- [ ] No timeout on external API calls, database queries, or network I/O
+- [ ] No retry logic for transient failures (network, database connections)
+- [ ] Resource leaks — files, connections, or handles opened but not closed in all paths
+- [ ] Panics/exceptions from nil/null dereference on values that could be absent
+- [ ] Missing circuit breaker pattern for calls to unreliable dependencies
+- [ ] Error messages that expose internal stack traces to end users
+
+## Category 4 — Performance
+
+- [ ] N+1 query problem — database query inside a loop
+- [ ] Missing database index on columns used in WHERE, JOIN, or ORDER BY clauses
+- [ ] Unnecessary data loading — fetching all columns/rows when only a subset is needed
+- [ ] Repeated computation inside a loop that could be hoisted out
+- [ ] Unbounded growth — lists/maps that accumulate without a cap or TTL
+- [ ] Synchronous blocking call on a hot path that could be async
+- [ ] Large payload serialized/deserialized unnecessarily
+- [ ] O(n²) algorithm where O(n log n) or O(n) exists for the problem size
+
+## Category 5 — Test Coverage
+
+- [ ] Is the new behavior covered by at least one test?
+- [ ] Are the error paths tested, not just the happy path?
+- [ ] Are edge cases tested (empty, nil/null, boundary values)?
+- [ ] Do tests actually assert meaningful behavior, or just that the function runs?
+- [ ] Are tests isolated — do they depend on external state, timing, or each other?
+- [ ] Is there a test that would catch a regression if this code were reverted?
+- [ ] Are mocks/stubs used correctly — do they verify call arguments, not just return values?
+
+## Category 6 — Code Style & Maintainability
+
+- [ ] Does the code match the naming conventions in `CLAUDE.md` and surrounding files?
+- [ ] Functions/methods longer than ~40 lines that could be decomposed
+- [ ] Magic numbers or strings that should be named constants
+- [ ] Comments that describe *what* the code does (redundant) instead of *why*
+- [ ] Commented-out code or debug logging left in (`console.log`, `print`, `fmt.Println`)
+- [ ] Duplicate logic that violates DRY and should be extracted
+- [ ] Function/method names that are misleading or too vague (`handle`, `process`, `data`)
+- [ ] Exported/public API that's wider than necessary (could be unexported/private)
+
+## Category 7 — Documentation
+
+- [ ] Public functions/methods missing docstrings (if project convention requires them)
+- [ ] Complex or non-obvious logic with no inline explanation
+- [ ] API-facing changes not reflected in any docs, OpenAPI spec, or changelog
+- [ ] `CLAUDE.md` or `memory/` files that should be updated to reflect this change
+
+---
+
+## Output Format
+
+**Always start with the scope**: state which files and commits you reviewed.
+
+For each issue:
+
+```
+**[SEVERITY]** `path/to/file.ts:42`
+**Category**: [one of: Correctness | Security | Error Handling | Performance | Tests | Style | Documentation]
+**Issue**: [Clear, specific description of the problem]
+**Fix**: [Concrete code change or action — not "consider refactoring", but "replace X with Y"]
+```
+
+Severity levels:
+- `CRITICAL` — bug, security vulnerability, or data loss risk. Must be fixed before merge.
+- `WARNING`  — likely causes problems under real conditions. Should be fixed before merge.
+- `SUGGESTION` — improvement that would meaningfully reduce risk or improve clarity. Can be a follow-up.
+
+**End every review with a verdict:**
+
+| Verdict | Meaning |
+|---------|---------|
+| `✓ LGTM` | No issues found — ready to merge |
+| `~ LGTM with suggestions` | Only SUGGESTION-level items — safe to merge, follow-ups welcome |
+| `⚠ Address warnings` | One or more WARNING items — fix recommended before merge |
+| `✗ Needs changes` | One or more CRITICAL items — must be fixed before merge |
+
+---
+
+## Important Rules
+
+- If you find nothing wrong in a category, say "No issues found" for that category. Do not invent nitpicks.
+- Every CRITICAL and WARNING must have a concrete fix, not just a description.
+- If a fix requires reading another file you haven't seen, read it before reporting.
+- Do not comment on style issues that are consistent with the rest of the codebase — only flag inconsistencies.
+- If the change is in a test file, focus on test quality (Categories 5 and 6) rather than production code concerns.

package/templates/claude/commands/commit.md.tpl

@@ -0,0 +1,34 @@
+---
+description: Stage relevant changes and create a conventional git commit with a well-formed message
+allowed-tools: Bash(git status:*), Bash(git diff:*), Bash(git add:*), Bash(git commit:*)
+---
+
+## Context
+
+Review the current repository state before committing:
+
+- Working tree status: !`git status`
+- Full diff (staged + unstaged): !`git diff HEAD`
+- Current branch: !`git branch --show-current`
+- Recent commits (for message style reference): !`git log --oneline -10`
+
+## Task
+
+Analyze the changes above and create a single commit:
+
+1. **Stage** only the files relevant to the current change (avoid staging unrelated files)
+2. **Write a commit message** following Conventional Commits format:
+   ```
+   type(scope): short description under 72 chars
+
+   Optional body explaining WHY, not what (the diff shows the what).
+   ```
+   Valid types: `feat`, `fix`, `docs`, `style`, `refactor`, `perf`, `test`, `chore`, `ci`
+3. **Run the commit** in a single `git commit -m "..."` call
+
+## Rules
+
+- Never use `git add .` or `git add -A` — stage files by name
+- Never skip hooks with `--no-verify`
+- If the diff is empty or nothing relevant is staged, report that instead of committing
+- Subject line must be under 72 characters

package/templates/claude/commands/explain-codebase.md.tpl

@@ -0,0 +1,37 @@
+---
+description: Get a thorough explanation of how this codebase is structured and how the key parts work. Useful when onboarding to a new project. Pass a specific area to focus on, or leave empty for a full overview.
+allowed-tools: Read, Glob, Grep, Bash(ls:*), Bash(git log:*), Bash(find:*)
+---
+
+## Context
+
+- Project root: !`ls -la`
+- Source files: !`find . -type f \( -name "*.ts" -o -name "*.js" -o -name "*.py" -o -name "*.go" -o -name "*.rs" \) -not -path "*/node_modules/*" -not -path "*/.git/*" | head -40`
+- CLAUDE.md: !`cat CLAUDE.md 2>/dev/null || echo "(no CLAUDE.md)"`
+- Recent changes: !`git log --oneline -10 2>/dev/null`
+- Entry points: !`cat package.json 2>/dev/null || cat go.mod 2>/dev/null || cat pyproject.toml 2>/dev/null || echo "(no manifest found)"`
+
+**Focus area**: $ARGUMENTS
+
+## Task
+
+Produce a clear explanation of this codebase tailored to someone who needs to contribute to it.
+
+### Structure
+Start with the directory layout and what each top-level folder/file does.
+
+### How It Works
+Explain the main flow: how a request/event/input enters the system and what happens to it. Trace the path through the key files.
+
+### Key Concepts
+Explain any domain-specific patterns, abstractions, or conventions that aren't obvious from the code alone. What do you need to understand to make changes confidently?
+
+### Entry Points
+Where does execution start? What are the main files someone would edit for common tasks (adding a feature, fixing a bug, adding a test)?
+
+### What to Read First
+If someone is new and wants to understand the codebase in 30 minutes, which 3–5 files should they read and in what order?
+
+${ARGUMENTS ? `\nFocus especially on: ${ARGUMENTS}` : ''}
+
+Keep the explanation practical — oriented toward making changes, not just describing what exists.

package/templates/claude/commands/fix-issue.md.tpl

@@ -0,0 +1,43 @@
+---
+description: Investigate and fix a bug or failing test. Pass the error message, issue number, or description of the problem. Usage: /fix-issue "TypeError: cannot read property of undefined in auth.ts:42"
+allowed-tools: Read, Edit, MultiEdit, Bash(git status:*), Bash(git diff:*), Bash(npm test:*), Bash(pytest:*), Bash(go test:*), Grep, Glob
+---
+
+## Context
+
+- Working state: !`git status --short`
+- Recent changes that may have introduced the bug: !`git log --oneline -5`
+
+**Issue**: $ARGUMENTS
+
+## Task
+
+Investigate and fix the issue described above. Follow this process:
+
+### 1. Understand Before Changing
+
+- Read the error message or description carefully
+- Locate the relevant files (use Grep/Glob to find them)
+- Read the failing code and understand what it's supposed to do
+- Check git log for when this code last changed: `git log -p --follow <file>`
+- Form a hypothesis before writing any code
+
+### 2. Minimal Fix
+
+- Make the smallest change that fixes the root cause
+- Do NOT refactor surrounding code, rename variables, or "improve" things you didn't break
+- If the fix requires touching more than 3 files, pause and explain the approach first
+
+### 3. Verify
+
+After the fix:
+- Run the relevant tests to confirm the fix works
+- Check that you haven't introduced regressions in related tests
+- If no tests cover this behavior, note that a test should be added
+
+### 4. Explain
+
+Briefly explain:
+- What was wrong (root cause, not just symptom)
+- What the fix does
+- Whether a test should be added and why

package/templates/claude/commands/memory-sync.md.tpl

@@ -0,0 +1,49 @@
+---
+description: Update the memory files based on what you learned this session. Run at the end of a work session to persist context across future sessions.
+allowed-tools: Read, Write, Edit
+---
+
+## Context
+
+Read the current memory files to understand what's already recorded:
+
+- Memory index: !`cat memory/MEMORY.md 2>/dev/null || echo "(not found)"`
+- User profile: !`cat memory/user_profile.md 2>/dev/null || echo "(not found)"`
+- Communication feedback: !`cat memory/feedback_communication.md 2>/dev/null || echo "(not found)"`
+- Project workflow: !`cat memory/project_ai_workflow.md 2>/dev/null || echo "(not found)"`
+
+## Task
+
+Review this conversation and update the memory files with anything worth persisting.
+
+### What to look for:
+
+**user_profile.md** — Update if you learned:
+- The user's role, team, or background
+- Technical areas they're strong or weak in
+- Working preferences they've stated or implied
+- Communication style they prefer
+
+**feedback_communication.md** — Update if you noticed:
+- Something the user corrected ("don't do X", "stop doing Y")
+- An approach they confirmed works well ("yes, exactly", "keep doing that")
+- Response format preferences (terse vs. detailed, bullet lists vs. prose, etc.)
+- Any non-obvious preferences worth remembering
+
+**project_ai_workflow.md** — Update if you learned:
+- New agents or commands created this session
+- Project-specific conventions discovered while working
+- External systems, APIs, or tools integrated
+- Important architectural decisions made this session
+- Deadlines, freezes, or priorities with dates
+
+### Rules for updating memory:
+
+1. **Lead with the rule/fact**, then add **Why:** and **How to apply:** lines
+2. **Don't duplicate** — check if the fact is already recorded before adding
+3. **Be specific** — "user prefers terse responses" is better than "user has preferences"
+4. **Convert relative dates** to absolute dates (e.g., "Thursday" → the actual date)
+5. **Update or remove** stale entries rather than appending contradictions
+6. **Keep MEMORY.md index concise** — one line per file, under 150 chars
+
+After updating, print a brief summary of what was added or changed.

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

@@ -0,0 +1,70 @@
+---
+description: Audit the Claude Code project setup and report what's missing, incomplete, or could be improved. Run this after init to see what still needs attention.
+allowed-tools: Read, Bash(ls:*), Bash(cat:*), Bash(find:*), Glob, Grep
+---
+
+## Context
+
+Gather the current project state:
+
+- Root files: !`ls -la`
+- .claude contents: !`find .claude -type f | sort 2>/dev/null || echo "(no .claude dir)"`
+- Memory files: !`find memory -type f 2>/dev/null || echo "(no memory dir)"`
+- Settings: !`cat .claude/settings.json 2>/dev/null || echo "(no settings.json)"`
+- MCP config: !`cat .mcp.json 2>/dev/null || echo "(no .mcp.json)"`
+- CLAUDE.md: !`cat CLAUDE.md 2>/dev/null || echo "(no CLAUDE.md)"`
+- .gitignore: !`cat .gitignore 2>/dev/null || echo "(no .gitignore)"`
+- Git status: !`git status 2>/dev/null || echo "(not a git repo)"`
+
+## Task
+
+Audit the Claude Code setup and produce a **health report** with three sections:
+
+---
+
+### ✓ What's Working Well
+
+List things that are properly configured. Be specific — mention file names and what's good about them.
+
+---
+
+### ⚠ Needs Attention
+
+For each issue found, format as:
+
+**[SEVERITY]** `path/to/file`
+Issue: [what's wrong or missing]
+Fix: [concrete action to take]
+
+Check for:
+- `CLAUDE.md` — is it still the generic template? Are commands real or placeholders?
+- `.claude/settings.json` — is the model set? Are permissions appropriate for the stack?
+- `.env.example` — does it have real variables or still generic?
+- `.mcp.json` — is it just context7 or are there project-appropriate servers?
+- `memory/` files — are they still empty templates (under 200 bytes)?
+- `.claude/agents/` — are there only the defaults, or project-specific agents?
+- `.claude/commands/` — are there only the defaults, or project-specific commands?
+- `.claude/hooks/` — do the hook scripts exist and are they executable?
+- `.gitignore` — does it cover secrets, local settings, and the tech stack?
+- Missing `CLAUDE.local.md` — is the personal context file present?
+
+---
+
+### 🚀 Recommended Next Steps
+
+Ordered by impact:
+
+1. [Highest impact action]
+2. [Second action]
+3. [etc.]
+
+**Quick wins** (under 5 minutes):
+- [Action 1]
+- [Action 2]
+
+**Bigger improvements**:
+- [Description and why it matters]
+
+---
+
+End with: "Run `claudeforge status` in the terminal for a machine-readable summary."