Skip to content

README.md

Latest commit

 

History

History
332 lines (241 loc) · 23.1 KB

README.md

File metadata and controls

332 lines (241 loc) · 23.1 KB
Raw

FORGE — Framework for Organized Reliable Gated Engineering

AI coding assistants lose context between sessions, drift from the original goal, and declare work done before it meets acceptance criteria. FORGE fixes that with specs, evidence gates, and a structured delivery process that remains reliable as agent autonomy increases.

Mission

FORGE's mission is to make each individual developer the CEO of a continuously-optimizing development company. FORGE provides strategic advisors, executive staff, and auditable process at every step — but the developer decides exactly what happens, when, and why.

Contents

What's new

Recent changes since the last published refresh — split by audience. Each item cites the closed spec for traceability.

User-facing changes

  • Install FORGE as a Claude Code plugin — the FORGE command, agent, skill, and hook payload now installs directly from a checkout with claude plugin install ./, alongside the existing Copier project scaffolding. One signing-ready package instead of hand-wired command directories (Specs 463, 487–491).
  • Hands-off chained delivery with a push safety gate — /implement can flow from one spec to the next without an intervening /close, while every git push still raises an in-session approval prompt so the human stays the release authority (Specs 494–498).
  • /evolve fires when signals warrant, not on a calendar — the Evolve Loop is admitted by accumulated signal thresholds (unreviewed signals, error autopsies, deferred scope) instead of a fixed cadence, so process review happens when there is actually something to review (Spec 500).
  • /consensus — structured multi-role review on demand — gather Devil's Advocate, Maverick Thinker, Competitor, and C-suite perspectives on a contentious spec in one pass before you commit (Spec 179).
  • /signal-to-strategy — turn research into scored advantage hypotheses — convert external research signals into ranked, testable strategy bets that feed the backlog (Spec 458).
  • /reconcile — ingest work done outside FORGE — scans git history for commits with no matching spec, clusters them by related files, and (routed by size) drafts retroactive stub specs for large clusters or operator memory notes for small ambient changes. Keeps the spec corpus a faithful map of the codebase on shared / mixed-team repos. Purely additive — stubs are draft and never auto-advance (Spec 486).
  • Aging-draft surface in /now — drafts past their valid-until date now appear in the daily report so they don't silently rot (Spec 363).
  • Tab-lane awareness in choice blocks — when a tab is active, post-action menus filter or annotate options to match lane scope (Spec 351). Single-tab sessions stay quiet — no active-tabs noise (Spec 352).
  • Active-tab marker — lifecycle commands (/implement, /close, /session) now self-identify their registry row from .forge/state/active-tab-*.json, eliminating ambiguous "which tab am I?" prompts (Spec 353).
  • Post-implementation value demo — high-risk and consensus-reviewed specs get an optional before/after demonstration to aid /close review (Spec 261).
  • Parallel-batch suggestion in /implement next — when adjacent backlog items are independent, the command surfaces a /parallel recommendation instead of serializing silently (Spec 087).
  • Checkpoint resume for /implement — interrupted runs can resume from the last completed step instead of restarting from scratch (Spec 123).
  • Choice-block format standardized — every lifecycle action ends with a numbered table of next moves, ranks, and rationales (Spec 025).
  • Cost-framework scope reduction — operator-advisory model tiering replaces brittle frontmatter routing; the IDE picker is the only real selector (Spec 316).

