<!-- HANDSHAKE_METADATA
source: omnibase_core/architecture-handshakes/repos/omniclaude.md
source_version: 0.16.0
source_sha256: d8df39f64798bfc5bae4a0ead668a15cf8ec0a2e2c20354b94bdfbef2ecf91a0
installed_at: 2026-02-10T13:51:26Z
installed_by: jonah
-->

# OmniNode Architecture – Constraint Map (omniclaude)

> **Role**: Claude Code integration – hooks, skills, agent definitions
> **Handshake Version**: 0.2.0

## Platform-Wide Rules

1. **No backwards compatibility** - Breaking changes always acceptable. No deprecation periods, shims, or migration paths.
2. **Delete old code immediately** - Never leave deprecated code "for reference." If unused, delete it.
3. **No speculative refactors** - Only make changes that are directly requested or clearly necessary.
4. **No silent schema changes** - All schema changes must be explicit and deliberate.
5. **Frozen event schemas** - All models crossing boundaries (events, intents, actions, envelopes, projections) must use `frozen=True`. Internal mutable state is fine.
6. **Explicit timestamps** - Never use `datetime.now()` defaults. Inject timestamps explicitly.
7. **No hardcoded configuration** - All config via `.env` or Pydantic Settings. No localhost defaults.
8. **Kafka is required infrastructure** - Use async/non-blocking patterns. Never block the calling thread waiting for Kafka acks.
9. **No `# type: ignore` without justification** - Requires explanation comment and ticket reference.

## Core Principles

- Hooks never block Claude Code
- Data loss acceptable; UI freeze is not
- Graceful degradation on infrastructure failure
- Fail-fast configuration (services disabled by default)
- Privacy-first event emission (public vs restricted topics)

## This Repo Contains

- Claude Code hooks (SessionStart, UserPromptSubmit, PostToolUse, SessionEnd)
- Agent YAML definitions (`plugins/onex/agents/configs/`)
- Slash commands and skills (`plugins/onex/commands/`, `plugins/onex/skills/`)
- Event emission via Unix socket daemon
- Context injection and pattern learning system
- General-purpose agent coordination (Polly)

## Rules the Agent Must Obey

### Hook Rules

1. **Hook scripts must NEVER block on Kafka** - Blocking hooks freeze Claude Code UI
2. **Hooks must exit 0 unless blocking is intentional** - Non-zero exit blocks the tool/prompt
3. **All event schemas are frozen** (`frozen=True`) - Events are immutable after emission
4. **`emitted_at` timestamps must be explicitly injected** - No `datetime.now()` defaults
5. **SessionStart must be idempotent** - May be called multiple times on reconnect

### Privacy & Topic Rules

6. **Only preview-safe data to `onex.evt.*` topics** - Observability topics have broad access
7. **Full prompts ONLY to `onex.cmd.omniintelligence.*`** - Intelligence topics are access-restricted
8. **Topic naming follows ONEX canonical format** - `onex.{kind}.{producer}.{event-name}.v{n}`
9. **Secrets must be auto-redacted** - OpenAI keys, AWS keys, GitHub tokens, etc.

### Agent YAML Rules

10. **Agent YAML requires `schema_version: "1.0.0"`** - Required for validation
11. **Agent names must start with `agent-`** - Convention: `agent-api-architect`
12. **Agent types use snake_case** - Example: `api_architect`
13. **All agents need `activation_patterns`** - Makes agent routable

### Configuration Rules

14. **No localhost defaults** - Prevents production mistakes
15. **Services default to disabled** - Explicit `USE_EVENT_ROUTING=true` required
16. **`KAFKA_ENVIRONMENT` must be explicit** - One of: `dev`, `staging`, `prod`
17. **Use `${CLAUDE_PLUGIN_ROOT}` for paths** - Never hardcode absolute paths

## Performance Budgets

| Hook | Budget | Sync Components | Async Components |
|------|--------|-----------------|------------------|
| SessionStart | <50ms | daemon check, stdin read | Kafka, Postgres |
| UserPromptSubmit | <500ms | routing, agent load, context | Kafka, intelligence |
| PostToolUse | <100ms | stdin read, quality check | Kafka, content capture |
| SessionEnd | <50ms | stdin read | Kafka, Postgres |

## Parallel Execution Rules (General-Purpose Agents)

- **File Separation**: Each Polly creates own file (zero conflicts)
- **Single Branch**: All work on same branch (no merge overhead)
- **Clear Interfaces**: Contracts defined upfront before dispatch
- **Simultaneous Launch**: All Pollys in single message (true parallelism)

## Non-Goals (DO NOT)

- ❌ No blocking operations in hooks
- ❌ No sensitive data in `onex.evt.*` topics
- ❌ No agent YAML without `schema_version`
- ❌ No sequential Polly dispatch when parallel is possible

## Failure Mode: Always Continue

| Failure | Behavior | Exit Code |
|---------|----------|-----------|
| Emit daemon down | Events dropped, hook continues | 0 |
| Kafka unavailable | Daemon buffers, then drops | 0 |
| PostgreSQL down | Logging skipped | 0 |
| Routing timeout | Fallback to `general-purpose` | 0 |
| Agent YAML missing | Use default agent, log warning | 0 |
| Context injection fails | Proceed without patterns | 0 |
| Malformed stdin | Log error, pass through empty | 0 |

**Design principle**: Hooks never block. Data loss is acceptable; UI freeze is not.

## Pydantic Model Configuration

All event models must use:

```python
model_config = ConfigDict(frozen=True, extra="ignore", from_attributes=True)
```

- `frozen=True` - Immutable after creation
- `extra="ignore"` - Permit external schema evolution
- `from_attributes=True` - pytest-xdist worker compatibility
