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

{feature_flow_cli-0.1.0 → feature_flow_cli-0.1.1}/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.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: feature-flow-cli
-Version: 0.1.0
+Version: 0.1.1
 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 ...
@@ -58,12 +58,15 @@ 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 +115,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 +123,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 +287,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.1}/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 ...
@@ -39,12 +39,15 @@ 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 +96,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 +104,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 +268,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.1}/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,11 +17,15 @@ 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
 
@@ -29,7 +33,7 @@ With a plan present, check these before `start`, and stop at the first that fail
 
 - `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.
+- `.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.1/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.1/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.1}/feature_flow/__init__.py

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

{feature_flow_cli-0.1.0 → feature_flow_cli-0.1.1}/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.1}/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.1}/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")
@@ -297,3 +301,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.1}/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"

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: feature-flow-cli
-Version: 0.1.0
+Version: 0.1.1
 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 ...
@@ -58,12 +58,15 @@ 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 +115,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 +123,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 +287,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.1}/feature_flow_cli.egg-info/SOURCES.txt

@@ -6,6 +6,8 @@ install.sh
 pyproject.toml
 adapters/codex/feature-flow/SKILL.md
 adapters/codex/feature-flow/agents/openai.yaml
+agents/feature-planner.md
+agents/plan-reviewer.md
 agents/ticket-builder.md
 agents/ticket-reviewer.md
 feature_flow/__init__.py
@@ -28,7 +30,9 @@ feature_flow_cli.egg-info/SOURCES.txt
 feature_flow_cli.egg-info/dependency_links.txt
 feature_flow_cli.egg-info/entry_points.txt
 feature_flow_cli.egg-info/top_level.txt
+guides/brief.md
 guides/build.md
+guides/plan-review.md
 guides/plan.md
 guides/review.md
 guides/show.md
@@ -44,7 +48,6 @@ scripts/flow-view.html
 scripts/flow-view.py
 scripts/flow.py
 scripts/gate.py
-skills/.DS_Store
 skills/architect-review/SKILL.md
 skills/automation-design/SKILL.md
 skills/feature-flow/SKILL.md

feature_flow_cli-0.1.1/guides/brief.md

