From f0b26408f8c1c2f8eee16f507e316cad49fe1dea Mon Sep 17 00:00:00 2001 From: Jon Staab Date: Wed, 8 Apr 2026 15:00:28 -0700 Subject: [PATCH] Add agents.md and skills --- .agents/skills/plan-chapter/SKILL.md | 87 +++++++++++++++++++++++ .agents/skills/research-chapter/SKILL.md | 86 ++++++++++++++++++++++ .agents/skills/write-chapter/SKILL.md | 61 ++++++++++++++++ AGENTS.md | 90 ++++++++++++++++++++++++ 4 files changed, 324 insertions(+) create mode 100644 .agents/skills/plan-chapter/SKILL.md create mode 100644 .agents/skills/research-chapter/SKILL.md create mode 100644 .agents/skills/write-chapter/SKILL.md create mode 100644 AGENTS.md diff --git a/.agents/skills/plan-chapter/SKILL.md b/.agents/skills/plan-chapter/SKILL.md new file mode 100644 index 0000000..1828537 --- /dev/null +++ b/.agents/skills/plan-chapter/SKILL.md @@ -0,0 +1,87 @@ +--- +name: plan-chapter +description: Develop a detailed plan for a book chapter through interactive Q&A +--- + +# Plan Chapter + +You are planning a chapter of a literate programming book about nostr. The chapter name +is provided as an argument: `$ARGUMENTS`. + +## Step 1: Read Research + +Read the research file at `./book/research/$ARGUMENTS.md`. This contains: +- The topic summary describing what the chapter should cover +- Detailed analysis of how six reference implementations handle this topic +- Common patterns and design considerations + +If the research file does not exist, tell the user to run `/research-chapter $ARGUMENTS` +first and stop. + +## Step 2: Interactive Q&A + +Your goal is to develop a complete chapter plan by asking the user targeted questions. +Draw on the research to make your questions specific and informed. Areas to explore: + +- **Scope**: What should be included vs. excluded from this chapter? Are there edge cases + or advanced features to defer to later chapters? +- **API Design**: What should the public API look like? Which patterns from the reference + implementations should we adopt, adapt, or avoid? +- **Dependencies**: What external crates are needed? Should we minimize dependencies or + use well-known crates? +- **Narrative Flow**: How should the chapter be structured? What order should concepts be + introduced? What prior knowledge can we assume from earlier chapters? +- **Code Organization**: Which crate(s) should this code live in? How should modules be + structured? +- **Teaching Approach**: Are there concepts that need careful explanation? Diagrams? + Worked examples? + +Ask questions in batches of 2-3 at a time. After each round of answers, follow up on +anything that needs clarification before moving on. Continue until you have enough detail +to write a comprehensive plan. + +## Step 3: Write Plan + +Once you have sufficient information, write the chapter plan to: +`./book/plan/$ARGUMENTS.md` + +The plan file should have this structure: + +```markdown +# Plan: + +## Topic Summary + + + +## Chapter Outline + + + +## API Design + + + +## Code Organization + + + +## Dependencies + + + +## Narrative Notes + + + +## Design Decisions + + + +## Open Questions + + +``` + +After writing the file, tell the user the plan is complete and they can proceed with +`/write-chapter $ARGUMENTS`. diff --git a/.agents/skills/research-chapter/SKILL.md b/.agents/skills/research-chapter/SKILL.md new file mode 100644 index 0000000..1f85b8f --- /dev/null +++ b/.agents/skills/research-chapter/SKILL.md @@ -0,0 +1,86 @@ +--- +name: research-chapter +description: Research how reference implementations handle a chapter's topic +--- + +# Research Chapter + +You are researching nostr library implementations to prepare for writing a chapter of a +literate programming book. The chapter name is provided as an argument: `$ARGUMENTS`. + +## Step 1: Gather Topic Context + +Before doing any research, ask the user to provide a brief summary of what this chapter +should cover. What concepts, data structures, protocols, or functionality should the +research focus on? Wait for their response before proceeding. + +## Step 2: Research Reference Implementations + +Once you have the topic summary, spawn **one sub-agent per reference implementation** in +`./ref/` to analyze them in parallel. Each sub-agent should: + +1. Search the reference implementation for code relevant to the chapter topic +2. Analyze in depth: + - What data structures and constructs are used? + - What programming style or patterns are employed? + - What are the dependencies (both internal and external)? + - Is the implementation coupled to other parts of the library, or self-contained? + - Are there any notable design decisions, trade-offs, or limitations? +3. Return a detailed summary focusing **only on functionality relevant to the chapter topic** + — ignore unrelated parts of the library + +The six reference implementations to analyze: +- `ref/applesauce` (TypeScript — noStrudel ecosystem) +- `ref/ndk` (TypeScript — Nostr Development Kit) +- `ref/nostr-gadgets` (TypeScript — high-level utilities, JSR) +- `ref/nostr-tools` (TypeScript — low-level tools, minimal deps) +- `ref/rust-nostr` (Rust — full implementation, multiple crates) +- `ref/welshman` (TypeScript — extracted from Coracle client) + +## Step 3: Write Research File + +Compile all sub-agent results into a single research document and write it to: +`./book/research/$ARGUMENTS.md` + +The research file should have this structure: + +```markdown +# Research: + +## Topic Summary + + + +## Reference Implementation Analysis + +### applesauce + + +### ndk + + +### nostr-gadgets + + +### nostr-tools + + +### rust-nostr + + +### welshman + + +## Common Patterns + + + +## Considerations for Our Implementation + + +``` + +After writing the file, tell the user the research is complete and they can proceed with +`/plan-chapter $ARGUMENTS`. diff --git a/.agents/skills/write-chapter/SKILL.md b/.agents/skills/write-chapter/SKILL.md new file mode 100644 index 0000000..f65ccca --- /dev/null +++ b/.agents/skills/write-chapter/SKILL.md @@ -0,0 +1,61 @@ +--- +name: write-chapter +description: Write a book chapter from its plan with tangled Rust code +--- + +# Write Chapter + +You are writing a chapter of a literate programming book about nostr. The chapter name +is provided as an argument: `$ARGUMENTS`. + +## Step 1: Read the Plan + +Read the chapter plan at `./book/plan/$ARGUMENTS.md`. This contains the outline, API +design, code organization, dependencies, and narrative notes developed with the user. + +If the plan file does not exist, tell the user to run `/plan-chapter $ARGUMENTS` first +and stop. + +Also read: +- `./book/SUMMARY.md` to understand the book structure and where this chapter fits +- Any existing chapters referenced in the plan to ensure continuity +- The existing code in any crate `src/` directories that this chapter will extend (these + are generated by tangle, but reading them shows the current state) + +## Step 2: Write the Chapter + +Create or update the chapter markdown file in `./book/`. Follow these conventions: + +- **Literate style**: The prose is the primary artifact. Code blocks are woven into the + narrative, not dumped in bulk. +- **Code blocks** that should be tangled use the annotation format: + ```` + ```rust {file=crate-name/src/path.rs} + ``` + ```` +- Multiple code blocks can target the same file — they are concatenated in document order. +- Code blocks without `{file=...}` are illustrative (examples, JSON, shell commands). +- Explain *why* before showing *what*. A reader should understand the motivation before + seeing the implementation. +- Keep code blocks focused — one concept per block where possible. +- Ensure all `use` statements and module declarations are included in tangled blocks. +- Update `./book/SUMMARY.md` if adding a new chapter. +- Update any `Cargo.toml` files if new dependencies are needed. + +## Step 3: Validate + +Run `just all` to verify that: +1. The tangle step extracts valid Rust source files +2. The Rust code compiles successfully +3. The mdBook build succeeds + +If the build fails, read the error output, fix the issue in the chapter markdown (not +in generated `src/` files), and run `just all` again. Repeat until the build passes. + +## Step 4: Report + +Tell the user the chapter is written and building. Summarize: +- What sections were written +- What types/functions were implemented +- Any deviations from the plan and why +- Any open items or things to revisit diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..8ea6e95 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,90 @@ +# Coracle Nostr Monorepo + +## Project Overview + +This is a literate programming monorepo for building nostr applications in Rust. The source of +truth is `book/`, which contains markdown files. Code blocks annotated with `{file=path}` are +extracted ("tangled") into Rust source files by `coracle-tangle`. The `src/` directories of +library crates are generated artifacts — never edit them directly. + +The project serves three goals: +1. A complete learning resource for the nostr protocol +2. A production-ready nostr utility library for Rust, KMP, and web projects +3. An experiment in literate programming as both library and LLM context + +## Crates + +- `coracle-lib` — Core nostr types and stateless utilities +- `coracle-net` — Relay networking +- `coracle-signer` — Signing abstractions (NIP-07, NIP-46, local key) +- `coracle-content` — Text parsing and rendering +- `coracle-storage` — Cross-platform storage adapters +- `coracle-tangle` — The tangle/weave build tool (not a library) + +## Bindings + +Platform bindings are provided via separate crates, keeping the core library free of +platform-specific annotations: + +- `coracle-wasm` — Web bindings via `wasm-bindgen`, producing JS-friendly types +- `coracle-ffi` — C-compatible FFI via UniFFI, consumed by KMP (Kotlin Multiplatform) + +These are separate crates (not feature flags in a single crate) because they have different +dependencies, build toolchains, and API surfaces. + +## Build Commands + +```sh +just tangle # Extract code from markdown into .rs files +just build # tangle + cargo build (excludes coracle-tangle) +just check # tangle + cargo check +just weave # tangle + mdbook build +just clean # Remove all generated src/ and book output +just all # build + weave — use this to validate work +``` + +Always run `just all` to validate changes. + +## Literate Programming Conventions + +- Each chapter in `book/` corresponds to a topic (events, keys, relays, etc.) +- Code blocks with `{file=crate/src/path.rs}` annotations are tangled into source files +- Multiple blocks targeting the same file are concatenated in document order +- Code blocks without annotations are illustrative only +- The narrative should flow naturally — explain *why* before showing *what* +- Write prose that a developer new to nostr could follow from start to finish + +## Reference Implementations + +The `ref/` directory contains nostr library implementations used for research: + +| Directory | Language | Description | +|-----------|----------|-------------| +| `ref/applesauce` | TypeScript | Libraries for building nostr web clients (noStrudel) | +| `ref/ndk` | TypeScript | Nostr Development Kit with framework integrations | +| `ref/nostr-gadgets` | TypeScript | High-level nostr client utilities (JSR) | +| `ref/nostr-tools` | TypeScript | Low-level nostr tools, minimal dependencies | +| `ref/rust-nostr` | Rust | Full Rust implementation with multiple crates | +| `ref/welshman` | TypeScript | Nostr toolkit extracted from the Coracle client | + +## Chapter Workflow + +Chapters are developed in three phases using slash commands: + +1. `/research-chapter ` — Asks the user for a topic summary, then spawns sub-agents to + analyze how each reference implementation handles the topic. Only reports on functionality + relevant to the chapter. Output: `book/research/.md` + +2. `/plan-chapter ` — Reads the research file and enters interactive Q&A with the user + to develop a detailed chapter plan. Output: `book/plan/.md` + +3. `/write-chapter ` — Reads the chapter plan and writes the actual chapter markdown + with tangled code blocks. Validates with `just all`. + +## Code Style + +- Rust code should be idiomatic and well-documented +- Prefer clarity over cleverness — this is a teaching resource +- Keep dependencies minimal +- All public items need doc comments that explain the *why* +- Code must compile and pass `just all` before a chapter is considered complete