How mbachorik/spec-kit-jira works
1. What this repository is
- This is a Spec Kit extension for Jira, not a standalone app or service.
- Its job is to translate Spec Kit artifacts in a local project into Jira issues, then sync local task state back to Jira.
2. Top-level architecture
- The repo is mostly configuration and command definitions, with no runtime source tree shown here.
- The important entry points are:
- extension.yml for extension registration/metadata
- commands/*.md for the three user-facing MCP/agent commands
- jira-config.template.yml for project configuration
- docs/ for examples and usage guidance
3. Primary operating model
- The extension is invoked from an AI agent / Spec Kit command interface, not by a traditional CLI binary.
- It depends on an MCP server that exposes Jira/Atlassian tools; the extension itself orchestrates specs, mappings, and issue relationships around those external tools.
4. Main workflow: spec-to-Jira creation
- Input comes from a Spec Kit project structure, especially:
- specs/<spec-name>/spec.md
- specs/<spec-name>/tasks.md
- The /speckit.jira.specstoissues command creates:
- one Jira Epic from the spec
- Stories from phase headers
- Tasks from checklist items
- It then persists the relationship map in specs/<spec-name>/jira-mapping.json.
5. Hierarchy modes
- The extension supports two structural modes:
- 3-level: Spec → Phase Stories → Task issues
- 2-level: Spec → Phase Stories, with task checklists embedded in story descriptions
- This mode is controlled by whether task_artifact is configured or left empty.
6. Status synchronization flow
- The /speckit.jira.sync-status command reads completion markers from tasks.md.
- It uses the previously saved mapping file to find Jira issue IDs and transitions.
- The result is written to specs/<spec-name>/jira-sync-log.json, showing that sync is stateful across runs.
7. Custom field discovery path
- The /speckit.jira.discover-fields command is a discovery/inspection utility against Jira via MCP.
- It outputs a local reference file at .specify/extensions/jira/discovered-fields.json, which helps users map Jira custom field IDs into config.
- This is a support subsystem for configuration, not part of the issue-creation path.
8. Configuration boundaries
- The authoritative config lives under .specify/extensions/jira/jira-config.yml.
- There is also support for:
- environment variable overrides
- a local gitignored override file, jira-config.local.yml
- This gives the extension a layered config model: template defaults, project config, local overrides, and env overrides.
9. Artifact and relationship mapping
- The config translates Spec Kit concepts into Jira concepts:
- spec_artifact, phase_artifact, task_artifact
- relationship types such as Epic Link, Relates, Blocks, etc.
- This mapping layer is central to the architecture because it decouples Spec Kit structure from Jira issue types and link semantics.
10. Defaults and field enrichment
- The config also includes per-artifact defaults:
- labels
- custom fields
- This means issue creation is not just structural; it can also apply metadata and Jira-specific field values during creation.
11. Repository contents and their roles
- commands/ contains the user-facing command docs that define behavior and expected inputs/outputs.
- docs/examples/ shows concrete config variants for different project shapes.
- README.md is effectively the product spec and usage contract for the extension.
- CHANGELOG.md, LICENSE, and .gitignore support release and repo hygiene, but do not affect runtime flow.
12. External dependencies and system boundary
- The extension’s functional boundary ends at Jira/MCP.
- It assumes:
- a Jira account with project access
- a compatible MCP server such as “atlassian” or “jira-mcp-server”
- a Spec Kit project with specs/tasks already generated
- So the architecture is a thin orchestration layer between local spec files and remote Jira APIs exposed through MCP.
13. State produced by the extension
- The extension creates and consumes local state files alongside the spec:
- jira-mapping.json for issue identity/link persistence
- jira-sync-log.json for sync history
- discovered-fields.json for field discovery results
- These files are important diagram elements because they show the extension is not stateless.
14. How to diagram it
- A good architecture diagram should show:
- the local Spec Kit project on one side
- the extension command layer in the middle
- Jira/MCP on the other side
- persistent local JSON artifacts as shared state
- The key flows are:
- spec/tasks → issue creation
- issue mapping → later status sync
- Jira field discovery → config refinement
Main entry points: specstoissues.md Spec to issues · sync-status.md Sync status · discover-fields.md Discover fields · jira-config.template.yml Jira config
Components 16
Local Spec Kit Project
Spec Kit artifacts, generated issue state, and sync outputs.
- Spec files · Local Spec Kit spec and task artifacts that drive Jira creation and status sync.
- Issue map · Saved issue identity and relationship mapping for later sync runs.
- Sync log · Recorded result of status synchronization across runs.
- Field refs · Discovered Jira custom field references used to refine config.
Extension Layer
Repository files that define commands, configuration, and usage guidance.
- Extension reg · Registers the Spec Kit extension and its entry metadata.
extension.yml - Config template · Template for Jira project configuration and artifact mapping.
jira-config.template.yml - README · Primary usage contract and behavior overview for the extension.
README.md - Usage guide · Operational guidance for configuring and running the extension.
docs/usage.md - Examples · Example project shapes and configuration variants.
docs/examples - Spec to issues · Creates Jira Epics, Stories, and Tasks from Spec Kit artifacts.
commands/specstoissues.md - Sync status · Reads task completion and updates Jira issue status via saved mapping.
commands/sync-status.md - Discover fields · Inspects Jira fields through MCP and writes local field references.
commands/discover-fields.md - Jira config · Authoritative project configuration with env and local override layers.
jira-config.template.yml - Artifact map · Translates Spec Kit artifacts into Jira issue types and link semantics.
- Defaults · Applies labels and custom fields during issue creation.
External Systems
Jira and MCP services used by the extension.
- Jira MCP · MCP server that exposes Jira/Atlassian tools to the extension.
Connections 20
- Spec files → Spec to issues: input · Spec and task artifacts are consumed to create Jira work items.
- Spec files → Sync status: input · Task completion markers drive status synchronization.
- Spec to issues → Artifact map: uses · Command resolves Spec Kit artifacts into Jira issue hierarchy.
- Artifact map → Jira config: driven by · Configured artifact names and relationship semantics control the mapping.
- Jira config → Defaults: supplies · Configuration provides labels, custom fields, and other defaults.
- Spec to issues → Jira MCP: creates issues · Issues are created through Jira tools exposed by MCP.
- Spec to issues → Issue map: writes · Persistent issue mapping is saved for future sync.
- Issue map → Sync status: input · Stored issue IDs and links are reused during status sync.
- Sync status → Jira MCP: transitions · Status updates are applied through Jira tools exposed by MCP.
- Sync status → Sync log: writes · Sync outcomes are recorded locally.
- Discover fields → Jira MCP: discovers · Field metadata is inspected through Jira tools exposed by MCP.
- Discover fields → Field refs: writes · Discovered field references are stored locally.
- Extension reg → Spec to issues: registers · Extension metadata exposes the issue-creation command.
- Extension reg → Sync status: registers · Extension metadata exposes the sync command.
- Extension reg → Discover fields: registers · Extension metadata exposes the field discovery command.
- README → Spec to issues: documents · README explains the issue-creation workflow.
- README → Sync status: documents · README explains the status synchronization workflow.
- README → Discover fields: documents · README explains the field discovery workflow.
- Usage guide → Jira config: guides · Usage docs explain layered configuration and overrides.
- Examples → Jira config: illustrates · Examples show how configuration changes across project shapes.