recursive-mode for coding agents
Installation
npx skills add try-works/recursive-mode --skill '*' --full-depth
skills.sh
https://skills.sh/try-works/recursive-mode/recursive-mode
GitHub
https://github.com/try-works/recursive-mode
recursive-mode.dev
For detailed documentation
recursive-mode is a workflow for agentic engineering that I have been using daily and refining over the past four months. It starts from a simple observation: chat context is a poor medium for engineering state.
It solves that problem and opens up a few new possibilities for further coding performance improvements, by using generative recursion during planning, implementation and verification. It is installable and invokable as a skill, but in practice is more like strict inner harness than an open-ended instruction like most skills are.
In a typical agentic coding session, requirements, codebase analysis, implementation plans, execution details, test output, and verification all end up in one expanding conversation. This works for smaller pieces of work but breaks down on larger tasks. As the session grows, it becomes harder to tell whether the agent is still working from the original requirements or just following the most recent context. Over time that causes drifting implementations and severe trust issues, as we can see in this Claude Code user‘s case (see further discussion on HackerNews):
‘Claude has regressed to the point it cannot be trusted to perform complex engineering.
- Ignores instructions
- Claims "simplest fixes" that are incorrect
- Does the opposite of requested activities
- Claims completion against instructions’
Thankfully, we can fix these issues by using better workflows. recursive-mode addresses them by moving the important state into repository docs and advancing work through explicit recursive phases during planning, implementation, and verification.
At a high level, recursive-mode formalizes the workflow most of us already try to follow, whether manually or through skills: define requirements, analyze the codebase, create an implementation plan, implement the plan, etc., and also adds recursion at every step.
recursive-mode is sequential and phased. Each phase takes accepted docs from earlier phases as input and produces one locked markdown doc as output. Each phase is gated on criteria defined earlier in the run. Once a phase is accepted, its output is locked. Later phases can extend or correct earlier work through addenda, but they do not silently rewrite prior state.
That constraint changes the workflow in a useful ways. It makes the run resumable. It makes the reasoning legible. It prevents later work from quietly changing the original intent. It gives verification phases something stable to verify against.
How it works
The user starts by creating a 00-requirements.md document inside a run folder, then invokes the recursive-mode skill in chat. Note that chat should be treated as a control surface for invocations and commands, never, ever as store for plans and tasks. The run then proceeds through its phases until manual QA, where it waits for user approval before continuing.
After the run is complete, the agent updates DECISIONS.md, which acts as a ledger of previously implemented requirements, including why they were made, what changed, and links to the relevant run docs. It also updates STATE.md, which provides a current overview of the application.
In practice, a repo using recursive-mode will generate this documentation per run:
.recursive/
├── /memory/ # Structured memory bank
├── RECURSIVE.md # Canonical workflow spec
├── STATE.md # Current repository state
├── DECISIONS.md # Decisions ledger
└──
run/00-my-first-requirements/
├── 00-requirements.md # User-created requirement
├── 01-as-is.md # Analysis of codebase current state
├── 02-to-be.md # Implementation plan
├── 03-implementation-summary.md # What was done in practice
├── 04-test-summary.md # Automated test summary
├── 05-manual-qa.md # Test cases
└── addenda/ # Addenda docs added as needed
The specific file names are not what matters. What matters is that requirements, codebase analysis, plans, implementation summaries, verification output, and manual QA exist as durable repo artifacts instead of being left inside a volatile chat session. The worktree diffs also combine with this documentation for an even stronger trace of codebase evolution and its reasons.
This gives us a number of concrete benefits:
-
Specs do not suffer context rot.
-
The workflow documents itself. It is readable by both humans and models, and it also produces material that can be reused for summaries and stakeholder communication.
- There is less no to compensate for a weak workflow by indexing large amounts of chat context into an external database. The recursive docs provide progressive disclosure and direct the model toward the right context at the right time. In practice, this should also reduce token usage compared with less structured workflows.
-
In my testing of the very first version of this workflow, then called rlm-workflow, both speed and code quality was significantly increased when building a new project from scratch based on a 700-line requirement. The quality improvements compound and makes you faster over time.
Factory.ai’s Missions is similar to recursive-mode in that both approaches treat long-running agentic work as something that should be broken into bounded units and driven by externalized state rather than one growing chat session. The difference is that recursive-mode is repo-native and document-first. It is open source, and it fits directly into a normal repository workflow. It installs and runs as a skill and works for pretty much any agent, IDE or CLI.
Using recursive-mode also opens up new possibilities:
Create a harness specific to your codebase by using AutoAgent or similar
https://github.com/kevinrgu/autoagent
Finetune or post-train an open model on your codebase using Embarrassingly Simple Self-Distillation
https://arxiv.org/abs/2604.01193
This is enabled because by using recursive-mode you create a comprehensive data set of documentation for each change: run docs are created before, during and after planning, implementation and verification, and worktrees hold the actual code diffs.
If you found this interesting, follow me on my new Twitter :)