KO | EN

GitLite

Minimalist Open Source Repository Search Engine

gitlite — search

#dsh #dsh-plugin #typescript #ai-agent #developer-tools #claude-code #codex #deepseek-harness #ai-agents #react #mcp #rust

soluna-workflow

★ 23 Open GitHub ↗

A cost-conscious Codex workflow that routes planning and review through Sol, implementation through Luna, and escalates reasoning only when evidence justifies it.

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# Codex Sol → Luna Workflow

A cost-conscious multi-agent workflow for GPT-5.6 Codex.

This repository is not intended to be a universal “best configuration.” It is
an opinionated starting point for teams that want strong architecture and
implementation quality without running every task at the highest reasoning
effort or passing an entire repository and conversation history to every agent.

## Goals

The workflow was designed around five goals:

1. Reduce unnecessary token and quota consumption.
2. Preserve strong planning and review for consequential changes.
3. Keep implementation workers narrowly scoped.
4. Escalate reasoning based on observed evidence rather than task size alone.
5. Prevent persistence, parallelism, or broad permissions from turning a normal
   coding task into an uncontrolled agent run.

## Model-routing decisions

| Stage | Agent | Model and effort |
|---|---|---|
| Root coordination | default | Sol Medium |
| Normal planning | `sol_architect` | Sol Medium |
| Difficult architecture | `sol_architect_deep` | Sol High |
| Tiny mechanical edit | `luna_worker_lite` | Luna Medium |
| Normal implementation | `luna_worker` | Luna High |
| Blocked implementation | `luna_escalation` | Luna Max |
| Final review | `sol_reviewer` | Sol High, read-only |

### Why the root runs Sol Medium

The root agent mostly routes work, maintains task state, and chooses the next
specialist. Those actions do not usually require deep architectural reasoning.

Medium gives the root enough reasoning capacity to preserve the complete task
model, route bounded work, and integrate evidence without promoting every task
to a high-effort specialist. Deeper reasoning remains isolated to the specific
planning, implementation, or review task that needs it.

### Why planning starts at Sol Medium

Planning benefits from stronger reasoning than routine coordination because it
must identify dependencies, define task boundaries, and choose interfaces.

Medium is the default because most repository planning should be solvable by:

- targeted code inspection;
- recognition of existing patterns;
- a few connected design decisions;
- explicit acceptance criteria and validation.

Starting every plan at High would spend more quota before there is evidence
that the problem is genuinely difficult.

### Why Sol High is an escalation, not the default

Sol High is reserved for planning problems that remain unresolved after a
normal architecture pass, such as:

- conflicting requirements;
- consequential architectural tradeoffs;
- cross-system coupling;
- data migration or compatibility risk;
- concurrency, security, or persistence concerns.

The deep architect refuses to run unless a concrete escalation trigger and
supporting evidence are recorded. This makes reasoning escalation an auditable
decision rather than an instinctive reaction to a large task.

### Why implementation defaults to Luna High

Most implementation work becomes substantially easier after the architect has
produced a bounded task with exact files, constraints, and validation.

Luna High is intended to handle normal bounded execution without paying Sol
rates for every file edit. Luna Medium is available for tiny mechanical changes,
while Luna Max is reserved for a bounded task that produces a concrete local
blocker or unexplained validation failure.

### Why final review returns to Sol High

Parallel workers can each complete their own task while still introducing
integration problems between modules.

The final reviewer receives the plan, handoff, diff, and validation evidence.
It uses Sol High because integration review may require checking assumptions
across worker boundaries, public interfaces, regressions, and unsupported
completion claims.

The reviewer is read-only so review does not silently turn into another
implementation pass.

### Why Terra is not in the default routing

This workflow intentionally routes work between Luna and Sol rather than using
Terra as an intermediate tier.

Current cost-versus-capability analysis indicates that Terra may be dominated
by some combination of Luna and Sol reasoning levels: Luna handles bounded,
repeatable work at substantially lower cost, while Sol handles ambiguous or
high-value reasoning.

Do not introduce Terra merely because a task is more difficult than a normal
Luna task. First:

1. improve or narrow the context packet;
2. increase Luna reasoning for a bounded implementation problem; or
3. return an architectural problem to Sol.

Consider Terra only when repository-specific evaluation shows that it produces
a better completion rate, latency, or total cost than both:

