convez.ai
SkillProdutividadeAvançado
raelli

Octowiz — Memory-backed Engineering Doctrine para Claude Code

raelli/octowiz

Memória e doutrina técnica cacheada para agentes de código Claude

Ver no GitHub
InicialPluginScore · de 0 a 100

Skill que injeta memória técnica e doutrina de engenharia em agentes Claude Code, organizando workflows de planning, TDD, review e QA através de um sistema de routing baseado em roles. Funciona como adapter que conecta sessões de desenvolvimento a uma orquestração central (ÆLLI), recuperando dinamicamente apenas contexto relevante para cada fase.

Instalação

$npx convez-ai raelli/octowiz

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
2
Forks
1
Acompanhando
0
Saúde
42%
Último commit
há 3 meses
Versão
v0.9.24
Issues abertas
0
Contribuidores
3

Casos de uso

  • Injetar padrões de engenharia consistentes em múltiplas sessões de codificação
  • Implementar workflows TDD, planning e review automatizados com context awareness
  • Escalar equipes de IA com role-based memory e routing inteligente de trabalho

Veredito

Ferramenta arquiteturalmente sofisticada para equipes que precisam de doutrina técnica compartilhada e escalável em codificação com IA. Requer infraestrutura LiteLLM e compreensão profunda de workflows de engenharia, não é plug-and-play.

README

A tradução para o português deste README ainda está na fila.

octowiz

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

license: MIT python 3.8+ LiteLLM Proxy compatible 26 memories

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

NameWhat it is
ÆLLIThe orchestration brain (raelli/aelli). Hosts all A2A agents listed below. Makes strategic decisions and delegates coding work via A2A.
Octowiz BridgeThis repo. The Claude Code plugin. Connects developer sessions to ÆLLI, routes to skills, seeds project memory. Install name: octowiz.
LiteLLMPlatform layer. A2A gateway, Memory API, and IntegraHub Marketplace.

A2A agents

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

LiteLLM nameAELLI endpointDescription
aelli-orchestrator/a2a/aelliRoutes natural language requests to specialist agents via tool_use
aelli-router/a2a/aelli-routerMulti-router dispatch — coding vs Nemotron; runs generate/review/revise workflows
aelli-octowiz/a2a/octowizContext packager for octowiz.plan and octowiz.review, scaled to model tier
aelli-engineering/a2a/engineeringAnswers questions from indexed GitHub, Confluence, and Jira content
aelli-dev-advisor/a2a/dev-advisorMonitors cross-session file conflicts, branch drift, and spec deviations

Memory namespaces

PrefixCountWhat it contains
playbook:*17Workflow doctrine: how to plan, slice, implement, review, and ship. Covers context management, alignment interviews, PRD structure, tracer-bullet slicing, HITL vs AFK, TDD, fresh-context review, deep modules, frontend prototypes, parallel agents, and more.
skills:*3Routing summaries for the two upstream skill libraries (mattpocock/skills, obra/superpowers) and the marketplace skills hub.
agent:{role}:*4Role-specific memory slices for planner, implementer, reviewer, and qa. Each agent pulls only its own slice.
config:*2Import guidance and the retrieval contract the coordinator reads on startup.

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:

PluginProvides
octowizThe /octowiz coordinator skill (this repo)
mattpocock-skillsAlignment, PRD, TDD, diagnosis, architecture, handoff skills
superpowersBrainstorming, plans, worktrees, subagents, review, verification skills

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:

VarPurpose
OCTOWIZ_ALLOWED_ROOTSRequired. Colon-separated list of repo root paths the daemon is allowed to serve (e.g. /Users/me/projects/myrepo). The daemon exits on startup if this is unset or empty.
AELLI_BASE_URLAELLI base URL — used for both the REST API (default http://localhost:3001/api) and the task-queue host (default http://localhost:3456); setting it points both at the same host
AELLI_AUTH_TOKENBearer token for the LiteLLM gateway / x-aelli-secret for direct AELLI calls
AELLI_LITELLM_BASELiteLLM gateway base — when set, advisory and router calls route through it with Bearer auth
AELLI_DEV_ADVISOR_URLDirect dev-advisor URL (used only when no gateway is set)
AELLI_CACHE_DIRHook/bridge cache + log dir (default ~/.cache/aelli-cc)
OCTOWIZ_A2A_URLDirect A2A server URL override
OCTOWIZ_A2A_PORTA2A server port (default: 8765)
OCTOWIZ_DISPATCH_TIMEOUTSeconds before capability dispatch times out
OCTOWIZ_INBOUND_SECRETShared secret for inbound hook verification

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

VarDefaultPurpose
LITELLM_BASE_URL—LiteLLM proxy URL for memory retrieval
LITELLM_API_KEY—API key for memory reads
OCTOWIZ_NAMESPACEallsparkMemory namespace
OCTOWIZ_CACHE_DIR~/.cache/octowizDoctrine cache root
OCTOWIZ_CACHE_TTL_SECONDS3600Bundle revalidation interval
OCTOWIZ_CACHE_BYPASS—Set to 1 to skip cache entirely

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:

OptionStarting pointEntry skill
AFresh ideabrainstorming
BHave a plan to stress-testgrill-me
CReady to implementusing-git-worktrees + TDD
DCode done, need reviewzoom-out + requesting-code-review

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:

RoleMemories fetched
Planneroverview, grill-me-alignment, prd-destination-document, kanban-tracer-bullets, skill-sources, agent:planner:*
Implementercontext-smart-zone, tdd-feedback-loops, ralph-loop, skills:matt-pocock:*, skills:obra-superpowers:*, agent:implementer:*
Reviewerfresh-context-review, push-pull-standards, skills:obra-superpowers:*, agent:reviewer:*
QAmanual-qa-taste, frontend-prototypes, agent:qa:*

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

Slash commandPurpose
/octowizCoordinator — reads project state, loads doctrine, routes A/B/C/D
/octowiz:setupEnvironment setup wizard — detects gaps (plugins, LiteLLM, memory), fixes them interactively
/octowiz:octowiz-doctowizDoctor — full multi-mode diagnostic for the octowiz + AELLI integration stack

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.

CapabilityDescription
octowiz.planGenerate an implementation plan for a given task description
octowiz.reviewReview a diff or file set and return structured findings
octowiz.dispatchDispatch a Claude Code background session for an autonomous task
octowiz.run_sandboxedExecute a task inside an isolated Sandcastle container
octowiz.manage_agentsList, start, stop, and inspect active Claude Code agents
octowiz.marketplace_infoQuery the IntegraHub Marketplace for available skills, plugins, and agents
octowiz.load_memoryFetch and return a memory bundle for the current session
octowiz.escalate_to_aelliEscalate a decision or blocker to ÆLLI for strategic resolution
octowiz.write_diaryWrite a session diary entry (observations, decisions, outcomes)

/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

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.

VariableDefaultPurpose
OCTOWIZ_CACHE_DIR~/.cache/octowizCache root directory
OCTOWIZ_CACHE_TTL_SECONDS3600Seconds before revalidation
OCTOWIZ_CACHE_BYPASS—Set to 1 to skip cache entirely
OCTOWIZ_NAMESPACEallsparkNamespace for memory key substitution

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
VarPurpose
ANTHROPIC_API_KEYRequired for claude CLI inside the container
ANTHROPIC_BASE_URLOptional — override the Anthropic API endpoint
AELLI_AUTH_TOKENForward-looking — for future hooks inside the container

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:

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 ↗

Ver o original no GitHub

Bom para

Relacionados