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 storytargets the current sprint andadd sprintthe current version.add taskhas 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
* Storiestable) 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'sv2_doc_generate.pyalready exposedmain(argv), so no refactor was needed — compass imports it and callsv2_doc_generate.main(["--type", t, ...]). The import is lazy (insideadd) because it pulls inpystache, which the other compass commands do not need.- Parent defaulting via Locate only covers the unambiguous cases
(
story→ current sprint,sprint→ current version).add taskrequires an explicit--parent-dirsince "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).