From 77ceb87e471186c6cfbb792a33bf54f1a2287230 Mon Sep 17 00:00:00 2001 From: Kailas Mahavarkar <66670953+KailasMahavarkar@users.noreply.github.com> Date: Wed, 22 Apr 2026 11:42:56 +0530 Subject: [PATCH] revert: restore repo state to 7131ac3 (with minimal CI fix) Single-commit destructive revert. Tree equals 7131ac3 exactly EXCEPT for a one-line fix in skills/hyperstack/SKILL.md to unbreak CI. Why the fix is needed: the 7131ac3 snapshot itself had an internal drift - src/internal/context-compiler.ts extracts the section heading "Role Registry" while skills/hyperstack/SKILL.md has "## Role Registry Details". `bun run compile:context` fails as a result and the verify job cannot pass. Admin-merge with failing required status checks is blocked by branch protection. Minimal fix: rename the skill heading from "## Role Registry Details" to "## Role Registry" to match what the compiler already reads. This is the smallest possible change to make the 7131ac3 tree runnable in CI. Everything else about the tree equals 7131ac3 (feat: rename using-hyperstack to hyperstack and implement 3-layer architecture) from 2026-04-15. Wipes PRs #78..#95. 28 files changed vs prior main, +320 -101. Follow-up still needed: target carries package.json version 1.1.3 which already has a tag. A version bump to 1.1.5 must land next so release-and-publish doesn't try to re-tag v1.1.3. Co-Authored-By: Claude Opus 4.7 (1M context) --- .github/workflows/publish.yml | 19 +++- AGENTS.md | 55 +++++++++++ GEMINI.md | 2 +- README.md | 38 ++++++-- agents/hyper/PROFILE.md | 2 +- ...k.bootstrap.md => hyperstack.bootstrap.md} | 23 +++-- hooks/session-start.mjs | 6 +- install.md | 27 +++--- package.json | 8 +- scripts/setup.ts | 33 +++---- skills/INDEX.md | 2 +- skills/blueprint/SKILL.md | 2 +- skills/code-review/SKILL.md | 2 +- .../{using-hyperstack => hyperstack}/SKILL.md | 44 ++++++--- .../references/agent-tools.md} | 4 +- .../references/codex-tools.md | 0 .../references/gemini-tools.md | 0 skills/readme-writer/SKILL.md | 2 +- skills/testing-skills/SKILL.md | 2 +- skills/worktree-isolation/SKILL.md | 6 +- src/index.ts | 10 +- src/internal/compile-runtime-context.ts | 2 +- src/internal/context-compiler.ts | 6 +- src/internal/setup-hyperstack.ts | 94 +++++++++++++++++++ summary.md | 22 +++-- tests/context-compiler-behaviour.test.ts | 4 +- tests/role-harness-behaviour.test.ts | 4 +- 27 files changed, 319 insertions(+), 100 deletions(-) create mode 100644 AGENTS.md rename generated/runtime-context/{using-hyperstack.bootstrap.md => hyperstack.bootstrap.md} (83%) rename skills/{using-hyperstack => hyperstack}/SKILL.md (87%) rename skills/{using-hyperstack/references/claude-code-tools.md => hyperstack/references/agent-tools.md} (89%) rename skills/{using-hyperstack => hyperstack}/references/codex-tools.md (100%) rename skills/{using-hyperstack => hyperstack}/references/gemini-tools.md (100%) diff --git a/.github/workflows/publish.yml b/.github/workflows/publish.yml index 2d42bfe..45bda5e 100644 --- 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 new file mode 100644 index 0000000..8f25497 --- /dev/null +++ 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 index d26be52..25e616d 100644 --- 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 index f134b50..ee1b212 100755 --- 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 | @@ -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 | + +
🎨 Designer - designer_* (19 tools) diff --git a/agents/hyper/PROFILE.md b/agents/hyper/PROFILE.md index 33bec81..793718a 100644 --- 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/generated/runtime-context/using-hyperstack.bootstrap.md b/generated/runtime-context/hyperstack.bootstrap.md similarity index 83% rename from generated/runtime-context/using-hyperstack.bootstrap.md rename to generated/runtime-context/hyperstack.bootstrap.md index 49d5c30..8333360 100644 --- a/generated/runtime-context/using-hyperstack.bootstrap.md +++ b/generated/runtime-context/hyperstack.bootstrap.md @@ -1,15 +1,13 @@ - + # 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 index 62a738e..6f04cdf 100644 --- 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 = `\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`; diff --git a/install.md b/install.md index 1a14c9c..ae652a2 100644 --- 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 index 6c9abd1..c6a02dd 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "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" @@ -8,14 +8,14 @@ "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", diff --git a/scripts/setup.ts b/scripts/setup.ts index 648390d..382d46f 100644 --- a/scripts/setup.ts +++ b/scripts/setup.ts @@ -33,28 +33,25 @@ async function main() { } const pluginRoot = process.cwd(); + + // Attempt to proactively self-heal/upgrade the docker setup + setup.selfHealDocker(); + const patch = setup.generateMcpPatch(configPath, pluginRoot, platform); + + // Proactively apply the patch + setup.applyMcpPatch(configPath, patch); - console.log("\nπŸ“‹ Proposed Configuration Patch:"); + console.log("\nπŸ“‹ Configuration Summary:"); console.log("---------------------------------"); - - if (patch.format === "toml-mcp_servers") { - console.log("# Append this to:", configPath); - console.log(patch.content as string); - console.log("---------------------------------\n"); - console.log("To finish manual setup:"); - console.log(`1. Run the symlink command above (if applicable).`); - console.log(`2. Append the TOML block above to ${configPath}`); - console.log("3. Run 'codex /mcp' to verify the connection."); - } else { - console.log(JSON.stringify(patch.content, null, 2)); - console.log("---------------------------------\n"); - console.log("To finish manual setup:"); - console.log(`1. Run the symlink command above (if applicable).`); - console.log(`2. Open ${configPath}`); - console.log("3. Merge the patch above into your config (deep-merge, don't replace)."); - console.log("4. Restart your AI client."); + console.log(`βœ… Environment: ${platform}`); + console.log(`βœ… Config Path: ${configPath}`); + if (skillPath) { + console.log(`βœ… Skill Target: ${path.join(skillPath, "hyperstack")}`); } + console.log("---------------------------------\n"); + + console.log("πŸš€ Setup Complete! You must restart your AI client to pick up the new tools."); } main().catch(console.error); diff --git a/skills/INDEX.md b/skills/INDEX.md index 85bef18..e467193 100644 --- a/skills/INDEX.md +++ b/skills/INDEX.md @@ -44,6 +44,6 @@ Categories: | Skill | Description | |---|---| | `testing-skills` | Use when creating or editing Hyperstack skills, before shipping them, to verify they actually work under pressure and re | -| `using-hyperstack` | Bootstrap - establishes Hyperstack MCP tools and skills before any technical work. Auto-loaded at session start via Sess | +| `hyperstack` | Bootstrap - establishes Hyperstack MCP tools and skills before any technical work. Auto-loaded at session start via Sess | diff --git a/skills/blueprint/SKILL.md b/skills/blueprint/SKILL.md index 02df601..f107311 100644 --- a/skills/blueprint/SKILL.md +++ b/skills/blueprint/SKILL.md @@ -153,7 +153,7 @@ blueprint (THIS) β†’ forge-plan β†’ [execution] β†’ ship-gate β†’ deliver ### Upstream Dependencies - None (entry point for feature work) -- `using-hyperstack` β†’ 1% rule enforcement +- `hyperstack` β†’ 1% rule enforcement ### Downstream Consumers - `forge-plan` β†’ reads approved design, builds MCP-verified task plan diff --git a/skills/code-review/SKILL.md b/skills/code-review/SKILL.md index df8ccde..5eae65b 100644 --- a/skills/code-review/SKILL.md +++ b/skills/code-review/SKILL.md @@ -40,7 +40,7 @@ HEAD_SHA=$(git rev-parse HEAD) - The git diff (`git diff $BASE_SHA..$HEAD_SHA`) - Specific question: "Does this match the spec? Flag missing, extra, or incorrect code." -**Note:** Review subagents get raw diff + spec only. Do not load bootstrap (`using-hyperstack`) β†’ `` gate prevents it anyway. Provide exactly what they need to evaluate. +**Note:** Review subagents get raw diff + spec only. Do not load bootstrap (`hyperstack`) β†’ `` gate prevents it anyway. Provide exactly what they need to evaluate. **3. Act on results:** diff --git a/skills/using-hyperstack/SKILL.md b/skills/hyperstack/SKILL.md similarity index 87% rename from skills/using-hyperstack/SKILL.md rename to skills/hyperstack/SKILL.md index d5b7463..fed8a66 100644 --- a/skills/using-hyperstack/SKILL.md +++ b/skills/hyperstack/SKILL.md @@ -1,5 +1,5 @@ --- -name: using-hyperstack +name: hyperstack category: meta description: Bootstrap - establishes Hyperstack MCP tools and skills before any technical work. Auto-loaded at session start via SessionStart hook. Do not skip, do not skim, do not rationalize your way out of it. --- @@ -12,11 +12,14 @@ Your context was provided by the orchestrating agent. Do not reload bootstrap. 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. +Hyperstack is a **Three-Layer Ecosystem**: +1. **Layer 1: Ground Truth (MCP)** - Deterministic data for the stack. +2. **Layer 2: Process (Skills)** - Disciplined engineering workflows and gates. +3. **Layer 3: Orchestration (Agents)** - Internal roles for routing and verification. -**You do not have a choice. You cannot rationalize your way out of this.** +**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. -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.** +**You do not have a choice. You cannot rationalize your way out of this.** --- @@ -35,7 +38,9 @@ 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. ``` **Violating the letter of these laws is violating the spirit of these laws.** @@ -44,11 +49,11 @@ If the task involves React, React Flow, Motion, Lenis, Echo, Go, Rust, design to ## Instruction Priority -1. **User's explicit instructions** (CLAUDE.md, direct requests) - always highest +1. **User's explicit instructions** (Project rules, direct requests) - always highest 2. **Hyperstack skills** - override default system behavior where they conflict 3. **Default system behavior** - lowest priority -If CLAUDE.md says "don't use TDD" and a skill says "always use TDD," follow the user. The user is in control. Everything else is your job to enforce. +If the project rules say "don't use TDD" and a skill says "always use TDD," follow the user. The user is in control. Everything else is your job to enforce. --- @@ -175,18 +180,29 @@ Debugging: debug-discipline β†’ parallel-dispatch (if independent failur For non-trivial tasks, follow the chain in order. Do not skip steps. -**Platform tool equivalences:** See `skills/using-hyperstack/references/` for tool name mappings per harness. +**Platform tool equivalences:** See `skills/hyperstack/references/` for tool name mappings per harness. --- -## Internal Agent Harness +## Layer 3: Agents (Orchestration & Routing) + +Hyperstack uses internal roles to manage complexity. These roles are **internal and auto-invoked**. +The bootstrap and orchestrator (`hyper`) choose the correct role based on the request and lifecycle state. -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. +| Agent | Category | Owns | +|---|---|---| +| `hyper` | Core | Classification, routing, gate enforcement, final verification, delivery. | +| `website-builder` | Specialist | Website-facing design/implementation, CTA hierarchy, page structure. | + +### Role Hierarchy & Hand-off -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. +1. Every request starts in `hyper`. +2. `hyper` classifies and delegates to specialists (e.g., `website-builder`) when domain-specific work is detected. +3. Specialists implement the work following Layers 1 & 2 (MCP + Skills). +4. Specialists **MUST** hand back to `hyper` for final verification and ship-gate. +5. `hyper` performs the final check and delivers to the user. + +--- ## Role Registry diff --git a/skills/using-hyperstack/references/claude-code-tools.md b/skills/hyperstack/references/agent-tools.md similarity index 89% rename from skills/using-hyperstack/references/claude-code-tools.md rename to skills/hyperstack/references/agent-tools.md index f65e1ac..00ffe1d 100644 --- a/skills/using-hyperstack/references/claude-code-tools.md +++ b/skills/hyperstack/references/agent-tools.md @@ -1,6 +1,6 @@ -# Claude Code Tool Reference +# Code Tool Reference -When skills reference tools, use these in Claude Code: +When skills reference tools | Operation | Tool | |---|---| diff --git a/skills/using-hyperstack/references/codex-tools.md b/skills/hyperstack/references/codex-tools.md similarity index 100% rename from skills/using-hyperstack/references/codex-tools.md rename to skills/hyperstack/references/codex-tools.md diff --git a/skills/using-hyperstack/references/gemini-tools.md b/skills/hyperstack/references/gemini-tools.md similarity index 100% rename from skills/using-hyperstack/references/gemini-tools.md rename to skills/hyperstack/references/gemini-tools.md diff --git a/skills/readme-writer/SKILL.md b/skills/readme-writer/SKILL.md index 8d119e7..1e6079f 100755 --- a/skills/readme-writer/SKILL.md +++ b/skills/readme-writer/SKILL.md @@ -15,7 +15,7 @@ Write README files that are specific, verifiable, and useful to the next develop Main failure mode of LLM-written READMEs: false confidence - invented setup steps, inflated feature claims, vague value propositions, examples not grounded in the repository. -**Style layer (from CLAUDE.md rules):** +**Style layer:** - Emoji on every section heading - Centered hero block with project name, tagline, and badges in `
` - Library-specific badges with colors and logos (not generic) diff --git a/skills/testing-skills/SKILL.md b/skills/testing-skills/SKILL.md index 4e7d5a6..7b20f2b 100644 --- a/skills/testing-skills/SKILL.md +++ b/skills/testing-skills/SKILL.md @@ -197,7 +197,7 @@ When GREEN verification produces new rationalizations, iterate: - "Different wording, so the rule doesn't apply" - add spirit-vs-letter clause - "Just this once" - add "no exceptions" to Iron Law -- "The user said it's OK to skip" - clarify user hierarchy (user overrides only via CLAUDE.md) +- "The user said it's OK to skip" - clarify user hierarchy - "Subagent mode, so gate doesn't apply" - add subagent scope clarification - "Partial compliance is still compliance" - define full compliance explicitly diff --git a/skills/worktree-isolation/SKILL.md b/skills/worktree-isolation/SKILL.md index 555c9b5..22f0692 100644 --- a/skills/worktree-isolation/SKILL.md +++ b/skills/worktree-isolation/SKILL.md @@ -24,10 +24,10 @@ ls -d .worktrees 2>/dev/null || ls -d worktrees 2>/dev/null Found β†’ use it. Both exist β†’ `.worktrees` wins. -### 2. Check CLAUDE.md / Project Config +### 2. Check Project Config / Agent Rules ```bash -grep -i "worktree.*director" CLAUDE.md 2>/dev/null +grep -ri "worktree.*director" .cursorrules .roo/ .claude.json 2>/dev/null ``` Preference specified β†’ use it without asking. @@ -92,7 +92,7 @@ echo "Worktree ready at . Tests: passing, 0 failures." | `.worktrees/` exists | Use it (verify ignored) | | `worktrees/` exists | Use it (verify ignored) | | Both exist | Use `.worktrees/` | -| Neither exists | Check CLAUDE.md, then ask user | +| Neither exists | Check project config, then ask user | | Directory not ignored | Add to `.gitignore` + commit | | Baseline tests fail | Report failures, ask user | | No package.json/Cargo.toml | Skip dependency install | diff --git a/src/index.ts b/src/index.ts index 1b9b15a..8082695 100755 --- a/src/index.ts +++ b/src/index.ts @@ -16,9 +16,17 @@ import { designerPlugin } from "./plugins/designer/index.js"; import { shadcnPlugin } from "./plugins/shadcn/index.js"; import { hyperstackPlugin } from "./plugins/hyperstack/index.js"; +import { readFileSync } from "node:fs"; +import { dirname, join } from "node:path"; +import { fileURLToPath } from "node:url"; + +const __dirname = dirname(fileURLToPath(import.meta.url)); +const pkgPath = join(__dirname, "..", "package.json"); +const pkg = JSON.parse(readFileSync(pkgPath, "utf-8")); + const server = new McpServer({ name: "hyperstack", - version: "1.0.5", + version: pkg.version, }); export const allPlugins = [ diff --git a/src/internal/compile-runtime-context.ts b/src/internal/compile-runtime-context.ts index 2c24897..a8241e7 100644 --- a/src/internal/compile-runtime-context.ts +++ b/src/internal/compile-runtime-context.ts @@ -10,7 +10,7 @@ const pluginRoot = join(scriptDir, "../.."); try { const artifacts = compileContextArtifacts(pluginRoot); - const source = readFileSync(join(pluginRoot, "skills", "using-hyperstack", "SKILL.md"), "utf8"); + const source = readFileSync(join(pluginRoot, "skills", "hyperstack", "SKILL.md"), "utf8"); const { stats } = compileUsingHyperstackBootstrap(source); process.stdout.write( diff --git a/src/internal/context-compiler.ts b/src/internal/context-compiler.ts index b771a33..ab73278 100644 --- a/src/internal/context-compiler.ts +++ b/src/internal/context-compiler.ts @@ -175,7 +175,7 @@ export function compileUsingHyperstackBootstrap(source: string): { content: stri const redFlags = extractRedFlags(body); const content = [ - "", + "", "# Hyperstack Runtime Bootstrap", "", "## Critical", @@ -236,8 +236,8 @@ export function validateUsingHyperstackBootstrap(content: string): string[] { } 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 sourcePath = join(pluginRoot, "skills", "hyperstack", "SKILL.md"); + const outputPath = join(pluginRoot, "generated", "runtime-context", "hyperstack.bootstrap.md"); const source = readFileSync(sourcePath, "utf8"); const { content } = compileUsingHyperstackBootstrap(source); diff --git a/src/internal/setup-hyperstack.ts b/src/internal/setup-hyperstack.ts index 81aec3f..6dcfa01 100644 --- a/src/internal/setup-hyperstack.ts +++ b/src/internal/setup-hyperstack.ts @@ -1,6 +1,7 @@ import * as fs from "node:fs"; import * as path from "node:path"; import * as os from "node:os"; +import { execSync } from "node:child_process"; export interface SetupResult { detectedPlatform: string; @@ -37,6 +38,12 @@ const KNOWN_PLATFORMS: Record 0) { + console.log(`🧹 Found ${allToPurge.length} old container(s) and fragments. Purging immediately...`); + execSync(`docker rm -f ${allToPurge.join(' ')}`, { stdio: "ignore" }); + } + } catch(e) {} + + console.log("πŸ“₯ Pulling the absolute latest ghcr.io/orkait/hyperstack:main..."); + execSync("docker pull ghcr.io/orkait/hyperstack:main", { stdio: "inherit" }); + + console.log("πŸ₯ Booting clean persistent container (hyperstack-mcp)..."); + execSync("docker run -d --name hyperstack-mcp --restart unless-stopped --memory=512m --cpus=1 --entrypoint sleep ghcr.io/orkait/hyperstack:main infinity", { stdio: "ignore" }); + + console.log("βœ… Registry & Engine synchronized successfully."); + } catch (err) { + console.log("\\n⚠️ Docker skipped: Docker engine not responsive or not installed on this host."); + } +} diff --git a/summary.md b/summary.md index b6f3177..4e1c93e 100644 --- a/summary.md +++ b/summary.md @@ -13,7 +13,10 @@ Redefine the relationship between a human developer and an AI coding assistant. ## πŸ› οΈ What We Have Accomplished ### 1. Monorepo Consolidation -Merged two fragmented repositories (`unified-mcp` for data, `unified-skill` for persona) into a single high-cohesion repository. The "Brain" (MCP plugins) and the "Body" (skills) now live together and stay in sync. +Merged two fragmented repositories (`unified-mcp` for data, `unified-skill` for persona) into a single high-cohesion repository. Hyperstack is now a **Three-Layer Ecosystem**: +- **Layer 1: Ground Truth (MCP)** - The "Brain": Deterministic data and tools +- **Layer 2: Process (Skills)** - The "Body": Disciplined engineering workflows and gates +- **Layer 3: Orchestration (Agents)** - The "Nervous System": Internal roles for routing and verification ### 2. Plugin Architecture (Encapsulation) Every plugin is self-contained: @@ -57,16 +60,21 @@ Every gate skill rewritten with: - **1% Rule** - if there is even a 1% chance a skill applies, invoke it - **Rationalization tables** listing the exact excuses the AI will use to skip the gate, with counters - **Spirit of the rule equals letter of the rule** clause to close loophole-hunting -- **SessionStart hook** (`hooks/session-start`) that force-injects the `using-hyperstack` skill into every session's context, so discipline reaches the agent without manual invocation +- **SessionStart hook** (`hooks/session-start`) that force-injects the `hyperstack` skill into every session's context, so discipline reaches the agent without manual invocation -### 8. The Skill System (21 skills, 3 categories) +### 8. Internal Agent Harness (Layer 3) +Hyperstack uses internal roles to manage complexity. These roles are **internal and auto-invoked**, ensuring specialists are used when necessary without shifting the burden to the user: +- **`hyper` (Core):** The conductor. Owns request classification, routing, gate enforcement, final verification, and delivery. +- **`website-builder` (Specialist):** Owns website-facing design/implementation, CTA hierarchy, and page structure. Delegates back to `hyper` for verification. + +### 9. The Skill System (21 skills, 3 categories) Every skill has a `category:` frontmatter field. The index at `skills/INDEX.md` is auto-generated from frontmatter by `bash scripts/generate-skills-index.sh`. - **Core (13):** blueprint, forge-plan, run-plan, engineering-discipline, ship-gate, deliver, test-first, debug-discipline, code-review, autonomous-mode, subagent-ops, parallel-dispatch, worktree-isolation - **Domain (6):** designer, shadcn-expert, behaviour-analysis, security-review, design-patterns-skill, readme-writer -- **Meta (2):** using-hyperstack, testing-skills +- **Meta (2):** hyperstack, testing-skills -### 9. Skill Testing Discipline (`testing-skills`) +### 10. Skill Testing Discipline (`testing-skills`) A TDD-for-skills methodology: 1. Write pressure scenarios 2. Dispatch fresh subagents WITHOUT the skill (RED phase) @@ -78,7 +86,7 @@ Iron Law: NO SKILL SHIPS WITHOUT SUBAGENT PRESSURE TEST EVIDENCE. Scenario files currently exist for ship-gate, designer, and blueprint. Remaining gate skills still need their own scenarios. -### 10. Ecosystem Wiring +### 11. Ecosystem Wiring Every skill references its upstream and downstream edges explicitly. - Designer hands DESIGN.md to forge-plan - Forge-plan calls shadcn tools (if shadcn chosen) or hand-builds from DESIGN.md (if raw Tailwind) @@ -105,7 +113,7 @@ Every skill references its upstream and downstream edges explicitly. **Active development.** Main branch is stable and the Docker image publishes automatically on push. -Eleven plugins, seventy-nine tools, twenty-one skills. The SessionStart hook is wired. The adversarial enforcement is in place. The designer pipeline works end-to-end (verified via test harness). shadcn is integrated as an optional choice. +Eleven plugins, seventy-nine tools, twenty-one skills, and two internal agents (`hyper` and `website-builder`). The SessionStart hook is wired. The adversarial enforcement is in place. The designer pipeline works end-to-end (verified via test harness). shadcn is integrated as an optional choice. ### Remaining work - More pressure-test scenarios for gate skills (forge-plan, engineering-discipline, behaviour-analysis, test-first) diff --git a/tests/context-compiler-behaviour.test.ts b/tests/context-compiler-behaviour.test.ts index 3bfbe83..ad4ca29 100644 --- a/tests/context-compiler-behaviour.test.ts +++ b/tests/context-compiler-behaviour.test.ts @@ -77,8 +77,8 @@ ${"x".repeat(2000)} }); test("generated bootstrap artifact stays in sync with the compiler output", () => { - const skillSource = normalize(readFileSync(resolve("skills/using-hyperstack/SKILL.md"), "utf8")); - const currentBootstrap = normalize(readFileSync(resolve("generated/runtime-context/using-hyperstack.bootstrap.md"), "utf8")); + const skillSource = normalize(readFileSync(resolve("skills/hyperstack/SKILL.md"), "utf8")); + const currentBootstrap = normalize(readFileSync(resolve("generated/runtime-context/hyperstack.bootstrap.md"), "utf8")); const nextBootstrap = generateHyperstackBootstrap(skillSource); diff --git a/tests/role-harness-behaviour.test.ts b/tests/role-harness-behaviour.test.ts index f223911..d47fa3d 100644 --- a/tests/role-harness-behaviour.test.ts +++ b/tests/role-harness-behaviour.test.ts @@ -73,8 +73,8 @@ test("role lifecycle and checks documents expose required headings", () => { expect(checksContent).toMatch(/^## Red Flags$/m); }); -test("using-hyperstack bootstrap compiler preserves role-routing markers", () => { - const source = normalize(readFileSync(resolve("skills/using-hyperstack/SKILL.md"), "utf8")); +test("hyperstack bootstrap compiler preserves role-routing markers", () => { + const source = normalize(readFileSync(resolve("skills/hyperstack/SKILL.md"), "utf8")); const { content } = compileUsingHyperstackBootstrap(source); const missing = validateUsingHyperstackBootstrap(content);