piyaz_task
Create, update, or delete tasks.
piyaz_task
Create, update, or delete tasks. Lifecycle: draft → planned → in_progress → in_review → done. The implementer subagent's terminal write is in_review (PR opened, tests green); the HOTL gate flips to done after PR approval. cancelled is terminal abandoned work with transparent dep semantics (dependents stay blocked through the cancelled task's own unsatisfied prereqs; populate executionRecord with rationale). create requires title (verb+noun, imperative), description (2-4 sentences; single-sentence rejected), 2-4 binary acceptanceCriteria, three tag dimensions (work-type, cross-cutting, tech), one project category. priority, estimate, and assigneeIds are first-class fields, not tags: priority (urgent / core / normal / backlog), estimate (Fibonacci story points 1/2/3/5/8/13), assigneeIds (array of team-member user UUIDs). After create: search precedents/coordinators by verb+noun+surface, wire piyaz_edge, verify with piyaz_query type='edges'. Bare tasks orphan from critical_path, downstream, depth='agent'. update: pass only changed fields. Array fields (acceptanceCriteria, decisions, files, assigneeIds) APPEND by default; overwriteArrays=true REPLACES them. Destructive, NO undo (history is an audit log); confirm with user first. delete: preview=true (default) shows impact; preview=false executes. Prefer status='cancelled' for abandoned scope so the rationale is preserved. Done means: executionRecord (3-5 sentences, what was built), decisions (CHOICE+WHY), files (every path), acceptanceCriteria evaluated. Open a PR if files non-empty; run piyaz_analyze type='downstream' to propagate.
Actions
| Action | Purpose |
|---|---|
create | new task |
update | modify fields (pass only what changed) |
delete | remove (preview by default) |
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
action | "create" | "update" | "delete" | Yes | create=new task. update=modify fields (pass only what changed). delete=remove (preview by default). |
acceptanceCriteria | unknown[] | No | 2-4 binary items (reviewer answers YES/NO; single-AC and vague ACs like 'works correctly' rejected). Pass strings for new criteria, or {text, checked} objects to evaluate existing rows. Artifacts §1. |
assigneeIds | string[] | No | User UUIDs to assign to this task. Each must be a member of the project's owning team; non-members are rejected. The single-worker in_progress invariant still applies; assignees declare ownership / intent, not concurrent claim. APPENDS by default on update; overwriteArrays=true REPLACES the full set. |
category | string | No | Architectural layer / subsystem this task belongs to (exactly one). Reuse a project category; do not silently coin mid-task. The project's 4-8 categories are set on creation or via decompose/onboarding gates. Run piyaz_query type='meta' to see them. Artifacts §4. |
decisions | string[] | No | Technical choices and constraints. One-liner per decision (CHOICE + WHY). |
description | string | No | 2-4 sentences (up to 6-8 for genuinely complex tasks; single-sentence rejected): what + who it serves + where it fits in the architecture. Required for create. Artifacts §1. |
estimate | 1 | 2 | 3 | 5 | 8 | 13 | No | Fibonacci story-point estimate. 1 = trivial, 2/3 = routine, 5 = nontrivial, 8/13 = risky or multi-day. If a task feels >13, split it (artifacts §5). |
executionRecord | string | No | 3-5 sentences on HOW it was built (function names, file paths, endpoints; distinct from description=scope). For cancelled: rationale + what was tried instead. Draft tasks must not carry this. Iron Law: cite real code, omit what you cannot. Markdown. Artifacts §1. |
files | string[] | No | Repo-relative paths created or modified (no leading slash, no absolute). Pass files=[] when nothing was touched (unscaffolded repo, research/spec-review/decision-only); never invent paths. |
implementationPlan | string | No | Implementation plan (markdown, unabridged; do not summarize). Pass with status='planned' to transition draft → planned; without the status change the task stays incomplete (lifecycle §1). |
overwriteArrays | boolean | No | Update only. true=replace decisions/acceptanceCriteria/files; default false=append. Destructive, NO undo; confirm with user first. |
preview | boolean | No | Delete only: true=show impact (default), false=actually delete. |
priority | "urgent" | "core" | "normal" | "backlog" | No | Priority of the task. urgent: cannot ship without; core: central to the release; normal: routine; backlog: deprioritized. |
projectId | string (uuid) | No | Project UUID. Required for create. Project's team scope is inherited. |
prUrl | string | null | No | PR URL for this task's code change. Sugar field that upserts a task_links row with kind derived from the URL classifier (pull_request for github.com/.../pull/N, gitlab.com/.../merge_requests/N). Pass alongside status='in_review' in the Completion Protocol payload; the composer-implementer subagent writes this in the same call as executionRecord/decisions/files/acceptanceCriteria. Pass null to remove an existing PR link. Other link kinds (issues, commits, docs) are user-managed via the UI; only PRs are agent-write today. |
status | "draft" | "planned" | "in_progress" | "in_review" | "done" | "cancelled" | No | Lifecycle: draft → planned → in_progress → in_review → done. The implementer subagent's terminal write is in_review (PR opened, tests green); the HOTL gate flips to done after PR approval. cancelled = terminal abandoned work; populate executionRecord with rationale. Cancelled deps are transparent: dependents stay blocked through the cancelled task's own unsatisfied deps. Excluded from progress and critical path. |
tags | string[] | No | Kebab-case. Every task carries three tag dimensions: exactly 1 work-type (bug/feature/refactor/docs/test/chore/perf), ≥1 cross-cutting concern (open: quality attribute or feature cluster), at most 2 tech tags (most important stack pieces touched). Priority is the priority field, not a tag. Do NOT tag codebase area (use category) or status. Run piyaz_query type='meta' before coining new tags. |
taskId | string (uuid) | No | Task UUID (not the 'MYM-N' taskRef; refs are display-only). Required for update/delete. |
title | string | No | Verb+noun, imperative. Required for create (e.g. 'Implement JWT auth', not 'Auth'). Artifacts §1. |