@codyswann/lisa 2.21.1 → 2.23.0

package/plugins/lisa/skills/setup-atlassian/SKILL.md

@@ -0,0 +1,316 @@
+---
+name: setup-atlassian
+description: "Configure Atlassian access for this project. Installs acli if missing, runs the OAuth or API-token login, optionally enables the Atlassian MCP, resolves the cloudId for the active site, and writes the `atlassian` section into `.lisa.config.json`. Prerequisite for /lisa:setup:jira and /lisa:setup:confluence (both need atlassian.cloudId). Idempotent — re-running updates the existing section rather than duplicating it."
+allowed-tools: ["Bash", "Read", "Write", "Edit", "Skill", "AskUserQuestion"]
+---
+
+# Setup Atlassian: $ARGUMENTS
+
+Resolve and persist Atlassian access for this project. After this skill, `.lisa.config.json` contains `atlassian.cloudId` (required) and optionally `atlassian.site` / `atlassian.email` for multi-account disambiguation.
+
+## Workflow
+
+### Step 0 — Pick a setup path
+
+Ask via `AskUserQuestion`:
+
+> How do you want lisa to talk to Atlassian for this project?
+>
+> 1. **MCP-only (simplest)** — authenticate the Atlassian MCP once via browser OAuth; lisa uses it for every operation. Best for: single-Atlassian-account developers on a personal laptop. New developers onboard with one OAuth flow, no token management. Skip the rest of this setup.
+> 2. **acli (CLI) + MCP fallback** — install acli, authenticate per-profile, MCP picks up anything acli can't do. Best for: developers who work across multiple Atlassian accounts and need profile switching. Continue with acli install.
+> 3. **API-token path (headless / CI)** — store a per-user API token in the OS keychain; lisa uses curl for everything. Best for: CI pipelines, headless dev containers, or any case where browser OAuth is impossible. Continue through token-create steps.
+
+If the user picks (1) and the MCP is already authenticated to the right workspace (verify by calling `getAccessibleAtlassianResources` and checking `atlassian.cloudId` is in the result), write only `atlassian.cloudId` and `atlassian.site` into `.lisa.config.json` and skip to Step 6 (cloudId resolution). If the MCP isn't authed yet, instruct the user to run `mcp__plugin_atlassian_atlassian__authenticate` (or the claude.ai equivalent) and complete the OAuth flow in their browser, then re-verify.
+
+If the user picks (2) or (3), continue through the rest of the steps; acli and/or the API token become available alongside the MCP.
+
+### Step 1 — Ensure acli is installed (preferred substrate)
+
+```bash
+if ! command -v acli >/dev/null 2>&1; then
+  if command -v brew >/dev/null 2>&1; then
+    brew tap atlassian/homebrew-acli
+    brew install acli
+  else
+    cat >&2 <<'EOF'
+Error: Homebrew not found. Install acli manually:
+  https://developer.atlassian.com/cloud/acli/guides/install-macos/
+or skip acli and rely on the Atlassian MCP only (CI/remote envs need acli).
+EOF
+    # Continue — acli is preferred but MCP-only is acceptable.
+  fi
+fi
+```
+
+If acli install fails or is skipped, the project will operate in MCP mode. Surface this clearly to the user.
+
+### Step 2 — Authenticate
+
+If acli is installed: prefer `acli auth login --web` for interactive environments; for headless, instruct the user to obtain a Rovo MCP-scoped API token and pipe via:
+
+```bash
+echo "$ATLASSIAN_TOKEN" | acli jira auth login --site "<site>.atlassian.net" --email "<email>" --token
+```
+
+After login, verify with `acli auth status`.
+
+### Step 3 — Acquire an Atlassian API token (curl substrate)
+
+acli covers most JIRA operations but **no Confluence page writes** (only `space`-level commands, and `page view`). The classic-vs-granular OAuth scope mismatch (see `config-resolution` rule) also blocks acli's bearer token from working against the v2 Confluence REST API. So lisa needs a second substrate — **curl with Basic auth + API token** — for everything Confluence-write-related.
+
+**Per-product tokens**: Atlassian's scoped API token UI is per-product, so the easiest path is one Confluence-scoped token. JIRA operations remain on acli (no JIRA token needed). If a future lisa op turns out to need a JIRA-scoped token (e.g., reading transition metadata or remote links — neither is required by the current dispatch), make a second token then.
+
+**Security posture**: the token is stored in the OS keychain when available (macOS/Linux/Windows native backends) so it never lives in plaintext on disk and never flows through chat history. Env-var fallback exists for headless / CI / Linux-without-libsecret.
+
+#### 3a. Check for existing token via the lookup ladder
+
+Use the same ladder `atlassian-access` uses (env var → email-suffixed env var → keychain):
+
+```bash
+EMAIL=$(jq -r '.atlassian.email // empty' .lisa.config.local.json 2>/dev/null)
+SITE=$(jq -r '.atlassian.site // empty' .lisa.config.json)
+CLOUDID=$(jq -r '.atlassian.cloudId // empty' .lisa.config.json)
+
+read_token() {
+  local email="$1"
+  [ -n "$ATLASSIAN_API_TOKEN" ] && { echo "$ATLASSIAN_API_TOKEN"; return; }
+  local slug=$(echo "$email" | tr '[:upper:]@.' '[:lower:]__')
+  local varname="ATLASSIAN_API_TOKEN_${slug}"
+  [ -n "${!varname}" ] && { echo "${!varname}"; return; }
+  case "$(uname -s)" in
+    Darwin)  security find-generic-password -s lisa-atlassian -a "$email" -w 2>/dev/null ;;
+    Linux)   command -v secret-tool >/dev/null && secret-tool lookup service lisa-atlassian account "$email" 2>/dev/null ;;
+    MINGW*|MSYS*|CYGWIN*) cmdkey /list:"lisa-atlassian-${email}" 2>/dev/null | grep Password | awk '{print $NF}' ;;
+  esac
+}
+
+EXISTING=$(read_token "$EMAIL")
+if [ -n "$EXISTING" ]; then
+  # Validate against Confluence.
+  AUTH=$(printf '%s:%s' "$EMAIL" "$EXISTING" | base64)
+  CODE=$(curl -s -o /dev/null -w "%{http_code}" \
+    -H "Authorization: Basic $AUTH" \
+    "https://api.atlassian.com/ex/confluence/${CLOUDID}/wiki/rest/api/space?limit=1")
+  if [ "$CODE" = "200" ]; then
+    echo "Existing Atlassian API token validated. Skipping setup."
+    # proceed to Step 4
+  fi
+fi
+```
+
+If validation fails or no token is found, continue.
+
+#### 3b. Prompt the user to generate a token
+
+Open the token-creation page in their browser:
+
+```bash
+case "$(uname -s)" in
+  Darwin) open "https://id.atlassian.com/manage-profile/security/api-tokens" ;;
+  Linux)  xdg-open "https://id.atlassian.com/manage-profile/security/api-tokens" 2>/dev/null ;;
+  MINGW*|MSYS*|CYGWIN*) start "https://id.atlassian.com/manage-profile/security/api-tokens" ;;
+esac
+```
+
+Then print these instructions for the user:
+
+```
+1. Click "Create API token with scopes" (NOT the legacy unscoped form).
+2. Label it: lisa-confluence-<machine-name>   (anything; just for revocation traceability)
+3. App: Confluence
+4. Select EXACTLY these scopes:
+     Read:   read:page:confluence
+             read:hierarchical-content:confluence
+             read:comment:confluence
+             read:space:confluence
+     Write:  write:page:confluence
+             write:comment:confluence
+             write:label:confluence
+     Search: search:confluence
+5. Set an expiry (1 year max).
+6. Click "Create token" and copy the value.
+```
+
+#### 3c. Have the user store the token via OS keychain (token never enters chat)
+
+**Critical: don't use the interactive prompt form of `security` / `secret-tool` / `cmdkey`.** Atlassian scoped tokens end with `=<CRC>` (a checksum); terminal `getpass`-style prompts on macOS Terminal.app and iTerm have been observed to silently truncate the paste at the `=` sign, storing a 128-byte prefix instead of the full ~192-byte token. The result authenticates as 401 because the CRC fails. Symptom: the stored token validates against `printf` length checks (the prefix is well-formed) but every API call returns 401 with `x-failure-category: FAILURE_CLIENT_AUTH`.
+
+Always pipe from the clipboard instead. Print platform-specific commands that take `$(pbpaste)` / `$(xsel)` / `$(Get-Clipboard)` directly into the `-w` / store arg:
+
+```bash
+case "$(uname -s)" in
+  Darwin)
+    cat <<EOF
+1. Click "Copy" in the Atlassian token-create modal so the token is in your clipboard.
+2. Run this single line in your terminal — leading space keeps it out of zsh history:
+
+   security delete-generic-password -s lisa-atlassian -a "$EMAIL" 2>/dev/null;  TOK="\$(pbpaste)"; security add-generic-password -U -s lisa-atlassian -a "$EMAIL" -w "\$TOK"; unset TOK
+
+The token is piped from clipboard straight to keychain — no prompt, no truncation.
+EOF
+    ;;
+  Linux)
+    if command -v secret-tool >/dev/null 2>&1; then
+      # Pick whichever clipboard tool is available.
+      if   command -v wl-paste >/dev/null 2>&1; then CLIP=wl-paste
+      elif command -v xclip    >/dev/null 2>&1; then CLIP="xclip -selection clipboard -o"
+      elif command -v xsel     >/dev/null 2>&1; then CLIP="xsel --clipboard --output"
+      else CLIP="cat"  # caller will have to paste; fallback path below
+      fi
+      cat <<EOF
+1. Click "Copy" in the Atlassian token modal so the token is in your clipboard.
+2. Run this single line in your terminal:
+
+   secret-tool clear service lisa-atlassian account "$EMAIL" 2>/dev/null; printf '%s' "\$($CLIP)" | secret-tool store --label="Lisa Atlassian ($EMAIL)" service lisa-atlassian account "$EMAIL"
+
+(If no clipboard tool is installed, the command will read from stdin — paste your token, press Ctrl-D.)
+EOF
+    else
+      cat <<EOF
+libsecret / secret-tool is not installed. Options:
+
+  1. Install it (recommended on desktop Linux):
+       Debian/Ubuntu:  sudo apt install libsecret-tools
+       Fedora/RHEL:    sudo dnf install libsecret
+     Then re-run /lisa:setup:atlassian.
+
+  2. Fall back to env-var storage (headless / CI / Docker):
+       Add this line to your shell rc (.bashrc / .zshrc):
+         export ATLASSIAN_API_TOKEN_$(echo "$EMAIL" | tr '[:upper:]@.' '[:lower:]__')="<paste-token-here>"
+       Reload shell. Be aware: token will be in plaintext on disk.
+EOF
+    fi
+    ;;
+  MINGW*|MSYS*|CYGWIN*)
+    cat <<EOF
+1. Click "Copy" in the Atlassian token modal so the token is in your clipboard.
+2. Run this in PowerShell (cmdkey doesn't accept piped passwords; this uses Credential Manager via PowerShell):
+
+   \$tok = Get-Clipboard; cmdkey /generic:"lisa-atlassian-$EMAIL" /user:"$EMAIL" /pass:"\$tok"; Remove-Variable tok
+EOF
+    ;;
+  *)
+    cat <<EOF
+Unknown platform. Fall back to env-var:
+
+  export ATLASSIAN_API_TOKEN_$(echo "$EMAIL" | tr '[:upper:]@.' '[:lower:]__')="<token>"
+
+Add to your shell rc to persist.
+EOF
+    ;;
+esac
+```
+
+**Do NOT accept the token via chat or stdin into this skill.** The user runs the command themselves; the token enters only the OS keychain. The clipboard-pipe form is mandatory — never advise the interactive `-w` (no-arg) prompt form, which truncates scoped tokens at the `=` sign on multiple terminal/readline combos.
+
+Wait for the user to confirm they've stored it.
+
+#### 3d. Verify retrieval
+
+After the user confirms storage, retrieve via the same `read_token` ladder and validate. Use a **v2 endpoint** (not v1) since v1 returns 410 Gone — and v2 is what `atlassian-access` actually uses at runtime.
+
+```bash
+NEW=$(read_token "$EMAIL")
+if [ -z "$NEW" ]; then
+  echo "Error: token not retrievable from any source. Re-check the storage command and try again." >&2
+  exit 1
+fi
+
+# Length probe — Atlassian scoped tokens are ~192 chars (token body + '=' + CRC).
+# A stored value shorter than ~150 chars almost certainly means the terminal truncated
+# the paste at the '=' separator before the CRC.
+if [ ${#NEW} -lt 150 ]; then
+  echo "Error: token is ${#NEW} chars — too short. Scoped tokens are ~192 chars and end with '=<CRC>'." >&2
+  echo "Likely your terminal truncated the paste. Use the clipboard-pipe form in Step 3c." >&2
+  exit 1
+fi
+
+AUTH=$(printf '%s:%s' "$EMAIL" "$NEW" | base64)
+PROBE=$(curl -s -o /tmp/lisa-probe -w "%{http_code}" \
+  -H "Authorization: Basic $AUTH" \
+  "https://api.atlassian.com/ex/confluence/${CLOUDID}/wiki/api/v2/pages/$(jq -r '.confluence.parentPageId // empty' .lisa.config.json)")
+# If no parentPageId in config, fall back to a generic spaces list (also v2).
+if [ -z "$(jq -r '.confluence.parentPageId // empty' .lisa.config.json)" ]; then
+  PROBE=$(curl -s -o /tmp/lisa-probe -w "%{http_code}" \
+    -H "Authorization: Basic $AUTH" \
+    "https://api.atlassian.com/ex/confluence/${CLOUDID}/wiki/api/v2/spaces?limit=1")
+fi
+
+if [ "$PROBE" != "200" ]; then
+  echo "Error: token probe returned HTTP $PROBE." >&2
+  cat /tmp/lisa-probe >&2
+  echo "" >&2
+  echo "Likely causes: missing required scope (see Step 3b), or token was truncated during paste." >&2
+  exit 1
+fi
+rm -f /tmp/lisa-probe
+echo "Token validated (${#NEW} chars). Confluence v2 access ready."
+```
+
+#### 3e. CI / headless instructions
+
+For pipelines that can't use keychain: the token comes in via `ATLASSIAN_API_TOKEN` as a pipeline secret env var. No setup-skill changes needed; the lookup ladder already prefers env. Document this in the project's CI README rather than the skill.
+
+### Step 4 — Resolve cloudId
+
+If acli is installed and authenticated:
+
+```bash
+acli auth status --output json
+# Returns { "site": "...", "email": "...", ... } — but cloudId is not always returned by acli.
+```
+
+If the MCP is available, call `mcp__plugin_atlassian_atlassian__getAccessibleAtlassianResources` and pick the entry whose `url` matches the desired site. Its `id` is the cloudId.
+
+If the user has multiple sites under their account, use `AskUserQuestion` to disambiguate, presenting each site's URL + cloudId as an option.
+
+### Step 5 — Write config files (split by ownership)
+
+Shared fields → `.lisa.config.json` (committed). Developer-specific fields → `.lisa.config.local.json` (gitignored). This is non-negotiable: a developer's email pinned in the committed file would break every other developer on the project.
+
+**Shared fields (committed):**
+
+```bash
+touch .lisa.config.json
+[ -s .lisa.config.json ] || echo '{}' > .lisa.config.json
+jq --arg cloudid "$CLOUDID" \
+   --arg site "$SITE" \
+   '.atlassian = ((.atlassian // {}) | .cloudId = $cloudid | .site = $site)' \
+   .lisa.config.json > .lisa.config.json.tmp \
+   && mv .lisa.config.json.tmp .lisa.config.json
+```
+
+**Developer-specific fields (local override, gitignored):**
+
+```bash
+touch .lisa.config.local.json
+[ -s .lisa.config.local.json ] || echo '{}' > .lisa.config.local.json
+jq --arg email "$EMAIL" \
+   '.atlassian = ((.atlassian // {}) | .email = $email)' \
+   .lisa.config.local.json > .lisa.config.local.json.tmp \
+   && mv .lisa.config.local.json.tmp .lisa.config.local.json
+```
+
+Confirm `.lisa.config.local.json` is gitignored (it should already be — lisa's bootstrap template adds it). If not, surface the issue and add it. NEVER write `email` to the committed file under any circumstances; if a user explicitly insists, refuse and explain why.
+
+### Step 6 — Verify
+
+```bash
+jq -e '.atlassian.cloudId' .lisa.config.json >/dev/null
+acli auth status     # if acli installed
+```
+
+Report success with the resolved `cloudId` and `site`. Direct the user to `/lisa:setup:jira` and/or `/lisa:setup:confluence` next, depending on what they need.
+
+## Idempotency
+
+- Re-running this skill replaces the `atlassian` section's fields rather than appending. Use `jq` merge semantics (above) — never raw-append JSON.
+- If the section already exists and matches the resolved values, exit successfully without prompting.
+- If the section exists but mismatches (different site/cloudId), prompt via `AskUserQuestion` whether to overwrite or abort.
+
+## Rules
+
+- Never write secrets to `.lisa.config.json`. Tokens stay in env / acli's `~/.config/acli/` / the MCP's keychain entry.
+- Never edit `.claude/settings.json` by hand-concatenation — always use `jq` to preserve the JSON shape.
+- Never default `tracker` or `source` from this skill — that is the job of `setup-jira` / `setup-confluence`.
+- If the user has multiple Atlassian accounts available locally, ask explicitly which to pin to this project; do not silently pick one.

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

@@ -0,0 +1,245 @@
+---
+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.
+
+#### 3a. Decide where the parents live
+
+If `confluence.parentPageId` is set in config, the six 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]`, create a page named after the role (`Draft`, `Ready`, `In Review`, `Blocked`, `Ticketed`, `Shipped`). 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. 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.
+
+#### 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" '
+  .confluence = ((.confluence // {})
+    | .parents = {
+        draft:     $d,
+        ready:     $r,
+        in_review: $iv,
+        blocked:   $b,
+        ticketed:  $t,
+        shipped:   $s
+      })
+' .lisa.config.json > .lisa.config.json.tmp \
+   && mv .lisa.config.json.tmp .lisa.config.json
+```
+
+### 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 six `Content by Label` macros side-by-side — one per PRD lifecycle status (`draft`, `ready`, `in_review`, `blocked`, `ticketed`, `shipped`). 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)
+
+Five columns inside a `ac:layout` block. Each column is a `Content by Label` macro filtered to one label, 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)
+```
+
+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 six macros in two rows of three columns (`ac:layout-section ac:type="three_equal"`). Confluence's `ac:layout` has no native 6-column preset; two rows of three is the cleanest readable layout. Row 1: Draft, Ready, In Review. Row 2: Blocked, Ticketed, Shipped.
+
+The grouping is semantic too — top row covers the human-driven lead-up to agent pickup; bottom row covers agent-driven states post-pickup.
+
+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 six lifecycle
+   parents: <strong>Draft</strong>, <strong>Ready</strong>, <strong>In Review</strong>,
+   <strong>Blocked</strong>, <strong>Ticketed</strong>, <strong>Shipped</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
+```
+
+Report success with the resolved scope (`spaceKey`, `parentPageId`, or both), 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 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.