gODtECH-FORGE

Framework for Orchestrated Reasoning, Governance & Engineering

A credit-aware control layer for deliberate, governed AI-assisted software development.

---

⚡ The 30-second version

FORGE sits between developer intent and an AI coding agent.

Instead of making the model spend paid reasoning time rediscovering a repository, FORGE performs repeatable local preparation first: repository inspection, bounded context selection, risk classification, command discovery, workflow planning, approval gating, caching, and evidence tracking.

TASK + REPOSITORY
       ↓
DETERMINISTIC PREFLIGHT
       ↓
BOUNDED AI WORK PACKET
       ↓
PROPORTIONAL MODEL REASONING
       ↓
APPROVALS + IMPLEMENTATION
       ↓
EVIDENCE + VERIFICATION
       ↓
SHIP

FORGE is not a model, not a fixed application stack, and not one giant prompt. It is a local CLI, a portable .forge/ project layer, a deterministic planning engine, and a provider-neutral MCP server.

Current focus: the Phase I execution/governance foundation is complete and Phase II Intelligence is active. Product, Market, Research, Architecture, Design, Engineering, Security, Quality, Operations, Documentation, Git/Delivery, and Provenance Intelligence are implemented reasoning modules; adaptive selection informed by measured outcomes follows.

↑ back to top

---

🤖 Build with AI without losing the engineering path

You do not have to make your AI coding agent figure out your entire development process from scratch.

FORGE is the layer that gives the agent an engineering path to follow.

Instead of handing an AI a repository and hoping it asks the right questions, discovers the right files, chooses the right workflow, remembers previous decisions, and verifies the result correctly, FORGE prepares and governs that work.

FORGE helps the agent:

• understand the task before implementation;
• inspect the repository and relevant project context;
• ask for missing information when a decision cannot safely be inferred;
• select the right product, research, architecture, design, engineering, security, quality, operations, documentation, delivery, and provenance guidance for the task;
• keep the working context bounded instead of loading the whole repository unnecessarily;
• follow risk-appropriate workflows and human approval checkpoints;
• maintain decisions, progress, and evidence under .forge/;
• verify what was actually completed instead of relying only on the model's claim;
• continue from an existing run instead of starting the reasoning process over.

Your AI still builds. FORGE keeps it on the right path.

FORGE does not replace your AI coding agent, your developers, or your product decisions.

It gives them an operating layer.

That means you can bring FORGE into an existing project, give your AI a task, and let FORGE handle the repeatable orchestration around that task:

YOU
 │
 │  "Add payments"
 ▼
FORGE
 │
 ├── understand the repository
 ├── identify relevant context
 ├── classify risk and capabilities
 ├── activate the right intelligence
 ├── identify missing decisions
 ├── prepare the work packet
 ├── define verification expectations
 └── gate sensitive decisions when required
 │
 ▼
AI CODING AGENT
 │
 ├── reasons about the actual task
 ├── implements within project conventions
 ├── uses the prepared context
 └── returns evidence for the work
 │
 ▼
FORGE RUN + VERIFICATION
 │
 └── record what happened and what was proven

The result is not “AI does everything.”

The result is AI works inside a deliberate engineering system.

Fork FORGE and make the process yours

FORGE is reusable under the Apache License 2.0.

You can fork the repository, adapt the workflows, policies, intelligence modules, templates, and project defaults, then use your distribution across your own repositories.

A practical path looks like this:

Fork FORGE
   ↓
Create your FORGE distribution
   ↓
Customize your rules and workflows
   ↓
Install / link FORGE
   ↓
forge init
   ↓
Your project gets .forge/ + AGENTS.md
   ↓
forge prepare --task "..."
   ↓
Connect your AI coding agent
   ↓
Build with governed context
   ↓
Verify + record evidence
   ↓
Ship

You do not need to redesign your AI development process for every new project.

Set the engineering operating layer once. Reuse it across the work.

Start with FORGE. Let the model focus on judgment and implementation while FORGE handles the preparation, orchestration, governance, and evidence around the work.

Fork it. Adapt it. Put it in your projects. Build with AI on a clearer path.

↑ back to top

---

🎯 Why FORGE exists

