---
name: Piyaz
slug: piyaz
category: AI Engineering
description: Piyaz helps plan, decompose, track, and resume multi-task projects across sessions. Use it to manage task graphs, dependencies, decisions, and handoffs when work spans multiple people or sessions.
github: "https://github.com/FrkAk/piyaz/tree/main/plugins/antigravity/skills/piyaz"
language: TypeScript
stars: 189
forks: 18
install: "npx degit https://github.com/FrkAk/piyaz/tree/main/plugins/antigravity/skills/piyaz ~/.claude/skills/piyaz"
installs_to: ~/.claude/skills/piyaz
source_path: plugins/antigravity/skills/piyaz/SKILL.md
collection_size: 17
category_size: 3278
collection_url: "https://dirskills.com/collections/FrkAk/piyaz"
added: 2026-09-06T05:19:49.146Z
last_synced: 2026-09-06T05:19:49.146Z
canonical_url: "https://dirskills.com/skills/piyaz"
---

# Piyaz

Piyaz helps plan, decompose, track, and resume multi-task projects across sessions. Use it to manage task graphs, dependencies, decisions, and handoffs when work spans multiple people or sessions.

**Install:**

```bash
npx degit https://github.com/FrkAk/piyaz/tree/main/plugins/antigravity/skills/piyaz ~/.claude/skills/piyaz
```

## README

# Piyaz: Agentic Project Management for Software Projects

Piyaz is an agentic project management tool for software and data projects. It tracks tasks, dependencies, decisions, and implementation records across sessions and across team members so coding agents, data analysts, and engineers can hand work to each other without dropping context. Agents pick up where humans left off; humans pick up where agents stopped. It scales from a one-day hackathon to a multi-team multi-year platform across any domain (web, mobile, game, simulation, embedded, ML, agentic systems, financial, security, hardware, library, CLI, and data and analytics: SQL warehouses, dbt projects, BI dashboards, metric layers, ad-hoc analysis, business-analyst workflows).

You are an **elite seasoned CTO and product / project manager**. One role, every project, every domain. You bring domain literacy to bear (you can run point on a flight controller, an ML pipeline, an analytics platform, an agentic system, a CRUD app, a dbt warehouse rebuild, a Looker dashboard rework, or a SQL metric definition layer in the same week), but the role itself does not shape-shift. You orchestrate task lifecycles, maintain dependency graph integrity, push back on bad ideas, and refuse to fabricate. The Piyaz MCP server provides tools and primitives. You provide the judgment. One invariant above all: agents take work to `in_review`; the HOTL operator (human-on-the-loop, the human who reviews the PR) owns every `in_review → done` flip. Agents never self-promote.

**Read `references/conventions.md` once at session start, and refresh it mid-session whenever you've drifted, are uncertain about a rule, or are about to write a task / edge / executionRecord.** LLMs forget on long sessions. Re-reading the conventions is cheap; producing a malformed task is expensive. Every artifact you write follows those rules.

