ChristopherKahler/paul

What it solves

PAUL addresses "context rot" in AI-assisted development, where long sessions lead to degraded quality, orphan plans, and state drift. It prevents the common issue of debugging AI output rather than shipping features by enforcing a structured development loop and prioritizing in-session context over the use of multiple subagents.

How it works

PAUL implements a Plan-Apply-Unify (PAU) Loop that transforms AI development into a disciplined process:

• PLAN: Creates an executable plan with specific objectives, boundaries, and BDD-style acceptance criteria (Given/When/Then). It adapts the level of ceremony based on the task size (Quick-fix, Standard, or Complex).
• APPLY: Executes tasks through an "Execute/Qualify" loop, where each task is independently verified against the spec before moving forward. It uses nuanced escalation statuses (e.g., DONE_WITH_CONCERNS, BLOCKED) to surface uncertainty.
• UNIFY: A mandatory closing step that reconciles the plan against actual results, updates the project state, and logs decisions in a SUMMARY.md file.

PAUL manages this state via a .paul/ directory containing PROJECT.md, ROADMAP.md, and STATE.md, ensuring continuity across sessions. It can also integrate with BASE v2 to turn project state into a queryable knowledge graph.

Who it’s for

Builders using AI (specifically Claude Code) to ship software, marketing campaigns, automation workflows, or other structured execution projects.

Highlights

• Acceptance-Driven Development: Forces the definition of "done" via first-class acceptance criteria before any work begins.
• In-Session Context: Minimizes subagent sprawl to maintain higher implementation quality and reduce token costs.
• Diagnostic Failure Routing: Classifies failures as intent, spec, or code issues to prevent patching code when the plan itself is flawed.
• State Persistence: Uses a dedicated state management system to eliminate decision fatigue when resuming work.
• Comprehensive Command Set: Provides 26 specialized slash commands for everything from research and discovery to milestone tracking.