@codyswann/lisa 2.119.1 → 2.121.1

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

@@ -0,0 +1,254 @@
+---
+name: setup-confluence
+description: "Configure Confluence as the PRD source for this project. Writes `confluence.spaceKey` and/or `confluence.parentPageId` into `.lisa.config.json` and offers to set top-level `source: \"confluence\"`. Depends on /lisa:setup:atlassian — atlassian.cloudId must already be present. Idempotent."
+allowed-tools: ["Bash", "Read", "Write", "Edit", "Skill", "AskUserQuestion"]
+---
+
+# Setup Confluence: $ARGUMENTS
+
+Pin a Confluence space (or a parent page within one) as the PRD-discovery scope for this project.
+
+## 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 scope
+
+Two scoping modes (mutually compatible; both can be set):
+
+- **Space scope** — discover PRDs anywhere in a Confluence space. Honor `--space=KEY` or list spaces via the active substrate:
+  - CLI: `acli confluence space list --output json`
+  - MCP: `mcp__plugin_atlassian_atlassian__getConfluenceSpaces` with `cloudId=$cloudid`
+- **Parent-page scope** — discover PRDs only as descendants of one page. Honor `--parent=PAGE_ID` or ask the user via `AskUserQuestion` to provide it.
+
+If neither arg is supplied, ask which mode (or both). Setting only `parentPageId` is valid; setting only `spaceKey` is valid; setting both narrows the scope.
+
+### Step 3 — Create lifecycle parent pages
+
+Confluence PRD lifecycle is **parent-page-based**, not label-based (see the `config-resolution` rule for why — Atlassian's scoped API tokens cannot write labels). Each lifecycle role gets its own parent page; a PRD's state = which parent it's a child of. The full PRD lifecycle is `draft → ready → in_review → (blocked | ticketed) → shipped → verified` (the `prd-lifecycle-rollup` rule, slug `prd-lifecycle-rollup`): rollup performs the `ticketed → shipped` hop, then `/lisa:verify-prd` performs the terminal `shipped → verified` (pass) / `shipped → ticketed` (fail) hop. `verified` is the terminal lifecycle state after `shipped` (the `verified` role from the `config-resolution` rule, #591).
+
+#### 3a. Decide where the parents live
+
+If `confluence.parentPageId` is set in config, the seven parent pages are created as children of that page (keeps the lifecycle scoped to a sub-tree of the space). Otherwise, they're created at the space root.
+
+```bash
+SPACE_ID=$(curl -s -H "Authorization: Basic $AUTH" \
+  "${GW}/api/v2/spaces?keys=$(jq -r '.confluence.spaceKey' .lisa.config.json)" \
+  | jq -r '.results[0].id')
+PARENT_ROOT=$(jq -r '.confluence.parentPageId // empty' .lisa.config.json)
+```
+
+#### 3b. Create each parent page
+
+For each role in `[draft, ready, in_review, blocked, ticketed, shipped, verified]`, create a page named after the role (`Draft`, `Ready`, `In Review`, `Blocked`, `Ticketed`, `Shipped`, `Verified`). Body: a short description of what PRDs in this state mean.
+
+```bash
+create_parent() {
+  local role="$1" title="$2" body="$3"
+  local payload
+  payload=$(jq -n \
+    --arg sid "$SPACE_ID" \
+    --arg pid "$PARENT_ROOT" \
+    --arg t "$title" \
+    --arg b "$body" '
+    {
+      spaceId: $sid,
+      status: "current",
+      title: $t,
+      body: { representation: "storage", value: $b }
+    } + (if $pid != "" then { parentId: $pid } else {} end)
+  ')
+  curl -s -X POST -H "Authorization: Basic $AUTH" -H "Content-Type: application/json" \
+    -d "$payload" "${GW}/api/v2/pages" | jq -r '.id'
+}
+
+P_DRAFT=$(create_parent     draft     "Draft"     "PRDs being authored; not yet ready for the agent queue.")
+P_READY=$(create_parent     ready     "Ready"     "PRDs flagged by humans as ready for agent ticketing.")
+P_REVIEW=$(create_parent    in_review "In Review" "PRDs the agent has claimed and is validating.")
+P_BLOCKED=$(create_parent   blocked   "Blocked"   "Validation failed — clarifying comments posted by the agent. Edit the PRD, then move back to Ready.")
+P_TICKETED=$(create_parent  ticketed  "Ticketed"  "Validated and tickets created. Tracked through the build queue from here.")
+P_SHIPPED=$(create_parent   shipped   "Shipped"   "All child tickets shipped.")
+P_VERIFIED=$(create_parent  verified  "Verified"  "Shipped product empirically checked against the PRD. Terminal state.")
+```
+
+Handle the "title already exists" case (400 BAD_REQUEST) by searching for an existing page with that title first and re-using its id rather than failing. This find-or-reuse path is what makes the scaffolding **idempotent** — re-running `setup-confluence` reuses an existing `Verified` parent page rather than creating a duplicate.
+
+#### 3c. Write `confluence.parents` to config
+
+```bash
+jq --arg d "$P_DRAFT" --arg r "$P_READY" --arg iv "$P_REVIEW" \
+   --arg b "$P_BLOCKED" --arg t "$P_TICKETED" --arg s "$P_SHIPPED" \
+   --arg v "$P_VERIFIED" '
+  .confluence = ((.confluence // {})
+    | .parents = {
+        draft:     $d,
+        ready:     $r,
+        in_review: $iv,
+        blocked:   $b,
+        ticketed:  $t,
+        shipped:   $s,
+        verified:  $v
+      })
+' .lisa.config.json > .lisa.config.json.tmp \
+   && mv .lisa.config.json.tmp .lisa.config.json
+```
+
+This persists `confluence.parents.verified` to config, matching the `confluence.parents.verified` schema from the `config-resolution` rule, #591.
+
+### Step 4 — Write top-level `confluence` section (spaceKey / parentPageId)
+
+```bash
+jq --arg space "$SPACE_KEY" --arg parent "$PARENT_ID" '
+  .confluence = (
+    (.confluence // {})
+    | (if $space != ""  then .spaceKey     = $space  else . end)
+    | (if $parent != "" then .parentPageId = $parent else . end)
+  )
+' .lisa.config.json > .lisa.config.json.tmp \
+   && mv .lisa.config.json.tmp .lisa.config.json
+```
+
+This step is small now that the heavy lifting moved into 3c — but it's still where `spaceKey` and (optionally) `parentPageId` get persisted.
+
+### Step 5 — Offer to set top-level `source`
+
+If `.source` is unset or differs from `"confluence"`, ask via `AskUserQuestion`:
+
+> Confluence configured. Set top-level `source: "confluence"` so `/lisa:intake` (with no args) scans this space for PRDs?
+
+Recommend "Yes" if the team's PRDs live in Confluence. If the team uses Notion or Linear for PRDs and Confluence is only for ad-hoc reference, recommend "No".
+
+If yes:
+
+```bash
+jq '.source = "confluence"' .lisa.config.json > .lisa.config.json.tmp \
+   && mv .lisa.config.json.tmp .lisa.config.json
+```
+
+### Step 6 — Create / update PRD Dashboard page
+
+Confluence has no native swimlane / kanban view for label-driven lifecycles. To approximate the Notion-board experience, create a single "PRD Dashboard" page in the configured space that renders seven `Children Display` macros side-by-side — one per PRD lifecycle status (`draft`, `ready`, `in_review`, `blocked`, `ticketed`, `shipped`, `verified`). The dashboard is the team's single-screen view of the PRD pipeline.
+
+The `draft` column captures PRDs that have been created but not yet flipped to `ready` — useful for authors to track their own in-flight work and for editors to find PRDs that need a polish pass before they hit the agent queue.
+
+#### Idempotency
+
+If `confluence.dashboardPageId` already exists in `.lisa.config.json`, update that page rather than create a new one. Otherwise create.
+
+#### Build the page body (Confluence storage format)
+
+Seven columns inside a `ac:layout` block. Each column is a `Children Display` macro targeting one lifecycle parent, scoped to the configured space (or parent page, if set).
+
+Read the parent page IDs from config:
+
+```bash
+P_DRAFT=$(jq -r '.confluence.parents.draft' .lisa.config.json)
+P_READY=$(jq -r '.confluence.parents.ready' .lisa.config.json)
+P_REVIEW=$(jq -r '.confluence.parents.in_review' .lisa.config.json)
+P_BLOCKED=$(jq -r '.confluence.parents.blocked' .lisa.config.json)
+P_TICKETED=$(jq -r '.confluence.parents.ticketed' .lisa.config.json)
+P_SHIPPED=$(jq -r '.confluence.parents.shipped' .lisa.config.json)
+P_VERIFIED=$(jq -r '.confluence.parents.verified' .lisa.config.json)
+```
+
+Build a `Children Display` macro per parent. The macro shows direct children of the specified page, automatically updating as PRDs move between parents:
+
+```xml
+<ac:structured-macro ac:name="children" ac:schema-version="2">
+  <ac:parameter ac:name="page"><ac:link><ri:page ri:content-title="<TITLE>"/></ac:link></ac:parameter>
+  <ac:parameter ac:name="depth">1</ac:parameter>
+  <ac:parameter ac:name="sort">modified</ac:parameter>
+  <ac:parameter ac:name="reverse">true</ac:parameter>
+  <ac:parameter ac:name="all">false</ac:parameter>
+</ac:structured-macro>
+```
+
+Children Display targets a parent by **content-title** (not by id, in storage format). The `ri:content-title` attribute references the parent by its title within the current space.
+
+Wrap the seven macros in three rows of `ac:layout-section`. Confluence's `ac:layout` has no native 7-column preset, so lay out as three rows: two `three_equal` rows plus a final single-column row for the seventh tile. Row 1 (`three_equal`): Draft, Ready, In Review. Row 2 (`three_equal`): Blocked, Ticketed, Shipped. Row 3 (`single`): Verified.
+
+The grouping is semantic too — top row covers the human-driven lead-up to agent pickup; middle row covers agent-driven build states post-pickup; the final row is the terminal `verified` state where the shipped product has been empirically checked against the PRD itself (`/lisa:verify-prd`).
+
+Heading each column with the status name and count keeps the board scannable:
+
+```xml
+<ac:layout-cell>
+  <h2>Ready</h2>
+  <!-- Content by Label macro for prd-ready -->
+</ac:layout-cell>
+```
+
+Above the layout, include a short header describing what the page is and how to use it:
+
+```xml
+<p>This page is the PRD pipeline view. PRDs live as child pages of one of seven lifecycle
+   parents: <strong>Draft</strong>, <strong>Ready</strong>, <strong>In Review</strong>,
+   <strong>Blocked</strong>, <strong>Ticketed</strong>, <strong>Shipped</strong>,
+   <strong>Verified</strong>.
+   Move a PRD between states by re-parenting the page (drag in the page tree, or
+   via the page's location settings).</p>
+<p>To add a new PRD: create a page under <strong>Draft</strong>. When ready for
+   agent pickup, move it to <strong>Ready</strong>.</p>
+```
+
+#### Write the page
+
+Invoke `lisa:atlassian-access` with `operation: write-page`. The payload differs by mode:
+
+- **Create**: `{ "spaceKey": "$SPACE", "title": "PRD Dashboard", "body": "<the storage-format XML built above>", "parentId": "$PARENT" }` (omit `parentId` if not set).
+- **Update**: `{ "id": "<dashboardPageId>", "title": "PRD Dashboard", "body": "<...>" }` — body is fully replaced.
+
+`atlassian-access`'s `write-page` CLI adapter is currently nominal (acli's Confluence surface is `view`-only as of writing), so this call falls through to the MCP adapter. That's acceptable — the dashboard is a one-time setup-only write; the lifecycle hot path (label add/remove) doesn't go through this.
+
+#### Persist the page ID
+
+```bash
+jq --arg id "$DASHBOARD_PAGE_ID" --arg url "$DASHBOARD_URL" \
+   '.confluence = ((.confluence // {})
+                   | .dashboardPageId = $id
+                   | .dashboardUrl    = $url)' \
+   .lisa.config.json > .lisa.config.json.tmp \
+   && mv .lisa.config.json.tmp .lisa.config.json
+```
+
+Both fields are committed (shared across developers — same dashboard for everyone).
+
+#### Skip conditions
+
+Skip Step 6 entirely if:
+
+- `$ARGUMENTS` includes `--no-dashboard`.
+- The MCP fallback is unavailable AND acli can't create pages (i.e., we have no path to write).
+- The user declines via `AskUserQuestion` when offered.
+
+### Step 7 — Verify
+
+```bash
+jq -e '.confluence.spaceKey // .confluence.parentPageId' .lisa.config.json >/dev/null
+jq -e '.confluence.parents.verified' .lisa.config.json >/dev/null
+```
+
+Report success with the resolved scope (`spaceKey`, `parentPageId`, or both), the seven lifecycle parents created or reused (including the terminal `verified` parent), whether `source` was set, and the PRD Dashboard URL if Step 6 ran.
+
+## Idempotency
+
+- Re-running replaces fields cleanly (jq merge).
+- Re-running does not re-prompt for `source` if it's already `"confluence"`.
+- Re-running reuses an existing lifecycle parent page (by title) rather than duplicating it — so the terminal `Verified` parent is created once and reused on every subsequent run.
+- Re-running with an existing `dashboardPageId` updates the page in place rather than creating duplicates.
+
+## Rules
+
+- Never invent a `spaceKey` or `parentPageId`. Resolve via the substrate or have the user provide it explicitly.
+- Setting `source` is opt-in — per-skill invocations with an explicit URL always win, so `source` is just the no-arg default for batch flows.
+- If the user wants both Notion and Confluence as PRD sources (rare), pick one for `source` and document that the other requires explicit URLs.

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

