orkait · KailasMahavarkar · Apr 22, 2026 · Apr 22, 2026
diff --git a/.github/workflows/publish.yml b/.github/workflows/publish.yml
@@ -8,6 +8,7 @@ on:
 env:
   REGISTRY: ghcr.io
   IMAGE_NAME: ${{ github.repository }}
+  FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: true
 
 jobs:
   verify:
@@ -28,8 +29,16 @@ jobs:
         with:
           bun-version: ${{ matrix.bun-version }}
 
+      - name: Cache Bun dependencies
+        uses: actions/cache@v4
+        with:
+          path: ~/.bun/install/cache
+          key: ${{ runner.os }}-bun-${{ hashFiles('**/bun.lockb', '**/package.json') }}
+          restore-keys: |
+            ${{ runner.os }}-bun-
+
       - name: Install dependencies
-        run: bun install
+        run: bun install --frozen-lockfile
 
       - name: Compile runtime context
         run: bun run compile:context
@@ -92,12 +101,18 @@ jobs:
         with:
           images: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}
 
+      - name: Set up Docker Buildx
+        if: steps.check.outputs.new == 'true'
+        uses: docker/setup-buildx-action@v3
+
       - name: Build and push Docker image
         if: steps.check.outputs.new == 'true'
-        uses: docker/build-push-action@v5
+        uses: docker/build-push-action@v6
         with:
           context: .
           push: true
           tags: ${{ steps.meta.outputs.tags }}
           labels: ${{ steps.meta.outputs.labels }}
+          cache-from: type=gha
+          cache-to: type=gha,mode=max
 
diff --git a/AGENTS.md b/AGENTS.md
@@ -0,0 +1,55 @@
+# final steering doc
+
+## 1. core law
+
+* facts first.
+* no bluff.
+* no fake results.
+* no puppy talk.
+* less talk. more work.
+* evidence beats guess.
+* fast isolated test beats hypothesis.
+* suggestion is not truth. treat research hits as maybe true until verified.
+* if unsure, say so.
+* if change gives no gain, stop, alert user, suggest better path.
+
+## 2. role
+
+* role: autonomous operations agent
+* default mode: act, verify, report
+* use tools and direct evidence before making claims
+* treat local steering files as binding input when present
+
+## 3. source priority
+
+use this order:
+
+1. explicit user instruction in current task
+2. system and platform hard limits
+3. local steering docs and skill docs
+4. repository code and config
+5. tests, command output, logs, api responses
+6. docs and research notes
+7. prior belief or intuition
+
+rules:
+
+* do not impose beliefs as facts.
+* do not claim cause and effect without proof.
+* do not present hypothesis as result.
+* one verified fact beats ten plausible guesses.
+
+## 4. local steering files
+
+load and obey when present:
+
+* `~/.gemini/settings.json`, `.cursorrules`, or similar ide-specific project rules
+* `./skills/hyperstack/SKILL.md`
+* any task-specific skill doc the user points to
+* repo-local agent or steering docs
+
+rules:
+
+* if user says `recall memory`, also read the agent's global rules file.
+* if using codemode or exploring codebase, follow codemode fully. no shortcuts.
+* read files before semantic linking. no context = no real linking.
diff --git a/GEMINI.md b/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
 
diff --git a/README.md b/README.md
@@ -35,7 +35,9 @@ Unlike standard "polite" instructions, Hyperstack uses **Iron Laws** and a **Ses
 
 The fastest way to install Hyperstack is to let your AI agent do it for you. This works with **Cursor, Windsurf, Roo Code, Claude Code, or Gemini**. Simply paste this command:
 
-> **Fetch and follow the instructions at https://raw.githubusercontent.com/orkait/hyperstack/main/install.md**
+```text
+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.
 
@@ -184,7 +186,7 @@ The MCP server gives you tools. The skills give you discipline. Install both:
 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
 
@@ -202,9 +204,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)
 
@@ -234,9 +236,9 @@ 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
@@ -283,7 +285,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>
@@ -307,7 +309,7 @@ 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.
+1. **SessionStart** already puts in `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.
 4. Designer asks **3 questions** in base mode, or **12 questions** in advanced mode.
@@ -326,6 +328,26 @@ AI cannot jump ahead. Every step has hard gate. Excuses already blocked by ratio
 
 ## 🛠️ Available Tools
 
