Add Jira bridge workflow

CHANGELOG.md

@@ -6,6 +6,13 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [1.3.0] — 2026-05-18
+
+### Added
+- Jira bridge commands for pulling Jira issues into local specs, attaching approved artifacts, and
+  creating Jira subtasks from `tasks.md`.
+- Jira integration docs and tutorial for enterprise intake workflows.
+
 ### Changed
 - Clarified README and tutorial command examples so one-off `uvx` usage is not mixed with direct
   `dbt-specify` commands unless the CLI is persistently installed.

README.md

@@ -40,6 +40,7 @@ become clear.
 | Agent knowledge | Use dbt Labs skills for dbt mechanics. Use dbt-spec-kit skills and sub-agent roles for business meaning, planning, governance, and review evidence. | [Skills and sub-agents](docs/skills-and-sub-agents.md) |
 | Warehouse guidance | Pick the closest warehouse preset for cost, materialization, SQL dialect, and governance guardrails. The project still runs through your normal dbt adapter and database connection. | [Warehouse guides](docs/warehouse-guides) |
 | CI evidence | Start with local `validate` and `report`; promote `dbt-specify ci` when the team wants lifecycle checks to block PRs. | [Enterprise CI](docs/enterprise-ci.md) |
+| Jira integration | Pull Jira issues into local specs, attach approved specs/plans back to Jira, and create Jira subtasks from `tasks.md`. | [Jira integration](docs/integrations/jira.md) |
 
 The key repo hygiene rule: keep approved decision records, not raw agent scratch work.
 
@@ -172,6 +173,26 @@ If you did not install the CLI persistently, run the `dbt-specify` commands abov
 
 Use `dbt-specify ci` when the lifecycle and dbt artifact checks should block a PR.
 
+## Jira bridge
+
+For teams that use Jira as the intake system:
+
+```bash
+export JIRA_BASE_URL="https://your-company.atlassian.net"
+export JIRA_EMAIL="you@company.com"
+export JIRA_API_TOKEN="<atlassian-api-token>"
+
+uvx --from dbt-spec-kit dbt-specify jira pull NBA-123
+uvx --from dbt-spec-kit dbt-specify jira attach NBA-123 \
+  --spec specs/001-nba-123-player-journey/spec.md \
+  --plan specs/001-nba-123-player-journey/plan.md
+uvx --from dbt-spec-kit dbt-specify jira create-tasks NBA-123 \
+  --from specs/001-nba-123-player-journey/tasks.md
+```
+
+Jira remains intake and tracking. `spec.md` and `plan.md` remain the approved engineering contract.
+See [Jira integration](docs/integrations/jira.md).
+
 ## Who this is for
 
 - Analytics engineers who want AI help without losing dbt conventions.
@@ -189,6 +210,7 @@ Use `dbt-specify ci` when the lifecycle and dbt artifact checks should block a P
 - [Spec retention and repo hygiene](docs/spec-retention-and-repo-hygiene.md)
 - [Skills and sub-agents](docs/skills-and-sub-agents.md)
 - [Enterprise CI](docs/enterprise-ci.md)
+- [Jira integration](docs/integrations/jira.md)
 - [Brownfield onboarding](docs/brownfield-onboarding.md)
 - [EARS cheatsheet](docs/ears-cheatsheet.md)
 - [Releasing to PyPI](docs/releasing.md)

docs/integrations/jira.md

