start-work

name	start-work
description	Start a Sisyphus work session from a Prometheus-generated plan. Manages boulder state, worktree setup, and delegates plan execution.

Start Work Session

Arguments

• /start-work [plan-name] [--worktree <path>]
  • plan-name (optional): name or partial match of the plan to start
  • --worktree <path> (optional): absolute path to an existing git worktree to work in
    • If specified and valid: sets worktree_path in boulder.json
    • If specified but invalid: run git worktree add <path> <branch> first
    • If omitted: work directly in the current project directory (no worktree)

Workflow

1. Find available plans: Search for Prometheus-generated plan files at .sisyphus/plans/

2. Check for active boulder state: Read .sisyphus/boulder.json if it exists

3. Decision logic:

   • If .sisyphus/boulder.json exists AND plan is NOT complete (has unchecked boxes):
     • Continue work on existing plan
   • If no active plan OR plan is complete:
     • List available plan files
     • If ONE plan: auto-select it
     • If MULTIPLE plans: show list with timestamps, ask user to select

4. Worktree Setup (ONLY when --worktree was explicitly specified):

   1. git worktree list --porcelain - see available worktrees
   2. Create: git worktree add <absolute-path> <branch-or-HEAD>
   3. Update boulder.json to add "worktree_path": "<absolute-path>"
   4. All work happens inside that worktree directory

5. Create/Update boulder.json:

   {
     "active_plan": "/absolute/path/to/plan.md",
     "started_at": "ISO_TIMESTAMP",
     "plan_name": "plan-name",
     "worktree_path": "/absolute/path/to/git/worktree"
   }
   

6. Read the plan file and start executing tasks

Output Format

When listing plans for selection:

Available Work Plans

1. [plan-name-1.md] - Modified: {date} - Progress: 3/10 tasks
2. [plan-name-2.md] - Modified: {date} - Progress: 0/5 tasks

Which plan would you like to work on? (Enter number or plan name)

When resuming existing work:

Resuming Work Session

Active Plan: {plan-name}
Progress: {completed}/{total} tasks
Worktree: {worktree_path}

Reading plan and continuing from last incomplete task...

Task Breakdown (MANDATORY)

After reading the plan file, you MUST decompose every plan task into granular, implementation-level sub-steps and register ALL of them as todos BEFORE starting any work.

How to break down:

• Each plan checkbox item must be split into concrete, actionable sub-tasks
• Sub-tasks should be specific enough that each one touches a clear set of files/functions
• Include: file to modify, what to change, expected behavior, and how to verify
• Do NOT leave any task vague

Example breakdown: Plan task: - [ ] Add rate limiting to API Sub-tasks:

1. Create src/middleware/rate-limiter.ts with sliding window algorithm (max 100 req/min per IP)
2. Add RateLimiter middleware to src/app.ts router chain, before auth middleware
3. Add rate limit headers to response in rate-limiter.ts
4. Add test: verify 429 response after exceeding limit
5. Add test: verify headers are present on normal responses

Worktree Completion

When working in a worktree and ALL plan tasks are complete:

1. Commit all remaining changes in the worktree
2. Sync .sisyphus/ state back to main repo before removal
3. Switch to the main working directory
4. Merge the worktree branch into the current branch
5. If merge succeeds, clean up: git worktree remove <worktree-path>
6. Remove the boulder.json state

Critical

• Always update boulder.json BEFORE starting work
• If worktree_path is set in boulder.json, all work happens inside that worktree directory
• Read the FULL plan file before delegating any tasks