gw-triage/skills/setup/SKILL.md

---
name: setup
description: Use when configuring the Jira API credentials for gw-triage — first-time setup, an "allegato saltato" warning from triage, missing or expired credentials, or replacing a revoked token. Triggers on /gw-triage:setup, $setup, "configura il token", "gli allegati non funzionano".
---

# Setup — token API Jira guidato

You guide the user through creating a Jira API token and storing it in
the gw-triage netrc file. The `triage` skill reads that file for its
REST calls: screenshot attachments on every platform, plus search /
create / comment when running under Codex.

**All interaction with the user happens in Italian.** This file is
English for precision; never quote it to the user.

## Environment

- **Root**: `${CLAUDE_PLUGIN_ROOT}` if that variable is set; otherwise
  the real path of this skill's own directory (resolve symlinks, e.g.
  with `realpath`), two levels up.
- **Store**: `~/.config/gw-triage/netrc`, mode 600. curl reads it at
  call time on every platform, so changes take effect immediately — no
  session restart, no shell configuration.
- **Host**: the `site` value in `<root>/config/routing.json` without
  the scheme (e.g. `growingway.atlassian.net`).

**Keep the token out of replies and displayed commands.** Refer to it
as "il token" and never repeat its value. Never inline a literal token
on a shell command line — it ends up in the transcript and the process
list. Write credentials into the netrc file with the file-writing
tool — or, for values that live only in session env vars, via shell
redirection with unexpanded `$VAR` references — then let curl read
them via `--netrc-file`.

The verification call used throughout:

    curl -s -o /dev/null -w "%{http_code}" \
      --netrc-file ~/.config/gw-triage/netrc \
      https://<host>/rest/api/2/myself

## Step 0 — Check existing configuration

1. If `~/.config/gw-triage/netrc` exists and is readable, run the
   verification call.
   - `200` → tell the user (Italian) the token already works and ask
     whether they want to replace it anyway. If not, stop.
   - `401`/`403` → tell them the stored token no longer works
     (probably expired or revoked) and continue to Step 1.
   - anything else (timeout, DNS) → network problem, not credentials:
     report it (Italian) and stop.
2. Otherwise look for legacy credentials, in order:
   - session env: `test -n "$JIRA_EMAIL" && test -n "$JIRA_API_TOKEN" && echo session || echo unset`
   - `~/.claude/settings.json` (if it exists): `env.JIRA_EMAIL` /
     `env.JIRA_API_TOKEN`.

   If found in either place: write them to the netrc (Step 2 format,
   chmod 600) and run the verification call.

   **Important — how to write the netrc depends on where the values
   came from:**
   - Values read from `~/.claude/settings.json` are literals you
     already hold: write the netrc with the file-writing tool as usual.
   - Session-env credentials must never be echoed or expanded by you:
     write the file via shell redirection with unexpanded references,
     e.g.

         printf 'machine <host>\nlogin %s\npassword %s\n' \
           "$JIRA_EMAIL" "$JIRA_API_TOKEN" > ~/.config/gw-triage/netrc
         chmod 600 ~/.config/gw-triage/netrc

   After writing, run the verification call.
   - `200` → tell the user (Italian) the existing credentials were
     migrated to the new store and work immediately; then do Step 3
     (clean up legacy stores) and Step 4. Done — skip token creation.
   - `401`/`403` → delete the netrc just written, tell them the old
     token no longer works, continue to Step 1.
   - anything else (timeout, DNS) → network problem, not credentials:
     report it (Italian) and stop, leaving the netrc in place — it may
     verify fine later.
3. Nothing found → first-time setup, continue to Step 1.

## Step 1 — Token creation (user, in the browser)

Print in Italian, compactly:

1. Apri <https://id.atlassian.com/manage-profile/security/api-tokens>
   (login con l'account Atlassian aziendale).
2. **Create API token** → nome `gw-triage` → scegli la scadenza →
   **copia subito il token** (viene mostrato una volta sola).
3. Incolla qui email aziendale e token (vanno bene anche su due righe).

Add one line: il token verrà salvato in chiaro in
`~/.config/gw-triage/netrc` sul suo computer, quindi non condividere né
il file né questa conversazione.

End the turn and wait. If the reply contains only one of the two
values, ask for the missing one. If the user can't create the token
(no permission, page unreachable), stop and suggest asking whoever
manages the Atlassian accounts.

## Step 2 — Save, then verify

1. Create `~/.config/gw-triage/` if missing. Write the netrc file with
   the file-writing tool:

       machine <host>
       login <email>
       password <token>

   Then `chmod 600 ~/.config/gw-triage/netrc`.
2. Run the verification call.
   - `200` → Step 3.
   - `401`/`403` → wrong email or token (a common cause: copied with a
     trailing space or truncated). Ask the user to re-copy and
     re-paste, rewrite the file, verify again; after the third failed
     verification overall, delete the netrc file, stop, and suggest
     creating a fresh token.
   - Anything else (timeout, DNS) → network problem, not credentials:
     report it and stop. Leave the netrc in place — it may verify fine
     later.

## Step 3 — Clean up legacy stores

1. `~/.claude/settings.json`: if it exists and has `env.JIRA_EMAIL` /
   `env.JIRA_API_TOKEN`, offer (Italian) to remove those two keys —
   with the file tools (Read + Edit), never shell text-mangling, and
   preserving every other key. If the file is invalid JSON, don't
   touch it; just tell the user it should be cleaned up by hand.
2. Shell profiles: run
   `fish -c 'set -U' 2>/dev/null | grep -i jira` and
   `grep -l JIRA_API_TOKEN ~/.config/fish/config.fish ~/.config/fish/conf.d/*.fish ~/.zshrc ~/.bashrc ~/.zprofile ~/.profile 2>/dev/null`.
   If anything turns up, tell the user (Italian) to remove it so it
   can't shadow the netrc (fish: `set -e JIRA_EMAIL; set -e
   JIRA_API_TOKEN`; altrimenti togliere gli `export` dal file
   indicato).

## Step 4 — Report

In Italian: token verificato e salvato in `~/.config/gw-triage/netrc`.
Vale da subito, anche nelle sessioni già aperte. Per sostituirlo o dopo
una revoca basta rilanciare il setup: `/gw-triage:setup` su Claude
Code, `$setup` su Codex.