Skip to content

Sync Boatstack from Intelligence Flow 29f36332e8e2 #6

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
github-actions wants to merge 1 commit into from
Closed

Sync Boatstack from Intelligence Flow 29f36332e8e2 #6

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion CONTRIBUTING.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@

# Contributing

Boatstack is a generated content distribution. Propose changes to workflow semantics, templates, evidence rules, or generated presentation in [Intelligence Flow](https://github.com/operatorstack/intelligence-flow/tree/3cd11c293b3903aeac9ff8d8eacd47840d63a02d/examples/12-product-engineering-loop).
Boatstack is a generated content distribution. Propose changes to workflow semantics, templates, evidence rules, or generated presentation in [Intelligence Flow](https://github.com/operatorstack/intelligence-flow/tree/29f36332e8e249528c6b088473d65e1190ff00b8/examples/12-product-engineering-loop).

The Boatstack repository receives product/runtime changes through a generated pull request. Review the PR's `UPSTREAM.json`, tests, adapter diff, and context-size change; do not hand-edit generated output on `main`. `.github/workflows` is the exception: it is Boatstack's executable control plane, excluded from scheduled projection and changed only through a separate manually reviewed Boatstack PR.

Expand Down
62 changes: 40 additions & 22 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,15 +1,49 @@
<!-- Generated from operatorstack/intelligence-flow. Edit the upstream product-loop source, not this file. -->

# Boatstack
<p align="center">
<img src="assets/boatstack-mark.svg" width="96" height="96" alt="Boatstack stacked-node B mark">
</p>

**Build freely. Prove it. Ship.**
<h1 align="center">Boatstack</h1>

Boatstack is **evidence-engineered coding**: a model-neutral coding node that turns product intent and repository context into an explicitly approved, tested, reviewable change. It does not prescribe the model, implementation technique, tools, or document structure. It governs what may be claimed, approved, or shipped. Its behavior is generated from [Intelligence Flow at `3cd11c293b3903aeac9ff8d8eacd47840d63a02d`](https://github.com/operatorstack/intelligence-flow/tree/3cd11c293b3903aeac9ff8d8eacd47840d63a02d/examples/12-product-engineering-loop).
<p align="center"><strong>Build freely. Prove it. Ship.</strong></p>

Boatstack is **evidence-engineered coding**: a model-neutral coding node that turns product intent and repository context into an explicitly approved, tested, reviewable change. It does not prescribe the model, implementation technique, tools, or document structure. It governs what may be claimed, approved, or shipped. Its behavior is generated from [Intelligence Flow at `29f36332e8e249528c6b088473d65e1190ff00b8`](https://github.com/operatorstack/intelligence-flow/tree/29f36332e8e249528c6b088473d65e1190ff00b8/examples/12-product-engineering-loop).

> **You are free in how you build. Only claims of completion require evidence.**

It is not a claim that a longer prompt writes better code. Here is what the node actually makes observable.

## Install in a repository

Install Boatstack on a clean infrastructure branch and merge that PR before starting product work. This keeps the one-time host adapters and repository policy separate from every feature diff.

macOS or Linux:

```bash
git switch -c chore/install-boatstack
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/operatorstack/boatstack/main/install.sh)"
```

Windows PowerShell:

```powershell
git switch -c chore/install-boatstack
irm https://raw.githubusercontent.com/operatorstack/boatstack/main/install.ps1 | iex
```

The installer previews the generated paths, verifies the platform helper, asks about optional gstack and Spec Kit integrations, runs a smoke check, and prints the exact infrastructure commit commands. Boatstack core requires no Python, Node, Go, or package manager. The helper is repository-local and ignored; the adapters and policy are committed.

**New here?** [Install and ship your first feature](docs/getting-started.md) · [Understand generated files](docs/generated-files.md) · [Troubleshoot](docs/troubleshooting.md) · [See the real account-recovery walkthrough](docs/account-recovery-walkthrough.md)

**Go deeper:** [Validation and evidence](docs/validation-and-evidence.md) · [gstack and Spec Kit](#use-boatstack-with-gstack-and-github-spec-kit) · [Evidence-engineered coding](docs/evidence-engineered-coding.md)

```text
idea -> Plan mode -> /auto-plan -> questions -> /plan-gate
-> approve -> Build -> /build -> /test-gate
-> /review-gate -> /ship-gate -> PR
```

## Plan first, then auto-plan

Start with ordinary product intent **inside Cursor, Codex, or Claude Plan mode**:
Expand Down Expand Up @@ -102,6 +136,8 @@ Choose the host's normal Build action.

`/plan-gate` presents a fingerprint over the complete source plan, spec, and `plan.md` and requires a named human. Explicit approval creates only `approval.md`, so the developer remains in Plan mode. The host's normal Build transition then validates and activates the exact approved plan before editing code.

The source plan remains required and hash-checked through `/build`; later gates rely on the resulting lock, actual diff, and accumulated evidence.

<details>
<summary>Internal deterministic boundary</summary>

Expand Down Expand Up @@ -163,24 +199,6 @@ existing product docs + code -> questions -> feature spec -> approval -> enginee

Product documents define what and why. ADRs record durable technical decisions. Gaps record known incomplete work. Boatstack references these sources without replacing them. Any generated spec or plan must remain traceable to its sources and reviewable as a lossy task projection. No context map or documentation migration is required in V1; the project config may list useful starting paths when a repository wants stable defaults.

## Install into a repository

macOS or Linux:

```bash
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/operatorstack/boatstack/main/install.sh)"
```

Windows PowerShell:

```powershell
irm https://raw.githubusercontent.com/operatorstack/boatstack/main/install.ps1 | iex
```

Run the command from the product repository. The installer detects the repository and available coding hosts, previews every generated path, verifies the downloaded helper, and asks whether to add gstack, Spec Kit, both, or core only. Boatstack core requires no Python, Node, Go, or package manager.

After installation, open the chosen host's Plan mode, describe the change, save its plan, and run `/auto-plan`. Boatstack uses the host-exposed active path or discovers exactly one file under `.product-loop/intake/`; an explicit path is only needed to resolve ambiguity. Auto-plan and plan-gate write Markdown only. After explicit approval, use the host's normal Build transition; `/build` activates and locks the plan before its first code edit. The source plan remains required and hash-checked through `/build`; later gates use the lock, actual diff, and evidence.

## Use Boatstack with gstack and GitHub Spec Kit

Boatstack is primarily a **control and evidence layer** over your coding host and optional planning/review tools. It does not need to reproduce everything those projects already do well:
Expand Down Expand Up @@ -283,7 +301,7 @@ Read the [research and design record](docs/research-and-design.md) and [corpus a

## Context has a budget

The three canonical runtime references currently total approximately **4521 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.
The three canonical runtime references currently total approximately **4625 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.

## Status

Expand Down
37 changes: 23 additions & 14 deletions UPSTREAM.json
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
{
"canonical_context": {
"characters": 18081,
"estimated_tokens": 4521,
"characters": 18498,
"estimated_tokens": 4625,
"estimator": "ceil(total characters / 4); compactness signal, not provider billing",
"files": [
"product-engineering-loop/references/workflow.md",
Expand All @@ -11,9 +11,10 @@
},
"files": {
".gitignore": "a7079e923a776f14f1bb3a6aa0a11a133a8e1dfb35af020f327623357b7e3957",
"CONTRIBUTING.md": "baaa5828ac493da05a5cf517524175534c318728830e191deb510e492b7d9c0f",
"README.md": "de733eb7d8a15a218cd52d37f510acfca1c3bdccc5085dfce8d9e09ea89d3ba2",
"boatstack/SKILL.md": "56cc1da6dea4fb57bd16d37ec9635eb06676d5e8580511190cddc78cd9e37346",
"CONTRIBUTING.md": "a24e1ad4601735f38b7499fc12a01273e7d5ef8871e87bdbf532a624b944abc7",
"README.md": "f423e876419caf5d4a84369fb41c07f6ea6b94e19826f8b8a0b3c5c04a31c3e1",
"assets/boatstack-mark.svg": "c46e935f06fcfde3b37abfd579c1963b765b2337a0fa993f9538c9b652297e39",
"boatstack/SKILL.md": "724dddef577576fb4c26e871422a4304fea3dc1d8b0f9324da200f20cd93078c",
"boatstack/agents/openai.yaml": "68a30a60859556c5a26e16d184594ca243a6043d99c8cf7d66b5dd6d50a93cd1",
"boatstack/assets/templates/adr.md": "c577a3c1c1319061f61deb053597e6e853657022185fe28b8f733327e2a78565",
"boatstack/assets/templates/approval.md": "74b0b816703a6dce3c96c8f95f981af910b020b6908e7f76cf5630778637e9f5",
Expand All @@ -25,31 +26,39 @@
"boatstack/assets/templates/plan.md": "358216e38d41f930c23c526741b718f30100c0071c8373a0c8b765d0e59f3fdf",
"boatstack/assets/templates/questions.md": "5875bbfc32d5a1b326c2a48da7449bb90c87f462a4c3a862173247e5f7ea6415",
"boatstack/assets/templates/test-plan.md": "6db8a9f27dd171fb80222a501cae50eb051e7278c04703fa43b5ff86dd4d2df4",
"boatstack/cmd/boatstack-helper/main.go": "853e60ba22766567afc3f7526260ab70b9056645c5c0500d97a9f3fc0f3a0bf0",
"boatstack/export.go": "7d70967d28032a76e58e083f07f27ad9609b0ab894dd208b1d2f3b726c8cd751",
"boatstack/export_test.go": "8f78c9bb50210161a19878d17775e73ffb591502d6ee11e6428ac436c128fe23",
"boatstack/atomic_unix.go": "89f2723361591de2bb8bd22ce7e34ec529d3278509f0df78fd5c4a7d4140fbe9",
"boatstack/atomic_windows.go": "cefd775cbe7e7c3bd8a3f5673b11cdd784c6d3ebd6de7dcb8f39406b0bee511f",
"boatstack/cmd/boatstack-helper/main.go": "e21101b8df6170c01a98bff71f8a2e9d7ac9ef92b883ec50020eb3a011a7737d",
"boatstack/export.go": "75e21e6602f7410bd332c2651097e77463976adc6977edd5b0415e33a25067e8",
"boatstack/export_test.go": "33c4d0754e59cfb6fc92938ffb3547f267a5dfdd6e8d5f8c359bef349b2862d4",
"boatstack/go.mod": "daf262a00abfe961d8ca266d4b26eea09a6aee73e4c53baaa537a809eaef59f6",
"boatstack/init.go": "6a04d5482748bd3b6a9febdf1723b89f8460144bcd5315d5feda0f82de477f07",
"boatstack/init_test.go": "7ca705f014f6bb22f7ea61a1eb370b98d1bc722f77a73711749375fb7a08ea14",
"boatstack/init.go": "4bcc010420f99a6d55b7ca4a48daa4ac49ced91c16fa6f7bdd7886b064324e22",
"boatstack/init_test.go": "1d1c51be4ef248ea1de0fbfd0a0af220f17247ed06ba353c690bfa700c95bf5d",
"boatstack/integrations.go": "75b39ce2e662fccd66bf4b9bff0e097a4db558f23b3aa1d9bc83a5fc6373444c",
"boatstack/plan.go": "8250ee93f91b4dd60e3788636ab79f32c626ace6daef6677fdc6338858f89a52",
"boatstack/plan_test.go": "f95ce7a38276f957064ee83901566c84ebf3eec0683e81794f823dc446b2ac54",
"boatstack/planning.go": "e3d8250d3343d724e0161cafd7f30202bc1b959b415697a99771067394aedc00",
"boatstack/planning_test.go": "9d19a64ee3b5361ef4413ee27f6d05b7e12ae5fc89e039f5ffec16095d6bdeea",
"boatstack/references/artifacts.md": "22b6cc596b65c8c2a22b0f3a692ca16a808fa495dad0b4453d23ea734978a2b7",
"boatstack/references/failure-moves.md": "2d7d3988c70718e9cc02104f9899a00208173e2f654d1046edd22079f4d46f41",
"boatstack/references/portability.md": "fb683095991bb0cb06ec56fb8884c49038b283172a7d2f8b203483b7cacb4bae",
"boatstack/references/workflow.md": "0b22fbe168aa31a3ac2832f2439367224aedd2b59468941ee45092b2c1ada1a9",
"boatstack/references/workflow.md": "2829b34cb5d62cca4c8a59e6ac3a62e75b5c6d6b3196005b36c3769e94ba262b",
"boatstack/runtime.go": "66c02aa0b6e9c031c26799b86dfbcb26df74487cc26b32f7fb85e38707eeec31",
"docs/account-recovery-walkthrough.md": "912edec85d930750c044bcd6117df9d03491a8c91f139af3ee82ab853452f1b7",
"docs/benchmark-corpus-audit.md": "f2d206fe8579a514f9da82b2c96c19b343ac004be67617e1bd34f0f8e0e5e6c6",
"docs/benchmark-submission-audit.md": "9518abdd17690729c6423f87cab20418ed47b0915b5faa44b9ef975e9e9c3b79",
"docs/evidence-engineered-coding.md": "453536fa767b98e4671ba885375a5f9af19cb95adb88444691e6e8905966fecf",
"docs/evidence-engineered-coding.md": "7e66d214d0f59bc7ecce42b7b0ffb3f612cdbf00b7ca10db614d5a181cab9184",
"docs/generated-files.md": "0ca73d52bb286b86324c6bcf0ef1c5aee5dc831e35b826b8a9e8cce65c311505",
"docs/getting-started.md": "4607ed828b6aa372a350046021bc8c2f6a758927554864a20b2e4a445ee7b57b",
"docs/research-and-design.md": "67dc454f0d13e0e2809f49e910f7847457fa78f03c4cef6fb0138f6039a57c4f",
"docs/troubleshooting.md": "6a2f8483d6f1fb7e0ae6265f3a07af05583e8c5585b8b887d307702bd9b14705",
"docs/validation-and-evidence.md": "3b5ed588bd44c5568f0c313be0dfaa411e959dc184fe886dfd0a81aee9fd25cc",
"examples/diagram-json/README.md": "061b583180e43bbd26618bbd9d3d79af4b75d7c8f37c66475640745a97328fbc",
"examples/diagram-json/approval.md": "bc421a825349923512d5cb0ce489310d3a4d7cbac35e661a693b4a32eec263d1",
"examples/diagram-json/compiled/evidence.md": "1ba1c989ade070a8ef9a508fbd788d100d7292f2dbacbb2bce895468019f619d",
"examples/diagram-json/compiled/tasks.json": "f040696f1f8bcedc4a8ed9816a61a49edbda970ec0cc3b28175ba37b73bbc896",
"examples/diagram-json/compiled/test-matrix.json": "6c6895c509271e4337f3c91d9f62ee3a2b34e768e78513784cb012506a328ecf",
"examples/diagram-json/plan.lock.json": "81617b3d642c50734c4b7188d639a244f344da16b5e35c6d0e0af8bd354efe37",
"examples/diagram-json/plan.lock.json": "a0df918570abdf146061852563a4684131fa7b5ba4b20108af9b537a7770b025",
"examples/diagram-json/plan.md": "3ad35cc3cbe48306e7ee401bd9e9047d25e46c8a6fe9679aa1b3f5e96ceea292",
"examples/diagram-json/questions.md": "1a0050041cac0a8d53e6ebfe04cbec4a298cdc8c50efeeb6fa15aeb663c5ec76",
"examples/diagram-json/request.md": "0808fc41c36779c404f4a3a121167da6e76cac56df526e70f9ed6d3e0d4c02ed",
Expand All @@ -62,7 +71,7 @@
"generator": "operatorstack/intelligence-flow:boatstack-distribution",
"schema_version": 1,
"source": {
"commit": "3cd11c293b3903aeac9ff8d8eacd47840d63a02d",
"commit": "29f36332e8e249528c6b088473d65e1190ff00b8",
"path": "examples/12-product-engineering-loop",
"repository": "operatorstack/intelligence-flow"
}
Expand Down
9 changes: 9 additions & 0 deletions assets/boatstack-mark.svg
View file
Open in desktop
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Loading