Backend & process changes

  • Forge-public publish scrub — build-time exclusion list, genericization transforms, and forbidden-token validator harden the public-facing sync (Spec 374).
  • /matrix backlog hygiene pass — recomputes scores, surfaces drift, and ships byte-identical guide mirrors across template surfaces (Spec 370).
  • Score-prediction audit loop — every /matrix run logs predicted-vs-recomputed deltas to .forge/state/score-audit.jsonl for cross-session calibration (Spec 368).
  • CI parity gate for spec-integrity sentinels — the lane-gate block in /implement and /close is now hash-checked at PR time so silent drift between mirrors becomes impossible (Spec 367).
  • Approved-SHA recompute step — /implement Step 6c rewrites the spec-integrity hash after DA dispositions edit protected sections, closing the recurring SHA-pingpong defect class (Spec 365).
  • DA-Encoded-Via convention — when a spec converges through /consensus rounds 1+2 with aligned-approve, /implement Step 2b can verify the encoded path (round value + SHA reachability + drift check) and skip a fresh DA subagent spawn, saving one role invocation per qualifying spec (Spec 389).
  • AGENTS.md prose↔YAML drift detector — sibling check to the auth-rule lint gate that catches prose bullets not yet reflected in the structured authorization block (Spec 330).
  • Authorization-rule lint gate — /implement Step 7c scans command bodies for sensitive actions (git push, gh pr create, rm -rf) that lack a confirmation token within proximity (Spec 327).
  • Two-pass adversarial DA review — when the first DA pass finds zero issues, a deeper second pass confirms or surfaces hidden risk (Spec 181).

Quickstart

FORGE v3 is delivered as a signed Claude Code plugin. The plugin is the runtime — it ships every slash command, agent role, skill, and hook. Your project keeps only its own data (specs, sessions, process docs); the framework updates through the plugin, not through file copies.

Prerequisites

  • Claude Code (recommended path): Claude Code and Git. That's it — no Python, no template engine.
  • Other AI IDEs (Cursor, Windsurf, Copilot, …): the legacy Copier scaffold path applies and requires Python and Copier — see CONTRIBUTING.md for the pinned versions.

Install the plugin

claude plugin marketplace add Renozoic-Foundry/forge-public

then, inside Claude Code:

/plugin install forge@forge

Or directly from a forge-public checkout:

git clone https://github.com/Renozoic-Foundry/forge-public.git
cd forge-public
claude plugin install ./

Bootstrap your project

In Claude Code, from your project (new or existing):

/forge init

/forge init detects your situation and adapts: a new/empty directory gets the plugin-native project scaffold (specs, sessions, backlog, AGENTS.md/CLAUDE.md, quick reference — no Copier involved); an existing repo gets FORGE's process files added alongside your code; a pre-plugin FORGE project is offered the upgrade path. Then run /forge onboarding — the one-time guided setup that configures stack, autonomy, and features — and /now to get your first recommended action.

What happens after install

Your environment Install Bootstrap First session
Claude Code /plugin install forge@forge /forge init /forge onboarding, then /now
Other AI IDE — (plugin is Claude Code-specific) Copier scaffold (collapsed section below) Open the project; your assistant reads AGENTS.md

Want the full walkthrough? See the Getting Started tutorial — zero to first closed spec in a single session. Or read the Concept Overview to understand what FORGE is and why it exists.

Want to see the result? See docs/examples/hello-forge/ for what a bootstrapped project looks like after /forge init and a first spec cycle.

Other AI IDEs and the legacy Copier path

Cross-IDE runtime (Spec 576 — the primary non-Claude path): point a user-level, pinned checkout of the framework at your projects — the repo stays as clean as a plugin consumer's:

git clone https://github.com/Renozoic-Foundry/forge-public.git ~/forge-runtime
git -C ~/forge-runtime checkout <release-tag>
echo "$HOME/forge-runtime" > ~/.forge/runtime-root

Every scaffolded project ships two thin launchers (bin/forge, bin\forge.ps1) resolving the chain CLAUDE_PLUGIN_ROOT → FORGE_RUNTIME_ROOT → ~/.forge/runtime-root → project-local — other AI agents read AGENTS.md and invoke bin/forge <command>; non-AI developers get bin/forge now|status|list. Optionally record forge.runtime.pin: <tag> in the project's AGENTS.md; the launcher warns when a teammate's checkout drifts from the pin.

