task-workflow — Claude Code skill: a gated task execution protocol

---
name: task-workflow
description: Canonical workflow for a task. Read and follow strictly end to end while working on the task.
---

# Task Workflow

## Strict Instruction Contract

This file is strict implementation instruction, not loose guidance and not optional reference material.

This is the canonical workflow for task execution. It is not one possible way to do the task; it is the required way.

If the Agent reads this skill, it must execute it exactly as written, in order, to the letter.

Required behavior:

- Do not reinterpret the steps.
- Do not reorder the steps.
- Do not skip the steps.
- Do not replace the steps with a simpler approach.
- Do not make assumptions that override this file.
- Do not treat broad similarity, intuition, or prior habits as permission to deviate.

If the Agent is uncertain, it must resolve that uncertainty inside the workflow defined here and not invent its own workflow.
If the skill says to perform a step, gate, checklist, review, or loop, that step is mandatory.
If the skill says a later phase is blocked, the Agent must treat it as blocked.
If the Agent cannot prove a phase passed in the required artifact, it must treat that phase as failed.

There is no successful stopping point before Phase 7. Stopping early can directly harm the user because they may depend on the completed workflow for job-critical work. It is a do-or-die situation: the user can be harmed if the run has not reached Phase 7 correctly, and the user can lose his job if the Agent stops early, signs off weak work, skips a gate, or damages live data. Treat premature stopping, partial signoff, live-data damage, or "mostly done" summaries as a serious failure of duty.

The first filesystem action in the target repo must be Phase 0 artifact reset and scaffolding.

Before `task-workflow/phase-0-artifact-reset.md` exists, the Agent may only:

- identify the target repo root
- read this `SKILL.md`
- read the task file
- create or replace `task-workflow/` artifacts from templates

Before Phase 1 passes, the Agent must not edit or generate implementation files, build outputs, databases, route types, migrations, tests, package files, or source files.

Production and live workspace databases, especially `.dbs/database.db`, are do-or-die user data. Deleting, resetting, reseeding, truncating, inspecting with ad hoc writes, or modifying them outside the app's legitimate migration command can destroy user work and can cause the user to lose his job. The only permitted production/live DB action is the repo's required app migration command for a real schema change. That exception does not permit "working on" the production DB: no manual query, data manipulation, seed, reset, fixture load, data repair, cleanup, delete, truncate, direct SQLite command, or debug mutation is allowed.

After Phase 1 passes and before any implementation edit, the Agent must set `task-workflow/CURRENT_PHASE.txt` to `phase-2-execution`.

If `CURRENT_PHASE.txt` still says `phase-0-artifact-reset` or `phase-1-task-research`, implementation files must remain unchanged.

If implementation files, generated app files, build outputs, or database files are changed before Phase 0 artifacts exist and Phase 1 passes, the run has failed and must be restarted from a clean fixture.

## Core Idea

Re-read this `SKILL.md` after every compaction before continuing work. Re-load the phase references and current task artifacts too. Do not rely on conversational memory.

This skill is a gated execution protocol, not a loose set of suggestions. It turns a task into a repeatable, artifact-driven workflow. The target app must be implemented from the task, target repo, and local codebase evidence, then proven through Phase 3 check/lint evidence, Phase 4 unit-test coverage decision, Phase 5 interactive Playwright verification, Phase 6 E2E coverage decision, and final audit.

Assume this skill may run fully autonomously and may be compacted mid-run. No human is expected to watch the run line by line. The artifact files are therefore the enforcement system. A phase is not complete because the Agent feels confident. A phase is complete only when its required artifact shows a real passing score and all critical items pass.

`task-workflow/progress.md` is the compact resume ledger. It must summarize the task, current phase, completed phase context, active work queue, verification state, and next local action. Hard rule: after compaction, resume, retry, reconnect, or new coding session, read it and `task-workflow/CURRENT_PHASE.txt` before doing any new work. Keep it current as work proceeds; it is the first file that should restore enough context to continue without conversation memory.

Never promote work from one phase to the next on optimism, partial evidence, a green build alone, or broad product similarity.

The workflow is intentionally looped. A failed gate means the Agent must rework that phase, update evidence, rerun the needed checks or verification, rescore the gate, and repeat until the gate passes. Quality gates are not reports to the user; they are control points that force more work before promotion.

