claude-forge

install.sh symlinks everything to ~/.claude/, so git pull updates instantly.

If you find Claude Forge useful, please consider giving it a star -- it helps others discover this project.

What's New in v2.2

| Change | Description | |:-------|:------------| | Surgical Changes Principle | New 12th golden principle: only change what was requested. No drive-by refactoring, style drift, or adjacent "improvements". Inspired by Andrej Karpathy's observations on LLM coding pitfalls. | | State Assumptions Before Coding | New interaction rule: surface assumptions and present alternatives before implementing ambiguous requirements -- don't guess silently. | | Anti-Rationalization Expansion | Two new entries block common LLM excuses: "while I'm here, let me clean up" and "need abstraction for extensibility". |

| Change | Description | |:-------|:------------| | Verification Rules | New verification.md rule enforces evidence-based completion -- no claims without fresh test/build output. | | Agent Self-Evolution | Core 5 agents (planner, architect, code-reviewer, security-reviewer, tdd-guide) now record learnings in ~/.claude/agent-memory/ after each task. | | Hook Sync | Added forge-update-check.sh (session start update notification) and observe.sh (continuous learning observation). |

New here?

If you're new to development or Claude Code, start with these:

| Step | What to do | |:-----|:-----------| | 1 | Run /guide after install -- an interactive 3-minute tour | | 2 | Read First Steps -- glossary + TOP 6 commands | | 3 | Browse Workflow Recipes -- 5 copy-paste scenarios |

Or just type /auto login page and let Claude Forge handle the entire plan-to-PR pipeline for you.

🔄 Development Workflows

Real-world workflows that chain commands, agents, and skills together.

Feature Development

Build new features with a plan-first, test-first approach:

/plan → /tdd → /code-review → /handoff-verify → /commit-push-pr → /sync

graph LR
    P["/plan<br><small>Design & risk analysis</small>"] --> T["/tdd<br><small>Tests first, then code</small>"]
    T --> CR["/code-review<br><small>Quality & security check</small>"]
    CR --> HV["/handoff-verify<br><small>Fresh-context validation</small>"]
    HV --> CPR["/commit-push-pr<br><small>Commit, push, PR & merge</small>"]
    CPR --> S["/sync<br><small>Sync project docs</small>"]

    style P fill:#533483,stroke:#fff,color:#fff
    style T fill:#0f3460,stroke:#fff,color:#fff
    style CR fill:#0f3460,stroke:#fff,color:#fff
    style HV fill:#e94560,stroke:#fff,color:#fff
    style CPR fill:#1a1a2e,stroke:#fff,color:#fff
    style S fill:#16213e,stroke:#fff,color:#fff

| Step | What happens | |:-----|:-------------| | /plan | AI creates an implementation plan. Waits for your confirmation before coding. | | /tdd | Write tests first, then code. One unit of work at a time. | | /code-review | Security + quality check on the code you just wrote. | | /handoff-verify | Auto-verify build/test/lint all at once. | | /commit-push-pr | Commit, push, create PR, and optionally merge -- all in one. | | /sync | Sync project docs (prompt_plan.md, spec.md, CLAUDE.md, rules). |

Bug Fix

Fast turnaround for bug fixes with automatic retry:

/explore → /tdd → /verify-loop → /quick-commit → /sync

| Step | What happens | |:-----|:-------------| | /explore | Navigate the codebase to find where the bug lives. | | /tdd | Write a test that reproduces the bug, then fix it. | | /verify-loop | Auto-retry build/lint/test up to 3 times with auto-fix on failure. | | /quick-commit | Fast commit for simple, well-tested changes. | | /sync | Sync project docs after commit. |

Security Audit

Comprehensive security analysis combining CWE and STRIDE:

/security-review → /stride-analysis-patterns → /security-compliance

| Step | What happens | |:-----|:-------------| | /security-review | CWE Top 25 vulnerability scan + STRIDE threat modeling. | | /stride-analysis-patterns | Systematic STRIDE methodology applied to system architecture. | | /security-compliance | SOC2, ISO27001, GDPR, HIPAA compliance verification. |

Team Collaboration

Parallel multi-agent execution for complex tasks:

/orchestrate → Agent Teams (parallel work) → /commit-push-pr

| Step | What happens | |:-----|:-------------| | /orchestrate | Create an Agent Team with file-ownership separation and hub-and-spoke coordination. | | Agent Teams | Multiple agents work in parallel on frontend, backend, tests, etc. | | /commit-push-pr | Merge all work, verify, and ship. |

Why Claude Forge?

Most developers either use Claude Code with no customization or spend hours assembling individual configs. Claude Forge gives you a production-ready setup in 5 minutes.

| Feature | Claude Forge | Basic .claude/ Setup | Individual Plugins | |:--------|:------------|:-----------------------|:-------------------| | Agents | 11 pre-configured (Opus + Sonnet) | Manual setup required | Varies by plugin | | Slash Commands | 40 ready-to-use | None | Per-plugin basis | | Skill Workflows | 15 multi-step pipelines | None | Per-plugin basis | | Security | 6-layer automated hooks | None by default | Per-plugin basis | | Installation | 5 min, one command | Hours of manual config | Per-plugin install | | Updates | git pull (instant) | Manual per-file | Per-plugin update | | Workflow Integration | End-to-end pipelines (plan to PR) | Disconnected tools | Not integrated |

📦 What's Inside Claude Forge

| Category | Count | Highlights | |:--------:|:-----:|:-----------| | Agents | 11 | planner architect code-reviewer security-reviewer tdd-guide database-reviewer + 5 more | | Commands | 40 | /commit-push-pr /handoff-verify /explore /tdd