Managing Tasks

Managing Tasks

Skill collection for durable, handoff-ready task work on disk. Works in any environment where the agent can read and write repository files.

Contract: `references/task-contract.md` — tasks root index.md marker, author UUID, layout, frontmatter, status fields, skill discovery.

Rule: Read exactly one recipe below for the user's intent. Do not load other recipe files unless the user switches intent mid-session.

When to use

Follow this skill for every task-lifecycle action under <tasks-root>/NNN-slug/: planning, executing, checking status, amending scope, blocking, verifying, archiving, reopening, skipping, or cancelling.

Tasks root: Located only via <tasks-root>/index.md with the static Author signature UUID in frontmatter. If none exists, ask the user for an empty folder path, then initialize with index.md before any task folder. See task-contract.md → Resolve tasks root.

Task recipes

Load this skill when intent matches any row, whether the user @-mentions the skill or describes the work in natural language.

Reference index

Templates

• `assets/index.md`
• `assets/plan.md`
• `assets/status.md`

Examples

Create (new repo): No index.md found → ask user for an empty folder (e.g. tasks/) → write tasks/index.md then tasks/001-dark-mode-toggle/plan.md + status.md → suggest _"Continue tasks/001-dark-mode-toggle"_.

Execute: User says continue tasks/001-dark-mode-toggle. Follow executing-task.md → read status.md first → run next_step_id.

Update: User adds a phase to an in-progress task. Follow updating-task.md → bump plan_revision → sync step queue.

Check: User asks "what's the status of the dark mode task?". Follow checking-task.md → read status.md → report without mutating files.

Triage: User asks "what can I work on?". Follow triaging-tasks.md → scan all tasks → split into startable now vs not ready with blocker type and unblock action.

Tasks

This folder is the tasks root for structured task folders managed by the managing-tasks skill.

Tasks

{{TASK_TITLE}} ({{TASK_ID}})

Goal

{{WHAT_DONE_LOOKS_LIKE}}

Non-goals

• {{OUT_OF_SCOPE_1}}
• {{OUT_OF_SCOPE_2}}

Context

• Area: {{package, app, or subsystem}}
• Primary files: {{paths}}
• Skills to load: {{skill names, or "none"}}
• References: {{basenames from chosen skill(s) — recipes, index, or references/ — e.g. creating-feature or skill-name/creating-feature — or "none"}}
• Related tasks: {{links to sibling task folders, or "none"}}

Current vs target

{{Brief bullet diff or mermaid diagram if helpful}}

Phases

Phase 1 — {{TITLE}}

{{Concrete steps with file paths and patterns to follow.}}

Phase 2 — {{TITLE}}

{{...}}

Verification checklist

• [ ] {{acceptance criterion 1}}
• [ ] {{acceptance criterion 2}}
• [ ] Typecheck / lint passes for affected packages
• [ ] Manual smoke: {{flow}}

Risks

Task status — {{TASK_ID}} {{TASK_TITLE}}

Execution source of truth for `plan.md`. Read this file first in every new agent session.

Agent startup protocol

1. Open this file and read the Execution pointer 2. Open plan.md for step details and acceptance criteria 3. Pick the workflow from managing-tasks → Task recipes (usually executing-task.md) 4. Execute next_step_id unless status is Blocked or Cancelled 5. Update this file before ending the session (pointer, queue, handoff note)

Execution pointer

• task_id: {{TASK_ID}}
• task_folder: {{TASKS_ROOT}}/{{TASK_FOLDER}}/
• overall_status: Not Started
• current_step_id: none
• next_step_id: {{FIRST_STEP_ID}}
• blocking_reason: None
• cancel_reason: None
• handoff_note: Task created. Start with {{FIRST_STEP_ID}} per plan.md.

Step queue

Check off steps as completed. The executor should always pick next_step_id unless blocked or cancelled.

• [ ] {{FIRST_STEP_ID}} — {{short description}}
• [ ] {{SECOND_STEP_ID}} — {{short description}}
• [ ] verify — Run verification checklist in plan.md

