forge

An opinionated .claude harness for prototype-driven AI development

Source: github.com/lps-ai/forge · Changelog: CHANGELOG.md · License: MIT

⚠️ Experimental — early access. This npm package is still experimental and needs a lot of adjustment. It was published to npm for convenience (so npx @jamie-tam/forge init works), but forge is not feature-complete and not well-tested yet. Expect breaking changes between versions, rough edges, half-finished commands, and gaps that dogfooding hasn't surfaced. Names, command surfaces, manifest schemas, and skill boundaries are all still in motion. If you try it: pin a version, expect to update often, and please file issues at github.com/lps-ai/forge/issues — every real-world signal helps stabilize the next release.

What is this?

forge is a complete .claude folder that turns Claude Code into a structured development workflow engine. It covers the path from idea to production via a prototype-driven SDLC (concept slides → wireframe → working prototype → codify → production build → deliver), with quality gates positioned where they're designed to catch real bugs — at the prototype-to-production transition. Install it into a Claude Code project to adopt the workflow on day one; expect to customize, since forge is opinionated by default and everything is markdown you can edit.

Release history: see CHANGELOG.md.

Who this is for

• Solo developers or small teams using Claude Code as a primary development surface, who want a structured workflow + quality gates instead of ad-hoc prompts.
• Projects where iteration speed matters more than ceremonial completeness — the prototype-driven SDLC collapses or skips phases on trivial work.
• Codebases that benefit from a captured knowledge layer (aiwiki/ typed pages — decisions, gotchas, conventions, architecture, sessions) compounding over time.
• Teams comfortable editing markdown rules, skills, and commands. Forge is opinionated by default; the entire surface is yours to tune.

Who this is NOT for

• Users who prefer lightweight prompt engineering over a structured harness. Forge is opinionated and writes substantial state to .forge/ and aiwiki/; that overhead pays off only when you embrace the workflow.
• Teams already running an established process harness. Forge overlaps with that surface rather than slotting in alongside.
• Throwaway scripts where the SDLC ceremony costs more than it saves.
• Agent surfaces other than Claude Code. Many concepts transfer; the commands, hooks, and work-manifest tooling don't.

Design overview

Two pillars shape forge's design:

1. Prototype-driven SDLC. Artifact-fidelity escalation (slides → wireframe → prototype → codify → production) puts iteration before code-perfection. Most phases are softened: trivial work skips them; the work manifest's phase_plan tracks deviations explicitly.
2. aiwiki/ knowledge layer. Typed pages (decisions / gotchas / conventions / architecture / sessions) with real-time LINT on every write and async dream consolidation at phase-close. Dream proposals land in aiwiki/proposed/ for user review (atomic swap on accept, discard on reject).

Work manifests carry phase_plan: at the top (see templates/manifests/v6/SCHEMA.md) — six plan-status values (active, active-light, active-commit-only, skipped, as-discovered, complete-inline) cover the patterns dogfood surfaced. Release notes are in CHANGELOG.md.

Key Features

• 31 skills spanning the prototype-driven pipeline plus quality gates at the prototype-to-production transition
• 16 commands for discovery, setup, workflows, knowledge capture, evolution, and validation
• 17 specialized agents with explicit phase-context (prototype-builder for Phase 3-4, builder for Phase 6, plus architects, reviewers, hunters, dreamers)
• 8 common rules auto-loaded every session (one — testing.md — is paths-conditional, loading only on test files and source code) + 8 common references for skill authoring, agent coordination, and workflow protocol
• Work manifests with phase_plan (preflight intent), phases (gate state), slice_graph (build decomposition), and artifacts (phase outputs + lock signals)
• aiwiki/ typed pages with LINT on every write + async dream consolidation
• Quality gates at the prototype-to-production transition where they catch real bugs, not premature plan-phase gates
• Self-learning via the gotcha system that captures lessons and promotes them to rules when patterns repeat

Installation

npx @jamie-tam/forge init

