Metadata-Version: 2.4
Name: inovagio-atlassian
Version: 0.2.0
Summary: Standalone, zero-pip-dep Python 3.12+ CLI for Atlassian operations and AI-agent-driven autonomous development workflows
Author-email: Inovagio <engineering@inovagio.com>
Maintainer-email: Inovagio <engineering@inovagio.com>
License-Expression: MIT
Project-URL: Homepage, https://github.com/inovagio/atlassiancli
Project-URL: Documentation, https://github.com/inovagio/atlassiancli/blob/main/docs/USAGE.md
Project-URL: Repository, https://github.com/inovagio/atlassiancli
Project-URL: Issues, https://github.com/inovagio/atlassiancli/issues
Project-URL: Changelog, https://github.com/inovagio/atlassiancli/blob/main/CHANGELOG.md
Keywords: atlassian,jira,confluence,cli,agent,ai-agent,autonomous-development,story-quality,doc-framework
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Topic :: Software Development
Classifier: Topic :: Software Development :: Documentation
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Software Development :: Quality Assurance
Classifier: Topic :: Software Development :: Version Control
Classifier: Topic :: Utilities
Classifier: Typing :: Typed
Requires-Python: >=3.12
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: dev
Requires-Dist: ruff>=0.5; extra == "dev"
Requires-Dist: build>=1.2; extra == "dev"
Requires-Dist: twine>=5.0; extra == "dev"
Requires-Dist: mypy>=1.10; extra == "dev"
Requires-Dist: pytest>=7.0; extra == "dev"
Dynamic: license-file

# inovagio-atlassian

