About this project

## Overview jira-integration is a plugin for Claude Code that processes a single Jira issue from branch creation → approach design → implementation → testing → review → local merge, and records the results of each step as Jira comments, attachments, and status transitions. It is designed to place multiple issues in a queue, consume them sequentially, then summarize pass/isolation results in a single exception report so that humans only need to judge isolated cases. ## Operational Structure It consists of two loops. - Stage loop (`auto`): Runs one task in the order start → approach → impl+test → review. Each stage runs as an isolated sub-agent, and different models are assigned per stage. The review gate evaluates the design-implementation match rate and the number of Critical issues as structured values; if not passed, a fixing agent runs a sensor loop (up to 5 times) that only runs lint, typecheck, and related tests to converge, then performs the full test suite and a delta re-review once each. The outer loop limit is 2 times. - Task loop (`loop`): Consumes the queue configured by `init` in order, performing auto → local `--no-ff` merge → rebase of remaining worktrees for each task. If the gate is not passed, a stage fails, or a merge/rebase conflict occurs, only that task is isolated and the loop proceeds to the next. It halts entirely only on infrastructure signals such as authentication (401/403), MCP connection issues, or base corruption, or when consecutive failures occur across different tasks. The documentation states that control flow is deterministically executed by a Workflow script (`scripts/auto.workflow.js`), not by prompt interpretation. ## Jira Integration Each issue key maps to a branch (`feature/<KEY>`), a worktree, and a context file. The main repository's `.jira-context.json` is an aggregate holding the entire queue, while each worktree's file holds that task's state. Per command, status transitions (To Do → In Progress → In Review → Done), comments, and attachments (approach/review documents, test reports) occur. Isolation is recorded only as local state without changing Jira. Jira calls are handled by `scripts/jira-cli.py` (REST), which uses only the standard library. Credentials are stored in the `jira` block of the workspace-level `.jira-context.json` and are automatically migrated from environment variables and legacy MCP settings. Registering the MCP server is optional. ## Main Commands - Issue creation: `epic set/show/clear`, `discover`, `create` - Queue/automation: `init`, `loop`, `auto` - Individual stages: `start`, `approach`, `impl`, `test`, `review`, `merge`, `pr`, `done` - Query/cleanup: `status`, `report`, `clean` - Miscellaneous: `/jira setup`, `/jira dashboard` ## Operating Rules Work size is classified as L1/L2/L3 to adjust the amount of artifacts and review depth. Touching the data model, transaction boundaries, external API contracts, concurrency, or security boundaries upgrades L1 to L2. `start` may recommend skipping only the approach and test stages; impl, review, and merge are never skipped. All stages are recorded in `completedSteps`, so re-runs skip completed stages. ## Artifacts and Dashboard Under `docs/`, requirements, approach, test, and review documents plus review-log and run-log (jsonl) accumulate. The run-log and review-log serve as observational data for the harness itself, such as review false-positive rate, stage duration, fix frequency, and isolation reasons. The dashboard at `http://127.0.0.1:8765` displays worktree-specific cards (current stage, tool calls, Jira status, blocks graph) in real time via SSE; it is localhost-only and has no authentication. ## License MIT.