This installs everything into your project's .claude/ directory:

• Rules — 8 common rules auto-loaded every session (one is paths-conditional) + language-specific rules layered per detected stack
• Skills — 31 atomic skills covering the prototype-driven pipeline + production gates
• Commands — 16 slash commands for discovery, setup, workflows, knowledge capture, evolution, and validation
• Agents — 17 specialized subagents with MCP server access (context7, playwright)
• Hooks — gate-enforcer, wiki-lint, telemetry, state preservation, session checkpoints
• CLAUDE.md — project configuration template
• aiwiki/ scaffold — typed-page schemas, LINT config, usage rules (populated on first work item)

Update

npx @jamie-tam/forge update           # sync to latest version
npx @jamie-tam/forge update --dry-run # preview what would change

Syncs forge assets to the latest version. Detects user-modified files and warns before overwriting. Cleans stale files from previous versions. CLAUDE.md is always preserved.

Uninstall

npx @jamie-tam/forge uninstall           # remove forge, keep user files + state
npx @jamie-tam/forge uninstall --force   # also remove CLAUDE.md and AGENTS.md
npx @jamie-tam/forge uninstall --purge   # also remove .forge/ state directory
npx @jamie-tam/forge uninstall --dry-run # preview what would be removed

Only removes forge-managed files — your custom skills, agents, and rules are preserved. Uses the installed file manifest for precise removal.

After Installation

# In Claude Code, run /setup to detect your stack and fill .claude/CLAUDE.md
/setup

# Then start building
/feature "add user authentication"

For AI Agents

If you are an LLM agent (Claude Code, Cursor, Windsurf, etc.) helping a user set up, update, or remove forge, follow these instructions.

Install

npx @jamie-tam/forge init

• Run from the root of the user's project directory.
• Requires Node.js 18+. Verify with node --version before running.
• After install, verify .claude/ directory exists and contains rules/, skills/, commands/, agents/.
• Then run the /setup slash command to detect the project stack and fill .claude/CLAUDE.md.

Update

npx @jamie-tam/forge update --dry-run   # preview first
npx @jamie-tam/forge update             # apply

• Always run --dry-run first and show the user what will change.
• User-modified files are preserved automatically. If --force is passed, all files are overwritten.
• CLAUDE.md is never overwritten.

Uninstall

npx @jamie-tam/forge uninstall --dry-run   # preview first
npx @jamie-tam/forge uninstall             # apply

• Always run --dry-run first and confirm with the user before removing.
• Default uninstall only removes forge-managed files. User-created skills, agents, and rules are preserved.
• --force also removes CLAUDE.md and AGENTS.md. --purge also removes .forge/ state. Only use these if the user explicitly asks.

Prerequisites

• Claude Code — Required. Get started
• Node.js 18+ — Required for npx @jamie-tam/forge init

Recommended Tools (Optional)

Forge detects these tools automatically and offers integration when available. Without them, forge works exactly the same — they add capabilities, not requirements.

| Tool | What It Adds | Install | |------|-------------|---------| | OpenAI Codex | Adversarial review across 10 skills (code review, security audit, architecture verification) plus an alternative TDD builder | Codex plugin for Claude Code | | Graphify | Knowledge graph for codebase navigation across 5 skills, up to 283x token reduction on large repos, feeds into Codex for maximum gap detection | pip install graphifyy (open source) |

Codex: When detected, forge offers Codex review at quality gates and planning reviews — either Claude does the work and Codex verifies it, or Codex takes over while Claude reviews. You choose per-feature whether to use it (always, ask each time, or never). Codex excels at gap detection — finding unused code, mismatched limits, and authorization inconsistencies. See protocols/codex.md.

Graphify: When graphify-out/graph.json exists in your project, forge automatically enriches codebase analysis with community structure, god nodes, and dependency edges. If the graphify CLI is also installed, skills use targeted graph queries during security audits, code reviews, and debugging. Graph context feeds into Codex for the highest-impact combination. See protocols/graphify.md.

