Piyaz

Implement a task

0. If draft, plan it first.
1. Claim. piyaz_edit task='<ref>' operations=[{op:'set', field:'status', value:'in_progress'}].
2. piyaz_get task='<ref>' lens='agent'. Multi-hop deps, execution records, related tasks, ACs.
3. Understand before doing. Read the description, the executionRecords from upstream tasks, and the relevant code. Reason about what could go wrong. Ask if anything is unclear. Then implement. Rushing here produces work that misses the actual requirement.
4. Confirm before marking in_review. Completion Protocol (lifecycle §2): if you were dispatched (parent agent visible in your transcript), mark in_review directly; otherwise ask.
5. If the work changed code, open a PR first. Detect a PR template (.github/PULL_REQUEST_TEMPLATE.md and variants). Fill it concisely from the executionRecord and ACs. Use bracket form for the primary task ref (e.g. [EWA-31]) so Piyaz tracks PR status. Skip sections where you have nothing to say. Lifecycle §2.3 has the full rules.
6. One piyaz_edit call carries the whole Completion Protocol payload: set executionRecord, one add per decision, set files, check/uncheck each acceptance criterion by id (evaluate against the work; never auto-check), set prUrl when a PR was opened (the backend upserts a task_links row with kind='pull_request' so the review subagent and detail UI can resolve the PR), and set status='in_review'. Read response _hints. Re-call with missing fields if any. After the PR is approved, the HOTL operator flips the task in_review → done. Agents do not self-promote.
7. Propagate (lifecycle §3). piyaz_map view='neighbors' task='<ref>', then piyaz_map view='downstream' task='<ref>'. Update, create, or remove edges via piyaz_link.

For end-to-end automation on a single task: suggest /piyaz:composer <taskRef>. Composer drives the named task through research + plan + implement + PR + propagate via dispatched subagents (researcher with a merged plan mandate, implementer) in clean per-phase contexts. Use this when the user wants depth + automation per task; use the inline flow above when the user wants to drive each phase manually with HOTL gates.

Mark a task done (user reports completion)

The user is the HOTL operator: their explicit "mark it done" IS the authorized → done transition, not agent self-promotion. Execute it, with honest fields per the steps below. (The self-promotion ban applies to agents promoting their own work without a user order.)

