From bcd4f14e0d9fb946cc642d6f157a2f953cc5de23 Mon Sep 17 00:00:00 2001 From: Kailas Mahavarkar <66670953+KailasMahavarkar@users.noreply.github.com> Date: Sat, 18 Jul 2026 15:29:27 +0530 Subject: [PATCH] chore(coherence): deep-pass fixes - stale layers docs, drift-proof persona refs, trigger dedup, changelog Deep coherence pass over the whole system after #126-#134: - skills/hyperstack/SKILL.md: stale 3-persona Layer 4 table KILLED (not updated - updating recreates the drift class); replaced with pointer to the manifest-compiled registry - README: Three-Layer -> Four-Layer Framework; Layer 4 Personas section added; Product & Growth plugin row added; tool count corrected 80 -> 118 (measured by registering all 16 plugins against a counting mock) - summary.md: four-layer phrasing - reflect manifest: 12 overlapping trigger phrasings deduped to 5 canonical (bootstrap 11224 -> 11011 chars) - CHANGELOG: [Unreleased] block covering all 9 unreleased feature PRs - release debt now visible instead of silent Verified live during the pass: audit harness clean (0 major-behind, 0 lint findings), all 5 platform manifests consistent at 1.3.2, Dockerfile persona-absence is not a bug (server runtime never loads personas - compile-time only). 87 tests pass, tsc clean. Known-and-deliberate: ghcr :main image stale while Actions stay disabled; release pin to 1.4.0 left as an explicit user decision. --- CHANGELOG.md | 13 +++++++++++++ README.md | 18 +++++++++++++++--- .../runtime-context/hyperstack.bootstrap.md | 2 +- personas/reflect/persona.json | 17 +++++------------ skills/hyperstack/SKILL.md | 10 ++++------ summary.md | 2 +- 6 files changed, 39 insertions(+), 23 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 077dba0..e712355 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -2,6 +2,19 @@ All notable changes to Hyperstack are documented here. Format follows Keep a Changelog; versioning is SemVer. +## [Unreleased] + +### Added +- **`bro` persona** (4th persona, first generalist, capability): decomposes challenges into sub-problems, solves with the full skill/MCP/web surface, evidence-backed and blunt about heuristics, comment-trimming, quality-proud; scientist-researcher doubt (workspace = a source, not the truth); underdog-genius identity welded to its guardrail; persistence contract with drift repair; controlled subtask dispatch with the 2-minute monitor rule; UI gear-change chain; optional Japanese-learning sidekick (native-usage format, skip list, no repeats). Pressure-tested (RED/GREEN/stay-GREEN). +- **`reflect` generalized + panel mode**: roster 4 -> 8 archetypes (Kenji devtool buyer, Sandra enterprise IT/security, Zoe consumer mobile, Sam screen-reader/accessibility); lens matched to the product's actual buyer; feature review mode (value verdicts, never invented-UI commentary); `reflect_get_panel` tool + panel protocol (relevance-seated lenses, own voices, named collisions, class-owned blocker vetoes). MCP voice contract de-brand-hardcoded. +- **Personas auto-trigger framework**: Personas layer of the bootstrap compiled from `personas//persona.json` manifests (single source of truth - id, mode, description, trigger table); one-framework four-layer declaration; gate semantics hardened (PASS requires evidence, "acting" defined, net-new vs tweak boundary). +- **Token Economy (lite)**: economical prose register in every session's bootstrap with a hard never-compress gate (diagrams/tables, evidence, code, safety warnings); pressure-tested against over-compression. +- **`bro` ecosystem wiring**: harness transitions/router/context-policy entries, bootstrap markers (`bro`, `marketing`, `reflect`, `Triggers:`, `Token Economy`), persistence + falsifiable UTF-8 output bar. + +### Changed +- **`codemode`**: two new Iron Laws - grep for inventory / read for understanding (extraction never replaces reading), and never re-read what is already in context (the context window is the cache). +- README/summary/SKILL docs aligned to the four-layer framework; stale persona tables replaced by pointers to the compiled registry; tool count corrected (118 tools, 16 plugins). + ## [1.3.2] - 2026-06-24 ### Fixed diff --git a/README.md b/README.md index df7b480..fd4a17b 100755 --- a/README.md +++ b/README.md @@ -204,9 +204,9 @@ Node 18+ required. --- -## 🧠 The Three-Layer System +## 🧠 The Four-Layer Framework -Hyperstack's strength comes from the friction between **Ground Truth** (MCP), **Enforcement** (Skills), and **Orchestration** (Agents). +One framework, four layers: **Ground Truth** (MCP), **Enforcement** (Skills), **Orchestration** (Roles), and **Personas** (domain lenses, auto-engaged by trigger). Each persona binds its plugin, skills, and routing through one manifest. ### Layer 1: MCP Plugins (Ground Truth) @@ -218,9 +218,10 @@ Your AI calls these for deterministic data. Memory is not acceptable. Every plug | 🎨 **UI Engine** | `designer`, `design-tokens`, `ui-ux`, `shadcn` | Design Systems, OKLCH, Typography, Accessibility, Component Specs | | ⚛️ **Frontend** | `react`, `reactflow`, `motion`, `lenis` | Next.js 15, RSC, Animation Curves, Smooth Scroll, DAG Layouts | | 🐹 **Backend** | `echo`, `golang`, `rust` | Professional Go Recipes, Rust Borrow Checker patterns, Clean Architecture | +| 📈 **Product & Growth** | `optimizer`, `product-manager`, `marketing`, `reflect` | DSA technique matching, Product risk gates (JTBD, RICE), Positioning & GTM, Target-customer screen/feature review | > [!TIP] -> **80 Tools Total**. Every tool is designed to provide the "Senior Engineer" answer, bypassing the "AI Slop" default. +> **118 tools across 16 plugins**. Every tool is designed to provide the "Senior Engineer" answer, bypassing the "AI Slop" default. ### Layer 2: Skills (Enforcement Teeth) @@ -245,6 +246,17 @@ The internal harness is what ties the public layers together by managing process - `website-builder` specializes in website-facing design and implementation work - roles are internal and auto-called, not user-invoked commands +### Layer 4: Personas (Domain Lenses) + +Domain-expert lenses `hyper` auto-engages when their triggers match the request - the user never has to name them. Each binds an MCP plugin + skills + routing via `personas//persona.json`, and the trigger table is compiled into the session bootstrap from those manifests (single source of truth). + +| Persona | Mode | Lens | +|---|---|---| +| `product-manager` | gate | blocks net-new builds until value + viability risks carry evidence | +| `bro` | capability | generalist execution: decomposition, evidence discipline, code quality | +| `marketing` | capability | positioning, messaging, copy, brand voice, GTM | +| `reflect` | capability | reviews screens and features AS the real target customer (8 archetypes + panel mode) | +
🧱 Core (13) - workflow, discipline, gates used on every task diff --git a/generated/runtime-context/hyperstack.bootstrap.md b/generated/runtime-context/hyperstack.bootstrap.md index fb5d105..bf2deb0 100644 --- a/generated/runtime-context/hyperstack.bootstrap.md +++ b/generated/runtime-context/hyperstack.bootstrap.md @@ -87,7 +87,7 @@ Hyperstack is **ONE framework with four layers** - not four separate systems: - `product-manager` (gate) - Grounds build decisions in validated customer problems (opportunity-vs-solution, four risks, RICE); owns value+viability; blocks net-new build until PASS. Triggers: net-new feature; new product; build request; scope decision. - `bro` (capability) - Triggers: bro or bro mode is named; end-to-end generalist task spanning design, code, and product; ambiguous challenge that needs decomposition before an approach exists; quality-critical build where scale and optimization matter; multi-subtask work needing controlled dispatch and management. - `marketing` (capability) - The product-marketer: positions any brand (Dunford), messages it (StoryBrand/value-prop), writes copy (Schwartz/Cialdini/formulas), sets brand voice, plans GTM/growth. Triggers: position a product or brand; write marketing copy or words; go-to-market or launch; messaging or brand voice; growth or channel strategy; marketing recommendation for an app or website. -- `reflect` (capability) - Reviews a screen OR a feature (shipped or planned) AS a real target customer - 8-lens roster matched to the product's buyer, plus panel mode (own voices, named collisions, blocker vetoes); human, blunt, market-smart; knows a screen react from a feature-value verdict. Triggers: review this screen as a real user; get a persona or stakeholder read on a design; critique this UI as a target customer; would my target buyer approve this screen; pressure-test a design from the buyer side; review as a developer or devtool buyer; review as an enterprise or security buyer; review as a consumer mobile user; review with an accessibility or screen-reader lens; get everyone's read or a panel review of a screen; review a feature or planned feature as the target customer; would my users actually want this feature. +- `reflect` (capability) - Reviews a screen OR a feature (shipped or planned) AS a real target customer - 8-lens roster matched to the product's buyer, plus panel mode (own voices, named collisions, blocker vetoes); human, blunt, market-smart; knows a screen react from a feature-value verdict. Triggers: review a screen or UI as a real user or target customer; get a persona or stakeholder read; pressure-test from the buyer side; review as a specific archetype (developer, enterprise, consumer, accessibility); get everyone's read - a panel review; review a feature or planned feature; would my users actually want this. ## Routing Summary - Every request enters through `hyper` diff --git a/personas/reflect/persona.json b/personas/reflect/persona.json index a89a68c..6758df1 100644 --- a/personas/reflect/persona.json +++ b/personas/reflect/persona.json @@ -11,17 +11,10 @@ }, "engaged_by": "hyper", "engages_when": [ - "review this screen as a real user", - "get a persona or stakeholder read on a design", - "critique this UI as a target customer", - "would my target buyer approve this screen", - "pressure-test a design from the buyer side", - "review as a developer or devtool buyer", - "review as an enterprise or security buyer", - "review as a consumer mobile user", - "review with an accessibility or screen-reader lens", - "get everyone's read or a panel review of a screen", - "review a feature or planned feature as the target customer", - "would my users actually want this feature" + "review a screen or UI as a real user or target customer", + "get a persona or stakeholder read; pressure-test from the buyer side", + "review as a specific archetype (developer, enterprise, consumer, accessibility)", + "get everyone's read - a panel review", + "review a feature or planned feature; would my users actually want this" ] } diff --git a/skills/hyperstack/SKILL.md b/skills/hyperstack/SKILL.md index 86085c9..00d608e 100644 --- a/skills/hyperstack/SKILL.md +++ b/skills/hyperstack/SKILL.md @@ -251,13 +251,11 @@ The bootstrap and orchestrator (`hyper`) choose the correct role based on the re Personas are domain-expert lenses that `hyper` engages for a domain. Two modes: GATE (owns a risk and blocks, e.g. product-manager) and CAPABILITY (produces -domain output, e.g. marketing). Internal and auto-engaged. +domain output, e.g. marketing). Internal and auto-engaged by trigger. -| Persona | Mode | Owns | Engages on | -|---|---|---|---| -| `product-manager` | gate | value + viability product risk | net-new feature/product/scope (hard gate, advisory tweaks, user override) | -| `marketing` | capability | positioning, messaging, copy, brand, GTM | position/launch/name/write-copy/grow a product, app, or website | -| `reflect` | capability | human screen-review as a target-customer persona | "review this screen as a real user", get a stakeholder/persona read, pressure-test a UI from the buyer side | +The roster, modes, descriptions, and trigger table are NOT listed here - they +compile into the bootstrap from `personas//persona.json` (see Persona +Registry below). One source of truth; a table here would drift. ## Persona Registry diff --git a/summary.md b/summary.md index 4e1c93e..341133a 100644 --- a/summary.md +++ b/summary.md @@ -13,7 +13,7 @@ Redefine the relationship between a human developer and an AI coding assistant. ## 🛠️ What We Have Accomplished ### 1. Monorepo Consolidation -Merged two fragmented repositories (`unified-mcp` for data, `unified-skill` for persona) into a single high-cohesion repository. Hyperstack is now a **Three-Layer Ecosystem**: +Merged two fragmented repositories (`unified-mcp` for data, `unified-skill` for persona) into a single high-cohesion repository. Hyperstack is now a **four-layer framework** (Layer 4, Personas, added later): - **Layer 1: Ground Truth (MCP)** - The "Brain": Deterministic data and tools - **Layer 2: Process (Skills)** - The "Body": Disciplined engineering workflows and gates - **Layer 3: Orchestration (Agents)** - The "Nervous System": Internal roles for routing and verification