Use Case: Spec Generation from Backlog

Complexity: Intermediate
Trigger: Jira issue moved to "Ready for Spec" status
Deliverable: Deliverable specification document, linked back to the Jira issue

Goal

Close the gap between a backlog item and an actionable specification. When a product or engineering manager moves a Jira issue into the "Ready for Spec" column, Xema automatically generates a full deliverable specification document — requirements, acceptance criteria, technical constraints — and links it back to the issue.

The team gets a structured starting point for implementation instead of a blank page.

Trigger

A Jira webhook fires when an issue transitions to status: "Ready for Spec". The connector-gateway-api normalises the event to a TrackerWebhookEvent.ISSUE_TRANSITIONED envelope and dispatches it to the workflow engine.

Steps

Step	Type	Description
`enrich`	Agent action	Fetches linked issues, Epic context, and comments from Jira
`generate-spec`	Agent action	Drafts the deliverable specification from the enriched context
`review-gate`	Human approval	Assignee or PM reviews and approves/rejects the draft
`link-back`	HTTP action	Attaches the final spec artifact URL to the Jira issue and transitions it to "Spec Ready"

Deliverables

deliverable-spec — A fully structured specification document including requirements, acceptance criteria, out-of-scope items, and technical notes. Stored as a versioned artifact.

Workflow YAML

yaml

1apiVersion: workflow/v1alpha1
2kind: Workflow
3metadata:
4  name: spec-from-backlog
5  version: "1.0.0"
6
7on:
8  webhook:
9    provider: jira
10    event: issue.transitioned
11    filters:
12      toStatus: "Ready for Spec"
13
14inputs:
15  issueKey:
16    type: string
17    source: "{{ event.issue.key }}"
18  issueSummary:
19    type: string
20    source: "{{ event.issue.fields.summary }}"
21  issueDescription:
22    type: string
23    source: "{{ event.issue.fields.description }}"
24  assigneeEmail:
25    type: string
26    source: "{{ event.issue.fields.assignee.emailAddress }}"
27
28jobs:
29  enrich:
30    action: [email protected]
31    input:
32      task: |
33        Retrieve all available context for Jira issue {{ inputs.issueKey }}:
34        - Parent Epic details and goals
35        - Linked issues (dependencies, blockers, related)
36        - Recent comments and decisions
37        - Labels and components
38        Summarise this context for use in spec generation.
39      context:
40        issueKey: "{{ inputs.issueKey }}"
41        summary: "{{ inputs.issueSummary }}"
42        description: "{{ inputs.issueDescription }}"
43    output:
44      artifactKey: enriched-context
45
46  generate-spec:
47    needs: [enrich]
48    action: [email protected]
49    input:
50      task: |
51        Using the backlog item context below, produce a complete deliverable specification.
52        Include:
53        - Problem statement and business goal
54        - Functional requirements (user-story format)
55        - Non-functional requirements (performance, security, accessibility)
56        - Acceptance criteria (checkboxes)
57        - Out-of-scope items
58        - Open questions
59        - Suggested technical approach (optional)
60      context:
61        issueContext: "{{ jobs.enrich.outputs.artifact.content }}"
62      deliverableSpec: deliverable-spec-v1
63    output:
64      artifactKey: deliverable-spec
65
66  review-gate:
67    needs: [generate-spec]
68    gate:
69      humanApproval:
70        assignees:
71          - "{{ inputs.assigneeEmail }}"
72        timeoutAction: escalate
73        timeoutHours: 48
74        message: |
75          A specification has been generated for {{ inputs.issueKey }}: {{ inputs.issueSummary }}.
76          Please review and approve or reject it.
77          Spec: {{ jobs.generate-spec.outputs.artifact.url }}
78
79  link-back:
80    needs: [review-gate]
81    action: [email protected]
82    input:
83      task: |
84        Attach the approved specification artifact to Jira issue {{ inputs.issueKey }},
85        add a comment with the artifact URL, and transition the issue to "Spec Ready".
86      context:
87        issueKey: "{{ inputs.issueKey }}"
88        artifactUrl: "{{ jobs.generate-spec.outputs.artifact.url }}"

Extending It

Slack notification — Add a step to notify the team channel when a spec is ready for review.
Multiple spec templates — Use the issue's component label to select between frontend-spec-v1, api-spec-v1, or infra-spec-v1.
Overlay customization — Apply team-specific overlays to the base deliverable-spec-v1 spec (e.g., add security-checklist requirements for the security team).
Linear support — Swap the jira webhook trigger for the Linear connector's tracker.issue.updated event and check the issue state in the payload, with the same workflow body. See Linear for the events and install steps.

Previous: ← Scheduled Security Audit
Next: Feature Lifecycle Pipeline →