Task Engineering With Taskfile

Keep orchestration in the project's Taskfiles. Go Task supplies execution semantics; pi-taskfile supplies reusable Task definitions and opt-in Pi helpers. We author their composition, instructions, checks, and public tasks.

Workflow

1. Locate the actual consumer. Identify the requested operation, entrypoint, includes, relevant scripts, .taskrc.yml, and working directory. Inspect existing changes and task --version; for Pi work, locate the actual package and check pi --version. Done when the changed behavior has an owner and the source directory is distinct from the execution directory. If essential source/tools are unavailable, request that resource or limit the deliverable explicitly.
2. Read the relevant contract. Use the branches below before choosing syntax or architecture. Start with installed-version source and official documentation, not recalled flags. Existing Task examples target 3.54.0; preserve a project's lower minimum unless a justified change requires raising it.
3. Compose the smallest change. Use includes for reuse, cmds task calls for order, and native loops, conditions, deadlines, and cleanup. Give leaf commands explicit inputs and effects. A helper is justified by work Task cannot express cleanly, not by moving the workflow into a second controller. For creation, define the public task and its completion condition; for updates, preserve callers and document any changed contract.
4. Exercise the boundary. Inspect dynamic variables and remote code before even listing or previewing: sh can execute during --dry. On trusted inputs, choose a disposable check that could expose the feared failure—ordering, overrides, literal data, freshness, cancellation, or packaging. Run only the relevant branch; model calls and project checks have real cost and effects.
5. Close with evidence. Report the artifact, observed result, and limits. Process success, passing checks, model advice, and user acceptance are distinct. Publishing or changing installed settings requires authorization for that action; preparing a candidate does not supply it.

References

Read only the branches needed for the current decision; follow another when the boundary changes.

• Pi usage — run or configure existing pi-taskfile consumers, select skills/recipes, or distinguish installation from invocation.
• Pi development — create or update consumers, agent specializations, recipes, Markdown inputs, or lifecycle helpers.
• Publishing and distribution — share Taskfiles or prepare/release a Pi package; distinguish local, remote-YAML, and complete-package boundaries.
• Troubleshooting — localize a symptom before changing flags, restoring files, or adding machinery.
• Execution — choose ordering, concurrency, repetition, guards, deadlines, or cleanup.
• Variables and inputs — preserve overrides, typed values, literal text, CLI arguments, validation, loops, and secret handling.
• Includes — resolve namespaces, source paths, execution directories, inherited defaults, or remote trust.
• Incremental builds — diagnose stale/repeated work, declare inputs/outputs, or configure watching.
• Shell and CLI — resolve shell state, environment/configuration, Taskfile selection, or CI output.
• Examples — choose a typed, bounded fixture with stated prerequisites and expected results; ordered calls is the smallest starting point.
• Taskfile versions — check format/minimum-version compatibility before adopting new syntax; use the schema for unlisted keys.
• Source history and evidence — refresh this maintained skill or inspect historical provenance and verification limits.