From c0c6c49f0d6a7a4789708207fbc6ddcab99b1389 Mon Sep 17 00:00:00 2001
From: Kailas Mahavarkar <66670953+KailasMahavarkar@users.noreply.github.com>
Date: Tue, 14 Apr 2026 05:48:28 +0530
Subject: [PATCH 1/2] updated hyperstack

---
 agents/main/CHECKS.md                         |  27 ++
 agents/main/CONTEXT.md                        |  27 ++
 agents/main/LIFECYCLE.md                      |  42 +++
 agents/main/PROFILE.md                        |  46 +++
 agents/website-builder/CHECKS.md              |  32 ++
 agents/website-builder/CONTEXT.md             |  31 ++
 agents/website-builder/LIFECYCLE.md           |  42 +++
 agents/website-builder/PROFILE.md             |  46 +++
 ...026-04-12-hyperstack-excellence-roadmap.md | 280 ++++++++++++++++++
 .../using-hyperstack.bootstrap.md             | 112 +++++++
 harness/context-policy.md                     |  31 ++
 harness/observability.md                      |  19 ++
 harness/router.md                             |  41 +++
 harness/transitions.md                        |  21 ++
 hooks/session-start.mjs                       |  18 +-
 package.json                                  |   1 +
 skills/designer/SKILL.md                      |  61 +++-
 .../website-experience-cheatsheet.md          | 142 +++++++++
 skills/using-hyperstack/SKILL.md              |  44 +++
 src/internal/compile-runtime-context.ts       |  28 ++
 src/internal/context-compiler.ts              | 248 ++++++++++++++++
 tests/context-compiler-behaviour.test.ts      |  26 ++
 tests/role-harness-behaviour.test.ts          |  99 +++++++
 tests/runtime-behaviour.test.ts               |  67 +++++
 24 files changed, 1527 insertions(+), 4 deletions(-)
 create mode 100644 agents/main/CHECKS.md
 create mode 100644 agents/main/CONTEXT.md
 create mode 100644 agents/main/LIFECYCLE.md
 create mode 100644 agents/main/PROFILE.md
 create mode 100644 agents/website-builder/CHECKS.md
 create mode 100644 agents/website-builder/CONTEXT.md
 create mode 100644 agents/website-builder/LIFECYCLE.md
 create mode 100644 agents/website-builder/PROFILE.md
 create mode 100644 docs/research/2026-04-12-hyperstack-excellence-roadmap.md
 create mode 100644 generated/runtime-context/using-hyperstack.bootstrap.md
 create mode 100644 harness/context-policy.md
 create mode 100644 harness/observability.md
 create mode 100644 harness/router.md
 create mode 100644 harness/transitions.md
 create mode 100644 skills/designer/references/website-experience-cheatsheet.md
 create mode 100644 src/internal/compile-runtime-context.ts
 create mode 100644 src/internal/context-compiler.ts
 create mode 100644 tests/context-compiler-behaviour.test.ts
 create mode 100644 tests/role-harness-behaviour.test.ts

