|
|
# CLAUDE.md
|
|
|
|
|
|
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
|
|
|
|
|
|
## What This Project Is
|
|
|
|
|
|
`edu` is an [mdbook](https://rust-lang.github.io/mdBook/)-based static site called **Vibed Learning** — a collection of self-guided courses and technical references. There is no Rust code here; all content is Markdown. The generated `book/` directory is gitignored.
|
|
|
|
|
|
## Commands
|
|
|
|
|
|
```sh
|
|
|
# Build the static site
|
|
|
mdbook build
|
|
|
|
|
|
# Serve locally with live reload (default: http://localhost:3000)
|
|
|
mdbook serve
|
|
|
|
|
|
# Enter the Nix dev shell (provides mdbook + nbd)
|
|
|
nix develop
|
|
|
# or automatically via direnv: cd into the directory
|
|
|
```
|
|
|
|
|
|
## Content Structure
|
|
|
|
|
|
- `src/SUMMARY.md` — mdbook table of contents; controls site navigation. **Every new page must be listed here.**
|
|
|
- `src/<page>.md` — individual course or reference pages
|
|
|
- `book.toml` — site title, theme (navy), and source directory
|
|
|
|
|
|
To add a new page: create `src/<name>.md`, then add it to `src/SUMMARY.md` under the appropriate section heading.
|
|
|
|
|
|
## Task Tracking with nbd
|
|
|
|
|
|
`nbd` is a CLI tool for managing work tickets, designed for agent workflows.
|
|
|
|
|
|
### Initialisation
|
|
|
|
|
|
```sh
|
|
|
nbd init
|
|
|
```
|
|
|
|
|
|
Run once in the project root. Creates `.nbd/tickets/`. Safe to run multiple times.
|
|
|
|
|
|
### Core commands
|
|
|
|
|
|
```sh
|
|
|
# Create a new ticket (use --ftype md for a human-readable body)
|
|
|
nbd create --title "Add OAuth login" --type feature --priority 7 --ftype md --json
|
|
|
|
|
|
# List all open tickets (sorted by priority)
|
|
|
nbd list --json
|
|
|
|
|
|
# Read a specific ticket
|
|
|
nbd read <id> --json
|
|
|
|
|
|
# Update a ticket
|
|
|
nbd update <id> --status in_progress --json
|
|
|
nbd update <id> --status done --json
|
|
|
```
|
|
|
|
|
|
### Finding what to work on
|
|
|
|
|
|
```sh
|
|
|
# All tickets that are unblocked and ready to start
|
|
|
nbd ready --json
|
|
|
|
|
|
# The single highest-priority unblocked ticket
|
|
|
nbd next --json
|
|
|
```
|
|
|
|
|
|
### Workflow
|
|
|
|
|
|
1. **Before starting** — create a ticket: `nbd create --title "..." --ftype md --json`
|
|
|
2. **When starting** — mark it in progress: `nbd update <id> --status in_progress --json`
|
|
|
3. **When done** — mark it complete: `nbd update <id> --status done --json`
|
|
|
|
|
|
### Guidelines
|
|
|
|
|
|
- **Always pass `--json`** to every command for structured, unambiguous output.
|
|
|
- **Always pass `--ftype md`** when creating tickets — markdown format keeps the body human-readable.
|
|
|
- Use `jq` to parse and transform JSON output when needed.
|
|
|
- Priority scale 0–10: use **7–9** for bugs, **5** for normal tasks, **3** for nice-to-haves.
|
|
|
- `--type` choices: `project`, `feature`, `task`, `bug`.
|
|
|
- Use `--deps id1,id2` to express blockers — tickets that must be done first.
|
|
|
- Create tickets *before* starting non-trivial tasks, not after.
|
|
|
|
|
|
Ticket IDs appear in commit messages in `[<id>]` format.
|
|
|
|
|
|
## Conventions
|
|
|
|
|
|
Inherits all Git and general conventions from the parent [`../CLAUDE.md`](../CLAUDE.md) (Conventional Commits, dual Apache-2.0/MIT license, Nix for dev, etc.).
|
|
|
|
|
|
Scope for commit messages: `edu` (e.g., `docs(edu): write §3 transition matrices`).
|
|
|
|
|
|
Stub sections in content are marked with 🚧 and reference an nbd ticket — fill in content and close the ticket when complete.
|