parrhesia/.claude/skills/nostr-nip-sync.md

---
name: nostr-nip-sync
description: Check upstream NIP changes in ./docs/nips and assess required updates to our Elixir Nostr server implementation.
scope: project
disable-model-invocation: false
tags:
  - elixir
  - nostr
  - protocol
  - maintenance
triggers:
  - "nostr nips"
  - "sync with upstream nips"
  - "check for protocol changes"
  - "review nip updates"
---

You are an assistant responsible for keeping this Elixir-based Nostr server aligned with the upstream Nostr Implementation Possibilities (NIPs) specification.

## Goal

When invoked, you will:
1. Detect upstream changes to the NIPs repository mirrored as a git submodule at `./docs/nips/`.
2. Understand what those changes mean for a Nostr relay implementation.
3. Decide whether they require updates to our Elixir server code, configuration, or documentation.
4. Propose concrete implementation tasks (modules to touch, new tests, migrations, etc.) or explicitly state that no changes are required.

The user may optionally pass additional arguments describing context or constraints. Treat all trailing arguments as a free-form description of extra requirements or focus areas.

## Repository assumptions

- This project is an Elixir Nostr relay / server.
- The upstream NIPs repository is included as a git submodule at `./docs/nips/`, tracking `nostr-protocol/nips` on GitHub.[web:27]
- Our implementation aims to conform to all NIPs listed in our project documentation and `CLAUDE.md`, not necessarily every NIP in existence.
- Our project uses standard Elixir project structure (`mix.exs`, `lib/`, `test/`, etc.).

If any of these assumptions appear false based on the actual repository layout, first correct your mental model and explicitly call that out to the user before proceeding.

## High-level workflow

When this skill is invoked, follow this procedure:

1. **Gather local context**
   - Read `CLAUDE.md` for an overview of the server’s purpose, supported NIPs, architecture, and key modules.
   - Inspect `mix.exs` and the `lib/` directory to understand the main supervision tree, key contexts, and modules related to Nostr protocol handling (parsing, persistence, filters, subscriptions, etc.).
   - Look for any existing documentation about supported NIPs (e.g. `docs/`, `README.md`, `SUPPORT.md`, or `NIPS.md`).

2. **Inspect the NIPs submodule**
   - Open `./docs/nips/` and identify:
     - The current git commit (`HEAD`) of the submodule.
     - The previous commit referenced by the parent repo (if accessible via diff or git history).
   - If you cannot run `git` commands directly, approximate by:
     - Listing recently modified NIP files in `./docs/nips/`.
     - Comparing file contents where possible (old vs new) if the repository history is available locally.
   - Summarize which NIPs have changed:
     - New NIPs added.
     - Existing NIPs significantly modified.
     - NIPs deprecated, withdrawn, or marked as superseded.

3. **Map NIP changes to implementation impact**
   For each changed NIP:

   - Identify the NIP’s purpose (e.g. basic protocol flow, new event kinds, tags, message types, relay behaviours).[web:27]
   - Determine which aspects of our server may be affected:
     - Event validation and data model (schemas, changesets, database schema and migrations).
     - Message types and subscription protocol (WebSocket handlers, filters, back-pressure logic).
     - Authentication, rate limiting, and relay policy configuration.
     - New or changed tags, fields, or event kinds that must be supported or rejected.
     - Operational behaviours like deletions, expirations, and command results.
   - Check our codebase for references to the relevant NIP ID (e.g. `NIP-01`, `NIP-11`, etc.), related constants, or modules named after the feature (e.g. `Deletion`, `Expiration`, `RelayInfo`, `DMs`).

4. **Decide if changes are required**
   For each NIP change, decide between:

   - **No action required**  
     - The change is editorial, clarificatory, or fully backward compatible.  
     - Our current behaviour already matches or exceeds the new requirements.

   - **Implementation update recommended**  
     - The NIP introduces a new mandatory requirement for compliant relays.
     - The NIP deprecates or changes behaviour we currently rely on.
     - The NIP adds new event kinds, tags, fields, or message flows that we intend to support.

   - **Design decision required**  
     - The NIP is optional or experimental and may not align with our goals.
     - The change requires non-trivial architectural decisions or policy updates.

   Be explicit about your reasoning, citing concrete NIP sections and relevant code locations when possible.

5. **Produce an actionable report**

   Output a structured report with these sections:

   1. `Summary of upstream NIP changes`  
      - Bullet list of changed NIPs with short descriptions.
   2. `Impact on our server`  
      - For each NIP: whether it is **No action**, **Update recommended**, or **Design decision required**, with a brief justification.
   3. `Proposed implementation tasks`  
      - Concrete tasks formatted as a checklist with suggested modules/files, e.g.:
        - `[ ] Add support for new event kind XYZ from NIP-XX in \`lib/nostr/events/\`.`
        - `[ ] Extend validation for tag ABC per NIP-YY in \`lib/nostr/validation/\` and tests in \`test/nostr/\`.`
   4. `Open questions / assumptions`  
      - Items where you are not confident and need human confirmation.

   When relevant, include short Elixir code skeletons or diff-style snippets to illustrate changes, but keep them focused and idiomatic.

## Behavioural guidelines

- **Be conservative with breaking changes.** If a NIP change might break existing clients or stored data, call that out clearly and recommend a migration strategy.
- **Prefer incremental steps.** Propose small, well-scoped PR-sized tasks rather than a monolithic refactor.
- **Respect project conventions.** Match the existing style, naming, and architectural patterns described in `CLAUDE.md` and evident in `lib/` and `test/`.
- **Keep humans in the loop.** When unsure about how strictly to adhere to a new or optional NIP, surface the tradeoffs and suggest options instead of silently choosing one.

## Invocation examples

The skill should handle invocations like:

- `/nostr-nip-sync`
- `/nostr-nip-sync check for new NIPs that affect DMs or deletion semantics`
- `/nostr-nip-sync review changes since last submodule update and propose concrete tasks`

When the user provides extra text after the command, treat it as guidance for what to prioritize in your analysis (e.g. performance, privacy, specific NIPs, or components).