formwork-kit 0.1.0__tar.gz → 0.2.1__tar.gz

{formwork_kit-0.1.0 → formwork_kit-0.2.1}/FORMWORK.md

@@ -12,16 +12,13 @@ Everything is one loop. Only the size changes.
 BRIEF → WORK → CHECK → REPORT → STOP → you say go → BRIEF …
 ```
 
-| Size | How long | The brief is | The report is |
-|---|---|---|---|
-| task | minutes | one line | files changed, check result |
-| checkpoint | one sitting | six headings | the full list |
-| round | hours to days | a question per role | a round record |
-| phase | weeks | what it settles | one document |
-| milestone | months | a direction | — |
+**The agent halts at STOP and waits for you**, however small the job was.
 
-Each one answers four questions: what it produces, what must be true before it
-starts, who says go, and **what would tell us it failed.**
+Five sizes run this way, from a task of minutes to a milestone of months. The
+sizes, and how to pick one, are in [`formwork/loop.md`](formwork/loop.md).
+
+Work is handed down from a planning conversation and reported back up by you.
+That part is in [`formwork/threads.md`](formwork/threads.md).
 
 ---
 
@@ -39,10 +36,14 @@ These do not ask you. They refuse.
 | A declared runtime is actually wired up | `formwork/check/checks/guard-wired` |
 | The agent does not quietly alter the kit's own files | `formwork/guard/protected-files` |
 | A turn does not end while the aggregate is red | `formwork/guard/quality-gate` |
+| The standing brief is not older than the newest decision | `formwork/check/checks/standing-current` |
+| Work marked finished left a report behind | `formwork/check/checks/work-paired` |
+| Every generated role names the style page | `formwork/check/checks/style-pointed` |
 
 > [!NOTE]
-> **The last one refuses three times in a session, then stands aside**, so a
-> genuinely stuck turn is not trapped for ever. Change it with `gate_budget`.
+> **The turn-end gate refuses three times in a session, then stands aside**, so
+> a genuinely stuck turn is not trapped for ever. Change it with `gate_budget`.
+> The rows below it are checks, and none of them has a budget.
 
 Run them:
 
@@ -60,10 +61,10 @@ instead: `formwork/fw check`, `formwork/fw demo`, `formwork/fw roles`. Run
 
 ## What is advice
 
-Everything else. **46 rules**, in two files.
+Everything else. **47 rules**, in two files.
 
-- `formwork/rules/core.md` — 13. You meet these every day.
-- `formwork/rules/full.md` — 33. Read one when you hit the situation it covers.
+- `formwork/rules/core.md` holds 13. You meet these every day.
+- `formwork/rules/full.md` holds 34. Read one when you hit the situation.
 
 > [!TIP]
 > Every rule says what it catches. None of them tells you a story, because the
@@ -89,7 +90,7 @@ A rule you follow without understanding gets dropped quietly later anyway.
 
 ## Settings
 
-This is the whole file, and the installer writes it for you:
+One file, `.formwork.toml`, and the installer writes it for you:
 
 ```toml
 [bindings]
@@ -98,17 +99,27 @@ runtime = "claude-code"          # which tool you use
 [strength]
 git_boundary = "block"           # block | warn | off
 protect_files = "block"          # block | warn | off
