From 66d9a701ffde8ee81cf001650131d600d9374303 Mon Sep 17 00:00:00 2001 From: Cursor Agent Date: Sun, 27 Sep 2026 12:56:23 +0000 Subject: [PATCH] docs: add Flows map with knobs to concepts Interactive #397 fix session: mermaid overview of on-path, hands-off, and epic flows plus the config knobs that steer them; link from home and how-to index. Co-authored-by: Jan Petter Maehlen --- .../01-current-issues/issue397_original.md | 11 +++ .../01-current-issues/issue397_status.md | 9 ++ docs/concepts.md | 85 +++++++++++++++++++ docs/how-to/index.md | 4 +- docs/index.md | 3 +- 5 files changed, 110 insertions(+), 2 deletions(-) create mode 100644 .issueflows/01-current-issues/issue397_original.md create mode 100644 .issueflows/01-current-issues/issue397_status.md diff --git a/.issueflows/01-current-issues/issue397_original.md b/.issueflows/01-current-issues/issue397_original.md new file mode 100644 index 0000000..02ad78f --- /dev/null +++ b/.issueflows/01-current-issues/issue397_original.md @@ -0,0 +1,11 @@ +# Issue #397: Iterative fixes: docs-flow-diagram + +Source: https://github.com/jepegit/issue-flow/issues/397 + +## Original issue text + +Interactive `/iflow-fix` session for iterative small fixes. + +Individual fixes are recorded in the status markdown and landed together via `/iflow-close`. + +**First intent:** Add a flow diagram of the available flows in the docs, including configuration knobs. diff --git a/.issueflows/01-current-issues/issue397_status.md b/.issueflows/01-current-issues/issue397_status.md new file mode 100644 index 0000000..4a1c002 --- /dev/null +++ b/.issueflows/01-current-issues/issue397_status.md @@ -0,0 +1,9 @@ +# Issue #397: Iterative fixes: docs-flow-diagram + +Interactive `/iflow-fix` session. Fixes recorded below; land together via `/iflow-close`. + +- [ ] Done + +## Iterative fixes log + +- 2026-09-27: Added Flows map (mermaid + knobs table) to `docs/concepts.md`; linked from `docs/index.md` and `docs/how-to/index.md`. diff --git a/docs/concepts.md b/docs/concepts.md index bda59a5..3d67d64 100644 --- a/docs/concepts.md +++ b/docs/concepts.md @@ -128,6 +128,91 @@ starts it for you. That includes: `iflow` may *mention* an off-path command (for example "run `iflow cleanup` after the PR merges"), but it never runs one. +## Flows map + +How the main entry points relate, and which **knobs** steer them. Solid arrows +are the usual path; dotted ones are opt-in or label-driven. Full knob list: +[Configuration](configuration.md). + +```mermaid +flowchart TB + subgraph start [Start work] + setup(["setup"]) + pick(["pick"]) + issueCmd(["issue"]) + fix(["fix"]) + end + + subgraph onpath [On-path — dispatcher iflow] + capture["capture"] + plan["plan"] + build["build"] + close["close"] + capture --> plan --> build --> close + end + + subgraph hands [Hands-off / batch] + yolo(["yolo"]) + cycle(["cycle"]) + auto(["auto"]) + drive(["drive"]) + ops(["ops"]) + end + + subgraph big [Bigger than one issue] + epic(["epic"]) + split(["split"]) + end + + setup -.->|harness ready| pick + pick -->|worktree_first| capture + pick -.->|label_flows + yolo_label| yolo + pick -.->|label_flows + ops_label
ops wins over yolo| ops + issueCmd -->|worktree_first| capture + fix -->|worktree_first| capture + fix -.->|auto_close| close + + pick -.->|auto_plan| plan + plan -.->|auto_build| build + build -.->|early_pr| close + build -.->|auto_close| close + close -->|PR merged| cleanup(["cleanup"]) + close -.->|publish_label| release["gh release"] + close -.->|auto_cleanup| cleanup + close -.->|auto_switchback / auto_remove_worktree| home["default branch"] + + yolo -->|"one confirm → full on-path chain"| capture + cycle -->|"each queued issue"| yolo + epic -->|"publish stages"| cycle + auto -->|"per stage"| cycle + drive --> epic + drive --> auto + split -.->|"2–5 children"| pick + ops --> close +``` + +| Knob | Steers | Default | +| --- | --- | --- | +| `mode` | Which commands exist at all (`standard` / `novice` / `simple`) | `standard` | +| `worktree_first` | `pick` / `issue` / `fix` start in a sibling worktree vs `inplace` | `true` | +| `auto_plan` | After pick, chain into plan | `true` | +| `auto_build` | After plan approval, chain into build | `true` | +| `auto_close` | After build (or end of fix), chain into close | `false` | +| `early_pr` | Build opens a draft PR after the first push | `false` | +| `label_flows` | Pick routes by issue label (`yolo_label` → yolo, `ops_label` → ops) | `true` | +| `publish_label` | Close bumps + creates a GitHub release after merge | `"publish"` | +| `auto_cleanup` | After a PR exists, watch merge then run cleanup | `false` | +| `auto_switchback` | After close opens a PR, switch home to the default branch | `true` | +| `auto_remove_worktree` | Close removes the issue worktree when the tree is clean | `true` | +| `pr_merge_method` | How hands-off closes merge (`squash` / `merge` / `rebase`) | `squash` | +| `cycle_max_issues` / `cycle_onfail` / `cycle_nonyolo` | Cycle queue size, failure policy, non-yolo merge policy | `10` / `stop` / `merge` | +| `auto_adversarial_loops` | Auto review-and-fix loops per stage before it asks | `2` | +| `model_label_flows` | Pick announces deep/fast model from labels | `false` | + +Per-run tokens (`inplace`, `worktree`, `noplan`, `nobuild`, `noearly`, …) override +the matching knob for that run only. See [Configuration](configuration.md) and +[Work in a sibling worktree](how-to/worktrees.md). + ## Where the agent always stops to ask The workflow is built so that nothing surprising happens without you seeing it diff --git a/docs/how-to/index.md b/docs/how-to/index.md index fe9b5bd..60afb24 100644 --- a/docs/how-to/index.md +++ b/docs/how-to/index.md @@ -6,7 +6,9 @@ title: How-to guides Short, task-oriented paths. Each page is goal → steps → related links — not a full command reference. Unfamiliar terms (focus issue, off-path, yolo, epic -stage …) are explained in [Concepts](../concepts.md). For every slash command in detail, see +stage …) are explained in [Concepts](../concepts.md). For a single diagram of +every flow and the knobs that steer them, see +[Flows map](../concepts.md#flows-map). For every slash command in detail, see [Command reference](../issue-workflow.md). ## Quick recipes diff --git a/docs/index.md b/docs/index.md index 1a961d8..d660d0c 100644 --- a/docs/index.md +++ b/docs/index.md @@ -30,7 +30,8 @@ In your editor's chat window: Forgot where you are? Type `iflow` and it runs the next step. For small issues, larger changes split into stages, and batch runs, see the -[How-to guides](how-to/index.md). +[How-to guides](how-to/index.md). A map of every flow and the knobs that steer +them is in [Flows map](concepts.md#flows-map). ## Start here