79 lines
5.1 KiB
Markdown
79 lines
5.1 KiB
Markdown
# Notes rules
|
|
|
|
Each project keeps its local working notes in `.notes/` at the project root: design docs, work that spans sessions, and questions parked for later. The notes are never committed to the project. The `notes` skill does the mechanics (creating the dir, picking ids, close-out).
|
|
|
|
## Layout
|
|
|
|
```
|
|
.notes/ # its own git repo, never pushed
|
|
README.md # one line pointing here
|
|
index.html # generated: the overview, links only
|
|
notes.css # generated: copy of the skill's stylesheet every page uses
|
|
_pages/ # generated: questions, briefs and other markdown rendered to pages
|
|
_out/ # generated: other/out/ made self-contained, css inlined, for sending
|
|
docs/ # dNNN-slug.html, or dNNN-slug/index.html with its assets
|
|
work/ # wNNN-slug/ while in flight, removed at close-out
|
|
questions/ # qNNN-slug.md, removed when settled
|
|
other/
|
|
in/ # placed by the user
|
|
out/ # prepared for someone else
|
|
```
|
|
|
|
- created on first need (the first doc, work item or question in a project), not up front
|
|
- the generated files are rebuilt by the skill's `notes.py` on every commit and never committed; browse every project's notes at once with `notes.py serve` (one port, roots `$NOTES_ROOTS`, else `~/git`), or one project with `python -m http.server -d .notes`
|
|
- every page has a back link to the index; ids like `d007` or `q014` in markdown become links
|
|
|
|
## Numbering
|
|
|
|
- `<letter><NNN>-<slug>`: `d` docs, `w` work, `q` questions; each letter has its own counter, three digits, lowercase kebab slug
|
|
- numbers are never reused, including numbers of deleted items: the next id is the highest ever used in that bucket (files plus `git -C .notes log --all --name-only`) + 1
|
|
- refer to items by id everywhere: chat, other notes, commit subjects ("see q014", "per d007")
|
|
- `other/` is not numbered
|
|
|
|
## docs
|
|
|
|
- point-in-time design docs: plans, proposals, research, reviews; html per the output format rules
|
|
- one look for all docs: link `notes.css`, start `main.page` with `nav.back`, use only the components documented at the top of `notes.css`, no `<style>` or font links of their own; the skill shows the skeleton
|
|
- a doc with assets becomes a folder: `dNNN-slug/index.html` plus its files, linked relatively
|
|
- a status line sits directly under the title as `<p class="status current|stale|superseded">…</p>` (`notes.py` reads it): `status: current`, `status: partly stale (<what changed>, <date>)` or `status: superseded by dNNN (<date>)`, with `dNNN` a relative link to the newer doc
|
|
- once done, a doc's body doesn't change; only its status line does. a new design gets a new doc
|
|
|
|
## work
|
|
|
|
- one folder per piece of work that spans sessions; a single-session task gets none
|
|
- typical files: `brief.md` (goal, done when, scope, decisions to ask), `plan.html` (the proposal to approve), `report.md` (what was built, what differs, leftovers), plus research the work needed
|
|
- close-out runs in the same session the work ends (branch merged or work dropped):
|
|
1. lasting design goes to `docs/`: a new doc, or a status line on an existing one
|
|
2. leftovers go to `questions/`, one each, with `origin: wNNN`
|
|
3. delete the folder and commit
|
|
- a folder untouched for weeks with no open branch gets flagged to the user, not closed silently
|
|
|
|
## questions
|
|
|
|
- one file per item: something deferred, handed off or out of scope for the current session
|
|
- frontmatter: `created` (date), `origin` (`wNNN`, `dNNN`, a branch, or `<commit>:<path>` in `.notes`), `status: open`
|
|
- body: what is open, why it matters, what is known, where to look
|
|
- before acting on one, check the repo for whether it still applies
|
|
- settled: fold the outcome into a doc or a work item if it is worth keeping, delete the file, commit with a subject saying how it was settled
|
|
|
|
## other
|
|
|
|
- `in/`: read only when the user points at it
|
|
- `out/`: written for a person, not for later sessions; don't treat it as context
|
|
- html in `out/` uses the same `notes.css` and components as docs, without an id or status line; the copy that leaves is the generated self-contained one in `_out/`
|
|
- `out/` holds documents and the few small files that go with them (a script, a config snippet); bulk output for a person (screenshot sets, builds, logs) does not go into `.notes/` at all: in a sandbox vm it goes to the host handoff mount once there is one, until then ask where
|
|
|
|
## History
|
|
|
|
- `.notes/` is its own git repo with no remote, its `.gitignore` holding the generated files; commit after each change set, subject line only, naming the ids touched (`q014: settled by a3f4573`)
|
|
- git history replaces archives: delete instead of moving to an archive folder, rewrite instead of keeping dated copies
|
|
- never stage `.notes/` from the project repo: stage project paths explicitly, never `git add .` or `git add -A` there
|
|
- the host's global gitignore hides `.notes/`; where it shows up as untracked (sandbox vms), that is expected
|
|
|
|
## What doesn't go in notes
|
|
|
|
- facts every session needs: the project's `AGENTS.md`/`CLAUDE.md`, or memory when they are personal
|
|
- anything teammates need: the project repo
|
|
- secrets
|
|
- committed project files never reference `.notes/` paths
|