Skip to content

Commit 4e6e401

Browse files
echarrodclaude
andcommitted
Initial preset: override speckit.taskstoissues to target Jira
Replaces the core GitHub Issues-only taskstoissues command with a Jira-aware implementation that creates epics, stories, tasks, and sub-tasks with dependency linking via Atlassian MCP tools. See github/spec-kit#2223 for context on why this is a preset rather than an extension. Co-Authored-By: Claude Opus 4.6 <[email protected]>
1 parent 3eaa953 commit 4e6e401

4 files changed

Lines changed: 275 additions & 0 deletions

File tree

‎CHANGELOG.md‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
## [1.0.0] - 2026-04-15
2+
3+
### Added
4+
- Override of core `speckit.taskstoissues` to target Jira instead of GitHub Issues
5+
- Jira issue hierarchy creation (Epic > Story/Task > Sub-task)
6+
- Dependency linking via Jira issue links
7+
- Configurable project key via config file, environment variable, or user input
8+
- Duplicate detection before creating issues

‎README.md‎

Lines changed: 79 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,79 @@
1+
# spec-kit-preset-jira
2+
3+
[![Spec Kit](https://img.shields.io/badge/spec--kit-preset-purple?logo=github)](https://github.com/github/spec-kit)
4+
[![Version](https://img.shields.io/badge/version-1.0.0-green)](https://github.com/luno/spec-kit-preset-jira/releases)
5+
[![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
6+
[![Issues](https://img.shields.io/github/issues/luno/spec-kit-preset-jira)](https://github.com/luno/spec-kit-preset-jira/issues)
7+
8+
Spec Kit preset that overrides `speckit.taskstoissues` to create Jira epics, stories, and tasks instead of GitHub Issues.
9+
10+
## Why a Preset?
11+
12+
The core `speckit.taskstoissues` command is hardcoded to GitHub Issues — it checks for a GitHub remote and uses the GitHub MCP server. For teams using Jira, the natural `/speckit.taskstoissues` workflow is unusable.
13+
14+
Extensions cannot override core commands due to the `speckit.{ext-id}.{command}` naming requirement. Presets sit higher in the resolution stack and can replace core commands directly, keeping the natural workflow intact.
15+
16+
See [github/spec-kit#2223](https://github.com/github/spec-kit/issues/2223) for the full discussion.
17+
18+
## What It Does
19+
20+
Overrides the core `speckit.taskstoissues` command so that `/speckit.taskstoissues` creates a Jira issue hierarchy:
21+
22+
- **Epic** — created from the feature name in `spec.md`
23+
- **Stories/Tasks** — one per task in `tasks.md`, linked to the epic
24+
- **Sub-tasks** — for tasks with sub-items
25+
- **Issue links** — dependency relationships from `tasks.md` are wired as "Blocks"/"is blocked by" links
26+
27+
## Installation
28+
29+
```bash
30+
specify preset add jira --from https://github.com/luno/spec-kit-preset-jira/archive/refs/heads/main.zip
31+
```
32+
33+
Or install from a local clone:
34+
35+
```bash
36+
git clone https://github.com/luno/spec-kit-preset-jira.git
37+
specify preset add --dev ./spec-kit-preset-jira
38+
```
39+
40+
### Prerequisites
41+
42+
This preset requires an Atlassian MCP server connection with access to:
43+
- `createJiraIssue`
44+
- `createIssueLink`
45+
- `getVisibleJiraProjects`
46+
- `getJiraProjectIssueTypesMetadata`
47+
- `searchJiraIssuesUsingJql`
48+
49+
## Configuration
50+
51+
The target Jira project is resolved in this order:
52+
53+
1. **User input** — pass a project key as an argument: `/speckit.taskstoissues CPB`
54+
2. **Preset config** — set `project_key` in `.specify/presets/jira/jira-config.yml`:
55+
```yaml
56+
project_key: "CPB"
57+
```
58+
3. **Environment variable** — set `SPECKIT_JIRA_PROJECT_KEY=CPB`
59+
4. **Interactive** — prompted to select from available projects
60+
61+
## Compatibility
62+
63+
This preset works alongside the existing [spec-kit-jira](https://github.com/mbachorik/spec-kit-jira) extension. The preset handles the core workflow override, while the extension can provide supplementary commands like `discover-fields` and `sync-status`.
64+
65+
## Overrides
66+
67+
| Core Command | Override |
68+
|---|---|
69+
| `speckit.taskstoissues` | Creates Jira issues instead of GitHub Issues |
70+
71+
## Links
72+
73+
- [Spec Kit](https://github.com/github/spec-kit/) — the Spec-Driven Development framework
74+
- [Presets catalog](https://github.com/github/spec-kit/tree/main/presets) — browse all available Spec Kit presets
75+
- [spec-kit-jira extension](https://github.com/mbachorik/spec-kit-jira) — complementary Jira extension with additional commands
76+
77+
## License
78+
79+
MIT

‎commands/speckit.taskstoissues.md‎

Lines changed: 161 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,161 @@
1+
---
2+
description: Convert existing tasks into actionable, dependency-ordered Jira issues for the feature based on available design artifacts.
3+
tools:
4+
- "Atlassian/createJiraIssue"
5+
- "Atlassian/createIssueLink"
6+
- "Atlassian/getVisibleJiraProjects"
7+
- "Atlassian/getJiraProjectIssueTypesMetadata"
8+
- "Atlassian/searchJiraIssuesUsingJql"
9+
scripts:
10+
sh: scripts/bash/check-prerequisites.sh --json --require-tasks --include-tasks
11+
ps: scripts/powershell/check-prerequisites.ps1 -Json -RequireTasks -IncludeTasks
12+
---
13+
14+
## User Input
15+
16+
```text
17+
$ARGUMENTS
18+
```
19+
20+
You **MUST** consider the user input before proceeding (if not empty).
21+
22+
## Pre-Execution Checks
23+
24+
**Check for extension hooks (before tasks-to-issues conversion)**:
25+
- Check if `.specify/extensions.yml` exists in the project root.
26+
- If it exists, read it and look for entries under the `hooks.before_taskstoissues` key
27+
- If the YAML cannot be parsed or is invalid, skip hook checking silently and continue normally
28+
- Filter out hooks where `enabled` is explicitly `false`. Treat hooks without an `enabled` field as enabled by default.
29+
- For each remaining hook, do **not** attempt to interpret or evaluate hook `condition` expressions:
30+
- If the hook has no `condition` field, or it is null/empty, treat the hook as executable
31+
- If the hook defines a non-empty `condition`, skip the hook and leave condition evaluation to the HookExecutor implementation
32+
- For each executable hook, output the following based on its `optional` flag:
33+
- **Optional hook** (`optional: true`):
34+
```
35+
## Extension Hooks
36+
37+
**Optional Pre-Hook**: {extension}
38+
Command: `/{command}`
39+
Description: {description}
40+
41+
Prompt: {prompt}
42+
To execute: `/{command}`
43+
```
44+
- **Mandatory hook** (`optional: false`):
45+
```
46+
## Extension Hooks
47+
48+
**Automatic Pre-Hook**: {extension}
49+
Executing: `/{command}`
50+
EXECUTE_COMMAND: {command}
51+
52+
Wait for the result of the hook command before proceeding to the Outline.
53+
```
54+
- If no hooks are registered or `.specify/extensions.yml` does not exist, skip silently
55+
56+
## Outline
57+
58+
### 1. Locate Feature Artifacts
59+
60+
Run `{SCRIPT}` from repo root and parse FEATURE_DIR and AVAILABLE_DOCS list. All paths must be absolute. For single quotes in args like "I'm Groot", use escape syntax: e.g 'I'\''m Groot' (or double-quote if possible: "I'm Groot").
61+
62+
From the executed script, extract the path to **tasks**.
63+
64+
### 2. Determine Jira Project
65+
66+
Resolve the target Jira project using the following precedence:
67+
68+
1. **User input** — if `$ARGUMENTS` contains a Jira project key (e.g. `--project CPB` or just `CPB`), use that
69+
2. **Preset config** — check `.specify/presets/jira/jira-config.yml` for a `project_key` field
70+
3. **Environment variable** — check `SPECKIT_JIRA_PROJECT_KEY`
71+
4. **Interactive** — use `getVisibleJiraProjects` to list available projects and ask the user to select one
72+
73+
Once the project key is determined, use `getJiraProjectIssueTypesMetadata` to discover available issue types (Epic, Story, Task, Sub-task, etc.) for the project.
74+
75+
### 3. Check for Existing Issues
76+
77+
Before creating issues, search Jira for existing issues that may have been created from a previous run:
78+
79+
```
80+
project = {PROJECT_KEY} AND summary ~ "{feature_name}"
81+
```
82+
83+
If matching issues are found, present them to the user and ask whether to:
84+
- **Skip** — do not create duplicates
85+
- **Continue** — create new issues alongside existing ones
86+
87+
### 4. Create Jira Issue Hierarchy
88+
89+
Create issues in the following order to establish the dependency chain:
90+
91+
**Epic** (if the feature has multiple phases/sections):
92+
- **Summary**: Feature name from spec.md
93+
- **Description**: Brief description from spec.md overview
94+
- **Issue type**: Epic
95+
96+
**Stories/Tasks** (one per task in tasks.md):
97+
- **Summary**: Task title from tasks.md
98+
- **Description**: Include the task description, acceptance criteria, and any relevant context from the spec
99+
- **Issue type**: Story for user-facing work, Task for technical work (infer from task content)
100+
- **Epic link**: Link to the parent epic
101+
- **Labels**: Add `spec-kit` label for traceability
102+
103+
**Sub-tasks** (for tasks with sub-items):
104+
- **Summary**: Sub-item title
105+
- **Description**: Sub-item details
106+
- **Issue type**: Sub-task
107+
- **Parent**: Link to the parent story/task
108+
109+
### 5. Establish Dependencies
110+
111+
For tasks that declare dependencies in tasks.md (e.g. "depends on Task 1"), create Jira issue links:
112+
- **Link type**: "Blocks" / "is blocked by"
113+
- Use `createIssueLink` to wire up the dependency graph
114+
115+
### 6. Summary Output
116+
117+
After creating all issues, output a summary table:
118+
119+
```
120+
## Jira Issues Created
121+
122+
| Key | Type | Summary | Links |
123+
|-----|------|---------|-------|
124+
| CPB-123 | Epic | Feature name | — |
125+
| CPB-124 | Story | Task 1 title | Epic: CPB-123 |
126+
| CPB-125 | Task | Task 2 title | Epic: CPB-123, Blocked by: CPB-124 |
127+
```
128+
129+
Include a direct link to the Jira board filtered by the epic.
130+
131+
## Post-Execution Checks
132+
133+
**Check for extension hooks (after tasks-to-issues conversion)**:
134+
Check if `.specify/extensions.yml` exists in the project root.
135+
- If it exists, read it and look for entries under the `hooks.after_taskstoissues` key
136+
- If the YAML cannot be parsed or is invalid, skip hook checking silently and continue normally
137+
- Filter out hooks where `enabled` is explicitly `false`. Treat hooks without an `enabled` field as enabled by default.
138+
- For each remaining hook, do **not** attempt to interpret or evaluate hook `condition` expressions:
139+
- If the hook has no `condition` field, or it is null/empty, treat the hook as executable
140+
- If the hook defines a non-empty `condition`, skip the hook and leave condition evaluation to the HookExecutor implementation
141+
- For each executable hook, output the following based on its `optional` flag:
142+
- **Optional hook** (`optional: true`):
143+
```
144+
## Extension Hooks
145+
146+
**Optional Hook**: {extension}
147+
Command: `/{command}`
148+
Description: {description}
149+
150+
Prompt: {prompt}
151+
To execute: `/{command}`
152+
```
153+
- **Mandatory hook** (`optional: false`):
154+
```
155+
## Extension Hooks
156+
157+
**Automatic Hook**: {extension}
158+
Executing: `/{command}`
159+
EXECUTE_COMMAND: {command}
160+
```
161+
- If no hooks are registered or `.specify/extensions.yml` does not exist, skip silently

‎preset.yml‎

Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,27 @@
1+
schema_version: "1.0"
2+
3+
preset:
4+
id: "jira"
5+
name: "Jira Issue Tracking"
6+
version: "1.0.0"
7+
description: "Overrides speckit.taskstoissues to create Jira epics, stories, and tasks instead of GitHub Issues"
8+
author: "luno"
9+
repository: "https://github.com/luno/spec-kit-preset-jira"
10+
license: "MIT"
11+
12+
requires:
13+
speckit_version: ">=0.1.0"
14+
15+
provides:
16+
templates:
17+
- type: "command"
18+
name: "speckit.taskstoissues"
19+
file: "commands/speckit.taskstoissues.md"
20+
description: "Convert tasks into Jira issues with epic/story/task hierarchy"
21+
replaces: "speckit.taskstoissues"
22+
23+
tags:
24+
- "jira"
25+
- "atlassian"
26+
- "issue-tracking"
27+
- "preset"

0 commit comments

Comments
 (0)