🧠 The Hyperstack Engine

---

⚖️ 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.

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.

---

🚦 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.