WheelWright AI Framework

Version 2.0.0 · Source: llms-full.txt

Complete documentation for the WheelWright AI Framework — the hub-and-spoke knowledge operating system.

Philosophy

WheelWright treats AI context as a compounding asset. The framework provides two universal primitives — Skills (executable capabilities) and Lugs (actionable knowledge records) — connected by a single execution contract: Perceive / Execute / Verify (PEV).

Architecture

The hub-and-spoke model: the Hub is the analytical clearinghouse and shared memory. Each Spoke is a project with its own Ozi orchestration agent, Advisors, and local Lug store. Advisors navigate by folder convention — directory position defines scope.

Lug Schema Specification

Version 1.1.0

Lugs are WAI’s universal communication primitive — actionable records, not summaries. Every Lug represents decomposed, meaningful work with full traceability.

Lug Types

Required Fields

id: "lug-2026-02-11-001"         # Unique: lug-{date}-{sequence}type: "diagnosis"                 # See Lug Types table title: "SQL injection in auth handler" status: "published"               # draft | published | acknowledged | in_progress | resolved impact: 9                         # 1-10. ≥8 = signal created_at: "2026-02-11T14:30:00Z" created_by: "security-reviewer" node: "ownersshare/cto"

PEV Fields (Perceive / Execute / Verify)

Optional structured execution context. When present, agents follow these instead of interpreting the title.

perceive: look_at: ["src/auth/handler.js"] current_state: "Email accepts any string" success_state: "Email validates against RFC 5322" execute: approach: "Add validation using phone.ts pattern" constraints: ["Do not modify phone validator"] verify: commands: ["npm test -- --grep 'email'"] expected_output: "All tests pass"

Lifecycle

draft → published → acknowledged → in_progress → resolved

Impact Scoring

Cross-Node Communication

Outbound (Spoke → Hub): Impact ≥8 Lugs copy to hub/intake/. Spoke tracks pending acknowledgment.

Inbound (Hub → Spoke): On wakeup, spoke reads Hub Lugs newer than its cursor, creates local Lugs with source_id, decomposes into actionable work.

Decision Records

Decision Lugs are the apprenticeship engine. They capture reasoning and alternatives, teaching agents the conductor’s judgment over time.

Session Ledger

WAI-Ledger.jsonl — append-only log of requests, agreements, and deliveries. Ensures commitments survive context loss.

Skill Contract Specification

Version 1.1.0

Skills are executable capabilities — sub-agents with defined scope, cost profile, and output contract.

Skill Types

Contract Schema

skill: security-review version: 1.2.0 type: reviewer model: tier: lightweight min_context: 32000 trigger: event: on_load frequency: per_session scope: reads: ["src/**", "WAI-Lugs.jsonl"] writes: ["WAI-Lugs.jsonl"] never: ["src/**", ".env*"]

Trigger Configuration

Scope & Permissions

never overrides writes. Only worker Skills write source code. Scope violations are logged as Lugs.

Tests & Use Cases

Every Skill MUST include use_cases — documentation, agent context, and institutional memory of why the Skill exists.

safe-refactor (Guardian)

Git checkpoint before structural changes. Cannot be skipped. Origin: A rogue agent destroyed a Hub folder on 2026-02-10 with no recovery.

qc-check (Reviewer)

Runs tests, verifies startup, diagnoses failures. Agents fix mechanical problems autonomously — never asks the user to debug.

hub-watcher (Watcher)

Checks Hub for signals, updates, and pending acknowledgments. Priority 1 in wakeup sequence.

framework-updater (Worker)

Applies template updates. Categorizes changes as safe/review/breaking. Auto-applies safe, creates Lugs for the rest. Depends on safe-refactor.

brief-advisor (Advisor)

Reviews BRIEF against Lug patterns. Detects contradictions between policy and practice. The apprenticeship engine.

Bench Test

Feature v1.0.0 · Internal · Open Dashboard →

Bench Test is the reception-side evaluator for WAI Tracks — a prompt laboratory, synchronization library, and scoring dashboard built inside WheelWright Vault.

The runtime prompt captures a session. Bench Test receives the output, scores it, compares it to prior runs, and generates grounded improvement suggestions. It turns prompt evolution from guesswork into a repeatable engineering practice.

Use Cases

Workflow

Step 1 — Prepare your Track

Export the WAI Track JSONL from your session. The standard path is:

WAI-Spoke/sessions/track_session-YYYYMMDD-HHMM.jsonl

Each line must be a valid JSON object. The evaluator records parse failures as warnings — it does not reject a track because of a few malformed lines.

Step 2 — Create a Run

Go to /dashboard/bench-test and fill in the form. Required fields: Project, Prompt Version, and the Track JSONL (upload file or paste). All other fields are optional metadata that help you filter and compare runs later.

Or POST directly via the API:

curl -X POST https://wheelwright.ai/api/bench-test/runs \
  -H 'X-API-Key: <your-key>' \
  -H 'Content-Type: application/json' \
  -d '{
    "project": "WAIWeb",
    "promptVersion": "v2.0.18",
    "trackContent": "{\"turn\":1,...}\n{\"turn\":2,...}",
    "model": "claude-sonnet-4-6",
    "sessionCodename": "session-20260323-0844"
  }'

Step 3 — Review the Evaluation

The run detail page shows the overall score, a category breakdown with bar indicators, critical issues, and strengths. Everything on this page traces back to specific findings in your track — not boilerplate.

Step 4 — Attach Supporting Artifacts (optional)

Add a chat transcript, reviewer notes, or a review document to the same run:

curl -X POST https://wheelwright.ai/api/bench-test/runs/{runId}/artifacts \
  -H 'X-API-Key: <your-key>' \
  -H 'Content-Type: application/json' \
  -d '{
    "artifactType": "chat_transcript",
    "content": "<raw transcript text>"
  }'

Valid artifact types: chat_transcript, review, notes, derived

Step 5 — Compare to a Prior Run

If a prior run exists for the same project, a Compare vs Previous button appears on the detail page. The comparison view shows side-by-side category scores, per-category deltas, and a badge summary. Link directly:

/dashboard/bench-test/compare?a={priorRunId}&b={thisRunId}

Step 6 — Work the Suggestions

Bench Test generates a list of suggested prompt improvements grounded in the evaluation findings. Each is classified:

Mark each suggestion Adopt, Defer, or Reject. Adopted suggestions form your change list for the next iteration.

Scoring

Each category scores 0–10. The overall score is a weighted average.

API Reference

All endpoints require auth: GitHub session cookie or X-API-Key header (generate from the Vault dashboard).

Submission Tips