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
Four database 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 |
| conversations | Chat history | projectId, taskId (optional), messages |
Tasks belong to a project. Edges connect tasks within the same project. A conversation can be project-level (no taskId) or task-scoped.
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
Piyaz provides 4 levels of context retrieval, each serving a different purpose:
Summary
Quick check: title, status, edge counts. Zero-hop traversal.
Working
Full task details with criteria, decisions, and 1-hop neighbors. ~4K tokens.
Agent
Multi-hop dependency chains with upstream execution records. For coding agents starting implementation.
Planning
Spec-focused: prerequisites, related work, acceptance criteria. For writing implementation plans.
Summary
Returns structured JSON with the task's title, status, description, edge counts grouped by type, full edge details (connected task titles, statuses, and notes), and counts of acceptance criteria and decisions. Zero-hop traversal -- no graph walking beyond direct edges. See lib/context/summary.ts for the implementation.
Working
Returns the full task object with all fields, plus 1-hop context: the parent project (ancestors), all connected tasks with edge types and notes, sibling tasks in the same project, and recent conversation history (last 10 messages). The output is formatted as structured markdown ordered by U-shaped attention. Used by the web UI's AI assistant during refinement and planning. See lib/context/working.ts for the implementation.
Agent
Follows depends_on edges recursively (up to 2 hops) 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, edge notes, and decisions as constraints.
- End (second-highest recall): acceptance criteria, files, own execution record (if done), downstream dependents with edge notes.
Upstream execution records are included inline so the coding agent knows what was built, what was decided, and which files were touched by prerequisite tasks. See lib/context/agent.ts for the implementation.
Planning
Gathers spec-focused context for writing an implementation plan. Starts with the project description for big-picture framing, then the task spec (description, acceptance criteria, existing plan if any), prerequisites with their statuses and execution records from done dependencies, decisions, and downstream tasks with descriptions. The planner can't read the codebase -- it depends entirely on this context to write a concrete plan. See lib/context/planning.ts for the implementation.
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.