+aggregate_gate = "block"         # the turn-end gate
+gate_budget = 3                  # refusals before it stands aside
 ```
 
-`[strength]` tunes how hard the enforced guards bite. `[bindings]` is your
-setup. There is no third section: see above.
+`[bindings]` is your setup. `[strength]` tunes how hard the enforced guards
+bite. There is no third section: see above.
 
-**Two more keys exist and both live in `[strength]`:**
+**The last two lines appear only once you change them.** They have working
+defaults, so a fresh file is shorter than this.
 
-```toml
-aggregate_gate = "block"   # block | warn | off. The turn-end gate
-gate_budget = 3            # how many times it refuses before standing aside
-```
+**You do not have to write any of it by hand.** `formwork setup` asks a few
+questions once, shows you everything it is about to do, and writes it only if
+you say yes:
+
+- `docs/style.md`, from how you said you want to be spoken to
+- `docs/standing.md`, seeded with what you are building and what is next
+- `docs/decisions/`, `docs/briefs/`, `docs/reports/`, started and explained
+- the `[strength]` values, including `gate_budget`
+
+It never overwrites a file you already have, and it never touches
+`[bindings]`, which the installer worked out by looking at your project.
 
 For one session only:
 
@@ -122,7 +133,7 @@ FORMWORK_GATE=off
 
 ## Your team
 
-`formwork/roles/` holds 27 roles. Six run the method. Twenty-one do the work,
+`formwork/roles/` holds 28 roles. Seven run the method. Twenty-one do the work,
 grouped into packs.
 
 **All of them are available. There is no switch yet**, and this page says so
@@ -131,6 +142,9 @@ rather than describing one that does not exist.
 Adding your own is copying `TEMPLATE.md`, filling in five sections and four
 frontmatter fields. A role missing any of them does not load.
 
+**How they talk to you** is one page, [`formwork/style.md`](formwork/style.md),
+pointed at from every generated role. Your own `docs/style.md` overrides it.
+
 The installer generates them for your runtime. To regenerate after an edit:
 
 ```
@@ -155,9 +169,9 @@ trusting any of this further than it deserves.
 **A check that refuses rather than advises.** Most tooling tells you something
 is wrong and lets the work continue. This stops the turn.
 
-**Rules about what counts as evidence.** A figure is reported together with the
-command behind it. Anything unmeasured says so in capitals. A check that nobody has
-watched fail is not treated as proof of anything.
+**Rules about what counts as evidence.** A figure arrives with the command
+behind it. A gap is named rather than filled. A check nobody has watched fail
+is not treated as proof of anything.
 
 Both came out of real use. Neither has been tried by anybody else yet, and the
 kit would rather say that than imply a crowd that does not exist.
@@ -177,6 +191,7 @@ would establish the rest.
 [`formwork/first-run.md`](formwork/first-run.md). Fifteen minutes, on your own
 project.
 
-Then [`formwork/loop.md`](formwork/loop.md) for the working loop, and
-[`formwork/round.md`](formwork/round.md) when a decision is expensive enough to
-be worth a round.
+Then [`formwork/loop.md`](formwork/loop.md) for the working loop,
+[`formwork/threads.md`](formwork/threads.md) for how work starts and where the
+plan lives between conversations, and [`formwork/round.md`](formwork/round.md)
+when a decision is expensive enough to be worth a round.

formwork_kit-0.2.1/PKG-INFO