[![Python](https://img.shields.io/badge/python-3.12%2B-blue.svg)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
[![CI](https://github.com/inovagio/atlassiancli/actions/workflows/ci.yml/badge.svg)](https://github.com/inovagio/atlassiancli/actions/workflows/ci.yml)
[![PyPI](https://img.shields.io/pypi/v/inovagio-atlassian.svg)](https://pypi.org/project/inovagio-atlassian/)
[![Python versions](https://img.shields.io/pypi/pyversions/inovagio-atlassian.svg)](https://pypi.org/project/inovagio-atlassian/)

> **DevCycle** is an autonomous AI-agent development system: agent picks a sprint story, validates it, implements it, gates it against architecture / security / code-quality SOPs, and ships a PR — without bypassing checks. This repo packages the system: agent prompt, SOPs, and the CLI that bridges them to Jira and Confluence.

```bash
pip install inovagio-atlassian
atlassiancli framework bootstrap --product myproduct       # installs the system
# ... open VS Code, then in Copilot Chat:
# @devcycle auto                                            # run the system
```

After `framework bootstrap`, your daily surface is **a single Copilot command**: `@devcycle auto`. You don't type CLI subcommands during the agent loop — the agent invokes them for you at every Atlassian / Confluence / SOP-enforcement boundary.

The installed binary is `atlassiancli`; the PyPI package is `inovagio-atlassian` ([why](docs/RELEASE.md#names--mind-the-three-way-split)).

---

## What DevCycle is

A verifiable, gated workflow that turns Jira stories into PRs autonomously. **Three components compose into one system:**

```
        ┌─────────────────────────────────────────────────────────────┐
        │     Component 1: The Copilot Agent (the state machine)      │
        │  .github/agents/DevCycle.agent.md — 8 phases, blocking gate │
        │  at Phase 6, escalation protocol, durable state in .vscode/ │
        └─────────────────────────────────────────────────────────────┘
                              ▲                       │
                              │ enforces              │ invokes
                              │                       ▼
        ┌─────────────────────────────────────┐  ┌─────────────────────────────────────┐
        │   Component 2: The SOPs (rules)     │  │  Component 3: The CLI (the bridge)  │
        │  Architecture · Security · Quality  │  │  inovagio-atlassian                 │
        │  Testing · Logging · Monitoring     │  │  Reaches Jira / Confluence /        │
        │  Stack-tuned, in docs/<product>/sops│  │  SOP-enforcement engine             │
        └─────────────────────────────────────┘  └─────────────────────────────────────┘
                                                            │
                                                            │ falls back to
                                                            ▼
                                              ┌──────────────────────────────────┐
                                              │  Atlassian MCP (read-only ops)   │
                                              └──────────────────────────────────┘
```

Each component has a job and **none of them work alone**:

| Component | Job | What you'd lose without it |
|---|---|---|
| **Copilot Agent** | Orchestrates the 8-phase state machine. Decides what runs when. Blocks Phase 8 (PR creation) if Phase 6 (review) fails. | The autonomous loop itself. You'd be back to driving every step manually. |
| **SOPs** | The rules every gate enforces. Pre-commit hooks, the Phase 6 gate, and CI all read from the same SOP manifest. | The "verifiable" part. Without rules to check against, the agent is just confident vibe-coding. |
| **CLI** | Bridges the agent to Jira (sprint queries, transitions, comments, link-pr), Confluence (page CRUD, doc sync), and the SOP enforcement engine (`analyze sop`, `framework sop-commit-gate`, the unified `review` gate). | The agent loses reliable access to Jira/Confluence/enforcement. MCP can substitute for some Atlassian *reads*, but times out on long-running write workflows and doesn't enforce SOPs. |

A typical run from a developer's perspective:

```
Sprint Backlog (Jira)  ─►  @devcycle auto  ─►  PR Open + Jira Done  ─►  next ticket
```

That's the entire user-facing surface. Everything else — fetching the right story, validating it against the Definition of Ready, transitioning Jira state, running the architecture / security / code-quality gates, opening the PR — is the agent calling the CLI on your behalf.

---

## Why DevCycle exists

Most teams adopting AI coding agents land in one of two failure modes:

1. **Agents that look productive while quietly bypassing every guardrail** — no tests, no SOPs, no real review, just confident-sounding diffs.
2. **So many manual checks layered on top that the agent provides no leverage over a human** — every output requires line-by-line scrutiny, defeating the point.

DevCycle is the third option: **an agent loop where every gate is enforced by tooling that the agent must satisfy to proceed**, not asked nicely. That enforcement is split across three layers:

```
1. Pre-commit hooks  ─►  catch defects before commit (mandatory; agent can't --no-verify)
2. DevCycle Phase 6  ─►  catch defects before PR  (BLOCKING — composes analyze sop +
                          analyze architecture + project SOP manifest into worst-of verdict)
3. CI pipeline       ─►  catch defects before merge (your team's CI config)
```

A defect that passes all three is a defect that ships. Each layer exists because the others miss things. **Phase 8 (Create PR) literally cannot run without a flag file written only by Phase 6 on PASS** — this is the hard architectural rule that prevents the agent from talking itself into shipping.

---

## How to set up DevCycle in your repo

You install the system (all three components) with one CLI command. The full walkthrough — toolchain prereqs, story-authoring rules, gate-by-gate validation checklists, anti-patterns, escalation flow — lives in **[docs/HOWTO_DEVCYCLE.md](docs/HOWTO_DEVCYCLE.md)**.

### 1. Install the CLI

```bash
pip install --user inovagio-atlassian
atlassiancli --version
```

Requires Python 3.12+. Zero runtime pip dependencies. The CLI ships with `templates/autonomous-dev-system/` — the canonical reference scaffolding for the other two components (agent file, SOPs).

### 2. Install the system into your project

`atlassiancli framework bootstrap` is the **system installer**. It detects your project's primary language (Python / TypeScript / Go / Rust / C++ / Java / Kotlin / C# / Ruby / JavaScript) and lays down all three components at once:

```bash
cd <your-repo>
atlassiancli framework bootstrap --product myproduct --name "My Product"
```

What lands in your repo:

| Component | Files |
|---|---|
| **Copilot Agent** | `.github/copilot-instructions.md` · `.github/prompts/devcycle.prompt.md` · `.vscode/devcycle-config.json` |
| **SOPs** | `docs/myproduct/sops/01-architecture.sop.md` … `06-monitoring.sop.md` · `docs/myproduct/sops/sop-manifest.yaml` (the enforceable rules — stack-tuned regexes for the language detected) |
| **CLI integration** | `.pre-commit-config.yaml` (with the `framework sop-commit-gate` hook wired in) · `.vscode/mcp.json` (MCP fallback config) · `sonar-project.properties` |
| **Doc framework floor** | `docs/myproduct/{ARCHITECTURE,DESIGN_SPEC,IMPLEMENTATION_PLAN,ROADMAP,PARITY_LEDGER}.md` · `docs/myproduct/{adrs,epics,stories,evidence}/` |

When the toolchain changes, refresh the SOPs in place:

```bash
atlassiancli framework regenerate-sops --product myproduct
```

Files carrying the `# auto-generated by atlassiancli` header are rewritten; user-edited files are preserved. See [docs/HOWTO_DEVCYCLE.md §3.2](docs/HOWTO_DEVCYCLE.md) for the full scaffold output and per-language SOP details.

### 3. Enable Copilot agent mode + MCP

In VS Code: enable `chat.agent.enabled` and `chat.mcp.enabled`. The MCP config landed in step 2 at `.vscode/mcp.json` — for the read-only fallback path. Restart VS Code; on first agent invocation, approve Atlassian + GitHub OAuth prompts.

### 4. Authenticate the CLI

```bash
export ATLASSIAN_EMAIL=you@example.com
export ATLASSIAN_TOKEN=<api-token-from-id.atlassian.com>
export ATLASSIAN_URL=https://your-site.atlassian.net
```

Or run the interactive multi-tenant wizard:

```bash
atlassiancli configure
```

### 5. Install pre-commit hooks (mandatory)

```bash
pip install pre-commit
pre-commit install
pre-commit install --hook-type commit-msg
pre-commit install --hook-type pre-push
pre-commit run --all-files                     # one-time check on the existing tree
```

The hook chain runs format + lint + typecheck + security scan + the SOP gate (`atlassiancli framework sop-commit-gate`) on every commit. **Never `--no-verify`** — the agent treats hook bypass as a Phase 6 critical defect.

### 6. Run the system

In Copilot Chat → Agent mode:

```
@devcycle sandbox        # first run — fully isolated, touches no real state
@devcycle <ISSUE-KEY>    # second run — real Jira read, low-stakes story
@devcycle auto           # daily — pulls highest-priority unassigned story from active sprint
```

Tail the agent's logs in a side terminal:

```bash
tail -f .vscode/devcycle/logs/*.log
```

That's the day-to-day surface. **You don't type CLI subcommands during the agent loop** — `@devcycle auto` is the whole interaction. Validate at the gates per [docs/HOWTO_DEVCYCLE.md §9](docs/HOWTO_DEVCYCLE.md). Don't passively trust the agent — speed and confidence aren't the same as correctness.

---

## What the agent invokes for you (under-the-hood reference)

Skip this section if you're a daily user — it's a transparency aid for debugging, validating independently, or migrating an agent definition. **You typically never type these directly.**

| Phase | What happens | What the agent invokes |
|---|---|---|
| **0. Initialize** | Bootstrap state file, log dirs, prereq checks | _(agent state only)_ |
| **1. Fetch** | Pull highest-priority unassigned story from active sprint | `sprint current` · `sprint stories --unassigned --priority-order` · `analyze fetch` |
| **2. Prepare** | Validate against Definition of Ready; auto-enhance gaps | `analyze ready` · `analyze lint` · `analyze atomicity` · `analyze architecture` · `analyze sop` · `enhance --apply` · `prepare --format ai` |
| **3. Claim** | Transition Jira → In Progress, assign, post run-id comment | `transition --execute` · `assign` · `comment --idempotency-key` |
| **4–5. Implement / Test** | Agent writes code + tests; pre-commit hooks gate the commit | _(no CLI)_ |
| **6. Code review (BLOCKING GATE)** | Run SOPs against the diff; block on any blocking finding | `review <KEY>` · `analyze sop` · `framework sop-commit-gate` |
| **7. Fix** | Loop back to 6 after agent applies fixes; max 3 iterations | _(no CLI)_ |
| **8. Create PR** | Push, open PR, link to Jira, transition Jira → Done | `link-pr` · `transition --execute` · `comment` |

Full per-phase detail in [docs/HOWTO_DEVCYCLE.md Appendix A](docs/HOWTO_DEVCYCLE.md).

---

## What you may type yourself

A handful of CLI surfaces are useful **outside** the agent loop:

- **At sprint planning / refinement** — `atlassiancli analyze ready <KEY>` validates a story against the 11-section Definition-of-Ready before you commit it to a sprint. `atlassiancli analyze atomicity <KEY>` flags stories that span multiple bounded contexts and need to be split. The agent runs these too in Phase 2, but running them upstream keeps bad stories out of the sprint backlog entirely.

- **As an independent gate sanity check** — `atlassiancli review <KEY>` runs the same composite gate the agent runs at Phase 6 (composes `analyze ready` + `analyze sop` + `analyze architecture` with worst-of verdict). Useful to confirm the agent's self-assessment matches an independent run.

- **For Atlassian operations the agent isn't running for you** — sprint reports, manual Confluence pushes, sprint reorganization, etc. The CLI works as a regular Atlassian CLI when you need it.

---

## What else the CLI does (outside the DevCycle loop)

DevCycle is the flagship use case; every CLI subcommand also stands on its own. The CLI is organised as four orthogonal capability tiers, all driven by the same `AgentResponse` JSON contract:

### Tier 1 — Atlassian basics

Daily-driver Jira + Confluence operations. Every command supports `--json` and idempotent writes.

- **Issue lifecycle:** `create epic` · `create story` · `create task` · `transition` · `assign` · `comment` · `link-pr` · `delete`
- **Sprint operations:** `sprint current` · `sprint stories` · `move` · `split` · `rebalance` · `reorganize` · `sprint-goals` · `goals` · `balance`
- **Reports:** `report quality` · `report velocity` · `report themes` · `report health`
- **Confluence:** `confluence get` · `children` · `find` · `create` · `update`

### Tier 2 — Story analysis + enhancement

Used by the DevCycle agent in Phase 2 + Phase 6, and by humans during refinement.

- `analyze lint <KEY>` — 0–100 quality score against the 11-section AI-implementable schema
- `analyze atomicity <KEY>` — 5-criteria PR-sized check
- `analyze ready <KEY>` — composite Definition-of-Ready gate
- `analyze sop <KEY>` — story-time SOP rule check (Phase 2 gate input)
- `analyze architecture <KEY>` — architectural-soundness audit
- `analyze description` / `analyze fetch` — primitives
- `prepare <KEY> --format ai --output <file>` — render the canonical 11-section technical spec
- `enhance <KEY> --apply` — review-then-apply story enhancement (auto-quality + agile-story rewrite by default; `--apply-architecture` enforces architecture AC + NFR requirements)
- `template story` / `template epic` — Conventional, AI-implementable story scaffolds
- `review <KEY>` — unified Phase 6 gate

### Tier 3 — SOP enforcement

The bridge between prose SOPs and machine-checkable rules.

- `framework sop-commit-gate` — Phase 6 / pre-commit blocking gate
- `framework sop-validate-manifest` — schema + regex validation of the manifest itself
- `framework regenerate-sops --product <handle>` — refresh stack-tuned SOPs in place

### Tier 4 — Doc-framework bridge

Manifest-driven Jira ↔ Confluence ↔ in-repo-docs reconciliation.

- `framework create-stories --product <handle>` — bulk-create Jira issues from per-product YAML manifests
- `framework verify-stories --product <handle>` — parity check between manifests and Jira
- `framework reverse-sync --product <handle>` — inverse rebuild of manifests from Jira
- `framework sync-docs --product <handle>` — push repo markdown to Confluence
- `framework bootstrap --product <handle>` — **the system installer** (covered above)

### Tier-specific niche utilities

- `split <KEY> --execute` — break a multi-context story into atomic subtasks (used by the agent when Phase 2 atomicity check fails)
- `context [<bounded-context>]` — list bounded contexts known to a product, or describe a specific one
- `auto analyze` / `auto enhance` / `auto split` — sweep a whole sprint with a single command

Full subcommand reference in [docs/USAGE.md](docs/USAGE.md).

---

## Why this CLI specifically

A note for evaluators wondering why DevCycle uses this CLI rather than (e.g.) shelling out to `acli` or composing MCP calls directly:

- **Zero pip dependencies at runtime.** `pyproject.toml` `dependencies = []`. Matters when shipping into hardened CI images, air-gapped environments, or codebases with strict supply-chain rules.
- **Stable 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 in [docs/AGENT_INTEGRATION.md](docs/AGENT_INTEGRATION.md). The agent branches on these — no prose parsing.
- **Idempotent writes.** `transition`, `assign`, `comment` (with `--idempotency-key`), `link-pr`, and every `framework` subcommand are safe to replay. Agent loops can be killed and restarted at any point without producing duplicate side effects.
- **Stack-aware SOPs.** 10 supported languages with hand-tuned regex patterns, source globs, error idioms, and structured-logger hints. `regenerate-sops` keeps them current. The SOP rules and the print-pattern regexes that catch them are pinned to your actual toolchain, not a generic placeholder.
- **DDD-layered architecture.** `domain` / `application` / `infrastructure` / `cli` boundaries are enforced; tests substitute alternate adapters at any layer.

---

## Documentation

| Doc | What's in it |
|---|---|
| **[docs/HOWTO_DEVCYCLE.md](docs/HOWTO_DEVCYCLE.md)** | **Full DevCycle adoption guide: prereqs, workstation setup, CLI vs MCP precedence, the three SOPs, story authoring for AI agents, the state machine, daily workflow, gate-by-gate validation, copilot-instructions reference.** |
| [docs/USAGE.md](docs/USAGE.md) | Every subcommand with arguments and examples |
| [docs/INSTALL.md](docs/INSTALL.md) | Install, auth, troubleshooting, optional CI / pre-commit / cron integrations |
| [docs/AGENT_INTEGRATION.md](docs/AGENT_INTEGRATION.md) | JSON schema, exit-code contract, idempotency rules, canonical invocation patterns |
| [docs/RUNBOOK.md](docs/RUNBOOK.md) | Operational procedures: setup, daily flows, doc-framework operations, gotchas, verification gates |
| [docs/RELEASE.md](docs/RELEASE.md) | Trust model + cutting a release (release-please + OIDC trusted publishing) |
| [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) | DDD layered overview |
| [docs/EXAMPLES/](docs/EXAMPLES/) | Runnable starter projects: Jira-only, doc-framework, agent-driven workflow |
| [templates/autonomous-dev-system/](templates/autonomous-dev-system/) | Canonical scaffolding `framework bootstrap` installs (DevCycle prompt, SOP templates, MCP config, pre-commit chain) |
| [PLAN.md](PLAN.md) | Vision, four-tier capability map, configuration model, build-out history |
| [CHANGELOG.md](CHANGELOG.md) | Release notes |
| [CONTRIBUTING.md](CONTRIBUTING.md) | Dev setup, Conventional Commits cheatsheet, lint conventions, release flow |

---

## Project status

**Version-agnostic status:** `pip install inovagio-atlassian` always installs the latest release; the [PyPI page](https://pypi.org/project/inovagio-atlassian/) is the canonical version source. The four-tier capability surface is shipped and tested; the agent-callable contract (JSON envelope + exit codes + idempotency) is stable. The DevCycle scaffolding (`templates/autonomous-dev-system/`) ships with the package and is the reference adoption path. Future versions are managed by [release-please](https://github.com/googleapis/release-please) — see [CONTRIBUTING.md](CONTRIBUTING.md) for the Conventional-Commits release flow.

---

## Contributing

Issues and pull requests welcome. `inovagio-atlassian` is intentionally small and focused — extensions live in the `cli/handlers/` layer with corresponding domain / application services. See [CONTRIBUTING.md](CONTRIBUTING.md) for dev setup, the Conventional-Commits → automated-version-bump flow, and lint conventions.

---

## License

MIT — see [LICENSE](LICENSE).