AI coding tools are powerful, but a surprising amount of model work is mechanical rather than intelligent: finding manifests, locating relevant files, guessing test commands, re-reading project rules, reconstructing previous decisions, or loading context that never mattered.

FORGE moves the repeatable parts out of the model call so model capacity can be spent on judgment, design, implementation, and interpretation.

Typical AI coding session	FORGE-assisted session
Re-scan the repository every session	Reuse fingerprinted repository facts
Load broad context “just in case”	Select bounded task-relevant context
Guess build, lint, and test commands	Discover commands from allowlisted manifests
Use the same model/ceremony for every task	Scale reasoning and approvals to task risk
Keep progress only in chat history	Persist runs, checkpoints, steps, and evidence
Mix instructions, assumptions, and proof	Separate context, policy, workflow, and verification
Recover from avoidable hallucinations later	Reduce ambiguity before implementation begins

FORGE does not claim a universal fixed percentage of token or credit savings. Savings depend on the repository, task, client, and model. The engineering goal is to reduce unnecessary discovery tokens, repeated tool calls, retries, context noise, and avoidable use of expensive reasoning.

---

🚀 Quick start

1. Install the verified GitHub release

FORGE v0.7.0 is available from the signed GitHub Release. The installers verify the release checksum before performing the global package installation.

Linux or macOS:

curl -fsSLO https://github.com/gODtECH-Ctl-Create/gODtECH-FORGE/releases/download/v0.7.0/install.sh
sh install.sh 0.7.0
forge --version

Windows PowerShell:

Invoke-WebRequest https://github.com/gODtECH-Ctl-Create/gODtECH-FORGE/releases/download/v0.7.0/install.ps1 -OutFile install.ps1
.\install.ps1 -Version 0.7.0
forge --version

If Windows reports that running scripts is disabled, use a process-scoped bypass for the current PowerShell session only, then run the downloaded installer:

Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass
.\install.ps1 -Version 0.7.0
forge --version

Alternatively, invoke the installer in a one-off PowerShell process without changing the current session policy:

powershell.exe -NoProfile -ExecutionPolicy Bypass -File .\install.ps1 -Version 0.7.0
forge --version

Only run install.ps1 after downloading it from the canonical signed FORGE GitHub Release shown above. Do not use a permanent machine-wide execution-policy bypass for FORGE installation.

The npm registry is a separate publication channel and is not yet published. Contributors can still install from source:

git clone https://github.com/gODtECH-Ctl-Create/gODtECH-FORGE.git
cd gODtECH-FORGE
npm ci
npm run build
npm link
forge --version

2. Add FORGE to a project

cd /path/to/your-project
forge init --dry-run
forge init
forge doctor
forge validate

--dry-run reports conflicts before anything is written. Initialization installs the portable .forge/ workspace and AGENTS.md; it does not copy the FORGE implementation into your application.

3. Prepare the work before the model

forge prepare --task "Add passwordless sign-in"

For agents and other tools:

forge prepare --task "Add passwordless sign-in" --json

4. Start a governed run

forge run start --task "Add passwordless sign-in"
forge run status

Higher-risk plans can stop at explicit human approval checkpoints.

FORGE supports two evidence-recording styles:

Granular mode — advance one stage at a time:

forge run advance --id <run-id> --evidence "Repository and context inspected."

Compact mode — after the work is complete, record evidence for every remaining stage in one atomic transition:

forge run complete --id <run-id> --evidence-file .forge/evidence/run-evidence.yaml

Example evidence file:

inspect-context: Repository state, constraints, and prior decisions were confirmed.
review-architecture: Architecture decisions and trade-offs were recorded.
review-security: Trust boundaries, threats, and required controls were reviewed.
review-operations: Rollout, observability, recovery, and runtime evidence were reviewed when applicable.
review-documentation: Documentation claims, examples, and status were checked against project sources when applicable.
review-provenance: Source, attribution, version, and evidence lineage were checked when provenance-sensitive work was present.
review-delivery: Tracked intent, branch scope, merge readiness, and post-merge synchronization requirements were reviewed.
implement: Scoped implementation was completed.
test: Applicable automated checks passed.
verify: Objective completion evidence was collected.
deliver: Issue, branch, review, and delivery state were recorded.