Architecture

Commands (workflows)          Skills (prefix-grouped)              Rules (auto-loaded)
---------------------         -----------------------              -------------------
/discover   (discovery)       concept-slides     [Phase 1]         common/forge-system
/setup                        build-wireframe    [Phase 2]         common/security
/feature                      build-prototype    [Phase 3]         common/guardrails
/greenfield                   iterate-prototype  [Phase 4]         common/verification
/bugfix                       harden             [Phase 5]         common/skill-selection
/refactor                     build-scaffold                       common/quality-gates
/hotfix                       build-tdd          [Phase 6]         common/git-workflow
/note       (capture)         build-pr-workflow                    common/testing (paths-conditional)
/dream      (capture)         quality-code-review
/wrap       (capture)         quality-test-plan
/parallel   (parallel)        quality-test-execution               References (load on demand)
/status                       quality-security-audit               ----------------------------
/resume                       quality-uiux                         common/
/forge-evolve                 deliver-deploy     [Phase 7]             agent-coordination
/validate                     deliver-db-migration                     io-protocol
/triage     (escape hatch)    deliver-onboarding                       skill-authoring
Work Manifests                discover-requirements                    skill-compliance
-------------------           discover-codebase-analysis               phases (canonical vocab)
.forge/work/                  plan-brainstorm                          coding-standards
  {type}/                     plan-architecture                        quality-gates
    {name}/                   plan-design-system                       feature-tracking
      manifest.yaml           plan-task-decompose                    typescript/  python/  react/
        schema_version: "6"   support-system-guide                     [extensible]
        phase_plan: {…}       support-debug
        phases: {…}           support-gotcha                         Protocols (read on demand)
        slice_graph: {…}      support-wiki-lint                      --------------------------
        artifacts: {…}        support-wiki-bootstrap                   protocols/codex.md
                              support-dream                            protocols/graphify.md
aiwiki/ (knowledge layer)     support-parallel
-------------------------     support-runtime-reachability           Hooks
  decisions/                  support-skill-validator                ------
  gotchas/                                                             gate-enforcer
  conventions/                                                         wiki-lint
  architecture/                                                        session-start / pre-compact
  sessions/  (per-session)                                             telemetry
  raw/  (free-form notes)
  oracles/ (prototype contracts)
  proposed/  (dream queue)
  schemas/
  CLAUDE.md  (usage rules)

Commands Overview

| Command | Description | When to Use | |---------|-------------|-------------| | /discover | One-screen orientation -- installed capabilities, active work, suggested next | Run this first if you're new, or any time you want an overview | | /setup | Detect project stack, install matching language rules, and fill the project profile | Right after npx @jamie-tam/forge init | | /feature | Feature workflow — lightweight by default (production-build → tests → review → PR); extended phases (concept / wireframe / prototype / codify) are opt-in at preflight | Adding a feature to an existing codebase | | /greenfield | New project from zero -- includes scaffolding and onboarding docs | Starting a brand-new project | | /bugfix | Systematic debug, TDD fix, code review, and PR | Something is broken and needs fixing | | /refactor | Analyze, plan approach, restructure with tests, PR | Code needs cleanup without new functionality | | /hotfix | Emergency compressed flow -- debug, minimal test, deploy | Production is down, need a fix now | | /note | Append an ad-hoc research note or brainstorm to aiwiki/raw/{date}.md | Phase 1-2 research, half-formed thoughts, anything that doesn't yet fit a typed page | | /dream | Manually trigger aiwiki consolidation (merge duplicates, promote raw → typed, prune stale) | After a refactor, branch merge, or whenever aiwiki/ feels noisy. Auto-fires at phase-close + PreCompact too. | | /wrap | Capture & finalize the current Claude session — fills aiwiki/sessions/{date}-{id}.md with Files touched / Decisions / Gotchas / Open questions / Next steps | At the natural end of a working session, before a long break, or before switching focus mid-day. Next session-start hook reads it. | | /parallel | Dispatch parallel agents for a punch list of ad-hoc tasks; lightweight by default (one worker per low-risk task), full crew on !max / production manifest / high-risk task types | Multiple independent small tasks to crunch in one pass | | /status | List in-flight .forge/work items and their current phase | Check what's open before starting new work | | /resume | Continue a paused work item from its current phase | Pick up a .forge/work item left mid-flow | | /forge-evolve | Review gotchas, improve skills, validate changes | Improving the system itself after a project cycle | | /validate | Run 5 consistency checks across all skills, rules, and commands | After customizing skills or running /forge-evolve | | /triage | Escape hatch for prompts that don't fit a standard workflow — classify, then route to rules-only, /feature (lightweight default), or document-gap-for-/forge-evolve | Research questions, monitoring playbooks, ad-hoc exploration, "explain this codebase," debug-without-fix |