## MITB Workspace Inputs

When running in a MITB sandbox, use these repo-relative workspace inputs:

- workflow skill: `.agents/skills/task-workflow/SKILL.md`
- task body: `.tasks/task.md`
- domain and brand context: `.tasks/domain.md`
- attached task files: `.tasks/files/`
- available skill files: `.agents/skills/`

`AGENTS.md` is the target repo's binding development-instructions file. It defines project-specific rules for architecture, type safety, tests, UX, commands, code style, docs, prohibited patterns, and completion. Phase 1 must extract the task-relevant rules from `AGENTS.md` before planning edits, including any required docs it points to. Later gates must verify the implementation follows those extracted rules.

Phase 1 must read `.tasks/domain.md`. It must enumerate `.tasks/files/` even when the folder is empty, then read or inspect every task attachment/supporting file in that folder before planning.

Available skills are kept under `.agents/skills/`. Discover available skills from the prompt's Skills section and `.agents/skills/`, then read only the selected skill `SKILL.md` files relevant to the current task. Do not bulk-read every skill file in `.agents/skills/`.

All Phase 1 input/reference files are read-only. This includes `AGENTS.md`, `.tasks/task.md`, `.tasks/domain.md`, every file under `.tasks/files/`, and every selected skill file under `.agents/skills/`. Treat files under `.tasks/` as canonical task inputs, not editable workspace artifacts. Do not rewrite, normalize, consolidate, clean up, trim, reformat, or "fix" these files unless the task explicitly asks to update that exact reference file. If a reference file appears inconsistent, record the ambiguity in `task-workflow/phase-1-task-research.md` or `task-workflow/open-gaps.md`; never resolve it by editing the reference input.

Record every `.tasks/files/` attachment/supporting file read or inspected, plus every selected skill path and why it was relevant, in `task-workflow/phase-1-task-research.md` and `task-workflow/progress.md`. After compaction or resume, re-read the selected relevant skill files listed in `progress.md` along with `AGENTS.md`, `.tasks/task.md`, `.tasks/domain.md`, and the relevant `.tasks/files/` attachments/supporting files recorded in Phase 1.

In MITB, `.tasks/task.md` or the prompt always provides the task completion command. Phase 7 must run the exact completed command only after every Phase 7 audit check passes. If any Phase 7 audit check fails, do not run task completion. Return to the earliest failing phase, repair the work, update evidence, rescore that phase, loop forward through the gates, and then re-enter Phase 7.

## Mandatory Process Shape

<mandatory_process_shape>

This workflow shape is not optional:

1. Clear old workflow artifacts for this repo and copy fresh artifact templates.
2. Read the task, root `AGENTS.md`, `.tasks/domain.md`, every task attachment/supporting file in `.tasks/files/`, only relevant available skill files from `.agents/skills/`, and relevant project docs. Extract the task-relevant development rules from `AGENTS.md` before planning. These instruction, task, domain, attachment, and skill-reference files are read-only unless the task explicitly asks to edit them.
3. Research the codebase and record the implementation plan.
4. Execute the primary implementation.
5. Execute a second gap-closure pass.
6. Run second-pass integrity review and repo check/lint validation.
7. Make the unit-test coverage decision: add, update, remove, or explicitly skip unit tests.
8. Verify interactively with standalone Playwright scripts.
9. Make the E2E coverage decision: add, update, remove, or explicitly skip E2E tests.
10. Recheck every phase artifact and sign off only when all gates pass.

If the work skips one of those phase boundaries, the run is off track.

### Phase Ownership Matrix

| Phase | Owns | Required evidence |
| --- | --- | --- |
| Phase 0 | artifact reset and scaffold | fresh artifacts, helper scripts, marker, no source edits |
| Phase 1 | task intake and research | task/domain/attachments/AGENTS/selected skills read, codebase research, implementation plan |
| Phase 2 | primary implementation | scoped work packets, file evidence, readback/diff/search proof |
| Phase 3 | second execution, integrity, check/lint validation | connected-surface review, repo check, focused lint when useful, build, reusable build evidence |
| Phase 4 | unit-test coverage decision | add/update/remove/skip decision, existing-test inspection, minimal unit command or `N/A` |
| Phase 5 | interactive Playwright verification | Stage 1 behavior proof, Stage 2 UI/responsive proof, screenshots, lifecycle evidence |
| Phase 6 | E2E coverage decision | add/update/remove/skip decision, connected E2E inspection, minimal E2E command or `N/A` |
| Phase 7 | final audit and signoff | artifact integrity review, current evidence, MITB completion command after audit |

