feature-flow-cli 0.1.0__tar.gz → 0.1.2__tar.gz

{feature_flow_cli-0.1.0 → feature_flow_cli-0.1.2}/MANIFEST.in

@@ -5,3 +5,4 @@ graft guides
 graft adapters/codex
 include scripts/*.py scripts/*.html
 include LICENSE README.md install.py install.sh
+global-exclude .DS_Store

{feature_flow_cli-0.1.0/feature_flow_cli.egg-info → feature_flow_cli-0.1.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: feature-flow-cli
-Version: 0.1.0
+Version: 0.1.2
 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
@@ -45,7 +45,7 @@ python3 install.py /path/to/your/repo --agent all      # both, side by side
 # `bash install.sh ...` still works on Linux and macOS: it only runs install.py
 ```
 
-Without a clone, once the package is on PyPI (it is not published yet), the same installer runs from it:
+Without a clone, the same installer runs from [PyPI](https://pypi.org/project/feature-flow-cli/):
 
 ```bash
 uvx feature-flow-cli install /path/to/your/repo --agent all   # or: pipx run feature-flow-cli install ...
@@ -53,17 +53,22 @@ uvx feature-flow-cli install /path/to/your/repo --agent all   # or: pipx run fea
 
 The package puts a `feature-flow` command on your PATH with `install`, `status <feature>` and `view <feature>`. It installs the same files, byte for byte, as `install.py` from a clone.
 
+The installer lists what it wrote in `.feature-flow/installed.txt`. Commit those files (`git add --pathspec-from-file=.feature-flow/installed.txt`); until you do, the flow does not count them as uncommitted changes.
+
 Then, in your repo, in the agent:
 
 | | Claude Code | Codex |
 |---|---|---|
 | Plan a feature (no plan yet) | `/feature-flow csv-export` | `$feature-flow csv-export` |
+| Plan what you just talked through | `/feature-flow` | `$feature-flow` |
 | Build its tickets (a plan exists) | `/feature-flow csv-export` | `$feature-flow csv-export` |
 | The same, asking nothing | `/feature-flow csv-export auto` | `$feature-flow csv-export auto` |
 | Watch the graph, animated | `/feature-flow csv-export show` | `$feature-flow csv-export show` |
 
 The same command plans when `plans/csv-export/` does not exist yet and builds when it does. Commit the plan before you build it.
 
+**Planning asks you twice.** First the session shows a short feature brief, written from your conversation (what, why, scope, the bar, and anything it had to assume), and waits for yes, edit or cancel. Then a fresh `feature-planner` subagent, given only that brief, reads the code, looks up outside docs where the code cannot answer, and writes a draft plan into the git-ignored `.feature-flow/state/draft/`. A fresh `plan-reviewer` checks the draft against the brief. The session shows you the goal, the commands, the ticket graph, what was dropped and the review result, and waits for a second yes. Only then does `flow.py plan-accept` copy the draft into `plans/<feature>/`.
+
 Try the graph first, with no setup and no agent: `bash examples/demo.sh --open`.
 
 ### What the installer does
@@ -112,7 +117,7 @@ The Claude Code skill is `skills/feature-flow/`. The Codex skill is written by h
 
 | Skill | What it does |
 |---|---|
-| `feature-flow` | **Plan:** writes `plans/<feature>/` with a spec, a map, commands, learnings and tickets, shows you the graph, and waits for a yes. **Build:** runs the tickets one by one, a builder and a reviewer subagent each, with `flow.py` deciding every step. **Show:** the animated ticket graph and a summary of what is ready and what blocks the finish. |
+| `feature-flow` | **Plan:** turns the conversation (or your answers) into a feature brief and waits for a yes, has a planner and a plan reviewer subagent draft and check `plans/<feature>/` (a spec, a map, commands, learnings and tickets), shows you the graph, and writes it after a second yes. **Build:** runs the tickets one by one, a builder and a reviewer subagent each, with `flow.py` deciding every step. **Show:** the animated ticket graph and a summary of what is ready and what blocks the finish. |
 | `architect-review` | Architecture review of a file, diff or feature, with severity rated findings. Reads `CLAUDE.md` or `AGENTS.md` for the project's own rules. |
 | `automation-design` | Blueprint for an automation pipeline. Hands off to `feature-flow` for the plan. |
 
@@ -120,10 +125,12 @@ The Claude Code skill is `skills/feature-flow/`. The Codex skill is written by h
 |---|---|---|
 | `ticket-builder` | Read, Glob, Grep, Edit, Write, Bash | Builds one ticket by the build guide in its prompt. |
 | `ticket-reviewer` | Read, Glob, Grep, Bash (no Edit, no Write) | Reviews one ticket by the review guide in its prompt and ends with `REVIEW: PASS` or `REVIEW: FAIL`. |
+| `feature-planner` | Read, Glob, Grep, Bash, Write, Edit, WebSearch, WebFetch | Plans one feature from the approved brief by the plan guide, writes only the draft, cites outside sources, and ends with `PLAN: READY` or `PLAN: QUESTIONS`. |
+| `plan-reviewer` | Read, Glob, Grep, Bash (no Edit, no Write) | Checks the draft against the brief by the plan review guide and ends with `PLAN-REVIEW: PASS` or `PLAN-REVIEW: FAIL`. |
 
-In Claude Code the reviewer's tool list is enforced, so it cannot edit. A Codex subagent cannot be limited that way, so there the reviewer works from its instructions, and the conductor stops the run if it changed anything.
+In Claude Code the reviewers' tool lists are enforced, so they cannot edit. A Codex subagent cannot be limited that way, so there the reviewers work from their instructions: the conductor stops the run if a ticket reviewer changed anything, and a planner's draft reaches `plans/` only through `plan-accept`. On Codex the planner can research the web only if web search is on; otherwise it plans from the code and says so. The Codex planning path has not been run by hand.
 
-The guides in `guides/` (installed to `.feature-flow/guides/`) hold the protocol: how to build, review, plan and show. The skill holds only what differs per agent.
+The guides in `guides/` (installed to `.feature-flow/guides/`) hold the protocol: how to build, review, write the brief, plan, review a plan and show. The skill holds only what differs per agent.
 
 ## Plans and tickets
 
@@ -282,7 +289,15 @@ The installer never deletes the old skill folders, but it names any it finds. De
 
 ## Releasing to PyPI
 
-The package is `feature-flow-cli` (the shorter `feature-flow` is likely refused by PyPI as too close to the existing `featureflow`). Its version is `__version__` in `feature_flow/__init__.py`. To release: bump it, then `python3 -m build` and `python3 -m twine upload dist/*` with a PyPI API token, or publish from a GitHub Actions workflow set up as a PyPI trusted publisher. Nothing in this repo uploads on its own.
+The package is [`feature-flow-cli`](https://pypi.org/project/feature-flow-cli/) (the shorter `feature-flow` is likely refused by PyPI as too close to the existing `featureflow`). Its version is `__version__` in `feature_flow/__init__.py`.
+
+To release, bump `__version__`, merge it to `main`, then tag that commit and push the tag:
+
+```bash
+git tag v0.1.1 && git push origin v0.1.1
+```
+
+`.github/workflows/release.yml` checks that the tag matches `__version__`, builds the wheel and the sdist, runs `tests/package_smoke.py` on them and publishes them to PyPI. PyPI trusts the workflow as a trusted publisher (owner `hamilton-sky`, repository `feature-flow`, workflow `release.yml`, environment `pypi`), so no token is stored. PyPI never accepts the same version twice.
 
 ## Caution
 

{feature_flow_cli-0.1.0 → feature_flow_cli-0.1.2}/README.md

@@ -26,7 +26,7 @@ python3 install.py /path/to/your/repo --agent all      # both, side by side
 # `bash install.sh ...` still works on Linux and macOS: it only runs install.py
 ```
 
-Without a clone, once the package is on PyPI (it is not published yet), the same installer runs from it:
+Without a clone, the same installer runs from [PyPI](https://pypi.org/project/feature-flow-cli/):
 
 ```bash
 uvx feature-flow-cli install /path/to/your/repo --agent all   # or: pipx run feature-flow-cli install ...
@@ -34,17 +34,22 @@ uvx feature-flow-cli install /path/to/your/repo --agent all   # or: pipx run fea
 
 The package puts a `feature-flow` command on your PATH with `install`, `status <feature>` and `view <feature>`. It installs the same files, byte for byte, as `install.py` from a clone.
 
+The installer lists what it wrote in `.feature-flow/installed.txt`. Commit those files (`git add --pathspec-from-file=.feature-flow/installed.txt`); until you do, the flow does not count them as uncommitted changes.
+
 Then, in your repo, in the agent:
 
 | | Claude Code | Codex |
 |---|---|---|
 | Plan a feature (no plan yet) | `/feature-flow csv-export` | `$feature-flow csv-export` |
+| Plan what you just talked through | `/feature-flow` | `$feature-flow` |
 | Build its tickets (a plan exists) | `/feature-flow csv-export` | `$feature-flow csv-export` |
 | The same, asking nothing | `/feature-flow csv-export auto` | `$feature-flow csv-export auto` |
 | Watch the graph, animated | `/feature-flow csv-export show` | `$feature-flow csv-export show` |
 
 The same command plans when `plans/csv-export/` does not exist yet and builds when it does. Commit the plan before you build it.
 
+**Planning asks you twice.** First the session shows a short feature brief, written from your conversation (what, why, scope, the bar, and anything it had to assume), and waits for yes, edit or cancel. Then a fresh `feature-planner` subagent, given only that brief, reads the code, looks up outside docs where the code cannot answer, and writes a draft plan into the git-ignored `.feature-flow/state/draft/`. A fresh `plan-reviewer` checks the draft against the brief. The session shows you the goal, the commands, the ticket graph, what was dropped and the review result, and waits for a second yes. Only then does `flow.py plan-accept` copy the draft into `plans/<feature>/`.
+
 Try the graph first, with no setup and no agent: `bash examples/demo.sh --open`.
 
 ### What the installer does
@@ -93,7 +98,7 @@ The Claude Code skill is `skills/feature-flow/`. The Codex skill is written by h
 
 | Skill | What it does |
 |---|---|
-| `feature-flow` | **Plan:** writes `plans/<feature>/` with a spec, a map, commands, learnings and tickets, shows you the graph, and waits for a yes. **Build:** runs the tickets one by one, a builder and a reviewer subagent each, with `flow.py` deciding every step. **Show:** the animated ticket graph and a summary of what is ready and what blocks the finish. |
+| `feature-flow` | **Plan:** turns the conversation (or your answers) into a feature brief and waits for a yes, has a planner and a plan reviewer subagent draft and check `plans/<feature>/` (a spec, a map, commands, learnings and tickets), shows you the graph, and writes it after a second yes. **Build:** runs the tickets one by one, a builder and a reviewer subagent each, with `flow.py` deciding every step. **Show:** the animated ticket graph and a summary of what is ready and what blocks the finish. |
 | `architect-review` | Architecture review of a file, diff or feature, with severity rated findings. Reads `CLAUDE.md` or `AGENTS.md` for the project's own rules. |
 | `automation-design` | Blueprint for an automation pipeline. Hands off to `feature-flow` for the plan. |
 
@@ -101,10 +106,12 @@ The Claude Code skill is `skills/feature-flow/`. The Codex skill is written by h
 |---|---|---|
 | `ticket-builder` | Read, Glob, Grep, Edit, Write, Bash | Builds one ticket by the build guide in its prompt. |
 | `ticket-reviewer` | Read, Glob, Grep, Bash (no Edit, no Write) | Reviews one ticket by the review guide in its prompt and ends with `REVIEW: PASS` or `REVIEW: FAIL`. |
+| `feature-planner` | Read, Glob, Grep, Bash, Write, Edit, WebSearch, WebFetch | Plans one feature from the approved brief by the plan guide, writes only the draft, cites outside sources, and ends with `PLAN: READY` or `PLAN: QUESTIONS`. |
+| `plan-reviewer` | Read, Glob, Grep, Bash (no Edit, no Write) | Checks the draft against the brief by the plan review guide and ends with `PLAN-REVIEW: PASS` or `PLAN-REVIEW: FAIL`. |
 
-In Claude Code the reviewer's tool list is enforced, so it cannot edit. A Codex subagent cannot be limited that way, so there the reviewer works from its instructions, and the conductor stops the run if it changed anything.
+In Claude Code the reviewers' tool lists are enforced, so they cannot edit. A Codex subagent cannot be limited that way, so there the reviewers work from their instructions: the conductor stops the run if a ticket reviewer changed anything, and a planner's draft reaches `plans/` only through `plan-accept`. On Codex the planner can research the web only if web search is on; otherwise it plans from the code and says so. The Codex planning path has not been run by hand.
 
-The guides in `guides/` (installed to `.feature-flow/guides/`) hold the protocol: how to build, review, plan and show. The skill holds only what differs per agent.
+The guides in `guides/` (installed to `.feature-flow/guides/`) hold the protocol: how to build, review, write the brief, plan, review a plan and show. The skill holds only what differs per agent.
 
 ## Plans and tickets
 
@@ -263,7 +270,15 @@ The installer never deletes the old skill folders, but it names any it finds. De
 
 ## Releasing to PyPI
 
-The package is `feature-flow-cli` (the shorter `feature-flow` is likely refused by PyPI as too close to the existing `featureflow`). Its version is `__version__` in `feature_flow/__init__.py`. To release: bump it, then `python3 -m build` and `python3 -m twine upload dist/*` with a PyPI API token, or publish from a GitHub Actions workflow set up as a PyPI trusted publisher. Nothing in this repo uploads on its own.
+The package is [`feature-flow-cli`](https://pypi.org/project/feature-flow-cli/) (the shorter `feature-flow` is likely refused by PyPI as too close to the existing `featureflow`). Its version is `__version__` in `feature_flow/__init__.py`.
+
+To release, bump `__version__`, merge it to `main`, then tag that commit and push the tag:
+
+```bash
+git tag v0.1.1 && git push origin v0.1.1
+```
+
+`.github/workflows/release.yml` checks that the tag matches `__version__`, builds the wheel and the sdist, runs `tests/package_smoke.py` on them and publishes them to PyPI. PyPI trusts the workflow as a trusted publisher (owner `hamilton-sky`, repository `feature-flow`, workflow `release.yml`, environment `pypi`), so no token is stored. PyPI never accepts the same version twice.
 
 ## Caution
 

{feature_flow_cli-0.1.0 → feature_flow_cli-0.1.2}/adapters/codex/feature-flow/SKILL.md

@@ -1,13 +1,13 @@
 ---
 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."
+description: "Use to plan a feature (from the conversation so far, with a fresh planner and plan reviewer subagent) 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 first word is the **feature**. `show` means draw the graph. `auto` means ask nothing and go. If no feature was given and the conversation so far describes work to build, plan it (below) and propose the feature's name in the brief. If no feature was given otherwise, 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.
 
@@ -17,19 +17,23 @@ 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:
+When `plans/<feature>/` does not exist, or you are planning from the conversation, follow `.feature-flow/guides/brief.md` with the user. You write the brief and ask for both yeses (unless `auto`); a child agent plans, another reviews, and you never draft the plan yourself. Once the brief names the feature, run `FLOW_INVOKE='$feature-flow' python3 scripts/flow.py <feature> start` and check that it prints `PLAN`, and check that `.agents/flow-roles/feature-planner.md` and `.agents/flow-roles/plan-reviewer.md` exist (see below).
 
-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.
+- `plan-prompt <brief>`: start the planner with `spawn_agent(task_name="feature_planner", fork_turns="none", message=...)`. The message is "Work only in <repo>." followed by the whole output. Get its final reply with `wait_agent`. A child cannot be limited to the draft folder, so it works from its instructions, and `plan-accept` is the only way its draft reaches `plans/`. If web search is off in this Codex, the planner plans from the codebase and says so.
+- `plan-review-prompt`: start a new reviewer the same way, with `task_name="plan_reviewer"` and `fork_turns="none"`, never with the planner's reply. Get its final reply with `wait_agent` and save it with the shell into `.feature-flow/state/plan-review-<feature>.txt`.
+- `plan-accept`: writes `plans/<feature>/` from the draft, only after the second yes.
+
+Then run `python3 scripts/flow-status.py <feature> --check`, list the files `plan-accept` wrote, 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.
+
+To add tickets to a plan that exists, edit it by hand following the ticket rules in `.feature-flow/guides/plan.md`.
 
 ## Before building
 
 With a plan present, check these before `start`, and stop at the first that fails:
 
-- `git status --porcelain` is empty.
+- `git status --porcelain` is empty, apart from untracked files listed in `.feature-flow/installed.txt`: those are feature-flow's own install, so never stop for them. Suggest committing them (`git add --pathspec-from-file=.feature-flow/installed.txt && git commit -m "chore: install feature-flow"`) and carry on.
 - `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.
+- `.agents/flow-roles/ticket-builder.md` and `.agents/flow-roles/ticket-reviewer.md` exist. If not, say to run `uvx feature-flow-cli install . --agent codex` in this repo (or `python3 install.py <repo> --agent codex` from a feature-flow clone).
 
 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.
 
@@ -53,7 +57,7 @@ A conductor command looks like this:
 
 ## Rules while building
 
-These apply from `start` on, once a plan exists. Planning (above) writes the plan files itself.
+These apply from `start` on, once a plan exists.
 
 - 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.

feature_flow_cli-0.1.2/agents/feature-planner.md

@@ -0,0 +1,33 @@
+---
+name: feature-planner
+description: Plans one feature from an approved feature brief by following the plan guide in its prompt. Writes a draft plan into the flow's state folder and nothing else. Use it from /feature-flow, in a fresh session that never saw the conversation.
+tools:
+- Read
+- Glob
+- Grep
+- Bash
+- Write
+- Edit
+- WebSearch
+- WebFetch
+model: inherit
+---
+
+You are the planner. You turn one feature brief into a draft plan, then stop.
+
+Follow the plan guide in your prompt exactly. It tells you what to read, how to research, how to cut the graph into tickets, where to write, and how to reply.
+
+How you think, in this order:
+
+- The brief is the whole ask. You never saw the conversation behind it. Plan what the brief says; a gap goes under Open questions or into a `settle` ticket, never into a silent guess.
+- Read before you plan: the project's conventions, similar features, the files that will change, and the real build, test and lint commands from the project's own config. Never guess a command.
+- Look outside the repo only where the code cannot answer: a library's documentation for the version the lockfile pins, an outside API the brief names. Every outside fact gets its source in `map.md`. If you cannot reach the web, say so in your reply and plan from the codebase.
+- At every real fork, write two options in a sentence each, pick one and say why. If the choice belongs to the user, make it a `settle` ticket instead of picking.
+- Be lazy: drop every ticket the bar does not need, and list what you dropped.
+- Prove the draft is well formed with the check the guide names, and fix every problem.
+
+Rules that never bend:
+
+- Write and edit only inside the draft folder your prompt names. Never change a file outside it, never write under `plans/`, never commit.
+- You cannot talk to the user. Anything only the user can decide comes back in your reply as an open question.
+- End your reply with exactly `PLAN: READY` or `PLAN: QUESTIONS`.

feature_flow_cli-0.1.2/agents/plan-reviewer.md

@@ -0,0 +1,16 @@
+---
+name: plan-reviewer
+description: Independently checks a draft plan against the approved feature brief by following the plan review guide in its prompt. Read only. Use it in a fresh session so it never saw the planner's reasoning.
+tools:
+- Read
+- Glob
+- Grep
+- Bash
+model: inherit
+---
+
+You are the plan reviewer, not the planner. You did not write this plan and you do not trust the planner's account of it.
+
+Follow the plan review guide in your prompt exactly. Read the brief and the draft, run the commands the draft relies on, and end with the single line `PLAN-REVIEW: PASS` or `PLAN-REVIEW: FAIL`.
+
+You cannot edit, write, stage or commit anything, and you must not try to get around that with shell commands. You may run read only commands, the plan check, and the commands the draft's `commands.md` lists.

{feature_flow_cli-0.1.0 → feature_flow_cli-0.1.2}/feature_flow/__init__.py

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

{feature_flow_cli-0.1.0 → feature_flow_cli-0.1.2}/feature_flow/checks.py

@@ -4,6 +4,7 @@ Each call lives in one function so plans/interactive-flow-python can swap it for
 in-process call without touching the conductor.
 """
 
+import os
 import subprocess
 from pathlib import Path
 
@@ -41,10 +42,21 @@ def _bash(script, *args):
     return Result(result.returncode, result.stdout)
 
 
-def flow_status(scripts, feature, mode):
-    """The ticket graph reader with --next, --counts or --check, in process. stderr is folded into the output."""
+def flow_status(scripts, feature, mode, root=None):
+    """The ticket graph reader with --next, --counts or --check, in process. stderr is folded into the output.
+    root, when given, stands in for FLOW_DIR for this one call (the planner's draft folder)."""
     out = _Collect()
-    code = status.run([feature, mode], out, out)
+    saved = os.environ.get("FLOW_DIR")
+    if root is not None:
+        os.environ["FLOW_DIR"] = str(root)
+    try:
+        code = status.run([feature, mode], out, out)
+    finally:
+        if root is not None:
+            if saved is None:
+                del os.environ["FLOW_DIR"]
+            else:
+                os.environ["FLOW_DIR"] = saved
     return Result(code, out.text())
 
 

{feature_flow_cli-0.1.0 → feature_flow_cli-0.1.2}/feature_flow/cli.py

@@ -5,8 +5,10 @@ from pathlib import Path
 
 from feature_flow.conductor import Conductor, NoPhase, Stop
 
-USAGE = "usage: python3 scripts/flow.py <feature> start | next | prompt | verdict <file>"
-COMMANDS = ("start", "next", "prompt", "verdict")
+USAGE = ("usage: python3 scripts/flow.py <feature> start | next | prompt | verdict <file>\n"
+         "       python3 scripts/flow.py <feature> plan-prompt <brief> [findings] | plan-review-prompt | plan-accept")
+COMMANDS = ("start", "next", "prompt", "verdict", "plan-prompt", "plan-review-prompt", "plan-accept")
+ARGS = {"verdict": (3,), "plan-prompt": (3, 4)}
 
 
 def main(argv=None, scripts=None):
@@ -15,7 +17,10 @@ def main(argv=None, scripts=None):
         print(USAGE, file=sys.stderr)
         return 2
     feature, command = args[0], args[1]
-    if (command == "verdict") != (len(args) == 3) or len(args) > 3:
+    if feature in (".", "..") or any(c in feature for c in "/\\:"):
+        print("the feature must be a plain folder name, not %s" % feature, file=sys.stderr)
+        return 2
+    if len(args) not in ARGS.get(command, (2,)):
         print(USAGE, file=sys.stderr)
         return 2
     scripts = Path(scripts) if scripts else Path.cwd() / "scripts"
@@ -24,6 +29,12 @@ def main(argv=None, scripts=None):
         conductor = Conductor(feature, scripts)
         if command == "verdict":
             line = conductor.verdict(args[2])
+        elif command == "plan-prompt":
+            line = conductor.plan_prompt(args[2], args[3] if len(args) == 4 else None)
+        elif command == "plan-review-prompt":
+            line = conductor.plan_review_prompt()
+        elif command == "plan-accept":
+            line = conductor.plan_accept()
         elif command == "prompt":
             line = conductor.prompt()
         elif command == "start":
@@ -39,7 +50,11 @@ def main(argv=None, scripts=None):
             conductor.log("STOP")
         print(line)
         return 1
-    print(line, end="" if line.endswith("\n") else "\n")
+    out = sys.stdout
+    if command in ("plan-prompt", "plan-review-prompt") and hasattr(out, "reconfigure"):
+        # the plan guides hold non-ASCII text, which a Windows console code page cannot print
+        out.reconfigure(encoding="utf-8")
+    print(line, end="" if line.endswith("\n") else "\n", file=out)
     return 0
 
 

{feature_flow_cli-0.1.0 → feature_flow_cli-0.1.2}/feature_flow/conductor.py

@@ -7,6 +7,7 @@ caller, and prints exactly one line per command.
 import os
 import re
 import secrets
+import shutil
 from pathlib import Path
 
 from feature_flow import checks, git, prompts, state, tickets
@@ -53,6 +54,9 @@ class Conductor:
         except OSError as err:
             raise Stop("cannot write the flow state in %s: %s. this session must be allowed to write there"
                        % (top / state.STATE_DIR, err.strerror or err))
+        self.draft_root = state.STATE_DIR / "draft"
+        self.draft = self.draft_root / feature
+        self.brief_file = state.STATE_DIR / ("brief-%s.md" % feature)
         self.state_file = state.state_path(folder, feature)
         self.log_file = state.log_path(folder, feature)
         self.findings_file = state.file_path(folder, feature, "findings")
@@ -157,8 +161,10 @@ class Conductor:
         check = checks.flow_status(self.scripts, self.feature, "--check")
         if not check.ok:
             raise Stop("ticket check failed, fix the tickets first")
-        if not git.is_clean():
-            raise Stop("working tree is not clean, commit or stash first")
+        dirty = git.changes()
+        if dirty:
+            raise Stop("working tree is not clean, commit or stash first: %s%s"
+                       % (" ".join(dirty[:5]), " and %d more" % (len(dirty) - 5) if len(dirty) > 5 else ""))
         nxt = checks.flow_status(self.scripts, self.feature, "--next")
         if nxt.code == 10:
             done = self.num("done")
@@ -297,3 +303,70 @@ class Conductor:
         self.save()
         self.log("VERDICT-%s" % (found or "none").upper())
         return "OK" if found else "RETRY no review verdict"
+
+    # ---- planning: stateless, the brief and the draft are all there is --
+
+    def no_plan_yet(self):
+        if self.plan.is_dir():
+            raise Stop("%s already exists. pick another name: a plan is never overwritten" % self.plan.as_posix())
+
+    def draft_text(self):
+        return self.draft.as_posix() + "/"
+
+    def read_text(self, path, what):
+        try:
+            return Path(path).read_text(encoding="utf-8", errors="replace")
+        except OSError as err:
+            raise Stop("cannot read the %s %s: %s" % (what, path, err.strerror))
+
+    def plan_prompt(self, brief, findings=None):
+        """The feature-planner's prompt. Saves the brief; a first round (no findings) starts an empty draft."""
+        self.no_plan_yet()
+        text = self.read_text(brief, "brief")
+        notes = self.read_text(findings, "review findings") if findings else ""
+        if not text.strip():
+            raise Stop("the brief %s is empty" % brief)
+        if Path(brief).resolve() != self.brief_file.resolve():
+            self.brief_file.write_text(text, encoding="utf-8")
+        if not findings and self.draft.is_dir():
+            if self.draft.resolve().parent != self.draft_root.resolve():
+                raise Stop("the draft folder %s is outside %s" % (self.draft_text(), self.draft_root.as_posix()))
+            shutil.rmtree(str(self.draft))
+        (self.draft / (os.environ.get("FLOW_TICKETS") or "tasks")).mkdir(parents=True, exist_ok=True)
+        self.log("PLAN-PROMPT")
+        try:
+            return prompts.plan("plan", self.scripts, self.feature, self.draft_text(), text, notes)
+        except FileNotFoundError as err:
+            raise Stop(str(err))
+
+    def plan_review_prompt(self):
+        """The plan-reviewer's prompt: the saved brief and the draft, nothing from the planner."""
+        self.no_plan_yet()
+        if not self.brief_file.is_file():
+            raise Stop("no brief for %s. run plan-prompt first" % self.feature)
+        if not self.draft.is_dir():
+            raise Stop("no draft plan in %s. run the planner first" % self.draft_text())
+        self.log("PLAN-REVIEW-PROMPT")
+        try:
+            return prompts.plan("plan-review", self.scripts, self.feature, self.draft_text(),
+                                self.read_text(self.brief_file, "brief"))
+        except FileNotFoundError as err:
+            raise Stop(str(err))
+
+    def plan_accept(self):
+        """Copy a draft that passes the check into the plan folder. Never overwrites, never commits."""
+        self.no_plan_yet()
+        if not self.draft.is_dir():
+            raise Stop("no draft plan in %s. run the planner first" % self.draft_text())
+        check = checks.flow_status(self.scripts, self.feature, "--check", root=self.draft_root)
+        if not check.ok:
+            raise Stop("the draft fails the plan check, fix it first: %s"
+                       % " ".join(check.out.split())[:400])
+        self.plan.parent.mkdir(parents=True, exist_ok=True)
+        shutil.copytree(str(self.draft), str(self.plan))
+        check = checks.flow_status(self.scripts, self.feature, "--check")
+        if not check.ok:
+            raise Stop("the accepted plan in %s fails the plan check: %s"
+                       % (self.plan.as_posix(), " ".join(check.out.split())[:400]))
+        self.log("PLAN-ACCEPT")
+        return "OK %s" % self.plan.as_posix()

{feature_flow_cli-0.1.0 → feature_flow_cli-0.1.2}/feature_flow/git.py

@@ -30,9 +30,35 @@ def head():
     return _git("rev-parse", "HEAD").stdout.strip()
 
 
+def changes():
+    """Every changed path, untracked files included, as `git status --porcelain` sees them, except
+    the untracked files feature-flow's installer wrote: an install not committed yet is not a change."""
+    installed = set()
+    top = toplevel()
+    if top is not None:
+        try:
+            installed = set((top / ".feature-flow" / "installed.txt").read_text(encoding="utf-8").splitlines())
+        except (OSError, UnicodeDecodeError):
+            pass
+    entries = _git("status", "--porcelain", "-z", "-uall").stdout.split("\0")
+    found = []
+    i = 0
+    while i < len(entries):
+        entry = entries[i]
+        i += 1
+        if len(entry) < 4:
+            continue
+        code, path = entry[:2], entry[3:]
+        if code[0] in "RC":
+            i += 1  # the rename's source path follows
+        if code == "??" and path in installed:
+            continue
+        found.append(path)
+    return found
+
+
 def is_clean():
-    """No change at all, untracked files included, as `git status --porcelain` sees it."""
-    return _git("status", "--porcelain").stdout.strip() == ""
+    return not changes()
 
 
 def tracked_clean():

{feature_flow_cli-0.1.0 → feature_flow_cli-0.1.2}/feature_flow/install.py

@@ -39,6 +39,9 @@ BUNDLE = "_bundle"
 
 # the skills this installs
 SKILLS = ("feature-flow", "architect-review", "automation-design")
+# the in-repo files an install wrote, one path per line, relative to the target. The conductor does not
+# count them as a dirty tree while they are untracked, and `git add --pathspec-from-file` commits them.
+INSTALLED = ".feature-flow/installed.txt"
 
 # an old skill that runs the ticket script (the bash one or the Python one) or ends a review with a verdict
 LEFTOVER = re.compile(rb"scripts/flow-status\.(?:sh|py)|REVIEW: PASS")
@@ -169,6 +172,7 @@ class Installer:
             package = os.path.dirname(os.path.abspath(__file__))
         self.package = package
         self.added = self.updated = self.same = self.kept = 0
+        self.written = []
 
     def place(self, file, dest, data=None):
         """One file: add it, replace it (--force), leave it alone (same) or keep the user's version.
@@ -177,14 +181,17 @@ class Installer:
         if not os.path.exists(dest):
             self.out("  add     " + dest)
             self.added += 1
+            self.written.append(dest)
             if not self.dry:
                 os.makedirs(os.path.dirname(dest), exist_ok=True)
                 self._copy(file, dest, data)
         elif new is not None and _read(dest) == new:
             self.same += 1
+            self.written.append(dest)
         elif self.force:
             self.out("  update  " + dest)
             self.updated += 1
+            self.written.append(dest)
             if not self.dry:
                 self._copy(file, dest, data)
         else:
@@ -235,6 +242,23 @@ class Installer:
             self.place(file, self.target + "/.agents/flow-roles/" + name,
                        role_body(data if data is not None else b""))
 
+    def write_installed(self):
+        """Add this run's in-repo files to the list, keeping the earlier runs' files that still exist."""
+        path = self.target + "/" + INSTALLED
+        names = set()
+        try:
+            with open(path, encoding="utf-8") as old:
+                names.update(line.strip() for line in old)
+        except OSError:
+            pass
+        names = set(n for n in names if n and os.path.isfile(self.target + "/" + n))
+        prefix = self.target + "/"
+        names.update(dest[len(prefix):] for dest in self.written if dest.startswith(prefix))
+        names.add(INSTALLED)
+        os.makedirs(os.path.dirname(path), exist_ok=True)
+        with open(path, "w", encoding="utf-8", newline="\n") as new:
+            new.write("".join(n + "\n" for n in sorted(names)))
+
     def report_leftovers(self, dirs):
         """A skill folder this installer does not own but that drives the flow (it runs the ticket
         scripts or ends a review with a verdict) is left from an earlier version: named once, never deleted."""
@@ -270,6 +294,8 @@ class Installer:
         self.copy_tree(here + "/guides", self.target + "/.feature-flow/guides")
         self.copy_tree(here + "/agents", self.target + "/.feature-flow/agents")
         self.copy_tree(self.package, self.target + "/.feature-flow/feature_flow", skip=BUNDLE)
+        if not self.dry:
+            self.write_installed()
 
         self.out("")
         verb = "would add" if self.dry else "added"
@@ -285,6 +311,12 @@ class Installer:
                 git = 127
             if git != 0:
                 self.out("note: %s is not a git repository, and the flow needs one" % self.target)
+            elif self.added or self.updated:
+                git_c = ""
+                if os.path.realpath(self.target) != os.path.realpath(os.getcwd()):
+                    git_c = '-C "%s" ' % self.target if " " in self.target else "-C %s " % self.target
+                self.out('next: commit the installed files: git %sadd --pathspec-from-file=%s'
+                         ' && git %scommit -m "chore: install feature-flow"' % (git_c, INSTALLED, git_c))
             if not shutil.which("python3"):
                 self.out("note: install python3 (3.9 or later): scripts/flow.py needs it")
             if agent in ("claude", "all"):

{feature_flow_cli-0.1.0 → feature_flow_cli-0.1.2}/feature_flow/prompts.py

@@ -5,8 +5,9 @@ The text is runtime neutral: any agent that can read a prompt can follow it.
 
 from pathlib import Path
 
-ROLES = {"build": "ticket-builder.md", "review": "ticket-reviewer.md"}
-GUIDES = {"build": "build.md", "review": "review.md"}
+ROLES = {"build": "ticket-builder.md", "review": "ticket-reviewer.md",
+         "plan": "feature-planner.md", "plan-review": "plan-reviewer.md"}
+GUIDES = {"build": "build.md", "review": "review.md", "plan": "plan.md", "plan-review": "plan-review.md"}
 
 
 def find_file(scripts, folder, name):
@@ -50,3 +51,28 @@ def build(phase, scripts, feature, ticket, num, sha):
                 "with exactly `REVIEW: PASS` or `REVIEW: FAIL`." % (num, feature, feature, num, sha, ticket, sha, fresh))
         intro = "The review guide follows. Follow it exactly."
     return "\n\n".join([role, "---", intro, guide, "---", task]) + "\n"
+
+
+def plan(phase, scripts, feature, draft, brief, findings=""):
+    """The prompt for the feature-planner (phase "plan") or the plan-reviewer ("plan-review").
+
+    Both get the approved brief and the draft folder, never the conversation or each other's reasoning.
+    """
+    role = _body(find_file(scripts, "agents", ROLES[phase]))
+    guide = _body(find_file(scripts, "guides", GUIDES[phase]))
+    guide = guide.replace("<feature>", feature).replace("<draft>", draft)
+    if phase == "plan":
+        task = ("Your task: plan the feature `%s` from the approved brief below. Write the draft only inside "
+                "`%s`, laid out as the plan guide says. Do not write anywhere else and do not commit. Your final "
+                "reply must end with exactly `PLAN: READY` or `PLAN: QUESTIONS`." % (feature, draft))
+        intro = "The plan guide follows. Follow it exactly."
+    else:
+        task = ("Your task: review the draft plan for the feature `%s` in `%s` against the approved brief below. "
+                "Do not edit any file or create a commit. Your final reply must end with exactly "
+                "`PLAN-REVIEW: PASS` or `PLAN-REVIEW: FAIL`." % (feature, draft))
+        intro = "The plan review guide follows. Follow it exactly."
+    parts = [role, "---", intro, guide, "---", task, "## The brief", brief.strip("\n")]
+    if findings.strip():
+        parts += ["## Review findings from the last round", "The draft is already in `%s`. Fix each finding in it, "
+                  "or say in your reply why it stays." % draft, findings.strip("\n")]
+    return "\n\n".join(parts) + "\n"