next

Files (1)

• SKILL.md

SKILL.md (first lines)

# fsad-harness:next — pick the next ready task and hand off to do-task

You find the most **ready** unchecked task(s) in the current project's todo file and invoke `fsad-harness:do-task` with the chosen ID(s). Readiness — not file order — decides which candidate wins.

## Asking the user

This rule covers every question this skill asks the user: a confirmation, a choice, a missing value, a numbered decision list, or a stop-and-ask. It applies even where a later step says "ask the user" or "ask exactly once". The user may watch the decisions pane rather than the chat, so a question that only goes to chat can go unanswered.

- **When `mcp__decision-tracker__decision` is in your tool list** (loaded, or named as a deferred tool; load a deferred one with `ToolSearch` first), log each question before you ask it:
  1. Call it with `action: "open"`, the question (ending in `?`), and `options` when the answers are a closed set. Set `required: false` when the work can go on without an answer. A numbered list of questions opens one decision per item. Keep each returned `id`.
  2. Ask the question in chat as this skill says. The open call does not replace the chat question.
  3. When the user answers, in chat or as a `Decision Dn: <answer>` message from the plugin, call the tool with `action: "close"`, the `id` and the answer.
  4. When the change the answer asked for is in place, call it with `action: "implement"`, the `id` and a `path:line`.
- **When the tool is absent**, ask in chat only.
- An `AskUserQuestion` call is logged on its own. Do not open it again.
- This rule changes where a question is logged. It does not change when this skill asks, or how many times.

## Step 0 — Detect the project

1. Determine the current working directory.
2. Read `${CLAUDE_PLUGIN_ROOT}/skills/add-task/add-task-projects.yaml`.
3. Match cwd against each project's `match_paths` (expand `~`). Prefer the longest (most specific) match if multiple match.
4. If a project matches, refer to its entry as `cfg` and the resolved project root as `project_root`. Proceed.
5. If **no project matches** in `add-task-projects.yaml`:
   - Tell the user the project is not registered.
   - Suggest running `/fsad-harness:add-task` from the project to register it.
   - Stop.

## Step 1 — Parse the optional count argument

`$ARGUMENTS` is either empty or a single positive integer `N`.

- Empty → `N = 1`.
- A positive integer → `N` = that value.
- Anything else (non-numeric, zero, negative) → tell the user: "Expected an optional count, e.g. `/fsad-harness:next` or `/fsad-harness:next 3`." Stop.

## Step 2 — Find candidate open tasks (targeted grep, not a full-file Read)

Run a targeted grep against the todo file instead of reading it in full:

```bash
grep -nE '^- \[ \] .*{prefix}-[0-9]+' "{todo_file_path}"
```

Use the resolved absolute path for `{todo_file_path}` and quote it to handle spaces. This returns only the open (`- [ ]`) lines that mention the project's `cfg.prefix`, each with its line number — never pull the whole backlog into context.

- **No matches**: tell the user "No open tasks found in `[cfg.todo_file]`. All done!" Stop.
- **One or more matches**: extract the canonical `PREFIX-NNN` identifier from each matching line. These are the candidate set. Continue.

## Step 3 — Rank candidates by readiness

For each candidate ID, gather three readiness signals without a full-file read:

1. **Has a task-detail file** — check whether `{project_root}/{cfg.task_dir}/{rendered cfg.task_filename_template}` exists for that ID (same path resolution `do-task` uses). A candidate with an existing task-detail file already has a plan drafted and is ready to execute immediately.
2. **No stated unmet dependency** — inspect the candidate's todo-line text (and, if it has a task-detail file, its Summary/Assessment section) for an explicit reference to another task ID as a blocker (e.g. "depends on TBS-040", "blocked by", "after TBS-045 lands"). If that referenced task is not yet checked `[x]` in the todo file, treat the candidate as **not ready**.
3. **Well-formed task-detail file** — only evaluated when signal 1 found a file. Run three targeted greps against it (never a full-file Read); the file is well-formed only if **all three** pass:
   - **ID matches filename** — the H1 starts with `# {ID} —` where `{ID}` is the canonical identifier the filename was rendered from: `grep -c "^# {ID} —" "{task_file}"` ≥ 1.
   - **≥1 unchecked AC** — the `## Acceptance Criteria` section itself (not the Plan or any other section) contains at least one `- [ ]` item: `awk '/^## Acceptance Criteria/{f=1;next} /^## /{f=0} f && /^- \[ \]/' "{task_file}" | grep -c .` ≥ 1. A file whose ACs are all `[x]` (or that has none) has nothing left for `do-task` to verify.
   - **No template placeholders** — no line still carries the task-file template's bracketed placeholders outside inline code (a task that *talks about* `[TBD]` in backticks is fine; one that still *contains* it as prose is not): `sed 's/`[^`]*`//g' "{task_file}" | grep -nE '\[TBD\]|\[Step (one|two)\]|\[Verification step [0-9]+\]|\[Where —|\[1–3 sentences|\[Current state\.|\[file path\]|\[section/line reference\]'` returns nothing.

   A candidate whose file fails any check is **not Tier 1** — it drops to Tier 2 with the failing check named in the report (the plan is not executable as written, so `do-task` must stop and re-plan before it can run). Do not "fix" the file here; `fsad-harness:next` never edits task files.

