Cursor issue workflow (Agent Skills)¶

This repo uses Cursor Agent Skills under .cursor/skills/ that line up with how we track GitHub issues in .issueflows/01-current-issues/. Skills appear in the slash menu as /iflow, /iflow-plan, and friends — or type iflow plan (space, no slash) in chat when / is awkward on your keyboard.

Keyboard-friendly chat: type iflow plan, iflow pick, iflow close, etc. in chat (letters + space only). Slash menu still uses /iflow-plan. Hyphen form iflow-plan also works. Norwegian and similar layouts often lack a dedicated / key; @ is awkward too — the space form is intentional.

Quick start: type iflow in chat or run /iflow from the slash menu. It inspects the state of the focus issue and dispatches to the right linear-flow skill (iflow init / /iflow-init, iflow plan / /iflow-plan, iflow build / /iflow-build, or iflow close / /iflow-close) — so you don't have to remember which step is next. Haven't chosen an issue yet? Start with iflow pick or /iflow-pick.

issue-flow init also creates a durable project brief at .issueflows/04-designs-and-guides/this-project.md when it is missing. Edit it by hand with project-specific context; issue-flow update and issue-flow init --force leave existing content untouched.

It also seeds .issueflows/00-tools/README.md — the index of the project's shared toolbox. Drop reusable helper scripts there during issue work and add a one-line index entry; check the folder before writing a new one-off helper. Like the project brief, this README is never overwritten by issue-flow update, so its index grows over time.

Multi-root workspaces: when several sibling repos share one editor workspace, resolve the target repo first (root: / repo: hints, or issue-flow agent resolve). A workspace-root issueflow-workspace.toml (create it with issue-flow workspace init) can name a default member repo used when a command runs from outside any single scaffold. Never let git or gh infer the repository from cwd alone. See .issueflows/04-designs-and-guides/multi-repo-workspaces.md when present.

Agent Skills¶

issue-flow init / issue-flow update install Cursor Agent Skills under .cursor/skills/ — longer, on-demand playbooks (plus a small helper for version bumps):

Each skill sets disable-model-invocation: true so it is included when you explicitly invoke it, not on every chat. Every rendered SKILL.md also carries issue-flow-version: <version> in its YAML frontmatter (the package version at last issue-flow init / issue-flow update). Compare with issue-flow --version; if they differ, re-run issue-flow update. See Agent Skills in the Cursor docs.

Lifecycle skills also carry a ### MODEL & EXECUTION DIRECTIVE — economy (speed/token savings) or reasoning (design depth) — baked at issue-flow update from [issueflow] / [issueflow.step_profiles] in .issueflows/config.toml. /iflow-pick can announce label-based session overrides when model_label_flows is enabled (deep_model_label / fast_model_label).

Branch and folder hygiene¶

Two recurring pain points the workflows actively help with:

• Stale local branches that look "several commits ahead of main" after a merged PR. /iflow-close switches back to the default branch after opening or updating the PR when the tree is clean, unless you pass stay / don't switch. /iflow-cleanup detects merge status after the PR is merged and offers (with one consolidated confirm) to git fetch --prune and run git branch -d on every local branch whose commits are already in the default branch (including squash merges). Destructive flags like -D are never used automatically.
• Left-overs in .issueflows/01-current-issues/. Both /iflow-init (when a new issue is captured) and /iflow-build (before implementation begins) sweep that folder: every issue<n>_* group other than the focus issue is moved automatically to .issueflows/03-solved-issues/ if a status file contains - [x] Done, otherwise to .issueflows/02-partly-solved-issues/.

All workflows that touch git also run a short branch-status preflight: git fetch --prune, current branch, ahead/behind vs the default branch, and a warning when the current branch's leading digits refer to an issue already archived in 02-/03-.

0a. /iflow-pick — choose the next issue (front door)¶

When: You are on the default branch with nothing in progress and want help deciding what to work on next.

What you pass: Nothing (survey + ask), fix (create a new general-fixes issue every time), or a hint (milestone v0.4, a topic) to bias ranking.

What the assistant does (three phases):

