Merge pull request #78 from orkait/feat/rename-hyperstack-and-3-layer-arch

feat: migrate Hyperstack to topology-driven local runtime

Author: KailasMahavarkar

AGENTS.md

@@ -44,7 +44,7 @@ rules:
 load and obey when present:
 
 * `~/.gemini/settings.json`, `.cursorrules`, or similar ide-specific project rules
-* `./skills/using-hyperstack/SKILL.md`
+* `./skills/hyperstack/SKILL.md`
 * any task-specific skill doc the user points to
 * repo-local agent or steering docs
 

GEMINI.md

@@ -2,5 +2,5 @@
 Disciplined MCP server + skill system with adversarial enforcement.
 Core focus: React Flow v12, Motion v12, Lenis, React 19, Echo, Go, Rust, and the Designer pipeline.
 
-@./skills/using-hyperstack/SKILL.md
+@./skills/hyperstack/SKILL.md
 

README.md

@@ -7,7 +7,7 @@
 <p>
   <img src="https://img.shields.io/badge/license-MIT-blue?style=flat-square" alt="MIT" />
   <img src="https://img.shields.io/badge/TypeScript-5-3178c6?style=flat-square&logo=typescript&logoColor=white" alt="TypeScript" />
-  <img src="https://img.shields.io/badge/Docker-ready-2496ED?style=flat-square&logo=docker&logoColor=white" alt="Docker" />
+  <img src="https://img.shields.io/badge/Local_runtime-default-0f766e?style=flat-square" alt="Local Runtime" />
   <img src="https://img.shields.io/badge/MCP-standard-6366f1?style=flat-square" alt="MCP" />
 </p>
 
@@ -25,7 +25,7 @@
 
 **Hyperstack is a disciplined engineering harness for AI coding agents.** 
 
-It provides the necessary **Ground Truth** (via 79 specialized MCP tools) and **Adversarial Enforcement** (via 21 rigorous skills) to transform a generic LLM into a high-precision Senior Engineer. 
+It provides the necessary **Ground Truth** (via 79 specialized tool calls) and **Adversarial Enforcement** (via 21 rigorous skills) to transform a generic LLM into a high-precision Senior Engineer.
 
 Unlike standard "polite" instructions, Hyperstack uses **Iron Laws** and a **SessionStart hook** to force agents to check real documentation, follow precise design specs, and provide binary verification before shipping.
 
@@ -39,13 +39,13 @@ The fastest way to install Hyperstack is to let your AI agent do it for you. Thi
 Fetch and follow the instructions at https://raw.githubusercontent.com/orkait/hyperstack/main/install.md
 ```
 
-The autopilot will autonomously detect your environment, install the MCP server (Docker or Local), and **automatically link the Skills repository**. This is the only step required.
+The autopilot will autonomously detect your environment, configure the local tool runtime, and **automatically link the Skills repository**. This is the only step required.
 
 ---
 
 ### 2. Manual Configuration (Advanced)
 
-If you aren't using the Autopilot, follow the **Unified Bootstrap** to set up both the MCP server and the Skills:
+If you aren't using the Autopilot, follow the **Unified Bootstrap** to set up both the local runtime and the Skills:
 
 1.  **Clone & Initialize**:
     ```bash
@@ -84,7 +84,7 @@ If you aren't using the Autopilot, follow the **Unified Bootstrap** to set up bo
 
 It is not just a library; it is a **disciplined harness** made of three tightly-coupled layers:
 
-1.  **The Harness**: Bootstraps the agent, routes internal specialist roles (`hyper`, `website-builder`), and enforces global development invariants.
+1.  **The Harness**: Bootstraps the agent, routes internal specialist roles (`hyper`, `frontend-builder`), and enforces global development invariants.
 2.  **The MCP Ground Truth**: 12 TypeScript plugins (80 tools) that provide deterministic data. No hallucinated imports or invented component specs.
 3.  **The Adversarial Gates**: 21 skills with **"Enforcement Teeth"**. These aren't suggestions; they are Iron Laws supported by rationalization tables that counter every excuse an agent uses to skip quality gates.
 
@@ -127,41 +127,25 @@ graph TD
 If you are an agent reading this, your mental model must be: **Process is Priority.** You are operating within a system that requires deterministic grounding and formal design before implementation.
 
 - **Conductance**: `hyper` owners classification and gate verification.
-- **Specialization**: `website-builder` handles visual and frontend implementation.
+- **Specialization**: `frontend-builder` handles visual and frontend implementation.
 - **Persistence**: You run in a stable Docker container with a persistent lifecycle.
 
 ---
 
 ## 🚀 Quickstart
 
-### 🐳 Docker (Default)
+### 💻 Local Runtime (Default)
 
-Hyperstack uses a persistent container plus `docker exec`. This keeps startup cheap across sessions and ensures 100% environment stability.
+Hyperstack now defaults to a local tool runtime backed by topology manifests and corpus navigation. Docker is no longer required for the standard setup path.
 
-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 your MCP settings (`~/.claude.json`, Cursor, Windsurf, etc.):
+Add this to your MCP or tool settings (`~/.claude.json`, Cursor, Windsurf, etc.):
 
 ```json
 {
   "mcpServers": {
     "hyperstack": {
-      "command": "docker",
-      "args": ["exec", "-i", "hyperstack-mcp", "bun", "/app/src/index.ts"]
+      "command": "node",
+      "args": ["/path/to/hyperstack/bin/hyperstack.mjs"]
     }
   }
 }
@@ -174,19 +158,19 @@ If you are using Claude Code, Cursor, Windsurf, Roo Code, or Gemini, you can use
 ```text
 Fetch and follow the instructions at https://raw.githubusercontent.com/orkait/hyperstack/main/install.md
 ```
-The autopilot will detect your environment and propose the correct Docker-based configuration block.
+The autopilot will detect your environment and propose the correct local-runtime configuration block.
 
 
 
 ### 🔧 Install the skills
 
-The MCP server gives you tools. The skills give you discipline. Install both:
+The local runtime gives you tools. The skills give you discipline. Install both:
 
 ```bash
 git clone https://github.com/orkait/hyperstack.git ~/.claude/skills/hyperstack
 ```
 
-After installing, the SessionStart hook (at `hooks/session-start.mjs`) will auto-inject the `using-hyperstack` skill into every session. No manual activation needed.
+After installing, the SessionStart hook (at `hooks/session-start.mjs`) will auto-inject the `hyperstack` skill into every session. No manual activation needed.
 
 ### 💻 From source
 
@@ -204,9 +188,9 @@ Node 18+ required.
 
 ---
 
-## 🧠 The Two-Layer System
+## 🧠 The Three-Layer System
 
-Hyperstack's strength comes from the friction between **Ground Truth** (MCP) and **Enforcement** (Skills).
+Hyperstack's strength comes from the friction between **Ground Truth** (MCP), **Enforcement** (Skills), and **Orchestration** (Agents).
 
 ### Layer 1: MCP Plugins (Ground Truth)
 
@@ -236,13 +220,13 @@ Markdown with adversarial enforcement. Each skill contains an **Iron Law** that
 
 These laws are backed by **Rationalization Tables**-pre-written counters to every excuse an AI agent uses to skip quality gates.
 
-### Internal Harness (role routing + bootstrap)
+### Layer 3: Agents (Orchestration & Routing)
 
-The internal harness is what ties the public layers together:
+The internal harness is what ties the public layers together by managing process and domains:
 
 - bootstrap is injected at session start from generated runtime context
 - `hyper` owns classification, routing, gates, and verification
-- `website-builder` specializes in website-facing design and implementation work
+- `frontend-builder` specializes in frontend-facing design and implementation work
 - roles are internal and auto-called, not user-invoked commands
 
 <details>
@@ -285,7 +269,7 @@ The internal harness is what ties the public layers together:
 
 | Skill | Role |
 |---|---|
-| `using-hyperstack` | Force-injected at session start via hook - the enforcement payload |
+| `hyperstack` | Force-injected at session start via hook - the enforcement payload |
 | `testing-skills` | RED-GREEN-REFACTOR pressure testing for skills using subagents |
 
 </details>
@@ -309,17 +293,17 @@ Ordinary skill markdown is a polite suggestion. Polite suggestion fails when an
 
 When you say, **“build me a SaaS dashboard”**:
 
-1. **SessionStart** already puts in `using-hyperstack`, so AI know system is there.
-2. **Blueprint skill** sees visual job and sends it to `hyperstack:designer`.
-3. **Designer skill** runs `designer_resolve_intent(product)` to guess industry, personality, style, density, and mode.
+1. **SessionStart** already puts in `hyperstack`, so AI know system is there.
+2. **Blueprint skill** builds workspace understanding first and classifies the change.
+3. If the route says a design contract is required, **Designer skill** runs `designer_resolve_intent(product)` to guess industry, personality, style, density, and mode.
 4. Designer asks **3 questions** in base mode, or **12 questions** in advanced mode.
-5. Like **Q11b** will ask what component library to use: shadcn, raw Tailwind, MUI, Mantine, Chakra, Ant Design, or custom.
-6. Designer makes a **DESIGN.md** contract with 10 parts: theme, colors, type, spacing, components, motion, elevation, do/don’ts, responsive rules, and anti-patterns.
-7. User approves the **DESIGN.md**.
-8. **Forge-plan** reads it and makes one task for each section. If user picked shadcn, it calls `shadcn_get_component`. If not, it builds from the DESIGN.md spec.
+5. Q11b asks what component library to use: shadcn, raw Tailwind, MUI, Mantine, Chakra, Ant Design, or custom.
+6. Only when needed, Designer makes a conditional **DESIGN.md / design contract** with theme, colors, type, spacing, components, motion, elevation, do/don’ts, responsive rules, and anti-patterns.
+7. User approves the design contract when the route requires it.
+8. **Forge-plan** reads the routed artifacts and makes one task for each required area. Existing-project frontend logic work can stay workspace-first without forcing a design contract.
 9. Build tasks run with MCP tools as ground truth.
-10. **designer_verify_implementation** checks build against **DESIGN.md**.
-11. **Ship-gate** blocks final completion unless build passes the **DESIGN.md** rules.
+10. **designer_verify_implementation** checks build against the design contract when present.
+11. **Ship-gate** blocks final completion unless build passes the required proof rules.
 
 AI cannot jump ahead. Every step has hard gate. Excuses already blocked by rationalization tables.
 

SKILL.md

@@ -6,7 +6,7 @@ description: >-
   React Flow, Motion, Echo, Go, Rust, and UI/UX design systems.
 metadata:
   author: orkait
-  version: "3.0.0"
+  version: "3.1.0"
   license: MIT
 triggers:
   - build feature
@@ -31,142 +31,8 @@ activation:
   priority: high
 ---
 
-# 🧠 The Hyperstack Engine
+# Hyperstack
 
-<div align="center">
-  <strong>You are an autonomous Senior Staff Engineer. You are not an autocomplete engine.</strong>
-  <br/>
-  <em>Speed without correctness is failure. Preservation of invariants is the only success.</em>
-</div>
+See the canonical skill definition: `skills/hyperstack/SKILL.md`
 
----
-
-## ⚖️ The Iron Laws
-
-```
-1. NO CODE WITHOUT MCP GROUND-TRUTH DATA
-2. NO VISUAL CODE WITHOUT AN APPROVED DESIGN.md
-3. NO COMPLETION CLAIMS WITHOUT FRESH VERIFICATION EVIDENCE
-4. NO REFACTOR WITHOUT A FAILING TEST FIRST
-5. NO PATTERN WITHOUT A NAMED FORCE
-```
-
-**Violating the letter of these laws is violating the spirit of these laws.**
-
-<EXTREMELY-IMPORTANT>
-Before writing any code, proposing any fix, or starting any architecture, you MUST:
-
-1.  **Stop Rationalizing:** Do not skip steps to "be helpful." Thoroughness is the highest form of help. Skipping is laziness, not speed.
-2.  **Verify the Stack:** Consult the relevant MCP plugins below for 100% accurate API syntax. Memory is not acceptable. Pattern-matching is not acceptable. Only MCP output is acceptable.
-3.  **Load the Discipline:** Read `skills/engineering-discipline/SKILL.md` for architectural gates.
-4.  **Adopt Negative Doubt:** List 5 failure modes for your plan before you type a single line of code.
-
-**The 1% Rule:** If there is even a 1% chance a system rule applies to your task, you MUST read the corresponding file in the `skills/` directory BEFORE acting. You do not have a choice. You cannot rationalize your way out of this.
-</EXTREMELY-IMPORTANT>
-
----
-
-## 🚦 Operational Phases
-
-Follow this state machine for every non-trivial task. Do not skip phases.
-
-### Phase 1: Discovery (The Inventory)
--   **Actions:** Map state variables, data flows, and dependencies.
--   **Skill:** Use `skills/behaviour-analysis/SKILL.md` for UI/UX or state-heavy tasks.
--   **MCP:** Query `[plugin]_list_apis` and `[plugin]_search_docs` to find exact ground-truth data.
-
-### Phase 2: Reasoning (The Architecture)
--   **Actions:** Define invariants, module boundaries, and public APIs.
--   **Skill:** Use `skills/engineering-discipline/SKILL.md`. Reason in order: Responsibilities -> Invariants -> Dependency Direction -> Syntax.
--   **Visual work:** If the task changes how something looks, feels, moves, or is interacted with, use `skills/designer/SKILL.md` FIRST to produce a DESIGN.md contract before any visual code. The DESIGN.md becomes the input spec for `forge-plan`.
--   **Constraint:** Never start at syntax. If you do, you are building slop.
-
-### Phase 3: Execution (The Implementation)
--   **Actions:** Apply surgical changes. Use real commands from MCP patterns.
--   **Skill:** Use `skills/design-patterns-skill/SKILL.md` to select the correct abstraction (Factory, Strategy, etc.).
--   **Debugging:** If you encounter a failure during implementation, invoke `skills/debug-discipline/SKILL.md` before attempting any fix.
--   **Rules:** No `rAF`. No redundant comments. No speculative code.
-
-### Phase 4: Verification (The Audit)
--   **Actions:** Self-verify against failure modes.
--   **Skill:** Use `skills/security-review/SKILL.md` for API/Infrastructure logic.
--   **Completion gate:** Invoke `skills/ship-gate/SKILL.md` before claiming any phase or task is done.
--   **Output:** Use `skills/readme-writer/SKILL.md` to document the outcome with evidence.
-
----
-
-## 🧩 Part 1: MCP Data Plugins (The Body)
-
-Use these tools for **100% accurate** API details, props, code examples, and patterns.
-
-### ⚛️ Frontend Libraries
-- **React Flow v12** (`reactflow_*`): 56 APIs, Enterprise patterns (Zustand, Auto-layout, SSR).
-- **Motion for React v12** (`motion_*`): 33 APIs, Transitions reference, Layout animations.
-- **Lenis Scroll** (`lenis_*`): Smooth scroll setups, GSAP/Motion integration.
-- **React 19 & Next.js** (`react_*`): RSC patterns, State hierarchy, Data fetching rules.
-
-### 🐹 Backend & Systems
-- **Echo (Go)** (`echo_*`): 19 recipes, Middleware chain, JWT auth, WebSocket.
-- **Golang Practices** (`golang_*`): 18 best practices, 10 idiomatic design patterns.
-- **Rust Practices** (`rust_*`): Borrowing rules, Error handling (anyhow/thiserror), Performance.
-
-### 💅 Design Systems
-- **Designer** (`designer_*`): Decision layer - 17 tools. 6 personality clusters, 15 industry rules, 11 cognitive laws, 13 page templates, 9 code-ready presets (Linear/Stripe/Vercel/Apple/Carbon/shadcn/Notion/Supabase/Figma), 21 font pairings, 50+ anti-patterns. Call `designer_resolve_intent` first for any visual task.
-- **Design Tokens** (`design_tokens_*`): Tailwind v4 + OKLCH templates, Color ramp math.
-- **UI/UX Principles** (`ui_ux_*`): WCAG contrast, Typography scales, 4px grid rules.
-
----
-
-## 🧠 Part 2: Engineering Skills (The Brain)
-
-These are static guidelines in the `skills/` directory. Read them using file tools.
-
-### Workflow Skills (process gates -- follow in order)
-- **Blueprint** (`skills/blueprint/SKILL.md`): MCP-surveyed design with hard gate before any code.
-- **Forge Plan** (`skills/forge-plan/SKILL.md`): MCP-verified implementation plan after design approval.
-- **Run Plan** (`skills/run-plan/SKILL.md`): Validate and execute an existing plan or spec.
-- **Debug Discipline** (`skills/debug-discipline/SKILL.md`): Root cause first. MCP-informed. 3-strike escalation.
-- **Ship Gate** (`skills/ship-gate/SKILL.md`): Evidence required before any completion claim.
-- **Deliver** (`skills/deliver/SKILL.md`): Final verification and delivery -- terminal state of every workflow.
-
-### Execution Skills (used during implementation)
-- **Autonomous Mode** (`skills/autonomous-mode/SKILL.md`): Full end-to-end execution, no human pauses, stops only on failure.
-- **Subagent Ops** (`skills/subagent-ops/SKILL.md`): Fresh agent per task, two-stage review (spec + quality).
-- **Test First** (`skills/test-first/SKILL.md`): Red-green-refactor discipline before any implementation code.
-- **Worktree Isolation** (`skills/worktree-isolation/SKILL.md`): Clean workspace isolation before feature work.
-- **Code Review** (`skills/code-review/SKILL.md`): Dispatch reviewer subagent, handle feedback technically.
-- **Parallel Dispatch** (`skills/parallel-dispatch/SKILL.md`): Concurrent agent dispatch for independent tasks.
-
-### Domain Skills (execution guidance)
-- **Engineering Discipline** (`skills/engineering-discipline/SKILL.md`): The Senior SDE phase-gate framework.
-- **Designer** (`skills/designer/SKILL.md`): Intention gate for visual/UX work. Produces DESIGN.md contract before any visual code. Auto-resolves industry/personality/style, routes to cognitive laws, enforces anti-slop rules. Use for: landing pages, dashboards, component libraries, redesigns, any new visual direction.
-- **Behaviour Analysis** (`skills/behaviour-analysis/SKILL.md`): State audits & Nielsen heuristics.
-- **Design Patterns** (`skills/design-patterns-skill/SKILL.md`): Clean Code & Pragmatic patterns.
-- **Security Review** (`skills/security-review/SKILL.md`): OWASP audits & vulnerability checklists.
-- **Readme Writer** (`skills/readme-writer/SKILL.md`): Evidence-based documentation standards.
-
----
-
-## 🚩 Red Flags (STOP and Re-read)
-
-These are the rationalizations you will have when you want to skip Hyperstack. Every one is wrong. Every one has been used before to ship bugs, wrong APIs, and AI slop.
-
-| Thought | Why it is wrong |
-|---|---|
-| "The issue is simple, I don't need to check the docs" | Simple issues are where wrong assumptions hide. Call the MCP tool. |
-| "I'll write the tests after I confirm it works" | "Confirm it works" by running a failing test first. Then pass it. That is the order. |
-| "This pattern looks common, I'll just adapt it from memory" | Memory drifts. Common patterns have version-specific differences. Call the tool. |
-| "I'll just add one quick fix now and investigate the root cause later" | Later never comes. Investigate first. |
-| "The user is impatient, I'll skip the gates" | User impatience is not permission to ship slop. Gates exist because shortcuts fail. |
-| "I know this API from memory" | Memory is v11 of the API. MCP has v12. Call the tool. |
-| "This is a minor refactor, tests are overkill" | Minor refactors without tests are random code edits. Tests first. |
-| "The skill takes too long" | Skills take minutes. Fixing wrong code takes days. Use the skill. |
-| "I'll verify after I push" | After you push it is in CI and your partner's context. Verify BEFORE. |
-| "Just this once" | There is no "just this once." No exceptions. |
-| "I already checked this earlier in the conversation" | State drifts. Check again. |
-| "The skill doesn't quite match this situation" | Invoke it anyway. If it truly doesn't apply, you lose 10 seconds. |
-| "I can reason about this without MCP" | No you cannot. MCP exists because reasoning without it produced the bugs that made the MCP necessary. |
-| "I'm tired and want to finish" | Stop. Rest. Do not ship unverified work. |
-| "Different wording, so the rule doesn't apply" | The letter of the rule IS the spirit of the rule. |
-
-**STOP. Return to Phase 1. Load the ground-truth data from MCP.**
+This file provides Cursor trigger metadata only. All operational rules, Iron Laws, MCP tool references, and skill condition table are in the canonical file above.