From 2d219760e51179789ff8b81c2a827167bb197e0f Mon Sep 17 00:00:00 2001 From: Mathias Bergqvist Date: Sat, 18 Apr 2026 06:11:13 +0200 Subject: [PATCH] docs: rewrite README for Phase 1 hyperguild Co-Authored-By: Claude Sonnet 4.6 --- README.md | 165 +++++++++++++++++++++++++++++------------------------- 1 file changed, 88 insertions(+), 77 deletions(-) diff --git a/README.md b/README.md index 1291d5c..6179888 100644 --- a/README.md +++ b/README.md @@ -1,98 +1,109 @@ -# Project template +# hyperguild -Harness-agnostic project scaffold using the Agent Skills open standard. +An MCP server that acts as a disciplined AI supervisor for Claude Code sessions. +Instead of letting Claude Code do whatever it wants, hyperguild enforces structured +workflows (TDD red/green/refactor), logs every session, and accumulates learnings +into a searchable brain. -## Quick start +## How it works + +``` +Your Claude Code session (in any project) + │ + │ MCP tools (over stdio bridge → HTTP) + ▼ +supervisor :3200 — skill workers: tdd, retrospective +ingestion :3300 — brain HTTP API: query wiki, write notes + │ + ▼ +brain/ +├── sessions/ — JSONL log, one file per session_id +├── wiki/ — searchable knowledge (full-text) +│ ├── concepts/ +│ ├── entities/ +│ └── sources/ +├── raw/ — retrospective output, staged for review +└── training-data/ — SFT/DPO/RL data (Phase 2) +``` + +## Phase 1 tools (available now) + +| Tool | What it does | +|------|-------------| +| `tdd_red` | Writes a failing test for a spec, verifies it fails | +| `tdd_green` | Writes the minimal implementation to make tests pass | +| `tdd_refactor` | Cleans up implementation while keeping tests green | +| `session_log` | Appends a structured entry to the session JSONL log | +| `retrospective` | Reads the session log, identifies novel learnings, writes to brain/raw/ | +| `brain_query` | Full-text search over brain/wiki/ | +| `brain_write` | Writes a note to brain/raw/ (with optional YAML frontmatter) | +| `tier` | Returns the current connectivity tier (1=cloud, 2=LAN, 3=offline) | + +## Start the servers ```bash -degit mathias/project-template my-new-project -cd my-new-project -task init +# Requires goreman: go install github.com/mattn/goreman@latest +task start # starts ingestion (:3300) + supervisor (:3200) via goreman +task stop # kills both by port ``` -## Structure +## Connect a project -``` -.context/ -├── PROJECT.md ← Canonical project context (edit this) -├── mcp.json ← MCP server config (generated on first sync) -└── system-prompt.txt ← Generated: generic system prompt +Create `.mcp.json` in your project root: -.skills/ -├── go-patterns/ -│ └── SKILL.md ← Agent Skills standard format -└── htmx-patterns/ - └── SKILL.md - -scripts/ -└── context-sync.sh ← Adapter generator (finds root AGENT.md automatically) - -Taskfile.yml ← Task runner config -DECISIONS.md ← Why things are the way they are +```json +{ + "mcpServers": { + "supervisor": { + "command": "/Users/mathias/dev/AI/supervisor/bin/supervisor-bridge", + "env": { + "SUPERVISOR_URL": "http://localhost:3200/mcp" + } + } + } +} ``` -## Generated files (gitignored) +Build the bridge binary once: `task bridge:build` -| File | Consumer | Notes | -|------|----------|-------| -| `AGENTS.md` | Crush, Pi, Antigravity | Root + project concatenated | -| `CLAUDE.md` | Claude Code | Project-only (inherits root via tree walk) | -| `.cursorrules` | Cursor | Root + project concatenated | -| `.aider.conventions.md` | Aider | Root + project concatenated | -| `.context/system-prompt.txt` | Open WebUI, Mods, generic | Root + project concatenated | +Then open Claude Code in your project — run `/mcp` to confirm `supervisor` is listed. -## How root context works +## A typical TDD session -The script walks up from the project directory looking for `~/dev/.context/AGENT.md`. - -- **Claude Code**: inherits natively (reads every `CLAUDE.md` up the tree) → project CLAUDE.md is project-only -- **Everything else**: can't walk the tree → script concatenates root + project into each generated file - -## Skills - -Skills use the [Agent Skills open standard](https://github.com/badlogic/pi-skills). Each skill is a folder with a `SKILL.md` containing frontmatter: - -```yaml ---- -name: my-skill -description: What this skill does. When to use it. ---- -# Instructions here +``` +1. Call tdd_red → spec in, failing test file out +2. Call tdd_green → test path in, implementation out +3. Call tdd_refactor → impl + test in, cleaned code out +4. Call session_log → log each phase result +5. Call retrospective → extracts learnings → brain/raw/ +6. Review brain/raw/, move worthy notes to brain/wiki/concepts/ +7. Future sessions: call brain_query to retrieve relevant context ``` -Supported natively by Claude Code, Pi, Crush, and Antigravity. No adapter needed for skills. +## Tier detection -### Adding a skill +The supervisor probes connectivity at call time: -```bash -mkdir .skills/my-new-skill -# Create .skills/my-new-skill/SKILL.md with frontmatter + instructions -``` +| Tier | Label | Condition | +|------|-------|-----------| +| 1 | full-online | Can reach api.anthropic.com | +| 2 | lan-only | Can reach LiteLLM but not Anthropic | +| 3 | airplane | No external connectivity | -### Using pi-skills (cross-compatible) +## Key env vars -```bash -# User-level (all projects) -git clone https://github.com/badlogic/pi-skills ~/.pi/agent/skills/pi-skills +| Variable | Default | Purpose | +|----------|---------|---------| +| `INGEST_BRAIN_DIR` | `../brain` | Brain directory for ingestion server | +| `INGEST_PORT` | `3300` | Ingestion server port | +| `SUPERVISOR_CONFIG_DIR` | `./config/supervisor` | Skill discipline files | +| `SUPERVISOR_SESSIONS_DIR` | `./brain/sessions` | JSONL session logs | +| `INGEST_BASE_URL` | `http://localhost:3300` | Supervisor → ingestion | +| `LITELLM_BASE_URL` | — | LiteLLM proxy for Tier 2 model routing | -# Symlink for Claude Code -ln -s ~/.pi/agent/skills/pi-skills/brave-search ~/.claude/skills/brave-search -``` +## Phase 2 (planned) -## Usage with specific tools - -**Claude Code**: `task context:sync:claude` → reads `CLAUDE.md` + discovers `.skills/*/SKILL.md` - -**Crush**: `task context:sync:agents` → reads `AGENTS.md` + discovers `.skills/*/SKILL.md` - -**Pi**: `task context:sync:agents` → reads `AGENTS.md` + discovers `.skills/*/SKILL.md` (or symlink `.skills/` to `.pi/skills/`) - -**Antigravity**: `task context:sync:agents` → reads `AGENTS.md` + discovers `.skills/*/SKILL.md` - -**Cursor**: `task context:sync:cursor` → reads `.cursorrules` - -**Mistral Vibe**: Run root-level `task context:sync:vibe` once → `vibe --agent mathias` - -**Open WebUI / Mods**: Copy `.context/system-prompt.txt` into a preset or pipe it - -**Any other tool**: Point at `.context/PROJECT.md` directly — it's human-readable markdown +- `review` skill — structured code review with iron law enforcement +- `debug` skill — hypothesis-driven debugging sessions +- `spec` skill — generates specs from conversations +- `trainer` — extracts SFT/DPO pairs from session logs for fine-tuning