okf-notebooks

The dev-project preset: running a software project

Running a project: glossary, ADRs, specs, tickets, research, bugs

A ready-made preset for a notebook where a team and its agents keep knowledge about a software project. Its types cover the domain glossary and ADRs, specs and tickets, research, prototypes, bug diagnosis and retrospectives. File: presets/dev-project.yaml.

Enabling it

Point config.yaml at the presets directory (in Docker it sits next to the config, for example /config/presets):

presets_dir: ./presets

Create the notebook:

uv run okf-notebooks notebook create my-project \
  --description "my-project development: glossary, decisions (ADR), specs, tickets, research and bugs" \
  --scope "Durable project knowledge: terms, ADRs, specs, tickets, research, bugs. No personal notes" \
  --preset dev-project

The presets directory is read on every access, no restart needed. A preset whose YAML is broken is skipped silently and --preset dev-project then reports “unknown preset”: check the file with yaml.safe_load.

Types

TypeDirectoryWhat it holdsRequired fieldsstale_after
Projectprojects/what the project is, how to run and test it—180d
Termterms/a glossary entry: a definition without implementation details, avoid lists words to avoid——
Decisiondecisions/an ADR: context, decision, alternatives, consequencesdecided—
Specspecs/a statement of work: problem, solution, user stories, out of scope—365d
Tickettickets/a task or bug with a brief and blocking ticketscategory, triage90d
Researchresearch/findings on a question, each fact linked to a primary sourcequestion180d
Prototypeprototypes/the question, what was built, what was learned, a verdictquestion90d
Bugbugs/symptom, reproduction, cause, fix and regression testsymptom—
Retroretros/a session retrospective: what slowed the agent down and what to change——
Playbookplaybooks/a repeatable procedure: release, deploy, setup—180d

Ticket.triage takes the roles needs-triage, needs-info, ready-for-agent, ready-for-human, wontfix; category is bug or enhancement.

How it works with agents

  • An agent finds the preset on its own: the presets_list tool returns the name, the description (“what it is for”) and the types of every preset, this one included.
  • status and verified are set by a human (Review UI or CLI): everything an agent writes stays draft until you verify it. That is why a ticket’s state lives in triage, not in status.
  • Aging by stale_after marks a note as stale in search: research and prototypes lose relevance quickly, ADRs and terms do not age on their own.
  • Add a line to your project’s AGENTS.md such as “write decisions, specs and research to the my-project notebook and choose the type from the type description in notebook_describe” (the rules block: okf-notebooks print-agent-guide).

Making your own variant

Copy presets/dev-project.yaml, rename it and adjust the types. The rules, the 12-type limit and the format are in presets.md.

This preset is one example of a format, not a requirement. If your case is different, design your own types or ask an agent to propose them.