Session log

Archiving a task

Move completed or cancelled tasks to archive/. No implementation in this workflow.

1. Resolve scope

Per task-contract.md → Resolve tasks root and Finding tasks root.

Resolve <task-folder> for a single task under <tasks-root>/. For batch, discover tasks per Finding existing tasks, then filter by overall_status (Done and/or Cancelled as the user specifies).

2. Eligibility

Archive only when overall_status is Done or Cancelled.

If the task is In Progress, Blocked, or Review → confirm with the user before archiving (unusual).

3. Move folder

For each task to archive:

1. Ensure <tasks-root>/archive/ exists (create if missing) 2. Move <tasks-root>/<NNN>-<slug>/ → <tasks-root>/archive/<NNN>-<slug>/ 3. Update task_folder in status.md to the new path 4. Append session log: date, —, Archived, optional note

Do not delete task folders unless the user explicitly requests deletion.

4. Confirm to the user

Reply with:

• Original and archive paths for each moved task
• Count of tasks archived in batch mode

Do not implement application code in this workflow.

Blocking a task

Mark a task as blocked when work cannot proceed. No implementation in this workflow.

1. Resolve task folder

Per task-contract.md → Resolve tasks root and Finding tasks root.

Resolve <task-folder> from the user's message under <tasks-root>/. If unclear, list folders per Finding existing tasks and ask. Read status.md, then plan.md.

If overall_status is Cancelled or Done → stop and tell the user.

2. Record blocking reason

Require a concrete blocking_reason from the user or context, e.g.:

• Waiting on external API or credentials
• Design review pending
• Upstream dependency not merged

3. Update status.md

1. Set overall_status: Blocked 2. Set blocking_reason: <reason> 3. Keep current_step_id and next_step_id unchanged — do not advance or check off steps 4. Update handoff_note: blocked; what must resolve before continuing 5. Append session log: date, current or next_step_id, Blocked, reason

Do not change plan.md frontmatter todo statuses.

4. Confirm to the user

Reply with:

• Task folder and blocking_reason
• Frozen next_step_id
• What to do when unblocked (unblocking-task.md)

Do not implement application code in this workflow.

Cancelling a task

Mark a task as abandoned. No further execution unless the user explicitly replans.

1. Resolve task folder

Per task-contract.md → Resolve tasks root and Finding tasks root.

Resolve <task-folder> from the user's message under <tasks-root>/. If unclear, list folders per Finding existing tasks and ask. Read status.md, then plan.md.

If already Done → confirm the user intends to cancel a completed task (unusual); otherwise stop.

2. Confirm intent

If the user's message is ambiguous (e.g. "stop working on this"), confirm cancellation vs pause. Cancellation is terminal for execution.

3. Record cancel reason

Capture cancel_reason from the user or context (e.g. duplicate task, wrong approach, deprioritized).

4. Update status.md

1. Set overall_status: Cancelled 2. Set next_step_id: none 3. Set current_step_id: none 4. Set blocking_reason: None 5. Add to execution pointer: cancel_reason: <reason> 6. Update handoff_note: task cancelled; replan only if user revives 7. Append session log: date, —, Cancelled, reason

`plan.md` frontmatter (optional):

• Set pending todos to status: cancelled
• Leave completed and skipped todos unchanged

5. Archive (optional)

If the user asks to archive or the tasks root uses archive/, follow archiving-task.md.

Do not delete task folders unless the user explicitly requests deletion.

6. Confirm to the user

Reply with:

• Task folder and cancel_reason
• Archive path if moved
• How to start fresh (new task via creating-task.md) or reopen (via reopening-task.md)

Do not implement application code in this workflow.

Checking a task

Read-only. Report status without changing artifacts or implementing work.

1. Resolve scope

Determine what the user wants:

Per task-contract.md → Resolve tasks root and Finding tasks root.

For a single task, resolve <task-folder> from the user's message under <tasks-root>/. If unclear, list folders per Finding existing tasks and ask.

For all tasks, discover every task folder under <tasks-root>/ per Finding existing tasks.

