fileplan 0.5.0__tar.gz

fileplan-0.5.0/LICENSE

@@ -0,0 +1,28 @@
+BSD 3-Clause License
+
+Copyright (c) 2026 John Borwick
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its contributors
+   may be used to endorse or promote products derived from this software
+   without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

fileplan-0.5.0/PKG-INFO

@@ -0,0 +1,301 @@
+Metadata-Version: 2.4
+Name: fileplan
+Version: 0.5.0
+Summary: A plan.toml interpreter: declared states, transitions and keys for filing work across sessions
+Author: John Borwick
+Author-email: John Borwick <john_borwick@pobox.com>
+License-Expression: BSD-3-Clause
+License-File: LICENSE
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development
+Classifier: Typing :: Typed
+Requires-Dist: click>=8.1
+Requires-Dist: dulwich>=1.2.14
+Requires-Python: >=3.12
+Project-URL: Homepage, https://github.com/borwick/fileplan
+Project-URL: Repository, https://github.com/borwick/fileplan
+Project-URL: Documentation, https://github.com/borwick/fileplan/blob/main/docs/index.md
+Project-URL: Issues, https://github.com/borwick/fileplan/issues
+Description-Content-Type: text/markdown
+
+# fileplan
+
+This project is primarily designed for AI-assisted development workflows. I didn't want to set up beads, basically.
+
+Track project plans in directories and files rather than PLAN.md. This lets multiple agents simultaneously develop code, and reduces the cost and churn of adding, reordering, or cancelling work.
+
+## Key elements
+
+Create a plan file for each "phase" or set of work you want to do. The plan file is markdown with TOML frontmatter, e.g.
+
+    todo/new-work.md:
+    +++
+    title = "This is a new piece of work"
+    +++
+
+    Description of work.
+
+Then, `fileplan` reads a `plan.toml` file that defines your workflow. A `plan.toml` can be composed of:
+
+  - states
+    - "paths" (directories) assigned to states
+    - "doc" - documentation for this state
+    - capabilities
+  - keys
+    - attributes related to a plan file
+  - transitions
+    - from state
+    - to state
+    - "doc" - documentation for this transition
+  - "identity"
+    - "doc" - documentation on how agents set their identities and "claim" items
+    - "pid" - environment variables to use to derive agent ID
+
+## Getting started
+
+Start with the default workflow:
+
+```
+$ fileplan init .
+inbox
+plan
+docs
+docs/archive.md
+docs/method.md
+docs/procedures.md
+plan.toml
+```
+
+Create an item:
+
+```
+$ fileplan capture "Rename the states" --body "The names init wrote are placeholders."
+inbox/rename-the-states.md
+```
+
+`capture` writes the plan file:
+
+    $ cat inbox/rename-the-states.md
+    +++
+    title = "Rename the states"
+    +++
+    
+    The names init wrote are placeholders.
+
+The plan file can then be found and managed via `fileplan`:
+
+```
+$ fileplan list
+rename-the-states  inbox
+  title  Rename the states
+  path   inbox/rename-the-states.md
+
+showing 1 of 1 items
+register plan: floor 1, nothing held yet, in docs/archive.md
+```
+
+Transition the plan file with the `queue` transition:
+
+```
+$ fileplan queue rename-the-states
+plan/rename-the-states.md
+
+$ fileplan list
+rename-the-states  plan
+  position  100
+  number    1
+  title     Rename the states
+  path      plan/rename-the-states.md
+
+showing 1 of 1 items
+register plan: floor 1, highest 1, in docs/archive.md
+```
+
+Mark the plan file as in progress:
+
+```
+$ fileplan work rename-the-states --status "in progress"
+plan/rename-the-states.md
+
+$ fileplan work rename-the-states --status nobody
+Usage: fileplan work [OPTIONS] ITEM
+Try 'fileplan work --help' for help.
+
+Error: Invalid value for '--status': 'nobody' is not one of 'in progress', 'waiting'.
+```
+
+Mark it done with `archive`:
+
+```
+$ fileplan archive rename-the-states --record "Renamed everything to our own words."
+docs/archive.md: filed `## 1. Rename the states` at its place in the register, with the record under it
+plan/rename-the-states.md is gone: archive took it away
+docs/archive.md
+
+$ cat docs/archive.md
+# Archive
+
+Closed items are filed here, newest last. Each one goes under its own number.
+
+## 1. Rename the states
+
+Renamed everything to our own words.
+```
+
+## The plan.toml behind it
+
+Here is the `plan.toml` for the workflow above, without the documentation
+pointers:
+
+```toml
+[states.inbox]
+path = "inbox"
+
+[states.plan]
+path         = "plan"
+capabilities = ["queued", "numbered"]
+
+[keys.status]
+help   = "How the work is going."
+values = ["in progress", "waiting"]
+
+[transitions.capture]
+help = "Log an idea in the inbox."
+to   = "inbox"
+
+[transitions.queue]
+help = "Commit to an idea: move it into the plan."
+from = "inbox"
+to   = "plan"
+
+[transitions.work]
+help = "Say how the work is going."
+from = "plan"
+to   = "plan"
+sets = ["status"]
+
+[transitions.archive]
+help      = "Close an item out: file its entry and remove the item."
+from      = "plan"
+archives  = true
+dissolves = true
+```
+
+Every name in that file is a placeholder. `inbox`, `plan`, `capture`, `queue`,
+`work` and `archive` are not fileplan's words. Rename each one to the word your
+own work already uses.
+
+A transition's `from` and `to` decide what the transition does:
+
+  - No `from` creates a new plan file.
+  - A `from` and a `to` move the plan file to another directory.
+  - A `from` and a `to` that match leave the plan file where it is, and write a
+    key into the plan file's frontmatter.
+
+`archives = true` writes the closing entry into an archive document.
+`dissolves = true` deletes the plan file, which is why `archive` declares no
+`to`.
+
+Capabilities give a state extra behaviour. The `plan` state above declares
+`queued` and `numbered`, which is why the plan file picked up a position and a
+number when it arrived there. The `register` line in the listing says which
+numbers the archive document has taken.
+
+## Asking fileplan about your workflow
+
+The workflow above is one example. To see your own, ask fileplan rather than
+a document.
+
+Run `fileplan` with no arguments to see what your `plan.toml` declares:
+
+```
+$ fileplan
+/private/tmp/fileplan-example/plan.toml
+
+States
+  inbox    inbox/
+  plan     plan/
+
+Transitions
+  capture  Log an idea in the inbox.
+  queue    Commit to an idea: move it into the plan.
+  work     Say how the work is going.
+  archive  Close an item out: file its entry and remove the item.
+
+Declares
+  archive  archives, dissolves
+
+Run `fileplan list` to see what is filed.
+Run `fileplan next COMMAND` to see what COMMAND could take right now.
+Run `fileplan show ITEM` to see one item's row.
+Run `fileplan COMMAND --help` to see what COMMAND takes.
+```
+
+`Declares` lists the transitions that do more than move a plan file.
+
+Ask one transition what it takes:
+
+```
+$ fileplan work --help
+Usage: fileplan work [OPTIONS] ITEM
+
+  Say how the work is going.
+
+Options:
+  --status [in progress|waiting]  How the work is going.
+  --check                         Say what this run would do, and stop before
+                                  writing anything. A refusal under --check is
+                                  the refusal a real run gives.
+  --help                          Show this message and exit.
+
+  Where the item goes
+    stays in plan
+
+  Reading
+    work    docs/method.md#work
+    status  docs/method.md#status
+
+  Running it
+    docs/procedures.md#working-an-item
+```
+
+`Reading` and `Running it` are the `doc` and `policy` pointers from your
+`plan.toml`, resolved to the sections they name. The sections are in your own
+documentation. fileplan prints the pointers and never writes the prose behind
+them.
+
+Add `--check` to any transition to print what the transition would do, and stop
+before writing anything.
+
+`fileplan --json` prints every transition at once, for a script or an agent
+rather than for a person.
+
+## Where to go next
+
+  - [Initializing fileplan](https://github.com/borwick/fileplan/blob/main/docs/initialization.md) — the full walk, from
+    installing fileplan to handing an agent the skills. Every command in it was
+    run and its output pasted.
+  - [Retrofitting fileplan](https://github.com/borwick/fileplan/blob/main/docs/retrofit.md) — the walk for a tree that
+    already has work in it, where `init` is the wrong first command.
+  - [The method](https://github.com/borwick/fileplan/blob/main/docs/method.md) — the reference for every word a `plan.toml`
+    can hold.
+  - [The documents](https://github.com/borwick/fileplan/blob/main/docs/index.md) — everything under `docs/`, plus the two
+    skills an agent reads.
+
+## Status
+
+`uv build` produces a wheel that installs and runs. Check the package index for
+which versions are published.
+
+## AI disclosure
+
+`fileplan` was written with Claude Code, under John Borwick's direction and
+review. [How this was written](https://github.com/borwick/fileplan/blob/main/docs/ai-disclosure.md) covers the disclosure
+level, who did what, and why the git history does not record it. Anthropic did
+not build this tool and does not endorse it.

fileplan-0.5.0/README.md

@@ -0,0 +1,275 @@
+# fileplan
+
+This project is primarily designed for AI-assisted development workflows. I didn't want to set up beads, basically.
+
+Track project plans in directories and files rather than PLAN.md. This lets multiple agents simultaneously develop code, and reduces the cost and churn of adding, reordering, or cancelling work.
+
+## Key elements
+
+Create a plan file for each "phase" or set of work you want to do. The plan file is markdown with TOML frontmatter, e.g.
+
+    todo/new-work.md:
+    +++
+    title = "This is a new piece of work"
+    +++
+
+    Description of work.
+
+Then, `fileplan` reads a `plan.toml` file that defines your workflow. A `plan.toml` can be composed of:
+
+  - states
+    - "paths" (directories) assigned to states
+    - "doc" - documentation for this state
+    - capabilities
+  - keys
+    - attributes related to a plan file
+  - transitions
+    - from state
+    - to state
+    - "doc" - documentation for this transition
+  - "identity"
+    - "doc" - documentation on how agents set their identities and "claim" items
+    - "pid" - environment variables to use to derive agent ID
+
+## Getting started
+
+Start with the default workflow:
+
+```
+$ fileplan init .
+inbox
+plan
+docs
+docs/archive.md
+docs/method.md
+docs/procedures.md
+plan.toml
+```
+
+Create an item:
+
+```
+$ fileplan capture "Rename the states" --body "The names init wrote are placeholders."
+inbox/rename-the-states.md
+```
+
+`capture` writes the plan file:
+
+    $ cat inbox/rename-the-states.md
+    +++
+    title = "Rename the states"
+    +++
+    
+    The names init wrote are placeholders.
+
+The plan file can then be found and managed via `fileplan`:
+
+```
+$ fileplan list
+rename-the-states  inbox
+  title  Rename the states
+  path   inbox/rename-the-states.md
+
+showing 1 of 1 items
+register plan: floor 1, nothing held yet, in docs/archive.md
+```
+
+Transition the plan file with the `queue` transition:
+
+```
+$ fileplan queue rename-the-states
+plan/rename-the-states.md
+
+$ fileplan list
+rename-the-states  plan
+  position  100
+  number    1
+  title     Rename the states
+  path      plan/rename-the-states.md
+
+showing 1 of 1 items
+register plan: floor 1, highest 1, in docs/archive.md
+```
+
+Mark the plan file as in progress:
+
+```
+$ fileplan work rename-the-states --status "in progress"
+plan/rename-the-states.md
+
+$ fileplan work rename-the-states --status nobody
+Usage: fileplan work [OPTIONS] ITEM
+Try 'fileplan work --help' for help.
+
+Error: Invalid value for '--status': 'nobody' is not one of 'in progress', 'waiting'.
+```
+
+Mark it done with `archive`:
+
+```
+$ fileplan archive rename-the-states --record "Renamed everything to our own words."
+docs/archive.md: filed `## 1. Rename the states` at its place in the register, with the record under it
+plan/rename-the-states.md is gone: archive took it away
+docs/archive.md
+
+$ cat docs/archive.md
+# Archive
+
+Closed items are filed here, newest last. Each one goes under its own number.
+
+## 1. Rename the states
+
+Renamed everything to our own words.
+```
+
+## The plan.toml behind it
+
+Here is the `plan.toml` for the workflow above, without the documentation
+pointers:
+
+```toml
+[states.inbox]
+path = "inbox"
+
+[states.plan]
+path         = "plan"
+capabilities = ["queued", "numbered"]
+
+[keys.status]
+help   = "How the work is going."
+values = ["in progress", "waiting"]
+
+[transitions.capture]
+help = "Log an idea in the inbox."
+to   = "inbox"
+
+[transitions.queue]
+help = "Commit to an idea: move it into the plan."
+from = "inbox"
+to   = "plan"
+
+[transitions.work]
+help = "Say how the work is going."
+from = "plan"
+to   = "plan"
+sets = ["status"]
+
+[transitions.archive]
+help      = "Close an item out: file its entry and remove the item."
+from      = "plan"
+archives  = true
+dissolves = true
+```
+
+Every name in that file is a placeholder. `inbox`, `plan`, `capture`, `queue`,
+`work` and `archive` are not fileplan's words. Rename each one to the word your
+own work already uses.
+
+A transition's `from` and `to` decide what the transition does:
+
+  - No `from` creates a new plan file.
+  - A `from` and a `to` move the plan file to another directory.
+  - A `from` and a `to` that match leave the plan file where it is, and write a
+    key into the plan file's frontmatter.
+
+`archives = true` writes the closing entry into an archive document.
+`dissolves = true` deletes the plan file, which is why `archive` declares no
+`to`.
+
+Capabilities give a state extra behaviour. The `plan` state above declares
+`queued` and `numbered`, which is why the plan file picked up a position and a
+number when it arrived there. The `register` line in the listing says which
+numbers the archive document has taken.
+
+## Asking fileplan about your workflow
+
+The workflow above is one example. To see your own, ask fileplan rather than
+a document.
+
+Run `fileplan` with no arguments to see what your `plan.toml` declares:
+
+```
+$ fileplan
+/private/tmp/fileplan-example/plan.toml
+
+States
+  inbox    inbox/
+  plan     plan/
+
+Transitions
+  capture  Log an idea in the inbox.
+  queue    Commit to an idea: move it into the plan.
+  work     Say how the work is going.
+  archive  Close an item out: file its entry and remove the item.
+
+Declares
+  archive  archives, dissolves
+
+Run `fileplan list` to see what is filed.
+Run `fileplan next COMMAND` to see what COMMAND could take right now.
+Run `fileplan show ITEM` to see one item's row.
+Run `fileplan COMMAND --help` to see what COMMAND takes.
+```
+
+`Declares` lists the transitions that do more than move a plan file.
+
+Ask one transition what it takes:
+
+```
+$ fileplan work --help
+Usage: fileplan work [OPTIONS] ITEM
+
+  Say how the work is going.
+
+Options:
+  --status [in progress|waiting]  How the work is going.
+  --check                         Say what this run would do, and stop before
+                                  writing anything. A refusal under --check is
+                                  the refusal a real run gives.
+  --help                          Show this message and exit.
+
+  Where the item goes
+    stays in plan
+
+  Reading
+    work    docs/method.md#work
+    status  docs/method.md#status
+
+  Running it
+    docs/procedures.md#working-an-item
+```
+
+`Reading` and `Running it` are the `doc` and `policy` pointers from your
+`plan.toml`, resolved to the sections they name. The sections are in your own
+documentation. fileplan prints the pointers and never writes the prose behind
+them.
+
+Add `--check` to any transition to print what the transition would do, and stop
+before writing anything.
+
+`fileplan --json` prints every transition at once, for a script or an agent
+rather than for a person.
+
+## Where to go next
+
+  - [Initializing fileplan](https://github.com/borwick/fileplan/blob/main/docs/initialization.md) — the full walk, from
+    installing fileplan to handing an agent the skills. Every command in it was
+    run and its output pasted.
+  - [Retrofitting fileplan](https://github.com/borwick/fileplan/blob/main/docs/retrofit.md) — the walk for a tree that
+    already has work in it, where `init` is the wrong first command.
+  - [The method](https://github.com/borwick/fileplan/blob/main/docs/method.md) — the reference for every word a `plan.toml`
+    can hold.
+  - [The documents](https://github.com/borwick/fileplan/blob/main/docs/index.md) — everything under `docs/`, plus the two
+    skills an agent reads.
+
+## Status
+
+`uv build` produces a wheel that installs and runs. Check the package index for
+which versions are published.
+
+## AI disclosure
+
+`fileplan` was written with Claude Code, under John Borwick's direction and
+review. [How this was written](https://github.com/borwick/fileplan/blob/main/docs/ai-disclosure.md) covers the disclosure
+level, who did what, and why the git history does not record it. Anthropic did
+not build this tool and does not endorse it.

fileplan-0.5.0/pyproject.toml

@@ -0,0 +1,53 @@
+[project]
+name = "fileplan"
+version = "0.5.0"
+description = "A plan.toml interpreter: declared states, transitions and keys for filing work across sessions"
+readme = "README.md"
+requires-python = ">=3.12"
+dependencies = [
+    "click>=8.1",
+    "dulwich>=1.2.14",
+]
+license = "BSD-3-Clause"
+license-files = ["LICENSE"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Software Development",
+    "Typing :: Typed",
+]
+
+[[project.authors]]
+name = "John Borwick"
+email = "john_borwick@pobox.com"
+
+[project.urls]
+Homepage = "https://github.com/borwick/fileplan"
+Repository = "https://github.com/borwick/fileplan"
+Documentation = "https://github.com/borwick/fileplan/blob/main/docs/index.md"
+Issues = "https://github.com/borwick/fileplan/issues"
+
+[project.scripts]
+fileplan = "fileplan.cli:console_main"
+
+[build-system]
+requires = ["uv_build>=0.12.3,<0.13.0"]
+build-backend = "uv_build"
+
+[dependency-groups]
+dev = ["pytest>=8.0"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+[tool.pysmelly]
+exclude = [
+    "tests/",
+    "test_*",
+    "conftest.py",
+]