@hidden-leaf/atlassian-skill

Open infrastructure for AI-native software teams.

What It Does

A unified Atlassian integration layer for AI-driven software development lifecycle automation.

Programmatic Atlassian access -- typed clients for Jira, Confluence, and Bitbucket Cloud APIs with built-in auth, retry, and rate limiting.
SDLC orchestration primitives -- branch naming, changelog generation, PR descriptions, and workflow transitions derived from Jira context.
Session capture and archival -- record development sessions and persist transcripts to Confluence pages or Jira comments.
Autonomous planning and triage -- sprint planning utilities and issue triage with categorization, duplicate detection, and assignee suggestions.

Key Features

Jira

Full Jira Cloud REST API v3 and Agile API coverage:

Issue CRUD (getIssue, createIssue, updateIssue, deleteIssue)
JQL query builder with composable, type-safe API
Sprint and board management (getSprint, getSprintIssues, moveIssuesToSprint)
Workflow transitions (getTransitions, transitionIssue)
Comments, labels, assignees, projects, users

Confluence

Confluence Cloud API v2 client:

Page lifecycle (createPage, getPage, updatePage, deletePage)
Space operations (listSpaces, getSpace, getSpaceByKey)
CQL search (searchByCQL)
Documentation sync -- push local Markdown files to Confluence as ADF
ADF document builder for structured content creation

Bitbucket

Bitbucket Cloud REST API v2 client with pull request operations:

PR lifecycle (createPullRequest, mergePullRequest, approvePullRequest, declinePullRequest)
Code review workflow (requestChanges, addReviewers, addPRComment)
Diff and diffstat retrieval (getPRDiff, getPRDiffStat)
Pagination helpers (getAllPages, getPage)

Orchestration

Convention-driven SDLC automation:

Branch naming from Jira issues (generateBranchName, generateReleaseBranchName)
Changelog generation from issue lists (generateChangelog, generateReleaseNotes)
PR description generation with diff analysis (generatePRDescription, generatePRTitle, analyzeDiff)
Branch validation and parsing (validateBranchName, parseBranchName, extractIssueKeyFromBranch)

Session Capture

Development session recording and archival:

Event capture (startSession, captureUserMessage, captureToolUse, captureFileOperation)
Transcript archival to Confluence or Jira (SessionArchiver.archive)
Configurable redaction patterns for sensitive data

Autonomous

Sprint planning and issue triage:

SprintPlanner -- velocity analysis, scope suggestions, risk assessment, sprint health reports
IssueTriage -- duplicate detection, priority recommendations, assignee suggestions

Quick Start

Install

npm install @hidden-leaf/atlassian-skill

Configure

Set your Atlassian credentials as environment variables:

export ATLASSIAN_CLOUD_ID=your-cloud-id
export ATLASSIAN_SITE_URL=https://your-domain.atlassian.net
export ATLASSIAN_USER_EMAIL=your-email@company.com
export ATLASSIAN_API_TOKEN=your-api-token

Use

import { createJiraClientFromEnv, jql, JqlFunctions } from '@hidden-leaf/atlassian-skill';

const client = createJiraClientFromEnv();

// Build a JQL query
const query = jql()
  .equals('project', 'ENG')
  .in('status', ['To Do', 'In Progress'])
  .equals('assignee', JqlFunctions.currentUser())
  .orderBy('priority', 'DESC')
  .build();

const results = await client.searchIssues({ jql: query });

// Create an issue
const issue = await client.createIssue({
  project: 'ENG',
  issuetype: 'Bug',
  summary: 'Fix login flow error',
  priority: 'High',
  labels: ['bug', 'auth'],
});

Usage Examples

Search and transition a Jira issue

import { createJiraClientFromEnv } from '@hidden-leaf/atlassian-skill';

const jira = createJiraClientFromEnv();

const issue = await jira.getIssue('ENG-452');
const transitions = await jira.getTransitions('ENG-452');

const inProgress = transitions.find(t => t.name === 'In Progress');
if (inProgress) {
  await jira.transitionIssue('ENG-452', {
    transitionId: inProgress.id,
    comment: { body: 'Starting work on this.' },
  });
}