2. Read artifacts

Single task:

1. Read <task-folder>/status.md — first 2. Read <task-folder>/plan.md for goal, phases, and verification checklist

All tasks:

1. For each task folder, read status.md (and plan.md frontmatter name / overview if status is sparse)

Do not modify any files.

3. Build the report

Single task — include:

• Task folder path and title (plan.md frontmatter name)
• overall_status, current_step_id, next_step_id
• blocking_reason, cancel_reason, or handoff_note when set
• Step queue progress: completed, pending, skipped, cancelled counts; list unchecked steps
• Last 2–3 Session log rows
• Plan revision (plan_revision from plan.md)
• Suggested next action (execute, unblock, verify, reopen, archive) — suggestion only

All tasks — table columns:

| Task folder | Title | overall_status | next_step_id | handoff_note (truncated) |

Sort by task id. Group or filter by status when the user asks (e.g. "blocked tasks only").

4. Confirm to the user

Reply with the report. Do not advance the execution pointer, check off steps, or write application code unless the user switches intent (e.g. "continue this task" → executing-task.md).

Creating a task

Planning only. Do not write application code unless the user explicitly asks to implement in the same message.

1. Resolve tasks root

Per task-contract.md → Resolve tasks root, Finding tasks root, and Initialize tasks root when no index.md marker exists.

2. Assign task id and slug

Within the resolved tasks root:

1. List directories matching [0-9][0-9][0-9]-*/. 2. Parse the highest three-digit prefix; next id = max + 1 (or 001 if none). 3. Build slug from the title:

• lowercase, hyphens only, max ~40 chars
• drop filler words when helpful (implement, the, a)
• example: Add user profile settings page → user-profile-settings

4. Folder name: {id}-{slug} (e.g. 007-user-profile-settings).

If the folder already exists, stop and ask whether to overwrite or pick a new slug.

3. Gather project context

Ask at most one clarifying question if scope or target area is ambiguous.

4. Write plan.md

Use `../assets/plan.md`. Required sections:

Keep phases implementation-ready: file paths, patterns to follow, acceptance criteria per phase.

Skills and references — when conventions apply, fill Context using skill discovery in task-contract.md. Include reference basenames, not skill names alone (~6 references max unless scope requires more).

5. Write status.md

Use `../assets/status.md`. Initialize:

• overall_status: Not Started
• next_step_id: first step id from the plan's todo/step queue
• All steps: unchecked
• handoff_note: one sentence describing what the executor should do first
• Include full task_folder path in the execution pointer

6. Confirm to the user

Reply with:

• Tasks root path (via index.md), task folder path, and whether index.md was newly created
• One-line summary
• next_step_id for the executor
• Suggested follow-up: _"Continue tasks/001-dark-mode-toggle"_ or _"Read tasks/001-dark-mode-toggle/status.md and run the next step"_

Stop without implementing unless the user also asked to implement in the same message.

Executing a task

Execution mode. Implement the current step unless it is documentation-only.

1. Resolve task folder

Per task-contract.md → Resolve tasks root and Finding tasks root.

Resolve <task-folder> from the user's message under <tasks-root>/. If unclear, list folders per Finding existing tasks and ask.

2. Startup protocol

1. Read <task-folder>/status.md — first 2. Read <task-folder>/plan.md for step details and acceptance criteria 3. If overall_status is Cancelled → stop; tell the user the task was cancelled 4. If overall_status is Blocked → stop unless the user says to unblock; address blocking_reason first 5. If overall_status is Done → stop; confirm completion or offer archiving-task.md 6. Set overall_status to In Progress if it was Not Started or Review

3. Execute next_step_id

1. Find the step in plan.md (phases and/or frontmatter todos) 2. Load Context Skills to load from plan.md; read each skill's SKILL.md 3. Read Context References per task-contract.md → Resolving domain references 4. Implement the step: code, config, or docs as the plan specifies 5. Run quick checks mentioned in the plan (lint, typecheck) when practical

4. Update status.md before stopping

Always update:

