Skip to content

Sync Boatstack from Intelligence Flow 40ebae5dfb3d #4

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

Merged
bigboateng merged 1 commit into from
Jul 16, 2026
Merged

Sync Boatstack from Intelligence Flow 40ebae5dfb3d #4

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
5 changes: 3 additions & 2 deletions .gitignore
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,5 +1,6 @@
__pycache__/
*.py[cod]
boatstack/boatstack-helper
boatstack/boatstack-helper.exe
dist/
.DS_Store
.venv/
venv/
4 changes: 2 additions & 2 deletions CONTRIBUTING.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,8 +2,8 @@

# Contributing

Boatstack is a generated distribution. Propose changes to workflow semantics, templates, evidence rules, or generated presentation in [Intelligence Flow](https://github.com/operatorstack/intelligence-flow/tree/fcc2faa55ac3c2332ce4a19293d89023f578784d/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/40ebae5dfb3d090812301a438aaac079426edcfc/examples/12-product-engineering-loop).

The Boatstack repository receives those 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`.
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.

Repository-specific examples and outcome reports can be proposed upstream as new evidence. A failure becomes a durable move only after its mechanism and non-regression gate are documented.
193 changes: 152 additions & 41 deletions README.md
View file
Open in desktop

Large diffs are not rendered by default.

60 changes: 34 additions & 26 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": 13481,
"estimated_tokens": 3371,
"characters": 16173,
"estimated_tokens": 4044,
"estimator": "ceil(total characters / 4); compactness signal, not provider billing",
"files": [
"product-engineering-loop/references/workflow.md",
Expand All @@ -10,49 +10,57 @@
]
},
"files": {
".github/workflows/ci.yml": "9480a65a3a4d24b42f7854566ad4a55100b7f2c2b25bffc6bb6b368ba0848104",
".github/workflows/sync-upstream.yml": "f8c84e316e296ac5928bc0222cef64848ea0fda6846a42f540b0747e8c4eb5f7",
".gitignore": "94fa252979321511b0ce5fa598f71905f6dc29c5bef6660ff4498a5a39c167ba",
"CONTRIBUTING.md": "125729f68cbf129ce27a72973d7c633ae04cf8159a39ebeaaed98a2d3d13a40c",
"README.md": "8262db68e8217f4c367fbc4b2575e235ee0e57651d4e169265b27fa855bc4c7e",
"boatstack/SKILL.md": "335731973cea2c5d0eb67b9d3870cc332490d1188e3943bb185ab78ab4b4b886",
"boatstack/agents/openai.yaml": "8429c65868025e798d345cc2a9bd78f2bc3280ee982f8f7874504395d6d68368",
".gitignore": "a7079e923a776f14f1bb3a6aa0a11a133a8e1dfb35af020f327623357b7e3957",
"CONTRIBUTING.md": "cf876c19c52a1758c7347c0a27f63c12ef3e49d67066988df638cd09889b88ca",
"README.md": "0aada7f928bd0f1d2dcfd703fe822759a178e0e6a49779370f0c85f3a9d098f7",
"boatstack/SKILL.md": "1c71535962a56c9f9c7841e55e0e44c2988af427929f95e12cd7fcf08ef26686",
"boatstack/agents/openai.yaml": "68a30a60859556c5a26e16d184594ca243a6043d99c8cf7d66b5dd6d50a93cd1",
"boatstack/assets/templates/adr.md": "c577a3c1c1319061f61deb053597e6e853657022185fe28b8f733327e2a78565",
"boatstack/assets/templates/evidence.md": "12dac552bc5373ab443367d5797f41988f14284bcf46d16dfd72015cfddf9ad1",
"boatstack/assets/templates/feature-spec.md": "c7e007cc4295ed4c599642c0587021ef978e729cf0946f6bf3a6c4f01d366ad4",
"boatstack/assets/templates/gaps.md": "911cc2f086104d35071b952950c2ec44258641419f10b2355c594f33eb492cbe",
"boatstack/assets/templates/move.md": "91bfd9a9b9426ac023eb88fd19f4f638190481c1855f1239acc73830528e50f0",
"boatstack/assets/templates/plan-lock.json": "3e44dea05419cf198ee8112e9b9fdff92287edc2480a03fca026560fe929d468",
"boatstack/assets/templates/plan.json": "803907480dd150da36337f3ecf46e3617f3e26ace9be282e540032983cb77e86",
"boatstack/assets/templates/plan.json": "ff530e27959495aa800a494ebb745cd3703c8bd1c2b6c800c373f5210e89c9af",
"boatstack/assets/templates/questions.md": "86c9bcf51172fe222b7b28bffccaf3da3b1ea0633c7a2348272fdbbd8eea6740",
"boatstack/assets/templates/test-plan.md": "6db8a9f27dd171fb80222a501cae50eb051e7278c04703fa43b5ff86dd4d2df4",
"boatstack/references/artifacts.md": "caaa7337674bf707a53f0854c7d95e58333ac566f2bc67f0d77533230796221a",
"boatstack/cmd/boatstack-helper/main.go": "c9238e078fd85540073a284772f7360597e68aa0af86b7d3fc0dbc2c73a198ac",
"boatstack/export.go": "e1dc2d79126e98a8202d93a5fc13049b7186e105724daa93814c7133336e810a",
"boatstack/export_test.go": "f880bc99e78bbb3d8533153abaa63eee39c3d067df0eef2451e622083cce5676",
"boatstack/go.mod": "daf262a00abfe961d8ca266d4b26eea09a6aee73e4c53baaa537a809eaef59f6",
"boatstack/init.go": "6a04d5482748bd3b6a9febdf1723b89f8460144bcd5315d5feda0f82de477f07",
"boatstack/init_test.go": "7ca705f014f6bb22f7ea61a1eb370b98d1bc722f77a73711749375fb7a08ea14",
"boatstack/integrations.go": "75b39ce2e662fccd66bf4b9bff0e097a4db558f23b3aa1d9bc83a5fc6373444c",
"boatstack/plan.go": "8787fb1204fc7a81a2c81e39e4469faab637fd180297dce220eab1e48bf7787d",
"boatstack/plan_test.go": "5afab86a9b7f749652cfd31675f5a9bd1ec3e03086300923dd7d47765cd80963",
"boatstack/references/artifacts.md": "3aa4b2abc4195656b011cbfdd61b8e05759a0b67b37590be3a028c21b8a453e6",
"boatstack/references/failure-moves.md": "2d7d3988c70718e9cc02104f9899a00208173e2f654d1046edd22079f4d46f41",
"boatstack/references/portability.md": "5490a045526c4cd6fd52bcddeb0039119208478fb17656cd2f6b3d5f71698ce6",
"boatstack/references/workflow.md": "2c2343b3ef3dd7684dc6a027da4c8e5b1ce927cf3979aca32abea0d0d2028ee7",
"boatstack/scripts/approve_plan.py": "92cb14cf0703bd25d053f8939575ab651a0274418d9ec85f3827f4c23c30001c",
"boatstack/scripts/compile_plan.py": "523befa52993f5606a5ed7a91678459254ba6cfa074e9aafa9f4010876332968",
"boatstack/scripts/export_repo.py": "42444369b2b4d8430b5347761626ac7725aae25aa4726b5bdca5325a4fc80ad0",
"boatstack/references/portability.md": "fb683095991bb0cb06ec56fb8884c49038b283172a7d2f8b203483b7cacb4bae",
"boatstack/references/workflow.md": "b8262570751ea73cf40cf9de76fc2e6acf1303657d1956b6957ca9af7034fbb0",
"boatstack/runtime.go": "66c02aa0b6e9c031c26799b86dfbcb26df74487cc26b32f7fb85e38707eeec31",
"docs/benchmark-corpus-audit.md": "f2d206fe8579a514f9da82b2c96c19b343ac004be67617e1bd34f0f8e0e5e6c6",
"docs/benchmark-submission-audit.md": "9518abdd17690729c6423f87cab20418ed47b0915b5faa44b9ef975e9e9c3b79",
"docs/loop-engineering.md": "63b114e57c129379757a57938e33abb2da21eed3fef19c1731dba22ea58b5baf",
"docs/research-and-design.md": "543836387090f8dc01381b1e46d1c6760bcbf8119b4004ece8d6f6f68d08db4f",
"examples/diagram-json/README.md": "51871b16438cbef2bbdf5077dda0b5b06e77cbe76882d34e4a05c17c8f13a2b3",
"docs/evidence-engineered-coding.md": "2c2b9cb428d3e75b8463d17099ec254afd204367cdc6f8a2214c9def97d8c2a9",
"docs/research-and-design.md": "fc9c517f2783489cbbc4de5ad020a4e4e5bb542c7092b13b317a1893a3415cb4",
"docs/validation-and-evidence.md": "3b5ed588bd44c5568f0c313be0dfaa411e959dc184fe886dfd0a81aee9fd25cc",
"examples/diagram-json/README.md": "fbb4721434e6110bbef84813c244132bbe7ae0e9e0cd535b6871e3359bcd4559",
"examples/diagram-json/compiled/evidence.md": "1ba1c989ade070a8ef9a508fbd788d100d7292f2dbacbb2bce895468019f619d",
"examples/diagram-json/compiled/tasks.json": "d66d693df1ba7dd34f65ce93afea54006563c14d642a1bf0d1d9311b3fcfb37b",
"examples/diagram-json/compiled/test-matrix.json": "0497cf73f84515cfc493e4904eda4c2be6c0621fc0a11a3b1349803b5acf91cb",
"examples/diagram-json/plan.json": "d1208003042a9d10f5efb010fc32fc7ac7bdefa427938260586e90daa0cb4414",
"examples/diagram-json/plan.lock.json": "3e0bb70807c5a06dd7ac7a87c691a19abfc2e27131754830fe1d32b365a20bba",
"examples/diagram-json/compiled/tasks.json": "f040696f1f8bcedc4a8ed9816a61a49edbda970ec0cc3b28175ba37b73bbc896",
"examples/diagram-json/compiled/test-matrix.json": "6c6895c509271e4337f3c91d9f62ee3a2b34e768e78513784cb012506a328ecf",
"examples/diagram-json/plan.json": "df1b205517cf7dbdf5c5db65a342622922bd959a5ba885326888f6dd2b9c50d3",
"examples/diagram-json/plan.lock.json": "c904d4873bf678198dc2d7aba4e90e278385d0266e8bf8bc54334d3f764f1a1a",
"examples/diagram-json/questions.md": "1a0050041cac0a8d53e6ebfe04cbec4a298cdc8c50efeeb6fa15aeb663c5ec76",
"examples/diagram-json/request.md": "0808fc41c36779c404f4a3a121167da6e76cac56df526e70f9ed6d3e0d4c02ed",
"examples/diagram-json/source-plan.md": "e10593ddaa7522ab80cc991d0a09399257139799e37f737794cd49d68a39985b",
"examples/diagram-json/spec.md": "a943c81cf2a88d23d5b300e6b9dc1dafc80923a9b6b9ab5297a67b4e2054b9d5",
"project.example.json": "2054228f4c824d43385b7732e9f38f17739900d3cec6567bc23c5fe6c890d1be",
"tests/test_boatstack.py": "9d61e552a196b9c9fba8bd175b7c3ae1fcfead1f61eb6396df065477086369e1"
"install.ps1": "c81f2f8eb6032ea82c36ebe98bd015ba4dabb8f4825b3c1bb89baea2a808690c",
"install.sh": "c9caf1eb0554715d189e4183478dfb3ae7e5c0a8187ea44229cbf268276652f8",
"project.example.json": "d1f7aa3cff0b55ede79500bd2ca710bb99cb2ae579f0a058dc00934accf03d33"
},
"generator": "operatorstack/intelligence-flow:boatstack-distribution",
"schema_version": 1,
"source": {
"commit": "fcc2faa55ac3c2332ce4a19293d89023f578784d",
"commit": "40ebae5dfb3d090812301a438aaac079426edcfc",
"path": "examples/12-product-engineering-loop",
"repository": "operatorstack/intelligence-flow"
}
Expand Down
47 changes: 28 additions & 19 deletions boatstack/SKILL.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,14 +5,14 @@ description: Turn a product request into a question-led, specification-first imp

# Boatstack

Build the smallest complete product slice that can be independently verified. Keep the workflow model-neutral: project facts and gate evidence are canonical; host-specific prompts are adapters.
Build the smallest complete product slice that can be independently verified. Implementation methods remain open: project facts, approval, and gate evidence are canonical; host-specific prompts are adapters. You are free in how you build. Only claims of completion require evidence.

## Start by selecting the operation

Map the request to one operation:

- `init`: inspect a repository and create or update `.product-loop/project.json`.
- `auto-plan`: turn product intent into a reviewable draft feature package.
- `auto-plan`: refine a saved host Plan-mode file into a reviewable draft feature package; refuse when that file is absent.
- `plan-gate`: present the draft for explicit human acceptance, then freeze its approved contents and generate the executable package.
- `build`: implement approved tasks in bounded, reversible slices.
- `test-gate`: test requirements and relevant regressions using independent evidence.
Expand All @@ -35,7 +35,7 @@ For ordinary feature work, define one bounded outcome:

Because this workflow is also a reusable product, maintain delivery and improvement as separate paths:

- **Delivery path:** intent -> questions -> spec -> plan -> code -> gates -> PR.
- **Delivery path:** intent -> host Plan mode -> saved source plan -> questions -> spec -> approved plan -> code -> gates -> PR.
- **Improvement path:** traces -> failure classification -> proposed move -> paired evaluation -> promote/reject.

Never mix benchmark observations or speculative harness changes into the delivery path during an active feature. The improvement path may propose an experiment; only a passed promotion gate changes the canonical loop.
Expand All @@ -53,37 +53,43 @@ Do not scan the entire repository by default. Record discovered paths and comman

## Run `auto-plan`

1. Write the bounded outcome definition before proposing architecture.
2. Separate facts, decisions, unknowns, and safely deferrable gaps.
3. Answer discoverable code questions by inspection.
4. Ask the developer only questions whose answers materially change behavior, contracts, risk, or acceptance. Ask 1-3 concise questions at a time, give 2-3 mutually exclusive choices, recommend one, and explain the impact.
5. Record answers and provenance in the question ledger.
6. Create the feature spec: problem, users, outcomes, non-goals, acceptance criteria, invariants, interfaces, failure behavior, observability, rollout, and rollback.
7. Run product, design, engineering, and developer-experience reviews only when applicable. If gstack is installed, its review skills can implement these lenses; do not require it.
8. If Spec Kit is installed, use its constitution/specify/clarify/plan/tasks/analyze/checklist flow as an artifact generator. The canonical artifact contract remains authoritative.
9. End with a **draft**, never an implied approval. Do not generate executable task state or start implementation from `auto-plan` alone.
0. Require exactly one saved plan file created in the active host's Plan mode. First use the active plan path exposed in host/system conversation context, when available, and validate it with `.product-loop/bin/boatstack-helper check-source-plan --repo . --plan <host-path>`. Otherwise run `check-source-plan --repo .` to search only `.product-loop/intake/` and bounded repo-local host plan directories. If the result is missing or ambiguous, return `BLOCKED`; never choose by recency alone. An explicit `/auto-plan <path>` is only the ambiguity fallback. Do not write the missing source plan inside `auto-plan`.
1. Treat the supplied plan as an initial proposal, not approved truth. Record its path as `source_plan_path` in the structured plan.
2. Write the bounded outcome definition before proposing architecture.
3. Separate facts, decisions, unknowns, and safely deferrable gaps.
4. Answer discoverable code questions by inspection.
5. Ask the developer only questions whose answers materially change behavior, contracts, risk, or acceptance. Ask 1-3 concise questions at a time, give 2-3 mutually exclusive choices, recommend one, and explain the impact.
6. Record answers and provenance in the question ledger.
7. Create the feature spec: problem, users, outcomes, non-goals, acceptance criteria, invariants, interfaces, failure behavior, observability, rollout, and rollback. Translate every accepted claim into an observable condition with a defensible oracle.
8. Run product, design, engineering, and developer-experience reviews only when applicable. If gstack is installed, its review skills can implement these lenses; do not require it.
9. If Spec Kit is installed, use its constitution/specify/clarify/plan/tasks/analyze/checklist flow as an artifact generator. The canonical artifact contract remains authoritative.
10. For every planned validation, record the exact `criteria` it can support plus `run`, `origin`, `oracle`, and `independence`. Commands, automated tests, external checks, and named human review procedures are all valid forms, but an ambiguous claim without a threshold/rubric and authorized decision remains `BLOCKED`.
11. End with a **draft**, never an implied approval. Do not generate executable task state or start implementation from `auto-plan` alone.

Do not treat an ADR as general project context. ADRs record accepted durable decisions. Use a question ledger for unknowns and a gap ledger for known divergence.

Treat repository-owned product context as canonical. Do not require it to be migrated or rewritten into a Boatstack memory. Specs, plans, summaries, and selected context are temporary task projections: keep them reviewable, link material claims back to their source paths, and never silently replace the source. Preserve the source; project only the relevant slice.

## Run `plan-gate`

1. Present the draft spec, plan, open decisions, accepted assumptions, gaps, risks, and proposed verification in a reviewable form.
1. Present the draft spec, plan, open decisions, accepted assumptions, gaps, risks, and proposed verification—including the origin, oracle, and independence of every validation—in a reviewable form.
2. Ask the developer to approve it or request changes. Silence and continued conversation are not approval.
3. On changes, return to `auto-plan`, preserve the feedback in the question/decision ledger, and issue a new draft.
4. On explicit approval, deterministically compile the already-approved structured plan into the task graph, requirement-test traceability rows, evidence skeleton, and expected gate commands. Do not add semantics during compilation.
5. Calculate content hashes and write `plan.lock.json` with the approver, timestamp, source commit, spec hash, plan hash, and task-graph hash.
6. If the spec or plan changes later, invalidate the lock and return to this gate.
5. Calculate content hashes and write `plan.lock.json` with the approver, timestamp, source commit, source-plan hash, spec hash, structured-plan hash, and task-graph hash.
6. If the source plan, spec, or structured plan changes later, invalidate the lock and return to this gate.

`build` must refuse to run when the plan lock is absent, stale, or does not match the approved artifacts.
`build` must refuse to run when the source Plan-mode file is absent or when the plan lock is absent, stale, or does not match the source plan and approved artifacts.

The reference implementation performs the post-approval materialization and lock in this order:

```bash
python3 .product-loop/tools/compile_plan.py \
.product-loop/bin/boatstack-helper compile-plan \
--plan .product-loop/features/<feature>/plan.json \
--out-dir .product-loop/features/<feature>/compiled

python3 .product-loop/tools/approve_plan.py \
.product-loop/bin/boatstack-helper approve-plan \
--source-plan <path-to-saved-host-plan> \
--spec .product-loop/features/<feature>/spec.md \
--plan .product-loop/features/<feature>/plan.json \
--tasks .product-loop/features/<feature>/compiled/tasks.json \
Expand All @@ -95,6 +101,8 @@ The first command validates and compiles already-approved semantics; it must not

## Build without erasing evidence

- Before the first edit, pass the source plan along with the approved artifacts to `approve-plan --check`. It remains a required, hash-checked input through completion of `build`.
- Choose any suitable model, tool, or implementation tactic inside the approved boundary. Boatstack controls transitions and claims, not local creativity.
- Work from approved tasks and acceptance criteria.
- Preserve the last known-good state; repair locally instead of restarting a near-correct implementation.
- Re-scope context at task boundaries. Include relevant source, interfaces, invariants, and tests—not arbitrary history.
Expand All @@ -108,6 +116,7 @@ Do not branch the workflow on model brand, price, or a guessed capability tier.

### Test gate

- After build completes, the source Plan-mode file is no longer a runtime prerequisite. Test, review, and ship use the approved lock, actual diff, and accumulated evidence; provenance remains recorded in the lock.
- Derive tests from acceptance criteria and affected contracts, not only from the implementation.
- Run existing relevant tests plus targeted new tests, linters, type checks, builds, and runtime checks.
- Treat model-authored tests and same-model self-review as evidence, not ground truth.
Expand Down Expand Up @@ -147,7 +156,7 @@ More steps, more context, stronger wording, more tests, or more retries are not
Read [portability.md](references/portability.md), then use:

```bash
python3 boatstack/scripts/export_repo.py --adapter-name boatstack --repo /path/to/repo --config /path/to/project.json --write
.product-loop/bin/boatstack-helper export --repo /path/to/repo --config /path/to/project.json --write
```

Run with `--check` in CI to detect drift. The exporter writes generated files only and refuses to overwrite user-owned files. Review the generated diff in a branch and ship it through a PR.
4 changes: 2 additions & 2 deletions boatstack/agents/openai.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
interface:
display_name: "Boatstack"
short_description: "Plan, build, verify, review, and ship with evidence."
default_prompt: "Use $boatstack to turn this product request into a question-led, evidence-gated implementation loop."
short_description: "Build freely; approve, verify, review, and ship with evidence."
default_prompt: "Use $boatstack as an evidence-engineered coding node: keep implementation tactics open and require evidence for approval, completion, review, and shipping."
Loading
Loading