1. Choose. Prefers parked work in .issueflows/02-partly-solved-issues/; otherwise lists open GitHub issues (gh issue list) ranked by milestone, labels, and topical similarity to recently solved issues, then asks you to confirm a pick from a short shortlist. fix skips the survey and creates a new chore: general fixes issue.
2. Branch. Requires a clean tree, branches off the default with the GitHub numeric convention git switch -c <N>-<short-slug>, then runs the /iflow-init flow automatically for <N>.
3. Hand off. Asks whether to continue with /iflow-plan (never auto-runs it).

Out of scope (Phase B follow-up): automated breakdown of an over-large issue into sub-issues created on GitHub and parked under 02-partly-solved-issues/. /iflow-pick only mentions the option for now.

Off-path: /iflow never auto-dispatches to /iflow-pick; it creates GitHub issues and branches, so you opt in explicitly.

Result: A chosen issue captured on a fresh <N>-<slug> branch, ready for /iflow-plan.

0. /iflow — smart dispatcher (quick start)¶

When: Any time you want the next right step without remembering which specific command applies.

What you pass: Nothing, or the same arguments the target command would take (e.g. /iflow 42 on a fresh branch, /iflow bump minor when the issue is done). /iflow forwards the trailing text verbatim.

How it decides:

Focus-issue resolution: prefer the leading digits of the current branch when it matches ^<N>-.+; else the single group in .issueflows/01-current-issues/; else ask.

Not auto-dispatched: /iflow-pause, /iflow-cleanup, /iflow-yolo, /iflow-fix, /iflow-issue, /iflow-status, /iflow-doctor, /iflow-review, /iflow-epic, /iflow-cycle, /iflow-auto, and /iflow-archive. /iflow will mention them in its output when relevant (e.g. "after the PR merges, run /iflow-cleanup") but never picks them for you.

Result: One of the four linear commands runs, with its own normal checkpoints intact.

1. /iflow-init — capture the issue locally¶

When: You have a GitHub issue you want to work on (or archive older "current" issues before starting a new one).

What you pass: Either an issue number (e.g. 42), a full GitHub issue URL, or nothing after /iflow-init—in that case, on a branch named like 42-short-description, the assistant may ask to use #42 from the branch (and refuses to guess on main/master). The assistant resolves owner/repo from git remote origin when you only pass a number.

What happens:

• The assistant uses GitHub CLI (gh) to fetch title, body, URL, and number. You need gh authenticated (gh auth login if needed).
• It creates .issueflows/01-current-issues/issue<number>_original.md with the title, source URL, and the exact issue body from GitHub.
• Archive: Other files already in .issueflows/01-current-issues/ (grouped by issue number, e.g. issue121_*) may be moved to .issueflows/02-partly-solved-issues/ or .issueflows/03-solved-issues/, based on whether a status file for that issue contains a checked Done line (- [x] Done). The new issue's files are never moved as part of this step.
• If the target issue<number>_original.md already exists, the assistant should not overwrite it without asking.

Result: One canonical "original issue" file under .issueflows/01-current-issues/ plus optional archive moves.

2. /iflow-plan — design the approach¶

When: The issue is captured (*_original.md exists) and you want a confirmed plan before any code changes.

What you pass: Optional free-form hints (constraints, design preferences).

What the assistant does:

1. Finds the focus issue in .issueflows/01-current-issues/.
2. Runs the branch-status preflight (non-destructive).
3. Reads the original issue and any prior status; reads .issueflows/04-designs-and-guides/this-project.md when present and consults other files under .issueflows/04-designs-and-guides/ when relevant.
4. Prior-art discovery — skim .issueflows/00-tools/ for an existing helper; if graphify-out/GRAPH_REPORT.md exists, skim God Nodes / Communities / Suggested Questions for the affected area; grep for adjacent helpers; record findings under ### Prior art in ## Constraints (or - None found (toolbox + grep + graph checked).). Strong overlaps become Open questions.
5. Explores read-only, then writes issue<N>_plan.md with sections: Goal, Constraints (including Prior art), Approach, Files to touch, Test strategy, Open questions.
6. Runs a scope check — if the change is broad, proposes splitting into smaller issues or phases.
7. Stops and asks for explicit confirmation: accept, revise, or abort. /iflow-plan never implements code itself.

