From 52dbdbb1da2e12c4c52fe5ba10683684e3d9d63e Mon Sep 17 00:00:00 2001 From: bigboateng Date: Tue, 21 Jul 2026 12:58:01 +0100 Subject: [PATCH] design(boatstack): blueprint diagram system + value-first README Reskin mark/portability/journey into a Draft(light)+Cyanotype(dark) blueprint system (grid, registration ticks, drawing title block) via prefers-color-scheme; viewBoxes, labels, arrow paths, and brand hexes unchanged. Reframe the README to lead painful current state -> transformed state and end features in observable value. Contract preserved: 18/18 product-loop tests pass, <=1700 words, 11 claim markers intact. --- .../boatstack-distribution/README.md | 8 +-- .../boatstack-journey.svg | 62 +++++++++++++++---- .../boatstack-distribution/boatstack-mark.svg | 29 ++++++--- .../boatstack-portability.svg | 60 ++++++++++++++---- ...1-blueprint-diagrams-value-first-readme.md | 3 + 5 files changed, 124 insertions(+), 38 deletions(-) create mode 100644 labs/12-product-engineering-loop/boatstack-distribution/release-notes/2026-07-21-blueprint-diagrams-value-first-readme.md diff --git a/labs/12-product-engineering-loop/boatstack-distribution/README.md b/labs/12-product-engineering-loop/boatstack-distribution/README.md index 9a4bc3ac5..a3f972342 100644 --- a/labs/12-product-engineering-loop/boatstack-distribution/README.md +++ b/labs/12-product-engineering-loop/boatstack-distribution/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/labs/12-product-engineering-loop/boatstack-distribution/boatstack-journey.svg b/labs/12-product-engineering-loop/boatstack-distribution/boatstack-journey.svg index c216e17ce..49e08ae5c 100644 --- a/labs/12-product-engineering-loop/boatstack-distribution/boatstack-journey.svg +++ b/labs/12-product-engineering-loop/boatstack-distribution/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/labs/12-product-engineering-loop/boatstack-distribution/boatstack-mark.svg b/labs/12-product-engineering-loop/boatstack-distribution/boatstack-mark.svg index 0b6a27e11..f0fdd778d 100644 --- a/labs/12-product-engineering-loop/boatstack-distribution/boatstack-mark.svg +++ b/labs/12-product-engineering-loop/boatstack-distribution/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/labs/12-product-engineering-loop/boatstack-distribution/boatstack-portability.svg b/labs/12-product-engineering-loop/boatstack-distribution/boatstack-portability.svg index 3c987a970..37a936e88 100644 --- a/labs/12-product-engineering-loop/boatstack-distribution/boatstack-portability.svg +++ b/labs/12-product-engineering-loop/boatstack-distribution/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/labs/12-product-engineering-loop/boatstack-distribution/release-notes/2026-07-21-blueprint-diagrams-value-first-readme.md b/labs/12-product-engineering-loop/boatstack-distribution/release-notes/2026-07-21-blueprint-diagrams-value-first-readme.md new file mode 100644 index 000000000..0a187af22 --- /dev/null +++ b/labs/12-product-engineering-loop/boatstack-distribution/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.