issue-flow 0.4.4.post3__tar.gz → 0.4.5__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (85) hide show
  1. {issue_flow-0.4.4.post3 → issue_flow-0.4.5}/PKG-INFO +87 -9
  2. {issue_flow-0.4.4.post3 → issue_flow-0.4.5}/README.md +86 -8
  3. {issue_flow-0.4.4.post3 → issue_flow-0.4.5}/pyproject.toml +1 -1
  4. {issue_flow-0.4.4.post3 → issue_flow-0.4.5}/src/issue_flow/agent.py +576 -19
  5. {issue_flow-0.4.4.post3 → issue_flow-0.4.5}/src/issue_flow/cli.py +278 -6
  6. {issue_flow-0.4.4.post3 → issue_flow-0.4.5}/src/issue_flow/config.py +223 -0
  7. issue_flow-0.4.5/src/issue_flow/console_io.py +7 -0
  8. issue_flow-0.4.5/src/issue_flow/convert.py +136 -0
  9. {issue_flow-0.4.4.post3 → issue_flow-0.4.5}/src/issue_flow/gitutils.py +266 -2
  10. {issue_flow-0.4.4.post3 → issue_flow-0.4.5}/src/issue_flow/init.py +143 -113
  11. {issue_flow-0.4.4.post3 → issue_flow-0.4.5}/src/issue_flow/modes.py +383 -0
  12. {issue_flow-0.4.4.post3 → issue_flow-0.4.5}/src/issue_flow/modes.toml +2 -2
  13. {issue_flow-0.4.4.post3 → issue_flow-0.4.5}/src/issue_flow/step_profiles.toml +4 -1
  14. issue_flow-0.4.5/src/issue_flow/surfaces.py +330 -0
  15. issue_flow-0.4.5/src/issue_flow/sync.py +510 -0
  16. {issue_flow-0.4.4.post3 → issue_flow-0.4.5}/src/issue_flow/templates/commands/iflow-archive.md.j2 +1 -1
  17. issue_flow-0.4.4.post3/src/issue_flow/templates/commands/iflow-start.md.j2 → issue_flow-0.4.5/src/issue_flow/templates/commands/iflow-build.md.j2 +8 -8
  18. {issue_flow-0.4.4.post3 → issue_flow-0.4.5}/src/issue_flow/templates/commands/iflow-cleanup.md.j2 +21 -7
  19. {issue_flow-0.4.4.post3 → issue_flow-0.4.5}/src/issue_flow/templates/commands/iflow-close.md.j2 +34 -20
  20. {issue_flow-0.4.4.post3 → issue_flow-0.4.5}/src/issue_flow/templates/commands/iflow-cycle.md.j2 +11 -6
  21. issue_flow-0.4.5/src/issue_flow/templates/commands/iflow-doctor.md.j2 +47 -0
  22. {issue_flow-0.4.4.post3 → issue_flow-0.4.5}/src/issue_flow/templates/commands/iflow-epic.md.j2 +1 -1
  23. {issue_flow-0.4.4.post3 → issue_flow-0.4.5}/src/issue_flow/templates/commands/iflow-fix.md.j2 +5 -4
  24. {issue_flow-0.4.4.post3 → issue_flow-0.4.5}/src/issue_flow/templates/commands/iflow-graphify.md.j2 +1 -1
  25. issue_flow-0.4.5/src/issue_flow/templates/commands/iflow-issue.md.j2 +61 -0
  26. {issue_flow-0.4.4.post3 → issue_flow-0.4.5}/src/issue_flow/templates/commands/iflow-pick.md.j2 +2 -2
  27. {issue_flow-0.4.4.post3 → issue_flow-0.4.5}/src/issue_flow/templates/commands/iflow-plan.md.j2 +5 -5
  28. issue_flow-0.4.5/src/issue_flow/templates/commands/iflow-review.md.j2 +80 -0
  29. {issue_flow-0.4.4.post3 → issue_flow-0.4.5}/src/issue_flow/templates/commands/iflow-status.md.j2 +2 -2
  30. {issue_flow-0.4.4.post3 → issue_flow-0.4.5}/src/issue_flow/templates/commands/iflow-yolo.md.j2 +6 -5
  31. {issue_flow-0.4.4.post3 → issue_flow-0.4.5}/src/issue_flow/templates/commands/iflow.md.j2 +12 -11
  32. {issue_flow-0.4.4.post3 → issue_flow-0.4.5}/src/issue_flow/templates/docs/issue-workflow.md.j2 +169 -30
  33. {issue_flow-0.4.4.post3 → issue_flow-0.4.5}/src/issue_flow/templates/rules/_body.md.j2 +21 -13
  34. {issue_flow-0.4.4.post3 → issue_flow-0.4.5}/src/issue_flow/templates/skills/grill_me/SKILL.md.j2 +1 -1
  35. {issue_flow-0.4.4.post3 → issue_flow-0.4.5}/src/issue_flow/templates/skills/iflow_archive/SKILL.md.j2 +1 -1
  36. {issue_flow-0.4.4.post3/src/issue_flow/templates/skills/iflow_start → issue_flow-0.4.5/src/issue_flow/templates/skills/iflow_build}/SKILL.md.j2 +12 -11
  37. issue_flow-0.4.5/src/issue_flow/templates/skills/iflow_cleanup/SKILL.md.j2 +67 -0
  38. {issue_flow-0.4.4.post3 → issue_flow-0.4.5}/src/issue_flow/templates/skills/iflow_close/SKILL.md.j2 +19 -10
  39. {issue_flow-0.4.4.post3 → issue_flow-0.4.5}/src/issue_flow/templates/skills/iflow_cycle/SKILL.md.j2 +22 -6
  40. issue_flow-0.4.5/src/issue_flow/templates/skills/iflow_doctor/SKILL.md.j2 +56 -0
  41. {issue_flow-0.4.4.post3 → issue_flow-0.4.5}/src/issue_flow/templates/skills/iflow_epic/SKILL.md.j2 +2 -2
  42. {issue_flow-0.4.4.post3 → issue_flow-0.4.5}/src/issue_flow/templates/skills/iflow_fix/SKILL.md.j2 +5 -5
  43. {issue_flow-0.4.4.post3 → issue_flow-0.4.5}/src/issue_flow/templates/skills/iflow_graphify/SKILL.md.j2 +1 -1
  44. {issue_flow-0.4.4.post3 → issue_flow-0.4.5}/src/issue_flow/templates/skills/iflow_history_update/SKILL.md.j2 +10 -5
  45. {issue_flow-0.4.4.post3 → issue_flow-0.4.5}/src/issue_flow/templates/skills/iflow_iflow/SKILL.md.j2 +9 -7
  46. issue_flow-0.4.5/src/issue_flow/templates/skills/iflow_issue/SKILL.md.j2 +63 -0
  47. {issue_flow-0.4.4.post3 → issue_flow-0.4.5}/src/issue_flow/templates/skills/iflow_pick/SKILL.md.j2 +3 -3
  48. {issue_flow-0.4.4.post3 → issue_flow-0.4.5}/src/issue_flow/templates/skills/iflow_plan/SKILL.md.j2 +4 -4
  49. issue_flow-0.4.5/src/issue_flow/templates/skills/iflow_review/SKILL.md.j2 +102 -0
  50. {issue_flow-0.4.4.post3 → issue_flow-0.4.5}/src/issue_flow/templates/skills/iflow_status/SKILL.md.j2 +2 -2
  51. {issue_flow-0.4.4.post3 → issue_flow-0.4.5}/src/issue_flow/templates/skills/iflow_yolo/SKILL.md.j2 +4 -4
  52. {issue_flow-0.4.4.post3 → issue_flow-0.4.5}/src/issue_flow/templating.py +45 -2
  53. {issue_flow-0.4.4.post3 → issue_flow-0.4.5}/src/issue_flow/tracking.py +259 -5
  54. issue_flow-0.4.4.post3/src/issue_flow/templates/skills/iflow_cleanup/SKILL.md.j2 +0 -47
  55. {issue_flow-0.4.4.post3 → issue_flow-0.4.5}/LICENSE +0 -0
  56. {issue_flow-0.4.4.post3 → issue_flow-0.4.5}/src/issue_flow/__init__.py +0 -0
  57. {issue_flow-0.4.4.post3 → issue_flow-0.4.5}/src/issue_flow/dependencies.py +0 -0
  58. {issue_flow-0.4.4.post3 → issue_flow-0.4.5}/src/issue_flow/editors.py +0 -0
  59. {issue_flow-0.4.4.post3 → issue_flow-0.4.5}/src/issue_flow/epicplan.py +0 -0
  60. {issue_flow-0.4.4.post3 → issue_flow-0.4.5}/src/issue_flow/graphify.py +0 -0
  61. {issue_flow-0.4.4.post3 → issue_flow-0.4.5}/src/issue_flow/project.py +0 -0
  62. {issue_flow-0.4.4.post3 → issue_flow-0.4.5}/src/issue_flow/py.typed +0 -0
  63. {issue_flow-0.4.4.post3 → issue_flow-0.4.5}/src/issue_flow/queueplan.py +0 -0
  64. {issue_flow-0.4.4.post3 → issue_flow-0.4.5}/src/issue_flow/step_profiles.py +0 -0
  65. {issue_flow-0.4.4.post3 → issue_flow-0.4.5}/src/issue_flow/templates/__init__.py +0 -0
  66. {issue_flow-0.4.4.post3 → issue_flow-0.4.5}/src/issue_flow/templates/commands/__init__.py +0 -0
  67. {issue_flow-0.4.4.post3 → issue_flow-0.4.5}/src/issue_flow/templates/commands/iflow-init.md.j2 +0 -0
  68. {issue_flow-0.4.4.post3 → issue_flow-0.4.5}/src/issue_flow/templates/commands/iflow-pause.md.j2 +0 -0
  69. {issue_flow-0.4.4.post3 → issue_flow-0.4.5}/src/issue_flow/templates/designs/python-quality-tools.md.j2 +0 -0
  70. {issue_flow-0.4.4.post3 → issue_flow-0.4.5}/src/issue_flow/templates/docs/__init__.py +0 -0
  71. {issue_flow-0.4.4.post3 → issue_flow-0.4.5}/src/issue_flow/templates/docs/this-project.md.j2 +0 -0
  72. {issue_flow-0.4.4.post3 → issue_flow-0.4.5}/src/issue_flow/templates/rules/AGENTS.md.j2 +0 -0
  73. {issue_flow-0.4.4.post3 → issue_flow-0.4.5}/src/issue_flow/templates/rules/CLAUDE.md.j2 +0 -0
  74. {issue_flow-0.4.4.post3 → issue_flow-0.4.5}/src/issue_flow/templates/rules/__init__.py +0 -0
  75. {issue_flow-0.4.4.post3 → issue_flow-0.4.5}/src/issue_flow/templates/rules/issueflow-rules.mdc.j2 +0 -0
  76. {issue_flow-0.4.4.post3 → issue_flow-0.4.5}/src/issue_flow/templates/skills/_invocation_forms.md.j2 +0 -0
  77. {issue_flow-0.4.4.post3 → issue_flow-0.4.5}/src/issue_flow/templates/skills/_model_directive.md.j2 +0 -0
  78. {issue_flow-0.4.4.post3 → issue_flow-0.4.5}/src/issue_flow/templates/skills/_resolve_project_root.md.j2 +0 -0
  79. {issue_flow-0.4.4.post3 → issue_flow-0.4.5}/src/issue_flow/templates/skills/caveman/SKILL.md.j2 +0 -0
  80. {issue_flow-0.4.4.post3 → issue_flow-0.4.5}/src/issue_flow/templates/skills/iflow_comments/SKILL.md.j2 +0 -0
  81. {issue_flow-0.4.4.post3 → issue_flow-0.4.5}/src/issue_flow/templates/skills/iflow_init/SKILL.md.j2 +0 -0
  82. {issue_flow-0.4.4.post3 → issue_flow-0.4.5}/src/issue_flow/templates/skills/iflow_pause/SKILL.md.j2 +0 -0
  83. {issue_flow-0.4.4.post3 → issue_flow-0.4.5}/src/issue_flow/templates/skills/iflow_version_bump/SKILL.md.j2 +0 -0
  84. {issue_flow-0.4.4.post3 → issue_flow-0.4.5}/src/issue_flow/templates/tools/README.md.j2 +0 -0
  85. {issue_flow-0.4.4.post3 → issue_flow-0.4.5}/src/issue_flow/versionplan.py +0 -0
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: issue-flow
3
- Version: 0.4.4.post3
3
+ Version: 0.4.5
4
4
  Summary: Agents should behave. Let them follow the issue flow.
