# AI Agent Orchestration Protocol

> Generated by Cortex Memory System - 2026-01-09

## Constitutional Principles

1. **Context First** - Query `cortex_context` before decisions when available; otherwise inspect the canonical strategy and repository state
2. **Document Why** - Save reasoning, not just choices
3. **Verify Before Change** - Check existing patterns first
4. **Incremental Progress** - Small commits, frequent checkpoints
5. **Zero Secrets** - Never log, commit, or transmit secrets/PII
6. **Single Responsibility** - One clear purpose per task
7. **Plan Before Code** - Outline approach, get approval, then implement

## Product North Star

Cortex is a local-first, evidence-backed engineering state plane for reliable handoffs between humans and coding agents. Read `docs/strategy/PRODUCT_DIRECTION.md` before product or architecture work.

## Agent Personas

### 1. Onboarding Agent
**Purpose:** Reduce developer ramp-up time from weeks to hours
- Queries Shared Knowledge Graph to explain *why* code exists
- References architectural decisions from memory
- Points to relevant documentation

### 2. Code Review Agent
**Purpose:** Ensure PRs don't contradict architectural consensus
- Queries Decision Trail before reviewing
- Flags "Semantic Drift" when code evolves away from truths
- Uses adversarial review: "What would a senior dev criticize?"

### 3. Tech Debt Radar
**Purpose:** Track and surface technical debt early
- Scans for patterns violating Architecture Guardrails
- Logs violations as a documented risk; use a supported record type until a dedicated risk type exists
- Prioritizes by impact and effort

### 4. Security Auditor
**Purpose:** Identify vulnerabilities before deployment
- Runs `/security-review` on changes
- Checks for OWASP Top 10 issues
- Validates input handling and auth flows

## Subagent Orchestration

Store subagent definitions in `.claude/agents/`:
```yaml
# .claude/agents/reviewer.yaml
name: Code Reviewer
description: Reviews code for bugs and style
tools: [Read, Search]
```

**Pattern:** Lead Agent delegates to specialized Subagents

## Hooks Configuration

Configure in `.claude/settings.json`:
```json
{
  "hooks": {
    "PreToolUse": [{
      "matcher": "Write|Edit",
      "command": "echo 'Validating...' && biome check"
    }],
    "PostToolUse": [{
      "matcher": "Write",
      "command": "biome format --write"
    }]
  }
}
```

## Context and Evidence Protocol

```javascript
cortex_context("summary of current task")
```

| Event | Memory Type |
|-------|-------------|
| Decisions | `decision` |
| Patterns | `code` |
| Facts | `fact` |
| Risks | `note` or `decision` until a dedicated risk type exists |

## Session Management

- `claude --resume` to continue previous session
- `/clear` to reset context for new task
- Session history stored locally for retrospective

## MCP Tools

| Tool | Purpose |
|------|---------|
| `cortex_context` | Load task-relevant memories |
| `cortex_add` | Save new memory |
| `cortex_search` | Query existing memories |