Running the reopt architecture five-phase loop in Claude Code

Overview — from methodology to tool

reopt architecture is a methodology for shaping an AI product by cycling through five phases: Assess → Define → Loop → Execute → Evaluate. The problem is that when the cycle lives only in weekly meeting notes or slide decks, no discipline reaches the actual commits, PRs, or agent behavior. Claude Code is the channel that drives this methodology into daily development tooling.

Map Claude Code's four extension points — CLAUDE.md auto-load, slash commands, sub-agents, and skills — onto the five phases, and governance becomes an executable workflow. Below is the minimum guide for running one cycle against a real repository.

Premise — repository layout

First, reserve the following paths under the repository root. All of them are version-controlled.

<repo-root>/
├── CLAUDE.md                       # auto-loaded at session start
├── GOVERNANCE.md                   # reopt architecture's four sections
├── docs/
│   └── assessment-YYYY-MM-DD.md    # timestamped assessment archive
└── .claude/
    ├── commands/
    │   ├── ocls-review.md          # Phase 03 (Loop) slash command
    │   └── debt-audit.md           # Phase 05 (Evaluate) slash command
    ├── agents/
    │   └── governance-reviewer.md  # sub-agent definition
    └── skills/
        └── reopt-module-contract/
            └── SKILL.md            # one of the eight pattern skills

01 Assess — make the current structure objective

Run two paths in parallel: a UI assessment the team drives directly with sliders, and an automated assessment where Claude scans the codebase itself. When the two results diverge, the gap itself becomes the input to the next phase.

1. Team: open /assessment on the site, move the 16 engineering and business sliders, and capture the result into docs/.
2. Claude Code: ask Claude to score the repository against the same 16 attributes, citing code evidence and a 1–10 score per attribute. Save the output to docs/assessment-YYYY-MM-DD.md.

# example prompt
Score this repo against the reopt 16 attributes.
Engineering axis: security, reliability, compliance, testing, latency, data,
                  scale, cost, autonomy
Business axis: revenue, CX, TTM, domain complexity, stakeholders,
               decision impact, market maturity, market size

For each attribute:
- score (1–10)
- evidence as file:line citations
- expected tensions (speed↔compliance, cost↔reliability, etc.)

Save the final output to docs/assessment-<today>.md.

Claude scans via Grep and Read and reports per-attribute scores, tensions, and priority patterns. That report becomes the source for GOVERNANCE.md in the next phase.

02 Define — author GOVERNANCE.md and wire it in

Declare the assessment results into four sections (OWN / CONTRACT / LAYER / SHARPEN). Hand the template on the site's /governance page to Claude and it produces a draft tailored to the current repo state.

Before that, export the assessment from /assessment. Two buttons give you the snapshot and the full report.

1. Copy GOVERNANCE.md summary — a markdown block with the top three priority patterns, key tensions, and recommended maturity is copied to the clipboard. Paste it into the "Diagnostic Snapshot" section at the top of GOVERNANCE.md.
2. Download full assessment report — produces a file with all 16 attribute scores, OCLS phase scores, the eight-pattern priority, and every tension. Save it as docs/assessment-YYYY-MM-DD.md to feed the next cycle's assessment.

# example prompt
Author GOVERNANCE.md based on docs/assessment-2026-04-17.md and the
template on /governance. Four sections:

1. Ownership Structure (OWN) — a table of outcome / owner (human or AI)
2. Judgment Contracts (CONTRACT) — input, output, refusal, failure paths per actor
3. Collaboration Rules (LAYER) — information-transfer scope, dependencies, parallelism
4. Improvement Criteria (SHARPEN) — metrics, thresholds, review cadence

The key move is binding this file to every Claude Code session call. Add the file reference to CLAUDE.md, and every Claude Code conversation in the project auto-loads the governance contract.

# CLAUDE.md (project root)

This repo's structural contract is declared in @GOVERNANCE.md.
Every code suggestion must honor the OWN / CONTRACT / LAYER / SHARPEN
sections of that document. Do not produce changes that bypass approval
classification, refusal conditions, or cost ceilings.

@GOVERNANCE.md

The @file reference in CLAUDE.md auto-loads the file at session start.

03 Loop — the OCLS checklist as a slash command

Encapsulate the four-phase OCLS check into a single command. Put the verification prompt at .claude/commands/ocls-review.md and a session-side /ocls-review is all it takes to run the checklist.

---
description: "Validate current changes against the four OCLS phases"
---

Review the files just changed (git status) through the OCLS lens.

**OWN**: For any new outcomes, is the owner (human or AI) registered in
GOVERNANCE.md's ownership structure?

**CONTRACT**: For any new modules, tools, or agents, are input/output,
refusal conditions, and failure modes declared in the contract?

**LAYER**: Are collaboration rules intact? Is the context-transfer scope
the minimum required?