@@ -0,0 +1,130 @@
+# Jira integration
+
+The Jira bridge lets enterprise teams keep Jira as the intake and tracking system while keeping
+`spec.md`, `plan.md`, and `tasks.md` as the local engineering contract.
+
+```text
+Jira story -> spec.md -> plan.md -> tasks.md -> Jira attachments/subtasks -> PR evidence
+```
+
+Jira does not replace the dbt-spec-kit workflow. It provides source context and receives approved
+artifacts after review.
+
+## Authentication
+
+Set these environment variables before running Jira commands:
+
+```bash
+export JIRA_BASE_URL="https://your-company.atlassian.net"
+export JIRA_EMAIL="you@company.com"
+export JIRA_API_TOKEN="<atlassian-api-token>"
+```
+
+Do not commit these values. Use local shell secrets or CI secrets.
+
+## Pull a Jira story into a spec
+
+Run from the dbt project root:
+
+```bash
+uvx --from dbt-spec-kit dbt-specify jira pull NBA-123
+```
+
+This creates:
+
+```text
+specs/001-nba-123-player-journey/
+  jira.yml
+  spec.md
+```
+
+`jira.yml` records the Jira issue key, URL, project key, local spec directory, and last sync time.
+`spec.md` is a draft. A human or AI agent should refine the business meaning, acceptance criteria,
+grain, downstream consumers, and open questions before the plan phase.
+
+## Plan and task locally
+
+Use the normal agent workflow:
+
+```text
+/dbt.plan
+/dbt.tasks
+```
+
+Review and approve `spec.md` before planning. Review and approve `plan.md` before implementation.
+
+## Attach approved artifacts to Jira
+
+Attach the approved spec and plan:
+
+```bash
+uvx --from dbt-spec-kit dbt-specify jira attach NBA-123 \
+  --spec specs/001-nba-123-player-journey/spec.md \
+  --plan specs/001-nba-123-player-journey/plan.md
+```
+
+The command uploads each file to the Jira issue and adds a short comment listing the attached
+artifacts. Add `--no-comment` when an automation or PR comment already summarizes the evidence.
+
+## Create Jira subtasks from tasks.md
+
+After tasks are approved:
+
+```bash
+uvx --from dbt-spec-kit dbt-specify jira create-tasks NBA-123 \
+  --from specs/001-nba-123-player-journey/tasks.md
+```
+
+Each unchecked task becomes a Jira subtask with a summary like:
+
+```text
+[dbt-specify T-01] Add player journey mart. AC: AC1, AC2.
+```
+
+The prefix keeps sync idempotent. If the command sees an existing child issue with the same
+`[dbt-specify T-01]` prefix, it skips that task instead of creating a duplicate.
+
+Use `--dry-run` to preview:
+
+```bash
+uvx --from dbt-spec-kit dbt-specify jira create-tasks NBA-123 \
+  --from specs/001-nba-123-player-journey/tasks.md \
+  --dry-run
+```
+
+If your Jira site uses a different subtask type name, pass it explicitly:
+
+```bash
+uvx --from dbt-spec-kit dbt-specify jira create-tasks NBA-123 \
+  --from specs/001-nba-123-player-journey/tasks.md \
+  --issue-type "Subtask"
+```
+
+## Sync a spec directory
+
+For the common case, sync the directory:
+
+```bash
+uvx --from dbt-spec-kit dbt-specify jira sync NBA-123 \
+  --spec-dir specs/001-nba-123-player-journey
+```
+
+This attaches `spec.md` and `plan.md` when they exist, then creates missing Jira subtasks from
+`tasks.md`.
+
+## Recommended enterprise policy
+
+- Pull Jira context into a spec branch, not directly into `main`.
+- Attach only reviewed or approved `spec.md` and `plan.md`; avoid publishing raw agent drafts.
+- Create Jira subtasks after `tasks.md` is approved.
+- Keep the PR as the merge gate. Jira status alone does not approve dbt code.
+- Store Jira credentials in environment variables or CI secrets only.
+- Use `jira sync --dry-run` before the first production rollout.
+
+## Troubleshooting
+
+- `Missing Jira environment variable`: set `JIRA_BASE_URL`, `JIRA_EMAIL`, and `JIRA_API_TOKEN`.
+- `Jira API request failed with HTTP 401`: check the email/token pair and site URL.
+- `Jira API request failed with HTTP 403`: confirm the account can browse the issue, add
+  attachments, create issues, and create subtasks in the project.
+- Duplicate subtasks: check whether existing child issues use the `[dbt-specify T-XX]` prefix.

docs/tutorials/05-jira-to-spec-workflow.md