</mandatory_process_shape>

## Looped Gate Contract

Every phase follows the same loop:

1. Re-read the required reference file or files for the phase from the Phase Reference Map.
2. Perform the phase work.
3. Update the phase artifact with concrete evidence.
4. Score the phase against its gate.
5. If the gate fails, stay in the same phase, repair the failing work or missing evidence, and repeat this loop.
6. If the gate passes, write the promotion-lock evidence, advance `task-workflow/CURRENT_PHASE.txt`, and immediately start the next phase.

This loop is mandatory for Phase 0, Phase 1, Phase 2, Phase 3, Phase 4, Phase 5, Phase 6, and Phase 7.

Do not lower a gate threshold to escape the loop.
Do not summarize failure as progress when the next local repair is available.
Do not wait for the user to tell you to continue when the phase can be repaired locally.
Do not move forward with a weak artifact because the implementation "probably works".

The only acceptable end state is Phase 7 passed with every earlier phase still passing. The only acceptable non-Phase-7 stop is a real external blocker that cannot be solved locally and is fully recorded in the current phase artifact and `task-workflow/open-gaps.md`.

## Autonomous Run Contract

<autonomous_run_contract>

Treat these rules as always active.

### Gate And Artifact Rules

- Every phase must end with an objective gate.
- Every gate must be recorded in the phase-owned artifact file.
- Every gate must have both a numeric threshold and critical-item pass requirement.
- If a gate fails, remain in that phase and keep iterating.
- A failed gate means "repair and loop", not "stop and report".
- Successful gates must immediately promote to the next phase when the next phase is locally available.
- `task-workflow/CURRENT_PHASE.txt` is only a resume pointer. It is not proof that earlier phases passed.
- `task-workflow/progress.md` is the compact resume ledger. It is not proof that gates passed, but it must stay current enough to resume the run after compaction.
- After every phase start, meaningful Phase 2 work packet, phase gate result, blocker discovery, and phase promotion, update `task-workflow/progress.md` with the current phase, earliest failing phase if any, last completed gate, next local action, and a compact summary of relevant context.
- Keep the `Current Phase Pointers`, `Phase Artifact Index`, and `Artifact Pointers` in `task-workflow/progress.md` current. They must point to the current phase artifact, current phase reference, and high-signal active files only. Do not duplicate full researched-file, edited-file, Playwright, screenshot, log, or test inventories from phase artifacts into `progress.md`.
- After compaction, resume, retry, reconnect, or new coding session, re-read this `SKILL.md`, `task-workflow/progress.md`, `task-workflow/CURRENT_PHASE.txt`, the current phase artifact, `task-workflow/open-gaps.md`, and the required current phase reference file or files before choosing the next action. If they disagree, inspect the phase artifacts and continue from the earliest failing phase.
- A phase may advance the current phase marker only after its phase-owned artifact has `Decision: Pass`, a passing score, all critical items passing, and no placeholder `Pending` rows in the gate or required evidence sections.
- The current phase marker must be written before work belonging to that phase begins. The marker is not merely cleanup after phase work.
- Before writing the next phase marker, re-open the current phase artifact and verify the promotion lock in writing inside that artifact.
- Immediately after writing a new phase marker, read the required reference file or files for that new phase before doing any work in that phase.
- If `CURRENT_PHASE.txt` points past the earliest failing phase artifact, artifact gates win. Correct `CURRENT_PHASE.txt` back to the earliest failing phase and continue there.
- When filling artifact templates, preserve auditable evidence for every required semantic category. Exact row wording may be condensed only if the same evidence remains clear and scorable.
- `task-workflow/open-gaps.md` is a gate artifact. A later phase may not claim a gap is resolved unless the gap ledger is updated in the same phase.
- A gap cannot remain `Open` after the phase named in its owner or next-action field has passed. If the later phase completed the work, move the gap to `Resolved Gaps`; if the gap is not real, reclassify or close it with evidence.
- `task-workflow/open-gaps.md` must not contain template placeholder rows such as `Pending` after Phase 0. If there are no gaps, replace placeholder rows with explicit `None currently recorded` rows.
- Phase 7 cannot pass while any critical gap remains `Open`, stale, or contradicted by another phase artifact.

