# OrchestKit — Full Documentation

> OrchestKit is a free, open-source plugin for Claude Code: 111 skills, 37 agents, and 210 lifecycle hooks with built-in security patterns and quality gates.

## Quickstart

1. Install Claude Code 2.1.170+.
2. Run `claude install orchestkit/ork`.
3. Invoke any skill with `/ork:<skill>` (e.g. `/ork:implement`, `/ork:review-pr`).

## API

- **Search** — `GET https://orchestkit.yonyon.ai/api/search?query=...` returns JSON results. OpenAPI: https://orchestkit.yonyon.ai/api/openapi
- **Ask** (natural language) — `POST https://orchestkit.yonyon.ai/ask` returns JSON (NLWeb); send `Accept: text/event-stream` for SSE streaming.
- **MCP server** (Streamable HTTP) — https://orchestkit.yonyon.ai/api/mcp · card: https://orchestkit.yonyon.ai/.well-known/mcp/server-card.json
- **Markdown** — append `.md` to any page URL, or send `Accept: text/markdown`.
- **API catalog** (RFC 9727) — https://orchestkit.yonyon.ai/.well-known/api-catalog

## Authentication

The public documentation and search API require no authentication — agents call the endpoints directly. Details: https://orchestkit.yonyon.ai/auth.md

---


## Configuration

Environment variables, MCP servers, and memory tier setup.

