Add agents.md and skills

2026-04-08 15:00:28 -07:00
parent 2d36400ba0
commit f0b26408f8
4 changed files with 324 additions and 0 deletions
@@ -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