feature-flow-cli 0.1.0__py3-none-any.whl

feature_flow/__init__.py

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

feature_flow/__main__.py

@@ -0,0 +1,7 @@
+"""python -m feature_flow: the same as the feature-flow command."""
+
+import sys
+
+from feature_flow.command import main
+
+sys.exit(main())

feature_flow/_bundle/adapters/codex/feature-flow/SKILL.md

@@ -0,0 +1,62 @@
+---
+name: feature-flow
+description: "Use to plan a feature or build its tickets, one fresh builder and one fresh reviewer subagent per ticket, with scripts/flow.py deciding every step. Also draws the ticket graph with show."
+---
+
+`<arguments>` below stands for the text the user typed after `$feature-flow`.
+
+Plan or build the feature in `<arguments>`.
+
+The first word is the **feature**. `show` means draw the graph. `auto` means ask nothing and go. If no feature was given, list `plans/*/` and ask which one.
+
+The conductor is `python3 scripts/flow.py <feature> <command>`. It decides the order, runs the gate and the floor guard, and keeps its state in `.feature-flow/state/`, a folder git ignores. You ask it, and you do what it says. The guides it uses are in `.feature-flow/guides/` (in a feature-flow checkout, `guides/`). Read the project's `AGENTS.md` for its conventions.
+
+## Show
+
+With `show`, follow `.feature-flow/guides/show.md` for the feature and stop.
+
+## Plan
+
+If `plans/<feature>/` does not exist, run `FLOW_INVOKE='$feature-flow' python3 scripts/flow.py <feature> start` and check that it prints `PLAN`. Then:
+
+1. Follow `.feature-flow/guides/plan.md` with the user.
+2. Run `python3 scripts/flow-status.py <feature> --check` and fix every problem.
+3. Stop. List the files you created and suggest the commit command (`git add plans/<feature> && git commit -m "docs(<feature>): plan"`). Say to commit the plan and run `$feature-flow <feature>` again. While the plan is uncommitted, do not say the feature is ready to build.
+
+## Before building
+
+With a plan present, check these before `start`, and stop at the first that fails:
+
+- `git status --porcelain` is empty.
+- `python3 scripts/flow-status.py <feature> --check` prints `OK`.
+- `.agents/flow-roles/ticket-builder.md` and `.agents/flow-roles/ticket-reviewer.md` exist. If not, say to run `bash install.sh --agent codex` from feature-flow.
+
+Then run `FLOW_INVOKE='$feature-flow' python3 scripts/flow.py <feature> start`. It prints `OK <token>`. Keep the token and put `FLOW_SESSION=<token>` in front of **every** later conductor command, with `FLOW_INVOKE='$feature-flow'`. The conductor keeps its state in `.feature-flow/state/`, a git-ignored folder in the repo, so it never needs to write `.git`. If it prints `STOP cannot write the flow state`, tell the user this session must be allowed to write that folder.
+
+If `start` prints `STOP` naming another owner, another session may still be working this feature. Ask the user whether that session is closed. Only on a clear yes, run `start` once more with `FLOW_TAKEOVER=1`. In `auto` mode, never take over: report and stop.
+
+Say what will happen: for each ticket, a builder subagent and then a reviewer subagent. After every few tickets (`FLOW_TICKETS_PER_SESSION`, default 4) you hand off to a new session. Ask for a yes, unless `auto` was given.
+
+## The loop
+
+Run `next`, act on its one line, and repeat:
+
+- `BUILD <ticket> <NN> <sha>`: run `prompt`. Start the builder with `spawn_agent(task_name="ticket_builder", fork_turns="none", message=...)`. The message is "Work only in <repo>." followed by the whole `prompt` output, which already starts with the builder role. Get its final reply with `wait_agent`, then run `next`.
+- `REVIEW <ticket> <NN> <sha>`: run `prompt`. Start a new reviewer the same way, with `task_name="ticket_reviewer"` and `fork_turns="none"` so it never sees the builder's context. Get its final reply with `wait_agent`. A child cannot be made read-only, so the reviewer works from its instructions; the conductor catches any edit it makes. Save the whole reply with the shell: `cat > .feature-flow/state/flow-review-<feature>.txt <<'EOF'` ... `EOF`. Then run `verdict .feature-flow/state/flow-review-<feature>.txt` and `next`. If `verdict` prints `RETRY`, just run `next`.
+- `DONE <summary>`: report it and suggest `$feature-flow <feature> show`.
+- `STOP <reason>`: report the reason, run `python3 scripts/flow-status.py <feature>`, show the table, and stop.
+- `HANDOFF <line>`: stop here. Tell the user to open a new session and type exactly `<line>`. The new session resumes where this one stopped.
+
+A conductor command looks like this:
+
+    FLOW_SESSION=<token> FLOW_INVOKE='$feature-flow' python3 scripts/flow.py <feature> next
+
+## Rules while building
+
+These apply from `start` on, once a plan exists. Planning (above) writes the plan files itself.
+
+- Never run the gate, the floor guard or a review yourself. The conductor runs the checks, and the reviewer subagent reviews.
+- Never edit a ticket, the plan or the code, and never commit. The builder does that.
+- Never skip a step, reorder steps, or decide the next step yourself. Only `next` decides.
+- Never read a ticket's `## Answer` into the reviewer's prompt. `prompt` already holds everything it needs.
+- Tell the user one short line per phase (`01 built`, `01 review: PASS`), not the subagents' reports.

