Jira Project Setup — Ghasi Melmastoon

Companion: JIRA_TICKET_TEMPLATE.md · REQUIREMENTS_GUARD_RAILS.md · docs/07-epics-and-user-stories.md · docs/roadmap/jira-epic-based-sprint-ruleset.md · docs/roadmap/jira-sprint-distribution-rules.md · docs/roadmap/team-capacity-model.md

This document is the single, authoritative configuration of the Jira project that backs Ghasi Melmastoon execution. It exists so that (a) every human contributor sees the same fields and workflows, (b) every AI agent (Cursor, Claude, Copilot) can map a Jira ticket to a spec entity deterministically, and (c) PRs and Jira tickets stay in lockstep automatically.

If this document and the live Jira instance disagree, the document wins. Reconcile in the same PR — change the Jira config, update this doc.

1. Project basics

Field	Value
Project name	Ghasi Melmastoon
Project key	`MEL`
Project type	Team-managed Software (Atlassian Cloud)
Lead	Engineering Director (rotating per quarter; see `team-capacity-model.md`)
Default assignee	Component lead (per service ownership table)
URL	`https://ghasitech.atlassian.net/jira/software/projects/MEL`
Time zone	`UTC` (single, fixed; locale displays adjust)
Working week	Sun–Thu (Afghanistan) + Mon–Fri (international) — calendars per assignee

The key MEL is the ticket prefix. Commit subjects, branch names, PR titles, and audit trails reference MEL-<n>. The branded ID prefix in the codebase is independent (tnt_, rsv_, …) — Jira IDs and entity IDs never collide because Jira is MEL-1234 and entity IDs are <prefix>_<ulid>.

2. Issue types (closed set)

Issue type	Purpose	Hierarchy parent	Spec source of truth
Epic	One-to-one with `EP-MEL-NN` from `07-epics-and-user-stories.md`. Twenty in total.	(root)	`docs/07-epics-and-user-stories.md` §3+
Story	One-to-one with `US-MEL-NNNN`. Engineering deliverable.	Epic	Same doc, story sections
Task	Engineering work that does not map to a `US-MEL-NNNN` (e.g., refactor, infra, tooling, ADR follow-up).	Epic (or none)	None
Bug	Defect against a shipped story. Mandatory regression test.	Story (or Epic if cross-story)	None
Spike	Time-boxed investigation. Output is an ADR or a sized story.	Epic (or none)	None
ADR	Architecture decision record. Captures a tradeoff before code lands.	Epic (or none)	`docs/architecture/ADR-NNNN-*.md`
Sub-task	Decomposition of a Story or Task only when needed for parallel work; never to bypass story sizing.	Story / Task	None

Forbidden: "Improvement", "Change Request", "Initiative" (use Epic), "Theme" (use Component / Label).

3. Components (one per service + one per surface + one cross-cutting)

A component pins ownership and routes work to the right squad. Components mirror the canonical service catalog and the four user surfaces.

