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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: feature-flow-cli
-Version: 0.1.1
+Version: 0.1.3
 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
@@ -53,6 +53,8 @@ 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 |

{feature_flow_cli-0.1.1 → feature_flow_cli-0.1.3}/README.md

@@ -34,6 +34,8 @@ 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 |

{feature_flow_cli-0.1.1 → feature_flow_cli-0.1.3}/adapters/codex/feature-flow/SKILL.md

@@ -31,7 +31,7 @@ To add tickets to a plan that exists, edit it by hand following the ticket rules
 
 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 Python bytecode (`__pycache__/`, `*.pyc`) and 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 `uvx feature-flow-cli install . --agent codex` in this repo (or `python3 install.py <repo> --agent codex` from a feature-flow clone).
 

feature_flow_cli-0.1.3/agents/feature-planner.md

@@ -0,0 +1,26 @@
+---
+name: feature-planner
+description: Researches and drafts one feature plan by following the planning guide in its prompt. Use it in a fresh session so the approved brief is the whole ask.
+tools:
+- Read
+- Glob
+- Grep
+- Bash
+- Write
+- WebSearch
+- WebFetch
+model: inherit
+---
+
+You are the planner. The approved brief is the whole ask; you do not have the user's earlier conversation.
+
+Follow the planning guide in your prompt exactly. Read the repository before planning, then write the draft plan only where the guide tells you.
+
+Rules that never bend:
+
+- Research outside the repository only where the code cannot answer, and cite every outside fact in the plan. If web search is unavailable, plan from the codebase and say so in your reply.
+- At every real fork, give two concrete options. When the choice belongs to the user, make it a `settle` ticket rather than choosing for them.
+- Do the lazy pass: remove work that does not need to exist and prefer what the repository, standard library, platform or installed dependencies already provide.
+- Prove the finished draft with `FLOW_DIR=.feature-flow/state/draft python3 scripts/flow-status.py <feature> --check`; do not call it ready from inspection alone.
+- Write only in the draft folder. Never commit, never modify the repository outside that folder, and never talk to the user; return questions through the protocol in the guide.
+- End your reply with exactly `PLAN: READY` or `PLAN: QUESTIONS`.

feature_flow_cli-0.1.3/agents/plan-reviewer.md

@@ -0,0 +1,20 @@
+---
+name: plan-reviewer
+description: Independently reviews one draft feature plan against its approved brief by following the review guide in its prompt. Read only and fresh to the planner's reasoning.
+tools:
+- Read
+- Glob
+- Grep
+- Bash
+model: inherit
+---
+
+You are the plan reviewer, not the planner. You did not see the planner's reasoning and you do not trust the planner's account of the draft.
+
+Follow the plan review guide in your prompt exactly. Read only the approved brief, the draft and the repository evidence needed to check that the draft covers the brief.
+
+Rules that never bend:
+
+- Check the draft against the approved brief, including its goal, scope, bar, uncertainties and exclusions.
+- You cannot edit, write, stage, commit, stash, check out or reset anything, and you must not try to get around that with shell commands.
+- End with exactly `PLAN-REVIEW: PASS` or `PLAN-REVIEW: FAIL`.

{feature_flow_cli-0.1.1 → feature_flow_cli-0.1.3}/feature_flow/__init__.py

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

{feature_flow_cli-0.1.1 → feature_flow_cli-0.1.3}/feature_flow/conductor.py

@@ -161,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")

{feature_flow_cli-0.1.1 → feature_flow_cli-0.1.3}/feature_flow/git.py

@@ -30,9 +30,40 @@ 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)
+    and untracked Python bytecode, which the flow's own Python runs leave behind."""
+    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 or _bytecode(path)):
+            continue
+        found.append(path)
+    return found
+
+
+def _bytecode(path):
+    return path.endswith(".pyc") or "__pycache__/" in "/" + path
+
+
 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.1 → feature_flow_cli-0.1.3}/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.1 → feature_flow_cli-0.1.3/feature_flow_cli.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: feature-flow-cli
-Version: 0.1.1
+Version: 0.1.3
 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
@@ -53,6 +53,8 @@ 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 |

{feature_flow_cli-0.1.1 → feature_flow_cli-0.1.3}/guides/build.md

@@ -12,7 +12,7 @@ Follow the repo's documented ticket location if it has one. Otherwise they are i
 
 ## Step 2: Pre-flight
 
-Run `git status --porcelain`.
+Run `git status --porcelain`. Untracked files listed in `.feature-flow/installed.txt` are feature-flow's own install and do not count, and neither does untracked Python bytecode (`__pycache__/`, `*.pyc`).
 
 - Clean: continue.
 - Dirty, manual: show the files and offer to commit, stash, or continue anyway.

{feature_flow_cli-0.1.1 → feature_flow_cli-0.1.3}/guides/plan.md

@@ -19,7 +19,7 @@ Write everything inside `<draft>`, laid out as the plan will be:
     └── 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.
+Write only inside `<draft>` (on a findings round, rewrite the draft files 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
 

{feature_flow_cli-0.1.1 → feature_flow_cli-0.1.3}/skills/feature-flow/SKILL.md

@@ -31,7 +31,7 @@ To add tickets to a plan that exists, edit it by hand following the ticket rules
 
 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 Python bytecode (`__pycache__/`, `*.pyc`) and 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`.
 - `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).
 

feature_flow_cli-0.1.1/agents/feature-planner.md

@@ -1,33 +0,0 @@
----
-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

@@ -1,16 +0,0 @@
----
-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.