Skip to main content

ADR-0005 — Jira (project MEL) is the execution surface; GitHub is the implementation surface

StatusAccepted
Date2026-04-23
DecisionJira project MEL is the canonical surface for execution (epics, stories, bugs, spikes, ADR tickets, sub-tasks). The GitHub repository ghasi-melmastoon is the canonical surface for implementation (branches, PRs, CI). Specs remain in ghasi-e-documentation.
OwnersPlatform Engineering, AI Agent Steward
ConsequencesClosed set of issue types and labels in Jira; commits and PRs must reference MEL-NNN; AI agents must round-trip through both surfaces.
Supersedesn/a
Superseded byn/a

Companion documents (must stay in sync):

  • docs/standards/JIRA_PROJECT_SETUP.md — project configuration, fields, workflow, automation.
  • docs/standards/JIRA_TICKET_TEMPLATE.md — content templates for every issue type.
  • docs/standards/REQUIREMENTS_GUARD_RAILS.md — Definition of Ready (DoR) gate.
  • docs/standards/DEFINITION_OF_DONE.md — Definition of Done (DoD) gate.
  • docs/roadmap/jira-epic-based-sprint-ruleset.md, …/jira-sprint-distribution-rules.md, …/team-capacity-model.md.
  • D:\GhasiTech\ghasi-melmastoon\CONTRIBUTING.md (commit / PR rules).
  • D:\GhasiTech\ghasi-melmastoon\.github\PULL_REQUEST_TEMPLATE.md.
  • D:\GhasiTech\ghasi-melmastoon\commitlint.config.cjs (machine enforcement).

1. Context​

The Ghasi Melmastoon programme spans three repositories:

RepoAuthoritative for
ghasi-e-documentation/ghasi-melmastoon/Specs — what we are building, why, "done" criteria.
ghasi-melmastoon/ (this implementation monorepo)Code — how the system is implemented.
Jira project MELExecution — who is doing what, when, with what evidence.

Until Wave 0 of the readiness programme, the execution surface was implicit. Squads tracked work in ad-hoc Markdown files inside planning/, in PR descriptions, or in private spreadsheets. AI agents had no canonical place to fetch the next thing to do, and no consistent place to write back execution telemetry (status, deviations, audit pointers).

This ambiguity caused four observable failures:

  1. Spec ↔ code drift. PRs landed without referencing the spec section that authorised the change, so deviations went unnoticed until late audit.
  2. Wave / sprint drift. Stories were started without confirming they passed the Definition of Ready, leading to mid-sprint scope creep and partial deliveries.
  3. AI agent drift. Multi-agent runs (ghasi-multi-agent.yaml) had no anchor outside the local planning/ folder, so resuming a run in a new session required reconstructing context manually.
  4. Audit drift. epic-spec-implementation-audit outputs were committed but not surfaced as actionable work — the Deviation register had no canonical place to land as Jira issues with owners.

We need a single source of truth for execution that:

  • Closes the loop between specs (doc repo), code (this repo), and CI/PR.
  • Is machine-readable so AI agents can read, write, and round-trip without inventing structure.
  • Supports the sprint cadence, distribution rules, and readiness gates already defined in docs/roadmap/.

2. Decision​

We adopt Jira (project key MEL) as the canonical execution surface and the GitHub repository ghasi-melmastoon as the canonical implementation surface. Together with the ghasi-e-documentation spec repo, the three form a closed loop with explicit, machine-checked links.

2.1 Canonical mapping​