Skills Overview

Prototype-driven SDLC (Phases 1-5)

| Skill | Phase | Description | |-------|-------|-------------| | concept-slides | 1 | Low-fidelity marp slide deck capturing the product idea (hook, sub-concepts, journey, deferrals) | | build-wireframe | 2 | Single-HTML annotated wireframe with click-through demo and callouts; backend-heavy products get a verification-UI sketch | | build-prototype | 3 | Stack-aware prototype scaffold with parallel partition builders. Stack variants: vite-react (default), nextjs, existing-repo, python-fastapi, cli, go-service, none — selected per work item via artifacts.prototype.stack: | | iterate-prototype | 4 | Polish loop with feedback file + 5-cycle drift checks; captures gotchas + conventions as side effects | | harden | 5 | Codifies the locked prototype into architecture files + ADRs (adversarial objections surfaced inline in each ADR review: block) + slice graph + tasks |

Discover & Plan (fallback for non-prototype work)

| Skill | Description | |-------|-------------| | discover-requirements | Transform raw input (meetings, emails, screenshots) into structured requirements | | discover-codebase-analysis | Map existing code patterns, dependencies, and conventions before making changes | | plan-brainstorm | Explore 2-3 approaches with tradeoffs, reach user-approved decision (non-prototype fallback) | | plan-architecture | Generate API contracts, DB schemas, system diagrams (non-prototype fallback) | | plan-task-decompose | Break work into 2-5 minute implementable tasks with dependency mapping | | plan-design-system | Establish visual direction (theme, colors, spacing, typography, component specs) — independent of prototype path |

Build (Phase 6 — production)

| Skill | Description | |-------|-------------| | build-scaffold | Set up new project structure, tooling, Docker, and initial tests | | build-tdd | Strict RED-GREEN-REFACTOR cycle — no production code without a failing test. Dispatches builder agent or runs inline | | build-pr-workflow | Git worktree management, atomic PR-per-function, manifest linking |

Quality (gates at the prototype-to-production transition)

| Skill | Description | |-------|-------------| | quality-code-review | Multi-stage review chain: safety → craft → runtime reachability → gotcha-hunter (→ optional Codex adversarial) | | quality-test-plan | Generate comprehensive test strategy: unit, integration, E2E, smoke, load, contract | | quality-test-execution | Execute ALL tests from the plan — no skipping any type or scenario | | quality-security-audit | OWASP Top 10, secrets scanning, dependency vulnerabilities, Codex + graphify integration | | quality-uiux | Accessibility, responsive design, component reuse, library recommendations |

Deliver (Phase 7)

| Skill | Description | |-------|-------------| | deliver-deploy | Pre-deploy verification, staging smoke tests, deploy, post-deploy verification | | deliver-db-migration | Safe migration with rollback scripts and forward+rollback+forward testing | | deliver-onboarding | Generate getting-started guide, architecture overview, testing guide, common tasks |

Support (cross-cutting)