@@ -0,0 +1,268 @@
+---
+name: setup-github
+description: "Configure GitHub Issues as the destination tracker and/or the PRD source for this project. Verifies the gh CLI is installed and authenticated, resolves `org/repo`, scaffolds the build-queue label namespace (`status:*`) when GitHub is the tracker and/or the PRD-lifecycle label namespace (`prd-*` + sentinel) when GitHub is the PRD source, writes the `github` section into `.lisa.config.json`, and offers to set top-level `tracker: \"github\"` and/or `source: \"github\"`. Idempotent — re-running updates the existing section and reuses existing labels rather than duplicating. No /lisa:setup:atlassian prerequisite (GitHub auth is standalone)."
+allowed-tools: ["Bash", "Read", "Write", "Edit", "Skill", "AskUserQuestion"]
+---
+
+# Setup GitHub: $ARGUMENTS
+
+Make GitHub Issues a tracker, a PRD source, or both for this project. After this skill, `.lisa.config.json` contains `github.org` + `github.repo`, the configured repo carries the lifecycle label namespaces lisa needs, and (optionally) `tracker` / `source` point at GitHub.
+
+Unlike `setup-jira` / `setup-confluence`, this skill has **no `setup-atlassian` dependency** — GitHub auth runs through the `gh` CLI directly.
+
+## Workflow
+
+### Step 0 — Decide what GitHub is for
+
+Ask via `AskUserQuestion` (multiSelect):
+
+> What should lisa use this GitHub repo for?
+>
+> 1. **Destination tracker** — lisa writes Epics / Stories / Sub-tasks here as Issues, and the build queue (`/lisa:intake`, `/lisa:implement`) runs off the `status:*` label namespace. Sets `tracker: "github"`.
+> 2. **PRD source** — humans drop PRDs here as Issues labeled `prd-ready`; `/lisa:intake` scans and ticketes them off the `prd-*` label namespace. Sets `source: "github"`.
+
+The answer drives which label namespaces get scaffolded in Step 3: **tracker → `status:*`**, **source → `prd-*` + sentinel**. Self-host (both) is supported — the two namespaces never overlap (see the `config-resolution` rule's "Self-host edge case").
+
+If the user selects neither, stop — there's nothing to configure.
+
+### Step 1 — Ensure the gh CLI is installed and authenticated
+
+```bash
+if ! command -v gh >/dev/null 2>&1; then
+  if command -v brew >/dev/null 2>&1; then
+    brew install gh
+  else
+    cat >&2 <<'EOF'
+Error: gh (GitHub CLI) not found and Homebrew unavailable. Install it:
+  https://github.com/cli/cli#installation
+Then re-run /lisa:setup:github.
+EOF
+    exit 1
+  fi
+fi
+
+# Auth: prefer an interactive login; CI/headless uses GH_TOKEN.
+if ! gh auth status >/dev/null 2>&1; then
+  if [ -n "$GH_TOKEN" ] || [ -n "$GITHUB_TOKEN" ]; then
+    echo "gh not logged in interactively, but GH_TOKEN/GITHUB_TOKEN is set — gh will use it."
+  else
+    cat >&2 <<'EOF'
+Error: gh is not authenticated. Run:
+  gh auth login           # interactive (developer machines)
+or set GH_TOKEN as a secret (CI / headless), then re-run /lisa:setup:github.
+EOF
+    exit 1
+  fi
+fi
+```
+
+Confirm the authenticated identity can write Issues and labels — `gh auth status` shows the token scopes; `repo` scope (or fine-grained Issues: read-write + metadata: read) is required to create labels and issues. If the scopes look read-only, surface it and instruct `gh auth refresh -s repo`.
+
+### Step 2 — Resolve `org/repo`
+
+Honor any `--repo=org/repo` argument. Otherwise default-detect from the current repo's `origin` remote, then confirm — the tracker/PRD repo is frequently a *different* repo than the code repo (e.g. a dedicated `product-prds` repo):
+
+```bash
+DEFAULT_REPO=$(gh repo view --json nameWithOwner -q .nameWithOwner 2>/dev/null)
+```
+
+Present the detected value via `AskUserQuestion`:
+
+> Use `<DEFAULT_REPO>` as the GitHub repo for lisa's issues/PRDs, or specify a different `org/repo`?
+
+Once resolved, split into `ORG` and `REPO` and confirm reachability + write access:
+
+```bash
+gh repo view "$ORG/$REPO" --json name,viewerPermission \
+  --jq 'if (.viewerPermission | IN("ADMIN","MAINTAIN","WRITE")) then "ok" else error("insufficient permission: \(.viewerPermission)") end'
+```
+
+If permission is `READ` / `TRIAGE`, stop — lisa cannot create labels or issues. Surface and exit.
+
+### Step 3 — Scaffold the lifecycle label namespaces
+
+Read role → label mappings with the same default-fallback ladder the intake skills use, so the labels created here exactly match what they look for. Only the namespaces selected in Step 0 are scaffolded.
+
+```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 ".github.labels.${ns}.${role} // empty" .lisa.config.local.json 2>/dev/null)
+  global_v=$(jq -r ".github.labels.${ns}.${role} // empty" .lisa.config.json 2>/dev/null)
+  echo "${local_v:-${global_v:-$default}}"
+}
+
+# Idempotent label creator: create if missing, leave untouched if present.
+ensure_label() {  # $1=name $2=hex-color $3=description
+  local name="$1" color="$2" desc="$3"
+  if gh label list --repo "$ORG/$REPO" --limit 200 --json name --jq '.[].name' | grep -qxF "$name"; then
+    echo "  = $name (exists)"
+  else
+    gh label create "$name" --repo "$ORG/$REPO" --color "$color" --description "$desc" \
+      && echo "  + $name (created)"
+  fi
+}
+```
+
+#### 3a. Build-queue labels (only if GitHub is the tracker)
+
+Defaults from `config-resolution`. The `done` role is **env-keyed** — create all three by default; a project whose terminal state is env-independent can later collapse `github.labels.build.done` to a single string.
+
+```bash
+ensure_label "$(read_role build ready    status:ready)"        FBCA04 "Ready for build (human signal)"
+ensure_label "$(read_role build claimed  status:in-progress)"  0E8A16 "Build in progress (agent owns)"
+ensure_label "$(read_role build blocked  status:blocked)"      D93F0B "Blocked — human attention required"
+ensure_label "$(read_role build done.dev        status:on-dev)" 1D76DB "Deployed to dev"
+ensure_label "$(read_role build done.staging    status:on-stg)" 1D76DB "Deployed to staging"
+ensure_label "$(read_role build done.production status:done)"   0E8A16 "Shipped to production"
+```
+
+#### 3b. PRD-lifecycle labels (only if GitHub is the PRD source)
+
+```bash
+ensure_label "$(read_role prd draft     prd-draft)"            C5DEF5 "PRD in progress (product owns)"
+ensure_label "$(read_role prd ready     prd-ready)"            FBCA04 "PRD ready for ticketing"
+ensure_label "$(read_role prd in_review prd-in-review)"        5319E7 "Claude is reviewing this PRD"
+ensure_label "$(read_role prd blocked   prd-blocked)"          D93F0B "PRD blocked — see comments"
+ensure_label "$(read_role prd ticketed  prd-ticketed)"         0E8A16 "Tickets created — see comments"
+ensure_label "$(read_role prd shipped   prd-shipped)"          1D76DB "Work delivered (product owns)"
+ensure_label "$(read_role prd verified  prd-verified)"         0E8A16 "Shipped product empirically verified against the PRD (product owns)"
+ensure_label "$(read_role prd sentinel  prd-intake-feedback)"  EDEDED "Marker for PRD-intake feedback issues"
+```
+
+#### 3c. Handle name collisions / renames
+
+If a project already uses a differently-named label for a role (e.g. `ready-for-dev` instead of `status:ready`), do NOT create a duplicate. Present the repo's existing labels via `AskUserQuestion` and let the user map the role to the existing label — that mapping becomes an override written in Step 4. Renaming-in-place (keeping lisa's defaults) is also fine if the user prefers; just surface the choice.
+
+### Step 4 — Write `.lisa.config.json`
+
+`github.org` / `github.repo` are project-wide → committed. Write **only label keys that differ from the documented defaults** — never echo the full default map into config (keeps it lean; missing keys inherit defaults at runtime).
+
+```bash
+touch .lisa.config.json
+[ -s .lisa.config.json ] || echo '{}' > .lisa.config.json
+
+jq --arg org "$ORG" --arg repo "$REPO" \
+   '.github = ((.github // {}) | .org = $org | .repo = $repo)' \
+   .lisa.config.json > .lisa.config.json.tmp && mv .lisa.config.json.tmp .lisa.config.json
+
+# Conditionally write label overrides (only roles the user mapped to non-default names).
+# $LABEL_OVERRIDES_JSON is e.g. {"build":{"ready":"ready-for-dev"}} — {} if all defaults.
+if [ -n "$LABEL_OVERRIDES_JSON" ] && [ "$LABEL_OVERRIDES_JSON" != "{}" ]; then
+  jq --argjson o "$LABEL_OVERRIDES_JSON" \
+     '.github.labels = ((.github.labels // {}) * $o)' \
+     .lisa.config.json > .lisa.config.json.tmp && mv .lisa.config.json.tmp .lisa.config.json
+fi
+```
+
+If this project later enables shared GitHub Project coordination, store it under the same `github` block as:
+
+```json
+"github": {
+  "org": "<tracked-repo-owner>",
+  "repo": "<tracked-repo>",
+  "projects": {
+    "v2": {
+      "owner": { "kind": "organization", "slug": "<tracked-repo-owner>" },
+      "number": 7,
+      "required": false
+    }
+  }
+}
+```
+
+That block is optional and coordination-only: real issues and pull requests stay the durable source of truth. In v1, `github.projects.v2.owner.slug` MUST match the tracked repository namespace (`github.org`) — user-owned repos use a user-owned Project, org-owned repos use an org-owned Project, and cross-namespace Project ownership is rejected. `required` defaults to `false`, meaning Project membership is best-effort unless a later setup/doctor flow explicitly opts into strict mode.
+
+When that block is present, later setup/doctor and runtime validation must read the shared Project's owner + access before membership writes depend on it. Best-effort mode (`required: false`) reports warning-level validation failures and continues repository-local writes without Project membership; strict mode (`required: true`) reports the same failures as blocking errors and stops the write.
+
+No secrets go in config — the GitHub token lives in `gh`'s own store (`~/.config/gh/`) or the `GH_TOKEN` env var, never in `.lisa.config.json`.
+
+### 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 set to GitHub).
+
+If **tracker** was selected and `.tracker` is unset or not `"github"`, ask via `AskUserQuestion`:
+
+> Repo `<org>/<repo>` configured. Set top-level `tracker: "github"` so all vendor-neutral skills write Issues here?
+
+If yes: `jq '.tracker = "github"' ...`
+
+If **source** was selected and `.source` is unset or not `"github"`, ask:
+
+> Set top-level `source: "github"` so `/lisa:intake` (with no args) scans this repo for `prd-ready` PRDs?
+
+If yes: `jq '.source = "github"' ...`
+
+Both are project-wide switches that change every downstream skill's default — never set either without explicit confirmation.
+
+### Step 6 — Verify
+
+```bash
+jq -e '.github.org and .github.repo' .lisa.config.json >/dev/null
+gh label list --repo "$ORG/$REPO" --limit 200 --json name --jq '.[].name' \
+  | grep -E 'status:|prd-' || true   # show the scaffolded namespaces
+```
+
+If `github.projects.v2` is configured, setup verification MUST also run the shared Project utility in
+read-only resolution mode before declaring success:
+
+```text
+operation: resolve-project
+```
+
+This is the setup/doctor chokepoint for GitHub Project coordination. Do not inline ad-hoc GraphQL
+here; delegate to `lisa:github-project-v2` so setup, doctor, writers, and linked-PR flows all read
+the same owner/access contract and surface the same exact failure text.
+
+Verification contract when `github.projects.v2` is present:
+
+- First enforce the v1 namespace rule locally: `github.projects.v2.owner.slug` MUST equal
+  `github.org`. If not, report the exact configuration failure and remediation:
+
+  ```yaml
+  code: project_namespace_mismatch
+  message: "github.projects.v2.owner.slug must match github.org in v1"
+  remediation: "Use a Project owned by <github.org> or remove github.projects.v2."
+  ```
+
+- Then resolve the configured Project owner + number through `lisa:github-project-v2`.
+- Preserve the exact GitHub / GraphQL failure text for inaccessible or unsupported Project
+  configurations. Examples: missing Project, `Resource not accessible by integration`, unsupported
+  owner kind, or any other Project read failure.
+- Report the exact remediation path. At minimum, say whether the operator must:
+  1. choose a Project owned by the tracked repo namespace,
+  2. grant the token Project read/write access,
+  3. correct the configured Project number/owner, or
+  4. remove `github.projects.v2` if coordination is not required.
+- Branch severity on `required` exactly the same way the shared utility does:
+  `required: false` => warning-level validation failure, continue repository-local setup success;
+  `required: true` => blocking verification failure, stop setup/doctor before claiming coordination
+  is usable.
+
+The verify output should make the operator's next step obvious. Good examples:
+
+```text
+WARNING github.projects.v2: Resource not accessible by integration
+Remediation: grant the token Project read/write access or remove github.projects.v2.required.
+Repository-local GitHub issue/PR flows remain usable; Project coordination is disabled.
+```
+
+```text
+ERROR github.projects.v2: github.projects.v2.owner.slug must match github.org in v1
+Remediation: use a Project owned by CodySwannGT or remove github.projects.v2.
+```
+
+Report success with the resolved `org/repo`, which label namespaces were scaffolded (and which labels already existed vs. were created), any non-default label overrides written, and whether `tracker` / `source` were set. Direct the user to `/lisa:intake` to test.
+
+## Idempotency
+
+- Re-running merges the `github` section's fields rather than appending — `jq` merge semantics throughout.
+- `ensure_label` is find-or-create: existing labels are left exactly as they are (color/description not overwritten), so a re-run never churns labels a human customized.
+- Re-running does not re-prompt for `tracker` / `source` if they already point at GitHub.
+
+## Rules
+
+- Never write the GitHub token to `.lisa.config.json`. It stays in `gh`'s store or `GH_TOKEN`.
+- Never create a duplicate label for a role that already has a (differently-named) label — map the role to the existing label and record it as a config override instead.
+- Never overload one label across both the PRD and build namespaces — a single issue is either a PRD or a build ticket, never both (see `config-resolution`).
+- Never set `tracker` / `source` without explicit user confirmation — they're project-wide and switch every downstream skill's behavior.
+- Never invent an `org/repo`. Default-detect from the remote and confirm; if detection fails, ask the user to supply it.