Story: ores.compass Scaffold — agile authoring over codegen

Table of Contents

This page documents a story in Sprint 18. It captures the goal, current status, acceptance criteria, and the tasks that compose it.

Goal

A contributor can create new agile artefacts — a story in the current sprint, a task in a story, a new sprint, a recipe, a capture — directly from the ores.compass CLI, without having to remember the codegen invocation, the parent directory, or the flag names. This is the Scaffold pillar of the ores.compass component. Compass is a thin, ergonomic front-end; the actual document generation is delegated to ores.codegen's generate_v2_doc.sh, honouring the non-negotiable rule that new .org docs are produced by codegen only — never hand-written.

Status

Field Value
State DONE
Parent sprint Sprint 18
Now Complete — add shipped in PR #815.
Waiting on Nothing.
Next Done.
Last touched 2026-05-24

Acceptance

  • compass.sh add story|task|sprint|recipe|capture … creates the artefact by calling ores.codegen as a library (its v2-doc generation API), passing type, slug, parent-dir, title, description and tags.
  • Compass does not reimplement frontmatter, UUID minting, or template rendering, and does not copy the generator into compass — generation stays in codegen, navigation stays in compass, no functionality is duplicated between the two.
  • "Current" defaults are resolved via the Locate pillar where unambiguous: add story targets the current sprint and add sprint the current version. add task has no single "current story", so it requires an explicit --parent-dir; other types likewise.
  • After creation it prints the generated path and reminds the user to wire the artefact into its parent's table (e.g. the sprint's * Stories table) where codegen does not do so automatically.
  • Behaviour and CLI surface are documented in the component overview Entry points.

Tasks

Task State Start End Description
Task: Implement the add command DONE 2026-05-24 2026-05-24 Add a compass add subcommand that calls ores.codegen as a library to create v2 docs.

Decisions

  • Division of labour: codegen generates, compass navigates. Scaffold uses codegen as a library (in-process), not by shelling out and not by copying the generator. No functionality is duplicated between the two components.
  • ores.codegen's v2_doc_generate.py already exposed main(argv), so no refactor was needed — compass imports it and calls v2_doc_generate.main(["--type", t, ...]). The import is lazy (inside add) because it pulls in pystache, which the other compass commands do not need.
  • Parent defaulting via Locate only covers the unambiguous cases (story → current sprint, sprint → current version). add task requires an explicit --parent-dir since "current story" is not well-defined.

Out of scope

  • Draining the capture buffer into stories/tasks — that is a separate capture-drain skill, not part of compass scaffolding.
  • Editing, closing, or transitioning existing artefacts.
  • Automatically wiring artefacts into parent tables (compass reminds; it does not edit the parent doc in this iteration).

Emacs 29.1 (Org mode 9.6.6)