Context Network
How Piyaz builds and propagates context across tasks and sessions.
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 lenses.
Context Lenses
Piyaz reads one task through a lens: a task-shaped view sized for the job at hand, so you never pull the whole project to answer a narrow question. There are six lenses, each shaped for a different stage of the workflow (see the lens 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 with edges.
Working
Acceptance criteria, decisions, and links WITH their item ids (the edit-address read), plus 1-hop edges. For refinement and surgical edits.
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.
Record
The retrospective bundle: outcome, decisions, and PR link for a done or cancelled task.
Summary
The lightest read that still carries edges: 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 does no deeper graph walking.
Working
Returns acceptance criteria, decisions, and links with their item ids, plus 1-hop edges (both depends_on and relates_to, in both directions, with notes). The ids are the edit addresses: an edit targets a specific criterion, decision, or link by the id this lens surfaces. It does not render the execution record, files, or implementation plan. This is the lens 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 lens returns the retrospective record bundle (what the task was, the outcome, decisions, PR link) instead of the implementation shape. Read it before coding. The dedicated record lens returns that same retrospective for any finished task.
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.
Record
The retrospective bundle for a done or cancelled task: the outcome (execution record), the decisions with their rationale, and the PR link. Read it to learn what a finished task actually shipped without reopening its implementation shape. The agent lens returns this same bundle automatically when the task it points at is already finished.
Always fetch context before reasoning about a task. Piyaz serves the right lens for each stage of the workflow, so pick the lightest one that answers the question.
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 lens. 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.
Last updated