Initialize Jira

State-aware skill for the Jira side of AI Workflow. Two phases triggered by detected state:

• Phase 1: Credentials and secret pre-gen. Runs when JIRA_BASE_URL is not yet in Vercel env.
• Phase 2: Webhook registration. Runs when phase 1 is done and a production deploy exists.

Canonical reference: SETUP.md section 2.1 holds the facts and constraints for Jira, and section 7 covers the webhook. This skill is the procedure; when the two disagree, SETUP.md wins and this skill gets updated.

If you want full project setup (Jira + VCS + Agent + Slack + Neon + deploy), invoke init-env instead. This skill only handles Jira.

Precondition

apps/worker/.vercel/project.json must exist: the worker is linked from apps/worker (SETUP.md section 3), and this skill's commands run there. If missing:

ERROR: no Vercel project linked. Run `vercel link` first, or invoke `init-env`
for the full first-time setup.

Halt. Do not proceed.

State detection

On entry, run:

test -f .vercel/project.json && cat .vercel/project.json   # project name
vercel env ls | grep -wE "JIRA_BASE_URL|JIRA_API_TOKEN"    # phase 1 done?
# Also check Integrations → Jira in the dashboard: values stored there count as phase 1 done.
vercel ls --prod                                           # production deploy?

Phase 1: Credentials and secret pre-gen

1a. Has the Jira project been set up for AI Workflow?

Ask: "Has your Jira board, statuses, and workflow transitions already been configured for AI Workflow?"

• No / unsure: walk the user through these references in order, one per turn:
  • references/column-statuses.md: statuses must exist in Jira and match the three board column settings.
  • references/transitions.md: the bot must find a transition into each target status, by configured id, destination status or name (the most-missed step).
  • references/description-format.md: the "Acceptance Criteria" block in the description.
• Yes: continue.

1b. Generate the webhook secret

openssl rand -hex 32

Hold the value for the paste-template below. Even if the user later defers webhook registration, having the secret in Vercel env now means no redeploy is needed when phase 2 runs.

1c. Collect values

Ask in one prompt (single credential bundle):

• JIRA_BASE_URL: e.g. https://acme.atlassian.net (no trailing slash, no /jira)
• JIRA_API_TOKEN: a scoped service-account token (read:jira-work, write:jira-work) from admin.atlassian.com, Directory, Service accounts, API tokens (SETUP.md section 2.1). A personal token from id.atlassian.com does not work: the client sends it as Bearer through api.atlassian.com.
• JIRA_PROJECT_KEY: e.g. AWT

Tell the user that the AI, AI Review, and Backlog status names are configured on the Settings page. They must match Jira status names exactly, ignoring case.

1d. Emit paste-template

Print this single block for the user to copy into Vercel → Project Settings → Environment Variables (set for all three environments: Production, Preview, Development):

JIRA_BASE_URL=<value>
JIRA_API_TOKEN=<value>
JIRA_PROJECT_KEY=<value>
JIRA_WEBHOOK_SECRET=<generated>

Tell the user to paste, save, and reply when done.

1e. Done

Phase 1 complete. Tell the user:

Phase 1 done. Webhook registration will run after the first production deploy.

If invoked from init-env, return control. If invoked standalone, end the turn.

Phase 2: Webhook registration

2a. Derive the webhook URL

Read .vercel/project.json to get the project name. Construct:

https://<project>.vercel.app/webhooks/jira

If the user has a custom domain configured for production traffic, they should swap the host themselves after registration. Note this in the runbook output but don't try to detect domains automatically.

2b. Walk the registration runbook

Hand the user references/webhook-setup.md. The TL;DR:

1. Open ${JIRA_BASE_URL}/plugins/servlet/webhooks (e.g. https://acme.atlassian.net/plugins/servlet/webhooks).
2. Click Create a WebHook.
3. Fill:
   • Name: AI Workflow dispatch
   • Status: Enabled
   • URL: the webhook URL from 2a
   • Secret: the JIRA_WEBHOOK_SECRET already in Vercel env (re-fetch with vercel env ls if the user needs to confirm it's set)
   • JQL filter: project = "<JIRA_PROJECT_KEY>"
   • Events: check Issue → Issue updated (required). Optionally Issue created and Comment created (SETUP.md section 7).
   • Exclude body: leave unchecked
4. Save.

The shared route apps/worker/src/routes/webhooks/[id].post.ts hands the delivery to integrations/jira/webhook.ts, which verifies the X-Hub-Signature HMAC. Without JIRA_WEBHOOK_SECRET every delivery is refused with 503, so tickets are only found by the cron poll.

2c. Verify

Tell the user to drag any ticket into the AI column. They should see (in vercel logs --prod):

jira_webhook_understood        ticketKey=... webhookEvent=jira:issue_updated
ticket_event_dispatch_started
ticket_event_dispatch_result

The Jira card's Webhook registration health check on the Integrations page also says whether a webhook points at this deployment and sends issue updates.

If they get 401 The signature did not match., the secret in Jira and in Vercel env don't match: copy from vercel env ls again.

2d. Defer path

If the user cannot register the webhook now (admin permission missing, custom domain pending, etc.), record this as a TODO. The bot still works via the cron poll fallback, which runs every 15 minutes (apps/worker/vercel.json).

If invoked from init-env, return control with the TODO flag set. If standalone, print the deferred message and end.

Troubleshooting

For diagnostic flows after phase 2 (signature failures, transition errors, missing PR), see references/troubleshooting.md.

Don'ts

• Don't print the webhook secret value back to chat after generating it. Reference by name.
• Don't try to detect custom domains from .vercel/project.json: that file doesn't carry domain info reliably. Default to <project>.vercel.app and tell the user to swap if they have a custom domain.
• Don't subscribe to every event: Issue updated is required, Issue created and Comment created are the only useful optional ones, and the rest is noise the handler filters away.