The stage history is still persisted separately inside the run. Compact mode removes repetitive manual stage transitions; it does not collapse the audit trail or bypass required approvals.

FORGE records workflow evidence and does not silently execute arbitrary discovered project commands.

---

🌀 How FORGE works

flowchart LR
    A[Developer intent] --> B[FORGE CLI / MCP]
    B --> C[Repository preflight]
    C --> D[Relevant context]
    C --> E[Risk + capabilities]
    C --> F[Verification commands]
    D --> G[AI work packet]
    E --> G
    F --> G
    G --> H[AI coding agent]
    H --> I[Implementation]
    I --> J{Approval required?}
    J -->|Yes| K[Human checkpoint]
    J -->|No| L[Evidence]
    K --> L
    L --> M[Verification]
    M --> N[Ship / continue]

The important boundary is simple: deterministic tooling prepares facts; the model handles judgment. FORGE tries to remove work the model should never have needed to do in the first place.

What forge prepare does locally

A preparation pass can:

• scan application files while excluding dependencies, builds, caches, and installed FORGE files;
• detect languages and allowlisted project manifests;
• inspect Git branch, commit, dirty state, and non-secret changed paths;
• reject secret-like environment, credential, key, and secret paths from context;
• select task-relevant project context instead of indiscriminate repository loading;
• discover build, check, lint, test, type-check, and verification commands;
• classify task type, risk, capabilities, workflow, and human approval requirements;
• select a bounded set of framework references and context;
• suggest an economy, standard, or advanced model tier;
• cache the resulting work packet by a SHA-256 fingerprint for reuse.

Selective Intelligence

FORGE now includes task-selective reasoning guidance under .forge/intelligence/.

The implemented modules are:

• Product Intelligence — clarifies the problem, users, value, workflows, MVP boundaries, non-goals, assumptions, and success criteria.
• Market Intelligence — evaluates target geography/segment, alternatives, expectations, differentiation, and adoption constraints using evidence rather than guesses.
• Research Intelligence — defines research questions, source-quality/freshness rules, fact-vs-inference boundaries, limitations, and stop conditions.
• Architecture Intelligence — defines system boundaries, responsibilities, dependency direction, data and integration flows, topology, failure implications, trade-offs, and the smallest robust architecture needed for implementation.
• Design Intelligence — defines user flows, information hierarchy, interaction states, accessibility, responsive behavior, design-system reuse, and an implementation-ready experience handoff.
• Engineering Intelligence — guides repository-aligned implementation, explicit contract and migration changes, failure behavior, compatibility, maintainability, and verification-ready handoff.
• Security Intelligence — identifies trust boundaries, identity and authorization requirements, sensitive-data and secret-handling rules, realistic abuse cases, proportional controls, residual risk, and security verification handoffs.
• Quality Intelligence — maps acceptance criteria to proportionate checks, identifies regression and failure-path risk, selects appropriate test layers, records test gaps and release blockers, and produces verification-ready quality evidence.
• Operations Intelligence — defines runtime targets, rollout and rollback behavior, configuration and secret delivery, observability, health, capacity, failure recovery, migration operations, runbooks, ownership, and post-release evidence.
• Documentation Intelligence — defines audience and reader outcomes, source-of-truth selection, factual accuracy, information architecture, command/example verification, status accuracy, stale-content detection, and documentation verification handoffs.
• Git / Delivery Intelligence — reasons about tracked intent, branch and scope discipline, commit/PR structure, merge readiness, conflict handling, hotfix delivery, and post-merge synchronization while leaving procedural Git actions to .forge/workflows/GIT.md.
• Provenance Intelligence — reasons about framework/artifact origin, attribution, source/claim traceability, evidence lineage, release provenance, provenance drift, and safe metadata while leaving normative requirements to .forge/policies/PROVENANCE.md.

