PAUL (Plan-Apply-Unify Loop)

PAUL manages project state through a specific directory structure within your project root. These files ensure context persists across sessions and decisions are logged.

• .paul/PROJECT.md: Project context and requirements.
• .paul/ROADMAP.md: Phase breakdown and milestones.
• .paul/STATE.md: Current loop position (PLAN/APPLY/UNIFY), session state, and accumulated decisions.
• .paul/paul.toml: Machine-readable manifest.
• .paul/ledger.toml: Session history (cost/time attribution).
• .paul/MILESTONES.md: Log of completed milestones.
• .paul/phases/: Directory containing phase-specific PLAN.md and SUMMARY.md files.

PAUL is a structured AI-assisted development framework that operates on a continuous cycle called 'The Loop'. Every unit of work must follow these three stages in order:

1. PLAN: Define the work, including tasks, acceptance criteria, and boundaries.
2. APPLY: Execute the tasks defined in the plan.
3. UNIFY: Reconcile the actual results against the plan, document what was built, and close the loop.

Crucial Rule: Never skip the UNIFY step. Every plan requires a summary to ensure the loop is properly closed and state is updated.

┌─────────────────────────────────────┐
│  PLAN ──▶ APPLY ──▶ UNIFY          │
│                                     │
│  Define    Execute    Reconcile     │
│  work      tasks      & close       │
└─────────────────────────────────────┘

When documenting a phase in SUMMARY.md, the one-liner describing the outcome must be substantive. Avoid generic descriptions like "Phase complete" or "All tasks done". Instead, describe exactly what was shipped.

Examples of Good One-liners:

• "JWT auth with refresh rotation using jose library"
• "Prisma schema with User, Session, Product models"
• "Dashboard with real-time metrics via SSE"

To prevent quality degradation in Claude, work plans must be sized to complete within approximately 50% of the available context. When context usage exceeds 50%, the model enters "efficiency mode," leading to rushed or minimal output.

Context Usage vs. Quality

The Rule: Stop planning before quality degrades (at the 50% mark), not when you hit the hard context limit.

When an automation attempt (CLI/API) results in an authentication error, it should be treated as an Authentication Gate rather than a failure.

The Pattern:

1. Claude attempts automation.
2. Claude receives an auth error.
3. Claude creates a dynamic checkpoint.
4. Human provides authentication/credentials.
5. Claude retries and continues.

Distinction:

• Incorrect: A pre-planned checkpoint asking a human to "deploy" (this should be automated).
• Correct: An auth gate where Claude says "I tried to deploy but need credentials."

When urgent work must be performed between two planned integer phases, use Decimal Phases (e.g., 2.1, 2.2).

Rules for Decimal Phases:

• Naming: Use X.Y where X is the preceding integer phase and Y >= 1.
• Tagging: Always mark the phase title with the [INSERTED] tag.
• Documentation: You must include a Reason field explaining why this work was inserted.
• Ordering: Decimal phases are designed to sort correctly in filesystems (e.g., 2 < 2.1 < 2.2 < 3).

Validation Checklist:

• Integer X must exist and be complete.
• Integer X+1 must exist in the roadmap.
• Decimal X.Y must not already exist.
• Y must be greater than or equal to 1.

Tasks in a PLAN.md are categorized by their type attribute, which determines how the execution engine handles them:

• auto: Used for tasks an AI can perform independently. These must include <name>, <files>, <action>, <verify>, and <done> tags.
• checkpoint:decision: Used for implementation choices requiring human input. The engine pauses and presents defined <options> for the user to select.
• checkpoint:human-verify: Used for visual or functional verification. The engine pauses and provides <how-to-verify> instructions, waiting for an "approved" signal.
• checkpoint:human-action: Used for rare, unavoidable manual steps. The engine pauses and waits for user confirmation after the action is performed.

Research files follow a specific lifecycle to track the progression from raw subagent output to actionable project data. You should manually update the Status field in the RESEARCH.md file as the information moves through these stages:

1. Draft: The initial state when a subagent has just completed the research.
2. Reviewed: The state after the main session has vetted and confirmed the findings.
3. Integrated: The final state once the findings have been incorporated into project plans or actual code.