Prompt file imported from anouar1991/copilot-prompts (.github/prompts/taskflow-contracts.prompt.md). Copyright stays with the author.

Prompt: /taskflow-contracts

Purpose Execute the tasks defined in plan/tasks.json, respecting explicit dependencies and using contract clauses if present. Update only the status fields inside plan/tasks.json (do not modify other content). Provide clear, concise logs and a final summary. Use the available toolset to implement, test, and validate each task.

Operational constraints (MANDATORY)

• Read and parse plan/tasks.json at start. Do not change any fields except status. You may create new files (logs, branches, PRs) as needed but do not alter task id, name, description, dependencies, or any other fields.
• Allowed status values (use these exact strings): "To Do", "In Progress", "Done", "Blocked", "Failed".
• Respect explicit dependencies: a task may only be started when all tasks listed in its dependencies are "Done".
• If a task includes contract fields (requires, guarantees, validation, actions), enforce them as described below. If those fields are absent, fall back to dependency-only gating.
• Always keep an execution log of actions, commands, outputs, and validation results. Save it to a file (e.g., artifacts/task-execution-log.md) and include a concise log summary in each chat update.
• Use available tools (e.g., editFiles, runCommands, codebase, runTests, playwright, vscodeAPI, githubRepo, changes, testFailure, etc.) to implement changes, run validation, and capture outputs.
• If you cannot complete a task for reasons outside your control (missing credentials, network/permission issues, human decision required), set status to "Blocked" or "Failed" with a clear reason and error outputs.

High-level flow (implement exactly)

1. Load & analyze plan/tasks.json. Build an in-memory dependency graph. Detect cycles; if cycles exist, mark the involved tasks "Blocked" and report them immediately with cycle details (list of task ids forming the cycle). Halt further automatic execution until cycles are resolved (report recommended resolution).
2. While there exists any task not "Done": a. Identify ready tasks: tasks whose status is "To Do" or "In Progress", and whose dependencies are all "Done". Among ready tasks, prefer lowest complexity (ties by lexical id) unless a task is "In Progress" — in that case continue it first. b. For each ready task, process as below (in priority order). Do not start multiple tasks in parallel unless explicitly allowed by orchestration; prefer sequential single-task processing to keep logs and commits atomic.

Per-task processing (guaranteed checks and strict steps)

1. Pre-check / Already-completed detection:

   • If the task has guarantees or validation fields:

     • Attempt to verify those guarantees BEFORE changing status:

       • Run the validation checks if they are machine-executable (commands, tests). Otherwise, run heuristics (e.g., check package.json for installed packages, check file existence, check exports in source files, run npm run build if appropriate).
       • If all declared validation checks pass or guarantees are clearly present, update task status to "Done" (write to plan/tasks.json) and append an entry to the execution log describing the verification steps and results. Skip further execution.

   • If the task has no contract fields: do best-effort heuristic checks (e.g., search codebase for expected changes, query test files). If heuristics show task is already implemented, mark "Done" with log notes.

2. Start or continue execution:

   • If status was "To Do", set "In Progress" in plan/tasks.json and commit that single-field update (use editFiles / version control tools).
   • If status was "In Progress", continue where it left off.

3. Ensure preconditions:

   • If task declares requires entries, verify each requires condition:

     • If a requires item is satisfied (validation/heuristic), proceed.
     • If unsatisfied but some other task in plan/tasks.json optionally guarantees it, ensure that guaranteeing task is "Done"; if not, pause this task, set it "Blocked", and begin executing the guaranteeing task(s) first (recursively follow normal flow).
     • If unsatisfied and no guaranteeing task exists, attempt to resolve automatically if feasible (install missing package, create missing file), otherwise set "Blocked" with an explicit reason and remediation steps.

   • Always record checks and decisions in the log.

4. Execute actions:

   • If the task has an actions list (shell commands or higher-level steps), run them in order using runCommands or appropriate tooling, capturing stdout/stderr, exit codes, and environment context.
   • If actions are human-level instructions (e.g., "Replace custom Button component with Ant Design Button"), implement using code-editing tools (editFiles, codebase, vscodeAPI), run linters/tests, and create commits in a task branch (recommended).
   • For code edits, include concise commit messages prefixed with the task id (e.g., task: install-refine-core-packages — install packages).

