Embed

---
name: embed
description: "Embed the Clarity Protocol into this project (scaffold protocol dir + CLAUDE.md snippet)"
disable-model-invocation: true
---

Embed the Clarity Protocol into the current project. Both steps are idempotent — safe to re-run.

1. **Scaffold the protocol directory:**

   ```bash
   python3 "${CLAUDE_PLUGIN_ROOT}/scripts/protocol_init.py" .
   ```

   This creates `.clarity-protocol/` (or `Clarity Protocol/` outside git repos) with template documents, `config.json`, and the suggestions mailbox, skipping anything that already exists.

2. **Install the snippet into CLAUDE.md:** take the template between the `SNIPPET-TEMPLATE` markers below (exclusive), replace every `{{PROTOCOL_DIR_NAME}}` with the actual protocol directory name from step 1, and place the result in the project's root `CLAUDE.md`:
   - If `CLAUDE.md` doesn't exist, create it with the snippet as its content.
   - If it exists and contains a `<!-- claudity-begin -->` ... `<!-- claudity-end -->` block, replace that block (and only that block) with the new snippet.
   - Otherwise append the snippet to the end, separated by a blank line. Never modify content outside the markers.

3. Confirm briefly what was created, then offer to start: the user can run `/claudity:start` or just begin talking about the project. The protocol directory is meant to be committed and reviewed like any other source file.

<!-- SNIPPET-TEMPLATE-BEGIN (everything between these markers, exclusive, is the installable template) -->
<!-- markdownlint-disable MD041 -->
<!-- claudity-begin -->
<!-- claudity-meta
schema_version: 1
protocol_dir_name: {{PROTOCOL_DIR_NAME}}
-->
<!-- Claudity manages this block; edits between the claudity-begin / claudity-end markers will be overwritten when the snippet is refreshed. Put project-specific guidance outside the markers. -->
<!-- Vendored from microsoft/clarity-agent@6b32c43 src/clarity_agent/setup/snippet.md — modified per PORTING.md rules R10, R12, R16, R17 (plugin provides the MCP server; packet-generator reference trimmed; template inlined in the embed skill; the no-freehand guard sentence is retained from Claudity 0.2 — e2e showed ambient sessions freestyle past the guides without it) -->

## Clarity Protocol

This project uses the Clarity Protocol for structured thinking about consequential decisions — what to build and why, how it should be designed, where it might fail. Protocol documents live in `{{PROTOCOL_DIR_NAME}}/`. The Claudity plugin provides the Clarity MCP tools (`clarity-agent` server) and skills (`/claudity:start`, `/claudity:status`, and friends). Use its tools to interact with the protocol — do not try to install or run Clarity directly.

### When to engage

**Before building — think when it matters.** Two triggers:

1. *The user asks.* When they want to explore what to build, clarify requirements, brainstorm risks, work through a decision, or create or update any protocol document: call the `run_clarity` MCP tool and follow the process guide it returns. Never work on protocol documents freehand — the guides carry required pipeline steps (mailbox snapshots, recording tools, state tracking) that freestyle edits silently miss.

2. *You recognize an inflection point.* Before making choices that would be expensive to reverse — new services, auth/trust models, data schemas, external integrations, significant API contracts — call `check_decision` with what you plan to do. It returns existing decisions, requirements, and architecture so you can check for conflicts. Don't interrupt for routine implementation. The test: "If this turns out wrong, is it a 5-minute fix or a multi-day rework?" Interrupt for the latter.

**After building — keep the record current.** After significant implementation work (new features, architectural changes), call `get_packet_status` to find stale protocol documents. Update them with `read_protocol_document` / `write_protocol_document`. Record significant choices with `record_decision`; add risks with `record_failure`.

### Behaviors (apply throughout)

**Move quickly through what's obvious.** Many processes have multiple steps, but sometimes the answer to a step is already clear from context. When it is, just do it — write the result and present a summary for confirmation. Don't stop to ask permission at every small step. The goal is a natural conversation, not a checklist. Reserve interactive discussion for genuine ambiguity, tradeoffs, or decisions that need the user's judgment.

**Keep outputs narrative but brief.** All `.md` files in this project — protocol documents, process guides, and instructions — are repeatedly read by both humans and LLMs. They should read as smooth, concise narrative: easy to understand on first read, with nothing that wastes the reader's attention. A reader must immediately understand both the "what" and the "why." Cut anything that doesn't carry meaningful information. Since many of these files are instructions for LLMs which create further `.md` files, they should encourage the same discipline.

**Use `{{PROTOCOL_DIR_NAME}}/notes.md` as shared memory.** At the start of every process, read `{{PROTOCOL_DIR_NAME}}/notes.md` for guiding principles and cross-phase observations. When you notice something worth remembering — a design philosophy, a team constraint, an insight relevant to a future phase — add it. Tag actionable items for a specific phase with `[for: <phase>]` (e.g., `[for: failure-analysis] Authentication is a single point of failure`). When acting on a tagged item, remove it. Keep the file compact: consolidate redundant entries and remove items that have been absorbed into the relevant protocol documents.

**Generate threat model artifacts.** When writing or updating `solution/architecture.md`, include a Mermaid threat model diagram directly in the file as a fenced ` ```mermaid ` block. Write the diagram yourself; you'll produce a better diagram than any code generator. Also write `{{PROTOCOL_DIR_NAME}}/system-design.json` with structured component/flow/threat data for tooling. After failure brainstorming or analysis, write `{{PROTOCOL_DIR_NAME}}/threat-model.md` — a concise threat model summary (1-2 pages max) with top risks, severities, one-line mitigations, and single points of failure.

<!-- claudity-end -->
<!-- SNIPPET-TEMPLATE-END -->