### Verification File Rules

- Phase 5 and Phase 6 must review the interactive scripts and E2E tests for fixed waits before passing.
- A fixed wait in `task-workflow/playwright` or `tests/e2e` is a gate failure. Do not justify it. Replace it with deterministic Playwright waits/assertions such as `locator.waitFor(...)`, `expect(locator)...`, `waitForURL(...)`, `waitForResponse(...)`, or persisted-state assertions, then rerun verification.
- Phase 5, Phase 6, and Phase 7 may pass only when their artifacts document that the inspected verification files contain no fixed waits and cite the deterministic waits/assertions used instead.
- If later work reveals missing evidence from an earlier phase, return to that earlier phase, repair it, and re-pass the gate.

### Write And Command Rules

- After every file write, patch, generated-file creation, or artifact update that matters to a gate, perform a readback check before relying on it. Use `sed`, `rg`, `ls`, `git diff`, or the repo's normal inspection command to prove the file exists and contains the intended change.
- If a write/edit tool reports an invalid write, missing file, failed patch, partial output, or uncertain result, stop that work packet, repair the write with a supported edit method, read it back, and only then continue. Do not proceed as if a failed write happened.
- Commands must be bounded. Do not leave long-lived servers, watchers, or interactive commands running in the foreground as the active tool call.
- Production/live workspace databases must never be used as test or verification state. In this skill, "production database" means `.dbs/database.db`, any repo-declared live/default user-data database, or any database path used by the normal app outside an isolated test/E2E config. The only allowed action on `.dbs/database.db` or any production/live database is the repo's required application migration command for a real schema change, run in the phase that owns that migration and recorded as migration evidence. This is a narrow migration-execution exception, not permission to work on the production DB. If the task creates or changes a migration, running the repo's app migration command against the production/live default DB is mandatory after the migration exists and before Phase 3 promotes; the user uses the completed app immediately, so unapplied migrations make the delivered change invisible or broken. No other production/live DB action is allowed: no manual query, data manipulation, seed, reset, fixture, Playwright, E2E, probe, debugging, cleanup, `rm`, truncate, direct SQLite, custom data repair, or data inspection with write risk. If the command might touch production data and the artifact cannot prove it is the repo migration command for a real schema change or an isolated test DB operation, do not run it.
- Outside Phase 5 and Phase 6, if a temporary dev server is needed for an API/runtime probe, use `task-workflow/scripts/server-probe.mjs`. It owns PID capture, readiness, bounded probe commands, runtime logs, and PID-only cleanup. Server readiness is usually 5-10 seconds; use 15-20 seconds as the normal budget and 30 seconds as the maximum startup-readiness limit. Broad process-name cleanup is only for explicit sandbox-owned recovery when PID/port cleanup is impossible and the artifact records why.
- In Phase 5 and Phase 6, the first browser, Playwright, or E2E command that needs a running app must establish lifecycle ownership through `task-workflow/scripts/playwright-lifecycle.mjs` by default. Do not run against an assumed existing server first and then infer that `fetch failed`, stale data, redirects, or wrong build output means manual server management is needed.
- Existing repo E2E tests are not a reason to bypass the helper. Run `pnpm exec playwright test ...` through the helper's `--run` by default. Use native Playwright with repo `webServer` ownership only when the helper cannot own the server for that exact command after a diagnosed reason, and record that reason before running it.
- The helper's `--env` is not a database-path override mechanism. Never set `E2E_DATABASE_FILE_PATH`, `DATABASE_PATH`, `DB_PATH`, or any similar database file/path variable in helper, setup, server, or run commands. The agent must not change the repo's internal E2E/end-to-end database file path. Test database paths must come from the repo's checked-in E2E/end-to-end config or the already-materialized environment. `.dbs/database.db` is the live workspace/production database; production databases must never be used for testing. Using `.dbs/database.db` for Playwright, E2E, fixtures, seed, reset, inspection, cleanup, or debugging is a critical failure even if it appears only in `task-workflow/`. The user can lose his job if this database is deleted or corrupted.
- Expected verification lifecycle pattern: discover the repo-owned setup and server commands from `AGENTS.md`, `package.json`, README/docs, Playwright config, and `tests/e2e` helpers before running Phase 5 or Phase 6. Prefer a repo-owned setup command that prepares isolated E2E/test state by resetting only the test DB, applying test-targeted migrations, and seeding deterministic verification data, plus a repo-owned server command that starts the app against that isolated state. If the target repo has no named scripts for this pattern, simulate the same pattern with the smallest repo-owned/test-only commands and record the mapping before running them; never replace the pattern with production DB writes, raw DB path overrides, or manual cleanup chains.
- Do not compose manual server cleanup, fixed sleep, DB-delete, server-start, and Playwright command chains in Phase 5 or Phase 6. Put pre-server setup such as isolated test DB reset, test migration, test seed, or test database preparation into lifecycle `--setup "..."` for helper-owned runs. Treat setup plus server startup as reusable for the current verification batch: prefer one helper-owned run with the needed script/spec commands, or rerun setup only after code, migrations, fixtures, DB state, build inputs, or the prior setup output changed. Do not repeatedly delete/recreate the DB or restart the server before each targeted script/spec just because another E2E command is next. If cleanup is needed, do it as a separate recorded recovery step before the helper run, then run the helper alone. If server state, database state, port ownership, or build freshness looks wrong, diagnose through the current lifecycle owner logs/readiness first and rerun through that owner after any code/setup fix. If the helper times out or produces no useful output, treat that as lifecycle/setup evidence, inspect `task-workflow/runtime/server.log`, `task-workflow/runtime/setup-*.log`, readiness output, and `task-workflow/runtime/run-*.log`, then change the setup, server command, ready URL, test command, fixture, or diagnostic before rerunning. If the helper fails once or twice with a diagnosed lifecycle/tooling issue after a corrected invocation, record the helper logs and switch to the smallest fallback that can prove the task: repo Playwright `webServer`, explicit PID/port cleanup, or manual server management with captured PID/log/readiness/cleanup evidence. Broad process-name cleanup is only a recorded sandbox recovery after PID/port cleanup is impossible.
- Do not run `playwright install`, `playwright install chromium`, or equivalent browser downloads during task verification. The managed lifecycle helper sets `PLAYWRIGHT_BROWSERS_PATH=/ms-playwright` when available and fails early if the project Playwright version does not match the sandbox browser cache.