- Luna at the appropriate higher reasoning effort; and
- Sol at the appropriate lower reasoning effort.

Record that evaluation before adding Terra to an agent definition.

## Context-management decisions

### Keep `AGENTS.md` small and durable

`AGENTS.md` is automatically relevant to many sessions, so every temporary
detail placed there becomes recurring context cost.

It contains only rules that should apply to almost every task:

- routing and escalation policy;
- context discipline;
- scope and authorization boundaries;
- validation expectations;
- documentation lifecycle.

Project architecture belongs in `docs/ai/PROJECT_CONTEXT.md`. Current work
belongs in `plans/ACTIVE_PLAN.md`. Session continuity belongs in
`plans/HANDOFF.md`.

### Use task-specific context packets

Each implementation task lists the exact files, symbols, documentation, and
constraints the worker should begin with.

This prevents every worker from:

- scanning the entire repository;
- rediscovering the same architecture;
- reading unrelated documentation;
- inheriting the full architect transcript;
- carrying completed investigative history.

A worker may perform a targeted search when a listed file reveals a necessary
dependency, but it must stop when the task requires materially broader scope.

### Make plans executor-independent

`plans/ACTIVE_PLAN.md` is an executable contract, not a transcript of planner
reasoning. Every task records bounded context, fixed decisions, ordered steps,
acceptance criteria, validation commands and expected evidence, authorization
boundaries, and stop or escalation conditions.

Task status is exactly one of `Not started`, `In progress`, `Blocked`, or
`Complete`. Criteria are checked only from direct evidence. Ordinary incomplete
or yielded work remains `In progress`; `Blocked` means an explicit stop or
escalation condition occurred. Sol/root keeps the active plan and
`plans/HANDOFF.md` synchronized with exactly one global coordinator action.

### Keep the execution ledger root-owned

An explicitly delegated architect may initialize or amend the contract before
implementation. During implementation, only Sol/root writes
`plans/ACTIVE_PLAN.md` and `plans/HANDOFF.md`; Luna workers return provisional
packets and never mutate these shared artifacts.

Before dispatch, Sol records one task, or at most two explicitly parallel-safe
tasks with disjoint implementation-file ownership, as `In progress` in one
execution group. The group holds live worker identities, root-accepted evidence
and statuses, and an exact task-local resume point per member. After dispatch
begins, its one global action is `Reconcile execution group {task IDs}` for every
nonterminal group, including one with no live workers. A failed dispatch records
direct evidence and one exact task-local retry or environment remedy.

After dispatch begins, Reconcile remains the sole global action for a
nonterminal group, even when zero workers are live. Each member separately
records `dispatch pending`, `live`, `retry pending`, `yielded`, `blocked`, or
`complete`, plus its spawn evidence and exact remedy. With two successful spawns
both become live; with one failure only that member becomes `retry pending`; and
with two failures reconciliation selects the first nonterminal member in plan
order while retaining both remedies. A peer retry is never a second global
action.

Sol first accepts or rejects a paused checkpoint, then records terminal packets
or spawn results, then applies the first plan-order retry or yielded
continuation. A continuing checkpoint carries a packet ID, is marked
`paused awaiting acknowledgment`, and stops every owned-file mutation until Sol
accepts or rejects that ID. Without in-turn acknowledgment the worker sends a
stopped yield, exits, remains `In progress`, and resumes by re-delegation.
Completion, yield, and block packets are stable only after stop; continuing
messages are telemetry and cannot advance evidence, status, or resume state.
The group closes only when every member is complete or has a recorded blocker.
During compaction recovery, the sole action is
`Recover execution group {task IDs}` until Sol re-establishes membership and
task-local resume state, then returns to Reconcile.

### Start a fresh session for a distinct task

Long conversations accumulate repeated exploration, superseded plans, command
output, and unrelated decisions.

Before compaction or changing features, the active session writes a concise
handoff that projects the active plan and contains only:

- objective and current task;
- decisions already made;
- changed files;
- directly observed validation results;
- authorization boundaries;
- blockers and exactly one next action.

The next session reads that handoff rather than the full transcript.

### Summarize tool output

Large build logs and test output can dominate context even when only one error
line matters.

The root configuration limits retained tool output, and the instructions require
agents to record concise outcomes rather than carrying full logs forward.

