Lunaforge

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

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

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

Note

Lunaforge is an open-source community project. It is not an official OpenAI project.

Why Lunaforge

Lunaforge is designed for work that benefits from one implementation owner and a stronger model challenging the important decisions.

• One accountable developer: Luna 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 Luna.
• 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 Luna implementation owner is no longer a good fit, Lunaforge 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.

Quick start

Requirements

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

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

1. Install

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

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

2. Configure global routing

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.

3. Start Luna Max

For Codex CLI:

codex --profile lunaforge

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

4. Use Lunaforge

$lunaforge

Goal: implement profile editing with validation and regression tests.

Usage

Standard mode

Standard mode is the default for ordinary work:

$lunaforge

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

Luna 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.

Strict mode

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

$lunaforge

Use strict mode.

Goal: implement payment webhook verification and replay protection.

Strict mode uses this sequence:

1. Luna plans and consults the read-only Sol advisor.
2. Luna decides how to use the advice, then closes the advisor.
3. Luna 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, Luna 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, Luna pauses before a third review to reconcile implementation, evidence, product/architecture, and acceptance-expectation gaps. Consequential ambiguity returns to the user.

Know when to switch

Lunaforge 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.

How it works

flowchart LR
    G["Software goal"] --> P["Luna Max<br/>Inspect and plan"]
    P --> A["Sol Max advisor<br/>Read-only challenge"]
    A --> F{"Single Luna owner<br/>still a good fit?"}
    F -->|"No"| S["Stop and offer Solweaver"]
    F -->|"Yes"| I["Luna 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["Luna revises and verifies"]
    X --> V

Loading

Role	Runtime	Responsibility
Main developer	gpt-5.6-luna / max	Planning, implementation, integration, verification, and delivery
Planning advisor	gpt-5.6-sol / max	Read-only challenge of assumptions, risks, tradeoffs, and verification
Strict reviewer	fresh gpt-5.6-sol / max	Independent read-only review of the actual diff and evidence

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

Runtime honesty

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

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

After every Sol advisor or reviewer turn, Lunaforge 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.

Lunaforge also makes no claim that it is cheaper than another workflow unless measured token or cost telemetry from comparable runs is available.

Safety model

• 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

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/lunaforge/scripts/validate_install.py" --codex-home "$tmp_dir"

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

License

MIT © Jay Jay. See LICENSE.