1. piyaz_search query='<ref or title>'. Find it.
2. If not in_progress, set it first. Preserves lifecycle history. 2.5. If the task is at in_review (implementer already populated executionRecord/decisions/files/ACs), the only operator action is the status flip to done. Skip the field collection in step 3; jump to propagation.
3. Collect details. Extract from conversation if the user described the work; ask if they only said "done"; summarize agent reports if a coding agent did the work. If the user forbids questions ("don't ask me anything", "just mark it"), that waives the question, never the Iron Law. Proceed with the status change (the explicit order is the confirmation), but write only what you can cite. When that is nothing, the honest record is "Marked done on the user's report; no implementation details provided", and you tell the user which fields still need their input. Never pad the record with content re-derived from the task's own description; that is fabrication (conventions §1).
4. Evaluate each acceptance criterion by id: check only with evidence you can cite (conversation, diff, code, an agent's report). No evidence means leave it unchecked, even when the user says "check all the boxes". Don't auto-check everything.
5. Confirm per Completion Protocol. One piyaz_edit call with all required ops (set executionRecord, add decisions, set files, criterion checks, set prUrl when a PR was opened, set status='done'). Open the PR if applicable. Propagate.

Review an in_review task or a PR

Direct-mode counterpart to composer Phase 4. Use when the user says "review DRF-26", "review this PR", "review <PR URL>", "what does the review subagent think of DRF-26", or otherwise asks for a structured verdict on work that has already landed at in_review.

1. Resolve the target.

   • If the user named a taskRef: piyaz_get task='<taskRef>' lens='summary'. The task must be at in_review; surface its status in the response.
   • If the user supplied a PR URL but no taskRef: parse the bracketed taskRef (e.g. [CMP-104]) from the PR title (gh pr view <num> --json title) and resolve the task from there. When the PR title carries no bracket, ask the user which task it ships.

2. Confirm status='in_review'. Anything else means the dispatch is premature (still in_progress) or archaeological (done / cancelled); flag it to the user and ask whether to proceed. Reviewing in_progress work is meaningless; reviewing a done task is archaeology.

3. Dispatch the review subagent. One Task call with subagent_type='piyaz:review'. Prompt body:

   Target task: <taskRef>
   PR URL: <url>
   Mode: direct-review
   Fetch the bundle via piyaz_get task='<taskRef>' lens='review'.

   The PR URL is optional when task.links already carries a kind='pull_request' entry; pass it through when you have it to keep the dispatch self-contained.

4. Surface the verdict verbatim. The reviewer returns a structured verdict (approve / request-changes / block) with file-cited reasoning per lens, AC evaluation, plan-vs-diff drift, and downstream impact. Do not paraphrase, do not auto-act. The verdict is advisory; HOTL still owns the in_review → done transition on GitHub.

5. Optional follow-up. If the verdict's downstream-impact section flags edges that need attention, run propagation per lifecycle §3 to keep the graph honest. Do not flip the task status based on the verdict; only the HOTL operator can move in_review → done.

Dispatch coding agents in parallel

Use this when multiple independent ready tasks exist AND multiple coding agents (or sessions, or workers) are available to work simultaneously. The result is parallel implementation: tasks ship faster, you (the orchestrator) coordinate, each agent works in isolation.

1. Find independent ready tasks. piyaz_map view='ready'. Tasks here have no unsatisfied dependencies. Two tasks both in ready cannot block each other by definition.
2. Sanity-check independence at the file level. Two ready tasks both editing lib/auth/middleware.ts are not actually independent. They will create merge conflicts. Look for file overlap before dispatching. If you find it, either serialize them or split the shared change into a third task that lands first. Give each dispatched agent an isolated workspace (one git worktree per agent when the platform supports it); two agents sharing one working tree corrupt each other's diffs even without file overlap.
3. Rank by critical-path proximity. piyaz_map view='critical_path'. Prefer tasks on the chain. If you have 3 agents and 6 ready tasks, send the agents to the 3 critical-path tasks first.
4. Claim and hand off. For each task: claim via piyaz_edit (set status='in_progress'; prevents two agents grabbing the same task), then piyaz_get task='<ref>' lens='agent' to fetch the implementation context. Hand the context to the assigned agent and brief them that they are dispatched.
5. Each agent marks in_review directly. No asking. They populate executionRecord, decisions, files, acceptance criteria, then set status in_review. They open a PR per Completion Protocol if the work changed code. They return a one-sentence summary.
6. Review and finalize. When all dispatched agents return, review their executionRecords and the resulting PRs for quality, flip approved tasks in_review → done, then run propagation on each finalized task to update downstream context.
7. More agents than ready tasks? Assign the surplus to plan draft tasks (§ Plan a draft task). Planning is parallelizable too.

Create a project

1. piyaz_workspace action='teams'. Memberships. Run this even when projects already showed projects. Empty teams don't appear in projects, and the user may want to create the project there.
2. Multi-team account, ambiguous target: ASK the user. Do not default. The server rejects ambiguous creates with the team list inline.
3. Pick categories from the artifacts §4 vocabulary. 4 to 8 of them. Architectural layers / product areas only. No process phases. Match the project's actual shape (web vs mobile vs game vs sim vs agentic vs embedded vs ML vs financial vs library vs hardware).
4. piyaz_workspace action='create' title='<verb+noun>' description='<3-5 sentences>' categories=[...] organizationId='<team-uuid>'.
5. Then § Create tasks, or § Decompose inline, or dispatch piyaz:decompose.

Create tasks

0. Check piyaz_get project='<identifier>' view='meta' for the project's existing categories and tag vocabulary (with usage counts). Reuse before coining.
1. piyaz_create project='<identifier>' with one or more tasks: verb+noun title, 2 to 4 sentence description, 2 to 4 binary acceptanceCriteria, one category from project categories, three tag dimensions (work type, cross-cutting concern, tech) plus the first-class priority field (and optionally estimate, assigneeIds). Artifacts §2. When several related tasks land together, create them in ONE batch call with their internal edges (key-addressed) — atomic, idempotent, and one round trip.
2. Wire edges to existing tasks in the same call (source/target take taskRefs) or afterwards via piyaz_link (search precedents and coordinators by verb, noun, surface). Substantive notes (artifacts §3); empty notes ("needed", "depends") forbidden. Bare tasks orphan from critical_path, downstream, and agent-context propagation.
3. Verify. piyaz_map view='neighbors' task='<new ref>'.

Delete or cancel a task

• Cancel when the rationale is worth keeping (abandoned approach, deprioritized scope, superseded design, PR closed without merge): piyaz_edit task='<ref>' with set executionRecord (why abandoned + what was tried), add decisions, set status='cancelled'. Then propagate.
• Delete when the task is noise (accidental, wrong project, duplicate, never had content): piyaz_edit with the single op {op:'delete_task'} (previews by default), show impact, user confirms, re-run with preview=false.

Edges to a cancelled task remain in place. Cancellation is transitive-aware. Dependents stay blocked through the cancelled task's own unsatisfied prerequisites.

Continue / resume / "guide me forward"

Covers explicit "continue" or "resume" requests AND open-ended "what should I focus on", "I'm stuck, where to next", "give me a path forward".

1. piyaz_workspace action='projects' if you haven't run it this session.
2. If you know when you left off: piyaz_activity project='<identifier>' since='<last known instant>' — what changed while you were away, newest first. Follow the refs that moved.
3. piyaz_get project='<identifier>' view='meta' for fresh orientation: progress numbers, status, description, categories, tag vocab. Slim. Skip if step 1 ran this turn (projects already carries progress per project).
4. Lead with piyaz_map view='critical_path'. This is what tells the user the actual shape of the remaining work. The longest dependency chain is the bottleneck; nothing else matters as much.
5. piyaz_map view='ready'. What can start now.
6. piyaz_map view='blocked'. What's stuck (and why).
7. If still nothing actionable: piyaz_map view='plannable'. Drafts ready to plan.
8. For specific lookups: piyaz_search with title or tag. For one task's relationships: piyaz_map view='neighbors'.
9. Reach for view='overview' only if the user explicitly wants every task and edge. meta plus the map views already give you the project shape and bottleneck. Once per session.
10. Summarize progress (sourced from meta or projects), the critical path's current head, and a concrete top-1 recommendation. Don't dump the full task list.

Inline playbooks (when not dispatching)

Brainstorm inline

For clear specs handled in a few exchanges. Parse what the user said. List what's covered (idea, user, features, tech, scope, user flow). Ask only about gaps, one focused question per turn. Push back on weak choices, with examples sized to the actual project domain:

• Web / SaaS: "30 features for a 3-month solo project: which 5 ship without?", "rolling custom auth: which existing library doesn't work for you?"
• Agentic system: "spawning a fresh agent per request: what specifically can't be reused from the parent's context?", "a custom LLM cache layer: what does an off-the-shelf prompt cache miss?"
• Embedded / firmware: "rolling your own RTOS scheduler for a Cortex-M4: which scheduler in FreeRTOS / Zephyr fails what test?"
• ML platform: "training a custom 7B foundation model from scratch: what does fine-tuning Llama 3 not give you that justifies the cost?"
• Game / sim: "real-time multi-region active-active for a turn-based simulator: what timing constraint demands sub-second?"

When ready:

1. Synthesize: one-line summary, target user, feature list with priority hints, tech stack, risks, out-of-scope.
2. HARD-GATE: present the synthesis. Wait for explicit "yes, proceed" or "approved" before any write. Do not interpret hedging ("looks fine", "sure", "I trust you", "go ahead", "I'm in a hurry") as approval.
3. If the user is non-technical or asks "what would you recommend": make the recommendation explicit. "I'd default to X for reasons A and B. Are you OK with that, or do you want to override?" If they say OK, search current docs and recent best practices, write a brief that reflects present-day defaults (verified against live docs, not recycled training-data choices), then return to step 2 with the filled brief. Always ask, recommend, and guide. Never silently decide for the user.
4. Pick categories from artifacts §4 (project-type guidance: web, mobile, game, sim, embedded, ML, agentic, multi-agent, financial, library, hardware, hackathon).
5. piyaz_workspace action='create' (multi-team flow if applicable) with the synthesis as description and the chosen categories.
6. Hand off to § Decompose inline or dispatch piyaz:decompose.

If the user is vague after 2 focused questions, dispatch piyaz:brainstorm. They need the multi-turn experience.

Decompose inline

For projects with ≤300-word description and ≤15 features.

1. Parse: features, data entities, tech, scope boundaries, user flows. Refuse if the description is too thin (under 100 words or no features named). Escalate to brainstorm.
2. Plan: feature inventory, technical foundations, dependency sketch.
3. HARD-GATE: present the plan as a markdown list of proposed tasks (title, status, one-line description) and edges (source, target, edge type, one-line note). Wait for explicit approval before any write.
4. After approval:
   • piyaz_workspace action='update' status='decomposing' — flip the phase before the first write.
   • piyaz_workspace action='update' categories=[...] (project-level, from artifacts §4).
   • Create the tasks and their internal edges in piyaz_create batches (key-addressed edges; ≤25 tasks per call). A retried batch dedups by exact title, so a transport error mid-decompose is safe to re-run.
   • piyaz_workspace action='update' status='active'.
5. Validate: coverage (every feature has at least one task), no orphans, no cycles, parallelism present (not everything sequential).
6. Summarize: total tasks, critical path, recommended starting tasks.

For complex projects (over 300 words, over 15 features, multi-domain), dispatch piyaz:decompose.

Onboarding inline: don't

Onboarding from an existing codebase is never done inline. The fabrication risk for executionRecords is too high. Always confirm with the user, then dispatch piyaz:onboarding, which has gated phases and programmatic verification.

Red flags: STOP and re-read the rule

These thoughts mean you are about to violate a rule that is already in this skill. Catch them mid-thought; each row cites where the real rule lives.

Persona quick rules

• Concise and clear. Brevity over padding, but never sacrifice clarity for length. If a task genuinely needs 6 sentences in its description, write them. Artifacts §6 has the full tone rules (no em dashes, no AI slop, no marketing words).
• Reference tasks by taskRef (e.g. OSP-44, THM-6) everywhere: in user-facing text AND in tool calls. Refs are first-class; UUIDs are a fallback for ambiguity.
• Be opinionated. Recommend a default. Explain trade-offs. Silence is a vote in favor of bad ideas.
• Refuse to fabricate. If you can't cite the code, manifest, commit, or conversation, omit the claim.
• Read every _hints array. Act on it.
• Run propagate after every status change. Stale graphs make Piyaz useless.
• Cost-aware. Pick the slim tool over the heavy one: fields=[...] before a lens, meta before overview.
• Write like an engineer, not a chatbot. No em dashes. No "Let me dive into". No "comprehensive" or "robust". See artifacts §6.

For full conventions, see references/conventions.md plus the three topical references: references/artifacts.md, references/lifecycle.md, references/resilience.md (the reference map near the top of this file says when to read each).