@@ -0,0 +1,62 @@
+# Plan a feature with the user
+
+You are the user's session. You turn what the user wants into an approved **feature brief**, have a fresh planner draft the plan and a fresh plan reviewer check it, and write the plan into the repo only after the user says yes twice. You never draft the plan yourself, and only you talk to the user.
+
+The conductor commands below are `python3 scripts/flow.py <feature> <command>`. The state folder is `.feature-flow/state/`, which git ignores.
+
+## Step 1: Write the brief
+
+If the conversation before this already describes the work, write the brief from it. If it does not, ask only what the code cannot tell you (what it does and why, what is in and out of scope, dependencies on other work, and the bar), then write the brief from the answers.
+
+```
+Feature: <folder name, lowercase-with-dashes>
+What: <one or two sentences>
+Why: <the problem, in the user's words where you can>
+In scope: <what this covers>
+Out: <what it does not cover, and anything the conversation set aside>
+The bar: <one command and what it should print, or the observable outcome that proves the whole feature>
+Unsure: <each thing you assumed, marked as an assumption>
+```
+
+Every line comes from the conversation or is marked as an assumption under Unsure. Never fill a gap with a guess. If there is no bar, ask for one: the brief is not ready without it. If `plans/<feature>/` already exists, say so and ask for another name; adding tickets to an existing plan is a hand edit that follows the ticket rules in the plan guide, not this flow.
+
+## Step 2: Approval 1
+
+Show the brief and ask: plan this? yes, edit, or cancel. On an edit, change the brief and show it again. On cancel, stop. Skip the question only in auto mode.
+
+On yes, save the brief with the shell, not a file tool:
+
+```
+cat > .feature-flow/state/brief-<feature>.md <<'BRIEF'
+<the brief>
+BRIEF
+```
+
+## Step 3: The planner
+
+Run `plan-prompt .feature-flow/state/brief-<feature>.md`. Start a fresh `feature-planner` subagent with the whole output as its prompt, and wait for its final reply. It writes the draft into `.feature-flow/state/draft/<feature>/` and ends with `PLAN: READY` or `PLAN: QUESTIONS`.
+
+On `PLAN: QUESTIONS`, ask the user the questions, add the answers to the brief under a `Decided:` line, save it again, and start a new planner with a new `plan-prompt`. After two rounds of questions, show the user what is still open and ask whether to go on.
+
+## Step 4: The plan reviewer
+
+Run `plan-review-prompt`. Start a fresh `plan-reviewer` subagent with the whole output, never with the planner's reply, and wait for its final reply. Save the whole reply with the shell into `.feature-flow/state/plan-review-<feature>.txt`.
+
+If it ends `PLAN-REVIEW: FAIL`, run the planner once more with the findings, `plan-prompt .feature-flow/state/brief-<feature>.md .feature-flow/state/plan-review-<feature>.txt`, then review again. A second FAIL is not retried: show its findings to the user at approval 2.
+
+## Step 5: Approval 2
+
+Show, from the planner's reply and the draft:
+
+- the goal and the bar
+- the build, test and smoke commands it found (they are frozen once approved)
+- the tickets as a compact graph, for example `02 Build the service   after 01`
+- what it dropped, so the user can overrule it
+- what it assumed, its open questions, and any outside sources it relied on
+- the plan review result, and its findings if it failed
+
+Ask: write this plan? yes, edit, or cancel. On an edit, add it to the brief under `Decided:`, save, and go back to Step 3. On cancel, stop: the draft stays in the state folder and nothing in the repo changed. Skip the question only in auto mode.
+
+## Step 6: Accept
+
+Run `plan-accept`. It copies the draft into `plans/<feature>/` (or the project's `FLOW_DIR`) and checks it, then prints `OK <folder>`, or `STOP <reason>`: report the reason and stop. It never overwrites a plan and never commits.

feature_flow_cli-0.1.1/guides/plan-review.md

@@ -0,0 +1,29 @@
+# Review a draft plan
+
+You are the **plan reviewer**, not the planner. You did not write this plan, you never saw the planner's reasoning, and you do not trust its account of it. You are given the approved feature brief and the draft folder (`.feature-flow/state/draft/<feature>/`).
+
+You cannot edit or write anything. You may read, search, run the plan check, and run the commands in the draft's `commands.md`.
+
+## What to check
+
+1. **The brief is covered.** Every part of the brief's What and In scope is planned by some ticket. Name each part that is not.
+2. **Nothing outside the brief.** No ticket builds what the brief puts under Out, or what the brief never asked for and the bar does not need.
+3. **The bar holds.** The spec's bar matches the brief's bar, and the last ticket is the acceptance ticket that runs it.
+4. **The commands are real.** Each command in `commands.md` exists in the project's own config, and Smoke runs and exits 0 now. Run it.
+5. **Done when is checkable by a stranger.** Each bullet names a command and the result it should print, or an outcome someone who has not read the plan can observe.
+6. **Forks belong to the right person.** A choice that changes what the user gets is a `settle` ticket or an open question, not a decision the planner made quietly.
+7. **The graph is sound.** Run `FLOW_DIR=.feature-flow/state/draft python3 scripts/flow-status.py <feature> --check` and report any problem or warning. Tickets are small (about 5 Done when bullets at most), and `Blocked by` lists only real dependencies.
+8. **Outside facts have sources.** Each fact about a library or outside API that a ticket relies on has a source line in `map.md`.
+
+Do not check style, wording or ticket order beyond what the list says.
+
+## Your reply
+
+For each failed check, one finding: the check's number, the file, and what is wrong in a sentence. Then a last line that is exactly one of:
+
+```
+PLAN-REVIEW: PASS
+PLAN-REVIEW: FAIL
+```
+
+PASS only when every check above holds. Nothing after that line.

feature_flow_cli-0.1.1/guides/plan.md

@@ -0,0 +1,94 @@
+# Plan a feature
+
+You are the **planner**. You are given a **feature brief** the user approved, and you turn it into one spec, one map and a graph of small tickets, written as a **draft**. You never saw the conversation behind the brief, and you cannot ask the user anything: what only the user can decide comes back in your reply.
+
+Below, `<feature>` is the feature's folder name from the brief, and `<draft>` is the draft folder your prompt names (`.feature-flow/state/draft/<feature>/`).
+
+## Where the files go
+
+Write everything inside `<draft>`, laid out as the plan will be:
+
+```
+<draft>
+├── spec.md            what and why
+├── map.md             destination, decisions so far, open questions
+├── commands.md        the real commands, frozen once approved
+├── learnings.md       empty, workers append to it
+└── tasks/
+    ├── 01-slug.md     one ticket per file
+    └── 02-slug.md
+```
+
+Write and edit only inside `<draft>` (on a findings round, fix the draft there), never change a file outside it, never commit. The conductor copies the draft into the repo after the user approves it. If the repo documents another place for plans (CLAUDE.md, AGENTS.md, `docs/`), still write the draft here, and name that place and the two variables the scripts need (`FLOW_DIR`, `FLOW_TICKETS`) in your reply.
+
+## Step 1: Read the brief
+
+The brief is the whole ask. Plan what it says: its What, Why, scope and bar. Each line under Unsure is an assumption you may keep or replace with what the code shows; say which in your reply. Lines under `Decided:` are the user's answers and win over everything above them. A gap the code cannot close goes under Open questions in `map.md`, or becomes a `settle` ticket when later tickets depend on it. If the brief has no bar, stop and reply `PLAN: QUESTIONS`.
+
+If your prompt carries review findings from an earlier round, the draft is already there: fix each finding in it, or say in your reply why it stays.
+
+## Step 2: Research
+
+**The codebase first.** 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. Find the **real** build, test and lint commands: 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. 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.
+
+**Outside only where the code cannot answer.** For a library or API the feature uses, read the version the lockfile pins, then that version's official documentation. When the brief names a hard problem, look for how others solved it. Never research what the codebase already decides. Write every outside fact you rely on into `map.md` under Decisions so far with its source (`docs: <url>`). If you cannot reach the web, say so in your reply and plan from the codebase.
+
+## Step 3: Draft the graph
+
+At every real fork (two reasonable ways to build something), write both in a sentence, pick one and give the reason in `spec.md` under Decisions, with the other named as rejected. If the choice changes what the user gets, do not pick: make it a `settle` ticket and list it under Open questions.
+
+Then 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 brief asks for.
+
+## Step 4: Write the files
+
+- `spec.md` from [templates/spec.md](templates/spec.md). One document. Remove the sections that do not apply. Its Problem and Goal carry the brief's What, Why and bar, so the plan never depends on the conversation.
+- `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.
+- `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 brief 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 say so in your reply. 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 `FLOW_DIR=.feature-flow/state/draft 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 you reply.
+
+## Step 6: Reply
+
+Reply in this shape, with nothing after the last line:
+
+```
+GOAL: <one sentence>
+BAR: <the command and what it should print>
+COMMANDS: Build <cmd> | Test <cmd> | Lint <cmd> | Smoke <cmd>
+GRAPH:
+01 Define the types
+02 Build the service            after 01
+03 Acceptance                   after 02
+DROPPED: <each dropped ticket and why, or none>
+ASSUMED: <each Unsure line: kept, or replaced by what the code showed>
+SOURCES: <outside sources relied on, or none; say if you had no web access>
+OPEN QUESTIONS: <what only the user can decide, or none>
+PLAN: READY
+```
+
+End with `PLAN: QUESTIONS` instead when the draft cannot be finished without an answer from the user. Then list the questions under OPEN QUESTIONS and leave the draft as far as you got.

{feature_flow_cli-0.1.0 → feature_flow_cli-0.1.1}/guides/show.md

@@ -8,7 +8,7 @@ If no feature was given, list `plans/*/` and ask which one.
 
 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.
+If the script is not installed, say so and point to `uvx feature-flow-cli install .` (or `python3 install.py <repo>` from a feature-flow clone). 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
 

{feature_flow_cli-0.1.0 → feature_flow_cli-0.1.1}/skills/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.
 argument-hint: "[feature] [show] [auto]"
 disable-model-invocation: true
 ---
 
 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 `guides/` or `.feature-flow/guides/`.
 
@@ -17,11 +17,15 @@ With `show`, follow `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 `guides/brief.md` with the user. You write the brief and ask for both yeses (unless `auto`); a subagent 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 `feature-planner.md` and `plan-reviewer.md` are installed where the builder's role is (see below).
 
-1. Follow `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>`: spawn a `feature-planner` subagent with the whole output as its prompt. Wait for its final reply.
+- `plan-review-prompt`: spawn a `plan-reviewer` subagent with the whole output, never with the planner's reply. Wait for its final reply and save it with Bash 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 `guides/plan.md`.
 
 ## Before building
 
@@ -29,7 +33,7 @@ With a plan present, check these before `start`, and stop at the first that fail
 
 - `git status --porcelain` is empty.
 - `python3 scripts/flow-status.py <feature> --check` prints `OK`.
-- `ticket-builder.md` and `ticket-reviewer.md` are in `.claude/agents/`, `~/.claude/agents/`, or `$CLAUDE_HOME/agents/` when `CLAUDE_HOME` is set. If not, say to run `bash install.sh` from feature-flow.
+- `ticket-builder.md` and `ticket-reviewer.md` are in `.claude/agents/`, `~/.claude/agents/`, or `$CLAUDE_HOME/agents/` when `CLAUDE_HOME` is set. If not, say to run `uvx feature-flow-cli install .` in this repo (or `python3 install.py <repo>` 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`.
 
@@ -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.0/guides/plan.md

@@ -1,93 +0,0 @@
-# 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>
-```