| name | issue-driven-workflow |
| description | Turn a large task into a persistent plan file and a trackable Issue CSV (local files, not an external issue tracker), then execute the issues autonomously with per-row status updates. Use when work must survive across sessions or hand off between agents, when you need an auditable record of multi-step execution, or to resume a plans/ and issues/ pair from an earlier session. Do not use for single-session tasks that your harness's built-in plan or todo tracking already covers. |
| metadata | {"short-description":"Plan file → Issue CSV → tracked autonomous execution"} |
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 and do not wait for permission on routine decisions.
The quality bar: every CSV row is completable, testable, and markable DONE without further clarification.
E2E loop
plan → issues → implement → test → review
Paths
Commands below write <skill_dir> for the absolute path of the directory containing this SKILL.md. Your harness usually reports that path when it loads the skill. If it does not, use this SKILL.md's own location. Substitute it before running.
Run the scripts from inside the target project. They resolve the project root from the working directory (nearest .git, then AGENTS.md), and artifacts land at that root: plans in plans/, issue CSVs in issues/.
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 body using the structure of
assets/_template.md and choose a complexity tier.
- Get the plan approved before writing it. Use the host's plan approval mechanism when one exists. In an interactive session without one, ask once in conversation. In a headless or autonomous run, proceed and record the assumptions in the plan's Assumptions section.
- Save the drafted body to a temp file, then write the plan:
python3 <skill_dir>/scripts/create_plan.py \
--task "<title>" --complexity <simple|medium|complex> --body-file <tmpfile>
A single-quoted heredoc piped to stdin also works. Use --template only to start from the blank scaffold. The script prints the plan path. Keep it for the next step.
- 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 per
references/issue-csv-spec.md, order rows by dependency chain, and set Dependencies so execution order is unambiguous.
- Draft the rows, canonical header included, to a temp file, then:
python3 <skill_dir>/scripts/create_issues.py --plan <plan-path> --rows-file <tmpfile>
The script derives issues/<timestamp>-<slug>.csv from the plan filename, validates every row, and writes nothing on any error.
Executing the CSV (autonomous)
The CSV is your execution state. Read it and update it through the scripts, and keep driving forward. Never string-edit the CSV: quoting rules and repeated status cells make hand edits corruption-prone. If validation reports the file itself as broken, rebuild it instead: correct the drafted rows and rerun create_issues.py with --overwrite.
- Pick work:
python3 <skill_dir>/scripts/update_issue.py <csv> --next
- Mark it started:
python3 <skill_dir>/scripts/update_issue.py <csv> --id A2 --dev-status DOING
- Complete the row. Search, read, write, test, whatever it requires.
- When
Acceptance is met and Test_Method passes, set --id A2 --dev-status DONE.
- Self-review, then set
--id A2 --review-status DONE. The script rejects incoherent transitions, for example review marked DONE before implementation.
- Immediately pick the next row with
--next and keep going.
- After all rows are DONE, run the regression pass and set
--id <ID> --regression-status DONE per 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 with --note. If in a git repo, commit at natural boundaries.
Scripts
| Script | Purpose | Key flags |
|---|
create_plan.py | Write a plan file with frontmatter under plans/ | --task, --complexity, --body-file, --template, --overwrite |
create_issues.py | Write the paired Issue CSV, fully validated | --plan, --rows-file, --overwrite |
update_issue.py | Row-addressable status and note updates, plus queries | <csv>, --id, --dev-status, --review-status, --regression-status, --note, --next, --show, --json |
validate_issues_csv.py | Validate schema and semantics, all errors in one run | <csv> |
list_plans.py | List existing plans | --query, --json |
read_plan_frontmatter.py | Read one plan's frontmatter | <plan-path>, --json |
Every script prints usage with --help.
Naming and persistence
Plans: plans/YYYY-MM-DD_HH-mm-ss-<slug>.md. Issue CSVs: issues/YYYY-MM-DD_HH-mm-ss-<slug>.csv with the same timestamp and slug, enforced by create_issues.py. A project with an existing plan/ directory from older runs keeps using it. Commit plans/ and issues/ in the consuming repo when tracking should survive sessions or hand off between agents. Gitignore them for scratch work.
References
