forge

Forge

Behavioral validation forged in, not bolted on.

Forge is an autonomous behavioral validation swarm skill for Claude Code that combines BDD behavioral verification, 7 behavioral validation gates, confidence-tiered learning, topological governance, and self-healing fix loops. It spawns 8 specialized agents that work in parallel to verify, test, fix, and commit - continuously - until every Gherkin scenario passes and every behavioral validation gate clears.

Key Features

• 8 specialized agents working in parallel with cost-optimized model routing
• Gherkin behavioral specifications as the single source of truth
• 7 behavioral validation gates: Functional, Behavioral, Coverage, Security, Accessibility, Resilience, Contract
• 12 topological governance specifications (§1.1–§1.12) - mathematical foundations for autonomous behavioral validation
• Confidence-tiered fix patterns (Platinum/Gold/Silver/Bronze) with Nash Equilibrium convergence
• Defect prediction based on historical failure data and file changes
• Chaos/resilience testing with controlled failure injection
• Cross-context dependency awareness with cascade re-testing and sheaf cohomology consistency
• Shared types and cross-cutting validation across bounded contexts
• Agent-optimized ADRs with MUST/MUST NOT constraints and verification commands
• Visual regression testing with pixel-by-pixel comparison
• Architecture-agnostic - monolith, microservices, monorepo, mobile+backend
• Optional Agentic QE integration for enhanced pattern search, security scanning, and more
• External-only mocking - mock third-party services, never internal code (production-validated policy)
• Spec drift detection - detects when Gherkin specs and implementation diverge
• LLM-as-Judge meta-review - second-model evaluation with Anti-Echo-Chamber guarantee
• Self-reflection gate - Bug Fixer asks "What could go wrong?" before committing
• Hallucination Gate - deterministic pre-LLM boundary (AST resolution, contract hash, mocking detection)
• Agent criticality scoring - bottleneck detection via Dirichlet energy and automatic optimization
• Narya-proofs - counterfactual verification proving fix necessity and sufficiency
• Property-based testing - generate 1000+ test cases from invariants
• Mutation testing - inject bugs to verify test effectiveness
• Blake3 witness chain - cryptographic tamper-evident audit trail for gate verdicts
• Infrastructure readiness markers - specify formally, implement pragmatically, upgrade transparently

Philosophy

Three Pillars

"DONE DONE"

"DONE DONE" means: the code compiles AND the product behaves as specified. Every Gherkin scenario passes. Every behavioral validation gate clears. Every dependency graph is satisfied.

Quick Start

# Copy SKILL.md to your Claude Code skills directory
cp SKILL.md ~/.claude/skills/forge.md

# Run on your project
/forge --autonomous --context payments

Invocation Modes

Architecture

Autonomous Loop

Specify → Test → Analyze → Fix → Audit → Gate → Commit → Learn → Repeat

┌────────────────────────────────────────────────────────────────────┐
│                    FORGE AUTONOMOUS LOOP                            │
├────────────────────────────────────────────────────────────────────┤
│                                                                    │
│  ┌──────────┐   ┌──────────┐   ┌──────────┐   ┌──────────┐      │
│  │ Specify  │──▶│   Test   │──▶│ Analyze  │──▶│   Fix    │      │
│  │ (Gherkin)│   │ (Run)    │   │ (Root    │   │ (Tiered) │      │
│  └──────────┘   └──────────┘   │  Cause)  │   └──────────┘      │
│       ▲                        └──────────┘        │              │
│       │                                            ▼              │
│  ┌──────────┐   ┌──────────┐   ┌──────────┐   ┌──────────┐      │
│  │  Learn   │◀──│  Commit  │◀──│  Gate    │◀──│  Audit   │      │
│  │ (Update  │   │ (Auto)   │   │ (7 Gates)│   │ (A11y)   │      │
│  │  Tiers)  │   └──────────┘   └──────────┘   └──────────┘      │
│  └──────────┘                                                     │
│       │                                                           │
│       └──────────────── REPEAT ──────────────────────────────────│
│                                                                    │
│  Loop continues until: ALL 7 VALIDATION GATES PASS or MAX 10    │
└────────────────────────────────────────────────────────────────────┘

Execution Phases

1. Phase 0 - Backend setup (build, run, health check, seed data)
2. Phase 1 - Behavioral specification & architecture records (Gherkin specs, ADRs)
3. Phase 2 - Contract & dependency validation (schemas, shared types, cross-cutting)
4. Phase 3 - Swarm initialization (load patterns, predictions, confidence tiers)
5. Phase 4 - Spawn 8 autonomous agents in parallel
6. Phase 5 - Behavioral validation gates evaluation (7 gates after every fix cycle, BFT consensus ≥5/7)

Behavioral Validation Gates

Agent Roles

Topological Governance (v1.2.0)

Forge v1.2.0 introduces 12 formal topological governance specifications (§1.1–§1.12) that provide mathematical foundations for autonomous behavioral validation. Production heuristics from v1.1.0 - criticality scoring, regression tracking, blocking gates - are now anchored to formal mathematical equivalents.

Four Specification Clusters

Infrastructure Readiness

Every specification is operational today. Infrastructure readiness markers define the path from "correct" to "correct and fast":

Configuration

Project Config (optional)

# forge.config.yaml - placed at repo root
architecture: microservices
backend:
  services:
    - name: auth-service
      port: 8081
      healthEndpoint: /health
      buildCommand: npm run build
      runCommand: npm start
frontend:
  technology: react
  testCommand: npx cypress run --spec {target}
  testDir: cypress/e2e/
  specDir: cypress/e2e/specs/

# Model routing overrides
model_routing:
  bug-fixer: opus
  failure-analyzer: sonnet
  test-runner: haiku

# Visual regression
visual_regression:
  enabled: true
  threshold: 0.001

# Agentic QE integration
integrations:
  agentic-qe:
    enabled: true
    domains: [defect-intelligence, security-compliance, visual-accessibility, contract-testing]

Context Config (optional)

# forge.contexts.yaml - bounded context definitions
contexts:
  - name: identity
    testFile: identity.cy.ts
    specFile: identity.feature
    paths: 68
    subdomains: [Auth, Profiles, Verification]
  - name: payments
    testFile: payments.cy.ts
    specFile: payments.feature
    paths: 89
    subdomains: [Wallet, Cards, Transactions]

dependencies:
  identity:
    blocks: [payments, orders]
  payments:
    depends_on: [identity]
    blocks: [orders, subscriptions]

If no configuration files are present, Forge auto-discovers the project structure on first run.

Agentic QE Integration

Forge optionally integrates with Agentic QE via MCP for enhanced capabilities:

All AQE features are additive. Forge works identically without AQE installed.

References

• Continuous Behavioral Verification: Ongoing Path to Done - Ikenna Okpala
• Build with Quality Skill: How I Build Software 10x Faster - Mondweep Chakravorty
• claude-code-v3-qe-skill - V3 QE Skill
• agentic-qe - Agentic QE Framework
• Advanced Topological Governance in Autonomous Software Engineering - Formal mathematical foundations (sheaf theory, spectral analysis, Galois fields) for v1.2.0 specifications

License

MIT