prompt/

This folder contains reusable prompt files and helper scripts for Codex-driven repository maintenance workflows.

Files

• AGENTS.md defines the local todo-file format and maintenance rules for agent edits in this directory.
• todo.md and todo-<name>.md files are the default implementation queues. Codex starts at the first listed queue that still has todo items, completes the first unfinished item, and archives finished entries into done.md. Completed queues may stay behind as short handoff notes that point at the next file.
• done.md records completed todo items that have been removed from the active queue.
• builder/ contains the reusable prompt templates that agent.sh runs: resolve-todo.md, planner.md, simplify-and-refactor.md, and stage-and-commit.md.
• builder/resolve-todo.md is a rendered template. agent.sh injects the selected todo files into it, then Codex inspects the first active queue, implements the first unfinished item, and moves finished items into done.md.
• builder/planner.md is a rendered template for refining todo plans before implementation. agent.sh --refine injects the selected todo files into it and runs it as a planner-only pass.
• builder/simplify-and-refactor.md asks Codex to review the codebase for cleanup, deduplication, and documentation improvements.
• builder/stage-and-commit.md tells Codex to stage and commit the current worktree using the rules in AGENTS.md.
• agent.sh runs the maintained prompt sequence, accepts todo files as positional arguments, accepts --iters to control how many times the loop executes, accepts --refine to run only the planner pass, accepts --prompt to run a comma-separated custom prompt sequence once by default, accepts --codex/--claude to select the backing agent CLI, and stops early when all selected todo files have no numbered or unchecked Markdown task-list items in implementation mode.
• agent.md documents the agent.sh command-line helper.

Maintenance

• Keep reusable instructions in the individual prompt files instead of embedding large prompt text directly in agent.sh.
• When one queue is emptied, leave a short completion note in that file and hand the active backlog to the next listed queue file.
• Update the prompt file list in agent.sh if the workflow order changes, so the automation and this README stay aligned.
• Run prompt/agent.sh --help to inspect the supported command-line flags. Example: prompt/agent.sh prompt/todo.md --iters 10. Plan refinement example: prompt/agent.sh --refine prompt/todo.md. Custom prompt sequence example: prompt/agent.sh --prompt resolve-todo.md,stage-and-commit.md. Claude example: prompt/agent.sh --claude --prompt resolve-todo.md,stage-and-commit.md.