AURA SEMANTIC ENGINE — MANDATORY PROTOCOL FOR CLAUDE CODE

# AURA SEMANTIC ENGINE — MANDATORY PROTOCOL FOR CLAUDE CODE

> **You are Claude (Anthropic), running inside Claude Code CLI.**
> **Model**: Claude Opus 4.6 / Sonnet 4.6
> **Aura Version**: v0.12.6
> **MCP Server**: aura-vcs (29+ tools available)

## YOU MUST USE AURA. THIS IS NOT OPTIONAL.

Aura is a semantic version control engine that tracks your code changes at the AST level. It catches bugs you miss, prevents accidental deletions, and mathematically verifies your work. Every command below exists to protect the codebase from AI mistakes — including yours.

---

## BEFORE WRITING ANY CODE

1. **Check semantic state** — call `aura_status` MCP tool
   - Shows: logic nodes tracked, active session, checkpoints, strict mode
   - Shows: **team sync status** — mothership online/offline, pending pulls from teammates, peer count
   - If `team.pending_pull` exists: **STOP and call `aura_live_sync_pull` first** — your teammates pushed changes
   - If strict mode is ON, the pre-commit hook WILL block you if you delete functions without logging intent
   - If `strict_mode_locked: true`, you CANNOT disable strict mode — only a human with the passcode can

1.5. **Check cross-branch impacts** — call `aura_live_impacts` MCP tool
   - Shows unresolved impact alerts where functions you depend on were modified/deleted on other branches
   - Fix or acknowledge each alert, then call `aura_live_resolve` with the alert ID

1.6. **Read team messages** — if you see `💬 TEAM: N unread messages`, call `aura_msg_list` immediately
   - Another developer or AI agent may be coordinating with you
   - Read the message and respond via `aura_msg_send` if needed
   - **Do NOT ignore team messages** — they may contain critical context about what others are changing

2. **Plan multi-file features** — call `aura_plan_discover` MCP tool with your objective
   - Required when: task touches 3+ files, adds a new feature, or refactors existing architecture
   - Returns: gray areas (decisions needing human input) + atomic wave plan
   - Then call `aura_plan_lock` to lock decisions, `aura_plan_next` to get each wave

3. **Verify logic paths** — call `aura_prove` MCP tool with your goal
   - Example: `aura_prove("User can authenticate via OAuth")`
   - Returns: which logic nodes exist, which connections are wired, gaps in implementation

---

## WHILE WRITING CODE

4. **Snapshot before editing** — call `aura_snapshot` MCP tool with the file path
   - Creates a durable pre-edit backup so `aura rewind` can recover the file
   - Do this BEFORE every file edit, not after
   - **Aura automatically checks team zones** — if the file is claimed by a teammate:
     - `WARNING` → proceed with caution, notify the zone owner via `aura_msg_send`
     - `BLOCKED` → do NOT edit this file. Ask the user or message the zone owner first.
   - If you see `🚨 TEAM ZONE` in the response, respect the zone ownership

5. **Log intent before every commit** — call `aura_log_intent` MCP tool
   - Example: `aura_log_intent("Refactored retry_logic to use exponential backoff for rate limit compliance")`
   - The pre-commit hook compares your stated intent against actual AST changes
   - If they don't match, the commit is flagged as Intent Poisoning
   - **Aura automatically pushes your changed functions to the mothership** for real-time team sync

6. **Review periodically** — call `aura_pr_review` MCP tool
   - Catches: layer violations, security issues, architectural drift, accidental deletions
   - Run this after completing a logical unit of work, not just at the end

6.5. **Re-check impacts during long sessions** — call `aura_live_impacts` periodically
   - Other developers may modify shared functions while you work
   - If new impacts appear, review them before continuing

---

## TEAM COLLABORATION (AUTOMATIC)

These happen automatically through Aura's MCP tool pipeline — you don't need to call them manually, but you MUST respond to their notifications:

- **`🔄 SYNC: N function updates available`** → Call `aura_live_sync_pull` to apply teammate changes
- **`💬 TEAM: N unread messages`** → Call `aura_msg_list` to read, reply with `aura_msg_send`
- **`📨 SENTINEL: N unread messages from another AI agent`** → Call `aura_sentinel_inbox`, reply with `aura_sentinel_send`
- **`⚠️ SENTINEL COLLISION`** → Another agent is editing same functions. Coordinate.
- **`🚨 TEAM ZONE WARNING/BLOCKED`** → A teammate owns this file area. Respect it.
- **`🔄 AUTO-SYNC: Pushed N functions`** → Your changes were auto-synced to teammates. No action needed.

### When to proactively communicate with the team:
- Before making breaking changes to shared functions → `aura_msg_send("I'm about to refactor X, heads up")`
- When you discover a bug that affects others → `aura_msg_send("Found bug in Y, fixing now")`
- When you learn something useful → Store it: the user can run `aura team knowledge store`

---

## AFTER COMPLETING WORK

7. **Final review** — run `aura pr-review --base main` via terminal
   - Full semantic diff with AI-powered bug/security scanning
   - Fix any violations before committing

8. **Prove the goal** — call `aura_prove` with the user-facing behavior
   - Mathematically verify the implementation actually achieves the goal

---

## WHEN CONTEXT IS LARGE (>50K TOKENS)

9. **Generate handover** — call `aura_handover` with `agent: "claude"`
   - Produces a dense XML payload with full semantic state
   - Ask the user to start a new conversation with this payload
   - Saves ~90% of context tokens

---

## WHEN THINGS BREAK

10. **Surgical rewind** — call `aura_rewind` MCP tool
    - Reverts a single function/class to its last safe state
    - Zero merge conflicts — operates on AST nodes, not text lines

11. **Diagnose issues** — call `aura_doctor` MCP tool
    - Finds: stuck sessions, orphaned snapshots, missing hooks, shadow branch issues

---

## MCP TOOLS AVAILABLE TO YOU

| Tool | When to Use |
|------|-------------|
| `aura_status` | Start of session — shows everything including team sync status |
| `aura_log_intent` | Before EVERY commit — auto-pushes your changes to teammates |
| `aura_plan_discover` | Before multi-file features — get wave plan |
| `aura_plan_lock` | After reviewing gray areas — lock the plan |
| `aura_plan_next` | Get next wave to execute |
| `aura_prove` | Verify a behavioral goal is met |
| `aura_pr_review` | Catch bugs, security issues, violations |
| `aura_rewind` | Surgically revert a function |
| `aura_handover` | Compress context for agent handoff |
| `aura_snapshot` | Backup a file before editing — auto-checks team zones |
| `aura_snapshot_list` | List available snapshots |
| `aura_doctor` | Diagnose repo health issues |
| `aura_suggest_edit` | Get AI-suggested fixes for violations |
| `aura_orchestrate_status` | Check multi-agent orchestration progress |
| `aura_session_resume` | Resume a previous session |
| `aura_session_summarize` | Summarize a session's work |
| `aura_live_impacts` | Fetch cross-branch impact alerts (session start + periodically) |
| `aura_live_resolve` | Mark an impact alert as resolved after fixing |
| `aura_msg_send` | Send a message to team or a specific developer/agent |
| `aura_msg_list` | Read recent team messages (call when notified) |
| `aura_live_sync_push` | Push function bodies to mothership (auto on intent log) |
| `aura_live_sync_pull` | Pull function changes from teammates and apply at AST level |
| `aura_live_sync_status` | Check pending sync changes, active pushers |
| `aura_sentinel_send` | Send message to another AI agent in this repo |
| `aura_sentinel_inbox` | Read messages from other AI agents |
| `aura_sentinel_agents` | See other active AI agents |
| `aura_zone_claim` | Claim files/functions so other agents don't edit them |

## WHAT YOU MUST NEVER DO

- Never commit without calling `aura_log_intent` first
- Never delete functions without explaining why in intent
- Never skip `aura_plan_discover` for features touching 3+ files
- Never ignore `aura_pr_review` findings — fix them
- Never edit a file without `aura_snapshot` first
- Never keep working past 50K tokens — use `aura_handover` instead
- Never ignore team messages (`💬 TEAM`) or agent messages (`📨 SENTINEL`)
- Never edit a file that is `BLOCKED` by a team zone — coordinate first
- Never ignore `🔄 SYNC` notifications — pull teammate changes before editing