### Phase-Owned Command Rules

- Phase 2 completes implementation packets with strict artifact, readback, diff, search, and narrow unblock-command evidence. Defer routine check, lint, build, unit/Vitest, E2E, Playwright, and repo combined check commands such as `pnpm run check` to their owning later phases unless a concrete compile/type issue blocks the current packet and is recorded before the command.
- Phase 3 reviews connected places, closes missed implementation gaps, performs implementation integrity review, then owns the ordered check/build checkpoint: repo check, focused lint when useful, and build when the repo has a separate build. Use targeted diagnostics or narrow fix checks only to prove a specific issue group. When a broad check/build command fails, inspect enough output to identify visible issue groups, fix every locally-fixable group before rerunning that broad command, and record only the groups/fixes/rerun reason. Do not rerun a broad command after each tiny fix when other visible issue groups remain. Do not keep huge command logs unless a temporary log is needed for triage; delete temporary full-output logs after extracting issue groups. Record unit/E2E coverage questions for the owning later phase.
- Phase 4 owns unit-test coverage. It decides whether unit, service, component, or integration-style coverage is warranted; then adds, updates, removes, or explicitly skips that coverage. It may remove existing unit tests when they protect non-core, non-complex, obsolete, or convoluted behavior and the artifact explains why removal improves the test suite. Phase 4 does not rerun check, lint, or build when Phase 3 evidence is current.
- Later phases reuse Phase 3 build evidence unless code, config, dependency/build inputs, migrations, generated assets, stale output, or incompatible verification tooling invalidates it. Do not rebuild in Phase 4, Phase 5, Phase 6, or Phase 7 only to prepare, reconfirm, or feel safe.
- Phase 6 owns E2E coverage. It decides whether E2E coverage is warranted; then adds, updates, removes, or explicitly skips that coverage. It may remove existing E2E tests when they protect non-core, non-complex, obsolete, brittle, or convoluted behavior and the artifact explains why removal improves the test suite.
- If unit, E2E, or browser work happens before its owning phase, do not fail the task solely for that timing. Carry the artifact, diff, and command output into the owning phase and make the owning phase's remove/update/add/skip decision current before promotion.

