> ## Documentation Index
> Fetch the complete documentation index at: https://sdlc-rstack.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Stage 05 — Jira / Ticketing

> Ticketing agent. Converts sprint plans and requirements into Epic → User Story → Task tickets, pushed to a live tracker or written as importable files.

<Info>
  **File:** `agents/sdlc/05-jira.md` · **Model:** Sonnet · **Tools:** Bash, Read, Write
</Info>

## 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:

1. `.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)
2. `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.

<Note>
  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.
</Note>

## 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 |

```json theme={null}
// 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.

## Related

* [Agent 02 — Requirements](/sdlc-pipeline/requirements)
* [Agent 06 — Architecture](/sdlc-pipeline/architecture)
* [Pipeline overview](/sdlc-pipeline/overview)