5
5
  Keywords: cursor,ai,agents,issue-tracking,workflow
6
6
  Author: jepegit
@@ -57,7 +57,7 @@ your-project/
57
57
  05-epics/ # Staged epic plans (epic<N>_plan.md)
58
58
  .cursor/
59
59
  skills/ # Agent Skills (/iflow, /iflow-pick, /iflow-init,
60
- # /iflow-plan, /iflow-start, /iflow-close, ...)
60
+ # /iflow-plan, /iflow-build, /iflow-close, ...)
61
61
  rules/
62
62
  issueflow-rules.mdc # Always-on Cursor rule for the workflow
63
63
  AGENTS.md # Workflow rules (managed block; shared by all editors)
@@ -71,7 +71,7 @@ The Cursor Agent Skills give agents a repeatable flow and appear in the slash me
71
71
 
72
72
  1. `/iflow-init 42` or `iflow init 42` — pulls GitHub issue #42 into `.issueflows/01-current-issues/` and archives older issues.
73
73
  2. `iflow plan` or `/iflow-plan` — drafts `issue<N>_plan.md` (Goal / Constraints / Approach / Files to touch / Test strategy / Open questions) and stops for your confirmation.
74
- 3. `/iflow-start` — reads the confirmed plan and implements it. If no plan file exists, it offers to run `/iflow-plan` first, proceed without a plan, or abort.
74
+ 3. `/iflow-build` — reads the confirmed plan and implements it. If no plan file exists, it offers to run `/iflow-plan` first, proceed without a plan, or abort.
75
75
  4. `/iflow-close` — runs tests, optionally bumps version with `uv version --bump`, appends a `HISTORY.md` entry (or promotes `[Unreleased]` to a new release section on a bump), updates status files, commits, pushes, and opens a PR.
