diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 817fb51..9e790aa 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -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/645d8e4103dd02e0a137c1c53ddd13f114dbe45f/labs/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/6413259bbc3b84cdc6eb347625e2820e4d5dd909/labs/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. diff --git a/README.md b/README.md index 9a4bc3a..a3f9723 100644 --- a/README.md +++ b/README.md @@ -10,14 +10,14 @@ ## A delivery harness for AI coding agents -Boatstack connects the work from an idea to a reviewed PR. Keep using Cursor, Codex, Claude Code, or Gemini CLI, with the models and specialist skills that fit the work. Boatstack keeps the plan, decisions, gaps, tests, review findings, and project context connected along the way. +An AI coding agent will guess a product decision, call the work "done" on one green check, and lose the reasoning the moment you change tools. Boatstack connects the work from an idea to a reviewed PR so none of that slips: the plan, decisions, gaps, tests, review findings, and project context stay connected along the way. Keep using Cursor, Codex, Claude Code, or Gemini CLI, with the models and specialist skills that fit the work. The agent remains free to build. Before it says the work is done, Boatstack asks for the approval, tests, review, and recorded evidence appropriate to the change. **Your product development flow stays with the repository—not the coding agent.** Change tools without rebuilding how you ship or redefining what “done” means. Boatstack carries the workflow and saved project state—not an agent's private chat history or a command already in progress.

- Coding agents, models, and specialist skills feed one repository-owned Boatstack flow that produces a reviewed pull request and useful context for the next feature + Change the tools, keep the flow: coding agents, models, and specialist skills feed one repository-owned Boatstack flow that produces a reviewed pull request and useful context for the next feature