Result: A confirmed issue<N>_plan.md ready for /iflow-build to execute.

3. /iflow-build — implement the plan¶

When: The issue has a confirmed issue<N>_plan.md (from /iflow-plan) and you are ready to code.

What you pass: Optional implementation hints. Early-PR tokens: early / pr (force on), noearly (force off). Precedence: trailing > baked [issueflow].early_pr (default False) > false.

What the assistant does:

1. Confirms which issue file applies if several exist or things are ambiguous.
2. Branch status preflight — git fetch --prune, report current branch and ahead/behind vs the default branch, warn if the current branch looks stale or if you are still on the default branch.
3. Sweeps stale current issues — moves every issue<n>_* group other than the focus issue to .issueflows/03-solved-issues/ (done) or .issueflows/02-partly-solved-issues/ (not done).
4. Plan precondition — reads issue<N>_plan.md. If missing, asks the user to choose: run /iflow-plan now, proceed without a plan (note in status file), or abort. Does not hard-stop.
5. Seeds issue<N>_status.md up front (unchecked - [ ] Done, What's done / Remaining work) and keeps it current as work progresses — it lives during the work, not just at close.
6. Implements the plan, using .issueflows/04-designs-and-guides/this-project.md and relevant design docs for project context when present. Reuses helpers from .issueflows/00-tools/ and contributes new reusable ones back there.
7. Early pull request (optional) — when early PR is on, after the first successful push: gh pr list then gh pr create --draft with Refs #N; record the PR in the status file. Does not write HISTORY.md (close owns that).

Result: Implementation aligned with the confirmed plan and project rules (tests with uv run, dependency management with uv, etc.), optionally with a draft PR already open.

4. /iflow-pause — park work safely¶

When: You need to stop partway through an issue (context switch, blocked on input) without closing it.

What you pass: Optional short note that becomes the Remaining work text.

What the assistant does:

1. Updates issue<N>_status.md with Done so far, Remaining work, and Paused on sections. The - [ ] Done checkbox stays unchecked.
2. Moves the whole issue<N>_* group from .issueflows/01-current-issues/ to .issueflows/02-partly-solved-issues/.
3. Offers, as one consolidated prompt, a WIP commit and/or git switch <default>. Never deletes branches, never force-pushes, never runs tests.

Result: The issue is safely archived under 02-partly-solved-issues/ with clear resume notes. Re-open via /iflow-init <N> (which will ask for the archived-issue confirmation).

5. /iflow-close — land the work¶

When: Implementation is done and you want to ship (commit, push, PR). Post-merge branch cleanup is a separate step — see /iflow-cleanup below.

What you pass: Optional notes (branch name, PR title, draft PR, or "skip issue doc update"). You can also ask for a semver bump in the same line, for example:

• /iflow-close bump — pre-release-aware default: stays on the current channel (alpha→alpha, beta→beta, rc→rc, dev→dev) or patch when the version is already stable.
• /iflow-close <level> — any uv level: patch, minor, major, stable, alpha, beta, rc, post, dev (e.g. /iflow-close minor, /iflow-close beta). dev must be paired, e.g. /iflow-close bump patch dev.
• Free text that clearly describes the bump level — the assistant infers the level (e.g. "bugfix release" → patch, "promote to beta" → beta); it never auto-picks major.
• /iflow-close nohistory (or skip history) — skip the HISTORY.md update step for this run.
• /iflow-close log "one-line summary" (or note "...") — override the HISTORY.md bullet summary instead of using the GitHub issue title.
• /iflow-close stay (or stay on branch, don't switch, dont switch to main) — skip the safe default-branch switch after the PR step.
• /iflow-close draft — create with gh pr create --draft (or leave an existing PR draft); skips yolo merge.

The bump runs after tests and before issue-folder moves and before commit / push / PR so the PR includes the new version. If pyproject.toml has no bumpable version, the assistant skips the bump and continues.

Typical steps the assistant follows:

1. Sanity check — e.g. uv run pytest, review the diff.
2. Optional version bump — if requested, follow .cursor/skills/iflow-version-bump/SKILL.md. It resolves the project's release strategy first (the "Release & version bump" section of .issueflows/04-designs-and-guides/this-project.md, else pyproject.toml detection): static versions are bumped with uv version --bump … from the project root; git-tag derived versions (setuptools-scm and friends) get a planned tag instead — created after the merge (by /iflow-cleanup, or the yolo close's post-merge step), never on the issue branch.
3. Update HISTORY.md — unless nohistory was passed, follow .cursor/skills/iflow-history-update/SKILL.md. Append a bullet to ## [Unreleased] (no bump) or promote ## [Unreleased] to ## [<new_version>] - <YYYY-MM-DD> and open a fresh empty ## [Unreleased] above it (with bump). The bullet is staged in the same commit that feeds (or updates) the PR — including when a draft was opened earlier via /iflow-build early PR. Never offered after close finishes or after merge. With confirm_changelog_update = false (the default), the assistant writes without asking (same as the yolo token's history behaviour). If HISTORY.md is missing at the project root, the step is skipped with a note — never auto-created.
4. Issue folders — update status markdown; use - [x] Done only when fully resolved. Move completed issue files from .issueflows/01-current-issues/ to .issueflows/03-solved-issues/, or partly done work to .issueflows/02-partly-solved-issues/.
5. Commit — focused staging and a clear message (include pyproject.toml / uv.lock if the bump changed them, and HISTORY.md when step 3 updated it). Sync with the default branch using git pull --ff-only.
6. Push — to your usual remote (e.g. origin).
7. Pull request — gh pr list --head <branch> first (reuse an open PR, including an early draft); else gh pr create (with --draft when the draft token was passed). Mark ready from draft when not keeping draft. Afterward, snapshot CI with gh pr checks. Link the GitHub issue (Closes #n / Refs #n).
8. Switch back when safe — unless stay / don't switch was passed, run git status --porcelain; if clean, git switch <default> and git pull --ff-only; if dirty, stay put and report why switching is unsafe.
9. After review — if switched back, return to the PR branch before review fixes; merge when approved and gh pr checks is green; once the PR merges, run /iflow-cleanup for the post-merge tidy-up. With yolo, close may gh pr checks --watch (budget: checks_watch_minutes, default 15) before merge, falling back to --auto only when the cap elapses.

Result: Commit, push, PR link, and either a clean switch back to the default branch or a clear reason for staying on the issue branch. No branches are deleted from /iflow-close itself.

6. /iflow-cleanup — post-merge branch hygiene¶

When: The PR opened by /iflow-close has merged on GitHub. (The optional GitHub remote audit can also run when you only want a remote-branch report.)

What you pass: Nothing (acts on the current branch), an explicit branch name, and/or a GitHub-audit token such as include GitHub / with github / github.

What the assistant does:

1. Detects the default branch.
2. Detects merge state via gh pr view (falls back to git cherry origin/<default> <branch> to catch squash-merges).
3. If not merged: reminds you to stay off the default for unrelated work and re-run after merge (Phase A stops; Phase B may still run if a GitHub-audit token was present).
4. If merged: one consolidated yes/no prompt covering git switch <default>, git pull --ff-only, git fetch --prune, and git branch -d on every local branch whose tip is already reachable from the default (including squash-merged ones). Never -D; if -d refuses, reports and moves on.
5. Optional safe folder sweep: moves any issue<N>_* group whose status file says - [x] Done to .issueflows/03-solved-issues/.
6. Optional Phase B (include GitHub): run issue-flow agent branches --json (or the manual git/gh fallback) to classify origin/* as deletable / unique work / skipped; summarise unique commits; then a second confirm for optional git push origin --delete on deletable remotes and/or a findings issue via gh issue create. Never --force; never delete the default.

Result: Working tree on the default, merged local branches deleted (with consent), folders tidy; when Phase B ran, remote audit report plus any consented remote deletes / findings issue.

7. /iflow-graphify — rebuild the knowledge graph (optional)¶

When: The project has the optional graphify integration enabled (the graphify CLI is on PATH and a graphify-out/ folder is present), and the graph has gone stale relative to the source tree.

What you pass: Optional graphify subcommand and args, forwarded verbatim. Common picks:

• (nothing) — AST-only build of the project root (graphify update <project>). No LLM API key required; produces the full graphify-out/. The default.
• extract — adds the slower semantic LLM pass for richer cross-file relationships. Needs an API key (GEMINI_API_KEY, ANTHROPIC_API_KEY, OPENAI_API_KEY, MOONSHOT_API_KEY) or --backend ollama for a local LLM via Ollama. Cursor's own LLM is not available to subprocesses.
• watch — long-running watcher that auto-rebuilds on save.
• cluster-only — rerun clustering on the existing graph.json without re-extraction (e.g. cluster-only --no-viz).
• ./subdir — restrict the scan to a sub-directory (default subcommand: update).

What the assistant does:

1. Runs issue-flow graphify (which shells out to the graphify CLI). If issue-flow is unavailable, falls back to graphify update . directly (graphify . alone is not valid — graphify requires a subcommand).
2. If graphify is not installed, prints install hints (uv tool install graphifyy) and stops — never silently retries.
3. If graphify extract fails with "no LLM API key found", suggests setting one of the supported env vars, or using --backend ollama, or dropping back to the default update subcommand.
4. Verifies that graphify-out/graph.html, GRAPH_REPORT.md, and graph.json exist after a successful run.

Result: A refreshed graphify-out/ so /iflow-build can navigate by graph instead of grepping. /iflow-graphify is off-path — /iflow, /iflow-build, and /iflow-close may suggest a rebuild but never invoke /iflow-graphify automatically.

8. /iflow-yolo — all-in-one for small issues¶

When: The change is genuinely small and low-risk (typo, one-line fix, doc tweak) and you want to skip the usual checkpoints. For anything bigger, use the individual commands.

Preflight (any failure aborts before the chain starts):

• Refuses to run on main / master.
• Refuses if git status --porcelain shows unrelated uncommitted changes.
• Runs uv run pytest up front; refuses if anything fails.
• Single consolidated confirmation listing the full planned chain (issue, branch, repo, downstream flags).

Chain: /iflow-init → /iflow-plan (auto-confirmed short plan; aborts if the scope check reveals the change isn't actually small) → /iflow-build → uv run pytest again → /iflow-close (with any forwarded bump/patch/minor/major/draft/stay). Does not run /iflow-cleanup — the PR hasn't merged yet.

Result: A commit, push, and PR ready for review, with the final branch reported — or an abort at the first ambiguity.

9. /iflow-fix — interactive iterative-fixes session¶

When: You have a bucket of small, iterative fixes (little bugs, typos, chores, polish) to knock out on one branch, rather than a single well-defined deliverable.

What you pass: An optional session name (used for the issue title and branch slug). No name → defaults to iterative-small-fixes. During an active session, a /iflow-fix <description> (or just describing a fix) means "run the next fix".

What the assistant does:

1. Set up (once). Preflight (default branch, git fetch --prune, clean tree); create a GitHub issue with gh issue create (always, after confirmation) and capture N; create branch <N>-<slug> (off the default, or — when already on a non-default branch — ask whether to branch from current or default); delegate local capture to /iflow-init; seed issue<N>_status.md with an unchecked - [ ] Done and an empty ## Iterative fixes log.
2. Loop. For each proposed fix: restate it, write a short inline plan, implement only on confirmation, and append a dated bullet to the Iterative fixes log. A fix that turns out to be a real feature is split out into its own issue instead.
3. Finish. Tells you to run /iflow-close to land the session (it never auto-runs it); reminds you about /iflow-cleanup after the PR merges.

Coexists with /iflow-pick fix and /iflow-issue: pick-fix is a one-shot general-fixes setup; /iflow-issue creates one well-specified normal issue; /iflow-fix stays and drives the small-fixes loop until close.

Off-path: /iflow never auto-dispatches to /iflow-fix. While a session is active, drive it with /iflow-fix + /iflow-close, not /iflow. GitHub only (gh); GitLab is not supported.

Result: A session issue + branch with a running fixes log, ready to land via /iflow-close.

10. /iflow-issue — create a normal (non-epic) issue¶

When: You want to file one well-specified GitHub issue — a single deliverable with a real body — then optionally start the normal lifecycle. Not for iterative small-fixes buckets (/iflow-fix) or multi-issue staged work (/iflow-epic).

What you pass: Optional free text to seed the draft (title / short description). Leading epic (e.g. /iflow-issue epic Large rewrite) creates an epic anchor (Epic: title + epic label when present). Bare /iflow-issue → the assistant asks for a one-line intent.

What the assistant does:

1. Preflight — default branch, git fetch --prune, clean/dirty tree.
2. Draft — propose title + body with Problem / context, Spec, Acceptance criteria, and optional Out of scope. Refine until you confirm. If clearly over-large for one PR, mention /iflow-epic (does not auto-split).
3. Create — show final title/body (and epic label when applicable); on confirm, gh issue create and capture N.
4. Optional setup — offer branch <N>-<slug> + /iflow-init, then ask about /iflow-plan (never auto-runs plan). Decline → create-only; pick up later via /iflow-pick / /iflow-init.

Off-path: /iflow never auto-dispatches to /iflow-issue. GitHub only (gh); GitLab is not supported.

Result: A new GitHub issue (and optionally a branch + local capture ready for /iflow-plan).

11. /iflow-status — status overview of all issues (read-only)¶

When: You want a bird's-eye view of where every issue stands, rather than acting on the single focus issue.

What you pass: Nothing (full report), local (skip the GitHub query), or a hint like milestone v0.4 to bias the GitHub section.

What the assistant does (all read-only):

1. Context — current branch, default branch, clean/dirty tree, ahead/behind; focus issue N derived from the branch when it matches ^<N>-.+.
2. Focus issue — the active group in .issueflows/01-current-issues/ and its lifecycle stage (init / plan / build / close) using the same file-presence logic as /iflow, plus the suggested next step.
3. Parked work — each issue<n>_* group under .issueflows/02-partly-solved-issues/ with title and one-line status.
4. Solved archive — count of distinct solved issues under .issueflows/03-solved-issues/ and the most recent few.
5. Open GitHub issues — gh issue list cross-referenced against the local folders, tagged focus / parked / solved-locally / untracked. Skipped gracefully when gh is unavailable or local was passed.
6. Summary — one terse line.

Off-path: /iflow never auto-dispatches to /iflow-status. It writes nothing, moves no files, and creates no branches, commits, or GitHub issues.

Result: A consolidated, read-only status report. Nothing on disk or GitHub changes.

12. /iflow-review — review open issues and apply labels¶

When: You want help deciding which open GitHub issues should carry workflow labels (v1: the configured yolo label).

What you pass: Nothing (list kinds and ask), or yolo to run the yolo review.

What the assistant does:

1. Kind — if omitted, list supported review kinds and ask.
2. Config / label — resolve yolo_label (and note label_flows); create the label under confirm if missing.
3. Candidates — list all open issues (issue-flow agent label-candidates), including already-labelled ones for re-score.
4. Judge — yolo-fitness (same criteria as /iflow-epic); propose add / keep / skip (never auto-remove).
5. Confirm + apply — one consolidated confirm, then issue-flow agent label-apply (or gh issue edit --add-label).

Example:

iflow review yolo
# → table of open issues with add / keep / skip
# → confirm → labels applied
iflow cycle yolo
# → batch-process every open issue that now carries the yolo label

Off-path: /iflow never auto-dispatches to /iflow-review. No issue creation; no label removals in v1.

Result: Selected open issues carry the target label so /iflow-pick can route them (when label_flows is on), or /iflow-cycle yolo can batch them.

13. /iflow-epic — plan a large change as staged issues¶

When: The work is too big for one PR. You want a staged plan anchored to a GitHub issue, then publish one stage at a time as real issues.

What you pass: /iflow-epic <N> to draft (or revise) .issueflows/05-epics/epic<N>_plan.md. Later: /iflow-epic <N> publish [stage <k>] to create that stage's issues on GitHub. No anchor yet → create one with /iflow-issue epic <intent>, then pass the new number.

What the assistant does (draft):

1. Reads the anchor issue and any design docs under 04-designs-and-guides/.
2. Drafts stages of manageable issue specs (title, scope, acceptance, dependencies, yolo: yes|no judgment).
3. Writes Status: draft and iterates with you until you confirm → Status: confirmed.
4. Does not create GitHub issues while drafting.

What the assistant does (publish):

1. Requires Status: confirmed. Selects the named stage (or the earliest unpublished stage).
2. Dry-run lists titles + labels, then one consolidated confirm.
3. Creates issues in dependency order (gh issue create), records Published: #<M> in the plan, updates the anchor issue's task list.
4. Re-runs are idempotent (already-published specs are skipped).

Example:

iflow epic 144
# → drafts .issueflows/05-epics/epic144_plan.md  (Status: draft)
# → you confirm → Status: confirmed
iflow epic 144 publish stage 1
# → creates stage-1 issues (yolo labels per judgment), task list on #144
issue-flow agent epic-status 144 --json
# → current stage + next_candidates for /iflow-pick / /iflow-cycle

Off-path: /iflow never auto-dispatches to /iflow-epic. Epics decompose into the normal single-issue lifecycle; they do not replace it.

Result: A durable epic plan file; published stages become ordinary issues you pick/yolo/cycle as usual.

14. /iflow-cycle — batch-process a queue of yolo-fit issues¶

When: You have several small, well-specified issues and want them landed hands-off under one up-front confirm — the batch form of /iflow-yolo.

What you pass: a queue spec, for example:

• yolo — alias for label:yolo (all open issues with the configured yolo trigger label)
• label:<L> — every open issue with that label
• explicit numbers — e.g. 12 15 18
• epic <N> [stage <k>] — current (or named) stage of an epic
• optional: onfail:stop|skip, max:<n>, resume, parallel:<n> (experimental)

What the assistant does:

1. Expands aliases, then resolves the queue with issue-flow agent queue … --json.
2. Cap check (default max 10 without max:<n>).
3. One consolidated confirm (ordered queue, skipped/blocked, auto-merge).
4. Writes cycle_status.md, then for each issue runs the full yolo chain from a clean default branch (merge → pull → next).
5. Stops only on strictly necessary input; onfail:stop (default) leaves the tree clean on default.

Example — all yolo-labelled issues:

iflow cycle yolo
# → agent queue --label yolo
# → confirm the ordered list
# → each issue: init → plan → build → close yolo (PR merged)
# → back on default, clean, between issues

Conflict stance: sequential cycles merge each PR and return to a clean default before the next issue, so shared files like HISTORY.md stay single-writer. See 04-designs-and-guides/parallel-cycle.md for experimental parallel:<n> (merges still serialized).

Off-path: /iflow never auto-dispatches to /iflow-cycle.

Result: A batch report of merged/failed/not-reached issues; run /iflow-cleanup once afterward to prune merged local branches.

15. /iflow-auto — unattended large-change orchestration¶

When: You have a confirmed epic plan and want overnight hands-off progress through a stage, then an adversarial inter-epoch review.

What you pass: epic <N>, optional stage <k>, optional loops:<n>, review (adversarial only), or status / dry-run.

What the assistant does:

1. Require epic<N>_plan.md with Status: confirmed; resolve stage via epic-status.
2. Resolve loop budget (loops:<n> > baked auto_adversarial_loops > 2).
3. Overnight confirm once (authorizes cycle auto-merge and adversarial reopen/create), then write auto_status.md and run /iflow-cycle for that stage.
4. Run adversarial review against epic/stage goals (criteria in advanced-auto-mode.md); record adversarial_clear or adversarial_findings in auto_status.md. Standalone: /iflow-auto <N> review.
5. Loop control: on findings, increment loop_count; if open work remains and loop_count < budget, re-queue via /iflow-cycle and re-review; when budget exhausted, stop and ask (accept / grant N more loops / abort).
6. Next-epoch gate: start stage k+1 only when epic-status marks stage k done and no open blockers remain in auto_status.md; otherwise epoch_gated. When clear, may continue to the next unfinished stage under the same overnight confirm.

Off-path: /iflow never auto-dispatches to /iflow-auto. See 04-designs-and-guides/advanced-auto-mode.md.

Result: Stage queue processed via cycle; durable auto_status.md; adversarial pass may reopen/create blockers; loops honour auto_adversarial_loops / loops:<n>; epochs advance only when the queue is clear.

16. /iflow-archive — condense the solved-issues archive (destructive, gated)¶

When: .issueflows/03-solved-issues/ has grown large and most of its issue<N>_* groups are no longer worth keeping as individual files.

What you pass: Nothing (archive all but the 5 most recent solved groups), keep <K> (keep the <K> most recent), an explicit list of issue numbers, or all.

What the assistant does:

1. Preflight — requires a clean working tree (stop if dirty) and records the pre-archive ref via git rev-parse HEAD.
2. Select — lists every solved group (number + title), applies your input rule, and shows the candidate list for you to adjust.
3. Consolidated confirm — one prompt covering exactly which issues get summarised and that their files will be deleted; nothing proceeds without a clear yes.
4. Summarise — appends to .issueflows/03-solved-issues/YYYY-MM-DD_archived_issues.md: a header with the pre-archive ref and recovery recipe (git show <ref>:<path>), then one section per issue with source URL, archived file names, and a 2–4 sentence outcome summary.
5. Delete — removes the archived groups' files (issue-flow agent archive <N> ... when the CLI is installed, else git rm).
6. Commit offer — proposes a single commit so the deletion lands right after the recorded ref; asks first, never pushes.

Off-path: /iflow never auto-dispatches to /iflow-archive. It deletes files, so you opt in explicitly.

Result: One dated summary file replaces the archived groups; every original file remains recoverable from git history via the recorded ref.

End-to-end flow¶

Tip: at any point in the linear flow below, you can just run /iflow and it will dispatch to the right step based on current state.

(no issue chosen yet)
    │  /iflow-pick   → choose issue, create branch, run /iflow-init
    ▼
GitHub issue
    │  /iflow-init   (or /iflow)
    ▼
.issueflows/01-current-issues/issueN_original.md
    │  /iflow-plan
    ▼
issueN_plan.md  (user confirmed)
    │  /iflow-build
    ▼
Code + tests (+ status updates during work)
    │  /iflow-close  [optional: bump <patch|minor|major|alpha|beta|rc|…>]
    ▼
Commit → push → PR
    │
    │  (PR merges on GitHub)
    │  /iflow-cleanup
    ▼
Default branch, stale local branches deleted (with single confirm)

Detours:
  /iflow-pick   — front door: choose the next issue, branch, init (before the linear flow)
  /iflow-pause  — park mid-stream; moves issueN_* to 02-partly-solved-issues/
  /iflow-yolo   — chain init → plan → build → close for tiny fixes (safeguarded)
  /iflow-fix    — interactive session: one branch, many small fixes, then /iflow-close
  /iflow-issue  — create one well-specified normal GitHub issue (optional branch + init)
  /iflow-status — read-only overview of all issues (focus / parked / solved + GitHub)
  /iflow-doctor — audit/repair dirty .issueflows/ folders
  /iflow-review — review open issues and apply labels (v1: yolo)
  /iflow-epic   — stage a large change; publish stages as real issues
  /iflow-cycle yolo — auto-process all open issues with the configured yolo label
  /iflow-auto <N> — unattended epic stage via cycle + adversarial review
  /iflow-archive — condense old solved issues into a dated summary file (gated deletion)

The skill packages under .cursor/skills/ are the primary workflow surface. This document is a readable overview only.