@codyswann/lisa 2.119.1 → 2.121.1

package/plugins/lisa-agy/skills/setup-jira/SKILL.md

@@ -0,0 +1,198 @@
+---
+name: setup-jira
+description: "Configure JIRA as the destination tracker for this project. Writes `jira.project` into `.lisa.config.json` and offers to set top-level `tracker: \"jira\"`. Depends on /lisa:setup:atlassian — atlassian.cloudId must already be present, otherwise this skill stops and instructs the user to run setup-atlassian first. Idempotent."
+allowed-tools: ["Bash", "Read", "Write", "Edit", "Skill", "AskUserQuestion"]
+---
+
+# Setup JIRA: $ARGUMENTS
+
+Set the JIRA project key and (optionally) make JIRA this project's destination tracker.
+
+## Workflow
+
+### Step 1 — Verify atlassian prerequisite
+
+```bash
+cloudid=$(jq -r '.atlassian.cloudId // empty' .lisa.config.json 2>/dev/null)
+if [ -z "$cloudid" ]; then
+  echo "Error: atlassian.cloudId not set. Run /lisa:setup:atlassian first." >&2
+  exit 1
+fi
+```
+
+If `atlassian` is missing, invoke `/lisa:setup-atlassian` via the Skill tool first, then resume.
+
+### Step 2 — Resolve the JIRA project key
+
+Honor any `--project=KEY` argument. Otherwise, list projects via the active access substrate:
+
+- CLI: `acli jira project list --output json`
+- MCP: `mcp__plugin_atlassian_atlassian__getVisibleJiraProjects` with `cloudId=$cloudid`
+
+If only one project is returned, pick it. If multiple, present them via `AskUserQuestion` (label = project key, description = project name) so the user picks the one this project should target.
+
+### Step 3 — Probe workflow & resolve role mapping
+
+Lisa's build lifecycle uses three role-keyed statuses (`ready` → `claimed` → `done[env]`). Defaults are `Ready`, `In Progress`, and `{dev: "On Dev", staging: "On Stg", production: "Done"}`. Probe the project's workflow to confirm these exist; prompt for overrides if not.
+
+```bash
+# Fetch a sample ticket's available transitions (or use a project-level workflow scheme query)
+# via lisa:atlassian-access operation: transitions key: <SAMPLE-KEY>
+# Collect the union of status names visible in the project.
+```
+
+For each role:
+
+1. If a status with the **default name** exists in the workflow → use the default; no config entry needed.
+2. If the default name is missing but a status with a similar role exists (e.g. `Resolved` instead of `Done`) → present the project's status list via `AskUserQuestion` and let the user pick which maps to the role.
+3. If nothing plausible exists → stop and tell the user to either add the missing status to their JIRA workflow (admin task) or pick a fallback that's close enough.
+
+Collect overrides as a partial workflow map. ONLY write keys that differ from defaults — don't bloat the config with redundant values.
+
+### Step 4 — Write `jira.project` + overrides
+
+```bash
+# Always write project key.
+jq --arg key "$PROJECT_KEY" \
+   '.jira = ((.jira // {}) | .project = $key)' \
+   .lisa.config.json > .lisa.config.json.tmp \
+   && mv .lisa.config.json.tmp .lisa.config.json
+
+# Conditionally write workflow overrides (only if any role differs from default).
+if [ -n "$WORKFLOW_OVERRIDES_JSON" ]; then
+  jq --argjson wf "$WORKFLOW_OVERRIDES_JSON" \
+     '.jira.workflow = $wf' \
+     .lisa.config.json > .lisa.config.json.tmp \
+     && mv .lisa.config.json.tmp .lisa.config.json
+fi
+```
+
+### Step 5 — Verify transition reachability (A → B → C cascade)
+
+Confirm every resolved role's status name is actually reachable in the JIRA workflow. **acli has no non-destructive workflow inspector** (the `workitem view --json` `transitions` key is always `null` because acli doesn't pass `expand=transitions`), so verification cascades through three modes, each more invasive than the last.
+
+#### Cache check (skip if unchanged)
+
+Hash the workflow-mapping object plus the project key:
+
+```bash
+WORKFLOW_HASH=$(jq -c '{project: .jira.project, workflow: .jira.workflow}' .lisa.config.json | shasum -a 256 | awk '{print $1}')
+CACHED=$(jq -r '.jira.verified_workflow_hash // empty' .lisa.config.local.json 2>/dev/null)
+if [ "$WORKFLOW_HASH" = "$CACHED" ]; then
+  echo "Workflow already verified; skipping probe."
+  # proceed to Step 6
+fi
+```
+
+The verification cache key lives in `.lisa.config.local.json` (per-developer, gitignored) because the workflow on disk might be stale relative to the user's local view of it.
+
+#### Mode A — Changelog inspection (non-destructive, fast)
+
+Aggregate every status name ever observed in the project's ticket histories:
+
+```bash
+acli jira workitem search --jql "project = $PROJECT" --paginate --json \
+  | jq -r '[.[].changelog.histories[]?.items[]? | select(.field == "status") | .fromString, .toString] | unique[]' \
+  | sort -u > /tmp/lisa-observed-statuses.txt
+```
+
+For each role (`ready`, `claimed`, `blocked`, each `done.<env>`), check whether the resolved status name appears in the observed set. Roles that match are **verified**. Roles that don't are **unverified** — but that doesn't yet mean they're missing; freshly-added statuses simply haven't accumulated history.
+
+If every role is verified, cache the hash and proceed to Step 6.
+
+#### Mode B — Create-probe-delete (synthetic ticket)
+
+For any role left unverified by Mode A, fall back to creating a throwaway ticket and walking it through.
+
+Prompt via `AskUserQuestion`:
+
+> Mode A could not verify these roles: `<list>`. Create a synthetic probe ticket to verify (recommended), or designate an existing ticket to use as the probe?
+
+If user picks synthetic:
+
+```bash
+# Create a probe ticket. Title makes its purpose obvious so a teammate doesn't act on it.
+PROBE_KEY=$(acli jira workitem create \
+  --project "$PROJECT" \
+  --type Task \
+  --summary "lisa-setup-probe (DELETE ME)" \
+  --description "Created by /lisa:setup:jira to verify workflow status reachability. Safe to delete." \
+  --json \
+  | jq -r '.key')
+
+trap 'acli jira workitem delete --key "$PROBE_KEY" --yes 2>/dev/null || acli jira workitem archive --key "$PROBE_KEY" --yes 2>/dev/null' EXIT
+
+# Walk through every unverified role's status in order.
+for status in $UNVERIFIED_STATUSES; do
+  if ! acli jira workitem transition --key "$PROBE_KEY" --status "$status" --yes 2>/dev/null; then
+    echo "Error: status '$status' is not reachable in the workflow from the probe ticket's current state." >&2
+    # Mark this role as missing; continue with remaining roles where possible (skip if transition is from a state we couldn't reach).
+    break
+  fi
+done
+
+# trap handles cleanup
+```
+
+If `acli jira workitem create` fails because the project has required fields, surface the field list and instruct the user to either (a) fill them in via `--field`/`--from-json`, (b) temporarily relax the required-fields configuration, or (c) fall through to Mode C.
+
+#### Mode C — Probe an existing ticket (last resort)
+
+If Mode B can't create a probe (mandatory fields, permission, etc.), prompt the user to designate a low-stakes existing ticket:
+
+> Provide a ticket key in `To Do` (or wherever you want to start the probe). I'll walk it through the unverified statuses and revert.
+
+Capture the ticket's starting status; walk through the unverified chain; revert to the starting status at the end. Use `trap` to ensure revert runs even on error.
+
+#### Outcome
+
+Once all roles are verified by some combination of A/B/C, cache the result:
+
+```bash
+jq --arg hash "$WORKFLOW_HASH" \
+   '.jira = ((.jira // {}) | .verified_workflow_hash = $hash)' \
+   .lisa.config.local.json > .lisa.config.local.json.tmp \
+   && mv .lisa.config.local.json.tmp .lisa.config.local.json
+```
+
+If any role is **unreachable** after all three modes, stop and surface a concrete admin-task message (which transition needs to be added, between which two statuses, in which workflow). Do not write a config that points at unreachable transitions.
+
+### Step 6 — Verify mid-build transition chain
+
+Independent of role reachability, confirm the lifecycle's required *transition graph* is intact: `ready → claimed`, `claimed → done.<env>` for each env. Mode A's changelog includes paired `(fromString, toString)` entries — count any pair that matches a required transition as verified. Modes B and C do this implicitly by walking the chain in order. If any required transition is missing (e.g., `claimed → done.staging` requires going through `review` first per the workflow), surface and stop with an admin remediation.
+
+### Step 7 — Offer to set top-level `tracker`
+
+If `.tracker` is unset or differs from `"jira"`, ask via `AskUserQuestion`:
+
+> JIRA project `<KEY>` written. Set top-level `tracker: "jira"` so all vendor-neutral skills target JIRA?
+
+Recommend "Yes" unless the project is using a different destination (e.g., GitHub Issues for build-queue but JIRA for read-only mirror — rare).
+
+If yes:
+
+```bash
+jq '.tracker = "jira"' .lisa.config.json > .lisa.config.json.tmp \
+   && mv .lisa.config.json.tmp .lisa.config.json
+```
+
+### Step 8 — Verify
+
+```bash
+jq -e '.jira.project' .lisa.config.json >/dev/null
+jq -e '.tracker' .lisa.config.json >/dev/null   # if user said yes in step 7
+```
+
+Report success with the resolved project key, the workflow mapping (defaults vs. overrides), and whether `tracker` was set.
+
+## Idempotency
+
+- Re-running replaces `jira.project` cleanly (jq merge, not append).
+- Re-running does not re-prompt for `tracker` if it's already `"jira"`.
+- Re-running with an unchanged workflow mapping skips the verification probe (Mode A/B/C) entirely via the `verified_workflow_hash` cache in `.lisa.config.local.json`. Editing any role name invalidates the cache and re-runs the probe.
+
+## Rules
+
+- Never invent a project key. If discovery fails (no projects visible), surface the error and ask the user to verify their JIRA permissions.
+- Never set `tracker` without explicit user confirmation — `tracker` is project-wide and switching it changes every downstream skill's behavior.
+- Never write env-level config (api tokens, server URLs) into `.lisa.config.json`.