76
76
  5. `/iflow-cleanup` — after the PR merges, switches to the default branch, fast-forwards, prunes, and deletes the merged local branch.
77
77
 
@@ -80,12 +80,19 @@ Plus a few off-path commands:
80
80
  - `/iflow-pick` — **front door**: when you haven't chosen an issue yet, it helps pick one (parked work in `02-partly-solved-issues/` first, else open GitHub issues ranked by milestone, labels, and similarity to recently solved work), creates the `<N>-slug` branch, and runs `/iflow-init`. Pass `fix` to create a new general-fixes issue. Off-path; never auto-dispatched.
81
81
  - `/iflow` — **quick start**: inspects the current issue's state and dispatches to the right linear step automatically. A branch-derived number (`42-fix-login` → `N=42`) is authoritative, so `/iflow` works from a fresh branch too.
82
82
  - `/iflow-pause` — park the current issue in `02-partly-solved-issues/` with a **Remaining work** note; optional WIP commit + switch back to the default branch.
83
- - `/iflow-yolo` — all-in-one chain (`init → plan → start → close`) for small, low-risk issues, with up-front safeguards (refuses on the default branch, refuses with dirty unrelated changes, requires passing tests, single consolidated confirm).
83
+ - `/iflow-yolo` — all-in-one chain (`init → plan → build → close`) for small, low-risk issues, with up-front safeguards (refuses on the default branch, refuses with dirty unrelated changes, requires passing tests, single consolidated confirm).
84
84
  - `/iflow-fix` — interactive iterative-fixes session: creates one GitHub issue + long-lived branch, then loops over many small fixes (each gets a short plan, implemented only on confirmation and recorded in `issue<N>_status.md`), ending with `/iflow-close`. Coexists with `/iflow-pick fix` (the one-shot setup). Off-path; never auto-dispatched.
