Remove external web automation provenance refs

Superpowers is cloned from git, so skills live under
.cursor/skills/superpowers/skills/<name>/SKILL.md, not
.cursor/skills/superpowers/<name>/SKILL.md.

.gitignore

@@ -0,0 +1,7 @@
+/ai_plan/
+/.worktrees/
+/skills/atlassian/shared/scripts/.env
+/skills/atlassian/shared/scripts/node_modules/
+/skills/atlassian/*/scripts/.env
+/skills/atlassian/*/scripts/node_modules/
+/skills/web-automation/*/scripts/node_modules/

README.md

@@ -1,6 +1,6 @@
 # ai-coding-skills
 
-Cross-agent skill collection for **Codex**, **Claude Code**, and **OpenCode**.
+Cross-agent skill collection for **Codex**, **Claude Code**, **OpenCode**, and **Cursor**.
 
 This repo is organized similarly to `obra/superpowers` and is designed to scale to many skills over time.
 
@@ -15,14 +15,30 @@ This repo is organized similarly to `obra/superpowers` and is designed to scale
 ai-coding-skills/
 ├── README.md
 ├── docs/
-│   └── install.md
+│   ├── README.md
+│   ├── ATLASSIAN.md
+│   ├── CREATE-PLAN.md
+│   ├── IMPLEMENT-PLAN.md
+│   └── WEB-AUTOMATION.md
 ├── skills/
 │   ├── _template/
 │   │   └── SKILL.md
+│   ├── atlassian/
+│   │   ├── codex/
+│   │   ├── claude-code/
+│   │   ├── cursor/
+│   │   ├── opencode/
+│   │   └── shared/
 │   ├── create-plan/
 │   │   ├── codex/
 │   │   ├── claude-code/
-│   │   └── opencode/
+│   │   ├── opencode/
+│   │   └── cursor/
+│   ├── implement-plan/
+│   │   ├── codex/
+│   │   ├── claude-code/
+│   │   ├── opencode/
+│   │   └── cursor/
 │   └── web-automation/
 │       ├── codex/
 │       ├── claude-code/
@@ -38,16 +54,29 @@ ai-coding-skills/
 
 ## Skills
 
-| Skill | Agent Variant | Purpose | Status |
-|---|---|---|---|
-| create-plan | codex | Structured planning with milestones + runbook-first execution workflow | Ready |
-| create-plan | claude-code | Structured planning with milestones + runbook-first execution workflow | Ready |
-| create-plan | opencode | Structured planning with milestones + runbook-first execution workflow | Ready |
-| web-automation | codex | Playwright + Camoufox browsing/scraping/auth automation | Ready |
-| web-automation | claude-code | Playwright + Camoufox browsing/scraping/auth automation | Ready |
-| web-automation | opencode | Playwright + Camoufox browsing/scraping/auth automation | Ready |
+| Skill | Agent Variant | Purpose | Status | Docs |
+|---|---|---|---|---|
+| atlassian | codex | Portable Jira and Confluence workflows through a shared Cloud-first CLI | Ready | [ATLASSIAN](docs/ATLASSIAN.md) |
+| atlassian | claude-code | Portable Jira and Confluence workflows through a shared Cloud-first CLI | Ready | [ATLASSIAN](docs/ATLASSIAN.md) |
+| atlassian | opencode | Portable Jira and Confluence workflows through a shared Cloud-first CLI | Ready | [ATLASSIAN](docs/ATLASSIAN.md) |
+| atlassian | cursor | Portable Jira and Confluence workflows through a shared Cloud-first CLI | Ready | [ATLASSIAN](docs/ATLASSIAN.md) |
+| create-plan | codex | Structured planning with milestones, iterative cross-model review, and runbook-first execution workflow | Ready | [CREATE-PLAN](docs/CREATE-PLAN.md) |
+| create-plan | claude-code | Structured planning with milestones, iterative cross-model review, and runbook-first execution workflow | Ready | [CREATE-PLAN](docs/CREATE-PLAN.md) |
+| create-plan | opencode | Structured planning with milestones, iterative cross-model review, and runbook-first execution workflow | Ready | [CREATE-PLAN](docs/CREATE-PLAN.md) |
+| create-plan | cursor | Structured planning with milestones, iterative cross-model review, and runbook-first execution workflow | Ready | [CREATE-PLAN](docs/CREATE-PLAN.md) |
+| implement-plan | codex | Worktree-isolated plan execution with iterative cross-model milestone review | Ready | [IMPLEMENT-PLAN](docs/IMPLEMENT-PLAN.md) |
+| implement-plan | claude-code | Worktree-isolated plan execution with iterative cross-model milestone review | Ready | [IMPLEMENT-PLAN](docs/IMPLEMENT-PLAN.md) |
+| implement-plan | opencode | Worktree-isolated plan execution with iterative cross-model milestone review | Ready | [IMPLEMENT-PLAN](docs/IMPLEMENT-PLAN.md) |
+| implement-plan | cursor | Worktree-isolated plan execution with iterative cross-model milestone review | Ready | [IMPLEMENT-PLAN](docs/IMPLEMENT-PLAN.md) |
+| web-automation | codex | CloakBrowser-backed browsing, scraping, auth, flow automation, and install validation | Ready | [WEB-AUTOMATION](docs/WEB-AUTOMATION.md) |
+| web-automation | claude-code | CloakBrowser-backed browsing, scraping, auth, flow automation, and install validation | Ready | [WEB-AUTOMATION](docs/WEB-AUTOMATION.md) |
+| web-automation | opencode | CloakBrowser-backed browsing, scraping, auth, flow automation, and install validation | Ready | [WEB-AUTOMATION](docs/WEB-AUTOMATION.md) |
 
-See install instructions: `docs/install.md`
+- Docs index: `docs/README.md`
+- Atlassian guide: `docs/ATLASSIAN.md`
+- Create-plan guide: `docs/CREATE-PLAN.md`
+- Implement-plan guide: `docs/IMPLEMENT-PLAN.md`
+- Web-automation guide: `docs/WEB-AUTOMATION.md`
 
 ## Compatibility Policy
 

docs/ATLASSIAN.md

@@ -0,0 +1,156 @@
+# ATLASSIAN
+
+## Purpose
+
+Provide a portable Atlassian Cloud skill for Codex, Claude Code, Cursor Agent, and OpenCode using one shared CLI surface for common Jira and Confluence workflows.
+
+## Why This Skill Exists
+
+The repo targets multiple agent environments with uneven MCP availability. This skill packages a consistent CLI contract so the same task-oriented workflows can be used across all supported agents without depending on MCP-specific integrations.
+
+The canonical runtime lives in `skills/atlassian/shared/scripts/`. Installable per-agent `scripts/` bundles are generated from that source with:
+
+```bash
+pnpm --dir skills/atlassian/shared/scripts sync:agents
+```
+
+## Requirements
+
+- Node.js 20+
+- `pnpm`
+- Atlassian Cloud access
+- `ATLASSIAN_BASE_URL`
+- `ATLASSIAN_EMAIL`
+- `ATLASSIAN_API_TOKEN`
+
+The `ATLASSIAN_*` values may come from the shell environment or a `.env` file in the installed agent-specific `scripts/` folder.
+
+Optional:
+
+- `ATLASSIAN_JIRA_BASE_URL`
+- `ATLASSIAN_CONFLUENCE_BASE_URL`
+- `ATLASSIAN_DEFAULT_PROJECT`
+- `ATLASSIAN_DEFAULT_SPACE`
+
+## Supported Commands
+
+- `health`
+- `jira-search`
+- `jira-get`
+- `jira-create`
+- `jira-update`
+- `jira-comment`
+- `jira-transitions`
+- `jira-transition`
+- `conf-search`
+- `conf-get`
+- `conf-create`
+- `conf-update`
+- `conf-comment`
+- `conf-children`
+- `raw`
+
+## Command Notes
+
+- `health` validates local configuration, probes Jira and Confluence separately, and reports one product as unavailable without masking the other.
+- `jira-create` requires `--type`, `--summary`, and either `--project` or `ATLASSIAN_DEFAULT_PROJECT`.
+- `jira-update` requires `--issue` and at least one of `--summary` or `--description-file`.
+- `conf-create` requires `--title`, `--body-file`, and either `--space` or `ATLASSIAN_DEFAULT_SPACE`.
+- `conf-update` requires `--page`, `--title`, and `--body-file`; it fetches the current page version before building the update payload.
+- `raw --body-file` expects a workspace-scoped JSON file and is limited to validated Atlassian API prefixes.
+
+## Safety Model
+
+- Default output is JSON.
+- Mutating commands support `--dry-run`.
+- Jira long-text fields are converted to ADF locally.
+- Confluence page writes are storage-first in v1.
+- `raw` is restricted to `GET|POST|PUT`.
+- `--body-file` must stay within the active workspace.
+
+## Install
+
+### Codex
+
+```bash
+mkdir -p ~/.codex/skills/atlassian
+cp -R skills/atlassian/codex/* ~/.codex/skills/atlassian/
+cd ~/.codex/skills/atlassian/scripts
+pnpm install
+```
+
+### Claude Code
+
+```bash
+mkdir -p ~/.claude/skills/atlassian
+cp -R skills/atlassian/claude-code/* ~/.claude/skills/atlassian/
+cd ~/.claude/skills/atlassian/scripts
+pnpm install
+```
+
+### OpenCode
+
+```bash
+mkdir -p ~/.config/opencode/skills/atlassian
+cp -R skills/atlassian/opencode/* ~/.config/opencode/skills/atlassian/
+cd ~/.config/opencode/skills/atlassian/scripts
+pnpm install
+```
+
+### Cursor
+
+Repo-local install:
+
+```bash
+mkdir -p .cursor/skills/atlassian
+cp -R skills/atlassian/cursor/* .cursor/skills/atlassian/
+cd .cursor/skills/atlassian/scripts
+pnpm install
+```
+
+Global install:
+
+```bash
+mkdir -p ~/.cursor/skills/atlassian
+cp -R skills/atlassian/cursor/* ~/.cursor/skills/atlassian/
+cd ~/.cursor/skills/atlassian/scripts
+pnpm install
+```
+
+## Verify Installation
+
+Run in the installed `scripts/` folder:
+
+```bash
+node -e "require.resolve('commander');require.resolve('dotenv');console.log('OK: runtime dependencies installed')"
+node -e 'require("dotenv").config({ path: ".env" }); const required = ["ATLASSIAN_BASE_URL", "ATLASSIAN_EMAIL", "ATLASSIAN_API_TOKEN"]; const missing = required.filter((key) => !(process.env[key] || "").trim()); if (missing.length) { console.error("Missing required Atlassian config: " + missing.join(", ")); process.exit(1); } console.log("OK: Atlassian config present")'
+pnpm atlassian health
+```
+
+## Usage Examples
+
+- Search Jira issues:
+  - `pnpm atlassian jira-search --jql "project = ENG ORDER BY updated DESC" --max-results 25`
+- Inspect an issue:
+  - `pnpm atlassian jira-get --issue ENG-123`
+- Dry-run a Jira comment:
+  - `pnpm atlassian jira-comment --issue ENG-123 --body-file comment.md --dry-run`
+- Dry-run a Jira issue create with default project fallback:
+  - `pnpm atlassian jira-create --type Story --summary "Add Atlassian skill" --description-file story.md --dry-run`
+- Search Confluence pages:
+  - `pnpm atlassian conf-search --query "title ~ \\\"Runbook\\\"" --max-results 10 --start-at 0`
+- Inspect a Confluence page:
+  - `pnpm atlassian conf-get --page 12345`
+- Dry-run a Confluence page update:
+  - `pnpm atlassian conf-update --page 12345 --title "Runbook" --body-file page.storage.html --dry-run`
+- Dry-run a Confluence footer comment:
+  - `pnpm atlassian conf-comment --page 12345 --body-file comment.storage.html --dry-run`
+- Use bounded raw mode:
+  - `pnpm atlassian raw --product jira --method GET --path "/rest/api/3/issue/ENG-123"`
+  - `pnpm atlassian raw --product confluence --method POST --path "/wiki/api/v2/pages" --body-file page.json --dry-run`
+
+## Scope Notes
+
+- Atlassian Cloud is first-class in v1.
+- Data Center support is future work.
+- Full `mcp-atlassian` parity is not the goal in v1; the initial scope is the approved core workflow set above.

docs/CREATE-PLAN.md

@@ -0,0 +1,270 @@
+# CREATE-PLAN
+
+## Purpose
+
+Create structured implementation plans with milestone and story tracking, and optionally review them iteratively with a second model/provider before finalizing.
+
+## Requirements
+
+- Superpowers skills installed from: https://github.com/obra/superpowers
+- Required dependencies:
+  - `superpowers:brainstorming`
+  - `superpowers:writing-plans`
+- For Codex, native skill discovery must be configured:
+  - `~/.agents/skills/superpowers -> ~/.codex/superpowers/skills`
+- For Cursor, skills must be installed under `.cursor/skills/` (repo-local) or `~/.cursor/skills/` (global)
+- Shared reviewer runtime must be installed beside agent skills when using reviewer CLIs:
+  - Codex: `~/.codex/skills/reviewer-runtime/run-review.sh`
+  - Claude Code: `~/.claude/skills/reviewer-runtime/run-review.sh`
+  - OpenCode: `~/.config/opencode/skills/reviewer-runtime/run-review.sh`
+  - Cursor: `.cursor/skills/reviewer-runtime/run-review.sh` or `~/.cursor/skills/reviewer-runtime/run-review.sh`
+- Telegram notification setup is documented in [TELEGRAM-NOTIFICATIONS.md](./TELEGRAM-NOTIFICATIONS.md)
+
+If dependencies are missing, stop and return:
+
+"Missing dependency: native Superpowers skills are required (`superpowers:brainstorming`, `superpowers:writing-plans`). Install from https://github.com/obra/superpowers, then retry."
+
+### Reviewer CLI Requirements (Optional)
+
+To use the iterative plan review feature, one of these CLIs must be installed:
+
+| Reviewer CLI | Install | Verify |
+|---|---|---|
+| `codex` | `npm install -g @openai/codex` | `codex --version` |
+| `claude` | `npm install -g @anthropic-ai/claude-code` | `claude --version` |
+| `cursor` | `curl https://cursor.com/install -fsS \| bash` | `cursor-agent --version` (binary: `cursor-agent`; alias `cursor agent` also works) |
+
+The reviewer CLI is independent of which agent is running the planning — e.g., Claude Code can send plans to Codex for review, and vice versa.
+
+**Additional dependency for `cursor` reviewer:** `jq` is required to parse Cursor's JSON output. Install via `brew install jq` (macOS) or your package manager. Verify: `jq --version`.
+
+## Install
+
+### Codex
+
+```bash
+mkdir -p ~/.codex/skills/create-plan
+cp -R skills/create-plan/codex/* ~/.codex/skills/create-plan/
+mkdir -p ~/.codex/skills/reviewer-runtime
+cp -R skills/reviewer-runtime/* ~/.codex/skills/reviewer-runtime/
+```
+
+### Claude Code
+
+```bash
+mkdir -p ~/.claude/skills/create-plan
+cp -R skills/create-plan/claude-code/* ~/.claude/skills/create-plan/
+mkdir -p ~/.claude/skills/reviewer-runtime
+cp -R skills/reviewer-runtime/* ~/.claude/skills/reviewer-runtime/
+```
+
+### OpenCode
+
+```bash
+mkdir -p ~/.config/opencode/skills/create-plan
+cp -R skills/create-plan/opencode/* ~/.config/opencode/skills/create-plan/
+mkdir -p ~/.config/opencode/skills/reviewer-runtime
+cp -R skills/reviewer-runtime/* ~/.config/opencode/skills/reviewer-runtime/
+```
+
+### Cursor
+
+Copy into the repo-local `.cursor/skills/` directory (where the Cursor Agent CLI discovers skills):
+
+```bash
+mkdir -p .cursor/skills/create-plan
+cp -R skills/create-plan/cursor/* .cursor/skills/create-plan/
+mkdir -p .cursor/skills/reviewer-runtime
+cp -R skills/reviewer-runtime/* .cursor/skills/reviewer-runtime/
+```
+
+Or install globally (loaded via `~/.cursor/skills/`):
+
+```bash
+mkdir -p ~/.cursor/skills/create-plan
+cp -R skills/create-plan/cursor/* ~/.cursor/skills/create-plan/
+mkdir -p ~/.cursor/skills/reviewer-runtime
+cp -R skills/reviewer-runtime/* ~/.cursor/skills/reviewer-runtime/
+```
+
+## Verify Installation
+
+```bash
+test -f ~/.codex/skills/create-plan/SKILL.md || true
+test -f ~/.claude/skills/create-plan/SKILL.md || true
+test -f ~/.config/opencode/skills/create-plan/SKILL.md || true
+test -f .cursor/skills/create-plan/SKILL.md || test -f ~/.cursor/skills/create-plan/SKILL.md || true
+test -x ~/.codex/skills/reviewer-runtime/run-review.sh || true
+test -x ~/.claude/skills/reviewer-runtime/run-review.sh || true
+test -x ~/.config/opencode/skills/reviewer-runtime/run-review.sh || true
+test -x .cursor/skills/reviewer-runtime/run-review.sh || test -x ~/.cursor/skills/reviewer-runtime/run-review.sh || true
+```
+
+Verify Superpowers dependencies exist in your agent skills root:
+
+- Codex: `~/.agents/skills/superpowers/brainstorming/SKILL.md`
+- Codex: `~/.agents/skills/superpowers/writing-plans/SKILL.md`
+- Claude Code: `~/.claude/skills/superpowers/brainstorming/SKILL.md`
+- Claude Code: `~/.claude/skills/superpowers/writing-plans/SKILL.md`
+- OpenCode: `~/.config/opencode/skills/superpowers/brainstorming/SKILL.md`
+- OpenCode: `~/.config/opencode/skills/superpowers/writing-plans/SKILL.md`
+- Cursor: `.cursor/skills/superpowers/skills/brainstorming/SKILL.md` or `~/.cursor/skills/superpowers/skills/brainstorming/SKILL.md`
+- Cursor: `.cursor/skills/superpowers/skills/writing-plans/SKILL.md` or `~/.cursor/skills/superpowers/skills/writing-plans/SKILL.md`
+
+## Key Behavior
+
+- Creates plans under `ai_plan/YYYY-MM-DD-<short-title>/`.
+- Ensures `/ai_plan/` is in `.gitignore`.
+- Commits `.gitignore` update locally when added.
+- Asks which reviewer CLI, model, and max rounds to use (or accepts `skip` for no review).
+- Iteratively reviews the plan with the chosen reviewer (default max 10 rounds) before generating files.
+- Runs reviewer commands through `reviewer-runtime/run-review.sh` when available, with fallback to direct synchronous execution only if the helper is missing.
+- Waits as long as the reviewer runtime keeps emitting per-minute `In progress N` heartbeats.
+- Requires reviewer findings to be ordered `P0` through `P3`, with `P3` explicitly non-blocking.
+- Captures reviewer stderr and helper status logs for diagnostics and retains them on failed, empty-output, or operator-decision review rounds.
+- Sends completion notifications through Telegram only when the shared setup in [TELEGRAM-NOTIFICATIONS.md](./TELEGRAM-NOTIFICATIONS.md) is installed and configured.
+- Produces:
+  - `original-plan.md`
+  - `final-transcript.md`
+  - `milestone-plan.md` — includes Planning Guardrails section
+  - `story-tracker.md` — includes Tracking Guardrails section
+  - `continuation-runbook.md` — includes Skill Workflow Guardrails section
+
+## Iterative Plan Review
+
+After the plan is created (design + milestones + stories), the skill sends it to a second model for review:
+
+1. **Configure** — user picks a reviewer CLI (`codex`, `claude`, `cursor`), a model, and optional max rounds (default 10), or skips
+2. **Prepare** — plan payload and a bash reviewer command script are written to temp files
+3. **Run** — the command script is executed through `reviewer-runtime/run-review.sh` when installed
+4. **Feedback** — reviewer evaluates correctness, risks, missing steps, alternatives, security, and returns `## Summary`, `## Findings`, and `## Verdict`
+5. **Prioritize** — findings are ordered `P0`, `P1`, `P2`, `P3`
+6. **Revise** — the planning agent addresses findings in priority order and re-submits
+7. **Repeat** — up to max rounds until the reviewer returns `VERDICT: APPROVED`
+8. **Finalize** — approved plan is used to generate the plan file package
+
+### Reviewer Output Contract
+
+- `P0` = total blocker
+- `P1` = major risk
+- `P2` = must-fix before approval
+- `P3` = cosmetic / nice to have
+- Each severity section should use `- None.` when empty
+- `VERDICT: APPROVED` is valid only when no `P0`, `P1`, or `P2` findings remain
+- `P3` findings are non-blocking, but the caller should still try to fix them when cheap and safe
+
+### Runtime Artifacts
+
+The review flow may create these temp artifacts:
+
+- `/tmp/plan-<id>.md` — plan payload
+- `/tmp/plan-review-<id>.md` — normalized review text
+- `/tmp/plan-review-<id>.json` — raw Cursor JSON output
+- `/tmp/plan-review-<id>.stderr` — reviewer stderr
+- `/tmp/plan-review-<id>.status` — helper heartbeat/status log
+- `/tmp/plan-review-<id>.runner.out` — helper-managed stdout from the reviewer command process
+- `/tmp/plan-review-<id>.sh` — reviewer command script
+
+Status log lines use this format:
+
+```text
+ts=<ISO-8601> level=<info|warn|error> state=<running-silent|running-active|in-progress|stall-warning|completed|completed-empty-output|failed|needs-operator-decision> elapsed_s=<int> pid=<int> stdout_bytes=<int> stderr_bytes=<int> note="<short message>"
+```
+
+`in-progress` is the liveness heartbeat emitted roughly once per minute with `note="In progress N"`.
+`stall-warning` is a non-terminal status-log state only. It does not mean the caller should stop waiting if `in-progress` heartbeats continue.
+
+### Failure Handling
+
+- `completed-empty-output` means the reviewer exited without producing review text; surface `.stderr` and `.status`, then retry only after diagnosing the cause.
+- `needs-operator-decision` means the helper reached hard-timeout escalation; surface `.status` and decide whether to extend the timeout, abort, or retry with different parameters.
+- Successful rounds clean up temp artifacts. Failed, empty-output, and operator-decision rounds should retain `.stderr`, `.status`, and `.runner.out` until diagnosed.
+- As long as fresh `in-progress` heartbeats continue to arrive roughly once per minute, the caller should keep waiting.
+
+### Supported Reviewer CLIs
+
+| CLI | Command | Session Resume | Read-Only Mode |
+|---|---|---|---|
+| `codex` | `codex exec -m <model> -s read-only` | Yes (`codex exec resume <id>`) | `-s read-only` |
+| `claude` | `claude -p --model <model> --strict-mcp-config --setting-sources user` | No (fresh call each round) | `--strict-mcp-config --setting-sources user` |
+| `cursor` | `cursor-agent -p --mode=ask --model <model> --trust --output-format json` | Yes (`--resume <id>`) | `--mode=ask` |
+
+For all three CLIs, the preferred execution path is:
+
+1. write the reviewer command to a bash script
+2. run that script through `reviewer-runtime/run-review.sh`
+3. fall back to direct synchronous execution only if the helper is missing or not executable
+
+## Notifications
+
+- Telegram is the only supported notification path.
+- Shared setup: [TELEGRAM-NOTIFICATIONS.md](./TELEGRAM-NOTIFICATIONS.md)
+- Notification failures are non-blocking, but they must be surfaced to the user.
+- Before stopping for any user interaction, approval, or manual decision, send a Telegram summary first if configured.
+
+## Template Guardrails
+
+All plan templates now include guardrail sections that enforce:
+
+**Planning Guardrails** (`milestone-plan.md`):
+- Design validation before implementation planning
+- Native skill discovery (no deprecated CLI wrappers)
+- Milestone verification + local commits + explicit approval
+
+**Tracking Guardrails** (`story-tracker.md`):
+- Immediate status updates when work starts/completes
+- Explicit user approval at each milestone boundary
+- No pushes until all milestones approved
+- Synchronization between tracker and plan files
+
+**Skill Workflow Guardrails** (`continuation-runbook.md`):
+- Native skill invocation before action
+- Explicit skill announcements
+- Checklist tracking for driven skills
+- No deprecated CLI wrappers
+
+## Variant Hardening Notes
+
+### Claude Code
+
+- Must invoke explicit required sub-skills:
+  - `superpowers:brainstorming`
+  - `superpowers:writing-plans`
+- Must enforce plan-mode file-write guard:
+  - if in plan mode, instruct user to exit plan mode before generating files
+- Must copy `original-plan.md` from `~/.claude/plans/` when available.
+
+### Codex
+
+- Must use native skill discovery from `~/.agents/skills/` (no CLI wrappers).
+- Must verify Superpowers skills symlink: `~/.agents/skills/superpowers -> ~/.codex/superpowers/skills`
+- Must invoke required sub-skills with explicit announcements:
+  - `superpowers:brainstorming` — for design exploration and approach validation
+  - `superpowers:writing-plans` — for milestone and story breakdown
+- Must track checklist-driven skills with `update_plan` todos.
+- Deprecated CLI commands (`superpowers-codex bootstrap`, `use-skill`) must NOT be used.
+
+### OpenCode
+
+- Must use OpenCode native skill tool (not Claude/Codex invocation syntax).
+- Must verify Superpowers skill discovery under:
+  - `~/.config/opencode/skills/superpowers`
+- Must explicitly load:
+  - `superpowers/brainstorming`
+  - `superpowers/writing-plans`
+
+### Cursor
+
+- Must use workspace discovery from `.cursor/skills/` (repo-local or `~/.cursor/skills/` global).
+- Must announce skill usage explicitly before invocation.
+- Must use `--mode=ask` (read-only) and `--trust` when running reviewer non-interactively.
+- Must not use `--force` or `--mode=agent` for review (reviewer should never write files).
+
+## Execution Workflow Rules
+
+- Read runbook first.
+- Complete one milestone at a time.
+- Lint/typecheck/test (changed files first).
+- Commit (do not push), ask for feedback, apply feedback, commit again.
+- Move to next milestone only after approval.
+- Ask permission before final push.

docs/IMPLEMENT-PLAN.md

@@ -0,0 +1,275 @@
+# IMPLEMENT-PLAN
+
+## Purpose
+
+Execute an existing plan (created by `create-plan`) in an isolated git worktree, with iterative cross-model review at each milestone boundary. Milestones are implemented one-by-one with lint/typecheck/test gates, reviewed by a second model/provider, and committed locally until all are approved.
+
+## Requirements
+
+- Plan folder under `ai_plan/` (created by `create-plan`) with:
+  - `continuation-runbook.md`
+  - `milestone-plan.md`
+  - `story-tracker.md`
+- Git repo with worktree support
+- Superpowers execution skills installed from: https://github.com/obra/superpowers
+- Required dependencies:
+  - `superpowers:executing-plans`
+  - `superpowers:using-git-worktrees`
+  - `superpowers:verification-before-completion`
+  - `superpowers:finishing-a-development-branch`
+- For Codex, native skill discovery must be configured:
+  - `~/.agents/skills/superpowers -> ~/.codex/superpowers/skills`
+- For Cursor, skills must be installed under `.cursor/skills/` (repo-local) or `~/.cursor/skills/` (global)
+- Shared reviewer runtime must be installed beside agent skills when using reviewer CLIs:
+  - Codex: `~/.codex/skills/reviewer-runtime/run-review.sh`
+  - Claude Code: `~/.claude/skills/reviewer-runtime/run-review.sh`
+  - OpenCode: `~/.config/opencode/skills/reviewer-runtime/run-review.sh`
+  - Cursor: `.cursor/skills/reviewer-runtime/run-review.sh` or `~/.cursor/skills/reviewer-runtime/run-review.sh`
+- Telegram notification setup is documented in [TELEGRAM-NOTIFICATIONS.md](./TELEGRAM-NOTIFICATIONS.md)
+
+If dependencies are missing, stop and return:
+
+"Missing dependency: [specific missing item]. Ensure all prerequisites are met, then retry."
+
+### Reviewer CLI Requirements (Optional)
+
+To use the iterative milestone review feature, one of these CLIs must be installed:
+
+| Reviewer CLI | Install | Verify |
+|---|---|---|
+| `codex` | `npm install -g @openai/codex` | `codex --version` |
+| `claude` | `npm install -g @anthropic-ai/claude-code` | `claude --version` |
+| `cursor` | `curl https://cursor.com/install -fsS \| bash` | `cursor-agent --version` (binary: `cursor-agent`; alias `cursor agent` also works) |
+
+The reviewer CLI is independent of which agent is running the implementation — e.g., Claude Code can send milestones to Codex for review, and vice versa.
+
+**Additional dependency for `cursor` reviewer:** `jq` is required to parse Cursor's JSON output. Install via `brew install jq` (macOS) or your package manager. Verify: `jq --version`.
+
+## Install
+
+### Codex
+
+```bash
+mkdir -p ~/.codex/skills/implement-plan
+cp -R skills/implement-plan/codex/* ~/.codex/skills/implement-plan/
+mkdir -p ~/.codex/skills/reviewer-runtime
+cp -R skills/reviewer-runtime/* ~/.codex/skills/reviewer-runtime/
+```
+
+### Claude Code
+
+```bash
+mkdir -p ~/.claude/skills/implement-plan
+cp -R skills/implement-plan/claude-code/* ~/.claude/skills/implement-plan/
+mkdir -p ~/.claude/skills/reviewer-runtime
+cp -R skills/reviewer-runtime/* ~/.claude/skills/reviewer-runtime/
+```
+
+### OpenCode
+
+```bash
+mkdir -p ~/.config/opencode/skills/implement-plan
+cp -R skills/implement-plan/opencode/* ~/.config/opencode/skills/implement-plan/
+mkdir -p ~/.config/opencode/skills/reviewer-runtime
+cp -R skills/reviewer-runtime/* ~/.config/opencode/skills/reviewer-runtime/
+```
+
+### Cursor
+
+Copy into the repo-local `.cursor/skills/` directory (where the Cursor Agent CLI discovers skills):
+
+```bash
+mkdir -p .cursor/skills/implement-plan
+cp -R skills/implement-plan/cursor/* .cursor/skills/implement-plan/
+mkdir -p .cursor/skills/reviewer-runtime
+cp -R skills/reviewer-runtime/* .cursor/skills/reviewer-runtime/
+```
+
+Or install globally (loaded via `~/.cursor/skills/`):
+
+```bash
+mkdir -p ~/.cursor/skills/implement-plan
+cp -R skills/implement-plan/cursor/* ~/.cursor/skills/implement-plan/
+mkdir -p ~/.cursor/skills/reviewer-runtime
+cp -R skills/reviewer-runtime/* ~/.cursor/skills/reviewer-runtime/
+```
+
+## Verify Installation
+
+```bash
+test -f ~/.codex/skills/implement-plan/SKILL.md || true
+test -f ~/.claude/skills/implement-plan/SKILL.md || true
+test -f ~/.config/opencode/skills/implement-plan/SKILL.md || true
+test -f .cursor/skills/implement-plan/SKILL.md || test -f ~/.cursor/skills/implement-plan/SKILL.md || true
+test -x ~/.codex/skills/reviewer-runtime/run-review.sh || true
+test -x ~/.claude/skills/reviewer-runtime/run-review.sh || true
+test -x ~/.config/opencode/skills/reviewer-runtime/run-review.sh || true
+test -x .cursor/skills/reviewer-runtime/run-review.sh || test -x ~/.cursor/skills/reviewer-runtime/run-review.sh || true
+```
+
+Verify Superpowers execution dependencies exist in your agent skills root:
+
+- Codex: `~/.agents/skills/superpowers/executing-plans/SKILL.md`
+- Codex: `~/.agents/skills/superpowers/using-git-worktrees/SKILL.md`
+- Codex: `~/.agents/skills/superpowers/verification-before-completion/SKILL.md`
+- Codex: `~/.agents/skills/superpowers/finishing-a-development-branch/SKILL.md`
+- Claude Code: `~/.claude/skills/superpowers/executing-plans/SKILL.md`
+- Claude Code: `~/.claude/skills/superpowers/using-git-worktrees/SKILL.md`
+- Claude Code: `~/.claude/skills/superpowers/verification-before-completion/SKILL.md`
+- Claude Code: `~/.claude/skills/superpowers/finishing-a-development-branch/SKILL.md`
+- OpenCode: `~/.config/opencode/skills/superpowers/executing-plans/SKILL.md`
+- OpenCode: `~/.config/opencode/skills/superpowers/using-git-worktrees/SKILL.md`
+- OpenCode: `~/.config/opencode/skills/superpowers/verification-before-completion/SKILL.md`
+- OpenCode: `~/.config/opencode/skills/superpowers/finishing-a-development-branch/SKILL.md`
+- Cursor: `.cursor/skills/superpowers/skills/executing-plans/SKILL.md` or `~/.cursor/skills/superpowers/skills/executing-plans/SKILL.md`
+- Cursor: `.cursor/skills/superpowers/skills/using-git-worktrees/SKILL.md` or `~/.cursor/skills/superpowers/skills/using-git-worktrees/SKILL.md`
+- Cursor: `.cursor/skills/superpowers/skills/verification-before-completion/SKILL.md` or `~/.cursor/skills/superpowers/skills/verification-before-completion/SKILL.md`
+- Cursor: `.cursor/skills/superpowers/skills/finishing-a-development-branch/SKILL.md` or `~/.cursor/skills/superpowers/skills/finishing-a-development-branch/SKILL.md`
+
+## Key Behavior
+
+- Reads existing plan from `ai_plan/YYYY-MM-DD-<short-title>/`.
+- Sets up an isolated git worktree with branch `implement/<plan-folder-name>`.
+- Executes milestones one-by-one, tracking stories in `story-tracker.md`.
+- Runs lint/typecheck/tests as a gate before each milestone review.
+- Sends each milestone to a reviewer CLI for approval (max rounds configurable, default 10).
+- Runs reviewer commands through `reviewer-runtime/run-review.sh` when available, with fallback to direct synchronous execution only if the helper is missing.
+- Waits as long as the reviewer runtime keeps emitting per-minute `In progress N` heartbeats.
+- Requires reviewer findings to be ordered `P0` through `P3`, with `P3` explicitly non-blocking.
+- Captures reviewer stderr and helper status logs for diagnostics and retains them on failed, empty-output, or operator-decision review rounds.
+- Commits each milestone locally only after reviewer approval (does not push).
+- After all milestones approved, merges worktree branch to parent and deletes worktree.
+- Supports resume: detects existing worktree and `in-dev`/`completed` stories.
+- Sends completion notifications through Telegram only when the shared setup in [TELEGRAM-NOTIFICATIONS.md](./TELEGRAM-NOTIFICATIONS.md) is installed and configured.
+
+## Milestone Review Loop
+
+After each milestone is implemented and verified, the skill sends it to a second model for review:
+
+1. **Configure** — user picks a reviewer CLI (`codex`, `claude`, `cursor`) and model, or skips
+2. **Prepare** — milestone payload and a bash reviewer command script are written to temp files
+3. **Run** — the command script is executed through `reviewer-runtime/run-review.sh` when installed
+4. **Feedback** — reviewer evaluates correctness, acceptance criteria, code quality, test coverage, security, and returns `## Summary`, `## Findings`, and `## Verdict`
+5. **Prioritize** — findings are ordered `P0`, `P1`, `P2`, `P3`
+6. **Revise** — the implementing agent addresses findings in priority order, re-verifies, and re-submits
+7. **Repeat** — up to max rounds (default 10) until the reviewer returns `VERDICT: APPROVED`
+7. **Approve** — milestone is marked approved in `story-tracker.md`
+
+### Reviewer Output Contract
+
+- `P0` = total blocker
+- `P1` = major risk
+- `P2` = must-fix before approval
+- `P3` = cosmetic / nice to have
+- Each severity section should use `- None.` when empty
+- `VERDICT: APPROVED` is valid only when no `P0`, `P1`, or `P2` findings remain
+- `P3` findings are non-blocking, but the caller should still try to fix them when cheap and safe
+
+### Runtime Artifacts
+
+The milestone review flow may create these temp artifacts:
+
+- `/tmp/milestone-<id>.md` — milestone review payload
+- `/tmp/milestone-review-<id>.md` — normalized review text
+- `/tmp/milestone-review-<id>.json` — raw Cursor JSON output
+- `/tmp/milestone-review-<id>.stderr` — reviewer stderr
+- `/tmp/milestone-review-<id>.status` — helper heartbeat/status log
+- `/tmp/milestone-review-<id>.runner.out` — helper-managed stdout from the reviewer command process
+- `/tmp/milestone-review-<id>.sh` — reviewer command script
+
+Status log lines use this format:
+
+```text
+ts=<ISO-8601> level=<info|warn|error> state=<running-silent|running-active|in-progress|stall-warning|completed|completed-empty-output|failed|needs-operator-decision> elapsed_s=<int> pid=<int> stdout_bytes=<int> stderr_bytes=<int> note="<short message>"
+```
+
+`in-progress` is the liveness heartbeat emitted roughly once per minute with `note="In progress N"`.
+`stall-warning` is a non-terminal status-log state only. It does not mean the caller should stop waiting if `in-progress` heartbeats continue.
+
+### Failure Handling
+
+- `completed-empty-output` means the reviewer exited without producing review text; surface `.stderr` and `.status`, then retry only after diagnosing the cause.
+- `needs-operator-decision` means the helper reached hard-timeout escalation; surface `.status` and decide whether to extend the timeout, abort, or retry with different parameters.
+- Successful rounds clean up temp artifacts. Failed, empty-output, and operator-decision rounds should retain `.stderr`, `.status`, and `.runner.out` until diagnosed.
+- As long as fresh `in-progress` heartbeats continue to arrive roughly once per minute, the caller should keep waiting.
+
+### Supported Reviewer CLIs
+
+| CLI | Command | Session Resume | Read-Only Mode |
+|---|---|---|---|
+| `codex` | `codex exec -m <model> -s read-only` | Yes (`codex exec resume <id>`) | `-s read-only` |
+| `claude` | `claude -p --model <model> --strict-mcp-config --setting-sources user` | No (fresh call each round) | `--strict-mcp-config --setting-sources user` |
+| `cursor` | `cursor-agent -p --mode=ask --model <model> --trust --output-format json` | Yes (`--resume <id>`) | `--mode=ask` |
+
+For all three CLIs, the preferred execution path is:
+
+1. write the reviewer command to a bash script
+2. run that script through `reviewer-runtime/run-review.sh`
+3. fall back to direct synchronous execution only if the helper is missing or not executable
+
+## Notifications
+
+- Telegram is the only supported notification path.
+- Shared setup: [TELEGRAM-NOTIFICATIONS.md](./TELEGRAM-NOTIFICATIONS.md)
+- Notification failures are non-blocking, but they must be surfaced to the user.
+- Before stopping for any user interaction, approval, or manual decision, send a Telegram summary first if configured.
+
+The helper also supports manual override flags for diagnostics:
+
+```bash
+run-review.sh \
+  --command-file <path> \
+  --stdout-file <path> \
+  --stderr-file <path> \
+  --status-file <path> \
+  --poll-seconds 10 \
+  --soft-timeout-seconds 600 \
+  --stall-warning-seconds 300 \
+  --hard-timeout-seconds 1800
+```
+
+## Variant Hardening Notes
+
+### Claude Code
+
+- Must invoke explicit required sub-skills:
+  - `superpowers:executing-plans`
+  - `superpowers:using-git-worktrees`
+  - `superpowers:verification-before-completion`
+  - `superpowers:finishing-a-development-branch`
+
+### Codex
+
+- Must use native skill discovery from `~/.agents/skills/` (no CLI wrappers).
+- Must verify Superpowers skills symlink: `~/.agents/skills/superpowers -> ~/.codex/superpowers/skills`
+- Must invoke required sub-skills with explicit announcements.
+- Must track checklist-driven skills with `update_plan` todos.
+- Deprecated CLI commands (`superpowers-codex bootstrap`, `use-skill`) must NOT be used.
+
+### OpenCode
+
+- Must use OpenCode native skill tool (not Claude/Codex invocation syntax).
+- Must verify Superpowers skill discovery under:
+  - `~/.config/opencode/skills/superpowers`
+- Must explicitly load all four execution sub-skills.
+
+### Cursor
+
+- Must use workspace discovery from `.cursor/skills/` (repo-local or `~/.cursor/skills/` global).
+- Must announce skill usage explicitly before invocation.
+- Must use `--mode=ask` (read-only) and `--trust` when running reviewer non-interactively.
+- Must not use `--force` or `--mode=agent` for review (reviewer should never write files).
+
+## Execution Workflow Rules
+
+- Read `continuation-runbook.md` first (source of truth).
+- Set up worktree before any implementation work.
+- Complete one milestone at a time.
+- Update `story-tracker.md` before/after each story.
+- Lint/typecheck/test after each milestone (all must pass).
+- Send to reviewer for approval before committing.
+- Address review feedback, re-verify, re-submit (do not commit between rounds).
+- Commit locally (do not push) only after reviewer approves the milestone.
+- Move to next milestone only after approval and commit.
+- After all milestones: run full test suite, merge worktree branch to parent, delete worktree.
+- Max review rounds default to 10 if user does not specify a value.

docs/README.md

@@ -0,0 +1,20 @@
+# Skills Documentation
+
+This directory contains user-facing docs for each skill.
+
+## Index
+
+- [ATLASSIAN.md](./ATLASSIAN.md) — Includes requirements, generated bundle sync, install, auth, safety rules, and usage examples for the Atlassian skill.
+- [CREATE-PLAN.md](./CREATE-PLAN.md) — Includes requirements, install, verification, and execution workflow for create-plan.
+- [IMPLEMENT-PLAN.md](./IMPLEMENT-PLAN.md) — Includes requirements, install, verification, and milestone review workflow for implement-plan.
+- [TELEGRAM-NOTIFICATIONS.md](./TELEGRAM-NOTIFICATIONS.md) — Shared Telegram notification setup used by reviewer-driven skills.
+- [WEB-AUTOMATION.md](./WEB-AUTOMATION.md) — Includes requirements, install, dependency verification, and usage examples for web-automation.
+
+## Repo Setup
+
+Clone the repo first:
+
+```bash
+git clone https://git.fiorinis.com/Home/ai-coding-skills.git
+cd ai-coding-skills
+```

docs/TELEGRAM-NOTIFICATIONS.md

@@ -0,0 +1,97 @@
+# TELEGRAM-NOTIFICATIONS
+
+## Purpose
+
+Shared setup for Telegram notifications used by reviewer-driven skills such as `create-plan` and `implement-plan`, both for completion and for pauses that need user attention.
+
+## Requirements
+
+- Telegram bot token in `TELEGRAM_BOT_TOKEN`
+- Telegram chat id in `TELEGRAM_CHAT_ID`
+- Notification helper installed beside the shared reviewer runtime:
+  - Codex: `~/.codex/skills/reviewer-runtime/notify-telegram.sh`
+  - Claude Code: `~/.claude/skills/reviewer-runtime/notify-telegram.sh`
+  - OpenCode: `~/.config/opencode/skills/reviewer-runtime/notify-telegram.sh`
+  - Cursor: `.cursor/skills/reviewer-runtime/notify-telegram.sh` or `~/.cursor/skills/reviewer-runtime/notify-telegram.sh`
+
+## Install
+
+The helper ships from `skills/reviewer-runtime/` together with `run-review.sh`.
+
+### Codex
+
+```bash
+mkdir -p ~/.codex/skills/reviewer-runtime
+cp -R skills/reviewer-runtime/* ~/.codex/skills/reviewer-runtime/
+```
+
+### Claude Code
+
+```bash
+mkdir -p ~/.claude/skills/reviewer-runtime
+cp -R skills/reviewer-runtime/* ~/.claude/skills/reviewer-runtime/
+```
+
+### OpenCode
+
+```bash
+mkdir -p ~/.config/opencode/skills/reviewer-runtime
+cp -R skills/reviewer-runtime/* ~/.config/opencode/skills/reviewer-runtime/
+```
+
+### Cursor
+
+Repo-local install:
+
+```bash
+mkdir -p .cursor/skills/reviewer-runtime
+cp -R skills/reviewer-runtime/* .cursor/skills/reviewer-runtime/
+```
+
+Global install:
+
+```bash
+mkdir -p ~/.cursor/skills/reviewer-runtime
+cp -R skills/reviewer-runtime/* ~/.cursor/skills/reviewer-runtime/
+```
+
+## Verify Installation
+
+```bash
+test -x ~/.codex/skills/reviewer-runtime/notify-telegram.sh || true
+test -x ~/.claude/skills/reviewer-runtime/notify-telegram.sh || true
+test -x ~/.config/opencode/skills/reviewer-runtime/notify-telegram.sh || true
+test -x .cursor/skills/reviewer-runtime/notify-telegram.sh || test -x ~/.cursor/skills/reviewer-runtime/notify-telegram.sh || true
+```
+
+## Configure Telegram
+
+Export the required variables before running a skill that sends Telegram notifications:
+
+```bash
+export TELEGRAM_BOT_TOKEN="<bot-token>"
+export TELEGRAM_CHAT_ID="<chat-id>"
+```
+
+Optional:
+
+```bash
+export TELEGRAM_API_BASE_URL="https://api.telegram.org"
+```
+
+## Test the Helper
+
+Example:
+
+```bash
+TELEGRAM_BOT_TOKEN="<bot-token>" \
+TELEGRAM_CHAT_ID="<chat-id>" \
+skills/reviewer-runtime/notify-telegram.sh --message "Telegram notification test"
+```
+
+## Rules
+
+- Telegram is the only supported notification path for these skills.
+- Notification failures are non-blocking, but they must be surfaced to the user.
+- Before stopping for any user interaction, approval, or manual decision, send a Telegram summary first if configured.
+- Skills should report when Telegram is not configured instead of silently pretending a notification was sent.

docs/WEB-AUTOMATION.md

@@ -0,0 +1,133 @@
+# WEB-AUTOMATION
+
+## Purpose
+
+Automate rendered browsing, scraping, authentication, and multi-step browser flows with Playwright-compatible CloakBrowser.
+
+## What Ships In Every Variant
+
+- `browse.ts` for direct navigation and screenshots
+- `auth.ts` for form and Microsoft SSO login flows
+- `scrape.ts` for markdown extraction
+- `flow.ts` for natural-language or JSON browser steps
+- `extract.js` for one-shot rendered JSON extraction
+- `check-install.js` for install and wiring validation
+- `scan-local-app.ts` for configurable local-app smoke scans
+
+## Requirements
+
+- Node.js 20+
+- pnpm
+- `cloakbrowser`
+- `playwright-core`
+- Network access to download the CloakBrowser binary on first use
+
+## Install
+
+### Codex
+
+```bash
+mkdir -p ~/.codex/skills/web-automation
+cp -R skills/web-automation/codex/* ~/.codex/skills/web-automation/
+cd ~/.codex/skills/web-automation/scripts
+pnpm install
+npx cloakbrowser install
+pnpm approve-builds
+pnpm rebuild better-sqlite3 esbuild
+```
+
+### Claude Code
+
+```bash
+mkdir -p ~/.claude/skills/web-automation
+cp -R skills/web-automation/claude-code/* ~/.claude/skills/web-automation/
+cd ~/.claude/skills/web-automation/scripts
+pnpm install
+npx cloakbrowser install
+pnpm approve-builds
+pnpm rebuild better-sqlite3 esbuild
+```
+
+### OpenCode
+
+```bash
+mkdir -p ~/.config/opencode/skills/web-automation
+cp -R skills/web-automation/opencode/* ~/.config/opencode/skills/web-automation/
+cd ~/.config/opencode/skills/web-automation/scripts
+pnpm install
+npx cloakbrowser install
+pnpm approve-builds
+pnpm rebuild better-sqlite3 esbuild
+```
+
+## Update To The Latest CloakBrowser
+
+Run inside the installed `scripts/` directory for the variant you are using:
+
+```bash
+pnpm up cloakbrowser playwright-core
+npx cloakbrowser install
+pnpm approve-builds
+pnpm rebuild better-sqlite3 esbuild
+```
+
+This repo intentionally treats `cloakbrowser` as a refreshable dependency: update to the latest available compatible release, then regenerate the lockfile from that resolved set.
+
+## Verify Installation & Wiring
+
+Run in the installed `scripts/` folder:
+
+```bash
+node check-install.js
+```
+
+Expected checks:
+
+- `cloakbrowser` and `playwright-core` resolve correctly
+- `browse.ts` is wired to CloakBrowser
+
+If the check fails, stop and return:
+
+"Missing dependency/config: web-automation requires `cloakbrowser` and `playwright-core` with CloakBrowser-based scripts. Run setup in this skill, then retry."
+
+If runtime later fails with native-binding issues, run:
+
+```bash
+pnpm approve-builds
+pnpm rebuild better-sqlite3 esbuild
+```
+
+## Environment Variables
+
+- `CLOAKBROWSER_PROFILE_PATH`
+- `CLOAKBROWSER_HEADLESS`
+- `CLOAKBROWSER_USERNAME`
+- `CLOAKBROWSER_PASSWORD`
+
+There are no `CAMOUFOX_*` compatibility aliases in this migration.
+
+## Usage Examples
+
+- Browse: `npx tsx browse.ts --url "https://example.com"`
+- Scrape markdown: `npx tsx scrape.ts --url "https://example.com" --mode main --output page.md`
+- Authenticate: `npx tsx auth.ts --url "https://example.com/login"`
+- Natural-language flow: `npx tsx flow.ts --instruction 'go to https://example.com then click on "Login"'`
+- JSON extract: `node extract.js "https://example.com"`
+- Local smoke scan: `SCAN_BASE_URL=http://localhost:3000 SCAN_ROUTES=/,/dashboard npx tsx scan-local-app.ts`
+
+## Local App Smoke Scan
+
+`scan-local-app.ts` is generic. Configure it with:
+
+- `SCAN_BASE_URL`
+- `SCAN_LOGIN_PATH`
+- `SCAN_USERNAME`
+- `SCAN_PASSWORD`
+- `SCAN_USERNAME_SELECTOR`
+- `SCAN_PASSWORD_SELECTOR`
+- `SCAN_SUBMIT_SELECTOR`
+- `SCAN_ROUTES`
+- `SCAN_REPORT_PATH`
+- `SCAN_HEADLESS`
+
+If `SCAN_USERNAME` or `SCAN_PASSWORD` are omitted, the script falls back to `CLOAKBROWSER_USERNAME` and `CLOAKBROWSER_PASSWORD`.

docs/install.md

@@ -1,86 +0,0 @@
-# Installation
-
-Install from this repo similarly to superpowers: clone once, then copy/symlink agent-specific skills.
-
-## 1) Clone
-
-```bash
-git clone https://git.fiorinis.com/Home/ai-coding-skills.git
-cd ai-coding-skills
-```
-
-## 2) Install `create-plan`
-
-### Codex
-
-```bash
-mkdir -p ~/.codex/skills/create-plan
-cp -R skills/create-plan/codex/* ~/.codex/skills/create-plan/
-```
-
-### Claude Code
-
-```bash
-mkdir -p ~/.claude/skills/create-plan
-cp -R skills/create-plan/claude-code/* ~/.claude/skills/create-plan/
-```
-
-### OpenCode
-
-Use your OpenCode skills/plugin path and copy the opencode variant.
-
-```bash
-# Example path (adjust for your environment)
-mkdir -p ~/.opencode/skills/create-plan
-cp -R skills/create-plan/opencode/* ~/.opencode/skills/create-plan/
-```
-
-## 3) Install `web-automation`
-
-### Codex
-
-```bash
-mkdir -p ~/.codex/skills/web-automation
-cp -R skills/web-automation/codex/* ~/.codex/skills/web-automation/
-cd ~/.codex/skills/web-automation/scripts
-pnpm install
-npx camoufox-js fetch
-```
-
-### Claude Code
-
-```bash
-mkdir -p ~/.claude/skills/web-automation
-cp -R skills/web-automation/claude-code/* ~/.claude/skills/web-automation/
-cd ~/.claude/skills/web-automation/scripts
-pnpm install
-npx camoufox-js fetch
-```
-
-### OpenCode
-
-```bash
-mkdir -p ~/.opencode/skills/web-automation
-cp -R skills/web-automation/opencode/* ~/.opencode/skills/web-automation/
-cd ~/.opencode/skills/web-automation/scripts
-pnpm install
-npx camoufox-js fetch
-```
-
-Requirements for `web-automation`:
-- Node.js 20+
-- pnpm
-- Browser download/network access for Camoufox
-
-## 4) Verify
-
-- Ensure `SKILL.md` exists in the destination folder.
-- Ensure `templates/` files (create-plan) or `scripts/` files (web-automation) are present.
-- Start a new agent session and ask:
-  - "create a plan for ..." (create-plan)
-  - "scrape this page ..." (web-automation)
-
-## Notes
-
-- `docs/plans` / `docs/plan` can be gitignored by design.
-- Plan artifacts are intentionally local.

skills/atlassian/claude-code/SKILL.md

@@ -0,0 +1,78 @@
+---
+name: atlassian
+description: Interact with Atlassian Cloud Jira and Confluence through a portable task-oriented CLI for search, issue/page edits, comments, transitions, and bounded raw requests.
+---
+
+# Atlassian (Claude Code)
+
+Portable Atlassian workflows for Claude Code using a shared TypeScript CLI.
+
+## Requirements
+
+- Node.js 20+
+- `pnpm`
+- Atlassian Cloud account access
+- `ATLASSIAN_BASE_URL`
+- `ATLASSIAN_EMAIL`
+- `ATLASSIAN_API_TOKEN`
+
+The `ATLASSIAN_*` values may come from the shell environment or a `.env` file in `~/.claude/skills/atlassian/scripts`.
+
+## First-Time Setup
+
+```bash
+mkdir -p ~/.claude/skills/atlassian
+cp -R skills/atlassian/claude-code/* ~/.claude/skills/atlassian/
+cd ~/.claude/skills/atlassian/scripts
+pnpm install
+```
+
+## Prerequisite Check (MANDATORY)
+
+```bash
+cd ~/.claude/skills/atlassian/scripts
+node -e "require.resolve('commander');require.resolve('dotenv');console.log('OK: runtime dependencies installed')"
+node -e 'require("dotenv").config({ path: ".env" }); const required = ["ATLASSIAN_BASE_URL", "ATLASSIAN_EMAIL", "ATLASSIAN_API_TOKEN"]; const missing = required.filter((key) => !(process.env[key] || "").trim()); if (missing.length) { console.error("Missing required Atlassian config: " + missing.join(", ")); process.exit(1); } console.log("OK: Atlassian config present")'
+pnpm atlassian health
+```
+
+If any check fails, stop and return:
+
+`Missing dependency/config: atlassian requires installed CLI dependencies and valid Atlassian Cloud credentials. Configure ATLASSIAN_* in the shell environment or scripts/.env, then retry.`
+
+## Supported Commands
+
+- `pnpm atlassian health`
+- `pnpm atlassian jira-search --jql "..."`
+- `pnpm atlassian jira-get --issue ABC-123`
+- `pnpm atlassian jira-create ... [--dry-run]`
+- `pnpm atlassian jira-update ... [--dry-run]`
+- `pnpm atlassian jira-comment ... [--dry-run]`
+- `pnpm atlassian jira-transitions --issue ABC-123`
+- `pnpm atlassian jira-transition ... [--dry-run]`
+- `pnpm atlassian conf-search --query "..."`
+- `pnpm atlassian conf-get --page 12345`
+- `pnpm atlassian conf-create ... [--dry-run]`
+- `pnpm atlassian conf-update ... [--dry-run]`
+- `pnpm atlassian conf-comment ... [--dry-run]`
+- `pnpm atlassian conf-children --page 12345`
+- `pnpm atlassian raw --product jira|confluence --method GET|POST|PUT --path ...`
+
+## Usage Examples
+
+- `pnpm atlassian jira-search --jql "project = ENG ORDER BY updated DESC" --max-results 10`
+- `pnpm atlassian conf-comment --page 12345 --body-file comment.storage.html --dry-run`
+- `pnpm atlassian raw --product jira --method GET --path "/rest/api/3/issue/ENG-123"`
+
+## Safety Rules
+
+- Default output is JSON; only switch to text output when the user needs a human-readable summary.
+- Use `--dry-run` before any write unless the user clearly asked for the mutation.
+- Treat `raw` as an escape hatch, not the default API surface.
+- `--body-file` must stay inside the current workspace.
+- Confluence write bodies should be storage-format inputs in v1.
+
+## Notes
+
+- Atlassian Cloud is the primary supported platform in v1.
+- The portable CLI exists so the same skill works consistently across multiple agent environments.

skills/atlassian/claude-code/scripts/package.json

@@ -0,0 +1,20 @@
+{
+  "name": "atlassian-skill-scripts",
+  "version": "1.0.0",
+  "description": "Shared runtime for the Atlassian skill",
+  "type": "module",
+  "scripts": {
+    "atlassian": "tsx src/cli.ts",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "commander": "^13.1.0",
+    "dotenv": "^16.4.7"
+  },
+  "devDependencies": {
+    "@types/node": "^24.3.0",
+    "tsx": "^4.20.5",
+    "typescript": "^5.9.2"
+  },
+  "packageManager": "pnpm@10.18.1+sha512.77a884a165cbba2d8d1c19e3b4880eee6d2fcabd0d879121e282196b80042351d5eb3ca0935fa599da1dc51265cc68816ad2bddd2a2de5ea9fdf92adbec7cd34"
+}

skills/atlassian/claude-code/scripts/pnpm-lock.yaml

@@ -0,0 +1,361 @@
+lockfileVersion: '9.0'
+
+settings:
+  autoInstallPeers: true
+  excludeLinksFromLockfile: false
+
+importers:
+
+  .:
+    dependencies:
+      commander:
+        specifier: ^13.1.0
+        version: 13.1.0
+      dotenv:
+        specifier: ^16.4.7
+        version: 16.6.1
+    devDependencies:
+      '@types/node':
+        specifier: ^24.3.0
+        version: 24.12.0
+      tsx:
+        specifier: ^4.20.5
+        version: 4.21.0
+      typescript:
+        specifier: ^5.9.2
+        version: 5.9.3
+
+packages:
+
+  '@esbuild/aix-ppc64@0.27.3':
+    resolution: {integrity: sha512-9fJMTNFTWZMh5qwrBItuziu834eOCUcEqymSH7pY+zoMVEZg3gcPuBNxH1EvfVYe9h0x/Ptw8KBzv7qxb7l8dg==}
+    engines: {node: '>=18'}
+    cpu: [ppc64]
+    os: [aix]
+
+  '@esbuild/android-arm64@0.27.3':
+    resolution: {integrity: sha512-YdghPYUmj/FX2SYKJ0OZxf+iaKgMsKHVPF1MAq/P8WirnSpCStzKJFjOjzsW0QQ7oIAiccHdcqjbHmJxRb/dmg==}
+    engines: {node: '>=18'}
+    cpu: [arm64]
+    os: [android]
+
+  '@esbuild/android-arm@0.27.3':
+    resolution: {integrity: sha512-i5D1hPY7GIQmXlXhs2w8AWHhenb00+GxjxRncS2ZM7YNVGNfaMxgzSGuO8o8SJzRc/oZwU2bcScvVERk03QhzA==}
+    engines: {node: '>=18'}
+    cpu: [arm]
+    os: [android]
+
+  '@esbuild/android-x64@0.27.3':
+    resolution: {integrity: sha512-IN/0BNTkHtk8lkOM8JWAYFg4ORxBkZQf9zXiEOfERX/CzxW3Vg1ewAhU7QSWQpVIzTW+b8Xy+lGzdYXV6UZObQ==}
+    engines: {node: '>=18'}
+    cpu: [x64]
+    os: [android]
+
+  '@esbuild/darwin-arm64@0.27.3':
+    resolution: {integrity: sha512-Re491k7ByTVRy0t3EKWajdLIr0gz2kKKfzafkth4Q8A5n1xTHrkqZgLLjFEHVD+AXdUGgQMq+Godfq45mGpCKg==}
+    engines: {node: '>=18'}
+    cpu: [arm64]
+    os: [darwin]
+
+  '@esbuild/darwin-x64@0.27.3':
+    resolution: {integrity: sha512-vHk/hA7/1AckjGzRqi6wbo+jaShzRowYip6rt6q7VYEDX4LEy1pZfDpdxCBnGtl+A5zq8iXDcyuxwtv3hNtHFg==}
+    engines: {node: '>=18'}
+    cpu: [x64]
+    os: [darwin]
+
+  '@esbuild/freebsd-arm64@0.27.3':
+    resolution: {integrity: sha512-ipTYM2fjt3kQAYOvo6vcxJx3nBYAzPjgTCk7QEgZG8AUO3ydUhvelmhrbOheMnGOlaSFUoHXB6un+A7q4ygY9w==}
+    engines: {node: '>=18'}
+    cpu: [arm64]
+    os: [freebsd]
+
+  '@esbuild/freebsd-x64@0.27.3':
+    resolution: {integrity: sha512-dDk0X87T7mI6U3K9VjWtHOXqwAMJBNN2r7bejDsc+j03SEjtD9HrOl8gVFByeM0aJksoUuUVU9TBaZa2rgj0oA==}
+    engines: {node: '>=18'}
+    cpu: [x64]
+    os: [freebsd]
+
+  '@esbuild/linux-arm64@0.27.3':
+    resolution: {integrity: sha512-sZOuFz/xWnZ4KH3YfFrKCf1WyPZHakVzTiqji3WDc0BCl2kBwiJLCXpzLzUBLgmp4veFZdvN5ChW4Eq/8Fc2Fg==}
+    engines: {node: '>=18'}
+    cpu: [arm64]
+    os: [linux]
+
+  '@esbuild/linux-arm@0.27.3':
+    resolution: {integrity: sha512-s6nPv2QkSupJwLYyfS+gwdirm0ukyTFNl3KTgZEAiJDd+iHZcbTPPcWCcRYH+WlNbwChgH2QkE9NSlNrMT8Gfw==}
+    engines: {node: '>=18'}
+    cpu: [arm]
+    os: [linux]
+
+  '@esbuild/linux-ia32@0.27.3':
+    resolution: {integrity: sha512-yGlQYjdxtLdh0a3jHjuwOrxQjOZYD/C9PfdbgJJF3TIZWnm/tMd/RcNiLngiu4iwcBAOezdnSLAwQDPqTmtTYg==}
+    engines: {node: '>=18'}
+    cpu: [ia32]
+    os: [linux]
+
+  '@esbuild/linux-loong64@0.27.3':
+    resolution: {integrity: sha512-WO60Sn8ly3gtzhyjATDgieJNet/KqsDlX5nRC5Y3oTFcS1l0KWba+SEa9Ja1GfDqSF1z6hif/SkpQJbL63cgOA==}
+    engines: {node: '>=18'}
+    cpu: [loong64]
+    os: [linux]
+
+  '@esbuild/linux-mips64el@0.27.3':
+    resolution: {integrity: sha512-APsymYA6sGcZ4pD6k+UxbDjOFSvPWyZhjaiPyl/f79xKxwTnrn5QUnXR5prvetuaSMsb4jgeHewIDCIWljrSxw==}
+    engines: {node: '>=18'}
+    cpu: [mips64el]
+    os: [linux]
+
+  '@esbuild/linux-ppc64@0.27.3':
+    resolution: {integrity: sha512-eizBnTeBefojtDb9nSh4vvVQ3V9Qf9Df01PfawPcRzJH4gFSgrObw+LveUyDoKU3kxi5+9RJTCWlj4FjYXVPEA==}
+    engines: {node: '>=18'}
+    cpu: [ppc64]
+    os: [linux]
+
+  '@esbuild/linux-riscv64@0.27.3':
+    resolution: {integrity: sha512-3Emwh0r5wmfm3ssTWRQSyVhbOHvqegUDRd0WhmXKX2mkHJe1SFCMJhagUleMq+Uci34wLSipf8Lagt4LlpRFWQ==}
+    engines: {node: '>=18'}
+    cpu: [riscv64]
+    os: [linux]
+
+  '@esbuild/linux-s390x@0.27.3':
+    resolution: {integrity: sha512-pBHUx9LzXWBc7MFIEEL0yD/ZVtNgLytvx60gES28GcWMqil8ElCYR4kvbV2BDqsHOvVDRrOxGySBM9Fcv744hw==}
+    engines: {node: '>=18'}
+    cpu: [s390x]
+    os: [linux]
+
+  '@esbuild/linux-x64@0.27.3':
+    resolution: {integrity: sha512-Czi8yzXUWIQYAtL/2y6vogER8pvcsOsk5cpwL4Gk5nJqH5UZiVByIY8Eorm5R13gq+DQKYg0+JyQoytLQas4dA==}
+    engines: {node: '>=18'}
+    cpu: [x64]
+    os: [linux]
+
+  '@esbuild/netbsd-arm64@0.27.3':
+    resolution: {integrity: sha512-sDpk0RgmTCR/5HguIZa9n9u+HVKf40fbEUt+iTzSnCaGvY9kFP0YKBWZtJaraonFnqef5SlJ8/TiPAxzyS+UoA==}
+    engines: {node: '>=18'}
+    cpu: [arm64]
+    os: [netbsd]
+
+  '@esbuild/netbsd-x64@0.27.3':
+    resolution: {integrity: sha512-P14lFKJl/DdaE00LItAukUdZO5iqNH7+PjoBm+fLQjtxfcfFE20Xf5CrLsmZdq5LFFZzb5JMZ9grUwvtVYzjiA==}
+    engines: {node: '>=18'}
+    cpu: [x64]
+    os: [netbsd]
+
+  '@esbuild/openbsd-arm64@0.27.3':
+    resolution: {integrity: sha512-AIcMP77AvirGbRl/UZFTq5hjXK+2wC7qFRGoHSDrZ5v5b8DK/GYpXW3CPRL53NkvDqb9D+alBiC/dV0Fb7eJcw==}
+    engines: {node: '>=18'}
+    cpu: [arm64]
+    os: [openbsd]
+
+  '@esbuild/openbsd-x64@0.27.3':
+    resolution: {integrity: sha512-DnW2sRrBzA+YnE70LKqnM3P+z8vehfJWHXECbwBmH/CU51z6FiqTQTHFenPlHmo3a8UgpLyH3PT+87OViOh1AQ==}
+    engines: {node: '>=18'}
+    cpu: [x64]
+    os: [openbsd]
+
+  '@esbuild/openharmony-arm64@0.27.3':
+    resolution: {integrity: sha512-NinAEgr/etERPTsZJ7aEZQvvg/A6IsZG/LgZy+81wON2huV7SrK3e63dU0XhyZP4RKGyTm7aOgmQk0bGp0fy2g==}
+    engines: {node: '>=18'}
+    cpu: [arm64]
+    os: [openharmony]
+
+  '@esbuild/sunos-x64@0.27.3':
+    resolution: {integrity: sha512-PanZ+nEz+eWoBJ8/f8HKxTTD172SKwdXebZ0ndd953gt1HRBbhMsaNqjTyYLGLPdoWHy4zLU7bDVJztF5f3BHA==}
+    engines: {node: '>=18'}
+    cpu: [x64]
+    os: [sunos]
+
+  '@esbuild/win32-arm64@0.27.3':
+    resolution: {integrity: sha512-B2t59lWWYrbRDw/tjiWOuzSsFh1Y/E95ofKz7rIVYSQkUYBjfSgf6oeYPNWHToFRr2zx52JKApIcAS/D5TUBnA==}
+    engines: {node: '>=18'}
+    cpu: [arm64]
+    os: [win32]
+
+  '@esbuild/win32-ia32@0.27.3':
+    resolution: {integrity: sha512-QLKSFeXNS8+tHW7tZpMtjlNb7HKau0QDpwm49u0vUp9y1WOF+PEzkU84y9GqYaAVW8aH8f3GcBck26jh54cX4Q==}
+    engines: {node: '>=18'}
+    cpu: [ia32]
+    os: [win32]
+
+  '@esbuild/win32-x64@0.27.3':
+    resolution: {integrity: sha512-4uJGhsxuptu3OcpVAzli+/gWusVGwZZHTlS63hh++ehExkVT8SgiEf7/uC/PclrPPkLhZqGgCTjd0VWLo6xMqA==}
+    engines: {node: '>=18'}
+    cpu: [x64]
+    os: [win32]
+
+  '@types/node@24.12.0':
+    resolution: {integrity: sha512-GYDxsZi3ChgmckRT9HPU0WEhKLP08ev/Yfcq2AstjrDASOYCSXeyjDsHg4v5t4jOj7cyDX3vmprafKlWIG9MXQ==}
+
+  commander@13.1.0:
+    resolution: {integrity: sha512-/rFeCpNJQbhSZjGVwO9RFV3xPqbnERS8MmIQzCtD/zl6gpJuV/bMLuN92oG3F7d8oDEHHRrujSXNUr8fpjntKw==}
+    engines: {node: '>=18'}
+
+  dotenv@16.6.1:
+    resolution: {integrity: sha512-uBq4egWHTcTt33a72vpSG0z3HnPuIl6NqYcTrKEg2azoEyl2hpW0zqlxysq2pK9HlDIHyHyakeYaYnSAwd8bow==}
+    engines: {node: '>=12'}
+
+  esbuild@0.27.3:
+    resolution: {integrity: sha512-8VwMnyGCONIs6cWue2IdpHxHnAjzxnw2Zr7MkVxB2vjmQ2ivqGFb4LEG3SMnv0Gb2F/G/2yA8zUaiL1gywDCCg==}
+    engines: {node: '>=18'}
+    hasBin: true
+
+  fsevents@2.3.3:
+    resolution: {integrity: sha512-5xoDfX+fL7faATnagmWPpbFtwh/R77WmMMqqHGS65C3vvB0YHrgF+B1YmZ3441tMj5n63k0212XNoJwzlhffQw==}
+    engines: {node: ^8.16.0 || ^10.6.0 || >=11.0.0}
+    os: [darwin]
+
+  get-tsconfig@4.13.6:
+    resolution: {integrity: sha512-shZT/QMiSHc/YBLxxOkMtgSid5HFoauqCE3/exfsEcwg1WkeqjG+V40yBbBrsD+jW2HDXcs28xOfcbm2jI8Ddw==}
+
+  resolve-pkg-maps@1.0.0:
+    resolution: {integrity: sha512-seS2Tj26TBVOC2NIc2rOe2y2ZO7efxITtLZcGSOnHHNOQ7CkiUBfw0Iw2ck6xkIhPwLhKNLS8BO+hEpngQlqzw==}
+
+  tsx@4.21.0:
+    resolution: {integrity: sha512-5C1sg4USs1lfG0GFb2RLXsdpXqBSEhAaA/0kPL01wxzpMqLILNxIxIOKiILz+cdg/pLnOUxFYOR5yhHU666wbw==}
+    engines: {node: '>=18.0.0'}
+    hasBin: true
+
+  typescript@5.9.3:
+    resolution: {integrity: sha512-jl1vZzPDinLr9eUt3J/t7V6FgNEw9QjvBPdysz9KfQDD41fQrC2Y4vKQdiaUpFT4bXlb1RHhLpp8wtm6M5TgSw==}
+    engines: {node: '>=14.17'}
+    hasBin: true
+
+  undici-types@7.16.0:
+    resolution: {integrity: sha512-Zz+aZWSj8LE6zoxD+xrjh4VfkIG8Ya6LvYkZqtUQGJPZjYl53ypCaUwWqo7eI0x66KBGeRo+mlBEkMSeSZ38Nw==}
+
+snapshots:
+
+  '@esbuild/aix-ppc64@0.27.3':
+    optional: true
+
+  '@esbuild/android-arm64@0.27.3':
+    optional: true
+
+  '@esbuild/android-arm@0.27.3':
+    optional: true
+
+  '@esbuild/android-x64@0.27.3':
+    optional: true
+
+  '@esbuild/darwin-arm64@0.27.3':
+    optional: true
+
+  '@esbuild/darwin-x64@0.27.3':
+    optional: true
+
+  '@esbuild/freebsd-arm64@0.27.3':
+    optional: true
+
+  '@esbuild/freebsd-x64@0.27.3':
+    optional: true
+
+  '@esbuild/linux-arm64@0.27.3':
+    optional: true
+
+  '@esbuild/linux-arm@0.27.3':
+    optional: true
+
+  '@esbuild/linux-ia32@0.27.3':
+    optional: true
+
+  '@esbuild/linux-loong64@0.27.3':
+    optional: true
+
+  '@esbuild/linux-mips64el@0.27.3':
+    optional: true
+
+  '@esbuild/linux-ppc64@0.27.3':
+    optional: true
+
+  '@esbuild/linux-riscv64@0.27.3':
+    optional: true
+
+  '@esbuild/linux-s390x@0.27.3':
+    optional: true
+
+  '@esbuild/linux-x64@0.27.3':
+    optional: true
+
+  '@esbuild/netbsd-arm64@0.27.3':
+    optional: true
+
+  '@esbuild/netbsd-x64@0.27.3':
+    optional: true
+
+  '@esbuild/openbsd-arm64@0.27.3':
+    optional: true
+
+  '@esbuild/openbsd-x64@0.27.3':
+    optional: true
+
+  '@esbuild/openharmony-arm64@0.27.3':
+    optional: true
+
+  '@esbuild/sunos-x64@0.27.3':
+    optional: true
+
+  '@esbuild/win32-arm64@0.27.3':
+    optional: true
+
+  '@esbuild/win32-ia32@0.27.3':
+    optional: true
+
+  '@esbuild/win32-x64@0.27.3':
+    optional: true
+
+  '@types/node@24.12.0':
+    dependencies:
+      undici-types: 7.16.0
+
+  commander@13.1.0: {}
+
+  dotenv@16.6.1: {}
+
+  esbuild@0.27.3:
+    optionalDependencies:
+      '@esbuild/aix-ppc64': 0.27.3
+      '@esbuild/android-arm': 0.27.3
+      '@esbuild/android-arm64': 0.27.3
+      '@esbuild/android-x64': 0.27.3
+      '@esbuild/darwin-arm64': 0.27.3
+      '@esbuild/darwin-x64': 0.27.3
+      '@esbuild/freebsd-arm64': 0.27.3
+      '@esbuild/freebsd-x64': 0.27.3
+      '@esbuild/linux-arm': 0.27.3
+      '@esbuild/linux-arm64': 0.27.3
+      '@esbuild/linux-ia32': 0.27.3
+      '@esbuild/linux-loong64': 0.27.3
+      '@esbuild/linux-mips64el': 0.27.3
+      '@esbuild/linux-ppc64': 0.27.3
+      '@esbuild/linux-riscv64': 0.27.3
+      '@esbuild/linux-s390x': 0.27.3
+      '@esbuild/linux-x64': 0.27.3
+      '@esbuild/netbsd-arm64': 0.27.3
+      '@esbuild/netbsd-x64': 0.27.3
+      '@esbuild/openbsd-arm64': 0.27.3
+      '@esbuild/openbsd-x64': 0.27.3
+      '@esbuild/openharmony-arm64': 0.27.3
+      '@esbuild/sunos-x64': 0.27.3
+      '@esbuild/win32-arm64': 0.27.3
+      '@esbuild/win32-ia32': 0.27.3
+      '@esbuild/win32-x64': 0.27.3
+
+  fsevents@2.3.3:
+    optional: true
+
+  get-tsconfig@4.13.6:
+    dependencies:
+      resolve-pkg-maps: 1.0.0
+
+  resolve-pkg-maps@1.0.0: {}
+
+  tsx@4.21.0:
+    dependencies:
+      esbuild: 0.27.3
+      get-tsconfig: 4.13.6
+    optionalDependencies:
+      fsevents: 2.3.3
+
+  typescript@5.9.3: {}
+
+  undici-types@7.16.0: {}

skills/atlassian/claude-code/scripts/src/adf.ts

@@ -0,0 +1,92 @@
+const TEXT_NODE = "text";
+
+function textNode(text: string) {
+  return {
+    type: TEXT_NODE,
+    text,
+  };
+}
+
+function paragraphNode(lines: string[]) {
+  const content: Array<{ type: string; text?: string }> = [];
+
+  lines.forEach((line, index) => {
+    if (index > 0) {
+      content.push({ type: "hardBreak" });
+    }
+
+    if (line.length > 0) {
+      content.push(textNode(line));
+    }
+  });
+
+  return {
+    type: "paragraph",
+    ...(content.length > 0 ? { content } : {}),
+  };
+}
+
+export function markdownToAdf(input: string) {
+  const lines = input.replace(/\r\n/g, "\n").split("\n");
+  const content: Array<Record<string, unknown>> = [];
+  let index = 0;
+
+  while (index < lines.length) {
+    const current = lines[index]?.trimEnd() ?? "";
+
+    if (current.trim().length === 0) {
+      index += 1;
+      continue;
+    }
+
+    const heading = current.match(/^(#{1,6})\s+(.*)$/);
+
+    if (heading) {
+      content.push({
+        type: "heading",
+        attrs: { level: heading[1].length },
+        content: [textNode(heading[2])],
+      });
+      index += 1;
+      continue;
+    }
+
+    if (/^[-*]\s+/.test(current)) {
+      const items: Array<Record<string, unknown>> = [];
+
+      while (index < lines.length && /^[-*]\s+/.test(lines[index] ?? "")) {
+        items.push({
+          type: "listItem",
+          content: [
+            {
+              type: "paragraph",
+              content: [textNode((lines[index] ?? "").replace(/^[-*]\s+/, ""))],
+            },
+          ],
+        });
+        index += 1;
+      }
+
+      content.push({
+        type: "bulletList",
+        content: items,
+      });
+      continue;
+    }
+
+    const paragraphLines: string[] = [];
+
+    while (index < lines.length && (lines[index]?.trim().length ?? 0) > 0) {
+      paragraphLines.push(lines[index] ?? "");
+      index += 1;
+    }
+
+    content.push(paragraphNode(paragraphLines));
+  }
+
+  return {
+    type: "doc",
+    version: 1,
+    content,
+  };
+}

skills/atlassian/claude-code/scripts/src/cli.ts

@@ -0,0 +1,332 @@
+import process from "node:process";
+import { pathToFileURL } from "node:url";
+
+import { Command } from "commander";
+
+import { createConfluenceClient } from "./confluence.js";
+import { loadConfig } from "./config.js";
+import { readWorkspaceFile } from "./files.js";
+import { runHealthCheck } from "./health.js";
+import { createJiraClient } from "./jira.js";
+import { writeOutput } from "./output.js";
+import { runRawCommand } from "./raw.js";
+import type { FetchLike, OutputFormat, Writer } from "./types.js";
+
+type CliContext = {
+  cwd?: string;
+  env?: NodeJS.ProcessEnv;
+  fetchImpl?: FetchLike;
+  stdout?: Writer;
+  stderr?: Writer;
+};
+
+function resolveFormat(format: string | undefined): OutputFormat {
+  return format === "text" ? "text" : "json";
+}
+
+function createRuntime(context: CliContext) {
+  const cwd = context.cwd ?? process.cwd();
+  const env = context.env ?? process.env;
+  const stdout = context.stdout ?? process.stdout;
+  const stderr = context.stderr ?? process.stderr;
+  let configCache: ReturnType<typeof loadConfig> | undefined;
+  let jiraCache: ReturnType<typeof createJiraClient> | undefined;
+  let confluenceCache: ReturnType<typeof createConfluenceClient> | undefined;
+
+  function getConfig() {
+    configCache ??= loadConfig(env, { cwd });
+    return configCache;
+  }
+
+  function getJiraClient() {
+    jiraCache ??= createJiraClient({
+      config: getConfig(),
+      fetchImpl: context.fetchImpl,
+    });
+    return jiraCache;
+  }
+
+  function getConfluenceClient() {
+    confluenceCache ??= createConfluenceClient({
+      config: getConfig(),
+      fetchImpl: context.fetchImpl,
+    });
+    return confluenceCache;
+  }
+
+  async function readBodyFile(filePath: string | undefined) {
+    if (!filePath) {
+      return undefined;
+    }
+
+    return readWorkspaceFile(filePath, cwd);
+  }
+
+  return {
+    cwd,
+    stdout,
+    stderr,
+    readBodyFile,
+    getConfig,
+    getJiraClient,
+    getConfluenceClient,
+    fetchImpl: context.fetchImpl,
+  };
+}
+
+export function buildProgram(context: CliContext = {}) {
+  const runtime = createRuntime(context);
+  const program = new Command()
+    .name("atlassian")
+    .description("Portable Atlassian CLI for multi-agent skills")
+    .version("0.1.0");
+
+  program
+    .command("health")
+    .description("Validate configuration and Atlassian connectivity")
+    .option("--format <format>", "Output format", "json")
+    .action(async (options) => {
+      const payload = await runHealthCheck(runtime.getConfig(), runtime.fetchImpl);
+      writeOutput(
+        runtime.stdout,
+        payload,
+        resolveFormat(options.format),
+      );
+    });
+
+  program
+    .command("conf-search")
+    .requiredOption("--query <query>", "CQL search query")
+    .option("--max-results <number>", "Maximum results to return", "50")
+    .option("--start-at <number>", "Result offset", "0")
+    .option("--format <format>", "Output format", "json")
+    .action(async (options) => {
+      const payload = await runtime.getConfluenceClient().searchPages({
+        query: options.query,
+        maxResults: Number(options.maxResults),
+        startAt: Number(options.startAt),
+      });
+
+      writeOutput(runtime.stdout, payload, resolveFormat(options.format));
+    });
+
+  program
+    .command("conf-get")
+    .requiredOption("--page <page>", "Confluence page ID")
+    .option("--format <format>", "Output format", "json")
+    .action(async (options) => {
+      const payload = await runtime.getConfluenceClient().getPage(options.page);
+      writeOutput(runtime.stdout, payload, resolveFormat(options.format));
+    });
+
+  program
+    .command("conf-create")
+    .requiredOption("--title <title>", "Confluence page title")
+    .requiredOption("--body-file <path>", "Workspace-relative storage-format body file")
+    .option("--space <space>", "Confluence space ID")
+    .option("--dry-run", "Print the request without sending it")
+    .option("--format <format>", "Output format", "json")
+    .action(async (options) => {
+      const payload = await runtime.getConfluenceClient().createPage({
+        space: options.space,
+        title: options.title,
+        body: (await runtime.readBodyFile(options.bodyFile)) as string,
+        dryRun: Boolean(options.dryRun),
+      });
+
+      writeOutput(runtime.stdout, payload, resolveFormat(options.format));
+    });
+
+  program
+    .command("conf-update")
+    .requiredOption("--page <page>", "Confluence page ID")
+    .requiredOption("--title <title>", "Confluence page title")
+    .requiredOption("--body-file <path>", "Workspace-relative storage-format body file")
+    .option("--dry-run", "Print the request without sending it")
+    .option("--format <format>", "Output format", "json")
+    .action(async (options) => {
+      const payload = await runtime.getConfluenceClient().updatePage({
+        pageId: options.page,
+        title: options.title,
+        body: (await runtime.readBodyFile(options.bodyFile)) as string,
+        dryRun: Boolean(options.dryRun),
+      });
+
+      writeOutput(runtime.stdout, payload, resolveFormat(options.format));
+    });
+
+  program
+    .command("conf-comment")
+    .requiredOption("--page <page>", "Confluence page ID")
+    .requiredOption("--body-file <path>", "Workspace-relative storage-format body file")
+    .option("--dry-run", "Print the request without sending it")
+    .option("--format <format>", "Output format", "json")
+    .action(async (options) => {
+      const payload = await runtime.getConfluenceClient().commentPage({
+        pageId: options.page,
+        body: (await runtime.readBodyFile(options.bodyFile)) as string,
+        dryRun: Boolean(options.dryRun),
+      });
+
+      writeOutput(runtime.stdout, payload, resolveFormat(options.format));
+    });
+
+  program
+    .command("conf-children")
+    .requiredOption("--page <page>", "Confluence page ID")
+    .option("--max-results <number>", "Maximum results to return", "50")
+    .option("--start-at <number>", "Cursor/start token", "0")
+    .option("--format <format>", "Output format", "json")
+    .action(async (options) => {
+      const payload = await runtime.getConfluenceClient().listChildren(
+        options.page,
+        Number(options.maxResults),
+        Number(options.startAt),
+      );
+
+      writeOutput(runtime.stdout, payload, resolveFormat(options.format));
+    });
+
+  program
+    .command("raw")
+    .requiredOption("--product <product>", "jira or confluence")
+    .requiredOption("--method <method>", "GET, POST, or PUT")
+    .requiredOption("--path <path>", "Validated API path")
+    .option("--body-file <path>", "Workspace-relative JSON file")
+    .option("--dry-run", "Print the request without sending it")
+    .option("--format <format>", "Output format", "json")
+    .action(async (options) => {
+      const payload = await runRawCommand(runtime.getConfig(), runtime.fetchImpl, {
+        product: options.product,
+        method: String(options.method).toUpperCase(),
+        path: options.path,
+        bodyFile: options.bodyFile,
+        cwd: runtime.cwd,
+        dryRun: Boolean(options.dryRun),
+      });
+
+      writeOutput(runtime.stdout, payload, resolveFormat(options.format));
+    });
+
+  program
+    .command("jira-search")
+    .requiredOption("--jql <jql>", "JQL expression to execute")
+    .option("--max-results <number>", "Maximum results to return", "50")
+    .option("--start-at <number>", "Result offset", "0")
+    .option("--format <format>", "Output format", "json")
+    .action(async (options) => {
+      const payload = await runtime.getJiraClient().searchIssues({
+        jql: options.jql,
+        maxResults: Number(options.maxResults),
+        startAt: Number(options.startAt),
+      });
+
+      writeOutput(runtime.stdout, payload, resolveFormat(options.format));
+    });
+
+  program
+    .command("jira-get")
+    .requiredOption("--issue <issue>", "Issue key")
+    .option("--format <format>", "Output format", "json")
+    .action(async (options) => {
+      const payload = await runtime.getJiraClient().getIssue(options.issue);
+      writeOutput(runtime.stdout, payload, resolveFormat(options.format));
+    });
+
+  program
+    .command("jira-create")
+    .requiredOption("--type <type>", "Issue type name")
+    .requiredOption("--summary <summary>", "Issue summary")
+    .option("--project <project>", "Project key")
+    .option("--description-file <path>", "Workspace-relative markdown/text file")
+    .option("--dry-run", "Print the request without sending it")
+    .option("--format <format>", "Output format", "json")
+    .action(async (options) => {
+      const payload = await runtime.getJiraClient().createIssue({
+        project: options.project,
+        type: options.type,
+        summary: options.summary,
+        description: await runtime.readBodyFile(options.descriptionFile),
+        dryRun: Boolean(options.dryRun),
+      });
+
+      writeOutput(runtime.stdout, payload, resolveFormat(options.format));
+    });
+
+  program
+    .command("jira-update")
+    .requiredOption("--issue <issue>", "Issue key")
+    .option("--summary <summary>", "Updated summary")
+    .option("--description-file <path>", "Workspace-relative markdown/text file")
+    .option("--dry-run", "Print the request without sending it")
+    .option("--format <format>", "Output format", "json")
+    .action(async (options) => {
+      const payload = await runtime.getJiraClient().updateIssue({
+        issue: options.issue,
+        summary: options.summary,
+        description: await runtime.readBodyFile(options.descriptionFile),
+        dryRun: Boolean(options.dryRun),
+      });
+
+      writeOutput(runtime.stdout, payload, resolveFormat(options.format));
+    });
+
+  program
+    .command("jira-comment")
+    .requiredOption("--issue <issue>", "Issue key")
+    .requiredOption("--body-file <path>", "Workspace-relative markdown/text file")
+    .option("--dry-run", "Print the request without sending it")
+    .option("--format <format>", "Output format", "json")
+    .action(async (options) => {
+      const payload = await runtime.getJiraClient().commentIssue({
+        issue: options.issue,
+        body: (await runtime.readBodyFile(options.bodyFile)) as string,
+        dryRun: Boolean(options.dryRun),
+      });
+
+      writeOutput(runtime.stdout, payload, resolveFormat(options.format));
+    });
+
+  program
+    .command("jira-transitions")
+    .requiredOption("--issue <issue>", "Issue key")
+    .option("--format <format>", "Output format", "json")
+    .action(async (options) => {
+      const payload = await runtime.getJiraClient().getTransitions(options.issue);
+      writeOutput(runtime.stdout, payload, resolveFormat(options.format));
+    });
+
+  program
+    .command("jira-transition")
+    .requiredOption("--issue <issue>", "Issue key")
+    .requiredOption("--transition <transition>", "Transition ID")
+    .option("--dry-run", "Print the request without sending it")
+    .option("--format <format>", "Output format", "json")
+    .action(async (options) => {
+      const payload = await runtime.getJiraClient().transitionIssue({
+        issue: options.issue,
+        transition: options.transition,
+        dryRun: Boolean(options.dryRun),
+      });
+
+      writeOutput(runtime.stdout, payload, resolveFormat(options.format));
+    });
+
+  return program;
+}
+
+export async function runCli(argv = process.argv, context: CliContext = {}) {
+  const program = buildProgram(context);
+  await program.parseAsync(argv);
+}
+
+const isDirectExecution =
+  Boolean(process.argv[1]) && import.meta.url === pathToFileURL(process.argv[1]).href;
+
+if (isDirectExecution) {
+  runCli().catch((error: unknown) => {
+    const message = error instanceof Error ? error.message : String(error);
+    process.stderr.write(`${message}\n`);
+    process.exitCode = 1;
+  });
+}

skills/atlassian/claude-code/scripts/src/config.ts

@@ -0,0 +1,52 @@
+import path from "node:path";
+
+import { config as loadDotEnv } from "dotenv";
+
+import type { AtlassianConfig } from "./types.js";
+
+function normalizeBaseUrl(value: string) {
+  return value.replace(/\/+$/, "");
+}
+
+function readRequired(env: NodeJS.ProcessEnv, key: string) {
+  const value = env[key]?.trim();
+
+  if (!value) {
+    throw new Error(`Missing required environment variable: ${key}`);
+  }
+
+  return value;
+}
+
+export function loadConfig(
+  env: NodeJS.ProcessEnv = process.env,
+  options?: {
+    cwd?: string;
+  },
+): AtlassianConfig {
+  loadDotEnv({
+    path: path.resolve(options?.cwd ?? process.cwd(), ".env"),
+    processEnv: env as Record<string, string>,
+    override: false,
+  });
+
+  const baseUrl = normalizeBaseUrl(readRequired(env, "ATLASSIAN_BASE_URL"));
+
+  return {
+    baseUrl,
+    jiraBaseUrl: normalizeBaseUrl(env.ATLASSIAN_JIRA_BASE_URL?.trim() || baseUrl),
+    confluenceBaseUrl: normalizeBaseUrl(env.ATLASSIAN_CONFLUENCE_BASE_URL?.trim() || baseUrl),
+    email: readRequired(env, "ATLASSIAN_EMAIL"),
+    apiToken: readRequired(env, "ATLASSIAN_API_TOKEN"),
+    defaultProject: env.ATLASSIAN_DEFAULT_PROJECT?.trim() || undefined,
+    defaultSpace: env.ATLASSIAN_DEFAULT_SPACE?.trim() || undefined,
+  };
+}
+
+export function createBasicAuthHeader(config: {
+  email: string;
+  apiToken: string;
+  [key: string]: unknown;
+}) {
+  return `Basic ${Buffer.from(`${config.email}:${config.apiToken}`).toString("base64")}`;
+}

skills/atlassian/claude-code/scripts/src/confluence.ts

@@ -0,0 +1,292 @@
+import { sendJsonRequest } from "./http.js";
+import type { AtlassianConfig, CommandOutput, FetchLike } from "./types.js";
+
+type ConfluenceClientOptions = {
+  config: AtlassianConfig;
+  fetchImpl?: FetchLike;
+};
+
+type SearchInput = {
+  query: string;
+  maxResults: number;
+  startAt: number;
+};
+
+type CreateInput = {
+  space?: string;
+  title: string;
+  body: string;
+  dryRun?: boolean;
+};
+
+type UpdateInput = {
+  pageId: string;
+  title: string;
+  body: string;
+  dryRun?: boolean;
+};
+
+type CommentInput = {
+  pageId: string;
+  body: string;
+  dryRun?: boolean;
+};
+
+type PageSummary = {
+  id: string;
+  title: string;
+  type: string;
+  status?: string;
+  spaceId?: string;
+  url?: string;
+};
+
+function buildUrl(baseUrl: string, path: string) {
+  return new URL(path, `${baseUrl}/`).toString();
+}
+
+function normalizePage(baseUrl: string, page: Record<string, unknown>, excerpt?: string) {
+  const links = (page._links ?? {}) as Record<string, unknown>;
+
+  return {
+    id: String(page.id ?? ""),
+    title: String(page.title ?? ""),
+    type: String(page.type ?? "page"),
+    ...(page.status ? { status: String(page.status) } : {}),
+    ...(page.spaceId ? { spaceId: String(page.spaceId) } : {}),
+    ...(excerpt ? { excerpt } : {}),
+    ...(links.webui ? { url: `${baseUrl}${String(links.webui)}` } : {}),
+  };
+}
+
+export function createConfluenceClient(options: ConfluenceClientOptions) {
+  const config = options.config;
+
+  async function getPageForUpdate(pageId: string) {
+    return (await sendJsonRequest({
+      config,
+      fetchImpl: options.fetchImpl,
+      url: buildUrl(config.confluenceBaseUrl, `/wiki/api/v2/pages/${pageId}?body-format=storage`),
+      method: "GET",
+      errorPrefix: "Confluence request failed",
+    })) as Record<string, unknown>;
+  }
+
+  return {
+    async searchPages(input: SearchInput): Promise<CommandOutput<unknown>> {
+      const url = new URL("/wiki/rest/api/search", `${config.confluenceBaseUrl}/`);
+      url.searchParams.set("cql", input.query);
+      url.searchParams.set("limit", String(input.maxResults));
+      url.searchParams.set("start", String(input.startAt));
+
+      const raw = (await sendJsonRequest({
+        config,
+        fetchImpl: options.fetchImpl,
+        url: url.toString(),
+        method: "GET",
+        errorPrefix: "Confluence request failed",
+      })) as Record<string, unknown>;
+
+      const results = Array.isArray(raw.results) ? raw.results : [];
+
+      return {
+        ok: true,
+        data: {
+          pages: results.map((entry) => {
+            const result = entry as Record<string, unknown>;
+            return normalizePage(
+              config.baseUrl,
+              (result.content ?? {}) as Record<string, unknown>,
+              result.excerpt ? String(result.excerpt) : undefined,
+            );
+          }),
+          startAt: Number(raw.start ?? input.startAt),
+          maxResults: Number(raw.limit ?? input.maxResults),
+          total: Number(raw.totalSize ?? raw.size ?? results.length),
+        },
+      };
+    },
+
+    async getPage(pageId: string): Promise<CommandOutput<unknown>> {
+      const raw = (await sendJsonRequest({
+        config,
+        fetchImpl: options.fetchImpl,
+        url: buildUrl(config.confluenceBaseUrl, `/wiki/api/v2/pages/${pageId}?body-format=storage`),
+        method: "GET",
+        errorPrefix: "Confluence request failed",
+      })) as Record<string, unknown>;
+
+      const body = ((raw.body ?? {}) as Record<string, unknown>).storage as Record<string, unknown> | undefined;
+
+      return {
+        ok: true,
+        data: {
+          page: {
+            ...normalizePage(config.baseUrl, raw),
+            version: Number((((raw.version ?? {}) as Record<string, unknown>).number ?? 0)),
+            body: body?.value ? String(body.value) : "",
+          },
+        },
+        raw,
+      };
+    },
+
+    async listChildren(pageId: string, maxResults: number, startAt: number): Promise<CommandOutput<unknown>> {
+      const url = new URL(`/wiki/api/v2/pages/${pageId}/direct-children`, `${config.confluenceBaseUrl}/`);
+      url.searchParams.set("limit", String(maxResults));
+      url.searchParams.set("cursor", String(startAt));
+
+      const raw = (await sendJsonRequest({
+        config,
+        fetchImpl: options.fetchImpl,
+        url: url.toString(),
+        method: "GET",
+        errorPrefix: "Confluence request failed",
+      })) as Record<string, unknown>;
+
+      const results = Array.isArray(raw.results) ? raw.results : [];
+      const links = (raw._links ?? {}) as Record<string, unknown>;
+
+      return {
+        ok: true,
+        data: {
+          pages: results.map((page) => normalizePage(config.baseUrl, page as Record<string, unknown>)),
+          nextCursor: links.next ? String(links.next) : null,
+        },
+      };
+    },
+
+    async createPage(input: CreateInput): Promise<CommandOutput<unknown>> {
+      const spaceId = input.space || config.defaultSpace;
+
+      if (!spaceId) {
+        throw new Error("conf-create requires --space or ATLASSIAN_DEFAULT_SPACE");
+      }
+
+      const request = {
+        method: "POST" as const,
+        url: buildUrl(config.confluenceBaseUrl, "/wiki/api/v2/pages"),
+        body: {
+          spaceId,
+          title: input.title,
+          status: "current",
+          body: {
+            representation: "storage",
+            value: input.body,
+          },
+        },
+      };
+
+      if (input.dryRun) {
+        return {
+          ok: true,
+          dryRun: true,
+          data: request,
+        };
+      }
+
+      const raw = await sendJsonRequest({
+        config,
+        fetchImpl: options.fetchImpl,
+        url: request.url,
+        method: request.method,
+        body: request.body,
+        errorPrefix: "Confluence request failed",
+      });
+
+      return {
+        ok: true,
+        data: raw,
+      };
+    },
+
+    async updatePage(input: UpdateInput): Promise<CommandOutput<unknown>> {
+      const currentPage = await getPageForUpdate(input.pageId);
+      const version = (((currentPage.version ?? {}) as Record<string, unknown>).number ?? 0) as number;
+      const spaceId = String(currentPage.spaceId ?? "");
+
+      const request = {
+        method: "PUT" as const,
+        url: buildUrl(config.confluenceBaseUrl, `/wiki/api/v2/pages/${input.pageId}`),
+        body: {
+          id: input.pageId,
+          status: String(currentPage.status ?? "current"),
+          title: input.title,
+          spaceId,
+          version: {
+            number: Number(version) + 1,
+          },
+          body: {
+            representation: "storage",
+            value: input.body,
+          },
+        },
+      };
+
+      if (input.dryRun) {
+        return {
+          ok: true,
+          dryRun: true,
+          data: request,
+        };
+      }
+
+      const raw = await sendJsonRequest({
+        config,
+        fetchImpl: options.fetchImpl,
+        url: request.url,
+        method: request.method,
+        body: request.body,
+        errorPrefix: "Confluence request failed",
+        handleResponseError(response) {
+          if (response.status === 409) {
+            return new Error(`Confluence update conflict: page ${input.pageId} was updated by someone else`);
+          }
+
+          return undefined;
+        },
+      });
+
+      return {
+        ok: true,
+        data: raw,
+      };
+    },
+
+    async commentPage(input: CommentInput): Promise<CommandOutput<unknown>> {
+      const request = {
+        method: "POST" as const,
+        url: buildUrl(config.confluenceBaseUrl, "/wiki/api/v2/footer-comments"),
+        body: {
+          pageId: input.pageId,
+          body: {
+            representation: "storage",
+            value: input.body,
+          },
+        },
+      };
+
+      if (input.dryRun) {
+        return {
+          ok: true,
+          dryRun: true,
+          data: request,
+        };
+      }
+
+      const raw = await sendJsonRequest({
+        config,
+        fetchImpl: options.fetchImpl,
+        url: request.url,
+        method: request.method,
+        body: request.body,
+        errorPrefix: "Confluence request failed",
+      });
+
+      return {
+        ok: true,
+        data: raw,
+      };
+    },
+  };
+}

skills/atlassian/claude-code/scripts/src/files.ts

@@ -0,0 +1,13 @@
+import { readFile } from "node:fs/promises";
+import path from "node:path";
+
+export async function readWorkspaceFile(filePath: string, cwd: string) {
+  const resolved = path.resolve(cwd, filePath);
+  const relative = path.relative(cwd, resolved);
+
+  if (relative.startsWith("..") || path.isAbsolute(relative)) {
+    throw new Error(`--body-file must stay within the active workspace: ${filePath}`);
+  }
+
+  return readFile(resolved, "utf8");
+}

skills/atlassian/claude-code/scripts/src/health.ts

@@ -0,0 +1,69 @@
+import { createJsonHeaders, createStatusError } from "./http.js";
+import type { AtlassianConfig, CommandOutput, FetchLike } from "./types.js";
+
+type ProductHealth = {
+  ok: boolean;
+  status?: number;
+  message?: string;
+};
+
+function buildUrl(baseUrl: string, path: string) {
+  return new URL(path, `${baseUrl}/`).toString();
+}
+
+export async function runHealthCheck(
+  config: AtlassianConfig,
+  fetchImpl: FetchLike | undefined,
+): Promise<CommandOutput<unknown>> {
+  const client = fetchImpl ?? globalThis.fetch;
+
+  if (!client) {
+    throw new Error("Fetch API is not available in this runtime");
+  }
+
+  async function probe(product: "Jira" | "Confluence", url: string): Promise<ProductHealth> {
+    try {
+      const response = await client(url, {
+        method: "GET",
+        headers: createJsonHeaders(config, false),
+      });
+
+      if (!response.ok) {
+        const error = createStatusError(`${product} health check failed`, response);
+        return {
+          ok: false,
+          status: response.status,
+          message: error.message,
+        };
+      }
+
+      return {
+        ok: true,
+        status: response.status,
+      };
+    } catch (error: unknown) {
+      return {
+        ok: false,
+        message: error instanceof Error ? error.message : String(error),
+      };
+    }
+  }
+
+  const jira = await probe("Jira", buildUrl(config.jiraBaseUrl, "/rest/api/3/myself"));
+  const confluence = await probe("Confluence", buildUrl(config.confluenceBaseUrl, "/wiki/api/v2/spaces?limit=1"));
+
+  return {
+    ok: jira.ok && confluence.ok,
+    data: {
+      baseUrl: config.baseUrl,
+      jiraBaseUrl: config.jiraBaseUrl,
+      confluenceBaseUrl: config.confluenceBaseUrl,
+      defaultProject: config.defaultProject,
+      defaultSpace: config.defaultSpace,
+      products: {
+        jira,
+        confluence,
+      },
+    },
+  };
+}

skills/atlassian/claude-code/scripts/src/http.ts

@@ -0,0 +1,86 @@
+import { createBasicAuthHeader } from "./config.js";
+import type { AtlassianConfig, FetchLike } from "./types.js";
+
+export type HttpMethod = "GET" | "POST" | "PUT";
+
+export function createJsonHeaders(config: AtlassianConfig, includeJsonBody: boolean) {
+  const headers: Array<[string, string]> = [
+    ["Accept", "application/json"],
+    ["Authorization", createBasicAuthHeader(config)],
+  ];
+
+  if (includeJsonBody) {
+    headers.push(["Content-Type", "application/json"]);
+  }
+
+  return headers;
+}
+
+export async function parseResponse(response: Response) {
+  if (response.status === 204) {
+    return null;
+  }
+
+  const contentType = response.headers.get("content-type") ?? "";
+
+  if (contentType.includes("application/json")) {
+    try {
+      return await response.json();
+    } catch {
+      throw new Error("Malformed JSON response from Atlassian API");
+    }
+  }
+
+  return response.text();
+}
+
+export function createStatusError(errorPrefix: string, response: Response) {
+  const base = `${errorPrefix}: ${response.status} ${response.statusText}`;
+
+  switch (response.status) {
+    case 401:
+      return new Error(`${base} - check ATLASSIAN_EMAIL and ATLASSIAN_API_TOKEN`);
+    case 403:
+      return new Error(`${base} - verify product permissions for this account`);
+    case 404:
+      return new Error(`${base} - verify the resource identifier or API path`);
+    case 429:
+      return new Error(`${base} - retry later or reduce request rate`);
+    default:
+      return new Error(base);
+  }
+}
+
+export async function sendJsonRequest(options: {
+  config: AtlassianConfig;
+  fetchImpl?: FetchLike;
+  url: string;
+  method: HttpMethod;
+  body?: unknown;
+  errorPrefix: string;
+  handleResponseError?: (response: Response) => Error | undefined;
+}) {
+  const fetchImpl = options.fetchImpl ?? globalThis.fetch;
+
+  if (!fetchImpl) {
+    throw new Error("Fetch API is not available in this runtime");
+  }
+
+  const response = await fetchImpl(options.url, {
+    method: options.method,
+    headers: createJsonHeaders(options.config, options.body !== undefined),
+    ...(options.body === undefined ? {} : { body: JSON.stringify(options.body) }),
+  });
+
+  if (!response.ok) {
+    const customError = options.handleResponseError?.(response);
+
+    if (customError) {
+      throw customError;
+    }
+
+    throw createStatusError(options.errorPrefix, response);
+  }
+
+  return parseResponse(response);
+}

skills/atlassian/claude-code/scripts/src/jira.ts

@@ -0,0 +1,264 @@
+import { markdownToAdf } from "./adf.js";
+import { sendJsonRequest } from "./http.js";
+import type { AtlassianConfig, CommandOutput, FetchLike, JiraIssueSummary } from "./types.js";
+
+const ISSUE_FIELDS = ["summary", "issuetype", "status", "assignee", "created", "updated"] as const;
+
+type JiraClientOptions = {
+  config: AtlassianConfig;
+  fetchImpl?: FetchLike;
+};
+
+type SearchInput = {
+  jql: string;
+  maxResults: number;
+  startAt: number;
+};
+
+type CreateInput = {
+  project?: string;
+  type: string;
+  summary: string;
+  description?: string;
+  dryRun?: boolean;
+};
+
+type UpdateInput = {
+  issue: string;
+  summary?: string;
+  description?: string;
+  dryRun?: boolean;
+};
+
+type CommentInput = {
+  issue: string;
+  body: string;
+  dryRun?: boolean;
+};
+
+type TransitionInput = {
+  issue: string;
+  transition: string;
+  dryRun?: boolean;
+};
+
+function normalizeIssue(config: AtlassianConfig, issue: Record<string, unknown>): JiraIssueSummary {
+  const fields = (issue.fields ?? {}) as Record<string, unknown>;
+  const issueType = (fields.issuetype ?? {}) as Record<string, unknown>;
+  const status = (fields.status ?? {}) as Record<string, unknown>;
+  const assignee = (fields.assignee ?? {}) as Record<string, unknown>;
+
+  return {
+    key: String(issue.key ?? ""),
+    summary: String(fields.summary ?? ""),
+    issueType: String(issueType.name ?? ""),
+    status: String(status.name ?? ""),
+    assignee: assignee.displayName ? String(assignee.displayName) : undefined,
+    created: String(fields.created ?? ""),
+    updated: String(fields.updated ?? ""),
+    url: `${config.baseUrl}/browse/${issue.key ?? ""}`,
+  };
+}
+
+function createRequest(config: AtlassianConfig, method: "GET" | "POST" | "PUT", path: string, body?: unknown) {
+  const url = new URL(path, `${config.jiraBaseUrl}/`);
+
+  return {
+    method,
+    url: url.toString(),
+    ...(body === undefined ? {} : { body }),
+  };
+}
+
+export function createJiraClient(options: JiraClientOptions) {
+  const fetchImpl = options.fetchImpl ?? globalThis.fetch;
+
+  if (!fetchImpl) {
+    throw new Error("Fetch API is not available in this runtime");
+  }
+
+  async function send(method: "GET" | "POST" | "PUT", path: string, body?: unknown) {
+    const request = createRequest(options.config, method, path, body);
+    return sendJsonRequest({
+      config: options.config,
+      fetchImpl,
+      url: request.url,
+      method,
+      body,
+      errorPrefix: "Jira request failed",
+    });
+  }
+
+  return {
+    async searchIssues(input: SearchInput): Promise<CommandOutput<unknown>> {
+      const raw = (await send("POST", "/rest/api/3/search", {
+        jql: input.jql,
+        maxResults: input.maxResults,
+        startAt: input.startAt,
+        fields: [...ISSUE_FIELDS],
+      })) as Record<string, unknown>;
+
+      const issues = Array.isArray(raw.issues) ? raw.issues : [];
+
+      return {
+        ok: true,
+        data: {
+          issues: issues.map((issue) => normalizeIssue(options.config, issue as Record<string, unknown>)),
+          startAt: Number(raw.startAt ?? input.startAt),
+          maxResults: Number(raw.maxResults ?? input.maxResults),
+          total: Number(raw.total ?? issues.length),
+        },
+      };
+    },
+
+    async getIssue(issue: string): Promise<CommandOutput<unknown>> {
+      const url = new URL(`/rest/api/3/issue/${issue}`, `${options.config.jiraBaseUrl}/`);
+      url.searchParams.set("fields", ISSUE_FIELDS.join(","));
+
+      const raw = (await send("GET", `${url.pathname}${url.search}`)) as Record<string, unknown>;
+
+      return {
+        ok: true,
+        data: {
+          issue: normalizeIssue(options.config, raw),
+        },
+        raw,
+      };
+    },
+
+    async getTransitions(issue: string): Promise<CommandOutput<unknown>> {
+      const raw = (await send(
+        "GET",
+        `/rest/api/3/issue/${issue}/transitions`,
+      )) as { transitions?: Array<Record<string, unknown>> };
+
+      return {
+        ok: true,
+        data: {
+          transitions: (raw.transitions ?? []).map((transition) => ({
+            id: String(transition.id ?? ""),
+            name: String(transition.name ?? ""),
+            toStatus: String(((transition.to ?? {}) as Record<string, unknown>).name ?? ""),
+            hasScreen: Boolean(transition.hasScreen),
+          })),
+        },
+      };
+    },
+
+    async createIssue(input: CreateInput): Promise<CommandOutput<unknown>> {
+      const project = input.project || options.config.defaultProject;
+
+      if (!project) {
+        throw new Error("jira-create requires --project or ATLASSIAN_DEFAULT_PROJECT");
+      }
+
+      const request = createRequest(options.config, "POST", "/rest/api/3/issue", {
+        fields: {
+          project: { key: project },
+          issuetype: { name: input.type },
+          summary: input.summary,
+          ...(input.description ? { description: markdownToAdf(input.description) } : {}),
+        },
+      });
+
+      if (input.dryRun) {
+        return {
+          ok: true,
+          dryRun: true,
+          data: request,
+        };
+      }
+
+      const raw = await send("POST", "/rest/api/3/issue", request.body);
+      return { ok: true, data: raw };
+    },
+
+    async updateIssue(input: UpdateInput): Promise<CommandOutput<unknown>> {
+      const fields: Record<string, unknown> = {};
+
+      if (input.summary) {
+        fields.summary = input.summary;
+      }
+
+      if (input.description) {
+        fields.description = markdownToAdf(input.description);
+      }
+
+      if (Object.keys(fields).length === 0) {
+        throw new Error("jira-update requires --summary and/or --description-file");
+      }
+
+      const request = createRequest(options.config, "PUT", `/rest/api/3/issue/${input.issue}`, {
+        fields,
+      });
+
+      if (input.dryRun) {
+        return {
+          ok: true,
+          dryRun: true,
+          data: request,
+        };
+      }
+
+      await send("PUT", `/rest/api/3/issue/${input.issue}`, request.body);
+      return {
+        ok: true,
+        data: {
+          issue: input.issue,
+          updated: true,
+        },
+      };
+    },
+
+    async commentIssue(input: CommentInput): Promise<CommandOutput<unknown>> {
+      const request = createRequest(options.config, "POST", `/rest/api/3/issue/${input.issue}/comment`, {
+        body: markdownToAdf(input.body),
+      });
+
+      if (input.dryRun) {
+        return {
+          ok: true,
+          dryRun: true,
+          data: request,
+        };
+      }
+
+      const raw = await send("POST", `/rest/api/3/issue/${input.issue}/comment`, request.body);
+      return {
+        ok: true,
+        data: raw,
+      };
+    },
+
+    async transitionIssue(input: TransitionInput): Promise<CommandOutput<unknown>> {
+      const request = createRequest(
+        options.config,
+        "POST",
+        `/rest/api/3/issue/${input.issue}/transitions`,
+        {
+          transition: {
+            id: input.transition,
+          },
+        },
+      );
+
+      if (input.dryRun) {
+        return {
+          ok: true,
+          dryRun: true,
+          data: request,
+        };
+      }
+
+      await send("POST", `/rest/api/3/issue/${input.issue}/transitions`, request.body);
+      return {
+        ok: true,
+        data: {
+          issue: input.issue,
+          transitioned: true,
+          transition: input.transition,
+        },
+      };
+    },
+  };
+}

skills/atlassian/claude-code/scripts/src/output.ts

@@ -0,0 +1,44 @@
+import type { CommandOutput, OutputFormat, Writer } from "./types.js";
+
+function renderText(payload: CommandOutput<unknown>) {
+  const data = payload.data as Record<string, unknown>;
+
+  if (Array.isArray(data?.issues)) {
+    return data.issues
+      .map((issue) => {
+        const item = issue as Record<string, string>;
+        return `${item.key} [${item.status}] ${item.issueType} - ${item.summary}`;
+      })
+      .join("\n");
+  }
+
+  if (data?.issue && typeof data.issue === "object") {
+    const issue = data.issue as Record<string, string>;
+    return [
+      issue.key,
+      `${issue.issueType} | ${issue.status}`,
+      issue.summary,
+      issue.url,
+    ].join("\n");
+  }
+
+  if (Array.isArray(data?.transitions)) {
+    return data.transitions
+      .map((transition) => {
+        const item = transition as Record<string, string>;
+        return `${item.id} ${item.name} -> ${item.toStatus}`;
+      })
+      .join("\n");
+  }
+
+  return JSON.stringify(payload, null, 2);
+}
+
+export function writeOutput(
+  writer: Writer,
+  payload: CommandOutput<unknown>,
+  format: OutputFormat = "json",
+) {
+  const body = format === "text" ? renderText(payload) : JSON.stringify(payload, null, 2);
+  writer.write(`${body}\n`);
+}

skills/atlassian/claude-code/scripts/src/raw.ts

@@ -0,0 +1,85 @@
+import { readWorkspaceFile } from "./files.js";
+import { sendJsonRequest } from "./http.js";
+import type { AtlassianConfig, CommandOutput, FetchLike } from "./types.js";
+
+const JIRA_ALLOWED_PREFIXES = ["/rest/api/3/"] as const;
+const CONFLUENCE_ALLOWED_PREFIXES = ["/wiki/api/v2/", "/wiki/rest/api/"] as const;
+
+type RawInput = {
+  product: "jira" | "confluence";
+  method: string;
+  path: string;
+  bodyFile?: string;
+  cwd: string;
+  dryRun?: boolean;
+};
+
+function getAllowedPrefixes(product: RawInput["product"]) {
+  return product === "jira" ? JIRA_ALLOWED_PREFIXES : CONFLUENCE_ALLOWED_PREFIXES;
+}
+
+function buildUrl(config: AtlassianConfig, product: RawInput["product"], path: string) {
+  const baseUrl = product === "jira" ? config.jiraBaseUrl : config.confluenceBaseUrl;
+  return new URL(path, `${baseUrl}/`).toString();
+}
+
+function validateMethod(method: string): asserts method is "GET" | "POST" | "PUT" {
+  if (!["GET", "POST", "PUT"].includes(method)) {
+    throw new Error("raw only allows GET, POST, and PUT");
+  }
+}
+
+function validatePath(product: RawInput["product"], path: string) {
+  const allowedPrefixes = getAllowedPrefixes(product);
+
+  if (!allowedPrefixes.some((prefix) => path.startsWith(prefix))) {
+    throw new Error(`raw path is not allowed for ${product}: ${path}`);
+  }
+}
+
+async function readRawBody(bodyFile: string | undefined, cwd: string) {
+  if (!bodyFile) {
+    return undefined;
+  }
+
+  const contents = await readWorkspaceFile(bodyFile, cwd);
+  return JSON.parse(contents) as unknown;
+}
+
+export async function runRawCommand(
+  config: AtlassianConfig,
+  fetchImpl: FetchLike | undefined,
+  input: RawInput,
+): Promise<CommandOutput<unknown>> {
+  validateMethod(input.method);
+  validatePath(input.product, input.path);
+
+  const body = await readRawBody(input.bodyFile, input.cwd);
+  const request = {
+    method: input.method,
+    url: buildUrl(config, input.product, input.path),
+    ...(body === undefined ? {} : { body }),
+  };
+
+  if (input.dryRun) {
+    return {
+      ok: true,
+      dryRun: true,
+      data: request,
+    };
+  }
+
+  const data = await sendJsonRequest({
+    config,
+    fetchImpl,
+    url: request.url,
+    method: input.method,
+    body,
+    errorPrefix: "Raw request failed",
+  });
+
+  return {
+    ok: true,
+    data,
+  };
+}

skills/atlassian/claude-code/scripts/src/types.ts

@@ -0,0 +1,35 @@
+export type AtlassianConfig = {
+  baseUrl: string;
+  jiraBaseUrl: string;
+  confluenceBaseUrl: string;
+  email: string;
+  apiToken: string;
+  defaultProject?: string;
+  defaultSpace?: string;
+};
+
+export type CommandOutput<T> = {
+  ok: boolean;
+  data: T;
+  dryRun?: boolean;
+  raw?: unknown;
+};
+
+export type JiraIssueSummary = {
+  key: string;
+  summary: string;
+  issueType: string;
+  status: string;
+  assignee?: string;
+  created: string;
+  updated: string;
+  url: string;
+};
+
+export type Writer = {
+  write(chunk: string | Uint8Array): unknown;
+};
+
+export type FetchLike = typeof fetch;
+
+export type OutputFormat = "json" | "text";

skills/atlassian/claude-code/scripts/tsconfig.json

@@ -0,0 +1,15 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "esModuleInterop": true,
+    "forceConsistentCasingInFileNames": true,
+    "strict": true,
+    "skipLibCheck": true,
+    "resolveJsonModule": true,
+    "types": ["node"],
+    "outDir": "dist"
+  },
+  "include": ["src/**/*.ts", "scripts/**/*.ts", "tests/**/*.ts"]
+}

skills/atlassian/codex/SKILL.md

@@ -0,0 +1,81 @@
+---
+name: atlassian
+description: Interact with Atlassian Cloud Jira and Confluence through a portable task-oriented CLI for search, issue/page edits, comments, transitions, and bounded raw requests.
+---
+
+# Atlassian (Codex)
+
+Portable Atlassian workflows for Codex using a shared TypeScript CLI.
+
+## Requirements
+
+- Node.js 20+
+- `pnpm`
+- Atlassian Cloud account access
+- `ATLASSIAN_BASE_URL`
+- `ATLASSIAN_EMAIL`
+- `ATLASSIAN_API_TOKEN`
+
+The `ATLASSIAN_*` values may come from the shell environment or a `.env` file in `~/.codex/skills/atlassian/scripts`.
+
+## First-Time Setup
+
+```bash
+mkdir -p ~/.codex/skills/atlassian
+cp -R skills/atlassian/codex/* ~/.codex/skills/atlassian/
+cd ~/.codex/skills/atlassian/scripts
+pnpm install
+```
+
+## Prerequisite Check (MANDATORY)
+
+Run before using the skill:
+
+```bash
+cd ~/.codex/skills/atlassian/scripts
+node -e "require.resolve('commander');require.resolve('dotenv');console.log('OK: runtime dependencies installed')"
+node -e 'require("dotenv").config({ path: ".env" }); const required = ["ATLASSIAN_BASE_URL", "ATLASSIAN_EMAIL", "ATLASSIAN_API_TOKEN"]; const missing = required.filter((key) => !(process.env[key] || "").trim()); if (missing.length) { console.error("Missing required Atlassian config: " + missing.join(", ")); process.exit(1); } console.log("OK: Atlassian config present")'
+pnpm atlassian health
+```
+
+If any check fails, stop and return:
+
+`Missing dependency/config: atlassian requires installed CLI dependencies and valid Atlassian Cloud credentials. Configure ATLASSIAN_* in the shell environment or scripts/.env, then retry.`
+
+## Supported Commands
+
+- `pnpm atlassian health`
+- `pnpm atlassian jira-search --jql "..."`
+- `pnpm atlassian jira-get --issue ABC-123`
+- `pnpm atlassian jira-create ... [--dry-run]`
+- `pnpm atlassian jira-update ... [--dry-run]`
+- `pnpm atlassian jira-comment ... [--dry-run]`
+- `pnpm atlassian jira-transitions --issue ABC-123`
+- `pnpm atlassian jira-transition ... [--dry-run]`
+- `pnpm atlassian conf-search --query "..."`
+- `pnpm atlassian conf-get --page 12345`
+- `pnpm atlassian conf-create ... [--dry-run]`
+- `pnpm atlassian conf-update ... [--dry-run]`
+- `pnpm atlassian conf-comment ... [--dry-run]`
+- `pnpm atlassian conf-children --page 12345`
+- `pnpm atlassian raw --product jira|confluence --method GET|POST|PUT --path ...`
+
+## Usage Examples
+
+- `pnpm atlassian jira-search --jql "project = ENG ORDER BY updated DESC" --max-results 10`
+- `pnpm atlassian conf-update --page 12345 --title "Runbook" --body-file page.storage.html --dry-run`
+- `pnpm atlassian raw --product confluence --method POST --path "/wiki/api/v2/pages" --body-file page.json --dry-run`
+
+## Safety Rules
+
+- Default output is JSON; prefer that for agent workflows.
+- Use `--dry-run` before any mutating command unless the user clearly wants the write to happen immediately.
+- Jira long-text fields are converted to ADF locally.
+- Confluence page bodies are storage-first in v1.
+- `--body-file` must point to workspace-scoped files only; do not use arbitrary system paths.
+- `raw` is for explicit edge cases only and does not allow `DELETE`.
+
+## Notes
+
+- Atlassian Cloud is the only first-class target in v1.
+- This skill exists so Codex, Claude Code, Cursor Agent, and OpenCode can share the same command surface even when MCP access differs.

skills/atlassian/codex/scripts/package.json

@@ -0,0 +1,20 @@
+{
+  "name": "atlassian-skill-scripts",
+  "version": "1.0.0",
+  "description": "Shared runtime for the Atlassian skill",
+  "type": "module",
+  "scripts": {
+    "atlassian": "tsx src/cli.ts",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "commander": "^13.1.0",
+    "dotenv": "^16.4.7"
+  },
+  "devDependencies": {
+    "@types/node": "^24.3.0",
+    "tsx": "^4.20.5",
+    "typescript": "^5.9.2"
+  },
+  "packageManager": "pnpm@10.18.1+sha512.77a884a165cbba2d8d1c19e3b4880eee6d2fcabd0d879121e282196b80042351d5eb3ca0935fa599da1dc51265cc68816ad2bddd2a2de5ea9fdf92adbec7cd34"
+}

skills/atlassian/codex/scripts/pnpm-lock.yaml

@@ -0,0 +1,361 @@
+lockfileVersion: '9.0'
+
+settings:
+  autoInstallPeers: true
+  excludeLinksFromLockfile: false
+
+importers:
+
+  .:
+    dependencies:
+      commander:
+        specifier: ^13.1.0
+        version: 13.1.0
+      dotenv:
+        specifier: ^16.4.7
+        version: 16.6.1
+    devDependencies:
+      '@types/node':
+        specifier: ^24.3.0
+        version: 24.12.0
+      tsx:
+        specifier: ^4.20.5
+        version: 4.21.0
+      typescript:
+        specifier: ^5.9.2
+        version: 5.9.3
+
+packages:
+
+  '@esbuild/aix-ppc64@0.27.3':
+    resolution: {integrity: sha512-9fJMTNFTWZMh5qwrBItuziu834eOCUcEqymSH7pY+zoMVEZg3gcPuBNxH1EvfVYe9h0x/Ptw8KBzv7qxb7l8dg==}
+    engines: {node: '>=18'}
+    cpu: [ppc64]
+    os: [aix]
+
+  '@esbuild/android-arm64@0.27.3':
+    resolution: {integrity: sha512-YdghPYUmj/FX2SYKJ0OZxf+iaKgMsKHVPF1MAq/P8WirnSpCStzKJFjOjzsW0QQ7oIAiccHdcqjbHmJxRb/dmg==}
+    engines: {node: '>=18'}
+    cpu: [arm64]
+    os: [android]
+
+  '@esbuild/android-arm@0.27.3':
+    resolution: {integrity: sha512-i5D1hPY7GIQmXlXhs2w8AWHhenb00+GxjxRncS2ZM7YNVGNfaMxgzSGuO8o8SJzRc/oZwU2bcScvVERk03QhzA==}
+    engines: {node: '>=18'}
+    cpu: [arm]
+    os: [android]
+
+  '@esbuild/android-x64@0.27.3':
+    resolution: {integrity: sha512-IN/0BNTkHtk8lkOM8JWAYFg4ORxBkZQf9zXiEOfERX/CzxW3Vg1ewAhU7QSWQpVIzTW+b8Xy+lGzdYXV6UZObQ==}
+    engines: {node: '>=18'}
+    cpu: [x64]
+    os: [android]
+
+  '@esbuild/darwin-arm64@0.27.3':
+    resolution: {integrity: sha512-Re491k7ByTVRy0t3EKWajdLIr0gz2kKKfzafkth4Q8A5n1xTHrkqZgLLjFEHVD+AXdUGgQMq+Godfq45mGpCKg==}
+    engines: {node: '>=18'}
+    cpu: [arm64]
+    os: [darwin]
+
+  '@esbuild/darwin-x64@0.27.3':
+    resolution: {integrity: sha512-vHk/hA7/1AckjGzRqi6wbo+jaShzRowYip6rt6q7VYEDX4LEy1pZfDpdxCBnGtl+A5zq8iXDcyuxwtv3hNtHFg==}
+    engines: {node: '>=18'}
+    cpu: [x64]
+    os: [darwin]
+
+  '@esbuild/freebsd-arm64@0.27.3':
+    resolution: {integrity: sha512-ipTYM2fjt3kQAYOvo6vcxJx3nBYAzPjgTCk7QEgZG8AUO3ydUhvelmhrbOheMnGOlaSFUoHXB6un+A7q4ygY9w==}
+    engines: {node: '>=18'}
+    cpu: [arm64]
+    os: [freebsd]
+
+  '@esbuild/freebsd-x64@0.27.3':
+    resolution: {integrity: sha512-dDk0X87T7mI6U3K9VjWtHOXqwAMJBNN2r7bejDsc+j03SEjtD9HrOl8gVFByeM0aJksoUuUVU9TBaZa2rgj0oA==}
+    engines: {node: '>=18'}
+    cpu: [x64]
+    os: [freebsd]
+
+  '@esbuild/linux-arm64@0.27.3':
+    resolution: {integrity: sha512-sZOuFz/xWnZ4KH3YfFrKCf1WyPZHakVzTiqji3WDc0BCl2kBwiJLCXpzLzUBLgmp4veFZdvN5ChW4Eq/8Fc2Fg==}
+    engines: {node: '>=18'}
+    cpu: [arm64]
+    os: [linux]
+
+  '@esbuild/linux-arm@0.27.3':
+    resolution: {integrity: sha512-s6nPv2QkSupJwLYyfS+gwdirm0ukyTFNl3KTgZEAiJDd+iHZcbTPPcWCcRYH+WlNbwChgH2QkE9NSlNrMT8Gfw==}
+    engines: {node: '>=18'}
+    cpu: [arm]
+    os: [linux]
+
+  '@esbuild/linux-ia32@0.27.3':
+    resolution: {integrity: sha512-yGlQYjdxtLdh0a3jHjuwOrxQjOZYD/C9PfdbgJJF3TIZWnm/tMd/RcNiLngiu4iwcBAOezdnSLAwQDPqTmtTYg==}
+    engines: {node: '>=18'}
+    cpu: [ia32]
+    os: [linux]
+
+  '@esbuild/linux-loong64@0.27.3':
+    resolution: {integrity: sha512-WO60Sn8ly3gtzhyjATDgieJNet/KqsDlX5nRC5Y3oTFcS1l0KWba+SEa9Ja1GfDqSF1z6hif/SkpQJbL63cgOA==}
+    engines: {node: '>=18'}
+    cpu: [loong64]
+    os: [linux]
+
+  '@esbuild/linux-mips64el@0.27.3':
+    resolution: {integrity: sha512-APsymYA6sGcZ4pD6k+UxbDjOFSvPWyZhjaiPyl/f79xKxwTnrn5QUnXR5prvetuaSMsb4jgeHewIDCIWljrSxw==}
+    engines: {node: '>=18'}
+    cpu: [mips64el]
+    os: [linux]
+
+  '@esbuild/linux-ppc64@0.27.3':
+    resolution: {integrity: sha512-eizBnTeBefojtDb9nSh4vvVQ3V9Qf9Df01PfawPcRzJH4gFSgrObw+LveUyDoKU3kxi5+9RJTCWlj4FjYXVPEA==}
+    engines: {node: '>=18'}
+    cpu: [ppc64]
+    os: [linux]
+
+  '@esbuild/linux-riscv64@0.27.3':
+    resolution: {integrity: sha512-3Emwh0r5wmfm3ssTWRQSyVhbOHvqegUDRd0WhmXKX2mkHJe1SFCMJhagUleMq+Uci34wLSipf8Lagt4LlpRFWQ==}
+    engines: {node: '>=18'}
+    cpu: [riscv64]
+    os: [linux]
+
+  '@esbuild/linux-s390x@0.27.3':
+    resolution: {integrity: sha512-pBHUx9LzXWBc7MFIEEL0yD/ZVtNgLytvx60gES28GcWMqil8ElCYR4kvbV2BDqsHOvVDRrOxGySBM9Fcv744hw==}
+    engines: {node: '>=18'}
+    cpu: [s390x]
+    os: [linux]
+
+  '@esbuild/linux-x64@0.27.3':
+    resolution: {integrity: sha512-Czi8yzXUWIQYAtL/2y6vogER8pvcsOsk5cpwL4Gk5nJqH5UZiVByIY8Eorm5R13gq+DQKYg0+JyQoytLQas4dA==}
+    engines: {node: '>=18'}
+    cpu: [x64]
+    os: [linux]
+
+  '@esbuild/netbsd-arm64@0.27.3':
+    resolution: {integrity: sha512-sDpk0RgmTCR/5HguIZa9n9u+HVKf40fbEUt+iTzSnCaGvY9kFP0YKBWZtJaraonFnqef5SlJ8/TiPAxzyS+UoA==}
+    engines: {node: '>=18'}
+    cpu: [arm64]
+    os: [netbsd]
+
+  '@esbuild/netbsd-x64@0.27.3':
+    resolution: {integrity: sha512-P14lFKJl/DdaE00LItAukUdZO5iqNH7+PjoBm+fLQjtxfcfFE20Xf5CrLsmZdq5LFFZzb5JMZ9grUwvtVYzjiA==}
+    engines: {node: '>=18'}
+    cpu: [x64]
+    os: [netbsd]
+
+  '@esbuild/openbsd-arm64@0.27.3':
+    resolution: {integrity: sha512-AIcMP77AvirGbRl/UZFTq5hjXK+2wC7qFRGoHSDrZ5v5b8DK/GYpXW3CPRL53NkvDqb9D+alBiC/dV0Fb7eJcw==}
+    engines: {node: '>=18'}
+    cpu: [arm64]
+    os: [openbsd]
+
+  '@esbuild/openbsd-x64@0.27.3':
+    resolution: {integrity: sha512-DnW2sRrBzA+YnE70LKqnM3P+z8vehfJWHXECbwBmH/CU51z6FiqTQTHFenPlHmo3a8UgpLyH3PT+87OViOh1AQ==}
+    engines: {node: '>=18'}
+    cpu: [x64]
+    os: [openbsd]
+
+  '@esbuild/openharmony-arm64@0.27.3':
+    resolution: {integrity: sha512-NinAEgr/etERPTsZJ7aEZQvvg/A6IsZG/LgZy+81wON2huV7SrK3e63dU0XhyZP4RKGyTm7aOgmQk0bGp0fy2g==}
+    engines: {node: '>=18'}
+    cpu: [arm64]
+    os: [openharmony]
+
+  '@esbuild/sunos-x64@0.27.3':
+    resolution: {integrity: sha512-PanZ+nEz+eWoBJ8/f8HKxTTD172SKwdXebZ0ndd953gt1HRBbhMsaNqjTyYLGLPdoWHy4zLU7bDVJztF5f3BHA==}
+    engines: {node: '>=18'}
+    cpu: [x64]
+    os: [sunos]
+
+  '@esbuild/win32-arm64@0.27.3':
+    resolution: {integrity: sha512-B2t59lWWYrbRDw/tjiWOuzSsFh1Y/E95ofKz7rIVYSQkUYBjfSgf6oeYPNWHToFRr2zx52JKApIcAS/D5TUBnA==}
+    engines: {node: '>=18'}
+    cpu: [arm64]
+    os: [win32]
+
+  '@esbuild/win32-ia32@0.27.3':
+    resolution: {integrity: sha512-QLKSFeXNS8+tHW7tZpMtjlNb7HKau0QDpwm49u0vUp9y1WOF+PEzkU84y9GqYaAVW8aH8f3GcBck26jh54cX4Q==}
+    engines: {node: '>=18'}
+    cpu: [ia32]
+    os: [win32]
+
+  '@esbuild/win32-x64@0.27.3':
+    resolution: {integrity: sha512-4uJGhsxuptu3OcpVAzli+/gWusVGwZZHTlS63hh++ehExkVT8SgiEf7/uC/PclrPPkLhZqGgCTjd0VWLo6xMqA==}
+    engines: {node: '>=18'}
+    cpu: [x64]
+    os: [win32]
+
+  '@types/node@24.12.0':
+    resolution: {integrity: sha512-GYDxsZi3ChgmckRT9HPU0WEhKLP08ev/Yfcq2AstjrDASOYCSXeyjDsHg4v5t4jOj7cyDX3vmprafKlWIG9MXQ==}
+
+  commander@13.1.0:
+    resolution: {integrity: sha512-/rFeCpNJQbhSZjGVwO9RFV3xPqbnERS8MmIQzCtD/zl6gpJuV/bMLuN92oG3F7d8oDEHHRrujSXNUr8fpjntKw==}
+    engines: {node: '>=18'}
+
+  dotenv@16.6.1:
+    resolution: {integrity: sha512-uBq4egWHTcTt33a72vpSG0z3HnPuIl6NqYcTrKEg2azoEyl2hpW0zqlxysq2pK9HlDIHyHyakeYaYnSAwd8bow==}
+    engines: {node: '>=12'}
+
+  esbuild@0.27.3:
+    resolution: {integrity: sha512-8VwMnyGCONIs6cWue2IdpHxHnAjzxnw2Zr7MkVxB2vjmQ2ivqGFb4LEG3SMnv0Gb2F/G/2yA8zUaiL1gywDCCg==}
+    engines: {node: '>=18'}
+    hasBin: true
+
+  fsevents@2.3.3:
+    resolution: {integrity: sha512-5xoDfX+fL7faATnagmWPpbFtwh/R77WmMMqqHGS65C3vvB0YHrgF+B1YmZ3441tMj5n63k0212XNoJwzlhffQw==}
+    engines: {node: ^8.16.0 || ^10.6.0 || >=11.0.0}
+    os: [darwin]
+
+  get-tsconfig@4.13.6:
+    resolution: {integrity: sha512-shZT/QMiSHc/YBLxxOkMtgSid5HFoauqCE3/exfsEcwg1WkeqjG+V40yBbBrsD+jW2HDXcs28xOfcbm2jI8Ddw==}
+
+  resolve-pkg-maps@1.0.0:
+    resolution: {integrity: sha512-seS2Tj26TBVOC2NIc2rOe2y2ZO7efxITtLZcGSOnHHNOQ7CkiUBfw0Iw2ck6xkIhPwLhKNLS8BO+hEpngQlqzw==}
+
+  tsx@4.21.0:
+    resolution: {integrity: sha512-5C1sg4USs1lfG0GFb2RLXsdpXqBSEhAaA/0kPL01wxzpMqLILNxIxIOKiILz+cdg/pLnOUxFYOR5yhHU666wbw==}
+    engines: {node: '>=18.0.0'}
+    hasBin: true
+
+  typescript@5.9.3:
+    resolution: {integrity: sha512-jl1vZzPDinLr9eUt3J/t7V6FgNEw9QjvBPdysz9KfQDD41fQrC2Y4vKQdiaUpFT4bXlb1RHhLpp8wtm6M5TgSw==}
+    engines: {node: '>=14.17'}
+    hasBin: true
+
+  undici-types@7.16.0:
+    resolution: {integrity: sha512-Zz+aZWSj8LE6zoxD+xrjh4VfkIG8Ya6LvYkZqtUQGJPZjYl53ypCaUwWqo7eI0x66KBGeRo+mlBEkMSeSZ38Nw==}
+
+snapshots:
+
+  '@esbuild/aix-ppc64@0.27.3':
+    optional: true
+
+  '@esbuild/android-arm64@0.27.3':
+    optional: true
+
+  '@esbuild/android-arm@0.27.3':
+    optional: true
+
+  '@esbuild/android-x64@0.27.3':
+    optional: true
+
+  '@esbuild/darwin-arm64@0.27.3':
+    optional: true
+
+  '@esbuild/darwin-x64@0.27.3':
+    optional: true
+
+  '@esbuild/freebsd-arm64@0.27.3':
+    optional: true
+
+  '@esbuild/freebsd-x64@0.27.3':
+    optional: true
+
+  '@esbuild/linux-arm64@0.27.3':
+    optional: true
+
+  '@esbuild/linux-arm@0.27.3':
+    optional: true
+
+  '@esbuild/linux-ia32@0.27.3':
+    optional: true
+
+  '@esbuild/linux-loong64@0.27.3':
+    optional: true
+
+  '@esbuild/linux-mips64el@0.27.3':
+    optional: true
+
+  '@esbuild/linux-ppc64@0.27.3':
+    optional: true
+
+  '@esbuild/linux-riscv64@0.27.3':
+    optional: true
+
+  '@esbuild/linux-s390x@0.27.3':
+    optional: true
+
+  '@esbuild/linux-x64@0.27.3':
+    optional: true
+
+  '@esbuild/netbsd-arm64@0.27.3':
+    optional: true
+
+  '@esbuild/netbsd-x64@0.27.3':
+    optional: true
+
+  '@esbuild/openbsd-arm64@0.27.3':
+    optional: true
+
+  '@esbuild/openbsd-x64@0.27.3':
+    optional: true
+
+  '@esbuild/openharmony-arm64@0.27.3':
+    optional: true
+
+  '@esbuild/sunos-x64@0.27.3':
+    optional: true
+
+  '@esbuild/win32-arm64@0.27.3':
+    optional: true
+
+  '@esbuild/win32-ia32@0.27.3':
+    optional: true
+
+  '@esbuild/win32-x64@0.27.3':
+    optional: true
+
+  '@types/node@24.12.0':
+    dependencies:
+      undici-types: 7.16.0
+
+  commander@13.1.0: {}
+
+  dotenv@16.6.1: {}
+
+  esbuild@0.27.3:
+    optionalDependencies:
+      '@esbuild/aix-ppc64': 0.27.3
+      '@esbuild/android-arm': 0.27.3
+      '@esbuild/android-arm64': 0.27.3
+      '@esbuild/android-x64': 0.27.3
+      '@esbuild/darwin-arm64': 0.27.3
+      '@esbuild/darwin-x64': 0.27.3
+      '@esbuild/freebsd-arm64': 0.27.3
+      '@esbuild/freebsd-x64': 0.27.3
+      '@esbuild/linux-arm': 0.27.3
+      '@esbuild/linux-arm64': 0.27.3
+      '@esbuild/linux-ia32': 0.27.3
+      '@esbuild/linux-loong64': 0.27.3
+      '@esbuild/linux-mips64el': 0.27.3
+      '@esbuild/linux-ppc64': 0.27.3
+      '@esbuild/linux-riscv64': 0.27.3
+      '@esbuild/linux-s390x': 0.27.3
+      '@esbuild/linux-x64': 0.27.3
+      '@esbuild/netbsd-arm64': 0.27.3
+      '@esbuild/netbsd-x64': 0.27.3
+      '@esbuild/openbsd-arm64': 0.27.3
+      '@esbuild/openbsd-x64': 0.27.3
+      '@esbuild/openharmony-arm64': 0.27.3
+      '@esbuild/sunos-x64': 0.27.3
+      '@esbuild/win32-arm64': 0.27.3
+      '@esbuild/win32-ia32': 0.27.3
+      '@esbuild/win32-x64': 0.27.3
+
+  fsevents@2.3.3:
+    optional: true
+
+  get-tsconfig@4.13.6:
+    dependencies:
+      resolve-pkg-maps: 1.0.0
+
+  resolve-pkg-maps@1.0.0: {}
+
+  tsx@4.21.0:
+    dependencies:
+      esbuild: 0.27.3
+      get-tsconfig: 4.13.6
+    optionalDependencies:
+      fsevents: 2.3.3
+
+  typescript@5.9.3: {}
+
+  undici-types@7.16.0: {}

skills/atlassian/codex/scripts/src/adf.ts

@@ -0,0 +1,92 @@
+const TEXT_NODE = "text";
+
+function textNode(text: string) {
+  return {
+    type: TEXT_NODE,
+    text,
+  };
+}
+
+function paragraphNode(lines: string[]) {
+  const content: Array<{ type: string; text?: string }> = [];
+
+  lines.forEach((line, index) => {
+    if (index > 0) {
+      content.push({ type: "hardBreak" });
+    }
+
+    if (line.length > 0) {
+      content.push(textNode(line));
+    }
+  });
+
+  return {
+    type: "paragraph",
+    ...(content.length > 0 ? { content } : {}),
+  };
+}
+
+export function markdownToAdf(input: string) {
+  const lines = input.replace(/\r\n/g, "\n").split("\n");
+  const content: Array<Record<string, unknown>> = [];
+  let index = 0;
+
+  while (index < lines.length) {
+    const current = lines[index]?.trimEnd() ?? "";
+
+    if (current.trim().length === 0) {
+      index += 1;
+      continue;
+    }
+
+    const heading = current.match(/^(#{1,6})\s+(.*)$/);
+
+    if (heading) {
+      content.push({
+        type: "heading",
+        attrs: { level: heading[1].length },
+        content: [textNode(heading[2])],
+      });
+      index += 1;
+      continue;
+    }
+
+    if (/^[-*]\s+/.test(current)) {
+      const items: Array<Record<string, unknown>> = [];
+
+      while (index < lines.length && /^[-*]\s+/.test(lines[index] ?? "")) {
+        items.push({
+          type: "listItem",
+          content: [
+            {
+              type: "paragraph",
+              content: [textNode((lines[index] ?? "").replace(/^[-*]\s+/, ""))],
+            },
+          ],
+        });
+        index += 1;
+      }
+
+      content.push({
+        type: "bulletList",
+        content: items,
+      });
+      continue;
+    }
+
+    const paragraphLines: string[] = [];
+
+    while (index < lines.length && (lines[index]?.trim().length ?? 0) > 0) {
+      paragraphLines.push(lines[index] ?? "");
+      index += 1;
+    }
+
+    content.push(paragraphNode(paragraphLines));
+  }
+
+  return {
+    type: "doc",
+    version: 1,
+    content,
+  };
+}

skills/atlassian/codex/scripts/src/cli.ts

@@ -0,0 +1,332 @@
+import process from "node:process";
+import { pathToFileURL } from "node:url";
+
+import { Command } from "commander";
+
+import { createConfluenceClient } from "./confluence.js";
+import { loadConfig } from "./config.js";
+import { readWorkspaceFile } from "./files.js";
+import { runHealthCheck } from "./health.js";
+import { createJiraClient } from "./jira.js";
+import { writeOutput } from "./output.js";
+import { runRawCommand } from "./raw.js";
+import type { FetchLike, OutputFormat, Writer } from "./types.js";
+
+type CliContext = {
+  cwd?: string;
+  env?: NodeJS.ProcessEnv;
+  fetchImpl?: FetchLike;
+  stdout?: Writer;
+  stderr?: Writer;
+};
+
+function resolveFormat(format: string | undefined): OutputFormat {
+  return format === "text" ? "text" : "json";
+}
+
+function createRuntime(context: CliContext) {
+  const cwd = context.cwd ?? process.cwd();
+  const env = context.env ?? process.env;
+  const stdout = context.stdout ?? process.stdout;
+  const stderr = context.stderr ?? process.stderr;
+  let configCache: ReturnType<typeof loadConfig> | undefined;
+  let jiraCache: ReturnType<typeof createJiraClient> | undefined;
+  let confluenceCache: ReturnType<typeof createConfluenceClient> | undefined;
+
+  function getConfig() {
+    configCache ??= loadConfig(env, { cwd });
+    return configCache;
+  }
+
+  function getJiraClient() {
+    jiraCache ??= createJiraClient({
+      config: getConfig(),
+      fetchImpl: context.fetchImpl,
+    });
+    return jiraCache;
+  }
+
+  function getConfluenceClient() {
+    confluenceCache ??= createConfluenceClient({
+      config: getConfig(),
+      fetchImpl: context.fetchImpl,
+    });
+    return confluenceCache;
+  }
+
+  async function readBodyFile(filePath: string | undefined) {
+    if (!filePath) {
+      return undefined;
+    }
+
+    return readWorkspaceFile(filePath, cwd);
+  }
+
+  return {
+    cwd,
+    stdout,
+    stderr,
+    readBodyFile,
+    getConfig,
+    getJiraClient,
+    getConfluenceClient,
+    fetchImpl: context.fetchImpl,
+  };
+}
+
+export function buildProgram(context: CliContext = {}) {
+  const runtime = createRuntime(context);
+  const program = new Command()
+    .name("atlassian")
+    .description("Portable Atlassian CLI for multi-agent skills")
+    .version("0.1.0");
+
+  program
+    .command("health")
+    .description("Validate configuration and Atlassian connectivity")
+    .option("--format <format>", "Output format", "json")
+    .action(async (options) => {
+      const payload = await runHealthCheck(runtime.getConfig(), runtime.fetchImpl);
+      writeOutput(
+        runtime.stdout,
+        payload,
+        resolveFormat(options.format),
+      );
+    });
+
+  program
+    .command("conf-search")
+    .requiredOption("--query <query>", "CQL search query")
+    .option("--max-results <number>", "Maximum results to return", "50")
+    .option("--start-at <number>", "Result offset", "0")
+    .option("--format <format>", "Output format", "json")
+    .action(async (options) => {
+      const payload = await runtime.getConfluenceClient().searchPages({
+        query: options.query,
+        maxResults: Number(options.maxResults),
+        startAt: Number(options.startAt),
+      });
+
+      writeOutput(runtime.stdout, payload, resolveFormat(options.format));
+    });
+
+  program
+    .command("conf-get")
+    .requiredOption("--page <page>", "Confluence page ID")
+    .option("--format <format>", "Output format", "json")
+    .action(async (options) => {
+      const payload = await runtime.getConfluenceClient().getPage(options.page);
+      writeOutput(runtime.stdout, payload, resolveFormat(options.format));
+    });
+
+  program
+    .command("conf-create")
+    .requiredOption("--title <title>", "Confluence page title")
+    .requiredOption("--body-file <path>", "Workspace-relative storage-format body file")
+    .option("--space <space>", "Confluence space ID")
+    .option("--dry-run", "Print the request without sending it")
+    .option("--format <format>", "Output format", "json")
+    .action(async (options) => {
+      const payload = await runtime.getConfluenceClient().createPage({
+        space: options.space,
+        title: options.title,
+        body: (await runtime.readBodyFile(options.bodyFile)) as string,
+        dryRun: Boolean(options.dryRun),
+      });
+
+      writeOutput(runtime.stdout, payload, resolveFormat(options.format));
+    });
+
+  program
+    .command("conf-update")
+    .requiredOption("--page <page>", "Confluence page ID")
+    .requiredOption("--title <title>", "Confluence page title")
+    .requiredOption("--body-file <path>", "Workspace-relative storage-format body file")
+    .option("--dry-run", "Print the request without sending it")
+    .option("--format <format>", "Output format", "json")
+    .action(async (options) => {
+      const payload = await runtime.getConfluenceClient().updatePage({
+        pageId: options.page,
+        title: options.title,
+        body: (await runtime.readBodyFile(options.bodyFile)) as string,
+        dryRun: Boolean(options.dryRun),
+      });
+
+      writeOutput(runtime.stdout, payload, resolveFormat(options.format));
+    });
+
+  program
+    .command("conf-comment")
+    .requiredOption("--page <page>", "Confluence page ID")
+    .requiredOption("--body-file <path>", "Workspace-relative storage-format body file")
+    .option("--dry-run", "Print the request without sending it")
+    .option("--format <format>", "Output format", "json")
+    .action(async (options) => {
+      const payload = await runtime.getConfluenceClient().commentPage({
+        pageId: options.page,
+        body: (await runtime.readBodyFile(options.bodyFile)) as string,
+        dryRun: Boolean(options.dryRun),
+      });
+
+      writeOutput(runtime.stdout, payload, resolveFormat(options.format));
+    });
+
+  program
+    .command("conf-children")
+    .requiredOption("--page <page>", "Confluence page ID")
+    .option("--max-results <number>", "Maximum results to return", "50")
+    .option("--start-at <number>", "Cursor/start token", "0")
+    .option("--format <format>", "Output format", "json")
+    .action(async (options) => {
+      const payload = await runtime.getConfluenceClient().listChildren(
+        options.page,
+        Number(options.maxResults),
+        Number(options.startAt),
+      );
+
+      writeOutput(runtime.stdout, payload, resolveFormat(options.format));
+    });
+
+  program
+    .command("raw")
+    .requiredOption("--product <product>", "jira or confluence")
+    .requiredOption("--method <method>", "GET, POST, or PUT")
+    .requiredOption("--path <path>", "Validated API path")
+    .option("--body-file <path>", "Workspace-relative JSON file")
+    .option("--dry-run", "Print the request without sending it")
+    .option("--format <format>", "Output format", "json")
+    .action(async (options) => {
+      const payload = await runRawCommand(runtime.getConfig(), runtime.fetchImpl, {
+        product: options.product,
+        method: String(options.method).toUpperCase(),
+        path: options.path,
+        bodyFile: options.bodyFile,
+        cwd: runtime.cwd,
+        dryRun: Boolean(options.dryRun),
+      });
+
+      writeOutput(runtime.stdout, payload, resolveFormat(options.format));
+    });
+
+  program
+    .command("jira-search")
+    .requiredOption("--jql <jql>", "JQL expression to execute")
+    .option("--max-results <number>", "Maximum results to return", "50")
+    .option("--start-at <number>", "Result offset", "0")
+    .option("--format <format>", "Output format", "json")
+    .action(async (options) => {
+      const payload = await runtime.getJiraClient().searchIssues({
+        jql: options.jql,
+        maxResults: Number(options.maxResults),
+        startAt: Number(options.startAt),
+      });
+
+      writeOutput(runtime.stdout, payload, resolveFormat(options.format));
+    });
+
+  program
+    .command("jira-get")
+    .requiredOption("--issue <issue>", "Issue key")
+    .option("--format <format>", "Output format", "json")
+    .action(async (options) => {
+      const payload = await runtime.getJiraClient().getIssue(options.issue);
+      writeOutput(runtime.stdout, payload, resolveFormat(options.format));
+    });
+
+  program
+    .command("jira-create")
+    .requiredOption("--type <type>", "Issue type name")
+    .requiredOption("--summary <summary>", "Issue summary")
+    .option("--project <project>", "Project key")
+    .option("--description-file <path>", "Workspace-relative markdown/text file")
+    .option("--dry-run", "Print the request without sending it")
+    .option("--format <format>", "Output format", "json")
+    .action(async (options) => {
+      const payload = await runtime.getJiraClient().createIssue({
+        project: options.project,
+        type: options.type,
+        summary: options.summary,
+        description: await runtime.readBodyFile(options.descriptionFile),
+        dryRun: Boolean(options.dryRun),
+      });
+
+      writeOutput(runtime.stdout, payload, resolveFormat(options.format));
+    });
+
+  program
+    .command("jira-update")
+    .requiredOption("--issue <issue>", "Issue key")
+    .option("--summary <summary>", "Updated summary")
+    .option("--description-file <path>", "Workspace-relative markdown/text file")
+    .option("--dry-run", "Print the request without sending it")
+    .option("--format <format>", "Output format", "json")
+    .action(async (options) => {
+      const payload = await runtime.getJiraClient().updateIssue({
+        issue: options.issue,
+        summary: options.summary,
+        description: await runtime.readBodyFile(options.descriptionFile),
+        dryRun: Boolean(options.dryRun),
+      });
+
+      writeOutput(runtime.stdout, payload, resolveFormat(options.format));
+    });
+
+  program
+    .command("jira-comment")
+    .requiredOption("--issue <issue>", "Issue key")
+    .requiredOption("--body-file <path>", "Workspace-relative markdown/text file")
+    .option("--dry-run", "Print the request without sending it")
+    .option("--format <format>", "Output format", "json")
+    .action(async (options) => {
+      const payload = await runtime.getJiraClient().commentIssue({
+        issue: options.issue,
+        body: (await runtime.readBodyFile(options.bodyFile)) as string,
+        dryRun: Boolean(options.dryRun),
+      });
+
+      writeOutput(runtime.stdout, payload, resolveFormat(options.format));
+    });
+
+  program
+    .command("jira-transitions")
+    .requiredOption("--issue <issue>", "Issue key")
+    .option("--format <format>", "Output format", "json")
+    .action(async (options) => {
+      const payload = await runtime.getJiraClient().getTransitions(options.issue);
+      writeOutput(runtime.stdout, payload, resolveFormat(options.format));
+    });
+
+  program
+    .command("jira-transition")
+    .requiredOption("--issue <issue>", "Issue key")
+    .requiredOption("--transition <transition>", "Transition ID")
+    .option("--dry-run", "Print the request without sending it")
+    .option("--format <format>", "Output format", "json")
+    .action(async (options) => {
+      const payload = await runtime.getJiraClient().transitionIssue({
+        issue: options.issue,
+        transition: options.transition,
+        dryRun: Boolean(options.dryRun),
+      });
+
+      writeOutput(runtime.stdout, payload, resolveFormat(options.format));
+    });
+
+  return program;
+}
+
+export async function runCli(argv = process.argv, context: CliContext = {}) {
+  const program = buildProgram(context);
+  await program.parseAsync(argv);
+}
+
+const isDirectExecution =
+  Boolean(process.argv[1]) && import.meta.url === pathToFileURL(process.argv[1]).href;
+
+if (isDirectExecution) {
+  runCli().catch((error: unknown) => {
+    const message = error instanceof Error ? error.message : String(error);
+    process.stderr.write(`${message}\n`);
+    process.exitCode = 1;
+  });
+}

skills/atlassian/codex/scripts/src/config.ts

@@ -0,0 +1,52 @@
+import path from "node:path";
+
+import { config as loadDotEnv } from "dotenv";
+
+import type { AtlassianConfig } from "./types.js";
+
+function normalizeBaseUrl(value: string) {
+  return value.replace(/\/+$/, "");
+}
+
+function readRequired(env: NodeJS.ProcessEnv, key: string) {
+  const value = env[key]?.trim();
+
+  if (!value) {
+    throw new Error(`Missing required environment variable: ${key}`);
+  }
+
+  return value;
+}
+
+export function loadConfig(
+  env: NodeJS.ProcessEnv = process.env,
+  options?: {
+    cwd?: string;
+  },
+): AtlassianConfig {
+  loadDotEnv({
+    path: path.resolve(options?.cwd ?? process.cwd(), ".env"),
+    processEnv: env as Record<string, string>,
+    override: false,
+  });
+
+  const baseUrl = normalizeBaseUrl(readRequired(env, "ATLASSIAN_BASE_URL"));
+
+  return {
+    baseUrl,
+    jiraBaseUrl: normalizeBaseUrl(env.ATLASSIAN_JIRA_BASE_URL?.trim() || baseUrl),
+    confluenceBaseUrl: normalizeBaseUrl(env.ATLASSIAN_CONFLUENCE_BASE_URL?.trim() || baseUrl),
+    email: readRequired(env, "ATLASSIAN_EMAIL"),
+    apiToken: readRequired(env, "ATLASSIAN_API_TOKEN"),
+    defaultProject: env.ATLASSIAN_DEFAULT_PROJECT?.trim() || undefined,
+    defaultSpace: env.ATLASSIAN_DEFAULT_SPACE?.trim() || undefined,
+  };
+}
+
+export function createBasicAuthHeader(config: {
+  email: string;
+  apiToken: string;
+  [key: string]: unknown;
+}) {
+  return `Basic ${Buffer.from(`${config.email}:${config.apiToken}`).toString("base64")}`;
+}

skills/atlassian/codex/scripts/src/confluence.ts

@@ -0,0 +1,292 @@
+import { sendJsonRequest } from "./http.js";
+import type { AtlassianConfig, CommandOutput, FetchLike } from "./types.js";
+
+type ConfluenceClientOptions = {
+  config: AtlassianConfig;
+  fetchImpl?: FetchLike;
+};
+
+type SearchInput = {
+  query: string;
+  maxResults: number;
+  startAt: number;
+};
+
+type CreateInput = {
+  space?: string;
+  title: string;
+  body: string;
+  dryRun?: boolean;
+};
+
+type UpdateInput = {
+  pageId: string;
+  title: string;
+  body: string;
+  dryRun?: boolean;
+};
+
+type CommentInput = {
+  pageId: string;
+  body: string;
+  dryRun?: boolean;
+};
+
+type PageSummary = {
+  id: string;
+  title: string;
+  type: string;
+  status?: string;
+  spaceId?: string;
+  url?: string;
+};
+
+function buildUrl(baseUrl: string, path: string) {
+  return new URL(path, `${baseUrl}/`).toString();
+}
+
+function normalizePage(baseUrl: string, page: Record<string, unknown>, excerpt?: string) {
+  const links = (page._links ?? {}) as Record<string, unknown>;
+
+  return {
+    id: String(page.id ?? ""),
+    title: String(page.title ?? ""),
+    type: String(page.type ?? "page"),
+    ...(page.status ? { status: String(page.status) } : {}),
+    ...(page.spaceId ? { spaceId: String(page.spaceId) } : {}),
+    ...(excerpt ? { excerpt } : {}),
+    ...(links.webui ? { url: `${baseUrl}${String(links.webui)}` } : {}),
+  };
+}
+
+export function createConfluenceClient(options: ConfluenceClientOptions) {
+  const config = options.config;
+
+  async function getPageForUpdate(pageId: string) {
+    return (await sendJsonRequest({
+      config,
+      fetchImpl: options.fetchImpl,
+      url: buildUrl(config.confluenceBaseUrl, `/wiki/api/v2/pages/${pageId}?body-format=storage`),
+      method: "GET",
+      errorPrefix: "Confluence request failed",
+    })) as Record<string, unknown>;
+  }
+
+  return {
+    async searchPages(input: SearchInput): Promise<CommandOutput<unknown>> {
+      const url = new URL("/wiki/rest/api/search", `${config.confluenceBaseUrl}/`);
+      url.searchParams.set("cql", input.query);
+      url.searchParams.set("limit", String(input.maxResults));
+      url.searchParams.set("start", String(input.startAt));
+
+      const raw = (await sendJsonRequest({
+        config,
+        fetchImpl: options.fetchImpl,
+        url: url.toString(),
+        method: "GET",
+        errorPrefix: "Confluence request failed",
+      })) as Record<string, unknown>;
+
+      const results = Array.isArray(raw.results) ? raw.results : [];
+
+      return {
+        ok: true,
+        data: {
+          pages: results.map((entry) => {
+            const result = entry as Record<string, unknown>;
+            return normalizePage(
+              config.baseUrl,
+              (result.content ?? {}) as Record<string, unknown>,
+              result.excerpt ? String(result.excerpt) : undefined,
+            );
+          }),
+          startAt: Number(raw.start ?? input.startAt),
+          maxResults: Number(raw.limit ?? input.maxResults),
+          total: Number(raw.totalSize ?? raw.size ?? results.length),
+        },
+      };
+    },
+
+    async getPage(pageId: string): Promise<CommandOutput<unknown>> {
+      const raw = (await sendJsonRequest({
+        config,
+        fetchImpl: options.fetchImpl,
+        url: buildUrl(config.confluenceBaseUrl, `/wiki/api/v2/pages/${pageId}?body-format=storage`),
+        method: "GET",
+        errorPrefix: "Confluence request failed",
+      })) as Record<string, unknown>;
+
+      const body = ((raw.body ?? {}) as Record<string, unknown>).storage as Record<string, unknown> | undefined;
+
+      return {
+        ok: true,
+        data: {
+          page: {
+            ...normalizePage(config.baseUrl, raw),
+            version: Number((((raw.version ?? {}) as Record<string, unknown>).number ?? 0)),
+            body: body?.value ? String(body.value) : "",
+          },
+        },
+        raw,
+      };
+    },
+
+    async listChildren(pageId: string, maxResults: number, startAt: number): Promise<CommandOutput<unknown>> {
+      const url = new URL(`/wiki/api/v2/pages/${pageId}/direct-children`, `${config.confluenceBaseUrl}/`);
+      url.searchParams.set("limit", String(maxResults));
+      url.searchParams.set("cursor", String(startAt));
+
+      const raw = (await sendJsonRequest({
+        config,
+        fetchImpl: options.fetchImpl,
+        url: url.toString(),
+        method: "GET",
+        errorPrefix: "Confluence request failed",
+      })) as Record<string, unknown>;
+
+      const results = Array.isArray(raw.results) ? raw.results : [];
+      const links = (raw._links ?? {}) as Record<string, unknown>;
+
+      return {
+        ok: true,
+        data: {
+          pages: results.map((page) => normalizePage(config.baseUrl, page as Record<string, unknown>)),
+          nextCursor: links.next ? String(links.next) : null,
+        },
+      };
+    },
+
+    async createPage(input: CreateInput): Promise<CommandOutput<unknown>> {
+      const spaceId = input.space || config.defaultSpace;
+
+      if (!spaceId) {
+        throw new Error("conf-create requires --space or ATLASSIAN_DEFAULT_SPACE");
+      }
+
+      const request = {
+        method: "POST" as const,
+        url: buildUrl(config.confluenceBaseUrl, "/wiki/api/v2/pages"),
+        body: {
+          spaceId,
+          title: input.title,
+          status: "current",
+          body: {
+            representation: "storage",
+            value: input.body,
+          },
+        },
+      };
+
+      if (input.dryRun) {
+        return {
+          ok: true,
+          dryRun: true,
+          data: request,
+        };
+      }
+
+      const raw = await sendJsonRequest({
+        config,
+        fetchImpl: options.fetchImpl,
+        url: request.url,
+        method: request.method,
+        body: request.body,
+        errorPrefix: "Confluence request failed",
+      });
+
+      return {
+        ok: true,
+        data: raw,
+      };
+    },
+
+    async updatePage(input: UpdateInput): Promise<CommandOutput<unknown>> {
+      const currentPage = await getPageForUpdate(input.pageId);
+      const version = (((currentPage.version ?? {}) as Record<string, unknown>).number ?? 0) as number;
+      const spaceId = String(currentPage.spaceId ?? "");
+
+      const request = {
+        method: "PUT" as const,
+        url: buildUrl(config.confluenceBaseUrl, `/wiki/api/v2/pages/${input.pageId}`),
+        body: {
+          id: input.pageId,
+          status: String(currentPage.status ?? "current"),
+          title: input.title,
+          spaceId,
+          version: {
+            number: Number(version) + 1,
+          },
+          body: {
+            representation: "storage",
+            value: input.body,
+          },
+        },
+      };
+
+      if (input.dryRun) {
+        return {
+          ok: true,
+          dryRun: true,
+          data: request,
+        };
+      }
+
+      const raw = await sendJsonRequest({
+        config,
+        fetchImpl: options.fetchImpl,
+        url: request.url,
+        method: request.method,
+        body: request.body,
+        errorPrefix: "Confluence request failed",
+        handleResponseError(response) {
+          if (response.status === 409) {
+            return new Error(`Confluence update conflict: page ${input.pageId} was updated by someone else`);
+          }
+
+          return undefined;
+        },
+      });
+
+      return {
+        ok: true,
+        data: raw,
+      };
+    },
+
+    async commentPage(input: CommentInput): Promise<CommandOutput<unknown>> {
+      const request = {
+        method: "POST" as const,
+        url: buildUrl(config.confluenceBaseUrl, "/wiki/api/v2/footer-comments"),
+        body: {
+          pageId: input.pageId,
+          body: {
+            representation: "storage",
+            value: input.body,
+          },
+        },
+      };
+
+      if (input.dryRun) {
+        return {
+          ok: true,
+          dryRun: true,
+          data: request,
+        };
+      }
+
+      const raw = await sendJsonRequest({
+        config,
+        fetchImpl: options.fetchImpl,
+        url: request.url,
+        method: request.method,
+        body: request.body,
+        errorPrefix: "Confluence request failed",
+      });
+
+      return {
+        ok: true,
+        data: raw,
+      };
+    },
+  };
+}

skills/atlassian/codex/scripts/src/files.ts

@@ -0,0 +1,13 @@
+import { readFile } from "node:fs/promises";
+import path from "node:path";
+
+export async function readWorkspaceFile(filePath: string, cwd: string) {
+  const resolved = path.resolve(cwd, filePath);
+  const relative = path.relative(cwd, resolved);
+
+  if (relative.startsWith("..") || path.isAbsolute(relative)) {
+    throw new Error(`--body-file must stay within the active workspace: ${filePath}`);
+  }
+
+  return readFile(resolved, "utf8");
+}

skills/atlassian/codex/scripts/src/health.ts

@@ -0,0 +1,69 @@
+import { createJsonHeaders, createStatusError } from "./http.js";
+import type { AtlassianConfig, CommandOutput, FetchLike } from "./types.js";
+
+type ProductHealth = {
+  ok: boolean;
+  status?: number;
+  message?: string;
+};
+
+function buildUrl(baseUrl: string, path: string) {
+  return new URL(path, `${baseUrl}/`).toString();
+}
+
+export async function runHealthCheck(
+  config: AtlassianConfig,
+  fetchImpl: FetchLike | undefined,
+): Promise<CommandOutput<unknown>> {
+  const client = fetchImpl ?? globalThis.fetch;
+
+  if (!client) {
+    throw new Error("Fetch API is not available in this runtime");
+  }
+
+  async function probe(product: "Jira" | "Confluence", url: string): Promise<ProductHealth> {
+    try {
+      const response = await client(url, {
+        method: "GET",
+        headers: createJsonHeaders(config, false),
+      });
+
+      if (!response.ok) {
+        const error = createStatusError(`${product} health check failed`, response);
+        return {
+          ok: false,
+          status: response.status,
+          message: error.message,
+        };
+      }
+
+      return {
+        ok: true,
+        status: response.status,
+      };
+    } catch (error: unknown) {
+      return {
+        ok: false,
+        message: error instanceof Error ? error.message : String(error),
+      };
+    }
+  }
+
+  const jira = await probe("Jira", buildUrl(config.jiraBaseUrl, "/rest/api/3/myself"));
+  const confluence = await probe("Confluence", buildUrl(config.confluenceBaseUrl, "/wiki/api/v2/spaces?limit=1"));
+
+  return {
+    ok: jira.ok && confluence.ok,
+    data: {
+      baseUrl: config.baseUrl,
+      jiraBaseUrl: config.jiraBaseUrl,
+      confluenceBaseUrl: config.confluenceBaseUrl,
+      defaultProject: config.defaultProject,
+      defaultSpace: config.defaultSpace,
+      products: {
+        jira,
+        confluence,
+      },
+    },
+  };
+}

skills/atlassian/codex/scripts/src/http.ts

@@ -0,0 +1,86 @@
+import { createBasicAuthHeader } from "./config.js";
+import type { AtlassianConfig, FetchLike } from "./types.js";
+
+export type HttpMethod = "GET" | "POST" | "PUT";
+
+export function createJsonHeaders(config: AtlassianConfig, includeJsonBody: boolean) {
+  const headers: Array<[string, string]> = [
+    ["Accept", "application/json"],
+    ["Authorization", createBasicAuthHeader(config)],
+  ];
+
+  if (includeJsonBody) {
+    headers.push(["Content-Type", "application/json"]);
+  }
+
+  return headers;
+}
+
+export async function parseResponse(response: Response) {
+  if (response.status === 204) {
+    return null;
+  }
+
+  const contentType = response.headers.get("content-type") ?? "";
+
+  if (contentType.includes("application/json")) {
+    try {
+      return await response.json();
+    } catch {
+      throw new Error("Malformed JSON response from Atlassian API");
+    }
+  }
+
+  return response.text();
+}
+
+export function createStatusError(errorPrefix: string, response: Response) {
+  const base = `${errorPrefix}: ${response.status} ${response.statusText}`;
+
+  switch (response.status) {
+    case 401:
+      return new Error(`${base} - check ATLASSIAN_EMAIL and ATLASSIAN_API_TOKEN`);
+    case 403:
+      return new Error(`${base} - verify product permissions for this account`);
+    case 404:
+      return new Error(`${base} - verify the resource identifier or API path`);
+    case 429:
+      return new Error(`${base} - retry later or reduce request rate`);
+    default:
+      return new Error(base);
+  }
+}
+
+export async function sendJsonRequest(options: {
+  config: AtlassianConfig;
+  fetchImpl?: FetchLike;
+  url: string;
+  method: HttpMethod;
+  body?: unknown;
+  errorPrefix: string;
+  handleResponseError?: (response: Response) => Error | undefined;
+}) {
+  const fetchImpl = options.fetchImpl ?? globalThis.fetch;
+
+  if (!fetchImpl) {
+    throw new Error("Fetch API is not available in this runtime");
+  }
+
+  const response = await fetchImpl(options.url, {
+    method: options.method,
+    headers: createJsonHeaders(options.config, options.body !== undefined),
+    ...(options.body === undefined ? {} : { body: JSON.stringify(options.body) }),
+  });
+
+  if (!response.ok) {
+    const customError = options.handleResponseError?.(response);
+
+    if (customError) {
+      throw customError;
+    }
+
+    throw createStatusError(options.errorPrefix, response);
+  }
+
+  return parseResponse(response);
+}

skills/atlassian/codex/scripts/src/jira.ts

@@ -0,0 +1,264 @@
+import { markdownToAdf } from "./adf.js";
+import { sendJsonRequest } from "./http.js";
+import type { AtlassianConfig, CommandOutput, FetchLike, JiraIssueSummary } from "./types.js";
+
+const ISSUE_FIELDS = ["summary", "issuetype", "status", "assignee", "created", "updated"] as const;
+
+type JiraClientOptions = {
+  config: AtlassianConfig;
+  fetchImpl?: FetchLike;
+};
+
+type SearchInput = {
+  jql: string;
+  maxResults: number;
+  startAt: number;
+};
+
+type CreateInput = {
+  project?: string;
+  type: string;
+  summary: string;
+  description?: string;
+  dryRun?: boolean;
+};
+
+type UpdateInput = {
+  issue: string;
+  summary?: string;
+  description?: string;
+  dryRun?: boolean;
+};
+
+type CommentInput = {
+  issue: string;
+  body: string;
+  dryRun?: boolean;
+};
+
+type TransitionInput = {
+  issue: string;
+  transition: string;
+  dryRun?: boolean;
+};
+
+function normalizeIssue(config: AtlassianConfig, issue: Record<string, unknown>): JiraIssueSummary {
+  const fields = (issue.fields ?? {}) as Record<string, unknown>;
+  const issueType = (fields.issuetype ?? {}) as Record<string, unknown>;
+  const status = (fields.status ?? {}) as Record<string, unknown>;
+  const assignee = (fields.assignee ?? {}) as Record<string, unknown>;
+
+  return {
+    key: String(issue.key ?? ""),
+    summary: String(fields.summary ?? ""),
+    issueType: String(issueType.name ?? ""),
+    status: String(status.name ?? ""),
+    assignee: assignee.displayName ? String(assignee.displayName) : undefined,
+    created: String(fields.created ?? ""),
+    updated: String(fields.updated ?? ""),
+    url: `${config.baseUrl}/browse/${issue.key ?? ""}`,
+  };
+}
+
+function createRequest(config: AtlassianConfig, method: "GET" | "POST" | "PUT", path: string, body?: unknown) {
+  const url = new URL(path, `${config.jiraBaseUrl}/`);
+
+  return {
+    method,
+    url: url.toString(),
+    ...(body === undefined ? {} : { body }),
+  };
+}
+
+export function createJiraClient(options: JiraClientOptions) {
+  const fetchImpl = options.fetchImpl ?? globalThis.fetch;
+
+  if (!fetchImpl) {
+    throw new Error("Fetch API is not available in this runtime");
+  }
+
+  async function send(method: "GET" | "POST" | "PUT", path: string, body?: unknown) {
+    const request = createRequest(options.config, method, path, body);
+    return sendJsonRequest({
+      config: options.config,
+      fetchImpl,
+      url: request.url,
+      method,
+      body,
+      errorPrefix: "Jira request failed",
+    });
+  }
+
+  return {
+    async searchIssues(input: SearchInput): Promise<CommandOutput<unknown>> {
+      const raw = (await send("POST", "/rest/api/3/search", {
+        jql: input.jql,
+        maxResults: input.maxResults,
+        startAt: input.startAt,
+        fields: [...ISSUE_FIELDS],
+      })) as Record<string, unknown>;
+
+      const issues = Array.isArray(raw.issues) ? raw.issues : [];
+
+      return {
+        ok: true,
+        data: {
+          issues: issues.map((issue) => normalizeIssue(options.config, issue as Record<string, unknown>)),
+          startAt: Number(raw.startAt ?? input.startAt),
+          maxResults: Number(raw.maxResults ?? input.maxResults),
+          total: Number(raw.total ?? issues.length),
+        },
+      };
+    },
+
+    async getIssue(issue: string): Promise<CommandOutput<unknown>> {
+      const url = new URL(`/rest/api/3/issue/${issue}`, `${options.config.jiraBaseUrl}/`);
+      url.searchParams.set("fields", ISSUE_FIELDS.join(","));
+
+      const raw = (await send("GET", `${url.pathname}${url.search}`)) as Record<string, unknown>;
+
+      return {
+        ok: true,
+        data: {
+          issue: normalizeIssue(options.config, raw),
+        },
+        raw,
+      };
+    },
+
+    async getTransitions(issue: string): Promise<CommandOutput<unknown>> {
+      const raw = (await send(
+        "GET",
+        `/rest/api/3/issue/${issue}/transitions`,
+      )) as { transitions?: Array<Record<string, unknown>> };
+
+      return {
+        ok: true,
+        data: {
+          transitions: (raw.transitions ?? []).map((transition) => ({
+            id: String(transition.id ?? ""),
+            name: String(transition.name ?? ""),
+            toStatus: String(((transition.to ?? {}) as Record<string, unknown>).name ?? ""),
+            hasScreen: Boolean(transition.hasScreen),
+          })),
+        },
+      };
+    },
+
+    async createIssue(input: CreateInput): Promise<CommandOutput<unknown>> {
+      const project = input.project || options.config.defaultProject;
+
+      if (!project) {
+        throw new Error("jira-create requires --project or ATLASSIAN_DEFAULT_PROJECT");
+      }
+
+      const request = createRequest(options.config, "POST", "/rest/api/3/issue", {
+        fields: {
+          project: { key: project },
+          issuetype: { name: input.type },
+          summary: input.summary,
+          ...(input.description ? { description: markdownToAdf(input.description) } : {}),
+        },
+      });
+
+      if (input.dryRun) {
+        return {
+          ok: true,
+          dryRun: true,
+          data: request,
+        };
+      }
+
+      const raw = await send("POST", "/rest/api/3/issue", request.body);
+      return { ok: true, data: raw };
+    },
+
+    async updateIssue(input: UpdateInput): Promise<CommandOutput<unknown>> {
+      const fields: Record<string, unknown> = {};
+
+      if (input.summary) {
+        fields.summary = input.summary;
+      }
+
+      if (input.description) {
+        fields.description = markdownToAdf(input.description);
+      }
+
+      if (Object.keys(fields).length === 0) {
+        throw new Error("jira-update requires --summary and/or --description-file");
+      }
+
+      const request = createRequest(options.config, "PUT", `/rest/api/3/issue/${input.issue}`, {
+        fields,
+      });
+
+      if (input.dryRun) {
+        return {
+          ok: true,
+          dryRun: true,
+          data: request,
+        };
+      }
+
+      await send("PUT", `/rest/api/3/issue/${input.issue}`, request.body);
+      return {
+        ok: true,
+        data: {
+          issue: input.issue,
+          updated: true,
+        },
+      };
+    },
+
+    async commentIssue(input: CommentInput): Promise<CommandOutput<unknown>> {
+      const request = createRequest(options.config, "POST", `/rest/api/3/issue/${input.issue}/comment`, {
+        body: markdownToAdf(input.body),
+      });
+
+      if (input.dryRun) {
+        return {
+          ok: true,
+          dryRun: true,
+          data: request,
+        };
+      }
+
+      const raw = await send("POST", `/rest/api/3/issue/${input.issue}/comment`, request.body);
+      return {
+        ok: true,
+        data: raw,
+      };
+    },
+
+    async transitionIssue(input: TransitionInput): Promise<CommandOutput<unknown>> {
+      const request = createRequest(
+        options.config,
+        "POST",
+        `/rest/api/3/issue/${input.issue}/transitions`,
+        {
+          transition: {
+            id: input.transition,
+          },
+        },
+      );
+
+      if (input.dryRun) {
+        return {
+          ok: true,
+          dryRun: true,
+          data: request,
+        };
+      }
+
+      await send("POST", `/rest/api/3/issue/${input.issue}/transitions`, request.body);
+      return {
+        ok: true,
+        data: {
+          issue: input.issue,
+          transitioned: true,
+          transition: input.transition,
+        },
+      };
+    },
+  };
+}

skills/atlassian/codex/scripts/src/output.ts

@@ -0,0 +1,44 @@
+import type { CommandOutput, OutputFormat, Writer } from "./types.js";
+
+function renderText(payload: CommandOutput<unknown>) {
+  const data = payload.data as Record<string, unknown>;
+
+  if (Array.isArray(data?.issues)) {
+    return data.issues
+      .map((issue) => {
+        const item = issue as Record<string, string>;
+        return `${item.key} [${item.status}] ${item.issueType} - ${item.summary}`;
+      })
+      .join("\n");
+  }
+
+  if (data?.issue && typeof data.issue === "object") {
+    const issue = data.issue as Record<string, string>;
+    return [
+      issue.key,
+      `${issue.issueType} | ${issue.status}`,
+      issue.summary,
+      issue.url,
+    ].join("\n");
+  }
+
+  if (Array.isArray(data?.transitions)) {
+    return data.transitions
+      .map((transition) => {
+        const item = transition as Record<string, string>;
+        return `${item.id} ${item.name} -> ${item.toStatus}`;
+      })
+      .join("\n");
+  }
+
+  return JSON.stringify(payload, null, 2);
+}
+
+export function writeOutput(
+  writer: Writer,
+  payload: CommandOutput<unknown>,
+  format: OutputFormat = "json",
+) {
+  const body = format === "text" ? renderText(payload) : JSON.stringify(payload, null, 2);
+  writer.write(`${body}\n`);
+}

skills/atlassian/codex/scripts/src/raw.ts

@@ -0,0 +1,85 @@
+import { readWorkspaceFile } from "./files.js";
+import { sendJsonRequest } from "./http.js";
+import type { AtlassianConfig, CommandOutput, FetchLike } from "./types.js";
+
+const JIRA_ALLOWED_PREFIXES = ["/rest/api/3/"] as const;
+const CONFLUENCE_ALLOWED_PREFIXES = ["/wiki/api/v2/", "/wiki/rest/api/"] as const;
+
+type RawInput = {
+  product: "jira" | "confluence";
+  method: string;
+  path: string;
+  bodyFile?: string;
+  cwd: string;
+  dryRun?: boolean;
+};
+
+function getAllowedPrefixes(product: RawInput["product"]) {
+  return product === "jira" ? JIRA_ALLOWED_PREFIXES : CONFLUENCE_ALLOWED_PREFIXES;
+}
+
+function buildUrl(config: AtlassianConfig, product: RawInput["product"], path: string) {
+  const baseUrl = product === "jira" ? config.jiraBaseUrl : config.confluenceBaseUrl;
+  return new URL(path, `${baseUrl}/`).toString();
+}
+
+function validateMethod(method: string): asserts method is "GET" | "POST" | "PUT" {
+  if (!["GET", "POST", "PUT"].includes(method)) {
+    throw new Error("raw only allows GET, POST, and PUT");
+  }
+}
+
+function validatePath(product: RawInput["product"], path: string) {
+  const allowedPrefixes = getAllowedPrefixes(product);
+
+  if (!allowedPrefixes.some((prefix) => path.startsWith(prefix))) {
+    throw new Error(`raw path is not allowed for ${product}: ${path}`);
+  }
+}
+
+async function readRawBody(bodyFile: string | undefined, cwd: string) {
+  if (!bodyFile) {
+    return undefined;
+  }
+
+  const contents = await readWorkspaceFile(bodyFile, cwd);
+  return JSON.parse(contents) as unknown;
+}
+
+export async function runRawCommand(
+  config: AtlassianConfig,
+  fetchImpl: FetchLike | undefined,
+  input: RawInput,
+): Promise<CommandOutput<unknown>> {
+  validateMethod(input.method);
+  validatePath(input.product, input.path);
+
+  const body = await readRawBody(input.bodyFile, input.cwd);
+  const request = {
+    method: input.method,
+    url: buildUrl(config, input.product, input.path),
+    ...(body === undefined ? {} : { body }),
+  };
+
+  if (input.dryRun) {
+    return {
+      ok: true,
+      dryRun: true,
+      data: request,
+    };
+  }
+
+  const data = await sendJsonRequest({
+    config,
+    fetchImpl,
+    url: request.url,
+    method: input.method,
+    body,
+    errorPrefix: "Raw request failed",
+  });
+
+  return {
+    ok: true,
+    data,
+  };
+}

skills/atlassian/codex/scripts/src/types.ts

@@ -0,0 +1,35 @@
+export type AtlassianConfig = {
+  baseUrl: string;
+  jiraBaseUrl: string;
+  confluenceBaseUrl: string;
+  email: string;
+  apiToken: string;
+  defaultProject?: string;
+  defaultSpace?: string;
+};
+
+export type CommandOutput<T> = {
+  ok: boolean;
+  data: T;
+  dryRun?: boolean;
+  raw?: unknown;
+};
+
+export type JiraIssueSummary = {
+  key: string;
+  summary: string;
+  issueType: string;
+  status: string;
+  assignee?: string;
+  created: string;
+  updated: string;
+  url: string;
+};
+
+export type Writer = {
+  write(chunk: string | Uint8Array): unknown;
+};
+
+export type FetchLike = typeof fetch;
+
+export type OutputFormat = "json" | "text";

skills/atlassian/codex/scripts/tsconfig.json

@@ -0,0 +1,15 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "esModuleInterop": true,
+    "forceConsistentCasingInFileNames": true,
+    "strict": true,
+    "skipLibCheck": true,
+    "resolveJsonModule": true,
+    "types": ["node"],
+    "outDir": "dist"
+  },
+  "include": ["src/**/*.ts", "scripts/**/*.ts", "tests/**/*.ts"]
+}

skills/atlassian/cursor/SKILL.md

@@ -0,0 +1,93 @@
+---
+name: atlassian
+description: Interact with Atlassian Cloud Jira and Confluence through a portable task-oriented CLI for search, issue/page edits, comments, transitions, and bounded raw requests.
+---
+
+# Atlassian (Cursor Agent CLI)
+
+Portable Atlassian workflows for Cursor Agent CLI using a shared TypeScript CLI.
+
+## Requirements
+
+- Cursor Agent CLI skill discovery via `.cursor/skills/` or `~/.cursor/skills/`
+- Node.js 20+
+- `pnpm`
+- Atlassian Cloud account access
+- `ATLASSIAN_BASE_URL`
+- `ATLASSIAN_EMAIL`
+- `ATLASSIAN_API_TOKEN`
+
+The `ATLASSIAN_*` values may come from the shell environment or a `.env` file in the installed `scripts/` folder.
+
+## First-Time Setup
+
+Repo-local install:
+
+```bash
+mkdir -p .cursor/skills/atlassian
+cp -R skills/atlassian/cursor/* .cursor/skills/atlassian/
+cd .cursor/skills/atlassian/scripts
+pnpm install
+```
+
+Global install:
+
+```bash
+mkdir -p ~/.cursor/skills/atlassian
+cp -R skills/atlassian/cursor/* ~/.cursor/skills/atlassian/
+cd ~/.cursor/skills/atlassian/scripts
+pnpm install
+```
+
+## Prerequisite Check (MANDATORY)
+
+Repo-local form:
+
+```bash
+cursor-agent --version
+cd .cursor/skills/atlassian/scripts
+node -e "require.resolve('commander');require.resolve('dotenv');console.log('OK: runtime dependencies installed')"
+node -e 'require("dotenv").config({ path: ".env" }); const required = ["ATLASSIAN_BASE_URL", "ATLASSIAN_EMAIL", "ATLASSIAN_API_TOKEN"]; const missing = required.filter((key) => !(process.env[key] || "").trim()); if (missing.length) { console.error("Missing required Atlassian config: " + missing.join(", ")); process.exit(1); } console.log("OK: Atlassian config present")'
+pnpm atlassian health
+```
+
+If any check fails, stop and return:
+
+`Missing dependency/config: atlassian requires installed CLI dependencies and valid Atlassian Cloud credentials. Configure ATLASSIAN_* in the shell environment or scripts/.env, then retry.`
+
+## Supported Commands
+
+- `pnpm atlassian health`
+- `pnpm atlassian jira-search --jql "..."`
+- `pnpm atlassian jira-get --issue ABC-123`
+- `pnpm atlassian jira-create ... [--dry-run]`
+- `pnpm atlassian jira-update ... [--dry-run]`
+- `pnpm atlassian jira-comment ... [--dry-run]`
+- `pnpm atlassian jira-transitions --issue ABC-123`
+- `pnpm atlassian jira-transition ... [--dry-run]`
+- `pnpm atlassian conf-search --query "..."`
+- `pnpm atlassian conf-get --page 12345`
+- `pnpm atlassian conf-create ... [--dry-run]`
+- `pnpm atlassian conf-update ... [--dry-run]`
+- `pnpm atlassian conf-comment ... [--dry-run]`
+- `pnpm atlassian conf-children --page 12345`
+- `pnpm atlassian raw --product jira|confluence --method GET|POST|PUT --path ...`
+
+## Usage Examples
+
+- `pnpm atlassian jira-get --issue ENG-123`
+- `pnpm atlassian conf-search --query "title ~ \\\"Runbook\\\"" --max-results 10 --start-at 0`
+- `pnpm atlassian raw --product confluence --method POST --path "/wiki/api/v2/pages" --body-file page.json --dry-run`
+
+## Safety Rules
+
+- Prefer JSON output for agent use.
+- Use `--dry-run` before writes unless the user explicitly wants the change applied.
+- Keep `--body-file` inputs within the current workspace.
+- Use `raw` only for user-requested unsupported endpoints.
+- `raw` does not allow `DELETE`.
+
+## Notes
+
+- Cursor discovers this skill from `.cursor/skills/` or `~/.cursor/skills/`.
+- Atlassian Cloud is the supported platform in v1.

skills/atlassian/cursor/scripts/package.json

@@ -0,0 +1,20 @@
+{
+  "name": "atlassian-skill-scripts",
+  "version": "1.0.0",
+  "description": "Shared runtime for the Atlassian skill",
+  "type": "module",
+  "scripts": {
+    "atlassian": "tsx src/cli.ts",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "commander": "^13.1.0",
+    "dotenv": "^16.4.7"
+  },
+  "devDependencies": {
+    "@types/node": "^24.3.0",
+    "tsx": "^4.20.5",
+    "typescript": "^5.9.2"
+  },
+  "packageManager": "pnpm@10.18.1+sha512.77a884a165cbba2d8d1c19e3b4880eee6d2fcabd0d879121e282196b80042351d5eb3ca0935fa599da1dc51265cc68816ad2bddd2a2de5ea9fdf92adbec7cd34"
+}

skills/atlassian/cursor/scripts/pnpm-lock.yaml

@@ -0,0 +1,361 @@
+lockfileVersion: '9.0'
+
+settings:
+  autoInstallPeers: true
+  excludeLinksFromLockfile: false
+
+importers:
+
+  .:
+    dependencies:
+      commander:
+        specifier: ^13.1.0
+        version: 13.1.0
+      dotenv:
+        specifier: ^16.4.7
+        version: 16.6.1
+    devDependencies:
+      '@types/node':
+        specifier: ^24.3.0
+        version: 24.12.0
+      tsx:
+        specifier: ^4.20.5
+        version: 4.21.0
+      typescript:
+        specifier: ^5.9.2
+        version: 5.9.3
+
+packages:
+
+  '@esbuild/aix-ppc64@0.27.3':
+    resolution: {integrity: sha512-9fJMTNFTWZMh5qwrBItuziu834eOCUcEqymSH7pY+zoMVEZg3gcPuBNxH1EvfVYe9h0x/Ptw8KBzv7qxb7l8dg==}
+    engines: {node: '>=18'}
+    cpu: [ppc64]
+    os: [aix]
+
+  '@esbuild/android-arm64@0.27.3':
+    resolution: {integrity: sha512-YdghPYUmj/FX2SYKJ0OZxf+iaKgMsKHVPF1MAq/P8WirnSpCStzKJFjOjzsW0QQ7oIAiccHdcqjbHmJxRb/dmg==}
+    engines: {node: '>=18'}
+    cpu: [arm64]
+    os: [android]
+
+  '@esbuild/android-arm@0.27.3':
+    resolution: {integrity: sha512-i5D1hPY7GIQmXlXhs2w8AWHhenb00+GxjxRncS2ZM7YNVGNfaMxgzSGuO8o8SJzRc/oZwU2bcScvVERk03QhzA==}
+    engines: {node: '>=18'}
+    cpu: [arm]
+    os: [android]
+
+  '@esbuild/android-x64@0.27.3':
+    resolution: {integrity: sha512-IN/0BNTkHtk8lkOM8JWAYFg4ORxBkZQf9zXiEOfERX/CzxW3Vg1ewAhU7QSWQpVIzTW+b8Xy+lGzdYXV6UZObQ==}
+    engines: {node: '>=18'}
+    cpu: [x64]
+    os: [android]
+
+  '@esbuild/darwin-arm64@0.27.3':
+    resolution: {integrity: sha512-Re491k7ByTVRy0t3EKWajdLIr0gz2kKKfzafkth4Q8A5n1xTHrkqZgLLjFEHVD+AXdUGgQMq+Godfq45mGpCKg==}
+    engines: {node: '>=18'}
+    cpu: [arm64]
+    os: [darwin]
+
+  '@esbuild/darwin-x64@0.27.3':
+    resolution: {integrity: sha512-vHk/hA7/1AckjGzRqi6wbo+jaShzRowYip6rt6q7VYEDX4LEy1pZfDpdxCBnGtl+A5zq8iXDcyuxwtv3hNtHFg==}
+    engines: {node: '>=18'}
+    cpu: [x64]
+    os: [darwin]
+
+  '@esbuild/freebsd-arm64@0.27.3':
+    resolution: {integrity: sha512-ipTYM2fjt3kQAYOvo6vcxJx3nBYAzPjgTCk7QEgZG8AUO3ydUhvelmhrbOheMnGOlaSFUoHXB6un+A7q4ygY9w==}
+    engines: {node: '>=18'}
+    cpu: [arm64]
+    os: [freebsd]
+
+  '@esbuild/freebsd-x64@0.27.3':
+    resolution: {integrity: sha512-dDk0X87T7mI6U3K9VjWtHOXqwAMJBNN2r7bejDsc+j03SEjtD9HrOl8gVFByeM0aJksoUuUVU9TBaZa2rgj0oA==}
+    engines: {node: '>=18'}
+    cpu: [x64]
+    os: [freebsd]
+
+  '@esbuild/linux-arm64@0.27.3':
+    resolution: {integrity: sha512-sZOuFz/xWnZ4KH3YfFrKCf1WyPZHakVzTiqji3WDc0BCl2kBwiJLCXpzLzUBLgmp4veFZdvN5ChW4Eq/8Fc2Fg==}
+    engines: {node: '>=18'}
+    cpu: [arm64]
+    os: [linux]
+
+  '@esbuild/linux-arm@0.27.3':
+    resolution: {integrity: sha512-s6nPv2QkSupJwLYyfS+gwdirm0ukyTFNl3KTgZEAiJDd+iHZcbTPPcWCcRYH+WlNbwChgH2QkE9NSlNrMT8Gfw==}
+    engines: {node: '>=18'}
+    cpu: [arm]
+    os: [linux]
+
+  '@esbuild/linux-ia32@0.27.3':
+    resolution: {integrity: sha512-yGlQYjdxtLdh0a3jHjuwOrxQjOZYD/C9PfdbgJJF3TIZWnm/tMd/RcNiLngiu4iwcBAOezdnSLAwQDPqTmtTYg==}
+    engines: {node: '>=18'}
+    cpu: [ia32]
+    os: [linux]
+
+  '@esbuild/linux-loong64@0.27.3':
+    resolution: {integrity: sha512-WO60Sn8ly3gtzhyjATDgieJNet/KqsDlX5nRC5Y3oTFcS1l0KWba+SEa9Ja1GfDqSF1z6hif/SkpQJbL63cgOA==}
+    engines: {node: '>=18'}
+    cpu: [loong64]
+    os: [linux]
+
+  '@esbuild/linux-mips64el@0.27.3':
+    resolution: {integrity: sha512-APsymYA6sGcZ4pD6k+UxbDjOFSvPWyZhjaiPyl/f79xKxwTnrn5QUnXR5prvetuaSMsb4jgeHewIDCIWljrSxw==}
+    engines: {node: '>=18'}
+    cpu: [mips64el]
+    os: [linux]
+
+  '@esbuild/linux-ppc64@0.27.3':
+    resolution: {integrity: sha512-eizBnTeBefojtDb9nSh4vvVQ3V9Qf9Df01PfawPcRzJH4gFSgrObw+LveUyDoKU3kxi5+9RJTCWlj4FjYXVPEA==}
+    engines: {node: '>=18'}
+    cpu: [ppc64]
+    os: [linux]
+
+  '@esbuild/linux-riscv64@0.27.3':
+    resolution: {integrity: sha512-3Emwh0r5wmfm3ssTWRQSyVhbOHvqegUDRd0WhmXKX2mkHJe1SFCMJhagUleMq+Uci34wLSipf8Lagt4LlpRFWQ==}
+    engines: {node: '>=18'}
+    cpu: [riscv64]
+    os: [linux]
+
+  '@esbuild/linux-s390x@0.27.3':
+    resolution: {integrity: sha512-pBHUx9LzXWBc7MFIEEL0yD/ZVtNgLytvx60gES28GcWMqil8ElCYR4kvbV2BDqsHOvVDRrOxGySBM9Fcv744hw==}
+    engines: {node: '>=18'}
+    cpu: [s390x]
+    os: [linux]
+
+  '@esbuild/linux-x64@0.27.3':
+    resolution: {integrity: sha512-Czi8yzXUWIQYAtL/2y6vogER8pvcsOsk5cpwL4Gk5nJqH5UZiVByIY8Eorm5R13gq+DQKYg0+JyQoytLQas4dA==}
+    engines: {node: '>=18'}
+    cpu: [x64]
+    os: [linux]
+
+  '@esbuild/netbsd-arm64@0.27.3':
+    resolution: {integrity: sha512-sDpk0RgmTCR/5HguIZa9n9u+HVKf40fbEUt+iTzSnCaGvY9kFP0YKBWZtJaraonFnqef5SlJ8/TiPAxzyS+UoA==}
+    engines: {node: '>=18'}
+    cpu: [arm64]
+    os: [netbsd]
+
+  '@esbuild/netbsd-x64@0.27.3':
+    resolution: {integrity: sha512-P14lFKJl/DdaE00LItAukUdZO5iqNH7+PjoBm+fLQjtxfcfFE20Xf5CrLsmZdq5LFFZzb5JMZ9grUwvtVYzjiA==}
+    engines: {node: '>=18'}
+    cpu: [x64]
+    os: [netbsd]
+
+  '@esbuild/openbsd-arm64@0.27.3':
+    resolution: {integrity: sha512-AIcMP77AvirGbRl/UZFTq5hjXK+2wC7qFRGoHSDrZ5v5b8DK/GYpXW3CPRL53NkvDqb9D+alBiC/dV0Fb7eJcw==}
+    engines: {node: '>=18'}
+    cpu: [arm64]
+    os: [openbsd]
+
+  '@esbuild/openbsd-x64@0.27.3':
+    resolution: {integrity: sha512-DnW2sRrBzA+YnE70LKqnM3P+z8vehfJWHXECbwBmH/CU51z6FiqTQTHFenPlHmo3a8UgpLyH3PT+87OViOh1AQ==}
+    engines: {node: '>=18'}
+    cpu: [x64]
+    os: [openbsd]
+
+  '@esbuild/openharmony-arm64@0.27.3':
+    resolution: {integrity: sha512-NinAEgr/etERPTsZJ7aEZQvvg/A6IsZG/LgZy+81wON2huV7SrK3e63dU0XhyZP4RKGyTm7aOgmQk0bGp0fy2g==}
+    engines: {node: '>=18'}
+    cpu: [arm64]
+    os: [openharmony]
+
+  '@esbuild/sunos-x64@0.27.3':
+    resolution: {integrity: sha512-PanZ+nEz+eWoBJ8/f8HKxTTD172SKwdXebZ0ndd953gt1HRBbhMsaNqjTyYLGLPdoWHy4zLU7bDVJztF5f3BHA==}
+    engines: {node: '>=18'}
+    cpu: [x64]
+    os: [sunos]
+
+  '@esbuild/win32-arm64@0.27.3':
+    resolution: {integrity: sha512-B2t59lWWYrbRDw/tjiWOuzSsFh1Y/E95ofKz7rIVYSQkUYBjfSgf6oeYPNWHToFRr2zx52JKApIcAS/D5TUBnA==}
+    engines: {node: '>=18'}
+    cpu: [arm64]
+    os: [win32]
+
+  '@esbuild/win32-ia32@0.27.3':
+    resolution: {integrity: sha512-QLKSFeXNS8+tHW7tZpMtjlNb7HKau0QDpwm49u0vUp9y1WOF+PEzkU84y9GqYaAVW8aH8f3GcBck26jh54cX4Q==}
+    engines: {node: '>=18'}
+    cpu: [ia32]
+    os: [win32]
+
+  '@esbuild/win32-x64@0.27.3':
+    resolution: {integrity: sha512-4uJGhsxuptu3OcpVAzli+/gWusVGwZZHTlS63hh++ehExkVT8SgiEf7/uC/PclrPPkLhZqGgCTjd0VWLo6xMqA==}
+    engines: {node: '>=18'}
+    cpu: [x64]
+    os: [win32]
+
+  '@types/node@24.12.0':
+    resolution: {integrity: sha512-GYDxsZi3ChgmckRT9HPU0WEhKLP08ev/Yfcq2AstjrDASOYCSXeyjDsHg4v5t4jOj7cyDX3vmprafKlWIG9MXQ==}
+
+  commander@13.1.0:
+    resolution: {integrity: sha512-/rFeCpNJQbhSZjGVwO9RFV3xPqbnERS8MmIQzCtD/zl6gpJuV/bMLuN92oG3F7d8oDEHHRrujSXNUr8fpjntKw==}
+    engines: {node: '>=18'}
+
+  dotenv@16.6.1:
+    resolution: {integrity: sha512-uBq4egWHTcTt33a72vpSG0z3HnPuIl6NqYcTrKEg2azoEyl2hpW0zqlxysq2pK9HlDIHyHyakeYaYnSAwd8bow==}
+    engines: {node: '>=12'}
+
+  esbuild@0.27.3:
+    resolution: {integrity: sha512-8VwMnyGCONIs6cWue2IdpHxHnAjzxnw2Zr7MkVxB2vjmQ2ivqGFb4LEG3SMnv0Gb2F/G/2yA8zUaiL1gywDCCg==}
+    engines: {node: '>=18'}
+    hasBin: true
+
+  fsevents@2.3.3:
+    resolution: {integrity: sha512-5xoDfX+fL7faATnagmWPpbFtwh/R77WmMMqqHGS65C3vvB0YHrgF+B1YmZ3441tMj5n63k0212XNoJwzlhffQw==}
+    engines: {node: ^8.16.0 || ^10.6.0 || >=11.0.0}
+    os: [darwin]
+
+  get-tsconfig@4.13.6:
+    resolution: {integrity: sha512-shZT/QMiSHc/YBLxxOkMtgSid5HFoauqCE3/exfsEcwg1WkeqjG+V40yBbBrsD+jW2HDXcs28xOfcbm2jI8Ddw==}
+
+  resolve-pkg-maps@1.0.0:
+    resolution: {integrity: sha512-seS2Tj26TBVOC2NIc2rOe2y2ZO7efxITtLZcGSOnHHNOQ7CkiUBfw0Iw2ck6xkIhPwLhKNLS8BO+hEpngQlqzw==}
+
+  tsx@4.21.0:
+    resolution: {integrity: sha512-5C1sg4USs1lfG0GFb2RLXsdpXqBSEhAaA/0kPL01wxzpMqLILNxIxIOKiILz+cdg/pLnOUxFYOR5yhHU666wbw==}
+    engines: {node: '>=18.0.0'}
+    hasBin: true
+
+  typescript@5.9.3:
+    resolution: {integrity: sha512-jl1vZzPDinLr9eUt3J/t7V6FgNEw9QjvBPdysz9KfQDD41fQrC2Y4vKQdiaUpFT4bXlb1RHhLpp8wtm6M5TgSw==}
+    engines: {node: '>=14.17'}
+    hasBin: true
+
+  undici-types@7.16.0:
+    resolution: {integrity: sha512-Zz+aZWSj8LE6zoxD+xrjh4VfkIG8Ya6LvYkZqtUQGJPZjYl53ypCaUwWqo7eI0x66KBGeRo+mlBEkMSeSZ38Nw==}
+
+snapshots:
+
+  '@esbuild/aix-ppc64@0.27.3':
+    optional: true
+
+  '@esbuild/android-arm64@0.27.3':
+    optional: true
+
+  '@esbuild/android-arm@0.27.3':
+    optional: true
+
+  '@esbuild/android-x64@0.27.3':
+    optional: true
+
+  '@esbuild/darwin-arm64@0.27.3':
+    optional: true
+
+  '@esbuild/darwin-x64@0.27.3':
+    optional: true
+
+  '@esbuild/freebsd-arm64@0.27.3':
+    optional: true
+
+  '@esbuild/freebsd-x64@0.27.3':
+    optional: true
+
+  '@esbuild/linux-arm64@0.27.3':
+    optional: true
+
+  '@esbuild/linux-arm@0.27.3':
+    optional: true
+
+  '@esbuild/linux-ia32@0.27.3':
+    optional: true
+
+  '@esbuild/linux-loong64@0.27.3':
+    optional: true
+
+  '@esbuild/linux-mips64el@0.27.3':
+    optional: true
+
+  '@esbuild/linux-ppc64@0.27.3':
+    optional: true
+
+  '@esbuild/linux-riscv64@0.27.3':
+    optional: true
+
+  '@esbuild/linux-s390x@0.27.3':
+    optional: true
+
+  '@esbuild/linux-x64@0.27.3':
+    optional: true
+
+  '@esbuild/netbsd-arm64@0.27.3':
+    optional: true
+
+  '@esbuild/netbsd-x64@0.27.3':
+    optional: true
+
+  '@esbuild/openbsd-arm64@0.27.3':
+    optional: true
+
+  '@esbuild/openbsd-x64@0.27.3':
+    optional: true
+
+  '@esbuild/openharmony-arm64@0.27.3':
+    optional: true
+
+  '@esbuild/sunos-x64@0.27.3':
+    optional: true
+
+  '@esbuild/win32-arm64@0.27.3':
+    optional: true
+
+  '@esbuild/win32-ia32@0.27.3':
+    optional: true
+
+  '@esbuild/win32-x64@0.27.3':
+    optional: true
+
+  '@types/node@24.12.0':
+    dependencies:
+      undici-types: 7.16.0
+
+  commander@13.1.0: {}
+
+  dotenv@16.6.1: {}
+
+  esbuild@0.27.3:
+    optionalDependencies:
+      '@esbuild/aix-ppc64': 0.27.3
+      '@esbuild/android-arm': 0.27.3
+      '@esbuild/android-arm64': 0.27.3
+      '@esbuild/android-x64': 0.27.3
+      '@esbuild/darwin-arm64': 0.27.3
+      '@esbuild/darwin-x64': 0.27.3
+      '@esbuild/freebsd-arm64': 0.27.3
+      '@esbuild/freebsd-x64': 0.27.3
+      '@esbuild/linux-arm': 0.27.3
+      '@esbuild/linux-arm64': 0.27.3
+      '@esbuild/linux-ia32': 0.27.3
+      '@esbuild/linux-loong64': 0.27.3
+      '@esbuild/linux-mips64el': 0.27.3
+      '@esbuild/linux-ppc64': 0.27.3
+      '@esbuild/linux-riscv64': 0.27.3
+      '@esbuild/linux-s390x': 0.27.3
+      '@esbuild/linux-x64': 0.27.3
+      '@esbuild/netbsd-arm64': 0.27.3
+      '@esbuild/netbsd-x64': 0.27.3
+      '@esbuild/openbsd-arm64': 0.27.3
+      '@esbuild/openbsd-x64': 0.27.3
+      '@esbuild/openharmony-arm64': 0.27.3
+      '@esbuild/sunos-x64': 0.27.3
+      '@esbuild/win32-arm64': 0.27.3
+      '@esbuild/win32-ia32': 0.27.3
+      '@esbuild/win32-x64': 0.27.3
+
+  fsevents@2.3.3:
+    optional: true
+
+  get-tsconfig@4.13.6:
+    dependencies:
+      resolve-pkg-maps: 1.0.0
+
+  resolve-pkg-maps@1.0.0: {}
+
+  tsx@4.21.0:
+    dependencies:
+      esbuild: 0.27.3
+      get-tsconfig: 4.13.6
+    optionalDependencies:
+      fsevents: 2.3.3
+
+  typescript@5.9.3: {}
+
+  undici-types@7.16.0: {}

skills/atlassian/cursor/scripts/src/adf.ts

@@ -0,0 +1,92 @@
+const TEXT_NODE = "text";
+
+function textNode(text: string) {
+  return {
+    type: TEXT_NODE,
+    text,
+  };
+}
+
+function paragraphNode(lines: string[]) {
+  const content: Array<{ type: string; text?: string }> = [];
+
+  lines.forEach((line, index) => {
+    if (index > 0) {
+      content.push({ type: "hardBreak" });
+    }
+
+    if (line.length > 0) {
+      content.push(textNode(line));
+    }
+  });
+
+  return {
+    type: "paragraph",
+    ...(content.length > 0 ? { content } : {}),
+  };
+}
+
+export function markdownToAdf(input: string) {
+  const lines = input.replace(/\r\n/g, "\n").split("\n");
+  const content: Array<Record<string, unknown>> = [];
+  let index = 0;
+
+  while (index < lines.length) {
+    const current = lines[index]?.trimEnd() ?? "";
+
+    if (current.trim().length === 0) {
+      index += 1;
+      continue;
+    }
+
+    const heading = current.match(/^(#{1,6})\s+(.*)$/);
+
+    if (heading) {
+      content.push({
+        type: "heading",
+        attrs: { level: heading[1].length },
+        content: [textNode(heading[2])],
+      });
+      index += 1;
+      continue;
+    }
+
+    if (/^[-*]\s+/.test(current)) {
+      const items: Array<Record<string, unknown>> = [];
+
+      while (index < lines.length && /^[-*]\s+/.test(lines[index] ?? "")) {
+        items.push({
+          type: "listItem",
+          content: [
+            {
+              type: "paragraph",
+              content: [textNode((lines[index] ?? "").replace(/^[-*]\s+/, ""))],
+            },
+          ],
+        });
+        index += 1;
+      }
+
+      content.push({
+        type: "bulletList",
+        content: items,
+      });
+      continue;
+    }
+
+    const paragraphLines: string[] = [];
+
+    while (index < lines.length && (lines[index]?.trim().length ?? 0) > 0) {
+      paragraphLines.push(lines[index] ?? "");
+      index += 1;
+    }
+
+    content.push(paragraphNode(paragraphLines));
+  }
+
+  return {
+    type: "doc",
+    version: 1,
+    content,
+  };
+}

skills/atlassian/cursor/scripts/src/cli.ts

@@ -0,0 +1,332 @@
+import process from "node:process";
+import { pathToFileURL } from "node:url";
+
+import { Command } from "commander";
+
+import { createConfluenceClient } from "./confluence.js";
+import { loadConfig } from "./config.js";
+import { readWorkspaceFile } from "./files.js";
+import { runHealthCheck } from "./health.js";
+import { createJiraClient } from "./jira.js";
+import { writeOutput } from "./output.js";
+import { runRawCommand } from "./raw.js";
+import type { FetchLike, OutputFormat, Writer } from "./types.js";
+
+type CliContext = {
+  cwd?: string;
+  env?: NodeJS.ProcessEnv;
+  fetchImpl?: FetchLike;
+  stdout?: Writer;
+  stderr?: Writer;
+};
+
+function resolveFormat(format: string | undefined): OutputFormat {
+  return format === "text" ? "text" : "json";
+}
+
+function createRuntime(context: CliContext) {
+  const cwd = context.cwd ?? process.cwd();
+  const env = context.env ?? process.env;
+  const stdout = context.stdout ?? process.stdout;
+  const stderr = context.stderr ?? process.stderr;
+  let configCache: ReturnType<typeof loadConfig> | undefined;
+  let jiraCache: ReturnType<typeof createJiraClient> | undefined;
+  let confluenceCache: ReturnType<typeof createConfluenceClient> | undefined;
+
+  function getConfig() {
+    configCache ??= loadConfig(env, { cwd });
+    return configCache;
+  }
+
+  function getJiraClient() {
+    jiraCache ??= createJiraClient({
+      config: getConfig(),
+      fetchImpl: context.fetchImpl,
+    });
+    return jiraCache;
+  }
+
+  function getConfluenceClient() {
+    confluenceCache ??= createConfluenceClient({
+      config: getConfig(),
+      fetchImpl: context.fetchImpl,
+    });
+    return confluenceCache;
+  }
+
+  async function readBodyFile(filePath: string | undefined) {
+    if (!filePath) {
+      return undefined;
+    }
+
+    return readWorkspaceFile(filePath, cwd);
+  }
+
+  return {
+    cwd,
+    stdout,
+    stderr,
+    readBodyFile,
+    getConfig,
+    getJiraClient,
+    getConfluenceClient,
+    fetchImpl: context.fetchImpl,
+  };
+}
+
+export function buildProgram(context: CliContext = {}) {
+  const runtime = createRuntime(context);
+  const program = new Command()
+    .name("atlassian")
+    .description("Portable Atlassian CLI for multi-agent skills")
+    .version("0.1.0");
+
+  program
+    .command("health")
+    .description("Validate configuration and Atlassian connectivity")
+    .option("--format <format>", "Output format", "json")
+    .action(async (options) => {
+      const payload = await runHealthCheck(runtime.getConfig(), runtime.fetchImpl);
+      writeOutput(
+        runtime.stdout,
+        payload,
+        resolveFormat(options.format),
+      );
+    });
+
+  program
+    .command("conf-search")
+    .requiredOption("--query <query>", "CQL search query")
+    .option("--max-results <number>", "Maximum results to return", "50")
+    .option("--start-at <number>", "Result offset", "0")
+    .option("--format <format>", "Output format", "json")
+    .action(async (options) => {
+      const payload = await runtime.getConfluenceClient().searchPages({
+        query: options.query,
+        maxResults: Number(options.maxResults),
+        startAt: Number(options.startAt),
+      });
+
+      writeOutput(runtime.stdout, payload, resolveFormat(options.format));
+    });
+
+  program
+    .command("conf-get")
+    .requiredOption("--page <page>", "Confluence page ID")
+    .option("--format <format>", "Output format", "json")
+    .action(async (options) => {
+      const payload = await runtime.getConfluenceClient().getPage(options.page);
+      writeOutput(runtime.stdout, payload, resolveFormat(options.format));
+    });
+
+  program
+    .command("conf-create")
+    .requiredOption("--title <title>", "Confluence page title")
+    .requiredOption("--body-file <path>", "Workspace-relative storage-format body file")
+    .option("--space <space>", "Confluence space ID")
+    .option("--dry-run", "Print the request without sending it")
+    .option("--format <format>", "Output format", "json")
+    .action(async (options) => {
+      const payload = await runtime.getConfluenceClient().createPage({
+        space: options.space,
+        title: options.title,
+        body: (await runtime.readBodyFile(options.bodyFile)) as string,
+        dryRun: Boolean(options.dryRun),
+      });
+
+      writeOutput(runtime.stdout, payload, resolveFormat(options.format));
+    });
+
+  program
+    .command("conf-update")
+    .requiredOption("--page <page>", "Confluence page ID")
+    .requiredOption("--title <title>", "Confluence page title")
+    .requiredOption("--body-file <path>", "Workspace-relative storage-format body file")
+    .option("--dry-run", "Print the request without sending it")
+    .option("--format <format>", "Output format", "json")
+    .action(async (options) => {
+      const payload = await runtime.getConfluenceClient().updatePage({
+        pageId: options.page,
+        title: options.title,
+        body: (await runtime.readBodyFile(options.bodyFile)) as string,
+        dryRun: Boolean(options.dryRun),
+      });
+
+      writeOutput(runtime.stdout, payload, resolveFormat(options.format));
+    });
+
+  program
+    .command("conf-comment")
+    .requiredOption("--page <page>", "Confluence page ID")
+    .requiredOption("--body-file <path>", "Workspace-relative storage-format body file")
+    .option("--dry-run", "Print the request without sending it")
+    .option("--format <format>", "Output format", "json")
+    .action(async (options) => {
+      const payload = await runtime.getConfluenceClient().commentPage({
+        pageId: options.page,
+        body: (await runtime.readBodyFile(options.bodyFile)) as string,
+        dryRun: Boolean(options.dryRun),
+      });
+
+      writeOutput(runtime.stdout, payload, resolveFormat(options.format));
+    });
+
+  program
+    .command("conf-children")
+    .requiredOption("--page <page>", "Confluence page ID")
+    .option("--max-results <number>", "Maximum results to return", "50")
+    .option("--start-at <number>", "Cursor/start token", "0")
+    .option("--format <format>", "Output format", "json")
+    .action(async (options) => {
+      const payload = await runtime.getConfluenceClient().listChildren(
+        options.page,
+        Number(options.maxResults),
+        Number(options.startAt),
+      );
+
+      writeOutput(runtime.stdout, payload, resolveFormat(options.format));
+    });
+
+  program
+    .command("raw")
+    .requiredOption("--product <product>", "jira or confluence")
+    .requiredOption("--method <method>", "GET, POST, or PUT")
+    .requiredOption("--path <path>", "Validated API path")
+    .option("--body-file <path>", "Workspace-relative JSON file")
+    .option("--dry-run", "Print the request without sending it")
+    .option("--format <format>", "Output format", "json")
+    .action(async (options) => {
+      const payload = await runRawCommand(runtime.getConfig(), runtime.fetchImpl, {
+        product: options.product,
+        method: String(options.method).toUpperCase(),
+        path: options.path,
+        bodyFile: options.bodyFile,
+        cwd: runtime.cwd,
+        dryRun: Boolean(options.dryRun),
+      });
+
+      writeOutput(runtime.stdout, payload, resolveFormat(options.format));
+    });
+
+  program
+    .command("jira-search")
+    .requiredOption("--jql <jql>", "JQL expression to execute")
+    .option("--max-results <number>", "Maximum results to return", "50")
+    .option("--start-at <number>", "Result offset", "0")
+    .option("--format <format>", "Output format", "json")
+    .action(async (options) => {
+      const payload = await runtime.getJiraClient().searchIssues({
+        jql: options.jql,
+        maxResults: Number(options.maxResults),
+        startAt: Number(options.startAt),
+      });
+
+      writeOutput(runtime.stdout, payload, resolveFormat(options.format));
+    });
+
+  program
+    .command("jira-get")
+    .requiredOption("--issue <issue>", "Issue key")
+    .option("--format <format>", "Output format", "json")
+    .action(async (options) => {
+      const payload = await runtime.getJiraClient().getIssue(options.issue);
+      writeOutput(runtime.stdout, payload, resolveFormat(options.format));
+    });
+
+  program
+    .command("jira-create")
+    .requiredOption("--type <type>", "Issue type name")
+    .requiredOption("--summary <summary>", "Issue summary")
+    .option("--project <project>", "Project key")
+    .option("--description-file <path>", "Workspace-relative markdown/text file")
+    .option("--dry-run", "Print the request without sending it")
+    .option("--format <format>", "Output format", "json")
+    .action(async (options) => {
+      const payload = await runtime.getJiraClient().createIssue({
+        project: options.project,
+        type: options.type,
+        summary: options.summary,
+        description: await runtime.readBodyFile(options.descriptionFile),
+        dryRun: Boolean(options.dryRun),
+      });
+
+      writeOutput(runtime.stdout, payload, resolveFormat(options.format));
+    });
+
+  program
+    .command("jira-update")
+    .requiredOption("--issue <issue>", "Issue key")
+    .option("--summary <summary>", "Updated summary")
+    .option("--description-file <path>", "Workspace-relative markdown/text file")
+    .option("--dry-run", "Print the request without sending it")
+    .option("--format <format>", "Output format", "json")
+    .action(async (options) => {
+      const payload = await runtime.getJiraClient().updateIssue({
+        issue: options.issue,
+        summary: options.summary,
+        description: await runtime.readBodyFile(options.descriptionFile),
+        dryRun: Boolean(options.dryRun),
+      });
+
+      writeOutput(runtime.stdout, payload, resolveFormat(options.format));
+    });
+
+  program
+    .command("jira-comment")
+    .requiredOption("--issue <issue>", "Issue key")
+    .requiredOption("--body-file <path>", "Workspace-relative markdown/text file")
+    .option("--dry-run", "Print the request without sending it")
+    .option("--format <format>", "Output format", "json")
+    .action(async (options) => {
+      const payload = await runtime.getJiraClient().commentIssue({
+        issue: options.issue,
+        body: (await runtime.readBodyFile(options.bodyFile)) as string,
+        dryRun: Boolean(options.dryRun),
+      });
+
+      writeOutput(runtime.stdout, payload, resolveFormat(options.format));
+    });
+
+  program
+    .command("jira-transitions")
+    .requiredOption("--issue <issue>", "Issue key")
+    .option("--format <format>", "Output format", "json")
+    .action(async (options) => {
+      const payload = await runtime.getJiraClient().getTransitions(options.issue);
+      writeOutput(runtime.stdout, payload, resolveFormat(options.format));
+    });
+
+  program
+    .command("jira-transition")
+    .requiredOption("--issue <issue>", "Issue key")
+    .requiredOption("--transition <transition>", "Transition ID")
+    .option("--dry-run", "Print the request without sending it")
+    .option("--format <format>", "Output format", "json")
+    .action(async (options) => {
+      const payload = await runtime.getJiraClient().transitionIssue({
+        issue: options.issue,
+        transition: options.transition,
+        dryRun: Boolean(options.dryRun),
+      });
+
+      writeOutput(runtime.stdout, payload, resolveFormat(options.format));
+    });
+
+  return program;
+}
+
+export async function runCli(argv = process.argv, context: CliContext = {}) {
+  const program = buildProgram(context);
+  await program.parseAsync(argv);
+}
+
+const isDirectExecution =
+  Boolean(process.argv[1]) && import.meta.url === pathToFileURL(process.argv[1]).href;
+
+if (isDirectExecution) {
+  runCli().catch((error: unknown) => {
+    const message = error instanceof Error ? error.message : String(error);
+    process.stderr.write(`${message}\n`);
+    process.exitCode = 1;
+  });
+}

skills/atlassian/cursor/scripts/src/config.ts

@@ -0,0 +1,52 @@
+import path from "node:path";
+
+import { config as loadDotEnv } from "dotenv";
+
+import type { AtlassianConfig } from "./types.js";
+
+function normalizeBaseUrl(value: string) {
+  return value.replace(/\/+$/, "");
+}
+
+function readRequired(env: NodeJS.ProcessEnv, key: string) {
+  const value = env[key]?.trim();
+
+  if (!value) {
+    throw new Error(`Missing required environment variable: ${key}`);
+  }
+
+  return value;
+}
+
+export function loadConfig(
+  env: NodeJS.ProcessEnv = process.env,
+  options?: {
+    cwd?: string;
+  },
+): AtlassianConfig {
+  loadDotEnv({
+    path: path.resolve(options?.cwd ?? process.cwd(), ".env"),
+    processEnv: env as Record<string, string>,
+    override: false,
+  });
+
+  const baseUrl = normalizeBaseUrl(readRequired(env, "ATLASSIAN_BASE_URL"));
+
+  return {
+    baseUrl,
+    jiraBaseUrl: normalizeBaseUrl(env.ATLASSIAN_JIRA_BASE_URL?.trim() || baseUrl),
+    confluenceBaseUrl: normalizeBaseUrl(env.ATLASSIAN_CONFLUENCE_BASE_URL?.trim() || baseUrl),
+    email: readRequired(env, "ATLASSIAN_EMAIL"),
+    apiToken: readRequired(env, "ATLASSIAN_API_TOKEN"),
+    defaultProject: env.ATLASSIAN_DEFAULT_PROJECT?.trim() || undefined,
+    defaultSpace: env.ATLASSIAN_DEFAULT_SPACE?.trim() || undefined,
+  };
+}
+
+export function createBasicAuthHeader(config: {
+  email: string;
+  apiToken: string;
+  [key: string]: unknown;
+}) {
+  return `Basic ${Buffer.from(`${config.email}:${config.apiToken}`).toString("base64")}`;
+}

skills/atlassian/cursor/scripts/src/confluence.ts

@@ -0,0 +1,292 @@
+import { sendJsonRequest } from "./http.js";
+import type { AtlassianConfig, CommandOutput, FetchLike } from "./types.js";
+
+type ConfluenceClientOptions = {
+  config: AtlassianConfig;
+  fetchImpl?: FetchLike;
+};
+
+type SearchInput = {
+  query: string;
+  maxResults: number;
+  startAt: number;
+};
+
+type CreateInput = {
+  space?: string;
+  title: string;
+  body: string;
+  dryRun?: boolean;
+};
+
+type UpdateInput = {
+  pageId: string;
+  title: string;
+  body: string;
+  dryRun?: boolean;
+};
+
+type CommentInput = {
+  pageId: string;
+  body: string;
+  dryRun?: boolean;
+};
+
+type PageSummary = {
+  id: string;
+  title: string;
+  type: string;
+  status?: string;
+  spaceId?: string;
+  url?: string;
+};
+
+function buildUrl(baseUrl: string, path: string) {
+  return new URL(path, `${baseUrl}/`).toString();
+}
+
+function normalizePage(baseUrl: string, page: Record<string, unknown>, excerpt?: string) {
+  const links = (page._links ?? {}) as Record<string, unknown>;
+
+  return {
+    id: String(page.id ?? ""),
+    title: String(page.title ?? ""),
+    type: String(page.type ?? "page"),
+    ...(page.status ? { status: String(page.status) } : {}),
+    ...(page.spaceId ? { spaceId: String(page.spaceId) } : {}),
+    ...(excerpt ? { excerpt } : {}),
+    ...(links.webui ? { url: `${baseUrl}${String(links.webui)}` } : {}),
+  };
+}
+
+export function createConfluenceClient(options: ConfluenceClientOptions) {
+  const config = options.config;
+
+  async function getPageForUpdate(pageId: string) {
+    return (await sendJsonRequest({
+      config,
+      fetchImpl: options.fetchImpl,
+      url: buildUrl(config.confluenceBaseUrl, `/wiki/api/v2/pages/${pageId}?body-format=storage`),
+      method: "GET",
+      errorPrefix: "Confluence request failed",
+    })) as Record<string, unknown>;
+  }
+
+  return {
+    async searchPages(input: SearchInput): Promise<CommandOutput<unknown>> {
+      const url = new URL("/wiki/rest/api/search", `${config.confluenceBaseUrl}/`);
+      url.searchParams.set("cql", input.query);
+      url.searchParams.set("limit", String(input.maxResults));
+      url.searchParams.set("start", String(input.startAt));
+
+      const raw = (await sendJsonRequest({
+        config,
+        fetchImpl: options.fetchImpl,
+        url: url.toString(),
+        method: "GET",
+        errorPrefix: "Confluence request failed",
+      })) as Record<string, unknown>;
+
+      const results = Array.isArray(raw.results) ? raw.results : [];
+
+      return {
+        ok: true,
+        data: {
+          pages: results.map((entry) => {
+            const result = entry as Record<string, unknown>;
+            return normalizePage(
+              config.baseUrl,
+              (result.content ?? {}) as Record<string, unknown>,
+              result.excerpt ? String(result.excerpt) : undefined,
+            );
+          }),
+          startAt: Number(raw.start ?? input.startAt),
+          maxResults: Number(raw.limit ?? input.maxResults),
+          total: Number(raw.totalSize ?? raw.size ?? results.length),
+        },
+      };
+    },
+
+    async getPage(pageId: string): Promise<CommandOutput<unknown>> {
+      const raw = (await sendJsonRequest({
+        config,
+        fetchImpl: options.fetchImpl,
+        url: buildUrl(config.confluenceBaseUrl, `/wiki/api/v2/pages/${pageId}?body-format=storage`),
+        method: "GET",
+        errorPrefix: "Confluence request failed",
+      })) as Record<string, unknown>;
+
+      const body = ((raw.body ?? {}) as Record<string, unknown>).storage as Record<string, unknown> | undefined;
+
+      return {
+        ok: true,
+        data: {
+          page: {
+            ...normalizePage(config.baseUrl, raw),
+            version: Number((((raw.version ?? {}) as Record<string, unknown>).number ?? 0)),
+            body: body?.value ? String(body.value) : "",
+          },
+        },
+        raw,
+      };
+    },
+
+    async listChildren(pageId: string, maxResults: number, startAt: number): Promise<CommandOutput<unknown>> {
+      const url = new URL(`/wiki/api/v2/pages/${pageId}/direct-children`, `${config.confluenceBaseUrl}/`);
+      url.searchParams.set("limit", String(maxResults));
+      url.searchParams.set("cursor", String(startAt));
+
+      const raw = (await sendJsonRequest({
+        config,
+        fetchImpl: options.fetchImpl,
+        url: url.toString(),
+        method: "GET",
+        errorPrefix: "Confluence request failed",
+      })) as Record<string, unknown>;
+
+      const results = Array.isArray(raw.results) ? raw.results : [];
+      const links = (raw._links ?? {}) as Record<string, unknown>;
+
+      return {
+        ok: true,
+        data: {
+          pages: results.map((page) => normalizePage(config.baseUrl, page as Record<string, unknown>)),
+          nextCursor: links.next ? String(links.next) : null,
+        },
+      };
+    },
+
+    async createPage(input: CreateInput): Promise<CommandOutput<unknown>> {
+      const spaceId = input.space || config.defaultSpace;
+
+      if (!spaceId) {
+        throw new Error("conf-create requires --space or ATLASSIAN_DEFAULT_SPACE");
+      }
+
+      const request = {
+        method: "POST" as const,
+        url: buildUrl(config.confluenceBaseUrl, "/wiki/api/v2/pages"),
+        body: {
+          spaceId,
+          title: input.title,
+          status: "current",
+          body: {
+            representation: "storage",
+            value: input.body,
+          },
+        },
+      };
+
+      if (input.dryRun) {
+        return {
+          ok: true,
+          dryRun: true,
+          data: request,
+        };
+      }
+
+      const raw = await sendJsonRequest({
+        config,
+        fetchImpl: options.fetchImpl,
+        url: request.url,
+        method: request.method,
+        body: request.body,
+        errorPrefix: "Confluence request failed",
+      });
+
+      return {
+        ok: true,
+        data: raw,
+      };
+    },
+
+    async updatePage(input: UpdateInput): Promise<CommandOutput<unknown>> {
+      const currentPage = await getPageForUpdate(input.pageId);
+      const version = (((currentPage.version ?? {}) as Record<string, unknown>).number ?? 0) as number;
+      const spaceId = String(currentPage.spaceId ?? "");
+
+      const request = {
+        method: "PUT" as const,
+        url: buildUrl(config.confluenceBaseUrl, `/wiki/api/v2/pages/${input.pageId}`),
+        body: {
+          id: input.pageId,
+          status: String(currentPage.status ?? "current"),
+          title: input.title,
+          spaceId,
+          version: {
+            number: Number(version) + 1,
+          },
+          body: {
+            representation: "storage",
+            value: input.body,
+          },
+        },
+      };
+
+      if (input.dryRun) {
+        return {
+          ok: true,
+          dryRun: true,
+          data: request,
+        };
+      }
+
+      const raw = await sendJsonRequest({
+        config,
+        fetchImpl: options.fetchImpl,
+        url: request.url,
+        method: request.method,
+        body: request.body,
+        errorPrefix: "Confluence request failed",
+        handleResponseError(response) {
+          if (response.status === 409) {
+            return new Error(`Confluence update conflict: page ${input.pageId} was updated by someone else`);
+          }
+
+          return undefined;
+        },
+      });
+
+      return {
+        ok: true,
+        data: raw,
+      };
+    },
+
+    async commentPage(input: CommentInput): Promise<CommandOutput<unknown>> {
+      const request = {
+        method: "POST" as const,
+        url: buildUrl(config.confluenceBaseUrl, "/wiki/api/v2/footer-comments"),
+        body: {
+          pageId: input.pageId,
+          body: {
+            representation: "storage",
+            value: input.body,
+          },
+        },
+      };
+
+      if (input.dryRun) {
+        return {
+          ok: true,
+          dryRun: true,
+          data: request,
+        };
+      }
+
+      const raw = await sendJsonRequest({
+        config,
+        fetchImpl: options.fetchImpl,
+        url: request.url,
+        method: request.method,
+        body: request.body,
+        errorPrefix: "Confluence request failed",
+      });
+
+      return {
+        ok: true,
+        data: raw,
+      };
+    },
+  };
+}

skills/atlassian/cursor/scripts/src/files.ts

@@ -0,0 +1,13 @@
+import { readFile } from "node:fs/promises";
+import path from "node:path";
+
+export async function readWorkspaceFile(filePath: string, cwd: string) {
+  const resolved = path.resolve(cwd, filePath);
+  const relative = path.relative(cwd, resolved);
+
+  if (relative.startsWith("..") || path.isAbsolute(relative)) {
+    throw new Error(`--body-file must stay within the active workspace: ${filePath}`);
+  }
+
+  return readFile(resolved, "utf8");
+}

skills/atlassian/cursor/scripts/src/health.ts

@@ -0,0 +1,69 @@
+import { createJsonHeaders, createStatusError } from "./http.js";
+import type { AtlassianConfig, CommandOutput, FetchLike } from "./types.js";
+
+type ProductHealth = {
+  ok: boolean;
+  status?: number;
+  message?: string;
+};
+
+function buildUrl(baseUrl: string, path: string) {
+  return new URL(path, `${baseUrl}/`).toString();
+}
+
+export async function runHealthCheck(
+  config: AtlassianConfig,
+  fetchImpl: FetchLike | undefined,
+): Promise<CommandOutput<unknown>> {
+  const client = fetchImpl ?? globalThis.fetch;
+
+  if (!client) {
+    throw new Error("Fetch API is not available in this runtime");
+  }
+
+  async function probe(product: "Jira" | "Confluence", url: string): Promise<ProductHealth> {
+    try {
+      const response = await client(url, {
+        method: "GET",
+        headers: createJsonHeaders(config, false),
+      });
+
+      if (!response.ok) {
+        const error = createStatusError(`${product} health check failed`, response);
+        return {
+          ok: false,
+          status: response.status,
+          message: error.message,
+        };
+      }
+
+      return {
+        ok: true,
+        status: response.status,
+      };
+    } catch (error: unknown) {
+      return {
+        ok: false,
+        message: error instanceof Error ? error.message : String(error),
+      };
+    }
+  }
+
+  const jira = await probe("Jira", buildUrl(config.jiraBaseUrl, "/rest/api/3/myself"));
+  const confluence = await probe("Confluence", buildUrl(config.confluenceBaseUrl, "/wiki/api/v2/spaces?limit=1"));
+
+  return {
+    ok: jira.ok && confluence.ok,
+    data: {
+      baseUrl: config.baseUrl,
+      jiraBaseUrl: config.jiraBaseUrl,
+      confluenceBaseUrl: config.confluenceBaseUrl,
+      defaultProject: config.defaultProject,
+      defaultSpace: config.defaultSpace,
+      products: {
+        jira,
+        confluence,
+      },
+    },
+  };
+}

skills/atlassian/cursor/scripts/src/http.ts

@@ -0,0 +1,86 @@
+import { createBasicAuthHeader } from "./config.js";
+import type { AtlassianConfig, FetchLike } from "./types.js";
+
+export type HttpMethod = "GET" | "POST" | "PUT";
+
+export function createJsonHeaders(config: AtlassianConfig, includeJsonBody: boolean) {
+  const headers: Array<[string, string]> = [
+    ["Accept", "application/json"],
+    ["Authorization", createBasicAuthHeader(config)],
+  ];
+
+  if (includeJsonBody) {
+    headers.push(["Content-Type", "application/json"]);
+  }
+
+  return headers;
+}
+
+export async function parseResponse(response: Response) {
+  if (response.status === 204) {
+    return null;
+  }
+
+  const contentType = response.headers.get("content-type") ?? "";
+
+  if (contentType.includes("application/json")) {
+    try {
+      return await response.json();
+    } catch {
+      throw new Error("Malformed JSON response from Atlassian API");
+    }
+  }
+
+  return response.text();
+}
+
+export function createStatusError(errorPrefix: string, response: Response) {
+  const base = `${errorPrefix}: ${response.status} ${response.statusText}`;
+
+  switch (response.status) {
+    case 401:
+      return new Error(`${base} - check ATLASSIAN_EMAIL and ATLASSIAN_API_TOKEN`);
+    case 403:
+      return new Error(`${base} - verify product permissions for this account`);
+    case 404:
+      return new Error(`${base} - verify the resource identifier or API path`);
+    case 429:
+      return new Error(`${base} - retry later or reduce request rate`);
+    default:
+      return new Error(base);
+  }
+}
+
+export async function sendJsonRequest(options: {
+  config: AtlassianConfig;
+  fetchImpl?: FetchLike;
+  url: string;
+  method: HttpMethod;
+  body?: unknown;
+  errorPrefix: string;
+  handleResponseError?: (response: Response) => Error | undefined;
+}) {
+  const fetchImpl = options.fetchImpl ?? globalThis.fetch;
+
+  if (!fetchImpl) {
+    throw new Error("Fetch API is not available in this runtime");
+  }
+
+  const response = await fetchImpl(options.url, {
+    method: options.method,
+    headers: createJsonHeaders(options.config, options.body !== undefined),
+    ...(options.body === undefined ? {} : { body: JSON.stringify(options.body) }),
+  });
+
+  if (!response.ok) {
+    const customError = options.handleResponseError?.(response);
+
+    if (customError) {
+      throw customError;
+    }
+
+    throw createStatusError(options.errorPrefix, response);
+  }
+
+  return parseResponse(response);
+}

skills/atlassian/cursor/scripts/src/jira.ts

@@ -0,0 +1,264 @@
+import { markdownToAdf } from "./adf.js";
+import { sendJsonRequest } from "./http.js";
+import type { AtlassianConfig, CommandOutput, FetchLike, JiraIssueSummary } from "./types.js";
+
+const ISSUE_FIELDS = ["summary", "issuetype", "status", "assignee", "created", "updated"] as const;
+
+type JiraClientOptions = {
+  config: AtlassianConfig;
+  fetchImpl?: FetchLike;
+};
+
+type SearchInput = {
+  jql: string;
+  maxResults: number;
+  startAt: number;
+};
+
+type CreateInput = {
+  project?: string;
+  type: string;
+  summary: string;
+  description?: string;
+  dryRun?: boolean;
+};
+
+type UpdateInput = {
+  issue: string;
+  summary?: string;
+  description?: string;
+  dryRun?: boolean;
+};
+
+type CommentInput = {
+  issue: string;
+  body: string;
+  dryRun?: boolean;
+};
+
+type TransitionInput = {
+  issue: string;
+  transition: string;
+  dryRun?: boolean;
+};
+
+function normalizeIssue(config: AtlassianConfig, issue: Record<string, unknown>): JiraIssueSummary {
+  const fields = (issue.fields ?? {}) as Record<string, unknown>;
+  const issueType = (fields.issuetype ?? {}) as Record<string, unknown>;
+  const status = (fields.status ?? {}) as Record<string, unknown>;
+  const assignee = (fields.assignee ?? {}) as Record<string, unknown>;
+
+  return {
+    key: String(issue.key ?? ""),
+    summary: String(fields.summary ?? ""),
+    issueType: String(issueType.name ?? ""),
+    status: String(status.name ?? ""),
+    assignee: assignee.displayName ? String(assignee.displayName) : undefined,
+    created: String(fields.created ?? ""),
+    updated: String(fields.updated ?? ""),
+    url: `${config.baseUrl}/browse/${issue.key ?? ""}`,
+  };
+}
+
+function createRequest(config: AtlassianConfig, method: "GET" | "POST" | "PUT", path: string, body?: unknown) {
+  const url = new URL(path, `${config.jiraBaseUrl}/`);
+
+  return {
+    method,
+    url: url.toString(),
+    ...(body === undefined ? {} : { body }),
+  };
+}
+
+export function createJiraClient(options: JiraClientOptions) {
+  const fetchImpl = options.fetchImpl ?? globalThis.fetch;
+
+  if (!fetchImpl) {
+    throw new Error("Fetch API is not available in this runtime");
+  }
+
+  async function send(method: "GET" | "POST" | "PUT", path: string, body?: unknown) {
+    const request = createRequest(options.config, method, path, body);
+    return sendJsonRequest({
+      config: options.config,
+      fetchImpl,
+      url: request.url,
+      method,
+      body,
+      errorPrefix: "Jira request failed",
+    });
+  }
+
+  return {
+    async searchIssues(input: SearchInput): Promise<CommandOutput<unknown>> {
+      const raw = (await send("POST", "/rest/api/3/search", {
+        jql: input.jql,
+        maxResults: input.maxResults,
+        startAt: input.startAt,
+        fields: [...ISSUE_FIELDS],
+      })) as Record<string, unknown>;
+
+      const issues = Array.isArray(raw.issues) ? raw.issues : [];
+
+      return {
+        ok: true,
+        data: {
+          issues: issues.map((issue) => normalizeIssue(options.config, issue as Record<string, unknown>)),
+          startAt: Number(raw.startAt ?? input.startAt),
+          maxResults: Number(raw.maxResults ?? input.maxResults),
+          total: Number(raw.total ?? issues.length),
+        },
+      };
+    },
+
+    async getIssue(issue: string): Promise<CommandOutput<unknown>> {
+      const url = new URL(`/rest/api/3/issue/${issue}`, `${options.config.jiraBaseUrl}/`);
+      url.searchParams.set("fields", ISSUE_FIELDS.join(","));
+
+      const raw = (await send("GET", `${url.pathname}${url.search}`)) as Record<string, unknown>;
+
+      return {
+        ok: true,
+        data: {
+          issue: normalizeIssue(options.config, raw),
+        },
+        raw,
+      };
+    },
+
+    async getTransitions(issue: string): Promise<CommandOutput<unknown>> {
+      const raw = (await send(
+        "GET",
+        `/rest/api/3/issue/${issue}/transitions`,
+      )) as { transitions?: Array<Record<string, unknown>> };
+
+      return {
+        ok: true,
+        data: {
+          transitions: (raw.transitions ?? []).map((transition) => ({
+            id: String(transition.id ?? ""),
+            name: String(transition.name ?? ""),
+            toStatus: String(((transition.to ?? {}) as Record<string, unknown>).name ?? ""),
+            hasScreen: Boolean(transition.hasScreen),
+          })),
+        },
+      };
+    },
+
+    async createIssue(input: CreateInput): Promise<CommandOutput<unknown>> {
+      const project = input.project || options.config.defaultProject;
+
+      if (!project) {
+        throw new Error("jira-create requires --project or ATLASSIAN_DEFAULT_PROJECT");
+      }
+
+      const request = createRequest(options.config, "POST", "/rest/api/3/issue", {
+        fields: {
+          project: { key: project },
+          issuetype: { name: input.type },
+          summary: input.summary,
+          ...(input.description ? { description: markdownToAdf(input.description) } : {}),
+        },
+      });
+
+      if (input.dryRun) {
+        return {
+          ok: true,
+          dryRun: true,
+          data: request,
+        };
+      }
+
+      const raw = await send("POST", "/rest/api/3/issue", request.body);
+      return { ok: true, data: raw };
+    },
+
+    async updateIssue(input: UpdateInput): Promise<CommandOutput<unknown>> {
+      const fields: Record<string, unknown> = {};
+
+      if (input.summary) {
+        fields.summary = input.summary;
+      }
+
+      if (input.description) {
+        fields.description = markdownToAdf(input.description);
+      }
+
+      if (Object.keys(fields).length === 0) {
+        throw new Error("jira-update requires --summary and/or --description-file");
+      }
+
+      const request = createRequest(options.config, "PUT", `/rest/api/3/issue/${input.issue}`, {
+        fields,
+      });
+
+      if (input.dryRun) {
+        return {
+          ok: true,
+          dryRun: true,
+          data: request,
+        };
+      }
+
+      await send("PUT", `/rest/api/3/issue/${input.issue}`, request.body);
+      return {
+        ok: true,
+        data: {
+          issue: input.issue,
+          updated: true,
+        },
+      };
+    },
+
+    async commentIssue(input: CommentInput): Promise<CommandOutput<unknown>> {
+      const request = createRequest(options.config, "POST", `/rest/api/3/issue/${input.issue}/comment`, {
+        body: markdownToAdf(input.body),
+      });
+
+      if (input.dryRun) {
+        return {
+          ok: true,
+          dryRun: true,
+          data: request,
+        };
+      }
+
+      const raw = await send("POST", `/rest/api/3/issue/${input.issue}/comment`, request.body);
+      return {
+        ok: true,
+        data: raw,
+      };
+    },
+
+    async transitionIssue(input: TransitionInput): Promise<CommandOutput<unknown>> {
+      const request = createRequest(
+        options.config,
+        "POST",
+        `/rest/api/3/issue/${input.issue}/transitions`,
+        {
+          transition: {
+            id: input.transition,
+          },
+        },
+      );
+
+      if (input.dryRun) {
+        return {
+          ok: true,
+          dryRun: true,
+          data: request,
+        };
+      }
+
+      await send("POST", `/rest/api/3/issue/${input.issue}/transitions`, request.body);
+      return {
+        ok: true,
+        data: {
+          issue: input.issue,
+          transitioned: true,
+          transition: input.transition,
+        },
+      };
+    },
+  };
+}

skills/atlassian/cursor/scripts/src/output.ts

@@ -0,0 +1,44 @@
+import type { CommandOutput, OutputFormat, Writer } from "./types.js";
+
+function renderText(payload: CommandOutput<unknown>) {
+  const data = payload.data as Record<string, unknown>;
+
+  if (Array.isArray(data?.issues)) {
+    return data.issues
+      .map((issue) => {
+        const item = issue as Record<string, string>;
+        return `${item.key} [${item.status}] ${item.issueType} - ${item.summary}`;
+      })
+      .join("\n");
+  }
+
+  if (data?.issue && typeof data.issue === "object") {
+    const issue = data.issue as Record<string, string>;
+    return [
+      issue.key,
+      `${issue.issueType} | ${issue.status}`,
+      issue.summary,
+      issue.url,
+    ].join("\n");
+  }
+
+  if (Array.isArray(data?.transitions)) {
+    return data.transitions
+      .map((transition) => {
+        const item = transition as Record<string, string>;
+        return `${item.id} ${item.name} -> ${item.toStatus}`;
+      })
+      .join("\n");
+  }
+
+  return JSON.stringify(payload, null, 2);
+}
+
+export function writeOutput(
+  writer: Writer,
+  payload: CommandOutput<unknown>,
+  format: OutputFormat = "json",
+) {
+  const body = format === "text" ? renderText(payload) : JSON.stringify(payload, null, 2);
+  writer.write(`${body}\n`);
+}

skills/atlassian/cursor/scripts/src/raw.ts

@@ -0,0 +1,85 @@
+import { readWorkspaceFile } from "./files.js";
+import { sendJsonRequest } from "./http.js";
+import type { AtlassianConfig, CommandOutput, FetchLike } from "./types.js";
+
+const JIRA_ALLOWED_PREFIXES = ["/rest/api/3/"] as const;
+const CONFLUENCE_ALLOWED_PREFIXES = ["/wiki/api/v2/", "/wiki/rest/api/"] as const;
+
+type RawInput = {
+  product: "jira" | "confluence";
+  method: string;
+  path: string;
+  bodyFile?: string;
+  cwd: string;
+  dryRun?: boolean;
+};
+
+function getAllowedPrefixes(product: RawInput["product"]) {
+  return product === "jira" ? JIRA_ALLOWED_PREFIXES : CONFLUENCE_ALLOWED_PREFIXES;
+}
+
+function buildUrl(config: AtlassianConfig, product: RawInput["product"], path: string) {
+  const baseUrl = product === "jira" ? config.jiraBaseUrl : config.confluenceBaseUrl;
+  return new URL(path, `${baseUrl}/`).toString();
+}
+
+function validateMethod(method: string): asserts method is "GET" | "POST" | "PUT" {
+  if (!["GET", "POST", "PUT"].includes(method)) {
+    throw new Error("raw only allows GET, POST, and PUT");
+  }
+}
+
+function validatePath(product: RawInput["product"], path: string) {
+  const allowedPrefixes = getAllowedPrefixes(product);
+
+  if (!allowedPrefixes.some((prefix) => path.startsWith(prefix))) {
+    throw new Error(`raw path is not allowed for ${product}: ${path}`);
+  }
+}
+
+async function readRawBody(bodyFile: string | undefined, cwd: string) {
+  if (!bodyFile) {
+    return undefined;
+  }
+
+  const contents = await readWorkspaceFile(bodyFile, cwd);
+  return JSON.parse(contents) as unknown;
+}
+
+export async function runRawCommand(
+  config: AtlassianConfig,
+  fetchImpl: FetchLike | undefined,
+  input: RawInput,
+): Promise<CommandOutput<unknown>> {
+  validateMethod(input.method);
+  validatePath(input.product, input.path);
+
+  const body = await readRawBody(input.bodyFile, input.cwd);
+  const request = {
+    method: input.method,
+    url: buildUrl(config, input.product, input.path),
+    ...(body === undefined ? {} : { body }),
+  };
+
+  if (input.dryRun) {
+    return {
+      ok: true,
+      dryRun: true,
+      data: request,
+    };
+  }
+
+  const data = await sendJsonRequest({
+    config,
+    fetchImpl,
+    url: request.url,
+    method: input.method,
+    body,
+    errorPrefix: "Raw request failed",
+  });
+
+  return {
+    ok: true,
+    data,
+  };
+}

skills/atlassian/cursor/scripts/src/types.ts

@@ -0,0 +1,35 @@
+export type AtlassianConfig = {
+  baseUrl: string;
+  jiraBaseUrl: string;
+  confluenceBaseUrl: string;
+  email: string;
+  apiToken: string;
+  defaultProject?: string;
+  defaultSpace?: string;
+};
+
+export type CommandOutput<T> = {
+  ok: boolean;
+  data: T;
+  dryRun?: boolean;
+  raw?: unknown;
+};
+
+export type JiraIssueSummary = {
+  key: string;
+  summary: string;
+  issueType: string;
+  status: string;
+  assignee?: string;
+  created: string;
+  updated: string;
+  url: string;
+};
+
+export type Writer = {
+  write(chunk: string | Uint8Array): unknown;
+};
+
+export type FetchLike = typeof fetch;
+
+export type OutputFormat = "json" | "text";

skills/atlassian/cursor/scripts/tsconfig.json

@@ -0,0 +1,15 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "esModuleInterop": true,
+    "forceConsistentCasingInFileNames": true,
+    "strict": true,
+    "skipLibCheck": true,
+    "resolveJsonModule": true,
+    "types": ["node"],
+    "outDir": "dist"
+  },
+  "include": ["src/**/*.ts", "scripts/**/*.ts", "tests/**/*.ts"]
+}

skills/atlassian/opencode/SKILL.md

@@ -0,0 +1,78 @@
+---
+name: atlassian
+description: Interact with Atlassian Cloud Jira and Confluence through a portable task-oriented CLI for search, issue/page edits, comments, transitions, and bounded raw requests.
+---
+
+# Atlassian (OpenCode)
+
+Portable Atlassian workflows for OpenCode using a shared TypeScript CLI.
+
+## Requirements
+
+- Node.js 20+
+- `pnpm`
+- Atlassian Cloud account access
+- `ATLASSIAN_BASE_URL`
+- `ATLASSIAN_EMAIL`
+- `ATLASSIAN_API_TOKEN`
+
+The `ATLASSIAN_*` values may come from the shell environment or a `.env` file in `~/.config/opencode/skills/atlassian/scripts`.
+
+## First-Time Setup
+
+```bash
+mkdir -p ~/.config/opencode/skills/atlassian
+cp -R skills/atlassian/opencode/* ~/.config/opencode/skills/atlassian/
+cd ~/.config/opencode/skills/atlassian/scripts
+pnpm install
+```
+
+## Prerequisite Check (MANDATORY)
+
+```bash
+cd ~/.config/opencode/skills/atlassian/scripts
+node -e "require.resolve('commander');require.resolve('dotenv');console.log('OK: runtime dependencies installed')"
+node -e 'require("dotenv").config({ path: ".env" }); const required = ["ATLASSIAN_BASE_URL", "ATLASSIAN_EMAIL", "ATLASSIAN_API_TOKEN"]; const missing = required.filter((key) => !(process.env[key] || "").trim()); if (missing.length) { console.error("Missing required Atlassian config: " + missing.join(", ")); process.exit(1); } console.log("OK: Atlassian config present")'
+pnpm atlassian health
+```
+
+If any check fails, stop and return:
+
+`Missing dependency/config: atlassian requires installed CLI dependencies and valid Atlassian Cloud credentials. Configure ATLASSIAN_* in the shell environment or scripts/.env, then retry.`
+
+## Supported Commands
+
+- `pnpm atlassian health`
+- `pnpm atlassian jira-search --jql "..."`
+- `pnpm atlassian jira-get --issue ABC-123`
+- `pnpm atlassian jira-create ... [--dry-run]`
+- `pnpm atlassian jira-update ... [--dry-run]`
+- `pnpm atlassian jira-comment ... [--dry-run]`
+- `pnpm atlassian jira-transitions --issue ABC-123`
+- `pnpm atlassian jira-transition ... [--dry-run]`
+- `pnpm atlassian conf-search --query "..."`
+- `pnpm atlassian conf-get --page 12345`
+- `pnpm atlassian conf-create ... [--dry-run]`
+- `pnpm atlassian conf-update ... [--dry-run]`
+- `pnpm atlassian conf-comment ... [--dry-run]`
+- `pnpm atlassian conf-children --page 12345`
+- `pnpm atlassian raw --product jira|confluence --method GET|POST|PUT --path ...`
+
+## Usage Examples
+
+- `pnpm atlassian jira-transition --issue ENG-123 --transition 31 --dry-run`
+- `pnpm atlassian conf-create --space OPS --title "Runbook" --body-file page.storage.html --dry-run`
+- `pnpm atlassian raw --product jira --method GET --path "/rest/api/3/issue/ENG-123"`
+
+## Safety Rules
+
+- Prefer JSON output for machine consumption.
+- Use `--dry-run` on writes unless the user explicitly asks to commit the remote mutation.
+- Restrict `--body-file` to project files.
+- Use `raw` only for unsupported edge cases.
+- `DELETE` is intentionally unsupported in raw mode.
+
+## Notes
+
+- Atlassian Cloud is first-class in v1; Data Center support is future work.
+- The CLI contract is shared across all agent variants so the same usage pattern works everywhere.

skills/atlassian/opencode/scripts/package.json

@@ -0,0 +1,20 @@
+{
+  "name": "atlassian-skill-scripts",
+  "version": "1.0.0",
+  "description": "Shared runtime for the Atlassian skill",
+  "type": "module",
+  "scripts": {
+    "atlassian": "tsx src/cli.ts",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "commander": "^13.1.0",
+    "dotenv": "^16.4.7"
+  },
+  "devDependencies": {
+    "@types/node": "^24.3.0",
+    "tsx": "^4.20.5",
+    "typescript": "^5.9.2"
+  },
+  "packageManager": "pnpm@10.18.1+sha512.77a884a165cbba2d8d1c19e3b4880eee6d2fcabd0d879121e282196b80042351d5eb3ca0935fa599da1dc51265cc68816ad2bddd2a2de5ea9fdf92adbec7cd34"
+}

skills/atlassian/opencode/scripts/pnpm-lock.yaml

@@ -0,0 +1,361 @@
+lockfileVersion: '9.0'
+
+settings:
+  autoInstallPeers: true
+  excludeLinksFromLockfile: false
+
+importers:
+
+  .:
+    dependencies:
+      commander:
+        specifier: ^13.1.0
+        version: 13.1.0
+      dotenv:
+        specifier: ^16.4.7
+        version: 16.6.1
+    devDependencies:
+      '@types/node':
+        specifier: ^24.3.0
+        version: 24.12.0
+      tsx:
+        specifier: ^4.20.5
+        version: 4.21.0
+      typescript:
+        specifier: ^5.9.2
+        version: 5.9.3
+
+packages:
+
+  '@esbuild/aix-ppc64@0.27.3':
+    resolution: {integrity: sha512-9fJMTNFTWZMh5qwrBItuziu834eOCUcEqymSH7pY+zoMVEZg3gcPuBNxH1EvfVYe9h0x/Ptw8KBzv7qxb7l8dg==}
+    engines: {node: '>=18'}
+    cpu: [ppc64]
+    os: [aix]
+
+  '@esbuild/android-arm64@0.27.3':
+    resolution: {integrity: sha512-YdghPYUmj/FX2SYKJ0OZxf+iaKgMsKHVPF1MAq/P8WirnSpCStzKJFjOjzsW0QQ7oIAiccHdcqjbHmJxRb/dmg==}
+    engines: {node: '>=18'}
+    cpu: [arm64]
+    os: [android]
+
+  '@esbuild/android-arm@0.27.3':
+    resolution: {integrity: sha512-i5D1hPY7GIQmXlXhs2w8AWHhenb00+GxjxRncS2ZM7YNVGNfaMxgzSGuO8o8SJzRc/oZwU2bcScvVERk03QhzA==}
+    engines: {node: '>=18'}
+    cpu: [arm]
+    os: [android]
+
+  '@esbuild/android-x64@0.27.3':
+    resolution: {integrity: sha512-IN/0BNTkHtk8lkOM8JWAYFg4ORxBkZQf9zXiEOfERX/CzxW3Vg1ewAhU7QSWQpVIzTW+b8Xy+lGzdYXV6UZObQ==}
+    engines: {node: '>=18'}
+    cpu: [x64]
+    os: [android]
+
+  '@esbuild/darwin-arm64@0.27.3':
+    resolution: {integrity: sha512-Re491k7ByTVRy0t3EKWajdLIr0gz2kKKfzafkth4Q8A5n1xTHrkqZgLLjFEHVD+AXdUGgQMq+Godfq45mGpCKg==}
+    engines: {node: '>=18'}
+    cpu: [arm64]
+    os: [darwin]
+
+  '@esbuild/darwin-x64@0.27.3':
+    resolution: {integrity: sha512-vHk/hA7/1AckjGzRqi6wbo+jaShzRowYip6rt6q7VYEDX4LEy1pZfDpdxCBnGtl+A5zq8iXDcyuxwtv3hNtHFg==}
+    engines: {node: '>=18'}
+    cpu: [x64]
+    os: [darwin]
+
+  '@esbuild/freebsd-arm64@0.27.3':
+    resolution: {integrity: sha512-ipTYM2fjt3kQAYOvo6vcxJx3nBYAzPjgTCk7QEgZG8AUO3ydUhvelmhrbOheMnGOlaSFUoHXB6un+A7q4ygY9w==}
+    engines: {node: '>=18'}
+    cpu: [arm64]
+    os: [freebsd]
+
+  '@esbuild/freebsd-x64@0.27.3':
+    resolution: {integrity: sha512-dDk0X87T7mI6U3K9VjWtHOXqwAMJBNN2r7bejDsc+j03SEjtD9HrOl8gVFByeM0aJksoUuUVU9TBaZa2rgj0oA==}
+    engines: {node: '>=18'}
+    cpu: [x64]
+    os: [freebsd]
+
+  '@esbuild/linux-arm64@0.27.3':
+    resolution: {integrity: sha512-sZOuFz/xWnZ4KH3YfFrKCf1WyPZHakVzTiqji3WDc0BCl2kBwiJLCXpzLzUBLgmp4veFZdvN5ChW4Eq/8Fc2Fg==}
+    engines: {node: '>=18'}
+    cpu: [arm64]
+    os: [linux]
+
+  '@esbuild/linux-arm@0.27.3':
+    resolution: {integrity: sha512-s6nPv2QkSupJwLYyfS+gwdirm0ukyTFNl3KTgZEAiJDd+iHZcbTPPcWCcRYH+WlNbwChgH2QkE9NSlNrMT8Gfw==}
+    engines: {node: '>=18'}
+    cpu: [arm]
+    os: [linux]
+
+  '@esbuild/linux-ia32@0.27.3':
+    resolution: {integrity: sha512-yGlQYjdxtLdh0a3jHjuwOrxQjOZYD/C9PfdbgJJF3TIZWnm/tMd/RcNiLngiu4iwcBAOezdnSLAwQDPqTmtTYg==}
+    engines: {node: '>=18'}
+    cpu: [ia32]
+    os: [linux]
+
+  '@esbuild/linux-loong64@0.27.3':
+    resolution: {integrity: sha512-WO60Sn8ly3gtzhyjATDgieJNet/KqsDlX5nRC5Y3oTFcS1l0KWba+SEa9Ja1GfDqSF1z6hif/SkpQJbL63cgOA==}
+    engines: {node: '>=18'}
+    cpu: [loong64]
+    os: [linux]
+
+  '@esbuild/linux-mips64el@0.27.3':
+    resolution: {integrity: sha512-APsymYA6sGcZ4pD6k+UxbDjOFSvPWyZhjaiPyl/f79xKxwTnrn5QUnXR5prvetuaSMsb4jgeHewIDCIWljrSxw==}
+    engines: {node: '>=18'}
+    cpu: [mips64el]
+    os: [linux]
+
+  '@esbuild/linux-ppc64@0.27.3':
+    resolution: {integrity: sha512-eizBnTeBefojtDb9nSh4vvVQ3V9Qf9Df01PfawPcRzJH4gFSgrObw+LveUyDoKU3kxi5+9RJTCWlj4FjYXVPEA==}
+    engines: {node: '>=18'}
+    cpu: [ppc64]
+    os: [linux]
+
+  '@esbuild/linux-riscv64@0.27.3':
+    resolution: {integrity: sha512-3Emwh0r5wmfm3ssTWRQSyVhbOHvqegUDRd0WhmXKX2mkHJe1SFCMJhagUleMq+Uci34wLSipf8Lagt4LlpRFWQ==}
+    engines: {node: '>=18'}
+    cpu: [riscv64]
+    os: [linux]
+
+  '@esbuild/linux-s390x@0.27.3':
+    resolution: {integrity: sha512-pBHUx9LzXWBc7MFIEEL0yD/ZVtNgLytvx60gES28GcWMqil8ElCYR4kvbV2BDqsHOvVDRrOxGySBM9Fcv744hw==}
+    engines: {node: '>=18'}
+    cpu: [s390x]
+    os: [linux]
+
+  '@esbuild/linux-x64@0.27.3':
+    resolution: {integrity: sha512-Czi8yzXUWIQYAtL/2y6vogER8pvcsOsk5cpwL4Gk5nJqH5UZiVByIY8Eorm5R13gq+DQKYg0+JyQoytLQas4dA==}
+    engines: {node: '>=18'}
+    cpu: [x64]
+    os: [linux]
+
+  '@esbuild/netbsd-arm64@0.27.3':
+    resolution: {integrity: sha512-sDpk0RgmTCR/5HguIZa9n9u+HVKf40fbEUt+iTzSnCaGvY9kFP0YKBWZtJaraonFnqef5SlJ8/TiPAxzyS+UoA==}
+    engines: {node: '>=18'}
+    cpu: [arm64]
+    os: [netbsd]
+
+  '@esbuild/netbsd-x64@0.27.3':
+    resolution: {integrity: sha512-P14lFKJl/DdaE00LItAukUdZO5iqNH7+PjoBm+fLQjtxfcfFE20Xf5CrLsmZdq5LFFZzb5JMZ9grUwvtVYzjiA==}
+    engines: {node: '>=18'}
+    cpu: [x64]
+    os: [netbsd]
+
+  '@esbuild/openbsd-arm64@0.27.3':
+    resolution: {integrity: sha512-AIcMP77AvirGbRl/UZFTq5hjXK+2wC7qFRGoHSDrZ5v5b8DK/GYpXW3CPRL53NkvDqb9D+alBiC/dV0Fb7eJcw==}
+    engines: {node: '>=18'}
+    cpu: [arm64]
+    os: [openbsd]
+
+  '@esbuild/openbsd-x64@0.27.3':
+    resolution: {integrity: sha512-DnW2sRrBzA+YnE70LKqnM3P+z8vehfJWHXECbwBmH/CU51z6FiqTQTHFenPlHmo3a8UgpLyH3PT+87OViOh1AQ==}
+    engines: {node: '>=18'}
+    cpu: [x64]
+    os: [openbsd]
+
+  '@esbuild/openharmony-arm64@0.27.3':
+    resolution: {integrity: sha512-NinAEgr/etERPTsZJ7aEZQvvg/A6IsZG/LgZy+81wON2huV7SrK3e63dU0XhyZP4RKGyTm7aOgmQk0bGp0fy2g==}
+    engines: {node: '>=18'}
+    cpu: [arm64]
+    os: [openharmony]
+
+  '@esbuild/sunos-x64@0.27.3':
+    resolution: {integrity: sha512-PanZ+nEz+eWoBJ8/f8HKxTTD172SKwdXebZ0ndd953gt1HRBbhMsaNqjTyYLGLPdoWHy4zLU7bDVJztF5f3BHA==}
+    engines: {node: '>=18'}
+    cpu: [x64]
+    os: [sunos]
+
+  '@esbuild/win32-arm64@0.27.3':
+    resolution: {integrity: sha512-B2t59lWWYrbRDw/tjiWOuzSsFh1Y/E95ofKz7rIVYSQkUYBjfSgf6oeYPNWHToFRr2zx52JKApIcAS/D5TUBnA==}
+    engines: {node: '>=18'}
+    cpu: [arm64]
+    os: [win32]
+
+  '@esbuild/win32-ia32@0.27.3':
+    resolution: {integrity: sha512-QLKSFeXNS8+tHW7tZpMtjlNb7HKau0QDpwm49u0vUp9y1WOF+PEzkU84y9GqYaAVW8aH8f3GcBck26jh54cX4Q==}
+    engines: {node: '>=18'}
+    cpu: [ia32]
+    os: [win32]
+
+  '@esbuild/win32-x64@0.27.3':
+    resolution: {integrity: sha512-4uJGhsxuptu3OcpVAzli+/gWusVGwZZHTlS63hh++ehExkVT8SgiEf7/uC/PclrPPkLhZqGgCTjd0VWLo6xMqA==}
+    engines: {node: '>=18'}
+    cpu: [x64]
+    os: [win32]
+
+  '@types/node@24.12.0':
+    resolution: {integrity: sha512-GYDxsZi3ChgmckRT9HPU0WEhKLP08ev/Yfcq2AstjrDASOYCSXeyjDsHg4v5t4jOj7cyDX3vmprafKlWIG9MXQ==}
+
+  commander@13.1.0:
+    resolution: {integrity: sha512-/rFeCpNJQbhSZjGVwO9RFV3xPqbnERS8MmIQzCtD/zl6gpJuV/bMLuN92oG3F7d8oDEHHRrujSXNUr8fpjntKw==}
+    engines: {node: '>=18'}
+
+  dotenv@16.6.1:
+    resolution: {integrity: sha512-uBq4egWHTcTt33a72vpSG0z3HnPuIl6NqYcTrKEg2azoEyl2hpW0zqlxysq2pK9HlDIHyHyakeYaYnSAwd8bow==}
+    engines: {node: '>=12'}
+
+  esbuild@0.27.3:
+    resolution: {integrity: sha512-8VwMnyGCONIs6cWue2IdpHxHnAjzxnw2Zr7MkVxB2vjmQ2ivqGFb4LEG3SMnv0Gb2F/G/2yA8zUaiL1gywDCCg==}
+    engines: {node: '>=18'}
+    hasBin: true
+
+  fsevents@2.3.3:
+    resolution: {integrity: sha512-5xoDfX+fL7faATnagmWPpbFtwh/R77WmMMqqHGS65C3vvB0YHrgF+B1YmZ3441tMj5n63k0212XNoJwzlhffQw==}
+    engines: {node: ^8.16.0 || ^10.6.0 || >=11.0.0}
+    os: [darwin]
+
+  get-tsconfig@4.13.6:
+    resolution: {integrity: sha512-shZT/QMiSHc/YBLxxOkMtgSid5HFoauqCE3/exfsEcwg1WkeqjG+V40yBbBrsD+jW2HDXcs28xOfcbm2jI8Ddw==}
+
+  resolve-pkg-maps@1.0.0:
+    resolution: {integrity: sha512-seS2Tj26TBVOC2NIc2rOe2y2ZO7efxITtLZcGSOnHHNOQ7CkiUBfw0Iw2ck6xkIhPwLhKNLS8BO+hEpngQlqzw==}
+
+  tsx@4.21.0:
+    resolution: {integrity: sha512-5C1sg4USs1lfG0GFb2RLXsdpXqBSEhAaA/0kPL01wxzpMqLILNxIxIOKiILz+cdg/pLnOUxFYOR5yhHU666wbw==}
+    engines: {node: '>=18.0.0'}
+    hasBin: true
+
+  typescript@5.9.3:
+    resolution: {integrity: sha512-jl1vZzPDinLr9eUt3J/t7V6FgNEw9QjvBPdysz9KfQDD41fQrC2Y4vKQdiaUpFT4bXlb1RHhLpp8wtm6M5TgSw==}
+    engines: {node: '>=14.17'}
+    hasBin: true
+
+  undici-types@7.16.0:
+    resolution: {integrity: sha512-Zz+aZWSj8LE6zoxD+xrjh4VfkIG8Ya6LvYkZqtUQGJPZjYl53ypCaUwWqo7eI0x66KBGeRo+mlBEkMSeSZ38Nw==}
+
+snapshots:
+
+  '@esbuild/aix-ppc64@0.27.3':
+    optional: true
+
+  '@esbuild/android-arm64@0.27.3':
+    optional: true
+
+  '@esbuild/android-arm@0.27.3':
+    optional: true
+
+  '@esbuild/android-x64@0.27.3':
+    optional: true
+
+  '@esbuild/darwin-arm64@0.27.3':
+    optional: true
+
+  '@esbuild/darwin-x64@0.27.3':
+    optional: true
+
+  '@esbuild/freebsd-arm64@0.27.3':
+    optional: true
+
+  '@esbuild/freebsd-x64@0.27.3':
+    optional: true
+
+  '@esbuild/linux-arm64@0.27.3':
+    optional: true
+
+  '@esbuild/linux-arm@0.27.3':
+    optional: true
+
+  '@esbuild/linux-ia32@0.27.3':
+    optional: true
+
+  '@esbuild/linux-loong64@0.27.3':
+    optional: true
+
+  '@esbuild/linux-mips64el@0.27.3':
+    optional: true
+
+  '@esbuild/linux-ppc64@0.27.3':
+    optional: true
+
+  '@esbuild/linux-riscv64@0.27.3':
+    optional: true
+
+  '@esbuild/linux-s390x@0.27.3':
+    optional: true
+
+  '@esbuild/linux-x64@0.27.3':
+    optional: true
+
+  '@esbuild/netbsd-arm64@0.27.3':
+    optional: true
+
+  '@esbuild/netbsd-x64@0.27.3':
+    optional: true
+
+  '@esbuild/openbsd-arm64@0.27.3':
+    optional: true
+
+  '@esbuild/openbsd-x64@0.27.3':
+    optional: true
+
+  '@esbuild/openharmony-arm64@0.27.3':
+    optional: true
+
+  '@esbuild/sunos-x64@0.27.3':
+    optional: true
+
+  '@esbuild/win32-arm64@0.27.3':
+    optional: true
+
+  '@esbuild/win32-ia32@0.27.3':
+    optional: true
+
+  '@esbuild/win32-x64@0.27.3':
+    optional: true
+
+  '@types/node@24.12.0':
+    dependencies:
+      undici-types: 7.16.0
+
+  commander@13.1.0: {}
+
+  dotenv@16.6.1: {}
+
+  esbuild@0.27.3:
+    optionalDependencies:
+      '@esbuild/aix-ppc64': 0.27.3
+      '@esbuild/android-arm': 0.27.3
+      '@esbuild/android-arm64': 0.27.3
+      '@esbuild/android-x64': 0.27.3
+      '@esbuild/darwin-arm64': 0.27.3
+      '@esbuild/darwin-x64': 0.27.3
+      '@esbuild/freebsd-arm64': 0.27.3
+      '@esbuild/freebsd-x64': 0.27.3
+      '@esbuild/linux-arm': 0.27.3
+      '@esbuild/linux-arm64': 0.27.3
+      '@esbuild/linux-ia32': 0.27.3
+      '@esbuild/linux-loong64': 0.27.3
+      '@esbuild/linux-mips64el': 0.27.3
+      '@esbuild/linux-ppc64': 0.27.3
+      '@esbuild/linux-riscv64': 0.27.3
+      '@esbuild/linux-s390x': 0.27.3
+      '@esbuild/linux-x64': 0.27.3
+      '@esbuild/netbsd-arm64': 0.27.3
+      '@esbuild/netbsd-x64': 0.27.3
+      '@esbuild/openbsd-arm64': 0.27.3
+      '@esbuild/openbsd-x64': 0.27.3
+      '@esbuild/openharmony-arm64': 0.27.3
+      '@esbuild/sunos-x64': 0.27.3
+      '@esbuild/win32-arm64': 0.27.3
+      '@esbuild/win32-ia32': 0.27.3
+      '@esbuild/win32-x64': 0.27.3
+
+  fsevents@2.3.3:
+    optional: true
+
+  get-tsconfig@4.13.6:
+    dependencies:
+      resolve-pkg-maps: 1.0.0
+
+  resolve-pkg-maps@1.0.0: {}
+
+  tsx@4.21.0:
+    dependencies:
+      esbuild: 0.27.3
+      get-tsconfig: 4.13.6
+    optionalDependencies:
+      fsevents: 2.3.3
+
+  typescript@5.9.3: {}
+
+  undici-types@7.16.0: {}

skills/atlassian/opencode/scripts/src/adf.ts

@@ -0,0 +1,92 @@
+const TEXT_NODE = "text";
+
+function textNode(text: string) {
+  return {
+    type: TEXT_NODE,
+    text,
+  };
+}
+
+function paragraphNode(lines: string[]) {
+  const content: Array<{ type: string; text?: string }> = [];
+
+  lines.forEach((line, index) => {
+    if (index > 0) {
+      content.push({ type: "hardBreak" });
+    }
+
+    if (line.length > 0) {
+      content.push(textNode(line));
+    }
+  });
+
+  return {
+    type: "paragraph",
+    ...(content.length > 0 ? { content } : {}),
+  };
+}
+
+export function markdownToAdf(input: string) {
+  const lines = input.replace(/\r\n/g, "\n").split("\n");
+  const content: Array<Record<string, unknown>> = [];
+  let index = 0;
+
+  while (index < lines.length) {
+    const current = lines[index]?.trimEnd() ?? "";
+
+    if (current.trim().length === 0) {
+      index += 1;
+      continue;
+    }
+
+    const heading = current.match(/^(#{1,6})\s+(.*)$/);
+
+    if (heading) {
+      content.push({
+        type: "heading",
+        attrs: { level: heading[1].length },
+        content: [textNode(heading[2])],
+      });
+      index += 1;
+      continue;
+    }
+
+    if (/^[-*]\s+/.test(current)) {
+      const items: Array<Record<string, unknown>> = [];
+
+      while (index < lines.length && /^[-*]\s+/.test(lines[index] ?? "")) {
+        items.push({
+          type: "listItem",
+          content: [
+            {
+              type: "paragraph",
+              content: [textNode((lines[index] ?? "").replace(/^[-*]\s+/, ""))],
+            },
+          ],
+        });
+        index += 1;
+      }
+
+      content.push({
+        type: "bulletList",
+        content: items,
+      });
+      continue;
+    }
+
+    const paragraphLines: string[] = [];
+
+    while (index < lines.length && (lines[index]?.trim().length ?? 0) > 0) {
+      paragraphLines.push(lines[index] ?? "");
+      index += 1;
+    }
+
+    content.push(paragraphNode(paragraphLines));
+  }
+
+  return {
+    type: "doc",
+    version: 1,
+    content,
+  };
+}

skills/atlassian/opencode/scripts/src/cli.ts

@@ -0,0 +1,332 @@
+import process from "node:process";
+import { pathToFileURL } from "node:url";
+
+import { Command } from "commander";
+
+import { createConfluenceClient } from "./confluence.js";
+import { loadConfig } from "./config.js";
+import { readWorkspaceFile } from "./files.js";
+import { runHealthCheck } from "./health.js";
+import { createJiraClient } from "./jira.js";
+import { writeOutput } from "./output.js";
+import { runRawCommand } from "./raw.js";
+import type { FetchLike, OutputFormat, Writer } from "./types.js";
+
+type CliContext = {
+  cwd?: string;
+  env?: NodeJS.ProcessEnv;
+  fetchImpl?: FetchLike;
+  stdout?: Writer;
+  stderr?: Writer;
+};
+
+function resolveFormat(format: string | undefined): OutputFormat {
+  return format === "text" ? "text" : "json";
+}
+
+function createRuntime(context: CliContext) {
+  const cwd = context.cwd ?? process.cwd();
+  const env = context.env ?? process.env;
+  const stdout = context.stdout ?? process.stdout;
+  const stderr = context.stderr ?? process.stderr;
+  let configCache: ReturnType<typeof loadConfig> | undefined;
+  let jiraCache: ReturnType<typeof createJiraClient> | undefined;
+  let confluenceCache: ReturnType<typeof createConfluenceClient> | undefined;
+
+  function getConfig() {
+    configCache ??= loadConfig(env, { cwd });
+    return configCache;
+  }
+
+  function getJiraClient() {
+    jiraCache ??= createJiraClient({
+      config: getConfig(),
+      fetchImpl: context.fetchImpl,
+    });
+    return jiraCache;
+  }
+
+  function getConfluenceClient() {
+    confluenceCache ??= createConfluenceClient({
+      config: getConfig(),
+      fetchImpl: context.fetchImpl,
+    });
+    return confluenceCache;
+  }
+
+  async function readBodyFile(filePath: string | undefined) {
+    if (!filePath) {
+      return undefined;
+    }
+
+    return readWorkspaceFile(filePath, cwd);
+  }
+
+  return {
+    cwd,
+    stdout,
+    stderr,
+    readBodyFile,
+    getConfig,
+    getJiraClient,
+    getConfluenceClient,
+    fetchImpl: context.fetchImpl,
+  };
+}
+
+export function buildProgram(context: CliContext = {}) {
+  const runtime = createRuntime(context);
+  const program = new Command()
+    .name("atlassian")
+    .description("Portable Atlassian CLI for multi-agent skills")
+    .version("0.1.0");
+
+  program
+    .command("health")
+    .description("Validate configuration and Atlassian connectivity")
+    .option("--format <format>", "Output format", "json")
+    .action(async (options) => {
+      const payload = await runHealthCheck(runtime.getConfig(), runtime.fetchImpl);
+      writeOutput(
+        runtime.stdout,
+        payload,
+        resolveFormat(options.format),
+      );
+    });
+
+  program
+    .command("conf-search")
+    .requiredOption("--query <query>", "CQL search query")
+    .option("--max-results <number>", "Maximum results to return", "50")
+    .option("--start-at <number>", "Result offset", "0")
+    .option("--format <format>", "Output format", "json")
+    .action(async (options) => {
+      const payload = await runtime.getConfluenceClient().searchPages({
+        query: options.query,
+        maxResults: Number(options.maxResults),
+        startAt: Number(options.startAt),
+      });
+
+      writeOutput(runtime.stdout, payload, resolveFormat(options.format));
+    });
+
+  program
+    .command("conf-get")
+    .requiredOption("--page <page>", "Confluence page ID")
+    .option("--format <format>", "Output format", "json")
+    .action(async (options) => {
+      const payload = await runtime.getConfluenceClient().getPage(options.page);
+      writeOutput(runtime.stdout, payload, resolveFormat(options.format));
+    });
+
+  program
+    .command("conf-create")
+    .requiredOption("--title <title>", "Confluence page title")
+    .requiredOption("--body-file <path>", "Workspace-relative storage-format body file")
+    .option("--space <space>", "Confluence space ID")
+    .option("--dry-run", "Print the request without sending it")
+    .option("--format <format>", "Output format", "json")
+    .action(async (options) => {
+      const payload = await runtime.getConfluenceClient().createPage({
+        space: options.space,
+        title: options.title,
+        body: (await runtime.readBodyFile(options.bodyFile)) as string,
+        dryRun: Boolean(options.dryRun),
+      });
+
+      writeOutput(runtime.stdout, payload, resolveFormat(options.format));
+    });
+
+  program
+    .command("conf-update")
+    .requiredOption("--page <page>", "Confluence page ID")
+    .requiredOption("--title <title>", "Confluence page title")
+    .requiredOption("--body-file <path>", "Workspace-relative storage-format body file")
+    .option("--dry-run", "Print the request without sending it")
+    .option("--format <format>", "Output format", "json")
+    .action(async (options) => {
+      const payload = await runtime.getConfluenceClient().updatePage({
+        pageId: options.page,
+        title: options.title,
+        body: (await runtime.readBodyFile(options.bodyFile)) as string,
+        dryRun: Boolean(options.dryRun),
+      });
+
+      writeOutput(runtime.stdout, payload, resolveFormat(options.format));
+    });
+
+  program
+    .command("conf-comment")
+    .requiredOption("--page <page>", "Confluence page ID")
+    .requiredOption("--body-file <path>", "Workspace-relative storage-format body file")
+    .option("--dry-run", "Print the request without sending it")
+    .option("--format <format>", "Output format", "json")
+    .action(async (options) => {
+      const payload = await runtime.getConfluenceClient().commentPage({
+        pageId: options.page,
+        body: (await runtime.readBodyFile(options.bodyFile)) as string,
+        dryRun: Boolean(options.dryRun),
+      });
+
+      writeOutput(runtime.stdout, payload, resolveFormat(options.format));
+    });
+
+  program
+    .command("conf-children")
+    .requiredOption("--page <page>", "Confluence page ID")
+    .option("--max-results <number>", "Maximum results to return", "50")
+    .option("--start-at <number>", "Cursor/start token", "0")
+    .option("--format <format>", "Output format", "json")
+    .action(async (options) => {
+      const payload = await runtime.getConfluenceClient().listChildren(
+        options.page,
+        Number(options.maxResults),
+        Number(options.startAt),
+      );
+
+      writeOutput(runtime.stdout, payload, resolveFormat(options.format));
+    });
+
+  program
+    .command("raw")
+    .requiredOption("--product <product>", "jira or confluence")
+    .requiredOption("--method <method>", "GET, POST, or PUT")
+    .requiredOption("--path <path>", "Validated API path")
+    .option("--body-file <path>", "Workspace-relative JSON file")
+    .option("--dry-run", "Print the request without sending it")
+    .option("--format <format>", "Output format", "json")
+    .action(async (options) => {
+      const payload = await runRawCommand(runtime.getConfig(), runtime.fetchImpl, {
+        product: options.product,
+        method: String(options.method).toUpperCase(),
+        path: options.path,
+        bodyFile: options.bodyFile,
+        cwd: runtime.cwd,
+        dryRun: Boolean(options.dryRun),
+      });
+
+      writeOutput(runtime.stdout, payload, resolveFormat(options.format));
+    });
+
+  program
+    .command("jira-search")
+    .requiredOption("--jql <jql>", "JQL expression to execute")
+    .option("--max-results <number>", "Maximum results to return", "50")
+    .option("--start-at <number>", "Result offset", "0")
+    .option("--format <format>", "Output format", "json")
+    .action(async (options) => {
+      const payload = await runtime.getJiraClient().searchIssues({
+        jql: options.jql,
+        maxResults: Number(options.maxResults),
+        startAt: Number(options.startAt),
+      });
+
+      writeOutput(runtime.stdout, payload, resolveFormat(options.format));
+    });
+
+  program
+    .command("jira-get")
+    .requiredOption("--issue <issue>", "Issue key")
+    .option("--format <format>", "Output format", "json")
+    .action(async (options) => {
+      const payload = await runtime.getJiraClient().getIssue(options.issue);
+      writeOutput(runtime.stdout, payload, resolveFormat(options.format));
+    });
+
+  program
+    .command("jira-create")
+    .requiredOption("--type <type>", "Issue type name")
+    .requiredOption("--summary <summary>", "Issue summary")
+    .option("--project <project>", "Project key")
+    .option("--description-file <path>", "Workspace-relative markdown/text file")
+    .option("--dry-run", "Print the request without sending it")
+    .option("--format <format>", "Output format", "json")
+    .action(async (options) => {
+      const payload = await runtime.getJiraClient().createIssue({
+        project: options.project,
+        type: options.type,
+        summary: options.summary,
+        description: await runtime.readBodyFile(options.descriptionFile),
+        dryRun: Boolean(options.dryRun),
+      });
+
+      writeOutput(runtime.stdout, payload, resolveFormat(options.format));
+    });
+
+  program
+    .command("jira-update")
+    .requiredOption("--issue <issue>", "Issue key")
+    .option("--summary <summary>", "Updated summary")
+    .option("--description-file <path>", "Workspace-relative markdown/text file")
+    .option("--dry-run", "Print the request without sending it")
+    .option("--format <format>", "Output format", "json")
+    .action(async (options) => {
+      const payload = await runtime.getJiraClient().updateIssue({
+        issue: options.issue,
+        summary: options.summary,
+        description: await runtime.readBodyFile(options.descriptionFile),
+        dryRun: Boolean(options.dryRun),
+      });
+
+      writeOutput(runtime.stdout, payload, resolveFormat(options.format));
+    });
+
+  program
+    .command("jira-comment")
+    .requiredOption("--issue <issue>", "Issue key")
+    .requiredOption("--body-file <path>", "Workspace-relative markdown/text file")
+    .option("--dry-run", "Print the request without sending it")
+    .option("--format <format>", "Output format", "json")
+    .action(async (options) => {
+      const payload = await runtime.getJiraClient().commentIssue({
+        issue: options.issue,
+        body: (await runtime.readBodyFile(options.bodyFile)) as string,
+        dryRun: Boolean(options.dryRun),
+      });
+
+      writeOutput(runtime.stdout, payload, resolveFormat(options.format));
+    });
+
+  program
+    .command("jira-transitions")
+    .requiredOption("--issue <issue>", "Issue key")
+    .option("--format <format>", "Output format", "json")
+    .action(async (options) => {
+      const payload = await runtime.getJiraClient().getTransitions(options.issue);
+      writeOutput(runtime.stdout, payload, resolveFormat(options.format));
+    });
+
+  program
+    .command("jira-transition")
+    .requiredOption("--issue <issue>", "Issue key")
+    .requiredOption("--transition <transition>", "Transition ID")
+    .option("--dry-run", "Print the request without sending it")
+    .option("--format <format>", "Output format", "json")
+    .action(async (options) => {
+      const payload = await runtime.getJiraClient().transitionIssue({
+        issue: options.issue,
+        transition: options.transition,
+        dryRun: Boolean(options.dryRun),
+      });
+
+      writeOutput(runtime.stdout, payload, resolveFormat(options.format));
+    });
+
+  return program;
+}
+
+export async function runCli(argv = process.argv, context: CliContext = {}) {
+  const program = buildProgram(context);
+  await program.parseAsync(argv);
+}
+
+const isDirectExecution =
+  Boolean(process.argv[1]) && import.meta.url === pathToFileURL(process.argv[1]).href;
+
+if (isDirectExecution) {
+  runCli().catch((error: unknown) => {
+    const message = error instanceof Error ? error.message : String(error);
+    process.stderr.write(`${message}\n`);
+    process.exitCode = 1;
+  });
+}

skills/atlassian/opencode/scripts/src/config.ts

@@ -0,0 +1,52 @@
+import path from "node:path";
+
+import { config as loadDotEnv } from "dotenv";
+
+import type { AtlassianConfig } from "./types.js";
+
+function normalizeBaseUrl(value: string) {
+  return value.replace(/\/+$/, "");
+}
+
+function readRequired(env: NodeJS.ProcessEnv, key: string) {
+  const value = env[key]?.trim();
+
+  if (!value) {
+    throw new Error(`Missing required environment variable: ${key}`);
+  }
+
+  return value;
+}
+
+export function loadConfig(
+  env: NodeJS.ProcessEnv = process.env,
+  options?: {
+    cwd?: string;
+  },
+): AtlassianConfig {
+  loadDotEnv({
+    path: path.resolve(options?.cwd ?? process.cwd(), ".env"),
+    processEnv: env as Record<string, string>,
+    override: false,
+  });
+
+  const baseUrl = normalizeBaseUrl(readRequired(env, "ATLASSIAN_BASE_URL"));
+
+  return {
+    baseUrl,
+    jiraBaseUrl: normalizeBaseUrl(env.ATLASSIAN_JIRA_BASE_URL?.trim() || baseUrl),
+    confluenceBaseUrl: normalizeBaseUrl(env.ATLASSIAN_CONFLUENCE_BASE_URL?.trim() || baseUrl),
+    email: readRequired(env, "ATLASSIAN_EMAIL"),
+    apiToken: readRequired(env, "ATLASSIAN_API_TOKEN"),
+    defaultProject: env.ATLASSIAN_DEFAULT_PROJECT?.trim() || undefined,
+    defaultSpace: env.ATLASSIAN_DEFAULT_SPACE?.trim() || undefined,
+  };
+}
+
+export function createBasicAuthHeader(config: {
+  email: string;
+  apiToken: string;
+  [key: string]: unknown;
+}) {
+  return `Basic ${Buffer.from(`${config.email}:${config.apiToken}`).toString("base64")}`;
+}

skills/atlassian/opencode/scripts/src/confluence.ts

@@ -0,0 +1,292 @@
+import { sendJsonRequest } from "./http.js";
+import type { AtlassianConfig, CommandOutput, FetchLike } from "./types.js";
+
+type ConfluenceClientOptions = {
+  config: AtlassianConfig;
+  fetchImpl?: FetchLike;
+};
+
+type SearchInput = {
+  query: string;
+  maxResults: number;
+  startAt: number;
+};
+
+type CreateInput = {
+  space?: string;
+  title: string;
+  body: string;
+  dryRun?: boolean;
+};
+
+type UpdateInput = {
+  pageId: string;
+  title: string;
+  body: string;
+  dryRun?: boolean;
+};
+
+type CommentInput = {
+  pageId: string;
+  body: string;
+  dryRun?: boolean;
+};
+
+type PageSummary = {
+  id: string;
+  title: string;
+  type: string;
+  status?: string;
+  spaceId?: string;
+  url?: string;
+};
+
+function buildUrl(baseUrl: string, path: string) {
+  return new URL(path, `${baseUrl}/`).toString();
+}
+
+function normalizePage(baseUrl: string, page: Record<string, unknown>, excerpt?: string) {
+  const links = (page._links ?? {}) as Record<string, unknown>;
+
+  return {
+    id: String(page.id ?? ""),
+    title: String(page.title ?? ""),
+    type: String(page.type ?? "page"),
+    ...(page.status ? { status: String(page.status) } : {}),
+    ...(page.spaceId ? { spaceId: String(page.spaceId) } : {}),
+    ...(excerpt ? { excerpt } : {}),
+    ...(links.webui ? { url: `${baseUrl}${String(links.webui)}` } : {}),
+  };
+}
+
+export function createConfluenceClient(options: ConfluenceClientOptions) {
+  const config = options.config;
+
+  async function getPageForUpdate(pageId: string) {
+    return (await sendJsonRequest({
+      config,
+      fetchImpl: options.fetchImpl,
+      url: buildUrl(config.confluenceBaseUrl, `/wiki/api/v2/pages/${pageId}?body-format=storage`),
+      method: "GET",
+      errorPrefix: "Confluence request failed",
+    })) as Record<string, unknown>;
+  }
+
+  return {
+    async searchPages(input: SearchInput): Promise<CommandOutput<unknown>> {
+      const url = new URL("/wiki/rest/api/search", `${config.confluenceBaseUrl}/`);
+      url.searchParams.set("cql", input.query);
+      url.searchParams.set("limit", String(input.maxResults));
+      url.searchParams.set("start", String(input.startAt));
+
+      const raw = (await sendJsonRequest({
+        config,
+        fetchImpl: options.fetchImpl,
+        url: url.toString(),
+        method: "GET",
+        errorPrefix: "Confluence request failed",
+      })) as Record<string, unknown>;
+
+      const results = Array.isArray(raw.results) ? raw.results : [];
+
+      return {
+        ok: true,
+        data: {
+          pages: results.map((entry) => {
+            const result = entry as Record<string, unknown>;
+            return normalizePage(
+              config.baseUrl,
+              (result.content ?? {}) as Record<string, unknown>,
+              result.excerpt ? String(result.excerpt) : undefined,
+            );
+          }),
+          startAt: Number(raw.start ?? input.startAt),
+          maxResults: Number(raw.limit ?? input.maxResults),
+          total: Number(raw.totalSize ?? raw.size ?? results.length),
+        },
+      };
+    },
+
+    async getPage(pageId: string): Promise<CommandOutput<unknown>> {
+      const raw = (await sendJsonRequest({
+        config,
+        fetchImpl: options.fetchImpl,
+        url: buildUrl(config.confluenceBaseUrl, `/wiki/api/v2/pages/${pageId}?body-format=storage`),
+        method: "GET",
+        errorPrefix: "Confluence request failed",
+      })) as Record<string, unknown>;
+
+      const body = ((raw.body ?? {}) as Record<string, unknown>).storage as Record<string, unknown> | undefined;
+
+      return {
+        ok: true,
+        data: {
+          page: {
+            ...normalizePage(config.baseUrl, raw),
+            version: Number((((raw.version ?? {}) as Record<string, unknown>).number ?? 0)),
+            body: body?.value ? String(body.value) : "",
+          },
+        },
+        raw,
+      };
+    },
+
+    async listChildren(pageId: string, maxResults: number, startAt: number): Promise<CommandOutput<unknown>> {
+      const url = new URL(`/wiki/api/v2/pages/${pageId}/direct-children`, `${config.confluenceBaseUrl}/`);
+      url.searchParams.set("limit", String(maxResults));
+      url.searchParams.set("cursor", String(startAt));
+
+      const raw = (await sendJsonRequest({
+        config,
+        fetchImpl: options.fetchImpl,
+        url: url.toString(),
+        method: "GET",
+        errorPrefix: "Confluence request failed",
+      })) as Record<string, unknown>;
+
+      const results = Array.isArray(raw.results) ? raw.results : [];
+      const links = (raw._links ?? {}) as Record<string, unknown>;
+
+      return {
+        ok: true,
+        data: {
+          pages: results.map((page) => normalizePage(config.baseUrl, page as Record<string, unknown>)),
+          nextCursor: links.next ? String(links.next) : null,
+        },
+      };
+    },
+
+    async createPage(input: CreateInput): Promise<CommandOutput<unknown>> {
+      const spaceId = input.space || config.defaultSpace;
+
+      if (!spaceId) {
+        throw new Error("conf-create requires --space or ATLASSIAN_DEFAULT_SPACE");
+      }
+
+      const request = {
+        method: "POST" as const,
+        url: buildUrl(config.confluenceBaseUrl, "/wiki/api/v2/pages"),
+        body: {
+          spaceId,
+          title: input.title,
+          status: "current",
+          body: {
+            representation: "storage",
+            value: input.body,
+          },
+        },
+      };
+
+      if (input.dryRun) {
+        return {
+          ok: true,
+          dryRun: true,
+          data: request,
+        };
+      }
+
+      const raw = await sendJsonRequest({
+        config,
+        fetchImpl: options.fetchImpl,
+        url: request.url,
+        method: request.method,
+        body: request.body,
+        errorPrefix: "Confluence request failed",
+      });
+
+      return {
+        ok: true,
+        data: raw,
+      };
+    },
+
+    async updatePage(input: UpdateInput): Promise<CommandOutput<unknown>> {
+      const currentPage = await getPageForUpdate(input.pageId);
+      const version = (((currentPage.version ?? {}) as Record<string, unknown>).number ?? 0) as number;
+      const spaceId = String(currentPage.spaceId ?? "");
+
+      const request = {
+        method: "PUT" as const,
+        url: buildUrl(config.confluenceBaseUrl, `/wiki/api/v2/pages/${input.pageId}`),
+        body: {
+          id: input.pageId,
+          status: String(currentPage.status ?? "current"),
+          title: input.title,
+          spaceId,
+          version: {
+            number: Number(version) + 1,
+          },
+          body: {
+            representation: "storage",
+            value: input.body,
+          },
+        },
+      };
+
+      if (input.dryRun) {
+        return {
+          ok: true,
+          dryRun: true,
+          data: request,
+        };
+      }
+
+      const raw = await sendJsonRequest({
+        config,
+        fetchImpl: options.fetchImpl,
+        url: request.url,
+        method: request.method,
+        body: request.body,
+        errorPrefix: "Confluence request failed",
+        handleResponseError(response) {
+          if (response.status === 409) {
+            return new Error(`Confluence update conflict: page ${input.pageId} was updated by someone else`);
+          }
+
+          return undefined;
+        },
+      });
+
+      return {
+        ok: true,
+        data: raw,
+      };
+    },
+
+    async commentPage(input: CommentInput): Promise<CommandOutput<unknown>> {
+      const request = {
+        method: "POST" as const,
+        url: buildUrl(config.confluenceBaseUrl, "/wiki/api/v2/footer-comments"),
+        body: {
+          pageId: input.pageId,
+          body: {
+            representation: "storage",
+            value: input.body,
+          },
+        },
+      };
+
+      if (input.dryRun) {
+        return {
+          ok: true,
+          dryRun: true,
+          data: request,
+        };
+      }
+
+      const raw = await sendJsonRequest({
+        config,
+        fetchImpl: options.fetchImpl,
+        url: request.url,
+        method: request.method,
+        body: request.body,
+        errorPrefix: "Confluence request failed",
+      });
+
+      return {
+        ok: true,
+        data: raw,
+      };
+    },
+  };
+}

skills/atlassian/opencode/scripts/src/files.ts

@@ -0,0 +1,13 @@
+import { readFile } from "node:fs/promises";
+import path from "node:path";
+
+export async function readWorkspaceFile(filePath: string, cwd: string) {
+  const resolved = path.resolve(cwd, filePath);
+  const relative = path.relative(cwd, resolved);
+
+  if (relative.startsWith("..") || path.isAbsolute(relative)) {
+    throw new Error(`--body-file must stay within the active workspace: ${filePath}`);
+  }
+
+  return readFile(resolved, "utf8");
+}

skills/atlassian/opencode/scripts/src/health.ts

@@ -0,0 +1,69 @@
+import { createJsonHeaders, createStatusError } from "./http.js";
+import type { AtlassianConfig, CommandOutput, FetchLike } from "./types.js";
+
+type ProductHealth = {
+  ok: boolean;
+  status?: number;
+  message?: string;
+};
+
+function buildUrl(baseUrl: string, path: string) {
+  return new URL(path, `${baseUrl}/`).toString();
+}
+
+export async function runHealthCheck(
+  config: AtlassianConfig,
+  fetchImpl: FetchLike | undefined,
+): Promise<CommandOutput<unknown>> {
+  const client = fetchImpl ?? globalThis.fetch;
+
+  if (!client) {
+    throw new Error("Fetch API is not available in this runtime");
+  }
+
+  async function probe(product: "Jira" | "Confluence", url: string): Promise<ProductHealth> {
+    try {
+      const response = await client(url, {
+        method: "GET",
+        headers: createJsonHeaders(config, false),
+      });
+
+      if (!response.ok) {
+        const error = createStatusError(`${product} health check failed`, response);
+        return {
+          ok: false,
+          status: response.status,
+          message: error.message,
+        };
+      }
+
+      return {
+        ok: true,
+        status: response.status,
+      };
+    } catch (error: unknown) {
+      return {
+        ok: false,
+        message: error instanceof Error ? error.message : String(error),
+      };
+    }
+  }
+
+  const jira = await probe("Jira", buildUrl(config.jiraBaseUrl, "/rest/api/3/myself"));
+  const confluence = await probe("Confluence", buildUrl(config.confluenceBaseUrl, "/wiki/api/v2/spaces?limit=1"));
+
+  return {
+    ok: jira.ok && confluence.ok,
+    data: {
+      baseUrl: config.baseUrl,
+      jiraBaseUrl: config.jiraBaseUrl,
+      confluenceBaseUrl: config.confluenceBaseUrl,
+      defaultProject: config.defaultProject,
+      defaultSpace: config.defaultSpace,
+      products: {
+        jira,
+        confluence,
+      },
+    },
+  };
+}

skills/atlassian/opencode/scripts/src/http.ts

@@ -0,0 +1,86 @@
+import { createBasicAuthHeader } from "./config.js";
+import type { AtlassianConfig, FetchLike } from "./types.js";
+
+export type HttpMethod = "GET" | "POST" | "PUT";
+
+export function createJsonHeaders(config: AtlassianConfig, includeJsonBody: boolean) {
+  const headers: Array<[string, string]> = [
+    ["Accept", "application/json"],
+    ["Authorization", createBasicAuthHeader(config)],
+  ];
+
+  if (includeJsonBody) {
+    headers.push(["Content-Type", "application/json"]);
+  }
+
+  return headers;
+}
+
+export async function parseResponse(response: Response) {
+  if (response.status === 204) {
+    return null;
+  }
+
+  const contentType = response.headers.get("content-type") ?? "";
+
+  if (contentType.includes("application/json")) {
+    try {
+      return await response.json();
+    } catch {
+      throw new Error("Malformed JSON response from Atlassian API");
+    }
+  }
+
+  return response.text();
+}
+
+export function createStatusError(errorPrefix: string, response: Response) {
+  const base = `${errorPrefix}: ${response.status} ${response.statusText}`;
+
+  switch (response.status) {
+    case 401:
+      return new Error(`${base} - check ATLASSIAN_EMAIL and ATLASSIAN_API_TOKEN`);
+    case 403:
+      return new Error(`${base} - verify product permissions for this account`);
+    case 404:
+      return new Error(`${base} - verify the resource identifier or API path`);
+    case 429:
+      return new Error(`${base} - retry later or reduce request rate`);
+    default:
+      return new Error(base);
+  }
+}
+
+export async function sendJsonRequest(options: {
+  config: AtlassianConfig;
+  fetchImpl?: FetchLike;
+  url: string;
+  method: HttpMethod;
+  body?: unknown;
+  errorPrefix: string;
+  handleResponseError?: (response: Response) => Error | undefined;
+}) {
+  const fetchImpl = options.fetchImpl ?? globalThis.fetch;
+
+  if (!fetchImpl) {
+    throw new Error("Fetch API is not available in this runtime");
+  }
+
+  const response = await fetchImpl(options.url, {
+    method: options.method,
+    headers: createJsonHeaders(options.config, options.body !== undefined),
+    ...(options.body === undefined ? {} : { body: JSON.stringify(options.body) }),
+  });
+
+  if (!response.ok) {
+    const customError = options.handleResponseError?.(response);
+
+    if (customError) {
+      throw customError;
+    }
+
+    throw createStatusError(options.errorPrefix, response);
+  }
+
+  return parseResponse(response);
+}

skills/atlassian/opencode/scripts/src/jira.ts

@@ -0,0 +1,264 @@
+import { markdownToAdf } from "./adf.js";
+import { sendJsonRequest } from "./http.js";
+import type { AtlassianConfig, CommandOutput, FetchLike, JiraIssueSummary } from "./types.js";
+
+const ISSUE_FIELDS = ["summary", "issuetype", "status", "assignee", "created", "updated"] as const;
+
+type JiraClientOptions = {
+  config: AtlassianConfig;
+  fetchImpl?: FetchLike;
+};
+
+type SearchInput = {
+  jql: string;
+  maxResults: number;
+  startAt: number;
+};
+
+type CreateInput = {
+  project?: string;
+  type: string;
+  summary: string;
+  description?: string;
+  dryRun?: boolean;
+};
+
+type UpdateInput = {
+  issue: string;
+  summary?: string;
+  description?: string;
+  dryRun?: boolean;
+};
+
+type CommentInput = {
+  issue: string;
+  body: string;
+  dryRun?: boolean;
+};
+
+type TransitionInput = {
+  issue: string;
+  transition: string;
+  dryRun?: boolean;
+};
+
+function normalizeIssue(config: AtlassianConfig, issue: Record<string, unknown>): JiraIssueSummary {
+  const fields = (issue.fields ?? {}) as Record<string, unknown>;
+  const issueType = (fields.issuetype ?? {}) as Record<string, unknown>;
+  const status = (fields.status ?? {}) as Record<string, unknown>;
+  const assignee = (fields.assignee ?? {}) as Record<string, unknown>;
+
+  return {
+    key: String(issue.key ?? ""),
+    summary: String(fields.summary ?? ""),
+    issueType: String(issueType.name ?? ""),
+    status: String(status.name ?? ""),
+    assignee: assignee.displayName ? String(assignee.displayName) : undefined,
+    created: String(fields.created ?? ""),
+    updated: String(fields.updated ?? ""),
+    url: `${config.baseUrl}/browse/${issue.key ?? ""}`,
+  };
+}
+
+function createRequest(config: AtlassianConfig, method: "GET" | "POST" | "PUT", path: string, body?: unknown) {
+  const url = new URL(path, `${config.jiraBaseUrl}/`);
+
+  return {
+    method,
+    url: url.toString(),
+    ...(body === undefined ? {} : { body }),
+  };
+}
+
+export function createJiraClient(options: JiraClientOptions) {
+  const fetchImpl = options.fetchImpl ?? globalThis.fetch;
+
+  if (!fetchImpl) {
+    throw new Error("Fetch API is not available in this runtime");
+  }
+
+  async function send(method: "GET" | "POST" | "PUT", path: string, body?: unknown) {
+    const request = createRequest(options.config, method, path, body);
+    return sendJsonRequest({
+      config: options.config,
+      fetchImpl,
+      url: request.url,
+      method,
+      body,
+      errorPrefix: "Jira request failed",
+    });
+  }
+
+  return {
+    async searchIssues(input: SearchInput): Promise<CommandOutput<unknown>> {
+      const raw = (await send("POST", "/rest/api/3/search", {
+        jql: input.jql,
+        maxResults: input.maxResults,
+        startAt: input.startAt,
+        fields: [...ISSUE_FIELDS],
+      })) as Record<string, unknown>;
+
+      const issues = Array.isArray(raw.issues) ? raw.issues : [];
+
+      return {
+        ok: true,
+        data: {
+          issues: issues.map((issue) => normalizeIssue(options.config, issue as Record<string, unknown>)),
+          startAt: Number(raw.startAt ?? input.startAt),
+          maxResults: Number(raw.maxResults ?? input.maxResults),
+          total: Number(raw.total ?? issues.length),
+        },
+      };
+    },
+
+    async getIssue(issue: string): Promise<CommandOutput<unknown>> {
+      const url = new URL(`/rest/api/3/issue/${issue}`, `${options.config.jiraBaseUrl}/`);
+      url.searchParams.set("fields", ISSUE_FIELDS.join(","));
+
+      const raw = (await send("GET", `${url.pathname}${url.search}`)) as Record<string, unknown>;
+
+      return {
+        ok: true,
+        data: {
+          issue: normalizeIssue(options.config, raw),
+        },
+        raw,
+      };
+    },
+
+    async getTransitions(issue: string): Promise<CommandOutput<unknown>> {
+      const raw = (await send(
+        "GET",
+        `/rest/api/3/issue/${issue}/transitions`,
+      )) as { transitions?: Array<Record<string, unknown>> };
+
+      return {
+        ok: true,
+        data: {
+          transitions: (raw.transitions ?? []).map((transition) => ({
+            id: String(transition.id ?? ""),
+            name: String(transition.name ?? ""),
+            toStatus: String(((transition.to ?? {}) as Record<string, unknown>).name ?? ""),
+            hasScreen: Boolean(transition.hasScreen),
+          })),
+        },
+      };
+    },
+
+    async createIssue(input: CreateInput): Promise<CommandOutput<unknown>> {
+      const project = input.project || options.config.defaultProject;
+
+      if (!project) {
+        throw new Error("jira-create requires --project or ATLASSIAN_DEFAULT_PROJECT");
+      }
+
+      const request = createRequest(options.config, "POST", "/rest/api/3/issue", {
+        fields: {
+          project: { key: project },
+          issuetype: { name: input.type },
+          summary: input.summary,
+          ...(input.description ? { description: markdownToAdf(input.description) } : {}),
+        },
+      });
+
+      if (input.dryRun) {
+        return {
+          ok: true,
+          dryRun: true,
+          data: request,
+        };
+      }
+
+      const raw = await send("POST", "/rest/api/3/issue", request.body);
+      return { ok: true, data: raw };
+    },
+
+    async updateIssue(input: UpdateInput): Promise<CommandOutput<unknown>> {
+      const fields: Record<string, unknown> = {};
+
+      if (input.summary) {
+        fields.summary = input.summary;
+      }
+
+      if (input.description) {
+        fields.description = markdownToAdf(input.description);
+      }
+
+      if (Object.keys(fields).length === 0) {
+        throw new Error("jira-update requires --summary and/or --description-file");
+      }
+
+      const request = createRequest(options.config, "PUT", `/rest/api/3/issue/${input.issue}`, {
+        fields,
+      });
+
+      if (input.dryRun) {
+        return {
+          ok: true,
+          dryRun: true,
+          data: request,
+        };
+      }
+
+      await send("PUT", `/rest/api/3/issue/${input.issue}`, request.body);
+      return {
+        ok: true,
+        data: {
+          issue: input.issue,
+          updated: true,
+        },
+      };
+    },
+
+    async commentIssue(input: CommentInput): Promise<CommandOutput<unknown>> {
+      const request = createRequest(options.config, "POST", `/rest/api/3/issue/${input.issue}/comment`, {
+        body: markdownToAdf(input.body),
+      });
+
+      if (input.dryRun) {
+        return {
+          ok: true,
+          dryRun: true,
+          data: request,
+        };
+      }
+
+      const raw = await send("POST", `/rest/api/3/issue/${input.issue}/comment`, request.body);
+      return {
+        ok: true,
+        data: raw,
+      };
+    },
+
+    async transitionIssue(input: TransitionInput): Promise<CommandOutput<unknown>> {
+      const request = createRequest(
+        options.config,
+        "POST",
+        `/rest/api/3/issue/${input.issue}/transitions`,
+        {
+          transition: {
+            id: input.transition,
+          },
+        },
+      );
+
+      if (input.dryRun) {
+        return {
+          ok: true,
+          dryRun: true,
+          data: request,
+        };
+      }
+
+      await send("POST", `/rest/api/3/issue/${input.issue}/transitions`, request.body);
+      return {
+        ok: true,
+        data: {
+          issue: input.issue,
+          transitioned: true,
+          transition: input.transition,
+        },
+      };
+    },
+  };
+}

skills/atlassian/opencode/scripts/src/output.ts

@@ -0,0 +1,44 @@
+import type { CommandOutput, OutputFormat, Writer } from "./types.js";
+
+function renderText(payload: CommandOutput<unknown>) {
+  const data = payload.data as Record<string, unknown>;
+
+  if (Array.isArray(data?.issues)) {
+    return data.issues
+      .map((issue) => {
+        const item = issue as Record<string, string>;
+        return `${item.key} [${item.status}] ${item.issueType} - ${item.summary}`;
+      })
+      .join("\n");
+  }
+
+  if (data?.issue && typeof data.issue === "object") {
+    const issue = data.issue as Record<string, string>;
+    return [
+      issue.key,
+      `${issue.issueType} | ${issue.status}`,
+      issue.summary,
+      issue.url,
+    ].join("\n");
+  }
+
+  if (Array.isArray(data?.transitions)) {
+    return data.transitions
+      .map((transition) => {
+        const item = transition as Record<string, string>;
+        return `${item.id} ${item.name} -> ${item.toStatus}`;
+      })
+      .join("\n");
+  }
+
+  return JSON.stringify(payload, null, 2);
+}
+
+export function writeOutput(
+  writer: Writer,
+  payload: CommandOutput<unknown>,
+  format: OutputFormat = "json",
+) {
+  const body = format === "text" ? renderText(payload) : JSON.stringify(payload, null, 2);
+  writer.write(`${body}\n`);
+}

skills/atlassian/opencode/scripts/src/raw.ts

@@ -0,0 +1,85 @@
+import { readWorkspaceFile } from "./files.js";
+import { sendJsonRequest } from "./http.js";
+import type { AtlassianConfig, CommandOutput, FetchLike } from "./types.js";
+
+const JIRA_ALLOWED_PREFIXES = ["/rest/api/3/"] as const;
+const CONFLUENCE_ALLOWED_PREFIXES = ["/wiki/api/v2/", "/wiki/rest/api/"] as const;
+
+type RawInput = {
+  product: "jira" | "confluence";
+  method: string;
+  path: string;
+  bodyFile?: string;
+  cwd: string;
+  dryRun?: boolean;
+};
+
+function getAllowedPrefixes(product: RawInput["product"]) {
+  return product === "jira" ? JIRA_ALLOWED_PREFIXES : CONFLUENCE_ALLOWED_PREFIXES;
+}
+
+function buildUrl(config: AtlassianConfig, product: RawInput["product"], path: string) {
+  const baseUrl = product === "jira" ? config.jiraBaseUrl : config.confluenceBaseUrl;
+  return new URL(path, `${baseUrl}/`).toString();
+}
+
+function validateMethod(method: string): asserts method is "GET" | "POST" | "PUT" {
+  if (!["GET", "POST", "PUT"].includes(method)) {
+    throw new Error("raw only allows GET, POST, and PUT");
+  }
+}
+
+function validatePath(product: RawInput["product"], path: string) {
+  const allowedPrefixes = getAllowedPrefixes(product);
+
+  if (!allowedPrefixes.some((prefix) => path.startsWith(prefix))) {
+    throw new Error(`raw path is not allowed for ${product}: ${path}`);
+  }
+}
+
+async function readRawBody(bodyFile: string | undefined, cwd: string) {
+  if (!bodyFile) {
+    return undefined;
+  }
+
+  const contents = await readWorkspaceFile(bodyFile, cwd);
+  return JSON.parse(contents) as unknown;
+}
+
+export async function runRawCommand(
+  config: AtlassianConfig,
+  fetchImpl: FetchLike | undefined,
+  input: RawInput,
+): Promise<CommandOutput<unknown>> {
+  validateMethod(input.method);
+  validatePath(input.product, input.path);
+
+  const body = await readRawBody(input.bodyFile, input.cwd);
+  const request = {
+    method: input.method,
+    url: buildUrl(config, input.product, input.path),
+    ...(body === undefined ? {} : { body }),
+  };
+
+  if (input.dryRun) {
+    return {
+      ok: true,
+      dryRun: true,
+      data: request,
+    };
+  }
+
+  const data = await sendJsonRequest({
+    config,
+    fetchImpl,
+    url: request.url,
+    method: input.method,
+    body,
+    errorPrefix: "Raw request failed",
+  });
+
+  return {
+    ok: true,
+    data,
+  };
+}

skills/atlassian/opencode/scripts/src/types.ts

@@ -0,0 +1,35 @@
+export type AtlassianConfig = {
+  baseUrl: string;
+  jiraBaseUrl: string;
+  confluenceBaseUrl: string;
+  email: string;
+  apiToken: string;
+  defaultProject?: string;
+  defaultSpace?: string;
+};
+
+export type CommandOutput<T> = {
+  ok: boolean;
+  data: T;
+  dryRun?: boolean;
+  raw?: unknown;
+};
+
+export type JiraIssueSummary = {
+  key: string;
+  summary: string;
+  issueType: string;
+  status: string;
+  assignee?: string;
+  created: string;
+  updated: string;
+  url: string;
+};
+
+export type Writer = {
+  write(chunk: string | Uint8Array): unknown;
+};
+
+export type FetchLike = typeof fetch;
+
+export type OutputFormat = "json" | "text";

skills/atlassian/opencode/scripts/tsconfig.json

@@ -0,0 +1,15 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "esModuleInterop": true,
+    "forceConsistentCasingInFileNames": true,
+    "strict": true,
+    "skipLibCheck": true,
+    "resolveJsonModule": true,
+    "types": ["node"],
+    "outDir": "dist"
+  },
+  "include": ["src/**/*.ts", "scripts/**/*.ts", "tests/**/*.ts"]
+}

skills/atlassian/shared/scripts/package.json

@@ -0,0 +1,22 @@
+{
+  "name": "atlassian-skill-scripts",
+  "version": "1.0.0",
+  "description": "Shared runtime for the Atlassian skill",
+  "type": "module",
+  "scripts": {
+    "atlassian": "tsx src/cli.ts",
+    "test": "node --import tsx --test tests/*.test.ts",
+    "typecheck": "tsc --noEmit",
+    "sync:agents": "tsx scripts/sync-agents.ts"
+  },
+  "dependencies": {
+    "commander": "^13.1.0",
+    "dotenv": "^16.4.7"
+  },
+  "devDependencies": {
+    "@types/node": "^24.3.0",
+    "tsx": "^4.20.5",
+    "typescript": "^5.9.2"
+  },
+  "packageManager": "pnpm@10.18.1+sha512.77a884a165cbba2d8d1c19e3b4880eee6d2fcabd0d879121e282196b80042351d5eb3ca0935fa599da1dc51265cc68816ad2bddd2a2de5ea9fdf92adbec7cd34"
+}

skills/atlassian/shared/scripts/pnpm-lock.yaml

@@ -0,0 +1,361 @@
+lockfileVersion: '9.0'
+
+settings:
+  autoInstallPeers: true
+  excludeLinksFromLockfile: false
+
+importers:
+
+  .:
+    dependencies:
+      commander:
+        specifier: ^13.1.0
+        version: 13.1.0
+      dotenv:
+        specifier: ^16.4.7
+        version: 16.6.1
+    devDependencies:
+      '@types/node':
+        specifier: ^24.3.0
+        version: 24.12.0
+      tsx:
+        specifier: ^4.20.5
+        version: 4.21.0
+      typescript:
+        specifier: ^5.9.2
+        version: 5.9.3
+
+packages:
+
+  '@esbuild/aix-ppc64@0.27.3':
+    resolution: {integrity: sha512-9fJMTNFTWZMh5qwrBItuziu834eOCUcEqymSH7pY+zoMVEZg3gcPuBNxH1EvfVYe9h0x/Ptw8KBzv7qxb7l8dg==}
+    engines: {node: '>=18'}
+    cpu: [ppc64]
+    os: [aix]
+
+  '@esbuild/android-arm64@0.27.3':
+    resolution: {integrity: sha512-YdghPYUmj/FX2SYKJ0OZxf+iaKgMsKHVPF1MAq/P8WirnSpCStzKJFjOjzsW0QQ7oIAiccHdcqjbHmJxRb/dmg==}
+    engines: {node: '>=18'}
+    cpu: [arm64]
+    os: [android]
+
+  '@esbuild/android-arm@0.27.3':
+    resolution: {integrity: sha512-i5D1hPY7GIQmXlXhs2w8AWHhenb00+GxjxRncS2ZM7YNVGNfaMxgzSGuO8o8SJzRc/oZwU2bcScvVERk03QhzA==}
+    engines: {node: '>=18'}
+    cpu: [arm]
+    os: [android]
+
+  '@esbuild/android-x64@0.27.3':
+    resolution: {integrity: sha512-IN/0BNTkHtk8lkOM8JWAYFg4ORxBkZQf9zXiEOfERX/CzxW3Vg1ewAhU7QSWQpVIzTW+b8Xy+lGzdYXV6UZObQ==}
+    engines: {node: '>=18'}
+    cpu: [x64]
+    os: [android]
+
+  '@esbuild/darwin-arm64@0.27.3':
+    resolution: {integrity: sha512-Re491k7ByTVRy0t3EKWajdLIr0gz2kKKfzafkth4Q8A5n1xTHrkqZgLLjFEHVD+AXdUGgQMq+Godfq45mGpCKg==}
+    engines: {node: '>=18'}
+    cpu: [arm64]
+    os: [darwin]
+
+  '@esbuild/darwin-x64@0.27.3':
+    resolution: {integrity: sha512-vHk/hA7/1AckjGzRqi6wbo+jaShzRowYip6rt6q7VYEDX4LEy1pZfDpdxCBnGtl+A5zq8iXDcyuxwtv3hNtHFg==}
+    engines: {node: '>=18'}
+    cpu: [x64]
+    os: [darwin]
+
+  '@esbuild/freebsd-arm64@0.27.3':
+    resolution: {integrity: sha512-ipTYM2fjt3kQAYOvo6vcxJx3nBYAzPjgTCk7QEgZG8AUO3ydUhvelmhrbOheMnGOlaSFUoHXB6un+A7q4ygY9w==}
+    engines: {node: '>=18'}
+    cpu: [arm64]
+    os: [freebsd]
+
+  '@esbuild/freebsd-x64@0.27.3':
+    resolution: {integrity: sha512-dDk0X87T7mI6U3K9VjWtHOXqwAMJBNN2r7bejDsc+j03SEjtD9HrOl8gVFByeM0aJksoUuUVU9TBaZa2rgj0oA==}
+    engines: {node: '>=18'}
+    cpu: [x64]
+    os: [freebsd]
+
+  '@esbuild/linux-arm64@0.27.3':
+    resolution: {integrity: sha512-sZOuFz/xWnZ4KH3YfFrKCf1WyPZHakVzTiqji3WDc0BCl2kBwiJLCXpzLzUBLgmp4veFZdvN5ChW4Eq/8Fc2Fg==}
+    engines: {node: '>=18'}
+    cpu: [arm64]
+    os: [linux]
+
+  '@esbuild/linux-arm@0.27.3':
+    resolution: {integrity: sha512-s6nPv2QkSupJwLYyfS+gwdirm0ukyTFNl3KTgZEAiJDd+iHZcbTPPcWCcRYH+WlNbwChgH2QkE9NSlNrMT8Gfw==}
+    engines: {node: '>=18'}
+    cpu: [arm]
+    os: [linux]
+
+  '@esbuild/linux-ia32@0.27.3':
+    resolution: {integrity: sha512-yGlQYjdxtLdh0a3jHjuwOrxQjOZYD/C9PfdbgJJF3TIZWnm/tMd/RcNiLngiu4iwcBAOezdnSLAwQDPqTmtTYg==}
+    engines: {node: '>=18'}
+    cpu: [ia32]
+    os: [linux]
+
+  '@esbuild/linux-loong64@0.27.3':
+    resolution: {integrity: sha512-WO60Sn8ly3gtzhyjATDgieJNet/KqsDlX5nRC5Y3oTFcS1l0KWba+SEa9Ja1GfDqSF1z6hif/SkpQJbL63cgOA==}
+    engines: {node: '>=18'}
+    cpu: [loong64]
+    os: [linux]
+
+  '@esbuild/linux-mips64el@0.27.3':
+    resolution: {integrity: sha512-APsymYA6sGcZ4pD6k+UxbDjOFSvPWyZhjaiPyl/f79xKxwTnrn5QUnXR5prvetuaSMsb4jgeHewIDCIWljrSxw==}
+    engines: {node: '>=18'}
+    cpu: [mips64el]
+    os: [linux]
+
+  '@esbuild/linux-ppc64@0.27.3':
+    resolution: {integrity: sha512-eizBnTeBefojtDb9nSh4vvVQ3V9Qf9Df01PfawPcRzJH4gFSgrObw+LveUyDoKU3kxi5+9RJTCWlj4FjYXVPEA==}
+    engines: {node: '>=18'}
+    cpu: [ppc64]
+    os: [linux]
+
+  '@esbuild/linux-riscv64@0.27.3':
+    resolution: {integrity: sha512-3Emwh0r5wmfm3ssTWRQSyVhbOHvqegUDRd0WhmXKX2mkHJe1SFCMJhagUleMq+Uci34wLSipf8Lagt4LlpRFWQ==}
+    engines: {node: '>=18'}
+    cpu: [riscv64]
+    os: [linux]
+
+  '@esbuild/linux-s390x@0.27.3':
+    resolution: {integrity: sha512-pBHUx9LzXWBc7MFIEEL0yD/ZVtNgLytvx60gES28GcWMqil8ElCYR4kvbV2BDqsHOvVDRrOxGySBM9Fcv744hw==}
+    engines: {node: '>=18'}
+    cpu: [s390x]
+    os: [linux]
+
+  '@esbuild/linux-x64@0.27.3':
+    resolution: {integrity: sha512-Czi8yzXUWIQYAtL/2y6vogER8pvcsOsk5cpwL4Gk5nJqH5UZiVByIY8Eorm5R13gq+DQKYg0+JyQoytLQas4dA==}
+    engines: {node: '>=18'}
+    cpu: [x64]
+    os: [linux]
+
+  '@esbuild/netbsd-arm64@0.27.3':
+    resolution: {integrity: sha512-sDpk0RgmTCR/5HguIZa9n9u+HVKf40fbEUt+iTzSnCaGvY9kFP0YKBWZtJaraonFnqef5SlJ8/TiPAxzyS+UoA==}
+    engines: {node: '>=18'}
+    cpu: [arm64]
+    os: [netbsd]
+
+  '@esbuild/netbsd-x64@0.27.3':
+    resolution: {integrity: sha512-P14lFKJl/DdaE00LItAukUdZO5iqNH7+PjoBm+fLQjtxfcfFE20Xf5CrLsmZdq5LFFZzb5JMZ9grUwvtVYzjiA==}
+    engines: {node: '>=18'}
+    cpu: [x64]
+    os: [netbsd]
+
+  '@esbuild/openbsd-arm64@0.27.3':
+    resolution: {integrity: sha512-AIcMP77AvirGbRl/UZFTq5hjXK+2wC7qFRGoHSDrZ5v5b8DK/GYpXW3CPRL53NkvDqb9D+alBiC/dV0Fb7eJcw==}
+    engines: {node: '>=18'}
+    cpu: [arm64]
+    os: [openbsd]
+
+  '@esbuild/openbsd-x64@0.27.3':
+    resolution: {integrity: sha512-DnW2sRrBzA+YnE70LKqnM3P+z8vehfJWHXECbwBmH/CU51z6FiqTQTHFenPlHmo3a8UgpLyH3PT+87OViOh1AQ==}
+    engines: {node: '>=18'}
+    cpu: [x64]
+    os: [openbsd]
+
+  '@esbuild/openharmony-arm64@0.27.3':
+    resolution: {integrity: sha512-NinAEgr/etERPTsZJ7aEZQvvg/A6IsZG/LgZy+81wON2huV7SrK3e63dU0XhyZP4RKGyTm7aOgmQk0bGp0fy2g==}
+    engines: {node: '>=18'}
+    cpu: [arm64]
+    os: [openharmony]
+
+  '@esbuild/sunos-x64@0.27.3':
+    resolution: {integrity: sha512-PanZ+nEz+eWoBJ8/f8HKxTTD172SKwdXebZ0ndd953gt1HRBbhMsaNqjTyYLGLPdoWHy4zLU7bDVJztF5f3BHA==}
+    engines: {node: '>=18'}
+    cpu: [x64]
+    os: [sunos]
+
+  '@esbuild/win32-arm64@0.27.3':
+    resolution: {integrity: sha512-B2t59lWWYrbRDw/tjiWOuzSsFh1Y/E95ofKz7rIVYSQkUYBjfSgf6oeYPNWHToFRr2zx52JKApIcAS/D5TUBnA==}
+    engines: {node: '>=18'}
+    cpu: [arm64]
+    os: [win32]
+
+  '@esbuild/win32-ia32@0.27.3':
+    resolution: {integrity: sha512-QLKSFeXNS8+tHW7tZpMtjlNb7HKau0QDpwm49u0vUp9y1WOF+PEzkU84y9GqYaAVW8aH8f3GcBck26jh54cX4Q==}
+    engines: {node: '>=18'}
+    cpu: [ia32]
+    os: [win32]
+
+  '@esbuild/win32-x64@0.27.3':
+    resolution: {integrity: sha512-4uJGhsxuptu3OcpVAzli+/gWusVGwZZHTlS63hh++ehExkVT8SgiEf7/uC/PclrPPkLhZqGgCTjd0VWLo6xMqA==}
+    engines: {node: '>=18'}
+    cpu: [x64]
+    os: [win32]
+
+  '@types/node@24.12.0':
+    resolution: {integrity: sha512-GYDxsZi3ChgmckRT9HPU0WEhKLP08ev/Yfcq2AstjrDASOYCSXeyjDsHg4v5t4jOj7cyDX3vmprafKlWIG9MXQ==}
+
+  commander@13.1.0:
+    resolution: {integrity: sha512-/rFeCpNJQbhSZjGVwO9RFV3xPqbnERS8MmIQzCtD/zl6gpJuV/bMLuN92oG3F7d8oDEHHRrujSXNUr8fpjntKw==}
+    engines: {node: '>=18'}
+
+  dotenv@16.6.1:
+    resolution: {integrity: sha512-uBq4egWHTcTt33a72vpSG0z3HnPuIl6NqYcTrKEg2azoEyl2hpW0zqlxysq2pK9HlDIHyHyakeYaYnSAwd8bow==}
+    engines: {node: '>=12'}
+
+  esbuild@0.27.3:
+    resolution: {integrity: sha512-8VwMnyGCONIs6cWue2IdpHxHnAjzxnw2Zr7MkVxB2vjmQ2ivqGFb4LEG3SMnv0Gb2F/G/2yA8zUaiL1gywDCCg==}
+    engines: {node: '>=18'}
+    hasBin: true
+
+  fsevents@2.3.3:
+    resolution: {integrity: sha512-5xoDfX+fL7faATnagmWPpbFtwh/R77WmMMqqHGS65C3vvB0YHrgF+B1YmZ3441tMj5n63k0212XNoJwzlhffQw==}
+    engines: {node: ^8.16.0 || ^10.6.0 || >=11.0.0}
+    os: [darwin]
+
+  get-tsconfig@4.13.6:
+    resolution: {integrity: sha512-shZT/QMiSHc/YBLxxOkMtgSid5HFoauqCE3/exfsEcwg1WkeqjG+V40yBbBrsD+jW2HDXcs28xOfcbm2jI8Ddw==}
+
+  resolve-pkg-maps@1.0.0:
+    resolution: {integrity: sha512-seS2Tj26TBVOC2NIc2rOe2y2ZO7efxITtLZcGSOnHHNOQ7CkiUBfw0Iw2ck6xkIhPwLhKNLS8BO+hEpngQlqzw==}
+
+  tsx@4.21.0:
+    resolution: {integrity: sha512-5C1sg4USs1lfG0GFb2RLXsdpXqBSEhAaA/0kPL01wxzpMqLILNxIxIOKiILz+cdg/pLnOUxFYOR5yhHU666wbw==}
+    engines: {node: '>=18.0.0'}
+    hasBin: true
+
+  typescript@5.9.3:
+    resolution: {integrity: sha512-jl1vZzPDinLr9eUt3J/t7V6FgNEw9QjvBPdysz9KfQDD41fQrC2Y4vKQdiaUpFT4bXlb1RHhLpp8wtm6M5TgSw==}
+    engines: {node: '>=14.17'}
+    hasBin: true
+
+  undici-types@7.16.0:
+    resolution: {integrity: sha512-Zz+aZWSj8LE6zoxD+xrjh4VfkIG8Ya6LvYkZqtUQGJPZjYl53ypCaUwWqo7eI0x66KBGeRo+mlBEkMSeSZ38Nw==}
+
+snapshots:
+
+  '@esbuild/aix-ppc64@0.27.3':
+    optional: true
+
+  '@esbuild/android-arm64@0.27.3':
+    optional: true
+
+  '@esbuild/android-arm@0.27.3':
+    optional: true
+
+  '@esbuild/android-x64@0.27.3':
+    optional: true
+
+  '@esbuild/darwin-arm64@0.27.3':
+    optional: true
+
+  '@esbuild/darwin-x64@0.27.3':
+    optional: true
+
+  '@esbuild/freebsd-arm64@0.27.3':
+    optional: true
+
+  '@esbuild/freebsd-x64@0.27.3':
+    optional: true
+
+  '@esbuild/linux-arm64@0.27.3':
+    optional: true
+
+  '@esbuild/linux-arm@0.27.3':
+    optional: true
+
+  '@esbuild/linux-ia32@0.27.3':
+    optional: true
+
+  '@esbuild/linux-loong64@0.27.3':
+    optional: true
+
+  '@esbuild/linux-mips64el@0.27.3':
+    optional: true
+
+  '@esbuild/linux-ppc64@0.27.3':
+    optional: true
+
+  '@esbuild/linux-riscv64@0.27.3':
+    optional: true
+
+  '@esbuild/linux-s390x@0.27.3':
+    optional: true
+
+  '@esbuild/linux-x64@0.27.3':
+    optional: true
+
+  '@esbuild/netbsd-arm64@0.27.3':
+    optional: true
+
+  '@esbuild/netbsd-x64@0.27.3':
+    optional: true
+
+  '@esbuild/openbsd-arm64@0.27.3':
+    optional: true
+
+  '@esbuild/openbsd-x64@0.27.3':
+    optional: true
+
+  '@esbuild/openharmony-arm64@0.27.3':
+    optional: true
+
+  '@esbuild/sunos-x64@0.27.3':
+    optional: true
+
+  '@esbuild/win32-arm64@0.27.3':
+    optional: true
+
+  '@esbuild/win32-ia32@0.27.3':
+    optional: true
+
+  '@esbuild/win32-x64@0.27.3':
+    optional: true
+
+  '@types/node@24.12.0':
+    dependencies:
+      undici-types: 7.16.0
+
+  commander@13.1.0: {}
+
+  dotenv@16.6.1: {}
+
+  esbuild@0.27.3:
+    optionalDependencies:
+      '@esbuild/aix-ppc64': 0.27.3
+      '@esbuild/android-arm': 0.27.3
+      '@esbuild/android-arm64': 0.27.3
+      '@esbuild/android-x64': 0.27.3
+      '@esbuild/darwin-arm64': 0.27.3
+      '@esbuild/darwin-x64': 0.27.3
+      '@esbuild/freebsd-arm64': 0.27.3
+      '@esbuild/freebsd-x64': 0.27.3
+      '@esbuild/linux-arm': 0.27.3
+      '@esbuild/linux-arm64': 0.27.3
+      '@esbuild/linux-ia32': 0.27.3
+      '@esbuild/linux-loong64': 0.27.3
+      '@esbuild/linux-mips64el': 0.27.3
+      '@esbuild/linux-ppc64': 0.27.3
+      '@esbuild/linux-riscv64': 0.27.3
+      '@esbuild/linux-s390x': 0.27.3
+      '@esbuild/linux-x64': 0.27.3
+      '@esbuild/netbsd-arm64': 0.27.3
+      '@esbuild/netbsd-x64': 0.27.3
+      '@esbuild/openbsd-arm64': 0.27.3
+      '@esbuild/openbsd-x64': 0.27.3
+      '@esbuild/openharmony-arm64': 0.27.3
+      '@esbuild/sunos-x64': 0.27.3
+      '@esbuild/win32-arm64': 0.27.3
+      '@esbuild/win32-ia32': 0.27.3
+      '@esbuild/win32-x64': 0.27.3
+
+  fsevents@2.3.3:
+    optional: true
+
+  get-tsconfig@4.13.6:
+    dependencies:
+      resolve-pkg-maps: 1.0.0
+
+  resolve-pkg-maps@1.0.0: {}
+
+  tsx@4.21.0:
+    dependencies:
+      esbuild: 0.27.3
+      get-tsconfig: 4.13.6
+    optionalDependencies:
+      fsevents: 2.3.3
+
+  typescript@5.9.3: {}
+
+  undici-types@7.16.0: {}

skills/atlassian/shared/scripts/scripts/sync-agents.ts

@@ -0,0 +1,60 @@
+import { cp, mkdir, readFile, rm, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+const SHARED_SCRIPTS_DIR = path.resolve(__dirname, "..");
+const ATLASSIAN_SKILL_DIR = path.resolve(SHARED_SCRIPTS_DIR, "..", "..");
+const AGENTS = ["codex", "claude-code", "cursor", "opencode"] as const;
+const ENTRIES_TO_COPY = ["pnpm-lock.yaml", "tsconfig.json", "src"] as const;
+
+async function replaceEntry(source: string, target: string) {
+  await rm(target, { recursive: true, force: true });
+  await cp(source, target, { recursive: true });
+}
+
+async function syncAgent(agent: (typeof AGENTS)[number]) {
+  const targetScriptsDir = path.join(ATLASSIAN_SKILL_DIR, agent, "scripts");
+  await mkdir(targetScriptsDir, { recursive: true });
+
+  for (const entry of ENTRIES_TO_COPY) {
+    await replaceEntry(
+      path.join(SHARED_SCRIPTS_DIR, entry),
+      path.join(targetScriptsDir, entry),
+    );
+  }
+
+  const sourcePackageJson = JSON.parse(
+    await readFile(path.join(SHARED_SCRIPTS_DIR, "package.json"), "utf8"),
+  ) as {
+    scripts?: Record<string, string>;
+    [key: string]: unknown;
+  };
+
+  sourcePackageJson.scripts = {
+    atlassian: sourcePackageJson.scripts?.atlassian ?? "tsx src/cli.ts",
+    typecheck: sourcePackageJson.scripts?.typecheck ?? "tsc --noEmit",
+  };
+
+  await writeFile(
+    path.join(targetScriptsDir, "package.json"),
+    `${JSON.stringify(sourcePackageJson, null, 2)}\n`,
+    "utf8",
+  );
+}
+
+async function main() {
+  for (const agent of AGENTS) {
+    await syncAgent(agent);
+  }
+
+  console.log(`Synced runtime bundle into ${AGENTS.length} agent script directories.`);
+}
+
+main().catch((error: unknown) => {
+  const message = error instanceof Error ? error.message : String(error);
+  console.error(message);
+  process.exitCode = 1;
+});

skills/atlassian/shared/scripts/src/adf.ts

@@ -0,0 +1,92 @@
+const TEXT_NODE = "text";
+
+function textNode(text: string) {
+  return {
+    type: TEXT_NODE,
+    text,
+  };
+}
+
+function paragraphNode(lines: string[]) {
+  const content: Array<{ type: string; text?: string }> = [];
+
+  lines.forEach((line, index) => {
+    if (index > 0) {
+      content.push({ type: "hardBreak" });
+    }
+
+    if (line.length > 0) {
+      content.push(textNode(line));
+    }
+  });
+
+  return {
+    type: "paragraph",
+    ...(content.length > 0 ? { content } : {}),
+  };
+}
+
+export function markdownToAdf(input: string) {
+  const lines = input.replace(/\r\n/g, "\n").split("\n");
+  const content: Array<Record<string, unknown>> = [];
+  let index = 0;
+
+  while (index < lines.length) {
+    const current = lines[index]?.trimEnd() ?? "";
+
+    if (current.trim().length === 0) {
+      index += 1;
+      continue;
+    }
+
+    const heading = current.match(/^(#{1,6})\s+(.*)$/);
+
+    if (heading) {
+      content.push({
+        type: "heading",
+        attrs: { level: heading[1].length },
+        content: [textNode(heading[2])],
+      });
+      index += 1;
+      continue;
+    }
+
+    if (/^[-*]\s+/.test(current)) {
+      const items: Array<Record<string, unknown>> = [];
+
+      while (index < lines.length && /^[-*]\s+/.test(lines[index] ?? "")) {
+        items.push({
+          type: "listItem",
+          content: [
+            {
+              type: "paragraph",
+              content: [textNode((lines[index] ?? "").replace(/^[-*]\s+/, ""))],
+            },
+          ],
+        });
+        index += 1;
+      }
+
+      content.push({
+        type: "bulletList",
+        content: items,
+      });
+      continue;
+    }
+
+    const paragraphLines: string[] = [];
+
+    while (index < lines.length && (lines[index]?.trim().length ?? 0) > 0) {
+      paragraphLines.push(lines[index] ?? "");
+      index += 1;
+    }
+
+    content.push(paragraphNode(paragraphLines));
+  }
+
+  return {
+    type: "doc",
+    version: 1,
+    content,
+  };
+}

skills/atlassian/shared/scripts/src/cli.ts

@@ -0,0 +1,332 @@
+import process from "node:process";
+import { pathToFileURL } from "node:url";
+
+import { Command } from "commander";
+
+import { createConfluenceClient } from "./confluence.js";
+import { loadConfig } from "./config.js";
+import { readWorkspaceFile } from "./files.js";
+import { runHealthCheck } from "./health.js";
+import { createJiraClient } from "./jira.js";
+import { writeOutput } from "./output.js";
+import { runRawCommand } from "./raw.js";
+import type { FetchLike, OutputFormat, Writer } from "./types.js";
+
+type CliContext = {
+  cwd?: string;
+  env?: NodeJS.ProcessEnv;
+  fetchImpl?: FetchLike;
+  stdout?: Writer;
+  stderr?: Writer;
+};
+
+function resolveFormat(format: string | undefined): OutputFormat {
+  return format === "text" ? "text" : "json";
+}
+
+function createRuntime(context: CliContext) {
+  const cwd = context.cwd ?? process.cwd();
+  const env = context.env ?? process.env;
+  const stdout = context.stdout ?? process.stdout;
+  const stderr = context.stderr ?? process.stderr;
+  let configCache: ReturnType<typeof loadConfig> | undefined;
+  let jiraCache: ReturnType<typeof createJiraClient> | undefined;
+  let confluenceCache: ReturnType<typeof createConfluenceClient> | undefined;
+
+  function getConfig() {
+    configCache ??= loadConfig(env, { cwd });
+    return configCache;
+  }
+
+  function getJiraClient() {
+    jiraCache ??= createJiraClient({
+      config: getConfig(),
+      fetchImpl: context.fetchImpl,
+    });
+    return jiraCache;
+  }
+
+  function getConfluenceClient() {
+    confluenceCache ??= createConfluenceClient({
+      config: getConfig(),
+      fetchImpl: context.fetchImpl,
+    });
+    return confluenceCache;
+  }
+
+  async function readBodyFile(filePath: string | undefined) {
+    if (!filePath) {
+      return undefined;
+    }
+
+    return readWorkspaceFile(filePath, cwd);
+  }
+
+  return {
+    cwd,
+    stdout,
+    stderr,
+    readBodyFile,
+    getConfig,
+    getJiraClient,
+    getConfluenceClient,
+    fetchImpl: context.fetchImpl,
+  };
+}
+
+export function buildProgram(context: CliContext = {}) {
+  const runtime = createRuntime(context);
+  const program = new Command()
+    .name("atlassian")
+    .description("Portable Atlassian CLI for multi-agent skills")
+    .version("0.1.0");
+
+  program
+    .command("health")
+    .description("Validate configuration and Atlassian connectivity")
+    .option("--format <format>", "Output format", "json")
+    .action(async (options) => {
+      const payload = await runHealthCheck(runtime.getConfig(), runtime.fetchImpl);
+      writeOutput(
+        runtime.stdout,
+        payload,
+        resolveFormat(options.format),
+      );
+    });
+
+  program
+    .command("conf-search")
+    .requiredOption("--query <query>", "CQL search query")
+    .option("--max-results <number>", "Maximum results to return", "50")
+    .option("--start-at <number>", "Result offset", "0")
+    .option("--format <format>", "Output format", "json")
+    .action(async (options) => {
+      const payload = await runtime.getConfluenceClient().searchPages({
+        query: options.query,
+        maxResults: Number(options.maxResults),
+        startAt: Number(options.startAt),
+      });
+
+      writeOutput(runtime.stdout, payload, resolveFormat(options.format));
+    });
+
+  program
+    .command("conf-get")
+    .requiredOption("--page <page>", "Confluence page ID")
+    .option("--format <format>", "Output format", "json")
+    .action(async (options) => {
+      const payload = await runtime.getConfluenceClient().getPage(options.page);
+      writeOutput(runtime.stdout, payload, resolveFormat(options.format));
+    });
+
+  program
+    .command("conf-create")
+    .requiredOption("--title <title>", "Confluence page title")
+    .requiredOption("--body-file <path>", "Workspace-relative storage-format body file")
+    .option("--space <space>", "Confluence space ID")
+    .option("--dry-run", "Print the request without sending it")
+    .option("--format <format>", "Output format", "json")
+    .action(async (options) => {
+      const payload = await runtime.getConfluenceClient().createPage({
+        space: options.space,
+        title: options.title,
+        body: (await runtime.readBodyFile(options.bodyFile)) as string,
+        dryRun: Boolean(options.dryRun),
+      });
+
+      writeOutput(runtime.stdout, payload, resolveFormat(options.format));
+    });
+
+  program
+    .command("conf-update")
+    .requiredOption("--page <page>", "Confluence page ID")
+    .requiredOption("--title <title>", "Confluence page title")
+    .requiredOption("--body-file <path>", "Workspace-relative storage-format body file")
+    .option("--dry-run", "Print the request without sending it")
+    .option("--format <format>", "Output format", "json")
+    .action(async (options) => {
+      const payload = await runtime.getConfluenceClient().updatePage({
+        pageId: options.page,
+        title: options.title,
+        body: (await runtime.readBodyFile(options.bodyFile)) as string,
+        dryRun: Boolean(options.dryRun),
+      });
+
+      writeOutput(runtime.stdout, payload, resolveFormat(options.format));
+    });
+
+  program
+    .command("conf-comment")
+    .requiredOption("--page <page>", "Confluence page ID")
+    .requiredOption("--body-file <path>", "Workspace-relative storage-format body file")
+    .option("--dry-run", "Print the request without sending it")
+    .option("--format <format>", "Output format", "json")
+    .action(async (options) => {
+      const payload = await runtime.getConfluenceClient().commentPage({
+        pageId: options.page,
+        body: (await runtime.readBodyFile(options.bodyFile)) as string,
+        dryRun: Boolean(options.dryRun),
+      });
+
+      writeOutput(runtime.stdout, payload, resolveFormat(options.format));
+    });
+
+  program
+    .command("conf-children")
+    .requiredOption("--page <page>", "Confluence page ID")
+    .option("--max-results <number>", "Maximum results to return", "50")
+    .option("--start-at <number>", "Cursor/start token", "0")
+    .option("--format <format>", "Output format", "json")
+    .action(async (options) => {
+      const payload = await runtime.getConfluenceClient().listChildren(
+        options.page,
+        Number(options.maxResults),
+        Number(options.startAt),
+      );
+
+      writeOutput(runtime.stdout, payload, resolveFormat(options.format));
+    });
+
+  program
+    .command("raw")
+    .requiredOption("--product <product>", "jira or confluence")
+    .requiredOption("--method <method>", "GET, POST, or PUT")
+    .requiredOption("--path <path>", "Validated API path")
+    .option("--body-file <path>", "Workspace-relative JSON file")
+    .option("--dry-run", "Print the request without sending it")
+    .option("--format <format>", "Output format", "json")
+    .action(async (options) => {
+      const payload = await runRawCommand(runtime.getConfig(), runtime.fetchImpl, {
+        product: options.product,
+        method: String(options.method).toUpperCase(),
+        path: options.path,
+        bodyFile: options.bodyFile,
+        cwd: runtime.cwd,
+        dryRun: Boolean(options.dryRun),
+      });
+
+      writeOutput(runtime.stdout, payload, resolveFormat(options.format));
+    });
+
+  program
+    .command("jira-search")
+    .requiredOption("--jql <jql>", "JQL expression to execute")
+    .option("--max-results <number>", "Maximum results to return", "50")
+    .option("--start-at <number>", "Result offset", "0")
+    .option("--format <format>", "Output format", "json")
+    .action(async (options) => {
+      const payload = await runtime.getJiraClient().searchIssues({
+        jql: options.jql,
+        maxResults: Number(options.maxResults),
+        startAt: Number(options.startAt),
+      });
+
+      writeOutput(runtime.stdout, payload, resolveFormat(options.format));
+    });
+
+  program
+    .command("jira-get")
+    .requiredOption("--issue <issue>", "Issue key")
+    .option("--format <format>", "Output format", "json")
+    .action(async (options) => {
+      const payload = await runtime.getJiraClient().getIssue(options.issue);
+      writeOutput(runtime.stdout, payload, resolveFormat(options.format));
+    });
+
+  program
+    .command("jira-create")
+    .requiredOption("--type <type>", "Issue type name")
+    .requiredOption("--summary <summary>", "Issue summary")
+    .option("--project <project>", "Project key")
+    .option("--description-file <path>", "Workspace-relative markdown/text file")
+    .option("--dry-run", "Print the request without sending it")
+    .option("--format <format>", "Output format", "json")
+    .action(async (options) => {
+      const payload = await runtime.getJiraClient().createIssue({
+        project: options.project,
+        type: options.type,
+        summary: options.summary,
+        description: await runtime.readBodyFile(options.descriptionFile),
+        dryRun: Boolean(options.dryRun),
+      });
+
+      writeOutput(runtime.stdout, payload, resolveFormat(options.format));
+    });
+
+  program
+    .command("jira-update")
+    .requiredOption("--issue <issue>", "Issue key")
+    .option("--summary <summary>", "Updated summary")
+    .option("--description-file <path>", "Workspace-relative markdown/text file")
+    .option("--dry-run", "Print the request without sending it")
+    .option("--format <format>", "Output format", "json")
+    .action(async (options) => {
+      const payload = await runtime.getJiraClient().updateIssue({
+        issue: options.issue,
+        summary: options.summary,
+        description: await runtime.readBodyFile(options.descriptionFile),
+        dryRun: Boolean(options.dryRun),
+      });
+
+      writeOutput(runtime.stdout, payload, resolveFormat(options.format));
+    });
+
+  program
+    .command("jira-comment")
+    .requiredOption("--issue <issue>", "Issue key")
+    .requiredOption("--body-file <path>", "Workspace-relative markdown/text file")
+    .option("--dry-run", "Print the request without sending it")
+    .option("--format <format>", "Output format", "json")
+    .action(async (options) => {
+      const payload = await runtime.getJiraClient().commentIssue({
+        issue: options.issue,
+        body: (await runtime.readBodyFile(options.bodyFile)) as string,
+        dryRun: Boolean(options.dryRun),
+      });
+
+      writeOutput(runtime.stdout, payload, resolveFormat(options.format));
+    });
+
+  program
+    .command("jira-transitions")
+    .requiredOption("--issue <issue>", "Issue key")
+    .option("--format <format>", "Output format", "json")
+    .action(async (options) => {
+      const payload = await runtime.getJiraClient().getTransitions(options.issue);
+      writeOutput(runtime.stdout, payload, resolveFormat(options.format));
+    });
+
+  program
+    .command("jira-transition")
+    .requiredOption("--issue <issue>", "Issue key")
+    .requiredOption("--transition <transition>", "Transition ID")
+    .option("--dry-run", "Print the request without sending it")
+    .option("--format <format>", "Output format", "json")
+    .action(async (options) => {
+      const payload = await runtime.getJiraClient().transitionIssue({
+        issue: options.issue,
+        transition: options.transition,
+        dryRun: Boolean(options.dryRun),
+      });
+
+      writeOutput(runtime.stdout, payload, resolveFormat(options.format));
+    });
+
+  return program;
+}
+
+export async function runCli(argv = process.argv, context: CliContext = {}) {
+  const program = buildProgram(context);
+  await program.parseAsync(argv);
+}
+
+const isDirectExecution =
+  Boolean(process.argv[1]) && import.meta.url === pathToFileURL(process.argv[1]).href;
+
+if (isDirectExecution) {
+  runCli().catch((error: unknown) => {
+    const message = error instanceof Error ? error.message : String(error);
+    process.stderr.write(`${message}\n`);
+    process.exitCode = 1;
+  });
+}

skills/atlassian/shared/scripts/src/config.ts

@@ -0,0 +1,52 @@
+import path from "node:path";
+
+import { config as loadDotEnv } from "dotenv";
+
+import type { AtlassianConfig } from "./types.js";
+
+function normalizeBaseUrl(value: string) {
+  return value.replace(/\/+$/, "");
+}
+
+function readRequired(env: NodeJS.ProcessEnv, key: string) {
+  const value = env[key]?.trim();
+
+  if (!value) {
+    throw new Error(`Missing required environment variable: ${key}`);
+  }
+
+  return value;
+}
+
+export function loadConfig(
+  env: NodeJS.ProcessEnv = process.env,
+  options?: {
+    cwd?: string;
+  },
+): AtlassianConfig {
+  loadDotEnv({
+    path: path.resolve(options?.cwd ?? process.cwd(), ".env"),
+    processEnv: env as Record<string, string>,
+    override: false,
+  });
+
+  const baseUrl = normalizeBaseUrl(readRequired(env, "ATLASSIAN_BASE_URL"));
+
+  return {
+    baseUrl,
+    jiraBaseUrl: normalizeBaseUrl(env.ATLASSIAN_JIRA_BASE_URL?.trim() || baseUrl),
+    confluenceBaseUrl: normalizeBaseUrl(env.ATLASSIAN_CONFLUENCE_BASE_URL?.trim() || baseUrl),
+    email: readRequired(env, "ATLASSIAN_EMAIL"),
+    apiToken: readRequired(env, "ATLASSIAN_API_TOKEN"),
+    defaultProject: env.ATLASSIAN_DEFAULT_PROJECT?.trim() || undefined,
+    defaultSpace: env.ATLASSIAN_DEFAULT_SPACE?.trim() || undefined,
+  };
+}
+
+export function createBasicAuthHeader(config: {
+  email: string;
+  apiToken: string;
+  [key: string]: unknown;
+}) {
+  return `Basic ${Buffer.from(`${config.email}:${config.apiToken}`).toString("base64")}`;
+}

skills/atlassian/shared/scripts/src/confluence.ts

@@ -0,0 +1,292 @@
+import { sendJsonRequest } from "./http.js";
+import type { AtlassianConfig, CommandOutput, FetchLike } from "./types.js";
+
+type ConfluenceClientOptions = {
+  config: AtlassianConfig;
+  fetchImpl?: FetchLike;
+};
+
+type SearchInput = {
+  query: string;
+  maxResults: number;
+  startAt: number;
+};
+
+type CreateInput = {
+  space?: string;
+  title: string;
+  body: string;
+  dryRun?: boolean;
+};
+
+type UpdateInput = {
+  pageId: string;
+  title: string;
+  body: string;
+  dryRun?: boolean;
+};
+
+type CommentInput = {
+  pageId: string;
+  body: string;
+  dryRun?: boolean;
+};
+
+type PageSummary = {
+  id: string;
+  title: string;
+  type: string;
+  status?: string;
+  spaceId?: string;
+  url?: string;
+};
+
+function buildUrl(baseUrl: string, path: string) {
+  return new URL(path, `${baseUrl}/`).toString();
+}
+
+function normalizePage(baseUrl: string, page: Record<string, unknown>, excerpt?: string) {
+  const links = (page._links ?? {}) as Record<string, unknown>;
+
+  return {
+    id: String(page.id ?? ""),
+    title: String(page.title ?? ""),
+    type: String(page.type ?? "page"),
+    ...(page.status ? { status: String(page.status) } : {}),
+    ...(page.spaceId ? { spaceId: String(page.spaceId) } : {}),
+    ...(excerpt ? { excerpt } : {}),
+    ...(links.webui ? { url: `${baseUrl}${String(links.webui)}` } : {}),
+  };
+}
+
+export function createConfluenceClient(options: ConfluenceClientOptions) {
+  const config = options.config;
+
+  async function getPageForUpdate(pageId: string) {
+    return (await sendJsonRequest({
+      config,
+      fetchImpl: options.fetchImpl,
+      url: buildUrl(config.confluenceBaseUrl, `/wiki/api/v2/pages/${pageId}?body-format=storage`),
+      method: "GET",
+      errorPrefix: "Confluence request failed",
+    })) as Record<string, unknown>;
+  }
+
+  return {
+    async searchPages(input: SearchInput): Promise<CommandOutput<unknown>> {
+      const url = new URL("/wiki/rest/api/search", `${config.confluenceBaseUrl}/`);
+      url.searchParams.set("cql", input.query);
+      url.searchParams.set("limit", String(input.maxResults));
+      url.searchParams.set("start", String(input.startAt));
+
+      const raw = (await sendJsonRequest({
+        config,
+        fetchImpl: options.fetchImpl,
+        url: url.toString(),
+        method: "GET",
+        errorPrefix: "Confluence request failed",
+      })) as Record<string, unknown>;
+
+      const results = Array.isArray(raw.results) ? raw.results : [];
+
+      return {
+        ok: true,
+        data: {
+          pages: results.map((entry) => {
+            const result = entry as Record<string, unknown>;
+            return normalizePage(
+              config.baseUrl,
+              (result.content ?? {}) as Record<string, unknown>,
+              result.excerpt ? String(result.excerpt) : undefined,
+            );
+          }),
+          startAt: Number(raw.start ?? input.startAt),
+          maxResults: Number(raw.limit ?? input.maxResults),
+          total: Number(raw.totalSize ?? raw.size ?? results.length),
+        },
+      };
+    },
+
+    async getPage(pageId: string): Promise<CommandOutput<unknown>> {
+      const raw = (await sendJsonRequest({
+        config,
+        fetchImpl: options.fetchImpl,
+        url: buildUrl(config.confluenceBaseUrl, `/wiki/api/v2/pages/${pageId}?body-format=storage`),
+        method: "GET",
+        errorPrefix: "Confluence request failed",
+      })) as Record<string, unknown>;
+
+      const body = ((raw.body ?? {}) as Record<string, unknown>).storage as Record<string, unknown> | undefined;
+
+      return {
+        ok: true,
+        data: {
+          page: {
+            ...normalizePage(config.baseUrl, raw),
+            version: Number((((raw.version ?? {}) as Record<string, unknown>).number ?? 0)),
+            body: body?.value ? String(body.value) : "",
+          },
+        },
+        raw,
+      };
+    },
+
+    async listChildren(pageId: string, maxResults: number, startAt: number): Promise<CommandOutput<unknown>> {
+      const url = new URL(`/wiki/api/v2/pages/${pageId}/direct-children`, `${config.confluenceBaseUrl}/`);
+      url.searchParams.set("limit", String(maxResults));
+      url.searchParams.set("cursor", String(startAt));
+
+      const raw = (await sendJsonRequest({
+        config,
+        fetchImpl: options.fetchImpl,
+        url: url.toString(),
+        method: "GET",
+        errorPrefix: "Confluence request failed",
+      })) as Record<string, unknown>;
+
+      const results = Array.isArray(raw.results) ? raw.results : [];
+      const links = (raw._links ?? {}) as Record<string, unknown>;
+
+      return {
+        ok: true,
+        data: {
+          pages: results.map((page) => normalizePage(config.baseUrl, page as Record<string, unknown>)),
+          nextCursor: links.next ? String(links.next) : null,
+        },
+      };
+    },
+
+    async createPage(input: CreateInput): Promise<CommandOutput<unknown>> {
+      const spaceId = input.space || config.defaultSpace;
+
+      if (!spaceId) {
+        throw new Error("conf-create requires --space or ATLASSIAN_DEFAULT_SPACE");
+      }
+
+      const request = {
+        method: "POST" as const,
+        url: buildUrl(config.confluenceBaseUrl, "/wiki/api/v2/pages"),
+        body: {
+          spaceId,
+          title: input.title,
+          status: "current",
+          body: {
+            representation: "storage",
+            value: input.body,
+          },
+        },
+      };
+
+      if (input.dryRun) {
+        return {
+          ok: true,
+          dryRun: true,
+          data: request,
+        };
+      }
+
+      const raw = await sendJsonRequest({
+        config,
+        fetchImpl: options.fetchImpl,
+        url: request.url,
+        method: request.method,
+        body: request.body,
+        errorPrefix: "Confluence request failed",
+      });
+
+      return {
+        ok: true,
+        data: raw,
+      };
+    },
+
+    async updatePage(input: UpdateInput): Promise<CommandOutput<unknown>> {
+      const currentPage = await getPageForUpdate(input.pageId);
+      const version = (((currentPage.version ?? {}) as Record<string, unknown>).number ?? 0) as number;
+      const spaceId = String(currentPage.spaceId ?? "");
+
+      const request = {
+        method: "PUT" as const,
+        url: buildUrl(config.confluenceBaseUrl, `/wiki/api/v2/pages/${input.pageId}`),
+        body: {
+          id: input.pageId,
+          status: String(currentPage.status ?? "current"),
+          title: input.title,
+          spaceId,
+          version: {
+            number: Number(version) + 1,
+          },
+          body: {
+            representation: "storage",
+            value: input.body,
+          },
+        },
+      };
+
+      if (input.dryRun) {
+        return {
+          ok: true,
+          dryRun: true,
+          data: request,
+        };
+      }
+
+      const raw = await sendJsonRequest({
+        config,
+        fetchImpl: options.fetchImpl,
+        url: request.url,
+        method: request.method,
+        body: request.body,
+        errorPrefix: "Confluence request failed",
+        handleResponseError(response) {
+          if (response.status === 409) {
+            return new Error(`Confluence update conflict: page ${input.pageId} was updated by someone else`);
+          }
+
+          return undefined;
+        },
+      });
+
+      return {
+        ok: true,
+        data: raw,
+      };
+    },
+
+    async commentPage(input: CommentInput): Promise<CommandOutput<unknown>> {
+      const request = {
+        method: "POST" as const,
+        url: buildUrl(config.confluenceBaseUrl, "/wiki/api/v2/footer-comments"),
+        body: {
+          pageId: input.pageId,
+          body: {
+            representation: "storage",
+            value: input.body,
+          },
+        },
+      };
+
+      if (input.dryRun) {
+        return {
+          ok: true,
+          dryRun: true,
+          data: request,
+        };
+      }
+
+      const raw = await sendJsonRequest({
+        config,
+        fetchImpl: options.fetchImpl,
+        url: request.url,
+        method: request.method,
+        body: request.body,
+        errorPrefix: "Confluence request failed",
+      });
+
+      return {
+        ok: true,
+        data: raw,
+      };
+    },
+  };
+}

skills/atlassian/shared/scripts/src/files.ts

@@ -0,0 +1,13 @@
+import { readFile } from "node:fs/promises";
+import path from "node:path";
+
+export async function readWorkspaceFile(filePath: string, cwd: string) {
+  const resolved = path.resolve(cwd, filePath);
+  const relative = path.relative(cwd, resolved);
+
+  if (relative.startsWith("..") || path.isAbsolute(relative)) {
+    throw new Error(`--body-file must stay within the active workspace: ${filePath}`);
+  }
+
+  return readFile(resolved, "utf8");
+}

skills/atlassian/shared/scripts/src/health.ts

@@ -0,0 +1,69 @@
+import { createJsonHeaders, createStatusError } from "./http.js";
+import type { AtlassianConfig, CommandOutput, FetchLike } from "./types.js";
+
+type ProductHealth = {
+  ok: boolean;
+  status?: number;
+  message?: string;
+};
+
+function buildUrl(baseUrl: string, path: string) {
+  return new URL(path, `${baseUrl}/`).toString();
+}
+
+export async function runHealthCheck(
+  config: AtlassianConfig,
+  fetchImpl: FetchLike | undefined,
+): Promise<CommandOutput<unknown>> {
+  const client = fetchImpl ?? globalThis.fetch;
+
+  if (!client) {
+    throw new Error("Fetch API is not available in this runtime");
+  }
+
+  async function probe(product: "Jira" | "Confluence", url: string): Promise<ProductHealth> {
+    try {
+      const response = await client(url, {
+        method: "GET",
+        headers: createJsonHeaders(config, false),
+      });
+
+      if (!response.ok) {
+        const error = createStatusError(`${product} health check failed`, response);
+        return {
+          ok: false,
+          status: response.status,
+          message: error.message,
+        };
+      }
+
+      return {
+        ok: true,
+        status: response.status,
+      };
+    } catch (error: unknown) {
+      return {
+        ok: false,
+        message: error instanceof Error ? error.message : String(error),
+      };
+    }
+  }
+
+  const jira = await probe("Jira", buildUrl(config.jiraBaseUrl, "/rest/api/3/myself"));
+  const confluence = await probe("Confluence", buildUrl(config.confluenceBaseUrl, "/wiki/api/v2/spaces?limit=1"));
+
+  return {
+    ok: jira.ok && confluence.ok,
+    data: {
+      baseUrl: config.baseUrl,
+      jiraBaseUrl: config.jiraBaseUrl,
+      confluenceBaseUrl: config.confluenceBaseUrl,
+      defaultProject: config.defaultProject,
+      defaultSpace: config.defaultSpace,
+      products: {
+        jira,
+        confluence,
+      },
+    },
+  };
+}

skills/atlassian/shared/scripts/src/http.ts

@@ -0,0 +1,86 @@
+import { createBasicAuthHeader } from "./config.js";
+import type { AtlassianConfig, FetchLike } from "./types.js";
+
+export type HttpMethod = "GET" | "POST" | "PUT";
+
+export function createJsonHeaders(config: AtlassianConfig, includeJsonBody: boolean) {
+  const headers: Array<[string, string]> = [
+    ["Accept", "application/json"],
+    ["Authorization", createBasicAuthHeader(config)],
+  ];
+
+  if (includeJsonBody) {
+    headers.push(["Content-Type", "application/json"]);
+  }
+
+  return headers;
+}
+
+export async function parseResponse(response: Response) {
+  if (response.status === 204) {
+    return null;
+  }
+
+  const contentType = response.headers.get("content-type") ?? "";
+
+  if (contentType.includes("application/json")) {
+    try {
+      return await response.json();
+    } catch {
+      throw new Error("Malformed JSON response from Atlassian API");
+    }
+  }
+
+  return response.text();
+}
+
+export function createStatusError(errorPrefix: string, response: Response) {
+  const base = `${errorPrefix}: ${response.status} ${response.statusText}`;
+
+  switch (response.status) {
+    case 401:
+      return new Error(`${base} - check ATLASSIAN_EMAIL and ATLASSIAN_API_TOKEN`);
+    case 403:
+      return new Error(`${base} - verify product permissions for this account`);
+    case 404:
+      return new Error(`${base} - verify the resource identifier or API path`);
+    case 429:
+      return new Error(`${base} - retry later or reduce request rate`);
+    default:
+      return new Error(base);
+  }
+}
+
+export async function sendJsonRequest(options: {
+  config: AtlassianConfig;
+  fetchImpl?: FetchLike;
+  url: string;
+  method: HttpMethod;
+  body?: unknown;
+  errorPrefix: string;
+  handleResponseError?: (response: Response) => Error | undefined;
+}) {
+  const fetchImpl = options.fetchImpl ?? globalThis.fetch;
+
+  if (!fetchImpl) {
+    throw new Error("Fetch API is not available in this runtime");
+  }
+
+  const response = await fetchImpl(options.url, {
+    method: options.method,
+    headers: createJsonHeaders(options.config, options.body !== undefined),
+    ...(options.body === undefined ? {} : { body: JSON.stringify(options.body) }),
+  });
+
+  if (!response.ok) {
+    const customError = options.handleResponseError?.(response);
+
+    if (customError) {
+      throw customError;
+    }
+
+    throw createStatusError(options.errorPrefix, response);
+  }
+
+  return parseResponse(response);
+}

skills/atlassian/shared/scripts/src/jira.ts

@@ -0,0 +1,264 @@
+import { markdownToAdf } from "./adf.js";
+import { sendJsonRequest } from "./http.js";
+import type { AtlassianConfig, CommandOutput, FetchLike, JiraIssueSummary } from "./types.js";
+
+const ISSUE_FIELDS = ["summary", "issuetype", "status", "assignee", "created", "updated"] as const;
+
+type JiraClientOptions = {
+  config: AtlassianConfig;
+  fetchImpl?: FetchLike;
+};
+
+type SearchInput = {
+  jql: string;
+  maxResults: number;
+  startAt: number;
+};
+
+type CreateInput = {
+  project?: string;
+  type: string;
+  summary: string;
+  description?: string;
+  dryRun?: boolean;
+};
+
+type UpdateInput = {
+  issue: string;
+  summary?: string;
+  description?: string;
+  dryRun?: boolean;
+};
+
+type CommentInput = {
+  issue: string;
+  body: string;
+  dryRun?: boolean;
+};
+
+type TransitionInput = {
+  issue: string;
+  transition: string;
+  dryRun?: boolean;
+};
+
+function normalizeIssue(config: AtlassianConfig, issue: Record<string, unknown>): JiraIssueSummary {
+  const fields = (issue.fields ?? {}) as Record<string, unknown>;
+  const issueType = (fields.issuetype ?? {}) as Record<string, unknown>;
+  const status = (fields.status ?? {}) as Record<string, unknown>;
+  const assignee = (fields.assignee ?? {}) as Record<string, unknown>;
+
+  return {
+    key: String(issue.key ?? ""),
+    summary: String(fields.summary ?? ""),
+    issueType: String(issueType.name ?? ""),
+    status: String(status.name ?? ""),
+    assignee: assignee.displayName ? String(assignee.displayName) : undefined,
+    created: String(fields.created ?? ""),
+    updated: String(fields.updated ?? ""),
+    url: `${config.baseUrl}/browse/${issue.key ?? ""}`,
+  };
+}
+
+function createRequest(config: AtlassianConfig, method: "GET" | "POST" | "PUT", path: string, body?: unknown) {
+  const url = new URL(path, `${config.jiraBaseUrl}/`);
+
+  return {
+    method,
+    url: url.toString(),
+    ...(body === undefined ? {} : { body }),
+  };
+}
+
+export function createJiraClient(options: JiraClientOptions) {
+  const fetchImpl = options.fetchImpl ?? globalThis.fetch;
+
+  if (!fetchImpl) {
+    throw new Error("Fetch API is not available in this runtime");
+  }
+
+  async function send(method: "GET" | "POST" | "PUT", path: string, body?: unknown) {
+    const request = createRequest(options.config, method, path, body);
+    return sendJsonRequest({
+      config: options.config,
+      fetchImpl,
+      url: request.url,
+      method,
+      body,
+      errorPrefix: "Jira request failed",
+    });
+  }
+
+  return {
+    async searchIssues(input: SearchInput): Promise<CommandOutput<unknown>> {
+      const raw = (await send("POST", "/rest/api/3/search", {
+        jql: input.jql,
+        maxResults: input.maxResults,
+        startAt: input.startAt,
+        fields: [...ISSUE_FIELDS],
+      })) as Record<string, unknown>;
+
+      const issues = Array.isArray(raw.issues) ? raw.issues : [];
+
+      return {
+        ok: true,
+        data: {
+          issues: issues.map((issue) => normalizeIssue(options.config, issue as Record<string, unknown>)),
+          startAt: Number(raw.startAt ?? input.startAt),
+          maxResults: Number(raw.maxResults ?? input.maxResults),
+          total: Number(raw.total ?? issues.length),
+        },
+      };
+    },
+
+    async getIssue(issue: string): Promise<CommandOutput<unknown>> {
+      const url = new URL(`/rest/api/3/issue/${issue}`, `${options.config.jiraBaseUrl}/`);
+      url.searchParams.set("fields", ISSUE_FIELDS.join(","));
+
+      const raw = (await send("GET", `${url.pathname}${url.search}`)) as Record<string, unknown>;
+
+      return {
+        ok: true,
+        data: {
+          issue: normalizeIssue(options.config, raw),
+        },
+        raw,
+      };
+    },
+
+    async getTransitions(issue: string): Promise<CommandOutput<unknown>> {
+      const raw = (await send(
+        "GET",
+        `/rest/api/3/issue/${issue}/transitions`,
+      )) as { transitions?: Array<Record<string, unknown>> };
+
+      return {
+        ok: true,
+        data: {
+          transitions: (raw.transitions ?? []).map((transition) => ({
+            id: String(transition.id ?? ""),
+            name: String(transition.name ?? ""),
+            toStatus: String(((transition.to ?? {}) as Record<string, unknown>).name ?? ""),
+            hasScreen: Boolean(transition.hasScreen),
+          })),
+        },
+      };
+    },
+
+    async createIssue(input: CreateInput): Promise<CommandOutput<unknown>> {
+      const project = input.project || options.config.defaultProject;
+
+      if (!project) {
+        throw new Error("jira-create requires --project or ATLASSIAN_DEFAULT_PROJECT");
+      }
+
+      const request = createRequest(options.config, "POST", "/rest/api/3/issue", {
+        fields: {
+          project: { key: project },
+          issuetype: { name: input.type },
+          summary: input.summary,
+          ...(input.description ? { description: markdownToAdf(input.description) } : {}),
+        },
+      });
+
+      if (input.dryRun) {
+        return {
+          ok: true,
+          dryRun: true,
+          data: request,
+        };
+      }
+
+      const raw = await send("POST", "/rest/api/3/issue", request.body);
+      return { ok: true, data: raw };
+    },
+
+    async updateIssue(input: UpdateInput): Promise<CommandOutput<unknown>> {
+      const fields: Record<string, unknown> = {};
+
+      if (input.summary) {
+        fields.summary = input.summary;
+      }
+
+      if (input.description) {
+        fields.description = markdownToAdf(input.description);
+      }
+
+      if (Object.keys(fields).length === 0) {
+        throw new Error("jira-update requires --summary and/or --description-file");
+      }
+
+      const request = createRequest(options.config, "PUT", `/rest/api/3/issue/${input.issue}`, {
+        fields,
+      });
+
+      if (input.dryRun) {
+        return {
+          ok: true,
+          dryRun: true,
+          data: request,
+        };
+      }
+
+      await send("PUT", `/rest/api/3/issue/${input.issue}`, request.body);
+      return {
+        ok: true,
+        data: {
+          issue: input.issue,
+          updated: true,
+        },
+      };
+    },
+
+    async commentIssue(input: CommentInput): Promise<CommandOutput<unknown>> {
+      const request = createRequest(options.config, "POST", `/rest/api/3/issue/${input.issue}/comment`, {
+        body: markdownToAdf(input.body),
+      });
+
+      if (input.dryRun) {
+        return {
+          ok: true,
+          dryRun: true,
+          data: request,
+        };
+      }
+
+      const raw = await send("POST", `/rest/api/3/issue/${input.issue}/comment`, request.body);
+      return {
+        ok: true,
+        data: raw,
+      };
+    },
+
+    async transitionIssue(input: TransitionInput): Promise<CommandOutput<unknown>> {
+      const request = createRequest(
+        options.config,
+        "POST",
+        `/rest/api/3/issue/${input.issue}/transitions`,
+        {
+          transition: {
+            id: input.transition,
+          },
+        },
+      );
+
+      if (input.dryRun) {
+        return {
+          ok: true,
+          dryRun: true,
+          data: request,
+        };
+      }
+
+      await send("POST", `/rest/api/3/issue/${input.issue}/transitions`, request.body);
+      return {
+        ok: true,
+        data: {
+          issue: input.issue,
+          transitioned: true,
+          transition: input.transition,
+        },
+      };
+    },
+  };
+}

skills/atlassian/shared/scripts/src/output.ts

@@ -0,0 +1,44 @@
+import type { CommandOutput, OutputFormat, Writer } from "./types.js";
+
+function renderText(payload: CommandOutput<unknown>) {
+  const data = payload.data as Record<string, unknown>;
+
+  if (Array.isArray(data?.issues)) {
+    return data.issues
+      .map((issue) => {
+        const item = issue as Record<string, string>;
+        return `${item.key} [${item.status}] ${item.issueType} - ${item.summary}`;
+      })
+      .join("\n");
+  }
+
+  if (data?.issue && typeof data.issue === "object") {
+    const issue = data.issue as Record<string, string>;
+    return [
+      issue.key,
+      `${issue.issueType} | ${issue.status}`,
+      issue.summary,
+      issue.url,
+    ].join("\n");
+  }
+
+  if (Array.isArray(data?.transitions)) {
+    return data.transitions
+      .map((transition) => {
+        const item = transition as Record<string, string>;
+        return `${item.id} ${item.name} -> ${item.toStatus}`;
+      })
+      .join("\n");
+  }
+
+  return JSON.stringify(payload, null, 2);
+}
+
+export function writeOutput(
+  writer: Writer,
+  payload: CommandOutput<unknown>,
+  format: OutputFormat = "json",
+) {
+  const body = format === "text" ? renderText(payload) : JSON.stringify(payload, null, 2);
+  writer.write(`${body}\n`);
+}

skills/atlassian/shared/scripts/src/raw.ts

@@ -0,0 +1,85 @@
+import { readWorkspaceFile } from "./files.js";
+import { sendJsonRequest } from "./http.js";
+import type { AtlassianConfig, CommandOutput, FetchLike } from "./types.js";
+
+const JIRA_ALLOWED_PREFIXES = ["/rest/api/3/"] as const;
+const CONFLUENCE_ALLOWED_PREFIXES = ["/wiki/api/v2/", "/wiki/rest/api/"] as const;
+
+type RawInput = {
+  product: "jira" | "confluence";
+  method: string;
+  path: string;
+  bodyFile?: string;
+  cwd: string;
+  dryRun?: boolean;
+};
+
+function getAllowedPrefixes(product: RawInput["product"]) {
+  return product === "jira" ? JIRA_ALLOWED_PREFIXES : CONFLUENCE_ALLOWED_PREFIXES;
+}
+
+function buildUrl(config: AtlassianConfig, product: RawInput["product"], path: string) {
+  const baseUrl = product === "jira" ? config.jiraBaseUrl : config.confluenceBaseUrl;
+  return new URL(path, `${baseUrl}/`).toString();
+}
+
+function validateMethod(method: string): asserts method is "GET" | "POST" | "PUT" {
+  if (!["GET", "POST", "PUT"].includes(method)) {
+    throw new Error("raw only allows GET, POST, and PUT");
+  }
+}
+
+function validatePath(product: RawInput["product"], path: string) {
+  const allowedPrefixes = getAllowedPrefixes(product);
+
+  if (!allowedPrefixes.some((prefix) => path.startsWith(prefix))) {
+    throw new Error(`raw path is not allowed for ${product}: ${path}`);
+  }
+}
+
+async function readRawBody(bodyFile: string | undefined, cwd: string) {
+  if (!bodyFile) {
+    return undefined;
+  }
+
+  const contents = await readWorkspaceFile(bodyFile, cwd);
+  return JSON.parse(contents) as unknown;
+}
+
+export async function runRawCommand(
+  config: AtlassianConfig,
+  fetchImpl: FetchLike | undefined,
+  input: RawInput,
+): Promise<CommandOutput<unknown>> {
+  validateMethod(input.method);
+  validatePath(input.product, input.path);
+
+  const body = await readRawBody(input.bodyFile, input.cwd);
+  const request = {
+    method: input.method,
+    url: buildUrl(config, input.product, input.path),
+    ...(body === undefined ? {} : { body }),
+  };
+
+  if (input.dryRun) {
+    return {
+      ok: true,
+      dryRun: true,
+      data: request,
+    };
+  }
+
+  const data = await sendJsonRequest({
+    config,
+    fetchImpl,
+    url: request.url,
+    method: input.method,
+    body,
+    errorPrefix: "Raw request failed",
+  });
+
+  return {
+    ok: true,
+    data,
+  };
+}

skills/atlassian/shared/scripts/src/types.ts

@@ -0,0 +1,35 @@
+export type AtlassianConfig = {
+  baseUrl: string;
+  jiraBaseUrl: string;
+  confluenceBaseUrl: string;
+  email: string;
+  apiToken: string;
+  defaultProject?: string;
+  defaultSpace?: string;
+};
+
+export type CommandOutput<T> = {
+  ok: boolean;
+  data: T;
+  dryRun?: boolean;
+  raw?: unknown;
+};
+
+export type JiraIssueSummary = {
+  key: string;
+  summary: string;
+  issueType: string;
+  status: string;
+  assignee?: string;
+  created: string;
+  updated: string;
+  url: string;
+};
+
+export type Writer = {
+  write(chunk: string | Uint8Array): unknown;
+};
+
+export type FetchLike = typeof fetch;
+
+export type OutputFormat = "json" | "text";

skills/atlassian/shared/scripts/tests/cli-help.test.ts

@@ -0,0 +1,14 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+import { spawnSync } from "node:child_process";
+
+test("CLI help prints the Atlassian skill banner", () => {
+  const result = spawnSync("pnpm", ["exec", "tsx", "src/cli.ts", "--help"], {
+    cwd: new URL("../", import.meta.url),
+    encoding: "utf8",
+  });
+
+  assert.equal(result.status, 0, result.stderr);
+  assert.match(result.stdout, /Portable Atlassian CLI for multi-agent skills/);
+  assert.match(result.stdout, /Usage:/);
+});

skills/atlassian/shared/scripts/tests/config.test.ts

@@ -0,0 +1,38 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+
+import { createBasicAuthHeader, loadConfig } from "../src/config.js";
+
+test("loadConfig derives Jira and Confluence base URLs from ATLASSIAN_BASE_URL", () => {
+  const config = loadConfig({
+    ATLASSIAN_BASE_URL: "https://example.atlassian.net/",
+    ATLASSIAN_EMAIL: "dev@example.com",
+    ATLASSIAN_API_TOKEN: "secret-token",
+    ATLASSIAN_DEFAULT_PROJECT: "ENG",
+  });
+
+  assert.deepEqual(config, {
+    baseUrl: "https://example.atlassian.net",
+    jiraBaseUrl: "https://example.atlassian.net",
+    confluenceBaseUrl: "https://example.atlassian.net",
+    email: "dev@example.com",
+    apiToken: "secret-token",
+    defaultProject: "ENG",
+    defaultSpace: undefined,
+  });
+});
+
+test("createBasicAuthHeader encodes email and API token for Atlassian Cloud", () => {
+  const header = createBasicAuthHeader({
+    baseUrl: "https://example.atlassian.net",
+    jiraBaseUrl: "https://example.atlassian.net",
+    confluenceBaseUrl: "https://example.atlassian.net",
+    email: "dev@example.com",
+    apiToken: "secret-token",
+  });
+
+  assert.equal(
+    header,
+    `Basic ${Buffer.from("dev@example.com:secret-token").toString("base64")}`,
+  );
+});

skills/atlassian/shared/scripts/tests/confluence.test.ts

@@ -0,0 +1,351 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+
+import { createTempWorkspace, jsonResponse, runCli } from "./helpers.js";
+
+const baseEnv = {
+  ATLASSIAN_BASE_URL: "https://example.atlassian.net",
+  ATLASSIAN_EMAIL: "dev@example.com",
+  ATLASSIAN_API_TOKEN: "secret-token",
+};
+
+test("conf-search uses CQL search and normalizes page results", async () => {
+  const calls: Array<{ url: string; init: RequestInit | undefined }> = [];
+  const fetchImpl: typeof fetch = async (input, init) => {
+    calls.push({ url: typeof input === "string" ? input : input.toString(), init });
+
+    return jsonResponse({
+      results: [
+        {
+          content: {
+            id: "123",
+            type: "page",
+            title: "Runbook",
+            _links: { webui: "/spaces/OPS/pages/123/Runbook" },
+          },
+          excerpt: "Operational runbook",
+        },
+      ],
+      start: 5,
+      limit: 1,
+      size: 1,
+      totalSize: 7,
+    });
+  };
+
+  const result = await runCli({
+    args: ["conf-search", "--query", "title ~ \"Runbook\"", "--max-results", "1", "--start-at", "5"],
+    env: baseEnv,
+    fetchImpl,
+  });
+
+  assert.equal(calls.length, 1);
+  assert.equal(
+    calls[0]?.url,
+    "https://example.atlassian.net/wiki/rest/api/search?cql=title+%7E+%22Runbook%22&limit=1&start=5",
+  );
+  assert.equal(calls[0]?.init?.method, "GET");
+
+  assert.deepEqual(JSON.parse(result.stdout), {
+    ok: true,
+    data: {
+      pages: [
+        {
+          id: "123",
+          title: "Runbook",
+          type: "page",
+          excerpt: "Operational runbook",
+          url: "https://example.atlassian.net/spaces/OPS/pages/123/Runbook",
+        },
+      ],
+      startAt: 5,
+      maxResults: 1,
+      total: 7,
+    },
+  });
+});
+
+test("conf-get returns normalized page details plus raw payload", async () => {
+  const rawPage = {
+    id: "123",
+    status: "current",
+    title: "Runbook",
+    spaceId: "OPS",
+    version: { number: 4 },
+    body: {
+      storage: {
+        value: "<p>Runbook</p>",
+        representation: "storage",
+      },
+    },
+    _links: {
+      webui: "/spaces/OPS/pages/123/Runbook",
+    },
+  };
+
+  const result = await runCli({
+    args: ["conf-get", "--page", "123"],
+    env: baseEnv,
+    fetchImpl: async () => jsonResponse(rawPage),
+  });
+
+  assert.deepEqual(JSON.parse(result.stdout), {
+    ok: true,
+    data: {
+      page: {
+        id: "123",
+        title: "Runbook",
+        type: "page",
+        status: "current",
+        spaceId: "OPS",
+        version: 4,
+        body: "<p>Runbook</p>",
+        url: "https://example.atlassian.net/spaces/OPS/pages/123/Runbook",
+      },
+    },
+    raw: rawPage,
+  });
+});
+
+test("conf-children returns normalized direct children with pagination", async () => {
+  const result = await runCli({
+    args: ["conf-children", "--page", "123", "--max-results", "2", "--start-at", "1"],
+    env: baseEnv,
+    fetchImpl: async (input) => {
+      const url = typeof input === "string" ? input : input.toString();
+      assert.equal(
+        url,
+        "https://example.atlassian.net/wiki/api/v2/pages/123/direct-children?limit=2&cursor=1",
+      );
+
+      return jsonResponse({
+        results: [
+          {
+            id: "124",
+            title: "Child page",
+            type: "page",
+            status: "current",
+            spaceId: "OPS",
+            _links: { webui: "/spaces/OPS/pages/124/Child+page" },
+          },
+        ],
+      });
+    },
+  });
+
+  assert.deepEqual(JSON.parse(result.stdout), {
+    ok: true,
+    data: {
+      pages: [
+        {
+          id: "124",
+          title: "Child page",
+          type: "page",
+          status: "current",
+          spaceId: "OPS",
+          url: "https://example.atlassian.net/spaces/OPS/pages/124/Child+page",
+        },
+      ],
+      nextCursor: null,
+    },
+  });
+});
+
+test("conf-create dry-run emits a storage-format request body", async () => {
+  const workspace = createTempWorkspace();
+
+  try {
+    workspace.write("page.storage.html", "<p>Runbook</p>");
+
+    const result = await runCli({
+      args: [
+        "conf-create",
+        "--title",
+        "Runbook",
+        "--body-file",
+        "page.storage.html",
+        "--dry-run",
+      ],
+      cwd: workspace.cwd,
+      env: {
+        ...baseEnv,
+        ATLASSIAN_DEFAULT_SPACE: "OPS",
+      },
+    });
+
+    assert.deepEqual(JSON.parse(result.stdout), {
+      ok: true,
+      dryRun: true,
+      data: {
+        method: "POST",
+        url: "https://example.atlassian.net/wiki/api/v2/pages",
+        body: {
+          spaceId: "OPS",
+          title: "Runbook",
+          status: "current",
+          body: {
+            representation: "storage",
+            value: "<p>Runbook</p>",
+          },
+        },
+      },
+    });
+  } finally {
+    workspace.cleanup();
+  }
+});
+
+test("conf-update fetches the current page version and increments it for dry-run", async () => {
+  const workspace = createTempWorkspace();
+  const calls: Array<{ url: string; init: RequestInit | undefined }> = [];
+
+  try {
+    workspace.write("page.storage.html", "<p>Updated</p>");
+
+    const result = await runCli({
+      args: [
+        "conf-update",
+        "--page",
+        "123",
+        "--title",
+        "Runbook",
+        "--body-file",
+        "page.storage.html",
+        "--dry-run",
+      ],
+      cwd: workspace.cwd,
+      env: baseEnv,
+      fetchImpl: async (input, init) => {
+        calls.push({ url: typeof input === "string" ? input : input.toString(), init });
+        return jsonResponse({
+          id: "123",
+          spaceId: "OPS",
+          status: "current",
+          title: "Runbook",
+          version: { number: 4 },
+          body: {
+            storage: {
+              value: "<p>Old</p>",
+              representation: "storage",
+            },
+          },
+        });
+      },
+    });
+
+    assert.equal(calls.length, 1);
+    assert.equal(
+      calls[0]?.url,
+      "https://example.atlassian.net/wiki/api/v2/pages/123?body-format=storage",
+    );
+
+    assert.deepEqual(JSON.parse(result.stdout), {
+      ok: true,
+      dryRun: true,
+      data: {
+        method: "PUT",
+        url: "https://example.atlassian.net/wiki/api/v2/pages/123",
+        body: {
+          id: "123",
+          status: "current",
+          title: "Runbook",
+          spaceId: "OPS",
+          version: {
+            number: 5,
+          },
+          body: {
+            representation: "storage",
+            value: "<p>Updated</p>",
+          },
+        },
+      },
+    });
+  } finally {
+    workspace.cleanup();
+  }
+});
+
+test("conf-comment dry-run targets footer comments", async () => {
+  const workspace = createTempWorkspace();
+
+  try {
+    workspace.write("comment.storage.html", "<p>Looks good</p>");
+
+    const result = await runCli({
+      args: ["conf-comment", "--page", "123", "--body-file", "comment.storage.html", "--dry-run"],
+      cwd: workspace.cwd,
+      env: baseEnv,
+    });
+
+    assert.deepEqual(JSON.parse(result.stdout), {
+      ok: true,
+      dryRun: true,
+      data: {
+        method: "POST",
+        url: "https://example.atlassian.net/wiki/api/v2/footer-comments",
+        body: {
+          pageId: "123",
+          body: {
+            representation: "storage",
+            value: "<p>Looks good</p>",
+          },
+        },
+      },
+    });
+  } finally {
+    workspace.cleanup();
+  }
+});
+
+test("conf-update surfaces version conflicts clearly", async () => {
+  const workspace = createTempWorkspace();
+
+  try {
+    workspace.write("page.storage.html", "<p>Updated</p>");
+
+    await assert.rejects(
+      runCli({
+        args: [
+          "conf-update",
+          "--page",
+          "123",
+          "--title",
+          "Runbook",
+          "--body-file",
+          "page.storage.html",
+        ],
+        cwd: workspace.cwd,
+        env: baseEnv,
+        fetchImpl: async (input, init) => {
+          const url = typeof input === "string" ? input : input.toString();
+
+          if (url.endsWith("?body-format=storage")) {
+            return jsonResponse({
+              id: "123",
+              spaceId: "OPS",
+              status: "current",
+              title: "Runbook",
+              version: { number: 4 },
+              body: {
+                storage: {
+                  value: "<p>Old</p>",
+                  representation: "storage",
+                },
+              },
+            });
+          }
+
+          assert.equal(init?.method, "PUT");
+          return new Response(JSON.stringify({ message: "Conflict" }), {
+            status: 409,
+            statusText: "Conflict",
+            headers: { "content-type": "application/json" },
+          });
+        },
+      }),
+      /Confluence update conflict: page 123 was updated by someone else/,
+    );
+  } finally {
+    workspace.cleanup();
+  }
+});

skills/atlassian/shared/scripts/tests/helpers.ts

@@ -0,0 +1,72 @@
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import path from "node:path";
+
+import { buildProgram } from "../src/cli.js";
+
+type RunCliOptions = {
+  args: string[];
+  cwd?: string;
+  env?: NodeJS.ProcessEnv;
+  fetchImpl?: typeof fetch;
+};
+
+class MemoryWriter {
+  private readonly chunks: string[] = [];
+
+  write(chunk: string | Uint8Array) {
+    this.chunks.push(typeof chunk === "string" ? chunk : Buffer.from(chunk).toString("utf8"));
+    return true;
+  }
+
+  toString() {
+    return this.chunks.join("");
+  }
+}
+
+export async function runCli(options: RunCliOptions) {
+  const stdout = new MemoryWriter();
+  const stderr = new MemoryWriter();
+  const program = buildProgram({
+    cwd: options.cwd,
+    env: options.env,
+    fetchImpl: options.fetchImpl,
+    stdout,
+    stderr,
+  });
+
+  await program.parseAsync(options.args, { from: "user" });
+
+  return {
+    stdout: stdout.toString(),
+    stderr: stderr.toString(),
+  };
+}
+
+export function createTempWorkspace() {
+  const cwd = mkdtempSync(path.join(tmpdir(), "atlassian-skill-"));
+
+  return {
+    cwd,
+    cleanup() {
+      rmSync(cwd, { recursive: true, force: true });
+    },
+    write(relativePath: string, contents: string) {
+      const target = path.join(cwd, relativePath);
+      mkdirSync(path.dirname(target), { recursive: true });
+      writeFileSync(target, contents, "utf8");
+      return target;
+    },
+  };
+}
+
+export function jsonResponse(payload: unknown, init?: ResponseInit) {
+  return new Response(JSON.stringify(payload), {
+    status: init?.status ?? 200,
+    statusText: init?.statusText,
+    headers: {
+      "content-type": "application/json",
+      ...(init?.headers ?? {}),
+    },
+  });
+}

skills/atlassian/shared/scripts/tests/http.test.ts

@@ -0,0 +1,131 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+
+import { sendJsonRequest } from "../src/http.js";
+import { runCli } from "./helpers.js";
+
+const baseConfig = {
+  baseUrl: "https://example.atlassian.net",
+  jiraBaseUrl: "https://example.atlassian.net",
+  confluenceBaseUrl: "https://example.atlassian.net",
+  email: "dev@example.com",
+  apiToken: "secret-token",
+};
+
+const baseEnv = {
+  ATLASSIAN_BASE_URL: "https://example.atlassian.net",
+  ATLASSIAN_EMAIL: "dev@example.com",
+  ATLASSIAN_API_TOKEN: "secret-token",
+};
+
+test("health probes Jira and Confluence independently", async () => {
+  const calls: string[] = [];
+
+  const result = await runCli({
+    args: ["health"],
+    env: baseEnv,
+    fetchImpl: async (input) => {
+      const url = typeof input === "string" ? input : input.toString();
+      calls.push(url);
+
+      if (url.endsWith("/rest/api/3/myself")) {
+        return new Response(JSON.stringify({ accountId: "1" }), {
+          status: 200,
+          headers: { "content-type": "application/json" },
+        });
+      }
+
+      return new Response(JSON.stringify({ message: "Forbidden" }), {
+        status: 403,
+        statusText: "Forbidden",
+        headers: { "content-type": "application/json" },
+      });
+    },
+  });
+
+  assert.deepEqual(calls, [
+    "https://example.atlassian.net/rest/api/3/myself",
+    "https://example.atlassian.net/wiki/api/v2/spaces?limit=1",
+  ]);
+
+  assert.deepEqual(JSON.parse(result.stdout), {
+    ok: false,
+    data: {
+      baseUrl: "https://example.atlassian.net",
+      jiraBaseUrl: "https://example.atlassian.net",
+      confluenceBaseUrl: "https://example.atlassian.net",
+      products: {
+        jira: {
+          ok: true,
+          status: 200,
+        },
+        confluence: {
+          ok: false,
+          status: 403,
+          message:
+            "Confluence health check failed: 403 Forbidden - verify product permissions for this account",
+        },
+      },
+    },
+  });
+});
+
+test("sendJsonRequest maps 401, 403, 404, and 429 to actionable messages", async () => {
+  const cases = [
+    {
+      status: 401,
+      statusText: "Unauthorized",
+      expected: /401 Unauthorized - check ATLASSIAN_EMAIL and ATLASSIAN_API_TOKEN/,
+    },
+    {
+      status: 403,
+      statusText: "Forbidden",
+      expected: /403 Forbidden - verify product permissions for this account/,
+    },
+    {
+      status: 404,
+      statusText: "Not Found",
+      expected: /404 Not Found - verify the resource identifier or API path/,
+    },
+    {
+      status: 429,
+      statusText: "Too Many Requests",
+      expected: /429 Too Many Requests - retry later or reduce request rate/,
+    },
+  ] as const;
+
+  for (const entry of cases) {
+    await assert.rejects(
+      sendJsonRequest({
+        config: baseConfig,
+        url: "https://example.atlassian.net/rest/api/3/issue/ENG-1",
+        method: "GET",
+        errorPrefix: "Jira request failed",
+        fetchImpl: async () =>
+          new Response(JSON.stringify({ message: entry.statusText }), {
+            status: entry.status,
+            statusText: entry.statusText,
+            headers: { "content-type": "application/json" },
+          }),
+      }),
+      entry.expected,
+    );
+  }
+});
+
+test("sendJsonRequest reports malformed JSON responses clearly", async () => {
+  await assert.rejects(
+    sendJsonRequest({
+      config: baseConfig,
+      url: "https://example.atlassian.net/rest/api/3/issue/ENG-1",
+      method: "GET",
+      errorPrefix: "Jira request failed",
+      fetchImpl: async () =>
+        new Response("{", {
+          status: 200,
+          headers: { "content-type": "application/json" },
+        }),
+    }),
+    /Malformed JSON response from Atlassian API/,
+  );
+});

skills/atlassian/shared/scripts/tests/jira.test.ts

@@ -0,0 +1,321 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+
+import { markdownToAdf } from "../src/adf.js";
+import { createTempWorkspace, jsonResponse, runCli } from "./helpers.js";
+
+const baseEnv = {
+  ATLASSIAN_BASE_URL: "https://example.atlassian.net",
+  ATLASSIAN_EMAIL: "dev@example.com",
+  ATLASSIAN_API_TOKEN: "secret-token",
+};
+
+test("jira-search emits normalized results and uses pagination inputs", async () => {
+  const calls: Array<{ url: string; init: RequestInit | undefined }> = [];
+
+  const fetchImpl: typeof fetch = async (input, init) => {
+    const url = typeof input === "string" ? input : input.toString();
+    calls.push({ url, init });
+
+    return jsonResponse({
+      startAt: 10,
+      maxResults: 2,
+      total: 25,
+      issues: [
+        {
+          key: "ENG-1",
+          fields: {
+            summary: "Add Jira search command",
+            issuetype: { name: "Story" },
+            status: { name: "In Progress" },
+            assignee: { displayName: "Ada Lovelace" },
+            created: "2026-03-01T00:00:00.000Z",
+            updated: "2026-03-02T00:00:00.000Z",
+          },
+        },
+      ],
+    });
+  };
+
+  const result = await runCli({
+    args: ["jira-search", "--jql", "project = ENG", "--max-results", "2", "--start-at", "10"],
+    env: baseEnv,
+    fetchImpl,
+  });
+
+  assert.equal(calls.length, 1);
+  assert.equal(calls[0]?.url, "https://example.atlassian.net/rest/api/3/search");
+  assert.equal(calls[0]?.init?.method, "POST");
+  assert.match(String(calls[0]?.init?.headers), /Authorization/);
+  assert.deepEqual(JSON.parse(String(calls[0]?.init?.body)), {
+    jql: "project = ENG",
+    maxResults: 2,
+    startAt: 10,
+    fields: ["summary", "issuetype", "status", "assignee", "created", "updated"],
+  });
+
+  assert.deepEqual(JSON.parse(result.stdout), {
+    ok: true,
+    data: {
+      issues: [
+        {
+          key: "ENG-1",
+          summary: "Add Jira search command",
+          issueType: "Story",
+          status: "In Progress",
+          assignee: "Ada Lovelace",
+          created: "2026-03-01T00:00:00.000Z",
+          updated: "2026-03-02T00:00:00.000Z",
+          url: "https://example.atlassian.net/browse/ENG-1",
+        },
+      ],
+      startAt: 10,
+      maxResults: 2,
+      total: 25,
+    },
+  });
+});
+
+test("jira-get returns normalized fields plus the raw Jira payload", async () => {
+  const rawIssue = {
+    key: "ENG-42",
+    fields: {
+      summary: "Ship v1",
+      issuetype: { name: "Task" },
+      status: { name: "Done" },
+      assignee: { displayName: "Grace Hopper" },
+      created: "2026-03-03T00:00:00.000Z",
+      updated: "2026-03-04T00:00:00.000Z",
+    },
+  };
+
+  const fetchImpl: typeof fetch = async () => jsonResponse(rawIssue);
+
+  const result = await runCli({
+    args: ["jira-get", "--issue", "ENG-42"],
+    env: baseEnv,
+    fetchImpl,
+  });
+
+  assert.deepEqual(JSON.parse(result.stdout), {
+    ok: true,
+    data: {
+      issue: {
+        key: "ENG-42",
+        summary: "Ship v1",
+        issueType: "Task",
+        status: "Done",
+        assignee: "Grace Hopper",
+        created: "2026-03-03T00:00:00.000Z",
+        updated: "2026-03-04T00:00:00.000Z",
+        url: "https://example.atlassian.net/browse/ENG-42",
+      },
+    },
+    raw: rawIssue,
+  });
+});
+
+test("markdownToAdf converts headings, paragraphs, and bullet lists", () => {
+  assert.deepEqual(markdownToAdf("# Summary\n\nBuild the Jira skill.\n\n- Search\n- Comment"), {
+    type: "doc",
+    version: 1,
+    content: [
+      {
+        type: "heading",
+        attrs: { level: 1 },
+        content: [{ type: "text", text: "Summary" }],
+      },
+      {
+        type: "paragraph",
+        content: [{ type: "text", text: "Build the Jira skill." }],
+      },
+      {
+        type: "bulletList",
+        content: [
+          {
+            type: "listItem",
+            content: [
+              {
+                type: "paragraph",
+                content: [{ type: "text", text: "Search" }],
+              },
+            ],
+          },
+          {
+            type: "listItem",
+            content: [
+              {
+                type: "paragraph",
+                content: [{ type: "text", text: "Comment" }],
+              },
+            ],
+          },
+        ],
+      },
+    ],
+  });
+});
+
+test("jira-create dry-run emits an ADF request body without calling Jira", async () => {
+  const workspace = createTempWorkspace();
+
+  try {
+    workspace.write("description.md", "# New story\n\n- one\n- two");
+    let called = false;
+
+    const result = await runCli({
+      args: [
+        "jira-create",
+        "--type",
+        "Story",
+        "--summary",
+        "Create the Atlassian skill",
+        "--description-file",
+        "description.md",
+        "--dry-run",
+      ],
+      cwd: workspace.cwd,
+      env: {
+        ...baseEnv,
+        ATLASSIAN_DEFAULT_PROJECT: "ENG",
+      },
+      fetchImpl: async () => {
+        called = true;
+        return jsonResponse({});
+      },
+    });
+
+    assert.equal(called, false);
+    assert.deepEqual(JSON.parse(result.stdout), {
+      ok: true,
+      dryRun: true,
+      data: {
+        method: "POST",
+        url: "https://example.atlassian.net/rest/api/3/issue",
+        body: {
+          fields: {
+            project: { key: "ENG" },
+            issuetype: { name: "Story" },
+            summary: "Create the Atlassian skill",
+            description: markdownToAdf("# New story\n\n- one\n- two"),
+          },
+        },
+      },
+    });
+  } finally {
+    workspace.cleanup();
+  }
+});
+
+test("jira-update, jira-comment, and jira-transition dry-runs build the expected Jira requests", async () => {
+  const workspace = createTempWorkspace();
+
+  try {
+    workspace.write("issue.md", "Updated description");
+    workspace.write("comment.md", "Comment body");
+
+    const update = await runCli({
+      args: [
+        "jira-update",
+        "--issue",
+        "ENG-9",
+        "--summary",
+        "Updated summary",
+        "--description-file",
+        "issue.md",
+        "--dry-run",
+      ],
+      cwd: workspace.cwd,
+      env: baseEnv,
+    });
+
+    const comment = await runCli({
+      args: ["jira-comment", "--issue", "ENG-9", "--body-file", "comment.md", "--dry-run"],
+      cwd: workspace.cwd,
+      env: baseEnv,
+    });
+
+    const transition = await runCli({
+      args: ["jira-transition", "--issue", "ENG-9", "--transition", "31", "--dry-run"],
+      cwd: workspace.cwd,
+      env: baseEnv,
+    });
+
+    assert.deepEqual(JSON.parse(update.stdout), {
+      ok: true,
+      dryRun: true,
+      data: {
+        method: "PUT",
+        url: "https://example.atlassian.net/rest/api/3/issue/ENG-9",
+        body: {
+          fields: {
+            summary: "Updated summary",
+            description: markdownToAdf("Updated description"),
+          },
+        },
+      },
+    });
+
+    assert.deepEqual(JSON.parse(comment.stdout), {
+      ok: true,
+      dryRun: true,
+      data: {
+        method: "POST",
+        url: "https://example.atlassian.net/rest/api/3/issue/ENG-9/comment",
+        body: {
+          body: markdownToAdf("Comment body"),
+        },
+      },
+    });
+
+    assert.deepEqual(JSON.parse(transition.stdout), {
+      ok: true,
+      dryRun: true,
+      data: {
+        method: "POST",
+        url: "https://example.atlassian.net/rest/api/3/issue/ENG-9/transitions",
+        body: {
+          transition: {
+            id: "31",
+          },
+        },
+      },
+    });
+  } finally {
+    workspace.cleanup();
+  }
+});
+
+test("jira-transitions returns normalized transition options", async () => {
+  const fetchImpl: typeof fetch = async () =>
+    jsonResponse({
+      transitions: [
+        {
+          id: "21",
+          name: "Start Progress",
+          to: { name: "In Progress" },
+          hasScreen: false,
+        },
+      ],
+    });
+
+  const result = await runCli({
+    args: ["jira-transitions", "--issue", "ENG-9"],
+    env: baseEnv,
+    fetchImpl,
+  });
+
+  assert.deepEqual(JSON.parse(result.stdout), {
+    ok: true,
+    data: {
+      transitions: [
+        {
+          id: "21",
+          name: "Start Progress",
+          toStatus: "In Progress",
+          hasScreen: false,
+        },
+      ],
+    },
+  });
+});

skills/atlassian/shared/scripts/tests/raw.test.ts

@@ -0,0 +1,129 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+
+import { createTempWorkspace, jsonResponse, runCli } from "./helpers.js";
+
+const baseEnv = {
+  ATLASSIAN_BASE_URL: "https://example.atlassian.net",
+  ATLASSIAN_EMAIL: "dev@example.com",
+  ATLASSIAN_API_TOKEN: "secret-token",
+};
+
+test("raw rejects DELETE requests", async () => {
+  await assert.rejects(
+    runCli({
+      args: ["raw", "--product", "jira", "--method", "DELETE", "--path", "/rest/api/3/issue/ENG-1"],
+      env: baseEnv,
+    }),
+    /raw only allows GET, POST, and PUT/,
+  );
+});
+
+test("raw rejects unsupported Jira and Confluence prefixes", async () => {
+  await assert.rejects(
+    runCli({
+      args: ["raw", "--product", "jira", "--method", "GET", "--path", "/wiki/api/v2/pages"],
+      env: baseEnv,
+    }),
+    /raw path is not allowed for jira/,
+  );
+
+  await assert.rejects(
+    runCli({
+      args: ["raw", "--product", "confluence", "--method", "GET", "--path", "/rest/api/3/issue/ENG-1"],
+      env: baseEnv,
+    }),
+    /raw path is not allowed for confluence/,
+  );
+});
+
+test("raw GET executes against the validated Jira endpoint", async () => {
+  let call: { url: string; init: RequestInit | undefined } | undefined;
+
+  const result = await runCli({
+    args: ["raw", "--product", "jira", "--method", "GET", "--path", "/rest/api/3/issue/ENG-1"],
+    env: baseEnv,
+    fetchImpl: async (input, init) => {
+      call = { url: typeof input === "string" ? input : input.toString(), init };
+      return jsonResponse({ id: "10001", key: "ENG-1" });
+    },
+  });
+
+  assert.deepEqual(call, {
+    url: "https://example.atlassian.net/rest/api/3/issue/ENG-1",
+    init: {
+      method: "GET",
+      headers: [
+        ["Accept", "application/json"],
+        ["Authorization", `Basic ${Buffer.from("dev@example.com:secret-token").toString("base64")}`],
+      ],
+    },
+  });
+
+  assert.deepEqual(JSON.parse(result.stdout), {
+    ok: true,
+    data: {
+      id: "10001",
+      key: "ENG-1",
+    },
+  });
+});
+
+test("raw POST dry-run reads only workspace-scoped body files", async () => {
+  const workspace = createTempWorkspace();
+
+  try {
+    workspace.write("payload.json", "{\"title\":\"Runbook\"}");
+
+    const result = await runCli({
+      args: [
+        "raw",
+        "--product",
+        "confluence",
+        "--method",
+        "POST",
+        "--path",
+        "/wiki/api/v2/pages",
+        "--body-file",
+        "payload.json",
+        "--dry-run",
+      ],
+      cwd: workspace.cwd,
+      env: baseEnv,
+    });
+
+    assert.deepEqual(JSON.parse(result.stdout), {
+      ok: true,
+      dryRun: true,
+      data: {
+        method: "POST",
+        url: "https://example.atlassian.net/wiki/api/v2/pages",
+        body: {
+          title: "Runbook",
+        },
+      },
+    });
+
+    await assert.rejects(
+      runCli({
+        args: [
+          "raw",
+          "--product",
+          "confluence",
+          "--method",
+          "POST",
+          "--path",
+          "/wiki/api/v2/pages",
+          "--body-file",
+          "../outside.json",
+          "--dry-run",
+        ],
+        cwd: workspace.cwd,
+        env: baseEnv,
+      }),
+      /--body-file must stay within the active workspace/,
+    );
+  } finally {
+    workspace.cleanup();
+  }
+});

skills/atlassian/shared/scripts/tsconfig.json

@@ -0,0 +1,15 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "esModuleInterop": true,
+    "forceConsistentCasingInFileNames": true,
+    "strict": true,
+    "skipLibCheck": true,
+    "resolveJsonModule": true,
+    "types": ["node"],
+    "outDir": "dist"
+  },
+  "include": ["src/**/*.ts", "scripts/**/*.ts", "tests/**/*.ts"]
+}

skills/create-plan/claude-code/SKILL.md

@@ -1,15 +1,15 @@
 ---
 name: create-plan
-description: Use when starting a new feature, project, or complex task that needs structured planning with milestones, bite-sized stories, and resumable execution context. Trigger for "create a plan", "make a plan", "plan this", "start planning", and similar requests.
+description: Use when starting a new feature, project, or complex task that needs structured planning with milestones, bite-sized stories, and resumable execution context. ALWAYS invoke when user says "create a plan", "make a plan", "plan this", "start planning", or similar planning requests.
 ---
 
 # Create Plan (Claude Code)
 
-Create and maintain a local plan folder under `docs/plans/` (or `docs/plan/` if that repository convention is already in use).
+Create and maintain a local plan folder under `ai_plan/` at project root.
 
 ## Prerequisite Check (MANDATORY)
 
-This skill depends on Superpowers planning skills. Before proceeding, verify required dependencies exist.
+This Claude Code variant depends on Superpowers planning skills and explicit sub-skill invocation.
 
 Required:
 - Superpowers repo: `https://github.com/obra/superpowers`
@@ -23,37 +23,480 @@ If any dependency is missing, stop immediately and return:
 ## Process
 
 ### Phase 1: Analyze
-- Explore the codebase and existing patterns.
+- Explore the codebase with exploration agents.
+- Understand existing patterns and context.
 
 ### Phase 2: Gather Requirements
-- Ask questions one at a time until user says ready.
-- Confirm scope, constraints, success criteria, dependencies.
+- Ask questions ONE AT A TIME until user says ready.
+- Cover scope, constraints, success criteria, dependencies.
+- Summarize before proceeding.
 
-### Phase 3: Design
-- Invoke `superpowers:brainstorming`.
-- Propose 2-3 approaches and recommend one.
+### Phase 3: Configure Reviewer
 
-### Phase 4: Plan
-- Invoke `superpowers:writing-plans`.
-- Break into milestones and bite-sized stories.
+If the user has already specified a reviewer CLI and model (e.g., "create a plan, review with codex o4-mini"), use those values. Otherwise, ask:
 
-### Phase 5: Generate Plan Files (MANDATORY)
+1. **Which CLI should review the plan?**
+   - `codex` — OpenAI Codex CLI (`codex exec`)
+   - `claude` — Claude Code CLI (`claude -p`)
+   - `cursor` — Cursor Agent CLI (`cursor-agent -p`)
+   - `skip` — No external review, proceed directly to file generation
 
-Create `docs/plans/YYYY-MM-DD-<short-title>/` with all files below:
-1. `original-plan.md` - copy of original planner-generated plan.
-2. `final-transcript.md` - copy of final planning transcript used to reach approved plan.
-3. `milestone-plan.md` - full implementation spec (from template).
-4. `story-tracker.md` - story/milestone status tracker (from template).
-5. `continuation-runbook.md` - execution instructions and context (from template).
+2. **Which model?** (only if a CLI was chosen)
+   - For `codex`: default `o4-mini`, alternatives: `gpt-5.3-codex`, `o3`
+   - For `claude`: default `sonnet`, alternatives: `opus`, `haiku`
+   - For `cursor`: **run `cursor-agent models` first** to see your account's available models (availability varies by subscription)
+   - Accept any model string the user provides
 
-Use templates from this skill's `templates/` folder.
+3. **Max review rounds for the plan?** (default: 10)
+   - If the user does not provide a value, set `MAX_ROUNDS=10`.
 
-### Phase 6: Handoff
+Store the chosen `REVIEWER_CLI`, `REVIEWER_MODEL`, and `MAX_ROUNDS` for Phase 6 (Iterative Plan Review).
 
-Always instruct the executing agent:
-> Read `docs/plans/YYYY-MM-DD-<short-title>/continuation-runbook.md` first, then execute from that folder.
+### Phase 4: Design (REQUIRED SUB-SKILL)
+- Invoke `superpowers:brainstorming` explicitly.
+- Present 2-3 approaches and recommend one.
+- Validate design in sections.
 
-Do not rely on planner-private files during implementation.
+### Phase 5: Plan (REQUIRED SUB-SKILL)
+- Invoke `superpowers:writing-plans` explicitly.
+- Break into milestones and bite-sized stories (2-5 min each).
+- Story IDs: `S-{milestone}{sequence}`.
+
+### Phase 6: Iterative Plan Review
+
+Send the plan to the configured reviewer CLI for feedback. Revise and re-submit until approved (default max 10 rounds).
+
+**Skip this phase entirely if reviewer was set to `skip`.**
+
+#### Step 1: Generate Session ID
+
+```bash
+REVIEW_ID=$(uuidgen | tr '[:upper:]' '[:lower:]' | head -c 8)
+```
+
+Use for temp artifacts:
+- `/tmp/plan-${REVIEW_ID}.md`
+- `/tmp/plan-review-${REVIEW_ID}.md`
+- `/tmp/plan-review-${REVIEW_ID}.json` (Cursor only)
+- `/tmp/plan-review-${REVIEW_ID}.stderr`
+- `/tmp/plan-review-${REVIEW_ID}.status`
+- `/tmp/plan-review-${REVIEW_ID}.runner.out`
+- `/tmp/plan-review-${REVIEW_ID}.sh`
+
+Resolve the shared reviewer helper from the installed Claude Code skills directory:
+
+```bash
+REVIEWER_RUNTIME=~/.claude/skills/reviewer-runtime/run-review.sh
+```
+
+Set helper success-artifact args before writing the command script:
+
+```bash
+HELPER_SUCCESS_FILE_ARGS=()
+case "$REVIEWER_CLI" in
+  codex)
+    HELPER_SUCCESS_FILE_ARGS+=(--success-file /tmp/plan-review-${REVIEW_ID}.md)
+    ;;
+  cursor)
+    HELPER_SUCCESS_FILE_ARGS+=(--success-file /tmp/plan-review-${REVIEW_ID}.json)
+    ;;
+esac
+```
+
+#### Step 2: Write Plan to Temp File
+
+Write the complete plan (milestones, stories, design decisions, specs) to `/tmp/plan-${REVIEW_ID}.md`.
+
+#### Review Contract (Applies to Every Round)
+
+The reviewer response must use this structure:
+
+```text
+## Summary
+...
+
+## Findings
+### P0
+- ...
+### P1
+- ...
+### P2
+- ...
+### P3
+- ...
+
+## Verdict
+VERDICT: APPROVED
+```
+
+Rules:
+- Order findings from `P0` to `P3`.
+- `P0` = total blocker, `P1` = major risk, `P2` = must-fix before approval, `P3` = cosmetic / nice to have.
+- Use `- None.` when a severity has no findings.
+- `VERDICT: APPROVED` is allowed only when no `P0`, `P1`, or `P2` findings remain. `P3` findings are non-blocking.
+- The calling agent should still try to fix `P3` findings when they are cheap and safe.
+
+#### Liveness Contract (Applies While Review Is Running)
+
+- The shared reviewer runtime emits `state=in-progress note="In progress N"` heartbeats every 60 seconds while the reviewer child is alive.
+- The calling agent must keep waiting as long as a fresh `In progress N` heartbeat keeps arriving roughly once per minute.
+- Do not abort just because the review is slow, a soft timeout fired, or a `stall-warning` line appears, as long as the `In progress N` heartbeat continues.
+- Treat missing heartbeats, `state=failed`, `state=completed-empty-output`, and `state=needs-operator-decision` as escalation signals.
+
+#### Step 3: Submit to Reviewer (Round 1)
+
+Write the reviewer invocation to `/tmp/plan-review-${REVIEW_ID}.sh` as a bash script:
+
+```bash
+#!/usr/bin/env bash
+set -euo pipefail
+```
+
+**If `REVIEWER_CLI` is `codex`:**
+
+```bash
+codex exec \
+  -m ${REVIEWER_MODEL} \
+  -s read-only \
+  -o /tmp/plan-review-${REVIEW_ID}.md \
+  "Review the implementation plan in /tmp/plan-${REVIEW_ID}.md. Focus on:
+1. Correctness — Will this plan achieve the stated goals?
+2. Risks — What could go wrong? Edge cases? Data loss?
+3. Missing steps — Is anything forgotten?
+4. Alternatives — Is there a simpler or better approach?
+5. Security — Any security concerns?
+
+Return exactly these sections in order:
+## Summary
+## Findings
+### P0
+### P1
+### P2
+### P3
+## Verdict
+
+Rules:
+- Order findings from highest severity to lowest.
+- Use `- None.` when a severity has no findings.
+- `P0` = total blocker, `P1` = major risk, `P2` = must-fix before approval, `P3` = cosmetic / nice to have.
+- End with exactly one verdict line: `VERDICT: APPROVED` or `VERDICT: REVISE`
+- `VERDICT: APPROVED` is allowed only when there are no `P0`, `P1`, or `P2` findings. `P3` findings are non-blocking."
+```
+
+Do not try to capture the Codex session ID yet. When using the helper, extract it from `/tmp/plan-review-${REVIEW_ID}.runner.out` after the command completes (look for `session id: <uuid>`), then store it as `CODEX_SESSION_ID` for resume in subsequent rounds.
+
+**If `REVIEWER_CLI` is `claude`:**
+
+```bash
+claude -p \
+  "Review the implementation plan below. Focus on:
+
+$(cat /tmp/plan-${REVIEW_ID}.md)
+
+1. Correctness — Will this plan achieve the stated goals?
+2. Risks — What could go wrong? Edge cases? Data loss?
+3. Missing steps — Is anything forgotten?
+4. Alternatives — Is there a simpler or better approach?
+5. Security — Any security concerns?
+
+Return exactly these sections in order:
+## Summary
+## Findings
+### P0
+### P1
+### P2
+### P3
+## Verdict
+
+Rules:
+- Order findings from highest severity to lowest.
+- Use `- None.` when a severity has no findings.
+- `P0` = total blocker, `P1` = major risk, `P2` = must-fix before approval, `P3` = cosmetic / nice to have.
+- End with exactly one verdict line: `VERDICT: APPROVED` or `VERDICT: REVISE`
+- `VERDICT: APPROVED` is allowed only when there are no `P0`, `P1`, or `P2` findings. `P3` findings are non-blocking." \
+  --model ${REVIEWER_MODEL} \
+  --strict-mcp-config \
+  --setting-sources user
+```
+
+**If `REVIEWER_CLI` is `cursor`:**
+
+```bash
+cursor-agent -p \
+  --mode=ask \
+  --model ${REVIEWER_MODEL} \
+  --trust \
+  --output-format json \
+  "Read the file /tmp/plan-${REVIEW_ID}.md and review the implementation plan. Focus on:
+1. Correctness — Will this plan achieve the stated goals?
+2. Risks — What could go wrong? Edge cases? Data loss?
+3. Missing steps — Is anything forgotten?
+4. Alternatives — Is there a simpler or better approach?
+5. Security — Any security concerns?
+
+Return exactly these sections in order:
+## Summary
+## Findings
+### P0
+### P1
+### P2
+### P3
+## Verdict
+
+Rules:
+- Order findings from highest severity to lowest.
+- Use `- None.` when a severity has no findings.
+- `P0` = total blocker, `P1` = major risk, `P2` = must-fix before approval, `P3` = cosmetic / nice to have.
+- End with exactly one verdict line: `VERDICT: APPROVED` or `VERDICT: REVISE`
+- `VERDICT: APPROVED` is allowed only when there are no `P0`, `P1`, or `P2` findings. `P3` findings are non-blocking." \
+  > /tmp/plan-review-${REVIEW_ID}.json
+```
+
+For `cursor`, the command script writes raw JSON to `/tmp/plan-review-${REVIEW_ID}.json`. Do not run `jq` extraction until after the helper or fallback execution completes. If `jq` is not installed, inform the user: `brew install jq` (macOS) or equivalent.
+
+Run the command script through the shared helper when available:
+
+```bash
+if [ -x "$REVIEWER_RUNTIME" ]; then
+  "$REVIEWER_RUNTIME" \
+    --command-file /tmp/plan-review-${REVIEW_ID}.sh \
+    --stdout-file /tmp/plan-review-${REVIEW_ID}.runner.out \
+    --stderr-file /tmp/plan-review-${REVIEW_ID}.stderr \
+    --status-file /tmp/plan-review-${REVIEW_ID}.status \
+    "${HELPER_SUCCESS_FILE_ARGS[@]}"
+else
+  echo "Warning: reviewer runtime helper not found at $REVIEWER_RUNTIME; falling back to direct synchronous review." >&2
+  bash /tmp/plan-review-${REVIEW_ID}.sh >/tmp/plan-review-${REVIEW_ID}.runner.out 2>/tmp/plan-review-${REVIEW_ID}.stderr
+fi
+```
+
+Run the helper in the foreground and watch its live stdout for `state=in-progress` heartbeats. If your agent environment buffers command output until exit, start the helper in the background and poll `/tmp/plan-review-${REVIEW_ID}.status` separately instead of treating heartbeats as post-hoc-only data.
+
+After the command completes:
+- If `REVIEWER_CLI=cursor`, extract the final review text:
+
+```bash
+CURSOR_SESSION_ID=$(jq -r '.session_id' /tmp/plan-review-${REVIEW_ID}.json)
+jq -r '.result' /tmp/plan-review-${REVIEW_ID}.json > /tmp/plan-review-${REVIEW_ID}.md
+```
+
+- If `REVIEWER_CLI=codex`, extract `CODEX_SESSION_ID` from `/tmp/plan-review-${REVIEW_ID}.runner.out` after the helper or fallback run. If the review text is only in `.runner.out`, move or copy the actual review body into `/tmp/plan-review-${REVIEW_ID}.md` before verdict parsing.
+- If `REVIEWER_CLI=claude`, promote stdout captured by the helper or fallback runner into the markdown review file:
+
+```bash
+cp /tmp/plan-review-${REVIEW_ID}.runner.out /tmp/plan-review-${REVIEW_ID}.md
+```
+
+Fallback is allowed only when the helper is missing or not executable.
+
+#### Step 4: Read Review & Check Verdict
+
+1. Read `/tmp/plan-review-${REVIEW_ID}.md`
+2. If the review failed, produced empty output, or reached helper timeout, also read:
+   - `/tmp/plan-review-${REVIEW_ID}.stderr`
+   - `/tmp/plan-review-${REVIEW_ID}.status`
+   - `/tmp/plan-review-${REVIEW_ID}.runner.out`
+3. Present review to the user:
+
+```
+## Plan Review — Round N (reviewer: ${REVIEWER_CLI} / ${REVIEWER_MODEL})
+
+[Reviewer feedback]
+```
+
+4. While the reviewer is still running, keep waiting as long as fresh `state=in-progress note="In progress N"` heartbeats continue to appear roughly once per minute.
+5. Check verdict:
+   - **VERDICT: APPROVED** with no `P0`, `P1`, or `P2` findings → proceed to Phase 7 (Initialize workspace)
+   - **VERDICT: APPROVED** with only `P3` findings → optionally fix the `P3` items if they are cheap and safe, then proceed
+   - **VERDICT: REVISE** or any `P0`, `P1`, or `P2` finding → go to Step 5
+   - No clear verdict but `P0`, `P1`, and `P2` are all `- None.` → treat as approved
+   - Helper state `completed-empty-output` → treat as failed review attempt, surface stderr/status, fix invocation or prompt handling, then retry
+   - Helper state `needs-operator-decision` → surface status log and decide whether to extend the timeout, abort, or retry with different helper parameters
+   - Max rounds (`MAX_ROUNDS`) reached → present the outcome to the user for a manual decision (proceed or stop)
+
+#### Step 5: Revise the Plan
+
+Address the reviewer findings in priority order (`P0` → `P1` → `P2`, then `P3` when practical). Update the plan in conversation context and rewrite `/tmp/plan-${REVIEW_ID}.md`.
+
+Summarize revisions for the user:
+
+```
+### Revisions (Round N)
+- [Change and reason, one bullet per issue addressed]
+```
+
+If a revision contradicts the user's explicit requirements, skip it and note it for the user.
+
+#### Step 6: Re-submit to Reviewer (Rounds 2-N)
+
+Rewrite `/tmp/plan-review-${REVIEW_ID}.sh` for the next round. The script should contain the reviewer invocation only; do not run it directly.
+
+**If `REVIEWER_CLI` is `codex`:**
+
+Resume the existing session:
+
+```bash
+codex exec resume ${CODEX_SESSION_ID} \
+  -o /tmp/plan-review-${REVIEW_ID}.md \
+  "I've revised the plan based on your feedback. Updated plan is in /tmp/plan-${REVIEW_ID}.md.
+
+Changes made:
+[List specific changes]
+
+Re-review using the same `## Summary`, `## Findings`, and `## Verdict` structure as before.
+Keep findings ordered `P0` to `P3`, use `- None.` when a severity has no findings, and only use `VERDICT: APPROVED` when no `P0`, `P1`, or `P2` findings remain. `P3` findings are non-blocking."
+```
+
+If resume fails (session expired), fall back to fresh `codex exec` with context about prior rounds.
+
+**If `REVIEWER_CLI` is `claude`:**
+
+Fresh call with accumulated context (Claude CLI has no session resume):
+
+```bash
+claude -p \
+  "You previously reviewed an implementation plan and requested revisions.
+
+Previous feedback summary: [key points from last review]
+
+I've revised the plan. Updated version is below.
+
+$(cat /tmp/plan-${REVIEW_ID}.md)
+
+Changes made:
+[List specific changes]
+
+Re-review the full plan using the same `## Summary`, `## Findings`, and `## Verdict` structure as before.
+Keep findings ordered `P0` to `P3`, use `- None.` when a severity has no findings, and only use `VERDICT: APPROVED` when no `P0`, `P1`, or `P2` findings remain. `P3` findings are non-blocking." \
+  --model ${REVIEWER_MODEL} \
+  --strict-mcp-config \
+  --setting-sources user
+```
+
+**If `REVIEWER_CLI` is `cursor`:**
+
+Resume the existing session:
+
+```bash
+cursor-agent --resume ${CURSOR_SESSION_ID} -p \
+  --mode=ask \
+  --model ${REVIEWER_MODEL} \
+  --trust \
+  --output-format json \
+  "I've revised the plan based on your feedback. Updated plan is in /tmp/plan-${REVIEW_ID}.md.
+
+Changes made:
+[List specific changes]
+
+Re-review using the same `## Summary`, `## Findings`, and `## Verdict` structure as before.
+Keep findings ordered `P0` to `P3`, use `- None.` when a severity has no findings, and only use `VERDICT: APPROVED` when no `P0`, `P1`, or `P2` findings remain. `P3` findings are non-blocking." \
+  > /tmp/plan-review-${REVIEW_ID}.json
+
+jq -r '.result' /tmp/plan-review-${REVIEW_ID}.json > /tmp/plan-review-${REVIEW_ID}.md
+```
+
+If resume fails, fall back to fresh `cursor-agent -p` with context about prior rounds.
+
+After updating `/tmp/plan-review-${REVIEW_ID}.sh`, run the same helper/fallback flow from Round 1.
+
+Return to Step 4.
+
+#### Step 7: Present Final Result
+
+```
+## Plan Review — Final (reviewer: ${REVIEWER_CLI} / ${REVIEWER_MODEL})
+
+**Status:** Approved after N round(s)
+[or]
+**Status:** Max rounds (`MAX_ROUNDS`) reached — not fully approved
+
+[Final feedback / remaining concerns]
+```
+
+#### Step 8: Cleanup
+
+```bash
+rm -f /tmp/plan-${REVIEW_ID}.md \
+  /tmp/plan-review-${REVIEW_ID}.md \
+  /tmp/plan-review-${REVIEW_ID}.json \
+  /tmp/plan-review-${REVIEW_ID}.stderr \
+  /tmp/plan-review-${REVIEW_ID}.status \
+  /tmp/plan-review-${REVIEW_ID}.runner.out \
+  /tmp/plan-review-${REVIEW_ID}.sh
+```
+
+If the round failed, produced empty output, or reached operator-decision timeout, keep `.stderr`, `.status`, and `.runner.out` until the issue is diagnosed instead of deleting them immediately.
+
+### Phase 7: Initialize Local Plan Workspace (MANDATORY)
+
+At project root:
+1. Ensure `ai_plan/` exists. Create it if missing.
+2. Ensure `.gitignore` contains `/ai_plan/`.
+3. If `.gitignore` was changed, commit that change immediately (local commit only).
+
+Recommended commit message:
+- `chore(gitignore): ignore ai_plan local planning artifacts`
+
+### Phase 8: Generate Plan Files (MANDATORY - DO NOT SKIP)
+
+**PLAN MODE CHECK:** If currently in plan mode:
+1. Inform user that plan files cannot be written while in plan mode.
+2. Instruct user to exit plan mode (approve plan or use ExitPlanMode).
+3. Proceed with file generation only after exiting plan mode.
+
+Create `ai_plan/YYYY-MM-DD-<short-title>/` with ALL files:
+1. `original-plan.md` - Copy the plan file from `~/.claude/plans/` as-is.
+2. `final-transcript.md` - Copy of final planning transcript for reference.
+3. `milestone-plan.md` - Full specification (template-based).
+4. `story-tracker.md` - Status tracking (template-based, all stories start as `pending`).
+5. `continuation-runbook.md` - Resume context and execution protocol (template-based).
+
+Use templates from this skill's `templates/` folder (or `~/.claude/skills/create-plan/templates/` when installed directly in Claude Code).
+
+### Phase 9: Handoff Instructions
+
+When handing off to execution, instruct:
+> Read `ai_plan/YYYY-MM-DD-<short-title>/continuation-runbook.md` first, then execute from `ai_plan` files only.
+
+Private plan files under `~/.claude/plans/` are planning artifacts and must not be used as execution source of truth.
+
+### Phase 10: Telegram Notification (MANDATORY)
+
+Resolve the Telegram notifier helper from the installed Claude Code skills directory:
+
+```bash
+TELEGRAM_NOTIFY_RUNTIME=~/.claude/skills/reviewer-runtime/notify-telegram.sh
+```
+
+On every terminal outcome for the create-plan run (approved, max rounds reached, skipped reviewer, or failure), send a Telegram summary if the helper exists and both `TELEGRAM_BOT_TOKEN` and `TELEGRAM_CHAT_ID` are configured:
+
+```bash
+if [ -x "$TELEGRAM_NOTIFY_RUNTIME" ] && [ -n "${TELEGRAM_BOT_TOKEN:-}" ] && [ -n "${TELEGRAM_CHAT_ID:-}" ]; then
+  "$TELEGRAM_NOTIFY_RUNTIME" --message "create-plan completed for <plan-folder-name>: <status summary>"
+fi
+```
+
+Rules:
+- Telegram is the only supported notification path. Do not use desktop notifications, `say`, email, or any other notifier.
+- Notification failures are non-blocking, but they must be surfaced to the user.
+- Before stopping for any user interaction, approval, or manual decision, send a Telegram summary first if configured.
+- If Telegram is not configured, state that no Telegram notification was sent.
+
+## Tracker Discipline (MANDATORY)
+
+**ALWAYS update `story-tracker.md` before/after each story. NEVER proceed with stale tracker state.**
+
+Before starting any story:
+1. Open `story-tracker.md`
+2. Mark story `in-dev`
+3. Add notes if relevant
+4. Then begin implementation
+
+After completing any story:
+1. Mark story `completed`
+2. Add commit hash in Notes
+3. Review pending stories
+4. Update Last Updated and Stories Complete counts
 
 ## Execution Rules to Include in Plan (MANDATORY)
 
@@ -68,14 +511,24 @@ Do not rely on planner-private files during implementation.
 
 ## Gitignore Note
 
-If `docs/plans` or `docs/plan` is gitignored, this is expected. Do not treat inability to commit plan-file updates as a problem. These files are local to the user.
+`ai_plan/` is intentionally local and must stay gitignored. Do not treat inability to commit plan-file updates in `ai_plan/` as a problem.
 
 ## Verification Checklist
 
-- [ ] Plan directory created under `docs/plans/` (or repo-standard `docs/plan/`)
-- [ ] `original-plan.md` present
+- [ ] `ai_plan/` exists at project root
+- [ ] `.gitignore` includes `/ai_plan/`
+- [ ] `.gitignore` ignore-rule commit was created if needed
+- [ ] Plan directory created under `ai_plan/YYYY-MM-DD-<short-title>/`
+- [ ] Reviewer configured or explicitly skipped
+- [ ] Max review rounds confirmed (default: 10)
+- [ ] Plan review completed (approved or max rounds) — or skipped
+- [ ] `original-plan.md` copied from `~/.claude/plans/` plan file
 - [ ] `final-transcript.md` present
 - [ ] `milestone-plan.md` present
-- [ ] `story-tracker.md` present
+- [ ] `story-tracker.md` created with all stories as `pending`
 - [ ] `continuation-runbook.md` present
 - [ ] Handoff explicitly says to read runbook first and execute from plan folder
+- [ ] Telegram notification attempted if configured
+
+## Exit Triggers for Question Phase
+User says: "ready", "done", "let's plan", "proceed", "enough questions"

skills/create-plan/claude-code/templates/continuation-runbook.md

@@ -28,7 +28,7 @@ Do NOT reference planner-private files during implementation.
 
 ## Mandatory Execution Workflow
 
-Work from this folder (`docs/plans/YYYY-MM-DD-<short-title>/` or repo-specific `docs/plan/...`) and always follow this order:
+Work from this folder (`ai_plan/YYYY-MM-DD-<short-title>/`) and always follow this order:
 
 1. Read `continuation-runbook.md` first.
 2. Execute stories milestone by milestone.
@@ -51,7 +51,7 @@ Work from this folder (`docs/plans/YYYY-MM-DD-<short-title>/` or repo-specific `
 
 ## Git Note
 
-If `docs/plan` or `docs/plans` is gitignored, that is expected and acceptable. Do not treat inability to commit plan-file updates as an error. These files are local planning artifacts.
+`ai_plan/` is intentionally local and must stay gitignored. Do not treat inability to commit plan-file updates inside `ai_plan/` as an error.
 
 ---
 

skills/create-plan/claude-code/templates/milestone-plan.md

@@ -93,7 +93,7 @@
 
 ## Related Plan Files
 
-This file is part of the plan folder under `docs/plans/` (or `docs/plan/` if that repo convention is used):
+This file is part of the plan folder under `ai_plan/`:
 - `original-plan.md` - Original approved plan (reference for original intent)
 - `final-transcript.md` - Final planning transcript (reference for rationale/context)
 - `milestone-plan.md` - This file (full specification)

skills/create-plan/codex/SKILL.md

@@ -1,48 +1,468 @@
 ---
 name: create-plan
-description: Use when starting a new feature, project, or complex task that needs structured planning with milestones, bite-sized stories, and resumable execution context. Trigger for "create a plan", "make a plan", "plan this", "start planning", and similar requests.
+description: Use when a user asks to create or maintain a structured implementation plan in Codex, including milestones, bite-sized stories, and resumable local planning artifacts under ai_plan.
 ---
 
-# Create Plan (Codex)
+# Create Plan (Codex Native Superpowers)
 
-Create and maintain a local plan folder under `docs/plans/` (or `docs/plan/` if that repository convention is already in use).
+Create and maintain a local plan workspace under `ai_plan/` at project root.
+
+## Overview
+
+This skill wraps the current Superpowers flow for Codex:
+1. Design first with `superpowers:brainstorming`
+2. Then build an implementation plan with `superpowers:writing-plans`
+3. Review the plan iteratively with a second model/provider
+4. Persist a local execution package in `ai_plan/YYYY-MM-DD-<short-title>/`
+
+**Core principle:** Codex uses native skill discovery from `~/.agents/skills/`. Do not use deprecated `superpowers-codex bootstrap` or `use-skill` CLI commands.
 
 ## Prerequisite Check (MANDATORY)
 
-This skill depends on Superpowers planning skills. Before proceeding, verify required dependencies exist.
-
 Required:
-- Superpowers repo: `https://github.com/obra/superpowers`
-- `brainstorming` skill
-- `writing-plans` skill
+- Superpowers skills symlink: `~/.agents/skills/superpowers -> ~/.codex/superpowers/skills`
+- `superpowers:brainstorming`
+- `superpowers:writing-plans`
 
-If any dependency is missing, stop immediately and return:
+Verify before proceeding:
 
-"Missing dependency: Superpowers planning skills are required (`brainstorming`, `writing-plans`). Install from https://github.com/obra/superpowers, then retry."
+```bash
+test -L ~/.agents/skills/superpowers
+test -f ~/.agents/skills/superpowers/brainstorming/SKILL.md
+test -f ~/.agents/skills/superpowers/writing-plans/SKILL.md
+```
+
+If any dependency is missing, stop and return:
+
+`Missing dependency: native Superpowers skills are required (superpowers:brainstorming, superpowers:writing-plans). Ensure ~/.agents/skills/superpowers is configured, then retry.`
+
+## Required Skill Invocation Rules
+
+- Invoke relevant skills through native discovery (no CLI wrapper).
+- Announce skill usage explicitly:
+  - `I've read the [Skill Name] skill and I'm using it to [purpose].`
+- For skills with checklists, track checklist items with `update_plan` todos.
+- Tool mapping for Codex:
+  - `TodoWrite` -> `update_plan`
+  - `Task` subagents -> unavailable in Codex; do the work directly and state the limitation
+  - `Skill` -> use native skill discovery from `~/.agents/skills/`
 
 ## Process
 
-### Phase 1: Bootstrap
-- Invoke Codex superpowers bootstrap and planning skills when available.
-
-### Phase 2: Analyze
+### Phase 1: Analyze
 - Explore the codebase and existing patterns.
 
-### Phase 3: Gather Requirements
+### Phase 2: Gather Requirements
 - Ask questions one at a time until user says ready.
 - Confirm scope, constraints, success criteria, dependencies.
 
-### Phase 4: Design
-- Use brainstorming workflow.
-- Propose 2-3 approaches and recommend one.
+### Phase 3: Configure Reviewer
 
-### Phase 5: Plan
-- Use writing-plans workflow.
-- Break into milestones and bite-sized stories.
+If the user has already specified a reviewer CLI and model (e.g., "create a plan, review with claude sonnet"), use those values. Otherwise, ask:
 
-### Phase 6: Generate Plan Files (MANDATORY)
+1. **Which CLI should review the plan?**
+   - `codex` — OpenAI Codex CLI (`codex exec`)
+   - `claude` — Claude Code CLI (`claude -p`)
+   - `cursor` — Cursor Agent CLI (`cursor-agent -p`)
+   - `skip` — No external review, proceed directly to file generation
 
-Create `docs/plans/YYYY-MM-DD-<short-title>/` with all files below:
+2. **Which model?** (only if a CLI was chosen)
+   - For `codex`: default `o4-mini`, alternatives: `gpt-5.3-codex`, `o3`
+   - For `claude`: default `sonnet`, alternatives: `opus`, `haiku`
+   - For `cursor`: **run `cursor-agent models` first** to see your account's available models (availability varies by subscription)
+   - Accept any model string the user provides
+
+3. **Max review rounds for the plan?** (default: 10)
+   - If the user does not provide a value, set `MAX_ROUNDS=10`.
+
+Store the chosen `REVIEWER_CLI`, `REVIEWER_MODEL`, and `MAX_ROUNDS` for Phase 6 (Iterative Plan Review).
+
+### Phase 4: Design (REQUIRED SUB-SKILL)
+
+Invoke `superpowers:brainstorming`, then propose 2-3 approaches and recommend one.
+
+### Phase 5: Plan (REQUIRED SUB-SKILL)
+
+Invoke `superpowers:writing-plans`, then break work into milestones and bite-sized stories.
+
+### Phase 6: Iterative Plan Review
+
+Send the plan to the configured reviewer CLI for feedback. Revise and re-submit until approved (default max 10 rounds).
+
+**Skip this phase entirely if reviewer was set to `skip`.**
+
+#### Step 1: Generate Session ID
+
+```bash
+REVIEW_ID=$(uuidgen | tr '[:upper:]' '[:lower:]' | head -c 8)
+```
+
+Use for temp artifacts:
+- `/tmp/plan-${REVIEW_ID}.md` - plan payload
+- `/tmp/plan-review-${REVIEW_ID}.md` - normalized review text presented to the user
+- `/tmp/plan-review-${REVIEW_ID}.json` - raw Cursor JSON (only for `cursor`)
+- `/tmp/plan-review-${REVIEW_ID}.stderr` - reviewer stderr
+- `/tmp/plan-review-${REVIEW_ID}.status` - helper heartbeat/status log
+- `/tmp/plan-review-${REVIEW_ID}.runner.out` - helper-managed stdout from the reviewer command process
+- `/tmp/plan-review-${REVIEW_ID}.sh` - reviewer command script
+
+Resolve the shared reviewer helper from the installed Codex skills directory:
+
+```bash
+REVIEWER_RUNTIME=~/.codex/skills/reviewer-runtime/run-review.sh
+```
+
+Set helper success-artifact args before writing the command script:
+
+```bash
+HELPER_SUCCESS_FILE_ARGS=()
+case "$REVIEWER_CLI" in
+  codex)
+    HELPER_SUCCESS_FILE_ARGS+=(--success-file /tmp/plan-review-${REVIEW_ID}.md)
+    ;;
+  cursor)
+    HELPER_SUCCESS_FILE_ARGS+=(--success-file /tmp/plan-review-${REVIEW_ID}.json)
+    ;;
+esac
+```
+
+#### Step 2: Write Plan to Temp File
+
+Write the complete plan (milestones, stories, design decisions, specs) to `/tmp/plan-${REVIEW_ID}.md`.
+
+#### Review Contract (Applies to Every Round)
+
+The reviewer response must use this structure:
+
+```text
+## Summary
+...
+
+## Findings
+### P0
+- ...
+### P1
+- ...
+### P2
+- ...
+### P3
+- ...
+
+## Verdict
+VERDICT: APPROVED
+```
+
+Rules:
+- Order findings from `P0` to `P3`.
+- `P0` = total blocker, `P1` = major risk, `P2` = must-fix before approval, `P3` = cosmetic / nice to have.
+- Use `- None.` when a severity has no findings.
+- `VERDICT: APPROVED` is allowed only when no `P0`, `P1`, or `P2` findings remain. `P3` findings are non-blocking.
+- The calling agent should still try to fix `P3` findings when they are cheap and safe.
+
+#### Liveness Contract (Applies While Review Is Running)
+
+- The shared reviewer runtime emits `state=in-progress note="In progress N"` heartbeats every 60 seconds while the reviewer child is alive.
+- The calling agent must keep waiting as long as a fresh `In progress N` heartbeat keeps arriving roughly once per minute.
+- Do not abort just because the review is slow, a soft timeout fired, or a `stall-warning` line appears, as long as the `In progress N` heartbeat continues.
+- Treat missing heartbeats, `state=failed`, `state=completed-empty-output`, and `state=needs-operator-decision` as escalation signals.
+
+#### Step 3: Submit to Reviewer (Round 1)
+
+Write the reviewer invocation to `/tmp/plan-review-${REVIEW_ID}.sh` as a bash script:
+
+```bash
+#!/usr/bin/env bash
+set -euo pipefail
+```
+
+**If `REVIEWER_CLI` is `codex`:**
+
+```bash
+codex exec \
+  -m ${REVIEWER_MODEL} \
+  -s read-only \
+  -o /tmp/plan-review-${REVIEW_ID}.md \
+  "Review the implementation plan in /tmp/plan-${REVIEW_ID}.md. Focus on:
+1. Correctness — Will this plan achieve the stated goals?
+2. Risks — What could go wrong? Edge cases? Data loss?
+3. Missing steps — Is anything forgotten?
+4. Alternatives — Is there a simpler or better approach?
+5. Security — Any security concerns?
+
+Return exactly these sections in order:
+## Summary
+## Findings
+### P0
+### P1
+### P2
+### P3
+## Verdict
+
+Rules:
+- Order findings from highest severity to lowest.
+- Use `- None.` when a severity has no findings.
+- `P0` = total blocker, `P1` = major risk, `P2` = must-fix before approval, `P3` = cosmetic / nice to have.
+- End with exactly one verdict line: `VERDICT: APPROVED` or `VERDICT: REVISE`
+- `VERDICT: APPROVED` is allowed only when there are no `P0`, `P1`, or `P2` findings. `P3` findings are non-blocking."
+```
+
+Do not try to capture the Codex session ID yet. When using the helper, extract it from `/tmp/plan-review-${REVIEW_ID}.runner.out` after the command completes (look for `session id: <uuid>`), then store it as `CODEX_SESSION_ID` for resume in subsequent rounds.
+
+**If `REVIEWER_CLI` is `claude`:**
+
+```bash
+claude -p \
+  "Review the implementation plan below. Focus on:
+
+$(cat /tmp/plan-${REVIEW_ID}.md)
+
+1. Correctness — Will this plan achieve the stated goals?
+2. Risks — What could go wrong? Edge cases? Data loss?
+3. Missing steps — Is anything forgotten?
+4. Alternatives — Is there a simpler or better approach?
+5. Security — Any security concerns?
+
+Return exactly these sections in order:
+## Summary
+## Findings
+### P0
+### P1
+### P2
+### P3
+## Verdict
+
+Rules:
+- Order findings from highest severity to lowest.
+- Use `- None.` when a severity has no findings.
+- `P0` = total blocker, `P1` = major risk, `P2` = must-fix before approval, `P3` = cosmetic / nice to have.
+- End with exactly one verdict line: `VERDICT: APPROVED` or `VERDICT: REVISE`
+- `VERDICT: APPROVED` is allowed only when there are no `P0`, `P1`, or `P2` findings. `P3` findings are non-blocking." \
+  --model ${REVIEWER_MODEL} \
+  --strict-mcp-config \
+  --setting-sources user
+```
+
+**If `REVIEWER_CLI` is `cursor`:**
+
+```bash
+cursor-agent -p \
+  --mode=ask \
+  --model ${REVIEWER_MODEL} \
+  --trust \
+  --output-format json \
+  "Read the file /tmp/plan-${REVIEW_ID}.md and review the implementation plan. Focus on:
+1. Correctness — Will this plan achieve the stated goals?
+2. Risks — What could go wrong? Edge cases? Data loss?
+3. Missing steps — Is anything forgotten?
+4. Alternatives — Is there a simpler or better approach?
+5. Security — Any security concerns?
+
+Return exactly these sections in order:
+## Summary
+## Findings
+### P0
+### P1
+### P2
+### P3
+## Verdict
+
+Rules:
+- Order findings from highest severity to lowest.
+- Use `- None.` when a severity has no findings.
+- `P0` = total blocker, `P1` = major risk, `P2` = must-fix before approval, `P3` = cosmetic / nice to have.
+- End with exactly one verdict line: `VERDICT: APPROVED` or `VERDICT: REVISE`
+- `VERDICT: APPROVED` is allowed only when there are no `P0`, `P1`, or `P2` findings. `P3` findings are non-blocking." \
+  > /tmp/plan-review-${REVIEW_ID}.json
+```
+
+For `cursor`, the command script writes raw JSON to `/tmp/plan-review-${REVIEW_ID}.json`. Do not run `jq` extraction until after the helper or fallback execution completes. If `jq` is not installed, inform the user: `brew install jq` (macOS) or equivalent.
+
+Run the command script through the shared helper when available:
+
+```bash
+if [ -x "$REVIEWER_RUNTIME" ]; then
+  "$REVIEWER_RUNTIME" \
+    --command-file /tmp/plan-review-${REVIEW_ID}.sh \
+    --stdout-file /tmp/plan-review-${REVIEW_ID}.runner.out \
+    --stderr-file /tmp/plan-review-${REVIEW_ID}.stderr \
+    --status-file /tmp/plan-review-${REVIEW_ID}.status \
+    "${HELPER_SUCCESS_FILE_ARGS[@]}"
+else
+  echo "Warning: reviewer runtime helper not found at $REVIEWER_RUNTIME; falling back to direct synchronous review." >&2
+  bash /tmp/plan-review-${REVIEW_ID}.sh >/tmp/plan-review-${REVIEW_ID}.runner.out 2>/tmp/plan-review-${REVIEW_ID}.stderr
+fi
+```
+
+Run the helper in the foreground and watch its live stdout for `state=in-progress` heartbeats. If your agent environment buffers command output until exit, start the helper in the background and poll `/tmp/plan-review-${REVIEW_ID}.status` separately instead of treating heartbeats as post-hoc-only data.
+
+After the command completes:
+- If `REVIEWER_CLI=cursor`, extract the final review text:
+
+```bash
+CURSOR_SESSION_ID=$(jq -r '.session_id' /tmp/plan-review-${REVIEW_ID}.json)
+jq -r '.result' /tmp/plan-review-${REVIEW_ID}.json > /tmp/plan-review-${REVIEW_ID}.md
+```
+
+- If `REVIEWER_CLI=codex`, extract `CODEX_SESSION_ID` from `/tmp/plan-review-${REVIEW_ID}.runner.out` after the helper or fallback run. If the review text is only in `.runner.out`, move or copy the actual review body into `/tmp/plan-review-${REVIEW_ID}.md` before verdict parsing.
+- If `REVIEWER_CLI=claude`, promote stdout captured by the helper or fallback runner into the markdown review file:
+
+```bash
+cp /tmp/plan-review-${REVIEW_ID}.runner.out /tmp/plan-review-${REVIEW_ID}.md
+```
+
+Fallback is allowed only when the helper is missing or not executable.
+
+#### Step 4: Read Review & Check Verdict
+
+1. Read `/tmp/plan-review-${REVIEW_ID}.md`
+2. If the review failed, produced empty output, or reached helper timeout, also read:
+   - `/tmp/plan-review-${REVIEW_ID}.stderr`
+   - `/tmp/plan-review-${REVIEW_ID}.status`
+   - `/tmp/plan-review-${REVIEW_ID}.runner.out`
+3. Present review to the user:
+
+```
+## Plan Review — Round N (reviewer: ${REVIEWER_CLI} / ${REVIEWER_MODEL})
+
+[Reviewer feedback]
+```
+
+4. While the reviewer is still running, keep waiting as long as fresh `state=in-progress note="In progress N"` heartbeats continue to appear roughly once per minute.
+5. Check verdict:
+   - **VERDICT: APPROVED** with no `P0`, `P1`, or `P2` findings → proceed to Phase 7 (Initialize workspace)
+   - **VERDICT: APPROVED** with only `P3` findings → optionally fix the `P3` items if they are cheap and safe, then proceed
+   - **VERDICT: REVISE** or any `P0`, `P1`, or `P2` finding → go to Step 5
+   - No clear verdict but `P0`, `P1`, and `P2` are all `- None.` → treat as approved
+   - Helper state `completed-empty-output` → treat as failed review attempt, surface stderr/status, fix invocation or prompt handling, then retry
+   - Helper state `needs-operator-decision` → surface status log and decide whether to extend the timeout, abort, or retry with different helper parameters
+   - Max rounds (`MAX_ROUNDS`) reached → present the outcome to the user for a manual decision (proceed or stop)
+
+#### Step 5: Revise the Plan
+
+Address the reviewer findings in priority order (`P0` → `P1` → `P2`, then `P3` when practical). Update the plan in conversation context and rewrite `/tmp/plan-${REVIEW_ID}.md`.
+
+Summarize revisions for the user:
+
+```
+### Revisions (Round N)
+- [Change and reason, one bullet per issue addressed]
+```
+
+If a revision contradicts the user's explicit requirements, skip it and note it for the user.
+
+#### Step 6: Re-submit to Reviewer (Rounds 2-N)
+
+Rewrite `/tmp/plan-review-${REVIEW_ID}.sh` for the next round. The script should contain the reviewer invocation only; do not run it directly.
+
+**If `REVIEWER_CLI` is `codex`:**
+
+Resume the existing session:
+
+```bash
+codex exec resume ${CODEX_SESSION_ID} \
+  -o /tmp/plan-review-${REVIEW_ID}.md \
+  "I've revised the plan based on your feedback. Updated plan is in /tmp/plan-${REVIEW_ID}.md.
+
+Changes made:
+[List specific changes]
+
+Re-review using the same `## Summary`, `## Findings`, and `## Verdict` structure as before.
+Keep findings ordered `P0` to `P3`, use `- None.` when a severity has no findings, and only use `VERDICT: APPROVED` when no `P0`, `P1`, or `P2` findings remain. `P3` findings are non-blocking."
+```
+
+If resume fails (session expired), fall back to fresh `codex exec` with context about prior rounds.
+
+**If `REVIEWER_CLI` is `claude`:**
+
+Fresh call with accumulated context (Claude CLI has no session resume):
+
+```bash
+claude -p \
+  "You previously reviewed an implementation plan and requested revisions.
+
+Previous feedback summary: [key points from last review]
+
+I've revised the plan. Updated version is below.
+
+$(cat /tmp/plan-${REVIEW_ID}.md)
+
+Changes made:
+[List specific changes]
+
+Re-review the full plan using the same `## Summary`, `## Findings`, and `## Verdict` structure as before.
+Keep findings ordered `P0` to `P3`, use `- None.` when a severity has no findings, and only use `VERDICT: APPROVED` when no `P0`, `P1`, or `P2` findings remain. `P3` findings are non-blocking." \
+  --model ${REVIEWER_MODEL} \
+  --strict-mcp-config \
+  --setting-sources user
+```
+
+**If `REVIEWER_CLI` is `cursor`:**
+
+Resume the existing session:
+
+```bash
+cursor-agent --resume ${CURSOR_SESSION_ID} -p \
+  --mode=ask \
+  --model ${REVIEWER_MODEL} \
+  --trust \
+  --output-format json \
+  "I've revised the plan based on your feedback. Updated plan is in /tmp/plan-${REVIEW_ID}.md.
+
+Changes made:
+[List specific changes]
+
+Re-review using the same `## Summary`, `## Findings`, and `## Verdict` structure as before.
+Keep findings ordered `P0` to `P3`, use `- None.` when a severity has no findings, and only use `VERDICT: APPROVED` when no `P0`, `P1`, or `P2` findings remain. `P3` findings are non-blocking." \
+  > /tmp/plan-review-${REVIEW_ID}.json
+
+jq -r '.result' /tmp/plan-review-${REVIEW_ID}.json > /tmp/plan-review-${REVIEW_ID}.md
+```
+
+If resume fails, fall back to fresh `cursor-agent -p` with context about prior rounds.
+
+After updating `/tmp/plan-review-${REVIEW_ID}.sh`, run the same helper/fallback flow from Round 1.
+
+Return to Step 4.
+
+#### Step 7: Present Final Result
+
+```
+## Plan Review — Final (reviewer: ${REVIEWER_CLI} / ${REVIEWER_MODEL})
+
+**Status:** Approved after N round(s)
+[or]
+**Status:** Max rounds (`MAX_ROUNDS`) reached — not fully approved
+
+[Final feedback / remaining concerns]
+```
+
+#### Step 8: Cleanup
+
+```bash
+rm -f /tmp/plan-${REVIEW_ID}.md \
+  /tmp/plan-review-${REVIEW_ID}.md \
+  /tmp/plan-review-${REVIEW_ID}.json \
+  /tmp/plan-review-${REVIEW_ID}.stderr \
+  /tmp/plan-review-${REVIEW_ID}.status \
+  /tmp/plan-review-${REVIEW_ID}.runner.out \
+  /tmp/plan-review-${REVIEW_ID}.sh
+```
+
+If the round failed, produced empty output, or reached operator-decision timeout, keep `.stderr`, `.status`, and `.runner.out` until the issue is diagnosed instead of deleting them immediately.
+
+### Phase 7: Initialize Local Plan Workspace (MANDATORY)
+
+At project root:
+1. Ensure `ai_plan/` exists. Create it if missing.
+2. Ensure `.gitignore` contains `/ai_plan/`.
+3. If `.gitignore` was changed, commit that change immediately (local commit only).
+
+Recommended commit message:
+- `chore(gitignore): ignore ai_plan local planning artifacts`
+
+### Phase 8: Generate Plan Files (MANDATORY)
+
+Create `ai_plan/YYYY-MM-DD-<short-title>/` with all files below:
 1. `original-plan.md` - copy of original planner-generated plan.
 2. `final-transcript.md` - copy of final planning transcript used to reach approved plan.
 3. `milestone-plan.md` - full implementation spec (from template).
@@ -51,13 +471,50 @@ Create `docs/plans/YYYY-MM-DD-<short-title>/` with all files below:
 
 Use templates from this skill's `templates/` folder.
 
-### Phase 7: Handoff
+### Phase 9: Handoff
 
 Always instruct the executing agent:
-> Read `docs/plans/YYYY-MM-DD-<short-title>/continuation-runbook.md` first, then execute from that folder.
+> Read `ai_plan/YYYY-MM-DD-<short-title>/continuation-runbook.md` first, then execute from that folder.
 
 Do not rely on planner-private files during implementation.
 
+### Phase 10: Telegram Notification (MANDATORY)
+
+Resolve the Telegram notifier helper from the installed Codex skills directory:
+
+```bash
+TELEGRAM_NOTIFY_RUNTIME=~/.codex/skills/reviewer-runtime/notify-telegram.sh
+```
+
+On every terminal outcome for the create-plan run (approved, max rounds reached, skipped reviewer, or failure), send a Telegram summary if the helper exists and both `TELEGRAM_BOT_TOKEN` and `TELEGRAM_CHAT_ID` are configured:
+
+```bash
+if [ -x "$TELEGRAM_NOTIFY_RUNTIME" ] && [ -n "${TELEGRAM_BOT_TOKEN:-}" ] && [ -n "${TELEGRAM_CHAT_ID:-}" ]; then
+  "$TELEGRAM_NOTIFY_RUNTIME" --message "create-plan completed for <plan-folder-name>: <status summary>"
+fi
+```
+
+Rules:
+- Telegram is the only supported notification path. Do not use desktop notifications, `say`, email, or any other notifier.
+- Notification failures are non-blocking, but they must be surfaced to the user.
+- Before stopping for any user interaction, approval, or manual decision, send a Telegram summary first if configured.
+- If Telegram is not configured, state that no Telegram notification was sent.
+
+## Quick Reference
+
+| Phase | Action | Required Output |
+|---|---|---|
+| 1 | Analyze codebase/context | Constraints and known patterns |
+| 2 | Gather requirements (one question at a time) | Confirmed scope and success criteria |
+| 3 | Configure reviewer CLI and model | `REVIEWER_CLI`, `REVIEWER_MODEL`, `MAX_ROUNDS` (or `skip`) |
+| 4 | Invoke `superpowers:brainstorming` | Chosen design approach |
+| 5 | Invoke `superpowers:writing-plans` | Milestones and bite-sized stories |
+| 6 | Iterative plan review (max `MAX_ROUNDS` rounds) | Reviewer approval or max-rounds warning |
+| 7 | Initialize `ai_plan/` + `.gitignore` | Local planning workspace ready |
+| 8 | Build plan package from templates | Full plan folder with required files |
+| 9 | Handoff with runbook-first instruction | Resumable execution context |
+| 10 | Send Telegram notification | User notified or notification status reported |
+
 ## Execution Rules to Include in Plan (MANDATORY)
 
 - Run lint/typecheck/tests after each milestone.
@@ -71,14 +528,52 @@ Do not rely on planner-private files during implementation.
 
 ## Gitignore Note
 
-If `docs/plans` or `docs/plan` is gitignored, this is expected. Do not treat inability to commit plan-file updates as a problem. These files are local to the user.
+`ai_plan/` is intentionally local and must stay gitignored. Do not treat inability to commit plan-file updates in `ai_plan/` as a problem.
+
+## Common Mistakes
+
+- Using deprecated commands like `superpowers-codex bootstrap` or `superpowers-codex use-skill`.
+- Jumping to implementation planning without running `superpowers:brainstorming` first.
+- Asking multiple requirement questions in one message.
+- Forgetting to create/update `.gitignore` for `/ai_plan/`.
+- Omitting one or more required files in the plan package.
+- Handoff without explicit "read runbook first" direction.
+- Skipping the reviewer phase without explicit user opt-out.
+- Not capturing the Codex session ID for resume in subsequent review rounds.
+- Using any notification path other than Telegram.
+
+## Rationalizations and Counters
+
+| Rationalization | Counter |
+|---|---|
+| "Bootstrap CLI is faster" | Deprecated for Codex; native discovery is the supported path. |
+| "I can skip brainstorming for small tasks" | Creative/planning work still requires design validation first. |
+| "I don't need `update_plan` for checklist skills" | Checklist tracking is mandatory for execution reliability. |
+| "I can keep plan files outside `ai_plan/`" | This skill standardizes local resumable planning under `ai_plan/`. |
+| "The reviewer approved, I can skip my own validation" | Reviewer feedback supplements but does not replace your own verification. |
+
+## Red Flags - Stop and Correct
+
+- You are about to run any `superpowers-codex` command.
+- You started writing milestones before design validation.
+- You did not announce which skill you invoked and why.
+- You are marking planning complete without all required files.
+- Handoff does not explicitly point to `continuation-runbook.md`.
+- You are applying a reviewer suggestion that contradicts user requirements.
 
 ## Verification Checklist
 
-- [ ] Plan directory created under `docs/plans/` (or repo-standard `docs/plan/`)
+- [ ] `ai_plan/` exists at project root
+- [ ] `.gitignore` includes `/ai_plan/`
+- [ ] `.gitignore` ignore-rule commit was created if needed
+- [ ] Plan directory created under `ai_plan/YYYY-MM-DD-<short-title>/`
+- [ ] Reviewer configured or explicitly skipped
+- [ ] Max review rounds confirmed (default: 10)
+- [ ] Plan review completed (approved or max rounds) — or skipped
 - [ ] `original-plan.md` present
 - [ ] `final-transcript.md` present
 - [ ] `milestone-plan.md` present
 - [ ] `story-tracker.md` present
 - [ ] `continuation-runbook.md` present
 - [ ] Handoff explicitly says to read runbook first and execute from plan folder
+- [ ] Telegram notification attempted if configured

skills/create-plan/codex/templates/continuation-runbook.md

@@ -14,6 +14,13 @@ Upon resumption, these files in this folder are the ONLY source of truth:
 
 Do NOT reference planner-private files during implementation.
 
+## Skill Workflow Guardrails
+
+- Invoke relevant skills before action using native skill discovery.
+- Announce which skill is being used and why.
+- If a checklist-driven skill applies, track checklist execution explicitly.
+- Do not use deprecated CLI wrappers for skill invocation.
+
 ---
 
 ## Quick Resume Instructions
@@ -28,7 +35,7 @@ Do NOT reference planner-private files during implementation.
 
 ## Mandatory Execution Workflow
 
-Work from this folder (`docs/plans/YYYY-MM-DD-<short-title>/` or repo-specific `docs/plan/...`) and always follow this order:
+Work from this folder (`ai_plan/YYYY-MM-DD-<short-title>/`) and always follow this order:
 
 1. Read `continuation-runbook.md` first.
 2. Execute stories milestone by milestone.
@@ -51,7 +58,7 @@ Work from this folder (`docs/plans/YYYY-MM-DD-<short-title>/` or repo-specific `
 
 ## Git Note
 
-If `docs/plan` or `docs/plans` is gitignored, that is expected and acceptable. Do not treat inability to commit plan-file updates as an error. These files are local planning artifacts.
+`ai_plan/` is intentionally local and must stay gitignored. Do not treat inability to commit plan-file updates inside `ai_plan/` as an error.
 
 ---
 
@@ -102,17 +109,17 @@ If `docs/plan` or `docs/plans` is gitignored, that is expected and acceptable. D
 
 ### Lint (changed files first)
 ```bash
-# example: pnpm eslint <changed-file-1> <changed-file-2>
+# example: <lint-command> <changed-file-1> <changed-file-2>
 ```
 
 ### Typecheck
 ```bash
-# example: pnpm tsc --noEmit
+# example: <typecheck-command>
 ```
 
 ### Tests (target changed scope first)
 ```bash
-# example: pnpm test -- <related spec/file>
+# example: <test-command> <related spec/file>
 ```
 
 ---

skills/create-plan/codex/templates/milestone-plan.md

@@ -5,6 +5,12 @@
 - **Created:** YYYY-MM-DD
 - **Status:** In Progress | Complete
 
+## Planning Guardrails
+- This plan assumes design was validated before implementation planning.
+- Skills are invoked via native discovery (Codex: `~/.agents/skills/`).
+- Deprecated CLI wrappers (for example, `superpowers-codex bootstrap` / `use-skill`) are not part of this workflow.
+- Milestones require verification + local commits + explicit approval before proceeding.
+
 ## Context
 
 ### Requirements
@@ -69,17 +75,17 @@
 
 ### Types & Interfaces
 ```typescript
-// Key type definitions
+// Key type definitions (or equivalent language constructs)
 ```
 
 ### API Contracts
 ```typescript
-// Endpoint signatures, request/response shapes
+// Endpoint signatures, request/response shapes (if applicable)
 ```
 
 ### Constants & Enums
 ```typescript
-// Shared constants
+// Shared constants (if applicable)
 ```
 
 ## Files Inventory
@@ -93,7 +99,7 @@
 
 ## Related Plan Files
 
-This file is part of the plan folder under `docs/plans/` (or `docs/plan/` if that repo convention is used):
+This file is part of the plan folder under `ai_plan/`:
 - `original-plan.md` - Original approved plan (reference for original intent)
 - `final-transcript.md` - Final planning transcript (reference for rationale/context)
 - `milestone-plan.md` - This file (full specification)

skills/create-plan/codex/templates/story-tracker.md

@@ -6,6 +6,12 @@
 - **Milestones Approved:** 0/M
 - **Last Updated:** YYYY-MM-DD
 
+## Tracking Guardrails
+- Update status immediately when work starts (`in-dev`) and when work completes (`completed`).
+- Require explicit user approval at each milestone boundary before continuing.
+- Do not push until all milestones are approved and permission is explicitly granted.
+- Keep this file and `milestone-plan.md` synchronized.
+
 ---
 
 ## Milestones

skills/create-plan/cursor/SKILL.md

@@ -0,0 +1,600 @@
+---
+name: create-plan
+description: Use when starting a new feature, project, or complex task that needs structured planning with milestones, bite-sized stories, and resumable execution context in Cursor Agent CLI workflows. ALWAYS invoke when user says "create a plan", "make a plan", "plan this", "start planning", or similar planning requests.
+---
+
+# Create Plan (Cursor Agent CLI)
+
+Create and maintain a local plan folder under `ai_plan/` at project root.
+
+## Overview
+
+This skill wraps the current Superpowers flow for the Cursor Agent CLI (`cursor-agent`):
+1. Design first with `superpowers:brainstorming`
+2. Then build an implementation plan with `superpowers:writing-plans`
+3. Review the plan iteratively with a second model/provider
+4. Persist a local execution package in `ai_plan/YYYY-MM-DD-<short-title>/`
+
+**Core principle:** Cursor Agent CLI discovers skills from `.cursor/skills/` (repo-local or `~/.cursor/skills/` global). It also reads `AGENTS.md` at the repo root for additional instructions.
+
+## Prerequisite Check (MANDATORY)
+
+Required:
+- Cursor Agent CLI: `cursor-agent --version` (install via `curl https://cursor.com/install -fsS | bash`). The binary is `cursor-agent` (installed to `~/.local/bin/`). Some environments alias it as `cursor agent` (subcommand of the Cursor IDE CLI) — both forms work, but this skill uses `cursor-agent` throughout.
+- `jq` (required only if using `cursor` as the reviewer CLI): `jq --version` (install via `brew install jq` or your package manager)
+- Superpowers repo: `https://github.com/obra/superpowers`
+- Superpowers skills installed under `.cursor/skills/` (repo-local) or `~/.cursor/skills/` (global)
+- `superpowers:brainstorming`
+- `superpowers:writing-plans`
+
+Verify before proceeding:
+
+```bash
+cursor-agent --version
+test -f .cursor/skills/superpowers/skills/brainstorming/SKILL.md || test -f ~/.cursor/skills/superpowers/skills/brainstorming/SKILL.md
+test -f .cursor/skills/superpowers/skills/writing-plans/SKILL.md || test -f ~/.cursor/skills/superpowers/skills/writing-plans/SKILL.md
+# Only if using cursor as reviewer CLI:
+# jq --version
+```
+
+If any dependency is missing, stop and return:
+
+`Missing dependency: Superpowers planning skills are required (superpowers:brainstorming, superpowers:writing-plans). Install from https://github.com/obra/superpowers and copy into .cursor/skills/ or ~/.cursor/skills/, then retry.`
+
+## Required Skill Invocation Rules
+
+- Invoke relevant skills through workspace discovery (`.cursor/skills/`).
+- Announce skill usage explicitly:
+  - `I've read the [Skill Name] skill and I'm using it to [purpose].`
+- For skills with checklists, track checklist items explicitly in conversation.
+
+## Process
+
+### Phase 1: Analyze
+- Explore the codebase and existing patterns.
+
+### Phase 2: Gather Requirements
+- Ask questions one at a time until user says ready.
+- Confirm scope, constraints, success criteria, dependencies.
+
+### Phase 3: Configure Reviewer
+
+If the user has already specified a reviewer CLI and model (e.g., "create a plan, review with codex o4-mini"), use those values. Otherwise, ask:
+
+1. **Which CLI should review the plan?**
+   - `codex` — OpenAI Codex CLI (`codex exec`)
+   - `claude` — Claude Code CLI (`claude -p`)
+   - `cursor` — Cursor Agent CLI (`cursor-agent -p`)
+   - `skip` — No external review, proceed directly to file generation
+
+2. **Which model?** (only if a CLI was chosen)
+   - For `codex`: default `o4-mini`, alternatives: `gpt-5.3-codex`, `o3`
+   - For `claude`: default `sonnet`, alternatives: `opus`, `haiku`
+   - For `cursor`: **run `cursor-agent models` first** to see your account's available models (availability varies by subscription)
+   - Accept any model string the user provides
+
+3. **Max review rounds for the plan?** (default: 10)
+   - If the user does not provide a value, set `MAX_ROUNDS=10`.
+
+Store the chosen `REVIEWER_CLI`, `REVIEWER_MODEL`, and `MAX_ROUNDS` for Phase 6 (Iterative Plan Review).
+
+### Phase 4: Design (REQUIRED SUB-SKILL)
+
+Invoke `superpowers:brainstorming`, then propose 2-3 approaches and recommend one.
+
+### Phase 5: Plan (REQUIRED SUB-SKILL)
+
+Invoke `superpowers:writing-plans`, then break work into milestones and bite-sized stories.
+Story IDs: `S-{milestone}{sequence}`.
+
+### Phase 6: Iterative Plan Review
+
+Send the plan to the configured reviewer CLI for feedback. Revise and re-submit until approved (default max 10 rounds).
+
+**Skip this phase entirely if reviewer was set to `skip`.**
+
+#### Step 1: Generate Session ID
+
+```bash
+REVIEW_ID=$(uuidgen | tr '[:upper:]' '[:lower:]' | head -c 8)
+```
+
+Use for temp artifacts:
+- `/tmp/plan-${REVIEW_ID}.md`
+- `/tmp/plan-review-${REVIEW_ID}.md`
+- `/tmp/plan-review-${REVIEW_ID}.json` (Cursor only)
+- `/tmp/plan-review-${REVIEW_ID}.stderr`
+- `/tmp/plan-review-${REVIEW_ID}.status`
+- `/tmp/plan-review-${REVIEW_ID}.runner.out`
+- `/tmp/plan-review-${REVIEW_ID}.sh`
+
+Resolve the shared reviewer helper from Cursor's installed skills directory:
+
+```bash
+if [ -x .cursor/skills/reviewer-runtime/run-review.sh ]; then
+  REVIEWER_RUNTIME=.cursor/skills/reviewer-runtime/run-review.sh
+else
+  REVIEWER_RUNTIME=~/.cursor/skills/reviewer-runtime/run-review.sh
+fi
+```
+
+Set helper success-artifact args before writing the command script:
+
+```bash
+HELPER_SUCCESS_FILE_ARGS=()
+case "$REVIEWER_CLI" in
+  codex)
+    HELPER_SUCCESS_FILE_ARGS+=(--success-file /tmp/plan-review-${REVIEW_ID}.md)
+    ;;
+  cursor)
+    HELPER_SUCCESS_FILE_ARGS+=(--success-file /tmp/plan-review-${REVIEW_ID}.json)
+    ;;
+esac
+```
+
+#### Step 2: Write Plan to Temp File
+
+Write the complete plan (milestones, stories, design decisions, specs) to `/tmp/plan-${REVIEW_ID}.md`.
+
+#### Review Contract (Applies to Every Round)
+
+The reviewer response must use this structure:
+
+```text
+## Summary
+...
+
+## Findings
+### P0
+- ...
+### P1
+- ...
+### P2
+- ...
+### P3
+- ...
+
+## Verdict
+VERDICT: APPROVED
+```
+
+Rules:
+- Order findings from `P0` to `P3`.
+- `P0` = total blocker, `P1` = major risk, `P2` = must-fix before approval, `P3` = cosmetic / nice to have.
+- Use `- None.` when a severity has no findings.
+- `VERDICT: APPROVED` is allowed only when no `P0`, `P1`, or `P2` findings remain. `P3` findings are non-blocking.
+- The calling agent should still try to fix `P3` findings when they are cheap and safe.
+
+#### Liveness Contract (Applies While Review Is Running)
+
+- The shared reviewer runtime emits `state=in-progress note="In progress N"` heartbeats every 60 seconds while the reviewer child is alive.
+- The calling agent must keep waiting as long as a fresh `In progress N` heartbeat keeps arriving roughly once per minute.
+- Do not abort just because the review is slow, a soft timeout fired, or a `stall-warning` line appears, as long as the `In progress N` heartbeat continues.
+- Treat missing heartbeats, `state=failed`, `state=completed-empty-output`, and `state=needs-operator-decision` as escalation signals.
+
+#### Step 3: Submit to Reviewer (Round 1)
+
+Write the reviewer invocation to `/tmp/plan-review-${REVIEW_ID}.sh` as a bash script:
+
+```bash
+#!/usr/bin/env bash
+set -euo pipefail
+```
+
+**If `REVIEWER_CLI` is `codex`:**
+
+```bash
+codex exec \
+  -m ${REVIEWER_MODEL} \
+  -s read-only \
+  -o /tmp/plan-review-${REVIEW_ID}.md \
+  "Review the implementation plan in /tmp/plan-${REVIEW_ID}.md. Focus on:
+1. Correctness — Will this plan achieve the stated goals?
+2. Risks — What could go wrong? Edge cases? Data loss?
+3. Missing steps — Is anything forgotten?
+4. Alternatives — Is there a simpler or better approach?
+5. Security — Any security concerns?
+
+Return exactly these sections in order:
+## Summary
+## Findings
+### P0
+### P1
+### P2
+### P3
+## Verdict
+
+Rules:
+- Order findings from highest severity to lowest.
+- Use `- None.` when a severity has no findings.
+- `P0` = total blocker, `P1` = major risk, `P2` = must-fix before approval, `P3` = cosmetic / nice to have.
+- End with exactly one verdict line: `VERDICT: APPROVED` or `VERDICT: REVISE`
+- `VERDICT: APPROVED` is allowed only when there are no `P0`, `P1`, or `P2` findings. `P3` findings are non-blocking."
+```
+
+Do not try to capture the Codex session ID yet. When using the helper, extract it from `/tmp/plan-review-${REVIEW_ID}.runner.out` after the command completes (look for `session id: <uuid>`), then store it as `CODEX_SESSION_ID` for resume in subsequent rounds.
+
+**If `REVIEWER_CLI` is `claude`:**
+
+```bash
+claude -p \
+  "Review the implementation plan below. Focus on:
+
+$(cat /tmp/plan-${REVIEW_ID}.md)
+
+1. Correctness — Will this plan achieve the stated goals?
+2. Risks — What could go wrong? Edge cases? Data loss?
+3. Missing steps — Is anything forgotten?
+4. Alternatives — Is there a simpler or better approach?
+5. Security — Any security concerns?
+
+Return exactly these sections in order:
+## Summary
+## Findings
+### P0
+### P1
+### P2
+### P3
+## Verdict
+
+Rules:
+- Order findings from highest severity to lowest.
+- Use `- None.` when a severity has no findings.
+- `P0` = total blocker, `P1` = major risk, `P2` = must-fix before approval, `P3` = cosmetic / nice to have.
+- End with exactly one verdict line: `VERDICT: APPROVED` or `VERDICT: REVISE`
+- `VERDICT: APPROVED` is allowed only when there are no `P0`, `P1`, or `P2` findings. `P3` findings are non-blocking." \
+  --model ${REVIEWER_MODEL} \
+  --strict-mcp-config \
+  --setting-sources user
+```
+
+**If `REVIEWER_CLI` is `cursor`:**
+
+```bash
+cursor-agent -p \
+  --mode=ask \
+  --model ${REVIEWER_MODEL} \
+  --trust \
+  --output-format json \
+  "Read the file /tmp/plan-${REVIEW_ID}.md and review the implementation plan. Focus on:
+1. Correctness — Will this plan achieve the stated goals?
+2. Risks — What could go wrong? Edge cases? Data loss?
+3. Missing steps — Is anything forgotten?
+4. Alternatives — Is there a simpler or better approach?
+5. Security — Any security concerns?
+
+Return exactly these sections in order:
+## Summary
+## Findings
+### P0
+### P1
+### P2
+### P3
+## Verdict
+
+Rules:
+- Order findings from highest severity to lowest.
+- Use `- None.` when a severity has no findings.
+- `P0` = total blocker, `P1` = major risk, `P2` = must-fix before approval, `P3` = cosmetic / nice to have.
+- End with exactly one verdict line: `VERDICT: APPROVED` or `VERDICT: REVISE`
+- `VERDICT: APPROVED` is allowed only when there are no `P0`, `P1`, or `P2` findings. `P3` findings are non-blocking." \
+  > /tmp/plan-review-${REVIEW_ID}.json
+```
+
+For `cursor`, the command script writes raw JSON to `/tmp/plan-review-${REVIEW_ID}.json`. Do not run `jq` extraction until after the helper or fallback execution completes.
+
+Notes on Cursor flags:
+- `--mode=ask` — read-only mode, no file modifications
+- `--trust` — trust workspace without prompting (required for non-interactive use)
+- `-p` / `--print` — non-interactive mode, output to stdout
+- `--output-format json` — structured output with `session_id` and `result` fields
+
+Run the command script through the shared helper when available:
+
+```bash
+if [ -x "$REVIEWER_RUNTIME" ]; then
+  "$REVIEWER_RUNTIME" \
+    --command-file /tmp/plan-review-${REVIEW_ID}.sh \
+    --stdout-file /tmp/plan-review-${REVIEW_ID}.runner.out \
+    --stderr-file /tmp/plan-review-${REVIEW_ID}.stderr \
+    --status-file /tmp/plan-review-${REVIEW_ID}.status \
+    "${HELPER_SUCCESS_FILE_ARGS[@]}"
+else
+  echo "Warning: reviewer runtime helper not found at $REVIEWER_RUNTIME; falling back to direct synchronous review." >&2
+  bash /tmp/plan-review-${REVIEW_ID}.sh >/tmp/plan-review-${REVIEW_ID}.runner.out 2>/tmp/plan-review-${REVIEW_ID}.stderr
+fi
+```
+
+Run the helper in the foreground and watch its live stdout for `state=in-progress` heartbeats. If your agent environment buffers command output until exit, start the helper in the background and poll `/tmp/plan-review-${REVIEW_ID}.status` separately instead of treating heartbeats as post-hoc-only data.
+
+After the command completes:
+- If `REVIEWER_CLI=cursor`, extract the final review text:
+
+```bash
+CURSOR_SESSION_ID=$(jq -r '.session_id' /tmp/plan-review-${REVIEW_ID}.json)
+jq -r '.result' /tmp/plan-review-${REVIEW_ID}.json > /tmp/plan-review-${REVIEW_ID}.md
+```
+
+- If `REVIEWER_CLI=codex`, extract `CODEX_SESSION_ID` from `/tmp/plan-review-${REVIEW_ID}.runner.out` after the helper or fallback run. If the review text is only in `.runner.out`, move or copy the actual review body into `/tmp/plan-review-${REVIEW_ID}.md` before verdict parsing.
+- If `REVIEWER_CLI=claude`, promote stdout captured by the helper or fallback runner into the markdown review file:
+
+```bash
+cp /tmp/plan-review-${REVIEW_ID}.runner.out /tmp/plan-review-${REVIEW_ID}.md
+```
+
+#### Step 4: Read Review & Check Verdict
+
+1. Read `/tmp/plan-review-${REVIEW_ID}.md`
+2. If the review failed, produced empty output, or reached helper timeout, also read:
+   - `/tmp/plan-review-${REVIEW_ID}.stderr`
+   - `/tmp/plan-review-${REVIEW_ID}.status`
+   - `/tmp/plan-review-${REVIEW_ID}.runner.out`
+3. Present review to the user:
+
+```
+## Plan Review — Round N (reviewer: ${REVIEWER_CLI} / ${REVIEWER_MODEL})
+
+[Reviewer feedback]
+```
+
+4. While the reviewer is still running, keep waiting as long as fresh `state=in-progress note="In progress N"` heartbeats continue to appear roughly once per minute.
+5. Check verdict:
+   - **VERDICT: APPROVED** with no `P0`, `P1`, or `P2` findings → proceed to Phase 7 (Initialize workspace)
+   - **VERDICT: APPROVED** with only `P3` findings → optionally fix the `P3` items if they are cheap and safe, then proceed
+   - **VERDICT: REVISE** or any `P0`, `P1`, or `P2` finding → go to Step 5
+   - No clear verdict but `P0`, `P1`, and `P2` are all `- None.` → treat as approved
+   - Helper state `completed-empty-output` → treat as failed review attempt, surface stderr/status, fix invocation or prompt handling, then retry
+   - Helper state `needs-operator-decision` → surface status log and decide whether to extend the timeout, abort, or retry with different helper parameters
+   - Max rounds (`MAX_ROUNDS`) reached → present the outcome to the user for a manual decision (proceed or stop)
+
+#### Step 5: Revise the Plan
+
+Address the reviewer findings in priority order (`P0` → `P1` → `P2`, then `P3` when practical). Update the plan in conversation context and rewrite `/tmp/plan-${REVIEW_ID}.md`.
+
+Summarize revisions for the user:
+
+```
+### Revisions (Round N)
+- [Change and reason, one bullet per issue addressed]
+```
+
+If a revision contradicts the user's explicit requirements, skip it and note it for the user.
+
+#### Step 6: Re-submit to Reviewer (Rounds 2-N)
+
+Rewrite `/tmp/plan-review-${REVIEW_ID}.sh` for the next round. The script should contain the reviewer invocation only; do not run it directly.
+
+**If `REVIEWER_CLI` is `codex`:**
+
+Resume the existing session:
+
+```bash
+codex exec resume ${CODEX_SESSION_ID} \
+  -o /tmp/plan-review-${REVIEW_ID}.md \
+  "I've revised the plan based on your feedback. Updated plan is in /tmp/plan-${REVIEW_ID}.md.
+
+Changes made:
+[List specific changes]
+
+Re-review using the same `## Summary`, `## Findings`, and `## Verdict` structure as before.
+Keep findings ordered `P0` to `P3`, use `- None.` when a severity has no findings, and only use `VERDICT: APPROVED` when no `P0`, `P1`, or `P2` findings remain. `P3` findings are non-blocking."
+```
+
+If resume fails (session expired), fall back to fresh `codex exec` with context about prior rounds.
+
+**If `REVIEWER_CLI` is `claude`:**
+
+Fresh call with accumulated context (Claude CLI has no session resume):
+
+```bash
+claude -p \
+  "You previously reviewed an implementation plan and requested revisions.
+
+Previous feedback summary: [key points from last review]
+
+I've revised the plan. Updated version is below.
+
+$(cat /tmp/plan-${REVIEW_ID}.md)
+
+Changes made:
+[List specific changes]
+
+Re-review the full plan using the same `## Summary`, `## Findings`, and `## Verdict` structure as before.
+Keep findings ordered `P0` to `P3`, use `- None.` when a severity has no findings, and only use `VERDICT: APPROVED` when no `P0`, `P1`, or `P2` findings remain. `P3` findings are non-blocking." \
+  --model ${REVIEWER_MODEL} \
+  --strict-mcp-config \
+  --setting-sources user
+```
+
+**If `REVIEWER_CLI` is `cursor`:**
+
+Resume the existing session:
+
+```bash
+cursor-agent --resume ${CURSOR_SESSION_ID} -p \
+  --mode=ask \
+  --model ${REVIEWER_MODEL} \
+  --trust \
+  --output-format json \
+  "I've revised the plan based on your feedback. Updated plan is in /tmp/plan-${REVIEW_ID}.md.
+
+Changes made:
+[List specific changes]
+
+Re-review using the same `## Summary`, `## Findings`, and `## Verdict` structure as before.
+Keep findings ordered `P0` to `P3`, use `- None.` when a severity has no findings, and only use `VERDICT: APPROVED` when no `P0`, `P1`, or `P2` findings remain. `P3` findings are non-blocking." \
+  > /tmp/plan-review-${REVIEW_ID}.json
+
+jq -r '.result' /tmp/plan-review-${REVIEW_ID}.json > /tmp/plan-review-${REVIEW_ID}.md
+```
+
+If resume fails, fall back to fresh `cursor-agent -p` with context about prior rounds.
+
+After updating `/tmp/plan-review-${REVIEW_ID}.sh`, run the same helper/fallback flow from Round 1.
+
+Return to Step 4.
+
+#### Step 7: Present Final Result
+
+```
+## Plan Review — Final (reviewer: ${REVIEWER_CLI} / ${REVIEWER_MODEL})
+
+**Status:** Approved after N round(s)
+[or]
+**Status:** Max rounds (`MAX_ROUNDS`) reached — not fully approved
+
+[Final feedback / remaining concerns]
+```
+
+#### Step 8: Cleanup
+
+```bash
+rm -f /tmp/plan-${REVIEW_ID}.md \
+  /tmp/plan-review-${REVIEW_ID}.md \
+  /tmp/plan-review-${REVIEW_ID}.json \
+  /tmp/plan-review-${REVIEW_ID}.stderr \
+  /tmp/plan-review-${REVIEW_ID}.status \
+  /tmp/plan-review-${REVIEW_ID}.runner.out \
+  /tmp/plan-review-${REVIEW_ID}.sh
+```
+
+If the round failed, produced empty output, or reached operator-decision timeout, keep `.stderr`, `.status`, and `.runner.out` until the issue is diagnosed instead of deleting them immediately.
+
+### Phase 7: Initialize Local Plan Workspace (MANDATORY)
+
+At project root:
+1. Ensure `ai_plan/` exists. Create it if missing.
+2. Ensure `.gitignore` contains `/ai_plan/`.
+3. If `.gitignore` was changed, commit that change immediately (local commit only).
+
+Recommended commit message:
+- `chore(gitignore): ignore ai_plan local planning artifacts`
+
+### Phase 8: Generate Plan Files (MANDATORY)
+
+Create `ai_plan/YYYY-MM-DD-<short-title>/` with all files below:
+1. `original-plan.md` - copy of original planner-generated plan.
+2. `final-transcript.md` - copy of final planning transcript used to reach approved plan.
+3. `milestone-plan.md` - full implementation spec (from template).
+4. `story-tracker.md` - story/milestone status tracker (from template).
+5. `continuation-runbook.md` - execution instructions and context (from template).
+
+Use templates from this skill's `templates/` folder.
+
+### Phase 9: Handoff
+
+Always instruct the executing agent:
+> Read `ai_plan/YYYY-MM-DD-<short-title>/continuation-runbook.md` first, then execute from that folder.
+
+Do not rely on planner-private files during implementation.
+
+### Phase 10: Telegram Notification (MANDATORY)
+
+Resolve the Telegram notifier helper from Cursor's installed skills directory:
+
+```bash
+if [ -x .cursor/skills/reviewer-runtime/notify-telegram.sh ]; then
+  TELEGRAM_NOTIFY_RUNTIME=.cursor/skills/reviewer-runtime/notify-telegram.sh
+else
+  TELEGRAM_NOTIFY_RUNTIME=~/.cursor/skills/reviewer-runtime/notify-telegram.sh
+fi
+```
+
+On every terminal outcome for the create-plan run (approved, max rounds reached, skipped reviewer, or failure), send a Telegram summary if the helper exists and both `TELEGRAM_BOT_TOKEN` and `TELEGRAM_CHAT_ID` are configured:
+
+```bash
+if [ -x "$TELEGRAM_NOTIFY_RUNTIME" ] && [ -n "${TELEGRAM_BOT_TOKEN:-}" ] && [ -n "${TELEGRAM_CHAT_ID:-}" ]; then
+  "$TELEGRAM_NOTIFY_RUNTIME" --message "create-plan completed for <plan-folder-name>: <status summary>"
+fi
+```
+
+Rules:
+- Telegram is the only supported notification path. Do not use desktop notifications, `say`, email, or any other notifier.
+- Notification failures are non-blocking, but they must be surfaced to the user.
+- Before stopping for any user interaction, approval, or manual decision, send a Telegram summary first if configured.
+- If Telegram is not configured, state that no Telegram notification was sent.
+
+## Quick Reference
+
+| Phase | Action | Required Output |
+|---|---|---|
+| 1 | Analyze codebase/context | Constraints and known patterns |
+| 2 | Gather requirements (one question at a time) | Confirmed scope and success criteria |
+| 3 | Configure reviewer CLI and model | `REVIEWER_CLI`, `REVIEWER_MODEL`, `MAX_ROUNDS` (or `skip`) |
+| 4 | Invoke `superpowers:brainstorming` | Chosen design approach |
+| 5 | Invoke `superpowers:writing-plans` | Milestones and bite-sized stories |
+| 6 | Iterative plan review (max `MAX_ROUNDS` rounds) | Reviewer approval or max-rounds warning |
+| 7 | Initialize `ai_plan/` + `.gitignore` | Local planning workspace ready |
+| 8 | Build plan package from templates | Full plan folder with required files |
+| 9 | Handoff with runbook-first instruction | Resumable execution context |
+| 10 | Send Telegram notification | User notified or notification status reported |
+
+## Tracker Discipline (MANDATORY)
+
+Before starting any story:
+1. Open `story-tracker.md`
+2. Mark story `in-dev`
+3. Add notes if relevant
+4. Then begin implementation
+
+After completing any story:
+1. Mark story `completed`
+2. Add commit hash in Notes
+3. Review pending stories
+4. Update Last Updated and Stories Complete counts
+
+## Execution Rules to Include in Plan (MANDATORY)
+
+- Run lint/typecheck/tests after each milestone.
+- Prefer linting changed files only for speed.
+- Commit locally after each completed milestone (**do not push**).
+- Stop and ask user for feedback.
+- Apply feedback, rerun checks, and commit again.
+- Move to next milestone only after user approval.
+- After all milestones are completed and approved, ask permission to push.
+- Only after approved push: mark plan as completed.
+
+## Gitignore Note
+
+`ai_plan/` is intentionally local and must stay gitignored. Do not treat inability to commit plan-file updates in `ai_plan/` as a problem.
+
+## Common Mistakes
+
+- Forgetting `--trust` flag when running `cursor-agent` non-interactively (causes interactive prompt).
+- Using `--mode=agent` or `--force` for reviews (reviewer should be read-only, use `--mode=ask`).
+- Jumping to implementation planning without running `superpowers:brainstorming` first.
+- Asking multiple requirement questions in one message.
+- Forgetting to create/update `.gitignore` for `/ai_plan/`.
+- Omitting one or more required files in the plan package.
+- Handoff without explicit "read runbook first" direction.
+- Skipping the reviewer phase without explicit user opt-out.
+- Using any notification path other than Telegram.
+
+## Red Flags - Stop and Correct
+
+- You started writing milestones before design validation.
+- You did not announce which skill you invoked and why.
+- You are marking planning complete without all required files.
+- Handoff does not explicitly point to `continuation-runbook.md`.
+- You are applying a reviewer suggestion that contradicts user requirements.
+- Reviewer CLI is running with write permissions (must be read-only).
+
+## Verification Checklist
+
+- [ ] `ai_plan/` exists at project root
+- [ ] `.gitignore` includes `/ai_plan/`
+- [ ] `.gitignore` ignore-rule commit was created if needed
+- [ ] Plan directory created under `ai_plan/YYYY-MM-DD-<short-title>/`
+- [ ] Reviewer configured or explicitly skipped
+- [ ] Max review rounds confirmed (default: 10)
+- [ ] Plan review completed (approved or max rounds) — or skipped
+- [ ] `original-plan.md` present
+- [ ] `final-transcript.md` present
+- [ ] `milestone-plan.md` present
+- [ ] `story-tracker.md` present
+- [ ] `continuation-runbook.md` present
+- [ ] Handoff explicitly says to read runbook first and execute from plan folder
+- [ ] Telegram notification attempted if configured
+
+## Exit Triggers for Question Phase
+User says: "ready", "done", "let's plan", "proceed", "enough questions"

skills/create-plan/cursor/templates/continuation-runbook.md

@@ -0,0 +1,134 @@
+# Continuation Runbook: [Plan Title]
+
+## Reference Files (START HERE)
+
+Upon resumption, these files in this folder are the ONLY source of truth:
+
+| File | Purpose | When to Use |
+|------|---------|-------------|
+| `continuation-runbook.md` | Full context reproduction + execution workflow | Read FIRST |
+| `story-tracker.md` | Current progress and status | Check/update BEFORE and AFTER every story |
+| `milestone-plan.md` | Complete plan with specifications | Reference implementation details |
+| `original-plan.md` | Original approved plan | Reference original intent |
+| `final-transcript.md` | Final planning transcript | Reference reasoning/context |
+
+Do NOT reference planner-private files during implementation.
+
+## Skill Workflow Guardrails
+
+- Invoke relevant skills before action using workspace discovery (`.cursor/skills/`).
+- Announce which skill is being used and why.
+- If a checklist-driven skill applies, track checklist execution explicitly.
+
+---
+
+## Quick Resume Instructions
+
+1. Read this runbook completely.
+2. Check `story-tracker.md`.
+3. Find next `pending` story and mark as `in-dev` before starting.
+4. Implement the story.
+5. Update tracker immediately after each change.
+
+---
+
+## Mandatory Execution Workflow
+
+Work from this folder (`ai_plan/YYYY-MM-DD-<short-title>/`) and always follow this order:
+
+1. Read `continuation-runbook.md` first.
+2. Execute stories milestone by milestone.
+3. After completing a milestone:
+   - Run lint/typecheck/tests, prioritizing changed files for speed.
+   - Commit locally (**DO NOT PUSH**).
+   - Stop and ask user for feedback.
+4. If feedback is provided:
+   - Apply feedback changes.
+   - Re-run checks for changed files.
+   - Commit locally again.
+   - Ask for milestone approval.
+5. Only move to next milestone after explicit approval.
+6. After all milestones are completed and approved:
+   - Ask permission to push.
+   - If approved, push.
+   - Mark plan status as `completed`.
+
+---
+
+## Git Note
+
+`ai_plan/` is intentionally local and must stay gitignored. Do not treat inability to commit plan-file updates inside `ai_plan/` as an error.
+
+---
+
+## Full Context Reproduction
+
+### Project Overview
+[What this project/feature is about]
+
+### User Requirements
+[All gathered requirements]
+
+### Scope
+[In scope / out of scope]
+
+### Dependencies
+[External dependencies, prerequisites, related systems]
+
+---
+
+## Key Specifications
+
+### Type Definitions
+```typescript
+// Copy-paste ready type definitions
+```
+
+### Enums & Constants
+```typescript
+// All enums/constants needed
+```
+
+### API Endpoints
+```typescript
+// Request/response shapes
+```
+
+---
+
+## Critical Design Decisions
+
+| Decision | Chosen Approach | Alternatives Rejected | Rationale |
+|----------|-----------------|----------------------|-----------|
+| [Topic] | [What we chose] | [Other options] | [Why] |
+
+---
+
+## Verification Commands
+
+### Lint (changed files first)
+```bash
+# example: <lint-command> <changed-file-1> <changed-file-2>
+```
+
+### Typecheck
+```bash
+# example: <typecheck-command>
+```
+
+### Tests (target changed scope first)
+```bash
+# example: <test-command> <related spec/file>
+```
+
+---
+
+## File Quick Reference
+
+| File | Purpose |
+|------|---------|
+| `original-plan.md` | Original approved plan |
+| `final-transcript.md` | Final planning transcript |
+| `milestone-plan.md` | Full specification |
+| `story-tracker.md` | Current progress tracker |
+| `continuation-runbook.md` | This runbook |