The legacy full-template Copier render remains a last resort (/forge init --copier; requires Python and Copier — pinned versions) but vendors the framework into your repo — prefer the runtime checkout above.

The legacy install.sh / install.ps1 scripts still work for this path; as of Spec 579 they no longer plant the user-level /forge-bootstrap command by default (compat: prefer /forge init — opt back in with --legacy-bootstrap / -LegacyBootstrap; see forge-bootstrap.md, legacy, scaffolding-only). Not sure which path your project needs? Run /forge doctor — it detects the state and offers the mapped fix (migration decision guide).

Bootstrapping with security overrides (consent-required):

If you need to override test_command, lint_command, harness_command, or any include_* security toggle at bootstrap time, supply the runtime consent token on the same invocation (Spec 437):

copier copy https://github.com/Renozoic-Foundry/forge-public.git my-project \
  --trust \
  --data accept_security_overrides=true \
  --data accept_security_overrides_confirmed=true \
  --data 'test_command=./mvnw test'

The --data accept_security_overrides_confirmed=true flag MUST be on the CLI command line — answers-file-supplied consent tokens are rejected by design. The same shape applies to copier update. For the rationale, see the copier-gotchas.md guide that ships in your scaffolded project (docs/process-kit/copier-gotchas.md after the template render).

Keeping up to date

What to update Claude Code (plugin) Legacy Copier projects
FORGE framework (commands, agents, skills, hooks) Update the plugin: re-run /plugin install forge@forge (marketplace) or claude plugin install ./ from a refreshed checkout Re-render via copier update
Your project's scaffold files (process kit, templates) /forge stoke (pre-plugin projects); plugin-native projects receive doc updates with the plugin /forge stoke or copier update

Framework behavior always comes from the installed plugin version. Generated reference docs (quick reference, command reference) carry a provenance header naming the source version and a revision-history section, so you can always tell what you're running.

What is FORGE?

FORGE is an opinionated development framework that synthesizes five foundational standards into a coherent workflow for human-AI collaborative software delivery. The underlying methodology — Evidence-Gated Iterative Delivery (EGID) — ensures every lifecycle transition requires demonstrable proof.

The speed multiplier: Traditional spec-driven development is thorough but slow. FORGE inverts that tradeoff — AI generates detailed specs from a brief description (objective, scope, acceptance criteria, test plan), then implements them with evidence at every gate. The human role shifts from writing documentation to reviewing and approving, where judgment adds the most value. At higher autonomy levels, AI can chain from spec creation straight through to validated closure — but by default, every AI-written spec is gated from implementation until a human approves it.

The Solve/Evolve double-loop: FORGE doesn't just deliver work — it learns from it. The Solve Loop (/spec → /implement → /close) delivers each change with evidence gates. The Evolve Loop captures signals from every session — errors, corrections, friction — and proposes process improvements as new specs. /session logs what happened. /note captures insights mid-work. /evolve reviews accumulated patterns and adapts the process. Static frameworks calcify; FORGE compounds. See Design Philosophy for the full treatment.

Core framework (every project)

