Skip to main content
CLAUDE.md is the source of truth for each SubTurtle. The Meta Agent seeds it before spawn. The SubTurtle reads and updates it every iteration. Supervision logic checks it to understand progress.

​
Location and Ownership

Each SubTurtle has its own workspace:
  • Meta Agent owns initial seeding and task framing.
  • SubTurtle owns iterative progress updates.
  • Both operate on the same file path: .superturtle/subturtles/<name>/CLAUDE.md.
ctl spawn always creates AGENTS.md -> CLAUDE.md so agents that read either filename see the same content.

​
Required Format

SubTurtle state files are plain markdown with stable sections. The minimum practical shape is:
When all backlog items are complete, append:

​
Backlog Rules

  • Use checkbox items: - [ ] or - [x].
  • Keep one active item marked with <- current.
  • Move <- current to the next unchecked item after completing the current one.
  • Keep Current Task aligned with the item marked <- current.

​
How Meta Agent Seeds State

ctl spawn accepts state from a file or stdin and writes it to .superturtle/subturtles/<name>/CLAUDE.md.
If no state is provided, spawn fails.
ctl start does not seed state. It requires an existing .superturtle/subturtles/<name>/CLAUDE.md.

​
How SubTurtle Uses State

In yolo/yolo-codex loops, the worker prompt explicitly instructs the SubTurtle to:
1

Read state first

Parse current task, end goal, and backlog item marked &lt;- current.
2

Do one commit-sized change

Implement one focused slice, run verification, and keep scope tight.
3

Update CLAUDE.md

Check off finished backlog items, move &lt;- current, and sync Current Task.
4

Commit

Commit code plus state-file progress in the same commit.
5

Self-stop when done

If all backlog items are [x], append ## Loop Control + STOP.

​
Loop Control STOP Directive

SubTurtle runtime checks for this exact directive:
When present, the loop exits cleanly and triggers completion handoff behavior.
AGENTS.md in each workspace is a symlink to CLAUDE.md:
This keeps compatibility with tooling that expects AGENTS.md while preserving a single state source of truth.