Context Network
How Piyaz builds and propagates context across tasks and sessions.
Context Network
A context network is a directed graph where tasks are nodes and edges represent dependencies or relationships between them. Unlike flat task lists, the network captures how work connects -- which tasks must finish before others can start, which tasks share context, and how decisions propagate downstream.
Every project in Piyaz is a context network. When you create tasks and connect them with edges, you're building a knowledge structure that agents can traverse to understand not just what to do, but why and how.
Why a DAG
Piyaz's task graph is a directed acyclic graph (DAG). Edges are directional (source → target) and cycles are rejected at creation time. This guarantees:
- Topological ordering -- there's always a valid execution sequence.
- Ready/blocked analysis -- a task is ready when all its
depends_ontargets are done. - Critical path computation -- the longest dependency chain identifies the project bottleneck.
- No circular deadlocks -- tasks can't form infinite dependency loops.
How It Composes
Three core tables compose the network (see lib/db/schema.ts):
| Table | Role | Key Fields |
|---|---|---|
| projects | Root container | title, description, status, categories, history |
| tasks | Work unit (node) | title, description, status, acceptanceCriteria, decisions, implementationPlan, executionRecord, files, tags, category |
| task_edges | Relationship (link) | sourceTaskId, targetTaskId, edgeType (depends_on or relates_to), note |
Tasks belong to a project. Edges connect tasks within the same project. (Acceptance criteria, decisions, and task links are stored in their own normalized tables but hang off a task.)
The note field on an edge explains why the relationship exists and propagates into downstream agent context via the agent and planning context depths.
Context Depths
The piyaz_context tool serves 5 depths, each shaped for a different stage of the workflow (see the depth descriptions in lib/mcp/create-server.ts and the renderer in lib/context/format.ts):
Summary
Task header, description, counts, and 1-hop edges with notes. The lightest read.
Working
Acceptance criteria, decisions, and 1-hop edges (both types, both directions). For refinement.
Agent
Multi-hop dependency closure with upstream execution records and PR links. For coding agents starting implementation.
Planning
Spec-focused: project description, prerequisites, criteria, downstream specs, and abandoned approaches. For writing implementation plans.
Review
The in_review bundle: implementation plan alongside execution record, PR link, AC evaluation, and review-lens prompts. For the review subagent.
Summary
The lightest read: the task header, description, edge counts grouped by type, full 1-hop edge details (connected task titles, statuses, and notes), and counts of acceptance criteria and decisions. It folds in what piyaz_query type='edges' would return -- no deeper graph walking.
Working
Returns acceptance criteria, decisions, and 1-hop edges (both depends_on and relates_to, in both directions, with notes). It does not render the execution record, files, or implementation plan -- it is the depth for refining a task's spec, not for reading its implementation. Used by the web UI's AI assistant during refinement.
Agent
Walks the effective depends_on closure (up to 2 hops, treating cancelled tasks as transparent) to build a multi-hop context document. The output is structured for LLM attention patterns (U-shaped recall -- start and end get the most attention):
- Start (highest recall): task title, tags, description, implementation plan.
- Middle (lowest recall): upstream prerequisites with their execution records (each with its PR link), edge notes, and decisions as constraints. A Blocked section appears when direct prerequisites are unfinished.
- End (second-highest recall): acceptance criteria, downstream dependents with edge notes.
Upstream execution records are included inline so the coding agent knows what was built, what was decided, and which prerequisites shipped (the linked PR diff is the source of truth for the files). For a done or cancelled task, the agent depth returns the retrospective record bundle (what the task was, the outcome, decisions, PR link) instead of the implementation shape -- read it before coding, and to read a finished task's record.
Planning
Gathers spec-focused context for writing an implementation plan: the project description for big-picture framing, the task spec (description, acceptance criteria, existing plan if any), prerequisites with their statuses and the execution records of done dependencies, downstream tasks with their specs, links, and abandoned approaches (the execution records of any cancelled dependencies, so the planner does not retread a dead end). The planner can't read the codebase -- it depends entirely on this context to write a concrete plan.
Review
The bundle the review subagent reads for an in_review task: the implementation plan rendered alongside the execution record, the PR link surfaced, the acceptance-criteria evaluation, downstream impact, and the review-lens prompts (security, performance, reliability, observability, codebase standards). The PR diff -- not this bundle -- is the artifact under review.
Always fetch context before reasoning about a task. The piyaz_context tool serves the right depth for each stage of the workflow.
Context Propagation
The network's real value is in propagation. When a task is marked done with an execution record, that record becomes available to every downstream task via the agent context depth. Edge notes travel the same path.
This means an agent implementing task C automatically receives:
- The execution records from tasks A and B (if C depends on them).
- The edge notes explaining why C depends on A and B.
- The acceptance criteria and constraints specific to C.
No manual briefing required. The context chain stays intact across sessions and across agents.