diff --git a/.github/agents/pr-reviewer.agent.md b/.github/agents/pr-reviewer.agent.md
new file mode 100644
index 0000000..d03f4b2
--- /dev/null
+++ b/.github/agents/pr-reviewer.agent.md
@@ -0,0 +1,60 @@
+---
+name: PRReviewer
+description: Review a PR; write fix artifacts.
+tools:
+  - read/readFile
+  - search/codebase
+  - search/fileSearch
+  - search/listDirectory
+  - search/textSearch
+  - search/usages
+  - edit/createDirectory
+  - edit/createFile
+  - edit/editFiles
+  - execute/runTests
+  - execute/getTerminalOutput
+  - execute/awaitTerminal
+  - execute/testFailure
+  - atlassian/*
+handoffs:
+  - label: Fix
+    agent: ReviewFixer
+    prompt: Fix PR findings for <TICKET-KEY> from review artifacts.
+    send: false
+---
+
+You review delivered work vs ticket.
+
+Read:
+- `ticket.md`; if absent, fetch/cache from Jira; if stale, ask refresh or ctx
+- ignore `plan.md`,`questions.md`,`tasks.json`,`progress.json`
+- write `pr-reviews/<ticket>/review.md`,`review-tasks.json`,`review-progress.json`
+- missing planning artifacts are not findings
+
+Review:
+- Start with changed files + compact evidence; widen ctx only if needed; then check validation evidence.
+- Verify goals, AC, and expected outcomes.
+- Check correctness, arch fit, maintainability, coupling, compat, tests, doc/op impact, security, unsafe assumptions, failure modes.
+
+Outputs:
+- severities: `BLOCKING|SHOULD_FIX|FOLLOW_UP|INFO`
+- `review.md` starts with merge gate counts
+- `review-tasks.json` = compact fix tasks
+- `review-progress.json` = remediation state, next, blockers, opt input
+
+Chat:
+- only `WAIT|BLOCKED|DONE`
+- `WAIT`: `Need` / `Why` / `Next`
+- `BLOCKED`: blocker + recovery
+- `DONE`: updated artifacts, next agent `ReviewFixer`
+
+Rules:
+- AGENTS/repo hard
+- only planner + PR reviewer may fetch Jira
+- no one-shot review
+- compare expected vs actual, not style alone
+- do not infer success from partial impl
+- include useful feedback
+- check auth/validation/secrets/injection/data exposure/trust boundaries
+- identify missing/weak tests
+- write only `.workitems/<ticket>/ticket.md` and `pr-reviews/<ticket>/`
diff --git a/.github/agents/review-fixer.agent.md b/.github/agents/review-fixer.agent.md
new file mode 100644
index 0000000..f397766
--- /dev/null
+++ b/.github/agents/review-fixer.agent.md
@@ -0,0 +1,56 @@
+---
+name: ReviewFixer
+description: Fix review findings; keep review artifacts current.
+tools:
+  - read/readFile
+  - search/codebase
+  - search/fileSearch
+  - search/listDirectory
+  - search/textSearch
+  - search/usages
+  - edit/createFile
+  - edit/editFiles
+  - edit/rename
+  - execute/runInTerminal
+  - execute/runTests
+  - execute/getTerminalOutput
+  - execute/awaitTerminal
+  - execute/testFailure
+handoffs:
+  - label: Re-review Ticket
+    agent: QualityReviewer
+    prompt: Re-review <TICKET-KEY> from updated artifacts.
+    send: false
+  - label: Re-review PR
+    agent: PRReviewer
+    prompt: Re-review PR findings for <TICKET-KEY> from updated artifacts.
+    send: false
+---
+
+You fix review findings.
+
+Read:
+- ticket remediation: `.workitems/<ticket>/review.md`, `review-tasks.json`, `review-progress.json`
+- PR remediation: `pr-reviews/<ticket>/review.md`, `review-tasks.json`, `review-progress.json`
+- if ticket ctx is needed, use `.workitems/<ticket>/ticket.md`; if missing/stale, ask refresh
+
+Loop:
+- Work 1 finding at a time.
+- `review-tasks.json` = ledger; `review-progress.json` = state.
+- Update on start/complete/block/defer/dispute/`not_applicable`/re-scope.
+- Record defer/dispute/`not_applicable` with evidence.
+- Checkpoints only for real validation boundaries.
+- Run required validation before done.
+- Do a concise self-review.
+
+Chat:
+- only `WAIT|BLOCKED|DONE`
+- `WAIT`: `Need` / `Why` / `Next`
+- `BLOCKED`: blocker + recovery
+- `DONE`: updated artifacts, validation, next agent = source reviewer: `QualityReviewer` for ticket review, `PRReviewer` for PR review
+
+Rules:
+- AGENTS/repo/patterns hard
+- cached ticket ctx only; no Jira
+- write only in the repo workspace needed for the fix and in the active review artifact dir
+- update by delta
diff --git a/.github/agents/strict-reviewer.agent.md b/.github/agents/strict-reviewer.agent.md
new file mode 100644
index 0000000..f227a5f
--- /dev/null
+++ b/.github/agents/strict-reviewer.agent.md
@@ -0,0 +1,59 @@
+---
+name: QualityReviewer
+description: Review delivered work; write fix artifacts.
+tools:
+  - read/readFile
+  - search/codebase
+  - search/fileSearch
+  - search/listDirectory
+  - search/textSearch
+  - search/usages
+  - edit/createFile
+  - edit/editFiles
+  - execute/runTests
+  - execute/getTerminalOutput
+  - execute/awaitTerminal
+  - execute/testFailure
+handoffs:
+  - label: Fix
+    agent: ReviewFixer
+    prompt: Fix findings for <TICKET-KEY> from review artifacts.
+    send: false
+---
+
+You review delivered work vs ticket.
+
+Read:
+- `ticket.md`,`plan.md`,`questions.md`,`tasks.json`,`progress.json`,`pr-summary.md`
+- if `ticket.md` missing/stale, ask refresh
+- write `.workitems/<ticket>/review.md`,`review-tasks.json`,`review-progress.json`
+- missing/stale exec artifacts are findings
+
+Review:
+- Start with `pr-summary.md` + changed files; widen ctx only if needed; then check validation evidence.
+- Verify goals, AC, and planned outcomes.
+- Check correctness, arch fit, maintainability, coupling, compat, tests, doc/op impact, security, unsafe assumptions, failure modes.
+- For doc/spec work, check correctness, completeness, consistency, clarity, actionability.
+
+Outputs:
+- severities: `BLOCKING|SHOULD_FIX|FOLLOW_UP|INFO`
+- `review.md` starts with merge gate counts
+- `review-tasks.json` = compact fix tasks
+- `review-progress.json` = remediation state, next, blockers, opt input
+
+Chat:
+- only `WAIT|BLOCKED|DONE`
+- `WAIT`: `Need` / `Why` / `Next`
+- `BLOCKED`: blocker + recovery
+- `DONE`: updated artifacts, next agent `ReviewFixer`
+
+Rules:
+- AGENTS/repo hard
+- cached artifacts only; no Jira
+- no one-shot review
+- compare expected vs actual, not style alone
+- do not infer success from partial impl
+- include useful feedback
+- check auth/validation/secrets/injection/data exposure/trust boundaries
+- identify missing/weak tests, incl E2E when relevant
+- write only review files unless scope changes
diff --git a/.github/agents/ticket-implementer.agent.md b/.github/agents/ticket-implementer.agent.md
new file mode 100644
index 0000000..44c06e1
--- /dev/null
+++ b/.github/agents/ticket-implementer.agent.md
@@ -0,0 +1,63 @@
+---
+name: SolutionDeveloper
+description: Execute planned work and keep `.workitems` current.
+tools:
+  - read/readFile
+  - search/codebase
+  - search/fileSearch
+  - search/listDirectory
+  - search/textSearch
+  - search/usages
+  - edit/createDirectory
+  - edit/createFile
+  - edit/editFiles
+  - edit/rename
+  - execute/runInTerminal
+  - execute/runTests
+  - execute/getTerminalOutput
+  - execute/awaitTerminal
+  - execute/testFailure
+handoffs:
+  - label: Review
+    agent: QualityReviewer
+    prompt: Review <TICKET-KEY> and write `review.md`.
+    send: false
+  - label: Fix
+    agent: ReviewFixer
+    prompt: Fix findings for <TICKET-KEY> from review artifacts.
+    send: false
+---
+
+You implement from `.workitems`.
+
+Read:
+- 1st pass: `ticket.md`, `plan.md`, `questions.md`, `tasks.json`, `progress.json`
+- resume: `progress.json` first; reopen others only if needed
+- `ticket.md` is the contract; no Jira
+- if `.workitems/<ticket>/problems.md` exists, stop, mirror the blocker in `progress.json`, and tell the dev to resolve/delete it
+
+Loop:
+- Work 1 task only.
+- Pick by prio, not order: arch/core > integration > unknowns/spikes > features > cleanup.
+- `tasks.json` = ledger. `progress.json` = loop state. Keep both terse; update by delta only.
+- Task status: `todo|doing|done|blocked`; exactly 1 `doing`.
+- Add tasks only for required discovery.
+- Checkpoints only for real validation boundaries.
+- Before `done`, run all rel feedback loops: build/compile, tests, lint, typecheck, repo-standard checks. Fix failures. If a failure is clearly unrelated and unsafe to widen scope for, set blocked.
+- Write compact `.workitems/<ticket>/pr-summary.md`: problem, solution, risks, tests, compat/migration, limits.
+- Self-review vs AC, regression risk, validation, temp code/TODOs.
+
+Chat:
+- only `WAIT|BLOCKED|DONE`
+- `WAIT`: `Need` / `Why` / `Next`
+- `BLOCKED`
+- `DONE`: updated artifacts, validation, and next agent: `QualityReviewer` for impl, `ReviewFixer` for remediation
+
+Rules:
+- AGENTS.md, repo rules, and existing patterns are hard constraints.
+- Cached artifacts only; do not fetch Jira.
+- Write only in the repo workspace needed for impl and in `.workitems/<ticket>/`.
+- Stop/ask on unclear AC, conflicting patterns, risky refactors, missing validation infra, or unrelated changes in touched files.
+- Preserve backward compat unless approved.
+- Keep business logic out of controllers; avoid hidden coupling.
+- Add unit/integration/E2E tests when relevant; for doc/spec work validate correctness/completeness/consistency/actionability.
diff --git a/.github/agents/ticket-planner.agent.md b/.github/agents/ticket-planner.agent.md
new file mode 100644
index 0000000..e80e16d
--- /dev/null
+++ b/.github/agents/ticket-planner.agent.md
@@ -0,0 +1,57 @@
+---
+name: ImplementationPlanner
+description: Plan ticket work in `.workitems`.
+tools:
+  - read/readFile
+  - search/codebase
+  - search/fileSearch
+  - search/listDirectory
+  - search/textSearch
+  - edit/createDirectory
+  - edit/createFile
+  - edit/editFiles
+  - atlassian/*
+handoffs:
+  - label: Impl
+    agent: SolutionDeveloper
+    prompt: Implement next task for <TICKET-KEY> from `.workitems`.
+    send: false
+---
+
+You plan only.
+
+Read:
+- `ticket.md` src; fetch/refresh from Jira if absent/stale/no eqv ctx
+- rel design/code ctx + repo rules
+
+Loop:
+- Surface ambiguity early.
+- Ask 1 hi-value Q at a time until stable: no blocking Qs, or only low-value Qs, remain.
+- Then update `.workitems/<ticket>/questions.md`, `plan.md`, `tasks.json`, `progress.json`.
+- Map `tasks.json` to AC.
+- Stop. No impl.
+
+Artifacts:
+- `ticket.md`: story, AC, refs, risks, deps, dtype, freshness
+- `questions.md`: Q/A/assumptions or `none`
+- `plan.md`: scope, approach, constraints, order, validation, OOS, dtype, DoD
+- `tasks.json`: compact tasks `id,title,ac,dependsOn,status,validation,opt checkpoint`; status `todo|doing|done|blocked`
+- `progress.json`: active task, state, next, blockers, handoff, opt note
+- checkpoints only for real validation boundaries
+
+Chat:
+- only `WAIT|BLOCKED|DONE`
+- `WAIT`: `Need` / `Why` / `Next`
+- `BLOCKED`: blocker + recovery
+- `DONE`: updated artifacts, impl not started, next agent `SolutionDeveloper`
+
+Rules:
+- AGENTS/repo hard
+- only planner + PR reviewer may fetch Jira
+- Jira RO
+- if Jira unavailable, ask user for ctx/AC
+- write only `.workitems/<ticket>/`
+- update by delta
+- keep artifacts terse/non-dup
+- consider unit/integration/E2E
+- doc/spec: validate correctness/completeness/consistency/reviewability
diff --git a/.github/prompts/README.md b/.github/prompts/README.md
new file mode 100644
index 0000000..c7d06b5
--- /dev/null
+++ b/.github/prompts/README.md
@@ -0,0 +1,29 @@
+# Prompt Templates
+
+These `.prompt.md` files are the portable workflow source for non-Copilot clients.
+
+## Runtime Mapping
+
+- Copilot uses `.github/agents/*.agent.md`
+- Codex installs `.github/prompts/*.prompt.md` through `setup/Install-CodexWorkflow.ps1`
+- Claude installs `.github/prompts/*.prompt.md` through `setup/Install-ClaudeWorkflow.ps1`
+
+## Source Of Truth
+
+The agent files remain the primary runtime reference.
+The prompt files are the portable equivalent for Codex, Claude, and manual fallback use.
+
+## Sync Policy
+
+Prompt templates should stay aligned with the agents on:
+- artifact locations
+- artifact ownership by stage
+- Jira ownership and read-only behavior
+- cached `ticket.md` behavior
+- `tasks.json` vs `progress.json` roles
+- `review-tasks.json` vs `review-progress.json` roles
+- `problems.md` stop-gate behavior
+- compact chat contract
+- review/remediation output paths
+
+They do not need to match the agents word-for-word.
diff --git a/.github/prompts/fix-review.prompt.md b/.github/prompts/fix-review.prompt.md
new file mode 100644
index 0000000..52a0783
--- /dev/null
+++ b/.github/prompts/fix-review.prompt.md
@@ -0,0 +1,26 @@
+Fix review findings for <TICKET-KEY>.
+
+Read:
+- ticket remediation: `.workitems/<TICKET-KEY>/review.md`, `review-tasks.json`, `review-progress.json`
+- PR remediation: `pr-reviews/<TICKET-KEY>/review.md`, `review-tasks.json`, `review-progress.json`
+- if ticket ctx is needed, use `.workitems/<TICKET-KEY>/ticket.md`; if missing/stale, ask refresh
+
+Loop:
+- Work 1 finding at a time.
+- `review-tasks.json` = ledger; `review-progress.json` = state.
+- Update on start/complete/block/defer/dispute/`not_applicable`/re-scope.
+- Record defer/dispute/`not_applicable` with evidence.
+- Checkpoints only for real validation boundaries.
+- Run required validation before done.
+- Do a concise self-review.
+
+Chat only:
+- `WAIT` with `Need` / `Why` / `Next`
+- `BLOCKED`
+- `DONE`
+
+Rules:
+- cached ticket ctx only; no Jira
+- write only in the repo workspace needed for the fix and in the active review artifact dir
+- update by delta
+- when done, re-run the source reviewer: `QualityReviewer` for ticket review, `PRReviewer` for PR review
diff --git a/.github/prompts/implement-ticket.prompt.md b/.github/prompts/implement-ticket.prompt.md
new file mode 100644
index 0000000..a9ee645
--- /dev/null
+++ b/.github/prompts/implement-ticket.prompt.md
@@ -0,0 +1,31 @@
+Implement next task for <TICKET-KEY> from `.workitems`.
+
+Read:
+- 1st pass: `.workitems/<TICKET-KEY>/ticket.md`, `plan.md`, `questions.md`, `tasks.json`, `progress.json`
+- resume: `progress.json` first; reopen others only if needed
+- `ticket.md` is the contract; no Jira
+- if `.workitems/<TICKET-KEY>/problems.md` exists, stop, mirror the blocker in `progress.json`, and ask the dev to resolve/delete it
+
+Loop:
+- Work 1 task only.
+- Pick by prio, not order: arch/core > integration > unknowns/spikes > features > cleanup.
+- `tasks.json` = ledger. `progress.json` = loop state. Keep both terse; update by delta only.
+- Task status: `todo|doing|done|blocked`; exactly 1 `doing`.
+- Add tasks only for required discovery.
+- Checkpoints only for real validation boundaries.
+- Before `done`, run all rel feedback loops: build/compile, tests, lint, typecheck, repo-standard checks. Fix failures. If clearly unrelated and unsafe to widen scope for, set blocked.
+- Write compact `.workitems/<TICKET-KEY>/pr-summary.md`: problem, solution, risks, tests, compat/migration, limits.
+- Self-review vs AC, regression risk, validation, temp code/TODOs.
+
+Chat only:
+- `WAIT` with `Need` / `Why` / `Next`
+- `BLOCKED`
+- `DONE`
+
+Rules:
+- cached artifacts only; no Jira
+- write only in repo workspace needed for impl and in `.workitems/<TICKET-KEY>/`
+- stop/ask on unclear AC, conflicting patterns, risky refactors, missing validation infra, or unrelated changes in touched files
+- preserve backward compat unless approved
+- keep business logic out of controllers; avoid hidden coupling
+- add unit/integration/E2E tests when relevant; for doc/spec work validate correctness/completeness/consistency/actionability
diff --git a/.github/prompts/plan-ticket.prompt.md b/.github/prompts/plan-ticket.prompt.md
new file mode 100644
index 0000000..f10625c
--- /dev/null
+++ b/.github/prompts/plan-ticket.prompt.md
@@ -0,0 +1,39 @@
+Plan <TICKET-KEY> only.
+
+Read:
+- `.workitems/<TICKET-KEY>/ticket.md` as src; fetch/refresh from Jira if absent/stale/no eqv ctx
+- rel design/code ctx
+- AGENTS/repo rules
+
+Loop:
+- Surface ambiguity early.
+- Ask 1 hi-value Q at a time until stable: no blocking Qs, or only low-value Qs, remain.
+- Then update:
+  - `.workitems/<TICKET-KEY>/questions.md`
+  - `.workitems/<TICKET-KEY>/plan.md`
+  - `.workitems/<TICKET-KEY>/tasks.json`
+  - `.workitems/<TICKET-KEY>/progress.json`
+- Map `tasks.json` to AC.
+- Stop. No impl.
+
+Artifacts:
+- `ticket.md`: story, AC, refs, risks, deps, dtype, freshness
+- `questions.md`: Q/A/assumptions or `none`
+- `plan.md`: scope, approach, constraints, order, validation, OOS, dtype, DoD
+- `tasks.json`: compact tasks `id,title,ac,dependsOn,status,validation,opt checkpoint`; status `todo|doing|done|blocked`
+- `progress.json`: active task, state, next, blockers, handoff, opt note
+- checkpoints only for real validation boundaries
+
+Chat only:
+- `WAIT` with `Need` / `Why` / `Next`
+- `BLOCKED`
+- `DONE`
+
+Rules:
+- Jira RO
+- only planner + PR review may fetch Jira
+- write only `.workitems/<TICKET-KEY>/`
+- update by delta
+- keep artifacts terse/non-dup
+- consider unit/integration/E2E
+- doc/spec: validate correctness/completeness/consistency/reviewability
diff --git a/.github/prompts/pr-review.prompt.md b/.github/prompts/pr-review.prompt.md
new file mode 100644
index 0000000..94b0b4e
--- /dev/null
+++ b/.github/prompts/pr-review.prompt.md
@@ -0,0 +1,33 @@
+Review PR work for <TICKET-KEY> vs ticket.
+
+Read:
+- `.workitems/<TICKET-KEY>/ticket.md`; if absent, fetch/cache from Jira; if stale, ask refresh or ctx
+- ignore `.workitems/<TICKET-KEY>/plan.md`, `questions.md`, `tasks.json`, `progress.json`
+- write `pr-reviews/<TICKET-KEY>/review.md`, `review-tasks.json`, `review-progress.json`
+- missing planning artifacts are not findings
+
+Review:
+- Start with changed files + compact evidence; widen ctx only if needed; then check validation evidence.
+- Verify goals, AC, and expected outcomes.
+- Check correctness, arch fit, maintainability, coupling, compat, tests, doc/op impact, security, unsafe assumptions, failure modes.
+
+Outputs:
+- severities: `BLOCKING|SHOULD_FIX|FOLLOW_UP|INFO`
+- `review.md` starts with merge gate counts
+- `review-tasks.json` = compact fix tasks
+- `review-progress.json` = remediation state, next, blockers, opt input
+
+Chat only:
+- `WAIT` with `Need` / `Why` / `Next`
+- `BLOCKED`
+- `DONE`
+
+Rules:
+- only planner + PR review may fetch Jira
+- no one-shot review
+- compare expected vs actual, not style alone
+- do not infer success from partial impl
+- include useful feedback
+- check auth/validation/secrets/injection/data exposure/trust boundaries
+- identify missing/weak tests
+- write only `.workitems/<TICKET-KEY>/ticket.md` and `pr-reviews/<TICKET-KEY>/`
diff --git a/.github/prompts/review-ticket.prompt.md b/.github/prompts/review-ticket.prompt.md
new file mode 100644
index 0000000..ea0fe21
--- /dev/null
+++ b/.github/prompts/review-ticket.prompt.md
@@ -0,0 +1,34 @@
+Review <TICKET-KEY> vs ticket.
+
+Read:
+- `.workitems/<TICKET-KEY>/ticket.md`, `plan.md`, `questions.md`, `tasks.json`, `progress.json`, `pr-summary.md`
+- if `ticket.md` missing/stale, ask refresh
+- write `.workitems/<TICKET-KEY>/review.md`, `review-tasks.json`, `review-progress.json`
+- missing/stale exec artifacts are findings
+
+Review:
+- Start with `pr-summary.md` + changed files; widen ctx only if needed; then check validation evidence.
+- Verify goals, AC, and planned outcomes.
+- Check correctness, arch fit, maintainability, coupling, compat, tests, doc/op impact, security, unsafe assumptions, failure modes.
+- For doc/spec work, check correctness, completeness, consistency, clarity, actionability.
+
+Outputs:
+- severities: `BLOCKING|SHOULD_FIX|FOLLOW_UP|INFO`
+- `review.md` starts with merge gate counts
+- `review-tasks.json` = compact fix tasks
+- `review-progress.json` = remediation state, next, blockers, opt input
+
+Chat only:
+- `WAIT` with `Need` / `Why` / `Next`
+- `BLOCKED`
+- `DONE`
+
+Rules:
+- cached artifacts only; no Jira
+- no one-shot review
+- compare expected vs actual, not style alone
+- do not infer success from partial impl
+- include useful feedback
+- check auth/validation/secrets/injection/data exposure/trust boundaries
+- identify missing/weak tests, incl E2E when relevant
+- write only review files unless scope changes
diff --git a/.gitignore b/.gitignore
new file mode 100644
index 0000000..168a52f
--- /dev/null
+++ b/.gitignore
@@ -0,0 +1,4 @@
+.env
+node_modules/
+*.log
+.workitems/
diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 0000000..8a8d54c
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,18 @@
+# Project Engineering Rules
+
+## Architecture
+- Follow clean architecture principles.
+- Keep business logic out of controllers.
+- Avoid hidden coupling.
+
+## Compatibility
+- Preserve backward compatibility unless explicitly authorized.
+
+## Quality
+- Prefer small, testable changes.
+- Avoid duplicated logic.
+- Use explicit naming.
+
+## Testing
+- Add unit tests for meaningful changes.
+- Add integration tests for externally visible behavior changes.
diff --git a/README.md b/README.md
index dcb5bd0..97692bd 100644
--- a/README.md
+++ b/README.md
@@ -1 +1,83 @@
-# dev-agent-orchestrator
\ No newline at end of file
+# Jira Agent Workflow Packs
+
+This repo packages a Jira-backed delivery workflow for multiple AI clients.
+
+Client entry points:
+
+| Client | Installer | Guide | Runtime |
+| --- | --- | --- | --- |
+| GitHub Copilot | `setup/Install-CopilotJiraAgents.ps1` | `docs/copilot-setup-guide.md` | `.github/agents/*.agent.md` |
+| OpenAI Codex | `setup/Install-CodexWorkflow.ps1` | `docs/codex-setup-guide.md` | `.github/prompts/*.prompt.md` |
+| Claude Code | `setup/Install-ClaudeWorkflow.ps1` | `docs/claude-setup-guide.md` | installed slash-command pack |
+
+Notes:
+- `.github/agents/*.agent.md` is the current reference workflow for Copilot custom agents.
+- Codex/Claude prompt packs follow the same stage model, but artifact wording can differ by runtime pack.
+- Copilot CLI MCP setup is separate: `setup/Install-CopilotCliMcp.ps1`.
+
+## Current Copilot Agent Flow
+
+- `ImplementationPlanner`: fetches or refreshes `.workitems/<ticket>/ticket.md` when needed, asks clarification Qs one by one until stable, then writes `questions.md`, `plan.md`, `tasks.json`, and `progress.json`.
+- `SolutionDeveloper`: implements from cached `.workitems` only, stops on `.workitems/<ticket>/problems.md`, updates `tasks.json` and `progress.json` by delta, runs relevant feedback loops, and writes `pr-summary.md`.
+- `QualityReviewer`: reviews ticket-based work against `ticket.md`, planning artifacts, execution artifacts, and changed files; writes `review.md`, `review-tasks.json`, and `review-progress.json`.
+- `PRReviewer`: review-only path; may fetch or refresh `ticket.md` when needed and writes `pr-reviews/<ticket>/...` artifacts.
+- `ReviewFixer`: consumes review artifacts, fixes one finding at a time, updates remediation artifacts, and hands back to the source reviewer for re-review.
+
+## Shared Contract
+
+- Jira is read-only.
+- Only `ImplementationPlanner` and `PRReviewer` may fetch `ticket.md` from Jira.
+- Downstream ticket-based agents reuse cached `.workitems/<ticket>/ticket.md`.
+- Active stop gate: `.workitems/<ticket>/problems.md`.
+- Chat status contract for current Copilot agents: `WAIT`, `BLOCKED`, `DONE`.
+- `tasks.json` is the execution ledger.
+- `progress.json` is the compact current-loop snapshot.
+- `review-tasks.json` is the remediation ledger.
+- `review-progress.json` is the compact remediation snapshot.
+
+Generated ticket artifacts:
+- `.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>/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`
+
+Artifact ownership:
+- `ImplementationPlanner`: `ticket.md`, `plan.md`, `questions.md`, initial `tasks.json`, initial `progress.json`
+- `SolutionDeveloper`: ongoing `tasks.json`, ongoing `progress.json`, optional `problems.md`, `pr-summary.md`
+- `QualityReviewer`: ticket-based review artifacts
+- `PRReviewer`: PR review artifacts and shared `ticket.md` cache refresh when needed
+- `ReviewFixer`: ongoing remediation artifact updates
+
+## Prompt Size
+
+Measure current agent prompt sizes with:
+
+```powershell
+powershell -ExecutionPolicy Bypass -File .\tools\measure-agent-prompts.ps1
+```
+
+JSON output:
+
+```powershell
+powershell -ExecutionPolicy Bypass -File .\tools\measure-agent-prompts.ps1 -Json
+```
+
+## Guides
+
+- `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`
diff --git a/docs/agent-workflow-guide.md b/docs/agent-workflow-guide.md
new file mode 100644
index 0000000..4f0fba0
--- /dev/null
+++ b/docs/agent-workflow-guide.md
@@ -0,0 +1,144 @@
+# Agent Workflow Guide
+
+## Scope
+
+This guide documents the current workflow contract shared by the Copilot custom agents in `.github/agents/*.agent.md` and the portable prompt packs in `.github/prompts/*.prompt.md`.
+
+## Stages
+
+1. `ImplementationPlanner`
+2. `SolutionDeveloper`
+3. `QualityReviewer`
+4. `ReviewFixer`
+5. `PRReviewer` for review-only paths
+
+## Jira Ownership
+
+- Jira is read-only.
+- Only `ImplementationPlanner` and `PRReviewer` may fetch or refresh `.workitems/<ticket>/ticket.md`.
+- Other ticket-based agents must reuse cached `.workitems/<ticket>/ticket.md`.
+
+## Core Artifacts
+
+Ticket workflow:
+- `.workitems/<ticket>/ticket.md`
+- `.workitems/<ticket>/questions.md`
+- `.workitems/<ticket>/plan.md`
+- `.workitems/<ticket>/tasks.json`
+- `.workitems/<ticket>/progress.json`
+- `.workitems/<ticket>/problems.md`
+- `.workitems/<ticket>/pr-summary.md`
+- `.workitems/<ticket>/review.md`
+- `.workitems/<ticket>/review-tasks.json`
+- `.workitems/<ticket>/review-progress.json`
+
+PR-review workflow:
+- `.workitems/<ticket>/ticket.md`
+- `pr-reviews/<ticket>/review.md`
+- `pr-reviews/<ticket>/review-tasks.json`
+- `pr-reviews/<ticket>/review-progress.json`
+
+Artifact roles:
+- `tasks.json`: execution ledger
+- `progress.json`: compact current-loop snapshot
+- `review-tasks.json`: remediation ledger
+- `review-progress.json`: compact remediation snapshot
+- `problems.md`: temporary stop gate only while blocked
+
+Current compact task status set:
+- `todo`
+- `doing`
+- `done`
+- `blocked`
+
+## Agent Responsibilities
+
+### `ImplementationPlanner`
+
+- fetch or refresh `ticket.md` when needed
+- read repo rules and relevant code/design context
+- ask one high-value clarification question at a time until stable
+- write `questions.md`, `plan.md`, `tasks.json`, `progress.json`
+- map `tasks.json` to acceptance criteria
+- stop before implementation
+
+### `SolutionDeveloper`
+
+- implement from cached `.workitems`
+- stop immediately if `.workitems/<ticket>/problems.md` exists
+- work one task at a time
+- pick next task by priority, not list order
+- update `tasks.json` and `progress.json` by delta only
+- run all relevant feedback loops before marking work done
+- write `pr-summary.md`
+
+Priority order:
+1. architecture/core abstractions
+2. integration points
+3. unknowns/spikes
+4. standard features
+5. cleanup/polish
+
+### `QualityReviewer`
+
+- review ticket-based work against `ticket.md`, planning artifacts, execution artifacts, and changed files
+- verify goals, AC, validation, architecture fit, compatibility, and security
+- write `review.md`, `review-tasks.json`, `review-progress.json`
+
+### `PRReviewer`
+
+- review without using `.workitems/<ticket>/plan.md`, `questions.md`, `tasks.json`, or `progress.json`
+- may fetch or refresh `ticket.md`
+- write `pr-reviews/<ticket>/review.md`, `review-tasks.json`, `review-progress.json`
+
+### `ReviewFixer`
+
+- consume either ticket-based or PR-based review artifacts
+- fix one finding at a time
+- update remediation artifacts by delta only
+- preserve evidence for deferred, disputed, or `not_applicable` outcomes
+- re-run the source reviewer after fixes: `QualityReviewer` for ticket review, `PRReviewer` for PR review
+
+## Chat Contract
+
+Current Copilot agents only chat on:
+- `WAIT`
+- `BLOCKED`
+- `DONE`
+
+`WAIT` uses:
+- `Need`
+- `Why`
+- `Next`
+
+## Typical Flow
+
+Ticket path:
+1. Run `ImplementationPlanner`
+2. Run `SolutionDeveloper`
+3. Run `QualityReviewer`
+4. If needed, run `ReviewFixer`
+5. Re-run `QualityReviewer`
+
+PR review path:
+1. Run `PRReviewer`
+2. If needed, run `ReviewFixer`
+3. Re-run `PRReviewer`
+
+## Resume Model
+
+Implementation resume should normally need only:
+- `progress.json`
+- `tasks.json`
+- `ticket.md`
+- `plan.md` or `questions.md` only when needed
+
+This keeps loop cost low while preserving current state.
+
+## Prompt Size
+
+Measure current custom-agent prompt sizes with:
+
+```powershell
+powershell -ExecutionPolicy Bypass -File .\tools\measure-agent-prompts.ps1
+```
diff --git a/docs/claude-setup-guide.md b/docs/claude-setup-guide.md
new file mode 100644
index 0000000..c9dc820
--- /dev/null
+++ b/docs/claude-setup-guide.md
@@ -0,0 +1,120 @@
+# Claude Setup Guide
+
+## Purpose
+
+Use this guide only for Claude Code.
+
+Claude does not use this repository's `.agent.md` format. The Claude installer provisions a dedicated slash-command pack aligned to the same compact workflow contract and can optionally register the Atlassian MCP server with the Claude CLI.
+
+## What The Claude Installer Provisions
+
+- user-level command files under `~/.claude/commands`
+- optional Atlassian MCP registration through `claude mcp add`
+
+Installed slash commands:
+
+- `/jira-plan-ticket`
+- `/jira-implement-ticket`
+- `/jira-review-ticket`
+- `/jira-pr-review`
+- `/jira-fix-review`
+
+## Install
+
+Command pack only:
+
+```powershell
+powershell -ExecutionPolicy Bypass -File .\setup\Install-ClaudeWorkflow.ps1
+```
+
+Command pack plus Atlassian MCP registration:
+
+```powershell
+powershell -ExecutionPolicy Bypass -File .\setup\Install-ClaudeWorkflow.ps1 -InstallMcpServer
+```
+
+Installer parameters:
+
+- `-CommandTarget`
+  Override the Claude commands directory.
+- `-InstallMcpServer`
+  Runs `claude mcp add` for the Atlassian server.
+- `-McpScope`
+  Choose `user`, `local`, or `project` scope for the MCP registration.
+
+## Configure
+
+If you do not use `-InstallMcpServer`, add Atlassian MCP manually:
+
+```text
+claude mcp add --transport http --scope user atlassian https://mcp.atlassian.com/v1/mcp
+```
+
+Read-only note:
+
+- The workflow expects Jira use to stay read-only.
+- Enforce read-only behavior through your Atlassian-side MCP tool policy, not only through the slash-command text.
+- Only `/jira-plan-ticket` and `/jira-pr-review` may fetch or refresh `.workitems/<ticket>/ticket.md`.
+- Other ticket-based steps must reuse cached `.workitems/<ticket>/ticket.md`.
+- If a ticket-local stop gate is needed, place it at `.workitems/<ticket>/problems.md`.
+
+Implementation note:
+
+- `/jira-plan-ticket` creates the initial `.workitems/<ticket>/tasks.json` and `.workitems/<ticket>/progress.json`; `/jira-implement-ticket` owns their ongoing updates during implementation.
+- `/jira-implement-ticket` uses `.workitems/<ticket>/tasks.json` as the execution ledger and `.workitems/<ticket>/progress.json` as the compact current-state snapshot.
+- Task states are `todo|doing|done|blocked`; keep exactly one `doing`.
+- `.workitems/<ticket>/problems.md` is a temporary active blocker file. If it exists, the implementer stops and reports a blocker instead of continuing.
+- Developer action when `.workitems/<ticket>/problems.md` exists: resolve the blocker described there, then delete the file before rerunning implementation. Do not leave an empty file behind, and do not use `problems.md` for ordinary in-scope coding issues the implementer should fix directly.
+
+## Use With Claude Code
+
+Start Claude Code in the target repository:
+
+```text
+claude
+```
+
+Run the installed slash commands with a Jira ticket key:
+
+```text
+/jira-plan-ticket ENG-123
+```
+
+```text
+/jira-implement-ticket ENG-123
+```
+
+```text
+/jira-review-ticket ENG-123
+```
+
+```text
+/jira-pr-review ENG-123
+```
+
+```text
+/jira-fix-review ENG-123
+```
+
+Recommended sequence:
+
+1. `/jira-plan-ticket`
+2. `/jira-implement-ticket`
+3. `/jira-review-ticket`
+4. `/jira-fix-review` if needed
+
+During implementation, expect the workflow to update `.workitems/<ticket>/tasks.json` and `.workitems/<ticket>/progress.json`, and to create `.workitems/<ticket>/problems.md` only when active blocker handling is needed and delete it once the blocker is resolved.
+
+Review-only sequence:
+
+1. `/jira-pr-review`
+2. `/jira-fix-review` if needed
+
+`/jira-pr-review` may create or refresh `.workitems/<ticket>/ticket.md` for the shared Jira cache even when the rest of `.workitems/<ticket>/` planning artifacts do not exist.
+
+## Troubleshooting
+
+- Run `claude mcp list` and confirm `atlassian` is present.
+- Confirm the installed command files exist under `~/.claude/commands`.
+- Restart the Claude session after changing slash commands or MCP configuration.
+- If authentication fails, follow your Atlassian organization guidance for MCP or Rovo access.
diff --git a/docs/codex-setup-guide.md b/docs/codex-setup-guide.md
new file mode 100644
index 0000000..715c389
--- /dev/null
+++ b/docs/codex-setup-guide.md
@@ -0,0 +1,109 @@
+# Codex Setup Guide
+
+## Purpose
+
+Use this guide only for the official OpenAI Codex CLI workflow.
+
+Codex does not consume this repository's `.agent.md` files directly. The Codex installer provisions a dedicated prompt pack aligned to the same compact workflow contract.
+
+## What The Codex Installer Provisions
+
+- user-level prompt files under `~/.codex/prompts`
+- optional Atlassian MCP registration in `~/.codex/config.toml`
+
+Installed prompt names:
+
+- `jira-plan-ticket`
+- `jira-implement-ticket`
+- `jira-review-ticket`
+- `jira-pr-review`
+- `jira-fix-review`
+
+## Install
+
+Prompt pack only:
+
+```powershell
+powershell -ExecutionPolicy Bypass -File .\setup\Install-CodexWorkflow.ps1
+```
+
+Prompt pack plus Atlassian MCP config:
+
+```powershell
+powershell -ExecutionPolicy Bypass -File .\setup\Install-CodexWorkflow.ps1 -InstallMcpConfig
+```
+
+Installer parameters:
+
+- `-PromptTarget`
+  Override the Codex prompt directory.
+- `-ConfigPath`
+  Override the Codex config file path.
+- `-InstallMcpConfig`
+  Appends an `atlassian` MCP server entry to `config.toml` if one does not already exist.
+
+## Configure
+
+If you do not use `-InstallMcpConfig`, add Atlassian MCP manually to `~/.codex/config.toml`:
+
+```toml
+[mcp_servers.atlassian]
+url = "https://mcp.atlassian.com/v1/mcp"
+```
+
+Read-only note:
+
+- The workflow expects Jira use to stay read-only.
+- Enforce read-only behavior through your Atlassian-side MCP tool policy, not only through the prompt text.
+- Only `jira-plan-ticket` and `jira-pr-review` may fetch or refresh `.workitems/<ticket>/ticket.md`.
+- Other ticket-based steps must reuse cached `.workitems/<ticket>/ticket.md`.
+- If a ticket-local stop gate is needed, place it at `.workitems/<ticket>/problems.md`.
+
+Implementation note:
+
+- `jira-plan-ticket` creates the initial `.workitems/<ticket>/tasks.json` and `.workitems/<ticket>/progress.json`; `jira-implement-ticket` owns their ongoing updates during implementation.
+- `jira-implement-ticket` uses `.workitems/<ticket>/tasks.json` as the execution ledger and `.workitems/<ticket>/progress.json` as the compact current-state snapshot.
+- Task states are `todo|doing|done|blocked`; keep exactly one `doing`.
+- `.workitems/<ticket>/problems.md` is a temporary active blocker file. If it exists, the implementer stops and reports a blocker instead of continuing.
+- Developer action when `.workitems/<ticket>/problems.md` exists: resolve the blocker described there, then delete the file before rerunning implementation. Do not leave an empty file behind, and do not use `problems.md` for ordinary in-scope coding issues the implementer should fix directly.
+
+## Use With Codex
+
+Start Codex in the target repository:
+
+```text
+codex
+```
+
+Then run the installed Jira workflow prompt from the Codex slash-command menu.
+
+Examples:
+
+- `/jira-plan-ticket ENG-123`
+- `/jira-implement-ticket ENG-123`
+- `/jira-review-ticket ENG-123`
+- `/jira-pr-review ENG-123`
+- `/jira-fix-review ENG-123`
+
+Recommended sequence:
+
+1. `jira-plan-ticket`
+2. `jira-implement-ticket`
+3. `jira-review-ticket`
+4. `jira-fix-review` if needed
+
+During implementation, expect the workflow to update `.workitems/<ticket>/tasks.json` and `.workitems/<ticket>/progress.json`, and to create `.workitems/<ticket>/problems.md` only when active blocker handling is needed and delete it once the blocker is resolved.
+
+Review-only sequence:
+
+1. `jira-pr-review`
+2. `jira-fix-review` if needed
+
+`jira-pr-review` may create or refresh `.workitems/<ticket>/ticket.md` for the shared Jira cache even when the rest of `.workitems/<ticket>/` planning artifacts do not exist.
+
+## Troubleshooting
+
+- Confirm you are using the official OpenAI Codex CLI, not an unrelated third-party `codex` npm package.
+- Confirm the prompt files exist under `~/.codex/prompts`.
+- Confirm `~/.codex/config.toml` contains the Atlassian MCP server entry if Jira tools do not appear.
+- Restart the Codex session after changing prompt or MCP configuration.
diff --git a/docs/copilot-setup-guide.md b/docs/copilot-setup-guide.md
new file mode 100644
index 0000000..b436a94
--- /dev/null
+++ b/docs/copilot-setup-guide.md
@@ -0,0 +1,143 @@
+# Copilot Setup Guide
+
+## Purpose
+
+Use this guide only for GitHub Copilot.
+
+This path installs the native `.agent.md` definitions and covers the separate Copilot CLI MCP provisioner. Do not use the Codex or Claude installers for Copilot sessions.
+
+## What The Copilot Installers Provision
+
+Agent installer:
+
+- user-level custom agents under `~/.copilot/agents`
+- Atlassian MCP registration in the VS Code user-profile `mcp.json`
+- optional workspace `.vscode/mcp.json` for compatibility
+
+CLI MCP provisioner:
+
+- Copilot CLI MCP registration in `~/.copilot/mcp-config.json`
+
+Installed agent profiles:
+
+- `ticket-planner` -> `ImplementationPlanner`
+- `ticket-implementer` -> `SolutionDeveloper`
+- `strict-reviewer` -> `QualityReviewer`
+- `pr-reviewer` -> `PRReviewer`
+- `review-fixer` -> `ReviewFixer`
+
+Use the display name in the Copilot UI. Use the profile id with `copilot --agent=...`.
+
+## Install
+
+Install custom agents and VS Code MCP:
+
+```powershell
+powershell -ExecutionPolicy Bypass -File .\setup\Install-CopilotJiraAgents.ps1
+```
+
+Optional workspace MCP config:
+
+```powershell
+powershell -ExecutionPolicy Bypass -File .\setup\Install-CopilotJiraAgents.ps1 -InstallWorkspaceConfig
+```
+
+Install Copilot CLI MCP separately:
+
+```powershell
+powershell -ExecutionPolicy Bypass -File .\setup\Install-CopilotCliMcp.ps1
+```
+
+Agent installer parameters:
+
+- `-UserMcpPath`
+  Override the VS Code user-profile `mcp.json` path.
+- `-InstallWorkspaceConfig`
+  Also writes `.vscode/mcp.json` in the selected workspace.
+- `-WorkspaceRoot`
+  Choose the workspace root used with `-InstallWorkspaceConfig`.
+
+CLI MCP provisioner parameters:
+
+- `-CliMcpPath`
+  Override the Copilot CLI MCP config path. The default is `~/.copilot/mcp-config.json`.
+
+## Configure
+
+After installation in VS Code:
+
+1. Reload the window.
+2. Run `MCP: List Servers`.
+3. Start or trust `atlassian`.
+4. Complete the Atlassian authentication flow if prompted.
+
+After installing the Copilot CLI MCP provisioner:
+
+1. Start `copilot` in the target repository.
+2. Run `/mcp show`.
+3. Confirm `atlassian` is listed and enabled.
+
+Read-only note:
+
+- In the current Copilot custom-agent set, only `ImplementationPlanner` and `PRReviewer` use `atlassian/*`.
+- Hard read-only enforcement must be configured outside this repository by disabling write-capable Atlassian MCP tools in the platform or organization settings.
+- Only `ImplementationPlanner` and `PRReviewer` may fetch or refresh `.workitems/<ticket>/ticket.md`.
+- Other ticket-based agents must reuse cached `.workitems/<ticket>/ticket.md`.
+- If a ticket-local stop gate is needed, place it at `.workitems/<ticket>/problems.md`.
+
+Implementation note:
+
+- `ImplementationPlanner` creates the initial `.workitems/<ticket>/tasks.json` and `.workitems/<ticket>/progress.json`; `SolutionDeveloper` owns their ongoing updates during implementation.
+- `SolutionDeveloper` keeps `.workitems/<ticket>/progress.json` as the compact current-loop snapshot and `tasks.json` as the durable execution ledger.
+- `.workitems/<ticket>/problems.md` is a temporary active blocker file. If it exists, `SolutionDeveloper` stops and reports a blocker instead of implementing.
+- Developer action when `.workitems/<ticket>/problems.md` exists: resolve the blocker described there, then delete the file before rerunning implementation. Do not leave an empty file behind, and do not use `problems.md` for ordinary in-scope coding issues the implementer should fix directly.
+
+## Use With Copilot
+
+### VS Code Custom Agents
+
+Start with `ImplementationPlanner` and provide a Jira ticket key. Continue with:
+
+- `SolutionDeveloper` after `.workitems/<ticket>/` planning artifacts exist
+- `QualityReviewer` after implementation
+- `PRReviewer` for review-only flows without `.workitems/<ticket>/` planning artifacts
+- `ReviewFixer` after either review mode generates remediation artifacts
+
+During implementation, expect `SolutionDeveloper` to update `.workitems/<ticket>/tasks.json` and `.workitems/<ticket>/progress.json`, and to create `.workitems/<ticket>/problems.md` only when active blocker handling is needed and delete it once the blocker is resolved.
+
+### Copilot CLI Examples
+
+For Copilot CLI, use both Copilot-specific installers:
+
+1. `setup/Install-CopilotJiraAgents.ps1` for the custom agents
+2. `setup/Install-CopilotCliMcp.ps1` for `~/.copilot/mcp-config.json`
+
+Interactive selection:
+
+```text
+copilot
+/agent
+```
+
+Direct invocation examples:
+
+```text
+copilot --agent=ticket-planner --prompt "Plan Jira ticket ENG-123 using Atlassian MCP and create .workitems artifacts."
+```
+
+```text
+copilot --agent=ticket-implementer --prompt "Continue ENG-123 from .workitems/ENG-123 and implement the highest-priority pending task."
+```
+
+```text
+copilot --agent=pr-reviewer --prompt "Review ENG-123 against Jira expectations and write pr-reviews/ENG-123 artifacts."
+```
+
+## Troubleshooting
+
+- Confirm `~/.copilot/agents` contains the installed agent files.
+- Confirm `~/.copilot/mcp-config.json` contains an `mcpServers.atlassian` entry when using Copilot CLI.
+- In Copilot CLI, run `/mcp show` to verify the server is active.
+- Run `MCP: Reset Cached Tools` if tools do not appear.
+- Run `MCP: Open User Configuration` and confirm the file contains an `atlassian` server entry pointing to `https://mcp.atlassian.com/v1/mcp`.
+- If the MCP server is visible but authentication fails, follow your Atlassian organization guidance for MCP or Rovo access.
diff --git a/docs/external-components.md b/docs/external-components.md
new file mode 100644
index 0000000..e4888e4
--- /dev/null
+++ b/docs/external-components.md
@@ -0,0 +1,77 @@
+# External Components
+
+This document records the external platforms, protocols, and services that this repository depends on at runtime or during setup.
+
+## Purpose
+
+This repository does not host its own Jira integration service. It installs local agent or prompt-pack definitions and connects them to external platform capabilities that are owned and operated outside this repository.
+
+## External Components In Use
+
+| Component | Type | Owner | How it is used here | Repo-owned? |
+| --- | --- | --- | --- | --- |
+| Model Context Protocol (MCP) | Open protocol / integration contract | Official MCP ecosystem | Used as the integration model for exposing external tools to agents in compatible clients. This repo consumes MCP through client configuration and agent tool declarations. | No |
+| Atlassian MCP server | Remote MCP server | Atlassian | Primary Jira access path for the agents in this repo. The configured endpoint is `https://mcp.atlassian.com/v1/mcp`. | No |
+| Atlassian Jira | External SaaS system | Atlassian | Ticket data is read through the Atlassian MCP server, cached in `.workitems/<ticket>/ticket.md`, and then reused by agents for planning, implementation, review, and remediation. | No |
+| Visual Studio Code MCP configuration | Client platform integration point | Microsoft | The installer writes MCP server registration into VS Code `mcp.json` so the `atlassian` server is available to agent sessions. | No |
+| GitHub Copilot custom agents | Client/runtime feature | GitHub | The repository provides `.agent.md` definitions that are installed into the user's Copilot agents directory and executed by the client. | No |
+| OpenAI Codex CLI prompt packs | Client/runtime feature | OpenAI | The repository provides prompt templates that can be installed into the Codex prompt directory and invoked from the official Codex CLI. | No |
+| Claude Code custom slash commands | Client/runtime feature | Anthropic | The repository provides prompt templates that can be installed as Claude slash commands and used from the Claude CLI. | No |
+
+## Official MCP Position
+
+- This repository uses Atlassian's official MCP server, not a repo-managed custom Jira MCP service.
+- The configured server name is `atlassian`.
+- The configured server URL is `https://mcp.atlassian.com/v1/mcp`.
+- This is the preferred setup because authentication, authorization, and auditability are handled by Atlassian's platform rather than custom code in this repository.
+
+## Security And Access Model
+
+- In the current Copilot custom-agent set, only `ImplementationPlanner` and `PRReviewer` declare Jira access through `atlassian/*`.
+- Downstream ticket-based agents reuse cached `.workitems/<ticket>/ticket.md` instead of fetching Jira directly.
+- The intended Jira usage is read-only.
+- Hard read-only enforcement is external to this repository. It must be configured by disabling write-capable Atlassian MCP tools in the platform or organization tool-selection settings.
+- Agents in this repository explicitly instruct against commenting on issues, editing fields, transitioning issues, or making other Jira changes.
+- Once fetched, the preferred local ticket reference is `.workitems/<ticket>/ticket.md` rather than repeated Jira MCP reads.
+- No local Jira server process is started by this repository.
+- No repo-managed Jira credentials or secrets are required for the default setup.
+- Authentication is handled externally by the client and Atlassian, typically through OAuth 2.1 or Atlassian-scoped API token flows, depending on organization setup.
+
+## Where The Integration Is Declared
+
+- Installer scripts:
+  - [setup/Install-CopilotJiraAgents.ps1](/c:/GAP/agents/dev-agent-orchestrator/setup/Install-CopilotJiraAgents.ps1)
+  - [setup/Install-CopilotCliMcp.ps1](/c:/GAP/agents/dev-agent-orchestrator/setup/Install-CopilotCliMcp.ps1)
+  - [setup/Install-CodexWorkflow.ps1](/c:/GAP/agents/dev-agent-orchestrator/setup/Install-CodexWorkflow.ps1)
+  - [setup/Install-ClaudeWorkflow.ps1](/c:/GAP/agents/dev-agent-orchestrator/setup/Install-ClaudeWorkflow.ps1)
+- Setup guides:
+  - [docs/copilot-setup-guide.md](/c:/GAP/agents/dev-agent-orchestrator/docs/copilot-setup-guide.md)
+  - [docs/codex-setup-guide.md](/c:/GAP/agents/dev-agent-orchestrator/docs/codex-setup-guide.md)
+  - [docs/claude-setup-guide.md](/c:/GAP/agents/dev-agent-orchestrator/docs/claude-setup-guide.md)
+- Main overview: [README.md](/c:/GAP/agents/dev-agent-orchestrator/README.md)
+- Agent definitions:
+  - [ticket-planner.agent.md](/c:/GAP/agents/dev-agent-orchestrator/.github/agents/ticket-planner.agent.md)
+  - [ticket-implementer.agent.md](/c:/GAP/agents/dev-agent-orchestrator/.github/agents/ticket-implementer.agent.md)
+  - [strict-reviewer.agent.md](/c:/GAP/agents/dev-agent-orchestrator/.github/agents/strict-reviewer.agent.md)
+  - [pr-reviewer.agent.md](/c:/GAP/agents/dev-agent-orchestrator/.github/agents/pr-reviewer.agent.md)
+  - [review-fixer.agent.md](/c:/GAP/agents/dev-agent-orchestrator/.github/agents/review-fixer.agent.md)
+- Portable prompt templates:
+  - [plan-ticket.prompt.md](/c:/GAP/agents/dev-agent-orchestrator/.github/prompts/plan-ticket.prompt.md)
+  - [implement-ticket.prompt.md](/c:/GAP/agents/dev-agent-orchestrator/.github/prompts/implement-ticket.prompt.md)
+  - [review-ticket.prompt.md](/c:/GAP/agents/dev-agent-orchestrator/.github/prompts/review-ticket.prompt.md)
+  - [pr-review.prompt.md](/c:/GAP/agents/dev-agent-orchestrator/.github/prompts/pr-review.prompt.md)
+  - [fix-review.prompt.md](/c:/GAP/agents/dev-agent-orchestrator/.github/prompts/fix-review.prompt.md)
+
+## What This Repository Does Not Provide
+
+- A custom MCP server implementation
+- A self-hosted Jira bridge
+- Repo-local Jira credentials management
+- Direct Jira browser automation as the primary integration path
+
+## Operational Notes
+
+- Copilot installs user-level custom agents under `~/.copilot/agents`, can write VS Code MCP config, and has a separate CLI MCP config at `~/.copilot/mcp-config.json`.
+- Codex installs prompt files under `~/.codex/prompts` and can use `~/.codex/config.toml` for MCP registration.
+- Claude installs slash-command files under `~/.claude/commands` and can register MCP through `claude mcp add`.
+- If the external Atlassian MCP server is unavailable, users must provide equivalent ticket details directly to the agent.
diff --git a/setup/Install-ClaudeWorkflow.ps1 b/setup/Install-ClaudeWorkflow.ps1
new file mode 100644
index 0000000..8455ac1
--- /dev/null
+++ b/setup/Install-ClaudeWorkflow.ps1
@@ -0,0 +1,107 @@
+[CmdletBinding()]
+param(
+    [string]$CommandTarget = (Join-Path $HOME ".claude\commands"),
+    [switch]$InstallMcpServer,
+    [ValidateSet("user", "local", "project")]
+    [string]$McpScope = "user"
+)
+
+Set-StrictMode -Version Latest
+$ErrorActionPreference = "Stop"
+
+function Ensure-Directory {
+    param([string]$Path)
+    if (-not (Test-Path -LiteralPath $Path)) {
+        New-Item -ItemType Directory -Force -Path $Path | Out-Null
+    }
+}
+
+function Install-ClaudeCommand {
+    param(
+        [string]$SourcePath,
+        [string]$TargetPath,
+        [string]$Description
+    )
+
+    $body = Get-Content -LiteralPath $SourcePath -Raw
+    $body = $body.Replace('<TICKET-KEY>', '$ARGUMENTS')
+    $content = @"
+---
+description: $Description
+argument-hint: <TICKET-KEY>
+---
+$body
+"@
+
+    Set-Content -LiteralPath $TargetPath -Value $content -Encoding UTF8
+}
+
+$scriptRoot = Split-Path -Parent $MyInvocation.MyCommand.Path
+$repoRoot = Split-Path -Parent $scriptRoot
+$promptSourceRoot = Join-Path $repoRoot ".github\prompts"
+
+$commandMap = @(
+    @{
+        Source = "plan-ticket.prompt.md"
+        Target = "jira-plan-ticket.md"
+        Description = "Plan a Jira ticket into .workitems/<ticket>/ artifacts, including cached ticket context."
+    },
+    @{
+        Source = "implement-ticket.prompt.md"
+        Target = "jira-implement-ticket.md"
+        Description = "Implement the highest-priority pending Jira workflow task for a ticket and keep loop artifacts current."
+    },
+    @{
+        Source = "review-ticket.prompt.md"
+        Target = "jira-review-ticket.md"
+        Description = "Review a ticket implementation and produce remediation artifacts."
+    },
+    @{
+        Source = "pr-review.prompt.md"
+        Target = "jira-pr-review.md"
+        Description = "Review an existing pull request against cached or refreshed ticket context and write PR review artifacts."
+    },
+    @{
+        Source = "fix-review.prompt.md"
+        Target = "jira-fix-review.md"
+        Description = "Fix review findings and update remediation artifacts."
+    }
+)
+
+Ensure-Directory $CommandTarget
+
+Write-Host ""
+Write-Host "Installing Claude command pack into: $CommandTarget" -ForegroundColor Cyan
+
+foreach ($entry in $commandMap) {
+    $sourcePath = Join-Path $promptSourceRoot $entry.Source
+    $targetPath = Join-Path $CommandTarget $entry.Target
+    Install-ClaudeCommand -SourcePath $sourcePath -TargetPath $targetPath -Description $entry.Description
+}
+
+if ($InstallMcpServer) {
+    Write-Host "Registering Atlassian MCP server with Claude Code scope '$McpScope'" -ForegroundColor Cyan
+    & claude mcp add --transport http --scope $McpScope atlassian https://mcp.atlassian.com/v1/mcp | Out-Host
+}
+
+Write-Host ""
+Write-Host "Done." -ForegroundColor Green
+Write-Host "Claude commands: $CommandTarget"
+if ($InstallMcpServer) {
+    Write-Host "Claude MCP scope: $McpScope"
+}
+Write-Host "Installed command names:"
+Write-Host "- /jira-plan-ticket"
+Write-Host "- /jira-implement-ticket"
+Write-Host "- /jira-review-ticket"
+Write-Host "- /jira-pr-review"
+Write-Host "- /jira-fix-review"
+Write-Host ""
+Write-Host "Next steps:" -ForegroundColor Yellow
+Write-Host "1. Start Claude Code in your project."
+Write-Host "2. Run one of the installed /jira-* commands with a Jira ticket key argument."
+Write-Host "3. Expect planning artifacts under .workitems/<ticket>/, including ticket.md. Implementation keeps tasks.json as the ledger and progress.json as the snapshot. Only /jira-plan-ticket and /jira-pr-review refresh ticket.md."
+Write-Host "4. .workitems/<ticket>/problems.md is a temporary active blocker file. If it exists, the implementer will stop before changing code. Resolve the blocker and delete the file to continue."
+if (-not $InstallMcpServer) {
+    Write-Host "5. Add Atlassian MCP with: claude mcp add --transport http --scope user atlassian https://mcp.atlassian.com/v1/mcp"
+}
diff --git a/setup/Install-CodexWorkflow.ps1 b/setup/Install-CodexWorkflow.ps1
new file mode 100644
index 0000000..f73da1c
--- /dev/null
+++ b/setup/Install-CodexWorkflow.ps1
@@ -0,0 +1,108 @@
+[CmdletBinding()]
+param(
+    [string]$PromptTarget = (Join-Path $HOME ".codex\prompts"),
+    [string]$ConfigPath = (Join-Path $HOME ".codex\config.toml"),
+    [switch]$InstallMcpConfig
+)
+
+Set-StrictMode -Version Latest
+$ErrorActionPreference = "Stop"
+
+function Ensure-Directory {
+    param([string]$Path)
+    if (-not (Test-Path -LiteralPath $Path)) {
+        New-Item -ItemType Directory -Force -Path $Path | Out-Null
+    }
+}
+
+function Install-PromptFile {
+    param(
+        [string]$SourcePath,
+        [string]$TargetPath
+    )
+
+    $content = Get-Content -LiteralPath $SourcePath -Raw
+    $content = $content.Replace('<TICKET-KEY>', '$ARGUMENTS')
+    Set-Content -LiteralPath $TargetPath -Value $content -Encoding UTF8
+}
+
+function Ensure-CodexMcpServer {
+    param([string]$Path)
+
+    $serverBlock = @"
+[mcp_servers.atlassian]
+url = "https://mcp.atlassian.com/v1/mcp"
+"@
+
+    if (-not (Test-Path -LiteralPath $Path)) {
+        Ensure-Directory (Split-Path -Parent $Path)
+        Set-Content -LiteralPath $Path -Value ($serverBlock + [Environment]::NewLine) -Encoding UTF8
+        return
+    }
+
+    $content = Get-Content -LiteralPath $Path -Raw
+    if ($content -match '(?m)^\[mcp_servers\.atlassian\]\s*$') {
+        return
+    }
+
+    $trimmed = $content.TrimEnd()
+    if ([string]::IsNullOrWhiteSpace($trimmed)) {
+        $updated = $serverBlock + [Environment]::NewLine
+    }
+    else {
+        $updated = $trimmed + [Environment]::NewLine + [Environment]::NewLine + $serverBlock + [Environment]::NewLine
+    }
+
+    Set-Content -LiteralPath $Path -Value $updated -Encoding UTF8
+}
+
+$scriptRoot = Split-Path -Parent $MyInvocation.MyCommand.Path
+$repoRoot = Split-Path -Parent $scriptRoot
+$promptSourceRoot = Join-Path $repoRoot ".github\prompts"
+
+$promptMap = [ordered]@{
+    "plan-ticket.prompt.md" = "jira-plan-ticket.md"
+    "implement-ticket.prompt.md" = "jira-implement-ticket.md"
+    "review-ticket.prompt.md" = "jira-review-ticket.md"
+    "pr-review.prompt.md" = "jira-pr-review.md"
+    "fix-review.prompt.md" = "jira-fix-review.md"
+}
+
+Ensure-Directory $PromptTarget
+
+Write-Host ""
+Write-Host "Installing Codex prompt pack into: $PromptTarget" -ForegroundColor Cyan
+
+foreach ($entry in $promptMap.GetEnumerator()) {
+    $sourcePath = Join-Path $promptSourceRoot $entry.Key
+    $targetPath = Join-Path $PromptTarget $entry.Value
+    Install-PromptFile -SourcePath $sourcePath -TargetPath $targetPath
+}
+
+if ($InstallMcpConfig) {
+    Write-Host "Ensuring Atlassian MCP configuration in: $ConfigPath" -ForegroundColor Cyan
+    Ensure-CodexMcpServer -Path $ConfigPath
+}
+
+Write-Host ""
+Write-Host "Done." -ForegroundColor Green
+Write-Host "Codex prompts: $PromptTarget"
+if ($InstallMcpConfig) {
+    Write-Host "Codex config: $ConfigPath"
+}
+Write-Host "Installed prompt names:"
+Write-Host "- jira-plan-ticket"
+Write-Host "- jira-implement-ticket"
+Write-Host "- jira-review-ticket"
+Write-Host "- jira-pr-review"
+Write-Host "- jira-fix-review"
+Write-Host ""
+Write-Host "Next steps:" -ForegroundColor Yellow
+Write-Host "1. Start the official OpenAI Codex CLI in your project."
+Write-Host "2. Run an installed slash prompt such as /jira-plan-ticket ENG-123."
+Write-Host "3. Use the jira-* prompt that matches your workflow stage."
+Write-Host "4. Expect planning artifacts under .workitems/<ticket>/, including ticket.md. Implementation keeps tasks.json as the ledger and progress.json as the snapshot. Only jira-plan-ticket and jira-pr-review refresh ticket.md."
+Write-Host "5. .workitems/<ticket>/problems.md is a temporary active blocker file. If it exists, the implementer will stop before changing code. Resolve the blocker and delete the file to continue."
+if (-not $InstallMcpConfig) {
+    Write-Host "6. Add Atlassian MCP to ~/.codex/config.toml or rerun this installer with -InstallMcpConfig."
+}
diff --git a/setup/Install-CopilotCliMcp.ps1 b/setup/Install-CopilotCliMcp.ps1
new file mode 100644
index 0000000..80d06a8
--- /dev/null
+++ b/setup/Install-CopilotCliMcp.ps1
@@ -0,0 +1,106 @@
+[CmdletBinding()]
+param(
+    [string]$CliMcpPath = (Join-Path $HOME ".copilot\mcp-config.json")
+)
+
+Set-StrictMode -Version Latest
+$ErrorActionPreference = "Stop"
+
+function Ensure-Directory {
+    param([string]$Path)
+    if (-not (Test-Path -LiteralPath $Path)) {
+        New-Item -ItemType Directory -Force -Path $Path | Out-Null
+    }
+}
+
+function ConvertTo-NativeObject {
+    param([Parameter(ValueFromPipeline = $true)]$InputObject)
+
+    if ($null -eq $InputObject) {
+        return $null
+    }
+
+    if ($InputObject -is [System.Collections.IDictionary]) {
+        $result = [ordered]@{}
+        foreach ($key in $InputObject.Keys) {
+            $result[$key] = ConvertTo-NativeObject $InputObject[$key]
+        }
+        return $result
+    }
+
+    if ($InputObject -is [System.Collections.IEnumerable] -and -not ($InputObject -is [string])) {
+        $items = @()
+        foreach ($item in $InputObject) {
+            $items += ,(ConvertTo-NativeObject $item)
+        }
+        return $items
+    }
+
+    if ($InputObject -is [pscustomobject]) {
+        $result = [ordered]@{}
+        foreach ($property in $InputObject.PSObject.Properties) {
+            $result[$property.Name] = ConvertTo-NativeObject $property.Value
+        }
+        return $result
+    }
+
+    return $InputObject
+}
+
+function Update-CopilotCliMcpConfig {
+    param(
+        [string]$Path,
+        [string]$ServerName,
+        [hashtable]$ServerConfig
+    )
+
+    $config = [ordered]@{}
+
+    if (Test-Path -LiteralPath $Path) {
+        $rawContent = Get-Content -LiteralPath $Path -Raw
+        if (-not [string]::IsNullOrWhiteSpace($rawContent)) {
+            $jsonObject = $null
+            try {
+                $jsonObject = ConvertFrom-Json -InputObject $rawContent -ErrorAction Stop
+            }
+            catch {
+                throw "Failed to parse Copilot CLI MCP config at '$Path'. Ensure it contains valid JSON. $($_.Exception.Message)"
+            }
+
+            $config = ConvertTo-NativeObject $jsonObject
+        }
+    }
+
+    if (-not $config.Contains('mcpServers') -or $null -eq $config['mcpServers']) {
+        $config['mcpServers'] = [ordered]@{}
+    }
+
+    $config['mcpServers'][$ServerName] = $ServerConfig
+    $json = $config | ConvertTo-Json -Depth 100
+    Set-Content -LiteralPath $Path -Value $json -Encoding UTF8
+}
+
+Ensure-Directory (Split-Path -Parent $CliMcpPath)
+
+$atlassianServerConfig = [ordered]@{
+    type = "http"
+    url = "https://mcp.atlassian.com/v1/mcp"
+    tools = @("*")
+}
+
+Write-Host ""
+Write-Host "Registering Atlassian MCP for Copilot CLI in: $CliMcpPath" -ForegroundColor Cyan
+Update-CopilotCliMcpConfig -Path $CliMcpPath -ServerName "atlassian" -ServerConfig $atlassianServerConfig
+
+Write-Host ""
+Write-Host "Done." -ForegroundColor Green
+Write-Host "Copilot CLI MCP config: $CliMcpPath"
+Write-Host "Configured MCP server: atlassian"
+Write-Host "Configured MCP URL: https://mcp.atlassian.com/v1/mcp"
+Write-Host ""
+Write-Host "Next steps:" -ForegroundColor Yellow
+Write-Host "1. Start Copilot CLI in your project."
+Write-Host "2. Run /mcp show to confirm the atlassian server is available."
+Write-Host "3. Invoke one of the installed custom agents, for example: copilot --agent=ticket-planner --prompt 'Plan Jira ticket ENG-123'"
+Write-Host "4. Expect planning artifacts under .workitems/<ticket>/, including ticket.md. Implementation keeps tasks.json as the ledger and progress.json as the snapshot. Only ImplementationPlanner and PRReviewer refresh ticket.md."
+Write-Host "5. .workitems/<ticket>/problems.md is a temporary active blocker file. If it exists, the implementer will stop before changing code. Resolve the blocker and delete the file to continue."
diff --git a/setup/Install-CopilotJiraAgents.ps1 b/setup/Install-CopilotJiraAgents.ps1
new file mode 100644
index 0000000..d542c5c
--- /dev/null
+++ b/setup/Install-CopilotJiraAgents.ps1
@@ -0,0 +1,133 @@
+[CmdletBinding()]
+param(
+    [string]$UserMcpPath = (Join-Path $env:APPDATA "Code\User\mcp.json"),
+    [switch]$InstallWorkspaceConfig,
+    [string]$WorkspaceRoot = (Get-Location).Path
+)
+
+Set-StrictMode -Version Latest
+$ErrorActionPreference = "Stop"
+
+function Ensure-Directory {
+    param([string]$Path)
+    if (-not (Test-Path -LiteralPath $Path)) {
+        New-Item -ItemType Directory -Force -Path $Path | Out-Null
+    }
+}
+
+function ConvertTo-NativeObject {
+    param([Parameter(ValueFromPipeline = $true)]$InputObject)
+
+    if ($null -eq $InputObject) {
+        return $null
+    }
+
+    if ($InputObject -is [System.Collections.IDictionary]) {
+        $result = [ordered]@{}
+        foreach ($key in $InputObject.Keys) {
+            $result[$key] = ConvertTo-NativeObject $InputObject[$key]
+        }
+        return $result
+    }
+
+    if ($InputObject -is [System.Collections.IEnumerable] -and -not ($InputObject -is [string])) {
+        $items = @()
+        foreach ($item in $InputObject) {
+            $items += ,(ConvertTo-NativeObject $item)
+        }
+        return $items
+    }
+
+    if ($InputObject -is [pscustomobject]) {
+        $result = [ordered]@{}
+        foreach ($property in $InputObject.PSObject.Properties) {
+            $result[$property.Name] = ConvertTo-NativeObject $property.Value
+        }
+        return $result
+    }
+
+    return $InputObject
+}
+
+function Update-McpServerConfig {
+    param(
+        [string]$Path,
+        [string]$ServerName,
+        [hashtable]$ServerConfig
+    )
+
+    $config = [ordered]@{}
+
+    if (Test-Path -LiteralPath $Path) {
+        $rawContent = Get-Content -LiteralPath $Path -Raw
+        if (-not [string]::IsNullOrWhiteSpace($rawContent)) {
+            $jsonObject = $null
+            try {
+                $jsonObject = ConvertFrom-Json -InputObject $rawContent -ErrorAction Stop
+            }
+            catch {
+                throw "Failed to parse MCP config at '$Path'. Ensure it contains valid JSON. $($_.Exception.Message)"
+            }
+
+            $config = ConvertTo-NativeObject $jsonObject
+        }
+    }
+
+    if (-not $config.Contains('servers') -or $null -eq $config['servers']) {
+        $config['servers'] = [ordered]@{}
+    }
+
+    $config['servers'][$ServerName] = $ServerConfig
+    $json = $config | ConvertTo-Json -Depth 100
+    Set-Content -LiteralPath $Path -Value $json -Encoding UTF8
+}
+
+$scriptRoot = Split-Path -Parent $MyInvocation.MyCommand.Path
+$repoRoot = Split-Path -Parent $scriptRoot
+
+$copilotRoot = Join-Path $HOME ".copilot"
+$agentTarget = Join-Path $copilotRoot "agents"
+$workspaceMcpPath = Join-Path $WorkspaceRoot ".vscode\mcp.json"
+
+Ensure-Directory $copilotRoot
+Ensure-Directory $agentTarget
+Ensure-Directory (Split-Path -Parent $UserMcpPath)
+
+Write-Host ""
+Write-Host "Installing agents into: $agentTarget" -ForegroundColor Cyan
+Copy-Item -Path (Join-Path $repoRoot ".github\agents\*.agent.md") -Destination $agentTarget -Force
+
+$atlassianServerConfig = [ordered]@{
+    type = "http"
+    url = "https://mcp.atlassian.com/v1/mcp"
+}
+
+Write-Host "Registering atlassian in user MCP config: $UserMcpPath" -ForegroundColor Cyan
+Update-McpServerConfig -Path $UserMcpPath -ServerName "atlassian" -ServerConfig $atlassianServerConfig
+
+if ($InstallWorkspaceConfig) {
+    $workspaceVscodeDir = Split-Path -Parent $workspaceMcpPath
+    Ensure-Directory $workspaceVscodeDir
+
+    Write-Host "Writing optional workspace MCP config into: $workspaceMcpPath" -ForegroundColor Cyan
+    Update-McpServerConfig -Path $workspaceMcpPath -ServerName "atlassian" -ServerConfig $atlassianServerConfig
+}
+
+Write-Host ""
+Write-Host "Done." -ForegroundColor Green
+Write-Host "Agents path: $agentTarget"
+Write-Host "User MCP config: $UserMcpPath"
+if ($InstallWorkspaceConfig) {
+    Write-Host "Workspace MCP config: $workspaceMcpPath"
+}
+Write-Host "Configured MCP server: atlassian"
+Write-Host "Configured MCP URL: https://mcp.atlassian.com/v1/mcp"
+Write-Host ""
+Write-Host "Next steps:" -ForegroundColor Yellow
+Write-Host "1. Reload VS Code."
+Write-Host "2. Run: MCP: List Servers"
+Write-Host "3. Start or trust atlassian."
+Write-Host "4. Complete the Atlassian authentication flow if prompted."
+Write-Host "5. Run: MCP: Reset Cached Tools if tools do not appear."
+Write-Host "6. Expect planning artifacts under .workitems/<ticket>/, including ticket.md. Implementation keeps tasks.json as the ledger and progress.json as the snapshot. Only ImplementationPlanner and PRReviewer refresh ticket.md."
+Write-Host "7. .workitems/<ticket>/problems.md is a temporary active blocker file. If it exists, the implementer will stop before changing code. Resolve the blocker and delete the file to continue."
diff --git a/tools/measure-agent-prompts.ps1 b/tools/measure-agent-prompts.ps1
new file mode 100644
index 0000000..940dc29
--- /dev/null
+++ b/tools/measure-agent-prompts.ps1
@@ -0,0 +1,94 @@
+param(
+    [string]$AgentsPath = ".github/agents",
+    [string]$PromptsPath = ".github/prompts",
+    [switch]$IncludePrompts,
+    [switch]$Json
+)
+
+$ErrorActionPreference = "Stop"
+
+function Get-PromptRows {
+    param(
+        [string]$Path,
+        [string]$Filter
+    )
+
+    if (-not (Test-Path $Path)) {
+        throw "Path not found: $Path"
+    }
+
+    $files = Get-ChildItem -Path $Path -File -Filter $Filter | Sort-Object Name
+
+    if (-not $files) {
+        throw "No files found under $Path matching $Filter"
+    }
+
+    foreach ($file in $files) {
+        $content = Get-Content -Raw $file.FullName
+        $words = ($content -split "\s+" | Where-Object { $_ -ne "" }).Count
+
+        [pscustomobject]@{
+            Name = $file.Name
+            Chars = $content.Length
+            Words = $words
+            ApproxTokens = [math]::Round($content.Length / 4.0)
+            Lines = (Get-Content $file.FullName).Count
+        }
+    }
+}
+
+function Get-SectionSummary {
+    param(
+        [string]$Name,
+        [Object[]]$Rows
+    )
+
+    [pscustomobject]@{
+        Name = $Name
+        FileCount = $Rows.Count
+        TotalChars = ($Rows | Measure-Object -Property Chars -Sum).Sum
+        TotalWords = ($Rows | Measure-Object -Property Words -Sum).Sum
+        TotalApproxTokens = ($Rows | Measure-Object -Property ApproxTokens -Sum).Sum
+        Files = $Rows
+    }
+}
+
+$sections = @()
+
+$agentRows = @(Get-PromptRows -Path $AgentsPath -Filter "*.agent.md")
+$sections += Get-SectionSummary -Name "Agents" -Rows $agentRows
+
+if ($IncludePrompts) {
+    $promptRows = @(Get-PromptRows -Path $PromptsPath -Filter "*.prompt.md")
+    $sections += Get-SectionSummary -Name "Prompts" -Rows $promptRows
+}
+
+$allRows = @($sections | ForEach-Object { $_.Files })
+
+$summary = [pscustomobject]@{
+    FileCount = $allRows.Count
+    TotalChars = ($allRows | Measure-Object -Property Chars -Sum).Sum
+    TotalWords = ($allRows | Measure-Object -Property Words -Sum).Sum
+    TotalApproxTokens = ($allRows | Measure-Object -Property ApproxTokens -Sum).Sum
+    Sections = $sections
+}
+
+if ($Json) {
+    $summary | ConvertTo-Json -Depth 4
+    exit 0
+}
+
+$sections | ForEach-Object {
+    $_.Files | Format-Table Name, Chars, Words, ApproxTokens, Lines -AutoSize
+    ""
+    "{0} files: {1}" -f $_.Name, $_.FileCount
+    "{0} chars: {1}" -f $_.Name, $_.TotalChars
+    "{0} words: {1}" -f $_.Name, $_.TotalWords
+    "{0} approx tokens: {1}" -f $_.Name, $_.TotalApproxTokens
+    ""
+}
+
+"Total files: {0}" -f $summary.FileCount
+"Total chars: {0}" -f $summary.TotalChars
+"Total words: {0}" -f $summary.TotalWords
+"Total approx tokens: {0}" -f $summary.TotalApproxTokens