Skip to content

docs: refresh architecture around topology runtime #79

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
KailasMahavarkar merged 1 commit into from
Apr 19, 2026
Merged

docs: refresh architecture around topology runtime #79

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
80 changes: 43 additions & 37 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -96,39 +96,40 @@ It is not just a library; it is a **disciplined harness** made of three tightly-

```mermaid
graph TD
User([User Request]) --> Harness[Internal Harness]
Harness --> Gates{Adversarial Gates}

subgraph "The Enforcement Layer"
Gates -->|Iron Laws| Skills[21 Skills with Enforcement Teeth]
Skills -->|SessionStart| Injection[Auto-Context Injection]
end

subgraph "The Knowledge Layer"
Skills -->|Ground Truth| MCP[12 MCP Plugins / 80 Tools]
MCP -->|Designer| Design[DESIGN.md Pipeline]
MCP -->|Verified| Code[Programmatic Compliance Check]
end

Code -->|Verification Evidence| User

linkStyle 0 stroke:#9ca3af,stroke-width:2px
linkStyle 1 stroke:#9ca3af,stroke-width:2px
linkStyle 2 stroke:#9ca3af,stroke-width:2px
linkStyle 3 stroke:#9ca3af,stroke-width:2px
linkStyle 4 stroke:#9ca3af,stroke-width:2px
linkStyle 5 stroke:#9ca3af,stroke-width:2px
linkStyle 6 stroke:#9ca3af,stroke-width:2px
linkStyle 7 stroke:#9ca3af,stroke-width:2px
User([User Request]) --> Hyper[hyper]
Hyper --> Inventory[workspace_inventory]
Inventory --> Routing[Topology Router]
Routing --> Agent[frontend-builder / backend-builder / fullstack-builder]
Agent --> Skills[Skills + Gates]
Skills --> Runtime[Local Tool Runtime]
Runtime --> Topology[Topology Manifest]
Runtime --> Corpus[Corpus + Tool Modules]
Skills --> Verify[verification_report]
Verify --> User
```

**Current runtime model**

1. `hyper` receives the request.
2. `workspace_inventory` is built first.
3. Topology routes to the right agent and computes the required artifacts.
4. Skills enforce process and proof rules.
5. Local tool runtime resolves stable tool calls against topology + corpus-backed truth.
6. `verification_report` is required before completion claims.

**Important correction:** `DESIGN.md` is not universal anymore. Design contracts are conditional:
- required for new surfaces
- required for visual-semantic changes
- required when no trustworthy existing pattern match exists
- not required for every existing-project frontend change

## 🤖 Agent Model

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**: `frontend-builder` handles visual and frontend implementation.
- **Persistence**: You run in a stable Docker container with a persistent lifecycle.
- **Routing**: the topology manifest decides required artifacts, proof mode, and allowed bundles.

---

Expand Down Expand Up @@ -192,9 +193,9 @@ Node 18+ required.

Hyperstack's strength comes from the friction between **Ground Truth** (MCP), **Enforcement** (Skills), and **Orchestration** (Agents).

### Layer 1: MCP Plugins (Ground Truth)
### Layer 1: Tool Ground Truth

Your AI calls these for deterministic data. Memory is not acceptable. Every plugin serves curated TypeScript data and architectural patterns.
Your AI calls these for deterministic data. Memory is not acceptable. The public tool surface stays stable even though the runtime is now local-first and topology-driven.

| Category | Plugins | Domain Coverage |
|---|---|---|
Expand All @@ -204,7 +205,7 @@ Your AI calls these for deterministic data. Memory is not acceptable. Every plug
| 🐹 **Backend** | `echo`, `golang`, `rust` | Professional Go Recipes, Rust Borrow Checker patterns, Clean Architecture |

> [!TIP]
> **80 Tools Total**. Every tool is designed to provide the "Senior Engineer" answer, bypassing the "AI Slop" default.
> **80 Tools Total**. Every tool is designed to provide the "Senior Engineer" answer, but routing now decides when design contracts are actually required.

