Ticket Workflow

Ticket Workflow

Overview

The ticket workflow drives an autonomous agent through 10 phases from ticket intake to production validation. Each phase is defined by a promptlet -- a markdown template that specifies what agents to spawn, how they coordinate, and what they produce.

Phases

#	Phase	Key	Session Boundary
1	Intake	intake	no
2	Planning	planning	YES - human reviews plan
3	Implementation	implementation	no
4	Verification	verification	no
5	PR Creation	pr-creation	no
6	CI + Review Loop	ci-review-loop	YES - if 3 fix attempts fail
7	Human Merge Gate	human-merge-gate	YES - always
8	Deploy Watch	deploy-watch	YES - conditional
9	Production Validation	production-validation	no
10	Completion	completion	no

Phase Transitions

• Phases execute sequentially from 1 to 10
• The orchestrator (main session) reads the promptlet for the current phase, spawns agents as specified, collects results, updates state, and transitions to the next phase
• Session boundaries cause the agent to save state and stop. Human resumes with /ticket <id>
• The agent NEVER auto-merges. Phase 7 (human-merge-gate) always requires human action

Promptlet Resolution

Two-tier resolution, project-local overrides defaults:

1. Project-local: .claude/ticket-agent/promptlets/<phase>.md
2. Plugin default: ${CLAUDE_PLUGIN_ROOT}/skills/ticket-workflow/resources/promptlets/<phase>.md

If a project-local promptlet exists, use it (it already contains project-specific knowledge from /ticket-learn). Otherwise, fall back to the generic default.

State Management

State is stored at .claude/ticket-agent/state/<ticket-id>.json in the target project. The state file is immutable-write (full replace each time). It tracks:

• ticket_id: The ticket identifier
• current_phase: Which phase the ticket is in
• branch_name: The VCS branch (created during implementation)
• pr_number and pr_url: PR details (set during pr-creation)
• phases: Per-phase status and data

VCS

All VCS operations use jj by default. Projects using git can override via learned promptlets.

Agent Topology

All sub-agents are general-purpose type. The promptlet defines:

• Which agents to spawn and their instructions
• Whether agents work in parallel or sequentially
• What each agent reports back
• How failures are handled

The /ticket command in the main session IS the orchestrator. Sub-agents cannot spawn sub-agents.

CRITICAL ORCHESTRATOR RULE: The orchestrator MUST delegate work to sub-agents as defined by each promptlet. During phases that define agents (especially implementation), the orchestrator MUST NOT directly use Edit, Write, Grep, or Bash tools for code changes. It should only use tools for state management (reading/writing state files) and spawning agents. Each promptlet's agent templates contain literal prompt text — the orchestrator fills in values from state data and passes the constructed prompt to the Agent tool. If a promptlet defines per-component agents, the orchestrator iterates over the components array and spawns one agent per component.

Session Boundaries

The agent saves state and ends at these natural breakpoints:

• After planning phase (human reviews plan before coding starts)
• After CI failures exhaust 3 fix attempts
• At human merge gate (human must merge the PR)
• When waiting for deploy to complete

CI + Review Monitoring Loop

After the PR is created, the ci-review-loop phase forms a continuous monitoring loop:

1. Push the PR
2. Poll CI status and PR comments in parallel
3. If CI fails -> analyze, fix, push (restarts CI check)
4. If review comments arrive -> address them, push
5. Loop exits when: CI green AND PR approved (or no outstanding comments)
6. Max 3 CI fix attempts before session boundary

Resources

Reference documents for this workflow:

• resources/phase-reference.md - Detailed phase definitions and transition rules
• resources/promptlet-format.md - How to write and customize promptlets
• Default promptlets in resources/promptlets/ - Generic implementations for each phase