piyaz_query
Search and browse project data.
piyaz_query
Search and browse project data. Pick the slim tool first; reserve overview for unfamiliar projects. search=tasks by taskRef, title, or tag substring (case-insensitive, up to 20). Pass tags=[...] for exact tag match (OR-within); combine with query to AND-narrow. Pass category='...' for exact project-category match (closed vocabulary; unknown values rejected with the valid list inline); combines with query/tags via AND. Single-result responses include a state hint pointing to the right next call. list=every task in the project (slim, ordered by position). edges=relationships on one task (connected title, status, direction, note). meta=slim project metadata: header, description, status, categories, tag vocabulary (with usage counts), progress + status counts. No task list, no edges. Use this to look up categories before setting one, or the tag vocabulary before coining new tags. overview=full project structure: every task, every edge, full tag vocab, progress. VERY HEAVY. Reserve for unfamiliar-project orientation, decompose's pre-write coverage check, or strategic review. At most once per session. For just categories or tag vocab, use meta.
Actions
| Action | Purpose |
|---|---|
search | find tasks by taskRef, title, or tag (case-insensitive, up to 20) |
list | all tasks ordered by position |
edges | relationships on a task |
meta | slim project metadata (header, categories, tag vocab with counts, progress); use to look up categories or tag vocab without overview |
overview | full project structure with progress + tag vocab + every task + every edge |
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
type | "search" | "list" | "edges" | "meta" | "overview" | Yes | search=find tasks by taskRef, title, or tag (case-insensitive, up to 20). list=all tasks ordered by position. edges=relationships on a task. meta=slim project metadata (header, categories, tag vocab with counts, progress); use to look up categories or tag vocab without overview. overview=full project structure with progress + tag vocab + every task + every edge. |
category | string | No | Filter to tasks in exactly this category (AND with query/tags). Must be one of the project's categories (closed vocabulary); unknown values are rejected. Run piyaz_query type='meta' for the current list. |
projectId | string (uuid) | No | Project UUID. Required for search/list/meta/overview. |
query | string | No | Search string for type='search'. Matches taskRef, title substring, or tag substring. Optional when tags is provided. |
tags | string[] | No | Filter to tasks containing ANY of these exact tags (OR-within). Combine with query to narrow further. Pick from the tag vocabulary in type='meta'. |
taskId | string (uuid) | No | Task UUID for type='edges'. |