• handoff_note — one sentence for the next session
• Session log — date, step id, result, brief notes

5. Blocked workflow

If a blocker prevents finishing the step, follow blocking-task.md (or apply the same updates inline):

• Set overall_status: Blocked
• Set blocking_reason to a concrete description
• Do not advance next_step_id or check off the step
• Log the attempt in the session log

If the user only wants to unblock without implementing, use unblocking-task.md.

6. Confirm to the user

Reply with:

• Step completed (or blocked reason)
• New next_step_id and overall_status
• Suggested follow-up if work remains

Reopening a task

Restore a cancelled task for continued work. Replanning optional; this workflow only restores execution state.

1. Resolve task folder

Per task-contract.md → Resolve tasks root and Finding tasks root.

Resolve <task-folder> from the user's message under <tasks-root>/. If unclear, list folders per Finding existing tasks and ask. Read status.md, then plan.md.

If overall_status is not Cancelled → stop; tell the user (offer checking-task.md or executing-task.md as appropriate).

2. Confirm intent

Confirm the user intends to reopen, not start a separate copy. Reopening continues the same folder; for a new task with similar scope, use creating-task.md.

If scope also changed, follow updating-task.md after reopening or in the same session if the user asks.

3. Restore execution state

1. Set overall_status: In Progress (or Not Started if no steps were ever completed) 2. Set cancel_reason: None 3. Set blocking_reason: None 4. Set next_step_id to the first pending step in the step queue (first unchecked non-verify step, or verify if only verification remains) 5. Set current_step_id: none 6. In plan.md frontmatter, set todos with status: cancelled back to status: pending (leave completed and skipped unchanged) 7. Update handoff_note for the executor 8. Append session log: date, —, Reopened, reason

Optional plan changelog — if the user describes scope changes while reopening, bump plan_revision and add a row per updating-task.md.

4. Confirm to the user

Reply with:

• Task folder and reopen reason
• Restored overall_status and next_step_id
• Suggested follow-up: _"Continue <task-folder>"_ → executing-task.md

Do not implement application code unless the user also asked to continue in the same message.

Skipping a step

Skip the current or named step and advance the execution pointer. Use when the user explicitly defers work or accepts missing acceptance criteria for that step.

1. Resolve task folder and step

Per task-contract.md → Resolve tasks root and Finding tasks root.

1. Resolve <task-folder> from the user's message under <tasks-root>/. If unclear, list folders per Finding existing tasks and ask. 2. Read status.md, then plan.md 3. Determine step to skip:

• Default: next_step_id from status.md
• Or the step id the user names (e.g. step-2)

If overall_status is Cancelled or Done → stop and tell the user.

2. Record skip reason

Require a brief reason (from the user or inferred from context), e.g.:

• Deferred to a follow-up task
• Blocked on external dependency
• No longer needed after scope change

3. Update artifacts

`plan.md` frontmatter:

• Set the skipped todo's status to skipped

`status.md`:

1. In the step queue, mark the step as skipped (append — SKIPPED: <reason> to the line, or add a Skipped steps subsection) 2. Set current_step_id to the skipped step id 3. Set next_step_id to the next pending step in queue (or verify if only verification remains) 4. Set overall_status to In Progress (or keep Review if skipping non-verify work while in review) 5. Append session log: date, step id, Skipped, reason 6. Update handoff_note

Do not check off skipped steps as completed.

4. Follow-up obligations

If skipping leaves a gap in the verification checklist:

• Add a note to handoff_note or a new todo in plan.md (prefer updating-task.md if the user wants a formal amend)
• Or link a related task under Context → Related tasks

5. Confirm to the user

Reply with:

• Which step was skipped and why
• New next_step_id
• Any verification or follow-up risk

Do not implement the skipped step's work in this workflow unless the user changes intent.

Task contract

On-disk layout and field meanings shared by all managing-tasks workflows.

Author signature

Static UUID identifying tasks roots created by this skill:

b2e4f6a8-3c1d-5e7f-9a2b-4d6e8f0c1a3b

