Skip to content

Forge Harness

Personal Software Engineering Harness with Anchored System Knowledge & Deterministic Staleness Detection

CI Python 3.11+ License Tree Sitter AST MkDocs

🌐 Language / Ngôn ngữ / 言語

🇬🇧 English Documentation 🇻🇳 Tài liệu Tiếng Việt 🇯🇵 日本語ドキュメント

What is Forge?

Forge is a personal software engineering harness designed to govern AI coding agents and engineering teams through deterministic verification.

Instead of relying on LLM self-reporting or loose Markdown notes that drift invisibly as code changes, Forge establishes a 3-Tier Ground Truth System:

graph TD
    subgraph Human ["Tier 1: Human Intent"]
        H1["Constitutional Rules<br/>docs/system/pitfalls.md"]
        H2["Architectural Models<br/>docs/system/domain.md"]
        H3["Decisions<br/>docs/system/decisions/"]
    end

    subgraph Agent ["Tier 2: Agent Work"]
        A1["Structured Changes<br/>changes/XXXX-name/"]
        A2["Gates: Proposal → Design → Verify"]
        A3["Attributed Touches & Drifts"]
    end

    subgraph Machine ["Tier 3: Machine Truth"]
        M1["AST Anchors (Python, TS, Go, C#)"]
        M2["Cryptographic SHA Baselines"]
        M3["Derived Dependency Graph & Trace"]
    end

    Human --> Agent
    Agent --> Machine
    Machine -.->|Deterministic Check| Human

⚡ Quickstart (30 Seconds)

1. Install Globally

# Recommended using pipx or uv
uv tool install git+https://github.com/CodeGenLabs/forge-harness.git
# or
pipx install git+https://github.com/CodeGenLabs/forge-harness.git

2. Initialize in Any Project

cd /path/to/my-project
forge init
forge doctor
forge check

📚 Documentation Navigation

  • Getting Started: Installation options, prerequisites, environment check, and your first repository initialization.
  • Core Concepts: 3-Tier model, Claim Store, AST Code Anchoring, Gate Lifecycle, and Attributed Drift.
  • CLI Reference: Full syntax, arguments, and examples for all 11 subcommands.
  • Guides & CI/CD: Working with AI Agents (Claude, Gemini, ChatGPT), GitHub Actions workflow, Monorepo setups.
  • Architecture: Deep dive into the kernel, AST fingerprints, and cryptographic verification.
  • Configuration: Complete .forge/config.yaml schema and options.
  • Troubleshooting: FAQ, Windows console quirks, PATH troubleshooting, and common gate errors.