ratchets 0.2.6

Progressive lint enforcement tool with budgeted violations that can only decrease over time
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68

<!-- Generated by rust-bucket v0.2.0. DO NOT EDIT BY HAND. -->

# Workflow (Coordinator Agent)

This repo uses Beads. Work is tracked as beads, executed one-at-a-time, in priority order.

## Key constraints
- **Sequential only**: one bead at a time, one subagent at a time.
- **Small commits**: each commit should typecheck and pass checks.
- **Retry limit**: max 4 attempts per bead, then escalate for human input.
- **Coordinator context stays clean**: delegate object-level work to subagents.

## Coordinator workflow rules
- **Coordinator does NOT do coding work itself** - it only orchestrates subagents.
- **Coordinator delegates object-level work to ONE Coding Subagent at a time.**
- **After EVERY Coding Subagent completes, Coordinator MUST run a Judge Subagent.**
- **Judge verifies both correctness AND style guide compliance.**
- **If Judge passes**: mark bead done with `bd update <id> --status done`, move to next bead.
- **If Judge fails**:
  - Run `git reset --hard` to revert to pre-attempt commit.
  - Retry with a fresh Coding Subagent (max 4 attempts total).
  - After 4 failed attempts, escalate for human input.

## Operational notes
- Bead list is stored in `.beads/issues.jsonl`
- Update bead status with: `bd update <id> --status done`
- When creating, updating, or closing beads, commit the changes to `.beads/issues.jsonl` and `.beads/last-touched` to ensure bead state is tracked in version control.
- If a subagent fails:
  - hard reset to pre-attempt commit: `git reset --hard <good_commit>`
  - run a Judge subagent to analyze the failure mode
  - retry with a fresh worker prompt that avoids the failure mode
- Success criteria:
  - tests pass
  - run a Judge subagent to verify that the bead success is accurate, and no style guides were violated.

## Graphviz workflow

```dot
digraph CoordinatorWorkflow {
  rankdir=TB;
  node [shape=box, style=rounded];

  START [shape=ellipse, style=filled, fillcolor=lightgreen];
  READ_DOCS [label="Read repo docs\n(README, AGENTS, ARCHITECTURE,\nSTYLE_GUIDE, WORKFLOW, TESTING)"];
  PICK_BEAD [label="Select next open bead\n(P0 → P3, one at a time)"];
  DELEGATE [label="Delegate to ONE Coding Subagent"];
  JUDGE [label="Run Judge Subagent\n(verify correctness + style compliance)"];
  JUDGE_RESULT [shape=diamond, style=filled, fillcolor=lightyellow, label="Judge passes?"];
  MARK_DONE [label="bd update <id> --status done"];
  MORE [shape=diamond, style=filled, fillcolor=lightyellow, label="More beads?"];
  END [shape=ellipse, style=filled, fillcolor=lightgreen];

  RETRIES [shape=diamond, style=filled, fillcolor=lightyellow, label="Retries < 4?"];
  RESET [label="git reset --hard\n(revert to pre-attempt commit)"];
  REPROMPT [label="Retry with fresh Coding Subagent\n(avoid previous failure mode)"];
  ESCALATE [shape=box, style=filled, fillcolor=lightcoral, label="Escalate for human input"];

  START -> READ_DOCS -> PICK_BEAD -> DELEGATE -> JUDGE -> JUDGE_RESULT;
  JUDGE_RESULT -> MARK_DONE [label="pass"];
  JUDGE_RESULT -> RETRIES [label="fail"];
  RETRIES -> RESET [label="yes"];
  RESET -> REPROMPT -> DELEGATE;
  RETRIES -> ESCALATE [label="no"];
  MARK_DONE -> MORE;
  MORE -> PICK_BEAD [label="yes"];
  MORE -> END [label="no"];
}
1