Rank the candidate set:

- **Tier 1 — ready**: has a well-formed task-detail file AND no unmet dependency.
- **Tier 2 — plannable**: no unmet dependency, but either no task-detail file (would enter `do-task` plan mode) or a task-detail file that fails a well-formed check (needs re-planning first).
- **Tier 3 — blocked**: has a stated unmet dependency. Exclude from selection unless every candidate is Tier 3 (in which case surface this to the user rather than silently picking one).

Within a tier, preserve file order (top-to-bottom) as the tiebreaker.

Select the top `N` candidates from this ranking (Tier 1 first, then Tier 2, then Tier 3 only if nothing else is available).

Report the choice and reason before proceeding, e.g.:

> Selected **TBS-042** (Tier 1 — ready: task-detail file exists and is well-formed, no unmet dependency) over TBS-043 (Tier 2 — task file fails well-formed check: no unchecked `- [ ]` AC) and TBS-044 (Tier 3 — blocked: references open TBS-041).

If `N > 1`, list all selected candidates with their tier and reason in the same format.

## Step 4 — Verify before handoff

Before invoking `do-task`, validate every selected ID:

1. Each ID matches the canonical `PREFIX-NNN` pattern exactly — correct prefix casing (`cfg.prefix`), a literal hyphen, and a numeric suffix zero-padded to `cfg.number_digits` digits.
2. Each ID corresponds to exactly one open (`- [ ]`) line in the candidate set from Step 2 — no duplicates, no ambiguous partial matches (e.g. two lines that could both plausibly resolve to the same prefix/number).

If any selected ID fails either check — malformed pattern, or an ambiguous/duplicate match — **stop and ask** the user to disambiguate rather than guessing or handing off a bad value. Show the conflicting lines so the user can pick.

If `N` exceeds the number of available (non-Tier-3, or all-Tier-3-if-forced) candidates, hand off as many as are available and tell the user how many were found vs. requested.

## Step 5 — No open tasks

(Covered in Step 2 — no separate action needed here.)

## Step 6 — Hand off to do-task

Resolve `desired_skill` = `cfg.skills.do_task` (if set) → else the YAML's top-level `defaults.skills.do_task` (if set) → else `"fsad-harness:do-task"`. Use `desired_skill` (not a hardcoded `fsad-harness:do-task`) for every handoff below, so a project configured for e.g. `kh:do-task` is respected here too.

- **`N = 1`**: Tell the user which task was selected and why, e.g.:

  > Next task: **TBS-006** — "Add a new skill `fsad-harness:next`" (Tier 1 — ready). Handing off to `{desired_skill}`…

  Then invoke `desired_skill` via the Skill tool, passing the single canonical task identifier as the argument.

- **`N > 1`**: Tell the user the full ranked list being dispatched, e.g.:

  > Dispatching 3 ready tasks to `{desired_skill}`: **TBS-042, TBS-044, TBS-046**.

  Then invoke `desired_skill` via the Skill tool, passing all selected canonical identifiers space-separated as a single argument string (e.g. `TBS-042 TBS-044 TBS-046`). If `desired_skill` is `fsad-harness:do-task`, its own Step 0.5 multi-task dispatch takes over from there — each ID is planned/executed concurrently in its own isolated worktree. Other skills may handle multi-ID dispatch differently; consult that skill's own instructions.

From tbeack/fsad_playbook, MIT.

More from tbeack/fsad_playbook