# OrchestKit: Full Documentation > OrchestKit is a free, open-source plugin for Claude Code: 110 skills, 36 agents, and 163 lifecycle hooks with built-in security patterns and quality gates. ## Quickstart 1. Install Claude Code 2.1.277+. 2. Run `claude plugin marketplace add yonatangross/orchestkit && claude plugin install ork@orchestkit`. 3. Invoke any skill with `/ork:` (e.g. `/ork:implement`, `/ork:review-pr`). ## Developer resources - [OrchestKit developer portal](https://orchestkit.dev/developers): Developer portal. One page linking every resource below; Markdown twin at https://orchestkit.dev/developers.md. - [OrchestKit OpenAPI specification](https://orchestkit.dev/openapi): OpenAPI spec. Human page for the OpenAPI 3.1 docs API spec. Machine copy at /openapi.json. - [OrchestKit MCP server](https://orchestkit.dev/docs/mcp): MCP server. How to connect the hosted Streamable HTTP server and the Docker stdio image. Transport stays at /api/mcp and /mcp. - [OrchestKit Actions MCP server](https://orchestkit.dev/docs/foundations/mcp-servers): MCP server. Read-only product MCP: list skills, plan installs, check config fragments. Executes nothing. Endpoint /api/mcp/actions; card /.well-known/mcp/actions-server-card.json. - [OrchestKit SDK packages](https://orchestkit.dev/docs/sdk): SDK documentation. Official clients: npm CLI, PyPI orchestkit, Go module github.com/yonatangross/orchestkit/sdk. - [OrchestKit plugin install and setup](https://orchestkit.dev/docs/getting-started/installation): Install guide. Install the plugin on Claude Code, Cursor, Codex, Devin, OpenCode, Muse Code, Pi or Antigravity, then configure it. - [OrchestKit skills reference](https://orchestkit.dev/docs/reference/skills): Reference docs. Reference page for each of the 110 skills: triggers, arguments, and the files each one ships. - [OrchestKit agents reference](https://orchestkit.dev/docs/reference/agents): Reference docs. Reference page for each of the 36 agents: model, tools, skills, and when to use it. - [OrchestKit hooks reference](https://orchestkit.dev/docs/reference/hooks): Reference docs. Every global lifecycle hook entry, grouped by Claude Code event, with what it checks. - [OrchestKit API docs (OpenAPI 3.1 JSON)](https://orchestkit.dev/api/openapi): API docs. OpenAPI 3.1 description of the public, read-only docs API: search, Markdown fetch, batch, async jobs. - [OrchestKit auth docs](https://orchestkit.dev/auth.md): Auth docs. The API is public and anonymous-only; auth.md states it in the WorkOS auth.md shape, with RFC 9728 PRM. ## API - **Search**: `GET https://orchestkit.dev/api/search?query=...` returns JSON results. OpenAPI: https://orchestkit.dev/api/openapi - **Ask** (natural language): `POST https://orchestkit.dev/ask` returns JSON (NLWeb); send `Accept: text/event-stream` for SSE streaming. - **MCP server** (Streamable HTTP): https://orchestkit.dev/api/mcp · card: https://orchestkit.dev/.well-known/mcp/server-card.json - **Actions MCP** (Streamable HTTP, read-only product tools): https://orchestkit.dev/api/mcp/actions · card: https://orchestkit.dev/.well-known/mcp/actions-server-card.json - **Markdown**: append `.md` to any page URL, or send `Accept: text/markdown`. - **API catalog** (RFC 9727): https://orchestkit.dev/.well-known/api-catalog ## Authentication The public documentation and search API require no authentication; agents call the endpoints directly. Details: https://orchestkit.dev/auth.md --- ## Antigravity Install OrchestKit skills in Google's Antigravity (agy). Agent Skills via skills.sh and workspace .agents/skills. No ork-agy pack; hooks and MCP config are a different contract. [https://orchestkit.dev/docs/getting-started/agy](/docs/getting-started/agy) import { Callout } from 'fumadocs-ui/components/callout'; import { Card, Cards } from 'fumadocs-ui/components/card'; import { HostHeading, HostMark } from '@/components/host-marks'; import { HostInstall } from '@/components/host-install'; **Antigravity** (`agy`) is Google's agentic CLI. OrchestKit treats it as a host. This page is that host, not a fake plugin pack. There is no `ork-agy` pack in this repository. agy discovers [Agent Skills](https://agentskills.io) from a workspace `.agents/skills` directory, which is the same convention Muse Code and OpenCode use, so `npx skills add` is the install path. Every load claim below comes from the measured audit at `docs/audits/agy-host-support-2026-09-18.md` (agy 1.2.6). ## Install skills Starter 12 (not the whole catalog). Click the chip to copy. `npx skills add` writes SKILL.md trees under `.agents/skills`, and Antigravity is in skills.sh's universal target list. Start `agy` in the repo and the skills appear in `/skills`. The verify command uses an absolute `--add-dir` on purpose: in print mode, agy registers a workspace from `--add-dir ` only. Bare `cwd` and a relative `--add-dir .` both miss `.agents/skills`. Inside the interactive TUI the launch directory is the workspace, so no flag is needed there. ## What loads today Measured with agy 1.2.6 (`agy -p "/skills"`, `agy -p "/agents"`, `agy plugin validate`, marker fixtures under a scratch workspace): | Surface | Status | |:-|:-| | Workspace `.agents/skills//SKILL.md` | Loads | | `.agents/skills.json` `entries[].path` (shared dirs) | Loads | | Plugin `skills/` + `agents/` + `commands/` (as `.agents/plugins//`) | Loads; commands convert to skills, namespaced `:` | | Workspace `.agents/hooks.json` | Loads, but it is agy's hook schema, not Claude Code's | | Plugin `mcp_config.json` | Loads; the server spawns and tools route | | `~/.gemini/config/skills` and `~/.gemini/skills` | Load (user scope) | | `~/.agents/skills` (skills.sh `-g` target) | Does not load | | Repo `.mcp.json` | Does not load | | ork `hooks/hooks.json` + `dist/` | Does not port: agy wants `/hooks.json` in its own event schema | | ork `.cursor-plugin/commands/*.md` wrappers | Does not load; invoke as `/` | Two honest gaps: - `skills add -g` lands in `~/.agents/skills`, which agy never reads. Use the project install line, or copy the directory into `~/.gemini/config/skills` if you want the skills in every workspace. - OrchestKit's hooks are Claude Code `hooks.json` format. agy's `hooks.json` uses its own event names and camelCase payloads, so none of ork's hook surface ports as files. After installing, run `agy -p "/skills" --add-dir "$PWD"` from the repo root. Expect the starter skills listed by name; if the list is empty, check that `--add-dir` is an absolute path. ## The fuller install `agy plugin validate plugins/ork` on a local checkout reports `skills: 108 processed`, `agents: 36 processed` (hooks and MCP report skipped: ork's plugin layout keeps them where agy does not look). `agy plugin install /plugins/ork` copies them into `~/.gemini/config/plugins/ork/` and namespaces every skill `ork:`, which matches the `/ork:` spelling. It needs a local clone, so it is a power path, not the one-liner. Antigravity Search for **agy** or **antigravity** should land on this page. The word Antigravity in this heading is the product name for Google's agentic CLI. } /> } /> ## Claude Code Add the full ork plugin to Claude Code with two commands, check it with /ork:doctor, and connect the context7 MCP server that many agents use for library docs. [https://orchestkit.dev/docs/getting-started/claude-code](/docs/getting-started/claude-code) import { Card, Cards } from 'fumadocs-ui/components/card'; import { Callout } from 'fumadocs-ui/components/callout'; import { LazySetupWizard } from '@/components/lazy'; import { Count, MinCC } from '@/components/count'; import { HostInstall } from '@/components/host-install'; Claude Code is the full plugin: skills, agents, and hooks. Slash-command equivalent, typed inside a Claude Code session: ```bash /plugin marketplace add yonatangross/orchestkit /plugin install ork ``` `/ork:setup` scans the repo, recommends skills, and writes MCP config. Project knobs (protected branches, commit scope, localhost browser, and the rest) live in [Configuration](/docs/getting-started/configuration#project-settings-wizard). ## Interactive install picker This browser wizard picks a host, then optionally a stack hint, and copies that host's install command. It is not the in-bot `/ork:setup --configure` wizard. ## Verify ``` /ork:doctor ``` A healthy report shows the **installed** plugin version (not a docs pin) and loaded counts matching skills, agents, and hooks: ``` OrchestKit Health Check ======================= Plugin: ork Skills: loaded (commands + reference) Agents: registered Hooks: active (global / agent / skill-scoped) Memory: Graph ✓ Local ✓ CC Native ✓ MCP: context7 ✓ memory ✓ tavily ○ Status: Healthy ``` `○` means optional and not configured. `✓` means active. `✗` means enabled but misconfigured. ### If you see errors | Status | Meaning | Fix | |---|---|---| | `✗ Memory: Graph ✗` | MCP memory server not responding | Check Node.js >= 18 is installed, restart Claude Code | | `✗ Hooks: 0 active` | Hook compilation failed | Run `node --version` (must be >= 18). If OK, reinstall: `claude plugin uninstall ork && claude plugin install ork@orchestkit` | | `✗ Skills: 0 loaded` | Plugin not found by Claude Code | Check `claude plugins` shows `ork`. Try closing and reopening Claude Code | | `○ tavily ○` | **Not an error**. Tavily is optional | See Tavily below if you want web research | Most issues are fixed by ensuring Node.js >= 18 is installed and restarting Claude Code. If problems persist, run `/ork:doctor --verbose`. ## Required: context7 MCP OrchestKit installs cleanly without it and `/ork:doctor` reports Healthy either way. But 22 of the agents grant `mcp__context7__*` in their frontmatter, and the plugin ships no server definition for it: `.mcp.json` is user-owned and project-scoped, so the grant refers to a server you supply. Without it, those agents answer from training data instead of current library docs, with no error to tell you so. Add it once, project-scoped in `.mcp.json` or user-scoped in `~/.claude.json`: ```json { "mcpServers": { "context7": { "type": "http", "url": "https://mcp.context7.com/mcp" } } } ``` That hosted HTTP entry is the whole free tier: 1,000 requests, public repositories, no account. A Context7 Pro subscription ($10 per seat per month) raises it to 5,000 requests per seat and adds private repo parsing. To use a Pro key, add `"headers": { "Authorization": "Bearer ${CONTEXT7_API_KEY}" }` to the entry and export `CONTEXT7_API_KEY` (keys start with `ctx7sk-`). A connected context7 is not proof that your key is in use. The server answers `tools/list` with HTTP 200 for every auth state, including an unset variable that arrives as the literal `${CONTEXT7_API_KEY}`. Only a real query discriminates: a bad key returns `Invalid API key. Please check your API key. API keys should start with 'ctx7sk' prefix.` Do not add the header until the variable is actually exported: with the variable unset, the literal is sent as the token and **every** query fails. It does not fall back to the anonymous free tier. The keyless entry above does work as the free tier, so the header plus the `export` line ship together or neither ships. The stdio transport (`npx -y @upstash/context7-mcp`) still works and is the fallback for proxied or air-gapped networks, but it spawns one child process per Claude Code session. Details are in the [MCP Servers guide](/docs/foundations/mcp-servers#prerequisite-context7). ## Optional: Tavily OrchestKit works out of the box with all 3 memory tiers (Graph, Local, CC Native). For enhanced web research, enable the Tavily MCP: **1.** Get a free API key at [app.tavily.com](https://app.tavily.com) (1,000 credits/month free) **2.** Set the key in your shell profile (`~/.zshrc` or `~/.bashrc`): ```bash export TAVILY_API_KEY="tvly-your-key-here" ``` **3.** Enable the MCP in `.mcp.json`: ```json "tavily": { "command": "sh", "args": ["-c", "TAVILY_API_KEY=${TAVILY_API_KEY} exec npx -y tavily-mcp@latest"], "disabled": false } ``` Without Tavily, web research falls back to WebFetch then agent-browser. ## Requirements - **Claude Code** >= - **Node.js** >= 18 (for hooks) - **Git** (for commit/PR workflows) ## Next steps ## Codex Install OrchestKit's Codex pack. codex plugin add ork-codex@orchestkit-codex, $ork-implement, Codex roles, and context7. [https://orchestkit.dev/docs/getting-started/codex](/docs/getting-started/codex) import { Callout } from 'fumadocs-ui/components/callout'; import { Card, Cards } from 'fumadocs-ui/components/card'; import { HostInstall } from '@/components/host-install'; Codex uses its own plugin format, skill picker, and standalone role configuration. The Claude Code `ork` plugin is not what Codex loads. Install the portable pack **ork-codex**. Restart Codex after installation. Invoke a workflow explicitly with `$ork-brainstorm`, `$ork-explore`, `$ork-implement`, `$ork-assess`, `$ork-verify`, `$ork-review-pr`, or `$ork-glyph`. Their narrow descriptions also let Codex select the relevant workflow automatically. Use `$ork-glyph` for a compact inline diagram of status, comparisons, inventories, or pipelines. With no topic supplied, it renders the current conversation. The skill named `implement` on [skills.sh](https://www.skills.sh/yonatangross/orchestkit/implement) is the same workflow. Codex's pack exposes it as `$ork-implement`. ## Roles The plugin ships roles as templates because Codex loads custom roles from `~/.codex/agents/`, not from a plugin manifest. From an OrchestKit checkout, run this one-time, non-overwriting install: ```bash plugins/ork-codex/scripts/install-codex-roles.sh ~/.codex/agents ``` It installs `ork_explorer`, `ork_implementer`, `ork_reviewer`, and `ork_verifier`. Restart Codex before spawning them. ## context7 The plugin ships a [context7](https://context7.com) MCP server in its own manifest (`mcpServers` in `.codex-plugin/plugin.json`, defined in `mcp.json`), so installing the plugin registers it. Confirm with `codex mcp get context7`. It is scoped to the only two tools context7 exposes, `resolve-library-id` and `query-docs`, and it uses the hosted HTTP transport rather than an `npx` stdio child, so it costs no extra process per Codex session. Export a key before starting Codex. The plugin references the variable name and never stores the value, so no token is written to `~/.codex/config.toml`: ```bash export CONTEXT7_API_KEY_CODEX="" ``` Put that in your shell profile so every Codex session inherits it. Get the key from your own context7 account and keep the value out of the repository. A server you already define under `[mcp_servers.context7]` in `~/.codex/config.toml` **wins**, and the plugin's definition is ignored entirely (including its tool scoping). That is intentional: your own configuration is never overridden. Without a valid key the server still connects and still lists its tools. Only a real call fails, with `Invalid API key`. A successful connection is therefore not proof of authentication. ## Mechanical profile For unattended runs, add the shipped profile from an OrchestKit checkout: ```bash plugins/ork-codex/scripts/install-codex-profile.sh ~/.codex codex exec --profile ork-mech "" `ref main` is a cached snapshot, not a tracker. Run `codex plugin update` after an OrchestKit release, then compare `codex plugin list | grep ork-codex` against `jq -r .version plugins/ork-codex/.codex-plugin/plugin.json`. Measurements: [OrchestKit on pi, Codex and Cursor](/docs/guides/orchestkit-on-pi-codex-cursor). ## Skills-only path Not installing the Codex pack? Pull the [skills.sh starter 12](/docs/getting-started/skills-sh). Do not run `npx skills add yonatangross/orchestkit` with no `-s` on day one. ## Configuration /ork:setup project knobs, environment variables, MCP servers, and memory tier setup. [https://orchestkit.dev/docs/getting-started/configuration](/docs/getting-started/configuration) OrchestKit works out of the box with zero configuration. This page covers optional settings for power users. ## Project settings wizard The product configuration UI is inside Claude Code (and hosts that load the `setup` skill). It is not a page on this site. - `/ork:setup` runs the full onboarding (scan, stack, safety, **project config**, permissions, skills, MCPs). - `/ork:setup --configure` skips to Phase 3.5 and writes the env block. The browser install picker on [Installation](/docs/getting-started/installation) only copies a host install command (for Claude Code, `claude plugin marketplace add …` and `claude plugin install …`). It does not write these knobs. Writes go to `.claude/settings.json` for a normal project, or `src/settings/ork.settings.json` when you are developing OrchestKit itself. | Variable | Default | Effect | |---|---|---| | `ORCHESTKIT_PROTECTED_BRANCHES` | `main,master` | Blocks direct commits and pushes to these branches | | `ORCHESTKIT_COMMIT_SCOPE` | `optional` | `optional`, `required`, or `none` | | `ORCHESTKIT_PERF_SNAPSHOT_ENABLED` | `1` | Write session token snapshots | | `ORCHESTKIT_LOG_LEVEL` | `warn` | Hook log verbosity (`debug`, `info`, `warn`, `error`) | Optional webhook: the wizard can save a URL to `.claude/orchestration/config.json`. Events leave the machine only when that URL is set **and** `ORCHESTKIT_HOOK_TOKEN` is exported in the launching shell. Do not put the token in a config file. Skip webhooks unless you run your own collector. Re-run: `/ork:setup --configure`. Score only: `/ork:setup --score-only`. ## Environment Variables ### Core (Auto-Detected) | Variable | Description | Default | |---|---|---| | `CLAUDE_PROJECT_DIR` | Your project root | Auto-detected | | `CLAUDE_PLUGIN_ROOT` | Plugin installation path | Auto-detected | | `CLAUDE_SESSION_ID` | Current session UUID | Auto-generated | ### Web Research (Optional) | Variable | Description | Effect | |---|---|---| | `TAVILY_API_KEY` | Tavily search API | Enables search/extract/map in web research workflow | ### Library Docs (Optional, Pro tier only) | Variable | Description | Effect | |---|---|---| | `CONTEXT7_API_KEY` | Context7 API key, format `ctx7sk-...` | Raises the context7 quota from the free 1,000 requests to 5,000 per seat and unlocks private repo parsing | context7 itself does **not** need this variable. The free tier works without a key. Set it only if you hold a Context7 Pro subscription, and only alongside the matching `Authorization` header in `.mcp.json` (see [MCP Servers](/docs/foundations/mcp-servers#context7-library-docs)). A header that references an unset variable is worse than no header: the server still connects and still lists its two tools, then fails every query with `Invalid API key. Please check your API key. API keys should start with 'ctx7sk' prefix.` ### Setting Variables Add to your shell profile (`~/.zshrc`, `~/.bashrc`, or `~/.config/fish/config.fish`): ```bash # Web Research export TAVILY_API_KEY="tvly-your-key-here" # Context7 Pro (optional; the free tier needs no key) export CONTEXT7_API_KEY="ctx7sk-your-key-here" ``` Then restart Claude Code or open a new terminal. ## Memory Tiers OrchestKit has 3 memory tiers. All work automatically with zero configuration: | Tier | Storage | Config Needed | What It Does | |---|---|---|---| | **1. Graph** | MCP `mcp__memory__*` | None (zero-config) | Knowledge graph: entities + relations | | **2. Local** | `.claude/memory/*.jsonl` | None (auto-created) | Session persistence, queue sync | | **3. CC Native** | `~/.claude/projects/*/memory/MEMORY.md` | None (auto-sync) | Injected into system prompt | High-confidence decisions (confidence >= 0.7) automatically promote from Graph to CC Native, ensuring they persist even without OrchestKit installed. ## MCP Servers OrchestKit supports 10 MCP servers for web search, component registries, design extraction, and more. All but one are optional. **context7 is a prerequisite.** 22 of the 36 agents grant `mcp__context7__*` in their frontmatter, the plugin ships no server definition for it, and `.mcp.json` is user-owned. An unconfigured context7 does not error: those agents fall back to training-data answers about your libraries, silently. Add it before you rely on them. See the full **[MCP Servers guide](/docs/foundations/mcp-servers)** for: - All 10 MCPs organized by tier (bundled, API key required, user-installable) - Recommended MCPs by project type (React, backend, design system, AI/LLM) - Complete agent-to-MCP mapping (all 36 agents) - Setup instructions, token overhead, and graceful degradation **Quick start**: memory and sequential-thinking work with zero config. context7 needs one `.mcp.json` entry, and is the one server not to skip; the free tier (1,000 requests, public repos) needs no API key, and a Context7 Pro key raises that to 5,000 per seat with private repo parsing. Tavily needs a free API key from [app.tavily.com](https://app.tavily.com). ```json "context7": { "type": "http", "url": "https://mcp.context7.com/mcp" } ``` ## Hook Behavior Hooks fire automatically. If a hook blocks an action unexpectedly: 1. Check which hook blocked: the error message includes the hook name 2. Hooks you can customize: - **file-guard**: Protected file paths and file size limits (override with `ORCHESTKIT_MAX_FILE_LINES` / `ORCHESTKIT_MAX_TEST_FILE_LINES` env vars) - **dangerous-command-blocker**: Blocked commands list - **permission auto-approve**: Safe command patterns Most users never need to customize hooks. They're designed to be transparent. ## Keybindings Claude Code owns keybindings, and a plugin cannot ship shortcuts that invoke its skills. Run `/keybindings` to create or open your own config at `~/.claude/keybindings.json`: ```json { "$schema": "https://www.schemastore.org/claude-code-keybindings.json", "bindings": [ { "context": "Chat", "bindings": { "ctrl+e": "chat:externalEditor" } } ] } ``` Every value on the right is drawn from a **closed set of built-in `namespace:action` identifiers** (`chat:submit`, `app:toggleTodos`, `scroll:bottom`, and so on). There is no action that runs a slash command, so `"ctrl+k ctrl+c": "/ork:commit"` is not expressible: Claude Code validates the file on load and reports invalid entries in the debug log (`claude --debug`). Earlier versions of this page advertised 8 `ctrl+k` chords bound to OrchestKit skills, and described `src/settings/ork.settings.json` as the place to customize them. Both were wrong. Claude Code reads only a small set of keys from a plugin `settings.json`, keybindings has never been one of them, and no keybinding of any kind can target a skill. The chords never fired. The fast path to a skill is typing `/ork:` and letting autocomplete narrow it. Keybindings are still worth setting for Claude Code's own controls. The full context and action tables are in the [Claude Code keybindings docs](https://code.claude.com/docs/en/keybindings). ## Fullscreen Rendering Claude Code v2.1.89+ ships an alternate rendering path that eliminates flicker, keeps memory flat in long conversations, and adds mouse support. Helpful in VS Code's integrated terminal, tmux, and iTerm2 where rendering throughput is the bottleneck. Enable it once and it persists: ```bash /tui fullscreen ``` Or set it directly in `~/.claude/settings.json`: ```json { "tui": "fullscreen" } ``` To disable: `/tui default`. Trade-offs (native `Cmd+f`, terminal selection) and tmux/iTerm caveats are covered in the official docs: [Fullscreen rendering](https://code.claude.com/docs/en/fullscreen). ## Status Line OrchestKit configures a persistent status line at the bottom of your terminal showing: ``` ork v7.1.4 │ feat/my-branch │ 3 uncommitted ``` This updates automatically and shows the plugin version, current git branch, and uncommitted file count. ## Spinner Customization ### Custom Verbs While Claude thinks, the spinner shows custom verbs: *Orchestrating*, *Coordinating*, *Synthesizing*, *Architecting*, *Dispatching*, *Producing*, *Rendering*, *Composing*. ### Spinner Tips Between tasks, the spinner shows OrchestKit tips to help discover features: - `/ork:memory search` to find past decisions - `ctrl+k ctrl+f` to quick-fix an issue - `/ork:analytics` shows usage patterns - `/ork:explore` for deep codebase understanding - `/ork:assess` rates code quality 0-10 Tips are additive. Claude Code's default tips still appear alongside OrchestKit's. ## Plugin Settings Run `/ork:configure` to adjust: - Notification preferences (desktop alerts, sounds) - Memory sync frequency - Hook toggle system (enable/disable specific hooks) - Agent model preferences - Keybindings and spinner customization ## Next Steps - **[The 3 Building Blocks](/docs/foundations/skills-agents-hooks)**: Understand the architecture - **[Memory System](/docs/memory/overview)**: Deep dive into 3-tier memory ## Cursor Install OrchestKit in Cursor. Same ork plugin as Claude Code, minus Claude hook scripts. Marketplace yonatangross/orchestkit. [https://orchestkit.dev/docs/getting-started/cursor](/docs/getting-started/cursor) import { Callout } from 'fumadocs-ui/components/callout'; import { Card, Cards } from 'fumadocs-ui/components/card'; import { HostInstall } from '@/components/host-install'; Cursor is an OrchestKit **host**, not a competing product. It loads [Agent Plugins](https://agent-plugins.org) and Cursor plugins. This repo already ships the Agent Plugins manifest at `plugins/ork/plugin.json`. There is no `cursor install` CLI for this repo. Copy the marketplace slug, paste it, enable **ork**. That is the same plugin Claude Code installs, not a five-skill fork. Claude hook scripts are not registered in Cursor. They depend on `${CLAUDE_PLUGIN_ROOT}` (orchestkit#293, closed). Cursor enforcement for HQ repos stays in the consuming project's `.cursor/hooks.json`. "Include third-party Plugins" can leak SKILL.md from `~/.claude/plugins`. That is not an install. Proof is the `ork` plugin id plus the full skill catalog. ## After install Run `/ork:setup` in the new Cursor chat (the skill is in the plugin). Then [configure project knobs](/docs/getting-started/configuration#project-settings-wizard) if you want protected branches, commit scope, and the rest. Need skills only, without the Cursor marketplace plugin? Use the [skills.sh starter](/docs/getting-started/skills-sh). ## Devin Install the ork plugin in the Devin CLI and Devin Desktop from this repository. Skills load; hooks and rules do not yet. [https://orchestkit.dev/docs/getting-started/devin](/docs/getting-started/devin) import { Callout } from 'fumadocs-ui/components/callout'; import { Card, Cards } from 'fumadocs-ui/components/card'; import { HostHeading, HostMark } from '@/components/host-marks'; import { HostInstall } from '@/components/host-install'; **Devin** is Cognition's coding agent: cloud sessions, the **Devin CLI**, and **Devin Desktop**. It installs plugins from a git source, so OrchestKit is a real plugin here, not a skills-only shim. ## Install The `#plugins/ork` fragment installs the built plugin tree directly. A bare `devin plugins install yonatangross/orchestkit` resolves the same tree through the repository's `.devin-plugin/plugin.json` (#4148). The command installs to your personal scope, so the plugin follows you to cloud sessions and your other signed-in devices. Add `--local` to keep it on this machine only. ## What loads today Measured with Devin CLI 3000.10.27 on ork 10.0.0-beta.30 (`devin plugins info ork`): | Surface | Status | |:-|:-| | Skills | 76 of 107 listed | | Agents | In the plugin files; `plugins info` does not report them | | Hooks | Not loaded | | Rules | Not loaded | Two honest gaps: - The skills Devin skips all carry a `triggers:` frontmatter block its parser does not read. Those are mostly the pipeline skills (`implement`, `explore`, `verify` and friends), so the headliners are exactly the ones missing. This is tracked in [orchestkit#4146](https://github.com/yonatangross/orchestkit/issues/4146). - OrchestKit's hooks are Claude Code `hooks.json` format. Devin expects `hooks.v1.json` with its own tool names, so hooks stay off until a `hooks.v1.json` ships. After installing, run `devin plugins info ork`. Expect 76 skills today; if the list is empty, update the Devin CLI and reinstall. Devin Search for **devin** should land on this page. The word Devin in this heading is the product name for Cognition's agent. } /> } /> ## Your First 10 Minutes Run a health check, write a conventional commit, watch agents start from plain prompts, and store a decision in memory. All in your first ten minutes. [https://orchestkit.dev/docs/getting-started/first-10-minutes](/docs/getting-started/first-10-minutes) import { Card, Cards } from 'fumadocs-ui/components/card'; import { Count } from '@/components/count'; This guide walks you through your first OrchestKit session. By the end, you'll understand how skills, agents, and hooks work together. ## Step 1: Health Check After installing, verify everything is working: ``` /ork:doctor ``` This runs diagnostics on all skills, agents, and hooks. If anything is misconfigured, it tells you exactly what to fix. ## Step 2: Your First Command Skill Make a small change to any file in your project, then: ``` /ork:commit ``` **What happens behind the scenes:** 1. The `commit` skill loads: it knows conventional commit format 2. Hooks fire: `git-validator` checks your branch, `dangerous-command-blocker` ensures safety 3. Claude analyzes your staged diff and writes a conventional commit message 4. The commit includes `Co-Authored-By: Claude` attribution **What you see:** ``` Analyzing staged changes... Commit message: feat: add user email validation to registration form Validate email format and check for duplicate emails before creating user accounts. Returns 422 with specific error messages. Co-Authored-By: Claude Proceed? [Y/n] ``` ## Step 3: See Agents Activate Agents activate from keywords in your natural language. Try: ``` "Review the code I just committed for security issues" ``` **What happens:** - OrchestKit detects "review" and "security" keywords - The `security-auditor` agent spawns automatically - It loads skills: `security-patterns`, `mcp-patterns` - Hooks fire: `security-command-audit` tracks the review **You didn't name the agent.** You just described what you wanted, and OrchestKit matched the right specialist. ## Step 4: Try Multi-Agent Orchestration For a more powerful example: ``` /ork:implement "Add rate limiting middleware to the API" ``` This spawns **multiple agents in parallel**: | Agent | Role | Skills Loaded | |---|---|---| | `backend-system-architect` | Plans the implementation | api-design, python-backend, architecture-patterns | | `test-generator` | Writes tests alongside code | testing-unit, testing-e2e, testing-integration | | `security-auditor` | Validates the approach | security-patterns | ## Step 5: Explore the Memory System OrchestKit remembers across sessions. Try: ``` /ork:remember "We use JWT tokens for auth, not session cookies" ``` This stores your decision in the knowledge graph. In future sessions, when you or an agent works on authentication, this context is automatically injected. Check what's remembered: ``` /ork:memory search "authentication" ``` ## What Just Happened? In 10 minutes, you used: - **3 command skills**: `/ork:commit`, `/ork:implement`, `/ork:remember` - **4 agents**: `security-auditor`, `backend-system-architect`, `test-generator`, plus the commit workflow - **~15 hooks**: firing invisibly on every action (security gates, memory sync, audit logging) - **~10 reference skills**: auto-injected into agents (you never invoked them directly) ## Next Steps ## Hosts Pick a runtime. Claude Code and Cursor install the full ork plugin. Codex uses ork-codex. Pi uses pi install. Muse Code loads skills from .agents/skills. OpenCode and other skills.sh clients use the starter 12. Devin installs the plugin from git. Antigravity reads workspace .agents/skills. [https://orchestkit.dev/docs/getting-started/hosts](/docs/getting-started/hosts) import { Card, Cards } from 'fumadocs-ui/components/card'; import { Callout } from 'fumadocs-ui/components/callout'; import { Count } from '@/components/count'; import { HostMark } from '@/components/host-marks'; import { HostInstallGrid } from '@/components/host-install'; OrchestKit is a plugin library. The host you use decides how much of it you get. | Host | What you get | Page | |---|---|---| | **Claude Code** | skills, agents, hooks | [Claude Code](/docs/getting-started/claude-code) | | **Cursor** | Same `ork` plugin. Claude hook scripts are not registered | [Cursor](/docs/getting-started/cursor) | | **Codex** | Portable workflow pack `ork-codex` (`$ork-implement`, roles) | [Codex](/docs/getting-started/codex) | | **skills.sh** | Skills only. Start with 12, not the whole catalog | [skills.sh](/docs/getting-started/skills-sh) | | **Pi** | Shipped `pi` manifest. Skills via `pi install`, not an `ork-pi` pack | [engine guide](/docs/guides/orchestkit-on-pi-codex-cursor) | | **Muse Code** | Meta's terminal agent. Skills via `.agents/skills`. No `ork-muse` pack yet | [Muse Code](/docs/getting-started/muse) | | **OpenCode** | Agent Skills via skills.sh | [skills.sh](/docs/getting-started/skills-sh) | | **Devin** | Plugin from git via `#plugins/ork`. 76 skills list; hooks and rules do not load | [Devin](/docs/getting-started/devin) | | **Antigravity** | Skills via workspace `.agents/skills`. ork hooks and `.mcp.json` do not load | [Antigravity](/docs/getting-started/agy) | There is no `ork-muse` plugin in this repository. Muse Code stays skills-only. Pi is a real `pi install`, measured in the [engine guide](/docs/guides/orchestkit-on-pi-codex-cursor). ## Quick install Copy the chip for the host you actually run. Cursor has no CLI for this repo: paste the GitHub slug into Settings → Plugins. Coming from Superpowers (official Anthropic marketplace)? Complementary, not a rival. See [OrchestKit vs Superpowers](/docs/getting-started/superpowers). } /> } /> } /> } /> } /> } /> } /> ## Getting Started Install OrchestKit in Claude Code or another host, run a real workflow in your first ten minutes, then learn how to find skills and configure the plugin. [https://orchestkit.dev/docs/getting-started](/docs/getting-started) import { Card, Cards } from 'fumadocs-ui/components/card'; Install the plugin on the host you use, get a real result in the first ten minutes, then learn how to navigate and configure it. ## OrchestKit Installation and Setup Copy one install command for your host: Claude Code, Cursor, Codex, Devin, Pi, Muse Code, Antigravity or skills.sh. On Claude Code, then run /ork:setup. [https://orchestkit.dev/docs/getting-started/installation](/docs/getting-started/installation) import { Callout } from 'fumadocs-ui/components/callout'; import { LazySetupWizard } from '@/components/lazy'; import { Count } from '@/components/count'; import { HostInstallGrid } from '@/components/host-install'; ## Choose your host Pick the host you actually use. Claude Code is the full plugin ( skills, agents, hooks). Cursor gets the same `ork` plugin minus Claude hook scripts. Codex gets the portable `ork-codex` pack. Devin installs the `ork` plugin from git (skills load, hooks do not yet). OpenCode and other Agent Skills clients start with 12 skills on skills.sh. Muse Code (Meta) loads skills from `.agents/skills`. Pi installs via the shipped `pi` manifest. Antigravity reads workspace `.agents/skills`. Click a card to copy its install command. Cursor is a marketplace slug, not a fake CLI. See the [host matrix](/docs/getting-started/hosts) if you are unsure which row you are on. Measured engine notes (pi, Codex, Cursor) live in [OrchestKit on pi, Codex and Cursor](/docs/guides/orchestkit-on-pi-codex-cursor). Evaluating, not installing yet? [Try OrchestKit safely](/docs/getting-started/sandbox): read-only hosted tools, a dry-run install plan, and a throwaway-project recipe. Coming from Superpowers (official Anthropic marketplace)? Complementary. [OrchestKit vs Superpowers](/docs/getting-started/superpowers). ## After you install Then run `/ork:setup`. That is the in-bot wizard (scan, skills, MCP, project knobs). The browser picker below copies a host install command. It is not `/ork:setup --configure`. Project settings (protected branches, commit scope, localhost browser, log level, optional webhook) are documented in [Configuration](/docs/getting-started/configuration#project-settings-wizard). ## Interactive install picker Claude Code users: after the command lands, `/ork:doctor` is the health check. Other hosts skip Claude-only hook diagnostics. ## Muse Code Install OrchestKit skills in Meta's Muse Code. Agent Skills via skills.sh and .agents/skills. No native ork-muse plugin pack yet. [https://orchestkit.dev/docs/getting-started/muse](/docs/getting-started/muse) import { Callout } from 'fumadocs-ui/components/callout'; import { Card, Cards } from 'fumadocs-ui/components/card'; import { HostHeading, HostMark } from '@/components/host-marks'; import { HostInstall } from '@/components/host-install'; **Muse Code** is Meta's terminal coding agent ([docs](https://ai.developer.meta.com/docs/muse-code/)). OrchestKit treats it as a host. This page is that host, not a fake marketplace plugin. There is no `ork-muse` pack in this repository. Muse Code loads [Agent Skills](https://dev.meta.ai/docs/muse-code/extending/#skills) from project `.agents/skills`, user `~/.agents/skills` / `$XDG_CONFIG_HOME/muse/skills`, and (by default) `.claude/skills`. That is the path we use today. ## Install skills Starter 12 (not the whole catalog). Click the chip to copy. `npx skills add` writes SKILL.md trees under `.agents/skills`. Muse Code already scans that directory. If you already installed **ork** in Claude Code on this machine: ```bash muse skills import --from claude ``` Then start Muse Code in the repo (`muse`) and invoke a skill by its slash name. The skill named `implement` is the implement workflow. Codex's pack exposes the same workflow as `$ork-implement`; Muse Code has no `$ork-implement` alias. ## What you do not get Claude Code hook scripts are not Muse Code hooks. Muse Code reads `.muse/hooks.json`, not OrchestKit's Claude `hooks.json`. Do not expect secret-scanning or quality-gate hooks from `ork` to fire here until a native pack exists. No `muse plugin add ork-muse`. No `pi install` style git URL. Official Muse Code install and auth stay on Meta's docs. Muse Search for **muse** should land on this page. The word Muse in this heading is the product short name for Muse Code. } /> } /> ## Find What You Need Hub-and-spoke navigation: find the right skills and agents for your role and task. [https://orchestkit.dev/docs/getting-started/navigating](/docs/getting-started/navigating) import { Card, Cards } from 'fumadocs-ui/components/card'; import { Count } from '@/components/count'; OrchestKit has skills and agents. You don't need to memorize them; this page helps you find exactly what you need. ## By Role Pick your role to see your recommended toolkit: ### Backend Developer **Your agents:** `backend-system-architect`, `database-engineer`, `event-driven-architect` **Your key skills:** - `/ork:implement`: Full feature implementation - `python-backend`: FastAPI, async patterns, middleware - `database-patterns`: Schema design, indexes, migrations - `api-design`: REST endpoint patterns, versioning - `async-jobs`: Task queues, background processing ### Frontend Developer **Your agents:** `frontend-ui-developer`, `frontend-performance-engineer`, `accessibility-specialist` **Your key skills:** - `react-server-components-framework`: RSC patterns, Next.js 16+ - `ui-components`: Component patterns, design systems - `responsive-patterns`: Responsive layouts, mobile-first - `zustand-patterns`: State management - `performance`: Core Web Vitals, bundle optimization ### AI / LLM Engineer **Your agents:** `workflow-architect`, `llm-integrator`, `data-pipeline-engineer` **Your key skills:** - `rag-retrieval`: Retrieval-Augmented Generation - `langgraph`: Multi-agent workflows, LangGraph patterns - `llm-integration`: Tool use, function calling, streaming - `multimodal-llm`: Vision, audio, video processing ### DevOps / Platform **Your agents:** `ci-cd-engineer`, `infrastructure-architect`, `deployment-manager` **Your key skills:** - `devops-deployment`: CI/CD pipelines, Terraform, K8s - `monitoring-observability`: Prometheus, Grafana, OpenTelemetry ### Tech Lead **Your agents:** `system-design-reviewer`, `code-quality-reviewer`, `product-strategist` **Your key skills:** - `/ork:review-pr`: AI-powered code review - `architecture-decision-record`: ADR templates - `architecture-patterns`: SOLID, hexagonal, clean architecture - `quality-gates`: Code quality standards ### Security Engineer **Your agents:** `security-auditor`, `ai-safety-auditor`, `security-layer-auditor` **Your key skills:** - `security-patterns`: OWASP Top 10, defense-in-depth, input validation - `mcp-patterns`: MCP server security ## By Task | I want to... | Use this | |---|---| | Ship a feature fast | `/ork:implement` | | Review a PR | `/ork:review-pr` | | Fix a GitHub issue | `/ork:fix-issue #123` | | Write tests | Just ask; `test-generator` auto-activates | | Debug a problem | Just describe it; `debug-investigator` activates | | Create a commit | `/ork:commit` | | Run all checks | `/ork:verify` | | Search memory | `/ork:memory search "topic"` | | Store a decision | `/ork:remember "decision text"` | | Check health | `/ork:doctor` | | Explore codebase | `/ork:explore` | | Create a PR | `/ork:create-pr` | ## By Keyboard Shortcut There are none, and there cannot be. Claude Code's keybindings bind keys to a closed set of built-in actions (`chat:submit`, `app:toggleTodos`, and so on); no action runs a slash command, so no plugin can ship a shortcut that invokes a skill. This page previously listed 8 `ctrl+k` chords for skills; they never fired. See [Configuration](/docs/getting-started/configuration#keybindings). Type `/ork:` and let autocomplete narrow the list; that is the fast path. ## By Command There are command skills. [Commands You Can Invoke](/docs/skills/command-skills) lists every one, grouped by task, with what it does and the arguments it takes. That page is generated from each skill's frontmatter, so it always matches the plugin you installed. ## Next Steps ## Try OrchestKit Safely Exercise OrchestKit without touching real data: read-only hosted tools, a dry-run install plan, and a throwaway local project. [https://orchestkit.dev/docs/getting-started/sandbox](/docs/getting-started/sandbox) import { Callout } from 'fumadocs-ui/components/callout'; You can evaluate OrchestKit end to end without giving it write access to anything you care about. Three layers, from least to most commitment. ## 1. Read-only hosted tools (no install) The public docs API and both MCP servers need no account and no key. Nothing here can write. - **CLI**: `npx orchestkit` (short form `npx -p orchestkit ork`; bare `npx ork` resolves a different npm package). The `search`, `ask`, `read`, `doctor` and `mcp` commands query the public API or print output; they write nothing. `install` prints the install command for you to inspect. - **OrchestKit Actions MCP** (`https://orchestkit.yonyon.ai/api/mcp/actions`, Streamable HTTP): the product MCP. Three tools, all read-only by construction: - `orchestkit_list_skills`: discover user-invocable skills. - `orchestkit_install_plan`: returns the install commands for a skill or goal. It executes nothing. - `orchestkit_doctor_check`: checks a pasted JSON config fragment. It reads only the input. Server card: [`/.well-known/mcp/actions-server-card.json`](https://orchestkit.yonyon.ai/.well-known/mcp/actions-server-card.json). There is no `dry_run` flag because no tool can mutate state. - **OrchestKit Docs MCP** (`https://orchestkit.yonyon.ai/api/mcp`): docs search and fetch. Details and the stdio Docker image are in [MCP servers](/docs/foundations/mcp-servers). ## 2. Plan an install without running it Call `orchestkit_install_plan` on the Actions MCP, or run `npx orchestkit install` and `npx orchestkit mcp`. Each prints exactly what a real setup would run. You read the plan; nothing executes. ## 3. Exercise the plugin in a throwaway project The plugin runs locally inside your agent host and acts only on the project you open it in. A scratch repo gives it something harmless to work on: ```bash mkdir /tmp/ork-sandbox && cd /tmp/ork-sandbox && git init ``` Install per [Installation](/docs/getting-started/installation), open your host in that directory, then: - `/ork:doctor` reports plugin health. Diagnostics only. - `/ork:commit`, `/ork:review-pr` and friends operate on the scratch repo, so a test file or two is enough to see a real run. - For integrations that call external APIs, the `emulate-seed` skill generates Vercel emulate seed configs (GitHub, Vercel, Stripe and more) so agents exercise stateful local fakes instead of production. Hooks are local lifecycle automation inside the project you opened. Uninstalling the plugin removes them. By default the plugin sends nothing to OrchestKit or to a new third party. Two default paths do call services you already use: the session namer sends the first 600 characters of the session's first prompt and the git branch name to the model provider behind your own `claude` CLI (set `ORK_SESSION_IDENTITY=0` to turn it off), and the review-pr and fix-issue skills fetch PR and issue context with `gh` under your GitHub login. Outbound calls beyond those two start only when you set a switch or provision the servers they call: a telemetry URL plus its token makes hooks post local analytics events to it; `ORK_TYPESAFE_API_KEY` together with `ORK_SESSION_CATEGORY_PROVIDER=jev` or `shadow` makes a hook send an excerpt of the session's first prompt and the git branch name to TypeSafe to label the session; the same key with `ORK_ROUTE_JEV=shadow` or `steer` makes a hook send a redacted copy of build-shaped prompts and the repo name to TypeSafe for routing; and the same key with `ORK_EXPECT_JEV=shadow`, `1` or `act` makes the expect skill's step judge send the step goal, the last verification result, sanitized element names and, when the caller supplies a task document, up to 1200 sanitized characters of it to TypeSafe. Separately, several skill scripts call `memory` and `hq-content` MCP servers: a brainstorm podcast step sends the brainstorm output and design doc, an explore summary step sends the explore synthesis and a notebook ID, the review writeback sends the verdict, the repo and PR number, the changed paths and the text of each finding, the assess writeback sends the scores, the summary and the topic, and lookup scripts send memory searches. These do nothing on a stock install because they need the private `yg-mcp-core` package and MCP servers you set up yourself, and once that setup exists they run without asking each time. ## What not to worry about - **No credentials**: nothing above needs an API key or an account. - **Rate limits**: the hosted API allows 120 requests per minute per IP and answers with `RateLimit-*` headers. Policy: [API versioning and deprecation](/api-policy). ## OpenCode and other skills.sh clients, plus Pi Pi installs from its shipped manifest; OpenCode and any other skills.sh client take the starter 12 skills. Muse Code has its own page. [https://orchestkit.dev/docs/getting-started/skills-sh](/docs/getting-started/skills-sh) import { Callout } from 'fumadocs-ui/components/callout'; import { Card, Cards } from 'fumadocs-ui/components/card'; import { HostHeading } from '@/components/host-marks'; import { HostInstall } from '@/components/host-install'; import { InstallSnippet } from '@/components/install-snippet'; import { SKILLS_SH_STARTER } from '@/lib/host-installs'; Use skills.sh when the host is not Claude Code, Cursor's `ork` marketplace plugin, Codex's `ork-codex` pack, Pi's shipped `pi` manifest, or [Muse Code](/docs/getting-started/muse). That includes **OpenCode**, **Antigravity**, and other skills.sh clients. ## Starter 12 Click the chip. That copies the starter. Do not install the whole catalog on day one. The skill named `implement` is the implement workflow (`/ork:implement` in Claude Code). There is no `ork-implement` on the Claude plugin; Codex uses `$ork-implement` after the [Codex pack](/docs/getting-started/codex) is installed. Full catalog: `npx skills add yonatangross/orchestkit`. That pulls every SKILL.md the indexer found (hundreds of files). Do not treat that as unique users, and do not install the whole firehose on day one. The implement workflow on the registry: [`implement`](https://www.skills.sh/yonatangross/orchestkit/implement). Pi Pi's shipped path is `pi install git:github.com/yonatangross/orchestkit` ([engine guide](/docs/guides/orchestkit-on-pi-codex-cursor)). That is not an `ork-pi` pack. skills.sh below is the fallback if you only want the starter 12 as SKILL.md files. `${CLAUDE_PLUGIN_ROOT}` still arrives as literal text in skill bodies Pi loads. Relative same-skill paths are the portable form. Muse **Muse Code** (Meta) has its own page: [Muse Code](/docs/getting-started/muse). Same skills.sh starter, loaded from `.agents/skills`. No `ork-muse` pack. OpenCode OpenCode is the same path: skills.sh starter 12, not a separate marketplace plugin. Antigravity **Antigravity** (`agy`, Google) has its own page: [Antigravity](/docs/getting-started/agy). Same skills.sh starter, loaded from workspace `.agents/skills`. One caveat: `skills add -g` lands in `~/.agents/skills`, which agy does not read. Claude Code users should install [ork](/docs/getting-started/claude-code). Cursor users should enable **ork** from the marketplace ([Cursor](/docs/getting-started/cursor)). Codex users should install [ork-codex](/docs/getting-started/codex). skills.sh is the remainder. ## OrchestKit vs Superpowers Superpowers is Anthropic's official process plugin. OrchestKit is production patterns plus lifecycle hooks. Complementary, not a rival listing. [https://orchestkit.dev/docs/getting-started/superpowers](/docs/getting-started/superpowers) import { Callout } from 'fumadocs-ui/components/callout'; Superpowers is on the official Anthropic marketplace. Do not treat OrchestKit as a replacement listing for it. Use both, or pick one, based on what you actually need. ## The split | | [Superpowers](https://github.com/obra/superpowers) | OrchestKit | |---|---|---| | Home | Official Anthropic marketplace | `yonatangross/orchestkit` | | Job | Process: how the agent works a task (TDD, planning, review loops) | Production patterns: FastAPI, React, RAG, security, CI, plus lifecycle hooks | | Shape | Small, official, workflow | Broad catalog + `/ork:doctor` + hooks that fire without being asked | If you want the agent to follow a disciplined process, start with Superpowers. If you want it to already know how you ship a FastAPI endpoint, a TanStack query, or a pgvector retriever, and to block a commit that skips tests, that is OrchestKit. ## Install either, or both Claude Code (inside a session): ```bash /plugin marketplace add yonatangross/orchestkit /plugin install ork ``` Cursor: Settings → marketplaces → `yonatangross/orchestkit` → enable **ork** → new chat. A 12-skill starter (not the skills.sh firehose): ```bash npx skills add yonatangross/orchestkit -s devops-deployment -s responsive-patterns -s architecture-decision-record -s ui-components -s rag-retrieval -s agent-orchestration -s brainstorm -s expect -s auto -s review-pr -s fix-issue -s commit ``` Public write-up on yonyon.ai: [OrchestKit vs Superpowers](https://yonyon.ai/compare/orchestkit-superpowers). ## Agent Attribution Automatic tracking of which sub-agents contributed to each branch, with attribution in commit messages and PR bodies. [https://orchestkit.dev/docs/foundations/agent-attribution](/docs/foundations/agent-attribution) # Agent Attribution OrchestKit automatically tracks which sub-agents contributed to your work and surfaces that attribution in **commit messages** and **PR descriptions**. Instead of GitHub showing a single "claude" contributor, agent attribution shows the full team: which specialized agents ran, what they did, how long they took, and whether they ran in parallel. ## How It Works ``` Agent spawns SubagentStart hook ─────────────────► Records HEAD sha + start time Agent completes SubagentStop hook ─────────────────► Appends to branch activity ledger (.claude/agents/activity/{branch}.jsonl) /ork:commit Reads ledger → injects trailers ─────────────────► "Agents Involved:" + Co-Authored-By /ork:create-pr Reads ledger → generates PR body ─────────────────► Badge row + Team Roster + Credits Roll ``` ### The Branch Activity Ledger Every time a sub-agent completes work, the `SubagentStop` hook appends an entry to a JSONL file scoped to the current branch: ```jsonl {"ts":"2026-03-29T07:58:05Z","agent":"ork:backend-system-architect","stage":0,"duration_ms":5263,"summary":"Designed REST API schema...","commit_base":"a8cef5f9..."} {"ts":"2026-03-29T07:58:19Z","agent":"Explore","stage":2,"duration_ms":6029,"summary":"Counted 10 exported functions","commit_base":"a8cef5f9..."} {"ts":"2026-03-29T07:58:23Z","agent":"ork:security-auditor","stage":2,"duration_ms":11369,"summary":"Found path traversal in sanitizeBranch()","commit_base":"a8cef5f9..."} ``` Each entry captures: | Field | Description | |-------|-------------| | `agent` | Sub-agent type (e.g., `ork:security-auditor`) | | `stage` | Execution stage: `0` = Lead, `1` = Parallel, `2` = Follow-up | | `duration_ms` | How long the agent ran (real wall-clock time) | | `summary` | What the agent concluded (first 300 chars of response) | | `commit_base` | HEAD sha when the agent started (for commit attribution) | | `orchestrator` | Which skill spawned the agent (e.g., `brainstorm`, `implement`) | ## Commit Attribution When you run `/ork:commit`, the skill reads the ledger and injects two things into the commit message: ### 1. "Agents Involved" Section ``` feat(auth): implement OAuth2 flow - Added token refresh endpoint - Configured PKCE flow Agents Involved: ork:backend-system-architect — API design + data models (2m14s) ork:security-auditor — Token rotation hardening (0m42s) ork:test-generator — 47 integration tests (2m01s) Co-Authored-By: Claude ``` ### 2. Per-Agent Co-Authored-By Trailers ``` Co-Authored-By: Claude Co-Authored-By: ork:backend-system-architect Co-Authored-By: ork:security-auditor Co-Authored-By: ork:test-generator ``` Only agents that ran for more than 5 seconds or produced file changes are included in commit trailers. Advisory-only agents appear in the PR body instead. ## PR Attribution When you run `/ork:create-pr`, the skill reads the full branch ledger and generates: ### Badge Row Shields.io badges showing agent count, tests generated, and vulnerability scan results. ### Agent Team Sheet A Markdown table showing each agent, what it did, its execution stage, and duration: | Agent | Task | Stage | Time | |-------|------|-------|------| | **backend-system-architect** | API design + data models | Lead | 2m14s | | **security-auditor** | Dependency audit | Parallel | 0m42s | | **test-generator** | 47 tests, 94% coverage | Parallel | 2m01s | ### Credits Roll A collapsible `
` section grouping agents by execution stage: - **Lead**: The first agent spawned (typically the architect or designer) - **Parallel**: Agents that ran simultaneously (security, testing, frontend) - **Follow-up**: Agents that ran after the parallel batch (CI/CD, quality review) ## Parallel Execution Stages OrchestKit tracks whether agents ran sequentially or in parallel: | Stage | Value | Meaning | |-------|-------|---------| | Lead | `0` | First agent spawned, sets the direction | | Parallel | `1` | Ran in background simultaneously with others | | Follow-up | `2` | Ran after the parallel batch completed | This maps to how OrchestKit skills actually work. For example, `/ork:brainstorm` spawns 4 agents in parallel after a lead agent designs the approach, then follow-up agents synthesize results. ## Data Storage | File | Purpose | Lifetime | |------|---------|----------| | `.claude/agents/activity/{branch}.jsonl` | Branch activity ledger | Until branch is deleted or 30 days | | `.claude/agents/session-state.json` | Start times + commit base | Current session | Both files are `.gitignore`d; they're ephemeral session data, never committed to the repository. ## Cleanup The `Stop` hook automatically cleans up stale ledger files: - Ledgers for branches that no longer exist are deleted - Ledgers older than 30 days are pruned - Session state resets on each new session ## Configuration Agent attribution is **enabled by default** with no configuration needed. The system activates automatically when: 1. You use any skill that spawns sub-agents (`/ork:implement`, `/ork:brainstorm`, `/ork:fix-issue`, etc.) 2. You commit with `/ork:commit` 3. You create PRs with `/ork:create-pr` ## Plugin Architecture OrchestKit ships as one unified plugin: everything loads on-demand with zero overhead. [https://orchestkit.dev/docs/foundations/choosing-a-plugin](/docs/foundations/choosing-a-plugin) import { Count } from '@/components/count'; ## One Plugin, Everything Included OrchestKit ships as a single plugin: **ork**. Inside a Claude Code session: ```bash /plugin marketplace add yonatangross/orchestkit /plugin install ork ``` Or from a terminal: ```bash claude plugin marketplace add yonatangross/orchestkit && claude plugin install ork@orchestkit ``` No choices, no configuration required. All skills, agents, and hooks install together. ## What Loads When Not everything runs at once. OrchestKit uses **on-demand loading** to stay fast: | Component | When It Loads | Overhead | |-----------|--------------|----------| | **Hooks** | Session start; only event-matched hooks fire | ~800 tokens/turn max | | **Agents** | When spawned by name or keyword match | Zero until invoked | | **Skills** | Injected into agent context when relevant | Zero until matched | | **Commands** | Available immediately via `/ork:skillname` | Listing only (~80 tokens/skill) | ## Why One Plugin Early versions split functionality into multiple plugins (`orkl`, `ork-creative`). This caused: - Version conflicts between plugins - Duplicate hook registrations - Confusing install instructions Since v7.0, everything is consolidated into `ork`. Skills you don't use have zero token cost. ## Next Steps - **[Installation](/docs/getting-started/installation)**: Full install guide with verification - **[First 10 Minutes](/docs/getting-started/first-10-minutes)**: Guided first session ## Foundations The core concepts behind OrchestKit: skills, agents, hooks, and how they compose. [https://orchestkit.dev/docs/foundations](/docs/foundations) import { Card, Cards } from 'fumadocs-ui/components/card'; The concepts everything else builds on. Start here if you want to understand what the plugin actually does before wiring it into a project. ## OrchestKit MCP Servers The MCP servers OrchestKit agents consume (web search, component registries, design extraction) and the OrchestKit Docs MCP server that agents can connect to. [https://orchestkit.dev/docs/foundations/mcp-servers](/docs/foundations/mcp-servers) MCP (Model Context Protocol) servers extend what OrchestKit agents can do by connecting them to external tools and services. Most are **optional**, and every skill and agent still runs without them, but MCPs add capabilities that can't be replicated with built-in tools alone. One of them, **context7**, is a prerequisite rather than an extra. ## Prerequisite: context7 22 of OrchestKit's 36 agents grant `mcp__context7__*` in their frontmatter, and the plugin ships **no server definition for it**. `plugins/ork/settings.json` carries a `permissions` block only, the plugin manifest declares no MCP servers, and `.mcp.json` is gitignored in the OrchestKit repo, so it is not part of the plugin payload either. A grant authorizes a server. It does not provide one. **What happens if you skip this.** Those 22 agents still spawn and still answer. They answer from training data, because the grant points at a server that is not in your session. No error is raised, no tool call fails, and `/ork:implement` looks like it worked. Stale API advice is the only symptom. Add context7 once, project-scoped in `.mcp.json` or user-scoped in `~/.claude.json`, before trusting any of them: ```json { "mcpServers": { "context7": { "type": "http", "url": "https://mcp.context7.com/mcp" } } } ``` Then run `/ork:doctor`; it prints `MCP: context7 ✓` once the server is live. API-key and transport options are in [context7 (library docs)](#context7-library-docs) below. ### Why ork does not ship a server definition Deliberate, and it stays that way: 1. **`.mcp.json` is user-owned.** It is project-scoped, gitignored here, and holds entries for servers that have nothing to do with ork. A plugin that writes it is editing a file it does not own, in every project it is installed in. 2. **A key cannot be shipped.** The Pro entry carries an `Authorization` header sourced from `${CONTEXT7_API_KEY}`. A shipped default would either omit the key (silently downgrading Pro subscribers to the free tier) or reference an environment variable most users have never set, which produces the unexpanded-literal failure described under [context7 (library docs)](#context7-library-docs). 3. **stdio would multiply.** The legacy transport spawns one child process per Claude Code session. Shipping it plugin-wide multiplies that by every project ork is installed in. `/ork:setup` recommends context7 and prints the entry for you to paste. `/ork:doctor` tells you whether it took. ## Available MCPs OrchestKit supports 10 MCP servers across three tiers: ### Core (no API key required) You add these to `.mcp.json` yourself; none of them needs an API key to start returning results. They are not shipped by the plugin. | MCP | Purpose | Tools | |-----|---------|-------| | **context7** | Up-to-date library docs (React, Next.js, Tailwind, etc.) | 2 | | **memory** | Knowledge graph: persist decisions across sessions | 8 | | **sequential-thinking** | Structured reasoning for Sonnet/Haiku subagents | 1 | context7's two tools are `mcp__context7__resolve-library-id` and `mcp__context7__query-docs`. That pair is the entire surface on every published version, 2.x through 4.x; any other spelling grants nothing and fails silently. ### API Key Required Pre-configured in `.mcp.json` but need an API key to activate. | MCP | Purpose | Setup | |-----|---------|-------| | **tavily** | Web search, extract, crawl, deep research | API key ([app.tavily.com](https://app.tavily.com), free 1K credits/month) | | **21st-dev-magic** | React component registry (1.4M developers) | API key ([21st.dev](https://21st.dev), free tier available) | ### User-Installable Not in `.mcp.json`: you add these per-project when needed. Agents that reference them degrade gracefully when they're absent. | MCP | Purpose | Setup | |-----|---------|-------| | **stitch** | Google Stitch: AI design to HTML, screenshots, design context | API key from [stitch.withgoogle.com](https://stitch.withgoogle.com/settings) | | **storybook-mcp** | Project component discovery, testing, previews via Storybook 10.3+ | `@storybook/addon-mcp` + running Storybook | | **notebooklm-mcp** | Google NotebookLM: RAG, research synthesis, podcasts | `uv tool install notebooklm-mcp-cli` + `nlm login` | ## Recommended by Project Type Not sure which MCPs to enable? Match your project: | Project Type | Recommended MCPs | Why | |---|---|---| | **Full-stack React** | context7, memory, storybook-mcp, 21st-dev-magic, stitch | Component reuse, design extraction, latest API docs | | **Backend Python/Node** | context7, memory, tavily | Library docs, decision persistence, web research | | **Design system** | stitch, storybook-mcp, 21st-dev-magic, context7 | Figma extraction, component discovery, registry search | | **AI/LLM project** | context7, memory, tavily, sequential-thinking | API docs, pattern memory, research, structured reasoning for subagents | | **Open source library** | context7, memory | Minimal footprint: docs + decision tracking | | **Research/analysis** | tavily, memory, notebooklm-mcp | Web search, knowledge graph, RAG synthesis | ## Which Agents Use Which MCPs OrchestKit scopes MCP access per agent to keep context windows lean. ### Multi-MCP Agents | Agent | MCPs | What It Uses Them For | |---|---|---| | frontend-ui-developer | context7, 21st-dev-magic, storybook-mcp | React docs, component search, story previews | | design-system-architect | context7, stitch, storybook-mcp | Token docs, design extraction, component discovery | | design-context-extractor | stitch, context7 | Screenshot analysis, token architecture docs | ### Single-MCP Specialists | Agent | MCP | What It Uses It For | |---|---|---| | web-research-analyst | tavily | Search, extract, crawl | | market-intelligence | tavily | Market analysis with domain filtering | | product-strategist | tavily | Competitive landscape research | | ai-safety-auditor | tavily | Content extraction with injection detection | | monitoring-engineer | tavily | Service status research | | component-curator | storybook-mcp | Component inventory, story coverage audit | | debug-investigator | memory | Recall past debugging decisions | ### context7 Library Docs (19 agents) These agents use **context7** for up-to-date library documentation: backend-system-architect, database-engineer, test-generator, workflow-architect, infrastructure-architect, event-driven-architect, data-pipeline-engineer, python-performance-engineer, llm-integrator, ci-cd-engineer, eval-runner, release-engineer, deployment-manager, git-operations-engineer, frontend-performance-engineer, accessibility-specialist, multimodal-specialist, code-quality-reviewer, claude-design-orchestrator With the three multi-MCP agents above (frontend-ui-developer, design-system-architect, design-context-extractor) that is **22 of 36 agents** whose behaviour changes when context7 is absent. ### No MCP Access These agents intentionally have `mcpServers: []`, so they work with built-in tools only: security-auditor, security-layer-auditor, system-design-reviewer, genui-architect, emulate-engineer, demo-producer ## Setup Instructions ### memory and sequential-thinking (no key, no account) Both are npx-launched stdio servers with nothing to configure beyond the entry itself. Copy `.claude/templates/mcp-enabled.json` from the OrchestKit repo for the exact shape. ### context7 (library docs) Two transports. Prefer the hosted one. **Hosted HTTP (recommended).** No local process, one shared endpoint: ```json "context7": { "type": "http", "url": "https://mcp.context7.com/mcp" } ``` That entry is the whole free tier. It needs no account and no key. **Pro key.** Add the header only once the variable is actually exported: ```json "context7": { "type": "http", "url": "https://mcp.context7.com/mcp", "headers": { "Authorization": "Bearer ${CONTEXT7_API_KEY}" } } ``` ```bash export CONTEXT7_API_KEY="ctx7sk-your-key-here" ``` Keys start with `ctx7sk-`. Keep them in your shell profile or a secret manager and reference the variable; never paste a literal key into `.mcp.json`, which is a file people share and diff. **stdio (fallback).** For a proxied or air-gapped network where the hosted endpoint is unreachable: ```json "context7": { "command": "npx", "args": ["-y", "@upstash/context7-mcp@4.0.2", "--api-key", "${CONTEXT7_API_KEY}"] } ``` Drop the `--api-key` pair to run keyless. **stdio costs one child process per Claude Code session**, because the client spawns the server: ten concurrent sessions means ten `npx` children resolving and running the package. That fan-out, not style, is why hosted HTTP is the recommended transport. #### Free vs Pro | | Free | Pro ($10 per seat per month) | |---|---|---| | Requests | 1,000 | 5,000 per seat, then $10 per additional 1,000 | | Repositories | Public only | Public plus private repo parsing | | Key | None needed | `ctx7sk-...` from [context7.com](https://context7.com) | Both tiers expose the same two tools. Pro raises quota and unlocks private repositories; it does not add a tool, and neither does moving from 2.x to 4.x. #### A connected context7 proves nothing about your key `tools/list` returns HTTP 200 for every auth state: no header, a garbage bearer, an unexpanded `${CONTEXT7_API_KEY}` literal, or a valid key. So "context7 connected" and a green tool count are not evidence that a Pro key is in use. Only an actual query discriminates. With a bad or unexpanded key it comes back with: ```text Invalid API key. Please check your API key. API keys should start with 'ctx7sk' prefix. ``` The practical rule: do not add the `Authorization` header until the variable is exported. A header that expands to the literal string `${CONTEXT7_API_KEY}` connects, lists two tools, and fails every query, which reads like a context7 outage rather than your own config. **Hosted plus bearer does not fall back to anonymous.** If `CONTEXT7_API_KEY` is unset, the unexpanded literal is transmitted as the bearer token and **every** query fails. It does not quietly downgrade to the free tier. The keyless entry above, with no `headers` block, is a fully working free tier. So the header is a hard dependency on the export: ship `"headers"` and `export CONTEXT7_API_KEY` together, or ship neither. ### Tavily (web research) ```bash # Option A: 1Password (recommended — no key in config files) # .mcp.json already uses: sh -c "TAVILY_API_KEY=$(op read '...') exec npx tavily-mcp@latest" # Just store your key: op item create --category "API Credential" --title "Tavily API Key" "API Key=tvly-..." # Option B: Environment variable # Replace the .mcp.json tavily entry with: # "command": "npx", "args": ["-y", "tavily-mcp@latest"] # Then add to ~/.zshrc: export TAVILY_API_KEY= # Option C: Remote MCP (no local process) # In .mcp.json: "type": "url", "url": "https://mcp.tavily.com/mcp/?tavilyApiKey=" ``` Free tier: 1,000 credits/month at [app.tavily.com](https://app.tavily.com). ### 21st.dev Magic (component registry) ```bash # .mcp.json already uses: sh -c "API_KEY=$(op read '...') exec npx @21st-dev/magic@latest" # Store your key: op item create --category "API Credential" --title "21st.dev Magic MCP" "credential=" # Alternative: replace .mcp.json entry with env var approach # "command": "npx", "args": ["-y", "@21st-dev/magic@latest"] # Then add to ~/.zshrc: export API_KEY= ``` Free tier available at [21st.dev](https://21st.dev). ### Stitch (design extraction) ```bash claude mcp add stitch --transport http https://stitch.googleapis.com/mcp \ --header "X-Goog-Api-Key: " -s user ``` Get your API key from [stitch.withgoogle.com/settings](https://stitch.withgoogle.com/settings). ### Storybook MCP (component discovery + testing) Requires Storybook 10.3+ with Vite builder: ```bash # Install the addon npx storybook add @storybook/addon-mcp # Enable docs toolset in .storybook/main.ts # experimentalComponentsManifest: true # Register with Claude Code npx mcp-add --type http --url "http://localhost:6006/mcp" --scope project ``` Storybook must be running for dev + testing tools. The docs toolset can be published remotely via Chromatic. ### NotebookLM (RAG + research) ```bash uv tool install notebooklm-mcp-cli nlm login nlm setup add claude-code ``` ## How MCP Scoping Works Each agent declares which MCPs it can access in its frontmatter: ```yaml --- name: frontend-ui-developer mcpServers: [context7, 21st-dev-magic, storybook-mcp] --- ``` - **`mcpServers` omitted**: agent inherits ALL MCP tools from parent - **`mcpServers: [tavily]`**: agent ONLY sees tavily tools - **`mcpServers: []`**: agent sees NO MCP tools This prevents Sonnet/Haiku subagents (128K context) from being overwhelmed by tool definitions they don't need. ## Token Overhead Each MCP adds tool definitions to the context window: | MCP | Tools | ~Tokens | |-----|-------|---------| | context7 | 2 | ~400 | | memory | 8 | ~1,200 | | sequential-thinking | 1 | ~600 | | tavily | 5 | ~2,000 | | 21st-dev-magic | 4 | ~800 | | stitch | 14 | ~2,800 | | storybook-mcp | 6 | ~1,200 | | notebooklm-mcp | 36 | ~7,000 | When total MCP tokens exceed 10% of context, Claude Code automatically activates **MCPSearch**, deferring schema loading and discovering tools on demand (~85% reduction). ## Graceful Degradation Every skill works without MCPs; they just lose specific capabilities: | Without | Fallback | |---------|----------| | context7 | The 22 agents that grant it answer from training data instead of current docs. Nothing errors, so stale API advice is the only symptom. | | tavily | Web research uses `WebFetch` (summarized) then `agent-browser` (headless) | | memory | Decisions persist via local `.jsonl` files and CC Native memory | | storybook-mcp | Component discovery falls back to `Glob` + `Grep` + 21st.dev search | | stitch | Design extraction uses Claude's multimodal vision on screenshots | | 21st-dev-magic | Component search falls back to `WebSearch("site:21st.dev ...")` | ## Disabling an MCP Set `"disabled": true` in `.mcp.json`: ```json "sequential-thinking": { "command": "npx", "args": ["-y", "@modelcontextprotocol/server-sequential-thinking"], "disabled": true } ``` ## Background Agent Limitation MCP tools are **not available** in background subagents (`run_in_background: true`). This is a Claude Code platform limitation. If an agent needs MCP tools, run it in the foreground. ## OrchestKit Docs MCP Server The servers above are ones OrchestKit *consumes*. OrchestKit also *publishes* one: the **OrchestKit Docs MCP** server exposes this documentation to any MCP client, read-only, with no authentication. | Surface | URL | |---------|-----| | Streamable HTTP endpoint | `https://orchestkit.yonyon.ai/api/mcp` (POST; JSON-RPC 2.0) | | Server card | [`/.well-known/mcp/server-card.json`](https://orchestkit.yonyon.ai/.well-known/mcp/server-card.json) | | Local stdio image | `docker run -i --rm ghcr.io/yonatangross/orchestkit-docs-mcp` | | Registry entry | `io.github.yonatangross/orchestkit` on [registry.modelcontextprotocol.io](https://registry.modelcontextprotocol.io/v0/servers?search=io.github.yonatangross/orchestkit) | Two tools: `orchestkit_docs_search` (ranked pages with titles and URLs) and `orchestkit_docs_get` (one page as Markdown by path). The same API is described by the [OrchestKit OpenAPI 3.1 spec](https://orchestkit.yonyon.ai/openapi.json); every developer surface is indexed at the [OrchestKit developer resources hub](/developers). ## OrchestKit Actions MCP Server OrchestKit also publishes a second MCP server: the **OrchestKit Actions MCP** exposes read-only CLI actions so agents can plan installations without executing anything. This is the product MCP that satisfies ora.ai's multi-surface coverage check. | Surface | URL | |---------|-----| | Streamable HTTP endpoint | `https://orchestkit.yonyon.ai/api/mcp/actions` (POST; JSON-RPC 2.0) | | Server card | [`/.well-known/mcp/actions-server-card.json`](https://orchestkit.yonyon.ai/.well-known/mcp/actions-server-card.json) | Three tools: - `orchestkit_list_skills`: Discover user-invocable skills with names, descriptions, and docs URLs. - `orchestkit_install_plan`: Generate install and invocation commands for user-invocable skills or goals. Returns a plan; executes nothing. - `orchestkit_doctor_check`: Run basic checks on a pasted JSON object config fragment. It does not parse YAML and reads only the input. All three tools are read-only by construction. The install plan tool returns shell commands to run for user-invocable skills; it never runs them. The doctor tool performs basic checks on pasted JSON objects; it touches no files. For hooks, the doctor tool expects a `hooks` object keyed by event name. Each event value must be an array of object entries, and each entry must contain a `hooks` array. It does not validate nested hook command fields. ## Sandbox and Dry-Run Mode Every tool on the Actions MCP server is read-only. There is no sandbox mode to enable because nothing writes. The documentation states this honestly: no tool can mutate state, so no special `dry_run` flag exists. If you need to test an installation without affecting your system, run the commands returned by `orchestkit_install_plan` in a disposable environment (a container, a VM, or a fresh git worktree). The MCP server itself cannot execute anything. ## Next Steps - **[The 3 Building Blocks](/docs/foundations/skills-agents-hooks)**: Understand agents that consume MCPs - **[Configuration](/docs/getting-started/configuration)**: Environment variables and hook settings - **[Plugin Architecture](/docs/foundations/choosing-a-plugin)**: How everything loads on-demand ## What is OrchestKit? OrchestKit is one Claude Code plugin. Hooks run on every action, agents start from your prompt, and skills load the right patterns. Stop explaining your stack. [https://orchestkit.dev/docs/foundations/overview](/docs/foundations/overview) import { Card, Cards } from 'fumadocs-ui/components/card'; import { Steps, Step } from 'fumadocs-ui/components/steps'; import { Count } from '@/components/count'; OrchestKit is a **Claude Code plugin** that gives your AI assistant deep expertise in software engineering. Instead of explaining your stack on every prompt, OrchestKit injects the right knowledge at the right time. ## Before vs After | Without OrchestKit | With OrchestKit | |---|---| | "Use FastAPI with async, SQLAlchemy 2.0..." | Just describe the feature | | Manual code review checklists | `/ork:review-pr` runs 3 agents in parallel | | Copy-paste commit conventions | `/ork:commit` writes conventional commits | | "Remember to check OWASP..." | Security hooks fire automatically | | Context lost between sessions | 3-tier memory persists everything | ## How It Works When you type a prompt, OrchestKit works in three layers: ### Hooks () fire automatically Security gates, auto-lint, and memory injection run on every action; you never invoke them directly. ### Agents () activate from keywords Say "review PR" and `security-auditor` spawns. Say "design API" and `backend-architect` activates. Multiple agents can run in parallel. ### Skills () inject into agents Reusable knowledge (FastAPI patterns, React hooks, OWASP checklist, RAG strategies), loaded on demand by whichever agent needs them. ## One Plugin OrchestKit ships as a single plugin: **ork**, with skills, agents, hooks. ## Next Steps ## The 3 Building Blocks Skills are knowledge, agents are specialists, hooks are automation. Here's how they work together. [https://orchestkit.dev/docs/foundations/skills-agents-hooks](/docs/foundations/skills-agents-hooks) import { Steps, Step } from 'fumadocs-ui/components/steps'; import { Count } from '@/components/count'; OrchestKit has three types of components. Understanding how they connect is the key to using the toolkit effectively. ## Skills: Reusable Knowledge A skill is a markdown file containing expert knowledge about a specific topic. Think of skills as **reference cards** that Claude reads when it needs domain expertise. ``` src/skills/python-backend/SKILL.md ``` ** skills** covering: FastAPI, React, SQLAlchemy, RAG, LangGraph, OWASP, Terraform, and more. ### Two Types | Type | Count | How It Works | Example | |---|---|---|---| | **Command** | | You invoke directly: `/ork:commit` | `/ork:verify`, `/ork:implement` | | **Reference** | | Auto-injected into agents | `python-backend`, `security-patterns` | Command skills are what you type. Reference skills are what agents read. You never need to invoke a reference skill; the right agent loads the right skills automatically. ### Skill Anatomy Every skill has YAML frontmatter that controls how it's discovered and used: ```yaml --- name: python-backend description: Python backend patterns including FastAPI, async, middleware tags: [python, fastapi, backend] user-invocable: false # Reference skill (not a command) complexity: medium # Helps Claude calibrate effort agent: backend-system-architect # Which agent uses this --- ``` ## Agents: Specialized AI Personas An agent is a **specialized Claude instance** with a specific role, tools, and injected skills. When you say "design a database schema", OrchestKit spawns the `database-engineer` agent, pre-loaded with schema design skills, migration patterns, and normalization knowledge. ** agents** covering: backend architecture, frontend UI, security auditing, test generation, debugging, deployment, and more. ### How Agents Activate Agents activate from **keywords in your prompt**. You don't need to name them: | You Say | Agent Spawned | Skills Loaded | |---|---|---| | "review this PR" | `code-quality-reviewer` | code-review-playbook, testing-unit, testing-e2e | | "design the API" | `backend-system-architect` | api-design, architecture-patterns | | "find the bug" | `debug-investigator` | errors, monitoring-observability | | "optimize performance" | `frontend-performance-engineer` | performance, vite-advanced | | "scan for vulnerabilities" | `security-auditor` | security-patterns, mcp-patterns | ### Agent Anatomy ```yaml --- name: backend-system-architect model: opus # Uses the most capable model tools: [Read, Write, Bash, Grep, Glob] skills: # 31 skills auto-injected - api-design - database-patterns - architecture-patterns # ... --- ``` ### Parallel Agents Some commands spawn **multiple agents in parallel**. When you run `/ork:review-pr`, three agents work simultaneously: | Agent | Role | |---|---| | `security-auditor` | OWASP scan | | `code-quality-reviewer` | Style and patterns | | `test-generator` | Coverage gaps | All three run in parallel, then results are synthesized into a single PR review. ## Hooks: Invisible Automation Hooks are TypeScript functions that **fire automatically** on lifecycle events. You never invoke them; they run in the background on every prompt, tool call, and session transition. **163 hooks** across 12 categories: | Category | Count | What It Does | |---|---|---| | `pretool` | 24 | Runs before a tool executes (security gates, validation) | | `posttool` | 19 | Runs after a tool executes (audit logging, metrics) | | `prompt` | 14 | Runs when you submit a prompt (context injection, memory) | | `lifecycle` | 16 | Session start/stop events (env setup, cleanup) | | `skill` | 22 | Runs during skill execution (quality gates, patterns) | | `agent` | 5 | Runs during agent operations (safety checks) | | `permission` | 3 | Auto-approves safe operations | | `stop` | 14 | Session end (save context, sync memory) | | `subagent` | 11 | Manages sub-agent lifecycle | | `setup` | 8 | First-run initialization | | `notification` | 3 | Desktop/sound alerts | ### Example: What Happens on a Git Push When Claude runs `git push`, hooks fire in sequence: **Before execution (pretool):** | Hook | Action | |---|---| | `dangerous-command-blocker` | Checks for force-push | | `git-validator` | Validates branch rules | | `compound-command-validator` | Checks piped commands | **After execution (posttool):** | Hook | Action | |---|---| | `audit-logger` | Records the action | | `session-metrics` | Updates session stats | | `workflow-analytics` | Updates workflow analytics | ## How They Connect Here's what happens when you say **"Add user auth to the API"**: ### Prompt hooks fire `context-injector`, `memory-context-loader`, and `skill-auto-suggest` enrich your prompt with project context. ### Agent spawns **backend-system-architect** activates (model: opus) based on keyword matching. ### Skills injected The agent auto-loads `security-patterns`, `api-design`, `python-backend`, and `architecture-patterns`. ### Agent writes code Pretool hooks validate each tool call. Posttool hooks audit and log every action. ### Stop hooks `auto-remember-continuity` and `session-profile-agg` save context for the next session. ## Next Steps - **[Choosing a Plugin](/docs/foundations/choosing-a-plugin)**: Plugin installation options - **[Installation](/docs/getting-started/installation)**: Get started in 2 minutes ## Worktree isolation When to keep the default EnterWorktree isolation for background sessions, and when worktree.bgIsolation "none" is the right opt-in. [https://orchestkit.dev/docs/foundations/worktree](/docs/foundations/worktree) Claude Code 2.1.143 added a `worktree.bgIsolation` setting. This page covers what it does, when opting in is reasonable, and why OrchestKit keeps the default. ## What `worktree.bgIsolation` does By default, a background session that wants to edit files calls `EnterWorktree` first. Claude Code creates a git worktree for the session, the session works inside it, and the shared working copy stays untouched. Two sessions in the same repo never write to the same files at the same time. Setting `worktree.bgIsolation` to `"none"` in `.claude/settings.json` removes that step: ```json { "worktree": { "bgIsolation": "none" } } ``` Background sessions then edit the working copy directly, with no worktree in between. The release notes name the intended audience: repos where worktrees are impractical. ## When to opt in `"none"` fits a narrow profile. Both conditions should hold: 1. **Worktrees are impractical in the repo.** Examples: a dependency install that cannot be duplicated per checkout (a symlinked `node_modules`, a build cache bound to one absolute path), tooling that only runs against the primary checkout, or a monorepo where a second checkout costs more than the isolation buys. 2. **Only one session runs in the repo at a time.** With two concurrent sessions on one working copy, edits interleave: one session's checkout, install, or file write lands in the middle of the other's task. That shared-tree thrash is the failure class `EnterWorktree` exists to prevent. If either condition fails, keep the default. ## Recommendation: do not set it in OrchestKit OrchestKit's working rule is that every concurrent session in a repo works in its own worktree. That rule depends on the default `EnterWorktree` path staying on, so OrchestKit does not set `worktree.bgIsolation` and its `.claude/settings.json` carries no `worktree` key. A repo that genuinely needs `"none"` should scope the setting to that repo's own `.claude/settings.json`, never to user-global settings, and only while the single-session condition holds. ## Related: the EnterWorktree bug class Issue [#1826](https://github.com/yonatangross/orchestkit/issues/1826) is the related class: an envelope leak reached `EnterWorktree`'s name path, and background sessions created literal `{"continue":true}` directories across five repos. That class argues for hardening the inputs `EnterWorktree` receives, not for abandoning isolation. `bgIsolation: "none"` would have hidden the symptom while leaving every shared-repo session exposed to interleaved writes. ## Graph Memory (Primary) The zero-config knowledge graph that stores entities and typed relations as OrchestKit's primary memory tier. [https://orchestkit.dev/docs/memory/graph-memory](/docs/memory/graph-memory) import { Callout } from 'fumadocs-ui/components/callout'; Graph memory is Tier 1, the **primary** storage layer in OrchestKit's memory architecture. It uses the `@modelcontextprotocol/server-memory` MCP server to maintain a knowledge graph of entities and their relationships. It requires zero configuration and is always available. ## How It Works The knowledge graph stores two things: 1. **Entities**: named nodes with a type and a list of observations 2. **Relations**: directed, typed edges between entities When you run `/ork:remember "database-engineer uses pgvector for RAG applications"`, the system creates: ``` Entities: - database-engineer (Agent) observations: ["Uses pgvector for RAG"] - pgvector (Technology) observations: ["Used for RAG applications"] - RAG (Pattern) observations: ["Implemented with pgvector"] Relations: database-engineer --USES--> pgvector pgvector --USED_FOR--> RAG ``` This structure enables precise queries that flat text search cannot answer: "What does database-engineer use?" returns `pgvector` via the `USES` relation. "What is pgvector used for?" returns `RAG` via the `USED_FOR` relation. ## MCP Commands All graph operations go through the MCP memory server. OrchestKit wraps these in hooks and skills so you rarely call them directly, but understanding the API helps when debugging or doing advanced queries. ### Creating Entities ``` mcp__memory__create_entities { "entities": [ { "name": "cursor-pagination", "entityType": "Pattern", "observations": [ "Chosen for all list endpoints", "Scales well for 2M+ row tables" ] }, { "name": "PostgreSQL", "entityType": "Technology", "observations": [ "Primary database for transactional data" ] } ] } ``` ### Creating Relations ``` mcp__memory__create_relations { "relations": [ { "from": "project", "to": "cursor-pagination", "relationType": "CHOSE" }, { "from": "cursor-pagination", "to": "offset-pagination", "relationType": "CHOSE_OVER" } ] } ``` ### Searching the Graph ``` mcp__memory__search_nodes { "query": "pagination database" } ``` Returns matching entities with their observations and connected relations. This is the call the `memory-context` hook generates automatically on every prompt. ### Opening Entity Details ``` mcp__memory__open_nodes { "names": ["cursor-pagination", "PostgreSQL"] } ``` Returns full entity details including all observations and all relations where the entity appears (as source or target). ### Adding Observations ``` mcp__memory__add_observations { "observations": [ { "entityName": "cursor-pagination", "contents": ["Confirmed to handle 5M rows with sub-100ms response"] } ] } ``` Appends new observations to an existing entity without creating duplicates. The `/ork:remember` skill uses this when it detects that an entity already exists in the graph. ## Entity Types The memory writer infers entity types from the content of your text: | Entity Type | Examples | When Assigned | |---|---|---| | `Technology` | PostgreSQL, React, FastAPI, pgvector | Capitalized technology names | | `Pattern` | cursor-pagination, connection-pooling, CQRS | Named patterns and conventions | | `Decision` | "Use JWT for auth" | Text with "decided", "chose", "selected" | | `Preference` | "Prefer TypeScript over JavaScript" | User preferences | | `AntiPattern` | offset-pagination (failed) | Patterns marked with `--failed` | | `Agent` | database-engineer, backend-system-architect | OrchestKit agent names | | `Tool` | grep, jest, pytest | Development tools | | `Workflow` | CI/CD pipeline, release process | Process descriptions | | `Solution` | "Fixed N+1 with DataLoader" | Problem-solution records | ## Relation Types | Relation | Meaning | Example | |---|---|---| | `CHOSE` | Active selection | `project --CHOSE--> JWT` | | `CHOSE_OVER` | Rejected alternative | `JWT --CHOSE_OVER--> session-cookies` | | `USES` | Active usage | `auth-service --USES--> JWT` | | `USED_FOR` | Purpose | `pgvector --USED_FOR--> RAG` | | `REQUIRES` | Dependency | `auth-service --REQUIRES--> PostgreSQL` | | `ENABLES` | Capability | `pgvector --ENABLES--> semantic-search` | | `PREFERS` | Preference | `user --PREFERS--> TypeScript` | | `RELATES_TO` | Co-occurrence | `PostgreSQL --RELATES_TO--> pgvector` | | `CONSTRAINT` | Limiting factor | `decision --CONSTRAINT--> "must be HIPAA compliant"` | | `TRADEOFF` | Accepted cost | `decision --TRADEOFF--> "more complex deployment"` | | `MENTIONS` | Reference | `decision --MENTIONS--> FastAPI` | | `SOLVED_BY` | Resolution | `N+1-problem --SOLVED_BY--> DataLoader` | ## Hooks That Read the Graph | Hook | Lifecycle | What It Does | |---|---|---| | `memory-context` | `prompt` | Searches graph for entities matching prompt keywords; injects search hints into Claude's context | | `memory-context-loader` | `prompt` (once) | Loads recent decisions from local JSONL on session start | ## Hooks That Write to the Graph | Hook | Lifecycle | What It Does | |---|---|---| | `memory-bridge` | `posttool` | Confirms graph writes after `mcp__memory__create_entities` calls | | `session-summary` | `stop` | Suggests graph entity capture via `additionalContext` for sessions with 20+ tool calls | | `auto-remember-continuity` | `stop` | Prompts Claude to persist session context to graph before ending | ## Agent Domain Mapping When a subagent is spawned, Claude uses the agent's domain to search for relevant graph entities. The mapping from agent type to domain keywords enables targeted graph search: | Agent | Search Keywords | |---|---| | `database-engineer` | database schema SQL PostgreSQL migration pgvector | | `backend-system-architect` | API REST architecture backend FastAPI microservice | | `frontend-ui-developer` | React frontend UI component TypeScript Tailwind | | `security-auditor` | security OWASP vulnerability audit authentication | | `workflow-architect` | LangGraph workflow agent orchestration state | | `llm-integrator` | LLM API OpenAI Anthropic embeddings RAG function-calling | This means a `database-engineer` agent automatically inherits all graph knowledge about PostgreSQL, schemas, and migrations stored in previous sessions. ## User-Facing Commands ### Storing Knowledge ```bash # The /ork:remember skill writes to graph as primary /ork:remember "Use PostgreSQL with pgvector for vector search" ``` Behind the scenes, the skill calls `mcp__memory__create_entities` and `mcp__memory__create_relations` to build the graph. It also writes to Tier 2 (local JSONL) as a backup. ### Searching Knowledge ```bash # The /ork:memory search skill queries the graph /ork:memory search "database indexing strategy" ``` This calls `mcp__memory__search_nodes` and formats results showing entity types, observations, and relations. ### Visualizing the Graph ```bash # Render as Mermaid diagram /ork:memory viz # Focus on specific entity /ork:memory viz --entity PostgreSQL --depth 2 # Filter by entity type /ork:memory viz --type Technology ``` ## MCP Server Configuration The knowledge graph MCP server is configured automatically by Claude Code. If you need to verify or troubleshoot the setup, the server configuration is: ```json { "mcpServers": { "memory": { "command": "npx", "args": ["-y", "@modelcontextprotocol/server-memory"] } } } ``` The graph MCP server stores data locally on your machine. No data is sent to external servers. The graph persists across sessions automatically; you do not need to configure storage paths or databases. ## Graph Size and Performance The graph search includes a practical threshold: if the graph contains fewer than 3 entities, searches return minimal results. As you store more decisions, the graph grows richer and the surfaced context becomes more valuable. The `memory-context` hook requires prompts to be at least 20 characters long before triggering a search. Single-word prompts or very short questions are skipped to avoid low-quality matches. ## Next Steps - [Local Persistence](/docs/memory/local-memory): how local JSONL files back up and queue graph operations - [Architecture Overview](/docs/memory/overview): see how graph memory fits into the 3-tier system - [Set Up Cross-Session Memory](/docs/cookbook/setup-memory): hands-on walkthrough ## Memory How OrchestKit persists decisions and context across sessions. [https://orchestkit.dev/docs/memory](/docs/memory) import { Card, Cards } from 'fumadocs-ui/components/card'; Three memory layers, each with a different lifetime and retrieval model. Most projects use more than one. ## Local Session Persistence How .claude/memory/ JSONL files act as optional local artifacts for OrchestKit skills, status, and compaction snapshots. [https://orchestkit.dev/docs/memory/local-memory](/docs/memory/local-memory) import { Callout } from 'fumadocs-ui/components/callout'; Local memory is Tier 2 in the public docs model: optional JSONL (JSON Lines) files under `.claude/memory/`. The directory is created when something writes to it. It is not an automatic safety net that captures every graph decision. ## The `.claude/memory/` Directory ``` .claude/memory/ decisions.jsonl # Optional log if something appends it (not auto-written) graph-queue.jsonl # Leftover artifact if present (not auto-flushed to MCP) open-problems.jsonl # Tracked open problems and blockers completed-flows.jsonl # Completed workflow records tool-preferences.json # Learned tool usage preferences ``` Each file serves a distinct purpose when present. Treat them as optional local artifacts for skills and compaction snapshots, not as an automatic write-ahead queue flushed into the graph by a hook. ## `decisions.jsonl`: The Decision Log This is the primary local backup when something appends to it. Skill scripts and tooling may write JSONL here for viz and status. There is no `memory-writer` hook that appends automatically. ### Record Structure ```json { "id": "decision-m1abc-x7y2z3", "type": "decision", "content": { "what": "Use cursor-based pagination for all list endpoints", "why": "Better performance for large datasets, stable under inserts/deletes", "alternatives": ["offset-based pagination"], "constraints": ["Must support 2M+ rows"], "tradeoffs": ["Slightly more complex client implementation"] }, "entities": ["cursor-pagination", "PostgreSQL"], "relations": [], "identity": { "user_id": "user@example.com", "anonymous_id": "anon-abc123", "machine_id": "machine-xyz" }, "metadata": { "session_id": "sess-123", "timestamp": "2026-02-06T10:30:00.000Z", "confidence": 0.85, "source": "user_prompt", "project": "orchestkit", "category": "pagination", "importance": "high", "is_generalizable": true, "sharing_scope": "global" } } ``` ### How It Gets Written No registered OrchestKit hook auto-appends to `.claude/memory/decisions.jsonl`. Writes come from skills, scripts, or agent file tools when those paths are used. Separately, some stop and compaction hooks read `.claude/logs/decisions.jsonl` (a different path under `.claude/logs/`). `lifecycle/pre-compact-saver` counts lines under `.claude/memory/*.jsonl` and snapshots recent `.claude/logs/decisions.jsonl` entries into session state before compaction. It does not append new decisions. ### How It Gets Read There is no live `memory-context-loader` hook on main. Reading happens when you run `/ork:memory` (load, history, viz, status) or when an agent opens the files directly. Claude Code still injects project `MEMORY.md` at session start for the native tier. Skill viz/history scripts may read the last lines of `.claude/memory/decisions.jsonl` when that file exists. Treat the sample below as the shape those tools format, not as automatic prompt injection: ```markdown ## Recent Project Decisions - **[Decision]** Use cursor-based pagination for all list endpoints _(because: Better performance for large datasets)_ `cursor-pagination`, `PostgreSQL` - **[Preference]** Prefer TypeScript over JavaScript for new modules - **[Decision]** JWT tokens for auth, not session cookies _(because: Stateless auth for microservices)_ `JWT`, `session-cookies` _For deeper graph traversal: use mcp__memory__search_nodes or mcp__memory__open_nodes_ ``` ## `open-problems.jsonl`: Problem Tracking This file tracks unresolved problems and blockers encountered during sessions. Entries include the problem description, related entities, and status. ## `completed-flows.jsonl`: Workflow Records Records of completed multi-step workflows, providing an audit trail of complex operations. ## `tool-preferences.json`: Learned Preferences Stores learned tool usage preferences (e.g., preferred editor, testing framework) as a JSON object rather than JSONL. ## Optional Local Artifacts Local JSONL under `.claude/memory/` is optional. Skills and scripts may create the directory and append records. Nothing on main auto-flushes `graph-queue.jsonl` into MCP memory. If a writer uses atomic line appends, a crashed process can leave at most one partial line. Consumers that parse JSONL should skip malformed lines. That is application discipline, not a live context-loader hook. ## Health Monitoring `lib/memory-health.ts` exposes `analyzeJsonlFile()` for per-file metrics (exists, line count, corrupt lines, size, mtime). The `checkMemoryHealth()` report used by status tooling currently probes only whether `.claude/memory/` exists and maps that to the graph-tier status. It does not probe MCP reachability, MEMORY.md, or queue depth. Run `/ork:memory status` for the skill-side health view. ## Synchronization Between Local and Graph There is no `memory-writer.ts` and no live `graph-queue-sync` stop hook. The primary write path is `/ork:remember` calling `mcp__memory__*` directly (validated by `memory-validator`). Local JSONL under `.claude/memory/` is an optional artifact surface, not an automatic write-ahead queue flushed by OrchestKit hooks. | Stage | Target | Timing | |---|---|---| | **`/ork:remember` (skill)** | Knowledge graph via MCP | On explicit invoke | | **Agent Edit/Write** | `MEMORY.md` or local memory files when chosen | On explicit edit | | **`pre-compact-saver`** | Session state snapshot of local + logs | On compaction | | **`session-summary`** | Graph capture *suggestion* via additionalContext | On stop (busy sessions) | If local `decisions.jsonl` exists, skill scripts can still use it for viz and status. Replaying it into the graph is a manual or skill-driven operation, not an automatic hook flush. ## File Size Management - `decisions.jsonl` can grow unbounded; readers that only need recent entries should read from the tail - `graph-queue.jsonl`, if present, is a leftover artifact. No live hook on main clears or flushes it ## Next Steps - [Graph Memory](/docs/memory/graph-memory): the primary tier for typed entities and relations - [Architecture Overview](/docs/memory/overview): the full 3-tier system ## Auto-Sync to MEMORY.md How OrchestKit auto-promotes high-confidence decisions to Claude Code's native MEMORY.md, ensuring they survive plugin removal. [https://orchestkit.dev/docs/memory/native-cc-memory](/docs/memory/native-cc-memory) import { Callout } from 'fumadocs-ui/components/callout'; CC Native memory is Tier 3, the **survivability layer**. Claude Code maintains a file at `~/.claude/projects//memory/MEMORY.md` that it automatically injects into the system prompt for every session. OrchestKit writes high-confidence decisions to this file, ensuring they persist even if the plugin is removed, reinstalled, or upgraded. ## How Claude Code Native Memory Works Claude Code has its own built-in memory system, independent of any plugins: 1. It maintains a directory at `~/.claude/projects/` with one subdirectory per project 2. The project subdirectory is named using the absolute path with separators replaced by dashes (e.g., `/Users/alice/my-app` becomes `-Users-alice-my-app`) 3. Inside each project directory, `memory/MEMORY.md` contains the persistent memory 4. Claude Code injects the entire contents of this file into the system prompt at the start of every session This means anything written to MEMORY.md is visible to Claude in every conversation, without any plugin or tool call needed. The file is plain Markdown. ## Auto-Promotion: Graph to MEMORY.md OrchestKit bridges its own memory system to CC Native through **auto-promotion**: high-signal decisions captured during a session get persisted into `MEMORY.md`, where Claude Code injects them into every future session. Promotion is performed by Claude itself, prompted by OrchestKit's session hooks (`session-summary`, `auto-remember-continuity`): at session end, Claude reviews what was decided and writes durable, high-confidence decisions to MEMORY.md. Low-signal material (patterns inferred from tool output, transient observations) stays in the session-local JSONL files instead. This keeps MEMORY.md focused and concise. ## What Gets Written Each promoted decision is formatted as a concise Markdown list item: ```markdown ## Recent Project Decisions - **[Decision]** Use cursor-based pagination for all list endpoints _(because: Better performance for large datasets, stable under inserts/deletes)_ `cursor-pagination`, `PostgreSQL` - **[Preference]** Prefer TypeScript over JavaScript for new modules - **[Pattern]** All React components export default function; named exports for utilities only `React`, `TypeScript` - **[Decision]** JWT tokens for auth, not session cookies _(because: Stateless auth required for microservices architecture)_ `JWT`, `session-cookies` ``` Each entry includes: - **Type label** in bold: `[Decision]`, `[Preference]`, `[Pattern]`, or `[Note]` - **The decision text**: the "what" - **Rationale** in italics (if provided): the "why" - **Entity tags** as inline code: technologies and patterns mentioned ## Deduplication Before adding an entry, existing MEMORY.md content is checked for the same decision so it is not recorded twice, even when multiple hooks capture it in the same session. ## Ordering: Most Recent First New decisions are inserted immediately after the `## Recent Project Decisions` header, pushing older entries down. This ensures Claude sees the most relevant, most recent decisions first in its system prompt. ## Size Limits MEMORY.md is injected into the system prompt in its entirety. To prevent it from consuming too much of Claude's context window, the memory writer enforces a soft limit of **50 entries**. When the 51st entry is added: 1. The oldest entry is removed 2. A marker is added: `_...older decisions archived..._` Archived decisions are not lost; they still exist in Tier 1 (Graph) and Tier 2 (Local JSONL). The limit only applies to what gets injected into every system prompt. ## File Location The path is constructed from the project directory: ``` Project: /Users/alice/coding/my-app Path: /Users/alice/.claude/projects/-Users-alice-coding-my-app/memory/MEMORY.md ``` On Windows, both `/` and `\` separators are replaced with `-`: ``` Project: C:\Users\alice\my-app Path: C:\Users\alice\.claude\projects\-C-Users-alice-my-app\memory\MEMORY.md ``` The memory writer creates the `memory/` subdirectory if it does not exist, but only if the parent project directory already exists (indicating Claude Code has been used with this project). ## Manual Editing You can edit MEMORY.md directly. It is a plain Markdown file. Any changes you make will be injected into Claude's system prompt in the next session. Common reasons to edit manually: - Remove outdated decisions that no longer apply - Reword a decision for clarity - Add context that hooks did not capture - Reorganize entries by topic If you edit MEMORY.md while a Claude Code session is active, the changes take effect in the next session, not the current one. The file is read at session start. ## Manual Storage via `/ork:remember` The `/ork:remember` skill also writes to MEMORY.md for high-confidence decisions. When you run: ```bash /ork:remember "Always validate user input at API boundaries" ``` The skill captures this as a high-confidence decision (explicit user statement with clear intent, typically scoring 0.8+). Since 0.8 >= 0.7, it is auto-promoted to MEMORY.md. For decisions that should always reach MEMORY.md regardless of confidence scoring, you can write directly: ```bash /ork:remember --success "Circuit breaker pattern with 5s timeout for external API calls" ``` The `--success` flag adds a positive outcome signal that increases confidence scoring. ## The Survivability Guarantee The core design principle behind Tier 3: ``` OrchestKit installed --> All 3 tiers active, decisions flow everywhere OrchestKit removed --> Tier 3 still works, MEMORY.md still injected Different plugin version --> Tier 3 still works, previous decisions visible New machine, same repo --> Tier 3 works if ~/.claude/ is synced/backed up ``` This means your most important decisions, the ones that cleared the 0.7 confidence threshold, are not locked into OrchestKit. They are plain text in a file that Claude Code itself manages. Even if you stop using OrchestKit entirely, Claude remembers what matters. ## Relationship to Other Tiers | Scenario | Tier 1 (Graph) | Tier 2 (Local) | Tier 3 (CC Native) | |---|---|---|---| | Low-confidence observation | Stored | Stored | **Skipped** | | Medium-confidence decision (0.5) | Stored | Stored | **Skipped** | | High-confidence decision (0.7+) | Stored | Stored | **Written** | | Very high confidence, generalizable (0.8+) | Stored | Stored | **Written** | Tier 3 is the most selective tier. It serves as a curated summary of your most important project decisions, automatically maintained by the confidence threshold. ## Hooks Involved | Hook | Role | |---|---| | `memory-writer.ts` (library) | Evaluates confidence, formats decision, writes to MEMORY.md | | `session-summary` (stop hook) | Suggests graph entity capture via `additionalContext` at session end | | `auto-remember-continuity` (stop hook) | Prompts Claude to persist critical session context before exit | ## Troubleshooting ### Decisions Not Appearing in MEMORY.md 1. **Check confidence.** Only decisions with confidence >= 0.7 are promoted. Implicit or inferred patterns score lower. 2. **Check project directory.** The parent directory `~/.claude/projects//` must exist. Claude Code creates it on first use. 3. **Check for duplicates.** If the first 50 characters of the decision already appear in MEMORY.md, the write is skipped. ### MEMORY.md Growing Too Large The 50-entry limit prevents runaway growth. If you still find the file too large, you can: - Edit it manually to remove obsolete entries - The most important entries are at the top (most recent first) - Older entries below the limit are archived automatically ### Entries From a Different Project Verify the project path mapping. The directory name conversion replaces all path separators with dashes. If two projects map to the same path ID, they share a MEMORY.md. This is uncommon but possible with symbolic links or unusual directory structures. ## Next Steps - [Architecture Overview](/docs/memory/overview): see how Tier 3 fits into the full system - [Graph Memory](/docs/memory/graph-memory): the primary tier that feeds auto-promotion - [Set Up Cross-Session Memory](/docs/cookbook/setup-memory): end-to-end cookbook ## 3-Tier Memory Architecture OrchestKit stores your decisions once and brings them back in later Claude Code sessions. See the three memory tiers, the confidence rule and the hooks. [https://orchestkit.dev/docs/memory/overview](/docs/memory/overview) import { Callout } from 'fumadocs-ui/components/callout'; OrchestKit maintains a **3-tier memory architecture** that stores decisions once and surfaces them automatically in every future session. Each tier serves a distinct purpose, and the system degrades gracefully: if a tier is unavailable, the tiers above it continue operating without interruption. ## Architecture at a Glance | Tier | Name | Storage | Config Required | Purpose | |------|------|---------|-----------------|---------| | **1** | [Graph Memory](/docs/memory/graph-memory) | MCP `mcp__memory__*` | None | Primary. Entities with typed relations. Always available. | | **2** | [Local Persistence](/docs/memory/local-memory) | `.claude/memory/*.jsonl` | None | Session backup, offline queues, durability. | | **3** | [CC Native](/docs/memory/native-cc-memory) | `~/.claude/projects/*/memory/MEMORY.md` | None | Injected into Claude's system prompt. Survives plugin removal. | All 3 tiers require zero configuration. They work the moment you install OrchestKit. Tier 2 creates its directory automatically. ## How Decisions Flow Across Tiers When you store a decision, whether explicitly via `/ork:remember` or implicitly through the capture hooks, the memory writer routes it to all configured backends simultaneously. | Tier | Backend | What Gets Stored | |---|---|---| | **1. Graph Memory** | `mcp__memory__create_entities` + `create_relations` | Entities: `cursor-pagination` (Pattern), `list-endpoints` (Component). Relation: `project -> CHOSE -> cursor-pagination` | | **2. Local Persistence** | `.claude/memory/decisions.jsonl` + `graph-queue.jsonl` | Appends decision record, queues graph operations | | **3. CC Native** (confidence >= 0.7) | `~/.claude/projects//memory/MEMORY.md` | Claude auto-injects this into every future system prompt | ### The Confidence Threshold Not every decision reaches Tier 3. Only decisions with a **confidence score of 0.7 or higher** are promoted to CC Native MEMORY.md. This keeps Claude's system prompt concise and focused on high-signal decisions. The confidence score is calculated from: - Explicit user statements ("we decided...", "always use...") score higher - Decisions with rationale ("because...") score higher than bare facts - Preferences stated directly by the user score higher than inferred patterns Lower-confidence observations still persist in Tier 1 (Graph) and Tier 2 (Local), where they are available through explicit search. ## The Read Path When Claude processes your prompt, multiple hooks activate to surface relevant memory. ### On Every Prompt The **memory-context** hook (`prompt` lifecycle) fires on every prompt submission. It: 1. Scans your prompt for trigger keywords (`implement`, `create`, `refactor`, `previous`, `decision`, `pattern`, etc.) 2. Extracts meaningful search terms by removing stopwords 3. Injects a system message telling Claude to search the knowledge graph with those terms 4. If the prompt contains relationship keywords (`related`, `connected`, `depends on`), adds graph traversal hints This is why Claude "remembers" your past decisions without you asking. The hook silently provides relevant context before Claude generates a response. ### On First Prompt of a Session The **memory-context-loader** hook (`prompt` lifecycle, `once: true`) fires exactly once per session. It: 1. Reads the last 10 decisions from `.claude/memory/decisions.jsonl` 2. Formats them as a markdown context block with type labels, rationale, and entity tags 3. Injects them into Claude's context as "Recent Project Decisions" 4. Caps output at 3000 characters to stay within budget This ensures Claude always starts a session with your most recent decisions loaded, even before you type a prompt related to them. ### On Agent Spawn When a subagent is created, it inherits memory context from the parent session. The agent's domain keywords (e.g., PostgreSQL, schema, migration for `database-engineer`) are used by Claude to search the knowledge graph via `mcp__memory__search_nodes` for relevant entities. ## The Write Path Decisions enter the system through multiple channels. ### Explicit Storage ```bash # Basic decision /ork:remember "Use JWT tokens for auth, not session cookies" # Successful pattern /ork:remember --success "Cursor-based pagination scales for 2M+ rows" # Anti-pattern /ork:remember --failed "Offset pagination caused timeouts at 1M rows" # Cross-project best practice /ork:remember --global "Always validate input at API boundaries" ``` ### Automatic Capture OrchestKit captures decisions automatically through hooks: | Hook | Lifecycle | What It Captures | |------|-----------|-----------------| | `session-summary` | `stop` | Suggests graph entity capture via `additionalContext` for high-activity sessions (20+ tool calls) | | `memory-bridge` | `posttool` | Entities created via graph MCP calls (confirms primary storage) | | `auto-remember-continuity` | `stop` | Session context preservation before session end | ### Entity and Relation Extraction The memory writer automatically extracts structured data from natural language: | Input Pattern | Extracted Entity Type | |---|---| | Capitalized terms (PostgreSQL, React) | Technology | | Agent names (database-engineer) | Agent | | Pattern names (cursor-pagination) | Pattern | | "decided to...", "chose..." | Decision | | Failed patterns (`--failed` flag) | AntiPattern | | Input Pattern | Extracted Relation | |---|---| | "X uses Y" | `USES` | | "chose X over Y" | `CHOSE_OVER` | | "X requires Y" | `REQUIRES` | | "X enables Y" | `ENABLES` | | "X prefers Y" | `PREFERS` | ## Memory Fabric: Unified Search The **Memory Fabric** layer sits above individual tiers and provides unified search with cross-referencing. When you run `/ork:memory search "pagination"`, the fabric: 1. **Parses** the query into search terms and entity hints 2. **Dispatches** queries to the knowledge graph 3. **Normalizes** results to a common format with source, relevance score, and entities 4. **Deduplicates** results with greater than 85% text similarity, keeping the higher-relevance copy 5. **Ranks** by: `recency (0.3) x relevance (0.5) x source_authority (0.2)` ## Memory Health Check the health of all tiers at any time: ```bash /ork:memory status ``` The health check validates: - **Graph tier**: `.claude/memory/` exists, `decisions.jsonl` is parseable, queue depth is below threshold - **Local tier**: JSONL files are parseable, queue depths are below threshold - **CC Native tier**: MEMORY.md exists and is readable Possible statuses: `healthy`, `degraded` (corrupt lines or high queue depth), `unavailable` (missing directory or API key). ## Sharing Scopes Decisions are scoped to control where they are visible: | Scope | User ID Format | Visibility | |---|---|---| | `local` | Current session only | Not persisted beyond session | | `user` | User-scoped ID | Personal across sessions | | `team` | `{project}-decisions` | Shared within project | | `global` | `orchestkit-global-best-practices` | Cross-project, anonymized | Decisions with confidence >= 0.8, a rationale, and a well-known technology or pattern keyword are automatically marked as generalizable and eligible for global sharing. ## Graceful Degradation The system is designed to function at every level of configuration: | Configuration | Available Tiers | Behavior | |---|---|---| | OrchestKit installed (default) | 1, 2, 3 | Full local memory, graph storage, CC Native auto-sync | | OrchestKit removed | 3 only | CC Native MEMORY.md still injected by Claude. High-confidence decisions survive. | | Fresh machine, no plugins | None | Start fresh. Install OrchestKit to begin building memory. | The most important design decision in the memory architecture: high-confidence decisions are written to CC Native MEMORY.md (Tier 3), which is a plain Markdown file managed by Claude Code itself. This means your critical decisions persist even if you uninstall OrchestKit, switch machines, or change plugin versions. ## Next Steps - [Graph Memory](/docs/memory/graph-memory): how the primary knowledge graph works - [Local Persistence](/docs/memory/local-memory): JSONL queues and session backup - [CC Native Memory](/docs/memory/native-cc-memory): auto-promotion to MEMORY.md - [Set Up Cross-Session Memory](/docs/cookbook/setup-memory): hands-on cookbook ## Analytics Dashboard Visualize your Claude Code usage: model delegation, token costs, agent performance, and session trends. [https://orchestkit.dev/docs/analytics](/docs/analytics) import { LazyAnalyticsDashboard as AnalyticsDashboard } from '@/components/lazy'; The analytics dashboard shows your Claude Code usage across sessions. It tracks model delegation (which models handle which tasks), daily token costs, agent and skill usage rankings, and session trends over time. Data is collected locally by OrchestKit's PostToolUse analytics hooks and stored in your project directory. Nothing is sent externally. ## AskUserQuestion picker fallback (ORK_ASK_FALLBACK=text) Text-prompt fallback for when the Claude Code AskUserQuestion picker stalls or otherwise refuses keystrokes. [https://orchestkit.dev/docs/guides/ask-fallback](/docs/guides/ask-fallback) # AskUserQuestion picker fallback ## When to use this Claude Code's `AskUserQuestion` picker can occasionally render fully but refuse to accept keystrokes: Enter / arrow keys do nothing, only `Esc` dismisses the picker. The skill that called the picker then sees `User declined to answer questions` and aborts. This was observed in CC 2.1.139 (see [orchestkit#1795](https://github.com/yonatangross/orchestkit/issues/1795)). Suspected upstream input-handling regression; reproduction is intermittent and not yet fully characterised. OrchestKit ships a mitigation: a `UserPromptSubmit` hook (`prompt/ask-fallback-injector`) that, when the `ORK_ASK_FALLBACK=text` environment variable is set, injects a system reminder telling the assistant to use inline numbered text prompts instead of calling `AskUserQuestion`. ## How to enable Set the env var before starting Claude Code: ```bash export ORK_ASK_FALLBACK=text claude ``` Or for a single session: ```bash ORK_ASK_FALLBACK=text claude ``` The hook checks this variable on every `UserPromptSubmit`. While set, every skill that would otherwise open a picker (33 skills today: `brainstorm`, `fix-issue`, `create-pr`, `assess`, `verify`, etc.) emits a numbered list inline and asks the user to reply with the option number. ## Example interaction Without fallback (picker mode): ``` ┌─ Which auth strategy? ─────────────────────────┐ │ ▸ JWT (stateless, no revoke) │ │ Session cookies (server-side store) │ │ OAuth-only (delegate to provider) │ └────────────────────────────────────────────────┘ Enter to select · ↑/↓ to navigate · Esc to cancel ``` With fallback (`ORK_ASK_FALLBACK=text`): ``` > Which auth strategy? > 1. JWT (stateless, no revoke) > 2. Session cookies (server-side store) > 3. OAuth-only (delegate to provider) > Reply with 1, 2, or 3. ``` ## How to disable Unset the variable and restart CC: ```bash unset ORK_ASK_FALLBACK claude ``` Restart restores picker mode. Recommended once an upstream CC fix ships. ## Implementation - **Hook:** `src/hooks/src/prompt/ask-fallback-injector.ts` - **Event:** `UserPromptSubmit` - **Cost:** one env-var read per prompt, ~80-byte reminder when active, no I/O - **Tests:** `src/hooks/src/__tests__/ask-fallback-injector.test.ts` - **Scope:** global, applies to all 33 skills using `AskUserQuestion` without per-skill edits ## Related - [orchestkit#1795](https://github.com/yonatangross/orchestkit/issues/1795): original bug report - M119 (Usage hygiene) milestone: UX behavioural mitigations - `ORK_GOAL_MAX_TURNS_PER_SESSION` / `ORK_GOAL_MAX_TOKENS_PER_SESSION`: sibling env-var-based behavioural controls (M140) ## How we adopt every Claude Code release The automated pipeline that turns each upstream Claude Code release into scored adoption issues, a support-floor bump, and an interactive wave dashboard. [https://orchestkit.dev/docs/guides/cc-adoption](/docs/guides/cc-adoption) import { LazyCcAdoptionBoard, LazyLabEmbed } from "@/components/lazy"; Claude Code ships several releases a week. OrchestKit (100+ skills, 36 agents, and a hook runtime that sits directly on CC's contracts) silently breaks if it falls behind. Reading changelogs manually is not a process, so the repo runs an automated adoption loop instead. In one July 2026 week, that loop turned three releases (2.1.210 → 2.1.212) into **37 auto-filed, scored adoption issues**. Zero were written by hand. ## The loop ``` detect → extract → verify → file → adopt → subtract ``` 1. **Detect.** A daily workflow polls the upstream Claude Code changelog and snapshots every new version into the repo. If the newest known version starts lagging the upstream head, a staleness alarm files an issue by itself. 2. **Extract.** An LLM triage (Opus) reads each snapshot like a reviewer: every bullet becomes a structured feature record with a category (`breaking`, `new_command`, `new_field`), a 0-20 **gap score**, and the list of OrchestKit skills it touches. 3. **Verify.** A token-free relevance gate then corrects the LLM in both directions: end-user-only noise is downgraded below the filing floor (never dropped; a drop would be invisible), and items that map to an existing skill get recall-boosted. Genuinely ambiguous releases fall back to a manual adversarial-refute pass. 4. **File.** Every feature above the floor becomes its own GitHub issue under a single rolling "CC adoption" milestone, deduplicated by body marker across reruns. 5. **Adopt.** A human (or an implementation session) picks up issues and ships PRs, which is deliberately the one manual step, because adoption is judgment. 6. **Subtract.** Every release also asks: *what can we now delete?* When CC ships a native mechanism, the corresponding OrchestKit shim is removed rather than kept. The support window closes the loop: once a version's compatibility entry lands, a workflow bumps the supported floor automatically and propagates it into the docs, the version matrix, and the doctor. The mechanics live in the repo and stay authoritative there; see [`docs/cc-release-integration-sop.md`](https://github.com/yonatangross/orchestkit/blob/main/docs/cc-release-integration-sop.md) for the stage-by-stage index. This page tells the story; the SOP owns the details. ## The board: current wave, real data ## What a wave looks like Each wave also renders an interactive explorer: the triage surface for deciding what to adopt first. This is the real dashboard for the 2.1.210-212 wave: More artifacts like this live in [The Lab](/docs/showcase/lab). ## Why this is worth copying If your product sits on a platform that ships daily (Claude Code, Cursor, a cloud SDK), you have a dependency nobody pins. The pattern here is portable: snapshot the changelog, make an LLM produce *structured, scored* records (not summaries), gate them with cheap deterministic checks, and let issues + a dashboard carry the memory. The pipeline cost one weekend. Falling one version behind used to cost more. ## Claude Fable 5 with OrchestKit How OrchestKit supports Claude Fable 5: correct pricing, a spend-consent gate for agent pins, advisor warnings, and the deliberate opt-in path (ORK_FABLE_OK). [https://orchestkit.dev/docs/guides/claude-fable-5](/docs/guides/claude-fable-5) # Claude Fable 5 with OrchestKit Claude Fable 5 (`claude-fable-5`, released 2026-06-09) is Anthropic's Mythos-class frontier model: state-of-the-art on coding, vision, and knowledge work, with week-long autonomous-run capability and a 1M-context variant (`claude-fable-5[1m]`). It bills at **$10 input / $50 output per MTok** (2x Opus 4.8 output pricing), and in under 5% of sessions a safety classifier transparently falls back to Opus 5 (cyber/bio topics; you are informed when it happens). OrchestKit supports Fable 5 fully, while treating it as a **deliberate spend decision** rather than a default. > **Dated note (availability changes as capacity scales; verify current plan terms):** As announced 2026-07-18, beginning **July 20, 2026** Fable 5 is included in all **Max** and **Team Premium** plans at **50% of limits**. **Pro** and **Team Standard** users keep Fable access via usage credits and receive a one-time **$100 credit**. Anthropic has extended and reshaped access several times while securing capacity, so treat any specific inclusion/limit as point-in-time. Everything below is evergreen. ## What OrchestKit does for you | Surface | Behavior | |---------|----------| | Pricing | `claude-fable-5` (+ `fable` alias and the `[1m]` variant) is priced correctly in cost estimation; previously unknown models silently fell back to sonnet pricing, underbilling by ~70% | | Model vocabulary | One source of truth (`src/hooks/src/lib/models.vocab.json`) feeds agent-frontmatter validation, docs generation, the skill content lint, and pricing; `model: fable` is a first-class, CI-validated value | | Spend consent | Spawning an agent **pinned** to fable triggers a permission prompt with the cost spelled out: approve per-spawn, or pre-consent with `ORK_FABLE_OK=1` | | Cost advice | An agent that merely *inherits* fable from your session gets a downgrade warning when its task is low/medium complexity (~70%/60% savings vs. sonnet, derived from real pricing) | | Tier rules | `fable` joins `opus` as a premium tier: CI reserves it for high-complexity agents (security/safety/system-design/event-driven/workflow) | ## Choosing where Fable 5 runs There are three distinct decisions, and OrchestKit treats them differently: 1. **Your session model** (`/model`): entirely yours; OrchestKit never interferes. `inherit` agents follow it. 2. **An agent pinned to fable** (`model: fable` in a spawn or agent frontmatter): this commits future runs to frontier pricing, so the spend-consent gate asks first. 3. **Pre-consented automation**: set `ORK_FABLE_OK=1` in the environment (or CI) when you have deliberately decided a workload is worth frontier pricing. ```bash # One-off: approve the permission prompt when it appears. # Session/CI-wide pre-consent: export ORK_FABLE_OK=1 ``` The cost-neutral default for agent fleets is `model: inherit`. Quality follows whatever you chose for the session (including fable when *you* chose it), prompt-cache forking keeps working, and nothing is silently committed to frontier pricing. ## Fallback behavior to know about Fable 5's safety classifiers fall back to Opus 5 in a small fraction of sessions, most likely on cyber/bio-adjacent content. For security-audit workloads this means a fable-pinned auditor could silently switch models mid-run, which is one reason OrchestKit keeps its own security agents on an explicit `opus` pin rather than fable. ## Requirements - Claude Code **2.1.220+** (OrchestKit's support floor); Fable 5 access shipped in CC 2.1.170. - No OrchestKit configuration is needed for any of the above; it ships in the `ork` plugin. ## Guides Longer-form walkthroughs for specific stacks and adoption topics. [https://orchestkit.dev/docs/guides](/docs/guides) import { Card, Cards } from 'fumadocs-ui/components/card'; Task-shaped guides that go deeper than a reference page. ## OrchestKit on pi, Codex and Cursor What each engine loads from an OrchestKit install, what it cannot load, the exact config per engine, and the sweep, mech and reason lane model. Measured on pi 0.85, Codex CLI and cursor-agent, September 2026. [https://orchestkit.dev/docs/guides/orchestkit-on-pi-codex-cursor](/docs/guides/orchestkit-on-pi-codex-cursor) import { Count } from '@/components/count'; # OrchestKit on pi, Codex and Cursor OrchestKit is built for Claude Code. Three other engines can load parts of it, and the parts differ per engine. This page is measured, not aspirational: every claim was checked against pi 0.85.0, codex-cli 0.153.4 and cursor-agent 2026.09.02 on 2026-09-08. The full audit, with the commands and their output, is in the repo at [`docs/audits/multi-engine-support-2026-09-08.md`](https://github.com/yonatangross/orchestkit/blob/main/docs/audits/multi-engine-support-2026-09-08.md). The generic-versus-native cut (what must run everywhere SKILL.md loads, versus what stays a native adapter file) is the Lab page [Generic floor, native adapter per harness](https://orchestkit.yonyon.ai/lab/generic-harness-matrix.html). Dual manifests stay: Agent Plugins `plugin.json` (closed schema), `.claude-plugin/plugin.json`, and `.cursor-plugin/plugin.json`. Do not move `agents/` or `hooks/` into a `com.*` folder unless a Claude Code version actually loads that directory. ## Support matrix | Surface | Claude Code | Cursor | Codex | pi | |---|---|---|---|---| | Skills (SKILL.md) | | via the `ork` plugin | 6, the `ork-codex` pack | 107 loaded, 78 auto-listed, via `--skill` or `.agents/skills` | | Agents | | | 4 role templates, installed by script | none | | Slash commands | `/ork:` | 36 generated command wrappers | `$ork-` | `/skill:` | | Hooks | | none (Cursor has its own `hooks.json`) | none (Codex has its own hooks) | none (pi has extensions) | | Rules | repo convention, not a plugin key | 14, `.cursor-plugin/rules/` | `AGENTS.md` | none | | MCP config | `.mcp.json` | `.cursor/mcp.json` | plugin `mcp.json` (context7 shipped) | `.pi/mcp.json` and `.mcp.json` | | Install status | shipped | shipped (#3748) | shipped (#3265), mech profile (#4002) | shipped (#4001) | The SKILL.md format is the cross-engine contract. Codex, Cursor and pi all read the [Agent Skills](https://agentskills.io) shape, so a skill body written for Claude Code loads everywhere. Hooks are Claude Code only. MCP configuration is a different file on every engine. ## What works and what does not **Works on every engine**: the skill body. Same-skill references are bare relative paths since #3940, and all four engines resolve those against the SKILL.md directory. **Does not port**: hooks (they need `${CLAUDE_PLUGIN_ROOT}` and the Claude Code event payload) and agents (only Claude Code and Cursor read the `agents` manifest key). Workflow skill bodies now use portable `../skill/` and `../../shared/` paths; YAML hook `command:` lines stay Claude-only. Cursor export still strips leftover plugin-root forms at generation time (#3941). **Hidden on pi by design**: 29 of the 107 skills carry `disable-model-invocation: true`. pi honours that flag, so those skills never appear in the model's auto-list and are reachable only as `/skill:`. The remaining 78 cost about 11k tokens of catalog before any body is read. ## pi Shipped since #4001. The package installs directly: ```bash pi install git:github.com/yonatangross/orchestkit ``` Add `-l` to write the source into the project's `.pi/settings.json` instead of your user settings. Pointing pi at a checkout still works and needs no install (`pi --skill ./plugins/ork/skills`), and the same directory can be symlinked into `.agents/skills` (project) or `~/.agents/skills` (user). What makes the install work is five lines in the root `package.json`. pi resolves a git or local package through the `pi` key, and falls back to `skills/`, `extensions/`, `prompts/` and `themes/` at the package root only when that key is absent. OrchestKit's skills live in `plugins/ork/skills`, which matches neither default, so before #4001 an install registered zero resources and raised no error: ```json "pi": { "skills": [ "./plugins/ork/skills", "-plugins/ork/skills/CONTRIBUTING-SKILLS.md" ] } ``` The second entry is a force-exclude. Without it pi registers 108 resources for 107 skills: `collectSkillEntries` takes every markdown child of the entry directory, and the extra file parses to nothing, so it would sit in `pi list` as a resource that is not a skill. `tests/plugins/test-pi-plugin.sh` gates this. When pi is installed it runs pi's own `collectPackageResources` and `loadSkillsFromDir` against the tree and asserts the count matches the repo's SKILL.md set with zero diagnostics; in CI, where pi is absent, it re-derives the same resolution from pi's documented rules and says which arm ran. Measured: **`--no-builtin-tools` hides every skill.** pi appends the skills block only when a tool that can read files is enabled. With built-in tools off the model reported `SKILLS=0` at 1.6k input tokens; with them on it reported 139 skills at 21.7k. This matters for the sweep lane below, and no manifest changes it. MCP on pi comes from `pi-mcp-adapter`, which reads `.pi/mcp.json`, then `.mcp.json`, then `~/.config/mcp/mcp.json`. It does not discover other hosts' configs. OrchestKit ships no `.mcp.json`, so copy the template: ```bash cp .pi/mcp.json.example .pi/mcp.json ``` It defines context7, memory, sequential-thinking and tavily, each with a read-only `includeTools` allowlist. That allowlist is fail-closed and applied at metadata-build time, so an excluded tool never enters the tool map and is not reachable through the mcp proxy either. It is a convenience filter and not a security perimeter: pi ships a `bash` tool and inherits the environment that started it, so a session can reach an endpoint directly. What it buys is that a cheap model following instructions cannot hit a mutating tool by accident. One shape difference worth pinning: pi's `ServerEntry` has no `type` field. stdio is `command` plus `args`, HTTP is `url`. A Claude Code entry pasted verbatim carries `"type": "http"`, which pi ignores. Two headless contracts, both load-bearing: `pi -p` blocks forever on an open stdin, so close it with `` in confined shells. ## Codex Shipped as a separate, thin plugin so Claude-only commands and hooks never reach Codex. ```bash codex plugin marketplace add yonatangross/orchestkit --ref main --sparse .agents/plugins --sparse plugins/ork-codex codex plugin add ork-codex@orchestkit-codex # optional roles, loaded from ~/.codex/agents, not from the plugin plugins/ork-codex/scripts/install-codex-roles.sh ~/.codex/agents export CONTEXT7_API_KEY_CODEX="" ``` What loads: six workflow skills (`$ork-brainstorm`, `$ork-explore`, `$ork-implement`, `$ork-assess`, `$ork-verify`, `$ork-review-pr`), one MCP server (context7 over HTTP, key by environment variable, never written to `config.toml`), and four role templates if you ran the script. Codex also reads project `.agents/skills`, `~/.agents/skills` and `AGENTS.md`, so a checkout of this repo already contributes its `AGENTS.md`. ### The `ork-mech` profile Shipped since #4002, for unattended mechanical work: ```bash plugins/ork-codex/scripts/install-codex-profile.sh ~/.codex codex exec --profile ork-mech "" ` layers `$CODEX_HOME/.config.toml` over the base user config. A legacy `[profiles.]` table inside `config.toml` turns the same flag into a hard config-load error, quoting the file it wants instead. The installer refuses both that collision and an overwrite. The profile sets approval `never`, `workspace-write` with network on, and high reasoning effort. `codex exec` prints the resolved shape in its header, which is how each line below was measured rather than assumed: ``` approval: never sandbox: workspace-write [workdir, /tmp, $TMPDIR] (network access enabled) reasoning effort: high ``` It pins no model (pass `-m`) and never reaches for `--dangerously-bypass-approvals-and-sandbox`, which drops the sandbox rather than widening it. A mech worker doing a rename does not need that. Two contracts live on the command line because a TOML file cannot carry them: | Contract | Why | |---|---| | ` skills, agents, command wrappers generated from the user-invocable skills into `.cursor-plugin/commands/`, and 14 rules under `.cursor-plugin/rules/`. Cursor also reads `.cursor/skills`, `.cursor/rules`, `.cursorrules` and `AGENTS.md` from the project, so a repo can add its own on top. ### Rules Re-deriving Cursor's discovery over the built plugin, using the loader rules read out of the shipped `cursor-agent` bundle (manifest keys, the `[".md", ".mdc", ".markdown"]` extension list, the frontmatter router): ``` manifest keys: agents, author, commands, description, homepage, keywords, license, name, repository, rules, skills, version skills 107 agents 36 commands 36 rules 14 routing: {'agentFetched': 14} ``` That is a re-derivation, not a live install. Every route to a live install writes state outside the repo (`cursor-agent plugin marketplace add` writes to your Cursor account, `--plugin-dir` needs an authenticated model turn), so it is named here rather than claimed. The cheapest live check is one command: ```bash cursor-agent --plugin-dir plugins/ork --mode ask -p 'list the plugin rules and commands you can see' ``` `rules` is a first-class key in Cursor's plugin manifest, alongside `skills`, `agents`, `commands` and `hooks`. Claude Code has no equivalent (its rules are a repo convention, not a plugin surface), so this key exists only in `.cursor-plugin/plugin.json`: ```json "rules": "./.cursor-plugin/rules/" ``` The build generates one `.mdc` per rule from `src/rules/` (host-neutral engineering rules) and `src/shared/rules/` (the rules the skill bodies cite by name: the verification gate, anti-sycophancy, adversarial refutation, evidence replay, the chart and playground standards). Each carries `name`, `description` and `alwaysApply: false`, which is Cursor's **agent-fetched** class: the rule is pulled in when its description matches the task and costs nothing until then. Pinning 14 rules globally would be a context tax nobody asked for. `.claude/rules/` is deliberately not exported. Those rules are scoped by `paths:` to this repository's own tree (`src/hooks/**`, `tests/**`, the manifests) and tell an agent how to build OrchestKit; a downstream Cursor user has no such tree, so shipping them would inject instructions about a codebase that is not theirs. ### Wrapper paths Fixed in #3941. A command wrapper lives in `.cursor-plugin/commands/`, one directory away from the skill whose body it carries, so a same-skill reference could not resolve from there in either form it has ever had: `${CLAUDE_PLUGIN_ROOT}/skills//references/x.md` is a Claude Code contract Cursor never substitutes, and bare `references/x.md` resolves against the SKILL.md directory, which the wrapper is not in. The build now rewrites both to plugin-relative paths at generation time: | in the skill body | in the Cursor wrapper | |---|---| | `${CLAUDE_PLUGIN_ROOT}/shared/rules/x.md` | `shared/rules/x.md` | | `${CLAUDE_SKILL_DIR}/scripts/x.py` | `skills//scripts/x.py` | | `references/x.md` | `skills//references/x.md` | A bare reference is rewritten only when the file really exists under that skill, so prose about OrchestKit's own `scripts/build-plugins.sh` is left alone and the rewrite cannot invent a target. `tests/plugins/test-cursor-paths.sh` gates all three shapes plus the reverse check that every rewritten path resolves to a real file in the plugin. Cursor's hooks live in `.cursor/hooks.json` (`version: 1`, camelCase events such as `sessionStart`). Enforcement for a project stays in that project's file; nothing ships from OrchestKit. ## The sweep, mech and reason lane model When several engines are available, route by class of work, not by preference. | Class | What it is | Engine and guard | Sees OrchestKit skills? | |---|---|---|---| | **sweep** | read-only: lint names, dry runs, verification, collector fan-outs | pi on a cheap model with `--no-builtin-tools`, MCP reads only | **no**, measured above | | **mech** | mechanical writes: renames, bumps, codemods, sweeps with a diff | pi with `--approve`, Codex `--profile ork-mech` (approval never, workspace-write sandbox, network on), or cursor-agent `--force --sandbox enabled` | yes | | **reason** | judgement: design, review, debugging, anything that needs hooks | Claude Code, attended | yes, plus hooks and agents | Two consequences. A sweep cannot use OrchestKit until its guard changes from "no tools" to "a read-only tool set", which is one of the epic's items. And a mech lane on Codex or Cursor gets skills but no hooks, so the quality gates that hooks enforce in Claude Code have to come from the engine's own sandbox and from CI. ## Tracking Epic [#4005](https://github.com/yonatangross/orchestkit/issues/4005) on the [Multi-engine support milestone](https://github.com/yonatangross/orchestkit/milestone/170), with one issue per adapter: pi manifest and MCP allowlist template ([#4001](https://github.com/yonatangross/orchestkit/issues/4001)), Codex profile ([#4002](https://github.com/yonatangross/orchestkit/issues/4002)), Cursor rules export ([#4003](https://github.com/yonatangross/orchestkit/issues/4003)), hooks fallback ([#4004](https://github.com/yonatangross/orchestkit/issues/4004)). ## Using OrchestKit with Next.js How OrchestKit's skills, agents, and hooks apply to a Next.js / React codebase: installation, which components activate, and real workflows. [https://orchestkit.dev/docs/guides/orchestkit-with-nextjs](/docs/guides/orchestkit-with-nextjs) # Using OrchestKit with Next.js OrchestKit is framework-agnostic (it extends Claude Code, not your app), but several of its skills and agents are written specifically for React and Next.js work. This guide shows what activates on a Next.js codebase and the workflows that benefit most. ## Install ```bash claude plugin install ork@orchestkit ``` That's the whole setup. OrchestKit detects your stack from the codebase itself (package.json, file extensions, framework conventions); there is no Next.js-specific configuration. ## What activates on a Next.js codebase **Skills** (auto-injected context when relevant, or invoked as `/ork:`): - `react-server-components-framework`: App Router, Cache Components, streaming SSR, Server Actions, and React 19 patterns for server-first architecture. - `performance`: Core Web Vitals, render optimization, lazy loading, bundle and image optimization. - `testing-e2e`: Playwright page objects, visual regression, accessibility testing with axe-core. - `testing-unit`: Vitest/Jest patterns, MSW network-level mocking, fixture scoping. - `api-design`: REST design and RFC 9457 error handling for your route handlers. **Agents** (spawned by workflows like `/ork:implement` and `/ork:review-pr`): - `frontend-ui-developer`: React 19/TypeScript components, optimistic updates, Zod-validated APIs. - `frontend-performance-engineer`: bundle analysis, render profiling, Web Vitals. - `accessibility-specialist`: WCAG 2.2 audits, keyboard navigation, ARIA patterns. - `test-generator`: coverage gap analysis and test generation across the stack. **Hooks** run regardless of framework: dangerous-command blocking, secret detection, stale-import detection after refactors, and the commit/PR quality gates. ## Workflows that pay off ### Implement a feature end-to-end ```text /ork:implement add an account-settings page with optimistic profile updates ``` `/ork:implement` plans the feature, then runs parallel specialist agents for frontend, backend (if your app has API routes), and test generation inside an isolated git worktree, and verifies the result before handing it back. ### Review a PR with parallel reviewers ```text /ork:review-pr 123 ``` Code-quality, security, testing, and architecture reviewers run in parallel and synthesize one verdict. On frontend-heavy diffs the frontend and accessibility specialists join automatically. ### Diff-aware browser testing ```text /ork:expect ``` Reads your git diff, maps changed components to affected pages, and runs targeted browser checks via the agent-browser CLI, useful before pushing UI changes. ## Honest limitations - OrchestKit does not replace Next.js tooling: `next build`, ESLint, and your test runner still do the verifying; OrchestKit orchestrates them. - Skills encode patterns current as of their last release; for bleeding-edge Next.js canary features, check the [changelog](/docs/changelog) for adoption status. - The plugin runs only inside Claude Code. It adds nothing to your production bundle, and nothing to your runtime. ## See also - [What OrchestKit adds to Claude Code](/compare) - [All skills reference](/docs/reference/skills) - [Developer resources](/developers) ## Using OrchestKit with Python and FastAPI How OrchestKit applies to a Python backend: async patterns, SQLAlchemy, migrations, and the typed hook contract on PyPI. [https://orchestkit.dev/docs/guides/orchestkit-with-python-fastapi](/docs/guides/orchestkit-with-python-fastapi) # Using OrchestKit with Python and FastAPI OrchestKit extends Claude Code rather than your application, so it works the same on a Python backend as anywhere else, but its backend skills encode patterns that are specifically Python-shaped, and its hook I/O contract ships as a typed package on PyPI. ## Install ```bash claude plugin install ork@orchestkit ``` No Python-specific configuration. Stack detection reads your `pyproject.toml`, imports, and project layout. ## What activates on a Python codebase **Skills:** - `python-backend`: asyncio TaskGroup patterns, FastAPI dependency injection and middleware, SQLAlchemy 2.0 async sessions, connection-pool tuning (Python 3.11+). - `database-patterns`: Alembic migrations, schema design, versioning, drift handling. - `api-design`: REST/GraphQL design, versioning strategies, RFC 9457 Problem Details errors. - `testing-integration`: API endpoint tests, database testing, contract verification. - `testing-perf`: k6/Locust load tests and pytest execution optimization (xdist, fixture scoping). - `security-patterns`: auth flows, input validation, OWASP coverage. **Agents:** `backend-system-architect` (API and schema boundaries), `database-engineer` (PostgreSQL, query optimization, pgvector), `python-performance-engineer` (profiling, async performance), `security-auditor`, and `test-generator`. **Hooks** enforce the guardrails that bite hardest on backends: dangerous-command blocking, secret-exfiltration detection, and batch-change discipline (run tests every few files in a migration sweep, not after fifty). ## Workflows that pay off ### Implement an endpoint with its migration and tests ```text /ork:implement add a paginated /api/orders endpoint with cursor pagination and an Alembic migration ``` The backend architect designs the boundary, the database engineer writes the migration, and the test generator covers the endpoint, in parallel, in an isolated worktree. Cursor pagination is the encoded default; offset pagination is flagged as an anti-pattern. ### Review with backend-aware specialists ```text /ork:review-pr 123 ``` On Python diffs the reviewer set includes async-correctness and N+1-query checks alongside the standard security and test-coverage passes. ## The typed hook contract on PyPI If you build tooling that consumes OrchestKit hook events, the I/O contract is published as a typed package: ```bash pip install orchestkit-hook-contract ``` It pins the exact JSON shapes hooks read and emit, so Python-side integrations stay in lockstep with the plugin's TypeScript hook runtime. Published via OIDC trusted publishing on every contract change; see the [PyPI project page](https://pypi.org/project/orchestkit-hook-contract/). ## Honest limitations - OrchestKit's skills assume modern Python (3.11+) and SQLAlchemy 2.x idioms; legacy 1.x codebases get generic help, not the encoded patterns. - Your own toolchain (pytest, ruff, mypy/ty) remains the source of truth. Hooks and workflows orchestrate it; they do not replace it. ## See also - [What OrchestKit adds to Claude Code](/compare) - [All skills reference](/docs/reference/skills) - [Developer resources](/developers) ## Output modes: try them See the same answer as a chat render, a question, or a page, for an operator or a novice, with and without the done sign-off. Pick one and copy the flag or the prompt. [https://orchestkit.dev/docs/guides/output-modes](/docs/guides/output-modes) import { AudienceCompare, CopyPrompt, ModePicker, SignoffCompare, SurfaceCompare, } from '@/components/output-modes'; OrchestKit answers in one of three **surfaces** (chat, ask, page) for one of two **audiences** (operator, novice), and can end with a **done sign-off**. `/ork:glyph` picks all of this for you and says what it picked in one line, for example `→ chat · operator`. A flag always wins over its guess. Pick a mode below: every section on this page follows your pick, and the last one gives you a prompt to paste. ## Pick a mode Defaults: surface **chat**, audience **operator**, no sign-off. `--eli5` on its own also sets the page surface, so the flag above always names the surface. ## One answer, three surfaces The question is "is beta.160 ready to ship?". Each panel is the same answer. Your pick has the heavy outline. - **chat** is the common case: one render in the reply, up to about 50 lines. - **ask** is for a real fork that must be settled before the next step. It blocks until someone answers, so glyph uses it only when the pick changes what happens next. - **page** is for answers over about 50 lines, or answers that must persist. ## Operator or novice Same surface, two readers. Novice (`--eli5`, or a request that names a reader who is not you, such as "explain it to the client") means plain words and an analogy before the mechanism. It does not mean less accurate. On the ask surface the announce line always says `operator`: it names who answers the question, not who reads the result. ## Done sign-off `--signoff` on glyph, and the last step of `/ork:verify`, end with one question: **Accept done**, **Show me the evidence**, or **Not satisfied**. Any failure is listed first. Runs with no one to answer (`claude -p`, a workflow) print the verdict and skip the question. ## Display env vars Sixteen environment variables change what OrchestKit shows you. Each one is read by the hook named in the last column. Set them in your shell before you start Claude Code. | Variable | Default | What it changes | Hook | |---|---|---|---| | `ORK_ASK_FALLBACK` | unset | `text` turns every picker into a numbered text list ([guide](/docs/guides/ask-fallback)) | `lifecycle/ask-fallback-injector` | | `ORK_DISPLAY_LINT` | on | `0` stops the nudge to put long multi-stage shell commands in a script file | `pretool/bash/display-lint` | | `ORK_NO_NOTIFY` | unset | `1` turns off desktop notifications | `notification/desktop` | | `ORK_NOTIFY_OSASCRIPT` | unset | `1` sends notifications with osascript or notify-send instead of the terminal escape code | `notification/desktop` | | `ORK_NO_CTX_WARN` | unset | `1` turns off the context-window warnings | `posttool/context-crossing-warn` | | `ORK_CTX_WARN_THRESHOLD` | unset | a token count used as the one warning point; turns off the wind-down zone | `posttool/context-crossing-warn` | | `ORK_CTX_WINDDOWN_PCT` | `0.70` | the share of the context window where the wind-down warning starts | `posttool/context-crossing-warn` | | `ORK_CTX_IMMINENT_PCT` | `0.85` | the share of the context window where the "compaction is near" warning starts | `posttool/context-crossing-warn` | | `ORCHESTKIT_AUTO_COMMIT_NUDGE` | on | `false` stops the "consider committing" reminder | `posttool/commit-nudge` | | `ORK_DISABLE_DEBT_SURFACER` | unset | `1` stops the list of deferred work shown when instructions load | `instructions-loaded/debt-surfacer` | | `ORK_NO_STRAY_PLAYGROUND_CHECK` | unset | `1` stops the session-start warning about uncommitted playground pages | `lifecycle/stray-playground-pages` | | `ORK_STRAY_PLAYGROUND_MIN_AGE_HOURS` | `1` | how old a playground page must be before that warning names it | `lifecycle/stray-playground-pages` | | `ORK_EXPECT_AUTO` | on | `0` stops the browser-test suggestion after UI file edits | `posttool/ui-change-detector` | | `ORK_NO_PRECOMPACT_PROMPT` | unset | `1` stops the "mark finished tasks done" prompt before compaction | `lifecycle/pre-compact-task-done-prompt` | | `ORK_TASK_NUDGE_MAX_UNANSWERED` | `3` | after this many ignored nudges, the task-list nudge gets quieter (2 to 1000) | `prompt/multi-step-task-nudge` | | `ORK_NO_MEMORY_LINT` | unset | `1` turns off the checks that come from your memory files | `lib/memory-lint` | The visual-style nudge that asks for a render on every prompt has no off switch today. ## Copy as prompt Paste this into Claude Code to get your pick on the next answer. ## Claude Design → PR Turn a claude.ai/design handoff bundle into a reviewable GitHub PR with one command, the closed-loop pipeline from design exploration to production code. [https://orchestkit.dev/docs/cookbook/claude-design-handoff](/docs/cookbook/claude-design-handoff) import { Callout } from 'fumadocs-ui/components/callout'; import { Files, Folder, File } from 'fumadocs-ui/components/files'; import { MinCC } from '@/components/count'; [Claude Design](https://claude.ai/design) generates prototypes, mockups, slides, and one-pagers from natural-language prompts. Once a design is ready to build, it ships a **handoff bundle** that Claude Code can consume directly. OrchestKit's `/ork:design-ship` workflow turns that bundle into a reviewable pull request, with components scaffolded against your existing codebase, Storybook stories generated, browser verification run, and a PR opened with screenshots embedded. This cookbook walks through the full design-to-PR loop end-to-end. Claude Design is in research preview. The handoff bundle schema is provisional; the `claude-design-orchestrator` agent adapts to schema changes and surfaces deviations rather than failing silently. ## What You'll Use | Component | Type | Role | |---|---|---| | `/ork:design-ship` | Skill | One-shot Design URL → PR | | `/ork:design-import` | Skill | Just the import (no tests, no PR) | | `claude-design-orchestrator` | Agent | Parses bundle, dedups components, tracks provenance | | `post-design-import` | Hook | Auto-suggests verification after import | | `/ork:design-to-code` | Skill (composed) | Owns the actual EXTRACT/MATCH/ADAPT/RENDER pipeline | | `/ork:cover` | Skill (composed) | Generates Storybook stories and Playwright tests | | `/ork:expect` | Skill (composed) | Diff-aware browser verification | | `/ork:create-pr` | Skill (composed) | Opens the PR with templated body | --- ## Prerequisites 1. **Connect your repo to Claude Design**: in claude.ai/design, link the GitHub repo so Claude reads your design tokens, Tailwind config, and existing components. Generated visuals will then stay on-brand automatically. 2. **OrchestKit installed**: `ork` plugin enabled in Claude Code or later. 3. **`gh` CLI authenticated**: required for the PR-opening step. --- ## Step 1: Generate a design in Claude Design Open [claude.ai/design](https://claude.ai/design) and prompt for what you want: > "Generate a pricing section for a developer-tools SaaS, three tiers, highlight the middle one, match our existing brand." Because the repo is connected, Claude Design reads your tokens and produces visuals that already use your colors, typography, and spacing scale. Refine in-canvas with direct edits or follow-up prompts until you're happy. When ready, click **Export → Handoff bundle**. You get a sharable URL like `https://claude.ai/design/abc123` (or download the bundle as JSON). --- ## Step 2: Ship it In your project directory: ```bash /ork:design-ship https://claude.ai/design/abc123 ``` That single command runs the full pipeline. Here's what happens internally: ``` Handoff bundle (URL or file) │ ▼ ┌──────────────────────────────┐ │ 1. /ork:design-import │ Scaffold components, write provenance │ (delegates to orchestrator │ Tokens reconciled │ for parse + dedup) │ Components written or reused └──────────┬───────────────────┘ │ ▼ ┌──────────────────────────────┐ │ 2. /ork:cover │ Storybook stories per new component │ (Storybook + Playwright) │ Playwright E2E for new routes └──────────┬───────────────────┘ │ ▼ ┌──────────────────────────────┐ │ 3. /ork:expect │ Diff-aware browser verification │ (CDP + ARIA-tree-first) │ Screenshots saved for PR body └──────────┬───────────────────┘ │ ▼ ┌──────────────────────────────┐ │ 4. /ork:create-pr │ PR opened with screenshots, coverage │ │ Label: claude-design └──────────────────────────────┘ ``` --- ## Step 3: Review the manifest After Phase 1 (`design-import`) completes, you'll see a concise manifest: ``` Imported bundle a1b2c3d4... Source: https://claude.ai/design/abc123 Provenance: .claude/design-handoffs/a1b2c3d4.json Components: ✓ PricingCard scaffold src/components/pricing/PricingCard.tsx ↻ Button reuse existing: src/components/ui/Button.tsx ⤳ Hero adapt adapted from: src/components/Hero.tsx Tokens: + 3 new (added to design-tokens.json) ~ 1 modified (user accepted bundle value) ✗ 0 conflicts unresolved ``` Three decisions per component: - **`scaffold`**: no existing match found; new file written - **`reuse`**: existing component matches; nothing touched on disk (still referenced by the design intent) - **`adapt`**: partial match; the existing component is updated rather than duplicated The orchestrator agent runs `component-search` (Storybook MCP first, then 21st.dev, then filesystem) so duplicates do not slip through. --- ## Step 4: Token reconciliation If the bundle declares tokens that conflict with your project's tokens, the import pauses and asks how to resolve: | Diff | Action | |---|---| | Added (new tokens) | Appended automatically, safe | | Modified (different value) | `AskUserQuestion`: keep project, accept bundle, or open editor | | Conflicts (same name, different semantics) | Block scaffolding; resolve before continuing | Conflict resolution is captured in the provenance file so re-runs do not re-prompt. --- ## Step 5: Open the PR `/ork:design-ship` opens the PR with a templated body that includes: - Link back to the Claude Design URL - Bundle ID and provenance file path - Component decision table (scaffold / reuse / adapt) - Token diff summary - `/ork:expect` verification results - Coverage delta from `/ork:cover` - Before/after screenshots (uploaded as PR comments) The PR is auto-labeled `claude-design` so all design-driven PRs are filterable: `gh issue list --label claude-design`. --- ## Provenance: connecting design to code Every imported bundle writes a provenance file to `.claude/design-handoffs/.json`: ```json { "bundle_id": "a1b2c3d4...", "bundle_url": "https://claude.ai/design/abc123", "fetched_at": "2026-04-18T12:00:00Z", "imported_at": "2026-04-18T12:01:30Z", "components": [ {"name": "PricingCard", "decision": "scaffold", "path": "src/components/pricing/PricingCard.tsx"} ], "pr": {"number": 1387, "url": "https://github.com/...", "opened_at": "2026-04-18T12:02:15Z"} } ``` This makes design intent traceable backward from any merged PR: the answer to "why does this component exist?" is one `git log → grep` away. --- ## When to use which command | Scenario | Command | |---|---| | Have a Claude Design URL, want a PR | `/ork:design-ship ` | | Have a bundle, want to scaffold but review before committing | `/ork:design-import ` | | Want to extract design tokens from an existing app (not generate) | `/ork:design-context-extract` | | Want to build a component from a screenshot (no Claude Design involved) | `/ork:design-to-code` | --- ## Limitations (current preview) - **No public Claude Design API yet**: bundles are a one-shot export. To iterate on a design, re-export from claude.ai/design and re-run `/ork:design-ship`. The reverse path (detect that the live UI has drifted from the imported design and emit a refinement prompt for claude.ai/design) is tracked as **M124: Claude Design Drift Sync (Bet B)** with 5 issues: design-drift-detector agent (#1395), `/ork:design-iterate` skill (#1393), design-review PR hook (#1391), drift-sync cookbook (#1394), monthly dogfood report (#1397). - **No auto-merge**: the skill opens the PR; humans review and merge. - **Schema is provisional**: the orchestrator agent adapts to schema changes but may need updates as the Claude Design bundle format stabilizes. --- ## Related - [Implement a feature](/docs/cookbook/implement-feature): the same agent-orchestration pattern for non-design work - [Review a PR](/docs/cookbook/review-pr): what reviewers should look for in design-driven PRs - [Design to code](/docs/skills/design-to-code): the underlying scaffold pipeline this workflow composes - [Claude Design](https://claude.ai/design): the design tool itself ## Create a Demo Video From script to polished video with AI-powered production. [https://orchestkit.dev/docs/cookbook/create-demo-video](/docs/cookbook/create-demo-video) ## Fix a GitHub Issue From issue to PR in one command with root cause analysis, memory-powered investigation, and auto-linked pull requests. [https://orchestkit.dev/docs/cookbook/fix-github-issue](/docs/cookbook/fix-github-issue) ## Implement a Feature From idea to merged PR with parallel AI agents: a complete walkthrough of the /ork:implement workflow. [https://orchestkit.dev/docs/cookbook/implement-feature](/docs/cookbook/implement-feature) ## Cookbook Step-by-step workflow walkthroughs for common development tasks with OrchestKit. [https://orchestkit.dev/docs/cookbook](/docs/cookbook) import { Card, Cards } from 'fumadocs-ui/components/card'; Real-world workflows showing OrchestKit in action. Each recipe walks through a complete task from start to finish. ## Workflows ## By Role Pick your role for curated workflows and agent recommendations: ## Review a Pull Request AI-powered code review with 6 parallel specialized agents that catch security, performance, and quality issues. [https://orchestkit.dev/docs/cookbook/review-pr](/docs/cookbook/review-pr) ## AI Engineer OrchestKit toolkit for AI engineers [https://orchestkit.dev/docs/cookbook/roles/ai-engineer](/docs/cookbook/roles/ai-engineer) ## You're an AI engineer. Here's your toolkit. You build RAG pipelines, orchestrate multi-agent systems, wire up function calling, and optimize token costs. OrchestKit gives you 7 skills covering retrieval, embeddings, LangGraph, evaluation, and prompt caching, plus 4 agents that can design agent workflows, integrate LLM APIs, build data pipelines, and craft prompts. When you describe an AI task, the relevant patterns for your specific LLM stack are injected automatically. ## Your Skills | Skill | What it does | |---|---| | `rag-retrieval` | RAG pipeline patterns for context construction, citations, hybrid search, and grounded responses | | `langgraph-supervisor` | Supervisor-worker pattern for LangGraph with round-robin and priority-based agent dispatch | | `function-calling` | Tool schemas, execution loops, and structured output patterns for OpenAI, Anthropic, and Ollama | | `llm-evaluation` | LLM-as-judge patterns, quality gates for AI outputs, RAGAS metrics, and Langfuse integration | | `embeddings` | Embedding model selection, chunking strategies, vector indexing, and document similarity | | `contextual-retrieval` | Anthropic's Contextual Retrieval with hybrid BM25+vector search to reduce retrieval failures | | `prompt-caching` | Provider-native cache breakpoints for Claude and OpenAI to cut token costs on repeated prefixes | ## Your Agents | Agent | Model | Activates when... | |---|---|---| | `workflow-architect` | opus | LangGraph, workflow, supervisor, state, checkpoint, RAG, multi-agent orchestration | | `llm-integrator` | inherit | LLM, OpenAI, Anthropic, Ollama, prompt, function calling, streaming, token costs | | `data-pipeline-engineer` | inherit | embeddings, chunking, vector index, data pipeline, batch processing, ETL, cache warming | | `multimodal-specialist` | inherit | vision, audio, video, transcription, OCR, multi-modal pipelines | ## Your Workflows - **[Implement a Feature](/docs/cookbook/implement-feature)**: Describe an AI feature, get agents building retrieval pipelines, tool schemas, and evaluation harnesses in parallel - **[Set Up Memory](/docs/cookbook/setup-memory)**: Configure OrchestKit's 3-tier memory system with knowledge graph, local storage, and CC Native memory ## Quick Start Try this right now: ```bash /ork:implement "Build a RAG pipeline with contextual retrieval and reranking" ``` The `workflow-architect` agent activates with `rag-retrieval` and `contextual-retrieval` skills injected, producing a pipeline with document chunking, hybrid BM25+vector search, contextual embedding enrichment, and a reranking step with evaluation metrics. ## Backend Developer OrchestKit toolkit for backend developers [https://orchestkit.dev/docs/cookbook/roles/backend-developer](/docs/cookbook/roles/backend-developer) ## You're a backend developer. Here's your toolkit. You build APIs, design database schemas, wire up background jobs, and keep services fast under load. OrchestKit gives you 7 skills covering FastAPI, SQLAlchemy, Celery, caching, and connection management, plus 3 agents that can design endpoints, write migrations, and architect event-driven systems alongside you. Instead of switching between docs tabs, you describe what you need and the right patterns are injected automatically. ## Your Skills | Skill | What it does | |---|---| | `fastapi-advanced` | Lifespan events, dependency injection, middleware chains, and Pydantic settings for async Python services | | `database-schema-designer` | SQL and NoSQL schema design with normalization, indexing strategies, and migration planning | | `alembic-migrations` | Alembic migration patterns for SQLAlchemy 2.0 async, reversible changes, zero-downtime deploys | | `celery-advanced` | Canvas workflows, priority queues, rate limiting, multi-queue routing, and Flower monitoring | | `sqlalchemy-2-async` | AsyncSession, async_sessionmaker, and FastAPI integration for async ORM queries | | `connection-pooling` | asyncpg and aiohttp pool configuration, connection lifecycle tuning for high-concurrency services | | `caching-strategies` | Redis write-through, write-behind, cache-aside, TTL management, and stampede prevention | ## Your Agents | Agent | Model | Activates when... | |---|---|---| | `backend-system-architect` | opus | API design, database schema, microservice, REST, GraphQL, JWT, middleware, dependency injection | | `database-engineer` | inherit | database, schema, migration, PostgreSQL, pgvector, SQL, Alembic, index, constraint | | `event-driven-architect` | opus | event sourcing, message queue, Kafka, RabbitMQ, pub/sub, CQRS, saga, outbox pattern | ## Your Workflows - **[Implement a Feature](/docs/cookbook/implement-feature)**: Describe a feature, get parallel agents writing endpoints, tests, and security scans simultaneously - **[Run a Security Audit](/docs/cookbook/security-audit)**: 8-layer defense-in-depth scan that checks auth, input validation, and data handling across your backend ## Quick Start Try this right now: ```bash /ork:implement "Add cursor-based pagination to the /api/users endpoint" ``` The `backend-system-architect` agent picks up the task, pulls in `api-design-framework` and `fastapi-advanced` skills, and produces the endpoint with proper cursor encoding, Pydantic response models, and integration tests. ## DevOps Engineer OrchestKit toolkit for DevOps engineers [https://orchestkit.dev/docs/cookbook/roles/devops-engineer](/docs/cookbook/roles/devops-engineer) ## Frontend Developer OrchestKit toolkit for frontend developers [https://orchestkit.dev/docs/cookbook/roles/frontend-developer](/docs/cookbook/roles/frontend-developer) ## Security Engineer OrchestKit toolkit for security engineers [https://orchestkit.dev/docs/cookbook/roles/security-engineer](/docs/cookbook/roles/security-engineer) ## Tech Lead OrchestKit toolkit for tech leads [https://orchestkit.dev/docs/cookbook/roles/tech-lead](/docs/cookbook/roles/tech-lead) ## Run a Security Audit 8-layer defense-in-depth verification for your codebase. [https://orchestkit.dev/docs/cookbook/security-audit](/docs/cookbook/security-audit) ## Set Up Cross-Session Memory Persist decisions, patterns, and context across conversations. [https://orchestkit.dev/docs/cookbook/setup-memory](/docs/cookbook/setup-memory) ## Task Management Patterns Track complex work with TaskCreate, TaskUpdate, and dependency chains, from single-phase tasks to multi-agent coordination. [https://orchestkit.dev/docs/cookbook/task-management](/docs/cookbook/task-management) ## AI & LLM Skills LLM integration, RAG, agent orchestration, MCP, embeddings. [https://orchestkit.dev/docs/skills/by-category/ai-llm](/docs/skills/by-category/ai-llm) ## Backend Skills API design, databases, Python, async patterns, distributed systems. [https://orchestkit.dev/docs/skills/by-category/backend](/docs/skills/by-category/backend) ## DevOps Skills CI/CD, deployment, monitoring, infrastructure, containers. [https://orchestkit.dev/docs/skills/by-category/devops](/docs/skills/by-category/devops) --- > Some pages above are listed as links only to keep this file under 200,000 characters. Fetch any page's full Markdown by appending `.md` to its URL, or read the navigation index at https://orchestkit.dev/llms.txt and per-section index at https://orchestkit.dev/docs/llms.txt.