Component	Owns
`iam-service`	Identity, auth, MFA, SSO, device binding
`tenant-service`	Tenants, memberships, roles
`property-service`	Properties, room types, rooms
`reservation-service`	Bookings, reservations, holds, stays
`inventory-service`	Allocation, availability
`pricing-service`	Rate plans, dynamic pricing, FX
`billing-service`	Folios, charges, invoices, taxes
`payment-gateway-service`	Card, PayPal, MFS, cash, refunds
`lock-integration-service`	Mobile keys, RFID, PIN, vendor adapters
`housekeeping-service`	Cleaning tasks, board, kiosk
`maintenance-service`	Work orders, assets
`notification-service`	Email, SMS, WhatsApp, push, templates
`file-storage-service`	Uploads, signed URLs, virus scan, lifecycle
`staff-service`	Staff members, shifts, schedules
`theme-config-service`	Themes, layouts, content blocks, branding
`search-aggregation-service`	Meta search index
`analytics-service`	Event ingestion, marts, query API
`reporting-service`	Operational, financial, regulatory reports
`ai-orchestrator-service`	All AI calls, HITL, provenance, evals
`bff-consumer-service`	Meta web BFF
`bff-tenant-booking-service`	Tenant booking web/mobile BFF
`bff-backoffice-service`	Electron backoffice BFF
`app-web-meta`	`apps/web-meta` (Next.js)
`app-web-tenant-booking`	`apps/web-tenant-booking` (Next.js)
`app-mobile`	`apps/mobile` (Expo / React Native)
`app-desktop-backoffice`	`apps/desktop-backoffice` (Electron)
`pkg-ui-melmastoon`	`@ghasi/ui-melmastoon` design system package
`pkg-domain-primitives`	`@ghasi/domain-primitives`
`pkg-event-envelope`	`@ghasi/event-envelope`
`pkg-event-schemas`	Event JSON schemas registry
`pkg-api-contracts`	OpenAPI + zod contracts
`pkg-sync-protocol`	Desktop ↔ cloud sync protocol
`pkg-telemetry`	Telemetry primitives
`pkg-config`	Shared env + config
`infra-cloud-run`	Terraform + Cloud Run
`infra-pubsub`	Topic / sub registry
`infra-cloud-sql`	Postgres provisioning, RLS audit
`infra-secret-kms`	Secret Manager + KMS
`infra-observability`	OTEL, dashboards, alerts
`cross-cutting`	Anything truly cross-cutting (rules, docs, governance)

A ticket carries one or more components. Stories that span services list every service involved (matches Services field in the spec story). Multi-component stories are routed by primary component = first listed service.

4. Labels (free-form, but with a controlled vocabulary)

Labels are additive classifiers; they don't replace components. Use the following controlled vocabulary; do not invent new ones without raising a ticket on cross-cutting.

Label	Meaning
`surface:web-meta`, `surface:web-tenant-booking`, `surface:mobile`, `surface:desktop`	Frontend surface(s) the work touches
`wave:r1`, `wave:r2`, `wave:r3`	Roadmap wave assignment
`priority:p0`, `priority:p1`, `priority:p2`, `priority:p3`	Priority (mirrors the field; label exists for JQL ergonomics)
`type:feature`, `type:tech-debt`, `type:perf`, `type:security`, `type:a11y`, `type:i18n`, `type:offline`, `type:ai`, `type:observability`, `type:ux-polish`	Cross-cutting work type
`risk:lock-vendor`, `risk:payment-vendor`, `risk:offline-sync`, `risk:multi-tenant-leak`, `risk:ai-cost`, `risk:locale`	Risk register linkage
`dor:incomplete`	Definition-of-Ready failed (see §8) — blocks sprint pull
`dod:waived`	One DoD bullet waived in this PR with explicit ADR (rare; mandatory ADR link in description)
`needs-adr`	Will produce an ADR before merge
`spec-drift`	Implementation does not match spec; will be reconciled in this ticket
`agent-driven`	Created or executed primarily by an AI agent (Cursor / Claude background, Copilot prompt)
`quarantine-flake`	Flaky E2E quarantined; deadline in description

5. Mandatory custom fields