ObjectCanonical homeCross-references
EpicJira MEL EpicSpec ID field → EP-MEL-NN in docs/07-epics-and-user-stories.md
User storyJira MEL StorySpec ID field → US-… anchor in 07-epics-and-user-stories.md (or per-epic backlog/EP-MEL-NN.md)
BugJira MEL BugLinked to Story / Epic when discovered during a slice; Symptom + reproduction; CI run URL
SpikeJira MEL SpikeTime-boxed; outcome → ADR link or new Story; never ships code
ADRJira MEL ADR ticket → spec PR adding docs/architecture/ADR-NNNN-*.mdThe Jira ticket is the proposal/approval; the merged ADR markdown is the artefact
Task / Sub-taskJira MEL Task or Sub-task under a StoryUsed for non-functional / chore work that doesn't deserve a Story
BranchGitHub branch (features/<slug>, fix/<slug>, spike/<slug>)Branch name embeds MEL-NNN where practical
Pull requestGitHub PRTitle and / or body MUST reference at least one MEL-NNN (enforced by spec-drift.yml)
CommitGitHub commitSubject or footer MUST reference a MEL-NNN (enforced by commitlint.config.cjs)
Spec changePR in ghasi-e-documentationLinked from the implementation PR; AC delta noted in the Story
Audit reportplanning/epic-audits/EP-MEL-NN-…-spec-vs-implementation.md (gitignored)Audit pointer recorded in the Story comment thread; deviations open as new MEL Bug / Task tickets

2.2 Definition of Ready and Definition of Done​

  • DoR is docs/standards/REQUIREMENTS_GUARD_RAILS.md — gated by the spec-review skill (added in Wave 2). A Story may not move from Backlog → Ready without passing DoR.
  • DoD is docs/standards/DEFINITION_OF_DONE.md — gated by the dev-pipeline and ghasi-multi-agent workflows; PR template mirrors the checklist.

2.3 Sprints and distribution​

Sprint composition follows:

  • docs/roadmap/jira-epic-based-sprint-ruleset.md (epic → sprint decomposition).
  • docs/roadmap/jira-sprint-distribution-rules.md (per-component capacity).
  • docs/roadmap/team-capacity-model.md (squads, focus factors, on-call).
  • docs/roadmap/service-readiness-gates.md (P0 → P4 gating per service).

2.4 Machine enforcement​

The contract is enforced, not just documented:

  • commitlint.config.cjs rejects commits without a MEL-NNN reference.
  • .github/workflows/spec-drift.yml rejects PRs without MEL-NNN in title or body.
  • .github/PULL_REQUEST_TEMPLATE.md mirrors the workflow status, AC checklist, and audit pointer.
  • epic-spec-implementation-audit and ghasi-audit-close-loop skills resolve epic_or_story against docs/07-epics-and-user-stories.md (which is itself anchored on the Jira-friendly EP-MEL-NN / US-… IDs).
  • jira-load-story command (added in Wave 2) and jira-story-implementation.yaml workflow round-trip Story state into the local run folder and back into Jira via the Atlassian MCP.

3. Consequences​

3.1 Positive​

  • Single source of truth for execution. Any human or AI agent can answer "what is the next thing to do?" by querying Jira.
  • Round-trippable AI workflows. AI agents can load a Story (jira-load-story), check DoR (spec-review), implement (ghasi-multi-agent or dev-pipeline), audit (epic-spec-implementation-audit), and write evidence back to the same ticket.
  • Spec ↔ code traceability. Every commit, PR, and audit row resolves back to a Jira ticket and a spec section.
  • Sprint integrity. Distribution and capacity rules can be applied because every Story carries Component / Wave / Complexity / Service fields (per JIRA_PROJECT_SETUP.md).
  • Deviations stop being silent. Audit deviations land as new MEL Bug / Task tickets with owners and SLAs; nothing rots in a Markdown file.

3.2 Negative / costs​

  • Process tax. Engineers must keep Jira tickets in sync with branch / PR state. Mitigated by: GitHub ↔ Jira automation (status transitions on PR open / merge), commitlint, spec-drift.yml, jira-load-story.
  • Tool-chain dependency. Atlassian Cloud must remain available; outages block fresh execution context. Mitigated by: every Story is mirrored into planning/<workflow>/runs/<run_slug>/ at run-start, so an in-flight run survives a Jira outage.
  • Onboarding friction. New engineers must learn the issue-type set, label vocabulary, and DoR/DoD. Mitigated by: closed issue type set, controlled label vocabulary, templated tickets, and CONTRIBUTING.md quick-start.

