# mbachorik/spec-kit-jira architecture

> Architecture diagram of the GitHub repository mbachorik/spec-kit-jira, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-30). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/mbachorik/spec-kit-jira
- Repository: https://github.com/mbachorik/spec-kit-jira

## Overview

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: [`commands/specstoissues.md`](https://github.com/mbachorik/spec-kit-jira/blob/main/commands/specstoissues.md) (Spec to issues), [`commands/sync-status.md`](https://github.com/mbachorik/spec-kit-jira/blob/main/commands/sync-status.md) (Sync status), [`commands/discover-fields.md`](https://github.com/mbachorik/spec-kit-jira/blob/main/commands/discover-fields.md) (Discover fields), [`jira-config.template.yml`](https://github.com/mbachorik/spec-kit-jira/blob/main/jira-config.template.yml) (Jira config)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_local_project["Local Spec Kit Project"]
  node_spec_artifacts["Spec files<br/>Spec inputs"]
  node_mapping_json["Issue map<br/>Persistent state"]
  node_sync_log_json["Sync log<br/>Persistent state"]
  node_fields_json["Field refs<br/>Persistent state"]
end

subgraph group_extension_layer["Extension Layer"]
  node_extension_yml["Extension reg<br/>Extension metadata<br/>[extension.yml]"]
  node_jira_template["Config template"]
  node_readme["README<br/>Product spec<br/>[README.md]"]
  node_usage_docs["Usage guide<br/>Documentation<br/>[usage.md]"]
  node_examples["Examples"]
  node_cmd_specstoissues["Spec to issues<br/>Command spec<br/>[specstoissues.md]"]
  node_cmd_syncstatus["Sync status<br/>Command spec<br/>[sync-status.md]"]
  node_cmd_discoverfields["Discover fields<br/>Command spec<br/>[discover-fields.md]"]
  node_project_config["Jira config<br/>Layered config"]
  node_artifact_mapping["Artifact map<br/>Mapping layer"]
  node_defaults_fields["Defaults"]
end

subgraph group_external_systems["External Systems"]
  node_jira_mcp[("Jira MCP<br/>External API")]
end

node_spec_artifacts -->|"input"| node_cmd_specstoissues
node_spec_artifacts -->|"input"| node_cmd_syncstatus
node_cmd_specstoissues -->|"uses"| node_artifact_mapping
node_artifact_mapping -->|"driven by"| node_project_config
node_project_config -->|"supplies"| node_defaults_fields
node_cmd_specstoissues -->|"creates issues"| node_jira_mcp
node_cmd_specstoissues -->|"writes"| node_mapping_json
node_mapping_json -->|"input"| node_cmd_syncstatus
node_cmd_syncstatus -->|"transitions"| node_jira_mcp
node_cmd_syncstatus -->|"writes"| node_sync_log_json
node_cmd_discoverfields -->|"discovers"| node_jira_mcp
node_cmd_discoverfields -->|"writes"| node_fields_json
node_extension_yml -->|"registers"| node_cmd_specstoissues
node_extension_yml -->|"registers"| node_cmd_syncstatus
node_extension_yml -->|"registers"| node_cmd_discoverfields
node_readme -.->|"documents"| node_cmd_specstoissues
node_readme -.->|"documents"| node_cmd_syncstatus
node_readme -.->|"documents"| node_cmd_discoverfields
node_usage_docs -.->|"guides"| node_project_config
node_examples -.->|"illustrates"| node_project_config

click node_extension_yml "https://github.com/mbachorik/spec-kit-jira/blob/main/extension.yml"
click node_jira_template "https://github.com/mbachorik/spec-kit-jira/blob/main/jira-config.template.yml"
click node_readme "https://github.com/mbachorik/spec-kit-jira/blob/main/README.md"
click node_usage_docs "https://github.com/mbachorik/spec-kit-jira/blob/main/docs/usage.md"
click node_examples "https://github.com/mbachorik/spec-kit-jira/tree/main/docs/examples"
click node_cmd_specstoissues "https://github.com/mbachorik/spec-kit-jira/blob/main/commands/specstoissues.md"
click node_cmd_syncstatus "https://github.com/mbachorik/spec-kit-jira/blob/main/commands/sync-status.md"
click node_cmd_discoverfields "https://github.com/mbachorik/spec-kit-jira/blob/main/commands/discover-fields.md"
click node_project_config "https://github.com/mbachorik/spec-kit-jira/blob/main/jira-config.template.yml"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_spec_artifacts,node_mapping_json,node_sync_log_json,node_fields_json toneBlue
class node_extension_yml,node_jira_template,node_readme,node_usage_docs,node_examples,node_cmd_specstoissues,node_cmd_syncstatus,node_cmd_discoverfields,node_project_config,node_artifact_mapping,node_defaults_fields toneAmber
class node_jira_mcp toneMint
```

## Components

### Local Spec Kit Project

Spec Kit artifacts, generated issue state, and sync outputs.

- **Spec files**: Spec inputs · Local Spec Kit spec and task artifacts that drive Jira creation and status sync.
- **Issue map**: Persistent state · Saved issue identity and relationship mapping for later sync runs.
- **Sync log**: Persistent state · Recorded result of status synchronization across runs.
- **Field refs**: Persistent state · Discovered Jira custom field references used to refine config.

### Extension Layer

Repository files that define commands, configuration, and usage guidance.

- [Extension reg](https://github.com/mbachorik/spec-kit-jira/blob/main/extension.yml): Extension metadata · Registers the Spec Kit extension and its entry metadata. · `extension.yml`
- [Config template](https://github.com/mbachorik/spec-kit-jira/blob/main/jira-config.template.yml): Config template · Template for Jira project configuration and artifact mapping. · `jira-config.template.yml`
- [README](https://github.com/mbachorik/spec-kit-jira/blob/main/README.md): Product spec · Primary usage contract and behavior overview for the extension. · `README.md`
- [Usage guide](https://github.com/mbachorik/spec-kit-jira/blob/main/docs/usage.md): Documentation · Operational guidance for configuring and running the extension. · `docs/usage.md`
- [Examples](https://github.com/mbachorik/spec-kit-jira/tree/main/docs/examples): Config examples · Example project shapes and configuration variants. · `docs/examples`
- [Spec to issues](https://github.com/mbachorik/spec-kit-jira/blob/main/commands/specstoissues.md): Command spec · Creates Jira Epics, Stories, and Tasks from Spec Kit artifacts. · `commands/specstoissues.md`
- [Sync status](https://github.com/mbachorik/spec-kit-jira/blob/main/commands/sync-status.md): Command spec · Reads task completion and updates Jira issue status via saved mapping. · `commands/sync-status.md`
- [Discover fields](https://github.com/mbachorik/spec-kit-jira/blob/main/commands/discover-fields.md): Command spec · Inspects Jira fields through MCP and writes local field references. · `commands/discover-fields.md`
- [Jira config](https://github.com/mbachorik/spec-kit-jira/blob/main/jira-config.template.yml): Layered config · Authoritative project configuration with env and local override layers. · `jira-config.template.yml`
- **Artifact map**: Mapping layer · Translates Spec Kit artifacts into Jira issue types and link semantics.
- **Defaults**: Field defaults · Applies labels and custom fields during issue creation.

### External Systems

Jira and MCP services used by the extension.

- **Jira MCP**: External API · MCP server that exposes Jira/Atlassian tools to the extension.

## Connections

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