Piyaz Docs

Piyaz structures project work into three phases. Each phase has a clear input, a clear output, and specialized tooling to move work forward.

The Three Phases

Brainstorm

Input: A rough idea or problem statement. Output: A refined project description with scope, constraints, and direction.

During brainstorming, you shape the idea through conversation. The goal is to clarify what you're building, who it's for, what the key technical constraints are, and what the first-pass scope looks like. The project starts in brainstorming status.

A good project description is 3-5 sentences covering: the problem, the user, the key features, the technical direction, and the constraints.

Decompose

Input: A refined project description. Output: A task graph with dependencies, acceptance criteria, and categories.

Decomposition breaks the project into concrete tasks, each with:

A title (verb + noun, e.g., "Add auth middleware").
A description (2-4 sentences: what to build, why it matters, key technical approach).
Acceptance criteria (2-4 testable done conditions).
Dependency edges connecting tasks into the right execution order.

Tasks start as draft. The project moves to decomposing status during this phase.

Good decomposition means each task is independently implementable once its dependencies are met. If a task requires knowing the internals of another task that hasn't been built yet, add a depends_on edge.

Manage

Input: A task graph. Output: Planned, implemented, and recorded tasks.

Management is the ongoing cycle of planning, implementing, and recording:

Find work: the ready set surfaces unblocked tasks. If none are ready, the plannable set finds drafts that need implementation plans, and the critical path shows the bottleneck chain to prioritize.
Plan: pull the task's planning context, write a detailed implementation plan, and mark the task planned.
Implement: claim the task (in_progress), pull its full agent context, and do the work.
Record: mark it done with an execution record, decisions, and the files touched.
Propagate: check the tasks downstream. Do their descriptions, edge notes, or dependencies need updating based on decisions made?

The project is active during this phase.

Project Status Lifecycle

The project itself tracks which phase it's in:

brainstorming → decomposing → active → archived

Status	Phase	What Happens
brainstorming	Brainstorm	Idea exploration and refinement.
decomposing	Decompose	Breaking into tasks and wiring dependencies.
active	Manage	Planning, implementing, and recording.
archived	Complete	All tasks done, project closed.

The Context Advantage

Each phase feeds the next with structured context:

Brainstorm → Decompose: The refined project description informs task breakdown. Agents decomposing the project see the full scope and constraints.
Decompose → Manage: Task descriptions, acceptance criteria, and dependency edges give planning agents everything they need to write implementation plans.
Manage → Manage: Execution records from completed tasks propagate to downstream tasks via the agent lens. Each successive task starts with full knowledge of what came before.

This is what makes Piyaz a network rather than a list. Every piece of recorded context feeds into the next step automatically, keeping agents effective across sessions without manual handoff.

The flow is not strictly linear. You can add new tasks during the manage phase, restructure dependencies, or revisit decomposition as you learn more. The graph adapts to how the project actually evolves.

Session Start

The server is stateless. There is no "active" project, so work is always named by its ref (PYZ, PYZ-42). At the beginning of any session, the standard pattern is:

Identify: confirm who you are and list every project you can reach.
Orient: read the project overview to see the full state (once per session, since it's the heavy read).
Find work: start from the critical path on resume, or the ready set for actionable tasks.

From there, the manage cycle takes over.

Auto-Loaded Instructions

The MCP server embeds workflow instructions that compatible clients (Claude Code, Codex, Cursor, Antigravity) receive automatically when they connect. These instructions encode the full session start, find work, implement, plan, and create patterns described above -- agents don't need to be taught the flow manually.

The instructions cover:

Session start: confirm identity and list projects to get oriented on a stateless server.
Find work: lead with the graph views (critical path, ready, plannable, blocked, downstream), and fall back to search for lookups.
Read: pick the lightest context lens (summary, working, agent, planning, review, record) that answers the question.
Implement: claim, pull the agent context, work, then record the execution record, decisions, and files.
Plan: pull the planning context, write the implementation plan, and mark the task planned.
Create: build a task and its dependency edges together in one atomic, idempotent step (up to 25 tasks at once).
Edge guidance: when to use depends_on vs relates_to, and why every edge needs a substantive note.
Post-completion: check the downstream tasks for needed updates after finishing work.
Resume: see what changed while you were away.

The server delivers this instructions block on connect; the MCP overview documents the same loop.

Example: Building a Metrics Dashboard

Here's a concrete walkthrough of the three phases applied to a real project.

1. Brainstorm

You describe the idea:

"I want to build a real-time dashboard for server metrics -- CPU, memory, disk. It should update every 5 seconds and support multiple servers."

The brainstorm agent shapes this into a project description: "Real-time server metrics dashboard. Displays CPU, memory, and disk usage for multiple servers with 5-second polling. Built with WebSocket push for live updates. PostgreSQL for metric storage, React frontend with charts."

The project is created with status brainstorming.

2. Decompose

The decompose agent breaks the project into tasks:

Define metrics schema -- PostgreSQL tables for servers and metric snapshots.
Build metrics collector -- Agent that polls servers and writes to the database. depends_on #1 (needs the schema).
Add WebSocket server -- Push new metrics to connected clients. depends_on #2 (needs the collector writing data).
Build dashboard UI -- React page with charts for CPU/memory/disk. depends_on #3 (needs the WebSocket feed).
Add server management -- CRUD for adding/removing monitored servers. relates_to #1 (shares the servers table but doesn't block).

All tasks start as draft. The project moves to decomposing.

3. Manage

The manage cycle begins. Nothing is ready yet, because all tasks are drafts. The plannable set returns "Define metrics schema" (it has a description and criteria).

An agent pulls that task's planning context, writes an implementation plan (specific table names, columns, index strategy), and marks it planned. Now it shows up as ready.

The agent claims it (in_progress), implements the schema, and marks it done with:

executionRecord: "Created servers and metric_snapshots tables in db/schema.ts. Snapshots use a composite index on (server_id, timestamp) for time-range queries. Added a server_status enum type."
decisions: "Composite index instead of partitioning -- simpler for the expected data volume."
files: db/schema.ts, db/migrations/001_metrics.sql

Now "Build metrics collector" becomes ready. When the agent pulls its full context, the response includes the schema task's execution record, so the agent knows the exact table names, column types, and index strategy without looking at the code.

The cycle continues: plan → implement → record → propagate, task by task, until the project is complete.

Last updated July 25, 2026

Brainstorm, Decompose, Manage