|
1 | | -# boatstack |
2 | | -Plan the route. Prove the work. Ship. |
| 1 | +<!-- Generated from operatorstack/intelligence-flow. Edit the upstream product-loop source, not this file. --> |
| 2 | + |
| 3 | +# Boatstack |
| 4 | + |
| 5 | +**Plan the route. Prove the work. Ship.** |
| 6 | + |
| 7 | +Boatstack is loop engineering for coding agents: a model-neutral path from a product request to an explicitly approved, tested, reviewed pull request. Its behavior is generated from [Intelligence Flow at `5e1bbedab7d5bae49dd0e5cdda1e4b7804ab057f`](https://github.com/operatorstack/intelligence-flow/tree/5e1bbedab7d5bae49dd0e5cdda1e4b7804ab057f/examples/12-product-engineering-loop). |
| 8 | + |
| 9 | +It is not a claim that a longer prompt writes better code. Here is what the loop actually does. |
| 10 | + |
| 11 | +## One request, as executable state |
| 12 | + |
| 13 | +Start with ordinary product intent: |
| 14 | + |
| 15 | +```text |
| 16 | +Add machine-readable JSON output to the diagram printer while preserving the current text output. |
| 17 | +``` |
| 18 | + |
| 19 | +`/auto-plan` inspects the smallest relevant code boundary and makes contract choices visible: |
| 20 | + |
| 21 | +```text |
| 22 | +Q1 Public API? sibling serializeFlowGraph() | change printFlowGraph() |
| 23 | +Q2 Stability? versioned schema | internal object dump |
| 24 | +Q3 Run data? compact overlay | entire execution trace |
| 25 | +``` |
| 26 | + |
| 27 | +The accepted answers become observable criteria and tasks—not hidden assumptions: |
| 28 | + |
| 29 | +```json |
| 30 | +{ |
| 31 | + "acceptance_criteria": [ |
| 32 | + {"id": "AC-1", "text": "Return parseable schema-versioned graph JSON."}, |
| 33 | + {"id": "AC-4", "text": "Keep existing ASCII output byte-compatible."} |
| 34 | + ], |
| 35 | + "tasks": [{ |
| 36 | + "id": "T-3", |
| 37 | + "acceptance_criteria": ["AC-1", "AC-4"], |
| 38 | + "validation": [ |
| 39 | + "pnpm exec tsx examples/05-diagram-printer/json-check.ts", |
| 40 | + "diff -u expected-output.txt actual-output.txt" |
| 41 | + ] |
| 42 | + }] |
| 43 | +} |
| 44 | +``` |
| 45 | + |
| 46 | +The compiler refuses a criterion with no task or verification. Then `/plan-gate` requires a named human and binds approval to content hashes: |
| 47 | + |
| 48 | +```bash |
| 49 | +python3 boatstack/scripts/compile_plan.py \ |
| 50 | + --plan .product-loop/features/diagram-json/plan.json \ |
| 51 | + --out-dir .product-loop/features/diagram-json/compiled |
| 52 | + |
| 53 | +python3 boatstack/scripts/approve_plan.py \ |
| 54 | + --spec .product-loop/features/diagram-json/spec.md \ |
| 55 | + --plan .product-loop/features/diagram-json/plan.json \ |
| 56 | + --tasks .product-loop/features/diagram-json/compiled/tasks.json \ |
| 57 | + --approved-by "Boateng Opoku-Yeboah" \ |
| 58 | + --output .product-loop/features/diagram-json/plan.lock.json |
| 59 | +``` |
| 60 | + |
| 61 | +Build work checks that lock first: |
| 62 | + |
| 63 | +```console |
| 64 | +$ python3 boatstack/scripts/approve_plan.py ... --check |
| 65 | +PASS: approved plan lock matches the current artifacts |
| 66 | + |
| 67 | +# after plan.json changes |
| 68 | +$ python3 boatstack/scripts/approve_plan.py ... --check |
| 69 | +BLOCKED: stale or invalid plan lock: plan |
| 70 | +``` |
| 71 | + |
| 72 | +That is the approval boundary in code: conversation cannot silently turn a draft into permission to build. |
| 73 | + |
| 74 | +See the complete, linked [worked example](examples/diagram-json/README.md). |
| 75 | + |
| 76 | +## Install into a repository |
| 77 | + |
| 78 | +```bash |
| 79 | +git clone https://github.com/operatorstack/boatstack.git && cd boatstack |
| 80 | +cp project.example.json /path/to/product/.boatstack-project.json |
| 81 | +# Replace the example paths and commands with facts from the product repository. |
| 82 | + |
| 83 | +python3 boatstack/scripts/export_repo.py \ |
| 84 | + --repo /path/to/product \ |
| 85 | + --config /path/to/product/.boatstack-project.json \ |
| 86 | + --adapter-name boatstack |
| 87 | + |
| 88 | +# Review the dry run, then materialize it on a branch. |
| 89 | +python3 boatstack/scripts/export_repo.py \ |
| 90 | + --repo /path/to/product \ |
| 91 | + --config /path/to/product/.boatstack-project.json \ |
| 92 | + --adapter-name boatstack \ |
| 93 | + --write |
| 94 | +``` |
| 95 | + |
| 96 | +The exporter creates one canonical `.product-loop/` runtime and thin adapters for: |
| 97 | + |
| 98 | +```text |
| 99 | +.cursor/commands/{auto-plan,plan-gate,build,test-gate,review,ship,retro}.md |
| 100 | +.cursor/rules/boatstack.mdc |
| 101 | +.agents/skills/boatstack/SKILL.md |
| 102 | +.claude/skills/boatstack/SKILL.md |
| 103 | +.github/PULL_REQUEST_TEMPLATE/boatstack.md |
| 104 | +``` |
| 105 | + |
| 106 | +It refuses to overwrite user-owned host files. Run the same export with `--check` in CI to detect drift. |
| 107 | + |
| 108 | +## Why “loop engineering” |
| 109 | + |
| 110 | +A coding model is one operator inside a controlled path: |
| 111 | + |
| 112 | +```text |
| 113 | +intent -> questions -> spec -> plan -> human approval -> build |
| 114 | + -> test evidence -> review evidence -> PR -> failure analysis |
| 115 | + ^ | |
| 116 | + +--- promoted moves ---+ |
| 117 | +``` |
| 118 | + |
| 119 | +- **Optimization:** select the smallest context and ceremony that preserve the required quality and evidence constraints. |
| 120 | +- **Control:** represent state explicitly, gate transitions, verify outputs, preserve known-good progress, and feed observed failures into separately tested improvements. |
| 121 | +- **Model neutrality:** route on ambiguity, risk, convergence, tool results, and evidence—not model brand, price, or a guessed capability tier. |
| 122 | + |
| 123 | +The full mapping from equations to files and checks is in [Loop engineering](docs/loop-engineering.md). |
| 124 | + |
| 125 | +## Evidence, with boundaries |
| 126 | + |
| 127 | +The rules were informed by a mechanically audited local corpus of **4,016 benchmark trial results** and **3,985 signal streams**, plus two real product-repository studies. For example: |
| 128 | + |
| 129 | +| Observed failure | Encoded move | |
| 130 | +|---|---| |
| 131 | +| Restarting discarded partial progress | Preserve known-good state; repair locally | |
| 132 | +| Structured-output errors hid useful work | Validate and perform bounded same-step repair | |
| 133 | +| Stronger verification wording regressed | Treat self-review as evidence, not the oracle | |
| 134 | +| Blind context trimming lost accuracy | Select relevant context without deleting required state | |
| 135 | +| A development-slice gain did not transfer | Require representative gates before promoting a move | |
| 136 | + |
| 137 | +Read the [research and design record](docs/research-and-design.md) and [corpus audit](docs/benchmark-corpus-audit.md). This evidence motivates the loop; it does not prove that every future feature or model will improve. |
| 138 | + |
| 139 | +## Context has a budget |
| 140 | + |
| 141 | +The three canonical runtime references currently total approximately **3371 estimated tokens** using `ceil(characters / 4)`. That is a stable compactness signal, not provider billing. Host adapters stay thin and load the operation-specific slice on demand. |
| 142 | + |
| 143 | +## Status |
| 144 | + |
| 145 | +Boatstack is an alpha research distribution. It can generate host adapters, compile traceable task/test artifacts, hash-lock explicit approval, detect stale plans, and preserve provenance. The next proof boundary is a paired feature-development evaluation against a plain host harness. |
0 commit comments