feature-flow-cli 0.26.0__tar.gz → 0.28.0__tar.gz

{feature_flow_cli-0.26.0 → feature_flow_cli-0.28.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: feature-flow-cli
-Version: 0.26.0
+Version: 0.28.0
 Summary: A ticket-graph workflow for coding agents: installs the feature-flow skill into a repo
 License-Expression: MIT
 Project-URL: Homepage, https://github.com/hamilton-sky/feature-flow
@@ -15,6 +15,8 @@ Classifier: Topic :: Software Development
 Requires-Python: >=3.9
 Description-Content-Type: text/markdown
 License-File: LICENSE
+Provides-Extra: codeintel
+Requires-Dist: codecortex>=0.29; extra == "codeintel"
 Dynamic: license-file
 
 # Feature Flow
@@ -42,7 +44,7 @@ One skill, 12 agent roles, a Python conductor, 6 Python scripts (`flow`, `flow-t
 [docs/releases.md](docs/releases.md) lists what each release added.
 
 - [Quick start](#quick-start) · [How a ticket flows](#how-a-ticket-flows) · [The skill and the roles](#the-skill-and-the-roles) · [Plans and tickets](#plans-and-tickets) · [See the graph](#see-the-graph)
-- [Lanes](#tickets-side-by-side-lanes) · [Scouts](#scouts) · [Questions](#questions-for-the-architect-designer-or-product-owner) · [Acceptance tests](#acceptance-tests-the-tester) · [Fast path](#the-fast-path) · [Time budget](#a-time-budget) · [Eval](#recording-a-run-eval) · [Profiles](#profiles) · [Brainstorm](#brainstorm-before-planning) · [Import](#starting-from-spec-kit-or-openspec)
+- [Lanes](#tickets-side-by-side-lanes) · [Scouts](#scouts) · [codeintel](#codeintel-optional) · [Questions](#questions-for-the-architect-designer-or-product-owner) · [Acceptance tests](#acceptance-tests-the-tester) · [Fast path](#the-fast-path) · [Time budget](#a-time-budget) · [Eval](#recording-a-run-eval) · [Profiles](#profiles) · [Brainstorm](#brainstorm-before-planning) · [Import](#starting-from-spec-kit-or-openspec)
 - [Long features and handoff](#long-features-and-handoff) · [Commands and settings](#commands-and-settings) · [What is tested](#what-is-tested) · [Limits](#limits) · [Upgrading](#upgrading) · [Caution](#caution)
 
 ## Quick start
@@ -332,6 +334,17 @@ Before a planner, builder or reviewer starts, the session can spawn cheap helper
 
 `scouts [lane]` lists `SCOUT <k> <agent> <reply file>` lines (or `NONE`) and clears the last ones' replies; `scout-prompt <k> [lane]` prints one scout's prompt. The session saves each reply into its file, and the phase's `prompt` adds them under `## Scout findings (unverified)`, cut to 60 lines each. A reply saved for one phase never reaches another. Retries and later rounds get no scouts. `FLOW_SCOUTS=off` turns them off.
 
+## codeintel (optional)
+
+[codeintel](https://github.com/hamilton-sky/codeintel) is a separate code-intelligence tool: one command answers who calls a function, what a change would break, or where the code that does something lives, from a call graph, a language server and semantic search. feature-flow never needs it. When it is installed and has the repository indexed, two roles get a short `## codeintel` section in their prompt:
+
+- **Scouts** (`flow-scout`, not `flow-web`) are told to ask it `callers`, `impact` or `search` where grep would take several tries.
+- **Reviewers** (every ticket review and the feature review) are told to run `codeintel query --op changed --target <base>`, which lists each function the change removed, re-signed or rewrote with the callers it did not update.
+
+Each of them ends its reply with one line per question, `codeintel: <op> <target>: helped | no answer | wrong: <why>`, and is told to check an answer before relying on it and to fall back to grep. `eval` counts the queries and those lines, and the verdict form asks whether codeintel helped, made no difference or misled the run, with a line for an answer it got wrong: material for a codeintel issue.
+
+To set it up: `pip install "feature-flow-cli[codeintel]"` (or `pip install codecortex`), then `codeintel setup --all .` in the repository. feature-flow asks `codeintel doctor --json` which engines are ready and keeps the answer for an hour in `.feature-flow/state/codeintel.json`; with nothing ready, or no `codeintel` on PATH, the prompts are as before. `FLOW_CODEINTEL=off` leaves it out. In a lane, the agents run it in the lane's worktree, where codeintel may not have an index, and then fall back to grep. The two tools are released on their own and neither imports the other.
+
 ## Questions for the architect, designer or product owner
 
 A builder, reviewer or planner that hits a question it should not decide alone asks it instead of guessing, and the flow pauses that job until the right role answers.
@@ -377,6 +390,7 @@ Every finished run can leave a record of what it cost and what it caught, so a t
 - **`plans/<feature>/eval.json`**: tickets, builds, reviews and rework; tickets settled when the plan was approved and never built; every catch by the check that made it (gate, floor guard, Done when, test first, footprint, reviewer, feature review); the follow-ups in `followups.md` and the deferred checks; who drove the run (`driver`: `person` or `agent`); where the run needed its driver (stops, questions, handoffs, resets); active minutes; and tokens.
 - **`plans/<feature>/followups.md`**: what the run left for later, committed as it goes: the `minor` findings of every passing review, the findings a level 2 ticket passed with after its full rounds, and each `needs` check (below) that could not pass on this host.
 - **Tokens** come from Claude Code's own session transcripts (`~/.claude/projects/`, or `CLAUDE_CONFIG_DIR`), never from the agent: every message of the sessions and subagents that worked in this repo during the run, each counted once, by model and, without lanes, split per ticket by time. Codex sessions are not read yet.
+- **codeintel**: when an agent asked [codeintel](#codeintel-optional), `codeintel` in `eval.json` counts the queries by op and what the agents said of the answers (helped, no answer, wrong, and why), and the form below asks whether it helped.
 - **`plans/<feature>/eval-verdict.md`**: a form for you. Was the plan right, how many fixes you made by hand, would you use it again, and for each catch whether it was real or a false alarm. Run `--eval` again and your answers land in `eval.json`. The false-alarm count is the only way to tell whether the checks are worth their cost.
 - **Later:** `feature-flow eval <feature> --later`, a week or two on, lists the commits since the run whose subject says fix, revert, bug or regression on the paths each ticket's `Touches:` names: the defects the run let through.
 
@@ -402,7 +416,7 @@ When an idea is still fuzzy, the session can brainstorm it with you before it wr
 
 Read only helpers work for the session during a brainstorm: a code scout, a web scout, the architect, designer and product owner, `flow-skeptic`, who attacks each finished option so the session that wrote the options is not the one that judges them, and `flow-lens`, who looks at the options through one lens the session picks for the idea: `positive`, `researcher`, `open-minded`, `artistic`, `ux` or `security` ([guides/lenses/](guides/lenses/)). Each gets its prompt from `brainstorm-prompt <helper> <question file>`, which counts them: `normal` allows 2 scouts, 1 web, 2 consultants, 1 skeptic and 2 lenses per brainstorm, `careful` 3, 2, 3, 1 and 3, and `FLOW_SCOUTS=off` no scouts. Helpers never write the brainstorm and never ask you anything; the session does both.
 
-Before you pick, the session shows the brainstorm as a review page: `feature-flow brainstorm-page <feature>` (or `flow-status.py <feature> --brainstorm-page`) writes it beside the brainstorm as one HTML file. It has a sidebar that routes between the sections and shows how far you read, a system, light or dark switch, flowchart diagrams you can edit (drag, add boxes of seven kinds, colour them from 12 colours, rename and delete them, connect them with arrows, undo and redo, with the keyboard too), reset, and copy back as mermaid (the edited diagram once you change it; edits are kept only in that browser), and an arrow animation that stays off until you turn it on. Its look is a style: `route` (the default) or `blueprint`, picked with `--style`, the brainstorm's `Style:` line or `FLOW_STYLE`. A style is one CSS file of colour and font tokens in Forkboard's [themes/](packages/forkboard/forkboard/themes/), so adding one is adding a file. `--fragment` leaves out the html and body tags, for publishing the page as an artifact.
+Before you pick, the session shows the brainstorm as a review page: `feature-flow brainstorm-page <feature>` (or `flow-status.py <feature> --brainstorm-page`) writes it beside the brainstorm as one HTML file. It has a sidebar that routes between the sections and shows how far you read, a system, light or dark switch, flowchart diagrams you can edit (arrange them left to right, top to bottom, radial or as a grid, drag, add boxes of seven kinds, colour them from 12 colours, rename and delete them, connect them with arrows, undo and redo, with the keyboard too), reset, and copy back as mermaid (the edited diagram once you change it; edits are kept only in that browser), and an arrow animation that stays off until you turn it on. Its look is a style: `route` (the default), `blueprint`, `sketch`, `paper`, `terminal` or `bright`, picked with `--style`, the brainstorm's `Style:` line or `FLOW_STYLE`; the session picks the one that fits the subject unless you name one, and colours boxes by role. A style is one CSS file of colour, font and box tokens in Forkboard's [themes/](packages/forkboard/forkboard/themes/), so adding one is adding a file. `--fragment` leaves out the html and body tags, for publishing the page as an artifact.
 
 ![A Forkboard review page for a rate-limits brainstorm: a sidebar with the sections and options, option A's diagram with the API gateway box selected and the editing tools above it, and its pros, cons, size and risky areas below](docs/forkboard.png)
 
@@ -493,6 +507,7 @@ The commands in `commands.md` run through `bash -c` on Linux and macOS and throu
 | `FLOW_BUDGET` | unset | read by `start`: minutes of active work before fast mode turns on, then a re-plan offer; `off` drops it |
 | `FLOW_BATCH` | `5` | fast mode: most small tickets one builder takes at once; `1` turns batches off |
 | `FLOW_SCOUTS` | `on` | `off` lists no scouts before any phase |
+| `FLOW_CODEINTEL` | `auto` | `off` keeps codeintel out of the scout's and reviewer's prompts; `auto` adds it when `codeintel doctor` reports an engine ready |
 | `FLOW_TAKEOVER` | unset | `1` lets `start` take a feature over from a session that is gone |
 | `FLOW_MAX_RETRIES` | `2` | builds or reviews per step before the run stops |
 | `FLOW_MAX_REVIEW_ROUNDS` | `3` | times a ticket may be sent back before the run stops (a level 1 ticket: once) |
@@ -505,7 +520,7 @@ The commands in `commands.md` run through `bash -c` on Linux and macOS and throu
 | `FLOW_DIR`, `FLOW_TICKETS` | `plans`, `tasks` | where the plans and the ticket folder live |
 | `FLOW_NO_OPEN` | unset | `1` makes `flow-view.py` never open a browser |
 | `FLOW_WATCH_SECONDS` | `3` | how often `flow-view.py --watch` rewrites the page |
-| `FLOW_STYLE` | `route` | the brainstorm page's look when the brainstorm has no `Style:` line: `route` or `blueprint` (Forkboard's themes) |
+| `FLOW_STYLE` | `route` | the brainstorm page's look when the brainstorm has no `Style:` line: `route`, `blueprint`, `sketch`, `paper`, `terminal` or `bright` (Forkboard's themes) |
 
 The run also stops on its own after a number of phases (`BUILD` and `REVIEW` hand-outs, the spec review and the quality review each counting as one, a single review counting as one) that grows with the ticket count, recomputed at every pick, so a loop of failures cannot go on forever.
 

feature_flow_cli-0.26.0/feature_flow_cli.egg-info/PKG-INFO → feature_flow_cli-0.28.0/README.md

@@ -1,22 +1,3 @@
-Metadata-Version: 2.4
-Name: feature-flow-cli
-Version: 0.26.0
-Summary: A ticket-graph workflow for coding agents: installs the feature-flow skill into a repo
-License-Expression: MIT
-Project-URL: Homepage, https://github.com/hamilton-sky/feature-flow
-Project-URL: Source, https://github.com/hamilton-sky/feature-flow
-Keywords: claude-code,codex,agents,workflow,tickets
-Classifier: Development Status :: 3 - Alpha
-Classifier: Environment :: Console
-Classifier: Intended Audience :: Developers
-Classifier: Operating System :: OS Independent
-Classifier: Programming Language :: Python :: 3
-Classifier: Topic :: Software Development
-Requires-Python: >=3.9
-Description-Content-Type: text/markdown
-License-File: LICENSE
-Dynamic: license-file
-
 # Feature Flow
 
 **A ticket-graph workflow for coding agents.** Works with Claude Code and Codex.
@@ -42,7 +23,7 @@ One skill, 12 agent roles, a Python conductor, 6 Python scripts (`flow`, `flow-t
 [docs/releases.md](docs/releases.md) lists what each release added.
 
 - [Quick start](#quick-start) · [How a ticket flows](#how-a-ticket-flows) · [The skill and the roles](#the-skill-and-the-roles) · [Plans and tickets](#plans-and-tickets) · [See the graph](#see-the-graph)
-- [Lanes](#tickets-side-by-side-lanes) · [Scouts](#scouts) · [Questions](#questions-for-the-architect-designer-or-product-owner) · [Acceptance tests](#acceptance-tests-the-tester) · [Fast path](#the-fast-path) · [Time budget](#a-time-budget) · [Eval](#recording-a-run-eval) · [Profiles](#profiles) · [Brainstorm](#brainstorm-before-planning) · [Import](#starting-from-spec-kit-or-openspec)
+- [Lanes](#tickets-side-by-side-lanes) · [Scouts](#scouts) · [codeintel](#codeintel-optional) · [Questions](#questions-for-the-architect-designer-or-product-owner) · [Acceptance tests](#acceptance-tests-the-tester) · [Fast path](#the-fast-path) · [Time budget](#a-time-budget) · [Eval](#recording-a-run-eval) · [Profiles](#profiles) · [Brainstorm](#brainstorm-before-planning) · [Import](#starting-from-spec-kit-or-openspec)
 - [Long features and handoff](#long-features-and-handoff) · [Commands and settings](#commands-and-settings) · [What is tested](#what-is-tested) · [Limits](#limits) · [Upgrading](#upgrading) · [Caution](#caution)
 
 ## Quick start
@@ -332,6 +313,17 @@ Before a planner, builder or reviewer starts, the session can spawn cheap helper
 
 `scouts [lane]` lists `SCOUT <k> <agent> <reply file>` lines (or `NONE`) and clears the last ones' replies; `scout-prompt <k> [lane]` prints one scout's prompt. The session saves each reply into its file, and the phase's `prompt` adds them under `## Scout findings (unverified)`, cut to 60 lines each. A reply saved for one phase never reaches another. Retries and later rounds get no scouts. `FLOW_SCOUTS=off` turns them off.
 
+## codeintel (optional)
+
+[codeintel](https://github.com/hamilton-sky/codeintel) is a separate code-intelligence tool: one command answers who calls a function, what a change would break, or where the code that does something lives, from a call graph, a language server and semantic search. feature-flow never needs it. When it is installed and has the repository indexed, two roles get a short `## codeintel` section in their prompt:
+
+- **Scouts** (`flow-scout`, not `flow-web`) are told to ask it `callers`, `impact` or `search` where grep would take several tries.
+- **Reviewers** (every ticket review and the feature review) are told to run `codeintel query --op changed --target <base>`, which lists each function the change removed, re-signed or rewrote with the callers it did not update.
+
+Each of them ends its reply with one line per question, `codeintel: <op> <target>: helped | no answer | wrong: <why>`, and is told to check an answer before relying on it and to fall back to grep. `eval` counts the queries and those lines, and the verdict form asks whether codeintel helped, made no difference or misled the run, with a line for an answer it got wrong: material for a codeintel issue.
+
+To set it up: `pip install "feature-flow-cli[codeintel]"` (or `pip install codecortex`), then `codeintel setup --all .` in the repository. feature-flow asks `codeintel doctor --json` which engines are ready and keeps the answer for an hour in `.feature-flow/state/codeintel.json`; with nothing ready, or no `codeintel` on PATH, the prompts are as before. `FLOW_CODEINTEL=off` leaves it out. In a lane, the agents run it in the lane's worktree, where codeintel may not have an index, and then fall back to grep. The two tools are released on their own and neither imports the other.
+
 ## Questions for the architect, designer or product owner
 
 A builder, reviewer or planner that hits a question it should not decide alone asks it instead of guessing, and the flow pauses that job until the right role answers.
@@ -377,6 +369,7 @@ Every finished run can leave a record of what it cost and what it caught, so a t
 - **`plans/<feature>/eval.json`**: tickets, builds, reviews and rework; tickets settled when the plan was approved and never built; every catch by the check that made it (gate, floor guard, Done when, test first, footprint, reviewer, feature review); the follow-ups in `followups.md` and the deferred checks; who drove the run (`driver`: `person` or `agent`); where the run needed its driver (stops, questions, handoffs, resets); active minutes; and tokens.
 - **`plans/<feature>/followups.md`**: what the run left for later, committed as it goes: the `minor` findings of every passing review, the findings a level 2 ticket passed with after its full rounds, and each `needs` check (below) that could not pass on this host.
 - **Tokens** come from Claude Code's own session transcripts (`~/.claude/projects/`, or `CLAUDE_CONFIG_DIR`), never from the agent: every message of the sessions and subagents that worked in this repo during the run, each counted once, by model and, without lanes, split per ticket by time. Codex sessions are not read yet.
+- **codeintel**: when an agent asked [codeintel](#codeintel-optional), `codeintel` in `eval.json` counts the queries by op and what the agents said of the answers (helped, no answer, wrong, and why), and the form below asks whether it helped.
 - **`plans/<feature>/eval-verdict.md`**: a form for you. Was the plan right, how many fixes you made by hand, would you use it again, and for each catch whether it was real or a false alarm. Run `--eval` again and your answers land in `eval.json`. The false-alarm count is the only way to tell whether the checks are worth their cost.
 - **Later:** `feature-flow eval <feature> --later`, a week or two on, lists the commits since the run whose subject says fix, revert, bug or regression on the paths each ticket's `Touches:` names: the defects the run let through.
 
@@ -402,7 +395,7 @@ When an idea is still fuzzy, the session can brainstorm it with you before it wr
 
 Read only helpers work for the session during a brainstorm: a code scout, a web scout, the architect, designer and product owner, `flow-skeptic`, who attacks each finished option so the session that wrote the options is not the one that judges them, and `flow-lens`, who looks at the options through one lens the session picks for the idea: `positive`, `researcher`, `open-minded`, `artistic`, `ux` or `security` ([guides/lenses/](guides/lenses/)). Each gets its prompt from `brainstorm-prompt <helper> <question file>`, which counts them: `normal` allows 2 scouts, 1 web, 2 consultants, 1 skeptic and 2 lenses per brainstorm, `careful` 3, 2, 3, 1 and 3, and `FLOW_SCOUTS=off` no scouts. Helpers never write the brainstorm and never ask you anything; the session does both.
 
-Before you pick, the session shows the brainstorm as a review page: `feature-flow brainstorm-page <feature>` (or `flow-status.py <feature> --brainstorm-page`) writes it beside the brainstorm as one HTML file. It has a sidebar that routes between the sections and shows how far you read, a system, light or dark switch, flowchart diagrams you can edit (drag, add boxes of seven kinds, colour them from 12 colours, rename and delete them, connect them with arrows, undo and redo, with the keyboard too), reset, and copy back as mermaid (the edited diagram once you change it; edits are kept only in that browser), and an arrow animation that stays off until you turn it on. Its look is a style: `route` (the default) or `blueprint`, picked with `--style`, the brainstorm's `Style:` line or `FLOW_STYLE`. A style is one CSS file of colour and font tokens in Forkboard's [themes/](packages/forkboard/forkboard/themes/), so adding one is adding a file. `--fragment` leaves out the html and body tags, for publishing the page as an artifact.
+Before you pick, the session shows the brainstorm as a review page: `feature-flow brainstorm-page <feature>` (or `flow-status.py <feature> --brainstorm-page`) writes it beside the brainstorm as one HTML file. It has a sidebar that routes between the sections and shows how far you read, a system, light or dark switch, flowchart diagrams you can edit (arrange them left to right, top to bottom, radial or as a grid, drag, add boxes of seven kinds, colour them from 12 colours, rename and delete them, connect them with arrows, undo and redo, with the keyboard too), reset, and copy back as mermaid (the edited diagram once you change it; edits are kept only in that browser), and an arrow animation that stays off until you turn it on. Its look is a style: `route` (the default), `blueprint`, `sketch`, `paper`, `terminal` or `bright`, picked with `--style`, the brainstorm's `Style:` line or `FLOW_STYLE`; the session picks the one that fits the subject unless you name one, and colours boxes by role. A style is one CSS file of colour, font and box tokens in Forkboard's [themes/](packages/forkboard/forkboard/themes/), so adding one is adding a file. `--fragment` leaves out the html and body tags, for publishing the page as an artifact.
 
 ![A Forkboard review page for a rate-limits brainstorm: a sidebar with the sections and options, option A's diagram with the API gateway box selected and the editing tools above it, and its pros, cons, size and risky areas below](docs/forkboard.png)
 
@@ -493,6 +486,7 @@ The commands in `commands.md` run through `bash -c` on Linux and macOS and throu
 | `FLOW_BUDGET` | unset | read by `start`: minutes of active work before fast mode turns on, then a re-plan offer; `off` drops it |
 | `FLOW_BATCH` | `5` | fast mode: most small tickets one builder takes at once; `1` turns batches off |
 | `FLOW_SCOUTS` | `on` | `off` lists no scouts before any phase |
+| `FLOW_CODEINTEL` | `auto` | `off` keeps codeintel out of the scout's and reviewer's prompts; `auto` adds it when `codeintel doctor` reports an engine ready |
 | `FLOW_TAKEOVER` | unset | `1` lets `start` take a feature over from a session that is gone |
 | `FLOW_MAX_RETRIES` | `2` | builds or reviews per step before the run stops |
 | `FLOW_MAX_REVIEW_ROUNDS` | `3` | times a ticket may be sent back before the run stops (a level 1 ticket: once) |
@@ -505,7 +499,7 @@ The commands in `commands.md` run through `bash -c` on Linux and macOS and throu
 | `FLOW_DIR`, `FLOW_TICKETS` | `plans`, `tasks` | where the plans and the ticket folder live |
 | `FLOW_NO_OPEN` | unset | `1` makes `flow-view.py` never open a browser |
 | `FLOW_WATCH_SECONDS` | `3` | how often `flow-view.py --watch` rewrites the page |
-| `FLOW_STYLE` | `route` | the brainstorm page's look when the brainstorm has no `Style:` line: `route` or `blueprint` (Forkboard's themes) |
+| `FLOW_STYLE` | `route` | the brainstorm page's look when the brainstorm has no `Style:` line: `route`, `blueprint`, `sketch`, `paper`, `terminal` or `bright` (Forkboard's themes) |
 
 The run also stops on its own after a number of phases (`BUILD` and `REVIEW` hand-outs, the spec review and the quality review each counting as one, a single review counting as one) that grows with the ticket count, recomputed at every pick, so a loop of failures cannot go on forever.
 

{feature_flow_cli-0.26.0 → feature_flow_cli-0.28.0}/feature_flow/__init__.py

@@ -1,3 +1,3 @@
 """Feature Flow: a ticket-graph workflow for coding agents."""
 
-__version__ = "0.26.0"
+__version__ = "0.28.0"

feature_flow_cli-0.28.0/feature_flow/codeintel.py

@@ -0,0 +1,127 @@
+"""codeintel: an optional code-intelligence tool the scouts and reviewers may ask, when it is installed.
+
+feature-flow never imports or installs it (`pip install feature-flow-cli[codeintel]` does). When the `codeintel`
+command is on PATH and its `doctor` says an engine is ready for this repository, the scout's and the reviewer's
+prompts get a short section on when to ask it, and each agent ends its reply with one line per question it asked.
+`feature-flow eval` counts the questions and those lines, so a run says whether codeintel helped. The doctor's
+answer is kept for an hour in the state folder. FLOW_CODEINTEL=off leaves codeintel out.
+"""
+
+import json
+import os
+import re
+import shutil
+import subprocess
+import time
+from pathlib import Path
+
+from feature_flow import state
+
+CACHE = "codeintel.json"
+FRESH = 3600  # seconds the doctor's answer is kept
+TIMEOUT = 30  # seconds the doctor may take
+OPS = {"graph": "callers, callees, impact, changed", "semantic": "search", "lsp": "symbol"}
+VERDICTS = ("helped", "no answer", "wrong")
+LINE = re.compile(r"^[\s>*-]*codeintel: (?!<)(\S+) (.+?): (helped|no answer|wrong)\b[:,]?\s*(.*)$")
+QUERY = re.compile(r"\bcodeintel\s+query\b.*?--op[=\s]+([\w-]+)")
+
+
+def ready(repo="."):
+    """The engines codeintel has ready for repo, such as ["graph", "semantic"]; [] when it is off or missing."""
+    if os.environ.get("FLOW_CODEINTEL", "auto") == "off":
+        return []
+    exe = shutil.which("codeintel")
+    if exe is None:
+        return []
+    top = Path(repo).resolve()
+    cache = top / state.STATE_DIR / CACHE
+    try:
+        saved = json.loads(cache.read_text(encoding="utf-8"))
+        if saved.get("exe") == exe and 0 <= time.time() - float(saved.get("checked", 0)) < FRESH:
+            return [e for e in saved.get("ready") or [] if e in OPS]
+    except (OSError, ValueError, TypeError, AttributeError):
+        pass
+    found = probe(exe, top)
+    try:
+        cache.parent.mkdir(parents=True, exist_ok=True)
+        cache.write_text(json.dumps({"exe": exe, "checked": time.time(), "ready": found}) + "\n", encoding="utf-8")
+    except OSError:
+        pass
+    return found
+
+
+def probe(exe, top):
+    """Ask `codeintel doctor --json` which engines are installed, runnable and have top indexed."""
+    try:
+        result = subprocess.run([exe, "doctor", "--json", str(top)], cwd=str(top), stdin=subprocess.DEVNULL,
+                                capture_output=True, text=True, timeout=TIMEOUT)
+        engines = json.loads(result.stdout).get("engines") or {}
+        return sorted(name for name, row in engines.items()
+                      if name in OPS and isinstance(row, dict) and row.get("status") == "ok")
+    except (OSError, subprocess.SubprocessError, ValueError, AttributeError):
+        return []
+
+
+def note(role, repo=".", base=None):
+    """The section a scout's or reviewer's prompt gets when codeintel is ready, else ""."""
+    engines = ready(repo)
+    if not engines:
+        return ""
+    ops = "; ".join("`%s` (%s engine)" % (OPS[e].replace(", ", "`, `"), e) for e in engines)
+    if role == "reviewer" and "graph" in engines:
+        ask = ("`codeintel query --op changed --target %s` lists each function this change removed, re-signed or "
+               "rewrote, with the callers it did not update: check those callers." % (base or "<base commit>"))
+    else:
+        ask = ("Ask it who calls a function or what a change would break (`--op callers` or `--op impact` with "
+               "`--target <name>`), or where the code that does something lives (`--op search --target \"<what it "
+               "does>\"`).")
+    return ("\n## codeintel\n\ncodeintel, a code-intelligence tool, is installed for this repository. Where grep "
+            "would take several tries, ask it once with `codeintel query --op <op> --target <name>`, a read only "
+            "command. Ready here: %s. %s Its answers can be wrong, empty or older than the code: check one before you "
+            "rely on it, and fall back to grep.\n\nAt the end of your reply, before any last verdict line, add one "
+            "line for each codeintel query you ran, so the run can judge the tool:\n\n"
+            "    codeintel: <op> <target>: helped | no answer | wrong: <what it got wrong>\n" % (ops, ask))
+
+
+# ---- what a run's transcripts say about codeintel, for eval ----------------------------
+
+def use(records):
+    """{"queries": {op: n}, "said": {verdict: n}, "wrong": [...]} from transcript records (dicts), or None
+    when codeintel was never asked."""
+    queries, said, wrong, seen = {}, {}, [], set()
+    for item in records:
+        message = item.get("message") if isinstance(item, dict) else None
+        blocks = message.get("content") if isinstance(message, dict) else None
+        if not isinstance(blocks, list):
+            continue
+        for block in blocks:
+            if not isinstance(block, dict):
+                continue
+            if block.get("type") == "tool_use":
+                op = _asked(block)
+                if op and ("tool", block.get("id")) not in seen:
+                    seen.add(("tool", block.get("id")))
+                    queries[op] = queries.get(op, 0) + 1
+            elif block.get("type") == "text" and "codeintel:" in str(block.get("text")):
+                for line in str(block["text"]).splitlines():
+                    found = LINE.match(line)
+                    if not found or ("line", line.strip()) in seen:
+                        continue
+                    seen.add(("line", line.strip()))
+                    op, target, verdict, why = found.groups()
+                    said[verdict] = said.get(verdict, 0) + 1
+                    if verdict == "wrong" and len(wrong) < 20:
+                        wrong.append({"op": op, "target": target.strip("`"), "why": why.strip()})
+    if not queries and not said:
+        return None
+    return {"queries": queries, "said": said, "wrong": wrong}
+
+
+def _asked(block):
+    """The op of a codeintel query made by this tool call, "" when it is not one."""
+    name = str(block.get("name") or "")
+    args = block.get("input") if isinstance(block.get("input"), dict) else {}
+    if "codeintel" in name.lower():
+        return str(args.get("op") or name.rsplit("__", 1)[-1])
+    found = QUERY.search(str(args.get("command") or ""))
+    return found.group(1) if found else ""

{feature_flow_cli-0.26.0 → feature_flow_cli-0.28.0}/feature_flow/conductor.py

@@ -1668,7 +1668,7 @@ class Conductor:
         about = ("The user's session is brainstorming how to build the feature `%s`, before it is planned: no brief "
                  "and no plan exist yet." % self.feature)
         if group in ("scout", "web"):
-            out = scouts.prompt(role_text, "planner", about + "\n\n" + question)
+            out = scouts.prompt(role_text, "planner", about + "\n\n" + question, codeintel=group == "scout")
         elif group == "lens":
             out = ("%s\n\n---\n\nYour lens is `%s`. Its guide follows.\n\n%s\n\n---\n\n%s The options it drafted "
                    "follow. Read the repository.\n\n%s\n\nDo not edit any file. Your final reply must end with exactly "
@@ -1766,7 +1766,7 @@ class Conductor:
             role_text = prompts.role(self.scripts, agent + ".md")
         except FileNotFoundError as err:
             raise Stop(str(err))
-        return scouts.prompt(role_text, role, question, workdir)
+        return scouts.prompt(role_text, role, question, workdir, codeintel=agent == "flow-scout")
 
     def scout_findings(self):
         """The scout replies saved for the phase handed out last, as a section for its prompt, or ""."""

{feature_flow_cli-0.26.0 → feature_flow_cli-0.28.0}/feature_flow/evaluate.py

@@ -5,6 +5,8 @@ Reads the run log and state in .feature-flow/state/, the plan's tickets, and, wh
 Claude Code session transcripts of this repo (for tokens). Writes <out>/eval.json, and the first time
 <out>/eval-verdict.md, a short form you fill in: was the plan right, what did you fix by hand, and was
 each catch real or a false alarm. Run it again after filling the form and eval.json carries your answers.
+When the agents asked codeintel (feature_flow/codeintel.py), the record counts their queries and what they said
+of each answer, and the form asks whether it helped.
 --later also looks at the commits made after the run for fixes and reverts on the files each ticket
 touched: run it a week or two after the feature is done. <out> is plans/<feature>/ unless --out is given,
 so the record is committed with the plan and survives a cloud session. Nothing is sent anywhere.
@@ -18,7 +20,7 @@ import time
 from datetime import datetime, timezone
 from pathlib import Path
 
-from feature_flow import __version__, git, lanes, report, state, suggest, tickets
+from feature_flow import __version__, codeintel, git, lanes, report, state, suggest, tickets
 
 USAGE = "usage: feature-flow eval <feature> [--later] [--out DIR] [--claude-home DIR]"
 CATCHES = report.FAILS + ("FOOTPRINT-FAIL", "FEATURE-FAIL", "ACCEPT-FAIL")
@@ -137,20 +139,15 @@ def _inside(cwd, top):
         return False
 
 
-def tokens(home, top, window, rows):
-    """Token use of the Claude Code sessions (and their subagents) that worked in this repo during the
-    run, summed from the transcripts' usage records, each message counted once. Split per ticket by
-    time slice: a record goes to the ticket of the last log line before it (approximate; with lanes
-    the slices overlap, so no split is given). None when there is nothing to read."""
+def records(home, top, window):
+    """(file, record) for each transcript record written in this repo during the run, from Claude Code's session
+    transcripts (and their subagents'). Nothing when there is no window or no transcripts."""
     projects = Path(home) / "projects"
     if window is None or not projects.is_dir():
-        return None
+        return
     start, end = window
     since = start.timestamp() - 60
     top = Path(top).resolve()
-    marks = sorted((t, num) for t, num, _, _ in rows if t is not None)
-    seen, total, models, per = set(), {}, {}, {}
-    files = 0
     for path in projects.rglob("*.jsonl"):
         try:
             if path.stat().st_mtime < since:
@@ -158,46 +155,59 @@ def tokens(home, top, window, rows):
             handle = open(path, encoding="utf-8", errors="replace")
         except OSError:
             continue
-        used = False
         with handle:
             for line in handle:
-                if '"usage"' not in line:
+                if '"message"' not in line:
                     continue
                 try:
                     item = json.loads(line)
                 except ValueError:
                     continue
-                message = item.get("message") if isinstance(item, dict) else None
-                usage = message.get("usage") if isinstance(message, dict) else None
-                if not isinstance(usage, dict) or not _inside(item.get("cwd") or "", top):
+                if not isinstance(item, dict) or not isinstance(item.get("message"), dict):
+                    continue
+                if not _inside(item.get("cwd") or "", top):
                     continue
                 when = parse_iso(item.get("timestamp"))
                 if when is None or when < start or when > end:
                     continue
-                key = (message.get("id"), item.get("requestId"))
-                if key != (None, None):
-                    if key in seen:
-                        continue
-                    seen.add(key)
-                used = True
-                counts = {
-                    "input": int(usage.get("input_tokens") or 0),
-                    "output": int(usage.get("output_tokens") or 0),
-                    "cache_read": int(usage.get("cache_read_input_tokens") or 0),
-                    "cache_write": int(usage.get("cache_creation_input_tokens") or 0),
-                }
-                add(total, counts)
-                add(models.setdefault(message.get("model") or "unknown", {}), counts)
-                num = "-"
-                for t, n in marks:
-                    if t > when:
-                        break
-                    num = n
-                add(per.setdefault(num, {}), counts)
-        files += used
+                yield path, item
+
+
+def tokens(found, rows):
+    """Token use of the transcript records found, summed from their usage records, each message counted once.
+    Split per ticket by time slice: a record goes to the ticket of the last log line before it (approximate; with
+    lanes the slices overlap, so no split is given). None when there is nothing to read."""
+    marks = sorted((t, num) for t, num, _, _ in rows if t is not None)
+    seen, total, models, per, files = set(), {}, {}, {}, set()
+    for path, item in found:
+        message = item["message"]
+        usage = message.get("usage")
+        if not isinstance(usage, dict):
+            continue
+        key = (message.get("id"), item.get("requestId"))
+        if key != (None, None):
+            if key in seen:
+                continue
+            seen.add(key)
+        files.add(path)
+        counts = {
+            "input": int(usage.get("input_tokens") or 0),
+            "output": int(usage.get("output_tokens") or 0),
+            "cache_read": int(usage.get("cache_read_input_tokens") or 0),
+            "cache_write": int(usage.get("cache_creation_input_tokens") or 0),
+        }
+        add(total, counts)
+        add(models.setdefault(message.get("model") or "unknown", {}), counts)
+        when = parse_iso(item.get("timestamp"))
+        num = "-"
+        for t, n in marks:
+            if t > when:
+                break
+            num = n
+        add(per.setdefault(num, {}), counts)
     if not total:
         return None
-    return {"source": "claude-code transcripts", "files": files, "total": total, "by_model": models,
+    return {"source": "claude-code transcripts", "files": len(files), "total": total, "by_model": models,
             "by_ticket": per, "by_ticket_note": "approximate: split by the time between log lines"}
 
 
@@ -217,7 +227,7 @@ def add(into, counts):
 
 # ---- the human verdict ---------------------------------------------------------------
 
-def verdict_template(feature, catches, driven_by="person"):
+def verdict_template(feature, catches, driven_by="person", asked_codeintel=False):
     minutes = ("minutes-of-your-time: (roughly, answering questions and reviewing)" if driven_by != "agent" else
                "minutes-of-your-time: (an agent drove this run: only the minutes you spent yourself, 0 if none)")
     lines = [
@@ -230,6 +240,11 @@ def verdict_template(feature, catches, driven_by="person"):
         "would-use-again: (yes | no)",
         minutes,
         "note: ",
+    ]
+    if asked_codeintel:
+        lines += ["codeintel: (helped | no difference | misled: did codeintel's answers help this run?)",
+                  "codeintel-note: (an answer it got wrong or could not give, for a codeintel issue)"]
+    lines += [
         "",
         "## Catches",
         "",
@@ -256,7 +271,8 @@ def read_verdict(path):
             word = re.match(r"[a-z]*", value.lower()).group(0)
             if word in ("real", "false"):
                 catches[key] = word
-        elif key in ("plan", "hand-fixes", "would-use-again", "minutes-of-your-time", "note"):
+        elif key in ("plan", "hand-fixes", "would-use-again", "minutes-of-your-time", "note", "codeintel",
+                     "codeintel-note"):
             answers[key.replace("-", "_")] = value
     if "plan" in answers and answers["plan"].split()[0].lower() not in PLAN_ANSWERS:
         answers["plan_unrecognised"] = answers.pop("plan")
@@ -320,6 +336,7 @@ def build(feature, top, out_dir, home, with_later):
     spent = run_state.get("spent", "")
     plan_dir = Path(top) / os.environ.get("FLOW_DIR", "plans") / feature
     driven_by = driver(rows, run_state)
+    found = list(records(home, top, window))
     totals["settled_at_plan"] = settled_at_plan(plan_dir, per)
     totals["followups"] = followups(plan_dir)
     record = {
@@ -333,7 +350,8 @@ def build(feature, top, out_dir, home, with_later):
         "driver": driven_by,
         "brainstorm": brainstorm(plan_dir, rows),
         "you": human,
-        "tokens": tokens(home, top, window, rows),
+        "tokens": tokens(found, rows),
+        "codeintel": codeintel.use(item for _, item in found),
         "verdict": read_verdict(out_dir / VERDICT_FILE),
     }
     if record["tokens"] and totals["lanes"]:
@@ -369,6 +387,12 @@ def render(record, out_dir, wrote_form):
     else:
         lines.append("  tokens: not found (no Claude Code transcripts for this repo in the run window,"
                      " or a log from before 0.15.0)")
+    ci = record.get("codeintel")
+    if ci:
+        lines.append("  codeintel: %d quer%s (%s); the agents said %s" % (
+            sum(ci["queries"].values()), "y" if sum(ci["queries"].values()) == 1 else "ies",
+            ", ".join("%s x%d" % kv for kv in sorted(ci["queries"].items())) or "none seen",
+            ", ".join("%s x%d" % (v, ci["said"][v]) for v in codeintel.VERDICTS if ci["said"].get(v)) or "nothing"))
     you = record["you"]
     lines.append("  %s: %d stop(s), %d question(s), %d handoff(s), %d reset(s)"
                  % ("needed the driving agent (not you)" if record.get("driver") == "agent" else "needed you",
@@ -377,7 +401,8 @@ def render(record, out_dir, wrote_form):
     if verdict:
         lines.append("  your verdict: plan %s, %s hand fix(es), %s real catch(es), %s false alarm(s)"
                      % (verdict.get("plan", "?"), verdict.get("hand_fixes", "?"),
-                        verdict.get("real_catches", "?"), verdict.get("false_alarms", "?")))
+                        verdict.get("real_catches", "?"), verdict.get("false_alarms", "?"))
+                     + (", codeintel %s" % verdict["codeintel"] if verdict.get("codeintel") else ""))
     elif wrote_form:
         lines.append("  fill in %s, then run eval again" % (out_dir / VERDICT_FILE))
     else:
@@ -430,7 +455,8 @@ def main(argv, out=None, err=None):
     form = out_dir / VERDICT_FILE
     wrote_form = not form.exists()
     if wrote_form:
-        form.write_text(verdict_template(feature, catches, record["driver"]), encoding="utf-8")
+        form.write_text(verdict_template(feature, catches, record["driver"], bool(record["codeintel"])),
+                        encoding="utf-8")
     (out_dir / "eval.json").write_text(json.dumps(record, indent=2, sort_keys=True) + "\n", encoding="utf-8")
     out.write(render(record, out_dir, wrote_form))
     return 0

{feature_flow_cli-0.26.0 → feature_flow_cli-0.28.0}/feature_flow/prompts.py

@@ -7,6 +7,8 @@ import re
 import shlex
 from pathlib import Path
 
+from feature_flow import codeintel
+
 ROLES = {"build": "ticket-builder.md", "review": "ticket-reviewer.md", "review-quality": "ticket-reviewer.md",
          "review-single": "ticket-reviewer.md",
          "review-feature": "ticket-reviewer.md", "plan": "feature-planner.md", "plan-review": "plan-reviewer.md",
@@ -106,6 +108,7 @@ def build(phase, scripts, feature, ticket, num, sha, notes=(), retry=False, work
                    fresh))
         for note in notes:
             task += "\nThe conductor notes: %s" % note
+        task += codeintel.note("reviewer", REPO, sha)
         intro = "The review guide follows. Follow it exactly."
     if workdir is not None:
         folder, branch = workdir
@@ -135,6 +138,7 @@ def feature_review(scripts, feature, plan, base, nums, notes=(), tasks="tasks"):
             "`REVIEW: PASS` or `REVIEW: FAIL`." % (feature, base, plan, ", ".join(nums) or "none"))
     for note in notes:
         task += "\nThe conductor notes: %s" % note
+    task += codeintel.note("reviewer", REPO, base)
     parts = [role_text, "---", "The feature review guide follows. Follow it exactly.", guide, "---", task]
     return "\n\n".join(parts) + "\n"
 

{feature_flow_cli-0.26.0 → feature_flow_cli-0.28.0}/feature_flow/scouts.py

@@ -8,6 +8,8 @@ import hashlib
 import shlex
 from pathlib import Path
 
+from feature_flow import codeintel as code_intel, prompts
+
 MAX = 3  # most scouts for one phase
 LINES = 60  # most lines of one reply that go into the prompt
 
@@ -82,9 +84,12 @@ def listing(folder, feature, slot, found):
                      for k, (agent, _, _) in enumerate(found, 1))
 
 
-def prompt(role_text, role, question, workdir=None):
-    """A scout's whole prompt: its role file, then the role it scouts for and the question."""
+def prompt(role_text, role, question, workdir=None, codeintel=False):
+    """A scout's whole prompt: its role file, then the role it scouts for and the question, and with codeintel
+    the section on asking codeintel when it is ready."""
     task = "ROLE: %s\n\n%s\n\nReply in the shape your role gives, and change nothing." % (role, question)
+    if codeintel:
+        task += code_intel.note("scout", prompts.REPO)
     if workdir is not None:
         task = ("Work in the folder `%s`: it is the worktree the %s will work in. Run `cd %s` before any git "
                 "command, and read every path here relative to it, as `%s/<path>`.\n\n%s"