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
|
||||
Reference in New Issue
Block a user