Headless Planner: A Systematic Workflow Framework Designed for Unsupervised AI Agents

Headless Planner is a planning and execution workflow framework specifically designed for Claude Code's headless mode, aiming to address the reliability issues of unsupervised AI agents. By enforcing a strict "plan first, execute later" cycle, the framework includes a four-stage workflow, state persistence, and failure handling mechanisms. It ensures decisions are recordable, dependencies are clear, and failures are traceable, providing valuable references for deploying AI agents in production environments.

With the widespread application of AI programming assistants in automated scenarios such as CI/CD pipelines and scheduled tasks, reliability issues in headless environments have become prominent. Traditional interactive assistants rely on human feedback to correct deviations, but headless agents operating autonomously are prone to failure modes like skipping key steps, swallowing errors, no records, or blocking—making post-hoc debugging difficult and costly.

Task Understanding

Need to identify goals, scope, constraints, and ambiguities. For ambiguities, adopt a "record and proceed" strategy (reasonable default choices + assumption recording) to avoid blocking.

Plan Writing to Disk

Before execution, the plan must be written to .headless-plan.md, including metadata, a list of assumptions, and a step list with dependencies. Explicit dependency declarations prevent sequence confusion.

Step-by-Step Execution

Execute in dependency order, check the status of blocked items, mark step statuses, and verify results; supports interruption recovery (resume from in-progress/pending steps).

Failure Handling

When a step fails, mark the status and write to .headless-error.md (including failure details, context, and recovery measures) instead of exiting with a non-zero code.

1. Emphasize observability: Plan and error files provide visibility into the agent's internal state;
2. Integrate software engineering best practices: Dependency management, state persistence, and error handling improve the predictability and maintainability of AI agents;
3. Balance autonomy and controllability: Agents make autonomous decisions but keep records, and are subject to clear constraints (e.g., one retry limit).

Implemented via Claude Code's skill system (behavioral norms defined in the SKILL.md skill file), supporting version control and reuse. Integrated with the task system: steps are registered as tasks, dependencies are established via the addBlockedBy attribute, and redundancy with disk plan files enhances reliability.

Applicable Scenarios: Long-running scenarios without real-time supervision, such as CI/CD automated code reviews, scheduled maintenance tasks, and batch processing jobs. Limitations: Assumes tasks can be decomposed into clear step sequences; not suitable for exploratory/creative tasks. The mandatory planning phase adds latency, making it unsuitable for ultra-fast response scenarios.

Headless Planner drives AI agents from "black-box intelligence" to "auditable, recoverable, and maintainable" automated components, providing references for production deployment. As AI agents become widespread in critical business systems, design patterns focusing on reliability and observability will become increasingly important, with structured constraints being the core to ensure reliable operation.