The Workbook

The workbook is the working memory of a feature — the structured record of what's been decided, what's pending, what's been verified, and what's still open. PRDs and TRDs describe what should happen; the workbook records what's actually happening as the feature gets built.

In the feature stepper it's labeled Agent Context (third stage, between Technical Requirements and Validation) because that's the role it plays at runtime: every Dezycro-aware AI agent — Claude Code, the Companion, the verifier — reads the workbook to ground its next action. When the docs talk about "the workbook" or "the agent context," they're the same thing.

Who writes the workbook

Mostly the agent. In a typical Claude-Code-driven session:

• Companion (background) sweeps the conversation when something material happens and records decisions / issues / assumptions before they get lost. It's trigger-based and silent by default — entries land in the workbook without the developer having to step out of flow.
• /dezycro:sync lets the developer say "checkpoint this" explicitly — Companion reviews the recent edits, opens the right tasks/issues, and links the commits.
• /dezycro:verify writes journey results, coverage gaps, and run history.
• Test generation writes journeys and intent links.

The human edits the workbook directly only for sharper-than-the-agent-knows nuance: marking an assumption invalidated, raising the severity on an issue, or promoting a journey from OBSERVED to ENFORCED.

This is why the workbook reads less like a doc and more like a database: it's curated by software for software, with human spot-corrections.

What's in it

The workbook surfaces split into eight sub-views in the UI. Each one is a typed log of a different kind of entry:

Sub-view	What lives there
Overview	A roll-up: open issues, blocking journeys, recent decisions, latest verifier run
Journeys	Generated test journeys + their ENFORCED / OBSERVED state and last status
Tasks	Discrete units of work an engineer (human or agent) is responsible for
Issues	Bugs, blockers, dev problems with severity and resolution status
Decisions	Committed technical / product choices worth preserving
Verify	Triggers a verifier run and shows the result inline
Coverage	Per-intent / per-endpoint coverage map — what's tested vs what's just speced
Audit	Append-only log of every mutation, with timestamp and actor

Journeys

A journey is a sequence of API calls that exercises a user-facing behavior end-to-end. Generated from the PRD (one journey per user story / acceptance criterion) and the OpenAPI spec, then run by the verifier on demand or in CI.

Each journey has:

• A name + description
• A linked PRD intent (the source statement) — used by the coverage report to map "did we test what the PRD promised?"
• An ordered list of steps (HTTP calls + assertions)
• An enforcement state — ENFORCED (failure blocks the feature lifecycle from advancing) or OBSERVED (logged but non-blocking — useful for nice-to-haves or in-progress journeys)
• A status — PASS / FAIL / INCONCLUSIVE / UNTESTED

Tasks

A task is a unit of work an engineer (human or agent) is responsible for. Each one has:

• A status: TODO → IN_PROGRESS → DONE → PUSHED → CONFIRMED
• Optional pathRefs — files in the codebase the task touches. The Companion verify gate uses these to block transitions to DONE or PUSHED without recent passing verifier evidence.
• Optional links to journeys, decisions, or issues

Tasks describe work. They're the smallest planning unit.

Decisions

A decision is a committed technical or product choice worth preserving:

"We chose Postgres over MySQL because the existing platform already uses Postgres."

Decisions have a summary, a rationale, and optional refs back to the journeys / intents they affect. They stay forever — they aren't "completed." If a decision turns out wrong, mark it INVALIDATED instead of deleting; the audit trail matters more than tidiness.

Issues

An issue is a current problem — a bug, a blocker, a flake — with a severity (BLOCKER / MAJOR / MINOR) and a status (OPEN / IN_PROGRESS / RESOLVED / CANCELLED).

Issue vs task: an issue describes the problem; a task describes the work to fix it. Most fixes get both — one issue plus one task that links to it. The issue is what the verifier and coverage report read; the task is what shows up on someone's plate.

Assumptions

An assumption is a working belief that affects implementation but isn't verified:

"We're assuming the upstream API returns ISO-8601 timestamps."

Recording assumptions explicitly is what stops them from silently becoming bugs. When an assumption turns out wrong, mark it INVALIDATED and (usually) open a corresponding issue.

