workflows-work

What this skill does

# Work Plan Execution Command

## Runtime Tools

When this skill needs user questions, todo/progress tracking, subagents, or another skill, use the active runtime equivalents in [RUNTIME_TOOLS.md](../RUNTIME_TOOLS.md).


## Requirements

This skill needs file read/write/edit access, search access, shell access, task-management/delegation support, skill-loading support, and a way to ask the user for decisions. Tool permissions are configured by the active agent runtime, not by this shared skill.

Adhere to the Builder Ethos (ETHOS.md): Boil the Lake, Search Before Building, User Sovereignty.

Execute a work plan efficiently while maintaining quality and finishing features.

## Introduction

This command takes a plan folder (containing spec.md and prd.json) and executes stories systematically. The focus is on **shipping complete features** by following the PRD story breakdown, respecting dependencies, and maintaining quality throughout.

## Input

<input> $ARGUMENTS </input>

**Parse input:** Split arguments into `<path>` and optional flags (`--swarm`).

**If the path is empty, ask the user:** "Which plan would you like to work on? Provide the folder path (e.g., `docs/plans/2026-01-30-feat-user-auth/`)."

**If input is a folder:** Look for prd.json insides
**If input is a file:** Check if it's prd.json or spec.md, find sibling files

## Execution Workflow

### Phase 1: Load Plan

#### 1.1 Read Plan Files

```bash
# List plan folder contents
ls -la <input_path>/
```

Read both files:
- `spec.md` - For context, rationale, technical approach
- `prd.json` - For executable stories

**If prd.json doesn't exist:**
- Fall back to legacy mode (use spec.md + todo/progress tool)
- Suggest running `/sm-plan` to generate prd.json

#### 1.2 Parse PRD and Normalize Schema

PRDs come in two variants. Detect and normalize before proceeding:

**Schema detection:**
```
If stories[0] has "passes" field (boolean):
  → Lightweight schema: passes=true means completed, passes=false means pending
  → depends_on may be missing (default to [])
  → acceptance_criteria may be missing (fall back to steps[])
  → log/completed_at/commit may be missing (initialize as needed)

If stories[0] has "status" field (string):
  → Full schema from /sm-plan — use as-is
```

**Normalize each story to working state:**
```
For each story:
  story._effective_status =
    if story.status exists → story.status
    else if story.passes === true → "completed"
    else → "pending"

  story._effective_deps = story.depends_on ?? []
  story._effective_criteria = story.acceptance_criteria ?? story.steps ?? []
```

**Display current state:**
```
Plan: [title]
Stories: [total] ([pending] pending, [in_progress] in progress, [completed] completed)

Next stories ready to execute:
  #[id] [title] (priority: [priority])
  #[id] [title] (priority: [priority])

Blocked stories:
  #[id] [title] - blocked by #[depends_on]
```