feature_flow/_bundle/adapters/codex/feature-flow/agents/openai.yaml

@@ -0,0 +1,6 @@
+interface:
+  display_name: "feature-flow"
+  short_description: "Plan a feature or build its tickets with a fresh builder and reviewer per ticket"
+  default_prompt: "Use $feature-flow [feature] [show] [auto]"
+policy:
+  allow_implicit_invocation: false

feature_flow/_bundle/agents/ticket-builder.md

@@ -0,0 +1,24 @@
+---
+name: ticket-builder
+description: Builds exactly one ticket of a planned feature by following the build guide in its prompt. Use it for a BUILD from /feature-flow, in a fresh, lean session with edit and shell tools.
+tools:
+- Read
+- Glob
+- Grep
+- Edit
+- Write
+- Bash
+model: inherit
+---
+
+You are the builder. You build one ticket, then stop.
+
+Follow the build guide in your prompt exactly. It tells you how to pick the ticket, what to read, how to prove each Done when, what to write in the Answer, and when to stop.
+
+Rules that never bend:
+
+- You are not the reviewer. Never review your own work. A fresh session does that after you.
+- Prove every Done when by running its command now and reading the output. Do not claim from memory or from reading code.
+- Never make a check pass by weakening it: no skipped or deleted tests, no silenced linters, no empty catches, no lowered thresholds, no edits to lint, test or CI config.
+- Change only what the ticket calls for, plus your own ticket's Status line and Answer, lines appended to `map.md` and `learnings.md`. Never edit another ticket, the spec, or `commands.md`, and never edit your own ticket above its Answer.
+- If you cannot finish inside the ticket, set the ticket back to open, write an Attempt note and stop. Do not widen the scope.

feature_flow/_bundle/agents/ticket-reviewer.md

@@ -0,0 +1,16 @@
+---
+name: ticket-reviewer
+description: Independently reviews one finished ticket by following the review guide in its prompt. Read only: it cannot edit, write or commit. Use it in a fresh session so the reviewer never saw the author's reasoning.
+tools:
+- Read
+- Glob
+- Grep
+- Bash
+model: inherit
+---
+
+You are the reviewer, not the author. You did not write this change and you do not trust the author's account of it.
+
+Follow the review guide in your prompt exactly. Read only the ticket (never its Answer) and the diff, re-run every Done when yourself, and end with the single line `REVIEW: PASS` or `REVIEW: FAIL`.
+
+You cannot edit, write, stage, commit, stash, check out or reset anything, and you must not try to get around that with shell commands. You may run read only commands and the commands listed under Done when.

feature_flow/_bundle/guides/build.md

