Agentops ratchet

Brownian Ratchet progress gates for RPI workflow. Check, record, verify. Triggers: "check gate", "verify progress", "ratchet status".

install

source · Clone the upstream repo

git clone https://github.com/boshu2/agentops

Claude Code · Install into ~/.claude/skills/

T=$(mktemp -d) && git clone --depth=1 https://github.com/boshu2/agentops "$T" && mkdir -p ~/.claude/skills && cp -r "$T/skills/ratchet" ~/.claude/skills/boshu2-agentops-ratchet-9ecb29 && rm -rf "$T"

manifest: skills/ratchet/SKILL.md

Ratchet Skill

Track progress through the RPI workflow with permanent gates.

Note:

/ratchet

tracks and locks progress. It does not “run the loop” by itself—pair it with

/crank

(epic loop) or

/swarm

(Ralph loop) to actually execute work.

The Brownian Ratchet

Progress = Chaos × Filter → Ratchet

Phase	What Happens
Chaos	Multiple attempts (exploration, implementation)
Filter	Validation gates (tests, /vibe, review)
Ratchet	Lock progress permanently (merged, closed, stored)

Key insight: Progress is permanent. You can't un-ratchet.

Execution Steps

Given

/ratchet [command]

status - Check Current State

ao ratchet status 2>/dev/null

Or check the chain manually:

cat .agents/ao/chain.jsonl 2>/dev/null | tail -10

check [step] - Verify Gate

ao ratchet check <step> 2>/dev/null

Steps:

research

plan

implement

vibe

post-mortem

record [step] - Record Completion

ao ratchet record <step> --output "<artifact-path>" 2>/dev/null

Or record manually by writing to chain:

echo '{"step":"<step>","status":"completed","output":"<path>","time":"<ISO-timestamp>"}' >> .agents/ao/chain.jsonl

skip [step] - Skip Intentionally

ao ratchet skip <step> --reason "<why>" 2>/dev/null

Workflow Steps

Step	Gate	Output
`research`	Research artifact exists	`.agents/research/*.md`
`plan`	Plan artifact exists	`.agents/plans/*.md`
`implement`	Code + tests pass	Source files
`vibe`	/vibe passes	`.agents/vibe/*.md`
`post-mortem`	Learnings extracted	`.agents/learnings/*.md`

Chain Storage

Progress stored in

.agents/ao/chain.jsonl

{"step":"research","status":"completed","output":".agents/research/auth.md","time":"2026-01-25T10:00:00Z"}
{"step":"plan","status":"completed","output":".agents/plans/auth-plan.md","time":"2026-01-25T11:00:00Z"}
{"step":"implement","status":"in_progress","time":"2026-01-25T12:00:00Z"}

Key Rules

Progress is permanent - can't un-ratchet
Gates must pass - validate before proceeding
Record everything - maintain the chain
Skip explicitly - document why if skipping a step

Examples

Check RPI Progress

User says:

/ratchet status

What happens:

Agent calls
```
ao ratchet status 2>/dev/null
```
to check current state
CLI reads
```
.agents/ao/chain.jsonl
```
and parses progress
Agent reports which steps are completed, in-progress, or pending
Agent shows output artifact paths for completed steps
Agent identifies next gate to pass

Result: Single-screen view of RPI workflow progress, showing which gates passed and what's next.

Record Step Completion

Skill says: After

/research

completes

What happens:

Agent calls

ao ratchet record research --output ".agents/research/auth.md"

CLI appends completion entry to
```
.agents/ao/chain.jsonl
```
Agent locks research step as permanently completed
Agent proceeds to plan phase knowing research gate passed

Result: Progress permanently recorded, gate locked, workflow advances without backsliding.

Troubleshooting

Problem	Cause	Solution
ao ratchet status fails	ao CLI not available or chain.jsonl missing	Manually check `.agents/ao/chain.jsonl` or create empty file
Step already completed error	Attempting to re-ratchet locked step	Use `ao ratchet status` to check state; skip if already done
chain.jsonl corrupted	Malformed JSON entries	Manually edit to fix JSON; validate each line with `jq -c '.' <file>`
Out-of-order steps	Implementing before planning	Follow RPI order strictly; use `--skip` only with explicit reason