[Extension]: Add Jira Mirror

[sebastienthibaud]

Extension ID

jira-mirror

Extension Name

Jira Mirror

Version

0.24.0

Description

Spec Kit ↔ Jira bridge for team-managed and company-managed projects: configurable workflows & hierarchies (Scrum/SAFe), multi-project, idempotent and fail-closed. macOS/Linux/Windows.

Author

Fyloss

Repository URL

https://github.com/Fyloss/spec-kit-jira-mirror

Download URL

https://github.com/Fyloss/spec-kit-jira-mirror/releases/download/v0.24.0/spec-kit-jira-mirror-0.24.0.zip

License

MIT

Homepage (optional)

https://github.com/Fyloss/spec-kit-jira-mirror

Documentation URL (optional)

https://github.com/Fyloss/spec-kit-jira-mirror/tree/main/docs

Changelog URL (optional)

https://github.com/Fyloss/spec-kit-jira-mirror/blob/main/CHANGELOG.md

Required Spec Kit Version

=0.13.0

Required Tools (optional)

- bash (>=4) - required on macOS/Linux
- pwsh (>=7) - required on Windows
- curl - required on macOS/Linux
- jq - required on macOS/Linux
- git - required

Number of Commands

4

Number of Hooks (optional)

7

Tags

jira, integration, sync

Key Features

• Works with both team-managed and company-managed Jira Cloud projects: issue types, hierarchy and workflow are discovered per project, never assumed
• No MCP server required: native Bash / PowerShell ports call the Jira REST API directly
• Mirrors spec.md / plan.md / tasks.md into Jira Cloud on every lifecycle event, via 7 registered hooks
• Idempotent: durable identifiers survive retitles, reorders and folder renames; an unchanged re-run writes nothing
• Fail-closed: a mirroring failure never fails the spec-kit command that triggered it
• A configured mapping a team-managed project cannot satisfy is refused at config time, with zero writes, rather than after tickets exist
• Status moves resolve against a ticket's real available transitions; ambiguous, gated or unreachable moves are withheld and warned once
• Seeds a specification from named, existing Jira issues, with an explicit write-plan confirmation before anything is created
• Ticket-first feature naming: resolves or creates the ticket, then names branch and spec folder
• Twin native ports proven equivalent by a language-agnostic conformance corpus
• Credentials never enter the tree, argv, logs or traces

Testing Checklist

• Extension installs successfully via download URL
• All commands execute without errors
• Documentation is complete and accurate
• No security vulnerabilities identified
• Tested on at least one real project

Submission Requirements

• Valid extension.yml manifest included
• README.md with installation and usage instructions
• LICENSE file included
• GitHub release created with version tag
• All command files exist and are properly formatted
• Extension ID follows naming conventions (lowercase-with-hyphens)

Testing Details

Tested on:

• macOS 26.6.1 "Tahoe" (Apple Silicon, MacBook Pro M1 Max) with Spec Kit v0.16.2 -
  Bash, jq and curl toolchain; primary day-to-day environment
• Ubuntu (ubuntu-latest) and Windows Server (windows-latest, PowerShell 7) on
  every push, via the GitHub Actions matrix
• Host-version floor verified separately: the install end-to-end workflow installs
  the extension against both the declared floor host (Spec Kit v0.13.0, the
  requires.speckit_version value) and current main, on all three OSes

Test project: a private company-managed Jira Cloud project used for real
day-to-day feature work (the extension is dogfooded on its own repository and on
internal projects), plus a dedicated scratch Jira Cloud project reserved for the
automated live suite. Neither instance is public, so no link can be shared.

Test scenarios:

Manual, against the real corporate Jira instance (macOS):

1. Installed the extension with specify extension add, then verified the four
   commands (config, feature, reconcile, seed) and the seven lifecycle
   hooks it registers.
2. Ran the install ceremony (/speckit.jira-mirror.config): per-project metadata
   discovery, managed README block, read-only verification of the registered hooks.
3. Bound the repository to the Jira project (committed config.yml + gitignored
   personal.yml), with the API token read from the macOS Keychain through a
   configured retrieval command — no credential in a tracked file.
4. Ran the full spec-kit lifecycle (specify → clarify → plan → tasks →
   analyze → implement) and confirmed each after_* hook mirrored the
   artifacts into Jira: epic + stories, acceptance criteria, managed description
   panels, per-phase status transitions.
5. Exercised ticket-first feature naming (before_specify): resolving an existing
   ticket, creating a new one, and the branch/folder naming conventions.
6. Seeded a specification from existing Jira issues (seed), including the
   binding and re-parenting confirmation flow.
7. Verified idempotency by hand: re-running reconcile on an unchanged feature
   performs zero writes, and human edits made directly in Jira outside the managed
   region survive a subsequent run.
