How do I add a doc with compass?

Table of Contents

The Scaffold pillar of the compass tool. add is a thin front-end over ores.codegen's generator (called as a library) — for the full set of flags per document type, see How do I create a new doc?.

Prefer story new / task new for starting work. compass story new creates both a story and a linked task, fetches main, and creates a feature branch in one step. Use add when you need the primitive: scaffolding a single document (a standalone task inside an existing story, a sprint, a recipe, etc.) without the branch/task side-effects.

Question

How do I create a new document (story, task, sprint, recipe, …) from the compass CLI, without remembering the codegen invocation or the parent directory?

Answer

Run compass.sh add <type> [flags]. The flags after <type> are passed straight to the generator (--slug, --title, --description, --tags, …).

  1. Add a story to the current sprint — --parent-dir is defaulted from where we are, so you can omit it: 

    ./projects/ores.compass/compass.sh add story \
  --slug my_new_story --title "My new story" \
  --description "One-line summary." --tags "topic"

  2. Add a task to a story — task has no single "current story", so give --parent-dir explicitly: 

    ./projects/ores.compass/compass.sh add task \
  --parent-dir doc/agile/versions/v0/sprint_18/my_new_story \
  --slug my_task --title "My task" --description "…"

  3. Add a sprint — defaults --parent-dir to the current version: 

    ./projects/ores.compass/compass.sh add sprint \
  --slug sprint_19 --title "Sprint 19" --description "…"

  4. Add a facet or facet-group doc — the literate template library under projects/ores.codegen/library/templates/ (the default --parent-dir for both types). A facet doc is the literate source for one template family, tangling to its .mustache artefacts; it requires --facet-group naming its group. A facet_group doc is the namespace page indexing a group's facets (written as <slug>_group.org): 

    ./projects/ores.compass/compass.sh add facet \
  --slug cpp_domain_type --facet-group cpp \
  --title "C++ domain type templates" --description "…"
./projects/ores.compass/compass.sh add facet_group \
  --slug cpp --title "C++ template group" --description "…"

    After adding or changing facet docs, regenerate the group inventories: 

    python3 projects/ores.codegen/scripts/regenerate_facet_inventories.py

Compass wires the new story/task into its parent's * Stories / * Tasks table automatically (state BACKLOG) — no manual edit of the parent is needed.

Note: --type is supplied by compass from the <type> positional — do not pass it yourself (the --help output shows the underlying generator's flags, including --type, but add expects the type as a positional argument).

Script

projects/ores.compass/compass.sh add → src/compass.py (cmd_add), which imports ores.codegen's doc_generate and calls doc_generate.main(["--type", <type>, …]). Needs pystache (in requirements.txt); only add does.

Tested by

Manual smoke test (add story into the current sprint; cleaned up).

See also

Emacs 29.1 (Org mode 9.6.6)