task-workflow

Files (1)

• SKILL.md

SKILL.md (first lines)

# Task Workflow

`tasks/` is the durable record of human intention, agent planning, execution, and review. The entry point is `/task-workflow:task-start`; this file is the shared contract it and every child agent operate under.

## Task creation

1. Read `CLAUDE.md`, this file, and `tasks/global-task-manager.md`.
2. Get `Next ID` from the GTM, create `tasks/planning/TXXX-task-slug/`, copy `tasks/main-template.md` to `main.md`, add the task to the GTM, and increment `Next ID`.
3. Draft the Intent Contract and `DONE_WHEN` from the human's request; set status `PLANNING`.
4. Offer `/task-workflow:intent-harden` for non-trivial work and record the outcome on the `Intent hardening:` line in `main.md`. If it runs, the hardened brief replaces the draft contract.
5. Build the Handoff Packet (defined in `task-start`). Every child prompt receives the same `DONE_WHEN` verbatim.
6. Route the task: `quickfix` (small, one plausible site, obvious validation, no product ambiguity — planning skipped, code review kept) or `planned`. Record the lane in `main.md`.

## Status machine

| Status | Meaning | Directory |
|---|---|---|
| `PLANNING` | Intent/plan being prepared | `tasks/planning/` |
| `PLAN_REVIEW` | Plan reviewer checking readiness | `tasks/planning/` |
| `READY` | Plan passed; task can execute | `tasks/active/` |
| `EXECUTING_PHASE_N` | Executor implementing phase N | `tasks/active/` |
| `CODE_REVIEW` | Code reviewer checking phase N | `tasks/active/` |
| `BLOCKED` | Human input or prerequisite required | `tasks/paused/` |
| `COMPLETE` | All phases implemented and reviewed | `tasks/completed/` |

A quickfix enters `tasks/active/` at routing and runs as a single phase. The parent moves folders with a normal filesystem move, keeps the `## Meta` status and GTM row in agreement, and stages the old/new paths at the next approved commit boundary. Tasks created before this workflow are historical evidence: reassess their intent against current repository direction before resuming; never execute stale plans automatically.

## Approved plan and report pointers

Keep the entire approved Task, Intent Contract and phased `## Plan` in `main.md` as the historical what/how/where agreement. Do not amend it, tick its checkboxes or append execution/review material. Agents write separate reports first, then replace compact status/outcome/path entries outside the specification; this is not a cumulative line quota.

- Executor: `execution-phase-N.md` → current phase under `## Execution Log`.
- Reviewer: `code-review-phase-N.md` → gate/date/path under `## Code Review Log`. Phase reports identify phase, execution attempt and baseline. `final-review.md` identifies cumulative baseline, current working tree, and review attempt, linked by a compact final-review entry.
- Plan reviewer: preserve numbered attempts in `plan-review.md`, recording `Review attempt` and `Reviewed specification SHA-256` for the exact Task/Intent/entire Plan byte range defined in task-start. Before `READY`, the parent compares latest report/pointer/dispatched attempt and freshly computed current digest; missing/stale evidence blocks, including after retries/replans. Metadata stays outside the specification.
- On `REVISE`, pass the exact current full review path; the executor must read its numbered blockers before repair. Parent checks report existence and current attempt before routing gates.
- Parent: status/GTM and compact completion pointer; full completion evidence in `completion.md`.
- If evidence invalidates scope, record it separately and stop `BLOCKED` for explicit replanning authorization and renewed review/acceptance. Preserve the earlier agreement in Git/history.
- Do not automatically rewrite historical tasks or upgrade copied templates without consent. Agree on the authoritative plan revision before resuming; preserve old records and use separate reports for new work.

Before routing gates, compare the full approved specification against its accepted Git revision and original path; only declared metadata/pointers may change. These are prompt-level safeguards, not a filesystem sandbox. Tests cover instructions/artifact fixtures, not guaranteed model compliance.

## Ownership and gates

