I Taught RUP in the Late '90s. I Just Rebuilt It for AI Agents.

From 1998 to 2000 I was a certified RUP instructor, teaching the Rational Unified Process to teams across Latin America and the Caribbean. RUP and its documentation-heavy relatives lost the industry argument because people found the paperwork tedious and skipped it. AI agents don't get bored, so I rebuilt the lean survivor of that family, OpenUP, into a framework that makes Claude Code work one logged, traceable task at a time.

Generate TL;DR ✨

TL;DR

Why a 2005 Process, and Why Me

I reached for OpenUP because I already know it in my bones. From 1998 to 2000 I was a certified RUP instructor, training and advising teams across Latin America and the Caribbean on the Rational Unified Process. RUP was the heavyweight of its era: commercial, exhaustive, role-driven, sold by IBM/Rational with a price tag to match. When it faded, one descendant stayed alive and free: OpenUP, the Open Unified Process, the lean core of that methodology kept by the Eclipse Foundation. It's the last member of the family you can still read, use, and adapt without a license.

So when I started letting coding agents do real work, and watched them behave exactly like an undisciplined junior with infinite energy, the fix looked familiar. Iterative phases. Milestones a human signs off. One increment at a time, with a paper trail. I had taught this. The surprise was how cleanly a process designed for human teams in 2005 maps onto an agent in 2026.

The result is a project template plus an enforced workflow, open-up-for-ai-agents. It started in January as a little converter that turned the original 961 Eclipse OpenUP HTML files into a clean Markdown knowledge base, and over 99 commits it grew into the thing I actually use to drive Claude Code.

Why Those Processes Actually Died

RUP and its documentation-heavy cousins were good engineering that died on human nature. The iterative, risk-first, milestone-gated discipline they prescribed was sound, I still believe that. But the discipline ran on people, and people, very reasonably, didn't keep it up.

Writing the artifact felt unproductive next to writing the code. The documents were easy to forget, easy to skip "just this once," and they drifted out of date the moment the code moved. Worst of all, nobody could cheaply check whether the doc still matched reality, so trust in the docs collapsed and the whole edifice got quietly abandoned or turned into ceremony nobody read. The industry concluded that heavy process doesn't work, when the accurate version of that conclusion adds two words at the end: on humans.

The agent changes that equation. An agent doesn't find writing the roadmap entry tedious. It doesn't "forget" the end-of-run log because it's Friday. It doesn't argue that the retrospective is a waste of time. The bookkeeping we experienced as friction is, for an agent, just another instruction, and it executes it fast. The parts that were hardest for us, cross-checking and verifying that the docs actually match the code, are exactly what an agent plus a few hooks can do continuously, tying every log entry to a real commit SHA. The methodology was right, the worker was wrong.

One Run, One Task, Logged

The mechanical heart of the framework is a single rule: one agent run completes exactly one task from the roadmap. No marathon sessions that touch forty files and end with a vague "done". Each run is bracketed by two procedures the agent has to follow, one at the start and one at the end.