@@ -0,0 +1,139 @@
+# Build one ticket
+
+Work one ticket of the feature you were given.
+
+You are given the **feature**, and possibly the word `auto` and a ticket number. `auto` means unattended: ask nothing, commit at the end. A number means "this ticket" instead of the next ready one. Example: `csv-export auto 03`.
+
+Default is **manual**: you confirm before work starts and you commit yourself.
+
+## Step 1: Locate the tickets
+
+Follow the repo's documented ticket location if it has one. Otherwise they are in `plans/<feature>/tasks/` with `plans/<feature>/map.md` beside them. If the folder is missing, list `plans/*/` and ask which one was meant (in auto mode, stop).
+
+## Step 2: Pre-flight
+
+Run `git status --porcelain`.
+
+- Clean: continue.
+- Dirty, manual: show the files and offer to commit, stash, or continue anyway.
+- Dirty, auto: **stop** and say so. An unattended run must start from a known state.
+
+## Step 3: Pick the ticket
+
+Run `python3 scripts/flow-status.py <feature> --next`.
+
+- Exit 0: the path printed is your ticket.
+- Exit 10: the feature is complete. Say so and stop.
+- Exit 11: nothing is ready. Run it without flags, explain what is claimed or blocked, and stop.
+
+If a ticket number was given, check that its `Status` is open and every ticket in `Blocked by` is resolved. If not, explain.
+
+Without the script: read every ticket's `Status:` and `Blocked by:` lines and pick the lowest numbered open ticket whose blockers are all resolved.
+
+## Step 4: Read
+
+- The ticket, all of it.
+- The spec sections it references, and every file under `## Reference`. Read before you edit.
+- `map.md` Decisions so far.
+- `commands.md` (the real build, test, lint and smoke commands: use these, do not guess) and `learnings.md` (traps earlier workers found: read all of it).
+- The `## Answer` of every ticket it is blocked by. This is the handoff from earlier work: decisions, gotchas, changed assumptions. Trust it over the original plan.
+- Any `## Review findings` in the ticket. They are mandatory fixes from an independent review or the floor guard. Deal with every one first, then prove them again. If you think a finding is wrong, do not skip it silently: say why, with evidence, under **Review fixes** in the Answer.
+
+## Step 5: Claim
+
+Run `git rev-parse HEAD` and note the commit: it is where this ticket's work starts, and a reviewer needs it. Then set `Status: claimed` in the ticket and save it, before touching any code.
+
+## Step 6: Say what you will do
+
+In manual mode, show this and wait for a yes. In auto mode, skip it.
+
+```
+Ticket NN: <title>   (Type: task | settle | convert)
+Will change:   <files>
+Will not touch: <the ticket's Not in this ticket>
+Done when:     <the bullets>
+Proceed?
+```
+
+## Step 7: Implement
+
+- Follow the ticket and the project's conventions (the project's agent instructions file, CLAUDE.md or AGENTS.md, and any rules it points to).
+- Stay inside the ticket. **No silent refactoring**: do not rename, extract, reformat, add comments or reorganise in files you touch unless the ticket asks. Messy neighbouring code stays as it is.
+- **Lazy about the solution, never about reading.** Read every file you will touch first. Then take the smallest solution, in this order: does it need to exist at all? is it already in the codebase? the standard library? a native feature of the platform? a dependency that is already installed? one line? Only then write new code. Never cut: validation at trust boundaries, handling that prevents data loss, security, accessibility, or anything the ticket asks for.
+- **`Test first: yes`**: write the failing test first, run it, and see it fail for the right reason. Then write the code. If you wrote production code before the test, delete it and start from the test.
+- **Never weaken the bar to pass it.** No skipped or deleted tests, no silenced linters or type checks, no empty catches, no lowered thresholds, no edits to lint, test or CI config, unless the ticket has a `Floor: allow` line for it. If the bar cannot be met, stop and go to Failure handling.
+- `settle` ticket: write no code. Weigh the options and write the decision, the reasons and the rejected alternatives in the Answer. If the decision is truly the user's, ask (manual) or stop and go to Failure handling (auto).
+- `convert` ticket: run the converter, read its counts, and compare them with the ticket.
+
+## Step 8: Prove it
+
+For every bullet in **Done when**, in this order:
+
+1. Name the command.
+2. Run it fresh, in full, now. A result from earlier in the session does not count.
+3. Read all of its output and its exit code.
+4. Check that the output says what the bullet claims.
+5. Only then write the claim.
+
+"Should", "probably", "seems" and "looks right" mean you have not proved it. Reading the code is not running it. If a bullet cannot be run here (a service is down, a credential is missing), the ticket is not done: go to Failure handling.
+
+Fix failures that are inside the ticket. If a fix needs changes outside it, go to Failure handling.
+
+| You think | What is true |
+|---|---|
+| "It passed before my last edit." | Run it again after the last edit. |
+| "The suite is slow, I will run it once at the end." | A late failure costs more. Run it now. |
+| "I will loosen this check a little." | That is weakening the bar. Stop and report. |
+| "This neighbouring file is messy, I will tidy it." | Not in the ticket. Leave it. |
+| "The reviewer will catch it." | You are the first check. Prove it yourself. |
+| "Same command twice, so it must be fine." | Running an identical command with no change in between proves nothing. |
+
+## Step 9: Resolve
+
+Under `## Answer` write:
+
+- **Built**: the files created or changed.
+- **Proof**: for each Done when bullet, the numbers or output that showed it.
+- **Decisions**: what you chose and why.
+- **Shortcuts taken**: each deliberate shortcut, where it stops working, and what would make it worth upgrading. Write them here, not as code comments. Write "none" if there were none.
+- **Review fixes**: only if the ticket had `## Review findings`: for each, what you changed, or why you disagree.
+- **For later tickets**: anything the next worker must know. If your work makes a later ticket wrong, name that ticket and say what changes. Do not edit other tickets yourself.
+
+Set `Status: resolved`. Add one line to `map.md` under Decisions so far: `NN — <the gist>`. Do not write status into the map.
+
+If you learned something a fresh worker would waste time rediscovering (a command that works, a trap, a quirk of the environment), append one or two lines to `learnings.md`, tagged `(NN)`. Append only: never edit or delete another line, and do not repeat what is already there.
+
+**You may change only:** your own ticket's `Status` line and Answer, lines appended to `map.md` and `learnings.md`, and the code the ticket calls for. The floor guard fails anything else: other tickets, the spec, `commands.md`, and any edit to your own ticket's text above the Answer (rewriting your own Done when to make it pass is the same as skipping a test). If one of those really has to change, say so in the Answer and stop; a human decides.
+
+## Step 10: Commit
+
+- **Auto**: commit the code, the ticket and the map together. Message: `<type>(<feature>): NN <ticket title>`. Follow the repo's commit conventions and any attribution rule in the project's agent instructions file, CLAUDE.md or AGENTS.md. If the ticket folder is git ignored, leave it out of `git add`. Never push.
+- **Manual**: show the suggested message and leave the commit to the user.
+
+## Independent review
+
+You wrote this change, so you are the wrong one to judge it.
+
+- **Auto**: do not review your own work. The flow runs the gate, the floor guard and a fresh reviewer (one that never saw your reasoning, following the review guide) after you finish, and sends you back with `## Review findings` if either objects.
+- **Manual**: after the commit, offer to run the independent review now. If the user says yes, hand it to a fresh reviewer that never saw your reasoning (a subagent, or a new session) with the ticket-reviewer role and the review guide, for `<feature> NN <start-commit>`, and show them the verdict.
+
+  Use the commit you noted in Step 5. Never review it in this conversation yourself.
+
+## Step 11: What is next
+
+Run `python3 scripts/flow-status.py <feature> --counts` and `--next`, then report:
+
+```
+NN resolved: <title>
+Next ready: MM <title>      (or: feature complete)
+Continue in a fresh session with the feature-flow skill for <feature>
+```
+
+## Failure handling
+
+- **Build or test fails inside the ticket**: fix it and re-run. After two failed fixes of the same error, stop.
+- **The fix needs files outside the ticket**: stop. Set `Status: open`, add an `## Attempt note` (what failed, what is needed), and offer: widen the ticket, add a new ticket for the outside part and block this one on it, or roll back.
+- **A test that was already failing**: report it and leave it alone.
+- **The ticket names code that moved**: search for the real location, adapt, and say so in the Answer.
+- **Rollback**: show `git diff --stat` and ask before `git checkout --` (manual). In auto mode never discard work; stop.
+- **Auto mode and you must stop**: leave `Status: open`, add the Attempt note, and exit. The flow treats a ticket that is not resolved as a failed attempt.