**Initialize log if missing:**
If prd.json has no top-level `log` array, treat it as `[]`. Only append log entries if the PRD already has one (don't bloat lightweight PRDs).

#### 1.3 Sync Stories to Task System

Create a progress item for **every** story in prd.json (mirrors full state to the active runtime's todo/task UI):

```
For each story in prd.json.stories:
  create_progress_item({
    subject: "Story #[id]: [title]",
    description: "[category] | Priority: [priority]\n\nSteps:\n- [step1]\n- [step2]...\n\nAcceptance Criteria:\n- [criteria]",
    activeForm: "Implementing story #[id]: [title]",
    metadata: { story_id: [id], prd_path: "[path/to/prd.json]", category: "[category]" }
  })
```

**After creating all tasks, set up dependencies:**
```
For each story with depends_on:
  update_progress_item({
    taskId: "[task_id]",
    addBlockedBy: [task_ids of depends_on stories]
  })
```

**For already-completed stories** (resuming a partial run):
```
If story._effective_status === "completed":
  update_progress_item({ taskId: "[task_id]", status: "completed" })
```

Store the story_id → task_id mapping for use during execution.

#### 1.4 Clarify and Confirm

- Review spec.md for context and technical approach
- Read any referenced files from the spec
- If anything is unclear or ambiguous, ask clarifying questions now
- Get user approval to proceed
- **Do not skip this** - better to ask questions now than build wrong thing

### Phase 2: Setup Environment

#### 2.1 Validate Expected Branch

Check if prd.json specifies a branch:

```bash
expected_branch=$(cat <input_path>/prd.json | jq -r '.branch // empty')
current_branch=$(git branch --show-current)
```

**If prd.json has a `branch` field:**

| Current State | Action |
|---------------|--------|
| `current_branch === expected_branch` | Proceed to Phase 3 |
| `expected_branch` exists locally | Ask: "Switch to `[expected_branch]`?" then `git checkout [expected_branch]` |
| `expected_branch` doesn't exist | Create it: `git checkout -b [expected_branch]` |

**If branch mismatch and user declines to switch:**
- Warn: "Continuing on `[current_branch]` but prd.json expects `[expected_branch]`. Commits may not align with plan."
- Proceed only with explicit confirmation

#### 2.2 Branch Fallback (No branch in prd.json)

If prd.json has no `branch` field, fall back to legacy behavior:

```bash
default_branch=$(git symbolic-ref refs/remotes/origin/HEAD 2>/dev/null | sed 's@^refs/remotes/origin/@@')

# Fallback if remote HEAD isn't set
if [ -z "$default_branch" ]; then
  default_branch=$(git rev-parse --verify origin/main >/dev/null 2>&1 && echo "main" || echo "master")
fi
```

**If already on a feature branch** (not the default branch):
- Ask: "Continue working on `[current_branch]`, or create a new branch?"
- If continuing, proceed to Phase 3
- If creating new, follow Option A or B below

**If on the default branch**, choose how to proceed:

**Option A: Create a new branch**
```bash
git pull origin [default_branch]
git checkout -b feature-branch-name
```
Use a meaningful name based on the work (e.g., `feat/user-authentication`, `fix/email-validation`).

**Option B: Use a worktree (recommended for parallel development)**
```bash
git worktree add ../{repo}--feature-branch-name -b feature-branch-name
# Use absolute paths for all subsequent commands: cd ../{repo}--feature-branch-name && ...
```

**Option C: Continue on the default branch**
- Requires explicit user confirmation
- Only proceed after user explicitly says "yes, commit to [default_branch]"
- Never commit directly to the default branch without explicit permission

### Phase 3: Execute Stories

#### 3.1 Story Selection

Get next executable story (using normalized fields from Phase 1.2):
1. Filter stories where `_effective_status === "pending"`
2. Filter stories where all `_effective_deps` story IDs have `_effective_status === "completed"`
3. Sort by `priority` ascending
4. Take first story

If no stories are ready but some are blocked, report the blockers.

#### 3.2 Story Execution Loop

```
while (executable stories remain):

  1. SELECT next story (lowest priority, unblocked)

  2. UPDATE prd.json + Launch subagent `system`:
     - If full schema (has "status" field): set story.status = "in_progress"
     - If lightweight schema (has "passes" field): no prd.json change (passes is boolean, no "in_progress" equivalent)
     - If prd.json has "log" array: append { timestamp, story_id, action: "status_change", from: "pending", to: "in_progress" }
     - update_progress_item({ taskId: "[mapped_task_id]", status: "in_progress" })

  3. ANNOUNCE to user:
     "Starting story #[id]: [title]"
     Display acceptance criteria

  4. LOAD SKILLS (hard gate — blocks Step 5):
     If story.skills is non-empty, load every skill before writing any code.
     Implementation MUST NOT begin until all skills are loaded.

     For each skill in story.skills:
       -> Call the runtime skill loader: load skill `name` with the active runtime skill loader

     This is a prerequisite, not a suggestion. Skills dis