### Minimal Test And Rerun Rules

> Tests are production code. Extra tests are not harmless evidence; they are maintenance load, false confidence risk, and future workflow drag.

Phase 4 and Phase 6 must treat test work as a pruning and minimal-coverage decision, not as a "more tests is safer" step.

| Rule | Required behavior |
| --- | --- |
| Existing tests are not grandfathered | If an older agent added unnecessary, obsolete, brittle, convoluted, duplicated, or non-core tests, the owning phase must remove or simplify them when they are connected to the current changed behavior. |
| New tests are exceptions | Add a new test only after proving the behavior is stable/core and no connected existing test can carry the warranted assertion cleanly. |
| Passing extra tests is not quality evidence | A large passing count does not improve the gate. The gate values necessary coverage, useful assertions, and removal of bad tests. |
| Test bulk is a warning | If added tests cause max-lines, fixture churn, helper churn, slow commands, broad reruns, or new maintenance structure, stop and re-evaluate whether the tests should be merged, reduced, updated in place, or removed. Do not solve self-created test bulk by adding more structure unless the artifact proves every test remains necessary. |
| Every new test needs a burden ledger | For each new unit or E2E test case/file, record the core risk, the connected existing tests inspected, why update/remove/`N/A` was insufficient, why the assertion is minimal, and what cheaper proof was rejected. |

- Keep tests minimal. Prefer the fewest tests that protect core behavior or critical workflows. Too many tests for incidental behavior are a codebase problem, not a quality signal.
- For E2E, run only new, changed, or directly connected specs that are warranted by the Phase 6 decision. Never run the unfiltered full E2E suite unless the task explicitly asks for full E2E or a concrete written repo instruction names full E2E/all-spec execution for this exact task; a repo having a Playwright suite, `webServer`, or "run tests" script is not enough. After warranted targeted or connected E2E evidence passes and no related code, test, config, fixture, migration, or build input changed, do not add a full E2E run as final confidence, final signoff, state discovery, or reviewer-satisfaction evidence.
- For a single targeted Playwright script or E2E spec, timeout increases are not a retry strategy. Start with the smallest practical timeout: `15000`-`20000` ms for Phase 5 launch/page-state/custom-script probes and up to `30000` ms for first-run Phase 6 targeted E2E where Playwright runner startup adds overhead. If the run fails with any useful error, assertion output, not-found state, console/runtime error, route error, fixture/DB miss, or helper diagnostic, use that evidence to diagnose; do not retry with a larger timeout. A larger timeout is allowed only when the first run ended only because the timer expired with no useful response or explanation, and only after helper logs, readiness, URL, not-found/error state, required DB/fixture records, server runtime logs, browser console, and network/page state prove the app and test are in the correct state to run. Only then may one rerun use `60000` ms, and never more than `120000` ms for one targeted script/spec. If a single targeted run needs more than two minutes, stop increasing timeouts; split the verifier or diagnose lifecycle, setup, fixture, page-state, console, network, or test-design failure first.
- Do not rerun tests only for confidence. Rerun when quality evidence can change: related implementation changed, the test changed, config/environment changed, previous output was incomplete/stale, or the next run gathers a narrower diagnostic needed to fix a real failure.
- Before rerunning an identical failing test command, record what changed since the previous run or what new evidence the rerun will collect. If nothing changed and the prior output is complete, inspect logs, DOM/state, traces, screenshots, or persisted data first, then change the implementation, test, command scope, or diagnostic strategy before running again. A suspected pre-existing or order-dependent failure is not a reason to broaden to a full suite; prove it with the narrow failing spec/test plus logs/state/trace evidence, then fix it if it is in scope or record it as an unrelated defended gap.
- Phase 5 and Phase 6 artifacts must record timeout values and any quiet-run/timeout triage before the gate can pass. A first-run targeted Playwright command longer than the Phase 5/Phase 6 budgets, or any longer rerun without recorded timer-only failure plus clean state triage, is a gate failure.
- If a command appears hung or idle and the next workflow action is locally available, stop the command, record the evidence in the current phase artifact or gap ledger, and continue with the b...