Companion logs assumptions whenever the developer says "I think…" / "I'm pretty sure…" / "this should be the case" in a way that affects code paths.

Blockers & required paths

Some features can't be fully verified until something external is in place — a Stripe webhook subscribed, an OAuth callback configured, a third-party fixture loaded. The workbook records these as blockers: explicit prerequisites that must be satisfied before the verifier can run end-to-end.

A feature with OPEN BLOCKER issues can't auto-advance to VERIFIED, even if all its journeys pass — the agent knows it isn't actually proven.

Lifecycle stages

Each feature progresses through stages, driven by the workbook's contents:

DRAFT → IN_PROGRESS → VERIFIED → RELEASED

Stage	Meaning
DRAFT	PRD/TRD being written; workbook mostly empty
IN_PROGRESS	Implementation underway; some journeys may pass, tasks moving
VERIFIED	All ENFORCED journeys pass, no OPEN BLOCKER issues, all journey-linked tasks are PUSHED
RELEASED	Feature is live; PRD/TRD locked from edits, workbook becomes append-only

Transitions are automatic where possible. As soon as the verifier reports all enforced journeys passing and the relevant tasks have reached PUSHED, the feature auto-moves to VERIFIED. RELEASED is the only stage that's a deliberate human action — and is reversible only by explicit demotion.

If you want to know why a feature is stuck on a stage, the Overview sub-view tells you exactly which gate hasn't been satisfied.

Documents on a feature

Each feature also carries two human-readable documents alongside the workbook:

Type	Purpose
PRD	Product Requirement Document — user stories, acceptance criteria, pillars
TRD	Technical Requirement Document — architecture, data model, API contracts, failure modes, migration, open questions

All three (PRD + TRD + workbook) are auto-created when you call create_feature. The documents start in DRAFT and the authoring flow walks them to COMPLETE → APPROVED. Once approved, edits create new revisions rather than mutating the existing version.

How agents use the workbook

This is the part that most differentiates Dezycro from a doc tool: the workbook is structured exactly so that an agent can ground itself in seconds.

When /dezycro:work <feature> starts a session, the plugin loads the entire workbook (overview + open issues + recent decisions + journeys + last verifier run) into the agent's context. The agent then reads:

• the PRD to learn what should happen,
• the TRD to learn how it's built,
• the workbook to learn what's already been decided, what's broken right now, and what's been verified so far.

That last category is what makes the difference between an agent that hallucinates and an agent that progresses. The PRD/TRD are aspirational; the workbook is current truth.

When the agent then does work — implements something, runs the verifier, hits a snag — it writes back:

• Decisions it made (via add_decision)
• Issues it found (via add_issue)
• Assumptions it relied on (via add_assumption)
• Tasks it completed (via update_task)

Either explicitly (the developer typed /dezycro:sync) or implicitly (Companion noticed something worth recording).

Editing the workbook

Three ways, all writing to the same store:

1. Web UI — app.dezycro.ai → feature page → workbook sub-views. Canonical surface; every other path's mutations appear here in real time.
2. MCP — add_decision, add_issue, add_assumption, update_task, create_task, link_artifact, etc. (see MCP server).
3. Claude Code plugin — Companion auto-logs during a session; /dezycro:sync does the explicit checkpoint; /dezycro:verify writes run results. (See Companion and slash commands.)

All three paths share the same audit log — the Audit sub-view shows every mutation with timestamp and actor (which user / which agent / which automation).

What the workbook is for

The workbook exists because PRDs and TRDs alone aren't enough to verify a feature is correctly built. A PRD says what should happen; the workbook records what was decided, what was assumed, what was actually tested, and what's still open.

It's also what makes Dezycro safe to leave an agent unattended on. Because every mutation is logged, every assumption is explicit, and every gate to VERIFIED is mechanical, you can audit what the agent did after the fact — and you can tell whether it actually finished or just thinks it did.

The verifier consumes the workbook (specifically the journeys + their enforcement state + their linked intents) to produce a coverage report. Coverage gaps surface in the workbook itself — which means the next person (or agent) to work on the feature sees the current truth, not a stale spec.