Jira Agent Workflow Packs

This repository packages the same Jira-backed delivery workflow for multiple AI clients without mixing their installation paths or runtime instructions.

Each client gets its own installer and its own setup guide:

Client	Installer	Guide	Runtime shape
GitHub Copilot	setup/Install-CopilotJiraAgents.ps1	docs/copilot-setup-guide.md	Native custom agents from .agent.md
OpenAI Codex	setup/Install-CodexWorkflow.ps1	docs/codex-setup-guide.md	Prompt pack for the official Codex CLI
Claude Code	setup/Install-ClaudeWorkflow.ps1	docs/claude-setup-guide.md	Slash-command pack for Claude Code

Copilot CLI MCP setup is intentionally separate:

• setup/Install-CopilotCliMcp.ps1 provisions ~/.copilot/mcp-config.json for terminal sessions.

Use only the guide for the client you intend to run. Do not combine installers in one environment unless you intentionally want multiple clients configured on the same machine.

Agent Flow

• ImplementationPlanner reads a Jira ticket through atlassian/*, caches it as .workitems/<ticket>/ticket.md, asks clarification questions when the plan is not actionable, and creates .workitems/<ticket>/plan.md, questions.md, tasks.json, and progress.json.
• SolutionDeveloper works from ticket.md plus the planning artifacts, stops immediately when .workitems/<ticket>/problems.md is present as an active blocker, chooses the next task by highest current priority, works one task at a time, uses Jira only to refresh the cache when needed, keeps progress.json as a compact snapshot plus worklog.md as the recent loop journal capped to the newest 10 entries, adds tasks only for required discoveries needed to finish the current ticket, pauses at planned checkpoints to recommend validation and an optional manual commit description, performs a concise self-review, and writes a compact pr-summary.md before handoff.
• QualityReviewer compares the implementation with the cached Jira ticket, planning artifacts, architecture rules, maintainability, tests, and backward compatibility, and generates review remediation artifacts.
• PRReviewer reviews a pull request against Jira expectations and repository quality rules without using .workitems/<ticket>/ planning artifacts, may create or reuse .workitems/<ticket>/ticket.md as the shared Jira cache, and generates PR review remediation artifacts under pr-reviews/<ticket>/.
• ReviewFixer executes the generated review remediation tasks, asks focused clarification questions when a finding is ambiguous, can record non-applicable or disputed findings with evidence, and keeps remediation progress current until the work is ready for re-review.

Shared Workflow Contract

• Jira access is intended to stay read-only.
• The official remote MCP endpoint is https://mcp.atlassian.com/v1/mcp.
• The workflow contract is stable across clients even when the invocation style differs.
• The agent prompts or prompt packs define behavior, while Atlassian MCP supplies Jira access.
• Ticket content should be fetched once into .workitems/<ticket>/ticket.md and reused from there unless the cache must be refreshed.
• If a ticket-local stop gate is needed, place it at .workitems/<ticket>/problems.md rather than the repository root.
• .workitems/<ticket>/problems.md should exist only while an active blocker still needs resolution; durable history belongs in tasks.json, progress.json, and worklog.md, not in a lingering stop-gate file.
• If .workitems/<ticket>/problems.md exists, the developer is expected to resolve the blocker described there and then delete the file before implementation resumes. Do not leave an empty problems.md behind because the stop gate is based on file existence.
• Do not use .workitems/<ticket>/problems.md for ordinary in-scope implementation issues the agent should fix directly.

Agent status contract:

• Agents now use explicit status lines in substantive chat updates so it is clear whether they are still working, waiting, blocked, or ready for handoff.
• Expected statuses are STATUS: IN_PROGRESS, STATUS: WAITING_FOR_INPUT, STATUS: BLOCKED, STATUS: READY_FOR_IMPLEMENTATION, STATUS: READY_FOR_REVIEW, STATUS: READY_FOR_FIXES, and STATUS: COMPLETE.
• When an agent needs a developer response before it can continue, it should ask using this structure: STATUS: WAITING_FOR_INPUT, Need: ..., Why: ..., Next: ....
• When an agent finishes its current stage, it should explicitly state the handoff-ready status and the next recommended agent instead of only implying completion from context.

Generated workitems:

• .workitems/<ticket>/ticket.md
• .workitems/<ticket>/plan.md
• .workitems/<ticket>/questions.md
• .workitems/<ticket>/tasks.json
• .workitems/<ticket>/progress.json
• .workitems/<ticket>/problems.md
• .workitems/<ticket>/worklog.md
• .workitems/<ticket>/pr-summary.md
• .workitems/<ticket>/review.md
• .workitems/<ticket>/review-tasks.json
• .workitems/<ticket>/review-progress.json

Generated PR review artifacts:

• pr-reviews/<ticket>/review.md
• pr-reviews/<ticket>/review-tasks.json
• pr-reviews/<ticket>/review-progress.json

Review outputs should start with a compact merge gate verdict and keep task/progress artifacts in a compact structured shape. Use the artifacts with strict separation of responsibility:

• tasks.json is the durable execution ledger
• progress.json is the compact current-state snapshot
• worklog.md is the recent implementation loop journal
• problems.md is the temporary active blocker file and should be deleted once the blocker is resolved
• review-tasks.json is the durable remediation ledger
• review-progress.json is the compact current remediation snapshot Use the full process proportionally: small low-risk tickets should use lightweight planning, minimal checkpoints, delta artifact updates, and reviewer focus on summaries plus changed files first.

Artifact ownership summary:

• ImplementationPlanner creates ticket.md, plan.md, questions.md, and the initial tasks.json and progress.json.
• SolutionDeveloper owns ongoing tasks.json and progress.json updates, creates worklog.md and pr-summary.md, and creates problems.md only when implementation is actively blocked by something outside normal in-scope implementation work.
• QualityReviewer creates ticket-based review artifacts, while PRReviewer creates the pr-reviews/<ticket>/ review artifacts and may refresh ticket.md.
• ReviewFixer owns ongoing updates to review task and review progress artifacts during remediation.

Client Guides

See:

• docs/copilot-setup-guide.md
• docs/codex-setup-guide.md
• docs/claude-setup-guide.md
• docs/agent-workflow-guide.md
• docs/external-components.md
• .github/prompts/README.md