Add agents.md and skills
This commit is contained in:
Jon Staab
@@ -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: <Chapter Name>
|
||||
|
||||
## Topic Summary
|
||||
|
||||
<From the research file>
|
||||
|
||||
## Chapter Outline
|
||||
|
||||
<Ordered list of sections with brief descriptions of what each covers>
|
||||
|
||||
## API Design
|
||||
|
||||
<Public types, traits, functions to be implemented. Include rough signatures where helpful.>
|
||||
|
||||
## Code Organization
|
||||
|
||||
<Which crate(s) and module(s) the code belongs in. How it relates to existing code.>
|
||||
|
||||
## Dependencies
|
||||
|
||||
<External crates needed and why>
|
||||
|
||||
## Narrative Notes
|
||||
|
||||
<Key teaching points, explanations that need care, examples to include>
|
||||
|
||||
## Design Decisions
|
||||
|
||||
<Choices made during planning and their rationale, referencing the research where relevant>
|
||||
|
||||
## Open Questions
|
||||
|
||||
<Anything unresolved that should be decided during writing>
|
||||
```
|
||||
|
||||
After writing the file, tell the user the plan is complete and they can proceed with
|
||||
`/write-chapter $ARGUMENTS`.
|
||||
@@ -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: <Chapter Name>
|
||||
|
||||
## Topic Summary
|
||||
|
||||
<The topic summary provided by the user in Step 1>
|
||||
|
||||
## Reference Implementation Analysis
|
||||
|
||||
### applesauce
|
||||
<detailed findings>
|
||||
|
||||
### ndk
|
||||
<detailed findings>
|
||||
|
||||
### nostr-gadgets
|
||||
<detailed findings>
|
||||
|
||||
### nostr-tools
|
||||
<detailed findings>
|
||||
|
||||
### rust-nostr
|
||||
<detailed findings>
|
||||
|
||||
### welshman
|
||||
<detailed findings>
|
||||
|
||||
## Common Patterns
|
||||
|
||||
<Cross-cutting observations: what approaches are shared, where do implementations
|
||||
diverge, what seems to work well>
|
||||
|
||||
## Considerations for Our Implementation
|
||||
|
||||
<Notes on dependencies, API design choices, and anything relevant to writing a Rust
|
||||
implementation in a literate programming style>
|
||||
```
|
||||
|
||||
After writing the file, tell the user the research is complete and they can proceed with
|
||||
`/plan-chapter $ARGUMENTS`.
|
||||
@@ -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
|
||||
@@ -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 <name>` — 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/<name>.md`
|
||||
|
||||
2. `/plan-chapter <name>` — Reads the research file and enters interactive Q&A with the user
|
||||
to develop a detailed chapter plan. Output: `book/plan/<name>.md`
|
||||
|
||||
3. `/write-chapter <name>` — 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
|
||||
Reference in New Issue
Block a user