Skip to content
  1. fael.tech
  2. Studies
  3. Radiant

Radiant.

How I turn an intent into software with agents, with a contract, verification, and learning in every cycle.

Type
Method
Status
In progress
Published
Updated

The question

How do you turn an intent into a real system without losing clarity, context, evidence, and learning along the way? Working with agents makes that question more urgent. An agent executes fast, but it executes what it understood, and what it understood depends on what was written before.

The cycle

Radiant organizes the work into stages, each with its own document.

  1. Frame and challenge. The Project Frame records the intent, the problem, and what is out of scope. The Design Frame does the same for the experience of the people who will use it. Before moving on, the challenge asks which hypothesis the increment tests and which simpler alternative would do the job.
  2. Specify and plan. The Spec and the Plan describe the system and the build order. The experience specification lives in a separate document.
  3. Contract. Each task becomes a contract with a single observable change as its objective, the allowed scope, the expected outputs, what not to do, and how to verify it.
  4. Build. An agent executes the contract, and only the contract.
  5. Verify. Automated checks, a focused verification of what changed, a readback of the result, and an independent critique.
  6. Learn. What went right or wrong goes back to the place responsible for it: the contract, the template, the procedure, or the method itself.
# Radiant Task Contract
Status: READY | HOLD | IN_PROGRESS | VERIFY | DONE | FAIL
Risk tier: 0 | 1 | 2 | 3

## 1. Objective
Descreva uma única mudança observável.

## 6. Non-goals
Excerpt from the contract every task fills in before an agent starts.

Roles

Each stage of the cycle has a role responsible for it. One main session, the orchestrator, talks to me, decides what to delegate, and gives the final acceptance. The rest of the work goes to subagents with a closed scope. None of them talks to me directly, and none of them delegates to another.

Orchestrator
Runs the cycle, applies the approval gates, and keeps scope changes, contract activation, and irreversible actions to itself.
Ideation
Researches sources for the Frame and gives an adversarial critique of assumptions and scope, without deciding either.
Design
Drafts the Spec, the Design Spec, and architecture decisions as proposals. Approving them is my call.
Dev
Executes the contract. The contract is the request, and the completion report is the answer.
Verifier
Checks the result against the contract and the Spec and returns findings with evidence, without fixing what it verifies.
Maintenance
Sits outside the cycle. Watches the project and proposes what to do next.

The orchestrator does not accept work as done on the word of whoever did it. It rereads the change, runs the checks, and compares the result with the contract.

Capabilities

The method does not name models. It talks about three capabilities: deep for judgment, critique, and acceptance, standard for execution bounded by an approved document, and light for search, collection, and mechanical checks. Each role has a default capability, and only the task contract can change it, with a one-line justification. Acceptance never uses a lower capability than the one that produced the work. That makes bounded work cheaper without loosening verification.

Each tool's adapter translates capabilities into models. There are two today, for Codex and Claude Code, on top of the same core. Every delegation is recorded with its role, its capability, and the model that actually ran.

{
  "capabilities": ["deep", "standard", "light"],
  "agents": [
    {
      "name": "radiant-verifier",
      "role": "verificador",
      "capability": "deep",
      "description": "Verifica outputs contra contrato, Spec e critérios, sem corrigir o que verifica."
    },
Excerpt from the file listing the profiles that can receive delegated work.

Units and routing

A contract can be split into execution units. Each unit declares its role, capability, and requirements, but never the tool or the model. Without that split, the whole contract is a single unit.

Which tool each kind of unit runs on is decided by routing rules that live on my machine, outside any project, because the installed tools and subscriptions are facts about the machine. The orchestrator picks the rule that describes the unit. From that rule's candidates, the ones without a Radiant adapter or that don't meet the unit's requirements drop out, and the first one left gets the work. The decision is recorded before launch.

A candidate never runs at a lower capability than the unit asks for. With no viable candidate, the unit stays in HOLD. A rule can also require my confirmation before dispatching.

The tool that reads the units and opens a session for each one is Demerzel, a separate tool with its own study. Radiant defines the format of units and rules, and its validators check the contract's unit block.

Maintenance

Maintenance runs on my machine, on demand or on a schedule, and only proposes. It looks at the state of the contracts, the checks the project declared safe, drift between the Spec and the code, dependencies and, when authorized, issues and CI. A source that is not authorized is skipped, and the report says why.

Every candidate needs evidence: command output, file, line. The result is a report with the proposals ranked by risk, value, and reversibility, and a draft contract for the top three. The only thing it writes is that report, in a folder outside Git. A report with nothing relevant is also a result. When I pick a proposal, the orchestrator creates the contract and the cycle starts.

Rules that apply to everything

Above the documents sits a constitution, with the method's invariants and the order of precedence when two rules conflict. It separates system design from experience design and holds that a lesson only becomes a general rule when it recurs. An isolated problem is fixed in the project where it showed up.

Radiant repositoryPublic, MIT license

Updates

  1. Execution units, routing rules, dispatch through Demerzel, and the public repository under the MIT license.
  2. Roles with delegation, capabilities instead of models, Maintenance, and the challenge in framing.
  3. First published.
← All studies