@@ -0,0 +1,100 @@
+# Tutorial 5: Jira to spec workflow
+
+This tutorial shows the enterprise intake path: start from a Jira story, generate a local
+dbt-spec-kit spec, approve the plan, and publish approved artifacts back to Jira.
+
+## 1. Configure Jira credentials
+
+```bash
+export JIRA_BASE_URL="https://your-company.atlassian.net"
+export JIRA_EMAIL="you@company.com"
+export JIRA_API_TOKEN="<atlassian-api-token>"
+```
+
+Use a local shell profile or secret manager. Do not write tokens into the repo.
+
+## 2. Pull the Jira issue
+
+Run from the dbt project root:
+
+```bash
+uvx --from dbt-spec-kit dbt-specify jira pull NBA-123
+```
+
+Expected output:
+
+```text
+created specs/001-nba-123-player-journey/spec.md
+created specs/001-nba-123-player-journey/jira.yml
+```
+
+Review `spec.md`. The generated file is a draft from Jira context, not an approved contract.
+
+## 3. Refine the spec with an agent
+
+Ask your agent:
+
+```text
+Read specs/001-nba-123-player-journey/spec.md and the current dbt project.
+Refine the spec into clear business meaning, grain, downstream consumers, and EARS acceptance
+criteria. Do not edit SQL or YAML models.
+```
+
+Approve `spec.md` before moving on.
+
+## 4. Plan and tasks
+
+Use the normal workflow:
+
+```text
+/dbt.plan
+/dbt.tasks
+```
+
+Approve `plan.md` before implementation. Approve `tasks.md` before creating Jira subtasks.
+
+## 5. Attach spec and plan to Jira
+
+```bash
+uvx --from dbt-spec-kit dbt-specify jira attach NBA-123 \
+  --spec specs/001-nba-123-player-journey/spec.md \
+  --plan specs/001-nba-123-player-journey/plan.md
+```
+
+## 6. Create Jira subtasks
+
+```bash
+uvx --from dbt-spec-kit dbt-specify jira create-tasks NBA-123 \
+  --from specs/001-nba-123-player-journey/tasks.md
+```
+
+For a first rollout, preview first:
+
+```bash
+uvx --from dbt-spec-kit dbt-specify jira create-tasks NBA-123 \
+  --from specs/001-nba-123-player-journey/tasks.md \
+  --dry-run
+```
+
+## 7. Implement and review
+
+Implementation remains local and PR-driven:
+
+```text
+/dbt.implement
+/dbt.review
+```
+
+After validation, attach final evidence if your team requires it:
+
+```bash
+uvx --from dbt-spec-kit dbt-specify report --format markdown > dbt-specify-report.md
+uvx --from dbt-spec-kit dbt-specify jira attach NBA-123 --file dbt-specify-report.md
+```
+
+## Success criteria
+
+- Jira story context is captured in `jira.yml` and `spec.md`.
+- The approved spec and plan are attached to the Jira issue.
+- Jira subtasks match `tasks.md` and do not duplicate on reruns.
+- The PR remains the merge gate for dbt code.

docs/tutorials/README.md

@@ -10,6 +10,7 @@ Use them in order when onboarding a team:
 | [2. Ship a jaffle-shop change](02-jaffle-shop-change.md) | 25 min | Analytics engineers and reviewers | Walk a real dbt feature from business request to review evidence |
 | [3. Adopt in a brownfield enterprise repo](03-brownfield-enterprise-adoption.md) | 30 min | Data platform leads | Roll out the workflow without rewriting production models |
 | [4. Run skills and sub-agent handoffs](04-skills-and-sub-agent-handoffs.md) | 20 min | Teams using AI agents | Decide when to use skills, sub-agents, and human approval gates |
+| [5. Jira to spec workflow](05-jira-to-spec-workflow.md) | 20 min | Enterprise teams using Jira | Pull Jira context into specs and publish approved artifacts back |
 
 ## Learning path
 
@@ -20,6 +21,7 @@ Install
   -> approve a plan
   -> implement one task
   -> attach CI evidence
+  -> sync approved artifacts to Jira
   -> review and merge
 ```
 
@@ -34,3 +36,4 @@ GitHub Copilot, Gemini CLI, Cline, and similar tools can all use the generated p
 - dbt Labs skills answer dbt framework questions.
 - dbt-spec-kit skills and sub-agent roles enforce enterprise delivery rules.
 - CI evidence proves the final diff followed the approved plan.
+- Jira remains the intake and task tracking system, while specs remain the engineering contract.

pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "dbt-spec-kit"
-version = "1.2.0"
+version = "1.3.0"
 description = "Enterprise AI SDLC toolkit for dbt projects, with spec-driven workflows, CI validation, and warehouse-specific presets."
 readme = "README.md"
 license = { file = "LICENSE" }
@@ -25,6 +25,7 @@ keywords = [
     "postgres",
     "duckdb",
     "athena",
+    "jira",
 ]
 classifiers = [
     "Development Status :: 3 - Alpha",

src/dbt_specify/_version.py

@@ -1,4 +1,4 @@
 """Single source of truth for the package version."""
 from __future__ import annotations
 
-__version__ = "1.2.0"
+__version__ = "1.3.0"