Compaction preserves requirements, decisions, relevant files, direct validation
evidence, authorization boundaries, the synchronized plan/handoff checkpoint,
one allowed status, and exactly one next action while dropping repeated
exploration and superseded material.

## Subagent decisions

### Limit parallelism to two workers

The configuration permits the root plus at most two worker threads:

```toml
[agents]
max_depth = 1
max_threads = 3
```

Parallelism is useful only when tasks are truly independent. Every extra worker
may repeat prompt context, repository discovery, tool calls, and validation.

Two workers provide useful parallelism without encouraging large uncontrolled
fan-out.

### Prevent recursive delegation

`max_depth = 1` prevents implementation workers from recursively spawning
additional workers.

The architect decides task boundaries once. The root performs delegation.
Workers execute their assigned task. This keeps ownership and token use
predictable.

### Do not pass the parent transcript

Workers receive only:

- their assigned task;
- the explicit context packet;
- the current handoff entry;
- ordered steps;
- fixed decisions and constraints;
- authorization boundaries;
- acceptance criteria;
- validation commands;
- expected evidence;
- stop or escalation conditions;
- the packet schema: task ID, packet ID, kind and proposed status, stability
  declaration, owned and changed files, completed steps, validation commands and
  observed outcomes, criterion evidence mapping, exact local continuation or
  blocker, assumptions, risks, and integration notes.

The architect’s complete conversation is deliberately excluded because its raw
exploration is usually not required for implementation.

## Reasoning-escalation decision

The workflow treats escalation as appropriate only when the problem is
reasoning-limited.

Valid signals include:

- unresolved design tradeoffs;
- contradictory constraints;
- hidden cross-component coupling;
- repeated incorrect hypotheses despite new evidence;
- an implementation failure with an unclear root cause;
- high-impact uncertainty involving data, APIs, security, concurrency,
  migrations, or compatibility.

These are not reasoning-escalation signals:

- missing or irrelevant context;
- vague acceptance criteria;
- missing permissions or credentials;
- tool, dependency, or environment failures;
- very large logs;
- excessive conversation history;
- several unrelated tasks combined into one request.

Those problems should be repaired directly instead of spending more reasoning
tokens.

The trigger and evidence are recorded in `plans/ACTIVE_PLAN.md`, and only the
affected task is escalated. Later bounded tasks return to their normal tier.

## Safety and authorization decisions

### Bounded persistence

The instructions avoid phrases such as:

- “never stop”;
- “do whatever it takes”;
- “find another way at all costs”;
- “complete the task without asking.”

Those instructions can encourage an agent to widen scope, bypass safeguards, or
keep consuming quota after meaningful progress has stopped.

Agents instead continue only within explicit scope and stop when progress
requires new permissions, credentials, targets, destructive actions, or a
material scope change.

### Exact target authorization

Agents may not silently substitute a different:

- environment;
- account;
- machine;
- service;
- branch;
- database;
- resource;
- credential source.

A failed action against the named target is reported as a blocker. It is not
treated as permission to find a different target.

### Evidence-backed completion

A test, build, migration, calculation, or behavior may be described as
successful only when the agent has direct evidence that it ran and observed the
result.

Plans and handoffs contain separate fields for validation commands and observed
evidence so assumptions do not become recorded facts.

### Auto-review and final review serve different purposes

The root config enables sandbox Auto-review for eligible permission-boundary
requests:

```toml
approval_policy = "on-request"
approvals_reviewer = "auto_review"
```

Auto-review evaluates whether an eligible sandbox-boundary action should be
approved. It does not grant unlimited access and does not review the completed
code.

`sol_reviewer` performs the final integration review of the diff and validation
evidence.

## Repository structure

```text
.codex/
├── config.toml
└── agents/
    ├── sol-architect.toml
    ├── sol-architect-deep.toml
    ├── sol-reviewer.toml
    ├── luna-worker-lite.toml
    ├── luna-worker.toml
    └── luna-escalation.toml

AGENTS.md
CODEX_WORKFLOW.md

docs/ai/
├── PROJECT_CONTEXT.md
└── INSTRUCTION_AUDIT.md

plans/
├── ACTIVE_PLAN.md
├── HANDOFF.md
├── TASK_TEMPLATE.md
└── completed/
```

## Install in a project

Copy the repository contents into the root of a trusted Codex project.