package/plugins/lisa-agy/skills/setup-linear/SKILL.md

@@ -0,0 +1,251 @@
+---
+name: setup-linear
+description: "Configure Linear as the destination tracker and/or the PRD source for this project. Verifies Linear access (MCP OAuth or a personal API key in OS keychain), resolves the workspace slug and team key, scaffolds the build-queue issue-label namespace (`status:*`) when Linear is the tracker and/or the PRD-lifecycle project-label namespace (`prd-*` + issue-level sentinel) when Linear is the PRD source, writes the `linear` section into `.lisa.config.json`, and offers to set top-level `tracker: \"linear\"` and/or `source: \"linear\"`. Idempotent — re-running updates the existing section and reuses existing labels. No /lisa:setup:atlassian prerequisite."
+allowed-tools: ["Bash", "Read", "Write", "Edit", "Skill", "AskUserQuestion", "mcp__linear-server__authenticate", "mcp__linear-server__complete_authentication", "mcp__linear-server__list_teams", "mcp__linear-server__list_issue_labels", "mcp__linear-server__create_issue_label", "mcp__linear-server__list_project_labels", "mcp__linear-server__create_project_label"]
+---
+
+# Setup Linear: $ARGUMENTS
+
+Make Linear a tracker, a PRD source, or both for this project. After this skill, `.lisa.config.json` contains `linear.workspace` (+ `linear.teamKey` when Linear is the tracker), the team carries the lifecycle label namespaces lisa needs, and (optionally) `tracker` / `source` point at Linear.
+
+Linear's data model splits labels into two **kinds** that matter here: **issue labels** (drive the build queue, `status:*`) and **project labels** (drive the PRD lifecycle, `prd-*`). They are distinct namespaces in Linear and are NOT interchangeable — the build lifecycle lives on Issues, the PRD lifecycle lives on Projects. The sentinel feedback marker is an **issue** label even though it belongs to the PRD flow (Linear's MCP has no project-level comments — see `linear-prd-intake`).
+
+## Workflow
+
+### Step 0 — Pick a setup path AND what Linear is for
+
+Ask two things via `AskUserQuestion`.
+
+**Access path:**
+
+> How should lisa talk to Linear for this project?
+>
+> 1. **MCP-only (simplest)** — authenticate the Linear MCP once via browser OAuth; lisa uses it for every operation. Best for single-workspace developers on a personal laptop.
+> 2. **MCP + API key (recommended for teams)** — MCP for interactive dev, a personal API key in keychain for headless / CI. Continue through key-store steps.
+> 3. **API-key-only (headless / CI)** — store a personal API key in the OS keychain; lisa uses curl against the Linear GraphQL API. Best for pipelines / containers.
+
+**Role** (multiSelect):
+
+> What should lisa use Linear for?
+>
+> 1. **Destination tracker** — lisa writes Epics→Projects, Stories→Issues, Sub-tasks→Sub-issues; the build queue runs off the `status:*` issue-label namespace. Sets `tracker: "linear"`. (Requires a team key.)
+> 2. **PRD source** — humans flag Linear **projects** with `prd-ready`; `/lisa:intake` scans and ticketes them off the `prd-*` project-label namespace. Sets `source: "linear"`.
+
+The role answer drives Step 3 (which label namespaces to scaffold) and whether `teamKey` is required (tracker → yes).
+
+### Step 1 — Establish Linear access
+
+#### MCP path (1 or 2)
+
+Verify the Linear MCP is authenticated to the right workspace by listing teams:
+
+```text
+mcp__linear-server__list_teams({})
+```
+
+If it errors / returns nothing, run `mcp__linear-server__authenticate` and have the user complete OAuth in the browser, then `mcp__linear-server__complete_authentication`, then re-list. A non-empty team list confirms the MCP is authed to a readable workspace.
+
+#### API-key path (2 or 3)
+
+Linear personal API keys are created at **Linear → Settings → Security & access → Personal API keys** (or `https://linear.app/<workspace>/settings/account/security`). Store the key in the OS keychain keyed by the workspace slug, using the clipboard-pipe pattern (key never enters chat), mirroring `setup-notion`:
+
+```bash
+case "$(uname -s)" in
+  Darwin)
+    cat <<EOF
+1. Copy the Linear API key (starts with 'lin_api_').
+2. Run this single line (leading space keeps it out of zsh history):
+
+    security delete-generic-password -s lisa-linear -a "$WORKSPACE" 2>/dev/null;  TOK="\$(pbpaste)"; security add-generic-password -U -s lisa-linear -a "$WORKSPACE" -w "\$TOK"; unset TOK
+EOF
+    ;;
+  Linux)
+    cat <<EOF
+secret-tool clear service lisa-linear account "$WORKSPACE" 2>/dev/null; printf '%s' "\$(wl-paste 2>/dev/null || xclip -selection clipboard -o 2>/dev/null || xsel --clipboard --output 2>/dev/null)" | secret-tool store --label="Lisa Linear ($WORKSPACE)" service lisa-linear account "$WORKSPACE"
+(no clipboard tool? the command reads stdin — paste, then Ctrl-D. Or env-var fallback: export LINEAR_API_KEY_$(echo "$WORKSPACE" | tr '[:upper:]-' '[:lower:]_')="<key>")
+EOF
+    ;;
+  MINGW*|MSYS*|CYGWIN*)
+    cat <<EOF
+PowerShell: \$tok = Get-Clipboard; cmdkey /generic:"lisa-linear-$WORKSPACE" /user:"$WORKSPACE" /pass:"\$tok"; Remove-Variable tok
+EOF
+    ;;
+esac
+```
+
+**Never accept the key via this skill's chat or stdin.** After the user confirms storage, retrieve via the lookup ladder (env → workspace-suffixed env → keychain) and validate against the GraphQL API:
+
+```bash
+read_linear_key() {  # $1=workspace slug
+  local ws="$1"
+  [ -n "$LINEAR_API_KEY" ] && { echo "$LINEAR_API_KEY"; return; }
+  local slug; slug=$(echo "$ws" | tr '[:upper:]-' '[:lower:]_')
+  local varname="LINEAR_API_KEY_${slug}"
+  [ -n "${!varname}" ] && { echo "${!varname}"; return; }
+  case "$(uname -s)" in
+    Darwin)  security find-generic-password -s lisa-linear -a "$ws" -w 2>/dev/null ;;
+    Linux)   command -v secret-tool >/dev/null && secret-tool lookup service lisa-linear account "$ws" 2>/dev/null ;;
+    MINGW*|MSYS*|CYGWIN*)
+      # `cmdkey /generic ... /pass:` stores the secret in Windows Credential Manager, but
+      # `cmdkey /list` never prints stored passwords (by design). Read the CredentialBlob
+      # back via the Win32 CredRead API through PowerShell; pass the target name via an env
+      # var to dodge nested quoting, and strip the CRLF powershell.exe appends.
+      LISA_CRED_TARGET="lisa-linear-${ws}" powershell.exe -NoProfile -NonInteractive -Command '
+Add-Type -TypeDefinition @"
+using System;
+using System.Runtime.InteropServices;
+public static class LisaCred {
+  [StructLayout(LayoutKind.Sequential)]
+  private struct CREDENTIAL {
+    public int Flags; public int Type; public IntPtr TargetName; public IntPtr Comment;
+    public System.Runtime.InteropServices.ComTypes.FILETIME LastWritten;
+    public int CredentialBlobSize; public IntPtr CredentialBlob; public int Persist;
+    public int AttributeCount; public IntPtr Attributes; public IntPtr TargetAlias; public IntPtr UserName;
+  }
+  [DllImport("advapi32.dll", CharSet=CharSet.Unicode, SetLastError=true)]
+  private static extern bool CredRead(string target, int type, int flags, out IntPtr credential);
+  [DllImport("advapi32.dll")] private static extern void CredFree(IntPtr cred);
+  public static string Read(string target) {
+    IntPtr p;
+    if (!CredRead(target, 1, 0, out p)) { return null; }
+    try {
+      CREDENTIAL c = (CREDENTIAL)Marshal.PtrToStructure(p, typeof(CREDENTIAL));
+      if (c.CredentialBlobSize == 0) { return String.Empty; }
+      return Marshal.PtrToStringUni(c.CredentialBlob, c.CredentialBlobSize / 2);
+    } finally { CredFree(p); }
+  }
+}
+"@
+[LisaCred]::Read($env:LISA_CRED_TARGET)' 2>/dev/null | tr -d '\r' ;;
+  esac
+}
+
+KEY=$(read_linear_key "$WORKSPACE")
+[ -z "$KEY" ] && { echo "Error: key not retrievable from any source. Re-run the store step." >&2; exit 1; }
+
+# Validate: viewer query. Personal API keys go in the Authorization header verbatim (no 'Bearer').
+VIEWER=$(curl -s -X POST https://api.linear.app/graphql \
+  -H "Authorization: $KEY" -H "Content-Type: application/json" \
+  -d '{"query":"{ viewer { id name } organization { urlKey name } }"}')
+if ! echo "$VIEWER" | jq -e '.data.viewer.id' >/dev/null 2>&1; then
+  echo "Error: API key failed the Linear viewer probe. Response: $VIEWER" >&2
+  exit 1
+fi
+echo "Linear key validated. Org: $(echo "$VIEWER" | jq -r '.data.organization.urlKey')"
+```
+
+### Step 2 — Resolve workspace slug + team key
+
+- **Workspace slug**: honor `--workspace=<slug>`. Otherwise derive from the validated identity — the GraphQL `organization.urlKey` (API path) or the team list's workspace (MCP path). Confirm with the user; this slug is the keychain `account` key and the multi-workspace disambiguator.
+- **Team key** (required when Linear is the **tracker**): honor `--team=<KEY>`. Otherwise enumerate teams via `mcp__linear-server__list_teams({})` (or the GraphQL `teams` query) and present them via `AskUserQuestion` (label = team key, description = team name) for the user to pick the team that owns lisa's destination Issues. If Linear is source-only, `teamKey` is optional — skip unless the user wants to pin a team scope.
+
+### Step 3 — Scaffold the lifecycle label namespaces
+
+Read role → label with the default-fallback ladder the intake skills use, so scaffolded labels match exactly what they query.
+
+```bash
+read_role() {  # $1=namespace (build|prd) $2=role $3=default
+  local ns="$1" role="$2" default="$3" local_v global_v
+  local_v=$(jq -r ".linear.labels.${ns}.${role} // empty" .lisa.config.local.json 2>/dev/null)
+  global_v=$(jq -r ".linear.labels.${ns}.${role} // empty" .lisa.config.json 2>/dev/null)
+  echo "${local_v:-${global_v:-$default}}"
+}
+```
+
+#### 3a. Build-queue labels — ISSUE labels (only if Linear is the tracker)
+
+Probe with `mcp__linear-server__list_issue_labels` (scoped to the team). For each role's resolved name, create it via `mcp__linear-server__create_issue_label` only if absent. The `done` role is env-keyed — create all three defaults; collapse to a single string in config later if the project's terminal state is env-independent.
+
+| Role | Default | 
+|------|---------|
+| `ready` | `status:ready` |
+| `claimed` | `status:in-progress` |
+| `review` | `status:code-review` |
+| `blocked` | `status:blocked` |
+| `done.dev` | `status:on-dev` |
+| `done.staging` | `status:on-stg` |
+| `done.production` | `status:done` |
+
+#### 3b. PRD-lifecycle labels — PROJECT labels (only if Linear is the PRD source)
+
+Probe with `mcp__linear-server__list_project_labels`. Create missing ones via `mcp__linear-server__create_project_label`. This probe-then-create is find-or-create per label: a label already present is reused untouched, so re-running never duplicates `prd-*`. These are a **separate label kind** from issue labels — creating an issue label of the same name will NOT work for the PRD flow.
+
+`prd-verified` is the terminal lifecycle state after `prd-shipped` (the `verified` role from config-resolution, #591): `/lisa:verify-prd` transitions a Linear PRD project into it once the shipped product has been empirically verified against the PRD. Scaffold it through the same find-or-create path as every other `prd-*` row.
+
+| Role | Default | Kind |
+|------|---------|------|
+| `draft` | `prd-draft` | project label |
+| `ready` | `prd-ready` | project label |
+| `in_review` | `prd-in-review` | project label |
+| `blocked` | `prd-blocked` | project label |
+| `ticketed` | `prd-ticketed` | project label |
+| `shipped` | `prd-shipped` | project label |
+| `verified` | `prd-verified` | project label |
+| `sentinel` | `prd-intake-feedback` | **issue** label (marks the sentinel feedback issue — create via `create_issue_label`) |
+
+#### 3c. Handle name collisions / renames
+
+If the team already uses a differently-named label for a role, do not create a duplicate — present the existing labels via `AskUserQuestion`, map the role to the existing label, and record the mapping as a config override (Step 4).
+
+### Step 4 — Write `.lisa.config.json`
+
+`linear.workspace` (and `linear.teamKey` when tracker) are project-wide → committed. Write **only label keys that differ from defaults**.
+
+```bash
+touch .lisa.config.json
+[ -s .lisa.config.json ] || echo '{}' > .lisa.config.json
+
+jq --arg ws "$WORKSPACE" \
+   '.linear = ((.linear // {}) | .workspace = $ws)' \
+   .lisa.config.json > .lisa.config.json.tmp && mv .lisa.config.json.tmp .lisa.config.json
+
+# teamKey only when Linear is the tracker (or the user pinned a team scope).
+if [ -n "$TEAM_KEY" ]; then
+  jq --arg tk "$TEAM_KEY" '.linear.teamKey = $tk' \
+     .lisa.config.json > .lisa.config.json.tmp && mv .lisa.config.json.tmp .lisa.config.json
+fi
+
+# Conditionally write label overrides (only non-default role names).
+if [ -n "$LABEL_OVERRIDES_JSON" ] && [ "$LABEL_OVERRIDES_JSON" != "{}" ]; then
+  jq --argjson o "$LABEL_OVERRIDES_JSON" \
+     '.linear.labels = ((.linear.labels // {}) * $o)' \
+     .lisa.config.json > .lisa.config.json.tmp && mv .lisa.config.json.tmp .lisa.config.json
+fi
+```
+
+No secrets in config — the API key stays in keychain / `LINEAR_API_KEY`, the MCP session in its own store.
+
+### Step 5 — Offer to set top-level `tracker` / `source`
+
+For each role selected in Step 0, offer the matching top-level flag (skip if already pointing at Linear).
+
+If **tracker** selected and `.tracker` ≠ `"linear"`: ask "Set top-level `tracker: \"linear\"` so vendor-neutral skills write Issues here?" → `jq '.tracker = "linear"'`.
+
+If **source** selected and `.source` ≠ `"linear"`: ask "Set top-level `source: \"linear\"` so `/lisa:intake` (no args) scans this workspace for `prd-ready` projects?" → `jq '.source = "linear"'`.
+
+Both are project-wide — never set without explicit confirmation.
+
+### Step 6 — Verify
+
+```bash
+jq -e '.linear.workspace' .lisa.config.json >/dev/null
+# If tracker: also require teamKey.
+[ "$(jq -r '.tracker // empty' .lisa.config.json)" = "linear" ] && jq -e '.linear.teamKey' .lisa.config.json >/dev/null
+```
+
+Confirm the scaffolded labels are present (`list_issue_labels` for `status:*` + the sentinel; `list_project_labels` for `prd-*`, including the terminal `prd-verified`). Report success with the resolved workspace, team key (if any), which namespaces were scaffolded (created vs. already existed), any non-default overrides, and whether `tracker` / `source` were set. Direct the user to `/lisa:intake` to test.
+
+## Idempotency
+
+- Re-running merges the `linear` section's fields rather than appending — `jq` merge throughout.
+- Label creation is find-or-create per kind; existing labels are left untouched, so re-runs never churn human-customized labels.
+- Re-running does not re-prompt for `tracker` / `source` if they already point at Linear. The keychain store in Step 1 is the user's manual action — they re-run the same `security` / `secret-tool` / `cmdkey` command.
+
+## Rules
+
+- Never write the API key to `.lisa.config.json`. It stays in keychain or `LINEAR_API_KEY`.
+- Never accept the API key via this skill's stdin/chat — always the platform clipboard-pipe pattern, so the value never enters the LLM context.
+- Never conflate the two label kinds: build labels are **issue** labels, PRD labels are **project** labels. The sentinel is an issue label. Creating the wrong kind silently breaks the corresponding intake flow.
+- Never create a duplicate label for a role that already has a (differently-named) label — map and record an override instead.
+- Never set `tracker` / `source` without explicit confirmation — they're project-wide switches.
+- Never invent a workspace slug or team key. Derive from the validated identity / team list and confirm; if resolution fails, ask the user.