| Artifact | Owner |
|---|---|
| Intent Contract and Handoff Packet | Human + parent orchestrator |
| `## Plan` | `task-workflow:planner` |
| `## Plan Review` / `plan-review.md` | `task-workflow:plan-reviewer` |
| Source edits, `execution-phase-N.md`, and compact `## Execution Log` pointer | `task-workflow:executor` |
| `## Code Review Log` / `code-review-phase-N.md` | `task-workflow:code-reviewer` |
| Git commits after `PASS`, GTM, transitions | Parent orchestrator |

| Gate | Outcome | Action |
|---|---|---|
| Plan review | `READY` | Promote to `tasks/active/` and execute |
| Plan review | `NEEDS_WORK` | Planner revises, re-review |
| Plan review | `NOT_READY` | Block for a real human decision/prerequisite |
| Code review | `PASS` | Parent commits the reviewed phase and continues |
| Code review | `REVISE` | Executor repairs numbered findings, re-review |
| Code review | `FAIL` | Block or re-plan |

Maximum three `NEEDS_WORK` or `REVISE` cycles before blocking. If a reviewer returns a verdict without persisting its declared artifacts, the parent writes the exact output to the separate report and updates only its outcome/path pointer before routing the gate.

## Review scope and safe validation

- Block on concrete defects, unmet criteria or material evidence gaps. Tooling/editorial suggestions do not force revision unless they affect executable requirements, required evidence or safety decisions. Do not waive approved criteria.
- Re-review prior blockers, repair delta and affected regressions/dependencies. Keep the full contract, cumulative integration obligations and freshness checks; reference still-valid evidence and expand review when new evidence undermines it.
- Choose checks by risk, not quotas for findings, reruns or negative controls. Inspect test configuration before running. Source-mutating controls must run only in a disposable isolated copy of the exact candidate, including uncommitted and untracked candidate files, with no shared writable source or live-service side effects. Never run them in the authoring tree; report unavailable safe verification as a gap. Required completion checks remain required, safely isolated when necessary.
- Preserve reports/attempts. Record blocker dispositions, changed evidence and prior report/attempt pointers, not repeated history. Handoffs carry gate, decisions, current attempt/baseline and exact paths; write full evidence once.

## Git and substrate discipline

- Choose current branch, feature branch, or worktree from repository instructions, Git state, concurrency, and delivery expectations; record the strategy, rationale, and task baseline SHA in `main.md`.
- Preserve unrelated human changes: never stash, reset, delete, or commit them; prefer safe isolation when allowed.
- Require a clean workspace before phase preparation. The executor may then see only the declared parent status/pointer edits; on repair it resumes the expected reviewed diff under the original phase baseline. Unrelated changes still block or require isolation. It leaves its phase uncommitted for review.
- The code reviewer inspects the actual working-tree diff from the recorded phase baseline, runs checks, and persists its verdict; the plan reviewer does the same for plans.
- The parent commits only after `PASS`, using `git add -- <explicit-reviewed-paths>` and a task/phase-specific message. Never use `git add .`, `git add -A`, or stage a path the reviewer did not inspect; verify `git diff --cached --name-only` before every commit.
- Push, PR, merge, deployment, force-push, and branch deletion require explicit authorization or an already-authorized repository workflow.

## Blocked recovery

Record the exact blocker and attempted work in the current phase report (or `blocked.md` before execution), link it from a compact blocker/status entry in `main.md`, set `BLOCKED`, move the task to `tasks/paused/`, and update the GTM. When the human answers, restore the appropriate prior stage — an answer does not imply "resume coding"; return to planning if intent or scope changed.

## Completion

Run the repository's full tests/lint/build checks under the safe-validation rules above, compare the cumulative result with `DONE_WHEN`, write full evidence to `completion.md` and update only the outcome/date/path under `## Completion`, move the task to `tasks/completed/`, update the GTM, and commit the ledger update. Follow the recorded delivery strategy; do not push, merge, open a PR, or deploy unless authorized.

From blakesims/task-workflow-plugin, MIT.

More from blakesims/task-workflow-plugin