These capabilities are built into every FORGE project out of the box:

  • AI-generated specs — Describe what you need; AI produces the full spec in seconds. Human approves; AI implements with evidence at every gate.
  • Evidence gates — Every lifecycle transition requires proof. Structured PASS/FAIL outcomes. Gate failures produce actionable feedback.
  • KCS v6 double-loop learning — Solve Loop delivers specs. Evolve Loop captures signals, analyzes patterns, and proposes process improvements automatically.
  • Role-separated agents — 17 roles (Spec Author, Devil's Advocate, Implementer, Validator, Maverick Thinker, Competitor, CTO, CISO, CFO, CXO, COO, CCO, CQO, CEfO, CMO, CRO, CResO) with runtime tool restrictions via .claude/agents/.
  • Scored backlog — Priority formula ranks every spec. AI picks the highest-value work. Dependency tracking prevents blocked starts.
  • 33 slash commands — Full lifecycle coverage with command chaining. Model tiering is advisory; the IDE model picker is the real selector (Spec 316). See command reference for the full list.
  • Session logging and signal capture — Every session ends with a log. Retro signals inform priority re-scoring.

Enhancing features (opt-in)

Optional capabilities activated per-project based on needs. The core framework operates fully without any of these.

  • NanoClaw Messaging Bridge — Async gate approvals via Telegram, WhatsApp, Slack. Agents work while you're away; you review on your phone. For L3+ autonomy.
  • Multi-agent swarms — Parallel spec delivery with conflict detection and swarm budgets. For high-throughput projects.
  • OCI container isolation — Role-scoped volume mounts for filesystem permission enforcement. Alternative to default git worktree isolation.

Roadmap

These features are under active development and will be available in future releases:

  • Lane B Compliance Engine — Pluggable compliance profiles for regulated industries (IEC 61508, EU 2023/1230, ISO 13485, IEC 62443). Bidirectional traceability, V&V reports, spec sealing. Designed for safety-critical firmware and medical device teams.
  • Hardware Authentication (PAL) — YubiKey HMAC-SHA1 challenge-response for gate decisions. Cryptographic proof of human approval. Will be required for Lane B; optional for Lane A.

Foundations

FORGE synthesizes five foundations — KCS v6 double-loop learning, Stage-Gate evidence gates, AAIF bounded autonomy, Spec Kit persistent specs-as-context-anchors, and plugin-primary distribution. The canonical definition (why these five, what each prevents, and how they interlock) lives in Design Philosophy § Five Foundations — defined once so the lists cannot drift.

Autonomy levels

FORGE defines five autonomy levels (L0–L4), all supported. The default is L1 (human-gated). At L2+, the agent chains /implement → /close → /implement next cycles with the human watching at the terminal, intervening only on gate failures or decision points. L3–L4 enable fully async operation via NanoClaw messaging (enhancing feature, opt-in).

Level Name Human role Status
L0 Full Manual Human drives everything; agent advises only Supported
L1 Human-Gated AI implements, human gates every transition Supported (default)
L2 Supervised Autonomy Commands auto-chain on success, human watches at decision points Supported
L3 Trusted Autonomy Agent completes full spec cycles; human reviews async via /close Available (NanoClaw messaging opt-in)
L4 Full Autonomy Kill switch and budget ceilings are the only hard stops Preview — requires NanoClaw

MCP Documentation Servers

FORGE uses Model Context Protocol servers to ensure agents work from current documentation rather than stale training data.

  • Context7 — Versioned library/framework documentation matched to your project's dependencies
  • Fetch (Anthropic official) — Any URL converted to agent-readable markdown on demand

MCP servers are declared in .mcp.json at the project root.

Architecture Overview

your-project/
  .claude/
    commands/           # FORGE workflow commands (slash commands)
    settings.json       # IDE hooks (auto-test on edit)
  .forge/
    bin/                # Agent runtime scripts + PowerShell wrappers
      forge-orchestrate.sh/.ps1   # Multi-agent pipeline orchestrator
      forge-kill.sh/.ps1          # Kill switch — halt all agents
      forge-status.sh/.ps1        # Agent status query
    lib/                # Shared libraries (config, adapters, handoff, audit, budget)
    adapters/           # Runtime adapters (native, OCI) and agent adapters (generic, claude-code)
    templates/          # Handoff schema + role instruction templates
    Dockerfile          # Base image for OCI mode (extend for your stack)
    handoffs/           # Runtime: inter-agent handoff artifacts (gitignored)
    audit/              # Runtime: audit logs and PID registry (gitignored)
  CLAUDE.md             # Operating contract (framework + project-specific)
  AGENTS.md             # AAIF agent configuration + runtime config
  docs/
    process-kit/        # Runbooks, rubrics, checklists, templates
    specs/              # Versioned spec files
    sessions/           # Session logs, signals, scratchpad
    decisions/          # ADR-style architecture decisions
    backlog.md          # Scored and ranked spec backlog

Key Concepts

  • Two hard rules: (1) Every change has a spec. (2) Every session has a log.
  • AI-generated specs: Describe what you need in a few sentences; AI produces the full spec. Human approves before implementation begins.
  • Spec lifecycle: draft → in-progress → implemented → closed
  • Evidence gates: Each transition requires demonstrable proof (structured GATE [name]: PASS/FAIL outcomes)
  • Spec approval gate: By default, every AI-written spec requires human approval before implementation — configurable per autonomy level
  • Change lanes: hotfix, small-change, standard-feature, process-only
  • Signal capture: Errors, insights, and retro findings are logged and inform priority scoring
  • Command chaining: /implement → /close → /implement next auto-chains on gate success (L2+)
  • Core vs enhancing: Core framework (specs, gates, learning, commands) works standalone; enhancing features (compliance, NanoClaw, hardware auth) are opt-in

Why structure?

Long-running AI agents fail in predictable ways — and the fix is the environment, not the model. This is harness engineering: reliability comes from architecture, not intelligence.

Failure mode What happens FORGE mitigation
Context decay Agent loses track over long sessions Session logs + structured handoff schemas
Goal drift Agent wanders from the original objective Spec gates — every action ties back to a spec
Premature completion Agent declares "done" too early Evidence gates in /close — no status transition without proof
Self-evaluation bias Agent overrates its own output Scoring rubric + Devil's Advocate role + external review criteria

FORGE's structures aren't process overhead — they're the harness that makes autonomous delivery reliable.

Agent Runtime

FORGE includes a multi-agent pipeline for L2+ autonomy levels. The orchestrator manages role-separated agents (Spec Author → Devil's Advocate → Implementer → Validator) with handoff artifacts and audit logging.

# Dry run — see the pipeline plan without executing
.forge/bin/forge-orchestrate.sh --spec 001 --dry-run

# Run the full pipeline
.forge/bin/forge-orchestrate.sh --spec 001

# Check agent status
.forge/bin/forge-status.sh

# Emergency halt — stop all agents
.forge/bin/forge-kill.sh

Runtime modes:

  • Native (default) — git worktree isolation. No container runtime required. Note: no filesystem permission enforcement.
  • OCI (opt-in) — container isolation with role-scoped volume mounts (:ro/:rw). Works with any OCI-compatible runtime: Rancher Desktop (dockerd), Podman, nerdctl, Docker Engine. Set runtime.adapter: oci in AGENTS.md.

On Windows, use the .ps1 wrappers (e.g., forge-orchestrate.ps1) — they auto-detect Git Bash and delegate.

Reference Implementation

FORGE was built using its own methodology — 578 specs across 157 sessions (2026-03-13 through 2026-07-06), validating the full lifecycle from draft through closure. The development history (specs, session logs, signals, ADRs) demonstrates the methodology in practice.

Contributing

See CONTRIBUTING.md for prerequisites, development setup, spec lifecycle, and how to open a PR. The canonical source repository is Renozoic-Foundry/forge-public.

Security

To report a vulnerability, use GitHub's private vulnerability reporting on Renozoic-Foundry/forge-public (Security tab → Report a vulnerability). Do not open a public issue for security reports. See SECURITY.md for the full policy and response timelines.

Compliance Disclaimer

FORGE is a process framework, not a certification authority. Compliance features (Lane B profiles, traceability matrices, V&V reports) are aids for qualified professionals — they do not constitute regulatory assessments, certifications, or legal determinations of compliance. All generated artifacts must be reviewed and approved by qualified engineers before submission to certification authorities. See concept-overview.md for details.

License

MIT License — see LICENSE.