**SHARPEN**: Have measurement points (logs, metrics) been added? Does
operational data flow into the SHARPEN loop?

List violations as a checklist and propose a patch for each.

.claude/commands/ocls-review.md — the prompt executed when /ocls-review is invoked

For formal PR validation, define a separate sub-agent. Let the main agent handle the general session and a specialized sub-agent handle governance validation — splitting responsibility, exactly as the Responsibility Partitioning pattern prescribes.

---
name: governance-reviewer
description: "Reviews PR or branch changes through the reopt architecture lens. Triggered automatically or manually during PR review."
tools: [Read, Grep, Glob, Bash]
---

You are a governance reviewer fluent in reopt architecture's four OCLS
phases and eight patterns. Use @GOVERNANCE.md's declarations as the
reference baseline and look for four signals:

- Authority Sprawl
- Contract Gap
- Observability Gap
- Validation Gap

Classify any debt found as one of the four agentic-debt types and propose
remediation per OCLS phase.

.claude/agents/governance-reviewer.md — sub-agent frontmatter + instructions

04 Execute — register patterns as skills and invoke them

Register the eight patterns as skills, and Claude loads the corresponding pattern guidance on situational triggers. Each pattern skill file turns the site's pattern content (context / problem / forces / solution / antiPattern) directly into a prompt.

---
name: reopt-module-contract
description: "Pattern that declares a module's input/output, authority, refusal conditions, and failure modes as a contract. Trigger when registering a new tool, designing an API boundary, or integrating an external system."
---

Module Contract pattern summary:
- Every module declares input schema, output schema, required authority,
  refusal conditions, and the failure-response shape.
- The contract must exist in both code and documentation.
- Contract violations must be detectable at runtime.
- Do not swap or add modules without a contract.

Application check:
1. What is this module's input schema?
2. What input must it refuse?
3. What is the failure-response shape? How does the caller detect it?
4. What is the required authority scope?

.claude/skills/reopt-module-contract/SKILL.md

The team's everyday prompts should be written as judgment questions, not concept explanations. When Claude loads a skill, the pattern's forces and antiPattern come into the context with it.

# good
"Apply Module Contract to the Response Agent's reply-generation function.
It currently returns a bare string with no contract. Include refusal
conditions (PII in response, legal advice) and failure modes
(confidence < 0.7)."

# bad
"Clean up this function"

05 Evaluate — audit agentic debt and refresh the contract

At sprint end, generate a debt report across the four agentic-debt types (Authority Sprawl, Contract Gap, Observability Gap, Validation Gap). The output updates GOVERNANCE.md and feeds the next assessment cycle.

---
description: "Audit agentic debt over the recent sprint"
---

Using the last two weeks of commits (git log --since=2.weeks) and
operational metrics, audit agentic debt.

1. **Authority Sprawl**: cases where agent or tool authority scope
   expanded implicitly
2. **Contract Gap**: modules or agents added without a contract
3. **Observability Gap**: decision paths missing logs or traces
4. **Validation Gap**: output paths with no evaluation criteria

For each debt item:
- origin (file:line)
- OCLS phase (OWN / CONTRACT / LAYER / SHARPEN)
- GOVERNANCE.md update proposal
- priority (High / Medium / Low)

Save the output to docs/debt-<today>.md.

.claude/commands/debt-audit.md

Feed the generated debt report into the next week's assessment (phase 01). With this, the methodology's five phases run not as a paper cycle but as an actual cycle of file timestamps.

One-cycle checklist

The minimum checklist for the team to complete one full reopt architecture cycle. Two-week sprint cadence.

1. Day 1 — team runs /assessment, ask Claude to score the 16 attributes, save to docs/assessment-YYYY-MM-DD.md.
2. Day 1 — generate GOVERNANCE.md from the assessment, add @GOVERNANCE.md to CLAUDE.md.
3. Day 2–10 — invoke /ocls-review on every PR during daily work. Run formal validation through the governance-reviewer sub-agent.
4. Day 2–10 — when adding a new module or agent, invoke the matching reopt-* skill explicitly or trigger it through a judgment-question prompt.
5. Day 10 — run /debt-audit to produce the two-week debt report.
6. Day 10 — update GOVERNANCE.md from the debt report. Return to Day 1 of the next cycle.

Conclusion — what keeps the methodology alive

reopt architecture's core claim is that structure is governance. For the claim to become real, governance must live inside the tools developers use every day — not in meeting notes or a wiki. A single line of @-reference in CLAUDE.md loads GOVERNANCE.md into every session; two slash commands (/ocls-review, /debt-audit) routinize the loop and the evaluation; sub-agents and skills inject responsibility and pattern guidance at the moment of implementation.

When each of the methodology's five phases is bound to one Claude Code feature, the document stops being inert print and becomes an executing structure. Speed is guaranteed by AI. Structure is guaranteed by this loop.