--- id: SPEC title: "@cleepi/atlassian" status: accepted created: 2026-05-24 accepted: 2026-06-02 owner: Honza related: - ../../docs/specs/0003-cleepi-atlassian-v0.1.0-mcp.md - ../../docs/adr/0005-mcp-adapter-over-native-atlassian-client.md - ../../docs/adr/0006-allow-writes-in-atlassian-v0.1.0.md - ../../docs/DRAFT-004-natural-language-ticket-flow/spec.md - ../sdd/SPEC.md --- # Spec: `@cleepi/atlassian` ## Problem Cleevians who use pi + `@cleepi/sdd` to drive non-trivial work start almost every task from a Jira ticket (and often linked Confluence pages). Today that means copy/pasting the summary, description, and a guessed-at subset of comments into pi. The pasted context is lossy ("boring" fields like acceptance criteria get skipped) and inconsistent across Cleevians. Specs built on half-pasted tickets are specs built on partial requirements. This package closes that gap as a layer of taste — a curated skill and a slash prompt — on top of Atlassian's Rovo MCP server (the real plumbing) and [`pi-mcp-adapter`](https://github.com/nicobailon/pi-mcp-adapter) (the thing that lets pi speak MCP). ## What this package is - A **skill** that teaches the agent which Jira/Confluence fields map to which spec sections, what to ignore (status churn, bot comments, sprint metadata), and how to degrade honestly when context is missing. - A **slash prompt** `/spec-from-ticket ` that fetches the ticket, optionally fetches up to 3 linked Confluence pages, and hands off to `/spec` when `@cleepi/sdd` is loaded — or to a structured manual printout when it isn't (soft-aware, same pattern as `@cleepi/coding`). - A **copy/paste MCP config snippet** (`mcp.example.json`) that wires the Atlassian Rovo MCP server into pi via pi-mcp-adapter with OAuth and a curated `directTools` allowlist covering both read tools (for ticket context) and the useful Jira writes (create / edit / transition / comment). The pi-mcp-adapter proxy is enabled so power users can reach further when needed. ## What this package is not - **Not an HTTP client, OAuth implementation, or ADF→Markdown converter.** All of that is delegated to Atlassian's Rovo MCP server and pi-mcp-adapter. See [ADR 0005](../../docs/adr/0005-mcp-adapter-over-native-atlassian-client.md) for why we pivoted away from native and what we accept as the cost. - **Not the place where Jira write *safety* is enforced.** Per [ADR 0006](../../docs/adr/0006-allow-writes-in-atlassian-v0.1.0.md), v0.1.0 ships with Jira writes (`createJiraIssue`, `editJiraIssue`, `transitionJiraIssue`, `addCommentToJiraIssue`) in the curated allowlist. The authoritative gate is the org-admin permission-group toggle in *Atlassian Administration → Rovo MCP server*. If your organisation doesn't want writes via MCP, disable the `write_jira` / `write_confluence` permission groups there. This package does not duplicate that gate client-side. - **Not write-heavy.** The primary endorsed workflow is `/spec-from-ticket` (read → draft). Confluence page creation, worklogs, bulk transitions, and Compass writes are reachable via pi-mcp-adapter's `mcp` proxy but not promoted via `directTools`. Dedicated write-back prompts (e.g. `/comment-spec-link `) are follow-up specs, not v0.1.0 deliverables. - **Not a JQL/CQL search workflow.** `searchJiraIssuesUsingJql` is in the allowlist as a cheap convenience, but the curated workflows this package endorses target one known ticket at a time. - **Not Server / Data Center compatible.** Atlassian's remote MCP is Cloud-only. - **Not a wrapper for the adapter.** `pi-mcp-adapter` is a peer install the user does themselves. We document, we don't bundle. - **Not a generic Atlassian SDK.** Power users can reach further via the MCP server, but this package's curated surface is the spec-from-ticket workflow. ## Decision Three decisions ground this package; full history lives in the linked ADRs (kept as archive under the v0.1.x convention). ### MCP adapter over native Atlassian client We chose **Atlassian's Rovo MCP server via `pi-mcp-adapter`** over a native HTTP/OAuth/ADF implementation. Native would mean owning an HTTP client, OAuth flows, ADF→Markdown conversion, credential storage, and a per-endpoint error matrix. MCP eliminates all of that: pi-mcp-adapter handles transport + auth, the Rovo server handles the API + ADF rendering, and this package becomes a thin config+skill+prompt layer. Cost we accept: Cloud-only (no Server / Data Center), and dependence on Atlassian's MCP roadmap. See [ADR 0005](../../docs/adr/0005-mcp-adapter-over-native-atlassian-client.md). ### Allow Jira writes in v0.1.0 We chose to **ship with Jira writes (`createJiraIssue`, `editJiraIssue`, `transitionJiraIssue`, `addCommentToJiraIssue`) in the `directTools` allowlist**, trusting Atlassian's org-admin permission groups as the authoritative safety gate, rather than duplicating that gate client-side. Phase-4 smoke-testing showed the write-back loop (post a spec link as a comment, transition the ticket) is the highest-leverage workflow on top of `/spec-from-ticket`. Cost we accept: orgs that *don't* want writes must disable the `write_jira` permission group in *Atlassian Administration → Rovo MCP server*. See [ADR 0006](../../docs/adr/0006-allow-writes-in-atlassian-v0.1.0.md). ### Self-tiering `/spec-from-ticket` (easy vs hard) We chose to make **`/spec-from-ticket` decide between a direct `/spec` handoff (easy) and a `/spec-with-crew` handoff (hard) using five explicit criteria** (single-package scope, AC present, ≤1 Confluence page, no "design/refactor" vocabulary, estimate ≤~1 day). Alternatives: ship two prompts and make the user pick (rejected — forces the user to make the call before they've read the ticket); always go through the crew (rejected — overkill for a one-line bug-fix ticket, burns subagent budget); always direct (rejected — misses the historian/scout pass that makes hard tickets worth specing). The tier decision is the agent's judgment, not a regex; manual `--with-crew` / `--simple` overrides exist. See DRAFT-004 for the dispatch context. ## Design at a glance See [spec 0003](../../docs/specs/0003-cleepi-atlassian-v0.1.0-mcp.md) for the full v0.1.0 design, including the exact `mcp.example.json`, the upstream tool inventory, and the resolved/open-question list. ``` packages/atlassian/ package.json # pi manifest: skills + prompts (no extensions) README.md # install, admin one-time setup, troubleshooting SPEC.md # this file CHANGELOG.md mcp.example.json # copy/paste into your .mcp.json docs/ specs/ # package-scope feature specs (future) adr/ # package-scope ADRs (future) skills/ atlassian/ SKILL.md # what to extract, what to ignore (Phase 2) prompts/ spec-from-ticket.md # /spec-from-ticket (Phase 3) ``` ## Related - [Spec 0003](../../docs/specs/0003-cleepi-atlassian-v0.1.0-mcp.md) — v0.1.0 implementation spec (accepted). - [Spec 0002](../../docs/specs/0002-cleepi-atlassian-v0.1.0.md) — superseded native-client plan, kept for history. - [ADR 0005](../../docs/adr/0005-mcp-adapter-over-native-atlassian-client.md) — why MCP over native. - [CHANGELOG.md](./CHANGELOG.md) — release history.