Start work on a new story

Take a story from idea to open PR — scaffold, fill in, branch, mark STARTED, wire into the sprint, commit, push, and open a pull request.

• You have a story idea with a slug, title, description, and tags.
• Current sprint exists (doc/agile/versions/v0/sprint_NN/).
• compass and gh CLI are installed and authenticated.
• SSH_AUTH_SOCK is exported (see SSH memory).

In execution order:

1. Ensure main is up to date. If you are not already on main, fetch without switching branches so the new branch starts from the latest remote state:

   git fetch origin main
   

   compass story new also fetches main internally, but doing it explicitly first makes divergence visible before any files are created.

2. Scaffold the story. Use How do I start a unit of work with compass? — specifically compass story new — to create the feature branch, scaffold the story, and link a task in one step:

   ./projects/ores.compass/compass.sh story new \
     --slug my_feature --title "My feature" \
     --description "What it delivers." --tags "topic"
   

   This fetches main, creates feature/my-feature, and writes three documents into the current sprint: story.org, a scaffold task (STARTED, owning the branch — the scaffold PR closes it), and the first real task (BACKLOG, no branch). To add a task to an existing story instead, use compass task new --story <id>.

2a. Prefer content at scaffold time. Pass --goal and --acceptance so the docs are born complete. When editing afterwards anyway, read every generated file first and use the real :ID: values — never placeholder UUIDs.

1. Already clocked on. story new clocks on to the scaffold task automatically (STARTED + journal). The first real task is picked up later, when its work begins:

   ./projects/ores.compass/compass.sh task start <first-task-slug>
   

   task start derives feature/<slug-kebab> when the task has no #+branch: (override with --branch).

2. Complete the prose. Whatever was not supplied at scaffold time: * Out of scope, extra * Tasks rows beyond the scaffolded one (each compass add task wires its own row), and any [[id:UUID]] cross-references.
3. Mark the story STARTED. compass task start (step 3) already set the story state and table row; fill the prose Now / Next fields by hand.
4. Wire into the sprint. Add a row to the parent sprint's * Stories table. Each row: | [[id:UUID][Title]] | STARTED | date | | Theme |.
5. Commit the status change. Use ORE Studio commit conventions: [agile] Mark <story> STARTED with a Co-Authored-By: trailer.
6. Open the scaffold PR. compass pr create --title "[agile] ..." ... per How do I create a PR? — it pushes the branch, builds the body (Summary / Changes / Traceability), records the PR on the scaffold task, and stamps the journal.

7. Close the scaffold task before merging. The bookkeeping rides the PR — never a follow-up PR:

   ./projects/ores.compass/compass.sh task done scaffold_<slug>
   

   Commit, push, and merge with compass pr merge — merge never touches task state.

• Story is STARTED in the current sprint and wired into the sprint's * Stories table.
• The scaffold PR is merged into main and its remote branch deleted; the PR number is recorded in the scaffold task's * PRs table.
• The scaffold task is DONE with its close-out commit inside the merged PR; the first real task remains BACKLOG until its work begins.

• Add a task to an existing story — use this instead when the story already exists and you only need a new task.
• How do I start a unit of work with compass? — compass story new and compass task new syntax, --dry-run flag.
• Product backlog — where captures live before becoming stories; the next, deferred, and discarded buckets; how to promote a capture into a sprint.
• How do I address PR review comments? — what comes after the PR is open.
• ORE Studio commit conventions — commit format reference.
• Work a task through to merged PR — the next runbook: from task pickup to merge.