Brainstorm, Decompose, Manage

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: piyaz_analyze type='ready' surfaces unblocked tasks. If none are ready, type='plannable' finds drafts that need implementation plans.
Plan: Fetch depth='planning' context, write a detailed implementation plan, update the task to planned.
Implement: Claim the task (in_progress), fetch depth='agent' context, do the work.
Record: Mark done with executionRecord, decisions, and files.
Propagate: Check downstream tasks -- 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 context depth. 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

At the beginning of any session, the standard pattern is:

Select project: piyaz_project action='list' then action='select'.
Get overview: piyaz_query type='overview' to see the full state.
Find work: piyaz_analyze type='ready' to see what's actionable.

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: how to select a project and get oriented.
Find work: the ready → plannable → critical_path priority order.
Implement: claim → get agent context → work → record execution record, decisions, and files.
Plan: get planning context → write implementation plan → mark as planned.
Create: create task → add edges → verify.
Edge guidance: when to use depends_on vs relates_to, and the importance of edge notes.
Post-completion: check downstream tasks for needed updates after finishing work.

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. piyaz_analyze type='ready' returns nothing yet -- all tasks are drafts. type='plannable' returns "Define metrics schema" (it has a description and criteria).

An agent fetches depth='planning' context for that task, writes an implementation plan (specific table names, columns, index strategy), and marks it planned. Now type='ready' returns it.

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 requests depth='agent' context for it, 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.

Brainstorm, Decompose, Manage

On this page