formwork-kit 0.1.0__tar.gz

formwork_kit-0.1.0/.gitignore

@@ -0,0 +1,30 @@
+# macOS
+.DS_Store
+
+# The denylist lives outside this repository and is never committed. A file
+# that cannot be committed cannot be published by accident. These guards are
+# the second line of defence, not the first.
+
+# Python
+__pycache__/
+*.pyc
+
+# Working documents are kept outside this repository.
+#   plan.md       planning history       (K0 decision 9)
+#   inventory.md  the mechanism inventory (K0 decision 10)
+# Both are inputs to K3, K4 and K5, not parts of the kit. These guards stop a
+# copy slipping back in.
+plan.md
+docs/plan.md
+inventory.md
+docs/inventory.md
+
+# The scanners live outside this repository too. They are build-time only:
+# they describe the private material they compare against, and that
+# description is itself a disclosure. Guard, not first line of defence.
+tools/
+
+# Build artefacts. Made by `python3 -m build`, never committed.
+dist/
+build/
+*.egg-info/

formwork_kit-0.1.0/FORMWORK.md

@@ -0,0 +1,182 @@
+# Formwork
+
+A way of running a project with coding agents.
+
+---
+
+## The loop
+
+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 | — |
+
+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.**
+
+---
+
+## What is blocked
+
+These do not ask you. They refuse.
+
+| Rule | Enforced by |
+|---|---|
+| The agent never writes to version control | `formwork/guard/git-boundary` |
+| One command runs every check | `formwork check` |
+| Every check ships with an input that breaks it | `formwork check` |
+| Every rule is labelled, and names a real check | `formwork/check/checks/rule-labels` |
+| Documents link only to files that exist | `formwork/check/checks/doc-links` |
+| 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` |
+
+> [!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`.
+
+Run them:
+
+```
+formwork check              everything, on your project
+formwork demo  watch each check refuse a broken input
+formwork check --list       what exists
+```
+
+**If you did not install the command**, every one of these works by path
+instead: `formwork/fw check`, `formwork/fw demo`, `formwork/fw roles`. Run
+`formwork/fw` on its own to see the list.
+
+---
+
+## What is advice
+
+Everything else. **46 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.
+
+> [!TIP]
+> Every rule says what it catches. None of them tells you a story, because the
+> stories belong to somebody else's project.
+
+---
+
+## Some of this will look like fussiness
+
+Several of these rules were learned from failures you have not had.
+
+Each one states what it catches. **If you never hit that, delete it** from
+`formwork/rules/core.md`, so losing a rule is a line in your version control
+with your name on it.
+
+There is no `[rules]` switch in `.formwork.toml`, and a check refuses one if you
+add it. A rule switched off in a settings file disappears quietly. A rule
+deleted from the rules file does not.
+
+A rule you follow without understanding gets dropped quietly later anyway.
+
+---
+
+## Settings
+
+This is the whole file, and the installer writes it for you:
+
+```toml
+[bindings]
+runtime = "claude-code"          # which tool you use
+
+[strength]
+git_boundary = "block"           # block | warn | off
+protect_files = "block"          # block | warn | off
+```
+
+`[strength]` tunes how hard the enforced guards bite. `[bindings]` is your
+setup. There is no third section: see above.
+
+**Two more keys exist and both live in `[strength]`:**
+
+```toml
+aggregate_gate = "block"   # block | warn | off. The turn-end gate
+gate_budget = 3            # how many times it refuses before standing aside
+```
+
+For one session only:
+
+```
+FORMWORK_GIT_BOUNDARY=off
+FORMWORK_PROTECT_FILES=warn
+FORMWORK_GATE=off
+```
+
+---
+
+## Your team
+
+`formwork/roles/` holds 27 roles. Six 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
+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.
+
+The installer generates them for your runtime. To regenerate after an edit:
+
+```
+formwork roles
+```
+
+---
+
+## What it cannot do
+
+The guards are pattern matching over a command line. They stop the ordinary
+path and not a determined one.
+
+[`formwork/limits.md`](formwork/limits.md) lists exactly what got past an audit, what
+was closed afterwards, and what cannot be closed this way. Read it before
+trusting any of this further than it deserves.
+
+---
+
+## Two things here you will not find elsewhere
+
+**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.
+
+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.
+
+---
+
+## What it costs
+
+Nobody has measured what one round costs in money. Not once. `formwork/COSTS.md`
+says so plainly, gives the part that can be measured for free, and says what
+would establish the rest.
+
+---
+
+## Where to start
+
+[`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.

formwork_kit-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Muhammad Elsherif
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

formwork_kit-0.1.0/PKG-INFO

@@ -0,0 +1,308 @@
+Metadata-Version: 2.5
+Name: formwork-kit
+Version: 0.1.0
+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 --runtime claude-code
+$ formwork check
+GATE: green. 9 check(s), each shown to reject the wrong and accept the right.
+```
+
+---
+
+## 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 seven roles, already written. A lead, a challenger, an architect, 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 write themselves.** Choices get a number and a page, 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.
+
+---
+
+## 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 |
+
+No packages, no setup. The kit is text files and small Python programs.
+
+```
+pipx install formwork-kit
+
+cd /your/project
+formwork init
+formwork install --runtime claude-code
+formwork check
+```
+
+That last line should say green.
+
+`init` puts `formwork/` and `FORMWORK.md` in your project. `install` wires the
+guards into your agent and writes your role files. Type `formwork` on its own
+to see the rest.
+
+> [!TIP]
+> **Use pipx, not pip.** Plain pip works, but often puts the command somewhere
+> your shell does not look, and you get `command not found` with no clue why.
+
+**Or install nothing.** The kit is just files:
+
+```
+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
+formwork/fw check
+```
+
+**What it touches.** It adds `formwork/` and `FORMWORK.md`, writes your agent's
+settings file keeping anything already there, 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 |
+
+---
+
+## 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_` |
+| **9 checks** | small programs that read your project and say green or red | `ls formwork/check/checks \| wc -l` |
+| **27 roles** | one file each, saying what that job does and where it stops | `ls formwork/roles/*/*.md \| wc -l` |
+| **46 rules** | 13 you meet daily, 33 for when you need them | `grep -c '^### ' formwork/rules/*.md` |
+| **295 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`.
+
+---
+
+## Which agents work
+
+| 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 |
+
+> [!NOTE]
+> For the three nobody has tried, `formwork check` stays red until you write
+> the hook file yourself. Your agent's page in `formwork/adapters/` says what
+> goes in it. **Red is the right answer there: nothing is guarding you yet.**
+
+**Those three are the easiest way to help.** Set one up, ask your agent to
+commit something, and tell us what happened. Either answer is useful.
+
+---
+
+## 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 way around them |
+| **Whether three of the four agents work** | nobody has tried them |
+
+> [!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.
+
+---
+
+## Where to start
+
+[`formwork/first-run.md`](formwork/first-run.md). Seven short steps, on your
+own project. No tutorial. No pretend example.
+
+It should take about fifteen minutes. Nobody has timed the part you do, and the
+page says so.
+
+---
+
+## The rest
+
+**Start here**
+
+| | |
+|---|---|
+| [`formwork/first-run.md`](formwork/first-run.md) | seven short steps, on your own project |
+| [`FORMWORK.md`](FORMWORK.md) | the whole method on one page. Read it after your first run |
+
+**While you work**
+
+| | |
+|---|---|
+| [`loop.md`](formwork/loop.md) | how one job goes, start to finish |
+| [`round.md`](formwork/round.md) | how to run a round, and when it is worth it |
+| [`templates/`](formwork/templates/) | brief, predictions, report, decision, round |
+| [`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. What helps most, in order:
+
+- **A command that got past a guard.** One line, no fix needed
+- **A normal command that was wrongly stopped.** Just as useful
+- **A report from an untried agent**, whether it worked or not
+- **A new role** the twenty seven do not cover
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) and [SECURITY.md](SECURITY.md).
+
+---
+
+## Licence
+
+MIT. See [LICENSE](LICENSE).