8. Verified fail-closed behaviour: missing config, unreadable credential, wrong
   project key, and network failure each produce a diagnostic and a non-blocking
   warning rather than a partial write.

Automated (CI, on every push):

• 2,616 Bats tests (Bash port, run on ubuntu-latest and macos-latest) and 1,957 Pester tests (PowerShell port, run on ubuntu-latest, macos-latest and windows-latest)
• 253 cross-port conformance scenarios asserting byte-for-byte equivalence between the Bash and PowerShell implementations against a mock Jira server, run on all three operating systems (this is also how the Bash port is exercised on Windows)
• An opt-in live suite (tests/live/) that runs against the real Jira Cloud
  scratch project on every push to main and nightly, proving the zero-write
  double-run invariant — something a mock cannot verify on its own
• Install end-to-end workflow (fresh specify extension add into a clean
  repository) on three OSes × two host versions
• shellcheck, actionlint and PSScriptAnalyzer gates

Example Usage

# Install the extension into a spec-kit repository
specify extension add jira-mirror --from https://github.com/Fyloss/spec-kit-jira-mirror/releases/download/v0.24.0/spec-kit-jira-mirror-0.24.0.zip

# One-command install ceremony: discovers project metadata, binds the repo
/speckit.jira-mirror.config

# From here the 7 hooks mirror automatically on /speckit.specify, /speckit.plan, etc.
# Manual reconcile and seeding remain available:
/speckit.jira-mirror.reconcile
/speckit.jira-mirror.seed specs/<feature>/spec.md

Proposed Catalog Entry

{
  "jira-mirror": {
    "name": "Jira Mirror",
    "id": "jira-mirror",
    "description": "Spec Kit ↔ Jira bridge for team-managed and company-managed projects: configurable workflows & hierarchies (Scrum/SAFe), multi-project, idempotent and fail-closed. macOS/Linux/Windows.",
    "author": "Fyloss",
    "version": "0.24.0",
    "download_url": "https://github.com/Fyloss/spec-kit-jira-mirror/releases/download/v0.24.0/spec-kit-jira-mirror-0.24.0.zip",
    "sha256": "c3fe2f81fc3f47010cf92cdb8c49b612416b4c6aedf91beb579eba871fe1df16",
    "repository": "https://github.com/Fyloss/spec-kit-jira-mirror",
    "homepage": "https://github.com/Fyloss/spec-kit-jira-mirror",
    "documentation": "https://github.com/Fyloss/spec-kit-jira-mirror/tree/main/docs",
    "changelog": "https://github.com/Fyloss/spec-kit-jira-mirror/blob/main/CHANGELOG.md",
    "license": "MIT",
    "category": "integration",
    "effect": "read-write",
    "requires": {
      "speckit_version": ">=0.13.0",
      "tools": [
        { "name": "bash", "version": ">=4", "required": true },
        { "name": "pwsh", "version": ">=7", "required": false },
        { "name": "curl", "required": true },
        { "name": "jq", "required": true },
        { "name": "git", "required": true }
      ]
    },
    "provides": {
      "commands": 4,
      "hooks": 7
    },
    "tags": ["jira", "integration", "sync"],
    "verified": false,
    "downloads": 0,
    "stars": 0,
    "created_at": "2026-08-31T00:00:00Z",
    "updated_at": "2026-08-31T00:00:00Z"
  }
}

Additional Context

At the time of submission I'm not aware of another Spec Kit extension that supports
both team-managed and company-managed Jira Cloud projects. The two have different
issue-type, hierarchy and workflow models, and the bridge resolves them per project
from the discovered binding rather than assuming one shape - a mapping a team-managed
project cannot satisfy is refused at config time with zero writes. It also runs
without an MCP server: the Bash and PowerShell ports call the Jira REST API directly.

The download URL points to a purpose-built release asset rather than the GitHub source
archive shown in the template placeholder. The asset excludes development-only material
(specs/, tests/, .github/, docs/) per .extensionignore, so it contains exactly what
specify extension add installs, and two builds from the same commit are byte-identical.
The identically-named unversioned asset on the same release is the stable "latest"
address; both carry the SHA-256 above.

CI runs the full suite on a three-OS matrix with shellcheck and PSScriptAnalyzer lint
gates, plus gates on engine/sink boundary, module parity, coverage, single-sourced
version, and an end-to-end install that diffs the installed tree against the derived
surface member for member.

[github-actions]

cc @github/spec-kit-maintainers — new catalog submission for review.

[github-actions]

Pull request created: #4376

Generated by Add Community Extension from Issue Submission · 249.2 AIC · ⌖ 16.5 AIC · ⊞ 35.3K