# Sequential Work Modes Implementation Plan

> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [x]`) syntax for tracking.

**Goal:** Add explicit implementation execution modes, a Next Up queue lane, and shared-workspace sequential execution for hierarchy work.

**Architecture:** Extend the contracts first so both web and runtime agree on `next_up`, `implementationExecutionMode`, and optional `workspaceTaskId`. Then update scheduling in `use-board-interactions` so sequential modes queue starts into Next Up and start only one running item. Finally route workspace metadata/session starts through `workspaceTaskId` and expose the mode in Settings.

**Tech Stack:** TypeScript, React, Zod contracts, Vitest, Tailwind/Radix UI already used by the app.

---

### Task 1: Contracts, Config, And Board Column

**Files:**
- Modify: `flow/contracts/src/api-contract.ts`
- Modify: `flow/runtime/src/config/runtime-config.ts`
- Modify: `flow/runtime/src/terminal/agent-registry.ts`
- Modify: `flow/web/src/data/board-data.ts`
- Modify: `flow/web/src/state/board-state.ts`
- Modify: `flow/web/src/state/drag-rules.ts`
- Modify: `flow/web/src/data/column-colors.ts`
- Modify: `flow/web/src/components/kanban-board.tsx`
- Modify: `flow/web/src/components/dependencies/dependency-overlay.tsx`
- Test: `test/runtime/config/runtime-config.test.ts`
- Test: `test/runtime/task-board-mutations.test.ts`

- [x] **Step 1: Write failing contract/config tests**

Add tests asserting that:
- board normalization inserts `next_up` between `backlog` and `in_progress`;
- runtime config defaults to `implementationExecutionMode: "parallel"`;
- saving `"sequential"` maps legacy booleans to false;
- saving `"sequential_same_workspace"` persists the explicit mode and keeps legacy booleans false.

Run: `npx vitest run test/runtime/config/runtime-config.test.ts test/runtime/task-board-mutations.test.ts`
Expected: FAIL because `next_up` and `implementationExecutionMode` are not defined.

- [x] **Step 2: Implement contracts/config/column plumbing**

Add:
```ts
export const runtimeImplementationExecutionModeSchema = z.enum([
  "parallel",
  "sequential",
  "sequential_same_workspace",
]);
export type RuntimeImplementationExecutionMode = z.infer<typeof runtimeImplementationExecutionModeSchema>;
```

Add `next_up` to `RUNTIME_BOARD_COLUMN_IDS` and `RUNTIME_BOARD_COLUMNS`, add optional `workspaceTaskId` to cards and task workspace metadata/info responses, add `implementationExecutionMode` to runtime config response/save schemas, and normalize legacy booleans through helper functions in `runtime-config.ts`.

Update web board defaults, column order, drag rules, column colors, and dependency overlay ordering to accept `next_up`.

- [x] **Step 3: Verify contract/config tests pass**

Run: `npx vitest run test/runtime/config/runtime-config.test.ts test/runtime/task-board-mutations.test.ts`
Expected: PASS.

### Task 2: Web Sequential Scheduler And Next Up Queue

**Files:**
- Modify: `flow/web/src/hooks/use-board-interactions.ts`
- Modify: `flow/web/src/hooks/use-task-start-actions.ts`
- Modify: `flow/web/src/hooks/use-linked-backlog-task-actions.ts`
- Modify: `flow/web/src/App.tsx`
- Test: `flow/web/src/hooks/use-board-interactions.test.tsx`

- [x] **Step 1: Write failing scheduler tests**

Add tests asserting that with `implementationExecutionMode="sequential"`:
- starting a parent starts only the first lowest executable descendant and moves remaining descendants to `next_up`;
- a second direct start while one session is running moves the requested item to `next_up` and does not call `startTaskSession`;
- when a running task becomes awaiting review, the first unblocked `next_up` item starts automatically.

Add a same-workspace test asserting descendants queued from a parent receive `workspaceTaskId` equal to the parent id.

Run: `npm --prefix flow/web run test -- src/hooks/use-board-interactions.test.tsx`
Expected: FAIL because the hook only supports the existing parallel boolean and has no `next_up` scheduling.

- [x] **Step 2: Implement scheduler helpers**

Introduce local helpers in `use-board-interactions.ts`:
- `isSequentialImplementationMode(mode)`;
- `isSameWorkspaceImplementationMode(mode)`;
- `getRunningTaskSessionIds(sessions)`;
- `queueTaskForSequentialStart(board, taskId, workspaceTaskId?)`;
- `startNextQueuedTaskIfIdle(board)`.

Use these helpers from direct starts, drag-to-In-Progress, bulk starts, dependency auto-pick, and parent starts. In sequential modes, use `next_up` for queued items and start only one running executable item.

- [x] **Step 3: Verify scheduler tests pass**

Run: `npm --prefix flow/web run test -- src/hooks/use-board-interactions.test.tsx`
Expected: PASS.

### Task 3: Shared Workspace Routing

**Files:**
- Modify: `flow/web/src/hooks/use-task-sessions.ts`
- Modify: `flow/web/src/hooks/use-cline-chat-runtime-actions.ts`
- Modify: `flow/web/src/hooks/use-git-actions.ts`
- Modify: `flow/web/src/stores/workspace-metadata-store.ts`
- Modify: `flow/runtime/src/core/api-validation.ts`
- Modify: `flow/runtime/src/trpc/runtime-api.ts`
- Modify: `flow/runtime/src/trpc/workspace-api.ts`
- Modify: `flow/runtime/src/workspace/task-worktree.ts`
- Modify: `flow/runtime/src/server/workspace-metadata-monitor.ts`
- Test: `flow/web/src/hooks/use-task-sessions.test.tsx`
- Test: `flow/web/src/hooks/use-git-actions.test.tsx`
- Test: `test/runtime/api-validation.test.ts`

- [x] **Step 1: Write failing workspace routing tests**

Add tests asserting:
- `ensureTaskWorkspace`, `fetchTaskWorkspaceInfo`, and `startTaskSession` use `workspaceTaskId` for filesystem scope while preserving visible `taskId`;
- git actions resolve metadata for a review card through `workspaceTaskId`;
- runtime parsing trims optional `workspaceTaskId`.

Run: `npm --prefix flow/web run test -- src/hooks/use-task-sessions.test.tsx src/hooks/use-git-actions.test.tsx && npx vitest run test/runtime/api-validation.test.ts`
Expected: FAIL because task workspace identity is currently always `task.id`.

- [x] **Step 2: Implement workspace routing**

Thread `workspaceTaskId` through task cards, workspace info requests/responses, task session starts, and task chat sends. Runtime `startTaskSession` and Cline chat fallback should resolve cwd with `body.workspaceTaskId ?? body.taskId`.

Store workspace metadata under the visible task id while preserving the filesystem owner id in the metadata object.

- [x] **Step 3: Verify workspace routing tests pass**

Run: `npm --prefix flow/web run test -- src/hooks/use-task-sessions.test.tsx src/hooks/use-git-actions.test.tsx && npx vitest run test/runtime/api-validation.test.ts`
Expected: PASS.

### Task 4: Settings UI And Prompt/CLI Behavior

**Files:**
- Modify: `flow/web/src/components/runtime-settings-dialog.tsx`
- Modify: `flow/web/src/runtime/runtime-config-query.ts`
- Modify: `flow/web/src/runtime/use-runtime-config.ts`
- Modify: `flow/web/src/platform/android/android-static-runtime.ts`
- Modify: `flow/runtime/src/prompts/append-system-prompt.ts`
- Modify: `flow/runtime/src/commands/task.ts`
- Test: `flow/web/src/components/runtime-settings-dialog.test.tsx`
- Test: `test/runtime/append-system-prompt.test.ts`

- [x] **Step 1: Write failing UI/prompt tests**

Add tests asserting the Settings dialog shows an "Implementation execution mode" select and saves `implementationExecutionMode`; prompt text mentions the selected mode.

Run: `npm --prefix flow/web run test -- src/components/runtime-settings-dialog.test.tsx && npx vitest run test/runtime/append-system-prompt.test.ts`
Expected: FAIL because the UI only has the legacy Parallel implementation switch.

- [x] **Step 2: Implement Settings and prompt updates**

Replace the visible Parallel implementation switch with a `NativeSelect` for the three modes. Keep save payloads writing the explicit mode and compatible booleans. Update prompt guidance and CLI start to use the saved mode by default.

- [x] **Step 3: Verify UI/prompt tests pass**

Run: `npm --prefix flow/web run test -- src/components/runtime-settings-dialog.test.tsx && npx vitest run test/runtime/append-system-prompt.test.ts`
Expected: PASS.

### Task 5: Final Verification And Closeout

**Files:**
- All changed files.

- [x] **Step 1: Run focused tests**

Run:
```bash
npx vitest run test/runtime/config/runtime-config.test.ts test/runtime/task-board-mutations.test.ts test/runtime/api-validation.test.ts test/runtime/append-system-prompt.test.ts
npm --prefix flow/web run test -- src/hooks/use-board-interactions.test.tsx src/hooks/use-task-sessions.test.tsx src/hooks/use-git-actions.test.tsx src/components/runtime-settings-dialog.test.tsx
```

- [x] **Step 2: Run typechecks**

Run:
```bash
npm run contracts:typecheck
npm run typecheck
npm run web:typecheck
```

- [x] **Step 3: Run browser QA**

Start the app on the canonical route if needed and verify `http://127.0.0.1:4217/project-test-zonegaze-flow-1` shows the Settings mode selector and Next Up lane between Backlog and In Progress.

- [x] **Step 4: Commit, merge to development, push, and refresh development app**

Commit the implementation branch after validation. Merge it into `development`, push `origin/development`, and refresh the canonical local app from `development`.