Every <tasks-root>/index.md must include this value in frontmatter author. Search the repository for that field to locate the tasks root — do not infer the root from plan.md, status.md, or numbered task folders alone.

Output layout

Only this skill may establish a tasks root. The root is always marked by <tasks-root>/index.md.

<tasks-root>/
  index.md                          # tasks root marker — required; created first
  <NNN>-<slug>/
    plan.md      # Stable spec: goal, phases, files, acceptance criteria
    status.md    # Mutable state: execution pointer, step queue, handoff note
  archive/       # Optional: cancelled or completed tasks moved here
    <NNN>-<slug>/

Templates: `../assets/plan.md`, `../assets/status.md`, `../assets/index.md` for new tasks roots.

Plan frontmatter

Every plan.md includes YAML frontmatter:

Resolve tasks root

1. Search per Finding tasks root below. 2. Decide location:

• One match → use that folder; no need to ask.
• Multiple matches → ask the user which root to use (list full paths to each index.md).
• No match → on create intent: ask the user where to create the tasks folder. Do not assume a default path. Then follow Initialize tasks root. On any other intent: stop and report that no tasks root exists; do not initialize.

Do not create task folders outside the resolved root. Do not treat a folder as the tasks root unless it contains a valid index.md per Finding tasks root.

Finding tasks root

Search the repository for index.md files whose YAML frontmatter contains all of:

The tasks root is the parent directory of each matching index.md (e.g. tasks/index.md → root is tasks/).

After resolving the root, list and read task folders only under that directory.

Initialize tasks root

When no valid index.md exists and the user is creating a task:

1. Ask the user for the target folder path (relative to repository root, e.g. tasks/, docs/tasks/). 2. Verify the folder is empty:

• Path does not exist → OK; create the directory.
• Path exists and contains no files and no subdirectories → OK.
• Path exists and is not empty → stop. Tell the user the folder must be empty and ask for another path.

3. Write <tasks-root>/index.md from `../assets/index.md` with the Author signature in author. This is the first file the skill creates in a new root. 4. Proceed with the requested task folder(s) under that root.

Only this skill may create or replace index.md. If the user points at a non-empty folder without a valid index.md, do not write tasks there.

Finding existing tasks

After resolving the tasks root per Finding tasks root, search under <tasks-root>/ and <tasks-root>/archive/ for directories matching [0-9][0-9][0-9]-*/ that contain plan.md.

Treat plan.md as a task when frontmatter contains generated_by: managing-tasks or generated_by: creating-tasks (legacy).

Status fields

Step queue rules

• Check off steps when completed.
• Skipped steps stay in the queue with a skip reason in the session log; set todo status: skipped in plan frontmatter.
• Never uncheck a completed step unless the user explicitly replans and confirms.
• verify is always the last step before Done.

Resolving domain references (execute / plan)

For each entry in plan.md → Context → References:

<skill-dir> is the folder containing that skill's SKILL.md. If missing under references/, use the link in that skill's SKILL.md index.

Discovering project skills

Each skill is <skill-name>/SKILL.md with optional references/, scripts/, and assets/ (Agent Skills).

Find skills:

1. Explicit pointers — AGENTS.md, the user request, @-mentioned or attached skills 2. Project skill roots — glob <root>/<skill-name>/SKILL.md under each existing root:

3. Custom roots — additional paths named in AGENTS.md or by the user

Deduplicate — one copy per skill name in frontmatter; prefer AGENTS.md path, else first matching root in the table order.

Choose skills to load — include every skill whose description (frontmatter) or scope clearly governs the work area. Read each chosen skill's SKILL.md before picking references.

Choose references for the plan — per skill, in order:

1. Task recipes — if SKILL.md has a ## Task recipes table, copy the closest row's reference basenames. 2. Reference index — pick rows whose "When to use" matches the task; add at most 1–2 extras if needed. 3. `references/` folder — list <skill-dir>/references/*.md and select basenames that match the task. 4. Linked root docs — include only when SKILL.md points to them for this task type.