A normal feature can load Product + Architecture + Engineering without automatically paying the cost of market research. Material UI/UX work adds Design Intelligence before Engineering, while backend-only features do not pay that design-context cost. Product-creation or early product-definition tasks can activate Product + Market + Research, with Architecture joining when structural technical decisions are required, Design joining only when a material user-facing surface is in scope, and Engineering joining when implementation is requested. Sensitive identity, permission, secret, payment, personal-data, production, destructive, and high-risk work adds Security Intelligence through the planner's existing security capability and approval model. Feature, bug, refactor, security, and infrastructure work adds Quality Intelligence through the existing quality capability. Infrastructure, production-impact, deployment, observability, health, rollback, runbook, capacity, backup/restore, and other material runtime work adds Operations Intelligence through the existing operations capability. Documentation and research/report work adds Documentation Intelligence through the existing documentation capability, while unrelated implementation work avoids that context cost. Git / Delivery Intelligence follows the existing cross-cutting git-delivery capability for governed repository work and does not add project-context fields. Provenance Intelligence activates only when origin, attribution, generated-by/source traceability, evidence origin, release provenance/metadata, attestation/SBOM-style lineage, or .forge/manifest.yaml is materially in scope. forge prepare includes only the intelligence files activated by the plan.

Measure the preparation layer

Every prepare call records a privacy-preserving local event. View aggregate cache reuse, preparation latency, deterministic steps, model-tier routing, and estimated context reduction with:

forge metrics
forge metrics --json

Events are Git-ignored under .forge/metrics/. They contain counts and categories—not task text, filenames, source, repository identity, Git metadata, or secrets. Token estimates use a transparent four-characters-per-token approximation and are not provider billing or guaranteed credit savings.

---

✨ What you get

Area	FORGE provides
Repository intelligence	Deterministic inspection of project facts, Git state, manifests, context, and verification commands
AI efficiency	Bounded work packets, cache reuse, task-relevant context, and proportional model-tier suggestions
Planning	Task classification, risk-aware capabilities, ordered steps, workflows, and approval checkpoints
Intelligence	Product, Market, Research, Architecture, Design, Engineering, Security, Quality, Operations, Documentation, Git/Delivery, and Provenance guidance for product definition, evidence-aware decisions, proportional system design, implementation-ready user experience, repository-aligned code changes, security controls, risk-based quality strategy, operable runtime delivery, source-grounded documentation, reviewable change delivery, and trustworthy origin/evidence lineage
Governance	Human gates for sensitive work and explicit separation of instructions, policies, evidence, and execution
Memory	Maintained project context, decisions, resumable runs, progress, approvals, and evidence under .forge/
Agent integration	Provider-neutral local MCP server plus a repository-bundled Codex plugin
Verification	Discovered quality commands and evidence records without silently running arbitrary application commands
Portability	A project-owned .forge/ layer that stays independent of the consuming application's technology stack

---

📦 Ways to use FORGE

Mode	Status	Best for
Verified GitHub release	✅ Available	Users who want the checksum-verified packaged CLI and platform installer
Source-installed CLI	✅ Available	Contributors, local development, and existing repositories
Portable .forge/ layer	✅ Available	Teams that want durable project context and governance inside the repository
Generic MCP server	✅ Available	MCP-compatible AI coding clients
Codex plugin	✅ Available in this repo	Codex users who want FORGE tools exposed directly
GitHub template / fork	✅ Reusable	Build your own FORGE distribution or customize the framework
npm / Homebrew / Scoop / native binaries	🗺️ Planned	Additional distribution channels

FORGE is open source under the Apache License 2.0. Commercial use, modification, distribution, and private use are permitted subject to the license terms.

Ecosystem note: gODtECH Steward is now publicly released as @godtech/steward@0.1.0. It remains an independent repository-health engine that FORGE may call through stable public contracts when maintenance or health evidence is relevant.

---

🔌 AI coding integration

FORGE exposes its deterministic engine over a local stdio MCP server:

forge mcp serve

Generic MCP configuration

{
  "mcpServers": {
    "forge": {
      "command": "forge",
      "args": ["mcp", "serve"]
    }
  }
}

Codex plugin

A local marketplace and plugin bundle lives under forge/codex/:

codex plugin marketplace add ./forge/codex
codex plugin add forge@personal

Start a new Codex thread after installation.

