Atlassian ACLI + REST API Automation
Configuration Discovery
Before starting any workflow, gather these from the user or discover via CLI:
| Setting | How to get it | Store as |
|---|---|---|
| Site URL | Ask user for *.atlassian.net URL | {site} |
| Jira Project Key | Ask user, or acli jira project list | {projectKey} |
| Confluence Space | Ask user, or query REST API | {spaceKey} |
| Parent Page | Ask user, or use space root | {parentId} |
Always ask the user which project/space to use. Never assume defaults. Use --limit 10 for all Jira list operations and limit=10 for Confluence REST API calls.
Setup & Authentication
For full setup, API token generation, and troubleshooting, see setup.md.
Quick config — add a .env file to your project root:
ATLASSIAN_EMAIL="you@example.com"
ATLASSIAN_API_TOKEN="your-api-token-here"
ATLASSIAN_SITE="https://yoursite.atlassian.net"Install ACLI and authenticate:
brew tap atlassian/homebrew-acli && brew install acli
set -a; source .env; set +a
# ACLI expects the bare domain, not the full URL — strip the https:// prefix
ACLI_SITE="${ATLASSIAN_SITE#https://}"
acli jira auth login \
--site "$ACLI_SITE" \
--email "$ATLASSIAN_EMAIL" \
--token < <(echo "$ATLASSIAN_API_TOKEN")For Confluence, use the REST API via curl with basic auth:
curl -s -u "$ATLASSIAN_EMAIL:$ATLASSIAN_API_TOKEN" \
"$ATLASSIAN_SITE/wiki/rest/api/content" ...See reference/atlassian-helpers.sh for convenience shell functions.
For image upload configuration, see image-upload.md. For git branch integration (GitHub/Bitbucket), see git-integration.md. For Confluence comment operations, see confluence-comments.md.
Agentic Project Management Workflow
Full lifecycle project management using Jira + Confluence.
Execution Modes
This workflow supports two modes:
- Multi-Agent Mode (Claude Code with Agent Teams): Parallel execution with TeamCreate/TaskCreate orchestration. Requires
CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1in~/.claude/settings.json. - Single-Agent Mode (all agents): Sequential execution — one workstream at a time. Same Jira tracking and Confluence updates, no multi-agent dependencies.
Prerequisites
- ACLI installed and authenticated (Jira)
- API token configured in
.env(Confluence REST API) - For multi-agent mode: Claude Code with
CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1
The 4-Phase Cycle
Phase 1: INTAKE -> User describes request -> Confluence plan + Jira Epic
Phase 2: EXECUTE -> Agent team works tickets with Jira tracking
Phase 3: RESUME -> New session resumes from Jira state (fully autonomous)
Phase 4: COMPLETE -> All tickets Done -> Epic closed -> summary deliveredPhase 1: Intake & Planning
Classify the request, create Confluence plan page, Jira Epic with [AI-PM] prefix, child tickets per workstream, link dependencies, then present plan to user for confirmation.
See phase-planning.md for step-by-step details and templates.
Phase 2: Execution
Multi-agent mode: Create agent team, map tickets to tasks with dependency tracking, spawn teammates with standard prompt. Orchestrator monitors progress and updates Confluence plan page.
Single-agent mode: Work each ticket sequentially, respecting dependency order. Track progress via Jira transitions and Confluence updates.
See phase-execution.md for both modes (multi-agent and single-agent workflows). Both modes share common protocols for transitions, branch creation, and publishing — see common-patterns.md.
Phase 3: Resume
Auto-detect open [AI-PM] Epics, read Confluence plan, query incomplete tickets, classify state.
Multi-agent mode: Spin up right-sized team for remaining work. Single-agent mode: Pick up the next incomplete ticket and continue sequentially.
See phase-resume.md for both modes (resume protocol and JQL patterns).
Phase 4: Completion
Update Confluence page status, transition Epic to Done, add final summary comment, report deliverables to user.
See phase-completion.md for completion checklist.
Team Sizing (Multi-Agent Mode)
| Request Type | Team Size | Roles |
|---|---|---|
| Small change | 2 | lead + implementer |
| Feature dev | 3-4 | lead + backend + frontend + (tester) |
| Research | 3 | lead + 2 researchers |
| Content | 3 | lead + writer + reviewer |
| Multi-component | 4-5 | lead + 1 per component |
One ticket per teammate. Lead coordinates only (no workstream tasks). Min team = 2.
Key Constraints
[AI-PM]prefix on all managed Epics — the resume phase uses JQLsummary ~ "\\[AI-PM\\]"to auto-detect managed Epics.- One writer per resource — Confluence uses optimistic locking with version numbers. Concurrent writes cause version conflicts and data loss. Only one agent should update a given page/issue at a time.
--limit 10on all Jira list operations;limit=10on all Confluence REST calls — larger result sets consume excessive tokens.- Transition to In Progress when work starts — this signals to other agents (and the resume phase) that a ticket is actively being worked.
- Assign tickets when starting work — use
acli jira workitem edit --key {key} --assignee "@me". Unassigned tickets look abandoned during resume. - Publish findings as child pages of the plan page (using
parentId) — keeps all deliverables organized under one parent. - GET before PUT for Confluence — the REST API PUT replaces the entire body. Always read the current version first, then PUT with incremented version number. Also check for inline/footer comments before updating — users leave review feedback as comments.
- JQL
!=workaround — ACLI escapes!in JQL. UseNOT IN (Done)instead of!= Done. - JQL
[/]escaping — square brackets are JQL range-query operators. Use\[AI-PM\](escaped) insummary ~queries, not[AI-PM]. - Confluence search uses v1 API — CQL search for pages must use
/wiki/rest/api/content/search, not v2/search. - Comment replies use v1 API — creating threaded replies requires
POST /wiki/rest/api/contentwithancestorsarray. The v2 children endpoint returns 405. See confluence-comments.md.