3.3 Out of scope (intentionally)​

  • Choice of project tracker beyond Jira (Linear, Asana, GitHub Projects). Reconsider only with a new ADR.
  • Migration of historical (pre-Wave 0) ad-hoc planning notes; those remain archived in their original locations.
  • Per-tenant customer support tickets — those flow through a separate support tool (out of scope for this ADR).

4. Alternatives considered​

4.1 GitHub Issues as the only execution surface​

Rejected. GitHub Issues lacks: structured sprints, components, custom fields (Spec ID, Service, Wave, Complexity, Risk score), saved JQL-equivalent filters, multi-team boards, and capacity / focus-factor support. Forcing the Jira semantic model into Issues + Projects would re-implement Jira badly.

4.2 Linear as the execution surface​

Rejected for now. Linear is excellent for fast-moving product engineering, but: (a) the organisation already operates Atlassian Cloud at scale; (b) Atlassian MCP is mature and integrated into our agent stack; (c) Jira's flexibility on custom fields and JQL maps better onto our 22-service / multi-wave / 5-readiness-gate model. Reconsider in a future ADR if cost / DX changes materially.

4.3 Plain Markdown in planning/​

Rejected. Already tried implicitly through Wave 0; failed the four observable drift modes listed in §1. Markdown is fine as runtime working memory (it remains the home for planning/<workflow>/runs/<run_slug>/), not as the canonical execution surface.

5. Implementation checklist​

  • Wave 0 — JIRA_PROJECT_SETUP.md, JIRA_TICKET_TEMPLATE.md, REQUIREMENTS_GUARD_RAILS.md published in this docs repo.
  • Wave 0 — team-capacity-model.md, jira-epic-based-sprint-ruleset.md, jira-sprint-distribution-rules.md, service-readiness-gates.md, 13-traceability-matrix.md published.
  • Wave 0 — backlog/ reorganisation complete (per-epic stubs + flat indices).
  • Wave 1 — commitlint.config.cjs, spec-drift.yml, PULL_REQUEST_TEMPLATE.md, CONTRIBUTING.md enforce the link in the implementation repo.
  • Wave 2 — commands/jira-load-story.md, commands/spec-review.md, .cursor/skills/spec-review/, .cursor/skills/jira-story-sync/, .cursor/workflows/jira-story-implementation.yaml close the AI agent loop.
  • Wave 2 — JIRA_PROJECT_SETUP.md provisioning checklist completed in the actual MEL Jira instance (issue types, components, custom fields, workflow, automation rules).
  • Wave 4 — Atlassian Cloud ↔ GitHub automation: PR opened → Story In review; PR merged → Story Done (only if all sub-tasks closed); Bug filed → Story comment with link.

6. References​

  • docs/standards/JIRA_PROJECT_SETUP.md
  • docs/standards/JIRA_TICKET_TEMPLATE.md
  • docs/standards/REQUIREMENTS_GUARD_RAILS.md
  • docs/standards/DEFINITION_OF_DONE.md
  • docs/standards/CODING_STANDARDS.md
  • docs/standards/TESTING_STANDARDS.md
  • docs/standards/API_PATH_CONVENTIONS.md
  • docs/roadmap/team-capacity-model.md
  • docs/roadmap/jira-epic-based-sprint-ruleset.md
  • docs/roadmap/jira-sprint-distribution-rules.md
  • docs/roadmap/service-readiness-gates.md
  • docs/13-traceability-matrix.md
  • D:\GhasiTech\ghasi-melmastoon\CONTRIBUTING.md
  • D:\GhasiTech\ghasi-melmastoon\.github\PULL_REQUEST_TEMPLATE.md
  • D:\GhasiTech\ghasi-melmastoon\commitlint.config.cjs

Document version: 1.0.0 Last updated: 2026-04-23