Terraforge

Terra builds. Sol advises. Fresh review when risk demands it.

A focused Codex workflow with GPT-5.6 Terra Max as the main developer and GPT-5.6 Sol Max as a bounded advisor and independent strict reviewer.

Why Terraforge · Quick start · Usage · How it works · Safety

Terraforge intentionally mirrors Lunaforge's advisor and strict-review lifecycle. The operational difference is the main developer: Terra Max instead of Luna Max. It is designed for work that benefits from one implementation owner and a stronger model challenging the important decisions.

• One accountable developer: Terra owns planning, implementation, integration, verification, and delivery.
• Bounded Sol advice: a read-only Sol advisor challenges the plan before consequential edits without taking ownership from Terra.
• Independent strict review: high-risk changes receive a fresh, read-only Sol review that has not inherited the advisor conversation.
• Controlled model usage: standard mode normally uses one planning consultation; strict mode replaces a final advisor checkpoint with the fresh reviewer.
• Honest routing: if one Terra implementation owner is no longer a good fit, Terraforge stops and offers a team workflow instead of silently switching.
• No surprise publishing: commits, pushes, pull requests, deployments, and production mutations still require explicit user authorization.

• Codex with access to gpt-5.6-terra and gpt-5.6-sol
• Python 3.9 or newer
• Multi-agent support available in the Codex surface you use

The included profile uses max reasoning for Terra and both Sol roles. This prioritizes capability over token usage.

git clone https://github.com/jay7793/terraforge.git
cd terraforge
python3 scripts/install.py

The installer adds the skill, two read-only Sol agent definitions, and the terraforge CLI profile to $CODEX_HOME, or ~/.codex when CODEX_HOME is unset. It refuses to overwrite existing files. If Lunaforge already installed the identical shared sol_advisor, Terraforge reuses that one file without overwriting it.

After updating the repository, run:

python3 scripts/install.py --upgrade

The upgrade moves the existing Terraforge skill, profile, reviewer, and legacy terraforge-advisor.toml into a timestamped directory under $CODEX_HOME/backups/ before installing the mirrored workflow. Restart Codex or open a new task afterward.

Merge these examples instead of replacing your current configuration:

• examples/config.toml → ~/.codex/config.toml
• examples/AGENTS.md → ~/.codex/AGENTS.md

Restart Codex or open a new task so the skill and agent definitions reload.

For Codex CLI:

codex --profile terraforge

For the Codex desktop app, select gpt-5.6-terra with Max reasoning before invoking the skill.

$terraforge

Goal: implement profile editing with validation and regression tests.

Standard mode is the default for ordinary work:

$terraforge

Goal: add CSV export and verify the affected API behavior.

Terra inspects the repository, drafts a plan, consults one read-only Sol advisor, implements the work, and verifies the result. A second advisor checkpoint is exceptional and used only for material new evidence, a remaining consequential ambiguity, or an explicit request.

Use strict mode explicitly, or let Terraforge select it for auth, authorization, secrets, tenant isolation, money, data integrity, migrations, destructive behavior, concurrency, public APIs, production-critical paths, or wide architectural refactors.

$terraforge

Use strict mode.

Goal: implement payment webhook verification and replay protection.

Strict mode uses this sequence:

1. Terra plans and consults the read-only Sol advisor.
2. Terra decides how to use the advice, then closes the advisor.
3. Terra implements, inspects the complete diff, and reruns verification.
4. A fresh read-only Sol reviewer independently returns ship, fix-first, or rethink.
5. After fix-first, Terra maps every finding to exact files, behavior, direct tests, evidence class, and known limitations before another fresh review.
6. After two consecutive fix-first verdicts, Terra pauses before a third review to reconcile implementation, evidence, product/architecture, and acceptance-expectation gaps. Consequential ambiguity returns to the user.

Terraforge is intentionally a single-implementer workflow. If the objective or design remains materially unresolved, or the work needs multiple independent implementation owners, it stops and recommends a team workflow such as Solweaver. It never switches without user approval.

flowchart LR
    G["Software goal"] --> P["Terra Max<br/>Inspect and plan"]
    P --> A["Sol Max advisor<br/>Read-only challenge"]
    A --> F{"Single Terra owner<br/>still a good fit?"}
    F -->|"No"| S["Stop and offer Solweaver"]
    F -->|"Yes"| I["Terra Max<br/>Implement and verify"]
    I --> R{"Strict assurance?"}
    R -->|"No"| D["Evidence-backed result"]
    R -->|"Yes"| V["Fresh Sol Max reviewer<br/>Read-only independent gate"]
    V -->|"ship"| D
    V -->|"fix-first or rethink"| X["Terra revises and verifies"]
    X --> V

The advisor and reviewer are deliberately separate. The reviewer receives no advisor conversation, recommendation, disposition, preferred outcome, or expected verdict.

A profile proves configuration, not the model that actually handled a task. Terraforge distinguishes:

• Observed: runtime metadata or model controls report Terra Max.
• Configured: the profile pins Terra Max but runtime metadata is unavailable.
• Unverified: neither source establishes the parent model and effort.

After every Sol advisor or reviewer turn, Terraforge inspects the child turn_context.model and turn_context.effort. The result counts only when they are gpt-5.6-sol and max; missing or mismatched metadata is rejected. This runtime gate checks only those two fields, and a model-generated self-report is not runtime proof.

Terraforge also makes no claim that it is cheaper than another workflow unless measured token or cost telemetry from comparable runs is available. Telemetry is intentionally not enabled by the public profile; add your own collector settings locally when you want measured comparisons.

• Sol agents are pinned to read-only sandboxes and cannot implement, commit, push, deploy, or mutate production.
• Reviewer packets must include the actual diff and verification evidence and must not request or imply a preferred verdict.
• Evidence is labeled as static/source, unit, integration, adapter, runtime/Compose, delivery, or production; lower-layer tests cannot alone prove a real production boundary.
• Unresolved external guarantees such as exactly-once delivery are escalated as product or architecture decisions instead of weakened to obtain ship.
• Worker summaries and model self-reports are claims, not proof.
• Strict completion requires a fresh reviewer verdict of ship.
• Repository rules, user changes, and external-action approval boundaries are preserved.

Validate the public package:

python3 scripts/validate.py

Test installation without touching your real Codex home:

tmp_dir="$(mktemp -d)"
python3 scripts/install.py --codex-home "$tmp_dir"
python3 "$tmp_dir/skills/terraforge/scripts/validate_install.py" \
  --codex-home "$tmp_dir" \
  --skip-codex-smoke

Static validation checks the package and installed configuration. Follow the included runtime smoke test after restarting Codex before calling the workflow runtime-certified.

MIT © Jay Jay. See LICENSE.