Record basenames without .md. Use skill-name/reference-basename when names collide across skills.

Triaging tasks

Read-only. Among available tasks, identify which can begin or continue implementation now and which still need prep work, inputs, or upstream completion.

Use when the user asks what to work on next across the backlog, which tasks are unblocked, or which tasks are waiting on something.

1. Resolve scope

Per task-contract.md → Resolve tasks root and Finding existing tasks.

Discover every task folder under <tasks-root>/ and <tasks-root>/archive/. Exclude archived tasks unless the user asks to include them.

2. Read artifacts

For each task folder:

1. Read status.md — first 2. Read plan.md — goal, Context, phases, frontmatter todos, verification checklist

Build a working map of task id → overall_status, next_step_id, blocking_reason, and Context → Related tasks.

Do not modify any files.

3. Evaluate readiness

A task is startable now when the executor can run next_step_id per executing-task.md without inventing missing prerequisites, guessing file paths, or doing preparatory work that belongs in another task or workflow.

Evaluate every task. A task may appear in only one group.

3.1 Lifecycle gate (hard stop)

3.2 Task dependencies

Inspect plan.md → Context → Related tasks and phase text for ordering language (depends on, after, requires, blocked by, once … is done).

For each referenced sibling task folder:

1. Resolve the path under <tasks-root>/ 2. Read its status.md → overall_status

When the plan does not state whether a related task is a prerequisite, treat it as informational only unless phase text implies ordering.

3.3 Artifacts and references on disk

Check inputs the next step (and steps it explicitly builds on in the same phase) requires:

Design and asset gap examples: no style-guide.md when the plan requires it; Figma URL with no export or spec file; assets/ path empty when the step consumes assets; API contract referenced but not checked in.

3.4 Plan completeness for the next step

Inspect the phase and todo matching next_step_id.

If the plan is incomplete but the gap is small and the user only asked for a readiness report, note the specific question to resolve in Unblock action — do not replan unless the user switches intent (updating-task.md or creating-task.md).

3.5 Startable verdict

If the task passes §3.1–§3.4, mark it Startable now.

Record a one-line Why startable (e.g. "In Progress; next step step-2 has paths and deps satisfied").

4. Build the report

Startable now

| Task folder | Title | overall_status | next_step_id | Why startable |

Sort order:

1. In Progress first (continue existing work) 2. Then Review with verify 3. Then Not Started 4. Within each group, ascending task id

Not ready

| Task folder | Title | overall_status | Blocker type | Detail | Unblock action |

Blocker type — use one primary label:

Unblock action — one concrete next step: finish prerequisite task, run design workflow, add asset path, amend plan, unblock task, etc. Link the relevant recipe when obvious (blocking-task.md, creating-task.md, updating-task.md).

When the user asked for a single recommendation, pick the top Startable now row and say why. If none are startable, summarize the shortest path to unblock one task.

5. Confirm to the user

Reply with the report. Do not advance execution pointers, check off steps, create tasks, or write application code unless the user switches intent (e.g. "continue tasks/003-…" → executing-task.md).

Unblocking a task

Clear a blocker and restore execution. No implementation unless the user also asks to continue.

1. Resolve task folder

Per task-contract.md → Resolve tasks root and Finding tasks root.

Resolve <task-folder> from the user's message under <tasks-root>/. If unclear, list folders per Finding existing tasks and ask. Read status.md, then plan.md.

If overall_status is not Blocked → stop; tell the user the task is not blocked (offer checking-task.md for status).

If overall_status is Cancelled or Done → stop and tell the user.

2. Confirm resolution

Capture how the blocker was resolved (from the user or context). Optional one-line note for the session log.

3. Update status.md

1. Set blocking_reason: None 2. Set overall_status: In Progress (or Review if only verify remains unchecked and was already in review) 3. Confirm next_step_id still exists in the step queue and is pending; if not, set to the first unchecked pending step 4. Update handoff_note for the executor 5. Append session log: date, next_step_id, Unblocked, resolution note

4. Confirm to the user

Reply with:

