Stage 05 — Jira / Ticketing

File: agents/sdlc/05-jira.md · Model: Sonnet · Tools: Bash, Read, Write

Purpose

The ticketing agent turns the sprint plan and requirements into a structured ticket hierarchy — Epic → User Story → Task — that a real sprint can execute without ambiguity. Its voice is explicit about the failure mode it exists to prevent: a vague acceptance criterion (“should work correctly”) that gets interpreted two ways and causes a rollback at 2am. Every user story it writes carries 3-5 Given/When/Then acceptance criteria, and every task has a single assignee role and an estimate.

Core principle

A ticket that can be interpreted two ways will be interpreted the wrong way at the worst possible time.

How it works

Inputs — the agent reads, in order:

$RSTACK_RUN_DIR/artifacts/planning/sprint_plan.json (from stage 04-planning)
$RSTACK_RUN_DIR/artifacts/requirements/requirement_spec.json (from stage 02-requirements)
$RSTACK_RUN_DIR/artifacts/environment_report.json (tool availability)

If sprint_plan.json or requirement_spec.json is missing, the agent stops and reports BLOCKED. Tool resolution is interactive and decision-cached. Before asking anything, it checks for a prior choice:

.rstack/integrations.json → ticketing.provider (plus base_url / project_key for Jira — endpoints and identifiers only; API tokens are always env vars, never written to this file)
environment_report.json → user_preferences.ticketing_platform, or a setup_needs entry with kind: "ticketing"

If either source names a platform, the agent uses it directly and does not re-ask. Otherwise it presents six options to the user: Jira Cloud, GitHub Issues, Azure DevOps, Linear, File-Based (always available, no credentials), or a dual “generate files + push to a platform” mode. Any live-platform failure mid-execution falls back to file-based automatically and the pipeline continues. Bidirectional sync. If a live platform is chosen, the agent checks whether the project already has tickets and offers to Merge (skip duplicates by >80% title match or linked requirement id), Replace, Supplement (only cover uncovered requirements), or Skip. Existing tickets are tagged "source": "existing_platform"; newly generated ones "source": "pipeline_generated". Ticket hierarchy:

Epic (1 per module)
  └── User Story (from each relevant actor's perspective)
        └── Task (Backend Dev | Frontend Dev | QA Engineer)

Each User Story carries Fibonacci story points (1, 2, 3, 5, 8, 13), a sprint assignment pulled from the sprint plan, and 3-5 acceptance criteria in GIVEN [context] WHEN [action] THEN [expected result] form.

This stage is skipped on adopted (brownfield) runs by design — tickets belong to new work, not to functionality that already exists. On a detected adopt run (manifest.json mode + adoption_report.json present), the agent creates tickets only for the change being made, and links to existing tracker tickets instead of duplicating them if bidirectional sync finds a matching project.

Outputs

Four files land under $RSTACK_RUN_DIR/artifacts/jira/:

File	Contents
`jira_tickets.json`	The machine-readable contract — epics, stories, tasks, summary counts
`jira_tickets_readable.md`	Human-readable rendering of the same hierarchy
`jira_import.csv`	Importable into Jira, Azure DevOps, Linear, or any tool later
`ticketing_report.md`	Which mode was used, live-push results, import instructions if file-based

// jira_tickets.json
{
  "contract_version": "1.0",
  "produced_by": "jira_agent",
  "summary": {
    "total_epics": 0,
    "total_stories": 0,
    "total_tasks": 0,
    "total_story_points": 0,
    "stories_per_sprint": {}
  },
  "epics": [
    {
      "epic_id": "EPIC-001",
      "epic_name": "<Module Name>",
      "user_stories": [
        {
          "story_id": "US-001",
          "title": "As a [role], I want to [action] so that [benefit]",
          "acceptance_criteria": [
            "GIVEN [context] WHEN [action] THEN [expected result]"
          ],
          "story_points": 5,
          "priority": "Critical|High|Medium|Low",
          "sprint": 1,
          "linked_requirements": ["FR-001"],
          "tasks": [
            {
              "task_id": "T-001",
              "assignee_role": "Backend Dev|Frontend Dev|QA Engineer",
              "estimated_hours": 8,
              "type": "development|testing|documentation"
            }
          ]
        }
      ]
    }
  ],
  "next_agent": "architecture_agent"
}

Quality self-check

Before reporting DONE, the agent verifies:

Every user story has 3+ Given/When/Then acceptance criteria
Every functional requirement is covered by at least one story
Every story is assigned to a sprint with story points

DONE_WITH_CONCERNS covers a partial API push or stories missing sprint assignment; BLOCKED means sprint_plan.json or requirement_spec.json is missing; NEEDS_CONTEXT asks one question about a ticketing platform credential or project key. After 3 failed calls to a live platform, the agent falls back to file-based rather than retrying indefinitely.

Where it sits in the pipeline

Stage 05 sits between 04-planning (sprint plan, story-point capacity) and 06-architecture. On completion it hands off directly by invoking the Architecture Agent with jira_tickets.json and requirement_spec.json as inputs — architecture reads the ticket hierarchy to scope its tech-stack and API-contract decisions per module.

Overview

Getting Started

Core Concepts

The Pipeline

Business Hub

Adapters

Security & Compliance

Roadmap & Research

Stage 05 — Jira / Ticketing

Purpose

Core principle

How it works

Outputs

Quality self-check

Where it sits in the pipeline

​Purpose

​Core principle

​How it works

​Outputs

​Quality self-check

​Where it sits in the pipeline

​Related

Purpose

Core principle

How it works

Outputs

Quality self-check

Where it sits in the pipeline

Related