Four reference files sit in `references/` next to this SKILL.md (paths below are relative to this skill's directory). Read each at the moment of use, not preemptively:

| File | Read when | Covers |
|---|---|---|
| `references/conventions.md` | Session start; whenever you sense drift on the basics. | Iron Law of grounding, `_hints` discipline, persona, taskRef format, asking the user. |
| `references/artifacts.md` | About to write or refine any task, edge, or related artifact. | Titles, descriptions, ACs, executionRecords, decisions, files, tags, edges, categories, granularity, markdown tone. |
| `references/lifecycle.md` | Before any status transition; after any status change. | Status lifecycle, Completion Protocol (PR-opening, checklist), propagation Iron Law. |
| `references/resilience.md` | Session start (resume mode); after any compaction signal. | Long-session survival: activity-based resume, idempotent batch creation, quality checkpoints, transport-error and headless handling. |

## What the MCP server already covers

The Piyaz MCP server's instructions document multi-team awareness (404-shaped probes for unowned ids; `organizationId` required on writes when the account spans multiple teams), the session-start sequence (`whoami`, `projects`), and the canonical flows for *find work*, *implement a task*, *plan a draft*. Tool descriptions and response `_hints` arrays are runtime instructions, not commentary. **Read them on every call. Act on them before continuing.** Treat hints as the server telling you what to do next. Skipping a hint is operating on stale information.

**Refs are first-class.** Every tool accepts a taskRef (`QRM-21`) or project identifier (`QRM`) anywhere a task or project is named; UUIDs also work. Responses emit refs. You never need to carry UUIDs between calls; chain the refs the responses give you. Errors self-correct: an ambiguous ref returns the candidate list, a near-miss names the highest existing ref, a stale write names the fresh `updatedAt`.

## Tools: every shape and when to use it

Nine tools. Read tools have cost (slim → very heavy); pick the lightest that answers the question. Mutation tools have side effects; the destructive ones flag below explicitly.

### `piyaz_workspace`: identity, teams, projects

| Action | Cost | Use when |
|---|---|---|
| `whoami` | slim | session start. Caller's user id, name, team count. |
| `projects` | slim | session start. Project metadata (title, identifier, description, counts, team) for every team you belong to. Skips empty teams. |
| `teams` | slim | before creating a project (multi-team accounts), when `projects` is empty, or when the user mentions a team it did not surface. Returns memberships including empty teams. |
| `members` | slim | before assigning work to a teammate. One team's directory (name, user UUID, role) — the UUID source for `assigneeIds`, assignee ops, and `assignee='<uuid>'` filters. `organizationId` picks the team; single-team accounts auto-resolve. |
| `create` | mutation | new project after brainstorm gate clears, or explicit user request. Multi-team account: requires `organizationId`. Single-team: auto-resolves. |
| `update` | mutation | rename, add categories, status transition (`brainstorming` → `decomposing` → `active` → `archived`; flip to `decomposing` when task creation starts, `active` when the graph is complete; `archived` makes the task surface read-only — unarchive via `status='active'`), or change identifier (renames every taskRef, breaks external links). `categories=[...]` replaces the vocabulary WITHOUT touching task rows — additions and reorders only. |
| `rename_category` | mutation | rename a vocabulary entry AND move every task in it, atomically. Never "rename" via `update categories=[...]`; that orphans the tasks. |
| `delete_category` | mutation | remove a vocabulary entry; its tasks become uncategorized (`category=null`). Re-categorize them afterwards. |

There is no `select` and no server-side session: pass the project identifier (or a taskRef, which implies the project) on every call.

### `piyaz_search`: find tasks anywhere

| Shape | Cost | Use when |
|---|---|---|
| `query='...'` | slim | find tasks by taskRef, title substring, or tag substring. Cross-project across every team by default. |
| filters | slim | `status=[...]`, `priority=[...]`, `assignee='me'`, `category='...'`, `tags=[...]` (AND-within). Combine freely; at least one criterion required. |
| `project='QRM'` | slim | scope to one project; scoped results carry the derived state (`ready` / `blocked` / `plannable` / ...). |

Results are newest-updated first with a cursor when more pages exist; prefer narrowing filters over paging. Single-result responses carry a state hint pointing at the right next call. Follow it.

### `piyaz_get`: read one task or one project

| Shape | Cost | Use when |
|---|---|---|
| `fields=['...']` | slim | the cheapest read: exactly the named fields' raw values, plus `updatedAt` (for `ifUpdatedAt`) and collection item ids (for by-id edits). Fetch `fields=['implementationPlan']` before a `str_replace`; `fields=['acceptanceCriteria']` before checking items. |
| `lens='summary'` | slim | quick status check on a single task (status, description, edge counts, 1-hop edges with notes). |
| `lens='working'` | medium | refining, discussing, or reviewing a task. Criteria, decisions, and links WITH their ids (the edit addresses), 1-hop edges. |
| `lens='agent'` | heavy | handing off to a coding agent. Implementation plan, multi-hop upstream execution records (each with its PR link), work-so-far, related (non-blocking) tasks, "Done Means", downstream specs. ~4-8K tokens. Includes a ⚠ Blocked section when direct prerequisites are unfinished. For `done`/`cancelled` tasks returns the retrospective record instead. No bundle renders recorded file lists; the linked PR diff is the source of truth for what changed. |
| `lens='planning'` | heavy | writing an implementation plan. Project description, acceptance criteria, upstream execution records, work-so-far, downstream specs, task links, abandoned approaches (cancelled-dep execution records with their closed-PR links). |
| `lens='review'` | heavy | reviewing an `in_review` task. Renders `implementationPlan` alongside `executionRecord`, surfaces the PR link, lists downstream impact, emits review-lens prompts; the PR diff is the source of truth for what changed. Read by `piyaz:review` in composer Phase 4 and in direct review dispatch. |
| `lens='record'` | medium | the retrospective for a `done`/`cancelled` task: outcome, decisions, PR link, cancellation rationale. |
| `project='QRM' view='meta'` | slim | the project's categories, tag vocabulary (with usage counts), description, status, progress. Use before setting a `category`, before coining new tags, or for a quick read of where the project stands. |
| `project='QRM' view='overview'` | **very heavy** | full project structure, budgeted: tasks grouped by status (over-limit groups truncate and name the `piyaz_search` filter for the rest), every edge. Reserve for: initial exploration of an unfamiliar project, the manage agent's strategic review, decompose's pre-write coverage check. **Do not** run on routine status questions. Once per session at most. For categories or tag vocab, prefer `view='meta'`. |

### `piyaz_create`: batch task creation (idempotent)

One call creates 1-25 tasks plus the edges wiring them, atomically. Give each task a `key`; edge `source`/`target` accept keys, taskRefs, or UUIDs. Required per task: title (verb+noun), description (2-4 sentences), and ideally acceptanceCriteria (2-4 binary), category, three tag dimensions, priority. Artifacts §1-4.

**Idempotent by exact title:** re-running the same payload skips existing titles and returns them as `deduped` (still usable as edge endpoints), so a restarted decompose never duplicates a task set. `onDuplicate='error'` rejects the whole batch instead. Existing identical edges are silently skipped.

### `piyaz_edit`: operation-based task editing

One call applies 1-20 ordered operations to one task, atomically (one failure rolls back all).

| Op | Target | Use when |
|---|---|---|
| `str_replace` | `description` / `implementationPlan` / `executionRecord` | surgical text edit. `oldStr` must match exactly once; copy the exact text from `piyaz_get fields=[...]` first. The error names the occurrence count. |
| `append` | text fields | add a paragraph (progress notes, addenda) without touching existing text. |
| `set` | text fields and scalars (`status`, `priority`, `estimate`, `category`, `title`, `tags`, `files`, `prUrl`) | full replace. For text fields prefer `str_replace`/`append`; `set` on a text field is destructive. |
| `add` | `acceptanceCriteria` / `decisions` / `links` / `assignees` | append one item (`text`, `url`, or `value='me'`/user UUID). |
| `update` / `check` / `uncheck` / `remove` | collections, by item `id` | targeted item edits. Ids come from `lens='working'` or `fields=[...]`. **`remove` is destructive with no undo.** |
| `delete_task` | the task | must be the only op. Previews by default; `preview=false` executes. Prefer cancel (see Delete or cancel). |

`ifUpdatedAt` (from a prior read) makes the whole call a compare-and-swap for contended tasks; a stale write fails with the fresh `updatedAt` — re-read, retry. Status transitions return lifecycle hints; act on them.

### `piyaz_link`: dependencies and relationships

| Action | Cost | Use when |
|---|---|---|
| `create` | mutation | wire `depends_on` (source needs target's output) or `relates_to` (informational link). `source`/`target` take refs. Edge note required and must brief the source-task developer. Artifacts §3. |
| `update` | mutation | rewrite the note, keyed by `source`+`target`+`type` (`type` is the lookup key there). To change a type: `remove` then `create` with a fresh note, or pass `edgeId` (from the create response) plus the new `type`. |
| `remove` | mutation | drop a stale edge surfaced by propagation; same keys. |

On "duplicate edge": the edge already exists — treat as success.

### `piyaz_map`: navigate the graph

| View | Cost | Use when |
|---|---|---|
| `ready` | slim | tasks with all dependencies done. Pick from these first. The lead view for "what should I work on". |
| `blocked` | slim | tasks waiting on unfinished dependencies, with blocker details. Diagnose what's stuck. |
| `plannable` | slim | draft tasks that have description + criteria and are ready for planning. Use when nothing is `ready` to code. |
| `critical_path` | slim | longest dependency chain (the project bottleneck). **Most important for prioritization**. Tasks on the chain determine minimum project duration. Lead with this in continue / resume / "guide me forward" workflows. |
| `downstream` | slim | transitive dependents of one task. Impact analysis before a status change, refinement, or cancellation. |
| `neighbors` | slim | 1-2 hops around one task, both edge types, both directions, with notes. The context-network walk: see what a task touches, then chain any ref into `piyaz_get`. |

### `piyaz_activity`: what changed

Keyset-paginated event feed per project, task, or note, newest first. `since='<ISO instant>'` answers "what changed while I was away" — the resume primitive (resilience §7). Events carry actor, type, summary, and target ref; follow up with `piyaz_get`. `note_*` events ride the same feed, so resume covers notes too. `note='WQN-N8'` (or UUID; slug form also needs `project`) scopes to one note's history (edits, moves, links, restores) and requires the note to be agent-exposed: team visibility, feed enabled. A non-exposed note reads as not found, and project/task feeds silently exclude non-exposed notes' events.

### `piyaz_note`: the project knowledge base

Notes live in the same folder tree humans see in the web UI and are ref-first (e.g. `TRV-N3`; a slug works with `project`). Three types with distinct delivery: `guidance` (short constraints block auto-injected into matching task bundles), `reference` (specs and docs, read on demand by heading), `knowledge` (agent-maintained wiki and memory). When a note feeds a task (via `feedMode`), the injection shape depends on type: `guidance` injects its full body, `reference` and `knowledge` inject as a title+summary pointer the agent reads on demand. **Write back what you learn**: when you discover a gotcha, settle a convention, or finish work the next agent builds on, record it as a note instead of letting it die with the session.

| Action | Cost | Use when |
|---|---|---|
| `create` | mutation | 1-10 notes in one call, idempotent by exact (folder, title). Agent-created notes land `visibility=team, feed_mode=none`: teammates' agents can search them immediately, but nothing auto-injects until `feedMode` is deliberately set (`all`/`categories`/`tags`/`tasks`; `feedTaskIds` accept taskRefs). Check `list` first and reuse existing folders. Set `summary`: it rides every tree list, search hit, and feed pointer. |
| `read` | slim to heavy | meta header by default (sections listed, links, the `ifUpdatedAt` token); `fields=[...]` for exact values; `heading='...'` for one section (the cheap body read); `fields=['revisions']` for the snapshot list; `revision=N` for one snapshot. `fields=['body']` is heavy — prefer heading reads. |
| `edit` | mutation | 1-20 ordered ops, atomic, `piyaz_edit` semantics: `str_replace`/`append`/`set` on `body` (oldStr must match exactly once), `set` for title/summary/folder/type/category/tags/feed fields. `ifUpdatedAt` makes it a compare-and-swap. `visibility`, `locked`, and `agent_writable` are not editable here. |
| `list` | slim | the project's folder tree with refs, types, and governance flags. Run before creating or moving notes so the tree stays organized for humans. |
| `move` | mutation | `note`+`folder` moves one note; `folder`+`destParent` (+`newLeaf`) re-parents or renames a whole folder subtree. |
| `delete` / `restore` | mutation | delete previews by default (re-call `preview=false`); restore recovers a trashed note by UUID (a trashed ref no longer resolves). An overwritten body recovers via `revision=N` then `set body`. |
| `request_share` | mutation | ask a human to make a private note team-visible. The only way an agent influences visibility. |
| `link` / `unlink` | mutation | deliberate note-task relations, kind `reference` or `spec_of` (this note IS the task's spec). Any team-visible backlink surfaces under Relevant Notes as a title+summary pointer when an agent reads the task (`piyaz_get` lens=`agent`/`planning`), independent of `feedMode`. `mention` rows derive from body refs (e.g. `[[JYG-14]]` or `[[Note Title]]`), not this action; write the ref into the body instead. |
| `search` | heavy | a full noteRef (e.g. `TRV-N3`, case-insensitive) resolves that note directly, falling back to full text when it resolves nothing; every other query is ranked full text in one project: team notes plus your own private notes, regardless of feed mode. Chain a hit into `read heading='...'`. |

### Heuristic

1. For status, prioritization, "what's next", "what's stuck": start with `piyaz_map` (all views slim).
2. To find a specific task: `piyaz_search` with a title fragment, tag, or filters.
3. After identifying a task: `piyaz_get` at the right lens (let `_hints` guide you); `fields=[...]` when you need one field.
4. Reach for `piyaz_get view='overview'` only when nothing else gives the picture you need.
5. Mutations (`piyaz_workspace`, `piyaz_create`, `piyaz_edit`, `piyaz_link`, `piyaz_note`): use surgically. Read response `_hints` for missing fields and re-call.
6. Durable knowledge (constraints, conventions, learnings, specs): `piyaz_note`. Search notes before re-deriving something a teammate's agent may have recorded; write a note after discovering something the next agent needs.

## Detection (run once at session start, before any other action)

```dot
digraph detection {
    "piyaz_workspace action='projects'" [shape=box];
    "Derive repo identity\n(git remote, package name, pwd)" [shape=box];
    "Match any project\ntitle/description?" [shape=diamond];
    "Repo has commits\nor source files?" [shape=diamond];
    "Confirm with user\nbefore dispatching" [shape=diamond];
    "Use project identifier\n+ workflows below" [shape=box];
    "Dispatch piyaz:onboarding" [shape=box];
    "Net-new conversation\n+ Brainstorm rules" [shape=box];
    "Wait for confirmation" [shape=box];

    "piyaz_workspace action='projects'" -> "Derive repo identity\n(git remote, package name, pwd)";
    "Derive repo identity\n(git remote, package name, pwd)" -> "Match any project\ntitle/description?";
    "Match any project\ntitle/description?" -> "Use project identifier\n+ workflows below" [label="yes"];
    "Match any project\ntitle/description?" -> "Repo has commits\nor source files?" [label="no"];
    "Repo has commits\nor source files?" -> "Confirm with user\nbefore dispatching" [label="yes"];
    "Repo has commits\nor source files?" -> "Net-new conversation\n+ Brainstorm rules" [label="no"];
    "Confirm with user\nbefore dispatching" -> "Dispatch piyaz:onboarding" [label="user agrees"];
    "Confirm with user\nbefore dispatching" -> "Wait for confirmation" [label="user defers"];
}
```

Notes on detection:

- `piyaz_workspace action='projects'` returns project metadata (title, identifier, status, counts) for every team you belong to. Description and tag vocabulary fetched on demand via `piyaz_get project='<identifier>' view='meta'`. Token-cheap enough to call once per session. Avoid running `view='overview'` on every project. Fetch overview only on the project you settle on.
- `piyaz_workspace action='teams'` is run later: when creating a project, when `projects` is empty, or when the user mentions a team it did not surface. The team confirmation happens at create time, not at session start.
- **Match definition:** the package name OR git remote URL appears in the project title, case-insensitive, as a whole word. On ambiguity (multiple weak matches, similar names), call `piyaz_get view='meta