MCP tool	What the agent receives
forge_prepare	Cached repository facts, selected context, risk, commands, and remaining model work
forge_plan	Proportional capabilities, approvals, workflow, and ordered steps
forge_context	Maintained product, technical, experience, security, and operations context
forge_run_status	Current progress, next step, approvals, and evidence for a resumable run
forge_run_complete	Atomically record evidence for all remaining stages after required approvals are resolved
forge_metrics	Local cache reuse, latency, deterministic-work, and context-reduction aggregates

These tools do not call a model, approve human gates, or silently execute arbitrary project commands. The MCP layer exposes FORGE's preparation and workflow engine; the coding client remains responsible for model execution.

---

🧩 Ecosystem

FORGE, StackPilot, and Steward are complementary systems with intentionally separate ownership:

                        FORGE
              orchestrate / govern / verify
                         |
             +-----------+-----------+
             |                       |
             v                       v
        StackPilot                Steward
        BUILD IT             KEEP IT HEALTHY
             |                       |
             +-----------+-----------+
                         v
                   TARGET PROJECT

StackPilot generates production-minded project foundations and owns stack selection, golden paths, recipes, scaffolding, and stack-aware readiness.

Steward inspects existing repositories and owns deterministic housekeeping, health findings, stable scan contracts, and conservative remediation.

FORGE may eventually orchestrate both through public interfaces, but neither StackPilot nor Steward is required for FORGE itself to operate.

The non-duplication rule is important: generic housekeeping belongs in Steward, golden-path semantics belong in StackPilot, and cross-product workflow belongs in FORGE.

• gODtECH Steward
• Steward npm package
• Steward v0.1.0
• StackPilot
• StackPilot Steward integration

---

🧠 Architecture

graph TD
    U[Developer / AI client] --> CLI[CLI or MCP server]

    CLI --> PRE[Deterministic preflight]
    CLI --> PLAN[Risk-aware planner]
    CLI --> RUN[Run + evidence engine]

    PRE --> CTX[Context selector]
    PRE --> CMD[Command discovery]
    PRE --> GIT[Git + repository facts]

    CTX --> PACK[AI work packet]
    CMD --> PACK
    GIT --> PACK
    PLAN --> PACK

    PACK --> AGENT[AI coding agent]
    AGENT --> RUN
    RUN --> GATE[Human approvals]
    RUN --> VERIFY[Verification evidence]

FORGE's implementation stack is deliberately independent of the consuming application's stack. The target project can be Next.js, Laravel, Django, Go, Rust, .NET, Flutter, or another reasonable technology. FORGE inspects and governs the project; it does not force that project to adopt FORGE's internal tools.

Living project layer

.forge/
├── context/          product and technical context
├── decisions/        important choices and trade-offs
├── runs/             plans, approvals, progress, and evidence
├── cache/            reusable deterministic work packets
├── metrics/          private local preparation measurements
├── workflows/        reusable procedures
├── intelligence/     selectively activated reasoning modules
├── policies/         guardrails
├── verification/     quality and release gates
└── templates/        generated project artifacts

Framework repository

forge/
├── assets/           README and distribution presentation assets
├── src/              CLI, planner, preflight, runs, and MCP server
├── test/             regression and protocol tests
├── scripts/          build and packaging helpers
├── framework/        assets installed into target projects
├── codex/            local marketplace and plugin
└── internal/         contributor planning

---

🧰 Command map

Command	Purpose
forge init [--dry-run] [--force]	Safely install or refresh the portable project layer
forge doctor	Diagnose runtime and repository prerequisites
forge validate [--strict]	Validate installed files and project context
forge context	Read maintained project context
forge context set --key … --value …	Update an allowlisted scalar context field
forge plan --task …	Produce a risk-aware deterministic plan
forge prepare --task …	Build or reuse a compact AI work packet
forge metrics	Summarize local preparation efficiency and estimated context reduction
forge run start --task …	Persist a resumable workflow run
forge run status [--id …]	Read the latest or a named run
forge run approve --id … --checkpoint … --by …	Record a required human approval
forge run advance --id … --evidence …	Complete the next step with evidence
forge run complete --id … --evidence-file …	Atomically record evidence for all remaining stages after approvals are resolved
forge mcp serve	Serve provider-neutral tools over stdio

Project-aware commands accept --cwd <directory>. Structured consumers can use --json where supported.

---