Field	Type	Required on	Validation
Spec ID	Short text	Story, Task	Regex `^(US-MEL-\d{4}
Service(s)	Multi-select (Components)	Story, Task, Bug	At least one.
Surface(s)	Multi-select	Story	Empty allowed for backend-only stories.
Wave	Single-select (`R1`, `R2`, `R3`)	Epic, Story	Required for stories pulled into a sprint.
Acceptance Criteria	Long text (Markdown)	Story, Bug	Gherkin (`Given/When/Then`). 2–5 clauses.
DoD applicability	Multi-select (Universal, Data, API, Events, Security, AI, Frontend, Observability)	Story	At least Universal. Drives the PR template checklist.
Test types required	Multi-select (Unit, Integration, Contract, E2E, Offline, AI-eval, Perf, Security)	Story	At least Unit + Integration.
Complexity	Single-select (S, M, L)	Story	XL is forbidden — split.
Story Points	Number	Story, Task	Optional but recommended; mapped from Complexity (S=2, M=5, L=8).
Linked Epic ID	Short text	Story	Auto-populated from Epic link; format `EP-MEL-NN`.
Linked Journey ID(s)	Short text (comma-list)	Story	Optional; format `J-NN`.
Linked Workflow ID(s)	Short text (comma-list)	Story	Optional; format `W-NN`.
Linked ADR(s)	URL	Any	Optional.
Branch name	Short text	Story, Task, Bug	Auto-populated by `commands/jira-pull-story.md` to `features/MEL-<n>-<slug>`.
PR URL	URL	Story, Task, Bug	Auto-populated by GitHub action on PR open.
Risk score	Number 0–10	Story	Optional; threshold ≥ 7 forces a security-reviewer subagent run.

Fields not in this table are forbidden unless added in a PR against this document.

6. Workflow (states + transitions)

State	Meaning	Who can move it in
Backlog	Not yet groomed. May lack AC, DoD applicability, complexity.	Anyone (creator).
Refined	Definition-of-Ready met (see §8). Eligible for sprint pull.	Tech lead or product owner.
To Do	Pulled into the active sprint.	Sprint planner.
In Progress	Branch open and active commits.	Assignee (or `commands/jira-sync-status.md`).
In Review	PR open, awaiting review.	Assignee (or GitHub action on PR open).
In QA	PR merged into a release branch; QA validation underway (only if a separate QA gate exists for this slice).	QA lead.
Blocked	Cannot proceed; description must list the blocker(s).	Anyone, with required `Blocker` field.
Done	Merged into `develop`, all DoD bullets ticked, telemetry live.	Reviewer on PR merge (action).
Won't Do	Decided not to ship.	Product owner. Mandatory rationale.
Deferred	Explicitly punted to a later sprint or wave. Mandatory `Deferred to wave` field.	Tech lead or product owner.

Allowed transitions:

Backlog -> Refined -> To Do -> In Progress -> In Review -> [In QA ->] Done
                                                                ^ failed -> In Progress
                                ^ Blocked <-> any active state
                  Refined -> Won't Do
                  Refined -> Deferred

A ticket cannot skip from Backlog directly to In Progress. The DoR gate (§8) is enforced at Refined → To Do.

7. Epic mapping (live)

Jira Epic	Spec ID	Title	Wave	Primary component
`MEL-` (created on first refinement)	`EP-MEL-01`	Tenant Onboarding & Configuration	R1	`tenant-service`
↳	`EP-MEL-02`	Consumer Meta Search Layer	R1	`search-aggregation-service`
↳	`EP-MEL-03`	Tenant-Branded Booking Experience	R1	`bff-tenant-booking-service`
↳	`EP-MEL-04`	Reservation Lifecycle	R1	`reservation-service`
↳	`EP-MEL-05`	Payment Gateway	R1	`payment-gateway-service`
↳	`EP-MEL-06`	Front-Desk Operations on Electron Desktop	R1	`bff-backoffice-service`
↳	`EP-MEL-07`	Housekeeping Coordination	R1	`housekeeping-service`
↳	`EP-MEL-08`	Maintenance & Asset Management	R2	`maintenance-service`
↳	`EP-MEL-09`	Lock & Key Integration	R1	`lock-integration-service`
↳	`EP-MEL-10`	Offline-First Desktop with Sync Engine	R1	`bff-backoffice-service`
↳	`EP-MEL-11`	AI-Assisted Operations	R2	`ai-orchestrator-service`
↳	`EP-MEL-12`	Multi-Tenant Theming & Booking Flow Config	R1	`theme-config-service`
↳	`EP-MEL-13`	Reporting (Op / Financial / Regulatory)	R1	`reporting-service`
↳	`EP-MEL-14`	Analytics Pipeline	R2	`analytics-service`
↳	`EP-MEL-15`	Multi-Channel Notification	R1	`notification-service`
↳	`EP-MEL-16`	File Storage	R1	`file-storage-service`
↳	`EP-MEL-17`	Identity, Auth, RBAC, MFA, SSO, Device Binding	R1	`iam-service`
↳	`EP-MEL-18`	Multi-Language & RTL/LTR	R1	`pkg-ui-melmastoon`
↳	`EP-MEL-19`	Compliance & Regulatory	R1	`cross-cutting`
↳	`EP-MEL-20`	Observability, Reliability, Cost Controls	R1	`infra-observability`

The first time an epic is refined, an agent (or human) runs commands/jira-create-from-spec.md (Wave 2 deliverable) which creates the Jira Epic, populates Spec ID + Wave + Primary component, and seeds child stories from the spec section.

8. Definition of Ready (DoR) — gate at `Refined → To Do`

A ticket cannot move into To Do unless every box is true:

Tickets failing DoR are sent back to Refined → Backlog with a dor:incomplete label and a comment listing the gaps.

9. Definition of Done (DoD) — gate at `In Review → Done`

DoD is the merge checklist in DEFINITION_OF_DONE.md, enforced by the PR template. Jira automation moves the ticket to Done when the PR is merged AND every DoD box ticked AND CI green. A ticket moved to Done without a merged PR raises an alert.

10. JQL filter library (curated)

Saved filters live under My filters and are owned by team-jira-admin. The following are mandatory and must always exist:

Filter name	JQL
`MEL: My current work`	`assignee = currentUser() AND status in ("In Progress", "In Review", "Blocked")`
`MEL: Backlog ready for refinement`	`project = MEL AND status = Backlog AND issuetype = Story`
`MEL: Refined awaiting sprint`	`project = MEL AND status = Refined AND sprint is EMPTY`
`MEL: Active sprint`	`project = MEL AND sprint in openSprints()`
`MEL: DoR-incomplete`	`project = MEL AND labels = "dor:incomplete"`
`MEL: Blocked > 24h`	`project = MEL AND status = Blocked AND updated < -1d`
`MEL: PR open > 3d`	`project = MEL AND status = "In Review" AND updated < -3d`
`MEL: Wave R1 remaining`	`project = MEL AND "Wave" = R1 AND status not in (Done, "Won't Do", Deferred)`
`MEL: Service <name>`	`project = MEL AND component = "<service>" AND status not in (Done, "Won't Do")` (one per component)
`MEL: Spec drift`	`project = MEL AND labels = "spec-drift"`
`MEL: Agent-driven`	`project = MEL AND labels = "agent-driven"`
`MEL: Security-reviewed required`	`project = MEL AND ("Risk score" >= 7 OR "DoD applicability" = "Security") AND status not in (Done, "Won't Do")`
`MEL: Audit close-loop targets`	`project = MEL AND labels = "spec-drift" AND status = "Refined"`

11. Sprints

Cadence: 2 weeks, Sun–Thu primary calendar.
Sprint name: R<N>-S<NN> (e.g., R1-S03).
Capacity model and per-component allocation: see team-capacity-model.md.
Distribution rules: see jira-sprint-distribution-rules.md.
Sprint goal: 1–3 sentences referencing the Wave's outcome and the dominant epic(s).
Sprint pull policy: only Refined tickets with the same Wave label as the sprint.
Mid-sprint scope changes: allowed only if a ticket already in the sprint is descoped to make room (1-for-1 capacity swap), and the change is logged as a comment on both tickets.

12. Boards

Board	Type	Filter
`MEL Active Sprint`	Scrum	`project = MEL AND sprint in openSprints()`
`MEL Refinement`	Kanban	`project = MEL AND status in (Backlog, Refined)`
`MEL Bugs`	Kanban	`project = MEL AND issuetype = Bug`
`MEL Per-Service`	Kanban (one per service)	`project = MEL AND component = "<service>"`
`MEL Roadmap`	Roadmap	All Epics, grouped by Wave
`MEL Risk register`	Kanban	`project = MEL AND labels in (risk:*)`

Columns mirror the workflow states; WIP limits are set per board (default: In Progress ≤ 3 per assignee, In Review ≤ 5 per service).

13. GitHub ↔ Jira automation (mandatory)

Trigger	Action
Branch push matching `^(features	fix
First commit on a `MEL-<n>` branch	Move ticket to `In Progress`.
PR opened referencing `MEL-<n>` (in title or body)	Set Jira `PR URL` field. Move ticket to `In Review`.
PR merged	Move Jira ticket to `Done`. Add a comment with the merge SHA + author + merged-into branch.
PR closed without merge	Move ticket back to `In Progress`. Add comment "PR closed without merge".
Comment on PR by `security-reviewer` agent with `BLOCK`	Add `dod:waived: false` and a comment to the Jira ticket; do not move state.
CI failure on a PR	Add a Jira comment with the failing job.

The actions live in .github/workflows/jira-sync.yml (Wave 3 deliverable) and use a service-account API token stored in GitHub Secrets.

14. AI-agent integration (Cursor / Claude / Copilot)

The Atlassian MCP server is registered in .cursor/mcp.json and the Claude allowlist (Wave 2 deliverable). Agents can read tickets, post comments, and transition status.
commands/jira-pull-story.md — fetch ticket → write planning/ghasi-multi-agent/runs/<slug>/story-from-jira.md → seed the multi-agent workflow.
commands/jira-sync-status.md — at each multi-agent stage boundary, comment the stage outcome on the Jira ticket.
commands/jira-create-from-spec.md — given an EP-MEL-NN, create the Jira Epic + child stories with all custom fields populated from the spec.
commands/jira-sprint-plan.md — apply jira-sprint-distribution-rules.md to assign Refined tickets to the next sprint.
The agent-driven label is added automatically by any of the above commands.

Hard rule for agents: never create a Jira ticket without a populated Spec ID unless the issue type is Task, Spike, or ADR. A Story or Bug without a Spec ID fails the Jira automation gate.

15. Provisioning checklist (one-time, by Atlassian admin)

16. Anti-patterns (auto-flagged in standups / retros)

A Story with no Spec ID.
A Story with > 5 acceptance criteria (likely too big — split).
A Story with Complexity = XL (forbidden).
A Story with no Acceptance Criteria but Refined.
An Epic with no child stories after sprint planning starts.
A Sub-task that exists only to bypass story sizing.
A Bug with no linked PR after merge.
A Done ticket with no merged PR.
A ticket that bounces Refined ↔ Backlog more than 3 times (likely a spec gap — escalate).
More than 30 % of In Progress tickets without a branch link (likely shadow work).

17. Cross-references

JIRA_TICKET_TEMPLATE.md — copyable templates per issue type.
REQUIREMENTS_GUARD_RAILS.md — what makes a "complete" story.
docs/07-epics-and-user-stories.md — spec source of truth for epics + stories.
docs/roadmap/jira-epic-based-sprint-ruleset.md — sprint composition rules.
docs/roadmap/jira-sprint-distribution-rules.md — capacity allocation.
docs/roadmap/team-capacity-model.md — squads ↔ services ↔ velocity.
commands/jira-*.md — agent playbooks (Wave 2).
.github/workflows/jira-sync.yml — automation (Wave 3).

18. Versioning of this document

Same governance as CODING_STANDARDS.md §19. Material change to issue types, custom fields, or workflow transitions requires an ADR.

1. Project basics​

2. Issue types (closed set)​

3. Components (one per service + one per surface + one cross-cutting)​

4. Labels (free-form, but with a controlled vocabulary)​

5. Mandatory custom fields​

6. Workflow (states + transitions)​

7. Epic mapping (live)​

8. Definition of Ready (DoR) — gate at Refined → To Do​

9. Definition of Done (DoD) — gate at In Review → Done​

10. JQL filter library (curated)​

11. Sprints​

12. Boards​

13. GitHub ↔ Jira automation (mandatory)​

14. AI-agent integration (Cursor / Claude / Copilot)​

15. Provisioning checklist (one-time, by Atlassian admin)​

16. Anti-patterns (auto-flagged in standups / retros)​

17. Cross-references​

18. Versioning of this document​