From 5bf468ddc20cf99bdb144629883af11fc90fceef Mon Sep 17 00:00:00 2001 From: Benjamin Borbe Date: Sat, 20 Jun 2026 22:08:19 +0200 Subject: [PATCH 1/2] =?UTF-8?q?feat(execute-task):=20add=20hard-gate=20sla?= =?UTF-8?q?sh=20command=20for=20planning=20=E2=86=92=20execution?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit New /vault-cli:execute-task is the missing third step of the create → plan → execute → complete lifecycle. The blocking sibling of /work-on-task's informational readiness nudge: refuses to flip phase: planning → execution unless plan-task's 4 hard non-negotiables re-pass (SC defined, subtasks reach goal, e2e verify subtask present, subtask-goal alignment). Idempotent on phase: execution — re-surfaces first unchecked subtask + DoD as session-start reminder. Refusal cases: - phase: todo / empty + status: in_progress → 'Planning gate not run. Run /plan-task first.' (planning non-skippable) - phase: done OR status: completed/aborted → 'Task closed. Run reopen' - Any hard check failed + phase: planning → lists failures + points to /plan-task Status entry contract: backlog/hold/next → flips to in_progress before running checks (resume-from-paused case). Output: '🎯 Start with: ' + '📋 When done, verify: ' — destination visible from step 1, prevents end-of-session dishonest ticks. Hard checks duplicated inline (not shared with /plan-task) per Notes section rationale; lift to a vault-cli task CLI verb if a third caller appears. Closes [[Phase-Gated Task Flow]] goal SC #2 for the planning → execution transition. Closes vault task [[Planning-To-Execution Transition Lacks Enforcement Gate]]. --- CHANGELOG.md | 4 ++ commands/execute-task.md | 147 +++++++++++++++++++++++++++++++++++++++ 2 files changed, 151 insertions(+) create mode 100644 commands/execute-task.md diff --git a/CHANGELOG.md b/CHANGELOG.md index 026827e..c5fa560 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -8,6 +8,10 @@ Please choose versions by [Semantic Versioning](http://semver.org/). * MINOR version when you add functionality in a backwards-compatible manner, and * PATCH version when you make backwards-compatible bug fixes. +## Unreleased + +- feat: new `/vault-cli:execute-task` slash command — the **hard gate** between planning and execution. Re-runs `/vault-cli:plan-task`'s 4 hard non-negotiables (Success Criteria defined, subtasks reach goal, e2e verify subtask, subtask-goal alignment); on pass, flips `phase: planning → execution` and prints first unchecked `# Tasks` subtask + `# Definition of Done` reminder. Refuses on `phase: todo` (planning non-skippable), `phase: done`, `status: completed/aborted` (closed tasks need explicit reopen), or any hard check failure (points to `/vault-cli:plan-task`). Idempotent on `phase: execution` — re-prints work block + DoD without mutation. Closes the lifecycle's last operational gap: every transition (`create → plan → execute → complete`) now has an enforced command. Stronger sibling of `/vault-cli:work-on-task`'s informational readiness nudge. + ## v0.82.0 - feat: `work-on-task-assistant` emits a one-line readiness nudge for Obsidian tasks (`✅ looks execution-ready` / `⚠ phase=planning / no Success Criteria / ... — run /vault-cli:plan-task first`). Shallow file-level check only — substance still belongs to `/vault-cli:plan-task`. Preserves work-on-task's content-agnostic core (no questions, no edits, no blocking) while closing the gap where a user starts work on a half-baked task without being nudged toward the planning gate. diff --git a/commands/execute-task.md b/commands/execute-task.md new file mode 100644 index 0000000..509a28c --- /dev/null +++ b/commands/execute-task.md @@ -0,0 +1,147 @@ +--- +description: Gate planning → execution. Re-runs plan-task's hard non-negotiables; on pass, flips phase + prints first subtask + DoD reminder. +argument-hint: (or detects from conversation) +allowed-tools: [Read, Edit, Glob, Bash, AskUserQuestion, Task] +--- + +The **hard gate** between planning and execution. Refuses to flip `phase: planning → execution` unless plan-task's 4 hard non-negotiables pass. Idempotent on `phase: execution` — re-prints first subtask + DoD as a session-start reminder. Closes the lifecycle's final operational gap: every phase transition now has an enforced command. + +This command **must stay inline** — it analyzes the parent conversation when no argument is given; a sub-agent cannot see the conversation. + +## When to use + +After `/vault-cli:plan-task` (or any time the plan is genuinely complete) to formally enter execution. Can also be re-run mid-session as "where was I?" — it re-surfaces the first unchecked subtask + DoD without side effects. + +```bash +/vault-cli:execute-task # detects from conversation +/vault-cli:execute-task "Some Task Name" +/vault-cli:execute-task 24\ Tasks/Some\ Task.md +``` + +## Process + +### 1. Resolve task path + +**With argument:** exact path if path-like, else `Glob` `/**.md` (vault-cli config respected). Multiple matches → list and STOP. Zero → STOP. + +**Without argument — detect from conversation** (same priority order as `/plan-task`): + +1. Most recent `/create-task` / `/plan-task` / `/work-on-task` output — scan the parent conversation for resolved task name. +2. Most recent `[[Task Name]]` wikilink referenced as a task subject. +3. Daily note's first `[/]` checkbox. +4. Most recently modified file in `/`. + +Multiple matches → ask via `AskUserQuestion`. Zero → `❌ No task detected. Pass a task identifier or name.` STOP. + +Print `Detected task: ` on first line so owner can interrupt before any state mutation. + +### 2. Read status + phase + +```bash +vault-cli task get "" status --output json +vault-cli task get "" phase --output json +``` + +### 3. Refusal cases (no mutation, exit non-zero) + +Refuse and STOP if any apply: + +- `status: completed` OR `status: aborted` → `❌ Task closed (status: ). Run reopen if you need to continue work.` +- `phase: done` → `❌ Task phase is done. Run reopen if work needs to resume.` +- `phase: todo` OR `phase` empty AND `status: in_progress` → `❌ Planning gate not run. Run /vault-cli:plan-task first.` (planning is non-skippable per [[Phase-Gated Task Flow]]) + +### 4. Status entry contract (mutate, then continue) + +If `status` is in `next` / `backlog` / `hold` → flip to `in_progress`: +```bash +vault-cli task set "" status in_progress +``` +Print: `ℹ️ Status: → in_progress (resume from )` + +If `status` is already `in_progress` → continue, no mutation. + +### 5. Run the 4 hard non-negotiables (re-check planning) + +Copy-paste from `/vault-cli:plan-task` § 5 *Hard* checks — DO NOT factor into a shared helper yet (keeps both commands self-contained; lift to a `vault-cli task verify-plan` CLI verb if a third caller appears). Read `~/.claude/plugins/marketplaces/vault-cli/docs/task-writing.md` as the canonical rule source. + +Check (in order, collect ALL failures — don't short-circuit): + +1. **Success Criteria defined** — `# Success Criteria` section exists with ≥ 2 binary checkboxes. +2. **Subtasks reach the goal** — `# Tasks` section lists concrete steps that, if completed, produce the SC outcomes. +3. **E2E verify subtask present** — for shipping-class tasks (PR / release / plugin update / agent / deploy / library publish; subtasks reference git repo / marketplace / registry), `# Tasks` must include a subtask with concrete procedure + observable outcome (no dishonest-tick phrases — see `plan-task.md:71-80` for the rejection list). +4. **Subtask-goal alignment** — every `# Tasks` checkbox maps by topic to ≥ 1 `# Success Criteria` outcome, OR is the e2e verify subtask. + +Skip check #3 entirely for non-shipping-class tasks (pure research, decision, doc-only with no published artifact). + +### 6. Phase transition or refusal + +**If ANY hard check failed AND `phase: planning`:** + +Print: +``` +❌ Plan not ready. Run /vault-cli:plan-task first. + +Failed checks: +- : +... +``` +STOP. Do NOT flip phase. + +**If all hard checks pass AND `phase: planning`:** + +```bash +vault-cli task set "" phase execution +``` +Print: `✅ Phase: planning → execution` + +Continue to step 7. + +**If `phase: execution` / `ai_review` / `human_review`:** no flip, no check (already past the gate). Continue to step 7 idempotently. Print: `ℹ️ Already in execution (phase: ) — re-surfacing context.` + +### 7. Surface first subtask + DoD (always — final output) + +Parse the task file: +- First unchecked `- [ ]` checkbox under `# Tasks` (or equivalent section) → "Start with" +- All `# Definition of Done` items → "When done, verify" + +Print: +``` +🎯 Start with: + +📋 When done, verify: +- +- +... +``` + +If `# Tasks` has zero unchecked items: print `✅ All subtasks complete — run /vault-cli:complete-task` instead of the "Start with" line. + +If `# Definition of Done` is absent or empty: omit the "When done, verify" block (no warning — some non-shipping-class tasks legitimately have no DoD). + +## Notes + +- **Idempotent re-entry.** Safe to re-run on `phase: execution` — no mutation, just re-prints the work block + destination. Useful as a session-start "where was I?" command. +- **Hard checks duplicated, not shared.** The 4 plan-task checks are re-implemented inline rather than factored into a sub-agent or shared CLI verb. Keeps both commands self-contained and fast; revisit if a third caller (e.g. `/vault-cli:complete-task` pre-check) needs the same logic. +- **Planning is non-skippable.** A task in `status: in_progress, phase: todo` (or empty phase) is refused with a pointer to `/plan-task`. This is the stricter sibling of `/work-on-task`'s informational nudge: nudge informs, execute-task blocks. +- **Status flips happen, phase flips don't (when planning gates fail).** Resume-from-paused is a separate concern from "is planning complete" — flipping `hold → in_progress` is always safe; flipping `planning → execution` requires the gates. +- **No daily-note tracking, no guide search.** Those belong to `/vault-cli:work-on-task`. This command is purely the gate + work-block kickoff. +- **Reads `~/.claude/plugins/marketplaces/vault-cli/docs/task-writing.md`** as the canonical rule source for the 4 hard checks — same source `/plan-task` and `task-auditor` use. + +## Integration + +Task lifecycle: + +1. `/vault-cli:create-task` — capture (lenient) +2. `/vault-cli:work-on-task` — orient (status + guides + daily note) +3. `/vault-cli:plan-task` — sharpen (5 hard gates; may flip phase if entry contract permits) +4. **`/vault-cli:execute-task`** — gate + kick off (this command) +5. *(execution: just code, no command)* +6. `/vault-cli:sync-progress` / `/vault-cli:update-task` — log progress +7. `/vault-cli:complete-task` — close + +Output ends with one of: +- `🎯 Start with: ` + `📋 When done, verify: ` (gate passed or idempotent re-entry) +- `❌ Plan not ready. Run /vault-cli:plan-task first.` (hard checks failed) +- `❌ Task closed (...). Run reopen if you need to continue work.` (status/phase terminal) +- `❌ Planning gate not run. Run /vault-cli:plan-task first.` (phase: todo) +- `❌ No task detected. Pass a task identifier or name.` (input error) From 6350bd88f6ef859b181038aebe9bf9569e879d9f Mon Sep 17 00:00:00 2001 From: Benjamin Borbe Date: Sat, 20 Jun 2026 22:30:06 +0200 Subject: [PATCH 2/2] pr-review fixes: add name + quote argument-hint; flesh out CHANGELOG MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Bot CHANGES_REQUESTED — 5 Should-Fix items applied: 1. Add 'name: execute-task' to frontmatter (skill-writing-guide compliance; siblings will follow over time) 2. Quote argument-hint value (the '<' is a YAML tag indicator; matches create-task.md + complete-task.md convention) 3. CHANGELOG: document the 4-priority task-detection chain 4. CHANGELOG: document the status entry contract (next/backlog/hold → in_progress as resume signal) 5. CHANGELOG: qualify hard check #3 (e2e verify) as shipping-class only — non-shipping tasks skip it NITs skipped (acknowledged as intentional in command Notes section or out of scope for this PR). --- CHANGELOG.md | 2 +- commands/execute-task.md | 3 ++- 2 files changed, 3 insertions(+), 2 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index c5fa560..a5035ca 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -10,7 +10,7 @@ Please choose versions by [Semantic Versioning](http://semver.org/). ## Unreleased -- feat: new `/vault-cli:execute-task` slash command — the **hard gate** between planning and execution. Re-runs `/vault-cli:plan-task`'s 4 hard non-negotiables (Success Criteria defined, subtasks reach goal, e2e verify subtask, subtask-goal alignment); on pass, flips `phase: planning → execution` and prints first unchecked `# Tasks` subtask + `# Definition of Done` reminder. Refuses on `phase: todo` (planning non-skippable), `phase: done`, `status: completed/aborted` (closed tasks need explicit reopen), or any hard check failure (points to `/vault-cli:plan-task`). Idempotent on `phase: execution` — re-prints work block + DoD without mutation. Closes the lifecycle's last operational gap: every transition (`create → plan → execute → complete`) now has an enforced command. Stronger sibling of `/vault-cli:work-on-task`'s informational readiness nudge. +- feat: new `/vault-cli:execute-task` slash command — the **hard gate** between planning and execution. Resolves the task via the 4-priority detection chain (explicit arg → recent `/create-task` or `/plan-task` output → most-recent `[[wikilink]]` task subject → daily-note's first `[/]` → MRU file in `/`). Promotes `status: next/backlog/hold → in_progress` as a resume signal *before* running the gate (silent state mutation operators should be aware of). Then re-runs `/vault-cli:plan-task`'s 4 hard non-negotiables (Success Criteria defined, subtasks reach goal, e2e verify subtask [shipping-class tasks only — PR/release/deploy/plugin/agent/library publish; skipped for pure research / decision / doc-only], subtask-goal alignment); on pass, flips `phase: planning → execution` and prints first unchecked `# Tasks` subtask + `# Definition of Done` reminder (or `✅ All subtasks complete — run /vault-cli:complete-task` if zero unchecked). Refuses on `phase: todo` / empty (planning non-skippable), `phase: done`, `status: completed/aborted` (closed tasks need explicit reopen), or any hard check failure (points to `/vault-cli:plan-task`). Idempotent on `phase: execution` / `ai_review` / `human_review` — re-prints work block + DoD without mutation. Closes the lifecycle's last operational gap: every transition (`create → plan → execute → complete`) now has an enforced command. Stronger sibling of `/vault-cli:work-on-task`'s informational readiness nudge. ## v0.82.0 diff --git a/commands/execute-task.md b/commands/execute-task.md index 509a28c..504c0c1 100644 --- a/commands/execute-task.md +++ b/commands/execute-task.md @@ -1,6 +1,7 @@ --- +name: execute-task description: Gate planning → execution. Re-runs plan-task's hard non-negotiables; on pass, flips phase + prints first subtask + DoD reminder. -argument-hint: (or detects from conversation) +argument-hint: " (or detects from conversation)" allowed-tools: [Read, Edit, Glob, Bash, AskUserQuestion, Task] ---