ai-coding-skills/docs/ATLASSIAN.md

# ATLASSIAN

## Purpose

Provide a portable Atlassian Cloud skill for Codex, Claude Code, Cursor Agent, OpenCode, and Pi
using one shared CLI surface for common Jira and Confluence workflows.

## Why This Skill Exists

The repo targets multiple agent environments with uneven MCP availability. This skill packages a
consistent CLI contract so the same task-oriented workflows can be used across all supported agents
without depending on MCP-specific integrations.

The canonical runtime lives in `skills/atlassian/shared/scripts/`. Installable per-agent
`scripts/` bundles are generated from that source with:

```bash
pnpm --dir skills/atlassian/shared/scripts sync:agents
```

## Requirements

- Node.js 20+
- `pnpm`
- Atlassian Cloud access
- `ATLASSIAN_BASE_URL`
- `ATLASSIAN_EMAIL`
- `ATLASSIAN_API_TOKEN`

The `ATLASSIAN_*` values may come from the shell environment or a `.env` file in the installed
agent-specific `scripts/` folder.

Optional:

- `ATLASSIAN_JIRA_BASE_URL`
- `ATLASSIAN_CONFLUENCE_BASE_URL`
- `ATLASSIAN_DEFAULT_PROJECT`
- `ATLASSIAN_DEFAULT_SPACE`

## Supported Commands

- `health`
- `jira-search`
- `jira-get`
- `jira-create`
- `jira-update`
- `jira-comment`
- `jira-transitions`
- `jira-transition`
- `conf-search`
- `conf-get`
- `conf-create`
- `conf-update`
- `conf-comment`
- `conf-children`
- `raw`

## Command Notes

- `health` validates local configuration, probes Jira and Confluence separately, and reports one
  product as unavailable without masking the other.
- `jira-create` requires `--type`, `--summary`, and either `--project` or `ATLASSIAN_DEFAULT_PROJECT`.
- `jira-update` requires `--issue` and at least one of `--summary` or `--description-file`.
- `conf-create` requires `--title`, `--body-file`, and either `--space` or `ATLASSIAN_DEFAULT_SPACE`.
- `conf-update` requires `--page`, `--title`, and `--body-file`; it fetches the current page
  version before building the update payload.
- `raw --body-file` expects a workspace-scoped JSON file and is limited to validated Atlassian
  API prefixes.

## Safety Model

- Default output is JSON.
- Mutating commands support `--dry-run`.
- Jira long-text fields are converted to ADF locally.
- Confluence page writes are storage-first in v1.
- `raw` is restricted to `GET|POST|PUT`.
- `--body-file` must stay within the active workspace.

## Install

### Codex

```bash
mkdir -p ~/.codex/skills/atlassian
cp -R skills/atlassian/codex/* ~/.codex/skills/atlassian/
cd ~/.codex/skills/atlassian/scripts
pnpm install
```

### Claude Code

```bash
mkdir -p ~/.claude/skills/atlassian
cp -R skills/atlassian/claude-code/* ~/.claude/skills/atlassian/
cd ~/.claude/skills/atlassian/scripts
pnpm install
```

### OpenCode

```bash
mkdir -p ~/.config/opencode/skills/atlassian
cp -R skills/atlassian/opencode/* ~/.config/opencode/skills/atlassian/
cd ~/.config/opencode/skills/atlassian/scripts
pnpm install
```

### Cursor

Repo-local install:

```bash
mkdir -p .cursor/skills/atlassian
cp -R skills/atlassian/cursor/* .cursor/skills/atlassian/
cd .cursor/skills/atlassian/scripts
pnpm install
```

Global install:

```bash
mkdir -p ~/.cursor/skills/atlassian
cp -R skills/atlassian/cursor/* ~/.cursor/skills/atlassian/
cd ~/.cursor/skills/atlassian/scripts
pnpm install
```

### Pi

Recommended full Pi package install:

```bash
./scripts/install-pi-package.sh --global
# or, for project-local Pi package install
./scripts/install-pi-package.sh --local
```

Manual single-skill Pi install from the package mirror:

```bash
pnpm run sync:pi
mkdir -p .pi/skills/atlassian
cp -R pi-package/skills/atlassian/* .pi/skills/atlassian/
cd .pi/skills/atlassian/scripts
pnpm install --frozen-lockfile
```

Global manual installs use `~/.pi/agent/skills/atlassian/` instead of `.pi/skills/atlassian/`.

## Verify Installation

Run in the installed `scripts/` folder:

```bash
node -e "require.resolve('commander');require.resolve('dotenv');console.log('OK: runtime dependencies installed')"
node -e 'require("dotenv").config({ path: ".env" }); const required = ["ATLASSIAN_BASE_URL", "ATLASSIAN_EMAIL", "ATLASSIAN_API_TOKEN"]; const missing = required.filter((key) => !(process.env[key] || "").trim()); if (missing.length) { console.error("Missing required Atlassian config: " + missing.join(", ")); process.exit(1); } console.log("OK: Atlassian config present")'
pnpm atlassian health
```

## Usage Examples

- Search Jira issues:
  - `pnpm atlassian jira-search --jql "project = ENG ORDER BY updated DESC" --max-results 25`
- Inspect an issue:
  - `pnpm atlassian jira-get --issue ENG-123`
- Dry-run a Jira comment:
  - `pnpm atlassian jira-comment --issue ENG-123 --body-file comment.md --dry-run`
- Dry-run a Jira issue create with default project fallback:
  - `pnpm atlassian jira-create --type Story --summary "Add Atlassian skill" --description-file story.md --dry-run`
- Search Confluence pages:
  - `pnpm atlassian conf-search --query "title ~ \\\"Runbook\\\"" --max-results 10 --start-at 0`
- Inspect a Confluence page:
  - `pnpm atlassian conf-get --page 12345`
- Dry-run a Confluence page update:
  - `pnpm atlassian conf-update --page 12345 --title "Runbook" --body-file page.storage.html --dry-run`
- Dry-run a Confluence footer comment:
  - `pnpm atlassian conf-comment --page 12345 --body-file comment.storage.html --dry-run`
- Use bounded raw mode:
  - `pnpm atlassian raw --product jira --method GET --path "/rest/api/3/issue/ENG-123"`
  - `pnpm atlassian raw --product confluence --method POST --path "/wiki/api/v2/pages" --body-file page.json --dry-run`

## Scope Notes

- Atlassian Cloud is first-class in v1.
- Data Center support is future work.
- Full `mcp-atlassian` parity is not the goal in v1; the initial scope is the approved core workflow set above.