🛠️ Technology direction

FORGE adds technology by responsibility rather than adding every ambitious component at once.

Technology	State	Responsibility
TypeScript + Node.js	✅ Active	CLI, orchestration, preflight, workflow state, MCP
CUE	✅ Active	Project, module, workflow, evidence, run, and work-packet contracts
GitHub Actions	✅ Active	Cross-platform validation and schema checks
Model Context Protocol	✅ Active	Provider-neutral local agent tools
Rust	🗺️ Planned	Trusted execution boundary and standalone native binaries
SQLite	🗺️ Planned	Indexed local memory, evidence, and queryable history
Tree-sitter	🗺️ Planned	Structural multi-language source analysis
OPA + Rego	🗺️ Planned	Executable security and governance policy
Playwright	🗺️ Planned	Browser, responsive, interaction, and visual verification
OpenTelemetry	🗺️ Planned	Cost, latency, quality, and operational traces

The current foundation stays intentionally compact: TypeScript, Node.js, CUE, GitHub Actions, and MCP. Heavier components should enter only when their operational value justifies their cost.

---

🛡️ Safety boundaries

FORGE is designed to increase agent capability without quietly removing human control.

• Initialization checks conflicts before writing and preserves project-owned state.
• Secret-like paths are excluded from generated work packets.
• Context and framework selections are explicitly bounded.
• Higher-risk plans can require recorded human checkpoints.
• MCP begins with preparation and workflow-oriented tools.
• Discovered commands are reported rather than silently executed.
• Application technology choices remain with the consuming project.
• Claims and completion should be backed by repository evidence.

---

🗺️ Roadmap

Phase I · Executable foundation — COMPLETE

• Portable project contracts and CUE validation
• Cross-platform CLI and safe initialization
• Context management and risk-aware planning
• Resumable runs, approvals, steps, and evidence
• Deterministic cached AI work packets
• Provider-neutral MCP server
• Repository-bundled Codex plugin
• Privacy-preserving local cache, latency, and context-reduction metrics
• Compact governed workflow completion
• Choose an open-source license
• Publish signed package and release artifacts
• Complete external DeployGuard exploratory benchmark phase
• Feed benchmark learning back into task classification

Deferred evidence track

These studies remain useful for measuring FORGE, but they are not prerequisites for Phase II:

• Controlled plain-AI versus FORGE comparisons (tracking issue #49)
• Opt-in provider usage, retry, cost, and outcome measurements where direct telemetry is available

Phase II · Intelligence — ACTIVE

• Product and market intelligence
• Research workflow and evidence quality
• Architecture intelligence
• Design intelligence
• Engineering intelligence
• Security intelligence
• Quality intelligence
• Operations intelligence
• Documentation intelligence
• Git/delivery intelligence
• Provenance intelligence
• Adaptive packet selection informed by measured outcomes

Phase III · Enforcement

• Rust trusted execution boundary
• Tree-sitter structural analysis
• OPA/Rego policy evaluation
• Playwright product verification
• Signed evidence and release gates

Phase IV · Ecosystem + memory

• SQLite indexed project memory
• Dedicated Claude, Cursor, and GitHub Copilot adapters
• Plugin installation and update automation
• OpenTelemetry cost and quality traces
• Durable remote orchestration where justified
• Orchestrate StackPilot and Steward through stable public contracts
• Correlate Steward health evidence into appropriate FORGE verification flows

---

🧪 Development

npm ci
npm run check
npm test
npm pack --dry-run

The CLI workflow validates Linux, Windows, and macOS across supported Node versions, while the schema workflow validates bundled CUE contracts and fixtures.

Contributions should keep implementation under forge/, preserve the distinction between instructions and proof, and follow the issue → branch → verification → pull request → review → merge workflow documented in AGENTS.md.

---

📄 License

FORGE is licensed under the Apache License 2.0.

You may use, modify, and distribute FORGE, including for commercial purposes, subject to the terms of the license. Contributions intentionally submitted for inclusion in FORGE are licensed under the same terms unless explicitly stated otherwise.

---

Less discovery for the model. More evidence for the result.

Prepare locally. Reason proportionally. Govern explicitly. Ship with evidence.

↑ back to top