At the start, it reads docs/project-status.md (what phase, which iteration, what's the goal), checks the institutional memory in iteration-learnings.md, picks the highest-priority pending task from docs/roadmap.md, confirms the task fits the current phase, and creates a branch. Working on trunk is forbidden. Then it implements, committing during the work instead of in one lump at the end.

At the end comes the part that matters most: a mandatory end-of-run procedure. Commit everything, verify the tree is clean, write a traceability log (both a Markdown entry and an append-only agent-runs.jsonl) tied to the real commit SHAs, update the roadmap and status. A task is complete when its history is persisted and logged, not when the code merely works. The skills that script this look like:

/openup-start-iteration task_id: T-007   # read state, deploy a team, branch
/openup-orchestrate     task_id: T-007    # PM decomposes, briefs specialists
/openup-complete-task   task_id: T-007    # commit, log, update roadmap, PR

The best idea in the repo is a clean split underneath all of this. docs-eng-process/ holds the process itself and is read-only scripture: the agent never edits it during a task. docs/ holds the living project state: roadmap, status, plans, logs, decisions. Rules in one place, state in another. That separation is what makes an agent's behavior reproducible across sessions instead of depending on whatever I happened to type that morning.

To keep it honest instead of aspirational, there are Python hooks wired into Claude Code events. One intercepts task-start language and refuses to let the agent start coding before it runs the intake. Another blocks the agent from stopping with uncommitted changes. A commit hook warns when there's no active iteration. You can bypass it with an explicit [openup-skip], which gets logged, because if there's no escape hatch people just route around the process where you can't see it.

The Context Lives in the Repo Now

The payoff I didn't see coming is that my prompts got short. Normally, driving an agent well means writing long, careful, context-stuffed instructions every single time: re-explaining the goal, the constraints, the current state, the conventions. With the framework in place, almost all of that already lives in the repository. The roadmap says what's next. The status says where we are. The process docs say how to work. The learnings say what was already decided and why.

So a run can start from "start the next iteration" or even just "continue", and the agent reconstructs what it needs by reading the repo. The cognitive load moved out of the prompt, which is ephemeral and easy to get wrong, and into the repository, which is durable, versioned, and shared across every session and every agent. It feels less like prompting a chatbot and more like onboarding a teammate who reads the docs before asking me anything.

This connects to the one cost I do watch: tokens. I won't put dollar figures here, because the honest measurement is messy and any number I quote would mislead. But the shape is clear from the session logs. The expensive thing with agents is re-establishing context, turn after turn, way more than the new reasoning itself. In my logs, cache reads (context being re-read) are around 97% of all tokens; the genuinely new output is a thin sliver on top. Writing state down in docs/ is, among other things, a token strategy: the agent reads its context instead of re-deriving it from scratch every session. And of course producing all that documentation also costs tokens, which is the part I keep going back and forth on.

Where It Still Breaks

Calling agents "obedient and meticulous" is the strong default, not a guarantee. I've used the framework on three real projects: a Rails tax-deduction tracker, a child-safe chat app, and most recently a small amateur-radio simulation built in a single eight-hour session. The radio project is where the gap between the strong default and the guarantee shows up.

That project ran the most mature version of the framework, with runtime hooks and rubric-graded specs and the whole apparatus. And under the pressure of an intense single-day build, the agent quietly skipped the bookkeeping-heavy artifacts: no run logs, no JSONL, no learnings file, retrospectives backfilled after the fact. It leaned on git history and architecture decision records and the status file, and dropped the rest. The thing that caught it was the framework's own retrospective template, which flagged the gap. So even with hooks, the most ceremony-heavy parts are the first to go when the heat is on. Humans skipped the docs out of boredom, the agent skips them under load.

The deeper tension is visible right in the framework's git log. On April 9th I shipped the hardest enforcement I had built, blocking hooks and a strict no-bypass rule, and softened it the same day, turning the blocks into warnings with that logged escape hatch. Months of commits are me fighting my own overhead: compact versions of the role instructions, a cheap Haiku-model "scribe" to do the mechanical writing so the expensive reasoning model doesn't, repeated cleanups of token bloat. Every enforcement mechanism I added had a cost, and half the work was clawing that cost back without losing the discipline that made the thing worth using.

Where I'm At With It

I'm not going to pretend this is solved. The framework works well enough that the older projects reached their twentieth-plus iterations with a real audit trail, and the newest one went from empty repo to running app in a day with most of its decisions documented. That's more discipline than I ever got out of a human team using RUP, myself included.

What I still can't answer is where the line sits between enough process to keep an agent honest and so much process that I'm paying tokens to generate documents nobody, human or model, will read. The radio project skipping its own logs was annoying, but it also made me wonder whether those logs earned their keep in the first place. I taught this methodology twenty-five years ago believing the documents were the point. Now I have a worker who'll write every one of them without complaint, and I'm the one deciding which ones are actually worth the cost.