Add a task to an existing story

Add a new task to an existing story: scaffold the task doc, fill in its content, wire it into the parent story, mark it STARTED, and open a PR.

• The target story exists in the current sprint (doc/agile/versions/v0/sprint_NN/<story-slug>/story.org).
• You have a task idea: slug, title, description, goal, and acceptance criteria.
• compass and gh CLI are installed and authenticated.
• SSH_AUTH_SOCK is exported (see SSH memory).

In execution order:

1. Find the story directory. If you know the story slug, the directory is doc/agile/versions/v0/sprint_NN/<story-slug>/. Otherwise locate it with compass:

   ./compass.sh search "<story topic>"
   

2. Scaffold the task. Use compass add task --parent-dir — the non-interactive form that writes the task doc and wires the story's * Tasks row in one step. Pass --goal and repeatable --acceptance so the doc is born complete:

   ./compass.sh add task \
     --parent-dir doc/agile/versions/v0/sprint_NN/<story-slug> \
     --slug <task_slug> \
     --title "Task title" \
     --description "One-sentence description." \
     --goal "What this task produces." \
     --acceptance "First verifiable criterion." \
     --acceptance "Second verifiable criterion."
   

   --parent-dir locates the story by its directory path; compass reads the :ID: from story.org automatically. The task doc is written under the story directory and a row is appended to * Tasks (state BACKLOG). No branch is created at this stage; that happens at task start time.

   Interactive alternative: compass task new --story <uuid-or-slug> does the same but prompts for missing fields on stdin. Use only in a terminal session, never from a non-interactive script. See How do I start a unit of work with compass?.

3. Complete the task content. If --goal and --acceptance were passed above, the doc is already filled. Otherwise open the generated task_<slug>.org and complete:

   • * Goal — what user-visible or internal change this task produces.
   • * Acceptance — verifiable criteria (each a bullet; no vague language).

   Every internal-doc reference must use an [[id:UUID]] link, never a relative path.

4. Update the story status. The * Tasks row is wired automatically by compass add task. The only manual update is the story's * Status table: refresh Now, Next, and Last touched to reflect the new task.

5. Commit the scaffold. Use ORE Studio commit conventions:

   git add doc/agile/versions/v0/sprint_NN/<story-slug>/
   git commit -m "[agile] Add task <slug> to <story> story
   
   Story-ID: <story-UUID>
   Task-ID: <task-UUID>
   Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>"
   

6. Decide PR strategy. Ask the user: "Do you want to do the task work now and open one combined PR, or open a scaffold-only PR first?"
   • Combined (default): do the task work on this branch, then open a single PR covering scaffold + work. This is preferred for short tasks.
   • Scaffold-only: open the PR now with just the scaffold, then continue work in a follow-up commit. Use this only when the task work is large or needs a separate review pass.
7. Push and open a PR. Push the branch, then follow How do I create a PR? — title [COMPONENT] Description, body sections Summary / Changes / Traceability. Record the PR number in the task's * PRs table.

• Task doc is BACKLOG (or STARTED once picked up) under the story directory.
• Task is wired into the parent story's * Tasks list.
• Parent story's * Status table reflects the new task.
• PR is open with Story-ID and Task-ID in the body.

• How do I work a task? — the next step: picking up, executing, and closing the task.
• Start work on a new story — use this instead when the story itself does not yet exist.
• How do I start a unit of work with compass? — compass task new (interactive) and compass add task (non-interactive) syntax and options.
• How do I start work on a story? — story-level branch creation and BACKLOG→STARTED transition.
• Work a task through to merged PR — the next runbook: from task pickup to merge.
• ORE Studio commit conventions — commit format reference.