Skills and agents

The Piyaz plugin ships the same skill set on Claude Code, Codex, Cursor, and Antigravity. Commands are skills you or the model invoke; agents are dispatched by skills for focused phases of work. The descriptions below are the live trigger text from the plugin source.

Commands

/piyaz

Use when the user wants to plan, decompose, track, or resume a multi-task project: scoping a new idea, importing or onboarding an existing repo or workspace, asking what to work on / what's next / what's blocked / where they left off, reporting task completion, dispatching work in parallel, or planning a draft task. Also when the user mentions Piyaz by name (e.g. "piyaz, do X") or references a task by its ref (e.g. VLT-9, KRN-153, PXD-31). Works for any project domain (code or data). Do not invoke for: one-off coding questions, single-file edits, debugging a specific error, generic todos, or scheduling.

/piyaz:brainstorm

Explicit doorway to the Piyaz brainstorm subagent. Use only when the user types /piyaz:brainstorm directly. For natural-language brainstorm requests (the user describes a net-new project idea), the /piyaz skill or the assistant dispatches the brainstorm agent via the Task tool, do not invoke this skill for that path.

/piyaz:composer

Use when the user types /piyaz:composer, /piyaz:composer <taskRef>, or /piyaz:composer rework <taskRef|pr-url>, or asks to run the next Piyaz task end-to-end, ship the backlog, compose through the ready queue, or loop through Piyaz tasks until done. Composer researches, refines, plans, implements, reviews, and fixes each task in a loop until the PR is ready, and merges and continues when the user authorizes it. Do NOT invoke for one-off task lookups, status checks, hand-refinement of one task, or interactive planning of a single task; those flows belong to the piyaz skill and composer adds latency without adding quality.

/piyaz:decompose

Explicit doorway to the Piyaz decompose subagent. Use only when the user types /piyaz:decompose directly. For natural-language decompose requests (the user asks to break a project description into tasks), the /piyaz skill or the assistant dispatches the decompose agent via the Task tool, do not invoke this skill for that path.

/piyaz:decompose-feature

Explicit doorway to the Piyaz decompose-feature subagent. Use only when the user types /piyaz:decompose-feature directly. For natural-language requests to add a new feature or capability cluster to an active project, the /piyaz skill or the assistant dispatches the decompose-feature agent via the Task tool. Do not invoke this skill for that path.

/piyaz:decompose-task