85
+ - `/iflow-issue` — create **one well-specified normal GitHub issue** (context / spec / acceptance criteria), then optionally branch + `/iflow-init` into the standard lifecycle. Use `/iflow-issue epic …` for an epic anchor. Off-path; never auto-dispatched.
85
86
  - `/iflow-status` — **read-only** overview of where every issue stands: the local tracking state (focus / parked / solved) plus open GitHub issues cross-referenced against it. Pass `local` to skip the GitHub query. Changes nothing; off-path; never auto-dispatched.
87
+ - `/iflow-epic` — plan a change too large for one issue as staged specs under `.issueflows/05-epics/`; `publish` creates a confirmed stage's GitHub issues behind one confirm. Off-path; never auto-dispatched.
88
+ - `/iflow-cycle` — batch-process a queue of yolo-fit issues under one up-front confirm (`yolo` / `label:<L>` / numbers / `epic <N>`). Off-path; never auto-dispatched.
89
+ - `/iflow-review` — review open GitHub issues and apply workflow labels (v1: the configured `yolo` label) behind one consolidated confirm. Off-path; never auto-dispatched.
90
+ - `/iflow-doctor` — scaffold health check (missing skills/commands, stale config). Off-path; never auto-dispatched.
86
91
  - `/iflow-archive` — **condense the solved archive (destructive, gated)**: summarises selected `issue<N>_*` groups under `03-solved-issues/` into a dated `YYYY-MM-DD_archived_issues.md` file. The summary records the pre-archive git ref so every original file stays recoverable (`git show <ref>:<path>`). Deletes the source files only after one consolidated confirm. Default: archive all but the **5 most recent** solved groups; pass `keep <K>`, an explicit list of issue numbers, or `all`. Requires a **clean working tree**. Off-path; never auto-dispatched.
87
92
 