| You change | Boatstack keeps | @@ -79,13 +79,13 @@ Receipts remain as history; published corrections become linked deliveries. ## Features - **A guided path from idea to PR.** `/auto-plan` starts a one-action-at-a-time delivery flow. -- **Instant orientation after a break.** `boatstack next` reconstructs the verified stage without treating chat or a running process as workflow evidence. +- **Instant orientation after a break.** `boatstack next` reconstructs the verified stage without treating chat or a running process as workflow evidence, so you resume in seconds instead of re-reading history. - **Human decisions stay human.** Material product questions remain open until a person answers them, and implementation waits for explicit approval. - **Evidence tied to the promise.** Tests and checks map to the outcomes the change claims to deliver instead of treating one green command as proof of everything. - **Context that survives the feature.** Plans, decisions, gaps, evidence, and code state remain useful beyond the chat. - **Conversational repair after Build.** Describe what changed; Boatstack preserves valid work and reruns only affected boundaries. - **Safer agent execution.** High-confidence destructive recovery is stopped before execution; phased work is gated and published one approved delivery slice at a time. -- **Reviewer-ready pull requests.** Actual changes, evidence, risks, rollout, and rollback become a focused PR brief. +- **Reviewer-ready pull requests.** Actual changes, evidence, risks, rollout, and rollback become a focused PR brief, so reviewers spend time on judgment, not reconstruction. - **Optional repository changelog.** Require readable `CHANGELOG.md` entries grounded in actual changes. - **Portable across your AI stack.** Hosts, models, and skills share one repository-owned delivery contract. - **Repository-friendly maintenance.** Worktrees restore runtime; updates stay in separate infrastructure PRs. diff --git a/UPSTREAM.json b/UPSTREAM.json index f54187e..d14bf43 100644 --- a/UPSTREAM.json +++ b/UPSTREAM.json @@ -12,11 +12,11 @@ }, "files": { ".gitignore": "a7079e923a776f14f1bb3a6aa0a11a133a8e1dfb35af020f327623357b7e3957", - "CONTRIBUTING.md": "029239e92fe35e117021e7978e60b2041d9f9257b745081010a4f3587785e21c", - "README.md": "590821a4cf3c4b196d3cfb39c972ccbebef7d4d558df817c1f1e88b4fd7ceb07", - "assets/boatstack-journey.svg": "9f016fbfd2881675551a44dafa282cbc7510a7091131005be490c2dbe5e4e051", - "assets/boatstack-mark.svg": "ec96165583b15cfd446c27049d49217973f3e9b1defa5771cc08eec0c9542ce4", - "assets/boatstack-portability.svg": "a621b8f4da5159bbfdfd858013ff3fefc3937d7f6e140612a2c82e84283865f9", + "CONTRIBUTING.md": "2cf7d6f5c55cc27a21bc9eeff92a46c5dfe26bba42a98b01888517fc28ccdb70", + "README.md": "a90ba7af7a9cbf71c858d99187f66e0f3db305b2a76fc98ba5625f78ac7c23a4", + "assets/boatstack-journey.svg": "e465befc50c8ce30f3e07e8fd97012931beeb053392c8fbf38ad645023b3cc63", + "assets/boatstack-mark.svg": "be1f984da1bfa69fa5d1f986d8343d21f7e20921b71db888c928b4d2e54b09b5", + "assets/boatstack-portability.svg": "66dfdfa85db857b3bd18b32047a6975f1fbbfc4dc091158e8277193f9969a346", "boatstack/SKILL.md": "b8a3bf396c29e5e728d50837c4546bd500a40cc24009217c2f7b80ed267d6bf1", "boatstack/agents/gemini.yaml": "cbf43b387399e456fa6178f86d83e6e35567e6142ff800f8de6ffca306fa963e", "boatstack/agents/openai.yaml": "68a30a60859556c5a26e16d184594ca243a6043d99c8cf7d66b5dd6d50a93cd1", @@ -89,10 +89,10 @@ "docs/account-recovery-walkthrough.md": "676034974594a7d1a559b24dbed31d7ccc429eb81404b203ca07bbdaa19ec3d3", "docs/benchmark-corpus-audit.md": "f2d206fe8579a514f9da82b2c96c19b343ac004be67617e1bd34f0f8e0e5e6c6", "docs/benchmark-submission-audit.md": "9518abdd17690729c6423f87cab20418ed47b0915b5faa44b9ef975e9e9c3b79", - "docs/evidence-engineered-coding.md": "88a8da0a75fcb3562e967f7f30066944585e9a475fea7f68a925746d63c37619", + "docs/evidence-engineered-coding.md": "9bf104ff034817b8f9ebf177898efd86d1b7cf64ff085c62133e84b7ecea448e", "docs/generated-files.md": "136422baf0c7fc2bd5100cfe0ebdb3d9d0705dfd7e7d54bf745dd1037e63492c", "docs/getting-started.md": "eacc814fdffdfa3c7d8052b7cd99a79c04da5c75d88d8b44f3fb68d9afec0316", - "docs/public-claims.json": "e8f53d50c201733a8c8980060dbb4ed3aff2077962e19dc1bdfcfb01f9481213", + "docs/public-claims.json": "74ba7f4500d161b6b8358c1f0dc57df85fcf604332363f578b32dfdd1b76090a", "docs/public-surface.md": "713f7a050b5f339cf948299103ef3800417dccfecf2cc1a4166397ea6f978907", "docs/research-and-design.md": "d65c66e323037bda5d45aacef5d48afa6bf93da55901378891d235aca3a5684f", "docs/safety.md": "7b9b5c515d36e683767ec8d3d9d6d119ac93650b2f629d351deadd4c600ed6a6", @@ -106,7 +106,7 @@ "labs/diagram-json/compiled/evidence.md": "1ba1c989ade070a8ef9a508fbd788d100d7292f2dbacbb2bce895468019f619d", "labs/diagram-json/compiled/tasks.json": "88f60851abf79d851e9fccc754ff3040034ae595306bc87d64784c19eb403e71", "labs/diagram-json/compiled/test-matrix.json": "424657ff505768e50fa113801fd8363364a18269d5297480907a993d44063a39", - "labs/diagram-json/plan.lock.json": "d1d074315db19359bcd8fa33e41c7bf6eb1f95526fce7b7a984404e1f68cc82b", + "labs/diagram-json/plan.lock.json": "7a1a050737a04ccb7b0b0a71f44f45c1ddeaf2c1eba8e0acdd3d8e6ba9218d60", "labs/diagram-json/plan.md": "3cc4f533b8d69386deff16b3a594a3ba09d4c0c3db636cccd8c4380084ce6a51", "labs/diagram-json/questions.md": "74733b015002c8a6777c558e7e997fa48c94850b9bd39054fe9366c97ecf728d", "labs/diagram-json/request.md": "0808fc41c36779c404f4a3a121167da6e76cac56df526e70f9ed6d3e0d4c02ed", @@ -146,13 +146,14 @@ "release-notes/2026-07-20-portability-diagram-dark-theme.md": "b06bebec1361b21ef6deb8c8f43168d189803a32588aeb803ea4b441525a77e2", "release-notes/2026-07-20-product-focused-pr-titles.md": "ffb8f58fa4978de81f102ca0bbc7fc09b019293aff24e7c661ae635aa46ac839", "release-notes/2026-07-20-speak-software-standards.md": "a8890ed7eb38868bdf3035572d71785ca89abd3ffc3a314a5dc5315150afe397", + "release-notes/2026-07-21-blueprint-diagrams-value-first-readme.md": "11eb70cb814a99606b4f7761401d3670074fe6bd1af8557f95f573b04a3195af", "release-notes/2026-07-21-e2e-architecture-grounding.md": "7fa7e99fc6fd4e0688009bb736e6506830bf0216f3fa19757cbd9f5679c7ac3b", "release-notes/2026-07-21-prevent-hallucinated-approver-names.md": "a5fd08bc3d8b983340a2ddd67b71c78b2b34a915fdfe6eb7cdffd0f1d52e3427" }, "generator": "operatorstack/intelligence-flow:boatstack-distribution", "schema_version": 1, "source": { - "commit": "645d8e4103dd02e0a137c1c53ddd13f114dbe45f", + "commit": "6413259bbc3b84cdc6eb347625e2820e4d5dd909", "path": "labs/12-product-engineering-loop", "repository": "operatorstack/intelligence-flow" } diff --git a/assets/boatstack-journey.svg b/assets/boatstack-journey.svg index c216e17..49e08ae 100644 --- a/assets/boatstack-journey.svg +++ b/assets/boatstack-journey.svg @@ -2,23 +2,51 @@ Boatstack episode handoff A complete feature turns an idea into a pull request. Decisions, gaps, evidence, and code state are retained, then combine with the next idea to create the next plan. + + + + + + + + + One feature improves the starting point of the next FEATURE EPISODE 1 @@ -37,17 +65,27 @@ - RETAINED PROJECT CONTEXT - plans · decisions · gaps · evidence · code state + RETAINED PROJECT CONTEXT + plans · decisions · gaps · evidence · code state The feature ends. Its useful state does not. FEATURE EPISODE 2 Next idea - + + + Next Plan …the next feature starts better informed + + + + + + DWG · JRNY + BOATSTACK + REV — + SCALE 1:1 + diff --git a/assets/boatstack-mark.svg b/assets/boatstack-mark.svg index 0b6a27e..f0fdd77 100644 --- a/assets/boatstack-mark.svg +++ b/assets/boatstack-mark.svg @@ -1,17 +1,28 @@ Boatstack - A rounded ink field with three stacked bars — the repository-owned delivery stack. + A rounded ink field with three stacked bars over a faint blueprint grid — the repository-owned delivery stack. - - + + + + + + + + + - + diff --git a/assets/boatstack-portability.svg b/assets/boatstack-portability.svg index 3c987a9..37a936e 100644 --- a/assets/boatstack-portability.svg +++ b/assets/boatstack-portability.svg @@ -2,25 +2,49 @@ Your product development flow stays with the repository Cursor, Codex, Claude Code, Gemini CLI, different model tiers, and specialist skills feed one repository-owned Boatstack flow. The flow retains plans, decisions, gaps, evidence, and review findings, producing a reviewed pull request and useful context for the next feature. + + + + + + + + + Change the tools. Keep the flow. The repository owns the working state and the standard for “done.” @@ -49,7 +73,7 @@ - YOUR REPOSITORY + YOUR REPOSITORY BOATSTACK one product-development flow @@ -70,4 +94,14 @@ for the next feature + + + + + + DWG · PORT + BOATSTACK + REV — + SCALE 1:1 + diff --git a/docs/evidence-engineered-coding.md b/docs/evidence-engineered-coding.md index cd4e5c6..b16a4d7 100644 --- a/docs/evidence-engineered-coding.md +++ b/docs/evidence-engineered-coding.md @@ -146,6 +146,6 @@ Delivery and system improvement also remain separate. A failed task may suggest ## What is evidence-backed -The current moves were derived from the Intelligence Flow benchmark corpus and product-repository studies. The generated source commit is [`645d8e4103dd02e0a137c1c53ddd13f114dbe45f`](https://github.com/operatorstack/intelligence-flow/tree/645d8e4103dd02e0a137c1c53ddd13f114dbe45f/labs/12-product-engineering-loop). +The current moves were derived from the Intelligence Flow benchmark corpus and product-repository studies. The generated source commit is [`6413259bbc3b84cdc6eb347625e2820e4d5dd909`](https://github.com/operatorstack/intelligence-flow/tree/6413259bbc3b84cdc6eb347625e2820e4d5dd909/labs/12-product-engineering-loop). The evidence supports specific failure mechanisms and guardrails. It does not establish that Boatstack is optimal, that control-theory notation proves software quality, or that one workflow dominates every team. Those are evaluation questions, so the distribution preserves measurements, provenance, gaps, and negative results. diff --git a/docs/public-claims.json b/docs/public-claims.json index e0d3b54..3638674 100644 --- a/docs/public-claims.json +++ b/docs/public-claims.json @@ -1,6 +1,6 @@ { "schema_version": 1, - "source_commit": "645d8e4103dd02e0a137c1c53ddd13f114dbe45f", + "source_commit": "6413259bbc3b84cdc6eb347625e2820e4d5dd909", "statuses": ["verified", "observed", "still_being_evaluated"], "claims": [ { @@ -12,7 +12,7 @@ "readable_evidence": "why-these-steps.md#portable-workflow-and-state", "implementation": ["../boatstack/export.go", "../boatstack/references/artifacts.md", "../boatstack/references/workflow.md"], "verification": ["../boatstack/export_test.go"], - "last_verified_version": "source:645d8e4103dd02e0a137c1c53ddd13f114dbe45f" + "last_verified_version": "source:6413259bbc3b84cdc6eb347625e2820e4d5dd909" }, { "id": "human-decisions", @@ -23,7 +23,7 @@ "readable_evidence": "why-these-steps.md#human-decisions", "implementation": ["../boatstack/references/workflow.md", "../boatstack/plan.go"], "verification": ["../boatstack/plan_test.go", "../boatstack/planning_test.go"], - "last_verified_version": "source:645d8e4103dd02e0a137c1c53ddd13f114dbe45f" + "last_verified_version": "source:6413259bbc3b84cdc6eb347625e2820e4d5dd909" }, { "id": "validation-provenance", @@ -34,7 +34,7 @@ "readable_evidence": "why-these-steps.md#validation-provenance", "implementation": ["validation-and-evidence.md", "../boatstack/plan.go"], "verification": ["../boatstack/plan_test.go"], - "last_verified_version": "source:645d8e4103dd02e0a137c1c53ddd13f114dbe45f" + "last_verified_version": "source:6413259bbc3b84cdc6eb347625e2820e4d5dd909" }, { "id": "irreversible-operations", @@ -46,7 +46,7 @@ "readable_evidence": "why-these-steps.md#irreversible-operations", "implementation": ["safety.md", "../boatstack/safety.go", "../boatstack/hooks.go"], "verification": ["../boatstack/safety_test.go", "../boatstack/hooks_test.go"], - "last_verified_version": "source:645d8e4103dd02e0a137c1c53ddd13f114dbe45f" + "last_verified_version": "source:6413259bbc3b84cdc6eb347625e2820e4d5dd909" }, { "id": "reviewer-ready-pr", @@ -57,7 +57,7 @@ "readable_evidence": "why-these-steps.md#reviewer-ready-pr", "implementation": ["../boatstack/pr.go", "getting-started.md"], "verification": ["../boatstack/pr_test.go"], - "last_verified_version": "source:645d8e4103dd02e0a137c1c53ddd13f114dbe45f" + "last_verified_version": "source:6413259bbc3b84cdc6eb347625e2820e4d5dd909" }, { "id": "phase-scoped-delivery", @@ -68,7 +68,7 @@ "readable_evidence": "why-these-steps.md#phase-scoped-delivery", "implementation": ["../boatstack/delivery.go", "../boatstack/safety.go", "../boatstack/hooks.go", "../boatstack/references/workflow.md"], "verification": ["../boatstack/delivery_test.go", "../boatstack/pr_test.go"], - "last_verified_version": "source:645d8e4103dd02e0a137c1c53ddd13f114dbe45f" + "last_verified_version": "source:6413259bbc3b84cdc6eb347625e2820e4d5dd909" }, { "id": "model-neutral-contract", @@ -79,7 +79,7 @@ "readable_evidence": "why-these-steps.md#model-choice-and-budget", "implementation": ["research-and-design.md", "../boatstack/references/workflow.md"], "verification": ["../boatstack/export_test.go", "../boatstack/planning_test.go"], - "last_verified_version": "source:645d8e4103dd02e0a137c1c53ddd13f114dbe45f" + "last_verified_version": "source:6413259bbc3b84cdc6eb347625e2820e4d5dd909" }, { "id": "cross-model-failures", @@ -90,7 +90,7 @@ "readable_evidence": "why-these-steps.md#model-choice-and-budget", "implementation": ["research-and-design.md"], "verification": ["benchmark-corpus-audit.md", "benchmark-submission-audit.md"], - "last_verified_version": "source:645d8e4103dd02e0a137c1c53ddd13f114dbe45f" + "last_verified_version": "source:6413259bbc3b84cdc6eb347625e2820e4d5dd909" }, { "id": "lower-cost-outcomes", @@ -101,7 +101,7 @@ "readable_evidence": "why-these-steps.md#model-choice-and-budget", "implementation": ["research-and-design.md"], "verification": ["benchmark-corpus-audit.md", "benchmark-submission-audit.md"], - "last_verified_version": "source:645d8e4103dd02e0a137c1c53ddd13f114dbe45f" + "last_verified_version": "source:6413259bbc3b84cdc6eb347625e2820e4d5dd909" }, { "id": "git-worktree-activation", @@ -112,7 +112,7 @@ "readable_evidence": "why-these-steps.md#git-worktree-activation", "implementation": ["../boatstack/runtime_cache.go", "../boatstack/hooks.go"], "verification": ["../boatstack/runtime_cache_test.go", "../boatstack/hooks_test.go"], - "last_verified_version": "source:645d8e4103dd02e0a137c1c53ddd13f114dbe45f" + "last_verified_version": "source:6413259bbc3b84cdc6eb347625e2820e4d5dd909" }, { "id": "visible-updates", @@ -123,7 +123,7 @@ "readable_evidence": "why-these-steps.md#visible-updates", "implementation": ["../boatstack/update.go", "../boatstack/init.go"], "verification": ["../boatstack/update_test.go", "../boatstack/init_test.go", "../boatstack/export_test.go"], - "last_verified_version": "source:645d8e4103dd02e0a137c1c53ddd13f114dbe45f" + "last_verified_version": "source:6413259bbc3b84cdc6eb347625e2820e4d5dd909" } ] } diff --git a/labs/diagram-json/plan.lock.json b/labs/diagram-json/plan.lock.json index d61d58a..e81e025 100644 --- a/labs/diagram-json/plan.lock.json +++ b/labs/diagram-json/plan.lock.json @@ -6,7 +6,7 @@ "plan_path": "labs/diagram-json/plan.md", "plan_sha256": "3cc4f533b8d69386deff16b3a594a3ba09d4c0c3db636cccd8c4380084ce6a51", "schema_version": 1, - "source_commit": "645d8e4103dd02e0a137c1c53ddd13f114dbe45f", + "source_commit": "6413259bbc3b84cdc6eb347625e2820e4d5dd909", "source_plan_path": "labs/diagram-json/source-plan.md", "source_plan_sha256": "e10593ddaa7522ab80cc991d0a09399257139799e37f737794cd49d68a39985b", "spec_path": "labs/diagram-json/spec.md", diff --git a/release-notes/2026-07-21-blueprint-diagrams-value-first-readme.md b/release-notes/2026-07-21-blueprint-diagrams-value-first-readme.md new file mode 100644 index 0000000..0a187af --- /dev/null +++ b/release-notes/2026-07-21-blueprint-diagrams-value-first-readme.md @@ -0,0 +1,3 @@ +### Redesign distribution diagrams as a blueprint system and reframe the README around user value + +Reskinned the mark, portability, and journey diagrams into a technical-blueprint system — an ink-on-paper Draft treatment in light mode and a Cyanotype treatment in dark mode via `prefers-color-scheme`, with a construction grid, registration ticks, and a drawing title block. All viewBoxes, labels, arrow paths, and brand hexes are unchanged. Reworded the README to lead with the failure it removes (an agent guessing a decision, calling work "done" on one green check, losing reasoning when tools change) before the transformed state, and made feature descriptions terminate in observable outcomes.