flanders 0.7.0 → 0.8.0

package/README.md

@@ -1,6 +1,6 @@
-# Flanders
+# Motivation
 
-Hi-diddly-ho, neighbor! Flanders is a Node.js toolkit that helps you author contracts, derive work plans from them, and implement those plans through a mix of plain code and AI orchestration. It reaches you through two surfaces — a CLI invoked as `npx flanders <command>`, and three AI-tool skills invoked from inside an AI-coding-tool session.
+Hi-diddly-ho, neighbor! I am a Node.js toolkit that helps avoid AI drifting. I was sick of the AI not reading the `CLAUDE.md`, avoiding rules and forgetting what I told it 3 prompts ago. You know that I, Ned Flanders, will never break a rule, so it was natural for me to spawn here at some point. I will help you define a specification, the public contracts and private rules, and then I will orchestrate the AI for you to implement and review anything without breaking the specification. I have no problem hitting the AI with a stick when it drifts.
 
 ## Contents
 
@@ -14,41 +14,49 @@ Hi-diddly-ho, neighbor! Flanders is a Node.js toolkit that helps you author cont
 
 ## How it works
 
-Flanders speaks to you through two surfaces. The **CLI** — invoked as `npx flanders <command>` — carries three commands: `install`, which sets Flanders up in your project or your home directory; `update`, which refreshes the already-installed skills in place; and `implement [plan]`, which builds a plan from start to finish. The three **AI-tool skills** — `/flanders-spec`, `/flanders-plan`, and `/flanders-work` — are invoked from right inside an AI-coding-tool session.
+With Flanders you first define a specification that will be stored in a `.spec` folder alongside where the specification applies. Then Flanders will help you to create a plan divided into tasks, and via CLI you then implement the plan.
 
-Underneath, Flanders keeps a tidy little spec corpus alongside your code, and everything flows from it:
+Flanders will implement one task at a time, and then will launch, in parallel, as many validators as you have configured. If something differs from the specification, they will notify the worker to review the problem and fix it.
 
-- **`.spec/contracts`** holds the public obligations a scope exposes — the promises its surface makes to the outside world.
-- **`.spec/rules`** holds the internal conventions its code follows — the house rules it keeps for itself.
-- **`.spec/flanders`** holds behavior rules — the obligations that govern how Flanders' own commands and skills behave while they work in your project.
-
-Ordered work plans then live under **`plans/`**: each plan is a sequence of tasks derived from the contracts and rules, ready to be built one at a time.
+I'm not gonna lie, it is token hungry, but that's what you get when you want to reduce specification drifting. The AI has to iterate and validate multiple times what it is doing to avoid the typical "Ah, you are right! You already told me that". Still, Flanders has rate limit detection and retries, so you can let an implementation run overnight while you sleep, without worrying about the limits.
 
 The whole neighborly cycle runs **spec → plan → implement**:
 
-1. Capture obligations and conventions as contracts, rules, and behavior rules in the spec corpus (with `/flanders-spec`).
+1. Capture obligations and conventions as contracts and rules in the spec corpus (with `/flanders-spec`).
 2. Derive an ordered work plan from them under `plans/` (with `/flanders-plan`).
-3. Implement the plan task by task, gating each result through build, test, and adversarial review (with `npx flanders implement`).
+3. Implement the plan task by task, gating each result through build, test, and adversarial review (with `flanders implement`).
 
 For a small, self-contained change that doesn't need a whole plan, there's a friendly shortcut: **`/flanders-work`** implements the request directly and gates it through the same build, test, and adversarial review, all in one invocation.
 
+Underneath, Flanders keeps a tidy little spec corpus alongside your code, and everything flows from it:
+
+- **`.spec/contracts`** holds the public obligations a scope exposes — the promises its surface makes to the outside world.
+- **`.spec/rules`** holds the internal conventions its code follows — the house rules it keeps for itself.
+- **`.spec/flanders`** holds behavior rules — the obligations that govern how Flanders' own commands and skills behave while they work in your project.
+
 ## Requirements
 
 A few neighborly things to have on hand before you start:
 
-- **Node.js** — the CLI is run with `npx`.
+- **Node.js**.
 - **A git repository** — the `implement` command requires the project to be a git repository.
-- **A supported AI coding tool** — currently Claude Code or Codex CLI.
+- **A supported CLI AI coding tool** — currently Claude Code or Codex.
 
 ## Installation
 
 Setting Flanders up is a breeze, neighbor — just run:
 
 ```sh
-npx flanders install
+npm install flanders -g
+```
+
+and then:
+
+```sh
+flanders install
 ```
 