5. Post-execution validation:

   • Run the task validation checks (if defined) and any additional checks appropriate for the changes (build, unit tests, type-check).
   • If all validations pass, set status to "Done", update plan/tasks.json, log the successful validations and attach outputs/links (branch/commit/PR).
   • If one or more validations fail, attempt the following in order: a. Capture and log the failure details (test diffs, error logs). b. If failure is due to a missing dependency, mark this task "Blocked" and begin the missing dependency task(s). c. If failure appears fixable automatically (lint, minor code fix), attempt a single automated fix and re-run validations. If fix succeeds, mark "Done". d. If failure persists or is non-trivial, set status to "Failed", include failure details and suggested next steps, and do not proceed to dependents that require this task.

6. Guarantee registration:

   • If task reaches "Done", register its guarantees (if present) in the internal contract registry so downstream tasks can detect them. Persist this registration to the execution log.

7. Update recommended next step (optional, do not overwrite fields in plan/tasks.json besides status):

   • Keep an internal recommendation logic (lowest complexity ready task). Do not modify recommendedNextStepId in the file unless explicitly authorized.

Atomic updates & safety

• Always write a single, atomic status change to plan/tasks.json per step and record the change in the execution log with timestamp and reason.
• If a code or configuration change is performed, create a small, focused commit and branch. When practical, open a pull request; include task id and summary in the PR body.
• If a task is automated and touches sensitive credentials or secrets, do not commit secrets — instead record the required steps and set "Blocked" with explicit instructions.

Error handling & escalation

• Cycles: detect immediately and mark involved tasks "Blocked". Report cycle and recommended breakpoints.
• Permission / environment errors: mark the affected task "Blocked", log the error, and request human intervention (use human-intelligence tool).
• Unexpected exceptions during execution: capture stack traces/logs, set "Failed", and include remediation suggestions.
• When encountering ambiguous requires/guarantees statements, apply conservative interpretation: prefer to block and request human clarification rather than make risky assumptions. Use human-intelligence if needed.

Reporting & final summary

• After each task completes (or becomes blocked/failed), produce a concise chat update showing:

  • Task id, name, previous status → new status
  • Short summary of actions taken (1–2 lines)
  • Validation results (pass/fail) and links to logs/commits/PRs

• When processing completes (all tasks "Done", or no further progress possible), produce a final report containing:

  • Total tasks, counts by status (Done, Blocked, Failed, In Progress, To Do)
  • List of "Blocked" and "Failed" tasks with exact reasons and next-step recommendations
  • Execution log file path and a short curated excerpt
  • Suggested human-review items (e.g., PRs to merge, tests to review)

Useful heuristics & utilities (apply liberally)

• For package install tasks: verify package.json (dependencies), node_modules, and package-lock.json or pnpm-lock.yaml. Run npm ci/pnpm install for validation when needed.
• For code migrations: run TypeScript type-check (tsc --noEmit) and npm run build.
• For UI/visual checks: run unit tests and, if available, Playwright/E2E tests; produce screenshot diffs if helpful.
• For data provider or API tasks: run integration smoke tests and sample queries, capture request/response logs.
• Use search and codebase to find occurrences of old components to migrate; record files changed.
• Prefer minimal, reversible changes. Keep every change traceable.

Example minimal status update (pseudo-step you must perform with the editFiles tool)

• Read plan/tasks.json → find task install-refine-core-packages status "To Do".
• After verifying it needs action, update file:

- "status": "To Do"
+ "status": "In Progress"

• Commit the single-field update with message: task: install-refine-core-packages → In Progress.

Final notes (short)

• Never change plan/tasks.json fields other than status.
• Always validate guarantees after executing actions; only mark "Done" when validations pass.
• Always keep a machine-readable and human-readable execution log.
• When uncertain, err on the side of blocking and asking for guidance rather than making destructive changes.

Start now: Load plan/tasks.json, analyze the graph, and begin with the first ready task following the rules above. Provide iterative chat updates as you progress and include links to logs/branches/PRs where relevant.

If you want, I can also produce:

• a tiny helper script (Node.js) that performs the status updates atomically and can be invoked by the agent, or
• a JSON Schema that enforces the allowed contract fields and status enum.

Which of those would you like me to generate next?