Create a pull request with a generated description

import {
  BitbucketClient,
  PullRequestOperations,
  generatePRDescription,
  generateBranchName,
} from '@hidden-leaf/atlassian-skill';

const bb = new BitbucketClient({
  auth: { accessToken: process.env.BITBUCKET_ACCESS_TOKEN! },
});
const prs = new PullRequestOperations(bb);

const description = generatePRDescription(issue, {
  template: 'standard',
  includeJiraContext: true,
  includeChecklist: true,
  jiraBaseUrl: 'https://your-domain.atlassian.net',
});

await prs.createPullRequest('acme', 'my-repo', {
  title: `ENG-452: ${issue.fields.summary}`,
  source: { branch: { name: 'feature/ENG-452-fix-login' } },
  destination: { branch: { name: 'main' } },
  description: description.body,
  close_source_branch: true,
});

Sync documentation to Confluence

import { ConfluenceClient, DocumentationSyncService } from '@hidden-leaf/atlassian-skill';

const confluence = new ConfluenceClient({
  cloudId: process.env.ATLASSIAN_CLOUD_ID!,
  accessToken: process.env.ATLASSIAN_ACCESS_TOKEN!,
});

const sync = new DocumentationSyncService(confluence);
const result = await sync.syncReadmeToConfluence('/path/to/repo', 'space-id', 'parent-page-id');

if (result.success) {
  console.log(`Synced: ${result.updated.length} updated, ${result.created.length} created`);
}

Capture and archive a session

import { SessionCapture, SessionArchiver } from '@hidden-leaf/atlassian-skill';

const capture = new SessionCapture();
capture.startSession({ projectName: 'My Project' });

capture.captureUserMessage('Fix the auth bug in login flow');
capture.captureToolUse('Read', 'tool-1', { file_path: '/src/auth.ts' });
capture.captureFileOperation('edit', '/src/auth.ts', true, 15);

const transcript = capture.endSession('Fixed authentication flow');

const archiver = new SessionArchiver();
await archiver.archive(transcript, {
  destination: 'confluence',
  confluenceSpaceKey: 'ENG',
  format: 'full',
  includeFullTranscript: true,
});

API Reference

Clients

Class	Description
`JiraClient`	Jira Cloud REST API v3 + Agile API
`ConfluenceClient`	Confluence Cloud API v2
`BitbucketClient`	Bitbucket Cloud REST API v2
`PullRequestOperations`	PR lifecycle operations (wraps `BitbucketClient`)

Builders

Class / Function	Description
`JqlBuilder` / `jql()`	Composable JQL query builder
`AdfBuilder` / `adf()`	Atlassian Document Format builder
`TextBuilder` / `text()`	Inline text builder with marks
`JqlFunctions`	JQL function helpers (`currentUser()`, etc.)
`JqlTemplates`	Pre-built JQL query templates

Orchestration

Function	Description
`generateBranchName(issue, options?)`	Branch name from Jira issue
`generateChangelog(issues, options?)`	Changelog from issue list
`generateReleaseNotes(issues, version, options?)`	Release notes
`generatePRDescription(issue, options?)`	PR description with context
`generatePRTitle(issue)`	PR title from issue
`analyzeDiff(diff)`	Diff analysis summary
`extractIssueKeyFromBranch(branchName)`	Extract Jira key from branch
`validateBranchName(branchName)`	Validate branch conventions
`parseBranchName(branchName)`	Parse branch into components

Autonomous

Class	Description
`SprintPlanner`	Velocity analysis, scope suggestions, risk assessment, health reports
`IssueTriage`	Duplicate detection, priority/assignee recommendations

Session

Class	Description
`SessionCapture`	Event recording for development sessions
`SessionArchiver`	Persist transcripts to Confluence/Jira

Auth and Utilities

