piyaz

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).

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).

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).

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).

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.

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).

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.