Task: goto: add a task to an existing story
This page documents a task in the compass goto: start a unit of work in one command story. It captures the goal, current status, acceptance, and any notes or results.
Goal
Extend compass goto so it can also start work on an existing
story: branch + add a task to that story, instead of only ever creating
a new story. Today goto always scaffolds a new story and fails if the
slug already exists.
Status
| Field | Value |
|---|---|
| State | DONE |
| Parent story | compass goto: start a unit of work in one command |
| Now | Implemented; both modes verified via –dry-run. |
| Waiting on | Nothing. |
| Next | Review. |
| Last touched | 2026-05-25 |
Acceptance
- Existing-story mode:
compass goto --story <id-or-slug> --task-slug <slug> --task "<title>" [--description …]fetches main, creates a feature branch (feature/<task-slug>), adds a task to the resolved story (viaadd), sets the task#+branch:, and prints next steps. --storyresolves by:ID:(UUID or unambiguous prefix) or by the story's folder slug, usingdoc_index.--storyis mutually exclusive with the new-story flags (--slug=/–title=/=–description=); a clear error if both/neither are given.- New-story mode is unchanged;
--dry-runworks for both.
Plan
Interface decision ("have a think"): keep the current new-story mode and
add an existing-story mode keyed on --story:
--story <id-or-slug>→ existing-story mode. Resolve viadoc_index: if the value is hex it matches a story:ID:(or prefix); otherwise it matches the story folder name (slug). Accepting both keeps it ergonomic (humans know slugs; tooling/links know UUIDs).- Required with
--story:--task-slugand--task(title);--descriptionoptional. Branch defaults tofeature/<task-slug>. - Mutually exclusive with
--slug=/–title=/=–description= (new-story).
Steps:
- Add
--story/--task-slugtocmd_goto's argparse; validate the two modes are not mixed. resolve_story(ident)→ (story_dir, story_title) viadoc_index.- In existing mode: branch from
task-slug; skip story creation; oneadd task --parent-dir <story_dir>; set#+branch; next steps. - Dry-run + dogfood; update component overview + the goto recipe.
Notes
Verified via --dry-run for both modes (existing-story by folder slug
and by :ID: prefix; new-story unchanged) and the three error paths
(mixed modes, --story without task, unknown story). The execution path
(git switch + add task --parent-dir) is the one already exercised by
new-story goto and by add.
PRs
| PR | Title |
|---|---|
| #838 | [ores.compass] goto: add existing-story mode (–story) |
Review
| Comment summary | File | Decision | Notes |
|---|---|---|---|
Result
cmd_goto now has two modes. Existing-story mode: goto --story
<id-or-slug> --task-slug <slug> --task "<title>" [--description …]
resolves the story via resolve_story (by :ID: exact/prefix or folder
slug), branches feature/<task-slug>, adds a task to the existing story
(add), sets #+branch, and prints next steps. New-story mode is
unchanged. The two modes are mutually exclusive with clear validation.