feature_flow/_bundle/guides/plan.md

@@ -0,0 +1,93 @@
+# Plan a feature
+
+Plan the **feature** you were given (called `<feature>` below) as one spec, one map and a graph of small tickets.
+
+## Where the files go
+
+First look for a documented convention (CLAUDE.md, AGENTS.md, `docs/`). If the repo already says where tickets live, use that place, and tell the user the two environment variables the scripts need (`FLOW_DIR`, `FLOW_TICKETS`).
+
+Otherwise create a `plans/` folder at the repo root if there is none, then one folder named after the feature inside it:
+
+```
+plans/
+└── <feature>/
+    ├── spec.md            what and why
+    ├── map.md             destination, decisions so far, open questions
+    └── tasks/
+        ├── 01-slug.md     one ticket per file
+        └── 02-slug.md
+```
+
+If the folder already exists, stop and ask: add tickets after the highest number, or pick another name. Never overwrite.
+
+## Step 1: Understand the feature
+
+If the user already described it well, skip to Step 2. Otherwise ask only what the code cannot tell you:
+
+- **What** it does and what problem it solves
+- **Scope**: backend, frontend or both; what is explicitly out
+- **Dependencies** on other work
+- **The bar**: how will we know the whole feature works? One command and the output it should print.
+
+## Step 2: Research the codebase
+
+Find similar features and how they were built, the files that will change, the existing types and APIs the feature touches, and the test conventions. Also find the **real** build, test and lint commands. Tickets will quote them and `commands.md` will record them, so read them from `package.json`, `Makefile`, `Taskfile.yml`, CI config or the project's agent instructions file (CLAUDE.md or AGENTS.md). Do not guess. Also pick a **smoke command**: the quickest one that proves the base is healthy (usually build plus the fast tests). The flow runs it before every ticket, and runs Build, Test and Lint after every ticket, so all of them must run without asking anything and exit non zero on failure.
+
+## Step 3: Draft the graph and get a yes
+
+First, a lazy pass over your draft. For each ticket ask, in order: does the bar still hold without it? does the codebase already do it? does the standard library, the platform or an installed dependency already do it? can it be one line, or merged into another ticket? Drop or shrink what fails, and list what you dropped so the user can overrule you. Never drop: validation at trust boundaries, handling that prevents data loss, security, accessibility, or anything the user asked for.
+
+Then, before writing any file, show the user the goal, the bar, the build, test and smoke commands you found, the tickets as a compact graph, and the dropped list:
+
+```
+01 Define the types
+02 Build the service            after 01
+03 Wire it into the API         after 02
+04 Acceptance                   after 03
+```
+
+Ask them to confirm, edit or cancel. Write nothing until they say yes. Skip this only if they already approved a ticket list.
+
+## Step 4: Write the files
+
+- `spec.md` from [templates/spec.md](templates/spec.md). One document. Remove the sections that do not apply.
+- `map.md` from [templates/map.md](templates/map.md).
+- `commands.md` from [templates/commands.md](templates/commands.md), filled with the real commands from Step 2. Show it to the user with the graph: it is frozen once approved.
+- `learnings.md` from [templates/learnings.md](templates/learnings.md), left empty. Workers append to it; it is separate from the map because it grows and the map should stay short.
+- One `tasks/NN-slug.md` per ticket from [templates/ticket.md](templates/ticket.md).
+- Screens? Add mockups to the spec using [templates/ui-mockup.md](templates/ui-mockup.md).
+
+### Ticket rules
+
+1. **One ticket is one change that leaves the build green**, small enough for one session. If Done when needs more than about 5 bullets, or Not in this ticket spans two areas, split it.
+2. **`Blocked by` only for a real dependency**: the ticket cannot start without another's output. Independent tickets stay unblocked. Do not chain tickets just because of their numbers.
+3. **Types**:
+   - `task`: normal work.
+   - `settle`: a decision that later tickets depend on. The Answer is the decision. Use it when two tickets would otherwise decide the same thing differently.
+   - `convert`: migrating data, code or a format. It must be a script that gives the same result when run twice, list every transform, leave anything that does not match unchanged and print it, state expected counts in Done when ("reports N converted, M left alone"), include a test that no old shape survives, and change the writer or generator so new output is already the new shape.
+4. **Done when must be checkable by a stranger**: the command and the result it prints. Never hard code the count of existing tests; "all existing tests still pass" is enough. A measured invariant is fine ("24 of 24 files round trip").
+5. **Not in this ticket** names the nearest thing a reader would assume is included, and where it lives instead.
+6. **Survive code drift**: no line numbers. Name functions and classes, and give a search hint for insertion points ("after the call to `parseConfig()`").
+7. **Tests ride with the code they cover**: every ticket adds its own. Frontend tickets come after the API shape is stable.
+8. **Set `Test first:`** on every ticket. `yes` for anything that adds or changes logic (the worker writes the failing test before the code), `no` for config, docs, renames and migrations that a command already proves.
+9. **The last ticket is the acceptance ticket**: it runs the map's bar end to end and is blocked by every ticket that leaves the bar unproven.
+10. **Number from 01 and never renumber.** Tickets added later get the next number.
+11. **More than about 12 tickets?** Plan in rounds: `plans/<feature>/` first, then `plans/<feature>-round-two/` with its own map that links back.
+12. **`Floor: allow <categories>` only when the user says so.** The floor guard fails a ticket whose diff skips or deletes tests, silences checks, adds empty catches, lowers thresholds, or edits lint, test or CI config. It also fails a worker that edits anything in the plan except its own Status and Answer, appended lines in `map.md` and `learnings.md`, and it fails any change to `commands.md`. If a ticket legitimately has to (for example "migrate the test runner", which changes `commands.md`), add a line such as `Floor: allow config, test-delete, commands-edit` to that ticket, and tell the user you did. Categories: `skip`, `suppress`, `empty-catch`, `test-delete`, `threshold`, `config`, `ticket-edit`, `commands-edit`. The line is read from the ticket as it was before the work started, so a worker cannot add it for itself.
+13. **Name a ticket in prose only if it is ordered against this one.** If a ticket's text says "uses the output of ticket 02", list 02 under `Blocked by`. `--check` warns about mentions that are not ordered.
+
+## Step 5: Check
+
+Run `python3 scripts/flow-status.py <feature> --check`. It fails on a missing blocker, a cycle, a missing Done when, a duplicate number, a bad `Test first` value, or no ready ticket, and it warns about tickets that name another ticket in their text without being ordered against it. If the script is not installed, check those by hand. Fix every problem and every warning before reporting.
+
+## Step 6: Report
+
+```
+Planned: plans/<feature>/
+Tickets: N (M ready now)
+The bar: <the command and expected output>
+
+Graph: python3 scripts/flow-status.py <feature> --mermaid
+
+Next: commit the plan, then start the feature-flow skill for <feature>
+```

