octowiz

Octowiz Bridge — the Claude Code adapter for the Octowiz Engineering Agent.

Live overview ↗  ·  ÆLLI — orchestration brain  ·  Install  ·  Diagnostics

Architecture  ·  Setup  ·  Using /octowiz  ·  Reference

Why this exists

Most AI coding tools give agents either a giant system prompt or nothing. Octowiz takes a third path: doctrine lives in a memory store, agents fetch only what is relevant to their current phase, and the coordinator skill routes to purpose-built skill libraries rather than trying to be everything itself.

Architecture

Components

A2A agents

All agents live in raelli/aelli and are registered in LiteLLM as the gateway layer.

Memory namespaces

Memory keys follow the pattern:

team:allspark:playbook:ai-coding-workflow:*   shared doctrine
team:allspark:skills:*                        external skill routing
agent:{role}:memory:ai-coding-workflow        role-specific
project:allspark:config:*                     import / namespacing

allspark is the example namespace. Replace it with your own project slug when forking.

Setup

Four steps to a working /octowiz.

1. Seed memory into LiteLLM

The workflow doctrine lives in LiteLLM's /v1/memory store. Use octowiz-cache seed to populate it for your project.

Set your LiteLLM endpoint and key:

export LITELLM_BASE_URL="https://your-proxy.example.com"
export LITELLM_ADMIN_API_KEY="sk-..."

Seed the project namespace (idempotent — safe to rerun):

octowiz-cache seed

Or seed with an explicit project slug:

octowiz-cache seed --project my-project

Confirm the seed landed:

curl "$LITELLM_BASE_URL/v1/memory/team%3Aallspark%3Askills%3Amatt-pocock%3Aai-engineering" \
  -H "Authorization: Bearer $LITELLM_ADMIN_API_KEY"

Or fetch a whole prefix:

curl "$LITELLM_BASE_URL/v1/memory?key_prefix=team:allspark:playbook:ai-coding-workflow:" \
  -H "Authorization: Bearer $LITELLM_ADMIN_API_KEY"

Team-scoped writes under team:allspark:* require proxy-admin scope. The commands above read LITELLM_ADMIN_API_KEY first and fall back to LITELLM_API_KEY.

2. Install the Claude Code plugins

Add the IntegraHub marketplace to ~/.claude/settings.json:

{
  "extraKnownMarketplaces": {
    "integrahub": {
      "source": "url",
      "url": "https://llm.integrahub.de/claude-code/marketplace.json"
    }
  },
  "env": {
    "LITELLM_BASE_URL": "https://your-proxy.example.com",
    "LITELLM_API_KEY": "sk-..."
  }
}

Then open Claude Code and run /plugins to install the three required plugins:

All three are required. /octowiz routes to skills from the other two — if either is missing the coordinator will fail mid-flow.

3. Background services

Two services run per machine, and both manage themselves:

• The Node daemon (a launchd service, de.integrahub.octowiz-daemon) connects the AELLI task queue to the local capability handlers. It auto-starts at login. On every session start the hook compares the launchd plist's target against the installed plugin and reloads the daemon when a plugin update has landed — no manual restart after /plugin update.
• The Python A2A server (port 8765) hosts the capability handlers. The session-start hook spawns it when the port is free and, when a server is already running, checks GET /health against the installed plugin version — a stale server is replaced automatically (only the recorded, pid-verified uvicorn is ever killed; a foreign service on the port is left alone).

First-time daemon install (one-off):

# plist at ~/Library/LaunchAgents/de.integrahub.octowiz-daemon.plist
launchctl load ~/Library/LaunchAgents/de.integrahub.octowiz-daemon.plist

The Claude Code hooks (SessionStart, PostToolUse, UserPromptSubmit, Stop) fire automatically once the plugin is installed.

Env vars

All environment resolution lives in one module (src/config.js) — these are the variables it reads:

For memory and doctrine configuration, set these in ~/.claude/settings.json under env:

4. Run /octowiz

Open any repo in Claude Code and invoke the coordinator:

/octowiz

The coordinator reads your project setup, fetches the relevant doctrine from LiteLLM, and routes you to the right workflow.

Run /mattpocock-skills:setup-matt-pocock-skills once per repo before first use to wire your issue tracker and domain docs.

Using /octowiz

After the pre-flight check, the coordinator asks where you're starting from:

What happens when you run /octowiz

1. Project state is read — CLAUDE.md, README, open issues, current branch, git log.
2. Routing doctrine is loaded — octowiz-cache get --role routing fetches the cached retrieval contract. If the cache is cold it pulls from LiteLLM. If LiteLLM is unreachable and the cache is stale, it serves the stale bundle with a warning.
3. You choose a starting point — A, B, C, or D. The coordinator suggests a default based on project state (open issues + active branch → C; no plan → A).
4. A role bundle is prepended to context — planner doctrine for A/B, implementer for C, reviewer for D. Stable rules land early in the context window.
5. Fresh project context is appended — git status, open issues, your request. Never cached.
6. The first skill in the chosen path is invoked.