• Task folder and resolution summary
• Restored overall_status and next_step_id
• Suggested follow-up: _"Continue <task-folder>"_ → executing-task.md if work should resume now

Do not implement application code unless the user also asked to continue in the same message.

Updating a task

Replanning only. Amend the spec when scope changes. Do not implement new work unless the user explicitly asks in the same message.

1. Resolve task folder

Same as executing-task.md → step 1.

2. Read current state

1. Read status.md, then plan.md 2. Note overall_status, completed steps, and next_step_id 3. If overall_status is Cancelled → confirm with the user before replanning; to restore execution state, prefer reopening-task.md

3. Gather changes

From the user message, determine:

• New goals, phases, or acceptance criteria
• Removed or deferred scope (move to Non-goals)
• New files, skills, or references to add to Context

Ask at most one clarifying question if the amend scope is ambiguous.

4. Update plan.md

1. Bump plan_revision in frontmatter (e.g. 1 → 2) 2. Append a Plan changelog section entry (if missing, add the section before Phases):

   ## Plan changelog

   | Rev | Date | Summary |
   | --- | --- | --- |
   | 2 | YYYY-MM-DD | Added phase 3 for API error handling |

3. Edit Goal, Non-goals, Context, Phases, Verification checklist, and Risks as needed 4. Sync frontmatter todos:

• Preserve todos with status: completed or skipped — do not reset them
• Add new todos for new steps; mark removed steps status: cancelled (do not delete rows)
• Renumber or rename step ids only when necessary; if ids change, update status.md queue to match

Re-run skill discovery from task-contract.md when the amended work touches new areas.

5. Sync status.md

1. Update the Step queue to match plan todos (keep checkmarks for completed steps) 2. Set next_step_id:

• If the current next_step_id still exists and is pending → keep it
• If it was removed or completed → set to the first unchecked pending step
• If user asked to redo a step → uncheck only that step with explicit confirmation

3. Clear blocking_reason if the amend resolves the blocker; set overall_status to In Progress if was Blocked 4. Update handoff_note for the executor

6. Confirm to the user

Reply with:

• plan_revision and changelog summary
• Updated next_step_id
• What changed vs what was preserved

Stop without implementing new phases unless the user also asked to continue in the same message.

Verifying a task

Run the plan's verification checklist when implementation is complete. Use when overall_status is Review or only the verify step remains.

1. Resolve task folder

Per task-contract.md → Resolve tasks root and Finding tasks root.

Resolve <task-folder> from the user's message under <tasks-root>/. If unclear, list folders per Finding existing tasks and ask. Read status.md, then plan.md.

If overall_status is Cancelled → stop and tell the user.

If overall_status is Done → confirm completion or offer archiving-task.md.

2. Confirm verify scope

1. Ensure all non-verify steps are completed or explicitly skipped in the step queue 2. If pending implementation steps remain → stop; tell the user to finish or skip them first (executing-task.md or skipping-step.md) 3. Set overall_status to Review if not already 4. Set next_step_id to verify if not already

3. Run verification checklist

Execute every item in plan.md → Verification checklist:

• Automated checks (lint, typecheck, tests) when practical
• Manual smoke steps when listed
• Do not add new features; only verify existing work

Record pass/fail per item.

4. Update artifacts

If all checks pass:

1. Check off verify in the step queue 2. Set todo verify to status: completed in plan.md frontmatter 3. Set overall_status: Done 4. Set current_step_id: verify 5. Set next_step_id: none 6. Update handoff_note: task complete 7. Append session log: date, verify, Completed, brief results

If checks fail:

1. Do not set overall_status to Done 2. Keep or set overall_status: Review or In Progress depending on whether code fixes are needed 3. Set handoff_note with failing items and suggested fix step 4. Append session log: date, verify, Failed, failing items 5. Optionally add a fix todo via updating-task.md if the user wants a formal replan

5. Confirm to the user

Reply with:

• Verification results (pass/fail per checklist item)
• overall_status and next_step_id
• Suggested follow-up: archive if Done (archiving-task.md), or fix and re-verify