{"id":50611408,"url":"https://github.com/raelli/octowiz","last_synced_at":"2026-06-06T04:01:47.566Z","repository":{"id":358162930,"uuid":"1240204601","full_name":"raelli/octowiz","owner":"raelli","description":"Octowiz gives Claude Code agents memory-backed engineering doctrine — cached by role, refreshed by project state, and routed through planning, TDD, review, and QA workflows.","archived":false,"fork":false,"pushed_at":"2026-05-31T20:02:32.000Z","size":2326,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-31T21:20:52.062Z","etag":null,"topics":["agents","claude-code","claude-code-plugin","claude-skills","harness-engineering","harness-framework","litellm","matt-pocock","memory","skills","superpowers"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/raelli.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-05-15T21:55:50.000Z","updated_at":"2026-05-31T19:47:03.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/raelli/octowiz","commit_stats":null,"previous_names":["raelli/octowiz"],"tags_count":4,"template":false,"template_full_name":null,"purl":"pkg:github/raelli/octowiz","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/raelli%2Foctowiz","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/raelli%2Foctowiz/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/raelli%2Foctowiz/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/raelli%2Foctowiz/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/raelli","download_url":"https://codeload.github.com/raelli/octowiz/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/raelli%2Foctowiz/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33968711,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-06T02:00:07.033Z","response_time":107,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agents","claude-code","claude-code-plugin","claude-skills","harness-engineering","harness-framework","litellm","matt-pocock","memory","skills","superpowers"],"created_at":"2026-06-06T04:01:47.110Z","updated_at":"2026-06-06T04:01:47.553Z","avatar_url":"https://github.com/raelli.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\n\n\u003cimg src=\"assets/octowiz.jpeg\" alt=\"octowiz — the octopus-wizard\" width=\"720\"\u003e\n\n# octowiz\n\n**Octowiz Bridge** — the Claude Code adapter for the Octowiz Engineering Agent.\n\n[![license: MIT](https://img.shields.io/badge/license-MIT-eab308.svg)](LICENSE)\n![python 3.8+](https://img.shields.io/badge/python-3.8%2B-3776AB.svg?logo=python\u0026logoColor=white)\n![LiteLLM Proxy compatible](https://img.shields.io/badge/LiteLLM_Proxy-compatible-7C3AED.svg)\n![26 memories](https://img.shields.io/badge/memories-26-22c55e.svg)\n![v0.9.6](https://img.shields.io/badge/version-0.9.6-6366f1.svg)\n\n[**Live overview ↗**](https://raelli.github.io/octowiz/) \u0026nbsp;·\u0026nbsp; [ÆLLI — orchestration brain](https://github.com/raelli/aelli) \u0026nbsp;·\u0026nbsp; [Install](#setup) \u0026nbsp;·\u0026nbsp; [Diagnostics](#diagnostics)\n\n[Architecture](#architecture) \u0026nbsp;·\u0026nbsp; [Setup](#setup) \u0026nbsp;·\u0026nbsp; [Using /octowiz](#using-octowiz) \u0026nbsp;·\u0026nbsp; [Reference](#reference)\n\n\u003c/div\u003e\n\n---\n\n## Why this exists\n\nMost 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.\n\n---\n\n## Architecture\n\n\u003cimg src=\"assets/diagrams/architecture.svg\" alt=\"Octowiz architecture: ÆLLI → A2A Agent → Octowiz Bridge → LiteLLM → Skills\" width=\"440\"\u003e\n\n### Components\n\n| Name | What it is |\n|---|---|\n| **ÆLLI** | The orchestration brain ([raelli/aelli](https://github.com/raelli/aelli)). Hosts all A2A agents listed below. Makes strategic decisions and delegates coding work via A2A. |\n| **Octowiz Bridge** | This repo. The Claude Code plugin. Connects developer sessions to ÆLLI, routes to skills, seeds project memory. Install name: `octowiz`. |\n| **LiteLLM** | Platform layer. A2A gateway, Memory API, and IntegraHub Marketplace. |\n\n### A2A agents\n\nAll agents live in [raelli/aelli](https://github.com/raelli/aelli) and are registered in LiteLLM as the gateway layer.\n\n| LiteLLM name | AELLI endpoint | Description |\n|---|---|---|\n| `aelli-orchestrator` | `/a2a/aelli` | Routes natural language requests to specialist agents via tool_use |\n| `aelli-router` | `/a2a/aelli-router` | Multi-router dispatch — coding vs Nemotron; runs generate/review/revise workflows |\n| `aelli-octowiz` | `/a2a/octowiz` | Context packager for `octowiz.plan` and `octowiz.review`, scaled to model tier |\n| `aelli-engineering` | `/a2a/engineering` | Answers questions from indexed GitHub, Confluence, and Jira content |\n| `aelli-dev-advisor` | `/a2a/dev-advisor` | Monitors cross-session file conflicts, branch drift, and spec deviations |\n\n### Memory namespaces\n\n| Prefix | Count | What it contains |\n|---|:--:|---|\n| `playbook:*` | **17** | Workflow 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. |\n| `skills:*` | **3** | Routing summaries for the two upstream skill libraries (mattpocock/skills, obra/superpowers) and the marketplace skills hub. |\n| `agent:{role}:*` | **4** | Role-specific memory slices for `planner`, `implementer`, `reviewer`, and `qa`. Each agent pulls only its own slice. |\n| `config:*` | **2** | Import guidance and the retrieval contract the coordinator reads on startup. |\n\nMemory keys follow the pattern:\n\n```text\nteam:allspark:playbook:ai-coding-workflow:*   shared doctrine\nteam:allspark:skills:*                        external skill routing\nagent:{role}:memory:ai-coding-workflow        role-specific\nproject:allspark:config:*                     import / namespacing\n```\n\n`allspark` is the example namespace. Replace it with your own project slug when forking.\n\n---\n\n## Setup\n\n\u003cimg src=\"assets/diagrams/setup-flow.svg\" alt=\"Four setup steps: seed memory, install plugins, start daemon, run /octowiz\" width=\"620\"\u003e\n\nFour steps to a working `/octowiz`.\n\n### 1. Seed memory into LiteLLM\n\nThe workflow doctrine lives in LiteLLM's `/v1/memory` store. Use `octowiz-cache seed` to populate it for your project.\n\nSet your LiteLLM endpoint and key:\n\n```bash\nexport LITELLM_BASE_URL=\"https://your-proxy.example.com\"\nexport LITELLM_ADMIN_API_KEY=\"sk-...\"\n```\n\nSeed the project namespace (idempotent — safe to rerun):\n\n```bash\noctowiz-cache seed\n```\n\nOr seed with an explicit project slug:\n\n```bash\noctowiz-cache seed --project my-project\n```\n\nConfirm the seed landed:\n\n```bash\ncurl \"$LITELLM_BASE_URL/v1/memory/team%3Aallspark%3Askills%3Amatt-pocock%3Aai-engineering\" \\\n  -H \"Authorization: Bearer $LITELLM_ADMIN_API_KEY\"\n```\n\nOr fetch a whole prefix:\n\n```bash\ncurl \"$LITELLM_BASE_URL/v1/memory?key_prefix=team:allspark:playbook:ai-coding-workflow:\" \\\n  -H \"Authorization: Bearer $LITELLM_ADMIN_API_KEY\"\n```\n\nTeam-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`.\n\n### 2. Install the Claude Code plugins\n\nAdd the IntegraHub marketplace to `~/.claude/settings.json`:\n\n```json\n{\n  \"extraKnownMarketplaces\": {\n    \"integrahub\": {\n      \"source\": \"url\",\n      \"url\": \"https://llm.integrahub.de/claude-code/marketplace.json\"\n    }\n  },\n  \"env\": {\n    \"LITELLM_BASE_URL\": \"https://your-proxy.example.com\",\n    \"LITELLM_API_KEY\": \"sk-...\"\n  }\n}\n```\n\nThen open Claude Code and run `/plugins` to install the three required plugins:\n\n| Plugin | Provides |\n|---|---|\n| `octowiz` | The `/octowiz` coordinator skill (this repo) |\n| `mattpocock-skills` | Alignment, PRD, TDD, diagnosis, architecture, handoff skills |\n| `superpowers` | Brainstorming, plans, worktrees, subagents, review, verification skills |\n\nAll three are required. `/octowiz` routes to skills from the other two — if either is missing the coordinator will fail mid-flow.\n\n### 3. Start the daemon\n\nThe Octowiz daemon is a Node.js service that runs per machine. It connects the Claude Code hooks to the AELLI A2A network and handles capability dispatch.\n\n```bash\npnpm start\n```\n\nOr directly:\n\n```bash\nnode index.js\n```\n\nThe Claude Code hooks (SessionStart, PostToolUse, UserPromptSubmit, Stop) fire automatically once the plugin is installed. They do not manage the daemon lifecycle.\n\n#### Env vars\n\n| Var | Purpose |\n|---|---|\n| `OCTOWIZ_ALLOWED_ROOTS` | **Required.** 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. |\n| `AELLI_BASE_URL` | AELLI server base URL |\n| `OCTOWIZ_A2A_URL` | Direct A2A server URL override |\n| `OCTOWIZ_A2A_PORT` | A2A server port (default: 8765) |\n| `OCTOWIZ_DISPATCH_TIMEOUT` | Seconds before capability dispatch times out |\n| `OCTOWIZ_INBOUND_SECRET` | Shared secret for inbound hook verification |\n\nFor memory and doctrine configuration, set these in `~/.claude/settings.json` under `env`:\n\n| Var | Default | Purpose |\n|---|---|---|\n| `LITELLM_BASE_URL` | — | LiteLLM proxy URL for memory retrieval |\n| `LITELLM_API_KEY` | — | API key for memory reads |\n| `OCTOWIZ_NAMESPACE` | `allspark` | Memory namespace |\n| `OCTOWIZ_CACHE_DIR` | `~/.cache/octowiz` | Doctrine cache root |\n| `OCTOWIZ_CACHE_TTL_SECONDS` | `3600` | Bundle revalidation interval |\n| `OCTOWIZ_CACHE_BYPASS` | — | Set to `1` to skip cache entirely |\n\n### 4. Run /octowiz\n\nOpen any repo in Claude Code and invoke the coordinator:\n\n```text\n/octowiz\n```\n\nThe coordinator reads your project setup, fetches the relevant doctrine from LiteLLM, and routes you to the right workflow.\n\nRun `/mattpocock-skills:setup-matt-pocock-skills` once per repo before first use to wire your issue tracker and domain docs.\n\n---\n\n## Using /octowiz\n\n\u003cimg src=\"assets/diagrams/routing.svg\" alt=\"/octowiz routes to A (brainstorming), B (grill-me), C (worktrees+TDD), D (zoom-out+review)\" width=\"560\"\u003e\n\nAfter the pre-flight check, the coordinator asks where you're starting from:\n\n| Option | Starting point | Entry skill |\n|---|---|---|\n| A | Fresh idea | `brainstorming` |\n| B | Have a plan to stress-test | `grill-me` |\n| C | Ready to implement | `using-git-worktrees` + TDD |\n| D | Code done, need review | `zoom-out` + `requesting-code-review` |\n\n### What happens when you run /octowiz\n\n1. **Project state is read** — CLAUDE.md, README, open issues, current branch, git log.\n2. **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.\n3. **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).\n4. **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.\n5. **Fresh project context is appended** — git status, open issues, your request. Never cached.\n6. **The first skill in the chosen path is invoked.**\n\n### Retrieval per role\n\nEach role pulls only its slice of the doctrine pack:\n\n| Role | Memories fetched |\n|---|---|\n| **Planner** | `overview`, `grill-me-alignment`, `prd-destination-document`, `kanban-tracer-bullets`, `skill-sources`, `agent:planner:*` |\n| **Implementer** | `context-smart-zone`, `tdd-feedback-loops`, `ralph-loop`, `skills:matt-pocock:*`, `skills:obra-superpowers:*`, `agent:implementer:*` |\n| **Reviewer** | `fresh-context-review`, `push-pull-standards`, `skills:obra-superpowers:*`, `agent:reviewer:*` |\n| **QA** | `manual-qa-taste`, `frontend-prototypes`, `agent:qa:*` |\n\n### Skill routing\n\nOctowiz routes to two upstream skill libraries rather than vendoring them:\n\n**[mattpocock/skills](https://github.com/mattpocock/skills)** — alignment interviews, PRD generation, vertical slicing, TDD, debugging, architecture improvement, prototyping, handoff. Best fit when a task starts loose and needs structure.\n\n**[obra/superpowers](https://github.com/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.\n\nNeither is bundled. Forks should keep routing entries pointing at the real upstream so attribution and updates stay intact.\n\n### Skills in this plugin\n\n| Slash command | Purpose |\n|---|---|\n| `/octowiz` | Coordinator — reads project state, loads doctrine, routes A/B/C/D |\n| `/octowiz:setup` | Environment setup wizard — detects gaps (plugins, LiteLLM, memory), fixes them interactively |\n| `/octowiz:octowiz-doctowiz` | Doctor — full multi-mode diagnostic for the octowiz + AELLI integration stack |\n\n---\n\n## Reference\n\n### A2A capabilities\n\nWhen 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.\n\n| Capability | Description |\n|---|---|\n| `octowiz.plan` | Generate an implementation plan for a given task description |\n| `octowiz.review` | Review a diff or file set and return structured findings |\n| `octowiz.dispatch` | Dispatch a Claude Code background session for an autonomous task |\n| `octowiz.run_sandboxed` | Execute a task inside an isolated Sandcastle container |\n| `octowiz.manage_agents` | List, start, stop, and inspect active Claude Code agents |\n| `octowiz.marketplace_info` | Query the IntegraHub Marketplace for available skills, plugins, and agents |\n| `octowiz.load_memory` | Fetch and return a memory bundle for the current session |\n| `octowiz.escalate_to_aelli` | Escalate a decision or blocker to ÆLLI for strategic resolution |\n| `octowiz.write_diary` | Write a session diary entry (observations, decisions, outcomes) |\n\n`/a2a/dev-advisor` is a compatibility alias for `/a2a/octowiz`, maintained while older clients migrate.\n\n### Memory caching\n\nOctowiz 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.\n\n```bash\noctowiz-cache get --role planner      # fetch planner bundle (from cache or LiteLLM)\noctowiz-cache build --all             # warm all role bundles\noctowiz-cache status                  # check freshness at a glance\noctowiz-cache refresh --all           # force-rebuild from LiteLLM\noctowiz-cache clear                   # delete cache for current namespace\noctowiz-cache clear --all-namespaces  # wipe entire cache\noctowiz-cache seed                    # seed project namespace into LiteLLM Memory\noctowiz-cache check                   # environment health check\noctowiz-cache init                    # bootstrap missing state files\n```\n\nIf 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.\n\n| Variable | Default | Purpose |\n|---|---|---|\n| `OCTOWIZ_CACHE_DIR` | `~/.cache/octowiz` | Cache root directory |\n| `OCTOWIZ_CACHE_TTL_SECONDS` | `3600` | Seconds before revalidation |\n| `OCTOWIZ_CACHE_BYPASS` | — | Set to `1` to skip cache entirely |\n| `OCTOWIZ_NAMESPACE` | `allspark` | Namespace for memory key substitution |\n\n### Sandcastle — sandboxed execution\n\n`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.\n\n**Container image:** `ghcr.io/raelli/octowiz-sandbox:latest`\n\nBuilt on `node:22-bookworm-slim`. Automatically rebuilt on every push to `containers/sandcastle/**` via GitHub Actions.\n\nBuild locally:\n\n```bash\nmake build-sandbox-image\n```\n\n| Var | Purpose |\n|---|---|\n| `ANTHROPIC_API_KEY` | Required for `claude` CLI inside the container |\n| `ANTHROPIC_BASE_URL` | Optional — override the Anthropic API endpoint |\n| `AELLI_AUTH_TOKEN` | Forward-looking — for future hooks inside the container |\n\n### Marketplace integration\n\nOctowiz publishes itself to the IntegraHub Marketplace and can query it via the `octowiz.marketplace_info` capability.\n\n```bash\n# List all marketplace items\npython -m packages.marketplace_client.cli discover\n\n# Resolve a specific item by name\npython -m packages.marketplace_client.cli resolve octowiz\n```\n\nKeep `octowiz-marketplace-manifest.json` in sync with `package.json` version and the capability list when shipping a new release.\n\n### Diagnostics\n\nRun the Doctowiz skill for a full integration health check at any time:\n\n```text\n/octowiz:octowiz-doctowiz\n```\n\nDoctowiz 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.\n\nRun the underlying script directly for a quick terminal check:\n\n```bash\nnode \"$CLAUDE_PLUGIN_ROOT/apps/doctowiz/index.js\"\n```\n\n### Security\n\n- `LITELLM_ADMIN_API_KEY` is only needed when memory writes require elevated scope; read operations work with a standard `LITELLM_API_KEY`.\n- 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.\n- `OCTOWIZ_INBOUND_SECRET` is a shared secret used to verify inbound hook events from Claude Code.\n- The daemon enforces an allowlist on incoming task roots to prevent dispatching outside declared project paths.\n\n---\n\n## Attribution\n\nSources this pack draws from:\n\n- **[\"Essential Skills for AI Coding from Planning to Production\"](https://www.youtube.com/watch?v=-QFHIoCo-Ko)** — Matt Pocock's workshop at AI Engineer. The workflow doctrine in this pack is distilled from it.\n- [mattpocock/skills](https://github.com/mattpocock/skills) — Matt Pocock\n- [obra/superpowers](https://github.com/obra/superpowers) — Jesse Vincent / Prime Radiant\n\nThe 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.\n\n## License\n\nMIT. See [`LICENSE`](LICENSE).\n\n\u003cdiv align=\"center\"\u003e\n\n—\n\n**[octowiz](https://github.com/raelli/octowiz)** \u0026nbsp;·\u0026nbsp; part of the **IntegraHub** engineering ecosystem \u0026nbsp;·\u0026nbsp; [ÆLLI ↗](https://github.com/raelli/aelli)\n\n\u003c/div\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fraelli%2Foctowiz","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fraelli%2Foctowiz","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fraelli%2Foctowiz/lists"}