flanders 0.6.1 → 0.8.0

package/README.md

@@ -0,0 +1,241 @@
+# Motivation
+
+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
+
+- [How it works](#how-it-works)
+- [Requirements](#requirements)
+- [Installation](#installation)
+- [Updating](#updating)
+- [Configuration](#configuration)
+- [Usage](#usage)
+- [A worked example](#a-worked-example)
+
+## How it works
+
+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.
+
+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.
+
+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 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 `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**.
+- **A git repository** — the `implement` command requires the project to be a git repository.
+- **A supported CLI AI coding tool** — currently Claude Code or Codex.
+
+## Installation
+
+Setting Flanders up is a breeze, neighbor — just run:
+
+```sh
+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.
+
+### Scope
+
+Flanders installs at one of two scopes, chosen with a pair of mutually exclusive flags:
+
+- `--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.
+
+### 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:
+
+| Tool | Project scope | Global scope |
+| --- | --- | --- |
+| Claude Code | `.claude/skills/` | `~/.claude/skills/` |
+| Codex CLI | `.codex/prompts/` | `~/.codex/prompts/` |
+
+Select `both` and the artifacts are written for both tools, each into its own folder. Alongside the skills, the command writes the `.flanders/` configuration at the chosen scope (see [Configuration](#configuration)).
+
+### Interactive prompts
+
+Run it without flags and Flanders walks you through the setup, asking in this order:
+
+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. 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. Just press Enter straight through to reproduce your saved configuration just as it was.
+
+### Flags
+
+Every question has an equivalent command-line flag, so the whole setup can run without a single prompt:
+
+**Scope** (mutually exclusive)
+
+- `--project` — install into the current working directory.
+- `--global` — install into your home directory.
+
+**Skills and worker**
+
+- `--skills-tool=<claude|codex|both>` — which AI tool(s) the skills are installed for.
+- `--worker-tool=<claude|codex>` — which AI tool the `implement` worker uses.
+- `--worker-model=<value>` — model the worker tool invokes; an empty value means "use the tool's default configured model".
+- `--worker-effort=<value>` — reasoning effort the worker tool invokes; an empty value means "use the tool's default configured effort".
+
+**Reviewers** — an ordered list, where reviewer 1 uses the unindexed names and reviewer `N` (2 or greater) carries the index:
+
+- `--reviewer-tool=<claude|codex>` / `--reviewer-N-tool=<claude|codex>`
+- `--reviewer-model=<value>` / `--reviewer-N-model=<value>`
+- `--reviewer-effort=<value>` / `--reviewer-N-effort=<value>`
+
+The reviewer indices must form a contiguous run starting at reviewer 1. Supplying any reviewer flag fixes the reviewer list to those indices and skips the "configure another reviewer?" prompt.
+
+**Weighted review** — only meaningful with two or more reviewers:
+
+- `--reviewer-optional` / `--reviewer-N-optional` — a presence flag that marks that reviewer optional; a reviewer with no such flag is required.
+- `--reviewer-minimum=<value>` — the minimum number of reviewers that must run to a verdict each round, an integer between `1` and the number of configured reviewers.
+
+A tool flag, or the `codex` effort flag, rejects a value outside its accepted set; model flags and the `claude` effort flag accept any value verbatim. Supplying a weighted-review flag with a single reviewer — or a `--reviewer-minimum` equal to the reviewer count together with any optional flag — is a usage error.
+
+### Overwriting and output
+
+Existing files at the destination — both skill artifacts and `.flanders/` configuration files — are overwritten silently, with no backup and no prompt, so preserving prior versions is up to your own version control. On success, the command prints the full list of files it wrote, one path per line.
+
+## Updating
+
+Updated the lib and itching for the freshest skills, neighbor? Just run:
+
+```sh
+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.
+
+## 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:
+
+- **Project scope** — `.flanders/` at the project root.
+- **Global scope** — `~/.flanders/` in your home directory.
+
+### 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.
+
+## Usage
+
+With Flanders installed, here's how to put it to work — running plans from the CLI and shaping them with the three skills.
+
+### The three skills
+
+- **`/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, 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:
+
+```
+/flanders-spec [<data>]
+/flanders-plan [<data>]
+/flanders-work [<data>]
+```
+
+- Omit it, and the skill takes your request straight from the conversation.
+- 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. **`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. **`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.
+
+## A worked example
+
+Let's build a tiny web calculator that only multiplies and subtracts, neighbor — start to finish, the whole spec → plan → implement stroll.
+
+1. **Set Flanders up** in your project and deliver the skills:
+
+```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.
+```
+
+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.
+
+The skill shows you the planned layout first and writes the files once you approve.
+
+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
+```
+
+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
+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.
+
+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
+```
+
+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/Flanders.d.ts

@@ -1,7 +1,8 @@
 import { ImplementContexts } from "./commands/Implement";
 import { InstallContexts } from "./commands/Install";
+import { UpdateContexts } from "./commands/Update";
 import type { AskContext, OutputContext } from "./contexts";
-export type FlandersContexts = ImplementContexts & InstallContexts & Readonly<{
+export type FlandersContexts = ImplementContexts & InstallContexts & UpdateContexts & Readonly<{
     output: OutputContext;
     ask: AskContext;
 }>;

package/lib/Flanders.js

@@ -3,8 +3,10 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.Flanders = void 0;
 const Implement_1 = require("./commands/Implement");
 const Install_1 = require("./commands/Install");
+const Update_1 = require("./commands/Update");
 const USAGE = `usage: flanders <command> [arguments...]
   install [--global | --project]    install Claude Code skills
+  update                            refresh installed skills in place
   implement [plan]                  run the iterative implementation loop`;
 class Flanders {
     constructor(args, _options, _contexts) {
@@ -26,6 +28,11 @@ class Flanders {
                 this._command = cmd;
                 return await cmd.result();
             }
+            case "update": {
+                const cmd = new Update_1.Update(rest, { projectRoot: this._options.projectRoot }, this._contexts);
+                this._command = cmd;
+                return await cmd.result();
+            }
             case "implement": {
                 const cmd = new Implement_1.Implement(rest, { projectRoot: this._options.projectRoot }, this._contexts);
                 this._command = cmd;

package/lib/cli.js

@@ -234,7 +234,8 @@ const ask = (() => {
         for (let i = 0; i < q.options.length; i++) {
             const o = q.options[i];
             const marker = pickedLabels.has(o.label) ? "*" : " ";
-            out.write(`  ${marker} ${i + 1}) ${o.label}${o.description ? ` — ${o.description}` : ""}\n`);
+            const isDefault = q.defaultIndex === i;
+            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(", ");
@@ -258,6 +259,9 @@ const ask = (() => {
                 hints.push(q.multiSelect
                     ? `[1-${q.options.length}, comma-separated; free-text OK]`
                     : `[1-${q.options.length}; free-text OK]`);
+                if (q.defaultIndex !== undefined) {
+                    hints.push("Enter for configured");
+                }
                 if (idx > 0) {
                     hints.push("'-' back");
                 }
@@ -288,6 +292,11 @@ const ask = (() => {
                     }
                     continue;
                 }
+                if (raw === "" && q.defaultIndex !== undefined) {
+                    answers[idx] = { picked: [q.options[q.defaultIndex]] };
+                    idx++;
+                    continue;
+                }
                 const parsed = parseAnswer(raw, q.options.length, q.multiSelect);
                 if (!parsed) {
                     out.writeError("Invalid input. Pick a valid option number, type free-form text, or use '-' / '+' to navigate.\n");

package/lib/commands/Implement.d.ts

@@ -55,10 +55,12 @@ export declare class Implement {
     private _gitOutputContext;
     private _runTask;
     private _workerStage;
-    private _appendLinkedContent;
+    private _buildSpecContent;
     private _buildStage;
     private _testStage;
     private _setReviewerState;
+    private _setReviewerWaiting;
+    private _writeReviewerEntry;
     private _renderReviewingFooter;
     private _setReviewerLogicalStatus;
     private _evaluateReviewRoundCompletion;

package/lib/commands/Implement.js

@@ -13,6 +13,7 @@ const prompts_1 = require("../prompts/prompts");
 const ScriptRunner_1 = require("../system/ScriptRunner");
 const BottomBlock_1 = require("../ui/BottomBlock");
 const formatters_1 = require("../ui/formatters");
+const voiceVariants_1 = require("../voiceVariants");
 const Workspace_1 = require("../workspace/Workspace");
 const MAX_ITER = 5;
 class LineBufferedBlock {
@@ -86,7 +87,7 @@ class Implement {
             write: text => this._contexts.output.write(text),
             columns: () => this._contexts.output.columns(),
             onResize: listener => this._contexts.output.onResize(listener)
-        }, this._contexts.time);
+        }, this._contexts.time, this._contexts.random);
         this._block = block;
         block.mount();
         this._buffered = new LineBufferedBlock(block);
@@ -141,7 +142,7 @@ class Implement {
             if (initialParse.tasks.every(t => t.done)) {
                 this._block.setHeader({ indexLabel: `${totalTasks}/${totalTasks}` });
                 this._block.setMetrics({ plan: { tokens: planTotals.it + planTotals.ot, seconds: planTotals.t } });
-                this._buffered.write("tasks completed\n");
+                this._buffered.write(`${(0, voiceVariants_1.pickVariant)(voiceVariants_1.tasksCompletedPool, this._contexts.random)}\n`);
                 this._finalizeBlock("Done");
                 return 0;
             }
@@ -193,7 +194,7 @@ class Implement {
                     return 1;
                 }
             }
-            this._buffered.write("all tasks completed\n");
+            this._buffered.write(`${(0, voiceVariants_1.pickVariant)(voiceVariants_1.allTasksCompletedPool, this._contexts.random)}\n`);
             this._finalizeBlock("Done");
             return 0;
         }
@@ -371,7 +372,7 @@ class Implement {
             taskText = "(The full task text and the contracts and rules it references were provided when this session began and remain available to you through session continuity; they are not repeated here.)";
         }
         else {
-            taskText = `(Your previous session for this task could not be resumed, so this is a fresh invocation. You are continuing work on the task at line ${task.line} of the plan file, titled "${task.title}". Re-read that task and the contracts and rules it references directly from the files on disk — they are not re-injected here — and address the previous-iteration briefing below.)`;
+            taskText = `(Your previous session for this task could not be resumed, so this is a fresh invocation. You are continuing work on the task at line ${task.line} of the plan file, titled "${task.title}". The task text and its referenced content are not re-injected here: re-read that task from the plan file, and for the contracts and rules it references reread the consolidated spec.md the orchestrator left in the temporary folder at ${ws.specFile} — read that single file rather than reopening each referenced file — then address the previous-iteration briefing below.)`;
         }
         let prompt = prompts_1.prompts.worker
             .split("<PLAN_PATH>").join(plan.path)
@@ -389,7 +390,8 @@ class Implement {
         }
         try {
             if (iteration === 1) {
-                prompt = await this._appendLinkedContent(plan, task, prompt);
+                await this._contexts.fs.writeFile(ws.specFile, await this._buildSpecContent(plan, task));
+                prompt = `${prompt}\n\n${(0, prompts_1.linkedReferenceDirective)(ws.specFile)}`;
             }
             const { result, capturedOutput } = iteration === 1
                 ? await this._runAi(this._config.worker.tool, this._config.worker.model, this._config.worker.effort, prompt)
@@ -411,19 +413,15 @@ class Implement {
             return false;
         }
     }
-    async _appendLinkedContent(plan, task, prompt) {
-        const linked = plan.linkedPaths(task);
-        const allPaths = [...linked.contracts, ...linked.rules];
-        if (allPaths.length === 0) {
-            return prompt;
-        }
-        const sections = [];
-        for (const relPath of allPaths) {
-            const absPath = (0, fsUtils_1.joinPath)(this._options.projectRoot, relPath);
-            const content = await this._contexts.fs.readFile(absPath);
-            sections.push(`## ${relPath}\n\n${content}`);
+    async _buildSpecContent(plan, task) {
+        const references = plan.linkedReferences(task);
+        const fileContents = new Map();
+        for (const { path } of references) {
+            if (!fileContents.has(path)) {
+                fileContents.set(path, await this._contexts.fs.readFile((0, fsUtils_1.joinPath)(this._options.projectRoot, path)));
+            }
         }
-        return `${prompt}\n\n## Linked reference content\n\nThe full content of every contract and rule this task references is included below, so you do not need to open these files for this iteration:\n\n${sections.join("\n\n")}`;
+        return (0, PlanFile_1.buildSpecFileContent)(references, fileContents);
     }
     async _buildStage(plan, taskLine, ws, iteration) {
         if (!(await (0, fsUtils_1.isNonEmptyFile)(this._contexts.fs, ws.buildScript))) {
@@ -460,12 +458,22 @@ class Implement {
         return true;
     }
     _setReviewerState(reviewerIdx, state) {
+        this._writeReviewerEntry(reviewerIdx, state, undefined);
+    }
+    _setReviewerWaiting(reviewerIdx, endTimeMs) {
+        this._writeReviewerEntry(reviewerIdx, "waiting", endTimeMs);
+    }
+    _writeReviewerEntry(reviewerIdx, state, endTime) {
         if (!this._reviewerStates)
             return;
         const entry = this._reviewerStates[reviewerIdx];
         if (!entry)
             return;
-        this._reviewerStates[reviewerIdx] = { tool: entry.tool, model: entry.model, effort: entry.effort, state };
+        const next = { tool: entry.tool, model: entry.model, effort: entry.effort, state };
+        if (endTime !== undefined) {
+            next.endTime = endTime;
+        }
+        this._reviewerStates[reviewerIdx] = next;
         this._renderReviewingFooter();
     }
     _renderReviewingFooter() {
@@ -551,8 +559,9 @@ class Implement {
             .split("<CONTRACT_LIST>").join(this._formatPathList(this._contractList))
             .split("<RULE_LIST>").join(this._formatPathList(this._ruleList))
             .split("<BEHAVIOR_RULE_LIST>").join(this._formatPathList(this._behaviorRuleList))
-            .split("<ERROR_LOG_PATH>").join(ws.reviewerErrorLog(reviewerNum));
-        prompt = await this._appendLinkedContent(plan, task, prompt);
+            .split("<ERROR_LOG_PATH>").join(ws.reviewerErrorLog(reviewerNum))
+            .split("<SPEC_PATH>").join(ws.reviewerSpecFile(reviewerNum));
+        await this._contexts.fs.writeFile(ws.reviewerSpecFile(reviewerNum), await this._buildSpecContent(plan, task));
         const controller = new AbortController();
         this._reviewerAbortControllers.set(idx, controller);
         try {
@@ -570,10 +579,10 @@ class Implement {
                     void currentSession.dispose();
                 };
                 const callbacks = {
-                    onLongWaitStart: () => {
+                    onLongWaitStart: (_kind, endTimeMs) => {
                         if (this._disposed)
                             return;
-                        this._setReviewerState(idx, "waiting");
+                        this._setReviewerWaiting(idx, endTimeMs);
                         this._setReviewerLogicalStatus(idx, "waiting");
                     },
                     onLongWaitEnd: () => {
@@ -614,7 +623,7 @@ class Implement {
                     continue;
                 }
                 const trimmed = (await this._workspace.readReviewerErrorLog(reviewerNum)).trim();
-                this._setReviewerState(idx, trimmed.length === 0 ? "ok" : "fail");
+                this._setReviewerState(idx, trimmed.length === 0 ? "pass" : "fail");
                 this._setReviewerLogicalStatus(idx, "done");
                 const verdictLine = trimmed.length === 0
                     ? "Verdict: PASS"

package/lib/commands/Install.d.ts

@@ -10,7 +10,6 @@ export type InstallContexts = Readonly<{
 export type InstallOptions = Readonly<{
     projectRoot: string;
 }>;
-export declare function stripYamlFrontmatter(body: string): string;
 type ReviewerFlagAnswers = Readonly<{
     tool?: "claude" | "codex";
     model?: string;