Issue-Driven Workflow
Philosophy
The plan and Issue CSV are a work amplifier. Front-load the thinking so the agent has a full plate of actionable work to execute autonomously — more rows means more useful work per run.
- Planning (interactive) — search the web, read docs, ask questions, gather context. A thorough plan means more work the agent can do without stopping.
- Execution (autonomous) — be proactive, not passive. Work through the CSV end-to-end. Maximize useful work per run — don't wait for permission on routine decisions.
The quality bar: every CSV row should be completable, testable, and markable DONE without further clarification.
E2E loop
plan → issues → implement → test → review
Planning (interactive)
- Restate the task and assumptions.
- Gather context — search the web, read project files, inspect dependencies. Make every plan section concrete, not aspirational.
- Ask up to 2 clarification questions if unclear, then proceed with stated assumptions.
- Draft the plan in chat using
assets/_template.md. Choose complexity (simple|medium|complex). - Ask: "Reply CONFIRM to write the plan file."
- On confirmation:
python3 .codex/skills/issue-driven-workflow/scripts/create_plan.py \ --task "<title>" --complexity <simple|medium|complex> - Do not edit code while planning.
Creating the CSV (interactive)
- Generate after the plan is approved.
- Break the plan into granular, independently actionable rows.
- Fill all required columns — see
references/issue-csv-spec.md. - Order by dependency chain. Set
Dependenciesso execution order is unambiguous. - Validate:
python3 .codex/skills/issue-driven-workflow/scripts/validate_issues_csv.py <issues.csv>
Executing the CSV (autonomous)
The CSV is your execution state. Read it to know where you are, update it as you work, keep driving forward.
- Read the CSV. Find the next
TODOrow in dependency order. - Set
Dev_Status = DOING. Start working. - Complete the row — search, read, write, test, whatever it requires.
- When
Acceptanceis met andTest_Methodpasses, setDev_Status = DONE. - Self-review. Mark
Review1_Status = DONE. - Immediately move to the next row. Read the CSV again, pick the next
TODO, keep going. - After all rows are
DONE, regression check. MarkRegression_Status = DONEper row. - Report progress briefly as you complete rows.
- Only stop for genuinely blocking unknowns that affect correctness, safety, or irreversible actions.
If a row is too large, split it. If a row fails, fix it or flag it. If in a git repo, commit at natural boundaries. Edit the CSV directly — re-validate after edits.
Scripts
| Script | Purpose |
|---|---|
create_plan.py | Create a plan file with YAML frontmatter under plan/ |
list_plans.py | List existing plans (supports --query, --json) |
validate_issues_csv.py | Validate Issue CSV schema and status values |
Run with --help first. Scripts live in scripts/ relative to this skill.
Naming
Plans: plan/YYYY-MM-DD_HH-mm-ss-<slug>.md — Issue CSVs: issues/YYYY-MM-DD_HH-mm-ss-<slug>.csv — same timestamp/slug.
References
- Issue CSV spec — read when creating or validating CSVs
- Testing policy — read when filling
Test_Method - Plan template — structure with complexity tiers
- CSV template — example rows with plan-to-CSV mapping