/atlassian-setup

name: atlassian-setup
description: "Connect Jira and Confluence for project tracking and knowledge search. Use when the user says 'connect Jira', 'hook up Confluence', 'my tickets/board'. Not for a personal task app like Todoist/Things/Trello; use `todoist-setup`/`things-setup`/`trello-setup`."
manifest:
  id: atlassian
  auth: oauth2
  category: project_management
  services:
    - jira
    - confluence

Atlassian Setup

Connect your Jira and Confluence to Dex so this session can query your Atlassian workspace when you ask, and optionally keep Dex tasks in sync with Jira issues.

What This Enables

Once connected, Dex can:

• **Ask Jira / Confluence in this session:** search issues and pages through the Atlassian connector. That is on-demand, not a standing dashboard.
• **Task sync (optional):** keep Dex tasks and Jira issues in sync when you turn that on. This is the one automatic write path.
• **Not a silent upgrade to other skills.** `/daily-plan`, `/project-health`, `/meeting-prep`, `/week-review`, and `/triage` do not currently add sprint status, velocity, blocked tickets, or Confluence docs on their own. Do not promise those surfaces. If the user wants Jira or Confluence context there, they ask, and Dex uses the connector in that turn.

Privacy

• Dex reads Jira issues and Confluence pages **on demand** -- nothing is stored permanently
• Data is fetched, summarized, and discarded after the session
• Only YOUR workspace data is accessible (scoped to your OAuth permissions)
• The OAuth token stays local on your machine and is gitignored

When to Run

• User types `/atlassian-setup`
• User asks about connecting Jira or Confluence
• User wants Jira context in daily plans, project health, or meeting prep
• During `/integrate-mcp` if Jira or Confluence is mentioned

---

Setup Flow

Step 1: Check if Already Connected

1. Check `System/integrations/config.yaml` for `atlassian.enabled: true` 2. If enabled, read `System/.atlassian-oauth-token.json` and test the token:

• Call `https://api.atlassian.com/oauth/token/accessible-resources` with the stored token
• If valid, skip to **Step 6** (Configure Projects)

3. If the token is missing, expired, or invalid, continue to Step 2

Step 2: Explain What We're Setting Up

Say:

**Let's connect Jira and Confluence to Dex.**

This uses Atlassian's OAuth flow to securely connect your Atlassian Cloud workspace.
No API tokens to manage -- it uses the standard Atlassian authorization flow.

**What you'll need:**
- An Atlassian Cloud account (e.g., yourcompany.atlassian.net)
- Permission to authorize third-party apps (check with your admin if unsure)
- About 3 minutes

**What gets connected:**
- **Jira:** Dex can search your issues when you ask, and optionally sync Dex tasks with Jira
- **Confluence:** Dex can search pages when you ask (read-only)
- Morning plans, project health, meeting prep, and week review do **not** automatically grow a Jira or Confluence section from this setup alone

**Ready to go?**

Wait for confirmation.

Step 3: Add the Atlassian MCP Server

Check the user's MCP configuration. If an Atlassian MCP server is not listed:

1. Explain what we're adding:

I need to add the Atlassian connector to your Dex configuration.

This uses the official Atlassian Remote MCP server which handles OAuth
authentication and provides secure access to your Jira and Confluence data.

2. Add to the user's `.mcp.json`:

{
  "atlassian": {
    "command": "npx",
    "args": ["-y", "mcp-remote@latest", "https://mcp.atlassian.com/v1/sse"]
  }
}

3. Tell the user the MCP server needs to restart for changes to take effect.

Step 4: Authenticate

Guide the user through the OAuth flow:

1. The Atlassian MCP server will open a browser window for authorization 2. User logs in to Atlassian and grants access 3. The MCP server stores the token locally

After auth completes, verify:

• Call the accessible-resources endpoint to confirm the token works
• Save token data to `System/.atlassian-oauth-token.json`

**If authentication succeeds:**

Connected! I can see your Atlassian workspace: [workspace-name]

**If it fails:**

Hmm, that didn't work. A few things to check:

1. **Are you logged in to Atlassian Cloud?** (Not Server/Data Center -- Cloud only)
2. **Does your account have permission to authorize apps?** Check with your admin
3. **Try the auth flow again** -- sometimes it takes two tries

Want to retry?

Retry up to 2 times, then offer to skip and come back later.

Step 5: Select Cloud Site

If the user has access to multiple Atlassian sites:

You have access to multiple Atlassian sites:

1. acme-corp.atlassian.net
2. acme-sandbox.atlassian.net

Which site should Dex connect to?

Save the selected `cloud_id` for API calls.

Step 6: Configure Jira Project

**Which Jira project should Dex sync with?**

This is the project where your tasks and issues live. I'll use it for:
- Task sync (if you enable it)
- On-demand Jira searches in this session
- Not an automatic sprint widget in `/daily-plan` or `/project-health`

**Enter a project key** (e.g., ACME, PROD, ENG) or say "show me what's available"

If they say "show me what's available":

• Call the Jira projects API to list accessible projects
• Show the list and let them pick

Step 7: Configure Confluence Space (Optional)

**Want to connect Confluence too?** (Optional)

If connected, Dex can search that Confluence space when you ask — including
during meeting prep if you want docs looked up. `/meeting-prep` does not add a
Confluence section on its own.

**Enter a space key** (e.g., TEAM, DOCS, KB) or say "skip" or "show me what's available"

If they say "show me what's available":

• Call the Confluence spaces API to list accessible spaces
• Show the list and let them pick

Step 8: Configure Task Sync Trust Level

**How should Dex handle Jira task sync?**

When you create tasks in Dex or compl