From f70d50933dffe772844064a4eb861ab79c9a3777 Mon Sep 17 00:00:00 2001 From: Steffen Beyer Date: Wed, 18 Mar 2026 23:57:35 +0100 Subject: [PATCH] dev: nips submodule, skill --- .claude/skills/nostr-nip-sync.md | 123 +++++++++++++++++++++++++++++++ .gitmodules | 3 + docs/nips | 1 + 3 files changed, 127 insertions(+) create mode 100644 .claude/skills/nostr-nip-sync.md create mode 160000 docs/nips diff --git a/.claude/skills/nostr-nip-sync.md b/.claude/skills/nostr-nip-sync.md new file mode 100644 index 0000000..4133159 --- /dev/null +++ b/.claude/skills/nostr-nip-sync.md @@ -0,0 +1,123 @@ +--- +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). + diff --git a/.gitmodules b/.gitmodules index 7e47289..ce866d7 100644 --- a/.gitmodules +++ b/.gitmodules @@ -1,3 +1,6 @@ [submodule "marmot-ts"] path = marmot-ts url = https://github.com/marmot-protocol/marmot-ts.git +[submodule "docs/nips"] + path = docs/nips + url = https://github.com/nostr-protocol/nips.git diff --git a/docs/nips b/docs/nips new file mode 160000 index 0000000..3492eb1 --- /dev/null +++ b/docs/nips @@ -0,0 +1 @@ +Subproject commit 3492eb1affa5e93e658224a81bb832d2b6090ecd