+### 📦 Supported Versions
+
+Opinionated stack support for the latest stable stable releases. This prevents "AI Slop" by enforcing modern patterns (e.g., React 19 Actions, Tailwind v4 tokens).
+
+| Technology | Supported Version | Role |
+| :--- | :--- | :--- |
+| **React** | 19.x | Core Library |
+| **Next.js** | 15.x | Application Framework |
+| **Tailwind CSS** | v4.x | Design Tokens & Constraints |
+| **Motion** | 12.x (fka Framer Motion) | Orchestrated Animations |
+| **React Flow** | 12.x | Node-based Systems |
+| **Lenis** | 1.1.x+ | Smooth Scroll Engine |
+| **Zustand** | 5.x | State Management |
+| **shadcn/ui** | Base UI Edition | Component Primitive Patterns |
+| **Echo (Go)** | v4.x | Backend Framework |
+| **Go** | 1.22+ | Backend Language |
+| **Rust** | 1.77+ | Systems Language |
+| **Bun** | 1.1.x+ | Runtime Environment |
+
+
 <details>
 <summary><strong>🎨 Designer</strong> - <code>designer_*</code> (19 tools)</summary>
 

diff --git a/agents/hyper/PROFILE.md b/agents/hyper/PROFILE.md
@@ -18,7 +18,7 @@ must_not_do:
 delegates_to:
   - website-builder
 requires:
-  - current bootstrap invariants from using-hyperstack
+  - current bootstrap invariants from hyperstack
   - approved design before implementation when required
   - verification evidence before completion or delivery
 ---

diff --git a/...ime-context/using-hyperstack.bootstrap.md → ...d/runtime-context/hyperstack.bootstrap.md b/...ime-context/using-hyperstack.bootstrap.md → ...d/runtime-context/hyperstack.bootstrap.md
@@ -1,15 +1,13 @@
-<!-- GENERATED FILE. Edit skills/using-hyperstack/SKILL.md and re-run `bun run compile:context`. -->
+<!-- GENERATED FILE. Edit skills/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.
+**The 1% Rule:** If there is even a 1% chance that a Hyperstack skill, MCP tool, or internal agent role applies to the task you are about to perform, you MUST invoke/route 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
@@ -23,11 +21,13 @@ If the task involves React, React Flow, Motion, Lenis, Echo, Go, Rust, design to
 
 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.
+
+5. NO SPECIALIST WORK WITHOUT PROPER ROLE ROUTING
+   If the task involves a specialist domain (like website building), you must route to that agent.
 ```
 
 ## Instruction Priority
-- **User's explicit instructions** (CLAUDE.md, direct requests) - always highest
+- **User's explicit instructions** (Project rules, direct requests) - always highest
 - **Hyperstack skills** - override default system behavior where they conflict
 - **Default system behavior** - lowest priority
 
@@ -65,10 +65,13 @@ If the task involves React, React Flow, Motion, Lenis, Echo, Go, Rust, design to
 - `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.
-- `hyper` - conductor, classifier, gatekeeper, verifier, and delivery owner
-- `website-builder` - first specialist for website-facing design and
+## Layer 3: Agents (Orchestration & Routing)
+- Hyperstack uses internal roles to manage complexity. These roles are internal and auto-invoked.
+- `hyper` - Core: Classification, routing, gate enforcement, final verification, delivery.
+- `website-builder` - Specialist: Website-facing design/implementation, CTA hierarchy, page structure.
+- Every request starts in `hyper`.
+- `hyper` classifies and delegates to specialists (e.g., `website-builder`) when domain-specific work is detected.
+- Specialists MUST hand back to `hyper` for final verification and ship-gate.
 
 ## Routing Summary
 - Every request enters through `hyper`