Complete `docs/ai/PROJECT_CONTEXT.md` with:

- the stable architecture map;
- module and data boundaries;
- formatting and build commands;
- focused and full test commands;
- static-analysis commands;
- the final integration check;
- production-sensitive or destructive operations.

Do not add project history or completed task logs to `AGENTS.md`.

## Start a non-trivial task

```text
Use sol_architect to investigate this request and create
plans/ACTIVE_PLAN.md. Do not implement code.

Use targeted repository searches. Define exact context packets,
ordered steps, authorization boundaries, expected validation evidence, stop
conditions, and an initial checkpoint synchronized with plans/HANDOFF.md.

Request:
<paste request>
```

Use `sol_architect_deep` only when the normal architect records a concrete
reasoning-limited blocker and supporting evidence.

## Implement a task

For a tiny mechanical edit:

```text
Implement Task 1 with luna_worker_lite.
Pass only Task 1, its context packet, current handoff, ordered steps,
constraints, authorization boundaries, acceptance criteria, validation
commands, expected evidence, and stop conditions. Return structured packets to
Sol; do not edit plans/ACTIVE_PLAN.md or plans/HANDOFF.md. Stop if the work is
not mechanical.
```

For a normal task:

```text
Implement Task 1 with luna_worker.
Pass only Task 1, its context packet, current handoff entry, constraints,
ordered steps, authorization boundaries, acceptance criteria, expected
evidence, validation commands, and stop conditions. Return structured packets
to Sol; do not edit plans/ACTIVE_PLAN.md or plans/HANDOFF.md.
```

For two independent tasks:

```text
Tasks 1 and 2 are explicitly marked parallel-safe.
For each worker, pass only its task, context packet, current handoff, ordered
steps, constraints, authorization boundaries, acceptance criteria, validation
commands, expected evidence, and stop conditions. Verify disjoint
implementation-file ownership, spawn one Luna worker for each, and reconcile
their structured packets. Workers must not edit plans/ACTIVE_PLAN.md or
plans/HANDOFF.md. Do not spawn additional agents.
```

Every checkpoint, completion, yield, or block packet contains the task ID;
task-scoped monotonically ordered packet ID; packet kind and proposed status;
stability declaration (`paused awaiting acknowledgment` or `stopped`); owned
and changed files; completed steps; validation commands and outcomes; criterion
evidence mapping; exact local continuation or blocker; assumptions; risks; and
integration notes. A continuing checkpoint pauses all owned-file mutations until
Sol accepts or rejects that packet ID; without an in-turn acknowledgment, send a
stopped yield and exit. Continuing messages are telemetry only.

## Escalate a task

```text
Task 2 has a recorded reasoning-limited blocker.

Use luna_escalation with only:
- Task 2;
- its context packet;
- the current handoff and previous worker packet;
- its ordered steps;
- its expected evidence;
- its stop conditions;
- the failed validation and concise evidence;
- the recorded escalation trigger.

Return structured packets to Sol; do not edit plans/ACTIVE_PLAN.md or
plans/HANDOFF.md. Do not repeat broad exploration or widen scope.
```

Return to the normal reasoning tier after the blocked task is resolved.

## Final review

```text
Use sol_reviewer to review:
- the original request;
- plans/ACTIVE_PLAN.md;
- plans/HANDOFF.md;
- the final diff;
- validation evidence.

Check for unsupported completion claims, authorization overreach,
regressions, interface mismatches, missing tests, invalid task statuses,
plan/handoff drift, unauthorized shared-artifact writers, execution-group
transition errors, and missing or multiple global actions.
```

## Audit inherited instructions

Run the process in `docs/ai/INSTRUCTION_AUDIT.md` after adopting the workflow,
changing models, or importing older personal or project instructions.

The audit looks for:

- unbounded persistence language;
- broad delegation triggers;
- oversized persistent context;
- missing authorization boundaries;
- reasoning tiers that start unnecessarily high.

## Archive completed work

Move the finished plan to:

```text
plans/completed/YYYY-MM-DD-short-feature-name.md
```

Reset `plans/ACTIVE_PLAN.md` and `plans/HANDOFF.md`.
Keep their reusable checkpoints synchronized with exactly one next action.

Do not copy completed feature history into `AGENTS.md`.

soluna-workflow

Explore Similar Repositories

Was this content helpful?

Recent Feedback

Download README