Introducing rlm-workflow

A skill for coding agents

rlm-workflow is a skill for coding agents that runs a repository workflow inspired by the MIT Recursive Language Models (RLM) paper: phase-gated work, durable artifacts, strict locking rules, and a bias toward traceability over conversational state.

The motivation is straightforward. LLM-assisted development tends to accumulate implicit requirements and “tribal knowledge” inside chat context. Over longer runs, that leads to drift, regressions, and repeated re-explanation of the same constraints. rlm-workflow moves the canonical inputs and outputs into the repository as immutable artifacts, so the work remains inspectable and reproducible.

Learn more: https://github.com/doubleuuser/rlm-workflow

Background: RLM as an artifact discipline

The RLM paper is often discussed in terms of agents and large effective context windows. For day-to-day engineering, the relevant concept is the separation of concerns between:

• transient, probabilistic model context

• persistent, reviewable repository state

rlm-workflow treats requirements, codebase analysis, and implementation plans as repository artifacts with explicit structure and lifecycle. The agent consumes these artifacts and produces the next artifacts; the run history becomes a readable chain of evidence.

Workflow overview

rlm-workflow models a Kanban-style flow using distinct phases. Each phase writes a file under a run directory, and later phases are blocked unless earlier phases are lock-valid.

Run artifacts live under:

/rlm/<run-id>/

A typical run includes:

• Phase 0: Requirements doc created by user, RLM workflow initialized by the user

• Phase 1: AS-IS analysis of the current behavior and code pointers

• Phase 1.5 (optional): structured root cause analysis for bug-fix work

• Phase 2: TO-BE implementation and validation plan

• Phase 3: implementation with TDD discipline and a compliance log

• Phase 3.5 (optional): code review phase

• Phase 4: test and validation summary with recorded evidence

• Phase 5: manual QA sign-off

• Phase 6: update DECISIONS.md

• Phase 7: update STATE.md

The output is an auditable record of why changes were made, what was changed, and how it was validated.

What rlm-workflow enforces

rlm-workflow is designed around enforcement rather than suggestion. The main mechanisms are worktree isolation, hard gates, locking, and addenda.

Worktree isolation

Phase 0 sets up an isolated git worktree for the run. This prevents accidental main-branch edits and makes it possible to run multiple efforts without contaminating the primary working tree. The workflow also verifies a clean baseline before changes begin:

• no uncommitted changes

• tests passing

• known starting state recorded in the artifact chain

Hard gates

Hard gates (<HG>) are explicit checkpoints that prevent skipping steps. Examples include:

• do not proceed until the worktree is created and verified

• do not start implementation until the plan artifact is locked

• do not write production code until a failing test is documented (TDD)

• do not advance to manual QA until tests pass

• do not update global docs until manual QA sign-off

• do not start Phase N unless all prior phases are lock-valid

These gates are evaluated during orchestration. If a gate fails, execution stops and the run remains resumable once the missing preconditions are satisfied.

Artifact locking and verification

When a phase is complete, its artifact is locked with:

• LockedAt

• LockHash (SHA-256)

Locked artifacts are immutable. The lock hash enables verification that the file has not been modified since it was locked, and later phases depend on lock validity.

Addenda instead of mutation

Long-running work frequently discovers new constraints after earlier artifacts are written. rlm-workflow supports addenda so that new findings can be recorded without rewriting prior-phase artifacts. Effective input for a phase is derived from:

• the upstream locked artifact(s)

• relevant addenda (stage-local or upstream-gap)

This preserves traceability while keeping earlier conclusions stable.

Quality-oriented subskills

The root skill (rlm-workflow) coordinates a set of subskills that enforce discipline in specific areas:

• skills/rlm-worktree/SKILL.md: Phase 0 isolation and baseline checks

• skills/rlm-tdd/SKILL.md: RED–GREEN–REFACTOR enforcement and compliance logging

• skills/rlm-debugging/SKILL.md: optional Phase 1.5 structured debugging

• skills/rlm-subagent/SKILL.md: parallel execution when subagents are available, with sequential fallback

The workflow also enforces checkable TODOs in each phase and references rationalization tables to reduce corner-cutting.

Execution modes

At Phase 3 start, the workflow detects whether the platform supports subagent execution. If available, it can parallelize implementation and testing across independent sub-phases and aggregate results into the run artifacts. If subagents are unavailable, it executes sequentially in the main agent while keeping the same phase structure and gates.

Supported patterns include:

• parallel implementation of independent sub-phases

• optional independent review in Phase 3.5

• parallel test execution for unit, integration, and E2E tiers

Installation

rlm-workflow is distributed as Agent Skills and installed via the Skills CLI.

Interactive install:

npx skills add doubleuuser/rlm-workflow

This repository contains a root skill plus subskills under skills/*. To list and install the full set from the repo root, use --full-depth.

List skills:

npx skills add doubleuuser/rlm-workflow --list
npx skills add doubleuuser/rlm-workflow --list --full-depth

Install all skills:

npx skills add doubleuuser/rlm-workflow --skill '*' --full-depth
npx skills add doubleuuser/rlm-workflow --skill '*' --full-depth -g -y

Install a single subskill:

npx skills add doubleuuser/rlm-workflow/skills/rlm-tdd
npx skills add doubleuuser/rlm-workflow --skill rlm-tdd --full-depth

Bootstrap (optional):

powershell -ExecutionPolicy Bypass -File "<SKILL_DIR>/scripts/install-rlm-workflow.ps1" -RepoRoot .

Using the workflow

A run is identified by a <run-id> and is backed by a directory:

.codex/rlm/<run-id>/

Create the initial requirements artifact:

.codex/rlm/<run-id>/00-requirements.md

Then invoke execution via the agent command:

• Implement requirement <run-id>

The workflow will create missing next-phase artifacts, resume incomplete phases, and stop at the manual QA phase for human sign-off.

You can also run a single phase directly (while still enforcing lock-chain constraints), for example:

• Run RLM Phase 3 for <run-id>

Verification and safety checks

Lock verification scripts can be used to validate artifact integrity:

powershell -ExecutionPolicy Bypass -File "<SKILL_DIR>/scripts/verify-locks.ps1" -RepoRoot . -RunId "<run-id>"
powershell -ExecutionPolicy Bypass -File "<SKILL_DIR>/scripts/verify-locks.ps1" -RepoRoot .

Worktree status can be checked via:

git worktree list

Closing

rlm-workflow is intended for developers who want LLM-assisted execution without losing repository-level discipline. The workflow makes requirements, planning, implementation evidence, and validation outputs durable and auditable.

Over time, the /rlm/ history, along with STATE.md and DECISIONS.md, becomes a practical index of what changed and why, and reduces the amount of context that needs to be carried in prompts or chat threads.