fractal-loop: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

What this is

Fractal Loop — recursive project management for Claude Code. A plugin that decomposes goals into predicates and works on the riskiest unknown first. One operation, repeated at any scale.

Version: 0.9.0 | Plugin manifest: .claude-plugin/plugin.json

Commands

# Test the state machine
bash scripts/fractal-state.sh

# View tree state (auto-discovers tree in .fractal/)
bash scripts/fractal-tree.sh

# Read active predicate
bash scripts/active-predicate.sh

# Timeline: concluded nodes newest-first
bash scripts/fractal-timeline.sh

No build step. No dependencies. Pure shell scripts + markdown skills.

Architecture

The primitive

fractal(predicate):
  evaluate(predicate, existing_children)  → new_child | complete | leaf | unachievable
  if unachievable            → prune
  if leaf                    → specify → execute → human validates
  if new_child               → create child → human validates → recurse → re-evaluate parent
  if complete                → validate branch satisfaction or select next pending child

Skill chain (execution order)

1. /fractal:init — bootstrap: extract objective, create tree
2. /fractal:run — idempotent state machine (main entry point, call repeatedly)
3. /fractal:patch — fast path for trivial leaf predicates
4. Sprint agent (agents/sprint.md) — runs the full cycle /fractal:planning → /fractal:delivery → /fractal:review → /fractal:ship as a single Sonnet subagent with no human gates
5. /fractal:doctor — tree integrity validation
6. /standards:generate — inspect repo and generate .claude/standards.md (called by /fractal:init when no standards.md exists)

Skills live in commands/. Subagents live in agents/ (evaluate, sprint, patch-worker).

On-disk state (.fractal/ in target repo)

The filesystem IS the state. No database, no JSON.

• root.md — root predicate + active_node pointer (always exactly one per tree)
• predicate.md — per node: verifiable condition, status (pending|satisfied|pruned)
• discovery.md — per node (after evaluation): evaluator response (new_child|complete|leaf|unachievable). Ephemeral on parents — deleted when child ascends.
• prd.md — leaf nodes only: acceptance criteria, out-of-scope, constraints
• Execution state derived from artifact presence:
  • Only predicate.md → not started
  • discovery.md exists (new_child) → create proposed child, recurse
  • discovery.md exists (leaf, no prd) → specify, write prd
  • discovery.md + prd.md → specified (run sprint)
  • plan.md exists → planned (run delivery)
  • plan.md + results.md → executed (run review)
  • plan.md + results.md + review.md → reviewed (validate, then ship)
• conclusion.md — per node (after satisfaction): what was achieved, key decisions, deferred items
• learnings.md — accumulated human corrections (read on every /fractal:run entry)