Explicit doorway to the Piyaz decompose-task subagent. Use only when the user types /piyaz:decompose-task directly. For natural-language requests to split an existing oversize task (the user says "split this task" or composer's oversize handler routes here), the /piyaz skill or the assistant dispatches the decompose-task agent via the Task tool. Do not invoke this skill for that path.

/piyaz:manage

Explicit doorway to the Piyaz manage subagent. Use only when the user types /piyaz:manage directly. For natural-language manage requests (strategic review, graph health audit, rebalancing, deep planning, housekeeping), the /piyaz skill or the assistant dispatches the manage agent via the Task tool, do not invoke this skill for that path.

/piyaz:onboarding

Explicit doorway to the Piyaz onboarding subagent. Use only when the user types /piyaz:onboarding directly. For natural-language onboarding requests (the user asks to import an existing repo into Piyaz), the /piyaz skill or the assistant dispatches the onboarding agent via the Task tool, do not invoke this skill for that path.

Agents

brainstorm

Use when the user has a net-new software project idea that needs shaping into a brief before tasks can be created. Triggers: "I want to build...", "I'm thinking about an app for...", "let's plan a project", vague or exploratory phrasing, ambiguous scope. Do not use when an existing repo is present (route to onboarding), a Piyaz project already exists with a description, or the user has a complete spec ready (route to decompose).

composer-implementer

Phase 3 of the /piyaz:composer pipeline. Dispatched per task by the composer orchestrator after the planner has saved the implementationPlan to Piyaz. Reads the plan, implements it on a feature branch with production-grade quality (security, performance, reliability, observability), runs the project's tests / typecheck / lint until green, opens a pull request using the project's PR template with the [<taskRef>] bracket form on the title, and marks the task in_review in dispatched mode per the Completion Protocol (executionRecord, decisions, files, evaluated acceptance criteria); the HOTL operator finalizes in_review → done after PR approval. Does not refine or replan. If the plan is broken, fails loudly back to the orchestrator. Invoked automatically by the composer skill; safe to call directly when the user asks "implement <taskRef> per the saved plan" outside the composer loop.

composer-planner

Phase 2 of the /piyaz:composer pipeline. Takes a research brief plus the target task's planning context, writes the unabridged implementationPlan to Piyaz, and transitions the task draft → planned in the same update. Fills refinement gaps the researcher missed via append-only updates. Returns a one-sentence confirmation. Does not edit code, run tests, or open PRs. The composer workflow runs a merged research+plan phase on the researcher, so this agent serves direct dispatch: call it when the user asks "plan <taskRef> from the research brief" outside the composer loop.

composer-researcher

Phase 1 of the /piyaz:composer pipeline. Dispatched per task by the composer orchestrator to gather grounded context before planning. Reads the target task at multiple Piyaz context depths, searches up-to-date library docs via context7, explores the codebase for files and patterns the implementer will touch, surfaces the project's house conventions (commit format, test/lint/typecheck commands, PR template), and reasons about security, performance, and reliability standards the work must meet. Applies refinements (description, acceptance criteria, tags, category, priority, estimate, decisions) directly to the target task and returns one research brief; writes nothing to the repo or any external system. Composer workflow dispatches carry a merged mandate: an explicit authority grant under which this agent also designs and writes the implementationPlan and flips draft → planned. Without that grant it never writes implementationPlan or status. Safe to call directly when the user asks "research task <taskRef>" or "investigate <taskRef> before planning" outside the composer loop.

decompose-feature

Use when the user wants to add a new feature, capability, or cluster of work to an existing active Piyaz project. Triggers: "add a feature for notifications", "decompose this idea into tasks", "I want to plan out the X subsystem", "extend the project with Y", "add Z to the project". Reuses the project's existing categories and tag vocabulary; creates 5 to 20 tasks plus internal edges and edges to existing project tasks. Does NOT change project status. Do NOT use for greenfield project decomposition (route to piyaz:decompose), for splitting an existing oversize task (route to piyaz:decompose-task), or for refining a single task (route to the piyaz skill directly).

decompose-task

Use when an existing task in an active Piyaz project carries scope larger than 13 points worth of work (composer's research brief raised the oversize-task flag, or the user explicitly says "split this task", "decompose RZE-42", "this task is too big", "break <taskRef> into smaller pieces"). Composer dispatches this from its oversize handler. Splits the parent into 2 to N child tasks, rewires every dependency edge touching the parent, and cancels the parent with rationale citing the children. Do NOT use for greenfield project decomposition (route to piyaz:decompose), for adding a new feature to an active project (route to piyaz:decompose-feature), or for refining a task without splitting it (route to the piyaz skill directly).

decompose

Use when a Piyaz project exists with a description but few or no tasks, and the user wants it broken into an implementable graph (project-level decomposition). Triggers: "decompose", "break this down", "create tasks", "turn this into tasks", "give me a task list", "plan out the work", "how should I build this". Do not use when no Piyaz project exists yet (route to brainstorm), the description is too thin to decompose responsibly (route back to brainstorm), the project already has a full task graph (route to manage), the user wants to split a single existing oversize task within an active project (route to piyaz:decompose-task), or the user wants to add a new feature to an active project (route to piyaz:decompose-feature).

manage

Use when the user explicitly wants a deep CTO-mode review of a Piyaz project. Triggers: "strategic review", "audit the project", "rebalance the graph", "what's the health of this project", "deep dive on the dependency graph", "I want a thorough navigation session", "prune orphans", "connect missing edges", "audit blockers", "consolidate categories or tags", "graph health check". Do not use for routine status / next-task / mark-done / refine; those are handled directly by the /piyaz skill.

onboarding

Use when the current repo has existing code but no Piyaz project that matches it, and the user wants to adopt Piyaz on day N. Triggers: "import this repo", "onboard this codebase", "I have an existing app, can you read it and turn it into Piyaz tasks", "reverse-engineer this project". Do not use when no code exists yet (route to brainstorm), a Piyaz project for this repo already exists (route to manage), or the user has a clean spec but no code (route to decompose).

review

Dispatched after a task lands at in_review to produce a structured CTO-grade verdict on the work and its PR. Two invocation paths: composer Phase 4 (orchestrator dispatches after the implementer's in_review write, surfaces the verdict to HOTL, stops), and direct mode from the piyaz skill on requests ("review VF-N", "review this PR", "review <PR URL>"). Reads piyaz_get lens='review' for the implementationPlan rendered alongside executionRecord, AC evaluation against executionRecord excerpts, downstream impact, and the PR handle from task.links filtered to kind='pull_request'; the PR diff is the source of truth for what changed, and tasks that ship deliverables instead of a PR are reviewed through their linked artifacts. Returns one of approve, request-changes, or block with file-cited reasoning across the security, performance, reliability, observability, and codebase standards lenses. Never auto-flips status; HOTL owns the in_review to done transition. Do not use for refinement, draft / planned review, style nits, or speculative scaling concerns outside the task's scope.

Last updated July 26, 2026