inovagio-atlassian 0.1.3

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

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.

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).

---

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.

1. Install the CLI

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:

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:

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 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

export ATLASSIAN_EMAIL=[e-mail]
export ATLASSIAN_TOKEN=<api-token-from-id.atlassian.com>
export ATLASSIAN_URL=https://your-site.atlassian.net

Or run the interactive multi-tenant wizard:

atlassiancli configure

5. Install pre-commit hooks (mandatory)

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:

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. 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.

---

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.

---

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. 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	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	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/RELEASE.md	Trust model + cutting a release (release-please + OIDC trusted publishing)
docs/ARCHITECTURE.md	DDD layered overview
docs/EXAMPLES/	Runnable starter projects: Jira-only, doc-framework, agent-driven workflow
templates/autonomous-dev-system/	Canonical scaffolding framework bootstrap installs (DevCycle prompt, SOP templates, MCP config, pre-commit chain)
PLAN.md	Vision, four-tier capability map, configuration model, build-out history
CHANGELOG.md	Release notes
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 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 — see 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 for dev setup, the Conventional-Commits → automated-version-bump flow, and lint conventions.

---

License

MIT — see LICENSE.