| Skill | Description | |-------|-------------| | support-system-guide | Meta-skill: guides which command/skill to use, manages .forge/ + aiwiki/ directories | | support-debug | Systematic 4-phase debugging with 3-fix threshold and fact-checking | | support-gotcha | Self-learning from mistakes — captures lessons to aiwiki/gotchas/, auto-promotes after N=3 occurrences | | support-wiki-lint | Validates aiwiki/ page schemas + citations on every write (hook-driven); backfills @<sha7> citation hashes | | support-wiki-bootstrap | Scaffold aiwiki/ (typed-page subdirs, schemas, CLAUDE.md, INDEX) once before workflows write to it | | support-dream | Async wiki consolidation (merge/promote/prune) at phase-close / pre-compact / manual. Writes to aiwiki/proposed/ for user review | | support-parallel | Run parallel agents for a user-supplied punch list; phase-aware crew sizing, command-routing for command-shaped items | | support-runtime-reachability | Detects orphaned exports (code with no production caller) — the gate that catches "tests pass but feature isn't wired up" | | support-skill-validator | Validate skill consistency: conflicts, I/O gaps, overlaps, gate coverage, drift |

How It Works

/feature is lightweight by default. Most invocations skip the prototype-driven phases entirely and run production-build → tests → review → PR. Extended phases (concept / wireframe / prototype / codify) are opt-in at the preflight question — pick them when the work genuinely needs them.

Lightweight default — /feature "add an /api/health endpoint"

User: /feature "add an /api/health endpoint"
  |
  +-- Preflight 0a: Repo-state detection
  |     Prototype mode? → offer redirect to iterate-prototype
  |     Production mode? → proceed
  +-- Preflight 0b: Trivial-pattern check (single-pattern phrases, single-file scope)
  |     If trivial signal fires → offer single-confirmation deep fast path
  |     (skips Steps 0c, 1–6 entirely; straight to worktree + build + tests + review + PR)
  +-- Preflight 0c: Lightweight-vs-extended question (the default decision)
  |     "Does this work need concept slides / wireframe / prototype / codify?"
  |     User: Enter (lightweight default)
  +-- Preflight 0d: aiwiki/ scaffold if missing
  +-- Step 1: Manifest created with phase_plan:
  |     concept, wireframe, prototype, iterate, codify, plan-design-system,
  |     discover-codebase, uiux-review: skipped
  |     production-build, test-plan, code-review-final, deliver, gotchas: active
  |
  +-- Step 7: [build-pr-workflow] worktree
  +-- Step 8: Single-slice production build (no slice graph — codify was skipped):
  |     [build-tdd] strict RED-GREEN-REFACTOR
  |     [quality-code-review] safety → craft → runtime-reach → gotcha-hunter
  |     [support-runtime-reachability] orphan-export gate
  |   === GATE: build + review pass ===
  |
  +-- Step 9: [quality-test-plan] + [quality-test-execution]
  +-- Step 10: [quality-code-review] final pass across full diff
  +-- Step 11: [build-pr-workflow] create PR
  +-- Step 13: [support-gotcha] retrospective (active by default, even on lightweight)

Extended flow — /feature "add user authentication" with cwpk

When the user opts in to all four extended phases at the preflight question:

User: /feature "add user authentication"
  +-- Preflight 0c: User picks `cwpk` (concept + wireframe + prototype + codify)
  +-- Step 1: Manifest created with all picked phases active + stack selection
  |
  +-- Phase 1: [concept-slides]      — mini deck (1-3 slides)
  |   === GATE: concept locked → artifacts.concept.locked_at ===
  +-- Phase 2: [build-wireframe]     — mini-wireframe for auth screens
  |   === GATE: wireframe locked ===
  +-- Phase 4.5: [plan-design-system] (auto-enabled by `w`/`p`)
  +-- Phase 3-4: [build-prototype] + [iterate-prototype]
  |     Capture gotchas + conventions to aiwiki/
  |   === GATE: prototype locked ===
  +-- Phase 5: [harden] — codify → aiwiki/architecture/, ADRs (adversarial review
  |     on auth/PII surfaces), slice graph in manifest
  |   === GATE: codify locked + user approves dream proposal ===
  +-- Phase 6: per-slice from slice graph (build-tdd → code-review → runtime-reach)
  +-- Steps 9–13: tests / UI-UX / final review / PR / onboarding / gotcha retrospective