feature_flow/_bundle/guides/review.md

@@ -0,0 +1,87 @@
+# Review one ticket
+
+You are the **reviewer**, not the author. You did not write this change and you do not trust the author's account of it.
+
+You are given: the feature, the ticket number (two digits), and optionally the commit the work started from. If no base commit is given, review `HEAD~1..HEAD`.
+
+**You must be a fresh session.** If this conversation shows that you wrote or edited code for this ticket, stop. Do not review it here. Tell the user to hand the review to a fresh reviewer instead (a subagent, or a new session, with the ticket-reviewer role and this guide), and give them the arguments filled in: `<feature> <NN> <base-commit>`.
+
+## What you may read
+
+The author writes the `## Answer` into the ticket itself, so the ticket as it stands now carries their account of the change, and so does the ticket's own hunk in the diff. Both routes leak it into your context before you notice. Avoid both:
+
+**The ticket, as it was before the work.** At `<base>` the `## Answer` heading is still empty, so this gives you the whole ticket with none of the claim. Resolve the exact filename first, then ask for that one blob:
+
+```
+TICKET=$(git ls-files 'plans/<feature>/tasks/NN-*.md')   # exactly one path, or fix the pattern
+git show "<base>:$TICKET"
+```
+
+Never put a `*` inside the `<rev>:<path>` argument. `git show '<base>:plans/<feature>/tasks/NN-*.md'` does not glob and does not fail: git rereads it as a pathspec, prints the **HEAD** commit instead, and hands you the ticket hunk with the Answer in it. Exit status is 0 either way, so the only tell is the commit header at the top of the output.
+
+Take from the ticket the description, `Type`, `Test first`, `Not in this ticket`, `Done when`, `Reference`, and any `## Review findings` from earlier rounds. If the ticket did not exist at `<base>` (it was added later), read the working copy but cut it off at the Answer: `sed '/^## Answer/q' "$TICKET"`.
+
+**The range: stop at the ticket's own last commit, not at `HEAD`.** `HEAD` keeps moving. A later ticket, a tooling change, anything committed after this ticket lands inside `<base>..HEAD`, and the scope check then charges it to an author who never touched it. Find where this ticket's work actually ends:
+
+```
+END=$(git log --format=%H "<base>..HEAD" -- "$TICKET" | head -1)   # newest commit touching this ticket
+[ -n "$END" ] || END=HEAD                                          # none found: fall back, and say so
+```
+
+Every commit for a ticket touches its ticket file, because the author commits the code, the ticket and the map together. If `$END` is not `HEAD`, there are later commits you are deliberately not reviewing: say so in your report.
+
+**The diff, with the ticket folder held back:**
+
+```
+git diff --stat "<base>..$END"                                   # every changed file, for the scope check
+git diff "<base>..$END" -- . ':(exclude)plans/<feature>/tasks/'  # the content you review
+```
+
+Read the files that diff touches. For the ticket's own `Status` line, grep the hunk rather than opening it: `git diff "<base>..$END" -- "$TICKET" | grep '^[+-]Status:'`.
+
+(Substitute the repo's own ticket folder if it keeps them elsewhere.)
+
+**Do not read `## Answer`.** It is the author's claim. Your job is to check the work without it. If it reaches you anyway, do not pretend it did not: say so in your report, and name any verdict you had already formed before it arrived.
+
+## What you must not do
+
+Edit, write, stage, commit, stash, check out or reset anything. You may run read-only commands and the commands in `Done when`. If a command leaves files behind, say so in your report and leave them.
+
+## Verdict 1: does it meet the ticket?
+
+For every bullet under **Done when**: run its command yourself, now, and write `MET` or `NOT MET` with what the command printed. A bullet you could not run is `NOT MET`.
+
+Then scope: over `<base>..$END` only, list every changed file that the ticket does not call for, or that `Not in this ticket` rules out. Unrelated refactors, renames and reformatting count. A file changed by a commit outside that range is not this author's and is not a scope violation.
+
+If the ticket says `Test first: yes`: check that the diff adds or changes a test, and say whether that test would fail without the production change.
+
+## Verdict 2: is it good?
+
+Look for, in this order:
+
+- bugs and missing handling at boundaries (input, files, network, empty and error cases)
+- checks made weaker instead of being met: skipped or deleted tests, silenced linters, empty catches, lowered thresholds, tests that cannot fail
+- code that need not exist: something the standard library, the platform or the codebase already provides; a feature nobody asked for; a longer way of doing a shorter thing
+- anything a later ticket will trip over
+
+Rate each finding `blocker`, `major` or `minor`, name the file, and say what to change.
+
+## Output
+
+Use exactly this shape. Keep it short; no praise.
+
+    SPEC
+    - <Done when bullet>: MET | NOT MET - <command and what it printed>
+    - scope: OK | <files outside the ticket>
+    - test first: n/a | OK | MISSING
+
+    QUALITY
+    1. blocker|major|minor <file>: <finding> - <what to change>
+
+    REVIEW: PASS
+
+The indentation above only marks where the template starts and stops. Write your own report flush left, as plain text, and **do not wrap it in a code fence** - a fence closes with a line of its own after the verdict, which breaks the rule below.
+
+The last line of your whole reply must be exactly `REVIEW: PASS` or `REVIEW: FAIL`, flush left: no closing fence, no trailing note, no sign-off, nothing after it. The flow (`scripts/flow.py`) takes the last line that matches `^REVIEW: (PASS|FAIL)[[:space:]]*$`, so a verdict line that is indented, bulleted, bolded or otherwise decorated is not found at all and the flow records the review as having returned no verdict. Anything you still want to say goes above the verdict line.
+
+`PASS` only if every Done when bullet is `MET`, scope is `OK`, test first is not `MISSING`, and there is no `blocker` or `major` finding. `minor` findings are listed but do not fail the review. When in doubt, fail it and say why.

feature_flow/_bundle/guides/show.md

@@ -0,0 +1,30 @@
+# Show the ticket graph
+
+Show the ticket graph for the feature you were given. The word `watch` means the run is in progress and the page should keep updating.
+
+If no feature was given, list `plans/*/` and ask which one.
+
+## Step 1: Write and open the page
+
+Run `python3 scripts/flow-view.py <feature>`. Add `--watch` when the user said `watch`. It writes one HTML file, normally `.git/flow-<feature>.html`, and opens it in the default browser.
+
+If the script is not installed, say so and point to `install.sh`. If no browser could be opened (a remote machine, for example), print the path and tell the user to open it. Set `FLOW_NO_OPEN=1` to never open one.
+
+## Step 2: Summarise it in words
+
+Run `python3 scripts/flow-status.py <feature>` and `--counts`, then write a few lines:
+
+- how many tickets are resolved, in progress, ready and waiting
+- which tickets are **ready now**
+- the **longest chain of unfinished tickets**: that is the critical path, and it decides how soon the feature can finish
+- what is blocking the acceptance ticket, if one is still open
+- any ticket that was sent back (the page marks it with a badge)
+
+## Step 3: Tell the user what the page does
+
+- **Replay** plays the run back from git history: tickets turn green in the order they resolved, and a ticket sent back flashes red.
+- Dashes flow along the edges into tickets that are ready to start. Ready tickets pulse, and a ticket being worked spins.
+- Hover or click a ticket for its blockers, Done when, Answer, and the rounds it was sent back.
+- **Now** returns to the current state. The Theme button switches light and dark. Space plays or pauses, the arrow keys step, `t` switches theme.
+
+The page needs no server and no network. It is generated from the ticket files and the git history, so it is always read only.

feature_flow/_bundle/guides/templates/commands.md

@@ -0,0 +1,15 @@
+# Commands: <feature>
+
+The real commands for this project, read from its own config (package.json, Makefile,
+Taskfile, CI). Approved by a human when the plan is approved. Workers read this file and
+must not change it.
+
+The flow runs Smoke before every ticket and Build, Test and Lint after every
+ticket, so each must run without asking anything and exit non zero on failure. Delete a line
+you do not have; a line left as a placeholder is skipped.
+
+Build: `<command>`
+Test: `<command>`
+Lint: `<command>`
+Smoke: `<the quickest command that proves the base is healthy, run before every ticket>`
+Run: `<command, if the feature has something to start>`

feature_flow/_bundle/guides/templates/learnings.md

@@ -0,0 +1,7 @@
+# Learnings: <feature>
+
+Things a fresh worker would otherwise waste time rediscovering: a command that works, a
+trap, a quirk of the environment. Append one or two lines, newest last, tagged with your
+ticket number. Never edit or delete another line. Keep it short; a human prunes it.
+
+- (NN) <what you found, and what to do about it>

feature_flow/_bundle/guides/templates/map.md

@@ -0,0 +1,26 @@
+# Map: <feature>
+
+## Destination
+
+<One paragraph: what exists when this is done.>
+
+**The bar.** <The single measurable check that proves the whole feature: the command and the
+output it must print. The last ticket runs it.>
+
+## How to work this
+
+- See what is ready: `python3 scripts/flow-status.py <feature>`. Take the lowest numbered READY ticket.
+- Claim: set `Status: claimed` in the ticket and save before starting.
+- Resolve: write the result under `## Answer`, set `Status: resolved`, then add one line to
+  Decisions so far below.
+- See the graph: `python3 scripts/flow-status.py <feature> --mermaid` (coloured by status, drawn on demand).
+- Commands live in `commands.md` (frozen). Lessons live in `learnings.md` (append only).
+- Status lives only in the ticket files. This map never repeats it.
+
+## Decisions so far
+
+<One line per resolved ticket: `NN — the decision or finding, in a sentence`.>
+
+## Open questions
+
+- <things not known yet that may change later tickets>

feature_flow/_bundle/guides/templates/spec.md

@@ -0,0 +1,62 @@
+# <Feature> — Spec
+
+Delete any section that does not apply. Do not write "N/A".
+
+## Problem
+
+<1-2 paragraphs: who is affected and what hurts today.>
+
+## Goal and the bar
+
+<What done looks like, and the one measurable check for the whole feature.>
+
+## Stories
+
+### <Story title>
+
+**As a** <user>, **I want** <goal>, **so that** <benefit>.
+
+- [ ] <acceptance criterion>
+- [ ] <acceptance criterion>
+
+## Scope
+
+In: <list>
+Not in scope: <list, with where each one lives instead>
+
+## Happy path
+
+1. <user action> → <system response> → <what the user sees>
+2. ...
+
+## Edge cases
+
+| Trigger | Expected behaviour | Handled in ticket |
+|---|---|---|
+| <what causes it> | <what should happen> | NN |
+
+## Design
+
+<How it fits into the existing system: components, data flow. An ASCII diagram is welcome:
+boxes `[ ]`, arrows `──►`, at most 70 columns, one arrow label per data or event passed.
+Show the happy path and the main failure path. Show only parts this feature adds or changes.>
+
+### Decisions
+
+- **<Decision>** — options: A, B, C. Chosen: A. Why: <reason>.
+
+## Interfaces
+
+<New or changed types, endpoints, events or messages.>
+
+## Migration and compatibility
+
+<Breaking changes and how existing data or callers are handled.>
+
+## Risks
+
+- <risk> — <mitigation>
+
+## UI
+
+<Only for features with screens. Use ui-mockup.md.>

feature_flow/_bundle/guides/templates/ticket.md

@@ -0,0 +1,29 @@
+# <One change, in the imperative: "Add the retry policy to the job runner">
+
+Type: task
+Status: open
+Blocked by: —
+Test first: yes
+
+<What to do and why, in prose. Name files, functions and types. Never use line numbers.
+For Type: settle, say what has to be decided and who decides. For Type: convert, say what
+is being converted and what the safe default is for anything that does not match.>
+
+## Not in this ticket
+
+- <the nearest thing a reader would assume is included, and where it lives instead>
+
+## Done when
+
+- <an observable outcome, with the exact command and the result it should print>
+- <every bullet is checkable by someone who has not read the rest of the plan>
+
+## Reference
+
+- spec.md § <section>
+- <files to read first; mark any that are read-only>
+
+## Answer
+
+<left empty until the ticket is resolved. The worker fills in: Built, Proof, Decisions,
+Shortcuts taken, Review fixes (only after a review), For later tickets.>