Work Sessions

A work session is the execution context for implementing a ticket. Start, implement, complete — with full support for pausing, resuming, blocking, and validation at the end.

What Is a Work Session?

When an agent (or a human) begins implementing a ticket, a work session opens. It tracks everything that happens during implementation: which steps were completed, what files were created or modified, what was discovered along the way, and whether the final result passes validation.

A work session is scoped to a single ticket. One ticket, one session at a time. The session owns the implementation context — and when it closes, the ticket’s status changes ripple through the dependency graph.

Session Lifecycle

Start


start_work_session({ ticketId: "tkt_abc123" })

The ticket must be in ready status — all dependencies satisfied, no external blocks. Starting a session:

Transitions the ticket from ready to active
Returns the full ticket context: implementation steps, acceptance criteria, file expectations, dependency outputs, and any linked blueprints
If the parent specification is in ready state, it transitions to in_progress

The returned context is everything the agent needs to implement without asking questions. Steps describe concrete actions. Acceptance criteria define done. File expectations list what should be created or modified.

💡 The context returned by start_work_session is deliberately self-contained. An agent should be able to implement the ticket using only this context, without needing to query other tickets or read the full specification. This is what makes parallel execution safe — each worker operates in isolation.

Progress Tracking

During implementation, the agent reports progress through action_work_session:


{
  "ticketId": "tkt_abc123",
  "steps": [
    { "index": 0, "completed": true },
    { "index": 1, "completed": true }
  ],
  "files": [
    { "path": "src/auth/jwt.service.ts", "action": "created" },
    { "path": "src/auth/jwt.service.test.ts", "action": "created" }
  ],
  "notes": "Used jose library instead of jsonwebtoken for Edge Runtime compatibility."
}

Progress tracking is incremental. The agent can report as frequently or infrequently as it wants — after each step, after a batch, or all at once before completing. Each report updates the ticket’s state in the dashboard.

You can also report:

Acceptance criteria results — Mark individual criteria as met or not met with evidence
Test results — Submit test execution outcomes (pass/fail counts, specific failures)
Discovery — New information found during implementation that wasn’t in the original plan (e.g., an undocumented API behavior, a missing database column)

Pause

An agent can pause a work session without completing or abandoning it. This is useful when:

The agent’s context window is filling up and needs to compact
The developer wants to manually review progress before continuing
A related ticket needs attention first (but isn’t a formal dependency)
The work session spans multiple coding sessions across time

Pausing preserves all progress reported so far. Steps completed, files tracked, notes recorded — everything persists. The ticket remains in active status.

ℹ️ Pausing is implicit in practice. If the agent session ends (context window reset, developer closes terminal), the work session stays open. The next agent session can resume by calling start_work_session on the same ticket, which detects the existing session and continues from where it left off.

Resume

Resuming a paused session returns the ticket context plus all previously reported progress. The agent sees:

Which steps are already completed
Which files have already been created or modified
Any notes from the previous session
Remaining acceptance criteria to satisfy

This means an agent can pick up exactly where the previous agent (or the same agent in a new session) left off. No duplicated work, no lost context.

Block

During implementation, an agent may discover an external blocker — something outside the ticket’s scope that prevents completion. Report it:


{
  "ticketId": "tkt_abc123",
  "blockReason": "The user_accounts table doesn't have a last_login_at column. Ticket tkt_def456 should create this migration but isn't in the current specification."
}

Reporting a block reason forces the ticket back to pending status regardless of dependency state. The block appears in the dashboard and in get_blocked_tickets results. The block reason is visible to the orchestrator, other agents, and humans monitoring the dashboard.

To unblock, the block reason must be cleared — either manually from the webapp or by the agent resolving the issue and calling action_work_session without a blockReason.

⚠️ Blocking is for external issues only — things that can’t be resolved within the ticket’s scope. If a ticket’s own steps are harder than expected, that’s not a block. If the ticket depends on something that doesn’t exist yet and wasn’t captured as a dependency, that’s a block.

Complete


{
  "ticketId": "tkt_abc123",
  "summary": "Implemented JWT token generation service with RS256 signing and configurable expiration. All tests passing.",
  "actualHours": 1.5,
  "validation": {
    "tests": true,
    "lint": true,
    "typeCheck": true,
    "build": true
  }
}

Completing a session:

Transitions the ticket from active to done
Records the summary, actual hours, and validation results
Triggers cascade recalculation (see below)

The summary is important — it’s what appears in reports and what reviewers see during Implementation Review. A good summary describes what was built, any deviations from the plan, and why.

Validation results (tests, lint, typeCheck, build) are optional but feed into the Implementation Review scoring. If your project requires test evidence, submitting validation here saves a review round-trip.

Cascade Effects

This is where work sessions connect to the broader system. When a ticket completes, three things happen automatically:

1. Dependent Tickets Unlock

Every ticket that lists the completed ticket in its dependsOn array is recalculated. If all of its dependencies are now done, it transitions from pending to ready — immediately available for the next agent to pick up.

This is how waves work. Wave 1 tickets have no dependencies and start as ready. When Wave 1 completes, Wave 2 tickets unlock. When Wave 2 completes, Wave 3 unlocks. The dependency graph drives the entire execution flow.

2. Epic Auto-Completion

When every ticket within an epic reaches done, the epic is automatically marked as completed. No manual action required.

3. Specification Advances

When the last epic in a specification completes (all tickets in all epics are done), the specification transitions to ready_for_review — or directly to completed if Implementation Review is disabled in your project’s Quality Standards.

This is the full chain: ticket completes → dependents unlock → epic auto-completes → specification advances to review. One complete_work_session call can trigger all of this.

Reset

Completed tickets can be reset back to a workable state:


{
  "specificationId": "spec_xyz789",
  "ticketIds": ["tkt_abc123", "tkt_def456"]
}

Reset clears session data (step completions, notes, acceptance criteria results) but preserves linked commits and pull requests. The ticket recalculates to pending or ready based on its current dependency state.

⚠️ Resetting cascades downward. If ticket B depends on ticket A and you reset ticket A, ticket B also reverts to pending — even if it was ready or done. The dependency graph is always consistent.

Work Sessions and Agent Teams

In autonomous implementation with Agent Teams, work sessions are the atomic unit of work distribution:

The orchestrator calls get_next_actionable_tickets to find tickets with all dependencies satisfied
It assigns tickets to workers by having each worker call start_work_session
Each worker implements its ticket, reports progress, and calls complete_work_session
The validator checks the completed work against acceptance criteria
The cascade unlocks the next wave of tickets
The orchestrator assigns the newly unlocked tickets to available workers
Repeat until all tickets are done

The work session ensures each worker operates in isolation with its own context. No shared state between workers. No file conflicts (the dependency graph prevents two workers from touching the same area simultaneously). No coordination overhead beyond the graph itself.