diff --git a/agents/main/CHECKS.md b/agents/main/CHECKS.md
new file mode 100644
index 0000000..aac6b69
--- /dev/null
+++ b/agents/main/CHECKS.md
@@ -0,0 +1,27 @@
+# Main Agent Checks
+
+## Preconditions
+
+- Request has been classified
+- Required specialist routing decision is explicit
+- Required gates are known
+
+## Required Evidence
+
+- Why the request stayed with `main` or routed to a specialist
+- What workspace/package evidence informed that routing decision
+- What MCP or skill gates were required
+- What verification command proves any completion claim
+
+## Done Criteria
+
+- Correct role selected
+- Specialist handoff or direct execution stayed within scope
+- Verification ownership remained with `main`
+
+## Red Flags
+
+- `main` doing specialist website work without delegation logic
+- Silent scope widening
+- Completion claims without evidence
+- Routing directly from user request to a specialist without `main`
diff --git a/agents/main/CONTEXT.md b/agents/main/CONTEXT.md
new file mode 100644
index 0000000..642a4db
--- /dev/null
+++ b/agents/main/CONTEXT.md
@@ -0,0 +1,27 @@
+# Main Agent Context Policy
+
+## Hot Context
+
+- Current user request
+- Active design or plan status
+- Global Hyperstack invariants
+- Required MCP-first rules
+- Role routing and transition rules
+
+## Warm Context
+
+- Relevant skill contracts
+- Recent verification results
+- Current diff or changed surface summary
+
+## Cold Context
+
+- Deep reference docs
+- Large examples
+- Historical research notes
+
+## Never Load
+
+- Entire reference forests unless required
+- Unrelated plugin docs
+- Full large files when a targeted slice is enough
diff --git a/agents/main/LIFECYCLE.md b/agents/main/LIFECYCLE.md
new file mode 100644
index 0000000..14a9d76
--- /dev/null
+++ b/agents/main/LIFECYCLE.md
@@ -0,0 +1,42 @@
+# Main Agent Lifecycle
+
+## Entry Criteria
+
+- A new user request exists
+- Hyperstack bootstrap is active
+- No other internal role currently owns the request lifecycle
+
+## Steps
+
+1. Read the request and inspect the workspace before routing
+2. Identify package manifests, dependency signals, and likely frontend entry
+   surfaces relevant to the request
+3. Classify the work using both the request and the workspace reality
+4. Determine whether a specialist role is required
+5. Enforce MCP-first and design/plan gates before implementation
+6. Route website-facing work to `website-builder`
+7. Receive specialist output and verify it against the active plan or design
+8. Run review, verification, and ship gates
+9. Deliver the result or report blockers with evidence
+
+## Handoffs
+
+- `main -> website-builder` for website pages, landing pages, dashboards,
+  redesigns, and website-experience-heavy UI work
+- `website-builder -> main` after specialist design or implementation output is
+  ready for review and verification
+
+## Exit Criteria
+
+- A specialist has been selected and briefed, or
+- `main` has completed the request itself, or
+- `main` has blocked safely and reported the blocker with evidence
+
+## Failure Escalation
+
+- If classification is ambiguous, default to `main` and require explicit
+  delegation criteria before specialist routing
+- If a specialist widens scope or attempts to self-ship, reclaim control and
+  route back through verification
+- If verification fails, route to the appropriate corrective path before any
+  completion claim
diff --git a/agents/main/PROFILE.md b/agents/main/PROFILE.md
new file mode 100644
index 0000000..e5208a1
--- /dev/null
+++ b/agents/main/PROFILE.md
@@ -0,0 +1,46 @@
+---
+name: main
+kind: core
+auto_invoke_when:
+  - every user request
+  - any task that requires classification, orchestration, verification, or delivery
+owns:
+  - request classification
+  - internal role routing
+  - gate enforcement
+  - lifecycle transitions
+  - final verification
+  - delivery orchestration
+must_not_do:
+  - silently bypass required specialists
+  - skip MCP-first grounding
+  - allow completion claims without verification evidence
+delegates_to:
+  - website-builder
+requires:
+  - current bootstrap invariants from using-hyperstack
+  - approved design before implementation when required
+  - verification evidence before completion or delivery
+---
+
+# Main Agent Profile
+
+## Mission
+
+`main` is Hyperstack's conductor. It owns request classification, internal role
+routing, gate enforcement, lifecycle transitions, and final verification.
+
+## Authority
+
+- Receives every user request first
+- Decides whether the work stays with `main` or routes to a specialist
+- Reuses existing Hyperstack skills and MCP plugins as the execution substrate
+- Owns final review, ship-gate, and delivery authority
+
+## Boundaries
+
+`main` does not exist to absorb all work. It delegates specialist work when the
+request is clearly in a specialist domain.
+
+For website-facing work, `main` routes to `website-builder` and later regains
+control for review, verification, and delivery.
diff --git a/agents/website-builder/CHECKS.md b/agents/website-builder/CHECKS.md
new file mode 100644
index 0000000..6272a48
--- /dev/null
+++ b/agents/website-builder/CHECKS.md
@@ -0,0 +1,32 @@
+# Website Builder Checks
+
+## Preconditions
+
+- Delegation from `main` exists
+- Website-facing scope is explicit
+- Required design/plan gate is active
+
+## Required Evidence
+
+- The package manifests and dependency signals that describe the active frontend stack
+- The core frontend file map for the active surface: routes, layouts, major
+  components, styles, tokens, navigation
+- What primary user task the page or flow serves
+- CTA hierarchy and page structure decisions
+- State coverage for loading, empty, error, success, disabled, or destructive states
+- Responsive and accessibility implications
+- MCP-backed grounding for stack-specific implementation choices
+
+## Done Criteria
+
+- Workspace and frontend inventory are explicit and tied to the delegated task
+- Website-facing scope completed without widening
+- Specialist output is ready for `main` to review
+- No shipping or completion claim made directly by `website-builder`
+
+## Red Flags
+
+- Acting like a generic frontend builder instead of a website specialist
+- Implementing outside delegated scope
+- Missing state coverage or CTA hierarchy
+- Claiming completion without handing back to `main`
diff --git a/agents/website-builder/CONTEXT.md b/agents/website-builder/CONTEXT.md
new file mode 100644
index 0000000..f7010f1
--- /dev/null
+++ b/agents/website-builder/CONTEXT.md
@@ -0,0 +1,31 @@
+# Website Builder Context Policy
+
+## Hot Context
+
+- Current delegated website task
+- Workspace inventory for the active website surface
+- Relevant package manifests and dependency signals
+- Core frontend files for the active page or flow
+- Relevant page intent and audience
+- Active website-specific design constraints
+- Relevant website-experience checklist items
+- Targeted MCP outputs for design, UI/UX, tokens, motion, and stack choices
+
+## Warm Context
+
+- Approved `DESIGN.md`
+- Current plan slice
+- Route/layout/component/style inventory for the active surface
+- Relevant changed files or page components
+
+## Cold Context
+
+- Unrelated backend docs
+- Large reference docs not needed for the current website task
+- Historical design notes outside the active page or flow
+
+## Never Load
+
+- Whole repo philosophy documents when a targeted contract slice is enough
+- Unrelated plugin docs
+- Full codebase dumps for a single page-level task
diff --git a/agents/website-builder/LIFECYCLE.md b/agents/website-builder/LIFECYCLE.md
new file mode 100644
index 0000000..5347d13
--- /dev/null
+++ b/agents/website-builder/LIFECYCLE.md
@@ -0,0 +1,42 @@
+# Website Builder Lifecycle
+
+## Entry Criteria
+
+- `main` has classified the request as website-facing work
+- Delegation to `website-builder` is explicit
+- Required design or planning gate is active
+
+## Steps
+
+1. Read the user workspace before making website decisions
+2. Inspect package manifests and dependencies (`package.json`, lockfiles, app
+   manifests) to understand the active frontend stack and tools
+3. Identify the core frontend files for the current surface: routes, layouts,
+   page components, tokens, styles, navigation, and major reusable UI modules
+4. Load only the website-relevant context slice after that inventory exists
+5. Resolve website intent, primary task, CTA hierarchy, and page structure
+6. Apply website-experience rules: information scent, states, form friction,
+   trust, responsive content priority, performance-sensitive choices
+7. Produce or refine website design outputs such as `DESIGN.md`
+8. Implement website-facing code only when delegated and within scope
+9. Return a specialist result package to `main` with evidence
+
+## Handoffs
+
+- `main -> website-builder` when the request is website-facing
+- `website-builder -> main` after specialist output is ready for review and
+  verification
+
+## Exit Criteria
+
+- Website-specific design or implementation output is complete for the delegated
+  scope
+- The workspace inventory is explicit: packages, stack, and core frontend files
+  are known
+- Required evidence is attached for `main` to verify
+
+## Failure Escalation
+
+- If the task drifts outside website-facing work, stop and hand back to `main`
+- If design or plan gates are missing, stop and hand back to `main`
+- If verification or shipping is requested, stop and hand back to `main`
diff --git a/agents/website-builder/PROFILE.md b/agents/website-builder/PROFILE.md
new file mode 100644
index 0000000..92ef043
--- /dev/null
+++ b/agents/website-builder/PROFILE.md
@@ -0,0 +1,46 @@
+---
+name: website-builder
+kind: specialist
+auto_invoke_when:
+  - landing pages
+  - dashboards
+  - marketing sites
+  - website redesigns
+  - website-experience-heavy page work
+owns:
+  - website-specific design work
+  - website-specific implementation work when delegated
+  - page structure and CTA hierarchy
+  - website experience quality
+must_not_do:
+  - self-ship
+  - bypass main
+  - widen scope outside website-facing work
+delegates_to:
+  - main
+requires:
+  - delegation from main
+  - active design and plan gates from Hyperstack
+  - MCP-first grounding for website stack choices
+---
+
+# Website Builder Profile
+
+## Mission
+
+`website-builder` is Hyperstack's first specialist role. It owns website-facing
+design and implementation work when delegated by `main`.
+
+## Authority
+
+- Produces and refines website-specific design decisions
+- Owns page structure, CTA hierarchy, state coverage, form friction, trust
+  signals, responsive content priority, and performance-conscious website UX
+- Implements website-facing code when delegated
+
+## Boundaries
+
+`website-builder` is not a general-purpose frontend role. It is specifically for
+website work and website experience.
+
+`website-builder` must always hand back to `main` for verification and delivery.
diff --git a/docs/research/2026-04-12-hyperstack-excellence-roadmap.md b/docs/research/2026-04-12-hyperstack-excellence-roadmap.md
new file mode 100644
index 0000000..27ab919
--- /dev/null
+++ b/docs/research/2026-04-12-hyperstack-excellence-roadmap.md
@@ -0,0 +1,280 @@
+# Hyperstack Excellence Roadmap
+
+## Goal
+
+Evolve Hyperstack into an AI-designer and AI-coder framework that is:
+
+- grounded in deterministic MCP data
+- disciplined enough to actually follow its workflows
+- strong on website experience, not only visual style
+- tested against real agent failure modes, not just happy-path tool outputs
+
+## Executive Summary
+
+Hyperstack already has stronger semantic grounding than most agent frameworks.
+Its designer, design-token, UI/UX, shadcn, React Flow, Motion, Lenis, Echo, Go,
+and Rust plugins make it unusually good at producing domain-aware outputs.
+
+What it lacks relative to Superpowers is enforcement confidence. Hyperstack has
+good gates, but weaker proof that agents actually obey them under realistic
+prompts.
+
+What it lacks relative to the VoltAgent ecosystem is ecosystem leverage:
+
+- large-scale skill and subagent pattern curation
+- design-contract libraries at scale
+- clearer interoperability and packaging patterns
+- stronger observability and evaluation framing
+
+## Current Position
+
+### Hyperstack Strengths
+
+- Strong MCP-first philosophy
+- Excellent `DESIGN.md` contract idea
+- Programmatic compliance checking via `designer_verify_implementation`
+- Better domain depth than generic workflow-only systems
+- Good anti-slop language and visual quality bias
+
+### Hyperstack Weaknesses
+
+- Limited regression tests for skill triggering and premature action
+- Limited enforcement tests for cross-harness bootstrap behavior
+- Website experience guidance is under-specified compared to visual styling
+- Design and implementation document review is weaker than it should be
+- Limited observability and evaluation surfaces for skill adherence
+
+## What to Learn from Superpowers
+
+Source repo:
+
+- https://github.com/obra/superpowers
+
+### 1. Test the Enforcement, Not Just the Output
+
+Superpowers directly tests:
+
+- naive prompt -> expected skill trigger
+- explicit skill request -> expected skill trigger
+- no tool use before skill invocation
+- multi-step workflow integration in realistic sandboxes
+
+Hyperstack should add:
+
+- `tests/skill-triggering/`
+- `tests/explicit-skill-requests/`
+- premature-action detection in logs
+- at least one end-to-end workflow test for:
+  - visual request -> `designer` -> `forge-plan`
+  - backend request -> `blueprint` -> `forge-plan`
+
+### 2. Treat Bootstrap as Product Infrastructure
+
+Superpowers invests heavily in making bootstrap unavoidable across harnesses.
+Hyperstack should improve:
+
+- Codex-specific bootstrap/install guidance
+- OpenCode bootstrap path
+- startup tests for every supported harness
+
+### 3. Separate Workflow Discipline from Domain Knowledge
+
+Superpowers is very strong at:
+
+- brainstorming
+- planning
+- TDD
+- debugging
+- review
+- branch completion
+
+Hyperstack should keep its domain depth, but borrow stronger workflow evals and
+document-review loops.
+
+## What to Learn from VoltAgent
+
+Key current repos:
+
+- https://github.com/orgs/VoltAgent/repositories?type=all
+- https://github.com/VoltAgent/voltagent
+- https://github.com/VoltAgent/awesome-design-md
+- https://github.com/VoltAgent/awesome-agent-skills
+- https://github.com/VoltAgent/awesome-claude-code-subagents
+- https://github.com/VoltAgent/awesome-codex-subagents
+- https://github.com/VoltAgent/vercel-ai-sdk-observability
+
+### 1. DESIGN.md as a Distribution Format
+
+VoltAgent's `awesome-design-md` validates that design contracts are now a
+portable ecosystem artifact, not just an internal trick.
+
+Hyperstack opportunity:
+
+- ship a curated library of Hyperstack-native DESIGN.md exemplars
+- provide quality-scored examples by industry and page type
+- add "reference designs" users can adopt before customization
+
+### 2. Skill and Subagent Interoperability
+
+VoltAgent's skills and subagent repos show that discoverability, path
+conventions, packaging, and naming matter.
+
+Hyperstack opportunity:
+
+- formalize compatibility targets by harness
+- publish a clearer "skill ABI" and "subagent ABI"
+- document path conventions and install surfaces like a platform, not a repo
+
+### 3. Observability Matters
+
+VoltAgent's observability work suggests a missing layer for Hyperstack:
+
+- trace which skills fired
+- trace which MCP tools were used
+- trace whether required gates were skipped
+- collect evaluation fixtures for agent behavior quality
+
+Hyperstack opportunity:
+
+- add lightweight execution traces for:
+  - bootstrap injection
+  - required skill invocation
+  - MCP tool usage before code generation
+  - verification before completion
+
+### 4. Ecosystem Curation Beats Reinvention
+
+VoltAgent's awesome lists prove that the ecosystem is a source of reusable
+patterns, not noise.
+
+Hyperstack opportunity:
+
+- curate approved external design references
+- curate approved external skills and subagents
+- maintain a security review note for third-party imports
+
+## What to Learn from Website Experience Standards
+
+Key sources:
+
+- https://web.dev/articles/lcp
+- https://web.dev/inp/
+- https://web.dev/optimize-cls
+- https://web.dev/articles/rendering-performance
+- https://web.dev/articles/codelab-address-form-best-practices
+- https://www.w3.org/TR/WCAG22/
+- https://www.w3.org/WAI/WCAG22/Understanding/target-size-minimum.html
+- https://www.w3.org/WAI/WCAG21/Understanding/target-size.html
+- https://www.w3.org/WAI/WCAG22/Understanding/focus-not-obscured-minimum.html
+- https://www.w3.org/WAI/WCAG22/Understanding/accessible-authentication-minimum.html
+- https://www.w3.org/WAI/WCAG22/Understanding/dragging-movements
+- https://developer.mozilla.org/en-US/docs/Web/CSS/@media/prefers-reduced-motion
+- https://www.nngroup.com/videos/mobile-images/
+
+### Hyperstack Must Treat These as Design Inputs
+
+- Core Web Vitals are website experience, not just engineering metrics:
+  - LCP <= 2.5s
+  - INP <= 200ms
+  - CLS <= 0.1
+- Website experience includes:
+  - information scent
+  - CTA hierarchy
+  - task flow clarity
+  - form friction
+  - error recovery
+  - accessible authentication
+  - focus safety
+  - target sizing
+  - reduced motion
+  - responsive content priority
+
+## Recommended Roadmap
+
+### Phase 1 - Enforcement Hardening
+
+Target: Make Hyperstack provably harder to bypass.
+
+Add:
+
+- skill-triggering tests modeled on Superpowers
+- explicit skill request tests
+- premature-action tests
+- bootstrap tests for supported harnesses
+
+Files to add:
+
+- `tests/skill-triggering/`
+- `tests/explicit-skill-requests/`
+- `tests/harness-bootstrap/`
+
+### Phase 2 - Website Experience as First-Class Design
+
+Target: Upgrade `designer` from visual style engine to website experience engine.
+
+Add:
+
+- website-experience reference material
+- explicit website-experience checklist in `designer`
+- stronger `DESIGN.md` requirements for:
+  - state coverage
+  - CTA hierarchy
+  - auth friction
+  - performance budgets
+  - responsive content priority
+
+### Phase 3 - Spec and Plan Review Systems
+
+Target: Catch bad design docs and bad plans before execution.
+
+Add:
+
+- `designer_review_design_md`
+- `forge-plan` document review loop
+- tests with intentionally bad specs and plans
+
+### Phase 4 - Observability and Eval Layer
+
+Target: Know whether Hyperstack is being followed in reality.
+
+Add:
+
+- skill invocation traces
+- MCP usage traces
+- compliance summaries
+- harness-specific eval fixtures
+
+Potential outputs:
+
+- machine-readable gate events
+- eval dashboards
+- regression fixtures for prompts that commonly bypass discipline
+
+### Phase 5 - Curated Design and Subagent Libraries
+
+Target: Make good defaults easy to start from.
+
+Add:
+
+- `examples/design-md/` library
+- `examples/subagents/` library
+- quality-scored starter packs by industry and stack
+
+## Immediate Action Items
+
+1. Add skill-trigger and premature-action tests.
+2. Expand `designer` with website-experience requirements.
+3. Add design/plan review loops before implementation.
+4. Add lightweight observability around gate adherence.
+5. Publish a curated set of Hyperstack-native DESIGN.md exemplars.
+
+## Success Criteria
+
+Hyperstack is "excellent" when:
+
+- agents reliably invoke the right skill before acting
+- agents use MCP tools before stack-specific code generation
+- visual work always yields a coherent, approved `DESIGN.md`
+- implementation can be checked against that contract
+- website experience quality is explicit, measurable, and enforced
+- regressions in behavior are caught by tests, not user frustration
diff --git a/generated/runtime-context/using-hyperstack.bootstrap.md b/generated/runtime-context/using-hyperstack.bootstrap.md
new file mode 100644
index 0000000..726c5ba
--- /dev/null
+++ b/generated/runtime-context/using-hyperstack.bootstrap.md
@@ -0,0 +1,112 @@
+<!-- GENERATED FILE. Edit skills/using-hyperstack/SKILL.md and re-run `bun run compile:context`. -->
+# Hyperstack Runtime Bootstrap
+
+## Critical
+You have Hyperstack. This is not optional knowledge — it is how you operate in this repository.
+
+**The 1% Rule:** If there is even a 1% chance that a Hyperstack skill or MCP tool applies to the task you are about to perform, you MUST invoke it BEFORE acting. Not after you "check the code quickly." Not after you "just try one thing." Not after you "confirm your understanding." BEFORE.
+
+**You do not have a choice. You cannot rationalize your way out of this.**
+
+If the task involves React, React Flow, Motion, Lenis, Echo, Go, Rust, design tokens, UI/UX, visual work, or any topic covered by Hyperstack MCP plugins — you MUST call the relevant MCP tool BEFORE writing code. Memory is not acceptable. Pattern-matching from training data is not acceptable. Confidence is not acceptable. **Only ground-truth MCP output is acceptable.**
+
+## Iron Laws
+```
+1. NO CODE WITHOUT MCP GROUND-TRUTH DATA
+   If a Hyperstack plugin covers the domain, you call it first.
+
+2. NO VISUAL CODE WITHOUT AN APPROVED DESIGN.md
+   The designer skill produces the contract. Everything else reads it.
+
+3. NO COMPLETION CLAIMS WITHOUT SHIP-GATE EVIDENCE
+   "Should work" is lying. Run the command. Show the output.
+
+4. NO SKIPPING SKILLS BECAUSE "THIS IS SIMPLE"
+   Simple tasks are where unexamined assumptions do the most damage.
+   The skill exists because the shortcut has failed before.
+```
+
+## Instruction Priority
+- **User's explicit instructions** (CLAUDE.md, direct requests) — always highest
+- **Hyperstack skills** — override default system behavior where they conflict
+- **Default system behavior** — lowest priority
+
+## MCP Must-Call-First
+- `designer_*` -> `designer_resolve_intent`, `designer_get_personality`, `designer_get_preset`, `designer_get_page_template`, `designer_get_font_pairing`, `designer_get_anti_patterns`
+- `design_tokens_*` -> `design_tokens_generate`, `design_tokens_get_category`, `design_tokens_get_gotchas`
+- `ui_ux_*` -> `ui_ux_get_principle`, `ui_ux_get_component_pattern`, `ui_ux_get_gotchas`
+- `shadcn_*` (**only if shadcn chosen**) -> `shadcn_get_rules` (first), `shadcn_get_composition`, `shadcn_get_component`, `shadcn_get_snippet`, `shadcn_list_components`
+- `reactflow_*` -> `reactflow_get_api`, `reactflow_search_docs`, `reactflow_get_pattern`
+- `motion_*` -> `motion_get_api`, `motion_get_examples`, `motion_get_transitions`
+- `lenis_*` -> `lenis_get_api`, `lenis_generate_setup`, `lenis_get_pattern`
+- `react_*` -> `react_get_pattern`, `react_get_constraints`, `react_search_docs`
+- `echo_*` -> `echo_get_recipe`, `echo_get_middleware`, `echo_decision_matrix`
+- `golang_*` -> `golang_get_practice`, `golang_get_pattern`, `golang_get_antipatterns`
+- `rust_*` -> `rust_get_practice`, `rust_cheatsheet`, `rust_search_docs`
+
+## Workflow Skills
+- `hyperstack:blueprint`: Before any feature build — MCP survey, design gate, negative doubt
+- `hyperstack:designer`: Before any visual/UX work — produces DESIGN.md contract
+- `hyperstack:forge-plan`: After design approval — MCP-verified implementation plan
+- `hyperstack:run-plan`: Have an existing plan — validate then execute
+- `hyperstack:engineering-discipline`: During execution — Senior SDE phase gates
+- `hyperstack:ship-gate`: Before any completion claim — evidence required
+- `hyperstack:deliver`: After all tasks complete — final verification and delivery
+- `hyperstack:autonomous-mode`: Full autonomous execution — runs end-to-end, only stops on failure
+- `hyperstack:subagent-ops`: Plans with independent tasks — fresh agent per task, two-stage review
+- `hyperstack:test-first`: Before writing any implementation code — red-green-refactor
+- `hyperstack:worktree-isolation`: Before feature work — clean workspace isolation
+- `hyperstack:code-review`: After completing tasks — dispatch reviewer subagent
+- `hyperstack:parallel-dispatch`: 2+ independent failures or tasks — concurrent agent dispatch
+- `hyperstack:designer`: Before any visual/UX work — produces DESIGN.md
+- `hyperstack:debug-discipline`: Any bug or unexpected behaviour — root cause first
+- `hyperstack:behaviour-analysis`: UI/UX audits, state machine correctness
+- `hyperstack:design-patterns-skill`: Selecting the right abstraction or design pattern
+- `hyperstack:security-review`: OWASP audits, API and infrastructure security
+- `hyperstack:readme-writer`: Evidence-based documentation
+
+## Internal Roles
+- Roles are internal and auto-called. Users do not invoke them directly.
+- `main` — conductor, classifier, gatekeeper, verifier, and delivery owner
+- `website-builder` — first specialist for website-facing design and
+
+## Routing Summary
+- Every request enters through `main`
+- `main` inspects the workspace first: package manifests, dependency signals,
+- `main -> website-builder` for website-facing work: landing pages, dashboards,
+- `website-builder -> main` after specialist output is ready for review and
+- If classification is ambiguous, stay in `main`
+
+## Allowed Transitions
+- `user request -> main`
+- `main -> website-builder`
+- `website-builder -> main`
+- `main -> existing Hyperstack skills/plugins`
+- `main -> verification and delivery gates`
+
+## Disallowed Transitions
+- `user request -> website-builder`
+- `website-builder -> ship`
+- `website-builder -> deliver`
+- `website-builder` claiming final completion directly
+
+## High-Signal Red Flags
+- "I know this React Flow API from memory" -> Memory drifts. v11 and v12 are different.
+- "This is a simple animation" -> Simple animations need `prefers-reduced-motion`, correct easing, and GPU-only properties
+- "Go error handling is straightforward" -> Straightforward code is where anti-patterns ship
+- "I'll check docs after I write it" -> You will ship before you check. Every time.
+- "I know the OKLCH token pattern" -> OKLCH has specific rules about alpha, chroma peaks, dark mode lightness
+- "This pattern looks common, I'll adapt it" -> Adaptation hides drift
+
+## Degraded Mode
+- If MCP unavailable, tell the user explicitly: "MCP unavailable" and flag answers as uncertain.
+
+## Announcement Rule
+- Before invoking any Hyperstack skill, announce it with the exact format and purpose so the user can audit it.
+
+## Final Check
+- [ ] Did I check whether any Hyperstack skill applies to this task? (1% rule)
+- [ ] Did I call any relevant MCP tool for ground-truth data? (memory is not acceptable)
+- [ ] If this involves visual work, did I invoke designer BEFORE writing any code?
+- [ ] If I'm claiming something is done, did I run the verification command THIS message?
+- [ ] Did I announce every skill invocation with the exact format?
diff --git a/harness/context-policy.md b/harness/context-policy.md
new file mode 100644
index 0000000..f246306
--- /dev/null
+++ b/harness/context-policy.md
@@ -0,0 +1,31 @@
+# Harness Context Policy
+
+## Principle
+
+Each internal role should load only the context slice it needs.
+
+## Role Slices
+
+- `main`
+  - classification, routing, gates, verification, delivery
+- `website-builder`
+  - workspace inventory
+  - package manifests and dependency signals
+  - core frontend files for the active surface
+  - website intent, page structure, website-experience constraints, website code
+
+## Tiers
+
+- Hot
+  - current task
+  - active role contract
+  - active design/plan slice
+- Warm
+  - targeted skill or MCP outputs
+  - changed surface summary
+- Cold
+  - deep references and examples
+- Never load by default
+  - unrelated plugin docs
+  - whole reference forests
+  - full repo dumps for narrow tasks
diff --git a/harness/observability.md b/harness/observability.md
new file mode 100644
index 0000000..66660b0
--- /dev/null
+++ b/harness/observability.md
@@ -0,0 +1,19 @@
+# Harness Observability
+
+## V1 Event Contract
+
+Future harness traces should emit these event names:
+
+- `request_classified`
+- `role_selected`
+- `role_handoff`
+- `required_skill_invoked`
+- `required_mcp_tool_invoked`
+- `verification_gate_entered`
+- `verification_gate_passed`
+- `verification_gate_failed`
+
+## V1 Scope
+
+No external telemetry backend is required in v1. This file defines the event
+contract so future traces and tests can rely on stable names.
diff --git a/harness/router.md b/harness/router.md
new file mode 100644
index 0000000..4b8639c
--- /dev/null
+++ b/harness/router.md
@@ -0,0 +1,41 @@
+# Harness Router
+
+## Default Rule
+
+Every user request enters through `main`.
+
+Users do not invoke internal roles directly. Roles are internal and auto-called.
+
+## Routing Matrix
+
+Route `main -> website-builder` when the request is primarily about:
+
+- landing pages
+- dashboards
+- marketing or product websites
+- page redesigns
+- website page structure
+- CTA hierarchy
+- trust signals
+- form friction
+- responsive content priority
+- "make the website/page feel better" style requests
+
+Before routing, `main` must inspect the workspace enough to know:
+
+- which package manifests and dependency signals define the active frontend stack
+- which core frontend files likely own the affected surface
+- whether the request is actually website-facing rather than generic frontend or
+  backend work
+
+Keep work in `main` when the request is primarily about:
+
+- backend or infra
+- pure MCP/plugin behavior
+- verification, review, or delivery
+- non-website specialist domains not yet modeled as roles
+
+## Safety Rule
+
+If the request is ambiguous, keep ownership in `main` until delegation criteria
+are explicit.
diff --git a/harness/transitions.md b/harness/transitions.md
new file mode 100644
index 0000000..2306775
--- /dev/null
+++ b/harness/transitions.md
@@ -0,0 +1,21 @@
+# Harness Transitions
+
+## Allowed
+
+- `user request -> main`
+- `main -> website-builder`
+- `website-builder -> main`
+- `main -> existing Hyperstack skills/plugins`
+- `main -> verification and delivery gates`
+
+## Disallowed
+
+- `user request -> website-builder`
+- `website-builder -> ship`
+- `website-builder -> deliver`
+- `website-builder` claiming final completion directly
+
+## V1 Principle
+
+The new role harness is layered on top of the current Hyperstack skills and MCP
+plugins. It does not replace them in v1.
diff --git a/hooks/session-start.mjs b/hooks/session-start.mjs
index f35b6df..62a738e 100644
--- a/hooks/session-start.mjs
+++ b/hooks/session-start.mjs
@@ -12,9 +12,21 @@ function emit(payload) {
 }
 
 try {
-  const skillPath = join(pluginRoot, "skills", "using-hyperstack", "SKILL.md");
-  const skillContent = readFileSync(skillPath, "utf8");
-  const sessionContext = `<EXTREMELY_IMPORTANT>\nYou have Hyperstack.\n\n**Below is the full content of your 'hyperstack:using-hyperstack' skill - your introduction to using Hyperstack. For all other skills, use the 'Skill' tool:**\n\n${skillContent}\n</EXTREMELY_IMPORTANT>`;
+  const compiledBootstrapPath = join(pluginRoot, "generated", "runtime-context", "using-hyperstack.bootstrap.md");
+  const fallbackSkillPath = join(pluginRoot, "skills", "using-hyperstack", "SKILL.md");
+
+  let bootstrapContent;
+  let bootstrapLabel;
+
+  try {
+    bootstrapContent = readFileSync(compiledBootstrapPath, "utf8");
+    bootstrapLabel = "compiled runtime bootstrap";
+  } catch {
+    bootstrapContent = readFileSync(fallbackSkillPath, "utf8");
+    bootstrapLabel = "full content of your 'hyperstack:using-hyperstack' skill";
+  }
+
+  const sessionContext = `<EXTREMELY_IMPORTANT>\nYou have Hyperstack.\n\n**Below is the ${bootstrapLabel} - your introduction to using Hyperstack. For all other skills, use the 'Skill' tool:**\n\n${bootstrapContent}\n</EXTREMELY_IMPORTANT>`;
 
   if (process.env.CURSOR_PLUGIN_ROOT) {
     emit({ additional_context: sessionContext });
diff --git a/package.json b/package.json
index a51ee53..1e0bd89 100644
--- a/package.json
+++ b/package.json
@@ -8,6 +8,7 @@
   "type": "module",
   "scripts": {
     "build": "tsc --noEmit",
+    "compile:context": "bun src/internal/compile-runtime-context.ts",
     "test": "bun test",
     "start": "bun src/index.ts",
     "dev": "bun --watch src/index.ts"
diff --git a/skills/designer/SKILL.md b/skills/designer/SKILL.md
index fac5e63..bb6afd3 100644
--- a/skills/designer/SKILL.md
+++ b/skills/designer/SKILL.md
@@ -38,6 +38,7 @@ activation:
     - ux
 references:
   - references/design-md-template.md
+  - references/website-experience-cheatsheet.md
   - examples/saas-dashboard.md
   - examples/developer-tool.md
   - examples/ecommerce-checkout.md
@@ -155,12 +156,68 @@ These are the rationalizations you will have when you want to skip this skill. E
 
 ---
 
+## Website Experience Non-Negotiables
+
+Visual quality is necessary, but it is not sufficient. Hyperstack designs must also
+produce good website experience under real usage. A page that "looks premium" but is
+slow, confusing, inaccessible, or conversion-hostile is a failed design.
+
+Every DESIGN.md must explicitly resolve these seven questions. If any are missing,
+the design is incomplete:
+
+1. **Primary path** - What is the user's main job-to-be-done on this page, and what
+   is the single primary action?
+2. **Information scent** - Can the user quickly answer "Where am I, what can I do,
+   and what happens next?"
+3. **State coverage** - What do loading, empty, error, success, disabled, and
+   destructive states look like?
+4. **Form and auth friction** - Are labels persistent, validation humane, paste
+   allowed, and password managers supported?
+5. **Performance budget** - What are the target budgets for LCP, INP, CLS, and
+   payload-sensitive media?
+6. **Accessibility floor** - How are focus visibility, focus not obscured, target
+   size, reduced motion, and keyboard usage handled?
+7. **Responsive content priority** - What survives first on mobile, and what gets
+   de-emphasized or deferred?
+
+Use [website-experience-cheatsheet](references/website-experience-cheatsheet.md)
+while resolving these.
+
+**Do not let visual style erase usability.**
+
+## User Preferences Override Defaults
+
+Auto-resolved defaults, presets, and recommendations are starting points only.
+They are not allowed to override explicit user preferences, brand language,
+existing workspace conventions, or product constraints.
+
+Priority order for visual decisions:
+
+1. Explicit user preferences and constraints
+2. Existing workspace reality (current framework, component library, design
+   system, tokens, and major frontend patterns)
+3. Approved product or brand requirements
+4. Designer auto-resolved defaults and presets
+
+If a user says "use these colors", "keep our current design system", "match this
+existing app shell", or "do not use shadcn", that preference wins even if the
+auto-resolved defaults would suggest something else.
+
+Treat auto-resolved defaults as suggestions to confirm or replace, never as
+authority.
+
 # PHASE 1: INTENT EXTRACTION
 
 Two modes. Default to **Base** unless user says "advanced" or "detailed."
 
 ## Base Mode (3 Questions + Confirm)
 
+**Step 0:** If this is an existing project, inspect the workspace first:
+- identify framework and package manifests
+- identify current component library and token system
+- identify core frontend files for the active surface
+- identify any explicit visual preferences already encoded in the repo
+
 **Step 1:** Call `designer_resolve_intent` with product description. Auto-detects: industry, personality, style, mode, density, color mood, must-haves, never-uses.
 
 **Step 2:** Ask 3 essential questions:
@@ -171,7 +228,9 @@ Two modes. Default to **Base** unless user says "advanced" or "detailed."
 | 2 | Brand color? (hex, name, or "generate") | Can't guess someone's brand |
 | 3 | What sections/pages to build? | What to implement |
 
-**Step 3:** Present auto-resolved defaults AND suggest a preset. Offer: *"Say 'advanced' for full control, or pick a preset to start from."*
+**Step 3:** Present auto-resolved defaults as suggestions, not decisions. Explicitly
+ask whether any user preferences or existing workspace patterns should override
+them. Then offer: *"Say 'advanced' for full control, or pick a preset to start from."*
 
 ## Presets (Fast Start)
 
diff --git a/skills/designer/references/website-experience-cheatsheet.md b/skills/designer/references/website-experience-cheatsheet.md
new file mode 100644
index 0000000..c747cc3
--- /dev/null
+++ b/skills/designer/references/website-experience-cheatsheet.md
@@ -0,0 +1,142 @@
+# Website Experience Cheatsheet
+
+Use this when designing pages, flows, and components that must work well as
+websites, not just look polished in screenshots.
+
+This reference is intentionally cross-cutting. These rules should influence
+multiple DESIGN.md sections, especially Components, Motion, Do's and Don'ts,
+Responsive, and Anti-Patterns.
+
+## 1. Orientation and Information Scent
+
+- The first viewport should make the page's purpose obvious.
+- Users should quickly understand:
+  - where they are
+  - what they can do
+  - what happens next
+- Navigation labels should use user language, not internal team vocabulary.
+- Each page or section should have one primary action with stronger visual weight
+  than secondary actions.
+- Avoid decorative hero sections that delay comprehension or hide the real task.
+
+## 2. Conversion and Task Flow
+
+- One primary CTA per section. Secondary actions should be visibly secondary.
+- Reduce avoidable friction:
+  - do not force account creation before obvious value unless required
+  - do not split simple tasks across unnecessary steps
+  - keep progress visible in multi-step flows
+- Prefer clear defaults and safe recommendations over blank states.
+- If the page is transactional, the user must always know:
+  - what they are committing to
+  - what information is required
+  - how to go back or recover
+
+## 3. Forms and Validation
+
+- Labels must remain visible. Placeholder-only forms are not acceptable.
+- Use correct `autocomplete` tokens where applicable.
+- Validate at sensible moments:
+  - on blur
+  - on submit
+  - in real time only when it clearly helps
+- Preserve user input across validation errors and network failures.
+- Error messages must say:
+  - what is wrong
+  - where it is wrong
+  - how to fix it
+- Authentication flows should allow paste and password managers. Do not rely on
+  memorization, transcription, or puzzle-like challenges.
+
+## 4. States and Feedback
+
+- Every async action needs immediate visible acknowledgment.
+- Every major component or page needs designed states for:
+  - loading
+  - empty
+  - error
+  - success
+  - disabled
+  - destructive confirmation or recovery
+- Avoid silent failures and silent no-ops.
+- Optimistic UI is acceptable only if rollback and failure messaging are explicit.
+
+## 5. Accessibility and Interaction Safety
+
+- Focus must be visible and should not be obscured by sticky UI, banners, or
+  overlays.
+- Minimum target size should meet WCAG 2.2 AA at 24x24 CSS px where applicable.
+  Prefer 44x44 CSS px for touch comfort.
+- Any dragging interaction needs a simpler pointer alternative.
+- Motion must respect `prefers-reduced-motion`.
+- Keyboard navigation must preserve logical focus order.
+- Hover or focus content must not trap, obscure, or disappear unexpectedly.
+
+## 6. Performance Is UX
+
+- Treat performance budgets as design decisions, not later engineering cleanup.
+- Baseline website budgets:
+  - LCP: <= 2.5s at p75
+  - INP: <= 200ms at p75
+  - CLS: <= 0.1 at p75
+- Avoid layout shifts from:
+  - images without dimensions
+  - late-loading UI
+  - banners, drawers, and injected content
+- Use images on mobile only when they add information or trust, not just mood.
+- Rich motion should never hide slow UI feedback.
+
+## 7. Responsive Content Priority
+
+- Design mobile-first content priority, not just mobile layout shrinkage.
+- At narrow widths, preserve:
+  - meaning
+  - main action
+  - orientation
+  - recovery paths
+- Reflow should remain usable down to 320 CSS px.
+- Zoom and responsive overlays should not hide focused controls or primary actions.
+- Dense desktop chrome should collapse into simpler, more legible mobile navigation.
+
+## 8. DESIGN.md Implications
+
+If a DESIGN.md is excellent, it should answer these questions somewhere in the
+contract:
+
+- What is the primary user task on each page?
+- What is the CTA hierarchy?
+- What are the major page and component states?
+- What form and authentication constraints apply?
+- What performance and motion budgets apply?
+- What accessibility floor is non-negotiable?
+- What content is prioritized on mobile?
+
+If those answers are missing, the design is visually specified but experientially
+under-specified.
+
+## Source Anchors
+
+- VoltAgent design-contract direction:
+  - https://github.com/VoltAgent/awesome-design-md
+- VoltAgent multi-platform skill packaging and curation:
+  - https://github.com/VoltAgent/awesome-agent-skills
+  - https://github.com/VoltAgent/awesome-codex-subagents
+- Web performance:
+  - https://web.dev/articles/lcp
+  - https://web.dev/inp/
+  - https://web.dev/optimize-cls
+- Rendering responsiveness:
+  - https://web.dev/articles/rendering-performance
+- Form UX:
+  - https://web.dev/articles/codelab-address-form-best-practices
+- Accessibility:
+  - https://www.w3.org/TR/WCAG22/
+  - https://www.w3.org/WAI/WCAG22/Understanding/target-size-minimum.html
+  - https://www.w3.org/WAI/WCAG21/Understanding/target-size.html
+  - https://www.w3.org/WAI/WCAG22/Understanding/focus-not-obscured-minimum.html
+  - https://www.w3.org/WAI/WCAG22/Understanding/accessible-authentication-minimum.html
+  - https://www.w3.org/WAI/WCAG22/Understanding/dragging-movements
+- Reduced motion:
+  - https://developer.mozilla.org/en-US/docs/Web/CSS/@media/prefers-reduced-motion
+- Mobile content discipline:
+  - https://www.nngroup.com/videos/mobile-images/
diff --git a/skills/using-hyperstack/SKILL.md b/skills/using-hyperstack/SKILL.md
index 2105681..b053e86 100644
--- a/skills/using-hyperstack/SKILL.md
+++ b/skills/using-hyperstack/SKILL.md
@@ -179,6 +179,50 @@ For non-trivial tasks, follow the chain in order. Do not skip steps.
 
 ---
 
+## Internal Agent Harness
+
+Hyperstack now has internal roles. These roles are **internal and auto-called**.
+Users do not invoke them directly. The bootstrap and harness choose the correct
+role based on the request and lifecycle state.
+
+V1 keeps the current skills and MCP plugins as the execution substrate. The role
+harness is layered on top of them; it does not replace them yet.
+
+## Role Registry
+
+- `main` — conductor, classifier, gatekeeper, verifier, and delivery owner
+- `website-builder` — first specialist for website-facing design and
+  implementation work
+
+## Routing Summary
+
+- Every request enters through `main`
+- `main` inspects the workspace first: package manifests, dependency signals,
+  and likely core files for the affected surface
+- `main -> website-builder` for website-facing work: landing pages, dashboards,
+  marketing pages, redesigns, page structure, CTA hierarchy, form friction,
+  trust signals, and website-experience-heavy UI work
+- `website-builder -> main` after specialist output is ready for review and
+  verification
+- If classification is ambiguous, stay in `main`
+
+## Allowed Transitions
+
+- `user request -> main`
+- `main -> website-builder`
+- `website-builder -> main`
+- `main -> existing Hyperstack skills/plugins`
+- `main -> verification and delivery gates`
+
+## Disallowed Transitions
+
+- `user request -> website-builder`
+- `website-builder -> ship`
+- `website-builder -> deliver`
+- `website-builder` claiming final completion directly
+
+---
+
 ## The Rationalization Catalog (Read Before Every Session)
 
 These are the exact thoughts you will have when you want to skip a skill. Every one is a bug in your reasoning. Every one has been written down because someone (probably you in a past session) used it to ship bad code.
diff --git a/src/internal/compile-runtime-context.ts b/src/internal/compile-runtime-context.ts
new file mode 100644
index 0000000..2c24897
--- /dev/null
+++ b/src/internal/compile-runtime-context.ts
@@ -0,0 +1,28 @@
+#!/usr/bin/env node
+
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { compileContextArtifacts, compileUsingHyperstackBootstrap } from "./context-compiler.js";
+import { readFileSync } from "node:fs";
+
+const scriptDir = dirname(fileURLToPath(import.meta.url));
+const pluginRoot = join(scriptDir, "../..");
+
+try {
+  const artifacts = compileContextArtifacts(pluginRoot);
+  const source = readFileSync(join(pluginRoot, "skills", "using-hyperstack", "SKILL.md"), "utf8");
+  const { stats } = compileUsingHyperstackBootstrap(source);
+
+  process.stdout.write(
+    [
+      "Compiled runtime context artifacts:",
+      ...artifacts.map((artifact) => `- ${artifact.outputPath}`),
+      `Bootstrap char savings: ${(stats.savingsRatio * 100).toFixed(1)}% (${stats.sourceChars} -> ${stats.artifactChars})`,
+      "",
+    ].join("\n"),
+  );
+} catch (error) {
+  const message = error instanceof Error ? error.message : String(error);
+  process.stderr.write(`Failed to compile runtime context: ${message}\n`);
+  process.exit(1);
+}
diff --git a/src/internal/context-compiler.ts b/src/internal/context-compiler.ts
new file mode 100644
index 0000000..e347d49
--- /dev/null
+++ b/src/internal/context-compiler.ts
@@ -0,0 +1,248 @@
+import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+
+export interface ContextArtifact {
+  outputPath: string;
+  sourcePath: string;
+  content: string;
+}
+
+export interface BootstrapCompilationStats {
+  sourceChars: number;
+  artifactChars: number;
+  savingsRatio: number;
+}
+
+const REQUIRED_BOOTSTRAP_MARKERS = [
+  "The 1% Rule",
+  "NO CODE WITHOUT MCP GROUND-TRUTH DATA",
+  "NO VISUAL CODE WITHOUT AN APPROVED DESIGN.md",
+  "NO COMPLETION CLAIMS WITHOUT SHIP-GATE EVIDENCE",
+  "NO SKIPPING SKILLS BECAUSE \"THIS IS SIMPLE\"",
+  "designer_*",
+  "design_tokens_*",
+  "ui_ux_*",
+  "reactflow_*",
+  "motion_*",
+  "lenis_*",
+  "react_*",
+  "echo_*",
+  "golang_*",
+  "rust_*",
+  "blueprint",
+  "designer",
+  "forge-plan",
+  "ship-gate",
+  "deliver",
+  "run-plan",
+  "autonomous-mode",
+  "subagent-ops",
+  "engineering-discipline",
+  "worktree-isolation",
+  "debug-discipline",
+  "parallel-dispatch",
+  "MCP unavailable",
+  "announce it",
+  "main",
+  "website-builder",
+  "auto-called",
+  "main -> website-builder",
+];
+
+function stripFrontmatter(source: string): string {
+  return source.replace(/^---\n[\s\S]*?\n---\n?/, "");
+}
+
+function extractTaggedBlock(source: string, tag: string): string {
+  const pattern = new RegExp(`<${tag}>([\\s\\S]*?)<\\/${tag}>`);
+  const match = source.match(pattern);
+  if (!match?.[1]) {
+    throw new Error(`Could not extract <${tag}> block from source`);
+  }
+  return match[1].trim();
+}
+
+function extractSection(source: string, heading: string): string {
+  const lines = source.split("\n");
+  const targetHeading = `## ${heading}`;
+  const startIndex = lines.findIndex((line) => line.trim() === targetHeading);
+  if (startIndex === -1) {
+    throw new Error(`Could not extract section "${heading}" from source`);
+  }
+  const contentLines: string[] = [];
+  for (let index = startIndex + 1; index < lines.length; index += 1) {
+    const line = lines[index] ?? "";
+    if (line.startsWith("## ")) {
+      break;
+    }
+    contentLines.push(line);
+  }
+  return contentLines.join("\n").trim();
+}
+
+function extractCodeBlock(section: string): string {
+  const match = section.match(/```([\s\S]*?)```/);
+  if (!match?.[1]) {
+    throw new Error("Could not extract code block from section");
+  }
+  return match[1].trim();
+}
+
+interface TableRow {
+  cells: string[];
+}
+
+function parseMarkdownTable(section: string): TableRow[] {
+  return section
+    .split("\n")
+    .map((line) => line.trim())
+    .filter((line) => line.startsWith("|"))
+    .filter((line) => !/^(\|\s*-+\s*)+\|?$/.test(line.replace(/:[-\s]+/g, "---")))
+    .slice(1)
+    .map((line) => ({
+      cells: line
+        .split("|")
+        .map((cell) => cell.trim())
+        .filter((cell) => cell.length > 0),
+    }))
+    .filter((row) => row.cells.length > 0);
+}
+
+function compactNamespaceTable(section: string): string[] {
+  return parseMarkdownTable(section)
+    .filter((row) => row.cells.length >= 3)
+    .map((row) => `- ${row.cells[0]} -> ${row.cells[2]}`);
+}
+
+function compactWorkflowTables(source: string): string[] {
+  const workflowSection = extractSection(source, "Layer 2: Skills (Engineering Process)");
+  const rows = parseMarkdownTable(workflowSection).filter((row) => row.cells.length >= 2);
+
+  return rows
+    .filter((row) => row.cells[0] !== "Skill")
+    .map((row) => `- ${row.cells[0]}: ${row.cells[1]}`);
+}
+
+function extractFinalCheck(source: string): string[] {
+  const finalSection = extractSection(source, "Final Check Before Any Response");
+  return finalSection
+    .split("\n")
+    .map((line) => line.trim())
+    .filter((line) => line.startsWith("1.") || line.startsWith("2.") || line.startsWith("3.") || line.startsWith("4.") || line.startsWith("5."))
+    .map((line) => `- ${line.replace(/^\d+\.\s*/, "")}`);
+}
+
+function extractRedFlags(source: string): string[] {
+  const redFlagsSection = extractSection(source, "Red Flags — STOP");
+  const rows = parseMarkdownTable(redFlagsSection).filter((row) => row.cells.length >= 2);
+  return rows.slice(0, 6).map((row) => `- ${row.cells[0]} -> ${row.cells[1]}`);
+}
+
+function extractInstructionPriority(source: string): string[] {
+  const section = extractSection(source, "Instruction Priority");
+  return section
+    .split("\n")
+    .map((line) => line.trim())
+    .filter((line) => /^\d+\./.test(line))
+    .map((line) => `- ${line.replace(/^\d+\.\s*/, "")}`);
+}
+
+function extractSimpleBullets(section: string): string[] {
+  return section
+    .split("\n")
+    .map((line) => line.trim())
+    .filter((line) => line.startsWith("- "))
+    .map((line) => line);
+}
+
+export function compileUsingHyperstackBootstrap(source: string): { content: string; stats: BootstrapCompilationStats } {
+  const body = stripFrontmatter(source);
+  const criticalBlock = extractTaggedBlock(body, "EXTREMELY-IMPORTANT");
+  const ironLaws = extractCodeBlock(extractSection(body, "The Iron Laws"));
+  const namespaces = compactNamespaceTable(extractSection(body, "Layer 1: MCP Tools (Ground-Truth Data)"));
+  const workflowSkills = compactWorkflowTables(body);
+  const instructionPriority = extractInstructionPriority(body);
+  const roleRegistry = extractSimpleBullets(extractSection(body, "Role Registry"));
+  const routingSummary = extractSimpleBullets(extractSection(body, "Routing Summary"));
+  const allowedTransitions = extractSimpleBullets(extractSection(body, "Allowed Transitions"));
+  const disallowedTransitions = extractSimpleBullets(extractSection(body, "Disallowed Transitions"));
+  const finalCheck = extractFinalCheck(body);
+  const redFlags = extractRedFlags(body);
+
+  const content = [
+    "<!-- GENERATED FILE. Edit skills/using-hyperstack/SKILL.md and re-run `bun run compile:context`. -->",
+    "# Hyperstack Runtime Bootstrap",
+    "",
+    "## Critical",
+    criticalBlock,
+    "",
+    "## Iron Laws",
+    "```",
+    ironLaws,
+    "```",
+    "",
+    "## Instruction Priority",
+    ...instructionPriority,
+    "",
+    "## MCP Must-Call-First",
+    ...namespaces,
+    "",
+    "## Workflow Skills",
+    ...workflowSkills,
+    "",
+    "## Internal Roles",
+    "- Roles are internal and auto-called. Users do not invoke them directly.",
+    ...roleRegistry,
+    "",
+    "## Routing Summary",
+    ...routingSummary,
+    "",
+    "## Allowed Transitions",
+    ...allowedTransitions,
+    "",
+    "## Disallowed Transitions",
+    ...disallowedTransitions,
+    "",
+    "## High-Signal Red Flags",
+    ...redFlags,
+    "",
+    "## Degraded Mode",
+    "- If MCP unavailable, tell the user explicitly: \"MCP unavailable\" and flag answers as uncertain.",
+    "",
+    "## Announcement Rule",
+    "- Before invoking any Hyperstack skill, announce it with the exact format and purpose so the user can audit it.",
+    "",
+    "## Final Check",
+    ...finalCheck,
+    "",
+  ].join("\n");
+
+  const stats: BootstrapCompilationStats = {
+    sourceChars: source.length,
+    artifactChars: content.length,
+    savingsRatio: source.length === 0 ? 0 : 1 - content.length / source.length,
+  };
+
+  return { content, stats };
+}
+
+export function validateUsingHyperstackBootstrap(content: string): string[] {
+  return REQUIRED_BOOTSTRAP_MARKERS.filter((marker) => !content.includes(marker));
+}
+
+export function compileContextArtifacts(pluginRoot: string): ContextArtifact[] {
+  const sourcePath = join(pluginRoot, "skills", "using-hyperstack", "SKILL.md");
+  const outputPath = join(pluginRoot, "generated", "runtime-context", "using-hyperstack.bootstrap.md");
+
+  const source = readFileSync(sourcePath, "utf8");
+  const { content } = compileUsingHyperstackBootstrap(source);
+  const missing = validateUsingHyperstackBootstrap(content);
+  if (missing.length > 0) {
+    throw new Error(`Generated bootstrap artifact is missing required markers: ${missing.join(", ")}`);
+  }
+
+  mkdirSync(dirname(outputPath), { recursive: true });
+  writeFileSync(outputPath, content, "utf8");
+
+  return [{ sourcePath, outputPath, content }];
+}
diff --git a/tests/context-compiler-behaviour.test.ts b/tests/context-compiler-behaviour.test.ts
new file mode 100644
index 0000000..2d0c3f3
--- /dev/null
+++ b/tests/context-compiler-behaviour.test.ts
@@ -0,0 +1,26 @@
+import assert from "node:assert/strict";
+import { readFileSync } from "node:fs";
+import { resolve } from "node:path";
+import test from "node:test";
+import {
+  compileUsingHyperstackBootstrap,
+  validateUsingHyperstackBootstrap,
+} from "../src/internal/context-compiler.ts";
+
+test("compileUsingHyperstackBootstrap keeps required invariants while shrinking the source", () => {
+  const source = readFileSync(resolve("skills/using-hyperstack/SKILL.md"), "utf8");
+  const { content, stats } = compileUsingHyperstackBootstrap(source);
+  const missing = validateUsingHyperstackBootstrap(content);
+
+  assert.equal(missing.length, 0, `Missing bootstrap markers: ${missing.join(", ")}`);
+  assert.ok(stats.artifactChars < stats.sourceChars, "Compiled bootstrap should be smaller than source");
+  assert.ok(stats.savingsRatio >= 0.2, `Expected at least 20% savings, got ${(stats.savingsRatio * 100).toFixed(1)}%`);
+});
+
+test("generated bootstrap artifact stays in sync with the compiler output", () => {
+  const source = readFileSync(resolve("skills/using-hyperstack/SKILL.md"), "utf8");
+  const generated = readFileSync(resolve("generated/runtime-context/using-hyperstack.bootstrap.md"), "utf8");
+  const { content } = compileUsingHyperstackBootstrap(source);
+
+  assert.equal(generated, content, "Generated bootstrap artifact is stale. Run `bun run compile:context`.");
+});
diff --git a/tests/role-harness-behaviour.test.ts b/tests/role-harness-behaviour.test.ts
new file mode 100644
index 0000000..b118f74
--- /dev/null
+++ b/tests/role-harness-behaviour.test.ts
@@ -0,0 +1,99 @@
+import assert from "node:assert/strict";
+import { existsSync, readFileSync } from "node:fs";
+import { resolve } from "node:path";
+import test from "node:test";
+import {
+  compileUsingHyperstackBootstrap,
+  validateUsingHyperstackBootstrap,
+} from "../src/internal/context-compiler.ts";
+
+const REQUIRED_ROLE_FILES = [
+  "agents/main/PROFILE.md",
+  "agents/main/LIFECYCLE.md",
+  "agents/main/CONTEXT.md",
+  "agents/main/CHECKS.md",
+  "agents/website-builder/PROFILE.md",
+  "agents/website-builder/LIFECYCLE.md",
+  "agents/website-builder/CONTEXT.md",
+  "agents/website-builder/CHECKS.md",
+  "harness/router.md",
+  "harness/transitions.md",
+  "harness/context-policy.md",
+  "harness/observability.md",
+];
+
+const REQUIRED_PROFILE_KEYS = [
+  "name",
+  "kind",
+  "auto_invoke_when",
+  "owns",
+  "must_not_do",
+  "delegates_to",
+  "requires",
+];
+
+test("role harness files exist for main and website-builder", () => {
+  for (const relativePath of REQUIRED_ROLE_FILES) {
+    assert.ok(existsSync(resolve(relativePath)), `Missing role harness file: ${relativePath}`);
+  }
+});
+
+test("role profile frontmatter includes the required contract keys", () => {
+  for (const relativePath of [
+    "agents/main/PROFILE.md",
+    "agents/website-builder/PROFILE.md",
+  ]) {
+    const content = readFileSync(resolve(relativePath), "utf8");
+    const frontmatter = content.match(/^---\n([\s\S]*?)\n---\n/);
+    assert.ok(frontmatter?.[1], `Missing frontmatter in ${relativePath}`);
+
+    for (const key of REQUIRED_PROFILE_KEYS) {
+      assert.match(frontmatter[1], new RegExp(`^${key}:`, "m"), `Missing frontmatter key "${key}" in ${relativePath}`);
+    }
+  }
+});
+
+test("role lifecycle and checks documents expose required headings", () => {
+  const lifecycleContent = readFileSync(resolve("agents/main/LIFECYCLE.md"), "utf8");
+  assert.match(lifecycleContent, /^## Entry Criteria$/m);
+  assert.match(lifecycleContent, /^## Steps$/m);
+  assert.match(lifecycleContent, /^## Handoffs$/m);
+  assert.match(lifecycleContent, /^## Exit Criteria$/m);
+  assert.match(lifecycleContent, /^## Failure Escalation$/m);
+
+  const checksContent = readFileSync(resolve("agents/website-builder/CHECKS.md"), "utf8");
+  assert.match(checksContent, /^## Preconditions$/m);
+  assert.match(checksContent, /^## Required Evidence$/m);
+  assert.match(checksContent, /^## Done Criteria$/m);
+  assert.match(checksContent, /^## Red Flags$/m);
+});
+
+test("using-hyperstack bootstrap compiler preserves role-routing markers", () => {
+  const source = readFileSync(resolve("skills/using-hyperstack/SKILL.md"), "utf8");
+  const { content } = compileUsingHyperstackBootstrap(source);
+  const missing = validateUsingHyperstackBootstrap(content);
+
+  assert.equal(missing.length, 0, `Missing bootstrap markers: ${missing.join(", ")}`);
+  assert.match(content, /main/);
+  assert.match(content, /website-builder/);
+  assert.match(content, /auto-called/);
+  assert.match(content, /main -> website-builder/);
+});
+
+test("website-builder lifecycle requires workspace discovery before website decisions", () => {
+  const lifecycleContent = readFileSync(resolve("agents/website-builder/LIFECYCLE.md"), "utf8");
+  const contextContent = readFileSync(resolve("agents/website-builder/CONTEXT.md"), "utf8");
+
+  assert.match(lifecycleContent, /workspace/i);
+  assert.match(lifecycleContent, /package\.json|manifests?|dependencies|packages/i);
+  assert.match(lifecycleContent, /frontend core files|core frontend files|routes|components|tokens|styles/i);
+  assert.match(contextContent, /package\.json|manifests?|dependencies|packages/i);
+});
+
+test("designer skill gives user preferences precedence over auto-resolved defaults", () => {
+  const designerContent = readFileSync(resolve("skills/designer/SKILL.md"), "utf8");
+
+  assert.match(designerContent, /user preferences?/i);
+  assert.match(designerContent, /preferences?.*override|override.*preferences?/i);
+  assert.match(designerContent, /auto-resolved defaults?|defaults?.*suggestions?/i);
+});
diff --git a/tests/runtime-behaviour.test.ts b/tests/runtime-behaviour.test.ts
index 6605d04..375fdad 100644
--- a/tests/runtime-behaviour.test.ts
+++ b/tests/runtime-behaviour.test.ts
@@ -6,6 +6,32 @@ import { setTimeout as delay } from "node:timers/promises";
 import { spawn } from "node:child_process";
 import test from "node:test";
 
+async function runSessionStartHook(envOverrides: Record<string, string | undefined>) {
+  const child = spawn(process.execPath, [resolve("hooks/session-start.mjs")], {
+    cwd: process.cwd(),
+    env: { ...process.env, ...envOverrides },
+    stdio: ["ignore", "pipe", "pipe"],
+  });
+
+  let stdout = "";
+  let stderr = "";
+  child.stdout.on("data", (chunk: Buffer | string) => {
+    stdout += chunk.toString();
+  });
+  child.stderr.on("data", (chunk: Buffer | string) => {
+    stderr += chunk.toString();
+  });
+
+  const [exitCode] = (await once(child, "close")) as [number | null];
+  assert.equal(exitCode, 0, `SessionStart hook failed.\nstdout:\n${stdout}\nstderr:\n${stderr}`);
+
+  return JSON.parse(stdout) as {
+    additional_context?: string;
+    additionalContext?: string;
+    hookSpecificOutput?: { additionalContext?: string };
+  };
+}
+
 test("Claude SessionStart hook command executes successfully on this platform", async () => {
   const raw = await readFile(resolve("hooks/hooks.json"), "utf8");
   const config = JSON.parse(raw) as {
@@ -46,6 +72,47 @@ test("Claude SessionStart hook command executes successfully on this platform",
     payload.additionalContext || payload.hookSpecificOutput?.additionalContext,
     "SessionStart hook output did not include additional context",
   );
+  assert.match(
+    payload.additionalContext || payload.hookSpecificOutput?.additionalContext || "",
+    /compiled runtime bootstrap/,
+    "Claude SessionStart hook should prefer the compiled bootstrap artifact",
+  );
+});
+
+test("SessionStart hook emits Cursor-compatible output shape when CURSOR_PLUGIN_ROOT is set", async () => {
+  const payload = await runSessionStartHook({
+    CURSOR_PLUGIN_ROOT: process.cwd(),
+    CLAUDE_PLUGIN_ROOT: undefined,
+    COPILOT_CLI: undefined,
+  });
+
+  assert.ok(payload.additional_context, "Cursor hook output did not include additional_context");
+  assert.equal(payload.additionalContext, undefined, "Cursor hook should not emit additionalContext");
+  assert.equal(payload.hookSpecificOutput, undefined, "Cursor hook should not emit hookSpecificOutput");
+});
+
+test("SessionStart hook emits SDK-standard output shape when no platform-specific env is set", async () => {
+  const payload = await runSessionStartHook({
+    CURSOR_PLUGIN_ROOT: undefined,
+    CLAUDE_PLUGIN_ROOT: undefined,
+    COPILOT_CLI: undefined,
+  });
+
+  assert.ok(payload.additionalContext, "Generic hook output did not include additionalContext");
+  assert.equal(payload.additional_context, undefined, "Generic hook should not emit additional_context");
+  assert.equal(payload.hookSpecificOutput, undefined, "Generic hook should not emit hookSpecificOutput");
+});
+
+test("SessionStart hook prefers Cursor output when both CURSOR_PLUGIN_ROOT and CLAUDE_PLUGIN_ROOT are set", async () => {
+  const payload = await runSessionStartHook({
+    CURSOR_PLUGIN_ROOT: process.cwd(),
+    CLAUDE_PLUGIN_ROOT: process.cwd(),
+    COPILOT_CLI: undefined,
+  });
+
+  assert.ok(payload.additional_context, "Cursor-preferred hook output did not include additional_context");
+  assert.equal(payload.additionalContext, undefined, "Cursor-preferred hook should not emit additionalContext");
+  assert.equal(payload.hookSpecificOutput, undefined, "Cursor-preferred hook should not emit hookSpecificOutput");
 });
 
 test("package bin entry starts without an immediate runtime crash", async () => {

From 295e7d30642844f1938f591a0ebe7a612fbed3f3 Mon Sep 17 00:00:00 2001
From: Kailas Mahavarkar <66670953+KailasMahavarkar@users.noreply.github.com>
Date: Tue, 14 Apr 2026 14:13:58 +0530
Subject: [PATCH 2/2] docs: clarify harness identity and install flow

---
 README.md  | 80 ++++++++++++++++++++++++++++++++++++++++++++++--------
 install.md | 36 ++++++++++++++++++++----
 2 files changed, 99 insertions(+), 17 deletions(-)

diff --git a/README.md b/README.md
index 46f7369..70d507d 100755
--- a/README.md
+++ b/README.md
@@ -34,18 +34,48 @@
 
 ## ⚡ What is this?
 
-Hyperstack is two things bolted together:
+Hyperstack is a coding-agent harness made of three tightly-coupled layers:
 
-1. **A TypeScript MCP server** with 11 plugins and 79 tools. Your AI calls these for ground-truth API signatures, component specs, design decisions, and architectural patterns. No hallucinated imports.
+1. **An internal harness** that bootstraps the agent, enforces global invariants, and routes internal roles like `main` and `website-builder`.
+2. **A TypeScript MCP server** with 11 plugins and 79 tools. Your AI calls these for ground-truth API signatures, component specs, design decisions, and architectural patterns. No hallucinated imports.
+3. **A skill system with enforcement teeth.** 21 skills with Iron Laws, rationalization tables, and a SessionStart hook that force-injects discipline on every session. Your AI cannot "just try one thing" without the gate firing.
 
-2. **A skill system with enforcement teeth.** 21 skills with Iron Laws, rationalization tables, and a SessionStart hook that force-injects discipline on every session. Your AI cannot "just try one thing" without the gate firing.
+The combination turns a generic coding assistant into a disciplined agent system that:
 
-The combination turns a generic coding assistant into a Senior Staff Engineer who checks docs before writing code, writes a DESIGN.md before any visual work, and refuses to claim completion without verification evidence.
+- checks docs before writing code
+- writes a DESIGN.md before visual work
+- routes website-heavy work to a specialist role
+- refuses to claim completion without verification evidence
 
 **You should use this if** you are tired of AI agents inventing API shapes, shipping AI-slop UIs, or claiming "tests pass" without running them.
 
 **Skip this if** you want a frictionless autocomplete. Hyperstack is the opposite of frictionless - it is intentional friction that catches bugs before they ship.
 
+## 🤖 Agent View
+
+If you are an agent reading this README, the shortest correct mental model is:
+
+- Hyperstack is not just an MCP server
+- Hyperstack is not just a skills pack
+- Hyperstack is a harness that combines internal role routing, MCP grounding, and workflow gates
+
+Current internal role model:
+
+- `main` - conductor, gatekeeper, verifier, delivery owner
+- `website-builder` - specialist for website-facing design and implementation work
+
+Public surface:
+
+- MCP plugins for deterministic knowledge
+- skills for process enforcement
+- SessionStart hook for bootstrap context injection
+
+Internal surface:
+
+- role contracts in `agents/`
+- orchestration contracts in `harness/`
+- generated runtime bootstrap artifacts in `generated/runtime-context/`
+
 ---
 
 ## 🚀 Quickstart
@@ -60,24 +90,40 @@ The agent will pull the Docker image and configure your MCP client.
 
 ### 🐳 Docker (manual)
 
-Add this to `~/.claude.json`, Cursor config, or equivalent:
+Hyperstack uses a persistent container plus `docker exec`. Do **not** use the
+older `docker run --rm` per-session pattern.
+
+1. Pull the image:
+
+```bash
+docker pull ghcr.io/orkait/hyperstack:main
+```
+
+2. Start the persistent container:
+
+```bash
+docker rm -f hyperstack-mcp 2>/dev/null
+docker run -d --name hyperstack-mcp --restart unless-stopped \
+  --memory=512m --cpus=1 \
+  --entrypoint sleep \
+  ghcr.io/orkait/hyperstack:main infinity
+```
+
+3. Add this to `~/.claude.json`, Cursor config, or equivalent:
 
 ```json
 {
   "mcpServers": {
     "hyperstack": {
       "command": "docker",
-      "args": [
-        "run", "-i", "--rm",
-        "--memory=256m", "--cpus=0.5",
-        "ghcr.io/orkait/hyperstack:main"
-      ]
+      "args": ["exec", "-i", "hyperstack-mcp", "bun", "/app/src/index.ts"]
     }
   }
 }
 ```
 
-The `--memory=256m` and `--cpus=0.5` flags enforce resource limits. Keep them.
+This keeps startup cheap across sessions and matches the installation flow in
+[install.md](/mnt/storage/codespace/code/orkait/hyperstack/install.md).
 
 ### 🔧 Install the skills
 
@@ -107,6 +153,9 @@ Node 18+ required.
 
 ## 🧠 The two-layer system
 
+The public product still has two user-facing layers, but they now sit inside an
+internal harness.
+
 ### Layer 1: MCP Plugins (deterministic knowledge)
 
 Your AI calls these for exact API data. Memory is not acceptable. Every plugin serves typed TypeScript data + `.txt` snippets bundled with the plugin.
@@ -133,6 +182,15 @@ Markdown with adversarial enforcement. Each gate skill has an Iron Law, a 1% Rul
 
 The `using-hyperstack` skill is injected into every session by `hooks/session-start.mjs`. You do not have to invoke it manually.
 
+### Internal Harness (role routing + bootstrap)
+
+The internal harness is what ties the public layers together:
+
+- bootstrap is injected at session start from generated runtime context
+- `main` owns classification, routing, gates, and verification
+- `website-builder` specializes in website-facing design and implementation work
+- roles are internal and auto-called, not user-invoked commands
+
 <details>
 <summary><strong>🧱 Core (13)</strong> - workflow, discipline, gates used on every task</summary>
 
diff --git a/install.md b/install.md
index 40f12bd..9060a36 100644
--- a/install.md
+++ b/install.md
@@ -2,14 +2,33 @@
 
 If you are an AI assistant reading this file, please perform the following steps to install Hyperstack on the user's system. You must adapt these steps based on the environment/CLI you are currently running in (e.g., Claude Code, Cursor, Gemini CLI, Copilot CLI, OpenCode, Codex, Windsurf, etc.).
 
+## Read This First
+
+If you only remember four things, remember these:
+
+1. Hyperstack is a harness, not just an MCP server.
+2. Both the MCP server and the skills must be installed.
+3. The preferred Docker setup is a persistent `hyperstack-mcp` container plus
+   `docker exec`, not `docker run --rm` per session.
+4. Installation is not complete until the MCP server responds and the skills are
+   visible on disk.
+
 ## What Hyperstack Gives the User
 
-Two things, installed together:
+Three tightly-coupled pieces, installed together:
+
+1. **An internal harness** - bootstrap, internal role routing, and workflow control. Current internal roles include `main` and `website-builder`.
+2. **An MCP server** with 11 plugins and 79 tools - deterministic knowledge for React Flow v12, Motion v12, Lenis, React 19 / Next.js, Echo, Go, Rust, design tokens, UI/UX principles, shadcn/ui (Base UI edition), and the `designer` DESIGN.md pipeline.
+3. **A skill system** with 21 skills including adversarial enforcement gates (`blueprint`, `designer`, `forge-plan`, `ship-gate`, `engineering-discipline`) and a SessionStart hook that force-injects the `using-hyperstack` skill at every session start.
+
+The install steps below wire the public pieces the user actually needs: the MCP
+server and the skills. The internal harness is shipped inside the repository and
+becomes active through the bootstrap hook and runtime context artifacts.
 
-1. **An MCP server** with 11 plugins and 79 tools - deterministic knowledge for React Flow v12, Motion v12, Lenis, React 19 / Next.js, Echo, Go, Rust, design tokens, UI/UX principles, shadcn/ui (Base UI edition), and the `designer` DESIGN.md pipeline.
-2. **A skill system** with 21 skills including adversarial enforcement gates (`blueprint`, `designer`, `forge-plan`, `ship-gate`, `engineering-discipline`) and a SessionStart hook that force-injects the `using-hyperstack` skill at every session start.
+If you install only one public piece:
 
-Both must be installed for the system to work correctly. The MCP server alone gives the user tools; the skills alone give the user prose rules with no tools to call.
+- MCP only -> the user gets tools without discipline
+- skills only -> the user gets prose rules without tools
 
 ## Step 1: Detect Environment
 
@@ -40,7 +59,12 @@ SKILLS_DIR="$HOME/.claude/skills/hyperstack" && \
 
 Replace `~/.claude/skills` with the correct path for the current environment (see table above). For example, on Qwen Code use `~/.qwen/skills/hyperstack`.
 
-The repository includes a `hooks/session-start.mjs` entrypoint that injects the `using-hyperstack` skill content into every session automatically. This is how the enforcement (Iron Laws, 1% Rule, rationalization tables) reaches the agent without manual invocation. On platforms that support `.claude-plugin/hooks.json`, this happens automatically. On others, the skill is still readable but the hook will not fire.
+The repository includes a `hooks/session-start.mjs` entrypoint that injects the
+generated Hyperstack bootstrap into every session automatically. This is how the
+enforcement and internal harness model reach the agent without manual
+invocation. On platforms that support `.claude-plugin/hooks.json`, this happens
+automatically. On others, the skills are still readable but the hook will not
+fire.
 
 ## Step 3: Configure the MCP Server
 
@@ -223,7 +247,7 @@ If any of these three checks fail, do not proceed. Fix the issue first:
 
 ---
 
-**Verification A: SessionStart hook fires (platforms with hooks only).** On Claude Code and platforms with hook support, the agent should receive the `using-hyperstack` skill content at session start. Ask: *"What Hyperstack skills are available?"* The agent should list skills from `skills/INDEX.md` (21 total, grouped into core / domain / meta). On platforms without hook support (e.g., Qwen Code), this step does not apply — skills are on disk but not auto-injected.
+**Verification A: SessionStart hook fires (platforms with hooks only).** On Claude Code and platforms with hook support, the agent should receive the Hyperstack bootstrap at session start. Ask: *"What Hyperstack skills are available?"* The agent should list skills from `skills/INDEX.md` (21 total, grouped into core / domain / meta). On platforms without hook support (e.g., Qwen Code), this step does not apply - skills are on disk but not auto-injected.
 
 **Verification B: Designer workflow triggers.** Ask: *"Help me design a SaaS dashboard for DevOps engineers."* On platforms with the SessionStart hook, the agent should invoke `hyperstack:designer` BEFORE writing any code. If it jumps straight to JSX, the hook did not fire — restart the client and try again. On platforms without hook support, this step is manual (the agent won't auto-invoke designer).