compile-plan

name

compile-plan

description

Convert a plan document such as PLAN.md into a single runnable Python workflow. Use only when Codex is explicitly invoked with `$compile-plan` and given a concrete plan file path to compile. Apply it when the task is to preserve the plan's ordered steps, conditions, retries, and agent tasks in one `.agentify.py` file, using `agentify.call_executor()` and `agentify.call_reviewer()` for delegated agent work.

Compile Plan

Turn the supplied plan file into one executable Python program. Read the plan completely before coding, then compile its behavior into concrete control flow instead of copying plan prose into the output.

Required Inputs

Work from a concrete plan file path.

If the user does not specify an output path, write the generated Python file next to the plan file as <plan_stem>.agentify.py.

The generated file must be zero-config at runtime. It must run successfully with python path/to/file.agentify.py and must not require CLI flags, interactive prompts, environment variables, or extra manual setup beyond the repository dependencies that already exist.

If the plan omits runtime inputs, resolve the minimum required configuration at compile time and encode it directly in the generated file as constants or deterministic derived values. If the plan cannot be compiled faithfully without asking the human for runtime input, fail loudly during compilation instead of pushing that requirement into the generated script.

Workflow

1. Read the plan file and identify its ordered steps, dependencies, conditions, retries, termination rules, and agent-owned tasks.
2. Decide which behavior should be implemented as plain Python and which should be delegated through agentify.
3. Generate exactly one Python file with all helper logic kept in that file.
4. Include a main() entrypoint and if __name__ == "__main__": main().
5. Check that every plan step is represented in code and that the file has no non-runnable placeholders.
6. Confirm the generated file can be invoked directly with python generated_file.agentify.py and no extra arguments.

Translation Rules

• Translate sequential plan steps into ordinary Python functions and explicit call order.
• Translate branching instructions into if/elif/else.
• Translate repeated review or retry steps into bounded loops with explicit exit conditions.
• Default to sequential execution. Add concurrency only when the plan explicitly requires it.
• Prefer standard-library modules unless the plan or repository clearly requires something else.
• Keep comments short and only where they clarify a non-obvious mapping from plan text to code.
• Do not emit multiple Python modules, shell scripts, or a rewritten markdown plan.
• Do not add argparse, environment-variable lookups, or any other manual runtime configuration surface unless the user explicitly requested such a runtime interface.
• Prefer deriving sibling plan/report paths from __file__ or compile-time constants so the generated script remains directly runnable.

Agent Tasks

For plan steps that ask an agent to perform work, import the real agentify API:

from agentify import ReviewStatus, call_executor, call_reviewer

Use call_executor(task_prompt) to run the delegated task.

Use call_reviewer(task_prompt, executor_output) when the plan needs a completion gate before continuing.

Treat reviewer outcomes as control flow:

• ReviewStatus.COMPLETE: continue
• ReviewStatus.INCOMPLETE: retry if the plan implies iteration; otherwise fail loudly
• ReviewStatus.FAILED: raise an error or surface the blocker
• ReviewStatus.WAITING or ReviewStatus.SUSPENDED: stop and report the state clearly

Read references/patterns.md for a concrete single-file execution pattern.

Output Quality Bar

• Ensure the generated file is directly runnable with python path/to/file.agentify.py and no additional arguments.
• Keep prompts sent to the executor specific and self-contained.
• Keep reviewer checks tied to the actual completion criteria from the plan.
• Prefer explicit errors over silent skips when the plan cannot be compiled faithfully.
• Run a lightweight syntax check when the environment allows it.