@@ -0,0 +1,505 @@
+Metadata-Version: 2.5
+Name: formwork-kit
+Version: 0.2.1
+Summary: You bring the idea. It brings the whole team. Rules your coding agent cannot ignore.
+Project-URL: Homepage, https://github.com/makariim/formwork
+Project-URL: Source, https://github.com/makariim/formwork
+Project-URL: Issues, https://github.com/makariim/formwork/issues
+Author: Muhammad Elsherif
+License-Expression: MIT
+License-File: LICENSE
+Keywords: agents,ai,claude,coding-agent,project-management
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Quality Assurance
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+
+<div align="center">
+
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="assets/logo-dark.svg">
+  <img src="assets/logo-light.svg" width="96" alt="">
+</picture>
+
+# Formwork
+
+**You bring the idea. It brings the whole team.**
+
+*Not a typo. Builders use formwork to hold a shape until it can stand on its
+own. Projects never had that. Now they do.*
+
+[![licence](https://img.shields.io/badge/licence-MIT-green.svg)](LICENSE)
+
+</div>
+
+---
+
+<div align="center">
+
+| A team | A way of working | Rules that refuse |
+|:--:|:--:|:--:|
+| everyone a project needs | brief, work, check, report, stop | some mistakes cannot happen |
+
+</div>
+
+```console
+$ pipx install formwork-kit
+$ formwork init && formwork install
+$ formwork setup && formwork check
+GATE: green. 12 check(s), each shown to reject the wrong and accept the right.
+```
+
+<div align="center">
+
+[Which agent you use](#which-agent-you-use-changes-what-you-get) ·
+[Install](#install) · [Your first turn](#your-first-turn) ·
+[Settings](#settings) · [What is inside](#what-is-inside) ·
+[What it will not pretend](#what-this-will-not-pretend) ·
+[Version one](#this-is-version-one) ·
+[Where to go next](#where-to-go-next)
+
+</div>
+
+---
+
+## Ideas do not die at the idea
+
+They die at what comes next.
+
+You need someone to find the holes in your plan. Someone who knows what breaks
+at 3am, what a screen should do, what the small print means. You need your
+choices written down so you are not arguing about them again next month. Most
+of all you need someone who will tell you no.
+
+That used to mean hiring people. People cost money. Hiring takes time.
+
+**Now it is a folder you copy into your project.**
+
+Twenty eight roles, already written. A director, a lead, a challenger, a
+researcher, a reviewer. Engineers for the back end, the front end, phones,
+data, servers and safety. A designer, a writer, a product person, a marketer.
+Someone who tells you when to call a real lawyer.
+
+Nobody to hire. Nobody to wait for. They are in the folder.
+
+---
+
+## Who it is for
+
+**Anyone building something with an AI agent.**
+
+**New to this?** The team, the order of work, the notes and the rules all
+arrive working. You bring the idea.
+
+**Done it many times?** Now it sits where your agents can read it, and some of
+it they cannot ignore. Delete the rules you disagree with. Rewrite any role you
+know better.
+
+**Expert in one thing?** Your role file will be thinner than you are. Replace
+it. Everything else keeps working around it.
+
+---
+
+## What you get
+
+**A way of working.** You say what you want. The agent works. The checks run.
+It tells you what it did, then stops and waits for you.
+
+**Notes that stay put.** Choices get a number and a page in your repository,
+instead of living in a chat you will close and lose.
+
+**Rules your agent cannot ignore.** Not tips. Real refusals.
+
+```console
+you:    commit this for me
+agent:  REFUSED by the version-control boundary: git commit changes
+        the repository.
+```
+
+Nobody read you a rule. You watched it work.
+
+> [!IMPORTANT]
+> That is the whole idea. You think about what you are building. The kit holds
+> everything else.
+
+---
+
+## Which agent you use changes what you get
+
+Read this before installing. It decides whether your first `formwork check`
+comes back green.
+
+| Agent | Can it stop a command? |
+|---|---|
+| **Claude Code** | Yes. Seen doing it |
+| **Codex** | It should. Nobody has tried |
+| **Cursor** | It should. Nobody has tried |
+| **Gemini CLI** | It should. Nobody has tried |
+
+**On Claude Code everything below works as written.**
+
+**On the other three, the install finishes and `formwork check` comes back
+red**, because the file that hooks the guards into your agent does not exist
+yet and you have to write it. Your agent's page in `formwork/adapters/` says
+exactly what goes in it. **Red is the honest answer there: nothing is guarding
+you yet.**
+
+Everything else works on all four from the start: the roles, the rules, the
+checks, the templates, the loop.
+
+**Setting one of those three up is the most useful thing anybody can do for
+this project.** [CONTRIBUTING.md](CONTRIBUTING.md) says what to send back.
+
+---
+
+## Install
+
+| You need | Check it |
+|---|---|
+| **Python 3.8 or newer** | `python3 --version` |
+| **git** | `git --version` |
+| **An AI coding agent** | Claude Code, Codex, Cursor or Gemini CLI |
+
+**Two ways in. They end in the same place.**
+
+### 1. As a package
+
+```
+pipx install formwork-kit
+```
+
+pipx puts the `formwork` command on your path and keeps it in its own
+environment, away from your project's packages.
+
+> [!IMPORTANT]
+> **If you used plain `pip` instead, `formwork` will say `command not found`.**
+> It installed fine. pip put the command in a folder your shell does not
+> search. You do not have to fix anything: put `python3 -m formwork_cli` in
+> front of every command below and they all work.
+>
+> ```
+> python3 -m formwork_cli init
+> ```
+
+Then, in your project:
+
+```
+cd /your/project
+formwork init
+formwork install --runtime claude-code    # or codex, cursor, gemini-cli
+formwork setup
+formwork check
+```
+
+**That last line should say green on Claude Code**, and red on the other three
+until you write the hook file, as above.
+
+Leave `--runtime` off and it finds your agent itself. When you have more than
+one set up, or none yet, it stops and tells you to name one.
+
+> [!TIP]
+> **Would you rather be walked through it?**
+> [`formwork/first-run.md`](formwork/first-run.md) is the same five commands
+> with somebody explaining each one: what it writes, what the exit codes mean,
+> what to do when your agent cannot block, and a first piece of real work at
+> the end. About fifteen minutes.
+
+<details>
+<summary><b>Other ways to install the package, and what to do when the command is not found</b></summary>
+
+<br>
+
+**In a virtual environment**, where the command lives inside it:
+
+```
+python3 -m venv .venv
+source .venv/bin/activate        # Windows: .venv\Scripts\activate
+python3 -m pip install formwork-kit
+```
+
+**With pip directly, say `python3 -m pip install formwork-kit`.** Typing `pip`
+or `pip3` can reach a different Python than the one you run, and then the
+package installs somewhere your `python3` never looks.
+
+**If `formwork` says `command not found`,** it installed fine and the command
+landed in a folder your shell does not search. You do not have to fix your
+path. Either of these works instead:
+
+```
+python3 -m formwork_cli check      the same command, run through Python
+formwork/fw check                  the kit's own command, needs no install
+```
+
+The second one only works after `formwork init`, because that is what puts the
+kit in your project. If you never got that far, use the first one, or install
+with pipx and start again.
+
+</details>
+
+### 2. As files, with nothing installed
+
+**There is no package to install and nothing to import.** The kit is text files
+and small Python programs, and it runs from where it sits.
+
+```
+git clone https://github.com/makariim/formwork.git the-kit
+cp -R the-kit/formwork the-kit/FORMWORK.md /your/project/
+
+cd /your/project
+formwork/fw install --runtime claude-code    # or codex, cursor, gemini-cli
+formwork/fw setup
+formwork/fw check
+```
+
+The copy is the whole kit, so you can delete `the-kit` afterwards. There is no
+`init` step here, because copying the folder in **is** the init step.
+
+`formwork check` becomes `formwork/fw check`, and the same for `install`,
+`setup`, `demo`, `roles`, `record` and `test`. Run `formwork/fw` on its own for
+the list. `where` and `version` belong to the installed command only.
+
+### What each step does
+
+| | |
+|---|---|
+| `init` | puts `formwork/` and `FORMWORK.md` into your project |
+| `install` | wires the guards into your agent, writes your role files. Add `--runtime <name>` when it cannot tell |
+| `setup` | asks eleven questions once, then writes your style file, your standing brief, and the folders for decisions, briefs and reports |
+| `check` | runs all twelve checks and says green or red |
+
+**What it touches.** It adds `formwork/` and `FORMWORK.md`, writes
+`.formwork.toml`, writes your agent's settings file keeping anything already
+there, generates one role file per role into your agent's folder, and puts one
+file in `~/.formwork/` holding a fingerprint of each file that enforces a
+rule.
+
+| System | Does it work? |
+|---|---|
+| **macOS** | Yes. Built and used here |
+| **Linux** | Should do. Nobody has tried. **Try it and tell us** |
+| **Windows** | The command installs. The guards assume a unix shell and nobody has run them there |
+
+---
+
+## Your first turn
+
+The kit is files, and your agent reads files. So the first turn is you telling
+it to. Four that cover most of it:
+
+**Starting something new**
+
+> Read `FORMWORK.md` and `formwork/first-run.md`. Then use the director role to
+> write me a brief for a command line tool that renames photos by the date they
+> were taken. Size the brief to the work. Do not build anything yet.
+
+*The **director** is the role that holds the plan and writes the briefs. It
+never builds anything.*
+
+**Picking up a project that already exists**
+
+> Read `FORMWORK.md`, then `docs/standing.md`. Tell me where we are in four
+> lines, and what you think the next piece of work is.
+
+*`docs/standing.md` is the **standing brief**, the one file that says where the
+project stands. `formwork setup` starts it for you. It is what stops every new
+window beginning with you retelling the whole story.*
+
+**Handing over one piece of work**
+
+> Here is the brief. [paste it] Do only what it says, nothing next to it. Check
+> your work with `formwork check`, tell me what you did, and stop there.
+
+**Asking one role for an opinion**
+
+> Use the security role. Read `formwork/guard/` and tell me what an attacker
+> would try first.
+
+**Then it stops and waits for you.** That is the shape, and it is the part
+people are surprised by. It does not carry on to the next thing because the
+next thing is obvious.
+
+---
+
+## Settings
+
+One file, `.formwork.toml`, in your project. The installer writes it and
+`formwork setup` fills it in by asking you.
+
+```toml
+[bindings]
+runtime = "claude-code"          # which agent you use
+
+[strength]
+git_boundary = "block"           # block | warn | off
+protect_files = "block"
+aggregate_gate = "block"
+gate_budget = 3
+```
+
+**Your file will be shorter than that**, and nothing is wrong. The installer
+writes the first two `[strength]` keys. The other two have working defaults, so
+they only appear once you change them. Adding them by hand works too.
+
+| When you would change something | What to change |
+|---|---|
+| you moved to a different agent | `runtime` |
+| a guard keeps stopping work you meant | that key to `warn`. It runs, and tells you |
+| you are only trying the kit out | that key to `off` |
+| a genuinely stuck turn keeps being refused | `gate_budget`, how many refusals before the gate stands aside |
+
+**For one session only**, without editing anything:
+
+```
+FORMWORK_GIT_BOUNDARY=off
+FORMWORK_PROTECT_FILES=warn
+FORMWORK_GATE=off
+```
+
+**Rules are not configured here.** There is no `[rules]` section and adding one
+fails a check. You drop a rule by deleting it from `formwork/rules/core.md`.
+[`FORMWORK.md`](FORMWORK.md) says why it works that way.
+
+**How the agents talk to you is not in this file.** That is
+[`formwork/style.md`](formwork/style.md), and your own `docs/style.md` written
+in your own words, which beats it. Every role points at both.
+
+---
+
+## What is inside
+
+| | | count it yourself |
+|---|---|---|
+| **3 guards** | small programs that refuse. Two stop a command, one stops a turn ending | `ls formwork/guard \| grep -v test_` |
+| **12 checks** | small programs that read your project and say green or red | `ls formwork/check/checks \| wc -l` |
+| **28 roles** | one file each, saying what that job does and where it stops | `ls formwork/roles/*/*.md \| wc -l` |
+| **47 rules** | 13 you meet daily, 34 for when you need them | `grep -c '^### ' formwork/rules/*.md` |
+| **356 tests** | every guard and check, proved able to fail | `formwork test` |
+
+It is all text files and small programs. You can read every line. Nothing is
+hidden. Nothing is sent anywhere.
+
+---
+
+## Every check has been watched failing
+
+A check nobody has seen fail proves nothing.
+
+So each check ships test cases of both kinds: at least one it must reject, at
+least one it must accept. It has to tell them apart. Watch it yourself with
+`formwork demo`.
+
+---
+
+## What this will not pretend
+
+Every number here comes with the command that made it. Anything unmeasured says
+so in capitals rather than guessing. There are three:
+
+| | |
+|---|---|
+| **What a round costs in money** | never measured. [`COSTS.md`](formwork/COSTS.md) says NOT ESTABLISHED instead of guessing |
+| **Whether the guards stop a determined agent** | they do not. [`limits.md`](formwork/limits.md) lists every route anybody has found |
+| **Whether three of the four agents work** | nobody has tried them. Said once already, near the top, because it changes what you get |
+
+> [!WARNING]
+> The guards stop the ordinary path, not a clever one. If you need real safety,
+> use a sandbox.
+
+Every time this kit failed on the person who wrote it, the failure went into
+[`docs/dogfood.md`](docs/dogfood.md) instead of being quietly patched. That page
+is the best reason to trust the rest.
+
+---
+
+## This is version one
+
+What is here is built and tested. What is not here, and is not being worked on
+today:
+
+| | |
+|---|---|
+| **Skills** | one word for a common job, instead of a paragraph. Considered, not started |
+| **A model per role** | pick the model and effort level for each role. Only Claude Code is known to allow it. Nobody has checked the other three, so this would be one agent out of four until somebody does |
+| **Teams** | more than one person on the same standing brief. Today the method says one director at a time, and nobody has tried two |
+| **Roles invented on the fly** | asked for by somebody who tried the kit. It cuts across the check that stops two roles owning one job, so it stays a question we have not settled |
+
+None of these is promised. They are written down so you can see the edge of
+what is here.
+
+Version one is not a draft. It is what one person built, used, and broke on
+purpose. **NOT ESTABLISHED: whether any of it works for more than one person.**
+
+---
+
+## Where to go next
+
+**[`formwork/first-run.md`](formwork/first-run.md)**. It walks you through the
+install, makes you watch a guard refuse something, and has you do one small
+real piece of work. On your own project, not a pretend one. About fifteen
+minutes.
+
+**Then [`FORMWORK.md`](FORMWORK.md)**, the whole method on one page. It reads
+better after you have run it once than before.
+
+---
+
+## Everything else
+
+**While you work**
+
+| | |
+|---|---|
+| [`loop.md`](formwork/loop.md) | how one job goes, start to finish |
+| [`threads.md`](formwork/threads.md) | how work starts, and where the plan lives between conversations |
+| [`style.md`](formwork/style.md) | how the agents talk to you, and how to change it |
+| [`round.md`](formwork/round.md) | how to run a round, and when it is worth it |
+| [`templates/`](formwork/templates/) | brief, predictions, report, decision, round, standing brief |
+| [`roles/`](formwork/roles/) | the roles, and how to write your own |
+| [`rules/`](formwork/rules/) | the rules, each saying what it catches |
+
+**When you need it**
+
+| | |
+|---|---|
+| [`troubleshooting.md`](formwork/troubleshooting.md) | every error message and what to do |
+| [`glossary.md`](formwork/glossary.md) | every word we use, in plain language |
+| [`limits.md`](formwork/limits.md) | what this kit cannot do |
+| [`COSTS.md`](formwork/COSTS.md) | what it costs, and the number nobody has |
+| [`FAQ.md`](FAQ.md) | questions people ask |
+
+**How it was built**
+
+| | |
+|---|---|
+| [`docs/`](docs/) | the survey, the design, and what broke |
+| [`docs/dogfood.md`](docs/dogfood.md) | the kit failing on its own author, written down |
+| [`RELEASING.md`](RELEASING.md) | for the maintainer |
+
+---
+
+## Contributing
+
+Forks are the point. The most useful thing you can send is a command that got
+past a guard, or one that was stopped when it should not have been.
+
+[CONTRIBUTING.md](CONTRIBUTING.md) has the rest, and
+[SECURITY.md](SECURITY.md) is for anything you would rather not post in public.
+
+---
+
+## Licence
+
+MIT. See [LICENSE](LICENSE).