Retrieval per role

Each role pulls only its slice of the doctrine pack:

Skill routing

Octowiz routes to two upstream skill libraries rather than vendoring them:

mattpocock/skills — alignment interviews, PRD generation, vertical slicing, TDD, debugging, architecture improvement, prototyping, handoff. Best fit when a task starts loose and needs structure.

obra/superpowers — brainstorming before code, written plans, git worktrees, subagent-driven development, systematic debugging, code review, verification before completion, finishing branches. Best fit when you want a strict end-to-end methodology.

Neither is bundled. Forks should keep routing entries pointing at the real upstream so attribution and updates stay intact.

Skills in this plugin

Reference

A2A capabilities

When AELLI dispatches a task to Octowiz via /a2a/octowiz, the daemon routes it to the matching capability handler. All capabilities are pull-based — the daemon polls the task queue and executes locally inside the developer's Claude Code session.

/a2a/dev-advisor is a compatibility alias for /a2a/octowiz, maintained while older clients migrate.

Memory caching

Octowiz caches stable doctrine bundles locally so repeated /octowiz runs load instantly without hitting LiteLLM on every invoke. Only stable doctrine is cached — git status, source files, test output, open issues, user requests, and review conclusions are never cached.

octowiz-cache get --role planner      # fetch planner bundle (from cache or LiteLLM)
octowiz-cache build --all             # warm all role bundles
octowiz-cache status                  # check freshness at a glance
octowiz-cache refresh --all           # force-rebuild from LiteLLM
octowiz-cache clear                   # delete cache for current namespace
octowiz-cache clear --all-namespaces  # wipe entire cache
octowiz-cache seed                    # seed project namespace into LiteLLM Memory
octowiz-cache check                   # environment health check
octowiz-cache init                    # bootstrap missing state files

Successful routing verification refreshes litellm.routing_verified_at in ~/.octowiz/machine-state.json only when octowiz-cache get --role routing completes with a live LiteLLM fetch (not a stale-cache fallback). octowiz-cache check uses that timestamp (24h TTL) for the litellm_cache hard gate.

If the cache is stale and LiteLLM is unreachable, octowiz-cache serves the stale bundle with a stderr warning rather than failing. If no cached bundle exists at all, it falls back to built-in routing.

Sandcastle — sandboxed execution

octowiz.run_sandboxed runs tasks inside a Docker/Podman container built from the official Octowiz sandbox image. The container has node 22, git, and the claude CLI pre-installed. No credentials are baked into the image — secrets are forwarded via name-only --env flags at runtime.

Container image: ghcr.io/raelli/octowiz-sandbox:latest

Built on node:22-bookworm-slim. Automatically rebuilt on every push to containers/sandcastle/** via GitHub Actions.

Build locally:

make build-sandbox-image

Marketplace integration

Octowiz publishes itself to the IntegraHub Marketplace and can query it via the octowiz.marketplace_info capability.

# List all marketplace items
python -m packages.marketplace_client.cli discover

# Resolve a specific item by name
python -m packages.marketplace_client.cli resolve octowiz

Keep octowiz-marketplace-manifest.json in sync with package.json version and the capability list when shipping a new release.

Diagnostics

Run the Doctowiz skill for a full integration health check at any time:

/octowiz:octowiz-doctowiz

Doctowiz probes each layer in sequence: Claude Code plugin version, env vars, hook pipeline, LiteLLM connectivity, AELLI reachability, daemon status, and memory bundles. It reports a pass/fail table per check and suggests targeted fixes for anything red.

Run the underlying script directly for a quick terminal check:

node "$CLAUDE_PLUGIN_ROOT/apps/doctowiz/index.js"

For the fastest staleness check, the A2A server exposes a public health route (0.9.16+):

curl -s http://localhost:8765/health
# {"status":"ok","version":"0.9.17"} — version should match the installed plugin

Security

• LITELLM_ADMIN_API_KEY is only needed when memory writes require elevated scope; read operations work with a standard LITELLM_API_KEY.
• The sandbox container image contains no credentials. Secrets are forwarded at container start time via name-only --env VAR flags — the value is read from the host environment by Docker/Podman and never enters argv or logs.
• OCTOWIZ_INBOUND_SECRET is a shared secret used to verify inbound hook events from Claude Code.
• The daemon enforces an allowlist on incoming task roots to prevent dispatching outside declared project paths.

Attribution

Sources this pack draws from:

• "Essential Skills for AI Coding from Planning to Production" — Matt Pocock's workshop at AI Engineer. The workflow doctrine in this pack is distilled from it.
• mattpocock/skills — Matt Pocock
• obra/superpowers — Jesse Vincent / Prime Radiant

The two skill libraries aren't bundled. Octowiz stores compact routing summaries that send agents to the right place when the current task calls for it.

License

MIT. See LICENSE.

—

octowiz  ·  part of the IntegraHub engineering ecosystem  ·  ÆLLI ↗