flow-workflows 0.79.0 → 0.80.0
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.
- package/adapters/codex/CORE.md +1 -1
- package/adapters/codex/skills/flow-feat-design/SKILL.md +31 -38
- package/adapters/codex/skills/flow-work-README/SKILL.md +1 -1
- package/adapters/gemini/CORE.md +1 -1
- package/adapters/gemini/commands/flow/feat/design.toml +31 -38
- package/adapters/gemini/commands/flow/work/README.toml +1 -1
- package/adapters/hermes/CORE.md +1 -1
- package/adapters/hermes/skills/flow-feat-design/SKILL.md +31 -38
- package/adapters/hermes/skills/flow-work-README/SKILL.md +1 -1
- package/adapters/opencode/CORE.md +1 -1
- package/adapters/opencode/commands/flow-feat-design.md +31 -38
- package/adapters/opencode/commands/flow-work-README.md +1 -1
- package/package.json +1 -1
- package/plugins/flow/.claude-plugin/plugin.json +1 -1
- package/plugins/flow/CHANGELOG.md +17 -0
package/adapters/codex/CORE.md
CHANGED
|
@@ -17,7 +17,7 @@ Every `$flow-*` command assumes these rules. They are stated once, here, so a co
|
|
|
17
17
|
carries what is specific to its phase. Read this once per session; a command that says "load
|
|
18
18
|
`flow-core`" means this file.
|
|
19
19
|
|
|
20
|
-
**This file belongs to flow `0.
|
|
20
|
+
**This file belongs to flow `0.80.0`.** Compare it once, at the start of the session, against
|
|
21
21
|
`version` in `~/.claude/flow/.claude-plugin/plugin.json`. The two differing means the session
|
|
22
22
|
is running a **mixture** — the commands from one copy of the plugin, these shared rules from another
|
|
23
23
|
— which is exactly what happens when a branch or a release candidate is loaded over an installed
|
|
@@ -42,7 +42,7 @@ read.)*
|
|
|
42
42
|
**No code, and no design yet.** The output of this section is a ranked set of options and one chosen
|
|
43
43
|
approach; §3 onwards designs *that* approach.
|
|
44
44
|
|
|
45
|
-
### 1.5.1 Focused knowledge query
|
|
45
|
+
### 1.5.1 Focused knowledge query, then the inventory
|
|
46
46
|
|
|
47
47
|
`knowledge.search` set → 2-3 parallel queries on the **concept or pattern** the feature covers, not
|
|
48
48
|
its title (`$flow-feat-start` already queried that): tracking → `"tracking deduplication"`,
|
|
@@ -50,6 +50,11 @@ its title (`$flow-feat-start` already queried that): tracking → `"tracking ded
|
|
|
50
50
|
`"attachment handler"`, `"tax rules integration"`. Two seconds, then continue regardless. Hits go
|
|
51
51
|
under "Additional domain context" in §5's template.
|
|
52
52
|
|
|
53
|
+
**Then the inventory.** Run §3's prior inventory **now**, before any approach is proposed, and keep
|
|
54
|
+
its result for `03-design.md`'s "## What already exists". An approach proposed without it reinvents
|
|
55
|
+
what the repository already has, and a lens whose only job was to go and look for it spends an
|
|
56
|
+
agent on what one search answers for every advisor at once. §3 is then already done.
|
|
57
|
+
|
|
53
58
|
### 1.5.2 Panel or single agent?
|
|
54
59
|
|
|
55
60
|
- **M or L**, in `manual`: offer the **parallel approach panel** with `AskUserQuestion` ("Generate
|
|
@@ -58,11 +63,14 @@ under "Additional domain context" in §5's template.
|
|
|
58
63
|
panel, note it in one line of `03-design.md`, go to §1.5.3.
|
|
59
64
|
- Declined, or the user insisted on running this on S → §1.5.4.
|
|
60
65
|
|
|
61
|
-
### 1.5.3 Approach panel (parallel fan-out
|
|
66
|
+
### 1.5.3 Approach panel (parallel fan-out, one round)
|
|
62
67
|
|
|
63
|
-
**Launch the advisors as parallel subagents** — one per lens, single round, each blind to the
|
|
64
|
-
|
|
65
|
-
|
|
68
|
+
**Launch the advisors as parallel subagents** — one per lens, a single round, each blind to the
|
|
69
|
+
others; then you synthesise. **There is no debate round.** Advisors that share one base model share
|
|
70
|
+
its blind spots: a round in which they read and attack each other tends to converge on the most
|
|
71
|
+
confident answer rather than surface a new one, and it costs as many agents as the first round. The
|
|
72
|
+
diversity is in what each lens is asked to *optimise*, and the adversarial pass is §6's challenger,
|
|
73
|
+
which attacks the design that was actually chosen.
|
|
66
74
|
|
|
67
75
|
**How wide the fan-out goes** — `agents.fanout_max` from `FLOW.md` (empty → **4**): never more than
|
|
68
76
|
that in one round, and never more than `agents.budget_max` (empty → **12**) across this whole
|
|
@@ -70,22 +78,16 @@ command run (flow-core §6); a round that does not fit is truncated and the trun
|
|
|
70
78
|
(`3/4`). With `models.workers` and `models.agents` empty, a round of 4 or more inherits this thread's
|
|
71
79
|
model — say so in one line before launching, naming the key and never a model (flow-core §1).
|
|
72
80
|
|
|
73
|
-
|
|
74
|
-
|
|
75
|
-
| M | Advisors → you synthesise |
|
|
76
|
-
| L | Advisors → cross-critique → you synthesise |
|
|
77
|
-
|
|
78
|
-
**You are the chairman.** Round 1 (and round 2 on L) are subagents; the synthesis and the ranking are
|
|
79
|
-
yours, never a subagent's — you hold the work's context and you write `03-design.md`.
|
|
81
|
+
**You are the chairman.** The advisors are subagents; the synthesis and the ranking are yours, never
|
|
82
|
+
a subagent's — you hold the work's context and you write `03-design.md`.
|
|
80
83
|
|
|
81
|
-
**
|
|
82
|
-
|
|
84
|
+
**Advisors (parallel, blind to each other).** One subagent per lens, up to `fanout_max`. M → the
|
|
85
|
+
first two lenses; L → add `operations`, and also on a sensitive surface (authentication or
|
|
83
86
|
authorization, payments, personal data, a public contract, a migration):
|
|
84
87
|
|
|
85
88
|
| Lens | Brief |
|
|
86
89
|
|---|---|
|
|
87
|
-
| `minimum` | The **smallest** approach that solves the declared use case,
|
|
88
|
-
| `reuse` | The approach that **most reuses** existing pieces in the affected module or its neighbours |
|
|
90
|
+
| `minimum` | The **smallest** approach that solves the declared use case, built on what the inventory found before anything new (strict MVP) |
|
|
89
91
|
| `reframe` | **Challenge the premise**: what if the problem is solved without building what was asked, or somewhere else? |
|
|
90
92
|
| `operations` | The most production-solid approach (observability, integration failure, data at scale) |
|
|
91
93
|
|
|
@@ -93,31 +95,22 @@ Each advisor gets this brief, with its lens substituted:
|
|
|
93
95
|
|
|
94
96
|
> Propose ONE approach to solve ticket `<TICKET>`, from this lens: `<lens brief>`. Read
|
|
95
97
|
> `.claude/work/<TICKET>/01-context.md` for context and the effective FLOW configuration (base plus
|
|
96
|
-
> active harness overlay) for project conventions.
|
|
98
|
+
> active harness overlay) for project conventions. What already exists in the repository:
|
|
99
|
+
> `<the §1.5.1 inventory>` — propose a new piece only where nothing there fits. Do not
|
|
97
100
|
> write code. Be specific about real modules and layers of this project. Report: name, what it is
|
|
98
101
|
> (one sentence), modules/layers affected, main risk, and why it could be a bad idea. Under 250 words.
|
|
99
102
|
> **Write that same answer to `.claude/work/<TICKET>/approaches/<lens>.md` before you reply** — the
|
|
100
103
|
> file is the deliverable and the reply is a copy of it.
|
|
101
104
|
|
|
102
|
-
**
|
|
103
|
-
*others* from its own lens:
|
|
104
|
-
|
|
105
|
-
> You are the "`<lens>`" advisor. The approaches proposed for `<TICKET>` are in
|
|
106
|
-
> `.claude/work/<TICKET>/approaches/` — read them all, plus `.claude/work/<TICKET>/01-context.md`.
|
|
107
|
-
> From your lens (`<lens brief>`), critique the
|
|
108
|
-
> OTHER approaches — not your own. For each one name its single biggest flaw for THIS project, or
|
|
109
|
-
> "none". Then say which is strongest and which weakest, and why. Be concrete and grounded in the
|
|
110
|
-
> project; do not invent flaws to fill space. **Write your critique to
|
|
111
|
-
> `.claude/work/<TICKET>/approaches/critique-<lens>.md` before you reply.**
|
|
112
|
-
|
|
113
|
-
**Round 3 — you synthesise.** A reply that arrived is already in your context and its file adds
|
|
105
|
+
**Then you synthesise.** A reply that arrived is already in your context and its file adds
|
|
114
106
|
nothing — **open only the files of the lenses that did not answer**, and only then. Rank the
|
|
115
|
-
approaches best to worst *for this case* (project fit and
|
|
116
|
-
|
|
117
|
-
where the advisors **agreed** and where they **disagreed** —
|
|
107
|
+
approaches best to worst *for this case* (project fit and simplicity, not generic merit), weighing
|
|
108
|
+
each one's own "why it could be a bad idea" against the others' — rank on substance, not on which
|
|
109
|
+
advisor wrote best. State explicitly where the advisors **agreed** and where they **disagreed** —
|
|
110
|
+
the disagreement is the useful part.
|
|
118
111
|
|
|
119
|
-
`agents.fanout_tool` set → run the
|
|
120
|
-
|
|
112
|
+
`agents.fanout_tool` set → run the round through that tool instead of plain parallel subagents; the
|
|
113
|
+
lenses, the briefs and the ceiling do not change.
|
|
121
114
|
|
|
122
115
|
**A round that answers nothing is read off disk before it is written off** (flow-core §6). The
|
|
123
116
|
advisors write their files first and reply second, so `ls .claude/work/<TICKET>/approaches/` settles
|
|
@@ -125,15 +118,15 @@ what actually happened: a file there is an answer that got lost in transit, and
|
|
|
125
118
|
it without spending a single agent. Only a lens with no file is empty — **it is asked once for its
|
|
126
119
|
answer and then dropped, never relaunched**, because an empty result is as often a truncated report
|
|
127
120
|
as an advisor with nothing to say, and a relaunched round is paid for twice out of one
|
|
128
|
-
`agents.budget_max`. Synthesise from those that answered and record `N/M`.
|
|
129
|
-
→ rank from the approaches alone.
|
|
121
|
+
`agents.budget_max`. Synthesise from those that answered and record `N/M`.
|
|
130
122
|
|
|
131
123
|
### 1.5.4 Single agent (the S case, or a declined panel)
|
|
132
124
|
|
|
133
125
|
Launch a `general-purpose` subagent with this short, self-contained brief:
|
|
134
126
|
|
|
135
127
|
> Generate 3-5 distinct approaches to solve `<title>` following the project conventions (see
|
|
136
|
-
> the effective FLOW configuration and `.claude/work/<TICKET>/01-context.md`)
|
|
128
|
+
> the effective FLOW configuration and `.claude/work/<TICKET>/01-context.md`), building on what
|
|
129
|
+
> already exists: `<the §1.5.1 inventory>`. For each: a
|
|
137
130
|
> one-sentence description,
|
|
138
131
|
> modules/layers affected, main risk, and why it could be a bad idea. Do not write code. Report in
|
|
139
132
|
> markdown, under 400 words.
|
|
@@ -166,7 +159,7 @@ A sensitive domain (payments, authentication, tracking) → launch **in parallel
|
|
|
166
159
|
|
|
167
160
|
## 3. Prior inventory (reuse before creating)
|
|
168
161
|
|
|
169
|
-
**
|
|
162
|
+
**M/L already ran this in §1.5.1** — reuse that result and skip to §4. XS/S: **before** launching the design subagents, list what the feature needs that **already exists** in code or DB. Launch an `Agent` with `subagent_type: Explore`:
|
|
170
163
|
|
|
171
164
|
> For feature `<title>` (see `.claude/work/<TICKET>/01-context.md`), search the repo for related pieces that already exist and could be reused: domain entities, value objects, repositories, services, events, columns or tables, CQRS commands/queries, and similar endpoints. Do not propose design — only list what is found with one line each and its location. If the feature mentions concepts like `<concept1>`, `<concept2>`, search for those specifically.
|
|
172
165
|
|
|
@@ -72,7 +72,7 @@ This system **orchestrates** the project's existing sub-agents and skills (it do
|
|
|
72
72
|
- **Code review is mandatory**: `$flow-feat-ship` is not run and `$flow-bug-postmortem` is not closed without passing through `/*:review`.
|
|
73
73
|
- **Existing sub-agents**: commands delegate to the project's agents and skills; work is never duplicated.
|
|
74
74
|
- **The subagents' model is the repo's call, never the plugin's (`models` in FLOW.md)**: `agents` (every subagent a command improvises) · `workers` (the fan-out rounds, falling back to `agents`). Empty = **inherit**. There is no key for what the main agent does itself: **an agent cannot switch its own model** (say it, **continue**); **a named agent keeps its own** (`agents.<role>`) — flow-core §1. `$flow-doctor` prints both resolved; `quality.review_skill` owns the review panel.
|
|
75
|
-
- **Parallel multi-agent fan-out (optional, only where it pays)**: plain subagents. (1) `$flow-feat-design` §1.5.3: one agent per lens (minimum /
|
|
75
|
+
- **Parallel multi-agent fan-out (optional, only where it pays)**: plain subagents. (1) `$flow-feat-design` §1.5.3: one agent per lens (minimum / reframe, + operations for L or a sensitive surface), one round, no debate. (2) `$flow-bug-investigate` §3.A: one agent per root cause, evidence **for and against**. (3) `$flow-feat-review` §6 and `$flow-bug-review` §5: one skeptic per **ambiguous** finding, refute-by-default. (4) `$flow-feat-build` §2.1bis and `$flow-bug-fix` §2.2: **one** skeptic on a premise the change depends on and nothing verifies — at **any size, XS included**, once per MR/PR, a category and not a depth tier, like the query duel. Other phases **do not** fan out. `manual`: offered with `AskUserQuestion`; `guided`/`auto`: runs, noted in the artifact. **The fan-out has two ceilings, and the synthesis is not a subagent**: `agents.fanout_max` (empty → **4**) per round and `agents.budget_max` (empty → **12**) for everything one command run launches, with what either cap drops **said** and the phase each command gives up first declared in it; both count agents, not findings, so grouping is intended and one-agent-per-finding past the cap is a breach; the review tier scales to the **diff under review**, not the size of the feature, and the verification gate also needs a **diff over 150 changed lines**; delegate the **gathering**, keep the **deciding**. **A heavier orchestrator is opt-in, per repo**: `agents.fanout_tool` (e.g. Claude Code's `Workflow`), rounds and ceiling unchanged; empty is the default and the portable path.
|
|
76
76
|
- **Knowledge sources (full cycle)**: the `knowledge` section names a tool per **role** — `search`, `stage`, `read_staging`, `save` — any MCP (domain-memory, codegraph…), CLI or skill; a role that is empty degrades (no lookup / finding stays in the artifact / artifacts are the staging / `KNOWLEDGE.md`); `knowledge.timeout_s` (2 s) or any failure → continue silently. **`knowledge.search`**: `$flow-feat-start`, `$flow-bug-start` (ticket keywords), `$flow-feat-design` (approaches, module + integrations), `$flow-bug-investigate` (component in §1.5, cause in §2). **`knowledge.stage`**: closing `$flow-feat-design` and `$flow-bug-investigate`, offer to stage non-obvious domain decisions (silence by default; per-branch). **`knowledge.read_staging`** then **`knowledge.save`** at `$flow-feat-ship` and `$flow-bug-postmortem`: offer to consolidate the "why" only.
|
|
77
77
|
|
|
78
78
|
## `meta.json` schema
|
package/adapters/gemini/CORE.md
CHANGED
|
@@ -16,7 +16,7 @@ Every `/flow:*` command assumes these rules. They are stated once, here, so a co
|
|
|
16
16
|
carries what is specific to its phase. Read this once per session; a command that says "load
|
|
17
17
|
`flow-core`" means this file.
|
|
18
18
|
|
|
19
|
-
**This file belongs to flow `0.
|
|
19
|
+
**This file belongs to flow `0.80.0`.** Compare it once, at the start of the session, against
|
|
20
20
|
`version` in `~/.claude/flow/.claude-plugin/plugin.json`. The two differing means the session
|
|
21
21
|
is running a **mixture** — the commands from one copy of the plugin, these shared rules from another
|
|
22
22
|
— which is exactly what happens when a branch or a release candidate is loaded over an installed
|
|
@@ -38,7 +38,7 @@ read.)*
|
|
|
38
38
|
**No code, and no design yet.** The output of this section is a ranked set of options and one chosen
|
|
39
39
|
approach; §3 onwards designs *that* approach.
|
|
40
40
|
|
|
41
|
-
### 1.5.1 Focused knowledge query
|
|
41
|
+
### 1.5.1 Focused knowledge query, then the inventory
|
|
42
42
|
|
|
43
43
|
`knowledge.search` set → 2-3 parallel queries on the **concept or pattern** the feature covers, not
|
|
44
44
|
its title (`/flow:feat:start` already queried that): tracking → `"tracking deduplication"`,
|
|
@@ -46,6 +46,11 @@ its title (`/flow:feat:start` already queried that): tracking → `"tracking ded
|
|
|
46
46
|
`"attachment handler"`, `"tax rules integration"`. Two seconds, then continue regardless. Hits go
|
|
47
47
|
under "Additional domain context" in §5's template.
|
|
48
48
|
|
|
49
|
+
**Then the inventory.** Run §3's prior inventory **now**, before any approach is proposed, and keep
|
|
50
|
+
its result for `03-design.md`'s "## What already exists". An approach proposed without it reinvents
|
|
51
|
+
what the repository already has, and a lens whose only job was to go and look for it spends an
|
|
52
|
+
agent on what one search answers for every advisor at once. §3 is then already done.
|
|
53
|
+
|
|
49
54
|
### 1.5.2 Panel or single agent?
|
|
50
55
|
|
|
51
56
|
- **M or L**, in `manual`: offer the **parallel approach panel** with `AskUserQuestion` ("Generate
|
|
@@ -54,11 +59,14 @@ under "Additional domain context" in §5's template.
|
|
|
54
59
|
panel, note it in one line of `03-design.md`, go to §1.5.3.
|
|
55
60
|
- Declined, or the user insisted on running this on S → §1.5.4.
|
|
56
61
|
|
|
57
|
-
### 1.5.3 Approach panel (parallel fan-out
|
|
62
|
+
### 1.5.3 Approach panel (parallel fan-out, one round)
|
|
58
63
|
|
|
59
|
-
**Launch the advisors as parallel subagents** — one per lens, single round, each blind to the
|
|
60
|
-
|
|
61
|
-
|
|
64
|
+
**Launch the advisors as parallel subagents** — one per lens, a single round, each blind to the
|
|
65
|
+
others; then you synthesise. **There is no debate round.** Advisors that share one base model share
|
|
66
|
+
its blind spots: a round in which they read and attack each other tends to converge on the most
|
|
67
|
+
confident answer rather than surface a new one, and it costs as many agents as the first round. The
|
|
68
|
+
diversity is in what each lens is asked to *optimise*, and the adversarial pass is §6's challenger,
|
|
69
|
+
which attacks the design that was actually chosen.
|
|
62
70
|
|
|
63
71
|
**How wide the fan-out goes** — `agents.fanout_max` from `FLOW.md` (empty → **4**): never more than
|
|
64
72
|
that in one round, and never more than `agents.budget_max` (empty → **12**) across this whole
|
|
@@ -66,22 +74,16 @@ command run (flow-core §6); a round that does not fit is truncated and the trun
|
|
|
66
74
|
(`3/4`). With `models.workers` and `models.agents` empty, a round of 4 or more inherits this thread's
|
|
67
75
|
model — say so in one line before launching, naming the key and never a model (flow-core §1).
|
|
68
76
|
|
|
69
|
-
|
|
70
|
-
|
|
71
|
-
| M | Advisors → you synthesise |
|
|
72
|
-
| L | Advisors → cross-critique → you synthesise |
|
|
73
|
-
|
|
74
|
-
**You are the chairman.** Round 1 (and round 2 on L) are subagents; the synthesis and the ranking are
|
|
75
|
-
yours, never a subagent's — you hold the work's context and you write `03-design.md`.
|
|
77
|
+
**You are the chairman.** The advisors are subagents; the synthesis and the ranking are yours, never
|
|
78
|
+
a subagent's — you hold the work's context and you write `03-design.md`.
|
|
76
79
|
|
|
77
|
-
**
|
|
78
|
-
|
|
80
|
+
**Advisors (parallel, blind to each other).** One subagent per lens, up to `fanout_max`. M → the
|
|
81
|
+
first two lenses; L → add `operations`, and also on a sensitive surface (authentication or
|
|
79
82
|
authorization, payments, personal data, a public contract, a migration):
|
|
80
83
|
|
|
81
84
|
| Lens | Brief |
|
|
82
85
|
|---|---|
|
|
83
|
-
| `minimum` | The **smallest** approach that solves the declared use case,
|
|
84
|
-
| `reuse` | The approach that **most reuses** existing pieces in the affected module or its neighbours |
|
|
86
|
+
| `minimum` | The **smallest** approach that solves the declared use case, built on what the inventory found before anything new (strict MVP) |
|
|
85
87
|
| `reframe` | **Challenge the premise**: what if the problem is solved without building what was asked, or somewhere else? |
|
|
86
88
|
| `operations` | The most production-solid approach (observability, integration failure, data at scale) |
|
|
87
89
|
|
|
@@ -89,31 +91,22 @@ Each advisor gets this brief, with its lens substituted:
|
|
|
89
91
|
|
|
90
92
|
> Propose ONE approach to solve ticket `<TICKET>`, from this lens: `<lens brief>`. Read
|
|
91
93
|
> `.claude/work/<TICKET>/01-context.md` for context and the effective FLOW configuration (base plus
|
|
92
|
-
> active harness overlay) for project conventions.
|
|
94
|
+
> active harness overlay) for project conventions. What already exists in the repository:
|
|
95
|
+
> `<the §1.5.1 inventory>` — propose a new piece only where nothing there fits. Do not
|
|
93
96
|
> write code. Be specific about real modules and layers of this project. Report: name, what it is
|
|
94
97
|
> (one sentence), modules/layers affected, main risk, and why it could be a bad idea. Under 250 words.
|
|
95
98
|
> **Write that same answer to `.claude/work/<TICKET>/approaches/<lens>.md` before you reply** — the
|
|
96
99
|
> file is the deliverable and the reply is a copy of it.
|
|
97
100
|
|
|
98
|
-
**
|
|
99
|
-
*others* from its own lens:
|
|
100
|
-
|
|
101
|
-
> You are the "`<lens>`" advisor. The approaches proposed for `<TICKET>` are in
|
|
102
|
-
> `.claude/work/<TICKET>/approaches/` — read them all, plus `.claude/work/<TICKET>/01-context.md`.
|
|
103
|
-
> From your lens (`<lens brief>`), critique the
|
|
104
|
-
> OTHER approaches — not your own. For each one name its single biggest flaw for THIS project, or
|
|
105
|
-
> "none". Then say which is strongest and which weakest, and why. Be concrete and grounded in the
|
|
106
|
-
> project; do not invent flaws to fill space. **Write your critique to
|
|
107
|
-
> `.claude/work/<TICKET>/approaches/critique-<lens>.md` before you reply.**
|
|
108
|
-
|
|
109
|
-
**Round 3 — you synthesise.** A reply that arrived is already in your context and its file adds
|
|
101
|
+
**Then you synthesise.** A reply that arrived is already in your context and its file adds
|
|
110
102
|
nothing — **open only the files of the lenses that did not answer**, and only then. Rank the
|
|
111
|
-
approaches best to worst *for this case* (project fit and
|
|
112
|
-
|
|
113
|
-
where the advisors **agreed** and where they **disagreed** —
|
|
103
|
+
approaches best to worst *for this case* (project fit and simplicity, not generic merit), weighing
|
|
104
|
+
each one's own "why it could be a bad idea" against the others' — rank on substance, not on which
|
|
105
|
+
advisor wrote best. State explicitly where the advisors **agreed** and where they **disagreed** —
|
|
106
|
+
the disagreement is the useful part.
|
|
114
107
|
|
|
115
|
-
`agents.fanout_tool` set → run the
|
|
116
|
-
|
|
108
|
+
`agents.fanout_tool` set → run the round through that tool instead of plain parallel subagents; the
|
|
109
|
+
lenses, the briefs and the ceiling do not change.
|
|
117
110
|
|
|
118
111
|
**A round that answers nothing is read off disk before it is written off** (flow-core §6). The
|
|
119
112
|
advisors write their files first and reply second, so `ls .claude/work/<TICKET>/approaches/` settles
|
|
@@ -121,15 +114,15 @@ what actually happened: a file there is an answer that got lost in transit, and
|
|
|
121
114
|
it without spending a single agent. Only a lens with no file is empty — **it is asked once for its
|
|
122
115
|
answer and then dropped, never relaunched**, because an empty result is as often a truncated report
|
|
123
116
|
as an advisor with nothing to say, and a relaunched round is paid for twice out of one
|
|
124
|
-
`agents.budget_max`. Synthesise from those that answered and record `N/M`.
|
|
125
|
-
→ rank from the approaches alone.
|
|
117
|
+
`agents.budget_max`. Synthesise from those that answered and record `N/M`.
|
|
126
118
|
|
|
127
119
|
### 1.5.4 Single agent (the S case, or a declined panel)
|
|
128
120
|
|
|
129
121
|
Launch a `general-purpose` subagent with this short, self-contained brief:
|
|
130
122
|
|
|
131
123
|
> Generate 3-5 distinct approaches to solve `<title>` following the project conventions (see
|
|
132
|
-
> the effective FLOW configuration and `.claude/work/<TICKET>/01-context.md`)
|
|
124
|
+
> the effective FLOW configuration and `.claude/work/<TICKET>/01-context.md`), building on what
|
|
125
|
+
> already exists: `<the §1.5.1 inventory>`. For each: a
|
|
133
126
|
> one-sentence description,
|
|
134
127
|
> modules/layers affected, main risk, and why it could be a bad idea. Do not write code. Report in
|
|
135
128
|
> markdown, under 400 words.
|
|
@@ -162,7 +155,7 @@ A sensitive domain (payments, authentication, tracking) → launch **in parallel
|
|
|
162
155
|
|
|
163
156
|
## 3. Prior inventory (reuse before creating)
|
|
164
157
|
|
|
165
|
-
**
|
|
158
|
+
**M/L already ran this in §1.5.1** — reuse that result and skip to §4. XS/S: **before** launching the design subagents, list what the feature needs that **already exists** in code or DB. Launch an `Agent` with `subagent_type: Explore`:
|
|
166
159
|
|
|
167
160
|
> For feature `<title>` (see `.claude/work/<TICKET>/01-context.md`), search the repo for related pieces that already exist and could be reused: domain entities, value objects, repositories, services, events, columns or tables, CQRS commands/queries, and similar endpoints. Do not propose design — only list what is found with one line each and its location. If the feature mentions concepts like `<concept1>`, `<concept2>`, search for those specifically.
|
|
168
161
|
|
|
@@ -68,7 +68,7 @@ This system **orchestrates** the project's existing sub-agents and skills (it do
|
|
|
68
68
|
- **Code review is mandatory**: `/flow:feat:ship` is not run and `/flow:bug:postmortem` is not closed without passing through `/*:review`.
|
|
69
69
|
- **Existing sub-agents**: commands delegate to the project's agents and skills; work is never duplicated.
|
|
70
70
|
- **The subagents' model is the repo's call, never the plugin's (`models` in FLOW.md)**: `agents` (every subagent a command improvises) · `workers` (the fan-out rounds, falling back to `agents`). Empty = **inherit**. There is no key for what the main agent does itself: **an agent cannot switch its own model** (say it, **continue**); **a named agent keeps its own** (`agents.<role>`) — flow-core §1. `/flow:doctor` prints both resolved; `quality.review_skill` owns the review panel.
|
|
71
|
-
- **Parallel multi-agent fan-out (optional, only where it pays)**: plain subagents. (1) `/flow:feat:design` §1.5.3: one agent per lens (minimum /
|
|
71
|
+
- **Parallel multi-agent fan-out (optional, only where it pays)**: plain subagents. (1) `/flow:feat:design` §1.5.3: one agent per lens (minimum / reframe, + operations for L or a sensitive surface), one round, no debate. (2) `/flow:bug:investigate` §3.A: one agent per root cause, evidence **for and against**. (3) `/flow:feat:review` §6 and `/flow:bug:review` §5: one skeptic per **ambiguous** finding, refute-by-default. (4) `/flow:feat:build` §2.1bis and `/flow:bug:fix` §2.2: **one** skeptic on a premise the change depends on and nothing verifies — at **any size, XS included**, once per MR/PR, a category and not a depth tier, like the query duel. Other phases **do not** fan out. `manual`: offered with `AskUserQuestion`; `guided`/`auto`: runs, noted in the artifact. **The fan-out has two ceilings, and the synthesis is not a subagent**: `agents.fanout_max` (empty → **4**) per round and `agents.budget_max` (empty → **12**) for everything one command run launches, with what either cap drops **said** and the phase each command gives up first declared in it; both count agents, not findings, so grouping is intended and one-agent-per-finding past the cap is a breach; the review tier scales to the **diff under review**, not the size of the feature, and the verification gate also needs a **diff over 150 changed lines**; delegate the **gathering**, keep the **deciding**. **A heavier orchestrator is opt-in, per repo**: `agents.fanout_tool` (e.g. Claude Code's `Workflow`), rounds and ceiling unchanged; empty is the default and the portable path.
|
|
72
72
|
- **Knowledge sources (full cycle)**: the `knowledge` section names a tool per **role** — `search`, `stage`, `read_staging`, `save` — any MCP (domain-memory, codegraph…), CLI or skill; a role that is empty degrades (no lookup / finding stays in the artifact / artifacts are the staging / `KNOWLEDGE.md`); `knowledge.timeout_s` (2 s) or any failure → continue silently. **`knowledge.search`**: `/flow:feat:start`, `/flow:bug:start` (ticket keywords), `/flow:feat:design` (approaches, module + integrations), `/flow:bug:investigate` (component in §1.5, cause in §2). **`knowledge.stage`**: closing `/flow:feat:design` and `/flow:bug:investigate`, offer to stage non-obvious domain decisions (silence by default; per-branch). **`knowledge.read_staging`** then **`knowledge.save`** at `/flow:feat:ship` and `/flow:bug:postmortem`: offer to consolidate the "why" only.
|
|
73
73
|
|
|
74
74
|
## `meta.json` schema
|
package/adapters/hermes/CORE.md
CHANGED
|
@@ -17,7 +17,7 @@ Every `/flow-*` command assumes these rules. They are stated once, here, so a co
|
|
|
17
17
|
carries what is specific to its phase. Read this once per session; a command that says "load
|
|
18
18
|
`flow-core`" means this file.
|
|
19
19
|
|
|
20
|
-
**This file belongs to flow `0.
|
|
20
|
+
**This file belongs to flow `0.80.0`.** Compare it once, at the start of the session, against
|
|
21
21
|
`version` in `~/.claude/flow/.claude-plugin/plugin.json`. The two differing means the session
|
|
22
22
|
is running a **mixture** — the commands from one copy of the plugin, these shared rules from another
|
|
23
23
|
— which is exactly what happens when a branch or a release candidate is loaded over an installed
|
|
@@ -42,7 +42,7 @@ read.)*
|
|
|
42
42
|
**No code, and no design yet.** The output of this section is a ranked set of options and one chosen
|
|
43
43
|
approach; §3 onwards designs *that* approach.
|
|
44
44
|
|
|
45
|
-
### 1.5.1 Focused knowledge query
|
|
45
|
+
### 1.5.1 Focused knowledge query, then the inventory
|
|
46
46
|
|
|
47
47
|
`knowledge.search` set → 2-3 parallel queries on the **concept or pattern** the feature covers, not
|
|
48
48
|
its title (`/flow-feat-start` already queried that): tracking → `"tracking deduplication"`,
|
|
@@ -50,6 +50,11 @@ its title (`/flow-feat-start` already queried that): tracking → `"tracking ded
|
|
|
50
50
|
`"attachment handler"`, `"tax rules integration"`. Two seconds, then continue regardless. Hits go
|
|
51
51
|
under "Additional domain context" in §5's template.
|
|
52
52
|
|
|
53
|
+
**Then the inventory.** Run §3's prior inventory **now**, before any approach is proposed, and keep
|
|
54
|
+
its result for `03-design.md`'s "## What already exists". An approach proposed without it reinvents
|
|
55
|
+
what the repository already has, and a lens whose only job was to go and look for it spends an
|
|
56
|
+
agent on what one search answers for every advisor at once. §3 is then already done.
|
|
57
|
+
|
|
53
58
|
### 1.5.2 Panel or single agent?
|
|
54
59
|
|
|
55
60
|
- **M or L**, in `manual`: offer the **parallel approach panel** with `AskUserQuestion` ("Generate
|
|
@@ -58,11 +63,14 @@ under "Additional domain context" in §5's template.
|
|
|
58
63
|
panel, note it in one line of `03-design.md`, go to §1.5.3.
|
|
59
64
|
- Declined, or the user insisted on running this on S → §1.5.4.
|
|
60
65
|
|
|
61
|
-
### 1.5.3 Approach panel (parallel fan-out
|
|
66
|
+
### 1.5.3 Approach panel (parallel fan-out, one round)
|
|
62
67
|
|
|
63
|
-
**Launch the advisors as parallel subagents** — one per lens, single round, each blind to the
|
|
64
|
-
|
|
65
|
-
|
|
68
|
+
**Launch the advisors as parallel subagents** — one per lens, a single round, each blind to the
|
|
69
|
+
others; then you synthesise. **There is no debate round.** Advisors that share one base model share
|
|
70
|
+
its blind spots: a round in which they read and attack each other tends to converge on the most
|
|
71
|
+
confident answer rather than surface a new one, and it costs as many agents as the first round. The
|
|
72
|
+
diversity is in what each lens is asked to *optimise*, and the adversarial pass is §6's challenger,
|
|
73
|
+
which attacks the design that was actually chosen.
|
|
66
74
|
|
|
67
75
|
**How wide the fan-out goes** — `agents.fanout_max` from `FLOW.md` (empty → **4**): never more than
|
|
68
76
|
that in one round, and never more than `agents.budget_max` (empty → **12**) across this whole
|
|
@@ -70,22 +78,16 @@ command run (flow-core §6); a round that does not fit is truncated and the trun
|
|
|
70
78
|
(`3/4`). With `models.workers` and `models.agents` empty, a round of 4 or more inherits this thread's
|
|
71
79
|
model — say so in one line before launching, naming the key and never a model (flow-core §1).
|
|
72
80
|
|
|
73
|
-
|
|
74
|
-
|
|
75
|
-
| M | Advisors → you synthesise |
|
|
76
|
-
| L | Advisors → cross-critique → you synthesise |
|
|
77
|
-
|
|
78
|
-
**You are the chairman.** Round 1 (and round 2 on L) are subagents; the synthesis and the ranking are
|
|
79
|
-
yours, never a subagent's — you hold the work's context and you write `03-design.md`.
|
|
81
|
+
**You are the chairman.** The advisors are subagents; the synthesis and the ranking are yours, never
|
|
82
|
+
a subagent's — you hold the work's context and you write `03-design.md`.
|
|
80
83
|
|
|
81
|
-
**
|
|
82
|
-
|
|
84
|
+
**Advisors (parallel, blind to each other).** One subagent per lens, up to `fanout_max`. M → the
|
|
85
|
+
first two lenses; L → add `operations`, and also on a sensitive surface (authentication or
|
|
83
86
|
authorization, payments, personal data, a public contract, a migration):
|
|
84
87
|
|
|
85
88
|
| Lens | Brief |
|
|
86
89
|
|---|---|
|
|
87
|
-
| `minimum` | The **smallest** approach that solves the declared use case,
|
|
88
|
-
| `reuse` | The approach that **most reuses** existing pieces in the affected module or its neighbours |
|
|
90
|
+
| `minimum` | The **smallest** approach that solves the declared use case, built on what the inventory found before anything new (strict MVP) |
|
|
89
91
|
| `reframe` | **Challenge the premise**: what if the problem is solved without building what was asked, or somewhere else? |
|
|
90
92
|
| `operations` | The most production-solid approach (observability, integration failure, data at scale) |
|
|
91
93
|
|
|
@@ -93,31 +95,22 @@ Each advisor gets this brief, with its lens substituted:
|
|
|
93
95
|
|
|
94
96
|
> Propose ONE approach to solve ticket `<TICKET>`, from this lens: `<lens brief>`. Read
|
|
95
97
|
> `.claude/work/<TICKET>/01-context.md` for context and the effective FLOW configuration (base plus
|
|
96
|
-
> active harness overlay) for project conventions.
|
|
98
|
+
> active harness overlay) for project conventions. What already exists in the repository:
|
|
99
|
+
> `<the §1.5.1 inventory>` — propose a new piece only where nothing there fits. Do not
|
|
97
100
|
> write code. Be specific about real modules and layers of this project. Report: name, what it is
|
|
98
101
|
> (one sentence), modules/layers affected, main risk, and why it could be a bad idea. Under 250 words.
|
|
99
102
|
> **Write that same answer to `.claude/work/<TICKET>/approaches/<lens>.md` before you reply** — the
|
|
100
103
|
> file is the deliverable and the reply is a copy of it.
|
|
101
104
|
|
|
102
|
-
**
|
|
103
|
-
*others* from its own lens:
|
|
104
|
-
|
|
105
|
-
> You are the "`<lens>`" advisor. The approaches proposed for `<TICKET>` are in
|
|
106
|
-
> `.claude/work/<TICKET>/approaches/` — read them all, plus `.claude/work/<TICKET>/01-context.md`.
|
|
107
|
-
> From your lens (`<lens brief>`), critique the
|
|
108
|
-
> OTHER approaches — not your own. For each one name its single biggest flaw for THIS project, or
|
|
109
|
-
> "none". Then say which is strongest and which weakest, and why. Be concrete and grounded in the
|
|
110
|
-
> project; do not invent flaws to fill space. **Write your critique to
|
|
111
|
-
> `.claude/work/<TICKET>/approaches/critique-<lens>.md` before you reply.**
|
|
112
|
-
|
|
113
|
-
**Round 3 — you synthesise.** A reply that arrived is already in your context and its file adds
|
|
105
|
+
**Then you synthesise.** A reply that arrived is already in your context and its file adds
|
|
114
106
|
nothing — **open only the files of the lenses that did not answer**, and only then. Rank the
|
|
115
|
-
approaches best to worst *for this case* (project fit and
|
|
116
|
-
|
|
117
|
-
where the advisors **agreed** and where they **disagreed** —
|
|
107
|
+
approaches best to worst *for this case* (project fit and simplicity, not generic merit), weighing
|
|
108
|
+
each one's own "why it could be a bad idea" against the others' — rank on substance, not on which
|
|
109
|
+
advisor wrote best. State explicitly where the advisors **agreed** and where they **disagreed** —
|
|
110
|
+
the disagreement is the useful part.
|
|
118
111
|
|
|
119
|
-
`agents.fanout_tool` set → run the
|
|
120
|
-
|
|
112
|
+
`agents.fanout_tool` set → run the round through that tool instead of plain parallel subagents; the
|
|
113
|
+
lenses, the briefs and the ceiling do not change.
|
|
121
114
|
|
|
122
115
|
**A round that answers nothing is read off disk before it is written off** (flow-core §6). The
|
|
123
116
|
advisors write their files first and reply second, so `ls .claude/work/<TICKET>/approaches/` settles
|
|
@@ -125,15 +118,15 @@ what actually happened: a file there is an answer that got lost in transit, and
|
|
|
125
118
|
it without spending a single agent. Only a lens with no file is empty — **it is asked once for its
|
|
126
119
|
answer and then dropped, never relaunched**, because an empty result is as often a truncated report
|
|
127
120
|
as an advisor with nothing to say, and a relaunched round is paid for twice out of one
|
|
128
|
-
`agents.budget_max`. Synthesise from those that answered and record `N/M`.
|
|
129
|
-
→ rank from the approaches alone.
|
|
121
|
+
`agents.budget_max`. Synthesise from those that answered and record `N/M`.
|
|
130
122
|
|
|
131
123
|
### 1.5.4 Single agent (the S case, or a declined panel)
|
|
132
124
|
|
|
133
125
|
Launch a `general-purpose` subagent with this short, self-contained brief:
|
|
134
126
|
|
|
135
127
|
> Generate 3-5 distinct approaches to solve `<title>` following the project conventions (see
|
|
136
|
-
> the effective FLOW configuration and `.claude/work/<TICKET>/01-context.md`)
|
|
128
|
+
> the effective FLOW configuration and `.claude/work/<TICKET>/01-context.md`), building on what
|
|
129
|
+
> already exists: `<the §1.5.1 inventory>`. For each: a
|
|
137
130
|
> one-sentence description,
|
|
138
131
|
> modules/layers affected, main risk, and why it could be a bad idea. Do not write code. Report in
|
|
139
132
|
> markdown, under 400 words.
|
|
@@ -166,7 +159,7 @@ A sensitive domain (payments, authentication, tracking) → launch **in parallel
|
|
|
166
159
|
|
|
167
160
|
## 3. Prior inventory (reuse before creating)
|
|
168
161
|
|
|
169
|
-
**
|
|
162
|
+
**M/L already ran this in §1.5.1** — reuse that result and skip to §4. XS/S: **before** launching the design subagents, list what the feature needs that **already exists** in code or DB. Launch an `Agent` with `subagent_type: Explore`:
|
|
170
163
|
|
|
171
164
|
> For feature `<title>` (see `.claude/work/<TICKET>/01-context.md`), search the repo for related pieces that already exist and could be reused: domain entities, value objects, repositories, services, events, columns or tables, CQRS commands/queries, and similar endpoints. Do not propose design — only list what is found with one line each and its location. If the feature mentions concepts like `<concept1>`, `<concept2>`, search for those specifically.
|
|
172
165
|
|
|
@@ -72,7 +72,7 @@ This system **orchestrates** the project's existing sub-agents and skills (it do
|
|
|
72
72
|
- **Code review is mandatory**: `/flow-feat-ship` is not run and `/flow-bug-postmortem` is not closed without passing through `/*:review`.
|
|
73
73
|
- **Existing sub-agents**: commands delegate to the project's agents and skills; work is never duplicated.
|
|
74
74
|
- **The subagents' model is the repo's call, never the plugin's (`models` in FLOW.md)**: `agents` (every subagent a command improvises) · `workers` (the fan-out rounds, falling back to `agents`). Empty = **inherit**. There is no key for what the main agent does itself: **an agent cannot switch its own model** (say it, **continue**); **a named agent keeps its own** (`agents.<role>`) — flow-core §1. `/flow-doctor` prints both resolved; `quality.review_skill` owns the review panel.
|
|
75
|
-
- **Parallel multi-agent fan-out (optional, only where it pays)**: plain subagents. (1) `/flow-feat-design` §1.5.3: one agent per lens (minimum /
|
|
75
|
+
- **Parallel multi-agent fan-out (optional, only where it pays)**: plain subagents. (1) `/flow-feat-design` §1.5.3: one agent per lens (minimum / reframe, + operations for L or a sensitive surface), one round, no debate. (2) `/flow-bug-investigate` §3.A: one agent per root cause, evidence **for and against**. (3) `/flow-feat-review` §6 and `/flow-bug-review` §5: one skeptic per **ambiguous** finding, refute-by-default. (4) `/flow-feat-build` §2.1bis and `/flow-bug-fix` §2.2: **one** skeptic on a premise the change depends on and nothing verifies — at **any size, XS included**, once per MR/PR, a category and not a depth tier, like the query duel. Other phases **do not** fan out. `manual`: offered with `AskUserQuestion`; `guided`/`auto`: runs, noted in the artifact. **The fan-out has two ceilings, and the synthesis is not a subagent**: `agents.fanout_max` (empty → **4**) per round and `agents.budget_max` (empty → **12**) for everything one command run launches, with what either cap drops **said** and the phase each command gives up first declared in it; both count agents, not findings, so grouping is intended and one-agent-per-finding past the cap is a breach; the review tier scales to the **diff under review**, not the size of the feature, and the verification gate also needs a **diff over 150 changed lines**; delegate the **gathering**, keep the **deciding**. **A heavier orchestrator is opt-in, per repo**: `agents.fanout_tool` (e.g. Claude Code's `Workflow`), rounds and ceiling unchanged; empty is the default and the portable path.
|
|
76
76
|
- **Knowledge sources (full cycle)**: the `knowledge` section names a tool per **role** — `search`, `stage`, `read_staging`, `save` — any MCP (domain-memory, codegraph…), CLI or skill; a role that is empty degrades (no lookup / finding stays in the artifact / artifacts are the staging / `KNOWLEDGE.md`); `knowledge.timeout_s` (2 s) or any failure → continue silently. **`knowledge.search`**: `/flow-feat-start`, `/flow-bug-start` (ticket keywords), `/flow-feat-design` (approaches, module + integrations), `/flow-bug-investigate` (component in §1.5, cause in §2). **`knowledge.stage`**: closing `/flow-feat-design` and `/flow-bug-investigate`, offer to stage non-obvious domain decisions (silence by default; per-branch). **`knowledge.read_staging`** then **`knowledge.save`** at `/flow-feat-ship` and `/flow-bug-postmortem`: offer to consolidate the "why" only.
|
|
77
77
|
|
|
78
78
|
## `meta.json` schema
|
|
@@ -16,7 +16,7 @@ Every `/flow-*` command assumes these rules. They are stated once, here, so a co
|
|
|
16
16
|
carries what is specific to its phase. Read this once per session; a command that says "load
|
|
17
17
|
`flow-core`" means this file.
|
|
18
18
|
|
|
19
|
-
**This file belongs to flow `0.
|
|
19
|
+
**This file belongs to flow `0.80.0`.** Compare it once, at the start of the session, against
|
|
20
20
|
`version` in `~/.claude/flow/.claude-plugin/plugin.json`. The two differing means the session
|
|
21
21
|
is running a **mixture** — the commands from one copy of the plugin, these shared rules from another
|
|
22
22
|
— which is exactly what happens when a branch or a release candidate is loaded over an installed
|
|
@@ -40,7 +40,7 @@ read.)*
|
|
|
40
40
|
**No code, and no design yet.** The output of this section is a ranked set of options and one chosen
|
|
41
41
|
approach; §3 onwards designs *that* approach.
|
|
42
42
|
|
|
43
|
-
### 1.5.1 Focused knowledge query
|
|
43
|
+
### 1.5.1 Focused knowledge query, then the inventory
|
|
44
44
|
|
|
45
45
|
`knowledge.search` set → 2-3 parallel queries on the **concept or pattern** the feature covers, not
|
|
46
46
|
its title (`/flow-feat-start` already queried that): tracking → `"tracking deduplication"`,
|
|
@@ -48,6 +48,11 @@ its title (`/flow-feat-start` already queried that): tracking → `"tracking ded
|
|
|
48
48
|
`"attachment handler"`, `"tax rules integration"`. Two seconds, then continue regardless. Hits go
|
|
49
49
|
under "Additional domain context" in §5's template.
|
|
50
50
|
|
|
51
|
+
**Then the inventory.** Run §3's prior inventory **now**, before any approach is proposed, and keep
|
|
52
|
+
its result for `03-design.md`'s "## What already exists". An approach proposed without it reinvents
|
|
53
|
+
what the repository already has, and a lens whose only job was to go and look for it spends an
|
|
54
|
+
agent on what one search answers for every advisor at once. §3 is then already done.
|
|
55
|
+
|
|
51
56
|
### 1.5.2 Panel or single agent?
|
|
52
57
|
|
|
53
58
|
- **M or L**, in `manual`: offer the **parallel approach panel** with `AskUserQuestion` ("Generate
|
|
@@ -56,11 +61,14 @@ under "Additional domain context" in §5's template.
|
|
|
56
61
|
panel, note it in one line of `03-design.md`, go to §1.5.3.
|
|
57
62
|
- Declined, or the user insisted on running this on S → §1.5.4.
|
|
58
63
|
|
|
59
|
-
### 1.5.3 Approach panel (parallel fan-out
|
|
64
|
+
### 1.5.3 Approach panel (parallel fan-out, one round)
|
|
60
65
|
|
|
61
|
-
**Launch the advisors as parallel subagents** — one per lens, single round, each blind to the
|
|
62
|
-
|
|
63
|
-
|
|
66
|
+
**Launch the advisors as parallel subagents** — one per lens, a single round, each blind to the
|
|
67
|
+
others; then you synthesise. **There is no debate round.** Advisors that share one base model share
|
|
68
|
+
its blind spots: a round in which they read and attack each other tends to converge on the most
|
|
69
|
+
confident answer rather than surface a new one, and it costs as many agents as the first round. The
|
|
70
|
+
diversity is in what each lens is asked to *optimise*, and the adversarial pass is §6's challenger,
|
|
71
|
+
which attacks the design that was actually chosen.
|
|
64
72
|
|
|
65
73
|
**How wide the fan-out goes** — `agents.fanout_max` from `FLOW.md` (empty → **4**): never more than
|
|
66
74
|
that in one round, and never more than `agents.budget_max` (empty → **12**) across this whole
|
|
@@ -68,22 +76,16 @@ command run (flow-core §6); a round that does not fit is truncated and the trun
|
|
|
68
76
|
(`3/4`). With `models.workers` and `models.agents` empty, a round of 4 or more inherits this thread's
|
|
69
77
|
model — say so in one line before launching, naming the key and never a model (flow-core §1).
|
|
70
78
|
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
| M | Advisors → you synthesise |
|
|
74
|
-
| L | Advisors → cross-critique → you synthesise |
|
|
75
|
-
|
|
76
|
-
**You are the chairman.** Round 1 (and round 2 on L) are subagents; the synthesis and the ranking are
|
|
77
|
-
yours, never a subagent's — you hold the work's context and you write `03-design.md`.
|
|
79
|
+
**You are the chairman.** The advisors are subagents; the synthesis and the ranking are yours, never
|
|
80
|
+
a subagent's — you hold the work's context and you write `03-design.md`.
|
|
78
81
|
|
|
79
|
-
**
|
|
80
|
-
|
|
82
|
+
**Advisors (parallel, blind to each other).** One subagent per lens, up to `fanout_max`. M → the
|
|
83
|
+
first two lenses; L → add `operations`, and also on a sensitive surface (authentication or
|
|
81
84
|
authorization, payments, personal data, a public contract, a migration):
|
|
82
85
|
|
|
83
86
|
| Lens | Brief |
|
|
84
87
|
|---|---|
|
|
85
|
-
| `minimum` | The **smallest** approach that solves the declared use case,
|
|
86
|
-
| `reuse` | The approach that **most reuses** existing pieces in the affected module or its neighbours |
|
|
88
|
+
| `minimum` | The **smallest** approach that solves the declared use case, built on what the inventory found before anything new (strict MVP) |
|
|
87
89
|
| `reframe` | **Challenge the premise**: what if the problem is solved without building what was asked, or somewhere else? |
|
|
88
90
|
| `operations` | The most production-solid approach (observability, integration failure, data at scale) |
|
|
89
91
|
|
|
@@ -91,31 +93,22 @@ Each advisor gets this brief, with its lens substituted:
|
|
|
91
93
|
|
|
92
94
|
> Propose ONE approach to solve ticket `<TICKET>`, from this lens: `<lens brief>`. Read
|
|
93
95
|
> `.claude/work/<TICKET>/01-context.md` for context and the effective FLOW configuration (base plus
|
|
94
|
-
> active harness overlay) for project conventions.
|
|
96
|
+
> active harness overlay) for project conventions. What already exists in the repository:
|
|
97
|
+
> `<the §1.5.1 inventory>` — propose a new piece only where nothing there fits. Do not
|
|
95
98
|
> write code. Be specific about real modules and layers of this project. Report: name, what it is
|
|
96
99
|
> (one sentence), modules/layers affected, main risk, and why it could be a bad idea. Under 250 words.
|
|
97
100
|
> **Write that same answer to `.claude/work/<TICKET>/approaches/<lens>.md` before you reply** — the
|
|
98
101
|
> file is the deliverable and the reply is a copy of it.
|
|
99
102
|
|
|
100
|
-
**
|
|
101
|
-
*others* from its own lens:
|
|
102
|
-
|
|
103
|
-
> You are the "`<lens>`" advisor. The approaches proposed for `<TICKET>` are in
|
|
104
|
-
> `.claude/work/<TICKET>/approaches/` — read them all, plus `.claude/work/<TICKET>/01-context.md`.
|
|
105
|
-
> From your lens (`<lens brief>`), critique the
|
|
106
|
-
> OTHER approaches — not your own. For each one name its single biggest flaw for THIS project, or
|
|
107
|
-
> "none". Then say which is strongest and which weakest, and why. Be concrete and grounded in the
|
|
108
|
-
> project; do not invent flaws to fill space. **Write your critique to
|
|
109
|
-
> `.claude/work/<TICKET>/approaches/critique-<lens>.md` before you reply.**
|
|
110
|
-
|
|
111
|
-
**Round 3 — you synthesise.** A reply that arrived is already in your context and its file adds
|
|
103
|
+
**Then you synthesise.** A reply that arrived is already in your context and its file adds
|
|
112
104
|
nothing — **open only the files of the lenses that did not answer**, and only then. Rank the
|
|
113
|
-
approaches best to worst *for this case* (project fit and
|
|
114
|
-
|
|
115
|
-
where the advisors **agreed** and where they **disagreed** —
|
|
105
|
+
approaches best to worst *for this case* (project fit and simplicity, not generic merit), weighing
|
|
106
|
+
each one's own "why it could be a bad idea" against the others' — rank on substance, not on which
|
|
107
|
+
advisor wrote best. State explicitly where the advisors **agreed** and where they **disagreed** —
|
|
108
|
+
the disagreement is the useful part.
|
|
116
109
|
|
|
117
|
-
`agents.fanout_tool` set → run the
|
|
118
|
-
|
|
110
|
+
`agents.fanout_tool` set → run the round through that tool instead of plain parallel subagents; the
|
|
111
|
+
lenses, the briefs and the ceiling do not change.
|
|
119
112
|
|
|
120
113
|
**A round that answers nothing is read off disk before it is written off** (flow-core §6). The
|
|
121
114
|
advisors write their files first and reply second, so `ls .claude/work/<TICKET>/approaches/` settles
|
|
@@ -123,15 +116,15 @@ what actually happened: a file there is an answer that got lost in transit, and
|
|
|
123
116
|
it without spending a single agent. Only a lens with no file is empty — **it is asked once for its
|
|
124
117
|
answer and then dropped, never relaunched**, because an empty result is as often a truncated report
|
|
125
118
|
as an advisor with nothing to say, and a relaunched round is paid for twice out of one
|
|
126
|
-
`agents.budget_max`. Synthesise from those that answered and record `N/M`.
|
|
127
|
-
→ rank from the approaches alone.
|
|
119
|
+
`agents.budget_max`. Synthesise from those that answered and record `N/M`.
|
|
128
120
|
|
|
129
121
|
### 1.5.4 Single agent (the S case, or a declined panel)
|
|
130
122
|
|
|
131
123
|
Launch a `general-purpose` subagent with this short, self-contained brief:
|
|
132
124
|
|
|
133
125
|
> Generate 3-5 distinct approaches to solve `<title>` following the project conventions (see
|
|
134
|
-
> the effective FLOW configuration and `.claude/work/<TICKET>/01-context.md`)
|
|
126
|
+
> the effective FLOW configuration and `.claude/work/<TICKET>/01-context.md`), building on what
|
|
127
|
+
> already exists: `<the §1.5.1 inventory>`. For each: a
|
|
135
128
|
> one-sentence description,
|
|
136
129
|
> modules/layers affected, main risk, and why it could be a bad idea. Do not write code. Report in
|
|
137
130
|
> markdown, under 400 words.
|
|
@@ -164,7 +157,7 @@ A sensitive domain (payments, authentication, tracking) → launch **in parallel
|
|
|
164
157
|
|
|
165
158
|
## 3. Prior inventory (reuse before creating)
|
|
166
159
|
|
|
167
|
-
**
|
|
160
|
+
**M/L already ran this in §1.5.1** — reuse that result and skip to §4. XS/S: **before** launching the design subagents, list what the feature needs that **already exists** in code or DB. Launch an `Agent` with `subagent_type: Explore`:
|
|
168
161
|
|
|
169
162
|
> For feature `<title>` (see `.claude/work/<TICKET>/01-context.md`), search the repo for related pieces that already exist and could be reused: domain entities, value objects, repositories, services, events, columns or tables, CQRS commands/queries, and similar endpoints. Do not propose design — only list what is found with one line each and its location. If the feature mentions concepts like `<concept1>`, `<concept2>`, search for those specifically.
|
|
170
163
|
|
|
@@ -70,7 +70,7 @@ This system **orchestrates** the project's existing sub-agents and skills (it do
|
|
|
70
70
|
- **Code review is mandatory**: `/flow-feat-ship` is not run and `/flow-bug-postmortem` is not closed without passing through `/*:review`.
|
|
71
71
|
- **Existing sub-agents**: commands delegate to the project's agents and skills; work is never duplicated.
|
|
72
72
|
- **The subagents' model is the repo's call, never the plugin's (`models` in FLOW.md)**: `agents` (every subagent a command improvises) · `workers` (the fan-out rounds, falling back to `agents`). Empty = **inherit**. There is no key for what the main agent does itself: **an agent cannot switch its own model** (say it, **continue**); **a named agent keeps its own** (`agents.<role>`) — flow-core §1. `/flow-doctor` prints both resolved; `quality.review_skill` owns the review panel.
|
|
73
|
-
- **Parallel multi-agent fan-out (optional, only where it pays)**: plain subagents. (1) `/flow-feat-design` §1.5.3: one agent per lens (minimum /
|
|
73
|
+
- **Parallel multi-agent fan-out (optional, only where it pays)**: plain subagents. (1) `/flow-feat-design` §1.5.3: one agent per lens (minimum / reframe, + operations for L or a sensitive surface), one round, no debate. (2) `/flow-bug-investigate` §3.A: one agent per root cause, evidence **for and against**. (3) `/flow-feat-review` §6 and `/flow-bug-review` §5: one skeptic per **ambiguous** finding, refute-by-default. (4) `/flow-feat-build` §2.1bis and `/flow-bug-fix` §2.2: **one** skeptic on a premise the change depends on and nothing verifies — at **any size, XS included**, once per MR/PR, a category and not a depth tier, like the query duel. Other phases **do not** fan out. `manual`: offered with `AskUserQuestion`; `guided`/`auto`: runs, noted in the artifact. **The fan-out has two ceilings, and the synthesis is not a subagent**: `agents.fanout_max` (empty → **4**) per round and `agents.budget_max` (empty → **12**) for everything one command run launches, with what either cap drops **said** and the phase each command gives up first declared in it; both count agents, not findings, so grouping is intended and one-agent-per-finding past the cap is a breach; the review tier scales to the **diff under review**, not the size of the feature, and the verification gate also needs a **diff over 150 changed lines**; delegate the **gathering**, keep the **deciding**. **A heavier orchestrator is opt-in, per repo**: `agents.fanout_tool` (e.g. Claude Code's `Workflow`), rounds and ceiling unchanged; empty is the default and the portable path.
|
|
74
74
|
- **Knowledge sources (full cycle)**: the `knowledge` section names a tool per **role** — `search`, `stage`, `read_staging`, `save` — any MCP (domain-memory, codegraph…), CLI or skill; a role that is empty degrades (no lookup / finding stays in the artifact / artifacts are the staging / `KNOWLEDGE.md`); `knowledge.timeout_s` (2 s) or any failure → continue silently. **`knowledge.search`**: `/flow-feat-start`, `/flow-bug-start` (ticket keywords), `/flow-feat-design` (approaches, module + integrations), `/flow-bug-investigate` (component in §1.5, cause in §2). **`knowledge.stage`**: closing `/flow-feat-design` and `/flow-bug-investigate`, offer to stage non-obvious domain decisions (silence by default; per-branch). **`knowledge.read_staging`** then **`knowledge.save`** at `/flow-feat-ship` and `/flow-bug-postmortem`: offer to consolidate the "why" only.
|
|
75
75
|
|
|
76
76
|
## `meta.json` schema
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "flow-workflows",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.80.0",
|
|
4
4
|
"description": "Guided feat/bug workflows (start→ship), post-deploy monitoring and multi-agent code review, stack-agnostic. Each repo uses a shared FLOW.md plus optional harness overlay.",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"bin": {
|
|
@@ -3,7 +3,7 @@
|
|
|
3
3
|
"name": "flow",
|
|
4
4
|
"displayName": "Flow — guided dev workflows",
|
|
5
5
|
"description": "Guided feat/bug workflows (start→ship), post-deploy monitoring and multi-agent code review, stack-agnostic. Each repo uses a shared FLOW.md plus optional harness overlay.",
|
|
6
|
-
"version": "0.
|
|
6
|
+
"version": "0.80.0",
|
|
7
7
|
"author": {
|
|
8
8
|
"name": "Alberto Vioque",
|
|
9
9
|
"email": "mashware@gmail.com"
|
|
@@ -5,6 +5,23 @@ plugin and is what `/flow:news` reads to show you what changed since your previo
|
|
|
5
5
|
|
|
6
6
|
The canonical, richest notes live in the [GitHub Releases](https://github.com/mashware/flow-workflows/releases).
|
|
7
7
|
|
|
8
|
+
## v0.80.0 — The advisors were arguing with themselves · 2026-09-25
|
|
9
|
+
|
|
10
|
+
**In short**
|
|
11
|
+
- **The design's approach panel is one round now, with no debate.** The L-only round in which each
|
|
12
|
+
advisor attacked the others is gone: advisors on one base model share its blind spots, and a
|
|
13
|
+
round of them critiquing each other converges on the most confident answer instead of finding a
|
|
14
|
+
new one. The adversarial pass is the challenger that already attacks the chosen design.
|
|
15
|
+
- **`minimum` and `reuse` are one lens.** They kept proposing the same approach. The prior
|
|
16
|
+
inventory now runs **before** the panel and every advisor reads it, so the smallest approach is
|
|
17
|
+
built on what already exists without an agent spent going to look for it.
|
|
18
|
+
- **M runs two advisors (`minimum`, `reframe`), L or a sensitive surface adds `operations`** —
|
|
19
|
+
down from three and four-plus-four.
|
|
20
|
+
- **Measured, not argued.** A new design bench (`evals/design-*`): a duplicate a neighbouring module
|
|
21
|
+
already has, a ticket whose premise one setting answers, and an L change that puts a slow,
|
|
22
|
+
outage-prone provider on the charge path. Before and after: 9 of 9 runs caught every trap in both;
|
|
23
|
+
the three cases went from $17.66 to $13.85, and the L case from $2.89 to $1.78 per run.
|
|
24
|
+
|
|
8
25
|
## v0.79.0 — The reviewer that missed it was never told · 2026-09-23
|
|
9
26
|
|
|
10
27
|
**In short**
|