-This is how Flanders first sets up on disk: it is the only command that writes the persistent `.flanders/` configuration that `implement` reads, and the way you publish the skills to a fresh scope. Once the skills are in place, `npx flanders update` refreshes them where they already live (see [Updating](#updating)).
+This is how Flanders first sets up on disk: it is the only command that writes the persistent `.flanders/` configuration that `implement` reads, and the way you publish the skills to a fresh scope.
 
 ### Scope
 
@@ -57,8 +65,6 @@ Flanders installs at one of two scopes, chosen with a pair of mutually exclusive
 - `--project` — the scope is the current working directory. Skills go into the project's AI-tool skill folders, and the `.flanders/` configuration is written at the project root.
 - `--global` — the scope is your home directory. Skills go into the user-level AI-tool skill folders, and the `.flanders/` configuration is written at your home directory.
 
-Passing both at once is a usage error. When you supply neither, the command kindly prompts you to pick one.
-
 ### What it writes
 
 For each AI tool you select for skills, `install` writes one skill artifact per Flanders skill (`/flanders-spec`, `/flanders-plan`, and `/flanders-work`) into that tool's skill folder for the chosen scope:
@@ -77,12 +83,10 @@ Run it without flags and Flanders walks you through the setup, asking in this or
 1. **Skills tool** — `claude`, `codex`, or `both`.
 2. **Scope** — `--project` or `--global`, each option labelled with the concrete destination path(s) for the skills tool you picked.
 3. **Worker tool, model, and effort** — the AI the `implement` command's worker uses.
-4. **Reviewer configuration** — an ordered list of one or more adversarial reviewers, each with its own tool, model, and effort.
-5. **Weighted-review configuration** — when two or more reviewers are configured, the minimum number of reviewers that must run to a verdict, and which reviewers are optional.
-
-Any question whose answer you supply by flag is not prompted again.
+4. **Reviewer configuration** — an ordered list of one or more adversarial reviewers, each with its own tool, model, and effort. You can have any number of reviewers, for example Claude Opus, Claude Sonnet and Codex. You can even duplicate them if you think that one pass is not enough to detect a problem.
+5. **Weighted-review configuration** — when two or more reviewers are configured, the minimum number of reviewers that must run to a verdict, and which reviewers are optional. Optional reviewers will not halt the implementation when they reach a rate limit.
 
-And if a `.flanders/` configuration already lives at the scope you choose, neighbor, `install` reads it the moment you pick that scope and pre-selects your stored answers as the question defaults — the worker's tool, model, and effort; the reviewer list, including how many reviewers there are and, for each one, its tool, model, effort, and whether it's optional; and the minimum number of reviewers that must run. Press Enter straight through and, but for one edge case, you reproduce your saved configuration just as it was. That edge case is a stored Codex model the probe no longer offers: with it no longer on the menu, that one question is shown with no pre-selected default and you answer it afresh. The skills tool and the scope aren't kept in that file, so they're always asked fresh too, and any flag you pass still wins over a pre-selected default. When no configuration lives at that scope yet — or the file can't be read — Flanders gently falls back to its fresh-install defaults and pre-selects nothing.
+And if a `.flanders/` configuration already lives at the scope you choose, neighbor, `install` reads it the moment you pick that scope and pre-selects your stored answers as the question defaults. Just press Enter straight through to reproduce your saved configuration just as it was.
 
 ### Flags
 
@@ -121,18 +125,14 @@ Existing files at the destination — both skill artifacts and `.flanders/` conf
 
 ## Updating
 
-Already set up and itching for the freshest skills, neighbor? Just run:
+Updated the lib and itching for the freshest skills, neighbor? Just run:
 
 ```sh
-npx flanders update
+flanders update
 ```
 
 `update` takes no flags. It scans the four skill destinations `install` writes to — Claude Code and Codex CLI, each at project and global scope — and wherever it finds at least one Flanders skill artifact already in place, it rewrites the full `/flanders-spec`, `/flanders-plan`, and `/flanders-work` trio there with the current version. A destination where no Flanders skill artifact is present is left untouched, so `update` refreshes the installations you already have and never creates one where you had none.
 
-It is entirely hands-off: `update` asks you nothing, and it never reads or writes your `.flanders/` configuration — the worker and reviewer answers a previous `install` saved carry over exactly as they were. Existing skill files are overwritten silently, the same way `install` overwrites them. On success it prints every file it wrote, one path per line.
-
-If no Flanders skills are installed at any scope or tool, `update` has nothing to refresh: it exits with an error that points you to `npx flanders install` to set one up first.
-
 ## Configuration
 
 The `install` command tucks your answers into a `.flanders/` folder so the command that consumes them — `implement` — knows just how you like things done. (`update` leaves this configuration untouched; it only refreshes the skills.) Where that folder lives depends on the scope you chose:
@@ -140,16 +140,6 @@ The `install` command tucks your answers into a `.flanders/` folder so the comma
 - **Project scope** — `.flanders/` at the project root.
 - **Global scope** — `~/.flanders/` in your home directory.
 
-It persists exactly the answers downstream commands need at run time:
-
-- The **worker** the `implement` command uses: its tool (`claude` or `codex`), its model, and its reasoning effort.
-- The **ordered list of adversarial reviewers**, in the order you configured them. Each reviewer carries its own tool (`claude` or `codex`), model, and effort, plus whether it is optional.
-- The **minimum number of reviewers** that must run to a verdict in each review round.
-
-For any model or effort you leave unset — the worker's or a reviewer's — Flanders doesn't record a concrete value; instead it persists the explicit marker `default configured model` or `default configured effort`, which tells the tool to fall back to its own default at run time.
-
-The skills-tool answer is used by `install` itself to decide which folders to write into, so it isn't persisted here.
-
 ### Which configuration wins
 
 When a command reads the configuration, a project-scope `.flanders/` always takes precedence over a global one — and it's all or nothing, with no field-by-field merge between the two. So a project `.flanders/` is used in full when it's present; otherwise the global `~/.flanders/` is used.
@@ -158,20 +148,10 @@ When a command reads the configuration, a project-scope `.flanders/` always take
 
 With Flanders installed, here's how to put it to work — running plans from the CLI and shaping them with the three skills.
 
-### Implementing a plan
-
-```sh
-npx flanders implement [plan]
-```
-
-`implement` takes a plan from your `plans/` folder and carries it through from start to finish. Leave `[plan]` off and Flanders runs the single plan in `plans/` for you automatically; when there's more than one, it lists them and asks you to re-run naming the one to implement. From there it works through each open task with the worker AI, gating every result through build, test, and adversarial review before marking that task complete in the plan — and it commits once per accepted task, so each step lands as its own neat little commit. The whole run is non-interactive: once started, it never stops to ask you anything, and it caps each task at five attempts before halting. The project must be a git repository: `implement` needs git and has no flag to turn it off.
-
 ### The three skills
 
-The skills become available after a successful `npx flanders install` run, and each is invoked from inside your AI-coding-tool session. Each one shapes a different part of the spec → plan → implement cycle:
-
 - **`/flanders-spec`** — turns a free-form request into your contracts, rules, and behavior rules, written into the `.spec/contracts`, `.spec/rules`, and `.spec/flanders` folders.
-- **`/flanders-plan`** — derives a single, ordered, contract-aware work plan under `plans/` from your request.
+- **`/flanders-plan`** — derives a single, ordered, specification-aware work plan from your request.
 - **`/flanders-work`** — implements a small, self-contained request directly and gates it through build, test, and a single adversarial review, all in one invocation — no plan file and no commit.
 
 Each skill takes the same optional `<data>` argument:
@@ -186,14 +166,24 @@ Each skill takes the same optional `<data>` argument:
 - Give it a path to an existing file, and the skill reads that file as the input.
 - Give it any other text, and the skill uses that text verbatim.
 
+### Implementing a plan
+
+```sh
+flanders implement [plan]
+```
+
+`implement` takes a plan from your `plans/` folder and carries it through from start to finish. Leave `[plan]` off and Flanders runs the single plan in `plans/` for you automatically. From there it works through each open task with the worker AI, gating every result through build, test, and adversarial review before marking that task complete in the plan — and it commits once per accepted task, so each step lands as its own neat little commit. The whole run is non-interactive: once started, it never stops to ask you anything, and it caps each task at five attempts before halting. The project must be a git repository: `implement` needs git and has no flag to turn it off.
+
+When the plan implementation is finished, you can squash all the plan commits. They are ordered by task for easier identification.
+
 ### A typical workflow
 
 Here's the neighborly path from a blank slate to shipped code:
 
-1. **`npx flanders install`** — set Flanders up and deliver the skills.
+1. **`flanders install`** — set Flanders up and deliver the skills.
 2. **`/flanders-spec`** — capture your obligations and conventions as contracts, rules, and behavior rules.
 3. **`/flanders-plan`** — derive an ordered work plan from them under `plans/`.
-4. **`npx flanders implement`** — build the plan task by task, each result gated through build, test, and review.
+4. **`flanders implement`** — build the plan task by task, each result gated through build, test, and review.
 
 And when a change is small enough that a whole plan would be overkill, **`/flanders-work`** is your shortcut — it carries that one request from request to reviewed finish without a plan or a commit.
 
@@ -203,43 +193,49 @@ Let's build a tiny web calculator that only multiplies and subtracts, neighbor
 
 1. **Set Flanders up** in your project and deliver the skills:
 
-   ```sh
-   npx flanders install
-   ```
+```sh
+flanders install
+```
 
 2. **Capture the spec** with `/flanders-spec`. You describe what you want; the skill sorts each obligation into the right folder — public behavior into `.spec/contracts`, internal conventions into `.spec/rules`:
 
-   ```
-   /flanders-spec A web calculator with exactly two operations — multiply and
-   subtract — over two number inputs, showing the result. The operation buttons
-   are teal, the result panel is white, and the page background is slate. Build
-   the UI with React bundled by Vite, and use no other UI framework.
-   ```
+```
+/flanders-spec A web calculator with exactly two operations — multiply and subtract — over two number inputs, showing the result. The operation buttons are teal, the result panel is white, and the page background is slate. Build the UI with React bundled by Vite, and use no other UI framework.
+```
 
-   From that one request it writes, for example:
+From that one request it writes, for example:
 
-   - a **functionality contract** under `.spec/contracts/` — the calculator offers exactly two operations, multiply and subtract, over two numeric inputs, and shows the result;
-   - a **colors contract** under `.spec/contracts/` — the operation buttons are teal, the result panel white, and the background slate;
-   - a **frameworks rule** under `.spec/rules/` — the UI is built with React bundled by Vite, and no other UI framework is introduced.
+- a **functionality contract** under `.spec/contracts/` — the calculator offers exactly two operations, multiply and subtract, over two numeric inputs, and shows the result;
+- a **colors contract** under `.spec/contracts/` — the operation buttons are teal, the result panel white, and the background slate;
+- a **frameworks rule** under `.spec/rules/` — the UI is built with React bundled by Vite, and no other UI framework is introduced.
 
-   The skill shows you the planned layout first and writes the files once you approve.
+The skill shows you the planned layout first and writes the files once you approve.
 
-3. **Derive the plan** with `/flanders-plan` — one ordered, contract-aware plan under `plans/`, each task linked back to the contracts and rules it satisfies:
+3. **Derive the plan** with `/flanders-plan` — one ordered, specification-aware plan under `plans/`, each task linked back to the contracts and rules it satisfies:
 
-   ```
-   /flanders-plan
-   ```
+```
+/flanders-plan
+```
 
 4. **Build it** with `implement` — Flanders works each task with the worker AI, gates every result through build, test, and adversarial review, and lands one commit per accepted task:
 
-   ```sh
-   npx flanders implement
-   ```
+```sh
+flanders implement
+```
 
-   When it finishes, the contracts are honored by code: a calculator that multiplies and subtracts and nothing else, in teal, white, and slate, built on the framework your rule pinned.
+When it finishes, the contracts are honored by code: a calculator that multiplies and subtracts and nothing else, in teal, white, and slate, built on the framework your rule pinned.
 
 5. **Tweak it later** with the shortcut — a small change that doesn't need a whole plan:
 
-   ```
-   /flanders-work make the result panel use a larger font
-   ```
+```
+/flanders-work make the result panel use a larger font
+```
+
+If you really want the font to be kept at that size, just save the spec, and no future work will ever break that specification:
+
+```
+/flanders-spec make the result panel use a larger font
+```
+```
+/flanders-work
+```

package/lib/cli.js

@@ -235,7 +235,7 @@ const ask = (() => {
             const o = q.options[i];
             const marker = pickedLabels.has(o.label) ? "*" : " ";
             const isDefault = q.defaultIndex === i;
-            out.write(`  ${marker} ${i + 1}) ${o.label}${o.description ? ` — ${o.description}` : ""}${isDefault ? " (default — press Enter)" : ""}\n`);
+            out.write(`  ${marker} ${i + 1}) ${o.label}${o.description ? ` — ${o.description}` : ""}${isDefault ? " (configured — press Enter)" : ""}\n`);
         }
         if (existing) {
             const labels = existing.picked.map(p => p.label).join(", ");
@@ -260,7 +260,7 @@ const ask = (() => {
                     ? `[1-${q.options.length}, comma-separated; free-text OK]`
                     : `[1-${q.options.length}; free-text OK]`);
                 if (q.defaultIndex !== undefined) {
-                    hints.push("Enter for default");
+                    hints.push("Enter for configured");
                 }
                 if (idx > 0) {
                     hints.push("'-' back");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "flanders",
-  "version": "0.7.0",
+  "version": "0.8.0",
   "description": "Flanders never breaks a rule",
   "main": "lib/",
   "types": "lib/types",