[https://orchestkit.yonyon.ai/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.

## 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 |

### 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"
```

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 are optional — skills and agents work without 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 37 agents)
- Setup instructions, token overhead, and graceful degradation

**Quick start**: context7, memory, and sequential-thinking work with zero config. Tavily needs a free API key from [app.tavily.com](https://app.tavily.com).

## 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

OrchestKit ships with 8 chord keybindings for the most-used skills. Press the first key combo, release, then press the second:

| Shortcut | Skill | What It Does |
|---|---|---|
| `ctrl+k ctrl+f` | `/ork:fix-issue` | Fix a GitHub issue |
| `ctrl+k ctrl+i` | `/ork:implement` | Implement a feature |
| `ctrl+k ctrl+e` | `/ork:explore` | Deep codebase exploration |
| `ctrl+k ctrl+r` | `/ork:review-pr` | Review a pull request |
| `ctrl+k ctrl+m` | `/ork:memory` | Search/load memory |
| `ctrl+k ctrl+a` | `/ork:assess` | Quality assessment |
| `ctrl+k ctrl+c` | `/ork:commit` | Conventional commit |
| `ctrl+k ctrl+h` | `/ork:help` | Skill directory |

These are defined in `settings.json` and can be customized via `/ork:configure` or by editing `src/settings/ork.settings.json`.

## 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

## Your First 10 Minutes

From install to your first AI-assisted commit — a guided walkthrough.

[https://orchestkit.yonyon.ai/docs/getting-started/first-10-minutes](/docs/getting-started/first-10-minutes)

import { Card, Cards } from 'fumadocs-ui/components/card';

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 111 skills, 37 agents, and 210 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 <noreply@anthropic.com>

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

<Cards>
  <Card title="Find Your Path" href="/docs/getting-started/navigating" description="Pick skills for your role" />
  <Card title="Configuration" href="/docs/getting-started/configuration" description="Customize env vars and memory" />
  <Card title="Implement Feature" href="/docs/cookbook/implement-feature" description="Deep dive into /ork:implement" />
</Cards>

## Installation

Install OrchestKit in Claude Code — marketplace, CLI, or manual setup.

[https://orchestkit.yonyon.ai/docs/getting-started/installation](/docs/getting-started/installation)

import { Card, Cards } from 'fumadocs-ui/components/card';
import { Callout } from 'fumadocs-ui/components/callout';
import { LazySetupWizard } from '@/components/lazy';

## From Claude Code Marketplace (Recommended)

```bash
claude install orchestkit/ork
```

This installs all 111 skills, 37 agents, and 210 hooks.

## Interactive Setup

<LazySetupWizard />

## Verify Installation

Run the health check after installing:

```
/ork:doctor
```

Expected output:

```
OrchestKit Health Check
=======================
Plugin:     ork v7.43.0
Skills:     111 loaded (31 commands, 80 reference)
Agents:     37 registered
Hooks:      210 active (142 global, 46 agent, 22 skill-scoped)
Memory:     Graph ✓  Local ✓  CC Native ✓
MCP:        context7 ✓  memory ✓  tavily ○  agentation ○

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 uninstall ork && claude install orchestkit/ork` |
| `✗ 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 setup below if you want web research |
| `○ agentation ○` | **Not an error** — Agentation is optional | Only needed for UI annotation workflows |

<Callout type="info">
Most issues are fixed by ensuring Node.js >= 18 is installed and restarting Claude Code. If problems persist, run `/ork:doctor --verbose` for detailed diagnostics.
</Callout>

## Optional: Web Research (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 → agent-browser automatically.

## Requirements

- **Claude Code** >= 2.1.148
- **Node.js** >= 18 (for hooks)
- **Git** (for commit/PR workflows)

## Next Steps

<Cards>
  <Card title="First 10 Minutes" href="/docs/getting-started/first-10-minutes" description="Guided walkthrough of your first session" />
  <Card title="Configuration" href="/docs/getting-started/configuration" description="Full environment setup" />
</Cards>

## Find What You Need

Hub-and-spoke navigation — find the right skills and agents for your role and task.

[https://orchestkit.yonyon.ai/docs/getting-started/navigating](/docs/getting-started/navigating)

import { Card, Cards } from 'fumadocs-ui/components/card';

OrchestKit has 111 skills and 37 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

The fastest way to invoke skills — chord keybindings (press first combo, release, press second):

| Shortcut | Skill | What It Does |
|---|---|---|
| `ctrl+k ctrl+f` | `/ork:fix-issue` | Fix a GitHub issue |
| `ctrl+k ctrl+i` | `/ork:implement` | Implement a feature |
| `ctrl+k ctrl+e` | `/ork:explore` | Deep codebase exploration |
| `ctrl+k ctrl+r` | `/ork:review-pr` | Review a pull request |
| `ctrl+k ctrl+m` | `/ork:memory` | Search/load memory |
| `ctrl+k ctrl+a` | `/ork:assess` | Quality assessment |
| `ctrl+k ctrl+c` | `/ork:commit` | Conventional commit |
| `ctrl+k ctrl+h` | `/ork:help` | Skill directory |

## By Command

All 18 user-invocable command skills:

| Command | What It Does |
|---|---|
| `/ork:implement` | Full feature implementation with parallel agents |
| `/ork:fix-issue` | Issue to PR in one command |
| `/ork:verify` | Run tests, security, and quality gates |
| `/ork:explore` | Deep codebase exploration |
| `/ork:brainstorm` | Design exploration |
| `/ork:assess` | Quality rating 0-10 |
| `/ork:commit` | Conventional commit with analysis |
| `/ork:create-pr` | PR with summary and test plan |
| `/ork:review-pr` | Multi-agent code review |
| `/ork:remember` | Store decisions in knowledge graph |
| `/ork:memory` | Search, load, sync memory |
| `/ork:doctor` | Health diagnostics |
| `/ork:configure` | Plugin settings |
| `/ork:help` | Skill directory |
| `/ork:setup` | Onboarding wizard with stack detection |
| `/ork:visualize-plan` | Visualize planned changes |

## Next Steps

<Cards>
  <Card title="Configuration" href="/docs/getting-started/configuration" description="Environment variables and MCP setup" />
  <Card title="How Skills Work" href="/docs/skills/overview" description="Deep dive into the skill system" />
</Cards>

## Release Channels

Install OrchestKit from stable, beta, or alpha release channels using Claude Code's multiple-marketplace pattern.

[https://orchestkit.yonyon.ai/docs/getting-started/release-channels](/docs/getting-started/release-channels)

import { Card, Cards } from 'fumadocs-ui/components/card';
import { Step, Steps } from 'fumadocs-ui/components/steps';

OrchestKit offers three release channels. Each channel is a **separate git branch** that Claude Code resolves via the marketplace `@ref` syntax. The **stable** channel (default) is recommended for most users.

## How It Works

Claude Code's plugin system uses **git refs** to resolve plugin versions. When you add a marketplace with `@beta`, CC clones the repo at the `beta` branch — which has a different version stamped into `plugin.json` (e.g., `7.2.0-beta.3` vs `7.2.0`). CC caches each version separately at `~/.claude/plugins/cache/ork/<version>/`.

```
main branch    →  marketplace.json version "7.2.0"          →  stable
beta branch    →  marketplace.json version "7.2.0-beta.3"   →  beta
alpha branch   →  marketplace.json version "7.2.0-alpha.42" →  alpha
```

## Channel Comparison

| Channel | Stability | Version Format | Who Should Use |
|---------|-----------|---------------|----------------|
| **Stable** (default) | Production-ready | `7.2.0` | All users |
| **Beta** | Mostly functional | `7.2.0-beta.N` | Early adopters, experienced users |
| **Alpha** | Experimental | `7.2.0-alpha.N` | Contributors, advanced users only |

## Stable Channel (Default)

Stable is the default when you install OrchestKit. Thoroughly tested and recommended for production use.

<Steps>
<Step>
### Install stable

```bash
/plugin install yonatangross/orchestkit
```

> **CC < 2.1.80:** Use `claude plugin marketplace add yonatangross/orchestkit && claude plugin install ork`
</Step>
<Step>
### Verify installation

```bash
/ork:doctor
```

Look for: `Plugin: ork v7.2.0 (stable)`
</Step>
</Steps>

**What you get:**
- Fully tested features across macOS, Ubuntu, Windows
- Regular bug fixes and security patches
- Compatible with Claude Code >= 2.1.148

**Update frequency:** Weekly or as needed for bug fixes.

## Beta Channel

Beta contains upcoming features that are largely functional but may have rough edges. The beta branch receives pre-release versions stamped by CI after passing the full test suite + cross-platform matrix (Node 18/20/22, macOS/Ubuntu/Windows).

<Steps>
<Step>
### Install beta

```bash
/plugin install yonatangross/orchestkit@beta
```

> **CC < 2.1.80:** Use `claude plugin marketplace add yonatangross/orchestkit@beta && claude plugin install ork`
</Step>
<Step>
### Verify channel

```bash
/ork:doctor
```

Look for: `Plugin: ork v7.2.0-beta.3 (beta)`
</Step>
</Steps>

**Update frequency:** Multiple times per week as development progresses.

## Alpha Channel

Alpha is cutting-edge and experimental. For contributors and advanced users only. May break, have missing features, or require manual fixes.

<Steps>
<Step>
### Install alpha

```bash
/plugin install yonatangross/orchestkit@alpha
```

> **CC < 2.1.80:** Use `claude plugin marketplace add yonatangross/orchestkit@alpha && claude plugin install ork`
</Step>
</Steps>

**Update frequency:** Multiple times per day as commits land.

## Switching Channels

### From Stable to Beta

```bash
claude plugin uninstall ork
/plugin install yonatangross/orchestkit@beta
```

### From Beta/Alpha Back to Stable

```bash
claude plugin uninstall ork
/plugin install yonatangross/orchestkit
```

**Note:** Restart Claude Code after switching channels for the change to take effect.

## Version Format

OrchestKit uses semantic versioning with pre-release identifiers:

```
MAJOR.MINOR.PATCH              →  Stable release
MAJOR.MINOR.PATCH-CHANNEL.N    →  Pre-release build

Examples:
  7.2.0              Stable release
  7.2.0-beta.3       Beta build 3 of v7.2.0
  7.2.0-alpha.42     Alpha build 42 of v7.2.0
```

Pre-release versions are **automatically stamped** by CI into all plugin files (`marketplace.json`, `plugin.json`, `package.json`, `pyproject.toml`, `CLAUDE.md`, `version.txt`) before the GitHub Release is created. This ensures CC sees a distinct version for each channel.

## Dogfooding Model

OrchestKit is tested daily across multiple real-world projects before any stable release. This "dogfooding-as-alpha" approach means:

- **Alpha signal**: The maintainer's 6+ projects running OrchestKit daily serve as the alpha test matrix
- **Beta signal**: Features stabilize on the beta branch after cross-project validation
- **Stable signal**: Merging to main triggers release-please for automated versioning and changelog

The beta and alpha channels provide **opt-in early access** for external users who want bleeding-edge features, while the dogfooding loop ensures quality before anything reaches stable.

## Checking Your Channel

```bash
/ork:doctor
```

Look for the version line:

```
Plugin:     ork v7.2.0 (stable)
            or
Plugin:     ork v7.2.0-beta.3 (beta)
            or
Plugin:     ork v7.2.0-alpha.42 (alpha)
```

## Compatibility

All three channels require:
- Claude Code >= 2.1.148
- Node.js >= 18 (for hooks)
- Git (for commit/PR workflows)

Pre-release builds may require a newer Claude Code version if they use unreleased CC APIs. The doctor health check will warn you of mismatches.

## Reporting Issues

When reporting issues from beta or alpha:

1. Run `/ork:doctor` to get your exact version
2. Include the full version string (e.g., `v7.2.0-beta.3`)
3. Report on [GitHub Issues](https://github.com/yonatangross/orchestkit/issues) with reproduction steps

## Channel Stability Guarantee

- **Stable**: No breaking changes within a major version (7.x → 8.0 is breaking, 7.1 → 7.2 is not)
- **Beta**: Breaking changes possible before stable release
- **Alpha**: All changes possible at any time

## Next Steps

<Cards>
  <Card title="Installation" href="/docs/getting-started/installation" description="Full installation instructions" />
  <Card title="Your First 10 Minutes" href="/docs/getting-started/first-10-minutes" description="Get started after installation" />
  <Card title="Configuration" href="/docs/getting-started/configuration" description="Configure memory, MCP, and environment" />
</Cards>

## Agent Attribution

Automatic tracking of which sub-agents contributed to each branch, with attribution in commit messages and PR bodies.

[https://orchestkit.yonyon.ai/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 <noreply@anthropic.com>
```

### 2. Per-Agent Co-Authored-By Trailers

```
Co-Authored-By: Claude <noreply@anthropic.com>
Co-Authored-By: ork:backend-system-architect <noreply@orchestkit.dev>
Co-Authored-By: ork:security-auditor <noreply@orchestkit.dev>
Co-Authored-By: ork:test-generator <noreply@orchestkit.dev>
```

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 `<details>` 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.yonyon.ai/docs/foundations/choosing-a-plugin](/docs/foundations/choosing-a-plugin)

## One Plugin, Everything Included

OrchestKit ships as a single plugin: **ork**.

```bash
claude install orchestkit/ork
```

No choices, no configuration required. All 111 skills, 37 agents, and 210 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

## MCP Servers

External tool integrations that give agents web search, component registries, design extraction, and more.

[https://orchestkit.yonyon.ai/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. They're **optional** — every skill and agent works without them, but MCPs add capabilities that can't be replicated with built-in tools alone.

## Available MCPs

OrchestKit supports 10 MCP servers across three tiers:

### Bundled (zero config)

These ship in `.mcp.json` and work immediately — no API keys, no setup.

| 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 |
| **ork-elicit** | Structured form elicitation for `/ork:setup` wizard | 1 |

### 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 |
| **agentation** | UI annotation — browser feedback picked up automatically | `npm install -D agentation-mcp` (disabled by default in `.mcp.json`) |
| **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 |
| ui-feedback | agentation | Browser annotations to code fixes |

### context7 Library Docs (18 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

### No MCP Access

These agents intentionally have `mcpServers: []` — they work with built-in tools only:

security-auditor, security-layer-auditor, system-design-reviewer, genui-architect, emulate-engineer, demo-producer

## Setup Instructions

### Bundled MCPs (zero config)

**context7**, **memory**, **sequential-thinking**, and **ork-elicit** work immediately — no API keys, no setup. They're defined in `.mcp.json` and start automatically.

### 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=<your-key>

# Option C: Remote MCP (no local process)
# In .mcp.json: "type": "url", "url": "https://mcp.tavily.com/mcp/?tavilyApiKey=<YOUR_KEY>"
```

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=<key>"

# Alternative: replace .mcp.json entry with env var approach
# "command": "npx", "args": ["-y", "@21st-dev/magic@latest"]
# Then add to ~/.zshrc: export API_KEY=<your-21st-dev-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: <YOUR-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.

### Agentation (UI feedback)

Pre-configured in `.mcp.json` but disabled by default. To enable:

```json
"agentation": {
  "command": "npx",
  "args": ["-y", "agentation-mcp", "server"],
  "disabled": false
}
```

### 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 |
| ork-elicit | 1 | ~300 |
| tavily | 5 | ~2,000 |
| 21st-dev-magic | 4 | ~800 |
| agentation | 8 | ~1,500 |
| 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 | `/ork:implement` works but won't fetch latest library docs |
| 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.

## 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?

The complete AI development toolkit for Claude Code — 111 skills, 37 agents, 210 hooks working together.

[https://orchestkit.yonyon.ai/docs/foundations/overview](/docs/foundations/overview)

import { Card, Cards } from 'fumadocs-ui/components/card';
import { Steps, Step } from 'fumadocs-ui/components/steps';

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:

<Steps>
  <Step>
    ### Hooks (210) fire automatically

    Security gates, auto-lint, and memory injection run on every action — you never invoke them directly.
  </Step>
  <Step>
    ### Agents (37) activate from keywords

    Say "review PR" and `security-auditor` spawns. Say "design API" and `backend-architect` activates. Multiple agents can run in parallel.
  </Step>
  <Step>
    ### Skills (111) inject into agents

    Reusable knowledge — FastAPI patterns, React hooks, OWASP checklist, RAG strategies — loaded on demand by whichever agent needs them.
  </Step>
</Steps>

## One Plugin

OrchestKit ships as a single plugin: **ork** — 111 skills, 37 agents, 210 hooks.

## Next Steps

<Cards>
  <Card title="The 3 Building Blocks" href="/docs/foundations/skills-agents-hooks" description="Understand skills, agents, and hooks in depth" />
  <Card title="Install OrchestKit" href="/docs/getting-started/installation" description="Get up and running in 2 minutes" />
  <Card title="First 10 Minutes" href="/docs/getting-started/first-10-minutes" description="Guided walkthrough of your first session" />
</Cards>

## The 3 Building Blocks

Skills are knowledge, agents are specialists, hooks are automation. Here's how they work together.

[https://orchestkit.yonyon.ai/docs/foundations/skills-agents-hooks](/docs/foundations/skills-agents-hooks)

import { Steps, Step } from 'fumadocs-ui/components/steps';

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
```

**111 skills** covering: FastAPI, React, SQLAlchemy, RAG, LangGraph, OWASP, Terraform, and more.

### Two Types

| Type | Count | How It Works | Example |
|---|---|---|---|
| **Command** | 23 | You invoke directly: `/ork:commit` | `/ork:verify`, `/ork:implement` |
| **Reference** | 80 | 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.

**37 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.

**183 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"**:

<Steps>
  <Step>
    ### Prompt hooks fire
    `context-injector`, `memory-context-loader`, and `skill-auto-suggest` enrich your prompt with project context.
  </Step>
  <Step>
    ### Agent spawns
    **backend-system-architect** activates (model: opus) based on keyword matching.
  </Step>
  <Step>
    ### Skills injected
    The agent auto-loads `security-patterns`, `api-design`, `python-backend`, and `architecture-patterns`.
  </Step>
  <Step>
    ### Agent writes code
    Pretool hooks validate each tool call. Posttool hooks audit and log every action.
  </Step>
  <Step>
    ### Stop hooks
    `auto-remember-continuity` and `session-profile-agg` save context for the next session.
  </Step>
</Steps>

## Next Steps

- **[Choosing a Plugin](/docs/foundations/choosing-a-plugin)** — Plugin installation options
- **[Installation](/docs/getting-started/installation)** — Get started in 2 minutes

## Graph Memory (Primary)

The zero-config knowledge graph that stores entities and typed relations as OrchestKit's primary memory tier.

[https://orchestkit.yonyon.ai/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 `@anthropic/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 |
| `memory-fabric-init` | `pretool` (once) | Lazy initialization of memory directories and session registration on first memory MCP call |

## 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", "@anthropic/memory-mcp-server"]
    }
  }
}
```

<Callout type="info">
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.
</Callout>

## 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

## Local Session Persistence

How .claude/memory/ JSONL files provide offline-first durability, queue management, and session backup for OrchestKit memory.

[https://orchestkit.yonyon.ai/docs/memory/local-memory](/docs/memory/local-memory)

import { Callout } from 'fumadocs-ui/components/callout';

Local memory is Tier 2 -- the **durability layer** that ensures no decision is lost even if graph operations fail or sessions end unexpectedly. It uses JSONL (JSON Lines) files in the `.claude/memory/` directory, which is auto-created on first write.

## The `.claude/memory/` Directory

```
.claude/memory/
  decisions.jsonl        # All captured decisions and preferences
  graph-queue.jsonl      # Pending graph operations (entities + relations)
  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. The JSONL files form a **write-ahead queue** system: decisions land in the local files first, then are processed asynchronously into graph storage.

## `decisions.jsonl` -- The Decision Log

This is the primary local backup. Every decision captured by the memory writer is appended here as a single JSON line, regardless of whether graph or cloud storage succeeds.

### 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

The `storeDecision` function in `memory-writer.ts` always writes to `decisions.jsonl` as its first action (step 1 of 4). This ensures the decision is durably stored before any network or MCP operations attempt to process it.

### How It Gets Read

The `memory-context-loader` hook reads this file once per session on the first prompt. It:

1. Reads the last 10 lines (most recent decisions)
2. Parses each JSON line, skipping any malformed entries
3. Reverses the order so the most recent decision appears first
4. Formats decisions as markdown with type labels (`[Decision]`, `[Preference]`), rationale, and entity tags
5. Truncates output at 3000 characters to stay within the context budget

Example injected context:

```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_
```

## `graph-queue.jsonl` -- Pending Graph Operations

When the memory writer captures a decision, it builds graph operations (entity creation, relation creation, observation additions) and appends them to this queue. Each line represents a single operation to be processed.

### Record Structure

```json
{
  "type": "create_entities",
  "payload": {
    "entities": [
      {
        "name": "decision-m1abc-x7y2z3",
        "entityType": "Decision",
        "observations": [
          "What: Use cursor-based pagination for all list endpoints",
          "Rationale: Better performance for large datasets",
          "Alternatives considered: offset-based pagination",
          "Category: pagination",
          "Confidence: 85%",
          "Source: user_prompt",
          "Project: orchestkit",
          "Timestamp: 2026-02-06T10:30:00.000Z"
        ]
      },
      {
        "name": "cursor-pagination",
        "entityType": "Pattern",
        "observations": [
          "Mentioned in decision: Use cursor-based pagination for all list endpoints"
        ]
      }
    ]
  },
  "timestamp": "2026-02-06T10:30:00.001Z"
}
```

A single decision typically generates two queued operations: one `create_entities` and one `create_relations`. The `buildGraphOperations` function in `memory-writer.ts` produces these operations, including:

- A main entity for the decision itself
- Entities for each mentioned technology/pattern
- `CHOSE` or `PREFERS` relations from the decision to its entities
- `CHOSE_OVER` relations for rejected alternatives
- `CONSTRAINT` relations for limiting factors
- `TRADEOFF` relations for accepted costs
- `RELATES_TO` cross-links between co-occurring entities

### Processing

Graph queue operations are designed to be processed when the MCP memory server is available. The hook system reads pending operations and issues the corresponding `mcp__memory__create_entities` and `mcp__memory__create_relations` calls.

## `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.

## Offline-First Design

The local persistence layer is designed around an offline-first principle:

1. **Writes always succeed locally.** The `appendToJsonl` function creates the directory if it does not exist and appends the record. Even if graph MCP is unreachable, the decision is safely stored.

2. **Queues are processed when services become available.** Graph operations queue in `graph-queue.jsonl` until the MCP server processes them.

3. **No data is lost on unexpected shutdown.** Since each write is an atomic file append (not a rewrite), partial writes at most lose one line. The JSONL parser in the context loader silently skips malformed lines.

## Health Monitoring

The `memory-health.ts` library provides detailed health analysis for each JSONL file:

```typescript
interface FileHealth {
  exists: boolean;       // File found on disk
  lineCount: number;     // Total JSONL lines
  corruptLines: number;  // Lines that fail JSON.parse
  sizeBytes: number;     // File size
  lastModified: string;  // Last modification timestamp
}
```

The health check flags:

| Condition | Status | Meaning |
|---|---|---|
| `.claude/memory/` does not exist | `unavailable` | No memory directory; nothing has been stored yet |
| `decisions.jsonl` has corrupt lines | `degraded` | Some entries were partially written; parseable entries still work |
| `graph-queue.jsonl` has 50+ entries | `degraded` | Queue is backing up; graph operations may not be processing |

Run `/ork:memory status` to see the full health report.

## Synchronization Between Local and Graph

The local layer and graph layer stay in sync through the write-ahead queue pattern:

| Stage | Target | Timing |
|---|---|---|
| **memory-writer.ts** | `decisions.jsonl` | Always, immediate |
| | `graph-queue.jsonl` | Always, queued operations |
| **Hook processing** | Graph queue processed via `mcp__memory__create_entities` | Async, batched |

The local files serve as the durable source of truth. If the graph is ever rebuilt or cleared, the decisions in `decisions.jsonl` can be replayed to reconstruct it.

## File Size Management

- `decisions.jsonl` grows unbounded but is read from the tail (last N lines), so size does not affect read performance
- `graph-queue.jsonl` is cleared as operations are processed

If files become very large, the health check reports `degraded` status at the 50-entry threshold for queue files, signaling that processing may need attention.

## Next Steps

- [Graph Memory](/docs/memory/graph-memory) -- the primary tier that local queues feed into
- [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.yonyon.ai/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/<project>/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**. The `storeDecision` function in `memory-writer.ts` evaluates every captured decision:

```
if (decision.metadata.confidence >= 0.7 && isCCNativeMemoryAvailable()) {
    storeToCCNativeMemory(decision);
}
```

The two conditions for auto-promotion:

1. **Confidence >= 0.7** -- the decision must be high-confidence (see scoring below)
2. **CC Native memory directory exists** -- Claude Code must have created the project directory (it does this automatically when you first open a project)

### Confidence Scoring

| Factor | Effect on Confidence |
|---|---|
| User explicitly states a decision ("we decided...", "always use...") | Higher (typically 0.8+) |
| Decision includes rationale ("because...") | Higher |
| User states a preference directly | Higher |
| Pattern inferred from tool output | Lower (typically 0.4-0.6) |
| Observation from agent completion | Lower |

Only decisions with clear intent and strong signal cross the 0.7 threshold. 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 writing a new entry, the memory writer checks if the first 50 characters of the decision text already appear in the existing MEMORY.md content. If found, the write is skipped to avoid duplicate entries. This prevents the same decision from appearing multiple times if it is captured by multiple hooks 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

<Callout type="warn">
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.
</Callout>

## 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/<project-id>/` 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

How OrchestKit persists decisions, patterns, and context across sessions using a layered memory system.

[https://orchestkit.yonyon.ai/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. |

<Callout type="info">
All 3 tiers require zero configuration. They work the moment you install OrchestKit. Tier 2 creates its directory automatically.
</Callout>

## 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/<project>/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. |

<Callout type="info">
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.
</Callout>

## 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.yonyon.ai/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.

<AnalyticsDashboard />

## AskUserQuestion picker fallback (ORK_ASK_FALLBACK=text)

Text-prompt fallback for when the Claude Code AskUserQuestion picker stalls or otherwise refuses keystrokes.

[https://orchestkit.yonyon.ai/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)

## 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.yonyon.ai/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 4.8 (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:** Fable 5 is included at no extra cost in Pro/Max/Team subscriptions until **June 22, 2026**; after that it requires usage credits. 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 4.8 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 — one reason OrchestKit keeps its own security agents on an explicit `opus` pin rather than fable.

## Requirements

- Claude Code **2.1.170+** (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.

## 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.yonyon.ai/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:<name>`):

- `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 — 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.yonyon.ai/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)

## 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.yonyon.ai/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';

[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.

<Callout type="info">
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.
</Callout>

## 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 2.1.148 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/<bundle_id>.json`:

<Files>
  <Folder name=".claude" defaultOpen>
    <Folder name="design-handoffs" defaultOpen>
      <File name="a1b2c3d4...json" />
      <File name="e5f6g7h8...json" />
    </Folder>
  </Folder>
</Files>

```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 <url>` |
| Have a bundle, want to scaffold but review before committing | `/ork:design-import <url>` |
| 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.yonyon.ai/docs/cookbook/create-demo-video](/docs/cookbook/create-demo-video)

import { Callout } from 'fumadocs-ui/components/callout';

## Scenario

You just shipped a new authentication flow: login, signup, OAuth, token refresh, password reset. The code works. The tests pass. Now your team lead asks for a 60-second demo video to show stakeholders.

You could open QuickTime, fumble through screen recordings, splice clips in iMovie, and spend two hours on something that looks amateur. Or you can let OrchestKit orchestrate the entire pipeline -- from storyboard to rendered video with background music and thumbnails -- in a single command.

## What You'll Use

| Component | Type | Purpose |
|---|---|---|
| `/ork:demo-producer` | Command skill | Orchestrates the full video pipeline |
| `demo-producer` | Agent | Coordinates storyboard, recording, composition |
| `video-storyboarding` | Reference skill | AI scene breakdown with timing |
| `terminal-demo-generator` | Reference skill | VHS terminal recording automation |
| `remotion-composer` | Reference skill | Programmatic video composition with React |
| `music-sfx-selection` | Reference skill | Background music and sound effects |
| `thumbnail-first-frame` | Reference skill | Cover image generation |
| `content-type-recipes` | Reference skill | Video structure templates by type |
| `hook-formulas` | Reference skill | Attention and retention patterns |

## Step-by-Step

### Step 1: Launch the Pipeline

Start with a description of what you want to demo:

```bash
/ork:demo-producer "Demo the new authentication flow — login, OAuth, and token refresh"
```

The `demo-producer` agent activates and asks you to choose a video type:

```
What type of video?

  1. Feature Demo     — Show a feature in action (60-90s)
  2. Tutorial          — Step-by-step walkthrough (2-5min)
  3. Release Notes     — Changelog highlights (30-60s)

> 1
```

Choose **Feature Demo** for a concise stakeholder-facing clip.

### Step 2: Storyboarding

The agent generates a scene-by-scene breakdown using the `video-storyboarding` skill. Each scene has a visual description, timing, text overlay, and audio note:

```
Storyboard: "Authentication Flow Demo"
Duration: 60 seconds | Aspect: 16:9 + 1:1

Scene 1 (0:00-0:08) — Hook
  Visual: Split-screen: old login page vs new login page
  Text overlay: "Authentication, reimagined"
  Audio: Upbeat intro sting

Scene 2 (0:08-0:22) — Login Flow
  Visual: Terminal recording — user signs up, receives JWT
  Text overlay: "JWT-based auth with automatic refresh"
  Audio: Ambient background

Scene 3 (0:22-0:36) — OAuth Integration
  Visual: Browser recording — Google OAuth flow
  Text overlay: "One-click OAuth for Google, GitHub, Apple"
  Audio: Continue ambient

Scene 4 (0:36-0:48) — Token Refresh
  Visual: Terminal — token expires, auto-refreshes, request succeeds
  Text overlay: "Seamless token refresh — zero user interruption"
  Audio: Continue ambient

Scene 5 (0:48-0:60) — CTA
  Visual: Code diff — before/after line count
  Text overlay: "Ship it. /ork:implement"
  Audio: Outro sting

Approve storyboard? [Y/edit/n]
```

Type `Y` to approve, or `edit` to modify individual scenes. The storyboard is saved as `storyboard.json` for reuse.

### Step 3: Terminal Recording

For scenes that show terminal interactions, OrchestKit uses **VHS** (the terminal recorder by Charm) to create reproducible recordings:

```bash
# VHS generates a .tape file for each terminal scene
# Scene 2: Login flow
Output scene-2-login.gif
Set FontSize 16
Set Width 1200
Set Height 800
Set Theme "Catppuccin Mocha"

Type "curl -X POST https://api.example.com/auth/signup"
Enter
Sleep 1s
Type '  -d '"'"'{"email":"demo@example.com","password":"secure123"}'"'"''
Enter
Sleep 2s

# Response appears...
```

The `terminal-demo-generator` skill handles `.tape` file creation. VHS renders each scene as a GIF or MP4 clip.

<Callout type="info">
VHS must be installed locally: `brew install vhs`. If not available, OrchestKit falls back to static code screenshots with syntax highlighting. The video still renders -- just with stills instead of animated terminal sequences.
</Callout>

### Step 4: Composition with Remotion

The `remotion-composer` skill assembles all scene clips into a final video using Remotion (React-based programmatic video):

```
Composing video...
  Composition: ScrapbookDemo (16:9)
  Scenes: 5 clips loaded
  Transitions: paper-fold (100-200ms between scenes)
  Background: warm paper texture (#F0F0E8)
  Text overlays: Tiempos serif for impact, Inter sans-serif for data
  Duration: 60.0s @ 30fps

Rendering 16:9...  [====================] 100%
Rendering 1:1...   [====================] 100%

Output:
  ./output/auth-demo-16x9.mp4  (1920x1080, 12.4 MB)
  ./output/auth-demo-1x1.mp4   (1080x1080, 8.7 MB)
```

The composition uses the **Anthropic "Scrapbook Motion"** visual style:
- Warm paper backgrounds (`#F0F0E8`), not dark themes
- Fast cuts (100-200ms transitions) with paper-fold effects
- Mixed media collage: terminal recordings, browser captures, code diffs
- Typography: Tiempos (serif) for headings, Inter (sans-serif) for data

<Callout type="info">
Two registered compositions handle most use cases: **ScrapbookDemo** for feature demos and **ReleaseNotes** for changelog videos. Both render in 16:9 and 1:1 aspect ratios automatically. OrchestKit has 79 total Remotion compositions for specialized needs.
</Callout>

### Step 5: Audio Generation

The pipeline adds audio using **Kling 3.0** as the primary source:

```
Generating audio...
  Engine: Kling 3.0 (native audio, 5 languages)
  Intro sting: 3s upbeat electronic
  Background: 54s ambient lo-fi
  Outro sting: 3s fade-out

  Mixing...
  Audio levels: music -18dB, SFX -12dB
  Output: ./output/auth-demo-audio.mp3
```

Kling 3.0 generates background music natively -- multi-shot, 4K at 60fps, up to 15 seconds per clip, with audio in 5 languages. For longer tracks, clips are stitched with crossfade.

Optionally, add voice narration via ElevenLabs (backup TTS):

```bash
# Only if you want narration — most feature demos skip it
/ork:demo-producer --narrate "Demo the new authentication flow"
```

<Callout type="warn">
Audio generation requires the `KLING_API_KEY` environment variable. Optional fallbacks: `FAL_KEY` for video generation, `SUNO_API_KEY` for music. Without any keys, the video renders silently -- still usable, just without generated audio.
</Callout>

### Step 6: Thumbnail Generation

The `thumbnail-first-frame` skill generates a cover image from the first scene:

```
Generating thumbnail...
  Source: Scene 1, frame 0
  Style: Scrapbook Motion (paper texture + bold text)
  Text: "Authentication Flow Demo"
  Sizes:
    ./output/thumb-1280x720.png  (YouTube)
    ./output/thumb-1080x1080.png (Social)
```

### Final Output

The complete pipeline produces:

```
Pipeline complete!

Files:
  ./output/auth-demo-16x9.mp4      1920x1080, 60s, 12.4 MB
  ./output/auth-demo-1x1.mp4       1080x1080, 60s, 8.7 MB
  ./output/auth-demo-audio.mp3     60s, 1.2 MB
  ./output/thumb-1280x720.png      YouTube thumbnail
  ./output/thumb-1080x1080.png     Social thumbnail
  ./output/storyboard.json         Scene data (reusable)

Elapsed: 4m 32s
```

## Behind the Scenes

### Agent Orchestration

When you invoke `/ork:demo-producer`, the `demo-producer` agent spawns and coordinates a multi-step pipeline. Here is the full execution flow:

The `demo-producer` agent spawns (model: opus) with skills: video-storyboarding, terminal-demo-generator, remotion-composer, music-sfx-selection, thumbnail-first-frame, content-type-recipes, hook-formulas.

| Step | What Happens |
|---|---|
| **1. Storyboard** | `content-type-recipes` selects "Feature Demo" template. `video-storyboarding` generates scene breakdown. `hook-formulas` inserts attention patterns (hook, payoff, CTA). |
| **2. Assets** (parallel) | `terminal-demo-generator` creates VHS recordings for terminal scenes. Playwright captures UI scenes. |
| **3. Composition** | `remotion-composer` assembles clips into ScrapbookDemo composition. Renders both 16:9 and 1:1 variants. |
| **4. Audio** (parallel with step 5) | `music-sfx-selection` selects style and generates via Kling 3.0. Audio mixing: music at -18dB, SFX at -12dB. |
| **5. Thumbnail** | `thumbnail-first-frame` extracts frame, applies Scrapbook style. |
| **Final** | Merge audio + video, output files. |

### Hooks That Fire

Throughout the pipeline, several hooks fire automatically:

| Hook | Event | What It Does |
|---|---|---|
| `session-env-setup` | lifecycle/start | Detects `KLING_API_KEY`, `FAL_KEY`, `SUNO_API_KEY` availability |
| `dangerous-command-blocker` | pretool/bash | Validates VHS and ffmpeg commands before execution |
| `file-guard` | pretool/write | Prevents overwriting existing output files without confirmation |
| `audit-logger` | posttool/bash | Records every tool execution for pipeline reproducibility |
| `session-metrics` | posttool/bash | Tracks render times, file sizes, scene counts |

### The Scrapbook Motion Style

OrchestKit's video output follows the Anthropic "Scrapbook Motion" aesthetic, inspired by the Claude Opus 4 announcement video:

| Element | Specification |
|---|---|
| Background | Warm paper texture `#F0F0E8` (not dark) |
| Transitions | Fast cuts, 100-200ms, paper-fold effect |
| Typography | Tiempos serif for impact text, Inter sans-serif for data |
| Media | Mixed collage: terminal, browser, code, diagrams |
| Audio | Lo-fi ambient, electronic stings for transitions |
| Voiceover | None by default (clean, visual-first) |

This style ensures every video produced through OrchestKit has a consistent, professional look without requiring design skills.

### Remotion Composition Registry

OrchestKit registers 89 Remotion compositions. The two most commonly used for demo videos:

| Composition | Use Case | Outputs |
|---|---|---|
| `ScrapbookDemo` | Feature demos, tutorials | 16:9 + 1:1 |
| `ReleaseNotes` | Changelog and version highlights | 16:9 + 1:1 |

Each composition is a React component that accepts scene data (clips, overlays, timing) as props and renders a programmatic video. The scene data comes from `storyboard.json`, making every video fully reproducible.

### Kling 3.0 Capabilities

Kling 3.0 (launched February 4, 2026) is the primary video and audio engine:

| Feature | Specification |
|---|---|
| Resolution | Up to 4K at 60fps |
| Duration | Up to 15 seconds per clip |
| Audio | Native generation in 5 languages |
| Multi-shot | Up to 6 cuts per generation |
| Element Library | Reusable assets and overlays |

ElevenLabs serves as a backup TTS provider, used only when explicit narration is requested. HeyGen was deprecated in favor of Kling 3.0 for all video generation tasks.

## Tips

<Callout type="info">
**Reuse storyboards.** The `storyboard.json` output file contains the full scene breakdown. Pass it back for iteration: `/ork:demo-producer --storyboard ./output/storyboard.json` skips the storyboarding step and goes straight to rendering. Useful for tweaking individual scenes without regenerating everything.
</Callout>

<Callout type="info">
**Use 1:1 for social, 16:9 for presentations.** Both aspect ratios render by default. The 1:1 version is optimized for Twitter/LinkedIn feeds where square video gets more screen real estate. The 16:9 version is standard for YouTube, Slack, and slide decks.
</Callout>

<Callout type="warn">
**Large videos need disk space.** Remotion renders frame-by-frame. A 60-second video at 30fps generates 1800 frames as intermediate PNGs before encoding to MP4. Ensure at least 2 GB of free disk space for the render. Intermediate files are cleaned up automatically after encoding.
</Callout>

<Callout type="info">
**Add vertical video for TikTok and Reels.** Use the `--vertical` flag to generate a 9:16 output alongside the standard formats: `/ork:demo-producer --vertical "Demo the auth flow"`. The storyboarding skill automatically reframes scenes for portrait orientation, repositioning text overlays and cropping terminal recordings.
</Callout>

<Callout type="info">
**No API keys? No problem.** Without `KLING_API_KEY`, the pipeline still generates the video -- just without generated audio. You can add a royalty-free music track manually in any video editor, or re-run with the key later using the saved storyboard. The pipeline is designed for graceful degradation at every step.
</Callout>

<Callout type="info">
**Generate release videos from changelogs.** For release notes videos, pass your version tag: `/ork:demo-producer --type release-notes v6.0.2`. The agent reads your CHANGELOG.md, extracts highlights, and generates a ReleaseNotes composition automatically. No storyboarding step needed -- the changelog is the storyboard.
</Callout>

## Next Steps

- **[The 3 Building Blocks](/docs/foundations/skills-agents-hooks)** -- Understand how agents and skills connect
- **[Configuration](/docs/getting-started/configuration)** -- Set up `KLING_API_KEY` and other env vars
- **[Security Audit Cookbook](/docs/cookbook/security-audit)** -- Another multi-agent workflow in action

## 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.yonyon.ai/docs/cookbook/fix-github-issue](/docs/cookbook/fix-github-issue)

import { Callout } from 'fumadocs-ui/components/callout';

The `/ork:fix-issue` command turns a GitHub issue into a complete fix -- root cause analysis, implementation, tests, and a PR linked back to the issue. It is particularly effective for bugs that require investigation, because the `debug-investigator` agent systematically traces execution paths rather than guessing. This cookbook walks through fixing an intermittent authentication failure on mobile Safari.

## Scenario

A user reports issue #123: "Login fails intermittently on mobile Safari." The error is not consistent -- it works on Chrome, works on desktop Safari, and even works on mobile Safari about 70% of the time. Your team has spent 30 minutes in the issue thread theorizing, but nobody has reproduced it yet.

## What You'll Use

| Component | Type | Role |
|---|---|---|
| `/ork:fix-issue` | Command skill | Orchestrates the full investigation-to-PR workflow |
| `/ork:verify` | Command skill | Targeted verification of the fix |
| `/ork:commit` | Command skill | Conventional commit linked to issue |
| `debug-investigator` | Agent | Reproduces the bug, traces execution, identifies root cause |
| `backend-system-architect` | Agent | Designs the fix with minimal blast radius |
| `test-generator` | Agent | Writes regression tests for the specific failure |
| `security-auditor` | Agent | Validates the fix does not weaken auth |
| `memory-context-injector` | Hook | Searches memory for similar past issues |
| `skill-suggester` | Hook | Injects relevant debugging and auth skills |
| `issue-progress-tracking` | Hook | Posts progress updates to the GitHub issue |

---

## Step 1: Read the Issue and Choose an Approach

```bash
/ork:fix-issue 123
```

OrchestKit fetches the issue from GitHub using `gh issue view 123`, reads the title, body, labels, and all comments, then asks you to choose a fix approach:

```
Issue #123: "Login fails intermittently on mobile Safari"
  Labels: bug, auth, P1  |  Comments: 4  |  Assignee: none

Fix approach:

  [1] Proper fix     — Full investigation, root cause analysis, tests
  [2] Quick fix      — Minimal change, skip deep analysis
  [3] Investigate    — Analysis only, no code changes yet
  [4] Hotfix         — Emergency patch, skip PR review

> 1
```

Selecting **Proper fix** triggers the full 11-phase workflow.

<Callout type="info">
The "Investigate" option is useful when you are not sure the issue is a bug at all. It runs the analysis phases without writing any code, producing a root cause report you can share in the issue thread before deciding on a fix.
</Callout>

---

## Step 2: Parallel Analysis Phase

OrchestKit spawns the `debug-investigator` agent and runs three analysis tracks simultaneously:

Three analysis tracks run in parallel:

| Track | Details |
|---|---|
| **debug-investigator** (opus) | Skills: root-cause-analysis, pwa-patterns, auth-patterns. Reads issue body + 4 comments, traces auth flow (login → cookie → session validation → response), searches codebase for cookie/session config, checks Safari-specific edge cases. |
| **Memory search** | Query: "Safari" + "cookie" + "authentication". Found 2 past observations — `SameSite-cookie` pattern linked to `intermittent-auth-failures`: *"Safari rejects SameSite=None without Secure flag on localhost"* |
| **Git blame analysis** | Files: `auth/middleware.py`, `auth/config.py`. Cookie config last changed 12 days ago in commit `a3f8c2d`: *"chore: update cookie defaults"* |

The memory search is the key accelerator here. OrchestKit's knowledge graph already contains a pattern from a previous session noting that Safari has stricter cookie handling. This observation immediately narrows the investigation.

<Callout type="warn">
Memory compounds across sessions. If your team has never encountered a Safari cookie issue before, the analysis phase takes longer because the `debug-investigator` must trace the full execution path from scratch. The first investigation populates memory, making every subsequent similar issue faster.
</Callout>

---

## Step 3: Root Cause Analysis

The `debug-investigator` synthesizes findings from all three tracks into a root cause report:

```
Root Cause Analysis — Issue #123
=====================================================

Symptom:
  Login fails intermittently on mobile Safari.

Root Cause:
  The session cookie is set with SameSite=Lax (the default
  after commit a3f8c2d), but the login endpoint redirects
  through an OAuth callback that crosses origin boundaries.
  Safari treats cross-origin redirects as "unsafe" navigation
  and strips SameSite=Lax cookies from the request. This
  causes the session validation middleware to reject the
  request because the cookie is missing.

Why Intermittent:
  The failure only occurs when the user arrives from an
  external link (cross-origin navigation). Users who type
  the URL directly or use a bookmark (same-origin navigation)
  get SameSite=Lax cookies attached normally. This explains
  the ~70% success rate: most users navigate directly.

Affected Code:
  File: app/auth/config.py:18
    SESSION_COOKIE_SAMESITE = "lax"  # Changed from "none"
    SESSION_COOKIE_SECURE = True

  File: app/auth/middleware.py:42
    No fallback when cookie is missing from redirect flow.

Confidence: HIGH (memory corroborated, git blame confirmed)
```

OrchestKit posts a summary of this analysis as a comment on issue #123 via the `issue-progress-tracking` hook:

```
Posted to issue #123:
  "Root cause identified: SameSite=Lax cookie stripped during
   cross-origin OAuth redirect on Safari. Fix in progress."
```

---

## Step 4: Implement the Fix

The `backend-system-architect` agent designs a minimal fix based on the root cause:

```python
# app/auth/config.py (before)
SESSION_COOKIE_SAMESITE = "lax"
SESSION_COOKIE_SECURE = True

# app/auth/config.py (after)
SESSION_COOKIE_SAMESITE = "none"
SESSION_COOKIE_SECURE = True  # Required when SameSite=None
```

```python
# app/auth/middleware.py (added fallback)
async def validate_session(request: Request):
    session_id = request.cookies.get("session_id")

    # Fallback: check Authorization header when cookie is missing.
    # This handles cross-origin redirects where Safari strips cookies.
    if not session_id:
        auth_header = request.headers.get("Authorization")
        if auth_header and auth_header.startswith("Bearer "):
            session_id = await resolve_session_from_token(
                auth_header.removeprefix("Bearer ")
            )

    if not session_id:
        raise HTTPException(status_code=401, detail="Session required")

    return await get_session(session_id)
```

The fix has two parts: restore `SameSite=None` for the cookie (the direct fix) and add a fallback Authorization header path in the middleware (defense in depth). The `security-auditor` validates that `SameSite=None` combined with `Secure=True` is safe for production.

---

## Step 5: Regression Tests

The `test-generator` agent writes tests targeting the exact failure scenario:

```python
# tests/auth/test_safari_cookie.py
import pytest
from httpx import AsyncClient

@pytest.mark.asyncio
async def test_login_with_cross_origin_redirect(client: AsyncClient):
    """Regression test for issue #123: Safari strips SameSite cookies
    on cross-origin OAuth redirect."""
    # Simulate a request without session cookie (as Safari would send)
    response = await client.get(
        "/protected/resource",
        headers={"Authorization": "Bearer valid-session-token"},
    )
    assert response.status_code == 200

@pytest.mark.asyncio
async def test_login_without_cookie_or_header(client: AsyncClient):
    """Verify that missing both cookie and header returns 401."""
    response = await client.get("/protected/resource")
    assert response.status_code == 401

@pytest.mark.asyncio
async def test_samesite_cookie_attribute(client: AsyncClient):
    """Verify cookie is set with SameSite=None; Secure."""
    response = await client.post("/auth/login", json={
        "email": "test@example.com",
        "password": "test-password",
    })
    cookie_header = response.headers.get("set-cookie", "")
    assert "SameSite=None" in cookie_header
    assert "Secure" in cookie_header
```

---

## Step 6: Verify, Commit, and Create PR

```bash
/ork:verify
```

OrchestKit runs targeted verification against the changed files:

```
Verification Results (targeted)
=====================================================

  Tests:     10/10   3 new + 22 existing passed, 0 failed
  Security:  10/10   SameSite=None with Secure flag validated
  Quality:    9/10   Clean diff, minimal blast radius

  Overall:   9.7/10
```

```bash
/ork:commit
```

```
Commit message:
  fix(auth): handle Safari SameSite cookie policy on cross-origin redirect

  Safari strips SameSite=Lax cookies during cross-origin OAuth redirects,
  causing intermittent login failures. Restore SameSite=None (with Secure)
  and add Authorization header fallback in session middleware.

  Closes #123

  Co-Authored-By: Claude <noreply@anthropic.com>

Proceed? [Y/n]
```

The `Closes #123` trailer is added automatically because OrchestKit knows which issue triggered the workflow.

```bash
/ork:create-pr
```

```
Created PR #89: fix(auth): handle Safari SameSite cookie policy

  ## Summary
  - Restore SameSite=None on session cookie for cross-origin compat
  - Add Authorization header fallback in session middleware
  - 3 regression tests for the Safari-specific failure

  ## Root Cause
  Safari strips SameSite=Lax cookies on cross-origin OAuth redirects.
  See issue #123 for full investigation.

  ## Test Plan
  - [x] Regression test: cross-origin redirect without cookie
  - [x] Regression test: missing both cookie and header -> 401
  - [x] Regression test: SameSite=None; Secure attribute verified
  - [x] Security validation: SameSite=None is safe with Secure flag
  - [ ] Manual: test on mobile Safari via BrowserStack

  Closes #123

  https://github.com/your-org/your-repo/pull/89
```

---

## Behind the Scenes

### The 11-Phase Workflow

The `/ork:fix-issue` command with "Proper fix" runs through these phases:

| Phase | Action | Agent |
|---|---|---|
| 1 | Fetch issue metadata from GitHub | -- |
| 2 | Read issue body and all comments | -- |
| 3 | Search memory for similar past issues | `memory-context-injector` |
| 4 | Analyze git blame on affected files | `debug-investigator` |
| 5 | Trace execution path to identify root cause | `debug-investigator` |
| 6 | Post root cause summary to issue | `issue-progress-tracking` |
| 7 | Design the fix | `backend-system-architect` |
| 8 | Security review of the fix | `security-auditor` |
| 9 | Write regression tests | `test-generator` |
| 10 | Run verification | parallel agents |
| 11 | Commit and create PR linked to issue | -- |

Phases 3-5 run in parallel during the analysis step. Phases 7-9 run sequentially because each depends on the previous output. Phase 10 spawns parallel verification agents.

### Hooks That Fired

| Hook | When | What It Did |
|---|---|---|
| `skill-suggester` | Issue fetched | Detected "Safari" and "login" keywords, injected `pwa-patterns` and `auth-patterns` skills |
| `memory-context-injector` | Analysis start | Searched graph for "Safari" + "cookie", found previous SameSite pattern |
| `issue-progress-tracking` | Root cause found | Posted analysis summary as comment on issue #123 |
| `dangerous-command-blocker` | During git blame | Validated the git commands were read-only |
| `auto-lint` | After fix written | Formatted the changed Python files with `ruff format` |
| `auto-remember-continuity` | Session end | Stored "Safari SameSite=Lax breaks cross-origin OAuth" in memory |

### Memory Made This Faster

The knowledge graph already contained a `SameSite-cookie` pattern entity from a previous debugging session. Without that memory, the `debug-investigator` would have needed to research Safari cookie behavior from scratch -- adding 30-60 seconds to the analysis phase. With memory, the agent corroborated the pattern against the codebase in under 10 seconds.

After this fix, the memory is enriched: the `SameSite-cookie` entity now has an additional observation linking it to OAuth redirects specifically, making future investigations even faster.

---

## Tips

<Callout type="info">
**Use "Investigate" for unclear issues.** If the issue title is vague or the root cause is uncertain, choose option 3 (Investigate). You get the full analysis without any code changes, so you can share the root cause report in the issue thread and discuss with your team before committing to a fix approach.
</Callout>

<Callout type="info">
**Memory carries across projects.** The SameSite cookie pattern stored here will surface in any future project where OrchestKit encounters a similar Safari issue. Use `/ork:remember --global` for patterns that apply universally across all your repositories.
</Callout>

<Callout type="warn">
**Hotfix mode skips PR review.** Option 4 (Hotfix) commits directly to a hotfix branch and merges without waiting for review. Use it only for production-down emergencies. The security auditor still runs, but test verification is skipped in favor of speed.
</Callout>

<Callout type="info">
**Issue progress comments keep your team informed.** The `issue-progress-tracking` hook posts status updates directly to the GitHub issue thread as the workflow progresses. Your teammates can follow along without asking "any updates?" -- they see the root cause analysis posted in real time.
</Callout>

<Callout type="info">
**The `Closes #123` trailer is automatic.** OrchestKit detects that the fix was triggered by `/ork:fix-issue 123` and appends the GitHub closing keyword to the commit message and PR body. When the PR merges, GitHub closes the issue automatically.
</Callout>

## Implement a Feature

From idea to merged PR with parallel AI agents — a complete walkthrough of the /ork:implement workflow.

[https://orchestkit.yonyon.ai/docs/cookbook/implement-feature](/docs/cookbook/implement-feature)

import { Callout } from 'fumadocs-ui/components/callout';
import { Files, Folder, File } from 'fumadocs-ui/components/files';

The `/ork:implement` command is OrchestKit's flagship workflow. It takes a feature description, breaks it into tasks, spawns parallel agents, and shepherds the work all the way to a merged pull request. This cookbook walks through a realistic example: adding JWT authentication to a FastAPI application.

## Scenario

Your team needs JWT-based authentication for a FastAPI backend. The requirements include login and registration endpoints, token refresh, middleware for protected routes, and proper password hashing. Instead of implementing each piece manually, you describe the feature and let OrchestKit orchestrate the work.

## What You'll Use

| Component | Type | Role |
|---|---|---|
| `/ork:implement` | Command skill | Orchestrates the full workflow |
| `/ork:verify` | Command skill | Parallel verification (tests, security, quality) |
| `/ork:commit` | Command skill | Conventional commit with scope |
| `/ork:create-pr` | Command skill | PR with summary and test plan |
| `backend-system-architect` | Agent | Designs auth endpoints, middleware, JWT flow |
| `test-generator` | Agent | Writes unit and integration tests |
| `security-auditor` | Agent | Scans for OWASP vulnerabilities |
| `code-quality-reviewer` | Agent | Style, patterns, complexity check |
| `dangerous-command-blocker` | Hook | Prevents destructive commands |
| `auto-lint` | Hook | Formats code on save |
| `file-guard` | Hook | Warns about sensitive files |
| `skill-suggester` | Hook | Injects relevant reference skills |

---

## Step 1: Launch the Implementation

```bash
/ork:implement "Add JWT authentication to the API"
```

OrchestKit does not start coding immediately. It first asks you to scope the work using `AskUserQuestion`:

```
How should I approach this implementation?

  [1] Full-stack     — Backend auth + frontend login/signup UI
  [2] Backend only   — Auth endpoints, middleware, JWT tokens
  [3] Frontend only  — Login/signup UI against existing API
  [4] Quick prototype — Minimal working auth, iterate later

> 2
```

After you select **Backend only**, OrchestKit creates a task plan via `TaskCreate` and spawns three parallel agents.

### Parallel Agent Execution

| Agent | Model | Skills Injected | Output |
|---|---|---|---|
| `backend-system-architect` | opus | api-design, python-backend, security-patterns, architecture-patterns | Endpoints, middleware, schemas |
| `test-generator` | sonnet | testing-unit, testing-integration | Unit + integration tests |
| `security-auditor` | opus | security-patterns | Vulnerability scan, recommendations |

All three agents work simultaneously, then **results are merged**. The `backend-system-architect` designs the implementation while `test-generator` writes tests and `security-auditor` reviews the approach for vulnerabilities. No agent waits for another.

<Callout type="info">
Parallel agents share the same project context but write to different files. OrchestKit uses `TaskCreate` with `addBlockedBy` dependencies to prevent file conflicts -- tests depend on the implementation being written first, but the security scan runs independently from the start.
</Callout>

### What Gets Created

After the agents finish, your project tree gains these files:

<Files>
  <Folder name="app" defaultOpen>
    <Folder name="auth" defaultOpen>
      <File name="__init__.py" />
      <File name="router.py" />
      <File name="dependencies.py" />
      <File name="schemas.py" />
      <File name="service.py" />
      <File name="config.py" />
    </Folder>
    <Folder name="core">
      <File name="security.py" />
    </Folder>
  </Folder>
  <Folder name="tests" defaultOpen>
    <Folder name="auth" defaultOpen>
      <File name="test_router.py" />
      <File name="test_service.py" />
      <File name="test_dependencies.py" />
      <File name="conftest.py" />
    </Folder>
    <Folder name="integration">
      <File name="test_auth_flow.py" />
    </Folder>
  </Folder>
</Files>

---

## Step 2: Review the Generated Code

Before verifying, look at what was produced. The `backend-system-architect` follows patterns from the `api-design-framework` skill -- endpoints use plural nouns, error responses follow RFC 9457 Problem Details, and tokens use short-lived access with long-lived refresh:

```python
# app/auth/router.py (simplified)
from fastapi import APIRouter, Depends, HTTPException, status
from app.auth.schemas import LoginRequest, TokenResponse, UserCreate
from app.auth.service import AuthService
from app.auth.dependencies import get_current_user

router = APIRouter(prefix="/auth", tags=["authentication"])

@router.post("/register", response_model=TokenResponse, status_code=201)
async def register(payload: UserCreate, auth: AuthService = Depends()):
    user = await auth.register(payload)
    return auth.create_token_pair(user.id)

@router.post("/login", response_model=TokenResponse)
async def login(payload: LoginRequest, auth: AuthService = Depends()):
    user = await auth.authenticate(payload.email, payload.password)
    if not user:
        raise HTTPException(status_code=401, detail="Invalid credentials")
    return auth.create_token_pair(user.id)

@router.post("/refresh", response_model=TokenResponse)
async def refresh(token: str, auth: AuthService = Depends()):
    return await auth.refresh_token(token)
```

<Callout type="warn">
The security auditor flags any hardcoded secrets it finds. If your `config.py` contains a default JWT secret like `"changeme"`, you will see a P0 finding in Step 3 instructing you to use an environment variable instead.
</Callout>

---

## Step 3: Verify Everything

```bash
/ork:verify
```

OrchestKit asks what level of verification you want:

```
Verification scope:

  [1] Full       — Tests + security + code quality + performance
  [2] Quick      — Tests + lint only
  [3] Security   — Security-focused deep scan
  [4] Pre-merge  — Everything, plus changelog and docs check

> 1
```

Selecting **Full** spawns four parallel agents:

| Agent | Check |
|---|---|
| `test-runner` | `pytest -x --tb=short` |
| `security-auditor` | OWASP scan + secrets detection |
| `code-quality-reviewer` | Complexity, style, patterns |
| `frontend-performance-engineer` | N+1 queries, startup cost |

All four run in parallel, producing a **unified scorecard** (0-10 per category):

The output is a scorecard:

```
Verification Results
=====================================================

  Tests:        9/10   25 passed, 0 failed, 2 skipped
  Security:     8/10   0 P0, 1 P1 (rate limiting recommended)
  Quality:      9/10   Cyclomatic complexity OK, clean imports
  Performance:  7/10   Token creation could cache JWK

  Overall:      8.3/10

Recommendations:
  [P1] Add rate limiting to /auth/login (brute force protection)
  [P2] Cache JWK set instead of reloading on each request
  [P2] Add request_id to error responses for traceability

Proceed to commit? [Y/n]
```

---

## Step 4: Commit

```bash
/ork:commit
```

OrchestKit analyzes the diff, detects the scope from changed files, and generates a conventional commit:

```
Analyzing staged changes...

  14 files changed, 487 insertions(+)

Commit message:
  feat(auth): add JWT authentication with login, register, and refresh

  Implement complete auth flow with bcrypt password hashing,
  short-lived access tokens (15m), and refresh token rotation.
  Includes 25 unit/integration tests and OAuth2 middleware.

  Co-Authored-By: Claude <noreply@anthropic.com>

Proceed? [Y/n]
```

---

## Step 5: Create the Pull Request

```bash
/ork:create-pr
```

OrchestKit generates a PR with a structured summary and test plan:

```
Created PR #47: feat(auth): add JWT authentication

  ## Summary
  - JWT auth with login, register, and token refresh endpoints
  - OAuth2PasswordBearer middleware for protected routes
  - bcrypt password hashing with configurable rounds
  - 25 tests covering happy paths, error cases, and token expiry

  ## Test Plan
  - [x] Unit tests: auth service, token creation, password hashing
  - [x] Integration tests: full register-login-refresh flow
  - [x] Security scan: no P0 findings
  - [ ] Manual: test with Postman/curl against dev environment

  https://github.com/your-org/your-repo/pull/47
```

---

## Behind the Scenes

Here is what happened invisibly during this workflow.

### Hooks That Fired

| Hook | When | What It Did |
|---|---|---|
| `skill-suggester` | Step 1 prompt | Detected "JWT" and "authentication" keywords, injected `security-patterns` and `python-backend` reference skills into agent context |
| `dangerous-command-blocker` | During coding | Blocked an `rm -rf` that would have wiped the existing `tests/` directory |
| `file-guard` | During coding | Warned when agent attempted to write `.env` with a JWT secret -- redirected to `.env.example` |
| `auto-lint` | After each file write | Ran `ruff format` on every Python file the agents created |
| `git-validator` | Step 4 commit | Verified the branch name and checked for uncommitted secrets |
| `security-command-audit` | Step 3 verify | Logged the security scan results to session metrics |
| `auto-remember-continuity` | Session end | Stored "JWT auth implemented with refresh rotation" in the knowledge graph for future sessions |

### Skills Auto-Injected

Several reference skills were loaded across the three agents without any explicit invocation:

- `api-design` -- REST endpoint patterns, HTTP status codes
- `python-backend` -- FastAPI, middleware, dependency injection patterns
- `security-patterns` -- OWASP Top 10, defense-in-depth, input validation
- `architecture-patterns` -- Clean architecture, separation of concerns
- `testing-unit` -- Fixtures, parametrize, mocking, data factories
- `testing-integration` -- API endpoint tests, database tests, contract testing
- `testing-e2e` -- Playwright, page objects, visual regression
- `database-patterns` -- Schema design, migrations, query optimization

---

## Tips

<Callout type="info">
**Start narrow, expand later.** Choose "Backend only" or "Quick prototype" scope first. You can always run `/ork:implement` again to add frontend auth or additional features. Each run is additive.
</Callout>

<Callout type="info">
**Memory compounds over time.** After this implementation, OrchestKit remembers that your project uses JWT with refresh rotation. Next time you work on auth-related code, this context is automatically injected -- no need to explain your auth strategy again.
</Callout>

<Callout type="warn">
**Always run `/ork:verify` before committing.** The parallel verification catches issues that a single-agent review would miss. The security auditor once caught a timing attack vulnerability in password comparison that the quality reviewer did not flag.
</Callout>

<Callout type="info">
**Check the scorecard thresholds.** A score below 6/10 in any category means there are blocking issues. Fix those before committing. Scores of 7-8 indicate suggestions worth considering. Scores of 9-10 mean the category is clean.
</Callout>

## Cookbook

Step-by-step workflow walkthroughs for common development tasks with OrchestKit.

[https://orchestkit.yonyon.ai/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

<Cards>
  <Card title="Implement a Feature" href="/docs/cookbook/implement-feature" description="End-to-end feature implementation with parallel agents" />
  <Card title="Review a PR" href="/docs/cookbook/review-pr" description="Multi-agent code review with security, performance, and style checks" />
  <Card title="Fix a GitHub Issue" href="/docs/cookbook/fix-github-issue" description="From issue triage to verified fix with automated testing" />
  <Card title="Set Up Memory" href="/docs/cookbook/setup-memory" description="Configure the 3-tier memory system for persistent context" />
  <Card title="Create a Demo Video" href="/docs/cookbook/create-demo-video" description="Produce polished demo videos with Kling 3.0 and Remotion" />
  <Card title="Security Audit" href="/docs/cookbook/security-audit" description="Run OWASP Top 10 checks and defense-in-depth verification" />
</Cards>

## By Role

Pick your role for curated workflows and agent recommendations:

<Cards>
  <Card title="Backend Developer" href="/docs/cookbook/roles/backend-developer" description="FastAPI, SQLAlchemy, API design patterns" />
  <Card title="Frontend Developer" href="/docs/cookbook/roles/frontend-developer" description="React 19, TypeScript, component patterns" />
  <Card title="DevOps Engineer" href="/docs/cookbook/roles/devops-engineer" description="CI/CD, Terraform, Kubernetes, monitoring" />
  <Card title="AI Engineer" href="/docs/cookbook/roles/ai-engineer" description="RAG, LangGraph, embeddings, fine-tuning" />
  <Card title="Tech Lead" href="/docs/cookbook/roles/tech-lead" description="Architecture decisions, code review, team workflows" />
  <Card title="Security Engineer" href="/docs/cookbook/roles/security-engineer" description="Vulnerability scanning, compliance, incident response" />
</Cards>

## Review a Pull Request

AI-powered code review with 6 parallel specialized agents that catch security, performance, and quality issues.

[https://orchestkit.yonyon.ai/docs/cookbook/review-pr](/docs/cookbook/review-pr)

import { Callout } from 'fumadocs-ui/components/callout';

The `/ork:review-pr` command runs a multi-agent code review against any pull request. Six specialized agents analyze the diff in parallel, each focused on a different dimension of code quality. The results are synthesized into a single, actionable PR comment. This cookbook walks through reviewing a payment processing PR.

## Scenario

A teammate opens PR #42 that adds a Stripe payment processing endpoint to your FastAPI backend. The PR is 420 lines across 9 files: a new router, service layer, webhook handler, database migration, and tests. You want a thorough review before merging code that handles real money.

## What You'll Use

| Component | Type | Role |
|---|---|---|
| `/ork:review-pr` | Command skill | Orchestrates the multi-agent review |
| `code-quality-reviewer` | Agent | Style, patterns, complexity |
| `security-auditor` | Agent | Injection, XSS, secrets, OWASP |
| `test-generator` | Agent | Missing test coverage |
| `frontend-performance-engineer` | Agent | N+1 queries, bundle size, latency |
| `backend-system-architect` | Agent | API design, error handling, contracts |
| `accessibility-specialist` | Agent | A11y issues (if frontend changes present) |
| `pr-size-warning` | Hook | Detects large PRs and warns about review difficulty |
| `security-command-audit` | Hook | Logs security findings |
| `skill-suggester` | Hook | Injects payment and Stripe reference skills |

---

## Step 1: Start the Review

```bash
/ork:review-pr 42
```

OrchestKit fetches the PR metadata from GitHub using `gh pr view 42` and asks for your review focus:

```
PR #42: "Add Stripe payment processing endpoint"
  Author: @teammate  |  +312 / -108  |  9 files  |  base: main

Review focus:

  [1] Full        — All 6 agents: security, quality, tests, performance, design, a11y
  [2] Security    — Deep security-only scan (2 agents)
  [3] Performance — Latency, queries, resource usage
  [4] Quick       — Quality + tests only (fast, 2 agents)

> 1
```

Selecting **Full** launches all six agents against the PR diff.

---

## Step 2: Six Parallel Agents Analyze the Diff

After fetching the diff (9 changed files, 420 lines), six agents launch in parallel:

| Agent | Skills | Focus |
|---|---|---|
| `code-quality-reviewer` | code-review-playbook, clean-architecture | Naming, complexity, DRY, patterns |
| `security-auditor` | owasp-top-10, defense-in-depth, input-validation, security-scanning | Injection, auth bypass, exposed secrets |
| `test-generator` | pytest-advanced, integration-testing | Missing coverage, edge cases, mocks |
| `frontend-performance-engineer` | performance-optimization, caching-strategies | N+1 queries, connection pooling, latency |
| `backend-system-architect` | api-design-framework, error-handling-rfc9457 | API contracts, error responses |
| `accessibility-specialist` | wcag-patterns, aria-guidelines | a11y (skipped — no frontend files) |

All results are **synthesized** into a single structured review.

Each agent receives the full diff plus relevant skill context. The `accessibility-specialist` detects that all 9 changed files are backend Python files, reports "no frontend changes detected", and completes in under a second. The remaining five agents work in parallel.

<Callout type="info">
The `pr-size-warning` hook fires immediately when it counts 420 changed lines. It injects a note into the review context: "Large PR (420 lines). Consider whether this should have been split into smaller PRs." This note appears in the final review output.
</Callout>

---

## Step 3: Review Results

After all agents complete (typically 30-90 seconds for a full review), OrchestKit synthesizes their findings into a structured report:

```
PR #42 Review — "Add Stripe payment processing endpoint"
=====================================================

Quality:      8/10
Security:     6/10   <- 1 P0, 2 P1 findings
Tests:        7/10   3 missing test cases identified
Performance:  9/10   No N+1 queries detected
Design:       8/10   1 API contract suggestion
A11y:         --     No frontend changes

------------------------------------------------------

SECURITY (security-auditor)

  [P0] Webhook signature not verified
       File: app/payments/webhook.py:34
       The Stripe webhook handler processes events without
       verifying the signature header. An attacker could forge
       webhook payloads to credit accounts.
       Fix: Use stripe.Webhook.construct_event() with your
       webhook signing secret.

  [P1] Stripe secret key in default parameter
       File: app/payments/config.py:12
       STRIPE_SECRET_KEY has a default value of "sk_test_..."
       in the config. This will leak to version control.
       Fix: Remove the default. Require it via env variable
       with no fallback.

  [P1] No idempotency key on charge creation
       File: app/payments/service.py:67
       stripe.PaymentIntent.create() is called without an
       idempotency_key. Network retries could create duplicate
       charges.
       Fix: Accept an idempotency key from the client or
       generate one from the order ID.

------------------------------------------------------

QUALITY (code-quality-reviewer)

  [Suggestion] Extract Stripe client initialization
       File: app/payments/service.py:15-22
       Stripe is initialized inline in three methods. Extract
       to a shared dependency or lifespan handler.

  [Suggestion] PaymentService has 8 methods (complexity: medium)
       Consider splitting webhook handling into a separate
       WebhookService class.

------------------------------------------------------

TESTS (test-generator)

  Missing test cases:
    1. Webhook with invalid signature -> should return 400
    2. Duplicate payment intent (idempotency) -> should not double-charge
    3. Stripe API timeout -> should return 502 with retry-after

  Coverage estimate: 74% (target: 85%)

------------------------------------------------------

DESIGN (backend-system-architect)

  [Suggestion] POST /payments/charge returns 200 on success
       Recommend 201 Created with a Location header pointing
       to the payment resource: /payments/{payment_id}

------------------------------------------------------

PR SIZE WARNING: 420 lines across 9 files. Consider splitting
webhook handling into a separate PR for easier review.
```

---

## Step 4: Post to GitHub

OrchestKit asks whether to post the review as a PR comment:

```
Post this review as a comment on PR #42? [Y/n]
> Y

Review posted to PR #42
  https://github.com/your-org/your-repo/pull/42#issuecomment-1234567
```

The comment uses GitHub markdown with collapsible sections for each category, so it does not overwhelm the PR conversation. Security P0 findings are always expanded and highlighted.

<Callout type="warn">
P0 security findings block the review with a "Changes Requested" status. P1 findings are flagged but do not block. P2 findings are informational suggestions. The webhook signature vulnerability in this example is a P0 -- the PR should not merge until it is fixed.
</Callout>

---

## Behind the Scenes

### How the Review Diff is Distributed

OrchestKit does not send the entire diff to every agent. It routes files intelligently:

| Agent | Files Received | Rationale |
|---|---|---|
| `security-auditor` | All 9 files | Security must see everything |
| `code-quality-reviewer` | All 9 files | Style applies everywhere |
| `test-generator` | Test files + source files they test | Needs both to assess coverage |
| `frontend-performance-engineer` | Service + migration files | Where query and latency issues live |
| `backend-system-architect` | Router + schema files | API surface area |
| `accessibility-specialist` | Frontend files only | Skipped when none exist |

### Hooks That Fired

| Hook | When | What It Did |
|---|---|---|
| `pr-size-warning` | PR fetched | Detected 420 lines, injected size warning into review |
| `skill-suggester` | Review started | Detected "payment" and "Stripe" keywords, injected `input-validation` and `api-design-framework` reference skills |
| `security-command-audit` | After security scan | Logged the P0 finding to session metrics and audit trail |
| `auto-remember-continuity` | Review complete | Stored "PR #42 has unverified webhook signatures" in memory for follow-up |

### Security Severity Levels

Each security finding is assigned a severity that maps to review actions:

| Severity | Meaning | Review Action |
|---|---|---|
| P0 | Exploitable vulnerability | Changes Requested -- blocks merge |
| P1 | Real issue, requires specific conditions | Flagged -- fix before production |
| P2 | Hardening suggestion | Informational -- consider improving |

### Skills Auto-Injected

Each agent received its standard skill set plus context-specific skills detected by the `skill-suggester` hook:

- `code-review-playbook` -- Structured review methodology
- `owasp-top-10` -- Common web vulnerability patterns
- `defense-in-depth` -- Layered security approach
- `api-design-framework` -- REST conventions, status codes, error formats
- `error-handling-rfc9457` -- Problem Details standard
- `pytest-advanced` -- Test patterns, fixtures, parametrize
- `performance-optimization` -- N+1 detection, bundle analysis
- `clean-architecture` -- Separation of concerns, dependency boundaries

---

## Tips

<Callout type="info">
**Use "Quick" for small PRs.** If the PR is under 100 lines and touches well-tested code, the Quick review (quality + tests only) runs in under 15 seconds. Save the Full review for complex or sensitive changes.
</Callout>

<Callout type="info">
**Re-review after fixes.** After the author pushes fixes for the P0 finding, run `/ork:review-pr 42` again. OrchestKit fetches the updated diff and verifies the fixes are correct. It also checks that the fix did not introduce new issues.
</Callout>

<Callout type="warn">
**Security findings use severity levels intentionally.** P0 means "do not merge" -- the code has a vulnerability that could be exploited. P1 means "fix before production" -- the issue is real but requires specific conditions. P2 means "consider improving" -- a hardening suggestion rather than a vulnerability.
</Callout>

<Callout type="info">
**Combine with `/ork:verify` for pre-merge confidence.** Run `/ork:review-pr` for the review comment, then `/ork:verify` locally to confirm tests pass and the security scan is clean. This catches issues that a diff-only review cannot detect, such as tests that pass individually but fail together.
</Callout>

## Run a Security Audit

8-layer defense-in-depth verification for your codebase.

[https://orchestkit.yonyon.ai/docs/cookbook/security-audit](/docs/cookbook/security-audit)

import { Callout } from 'fumadocs-ui/components/callout';

## Scenario

Your app is a week away from production launch. The FastAPI backend handles user authentication, payment processing, and file uploads. The React frontend consumes 14 API endpoints. You have 200+ tests passing, but nobody has done a dedicated security review.

You know the OWASP Top 10 exists. You know you should check for SQL injection, XSS, and hardcoded secrets. But manually scanning every endpoint, dependency, and configuration file would take days -- and you would still miss things a specialist would catch.

OrchestKit runs a **defense-in-depth security audit** that checks 8 layers in parallel, returns findings by severity with file-and-line references, and grades each layer on a 0-10 scale. The entire audit takes 2-5 minutes depending on codebase size.

## What You'll Use

| Component | Type | Purpose |
|---|---|---|
| `/ork:verify --scope=security` | Command skill | Launches security-focused verification |
| `security-auditor` | Agent (opus) | OWASP Top 10 scan, dependency audit, secrets detection |
| `code-quality-reviewer` | Agent | Identifies unsafe code patterns and complexity |
| `debug-investigator` | Agent | Traces data flow for injection points |
| `dangerous-command-blocker` | Hook (pretool) | Prevents destructive commands during audit |
| `file-guard` | Hook (pretool) | Blocks commits of `.env`, `*.pem`, credentials |
| `security-command-audit` | Hook (posttool) | Logs all security scan results to audit trail |
| `owasp-top-10` | Reference skill | OWASP vulnerability patterns and fixes |
| `defense-in-depth` | Reference skill | Layered security architecture patterns |
| `input-validation` | Reference skill | Injection prevention at every boundary |
| `auth-patterns` | Reference skill | JWT, OAuth, session management patterns |
| `llm-safety-patterns` | Reference skill | Prompt injection and LLM-specific threats |

## The 8 Defense-in-Depth Layers

OrchestKit's security audit evaluates your application across 8 distinct layers. Each layer represents a security boundary where attacks can be detected and stopped. A weakness at one layer does not compromise the system if the other seven hold.

| Layer | What It Checks | Example Findings |
|---|---|---|
| **1. Edge** | Rate limiting, WAF rules, DDoS protection | No rate limit on `/auth/login`, missing request size caps |
| **2. Transport** | TLS configuration, HSTS, certificate pinning | HTTP allowed in production, missing `Strict-Transport-Security` |
| **3. Authentication** | JWT validation, session management, MFA | Weak JWT secret, no token expiry, missing refresh rotation |
| **4. Authorization** | RBAC, resource-level permissions, policy enforcement | IDOR on `/api/documents/{id}`, missing ownership checks |
| **5. Input Validation** | SQL injection, XSS, command injection, path traversal | f-string SQL query, `innerHTML` with user input, `shell=True` |
| **6. Business Logic** | IDOR, mass assignment, race conditions | Price manipulation via request body, TOCTOU on inventory |
| **7. Data** | Encryption at rest, PII handling, backup security | Plaintext passwords in logs, PII in error responses |
| **8. Monitoring** | Audit logs, anomaly detection, incident response | No failed-login tracking, missing structured logging |

## Step-by-Step

### Step 1: Launch the Security Audit

Start with the verify command scoped to security:

```bash
/ork:verify --scope=security
```

OrchestKit asks for the audit depth:

```
Security Audit Scope:

  [1] Quick scan      — Dependency audit + secrets detection (2 min)
  [2] Standard audit  — OWASP Top 10 + dependencies + patterns (5 min)
  [3] Deep audit      — Full 8-layer analysis with data flow tracing (10 min)

> 3
```

Choose **Deep audit** for a pre-launch review. The quick scan is useful for day-to-day checks after changes.

### Step 2: Three Parallel Agents Scan Your Codebase

Once you select the audit depth, OrchestKit spawns three agents simultaneously:

| Agent | Model | Skills Injected | Tasks |
|---|---|---|---|
| **security-auditor** | opus | owasp-top-10, defense-in-depth, auth-patterns, input-validation, llm-safety-patterns, security-scanning, mcp-security-hardening | Run bandit for Python vulns, npm/pip audit for CVEs, grep for secrets, check OWASP Top 10 per endpoint, validate JWT/session security |
| **code-quality-reviewer** | sonnet | code-review-playbook, clean-architecture | Identify unsafe patterns (eval, exec, pickle), check complexity hiding vulns, flag missing error handling |
| **debug-investigator** | sonnet | input-validation | Trace user input from request to DB, map data flow for injection points, identify unvalidated boundaries |

All three run in parallel, then **results are merged** into a unified security report.

The `security-auditor` runs automated tools (bandit, pip-audit, npm audit). The `code-quality-reviewer` analyzes code patterns. The `debug-investigator` traces data flow from request input to storage to find gaps the automated tools miss.

<Callout type="info">
The `security-auditor` agent uses parallel tool calls internally. It runs `bandit -r backend/`, `pip-audit`, `npm audit`, and secret-pattern grep all at the same time -- cutting scan time by roughly 60% compared to sequential execution.
</Callout>

### Step 3: Review the Security Scorecard

After all agents complete (typically 2-10 minutes depending on codebase size and audit depth), OrchestKit synthesizes findings into a graded scorecard:

```
Security Audit Results
===========================================================

  Layer 1 — Edge:            7/10   Rate limiting missing on 3 endpoints
  Layer 2 — Transport:       9/10   HSTS configured, TLS 1.3 enforced
  Layer 3 — Authentication:  6/10   1 P0: JWT secret too short (32 chars)
  Layer 4 — Authorization:   5/10   1 P0: IDOR on /api/documents/{id}
  Layer 5 — Input Validation:8/10   1 P1: Missing Zod validation on webhook
  Layer 6 — Business Logic:  7/10   1 P1: Race condition on inventory update
  Layer 7 — Data:            8/10   PII redacted in logs, encryption at rest OK
  Layer 8 — Monitoring:      4/10   No structured logging, no failed-login alerts

  Overall Security Score:    6.8/10

===========================================================

P0 CRITICAL (fix before launch — 2 findings)

  [SEC-001] JWT secret is only 32 characters
       Layer: Authentication (3)
       File: app/auth/config.py:8
       Code: JWT_SECRET = os.getenv("JWT_SECRET", "a" * 32)
       Risk: Brute-forceable secret enables token forgery
       Fix:  Use a 256-bit (64-char hex) secret with no default value.
             Remove the fallback entirely — fail on startup if missing.
       OWASP: A02:2021 — Cryptographic Failures

  [SEC-002] Direct object reference without ownership check
       Layer: Authorization (4)
       File: app/api/routes/documents.py:23
       Code: doc = db.query(Document).get(doc_id)
       Risk: Any authenticated user can read any document by ID
       Fix:  Add ownership check: if doc.owner_id != current_user.id
       OWASP: A01:2021 — Broken Access Control

-----------------------------------------------------------

P1 HIGH (fix before production traffic — 3 findings)

  [SEC-003] No rate limiting on /auth/login
       Layer: Edge (1)
       File: app/auth/router.py:18
       Risk: Enables brute-force password attacks
       Fix:  Add slowapi or custom rate limiter: 5 attempts/minute

  [SEC-004] Webhook payload not validated with Zod/Pydantic
       Layer: Input Validation (5)
       File: app/payments/webhook.py:12
       Risk: Malformed payloads bypass type checking
       Fix:  Add Pydantic model for webhook body validation

  [SEC-005] Race condition on inventory decrement
       Layer: Business Logic (6)
       File: app/orders/service.py:45
       Risk: Concurrent requests can oversell inventory
       Fix:  Use SELECT ... FOR UPDATE or optimistic locking

-----------------------------------------------------------

P2 MEDIUM (fix within one week — 4 findings)

  [SEC-006] No structured logging for auth events
       Layer: Monitoring (8)
       File: app/auth/router.py
       Risk: Cannot detect or investigate brute-force attempts
       Fix:  Log login success/failure with user ID and IP

  [SEC-007] Missing Content-Security-Policy header
       Layer: Transport (2)
       Fix:  Add CSP header via middleware

  [SEC-008] Error responses include stack traces in non-debug mode
       Layer: Data (7)
       File: app/core/exceptions.py:34
       Fix:  Return generic error message; log details server-side

  [SEC-009] pip-audit: aiohttp 3.8.4 has CVE-2024-23334
       Layer: Edge (1)
       Fix:  Upgrade to aiohttp >= 3.9.2

-----------------------------------------------------------

Dependencies:
  Python (pip-audit): 1 vulnerable, 3 outdated
  JavaScript (npm audit): 0 critical, 2 moderate

Secrets Scan:
  0 hardcoded secrets detected
  .env in .gitignore: YES
  .env.example contains no real values: YES
```

Each finding includes a severity (P0/P1/P2), the defense layer it belongs to, exact file and line reference, the vulnerable code, a concrete fix, and the OWASP category.

### Step 4: Understand the Severity Levels

Findings use three severity levels that map to clear action timelines:

| Severity | Meaning | Action | SLA |
|---|---|---|---|
| **P0 Critical** | Exploitable vulnerability, data breach risk | Fix immediately, block launch | Before merge |
| **P1 High** | Real vulnerability requiring specific conditions | Fix before production traffic | Within 24 hours |
| **P2 Medium** | Hardening recommendation, best practice gap | Fix in next sprint | Within 1 week |

<Callout type="warn">
A score below 6/10 on any single layer means the audit found blocking issues at that layer. Do not proceed to production until all P0 findings are resolved and every layer scores at least 6/10. The overall score is an average -- it can hide a critically weak layer.
</Callout>

### Step 5: Fix and Re-Audit

After fixing the P0 findings, run the audit again to verify:

```bash
/ork:verify --scope=security
```

The re-audit checks that your fixes actually address the vulnerabilities. It also ensures fixes did not introduce new issues. For example, after adding the IDOR ownership check, the agent verifies that admin users can still access all documents and that the new check does not break the API tests.

```
Security Re-Audit Results
===========================================================

  Layer 3 — Authentication:  9/10   JWT secret upgraded to 256-bit
  Layer 4 — Authorization:   9/10   Ownership check added, admin bypass works

  Previously P0: 2 -> 0 resolved
  Previously P1: 3 -> 3 remaining (non-blocking)

  Overall Security Score:    8.1/10   (was 6.8)
```

### Step 6: Run Security Tests in CI

OrchestKit includes security tests that validate all 8 defense layers in your CI pipeline:

```bash
npm run test:security
```

This runs the security test suite:

```
OrchestKit Security Tests (CRITICAL — ZERO TOLERANCE)
============================================================================

  PASS: Command Injection Tests
  PASS: JQ Injection Tests
  PASS: Path Traversal Tests
  PASS: Unicode Attack Tests
  PASS: Symlink Attack Tests
  PASS: Input Validation Tests
  PASS: Additional Security Tests

============================================================================
Results: 7 passed, 0 failed
```

These tests validate that OrchestKit's own hooks (like `dangerous-command-blocker` and `file-guard`) correctly block attack vectors. They run automatically in CI and must all pass before merge.

<Callout type="info">
The security test suite covers 7 attack categories: command injection, JQ injection, path traversal, Unicode attacks, symlink attacks, input validation, and additional security checks. These are not application tests -- they validate OrchestKit's defensive hooks that protect your development workflow.
</Callout>

## Behind the Scenes

### Hooks That Fire During the Audit

| Hook | Event | What It Does |
|---|---|---|
| `dangerous-command-blocker` | pretool/bash | Prevents the security auditor from running destructive commands like `rm -rf /`, `chmod 777`, or `DROP TABLE`. Even security agents are sandboxed. |
| `file-guard` | pretool/write | Blocks any attempt to write `.env`, `*.pem`, `*credentials*`, or `*.key` files to disk. Prevents accidental exposure of secrets during testing. |
| `security-command-audit` | posttool/bash | Logs every security scan command and its results to the session audit trail. Creates a reproducible record of what was checked. |
| `session-env-setup` | lifecycle/start | Detects available security tools (bandit, pip-audit, npm audit, semgrep) at session start. Reports missing tools so you can install them. |
| `auto-remember-continuity` | lifecycle/stop | Persists security findings to memory so the next session knows about unresolved vulnerabilities. |

### Skills Auto-Injected

The `security-auditor` agent receives 7 skills via its agent definition:

- **`owasp-top-10`** -- Patterns for all 10 OWASP 2021 categories with vulnerable-vs-secure code examples
- **`defense-in-depth`** -- The 8-layer model, ensuring the agent checks every boundary
- **`auth-patterns`** -- JWT validation, OAuth2 flows, password hashing best practices
- **`input-validation`** -- SQL injection, XSS, command injection prevention at each input boundary
- **`llm-safety-patterns`** -- Prompt injection, model output validation, LLM-specific threat vectors
- **`security-scanning`** -- Scan command templates for bandit, pip-audit, npm audit, semgrep
- **`mcp-security-hardening`** -- MCP server security: tool whitelisting, input sanitization

### How the Agents Collaborate

The three agents produce complementary findings:

| Agent | Perspective | Catches What Others Miss |
|---|---|---|
| `security-auditor` | Automated scanning | Known CVEs, secrets patterns, OWASP checklist items |
| `code-quality-reviewer` | Code structure | Complexity that hides bugs, missing error handling, unsafe patterns |
| `debug-investigator` | Data flow tracing | Unvalidated boundaries where user input reaches databases or shell commands |

The `security-auditor` runs bandit and finds a SQL injection via f-string. But it might miss that a seemingly safe ORM query has a `.filter()` call that accepts raw user input through a dynamic field name. The `debug-investigator` traces the full data path from `request.query_params["sort_by"]` through the service layer to `getattr(Model, sort_by)` and flags the dynamic attribute access as an injection vector.

### The Severity Classification

OrchestKit uses a consistent severity system aligned with industry standards:

| Severity | Criteria | Examples |
|---|---|---|
| **P0 Critical** | Remote code execution, SQL injection, auth bypass, data breach | `f"SELECT * FROM users WHERE id = {user_id}"` |
| **P1 High** | XSS, CSRF, sensitive data exposure, missing rate limits | `element.innerHTML = userInput` |
| **P2 Medium** | Information disclosure, weak crypto, hardening gaps | Missing CSP header, outdated dependency with moderate CVE |
| **P3 Low** | Best practice violations, minor deviations | Missing X-Frame-Options, verbose error messages in staging |

### Security Scan Commands Used

The `security-auditor` agent runs these scans in parallel:

```bash
# Python vulnerability scan (static analysis)
bandit -r app/ -f json -o bandit-report.json

# Python dependency audit
pip-audit --format=json

# JavaScript dependency audit
npm audit --json

# Secret pattern detection
grep -rn "(?i)(api[_-]?key|secret|password|token|credential)" \
  --include="*.py" --include="*.ts" --include="*.env*"

# Semgrep (if installed)
semgrep scan --config=p/security-audit --json
```

If a tool is not installed, the agent skips it and notes it in the findings: "bandit not available -- install with `pip install bandit` for Python static analysis."

## Tips

<Callout type="info">
**Run quick scans after every feature.** Use `/ork:verify --scope=security` with the Quick scan option (option 1) after implementing features that touch authentication, payment, or user input. It takes 2 minutes and catches the most common issues. Save Deep audits for milestones and pre-launch reviews.
</Callout>

<Callout type="info">
**Memory compounds security knowledge.** After your first audit, OrchestKit remembers findings via the memory system. Next time you write auth code, the `memory-context-injector` hook surfaces your past security decisions: "This project uses 256-bit JWT secrets, Argon2 for password hashing, and cursor-based pagination." The agent does not repeat past mistakes.
</Callout>

<Callout type="warn">
**P0 findings block the entire audit with a failing score.** This is intentional. A single SQL injection or auth bypass makes all other security measures irrelevant. Fix P0 issues before addressing P1 and P2 findings. The re-audit verifies your fix actually resolves the vulnerability.
</Callout>

<Callout type="info">
**Combine with `/ork:review-pr` for defense in depth.** Run the security audit on your local branch, then create a PR and run `/ork:review-pr` for a second opinion. The PR review uses the same `security-auditor` agent but operates on the diff rather than the full codebase, catching issues specific to the changed code.
</Callout>

<Callout type="info">
**Install all scanning tools for maximum coverage.** The security auditor works best with all tools available: `pip install bandit pip-audit`, `npm install`, and optionally `brew install semgrep`. Each missing tool reduces coverage. The `session-env-setup` hook reports which tools are available at session start.
</Callout>

<Callout type="info">
**Export findings as JSON for tracking.** The `security-auditor` agent returns structured JSON output. Pipe it to your issue tracker or security dashboard. Each finding has a unique ID (SEC-001, SEC-002) for tracking resolution across sprints.
</Callout>

## Next Steps

- **[Implement a Feature](/docs/cookbook/implement-feature)** -- See how security checks integrate into the implementation workflow
- **[Review a Pull Request](/docs/cookbook/review-pr)** -- Multi-agent PR review with security as one of six dimensions
- **[Hooks Overview](/docs/hooks/overview)** -- Understand how `dangerous-command-blocker` and `file-guard` work
- **[Configuration](/docs/getting-started/configuration)** -- Environment setup for security scanning tools

## Set Up Cross-Session Memory

Persist decisions, patterns, and context across conversations.

[https://orchestkit.yonyon.ai/docs/cookbook/setup-memory](/docs/cookbook/setup-memory)

import { Callout } from 'fumadocs-ui/components/callout';

## Scenario

You have been working on a project for a week. Over that time you made twenty-plus architecture decisions: JWT over session cookies, PostgreSQL with pgvector for embeddings, cursor-based pagination for all list endpoints, Zod for runtime validation at API boundaries.

Then Monday arrives. You open a new Claude Code session. Claude knows none of it. It suggests session cookies. It reaches for offset pagination. Every conversation starts from zero.

OrchestKit solves this with a **3-tier memory architecture** that stores decisions once and surfaces them automatically in every future session. No manual copy-pasting. No re-explaining your stack. Decisions persist across conversations, projects, and machines.

## What You'll Use

| Component | Type | Purpose |
|---|---|---|
| `/ork:remember` | Command skill | Store decisions, patterns, and context |
| `/ork:memory` | Command skill | Search, load, sync, visualize stored knowledge |
| `memory-writer` | Hook (posttool) | Auto-writes high-confidence decisions to CC Native |
| `memory-context-injector` | Hook (prompt) | Searches graph memory on every prompt submit |
| `mcp__memory__*` | MCP server | Graph database for entities and relations |

## The 3 Memory Tiers

Before diving into commands, understand what each tier does and when it activates.

| Tier | Storage | Config | Behavior |
|---|---|---|---|
| **1. Graph** | MCP `mcp__memory__*` | None (zero-config) | Stores entities with typed relations. Primary tier. Always available. |
| **2. Local** | `.claude/memory/*.jsonl` | None (auto-created) | JSONL queue files for session persistence and offline backup. |
| **3. CC Native** | `~/.claude/projects/*/memory/MEMORY.md` | None (auto-sync) | Injected directly into Claude's system prompt. Survives plugin removal. |

<Callout type="info">
All three tiers require zero configuration. They work the moment you install OrchestKit. Tier 1 (Graph) is the primary storage. Tier 2 adds local durability automatically. Tier 3 (CC Native) is written automatically for high-confidence decisions and persists even without OrchestKit installed.
</Callout>

## Step-by-Step

### Step 1: Store Your First Decision

Use `/ork:remember` to record an architecture decision. The skill auto-detects the category from keywords in your text, extracts entities, and creates typed relations in the knowledge graph.

```bash
/ork:remember "We use JWT tokens for auth, not session cookies"
```

**What you see:**

```
Remembered (authentication): "We use JWT tokens for auth, not session cookies"
   -> Stored in knowledge graph
   -> Created entity: JWT (Technology)
   -> Created entity: session-cookies (Technology)
   -> Created relation: project -> CHOSE_OVER -> JWT vs session-cookies
   Graph: 3 entities, 1 relation
```

The skill detected `authentication` as the category from the keywords "JWT" and "auth". It extracted two Technology entities and a `CHOSE_OVER` relation. All of this happens in a single command with no manual tagging.

### Step 2: Store Patterns with Outcome Tracking

Mark successful patterns so OrchestKit reinforces them in future sessions. Mark anti-patterns so it warns you away from repeating mistakes.

```bash
# A pattern that worked well
/ork:remember --success "Cursor-based pagination scales well for our 2M-row tables"

# A pattern that caused problems
/ork:remember --failed "Offset pagination caused timeouts on tables with 1M+ rows"
```

**Success output:**

```
Remembered SUCCESS (pagination): "Cursor-based pagination scales well for our 2M-row tables"
   -> Stored in knowledge graph
   -> Created entity: cursor-pagination (Pattern)
   Graph: 1 entity, 0 relations
```

**Anti-pattern output:**

```
Remembered ANTI-PATTERN (pagination): "Offset pagination caused timeouts on tables with 1M+ rows"
   -> Stored in knowledge graph
   -> Created entity: offset-pagination (AntiPattern)
   Lesson: Use cursor-based pagination for large datasets
```

The `--failed` flag creates an `AntiPattern` entity type instead of `Pattern`. When a future session mentions offset pagination, OrchestKit surfaces the anti-pattern warning automatically.

<Callout type="warn">
If you provide both `--success` and `--failed` on the same command, OrchestKit asks you to clarify. A single decision cannot be both a success and a failure.
</Callout>

### Step 3: Search Across All Tiers

Query stored knowledge from any future session using `/ork:memory search`:

```bash
/ork:memory search "authentication"
```

**What you see:**

```
Found 3 results matching "authentication":

[GRAPH] JWT (Technology)
   -> CHOSE_OVER -> session-cookies
   Observations: "Used for auth, not session cookies"

[GRAPH] auth-service (Component)
   -> USES -> JWT
   Observations: "Handles login, signup, token refresh"

[GRAPH] oauth-provider (Technology)
   -> USED_FOR -> third-party auth
```

Results show the source tier, entity type, relations, and observations. You can filter and scope results with flags:

```bash
# Filter by category
/ork:memory search --category database "indexing strategy"

# Scope to a specific agent's memories
/ork:memory search --agent backend-system-architect "caching"

# Search cross-project best practices
/ork:memory search --global "rate limiting"
```

### Step 4: Verify Memory System Health

Check that all tiers are operational at any time:

```bash
/ork:memory status
```

**What you see:**

```
Memory System Status:
  Graph Memory:  healthy (42 decisions, 0 corrupt)
  Queue Depth:   3 pending
  CC Native:     active (MEMORY.md present)
```

### Step 5: Visualize Your Knowledge Graph

See how your decisions connect to each other:

```bash
/ork:memory viz
```

This produces a Mermaid diagram showing entities and relations:

```
graph LR
  JWT[JWT] -->|CHOSE_OVER| session-cookies[session-cookies]
  auth-service[auth-service] -->|USES| JWT
  PostgreSQL[PostgreSQL] -->|USES| connection-pooling[connection-pooling]
  PostgreSQL -->|USES| pgvector[pgvector]
  pgvector -->|USED_FOR| RAG[RAG]
  cursor-pagination[cursor-pagination] -->|CHOSE_OVER| offset-pagination[offset-pagination]
```

Focus on a specific entity or limit relationship depth:

```bash
# Focus on one entity and its neighbors
/ork:memory viz --entity PostgreSQL --depth 2

# Filter to a specific entity type
/ork:memory viz --type Technology
```

## Behind the Scenes

Here is what happens invisibly every time you interact with Claude in an OrchestKit session.

### On Every Prompt Submit

The `memory-context-injector` hook fires on the `prompt` lifecycle event. It searches the knowledge graph for entities related to keywords in your prompt. If you type "set up the authentication endpoint," the hook finds your JWT decision and injects it into Claude's context -- before Claude even starts thinking about a response.

This is why Claude stops suggesting session cookies after you store the JWT decision. The hook silently provides the relevant context on every prompt.

### On High-Confidence Decisions

The `memory-writer` hook monitors for decisions with confidence >= 0.7. When it detects one, it automatically writes to Tier 3 (CC Native MEMORY.md). This file lives at `~/.claude/projects/<your-project>/memory/MEMORY.md` and is injected into Claude's system prompt for every session -- even sessions that do not use OrchestKit.

This means your most important decisions survive plugin removal, reinstallation, or upgrades. They are baked into Claude's base context.

### On Session End

The `auto-remember-continuity` hook fires on the `stop` lifecycle event. It captures key decisions and context from the current session and persists them to the local queue (Tier 2), ensuring nothing is lost if the session ends unexpectedly or you forget to run `/ork:remember` manually.

### The Write Path

When you invoke `/ork:remember`, the skill writes to all configured tiers simultaneously:

| Tier | Storage | Method |
|---|---|---|
| **1. Graph** | Knowledge graph | `mcp__memory__create_entities` + `create_relations` |
| **2. Local** | `.claude/memory/graph-queue.jsonl` | File append |
| **3. CC Native** | `MEMORY.md` | Written if confidence >= 0.7 |

### Entity and Relation Extraction

The skill automatically extracts entities from your text using these heuristics:

- **Capitalized terms** become Technology entities (PostgreSQL, React, FastAPI)
- **Agent names** with hyphens become Agent entities (database-engineer, backend-system-architect)
- **Pattern names** become Pattern entities (cursor-pagination, connection-pooling)
- **Relationship phrases** like "uses", "requires", "prefers", "chose X over Y" become typed relations (USES, REQUIRES, PREFERS, CHOSE_OVER)
- **Failed patterns** become AntiPattern entities with an extracted lesson

Graph memory stores explicit relationships between entities: `"JWT" -> USED_FOR -> "auth-service"`. This structure enables precise queries like "what does auth-service use?" -- something flat text search cannot do.

## Tips

<Callout type="info">
**Store investigation context before ending a session.** Run `/ork:remember "Session summary: completed X, found Y, next steps Z"` before closing. The `auto-remember-continuity` hook captures some context automatically, but explicit summaries are richer, more reliable, and higher confidence -- meaning they are more likely to reach Tier 3 (CC Native).
</Callout>

<Callout type="info">
**Use categories to organize decisions.** The 12 built-in categories (decision, architecture, pattern, blocker, constraint, preference, pagination, database, authentication, api, frontend, performance) make searching significantly faster. Use `--category` on both `remember` and `search` commands for precision.
</Callout>

<Callout type="info">
**Use `--global` for cross-project wisdom.** Decisions like "always validate input at API boundaries" apply everywhere. Store them with `/ork:remember --global` and search them with `/ork:memory search --global`. They use a separate user ID (`orchestkit-global-best-practices`) so they never pollute project-specific context.
</Callout>

<Callout type="warn">
**Duplicate detection is automatic.** If you store the same decision twice, OrchestKit detects the existing entity in the graph and adds a new observation instead of creating a duplicate. You see: "Updated existing entity (added observation)".
</Callout>

<Callout type="info">
**Resume sessions with memory load.** Start a new session with `/ork:memory load` to pull in recent decisions, active project context, and agent-specific memories. Pair this with Claude Code's `--from-pr` flag for PR work: `claude --from-pr 123` loads the PR context, then `/ork:memory load` layers in your architecture decisions on top.
</Callout>

<Callout type="info">
**Context budget scales automatically.** On CC 2.1.33+, skill injection budgets scale to 2% of your context window. With a 200K context window you get roughly 1200 tokens for memory injection; with 1M context you get roughly 6000 tokens. OrchestKit uses this budget to inject the most relevant decisions first, ranked by recency and confidence.
</Callout>

## Next Steps

- **[Memory Overview](/docs/memory/overview)** -- Deep dive into the 3-tier architecture
- **[Configuration](/docs/getting-started/configuration)** -- Set up environment variables
- **[Security Audit Cookbook](/docs/cookbook/security-audit)** -- See memory in action during a security review

## Task Management Patterns

Track complex work with TaskCreate, TaskUpdate, and dependency chains — from single-phase tasks to multi-agent coordination.

[https://orchestkit.yonyon.ai/docs/cookbook/task-management](/docs/cookbook/task-management)

## AI Engineer

OrchestKit toolkit for AI engineers

[https://orchestkit.yonyon.ai/docs/cookbook/roles/ai-engineer](/docs/cookbook/roles/ai-engineer)

## Backend Developer

OrchestKit toolkit for backend developers

[https://orchestkit.yonyon.ai/docs/cookbook/roles/backend-developer](/docs/cookbook/roles/backend-developer)

---

> 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.yonyon.ai/llms.txt and per-section index at https://orchestkit.yonyon.ai/docs/llms.txt.