rmolines/fractal

Summary

Fractal is a Claude Code plugin that replaces flat task lists with a recursive predicate tree for AI-assisted project management. Instead of 'implement auth', you state 'users can authenticate with Google' and the agent decomposes it, always attacking the highest-uncertainty child node first. The entire state machine lives on disk as markdown files in a .fractal/ directory — no database, no external services.

Great for

People interested in AI-driven project orchestration systems, specifically the problem of autonomous goal decomposition with human-in-the-loop validation gates and filesystem-as-state persistence

Easy wins

• +Fix the documented session.lock PPID bug: CLAUDE.md explicitly calls out that session locks use $PPID from a short-lived shell, meaning PIDs get recycled and locks appear permanently active — scripts/session-lock.sh needs a more robust lock strategy (e.g., lockfiles with timestamps or flock)
• +The 'return-to-parent' node is marked pruned in the README's own tree (recursive-skill-invocation > return-to-parent shows ✗) — this is an unresolved core feature gap worth investigating and documenting as a known limitation or opening an issue for
• +Add a CONTRIBUTING.md explaining the prompt-as-code pattern, how to test commands locally, and what 'no build step, pure shell + markdown' means in practice — the architecture is non-obvious to newcomers
• +The statechart.ts is documentation-only but is a clean XState v5 machine — adding a runtime interpreter or at least a validation harness against the shell scripts would catch state/code drift

Red flags

• !1 commit total — this is either a very fresh project or was developed entirely elsewhere and bulk-uploaded; the git history provides zero context for contributors
• !The README's own .fractal tree shows 'return-to-parent' as pruned (✗), meaning the recursive self-invocation feature — the project's core differentiator — has a known unimplemented path
• !CLAUDE.md documents a known correctness bug in session locking: PPID recycling can make locks appear permanently active, breaking the 'parallel sessions safely' guarantee advertised in the README
• !No tests whatsoever for a tool whose value prop is reliable autonomous state management across sessions
• !The 'auto-selection-by-score' node is marked pending (◎) in the README tree — risk-first ordering, the primary stated differentiator vs. Task Master, is not fully implemented
• !Commands/ directory contains the actual agent logic as markdown prompt files — these are effectively unverifiable as code and untestable without Claude Code

Code quality

The XState statechart in references/statechart.ts is well-structured with clear state names, documented human gates, and explicit idempotency checkpoints — it's clearly the design authority even though it's not runtime code. The CLAUDE.md architecture notes are unusually thorough for a 1-commit repo, suggesting careful upfront design. However, the actual executable logic lives in markdown prompt files (commands/*.md) which weren't surfaced as samples, so true code quality of the agent logic is unverifiable from the outside. The shell scripts are referenced but not shown — the PPID lock bug documented in CLAUDE.md itself suggests at least one known correctness issue in scripts/session-lock.sh.

What makes it unique

The predicate-vs-task distinction (verifiable conditions over imperative steps) and the single recursive primitive with risk-scoring are genuinely differentiated from Task Master's flat PRD-to-tasklist and BMAD's fixed 6-phase pipeline. The filesystem-as-state-machine design with idempotent resume is architecturally interesting. That said, the two core differentiators — risk-first auto-selection and recursive self-invocation — are both marked incomplete in the project's own self-managed tree, so the current implementation is closer to 'structured Claude Code scaffolding' than the adaptive planning system described.