docs: rewrite README for Phase 1 hyperguild
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
This commit is contained in:
Mathias Bergqvist
165
README.md
165
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
|
||||
|
||||
Reference in New Issue
Block a user