### Layer 2: Skills (Enforcement Teeth)

Expand All @@ -213,7 +214,7 @@ Markdown with adversarial enforcement. Each skill contains an **Iron Law** that
> [!CAUTION]
> ### ⚖️ The Iron Laws of Hyperstack
> - **NO CODE** without MCP grounding.
> - **NO VISUAL CODE** without an approved `DESIGN.md`.
> - **NO NEW VISUAL SURFACE OR VISUAL-SEMANTIC CHANGE** without an approved design contract.
> - **NO COMPLETION CLAIMS** without programmatic verification evidence.
> - **NO REFACTOR** without a failing test first.
> - **NO PATTERN** without a named Force.
Expand Down Expand Up @@ -289,19 +290,24 @@ Ordinary skill markdown is a polite suggestion. Polite suggestion fails when an

---

## 🎨 The designer agent
## 🎨 The Designer Flow

When you say, **“build me a SaaS dashboard”**:

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. 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.
3. `workspace_inventory` captures stack, owned surfaces, existing patterns, and verification commands.
4. Routing decides whether this is:
- existing-project frontend logic
- frontend visual change
- new surface
- backend-only
- fullstack slice
5. If the route says a design contract is required, **Designer skill** runs `designer_resolve_intent(product)` and related tools.
6. Designer asks the necessary questions, including component library choice.
7. Only when needed, Designer produces a conditional **DESIGN.md / design contract**.
8. **Forge-plan** reads the routed artifacts and builds the implementation plan.
9. Build tasks run with MCP-backed tool calls as ground truth.
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.

Expand Down
142 changes: 142 additions & 0 deletions docs/architecture.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,142 @@
# Hyperstack Architecture

## Purpose

Hyperstack is no longer a Docker-first MCP server with skills attached.

Current architecture is:

```text
user request
-> hyper
-> workspace_inventory
-> topology routing
-> delegated agent
-> skills and gates
-> local tool runtime
-> topology + corpus-backed truth
-> verification_report
```

## Core Layers

### 1. Topology

Location:
- `topology/`

Owns:
- domains
- agents
- bundles
- artifacts
- route defaults
- allowed/forbidden links

Topology is the source of truth for runtime wiring.

### 2. Runtime

Location:
- `src/cli.ts`
- `src/adapters/local-tools/`
- `src/engine/`

Owns:
- loading topology
- validating artifact payloads
- routing requests
- enforcing allowed skills
- resolving stable tool calls

### 3. Knowledge

Location:
- `src/plugins/*`
- `corpus/`

Current state:
- stable tool calls already run locally
- research still mostly lives in plugin-shaped data
- `corpus/` exists but is still a partial ownership layer

This is the main remaining architecture gap.

## Universal vs Conditional Artifacts

### Universal

- `workspace_inventory`
- `task_handoff`
- `verification_report`

### Conditional

- `design_contract`

`design_contract` is required only when:
- a new surface is created
- visual semantics change
- no trustworthy existing pattern match exists

It is not required for every frontend task.

## Proof Model

### Backend

Usually uses `executable` proof:
- tests
- API calls
- logs
- integration checks

### Frontend

Usually uses `visual_and_behavioral` proof:
- state coverage
- interaction behavior
- accessibility
- layout and structure correctness

### Fullstack

Uses the strictest proof of the touched domains.

## Current Role Model

### `hyper`

Owns:
- classification
- routing
- gate enforcement
- final verification

### `frontend-builder`

Owns:
- frontend-facing implementation
- page structure
- interaction work
- existing-project frontend logic work

### `backend-builder`

Owns:
- API, service, auth, jobs, backend logic

### `fullstack-builder`

Owns:
- tightly coupled frontend + backend slices

## Current Invariant

The correct repo behavior is:

**planning is universal
design contracts are conditional
verification is universal**

Any future change that violates this should be treated as architectural drift.
Loading