The manifest tracks plan, gate state, slice graph (extended-flow only), and phase artifacts (with locked_at timestamps acting as lock signals). Wiki-lint fires on every aiwiki/ write. Dream runs async at phase-close and pre-compact, writing proposals to aiwiki/proposed/ for user review. If a session ends mid-feature, re-running /feature "<same name>" resumes from exactly where you left off — phases with artifacts.{phase}.locked_at set are skipped on resume.

The lightweight default is the assumption, not a one-way door. If the build reveals genuinely new multi-screen flows or unsettled UX, the affected phases can be re-opened mid-flight (change phase_plan.{phase} from skipped to active).

Comparison to Alternatives

forge synthesizes the best patterns from four leading Claude Code configuration repos. For a detailed feature-by-feature comparison, see docs/COMPARISON.md.

Provenance

Every skill in forge has a documented origin -- what it was inspired by, what was adapted, and what is entirely new. See docs/PROVENANCE.md for the full provenance table.

Philosophy

Process over tools. Skills enforce workflows, not just provide advice. Every skill has a defined process with concrete steps, not vague guidance.

Test-first discipline. No production code without a failing test. RED-GREEN-REFACTOR is non-negotiable. Tests prove behavior, not just coverage numbers.

Self-improving. The gotcha system captures lessons from every feature, every bug, every debugging session. When patterns repeat three times, they promote to rules. The system gets better the more you use it.

Quality over speed. Quality gates enforce real criteria at every phase transition. You cannot skip from brainstorm to code without approved architecture. You cannot deploy with failing tests. The gates exist because cutting corners costs more time in the long run.

Adaptive to project. The project profile in CLAUDE.md controls how skills behave. A startup prototype gets lighter reviews and skips load testing. A mission-critical system gets full security audits and multi-pass reviews. One system, tuned to your context.

Quick Reference

For a compact cheat sheet covering all commands, workflows, and skills, see docs/CHEATSHEET.md.

Contributing

Contributions are welcome. To contribute:

1. Fork the repository
2. Create a feature branch (feat/your-improvement)
3. Make your changes
4. Run /validate to ensure skill consistency
5. Submit a pull request with a clear description of what changed and why

If you are adding a new skill, follow the I/O protocol (skills with artifact handoffs should declare Requires and Produces; pure methodology skills may omit the I/O Contract) and ensure your skill does not conflict with existing ones.

License

MIT

Credits

forge stands on the shoulders of four excellent Claude Code configuration repositories:

• gstack by Garry Tan -- The "Boil the Lake" philosophy. Role-based virtual team, security auditing (/cso), deployment pipeline (/ship), and the idea that completeness is cheap with AI. Inspired our guardrails, security audit, and deploy skills.

• superpowers by Jesse Vincent (obra) -- Test-first discipline and systematic process skills. The most rigorous TDD and debugging methodology available. Directly influenced our build-tdd, support-debug, plan-brainstorm, and code review approach.

• everything-claude-code (ECC) by Affaan Mustafa -- Battle-tested over 10+ months with 125+ skills and 28 agents. Layered rules, continuous learning via instincts, and enterprise-grade coverage. Inspired our gotcha system, onboarding skill, and layered rule architecture.

• oh-my-claudecode by Yeachan Heo -- Slash command ergonomics and composable prompt engineering. Influenced our command routing, skill invocation patterns, and the overall developer experience of the slash command system.

forge combines superpowers' process discipline, gstack's safety guardrails, ECC's layered rules, and oh-my-claudecode's slash command ergonomics -- then adds feature manifests, quality gates, I/O protocol, self-learning, and skill validation to create a reusable foundation for all projects.