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.
- {issue_flow-0.4.4.post3 → issue_flow-0.4.5}/PKG-INFO +87 -9
- {issue_flow-0.4.4.post3 → issue_flow-0.4.5}/README.md +86 -8
- {issue_flow-0.4.4.post3 → issue_flow-0.4.5}/pyproject.toml +1 -1
- {issue_flow-0.4.4.post3 → issue_flow-0.4.5}/src/issue_flow/agent.py +576 -19
- {issue_flow-0.4.4.post3 → issue_flow-0.4.5}/src/issue_flow/cli.py +278 -6
- {issue_flow-0.4.4.post3 → issue_flow-0.4.5}/src/issue_flow/config.py +223 -0
- issue_flow-0.4.5/src/issue_flow/console_io.py +7 -0
- issue_flow-0.4.5/src/issue_flow/convert.py +136 -0
- {issue_flow-0.4.4.post3 → issue_flow-0.4.5}/src/issue_flow/gitutils.py +266 -2
- {issue_flow-0.4.4.post3 → issue_flow-0.4.5}/src/issue_flow/init.py +143 -113
- {issue_flow-0.4.4.post3 → issue_flow-0.4.5}/src/issue_flow/modes.py +383 -0
- {issue_flow-0.4.4.post3 → issue_flow-0.4.5}/src/issue_flow/modes.toml +2 -2
- {issue_flow-0.4.4.post3 → issue_flow-0.4.5}/src/issue_flow/step_profiles.toml +4 -1
- issue_flow-0.4.5/src/issue_flow/surfaces.py +330 -0
- issue_flow-0.4.5/src/issue_flow/sync.py +510 -0
- {issue_flow-0.4.4.post3 → issue_flow-0.4.5}/src/issue_flow/templates/commands/iflow-archive.md.j2 +1 -1
- 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
- {issue_flow-0.4.4.post3 → issue_flow-0.4.5}/src/issue_flow/templates/commands/iflow-cleanup.md.j2 +21 -7
- {issue_flow-0.4.4.post3 → issue_flow-0.4.5}/src/issue_flow/templates/commands/iflow-close.md.j2 +34 -20
- {issue_flow-0.4.4.post3 → issue_flow-0.4.5}/src/issue_flow/templates/commands/iflow-cycle.md.j2 +11 -6
- issue_flow-0.4.5/src/issue_flow/templates/commands/iflow-doctor.md.j2 +47 -0
- {issue_flow-0.4.4.post3 → issue_flow-0.4.5}/src/issue_flow/templates/commands/iflow-epic.md.j2 +1 -1
- {issue_flow-0.4.4.post3 → issue_flow-0.4.5}/src/issue_flow/templates/commands/iflow-fix.md.j2 +5 -4
- {issue_flow-0.4.4.post3 → issue_flow-0.4.5}/src/issue_flow/templates/commands/iflow-graphify.md.j2 +1 -1
- issue_flow-0.4.5/src/issue_flow/templates/commands/iflow-issue.md.j2 +61 -0
- {issue_flow-0.4.4.post3 → issue_flow-0.4.5}/src/issue_flow/templates/commands/iflow-pick.md.j2 +2 -2
- {issue_flow-0.4.4.post3 → issue_flow-0.4.5}/src/issue_flow/templates/commands/iflow-plan.md.j2 +5 -5
- issue_flow-0.4.5/src/issue_flow/templates/commands/iflow-review.md.j2 +80 -0
- {issue_flow-0.4.4.post3 → issue_flow-0.4.5}/src/issue_flow/templates/commands/iflow-status.md.j2 +2 -2
- {issue_flow-0.4.4.post3 → issue_flow-0.4.5}/src/issue_flow/templates/commands/iflow-yolo.md.j2 +6 -5
- {issue_flow-0.4.4.post3 → issue_flow-0.4.5}/src/issue_flow/templates/commands/iflow.md.j2 +12 -11
- {issue_flow-0.4.4.post3 → issue_flow-0.4.5}/src/issue_flow/templates/docs/issue-workflow.md.j2 +169 -30
- {issue_flow-0.4.4.post3 → issue_flow-0.4.5}/src/issue_flow/templates/rules/_body.md.j2 +21 -13
- {issue_flow-0.4.4.post3 → issue_flow-0.4.5}/src/issue_flow/templates/skills/grill_me/SKILL.md.j2 +1 -1
- {issue_flow-0.4.4.post3 → issue_flow-0.4.5}/src/issue_flow/templates/skills/iflow_archive/SKILL.md.j2 +1 -1
- {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
- issue_flow-0.4.5/src/issue_flow/templates/skills/iflow_cleanup/SKILL.md.j2 +67 -0
- {issue_flow-0.4.4.post3 → issue_flow-0.4.5}/src/issue_flow/templates/skills/iflow_close/SKILL.md.j2 +19 -10
- {issue_flow-0.4.4.post3 → issue_flow-0.4.5}/src/issue_flow/templates/skills/iflow_cycle/SKILL.md.j2 +22 -6
- issue_flow-0.4.5/src/issue_flow/templates/skills/iflow_doctor/SKILL.md.j2 +56 -0
- {issue_flow-0.4.4.post3 → issue_flow-0.4.5}/src/issue_flow/templates/skills/iflow_epic/SKILL.md.j2 +2 -2
- {issue_flow-0.4.4.post3 → issue_flow-0.4.5}/src/issue_flow/templates/skills/iflow_fix/SKILL.md.j2 +5 -5
- {issue_flow-0.4.4.post3 → issue_flow-0.4.5}/src/issue_flow/templates/skills/iflow_graphify/SKILL.md.j2 +1 -1
- {issue_flow-0.4.4.post3 → issue_flow-0.4.5}/src/issue_flow/templates/skills/iflow_history_update/SKILL.md.j2 +10 -5
- {issue_flow-0.4.4.post3 → issue_flow-0.4.5}/src/issue_flow/templates/skills/iflow_iflow/SKILL.md.j2 +9 -7
- issue_flow-0.4.5/src/issue_flow/templates/skills/iflow_issue/SKILL.md.j2 +63 -0
- {issue_flow-0.4.4.post3 → issue_flow-0.4.5}/src/issue_flow/templates/skills/iflow_pick/SKILL.md.j2 +3 -3
- {issue_flow-0.4.4.post3 → issue_flow-0.4.5}/src/issue_flow/templates/skills/iflow_plan/SKILL.md.j2 +4 -4
- issue_flow-0.4.5/src/issue_flow/templates/skills/iflow_review/SKILL.md.j2 +102 -0
- {issue_flow-0.4.4.post3 → issue_flow-0.4.5}/src/issue_flow/templates/skills/iflow_status/SKILL.md.j2 +2 -2
- {issue_flow-0.4.4.post3 → issue_flow-0.4.5}/src/issue_flow/templates/skills/iflow_yolo/SKILL.md.j2 +4 -4
- {issue_flow-0.4.4.post3 → issue_flow-0.4.5}/src/issue_flow/templating.py +45 -2
- {issue_flow-0.4.4.post3 → issue_flow-0.4.5}/src/issue_flow/tracking.py +259 -5
- issue_flow-0.4.4.post3/src/issue_flow/templates/skills/iflow_cleanup/SKILL.md.j2 +0 -47
- {issue_flow-0.4.4.post3 → issue_flow-0.4.5}/LICENSE +0 -0
- {issue_flow-0.4.4.post3 → issue_flow-0.4.5}/src/issue_flow/__init__.py +0 -0
- {issue_flow-0.4.4.post3 → issue_flow-0.4.5}/src/issue_flow/dependencies.py +0 -0
- {issue_flow-0.4.4.post3 → issue_flow-0.4.5}/src/issue_flow/editors.py +0 -0
- {issue_flow-0.4.4.post3 → issue_flow-0.4.5}/src/issue_flow/epicplan.py +0 -0
- {issue_flow-0.4.4.post3 → issue_flow-0.4.5}/src/issue_flow/graphify.py +0 -0
- {issue_flow-0.4.4.post3 → issue_flow-0.4.5}/src/issue_flow/project.py +0 -0
- {issue_flow-0.4.4.post3 → issue_flow-0.4.5}/src/issue_flow/py.typed +0 -0
- {issue_flow-0.4.4.post3 → issue_flow-0.4.5}/src/issue_flow/queueplan.py +0 -0
- {issue_flow-0.4.4.post3 → issue_flow-0.4.5}/src/issue_flow/step_profiles.py +0 -0
- {issue_flow-0.4.4.post3 → issue_flow-0.4.5}/src/issue_flow/templates/__init__.py +0 -0
- {issue_flow-0.4.4.post3 → issue_flow-0.4.5}/src/issue_flow/templates/commands/__init__.py +0 -0
- {issue_flow-0.4.4.post3 → issue_flow-0.4.5}/src/issue_flow/templates/commands/iflow-init.md.j2 +0 -0
- {issue_flow-0.4.4.post3 → issue_flow-0.4.5}/src/issue_flow/templates/commands/iflow-pause.md.j2 +0 -0
- {issue_flow-0.4.4.post3 → issue_flow-0.4.5}/src/issue_flow/templates/designs/python-quality-tools.md.j2 +0 -0
- {issue_flow-0.4.4.post3 → issue_flow-0.4.5}/src/issue_flow/templates/docs/__init__.py +0 -0
- {issue_flow-0.4.4.post3 → issue_flow-0.4.5}/src/issue_flow/templates/docs/this-project.md.j2 +0 -0
- {issue_flow-0.4.4.post3 → issue_flow-0.4.5}/src/issue_flow/templates/rules/AGENTS.md.j2 +0 -0
- {issue_flow-0.4.4.post3 → issue_flow-0.4.5}/src/issue_flow/templates/rules/CLAUDE.md.j2 +0 -0
- {issue_flow-0.4.4.post3 → issue_flow-0.4.5}/src/issue_flow/templates/rules/__init__.py +0 -0
- {issue_flow-0.4.4.post3 → issue_flow-0.4.5}/src/issue_flow/templates/rules/issueflow-rules.mdc.j2 +0 -0
- {issue_flow-0.4.4.post3 → issue_flow-0.4.5}/src/issue_flow/templates/skills/_invocation_forms.md.j2 +0 -0
- {issue_flow-0.4.4.post3 → issue_flow-0.4.5}/src/issue_flow/templates/skills/_model_directive.md.j2 +0 -0
- {issue_flow-0.4.4.post3 → issue_flow-0.4.5}/src/issue_flow/templates/skills/_resolve_project_root.md.j2 +0 -0
- {issue_flow-0.4.4.post3 → issue_flow-0.4.5}/src/issue_flow/templates/skills/caveman/SKILL.md.j2 +0 -0
- {issue_flow-0.4.4.post3 → issue_flow-0.4.5}/src/issue_flow/templates/skills/iflow_comments/SKILL.md.j2 +0 -0
- {issue_flow-0.4.4.post3 → issue_flow-0.4.5}/src/issue_flow/templates/skills/iflow_init/SKILL.md.j2 +0 -0
- {issue_flow-0.4.4.post3 → issue_flow-0.4.5}/src/issue_flow/templates/skills/iflow_pause/SKILL.md.j2 +0 -0
- {issue_flow-0.4.4.post3 → issue_flow-0.4.5}/src/issue_flow/templates/skills/iflow_version_bump/SKILL.md.j2 +0 -0
- {issue_flow-0.4.4.post3 → issue_flow-0.4.5}/src/issue_flow/templates/tools/README.md.j2 +0 -0
- {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.
|
|
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-
|
|
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-
|
|
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 →
|
|
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
|
-
|
|
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-
|
|
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-
|
|
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 →
|
|
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-
|
|
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-
|
|
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 →
|
|
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
|
-
|
|
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-
|
|
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-
|
|
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 →
|
|
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
|
|