Export	Description
`createJiraClientFromEnv()`	Factory: Jira client from env vars
`createClientFromEnv()`	Factory: base Atlassian client from env vars
`createAuthFromEnv()`	Factory: auth config from env vars
`RateLimiter`	Configurable rate limiter
`Logger` / `createLogger()`	Structured logger
`markdownToAdf(md)`	Convert Markdown to ADF
`adfToText(doc)`	Convert ADF to plain text

Configuration

Environment Variables

Variable	Required	Description
`ATLASSIAN_CLOUD_ID`	Yes	Your Atlassian Cloud ID
`ATLASSIAN_SITE_URL`	Yes	Site URL (e.g., `https://acme.atlassian.net`)
`ATLASSIAN_USER_EMAIL`	For API token auth	Account email
`ATLASSIAN_API_TOKEN`	For API token auth	API token
`ATLASSIAN_CLIENT_ID`	For OAuth	OAuth client ID
`ATLASSIAN_CLIENT_SECRET`	For OAuth	OAuth client secret
`ATLASSIAN_ACCESS_TOKEN`	For OAuth	OAuth access token
`ATLASSIAN_REFRESH_TOKEN`	For OAuth	OAuth refresh token
`ATLASSIAN_REDIRECT_URI`	For OAuth	OAuth redirect URI
`SESSION_CAPTURE_ENABLED`	No	Enable session capture (`true`/`false`)
`SESSION_CAPTURE_MODE`	No	Capture mode (`full`/`summary`)
`SESSION_AUTO_ARCHIVE`	No	Auto-archive on session end

Getting Your Cloud ID

Navigate to your Atlassian site (e.g., https://your-domain.atlassian.net).
Open browser developer tools and run window._siteConfig?.cloudId.

Creating an API Token

Go to https://id.atlassian.com/manage-profile/security/api-tokens.
Create a token and store it securely.

Known Limitations

Jira Workflow Lock (ATLSK-62): Jira Cloud's POST /workflows/update endpoint may return a 409 "workflow lock" error tenant-wide. This is a platform bug with no API workaround. Use ProjectReset to recreate the project, or configure board columns manually via the Jira UI.
Workflow Creation: POST /workflows/create has an undocumented links format that prevents workflow creation via API. Use Jira UI for initial workflow setup.
Rate Limits: The client respects Atlassian's 65,000 points/hour rate limit with automatic backoff, but high-volume batch operations may still hit limits.

Enterprise

For enterprise features including multi-model orchestration, analytics dashboards, team memory, and workflow governance, contact Hidden Leaf Networks.

Contact us

Contributing

See CONTRIBUTING.md for guidelines on setting up a development environment, running tests, and submitting pull requests.

License

MIT -- Built by Hidden Leaf Networks.

Part of HLN's AI infrastructure ecosystem.

Name		Name	Last commit message	Last commit date
Latest commit History 24 Commits
.github/workflows		.github/workflows
scripts		scripts
src		src
.env.example		.env.example
.env.template		.env.template
.eslintrc.json		.eslintrc.json
.gitignore		.gitignore
CHANGELOG.md		CHANGELOG.md
CLAUDE.md		CLAUDE.md
CLAUDE.snippet.md		CLAUDE.snippet.md
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
NOTICE		NOTICE
README.md		README.md
SKILL.md		SKILL.md
jest.config.js		jest.config.js
jira-skill-feasibility-report.md		jira-skill-feasibility-report.md
package-lock.json		package-lock.json
package.json		package.json
tsconfig.eslint.json		tsconfig.eslint.json
tsconfig.json		tsconfig.json

Folders and files

Latest commit

History

Repository files navigation

@hidden-leaf/atlassian-skill

What It Does

Key Features

Jira

Confluence

Bitbucket

Orchestration

Session Capture

Autonomous

Quick Start

Install

Configure

Use

Usage Examples

Search and transition a Jira issue

Create a pull request with a generated description

Sync documentation to Confluence

Capture and archive a session

API Reference

Clients

Builders

Orchestration

Autonomous

Session

Auth and Utilities

Configuration

Environment Variables

Getting Your Cloud ID

Creating an API Token

Known Limitations

Enterprise

Contributing

License

About

Topics

Resources

License

Contributing

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages