inovagio-atlassian 0.1.0

Standalone, zero-pip-dep Python 3.12+ CLI for Atlassian operations and AI-agent-driven autonomous development workflows

atlassiancli

A standalone, pip-installable Python 3.12+ CLI for Jira and Confluence with zero runtime dependencies and a stable JSON / exit-code contract that makes it safe to drive from AI coding agents. Engineers use it interactively for daily Atlassian work; autonomous-development agents use it as the ticket-to-PR control surface.

Why atlassiancli

Most Atlassian tooling falls into one of two traps. Either it lives inside one organisation's monorepo and is non-portable, or it pulls a tower of PyPI packages that fight every other project's pinning policy. atlassiancli avoids both:

• Drop-in portable. Copy src/atlassiancli/ into any repo, or pip install it — same behaviour, no project-specific assumptions baked into the source.
• Stdlib-only at runtime. Python 3.12 standard library is the only dependency. No requests, no pyyaml, no python-dotenv — the CLI ships its own minimal HTTP client, YAML codec, and .env loader. CI images and air-gapped environments install instantly.
• Designed to be machine-driven. Every analyse / write subcommand emits a stable AgentResponse JSON envelope under --json, follows a fixed exit-code contract (0 / 1 / 2 / 75 / 77), and is idempotent on retry. Agents and CI loops can branch on results without parsing prose.
• Cleanly extensible. A DDD-layered Python package (domain / application / infrastructure / cli) keeps adapters swappable and tests fast.

Two ways to use it

As an engineer's CLI. Create epics and stories, transition workflow, balance sprints, run quality / velocity / health reports, push markdown to Confluence, link PRs back to issues. One tool covers most of what you'd otherwise stitch together from acli, scripts, and the Jira UI.

As agent-callable infrastructure. Wire it into an autonomous-development loop — the kind of system where an AI coding agent picks an unassigned story, runs a Definition-of-Ready gate, marks the story in-progress, opens a PR, and transitions to Done. The JSON envelope and idempotency guarantees exist to make that loop safe. See docs/AGENT_INTEGRATION.md for the full contract.

Capability tiers

Tier	What it does	Agent-callable
1. Atlassian basics	Create / transition / assign / comment issues; sprint operations (current, stories, move, balance, split); Confluence page CRUD; markdown-to-Confluence import; quality / velocity / themes / health reports.	Yes — write commands are idempotent.
2. Story analysis + enhancement	analyze lint (0–100 score against the 11-section AI-implementable schema), analyze atomicity (5-criteria PR-sized check), analyze ready (composite Definition-of-Ready gate), analyze description / architecture / fetch, enhance (review-then-apply), template (story / epic scaffolds).	Yes — primary agent surface.
3. Doc framework bridge	framework create-stories, verify-stories, reverse-sync, sync-docs — manifest-driven Jira sync from per-product YAML under docs/<product>/stories/manifests/, plus repo-markdown to Confluence.	Yes — every subcommand supports --json.
4. Project bootstrap	framework bootstrap --product <handle> validates a product's configured-state (.docframework.yaml, credentials, hub page, epics) so a new project can adopt the framework cleanly.	Read-only validation.

The full subcommand surface is in docs/USAGE.md. The end-to-end agent contract — JSON schema, exit codes, idempotency rules, canonical invocation patterns — is in docs/AGENT_INTEGRATION.md.

Quick start

Five minutes from zero to a working setup.

1. Install

# From PyPI (once published):
pip install inovagio-atlassian

# Or from a clone, for development:
git clone https://github.com/inovagio/atlassiancli.git
cd atlassiancli
pip install -e ".[dev]"

Requires Python 3.12 or newer. Runtime install pulls zero third-party packages. The optional dev extra adds ruff, build, twine, mypy, and pytest for contributors.

Naming note. The PyPI package is inovagio-atlassian; the installed binary command is atlassiancli. So pip install inovagio-atlassian gives you atlassiancli --version on your PATH. The split exists because PyPI's name normalizer treats atlassiancli and the already-taken atlassian-cli as the same canonical name.

2. Configure

Set credentials via environment variables (preferred for CI):

export ATLASSIAN_EMAIL=[e-mail]
export ATLASSIAN_TOKEN=<atlassian api token>
export ATLASSIAN_SITE=<your-site>.atlassian.net

A .env file at the project root works too — atlassiancli's stdlib .env loader picks it up automatically. Get an API token at id.atlassian.com under Profile -> Security -> API tokens.

3. Verify

atlassiancli --version                         # confirms install
atlassiancli template story                    # confirms the rule engine
atlassiancli --json sprint current --board 42  # confirms auth + transport

If the third command returns a parseable JSON envelope, you're done.

4. First real commands

# Find the active sprint and pick the highest-priority unassigned story
atlassiancli --json sprint current --board 42
atlassiancli --json sprint stories --sprint <id> --unassigned --priority-order

# Run the Definition-of-Ready gate against a story
atlassiancli --json analyze ready PROJ-247

# Lint a story's quality score against the 11-section schema
atlassiancli analyze lint PROJ-247

# Verify per-product YAML manifests against Jira (doc-framework users)
atlassiancli framework verify-stories --product myproduct

For the full install walkthrough — auth troubleshooting, optional GitHub Actions / pre-commit / cron integrations — see docs/INSTALL.md.

Use cases

Engineer driving daily Atlassian operations

You've just cut a feature branch and want to wire it to a Jira story without leaving the terminal:

# Pick up a sprint story
atlassiancli transition PROJ-247 --to "In Progress" --execute
atlassiancli assign PROJ-247 --user [e-mail]

# When the PR is up
atlassiancli link-pr PROJ-247 --pr-url https://github.com/org/repo/pull/123
atlassiancli comment PROJ-247 --body "PR opened — ready for review"

# End of sprint: pull the quality + velocity rollup
atlassiancli report quality  --project PROJ
atlassiancli report velocity --board 42

No clicking through screens, no tab-juggling, no shell scripts wrapping curl.

AI coding agent driving an autonomous ticket-to-PR cycle

An autonomous-development agent uses atlassiancli as the Jira / Confluence control surface. The whole loop is JSON in, JSON out:

# Phase 1 — fetch sprint item
atlassiancli --json sprint current --board 42
atlassiancli --json sprint stories --sprint $SPRINT --unassigned --priority-order

# Phase 2 — validate against the Definition-of-Ready gate
atlassiancli --json analyze ready $ISSUE
# verdict == "READY"  → continue
# verdict == "NOT_READY" → halt, surface findings to operator

# Phase 3 — claim the story (all idempotent on retry)
atlassiancli transition $ISSUE --to "In Progress" --execute
atlassiancli assign $ISSUE --user "$ATLASSIAN_EMAIL"
atlassiancli comment $ISSUE --body "Run id: $RUN_ID" --idempotency-key "$RUN_ID"

# ... agent writes code, opens PR ...

# Phase 4 — close out
atlassiancli transition $ISSUE --to "Done" --execute
atlassiancli link-pr    $ISSUE --pr-url "$PR_URL"

Exit codes drive the agent's state machine: 0 proceeds, 75 retries with backoff, 77 halts on auth, 1 surfaces the finding to the operator. Idempotent writes mean the agent can be killed and restarted at any point without producing duplicate comments, transitions, or PR links.

Differentiators

• Zero pip dependencies at runtime. pyproject.toml dependencies = []. Matters when you're shipping into hardened CI images, air-gapped environments, or codebases with strict supply-chain rules.
• JSON output + exit-code contract. Every analyse / write subcommand emits the same AgentResponse envelope on stdout and returns one of five documented exit codes (0 / 1 / 2 / 75 / 77). Schemas and fixtures in docs/AGENT_INTEGRATION.md.
• Project-agnostic + copy-deployable. No Jira project keys, Confluence ids, or label namespaces hardcoded in source. Per-project config lives in .atlassiancli.yaml; per-product framework config in docs/<product>/.docframework.yaml. cp -R src/atlassiancli/ <target>/ is a supported deployment path.
• DDD-layered architecture. domain / application / infrastructure / cli boundaries are enforced; tests substitute alternate adapters at any layer. See docs/ARCHITECTURE.md.
• Idempotent writes. transition, assign, comment (with --idempotency-key), link-pr, and every framework subcommand are safe to replay.

Documentation

Doc	What's in it
docs/USAGE.md	Every subcommand with arguments and examples
docs/INSTALL.md	Install, auth, troubleshooting, optional CI / pre-commit / cron integrations
docs/AGENT_INTEGRATION.md	JSON schema, exit-code contract, idempotency rules, canonical invocation patterns
docs/RUNBOOK.md	Operational procedures: setup, daily flows, doc-framework operations, gotchas, verification gates
docs/ARCHITECTURE.md	DDD layered overview
docs/EXAMPLES/	Runnable starter projects: Jira-only, doc-framework, agent-driven workflow
PLAN.md	Vision, four-tier capability map, configuration model, build-out history
CHANGELOG.md	Release notes
CONTRIBUTING.md	Dev setup, test runner choices, lint conventions

Project status

Version 0.1.0 — initial release. The full subcommand surface across all four tiers is shipped and tested; the agent-callable contract (JSON envelope + exit codes + idempotency) is stable. A small number of polish items (interactive configure wizard, multi-profile --profile switch) are tracked in CHANGELOG.md and PLAN §11.

Contributing

Issues and pull requests welcome. atlassiancli is intentionally small and focused — extensions live in the cli/handlers/ layer with corresponding domain / application services. See CONTRIBUTING.md for dev setup, the test runner matrix (stdlib unittest is the default; pytest runs the same tests unchanged), and lint conventions.

License

MIT — see LICENSE.