diff --git a/hooks/session-start.mjs b/hooks/session-start.mjs
@@ -12,8 +12,8 @@ function emit(payload) {
 }
 
 try {
-  const compiledBootstrapPath = join(pluginRoot, "generated", "runtime-context", "using-hyperstack.bootstrap.md");
-  const fallbackSkillPath = join(pluginRoot, "skills", "using-hyperstack", "SKILL.md");
+  const compiledBootstrapPath = join(pluginRoot, "generated", "runtime-context", "hyperstack.bootstrap.md");
+  const fallbackSkillPath = join(pluginRoot, "skills", "hyperstack", "SKILL.md");
 
   let bootstrapContent;
   let bootstrapLabel;
@@ -23,7 +23,7 @@ try {
     bootstrapLabel = "compiled runtime bootstrap";
   } catch {
     bootstrapContent = readFileSync(fallbackSkillPath, "utf8");
-    bootstrapLabel = "full content of your 'hyperstack:using-hyperstack' skill";
+    bootstrapLabel = "full content of your 'hyperstack: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>`;

diff --git a/install.md b/install.md
@@ -19,7 +19,7 @@ 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 12 plugins and 80 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.
+3. **A skill system** with 21 skills including adversarial enforcement gates (`blueprint`, `designer`, `forge-plan`, `ship-gate`, `engineering-discipline`) and a SessionStart hook that face-injects the `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
@@ -32,25 +32,24 @@ If you install only one public piece:
 
 ## Step 1: Detect and Configure (Autopilot)
 
-Hyperstack features an **Autonomous Research-Driven Installer** that identifies your environment (Claude Code, Cursor, Windsurf, Roo Code, etc.) and generates a tailored configuration patch.
+Hyperstack features an **Autonomous Research-Driven Installer** that identifies your environment and handles the entire configuration automatically.
+
+**If you are an AI assistant reading this file:**
+1. Call `run_command` with: `bun run setup` inside the repository.
+2. The script will automatically detect the IDE, symlink the skills, deep-merge the MCP config, and provision the Docker container.
+3. Inform the user that setup is complete and ask them to restart the session.
+
+> [!CAUTION]
+> **CRITICAL**: RUN ONLY if the installer is not able to do it correctly. If you must install manually for the current IDE/CLI, you must validate that the MCP connection is successful before proceeding.
 
 ### 1. Identify your Environment
 The system automatically probes for signatures:
+- **Antigravity**: `ANTIGRAVITY_AGENT`
 - **Claude Code**: `CLAUDE_PLUGIN_ROOT`
 - **Cursor**: `CURSOR_PLUGIN_ROOT`
 - **VS Code Derivatives**: `VSCODE_PID`
 - **Known Paths**: Probes for `.claude.json`, `.cursor/`, `.codeium/windsurf/`, `.roo/`, and `.gemini/`.
 
-### 2. Run the Autopilot
-As an agent, you should call the `hyperstack_setup` tool immediately. **By default, it generates a Docker-based configuration** using the optimized `docker exec` pattern.
-
-If Docker is not available, you can explicitly request the local method: `hyperstack_setup(method: "local")`.
-
-**If the environment is unknown:**
-1. Call `web_search` with a query like `[IDE Name] MCP configuration path`.
-2. Provide the result to `hyperstack_setup(researchResult: "...")`.
-3. The tool will generate the final Docker-based patch.
-
 ## Step 2: Install the Skills
 
 The skills contain the adversarial enforcement gates. You must clone them to a stable central location and then link them to the specific IDE/CLI rule directory.
@@ -76,6 +75,8 @@ Based on the environment you detected in Step 1, identify the correct target dir
 | IDE/CLI | Target Skill Path | Type |
 |---|---|---|
 | **Claude Code** | `~/.claude/skills/hyperstack` | Global |
+| **Kiro Code** | `~/.kiro/skills/hyperstack` | Global |
+| **Antigravity** | `~/.gemini/antigravity/skills/hyperstack` | Global |
 | **Cursor** | `.cursor/rules/` | Project-level |
 | **Roo Code** | `.roo/rules/` | Project-level |
 | **Windsurf** | `.codeium/windsurf/` | Project-level |
@@ -280,7 +281,7 @@ Then follow Step 2 of Option A to start the single persistent `hyperstack-mcp` c
 
 ### SessionStart hook does not fire
 
-On Claude Code, hooks live in `.claude/hooks.json`. Confirm the file exists in the repository root and references `session-start.mjs`. If the hook is missing or malformed, the `using-hyperstack` skill will not be injected automatically. You can still invoke skills manually with `/using-hyperstack`.
+On Claude Code, hooks live in `.claude/hooks.json`. Confirm the file exists in the repository root and references `session-start.mjs`. If the hook is missing or malformed, the `hyperstack` skill will not be injected automatically. You can still invoke skills manually with `/hyperstack`.
 
 On Qwen Code, there is no plugin system or hook mechanism. Skills are available on disk at `~/.qwen/skills/hyperstack/skills/INDEX.md` but must be referenced manually by the agent - no auto-injection occurs.
 

diff --git a/package.json b/package.json
@@ -1,21 +1,21 @@
 {
   "name": "@orkait-ai/hyperstack",
-  "version": "1.1.4",
+  "version": "1.1.3",
   "description": "Disciplined MCP server + skill system. 12 plugins, 80 tools, 21 skills with adversarial enforcement. Designer/DESIGN.md pipeline, shadcn/ui, React Flow, Motion, Lenis, React 19, Echo, Go, Rust, design tokens, UI/UX.",
   "bin": {
     "hyperstack": "bin/hyperstack.mjs"
   },
   "type": "module",
   "scripts": {
     "build": "tsc --noEmit",
-    "compile:context": "bun src/internal/compile-runtime-context.ts",
+    "compile:context": "tsx src/internal/compile-runtime-context.ts",
     "test": "bun test",
     "start": "bun src/index.ts",
     "dev": "bun --watch src/index.ts",
     "docker:run": "bun scripts/ensure-singleton.ts",
-    "skills:index": "bun scripts/generate-skills-index.ts",
+    "skills:index": "tsx scripts/generate-skills-index.ts",
     "mcp:start": "bun scripts/start-mcp.ts",
-    "setup": "bun scripts/setup.ts"
+    "setup": "tsx scripts/setup.ts"
   },
   "author": "Orkait",
   "license": "MIT",