88
- The **Agent Skills** under `.cursor/skills/` carry the workflows for on-demand use with `/iflow-pick`, `/iflow`, `/iflow-init`, `/iflow-plan`, `/iflow-start`, `/iflow-pause`, `/iflow-close`, `/iflow-cleanup`, `/iflow-yolo`, `/iflow-fix`, `/iflow-status`, `/iflow-archive`, `@iflow-version-bump` when you need only the bump steps, or `@iflow-history-update` when you need only the changelog update (see [Cursor Agent Skills](https://cursor.com/help/customization/skills)).
93
+ See the [docs](https://issue-flow.readthedocs.io/) for worked recipes (review cycle, epic publish, cycle queues).
94
+
95
+ The **Agent Skills** under `.cursor/skills/` carry the workflows for on-demand use with `/iflow-pick`, `/iflow`, `/iflow-init`, `/iflow-plan`, `/iflow-build`, `/iflow-pause`, `/iflow-close`, `/iflow-cleanup`, `/iflow-yolo`, `/iflow-fix`, `/iflow-issue`, `/iflow-status`, `/iflow-epic`, `/iflow-cycle`, `/iflow-review`, `/iflow-doctor`, `/iflow-archive`, `@iflow-version-bump` when you need only the bump steps, or `@iflow-history-update` when you need only the changelog update (see [Cursor Agent Skills](https://cursor.com/help/customization/skills)).
89
96
 
90
97
  ## Prerequisites
91
98
 
@@ -162,7 +169,7 @@ loads `.env` from the project root before invoking graphify — or export it in
162
169
  your shell environment. Cursor's own LLM is not available to subprocesses, so
163
170
  graphify needs its own backend. Other subcommands (`watch`, `cluster-only`, …)
164
171
  pass through too; trailing flags forward verbatim.
165
- - The scaffolded rules and `/iflow-start` mention `graphify-out/GRAPH_REPORT.md`
172
+ - The scaffolded rules and `/iflow-build` mention `graphify-out/GRAPH_REPORT.md`
166
173
  as a recommended pre-read when the file exists. `/iflow-graphify` is **off-path** —
167
174
  `/iflow` never auto-dispatches to it.
168
175
 
@@ -217,7 +224,7 @@ That's it. Open the project in Cursor and start with `/iflow` — or step throug
217
224
 
218
225
  1. `/iflow-init 42` — pulls GitHub issue #42 into `.issueflows/01-current-issues/` and archives older issues.
219
226
  2. `/iflow-plan` — drafts `issue<N>_plan.md` (Goal / Constraints / Approach / Files to touch / Test strategy / Open questions) and stops for your confirmation.
220
- 3. `/iflow-start` — reads the confirmed plan and implements it.
227
+ 3. `/iflow-build` — reads the confirmed plan and implements it.
221
228
  4. `/iflow-close` — runs tests, optionally bumps version, appends a `HISTORY.md` entry, updates status files, commits, pushes, and opens a PR.
222
229
  5. `/iflow-cleanup` — after the PR merges, switches to the default branch, fast-forwards, prunes, and deletes the merged local branch.
223
230
 
@@ -226,11 +233,19 @@ Plus a few off-path commands (never auto-dispatched):
226
233
  - `/iflow-pick` — **front door**: helps pick the next issue (parked work first, else open GitHub issues ranked by milestone, labels, and similarity to recent work), creates the branch, and runs `/iflow-init`.
227
234
  - `/iflow` — **quick start**: inspects the current issue's state and dispatches to the right linear step automatically (a branch-derived number like `42-fix-login` is authoritative).
228
235
  - `/iflow-pause` — park the current issue with a **Remaining work** note.
229
- - `/iflow-yolo` — all-in-one chain (`init → plan → start → close`) for small, low-risk issues, with up-front safeguards and a single consolidated confirm.
236
+ - `/iflow-yolo` — all-in-one chain (`init → plan → build → close`) for small, low-risk issues, with up-front safeguards and a single consolidated confirm.
230
237
  - `/iflow-fix` — interactive iterative-fixes session: one GitHub issue + long-lived branch, many small confirmed fixes.
238
+ - `/iflow-issue` — create one well-specified normal GitHub issue; optional branch + `/iflow-init`.
231
239
  - `/iflow-status` — **read-only** overview of where every issue stands, locally and on GitHub.
240
+ - `/iflow-epic` — staged epic plan + publish; decomposes into normal single-issue work.
241
+ - `/iflow-cycle` — batch yolo queue (`yolo` / `label:<L>` / numbers / epic).
242
+ - `/iflow-review` — propose and apply workflow labels on open issues (v1: `yolo`).
243
+ - `/iflow-doctor` — scaffold health check.
232
244
  - `/iflow-archive` — condense old solved-issue files into a dated summary (destructive, gated behind one consolidated confirm; originals stay recoverable via git).
233
245
 
246
+ Docs cover epics, cycles, and reviews with examples:
247
+ https://issue-flow.readthedocs.io/
248
+
234
249
  ## CLI overview
235
250
 
236
251
  ```
@@ -275,12 +290,75 @@ See [docs/developing.md](https://github.com/jepegit/issue-flow/blob/main/docs/de
275
290
 
276
291
  See [HISTORY.md](https://github.com/jepegit/issue-flow/blob/main/HISTORY.md) for release notes.
277
292
 
293
+ ## GitHub Actions sync
294
+
295
+ Sync `.issueflows/` folder placement (`01-current-issues` / `02-partly-solved-issues` /
296
+ `03-solved-issues`) to GitHub issue labels (one-way: files → GitHub).
297
+
298
+ **CLI (local or CI):**
299
+
300
+ ```bash
301
+ issue-flow sync # dry-run (shows planned label changes)
302
+ issue-flow sync --apply # push labels via gh
303
+ issue-flow sync --json # machine-readable report
304
+ ```
305
+
306
+ **Managed labels** (default prefix `status:`): `status:current`, `status:parked`,
307
+ `status:solved`. Only labels with that prefix are added/removed; other labels
308
+ (e.g. `yolo`) are left alone.
309
+
310
+ **Bootstrap labels once** (if they do not exist yet):
311
+
312
+ ```bash
313
+ gh label create 'status:current' --color 0E8A16
314
+ gh label create 'status:parked' --color FBCA04
315
+ gh label create 'status:solved' --color 6E7781
316
+ ```
317
+
318
+ By default, `issue-flow sync --apply` **auto-creates** any missing managed labels
319
+ (`bootstrap_labels = true` in `[issueflow.sync]`). Set `bootstrap_labels = false`
320
+ to keep the manual-only behaviour.
321
+
322
+ **Configuration** — optional `[issueflow.sync]` in `.issueflows/config.toml`:
323
+
324
+ ```toml
325
+ [issueflow.sync]
326
+ enabled = true
327
+ label_prefix = "status:"
328
+ labels = true
329
+ milestones = false
330
+ close_on_solved = false
331
+ bootstrap_labels = true
332
+
333
+ [issueflow.sync.milestone_map]
334
+ current = ""
335
+ parked = ""
336
+ solved = ""
337
+ ```
338
+
339
+ **Reusable workflow** — add a caller in your repo (pin to a release tag):
340
+
341
+ ```yaml
342
+ on:
343
+ push:
344
+ paths: ['.issueflows/**']
345
+ jobs:
346
+ sync:
347
+ uses: jepegit/issue-flow/.github/workflows/issue-flow-sync.yml@v0.4.4
348
+ with:
349
+ dry_run: false
350
+ secrets: inherit
351
+ ```
352
+
353
+ Requires `permissions: issues: write` on the job. The workflow installs
354
+ `issue-flow` from PyPI by default (`install_mode: pypi`); this repo dogfoods
355
+ with `install_mode: workspace` via [`.github/workflows/issueflow-sync.yml`](.github/workflows/issueflow-sync.yml).
356
+
278
357
  ## Future plans
279
358
 
280
359
  - **More editors** — extend `--editor` coverage to further AI coding tools (e.g. Windsurf) on top of the current Cursor / Claude Code / opencode / Codex support.
281
360
  - **Custom templates** — let users supply their own Jinja2 templates to tailor slash commands and rules to their team's conventions.
282
361
  - **Git hook integration** — optionally move issue files on commit based on status markers.
283
- - **GitHub Actions workflow** — ship a reusable action that syncs issue state between `.issueflows/` and GitHub issue labels/milestones.
284
362
 
285
363
  ## Acknowledgements
286
364
 
@@ -30,7 +30,7 @@ your-project/
30
30
  05-epics/ # Staged epic plans (epic<N>_plan.md)
31
31
  .cursor/
32
32
  skills/ # Agent Skills (/iflow, /iflow-pick, /iflow-init,
33
- # /iflow-plan, /iflow-start, /iflow-close, ...)
33
+ # /iflow-plan, /iflow-build, /iflow-close, ...)
34
34
  rules/
35
35
  issueflow-rules.mdc # Always-on Cursor rule for the workflow
36
36
  AGENTS.md # Workflow rules (managed block; shared by all editors)
@@ -44,7 +44,7 @@ The Cursor Agent Skills give agents a repeatable flow and appear in the slash me
44
44
 
45
45
  1. `/iflow-init 42` or `iflow init 42` — pulls GitHub issue #42 into `.issueflows/01-current-issues/` and archives older issues.
46
46
  2. `iflow plan` or `/iflow-plan` — drafts `issue<N>_plan.md` (Goal / Constraints / Approach / Files to touch / Test strategy / Open questions) and stops for your confirmation.
47
- 3. `/iflow-start` — reads the confirmed plan and implements it. If no plan file exists, it offers to run `/iflow-plan` first, proceed without a plan, or abort.
47
+ 3. `/iflow-build` — reads the confirmed plan and implements it. If no plan file exists, it offers to run `/iflow-plan` first, proceed without a plan, or abort.
48
48
  4. `/iflow-close` — runs tests, optionally bumps version with `uv version --bump`, appends a `HISTORY.md` entry (or promotes `[Unreleased]` to a new release section on a bump), updates status files, commits, pushes, and opens a PR.
49
49
  5. `/iflow-cleanup` — after the PR merges, switches to the default branch, fast-forwards, prunes, and deletes the merged local branch.
50
50
 
@@ -53,12 +53,19 @@ Plus a few off-path commands:
53
53
  - `/iflow-pick` — **front door**: when you haven't chosen an issue yet, it helps pick one (parked work in `02-partly-solved-issues/` first, else open GitHub issues ranked by milestone, labels, and similarity to recently solved work), creates the `<N>-slug` branch, and runs `/iflow-init`. Pass `fix` to create a new general-fixes issue. Off-path; never auto-dispatched.
54
54
  - `/iflow` — **quick start**: inspects the current issue's state and dispatches to the right linear step automatically. A branch-derived number (`42-fix-login` → `N=42`) is authoritative, so `/iflow` works from a fresh branch too.
55
55
  - `/iflow-pause` — park the current issue in `02-partly-solved-issues/` with a **Remaining work** note; optional WIP commit + switch back to the default branch.
56
- - `/iflow-yolo` — all-in-one chain (`init → plan → start → close`) for small, low-risk issues, with up-front safeguards (refuses on the default branch, refuses with dirty unrelated changes, requires passing tests, single consolidated confirm).
56
+ - `/iflow-yolo` — all-in-one chain (`init → plan → build → close`) for small, low-risk issues, with up-front safeguards (refuses on the default branch, refuses with dirty unrelated changes, requires passing tests, single consolidated confirm).
57
57
  - `/iflow-fix` — interactive iterative-fixes session: creates one GitHub issue + long-lived branch, then loops over many small fixes (each gets a short plan, implemented only on confirmation and recorded in `issue<N>_status.md`), ending with `/iflow-close`. Coexists with `/iflow-pick fix` (the one-shot setup). Off-path; never auto-dispatched.
58
+ - `/iflow-issue` — create **one well-specified normal GitHub issue** (context / spec / acceptance criteria), then optionally branch + `/iflow-init` into the standard lifecycle. Use `/iflow-issue epic …` for an epic anchor. Off-path; never auto-dispatched.
58
59
  - `/iflow-status` — **read-only** overview of where every issue stands: the local tracking state (focus / parked / solved) plus open GitHub issues cross-referenced against it. Pass `local` to skip the GitHub query. Changes nothing; off-path; never auto-dispatched.
60
+ - `/iflow-epic` — plan a change too large for one issue as staged specs under `.issueflows/05-epics/`; `publish` creates a confirmed stage's GitHub issues behind one confirm. Off-path; never auto-dispatched.
61
+ - `/iflow-cycle` — batch-process a queue of yolo-fit issues under one up-front confirm (`yolo` / `label:<L>` / numbers / `epic <N>`). Off-path; never auto-dispatched.
62
+ - `/iflow-review` — review open GitHub issues and apply workflow labels (v1: the configured `yolo` label) behind one consolidated confirm. Off-path; never auto-dispatched.
63
+ - `/iflow-doctor` — scaffold health check (missing skills/commands, stale config). Off-path; never auto-dispatched.
59
64
  - `/iflow-archive` — **condense the solved archive (destructive, gated)**: summarises selected `issue<N>_*` groups under `03-solved-issues/` into a dated `YYYY-MM-DD_archived_issues.md` file. The summary records the pre-archive git ref so every original file stays recoverable (`git show <ref>:<path>`). Deletes the source files only after one consolidated confirm. Default: archive all but the **5 most recent** solved groups; pass `keep <K>`, an explicit list of issue numbers, or `all`. Requires a **clean working tree**. Off-path; never auto-dispatched.
60
65
 
61
- The **Agent Skills** under `.cursor/skills/` carry the workflows for on-demand use with `/iflow-pick`, `/iflow`, `/iflow-init`, `/iflow-plan`, `/iflow-start`, `/iflow-pause`, `/iflow-close`, `/iflow-cleanup`, `/iflow-yolo`, `/iflow-fix`, `/iflow-status`, `/iflow-archive`, `@iflow-version-bump` when you need only the bump steps, or `@iflow-history-update` when you need only the changelog update (see [Cursor Agent Skills](https://cursor.com/help/customization/skills)).
66
+ See the [docs](https://issue-flow.readthedocs.io/) for worked recipes (review cycle, epic publish, cycle queues).
67
+
68
+ The **Agent Skills** under `.cursor/skills/` carry the workflows for on-demand use with `/iflow-pick`, `/iflow`, `/iflow-init`, `/iflow-plan`, `/iflow-build`, `/iflow-pause`, `/iflow-close`, `/iflow-cleanup`, `/iflow-yolo`, `/iflow-fix`, `/iflow-issue`, `/iflow-status`, `/iflow-epic`, `/iflow-cycle`, `/iflow-review`, `/iflow-doctor`, `/iflow-archive`, `@iflow-version-bump` when you need only the bump steps, or `@iflow-history-update` when you need only the changelog update (see [Cursor Agent Skills](https://cursor.com/help/customization/skills)).
62
69
 
63
70
  ## Prerequisites
64
71
 
@@ -135,7 +142,7 @@ loads `.env` from the project root before invoking graphify — or export it in
135
142
  your shell environment. Cursor's own LLM is not available to subprocesses, so
136
143
  graphify needs its own backend. Other subcommands (`watch`, `cluster-only`, …)
137
144
  pass through too; trailing flags forward verbatim.
138
- - The scaffolded rules and `/iflow-start` mention `graphify-out/GRAPH_REPORT.md`
145
+ - The scaffolded rules and `/iflow-build` mention `graphify-out/GRAPH_REPORT.md`
139
146
  as a recommended pre-read when the file exists. `/iflow-graphify` is **off-path** —
140
147
  `/iflow` never auto-dispatches to it.
141
148
 
@@ -190,7 +197,7 @@ That's it. Open the project in Cursor and start with `/iflow` — or step throug
190
197
 
191
198
  1. `/iflow-init 42` — pulls GitHub issue #42 into `.issueflows/01-current-issues/` and archives older issues.
192
199
  2. `/iflow-plan` — drafts `issue<N>_plan.md` (Goal / Constraints / Approach / Files to touch / Test strategy / Open questions) and stops for your confirmation.
193
- 3. `/iflow-start` — reads the confirmed plan and implements it.
200
+ 3. `/iflow-build` — reads the confirmed plan and implements it.
194
201
  4. `/iflow-close` — runs tests, optionally bumps version, appends a `HISTORY.md` entry, updates status files, commits, pushes, and opens a PR.
195
202
  5. `/iflow-cleanup` — after the PR merges, switches to the default branch, fast-forwards, prunes, and deletes the merged local branch.
196
203
 
@@ -199,11 +206,19 @@ Plus a few off-path commands (never auto-dispatched):
199
206
  - `/iflow-pick` — **front door**: helps pick the next issue (parked work first, else open GitHub issues ranked by milestone, labels, and similarity to recent work), creates the branch, and runs `/iflow-init`.
200
207
  - `/iflow` — **quick start**: inspects the current issue's state and dispatches to the right linear step automatically (a branch-derived number like `42-fix-login` is authoritative).
201
208
  - `/iflow-pause` — park the current issue with a **Remaining work** note.
202
- - `/iflow-yolo` — all-in-one chain (`init → plan → start → close`) for small, low-risk issues, with up-front safeguards and a single consolidated confirm.
209
+ - `/iflow-yolo` — all-in-one chain (`init → plan → build → close`) for small, low-risk issues, with up-front safeguards and a single consolidated confirm.
203
210
  - `/iflow-fix` — interactive iterative-fixes session: one GitHub issue + long-lived branch, many small confirmed fixes.
211
+ - `/iflow-issue` — create one well-specified normal GitHub issue; optional branch + `/iflow-init`.
204
212
  - `/iflow-status` — **read-only** overview of where every issue stands, locally and on GitHub.
213
+ - `/iflow-epic` — staged epic plan + publish; decomposes into normal single-issue work.
214
+ - `/iflow-cycle` — batch yolo queue (`yolo` / `label:<L>` / numbers / epic).
215
+ - `/iflow-review` — propose and apply workflow labels on open issues (v1: `yolo`).
216
+ - `/iflow-doctor` — scaffold health check.
205
217
  - `/iflow-archive` — condense old solved-issue files into a dated summary (destructive, gated behind one consolidated confirm; originals stay recoverable via git).
206
218
 
219
+ Docs cover epics, cycles, and reviews with examples:
220
+ https://issue-flow.readthedocs.io/
221
+
207
222
  ## CLI overview
208
223
 
209
224
  ```
@@ -248,12 +263,75 @@ See [docs/developing.md](https://github.com/jepegit/issue-flow/blob/main/docs/de
248
263
 
249
264
  See [HISTORY.md](https://github.com/jepegit/issue-flow/blob/main/HISTORY.md) for release notes.
250
265
 
266
+ ## GitHub Actions sync
267
+
268
+ Sync `.issueflows/` folder placement (`01-current-issues` / `02-partly-solved-issues` /
269
+ `03-solved-issues`) to GitHub issue labels (one-way: files → GitHub).
270
+
271
+ **CLI (local or CI):**
272
+
273
+ ```bash
274
+ issue-flow sync # dry-run (shows planned label changes)
275
+ issue-flow sync --apply # push labels via gh
276
+ issue-flow sync --json # machine-readable report
277
+ ```
278
+
279
+ **Managed labels** (default prefix `status:`): `status:current`, `status:parked`,
280
+ `status:solved`. Only labels with that prefix are added/removed; other labels
281
+ (e.g. `yolo`) are left alone.
282
+
283
+ **Bootstrap labels once** (if they do not exist yet):
284
+
285
+ ```bash
286
+ gh label create 'status:current' --color 0E8A16
287
+ gh label create 'status:parked' --color FBCA04
288
+ gh label create 'status:solved' --color 6E7781
289
+ ```
290
+
291
+ By default, `issue-flow sync --apply` **auto-creates** any missing managed labels
292
+ (`bootstrap_labels = true` in `[issueflow.sync]`). Set `bootstrap_labels = false`
293
+ to keep the manual-only behaviour.
294
+
295
+ **Configuration** — optional `[issueflow.sync]` in `.issueflows/config.toml`:
296
+
297
+ ```toml
298
+ [issueflow.sync]
299
+ enabled = true
300
+ label_prefix = "status:"
301
+ labels = true
302
+ milestones = false
303
+ close_on_solved = false
304
+ bootstrap_labels = true
305
+
306
+ [issueflow.sync.milestone_map]
307
+ current = ""
308
+ parked = ""
309
+ solved = ""
310
+ ```
311
+
312
+ **Reusable workflow** — add a caller in your repo (pin to a release tag):
313
+
314
+ ```yaml
315
+ on:
316
+ push:
317
+ paths: ['.issueflows/**']
318
+ jobs:
319
+ sync:
320
+ uses: jepegit/issue-flow/.github/workflows/issue-flow-sync.yml@v0.4.4
321
+ with:
322
+ dry_run: false
323
+ secrets: inherit
324
+ ```
325
+
326
+ Requires `permissions: issues: write` on the job. The workflow installs
327
+ `issue-flow` from PyPI by default (`install_mode: pypi`); this repo dogfoods
328
+ with `install_mode: workspace` via [`.github/workflows/issueflow-sync.yml`](.github/workflows/issueflow-sync.yml).
329
+
251
330
  ## Future plans
252
331
 
253
332
  - **More editors** — extend `--editor` coverage to further AI coding tools (e.g. Windsurf) on top of the current Cursor / Claude Code / opencode / Codex support.
254
333
  - **Custom templates** — let users supply their own Jinja2 templates to tailor slash commands and rules to their team's conventions.
255
334
  - **Git hook integration** — optionally move issue files on commit based on status markers.
256
- - **GitHub Actions workflow** — ship a reusable action that syncs issue state between `.issueflows/` and GitHub issue labels/milestones.
257
335
 
258
336
  ## Acknowledgements
259
337
 
@@ -1,6 +1,6 @@
1
1
  [project]
2
2
  name = "issue-flow"
3
- version = "0.4.4.post3"
3
+ version = "0.4.5"
4
4
  description = "Agents should behave. Let them follow the issue flow."
5
5
  readme = "README.md"
6
6
  license = "MIT"