Concepts on DevFlow

Context rot

Mon, 01 Jan 0001 00:00:00 +0000

What it is

Context rot is the quality degradation that happens as an LLM fills its context window. It is not a single failure — it is a slow slide:

Early reconnaissance (files read, commands run, dead ends explored) stays in the window forever, crowding out the information that matters now.
Instructions given at turn 3 compete with 200 turns of tool output by turn 200.
The model starts repeating itself, re-reading files it already has, and re-deriving conclusions it already reached.
Errors compound, because a wrong assumption made early is now “established context” that later turns treat as settled.

A single Claude Code session that researches, plans, builds and verifies a feature will hit this. Not because the model is bad, but because by the time it writes the code that matters, the signal it needs is buried under everything it did to get there.

The loop

Mon, 01 Jan 0001 00:00:00 +0000

DevFlow’s lifecycle is a loop you can enter and leave at any point. Each phase produces artifacts on disk; the next phase reads them. Nothing is passed through the conversation.

new-project → discuss-objective → plan-objective → execute-objective → verify-work → milestone complete
 │ │
 └───────────────────────────────── next milestone ──────────────────────────────────────┘

1. new-project

Command: /devflow:new-project · Agents: project-researcher, research-synthesizer, roadmapper

Interviews you, researches the domain in parallel, scopes requirements into v1/v2, and orders objectives into a roadmap.

The .planning directory

Mon, 01 Jan 0001 00:00:00 +0000

.planning/ is the project’s memory. It is the reason DevFlow survives context resets: nothing important lives in the conversation.

.planning/
 PROJECT.md vision, context, `kind` — loaded on nearly every operation
 REQUIREMENTS.md scoped v1/v2 requirements with stable IDs
 ROADMAP.md objectives in dependency order, with checkboxes
 STATE.md decisions, blockers, position, session memory
 MILESTONES.md archive of completed milestones
 config.json workflow configuration
 state.json machine-readable position mirror

 research/ domain research from new-project
 codebase/ brownfield mapping from map-codebase
 todos/
 pending/ captured ideas awaiting work
 done/
 debug/ active debug sessions
 resolved/
 decisions/
 pending/ parked DECISION-NNN.md awaiting your answer
 milestones/ archived milestone directories

 objectives/
 NN-objective-name/
 OBJECTIVE.md goal, success criteria, `work` type
 CONTEXT.md your implementation preferences (discuss-objective)
 RESEARCH.md ecosystem research (research-objective)
 NN-YY-JOB.md atomic execution plan, one per job
 NN-YY-SUMMARY.md execution outcome, decisions, evidence
 VERIFICATION.md post-execution verification results
 UAT.md user acceptance walkthrough
 verification/ Maestro YAML flows, capture manifests

The files you will actually read

PROJECT.md

Short by design — it is loaded on nearly every operation, so every line costs context on every command. Vision, constraints, key decisions, and the project kind on frontmatter.

The intent model

Mon, 01 Jan 0001 00:00:00 +0000

Uniform rigor is wrong in both directions: it over-tests throwaway spikes and under-tests payment paths. DevFlow’s intent model derives the right posture from two declarations.

The two axes

Project kinds

api app library ui-lib cli plugin

Work types

feature port refactor foundation bugfix prototype spike

kind is declared once, on PROJECT.md frontmatter. It says what sort of software this is.

work is declared per objective, on OBJECTIVE.md frontmatter, or inherited from PROJECT.md’s default_work. It says what sort of change this objective is.

Waves and checkpoints

Mon, 01 Jan 0001 00:00:00 +0000

Wave-based parallelism

The planner records a dependency position on each job. At execution time, jobs are grouped into waves: everything in a wave is independent of everything else in that wave, so it can run concurrently.

Wave 1: job 4-01 job 4-02 job 4-03 ← no dependencies, run together
 │ │ │
 └──────────┴──────────┘
Wave 2: job 4-04 ← depends on wave 1 output

Each job goes to its own executor subagent with a fresh context window. This is not just a speed optimisation — it is the mechanism from context rot. Three jobs in a wave means three clean windows rather than one window carrying all three jobs’ reconnaissance.

State and memory

Mon, 01 Jan 0001 00:00:00 +0000

DevFlow’s durability claim is simple: the things worth remembering were never in the context window, so losing the window loses nothing.

What is remembered

Thing	Where	Survives
Vision, constraints, `kind`	`PROJECT.md`	everything
Requirements with IDs	`REQUIREMENTS.md`	everything
Objectives and completion	`ROADMAP.md`	everything
Decisions and rationale	`STATE.md`	everything
Open blockers	`STATE.md`	everything
Position in the plan	`STATE.md` + `state.json`	everything
What each job did	`SUMMARY.md`	everything
Verification evidence	`VERIFICATION.md`	everything
Debug hypotheses and evidence	`debug/`	everything
The conversation	context window	nothing

Reading and writing state

State is manipulated through df-tools rather than by editing files, so the markdown and its JSON mirror stay consistent.

Context discipline

Mon, 01 Jan 0001 00:00:00 +0000

DevFlow’s context guidance comes from an audit of roughly 93 million tokens of real message blocks. The figures below are measured, not estimated.

Where the window actually goes

Component	Share	Who produces it
Tool results (text)	59.3%	the environment, read back in
Tool-call inputs	33.8%	the agent — file bodies, heredocs, patches
Assistant text	5.5%	prose to the user
Images	1.5%	screenshots

Two tools account for 94% of tool-result tokens: