@codyswann/lisa 2.21.1 → 2.23.1

package/plugins/lisa/skills/confluence-prd-intake/SKILL.md

@@ -1,101 +1,176 @@
 ---
 name: confluence-prd-intake
-description: "Scans a Confluence space (or a parent page) for PRD pages labelled `prd-ready` and runs each one through the dry-run validation pipeline. PRDs that pass every gate get tickets written and the label flipped to `prd-ticketed`; PRDs that fail get clarifying-question comments and the label flipped to `prd-blocked`. Confluence counterpart of `lisa:notion-prd-intake` — the workflow is identical; only the source-of-truth tools differ. Composes existing skills (confluence-to-tracker, tracker-validate, tracker-source-artifacts, product-walkthrough)."
-allowed-tools: ["Skill", "Bash", "mcp__atlassian__getConfluencePage", "mcp__atlassian__getConfluenceSpaces", "mcp__atlassian__getPagesInConfluenceSpace", "mcp__atlassian__getConfluencePageDescendants", "mcp__atlassian__searchConfluenceUsingCql", "mcp__atlassian__updateConfluencePage", "mcp__atlassian__createConfluenceFooterComment", "mcp__atlassian__createConfluenceInlineComment", "mcp__atlassian__getConfluencePageFooterComments", "mcp__atlassian__getConfluencePageInlineComments", "mcp__atlassian__getAccessibleAtlassianResources"]
+description: "Scans a Confluence space (or a parent page) for PRD pages currently parented under the configured `ready` lifecycle page and runs each one through the dry-run validation pipeline. PRDs that pass every gate get tickets written and are re-parented under the `ticketed` lifecycle page; PRDs that fail get clarifying-question comments and are re-parented under the `blocked` lifecycle page. Confluence counterpart of `lisa:notion-prd-intake` — the workflow is identical; only the source-of-truth tools and the state encoding differ (parent-page re-parenting instead of a status property). Composes existing skills (confluence-to-tracker, tracker-validate, tracker-source-artifacts, product-walkthrough)."
+allowed-tools: ["Skill", "Bash"]
 ---
 
 # Confluence PRD Intake: $ARGUMENTS
 
+All Atlassian operations in this skill go through `lisa:atlassian-access`. Do not call MCP tools or `acli` directly.
+
 `$ARGUMENTS` is one of:
 
-- A Confluence **space** URL or space key — scans every page in the space whose labels include `prd-ready`. Example: `https://mycompany.atlassian.net/wiki/spaces/PRD` or `PRD`.
-- A Confluence **parent page** URL or page ID — scans every descendant of the parent whose labels include `prd-ready`. Example: `https://mycompany.atlassian.net/wiki/spaces/PRD/pages/123456789/PRDs`.
+- A Confluence **space** URL or space key — used as the surrounding scope sanity check. Example: `https://mycompany.atlassian.net/wiki/spaces/PRD` or `PRD`.
+- A Confluence **parent page** URL or page ID — overrides the configured `confluence.parents.ready` page for this run (useful when an operator wants to drain an alternative lifecycle parent). Example: `https://mycompany.atlassian.net/wiki/spaces/PRD/pages/123456789/PRDs`.
+- Empty — use `confluence.parents.ready` from `.lisa.config.json` as the scope.
+
+Run one intake cycle against the resolved `ready` lifecycle parent. Each direct child of that parent is treated as a PRD currently in the `ready` state. Each PRD is claimed (re-parented to `in_review`), validated, and routed to either the `blocked` parent (with clarifying comments) or the `ticketed` parent (with destination tickets created).
+
+## Why parent pages, not labels
+
+GitHub and Linear PRD lifecycles use labels (`prd-ready` / `prd-in-review` / etc.). Confluence does NOT — it uses parent pages instead. Scoped Atlassian API tokens (the only secure form Atlassian offers) cannot write Confluence labels via the v1 endpoint, and the v2 Label API group has no POST endpoint at all. Parent-id transitions, by contrast, are first-class in v2 and work with `write:page:confluence` scope. See `config-resolution` rule, section "Confluence PRD lifecycle uses parent pages, not labels," for the full rationale.
+
+## Workflow resolution
+
+Lifecycle parent-page IDs are read from `.lisa.config.json` `confluence.parents.*`. Local overrides global per-key. Bash pattern:
+
+```bash
+# Read a lifecycle parent-page id by role. Local overrides global per-key.
+read_parent_id() {
+  local role="$1"
+  local local_v global_v
+  local_v=$(jq -r ".confluence.parents.${role} // empty" .lisa.config.local.json 2>/dev/null)
+  global_v=$(jq -r ".confluence.parents.${role} // empty" .lisa.config.json 2>/dev/null)
+  echo "${local_v:-$global_v}"
+}
+
+READY_PARENT=$(read_parent_id ready)
+IN_REVIEW_PARENT=$(read_parent_id in_review)
+BLOCKED_PARENT=$(read_parent_id blocked)
+TICKETED_PARENT=$(read_parent_id ticketed)
+SHIPPED_PARENT=$(read_parent_id shipped)
+DRAFT_PARENT=$(read_parent_id draft)
+
+# Fail fast if any required role is unmapped — the lifecycle scaffolding hasn't been provisioned.
+for role in ready in_review blocked ticketed; do
+  if [ -z "$(read_parent_id "$role")" ]; then
+    echo "Error: confluence.parents.${role} is not set in .lisa.config.json. Run /lisa:setup:confluence to provision the lifecycle parent pages." >&2
+    exit 1
+  fi
+done
+
+# Reverse-lookup: given a page's parentId, return which lifecycle role it currently occupies.
+current_role_for_prd() {
+  local parent_id="$1"
+  for role in draft ready in_review blocked ticketed shipped; do
+    if [ "$(read_parent_id "$role")" = "$parent_id" ]; then
+      echo "$role"; return
+    fi
+  done
+  echo "unknown"
+}
+```
 
-Run one intake cycle against that scope. Each PRD with the `prd-ready` label is claimed, validated, and routed to either `prd-blocked` (with clarifying comments) or `prd-ticketed` (with JIRA tickets created).
+In prose below, the role names refer to the resolved parent-page IDs: e.g. "the `ready` parent" means whatever `confluence.parents.ready` resolves to.
 
-This skill is the Confluence counterpart of `lisa:notion-prd-intake`. The phases, gates, comment templates, and rules are identical — the only differences are (1) the lifecycle is encoded as **page labels** instead of a Status property, and (2) the fetch / comment / update tools are Confluence MCP instead of Notion MCP. Keep the two skills behaviorally aligned: when changing intake logic, change BOTH skills together.
+This skill is the Confluence counterpart of `lisa:notion-prd-intake`. The phases, gates, comment templates, and rules are identical — the only differences are (1) the lifecycle is encoded as **parent-page placement** instead of a status property, and (2) the fetch / comment / update tools route through `lisa:atlassian-access`. Keep the two skills behaviorally aligned: when changing intake logic, change BOTH skills together.
 
 ## Confirmation policy
 
-Do NOT ask the caller whether to proceed. Once invoked with a space or parent-page URL, run the cycle to completion — claim, validate, branch to `prd-blocked` or `prd-ticketed`, write the summary. The caller (a human or a cron) has already authorized the run by invoking the skill; re-prompting defeats the purpose of a background batch.
+Do NOT ask the caller whether to proceed. Once invoked, run the cycle to completion — claim, validate, branch to the `blocked` or `ticketed` parent, write the summary. The caller (a human or a cron) has already authorized the run by invoking the skill; re-prompting defeats the purpose of a background batch.
 
 Specifically forbidden:
 
 - Previewing projected scope (epic count, story count, write count) and asking whether to continue.
 - Offering A/B/C-style choices like "proceed / skip / dry-run only" — the documented behavior IS the default.
-- Pausing because a PRD looks large, has many open questions, or is likely to end in `prd-blocked`. `prd-blocked` is a valid terminal state of this lifecycle, not a failure mode — routing a PRD to `prd-blocked` with gate-failure comments is exactly how this skill communicates "the PRD needs more work before it can be ticketed." That outcome is success.
+- Pausing because a PRD looks large, has many open questions, or is likely to end under the `blocked` parent. The `blocked` parent is a valid terminal state of this lifecycle, not a failure mode — routing a PRD there with gate-failure comments is exactly how this skill communicates "the PRD needs more work before it can be ticketed." That outcome is success.
 - Pausing because the dry-run validation looks expensive. The cost of one cycle is bounded; the cost of stalling a scheduled cron waiting on a human is unbounded.
 
 The only legitimate reasons to stop early:
 
-- Missing space/parent argument or required configuration (`atlassian.cloudId` in `.lisa.config.json`, `E2E_BASE_URL`, etc.). Surface the missing value and exit.
-- Space/parent unreachable, or the labelling convention not yet adopted (no PRDs carry any of `prd-ready` / `prd-in-review` / `prd-blocked` / `prd-ticketed`). Surface and exit.
-- Empty `prd-ready` set. Exit cleanly with `"No PRDs labelled prd-ready. Nothing to do."`
+- Missing required configuration (`atlassian.cloudId`, `confluence.parents.{ready,in_review,blocked,ticketed}` in `.lisa.config.json`, `E2E_BASE_URL`, etc.). Surface the missing value and exit.
+- Lifecycle parent unreachable. Surface and exit.
+- Empty ready set. Exit cleanly with `"No PRDs currently parented under the 'ready' lifecycle page. Nothing to do."`
 
 ## Lifecycle assumed
 
-The Confluence PRD lifecycle is encoded as **page labels** (Confluence has no native status field). Exactly one of these labels is expected on a PRD page at any time:
+The Confluence PRD lifecycle is encoded as **parent-page placement** — Confluence has no native status field, and scoped API tokens cannot write labels. Each lifecycle role corresponds to a dedicated parent page in the project's Confluence space:
 
 ```text
-prd-draft → prd-ready → prd-in-review → prd-blocked | prd-ticketed → prd-shipped
-            (product)    (us)            (us)                          (product)
+draft → ready → in_review → blocked | ticketed → shipped
+        (product)  (us)      (us)                  (product)
 ```
 
+A PRD's current state is determined entirely by which lifecycle parent it sits under. Re-parenting is the transition.
+
 This skill ONLY transitions:
 
-- `prd-ready` → `prd-in-review` (claim)
-- `prd-in-review` → `prd-blocked` (gate failures or coverage gaps)
-- `prd-in-review` → `prd-ticketed` (success)
+- `ready` → `in_review` (claim)
+- `in_review` → `blocked` (gate failures or coverage gaps)
+- `in_review` → `ticketed` (success)
 
-It never adds, removes, or touches `prd-draft` or `prd-shipped`. Those labels are owned by product.
+It never re-parents PRDs into or out of the `draft` or `shipped` parents. Those parents are owned by product.
 
-A "transition" means: remove the old lifecycle label and add the new one in a single `updateConfluencePage` call. The skill MUST verify that exactly one lifecycle label exists on the page after the update — having two simultaneously breaks idempotency.
+A "transition" means: update the PRD's `parentId` to the new role's parent-page id via `lisa:atlassian-access` `operation: write-page payload: { id, parentId, title, version: { number: <next> } }`. The v2 PUT endpoint requires the next version number and the page title in the payload; the body content is not strictly required for a re-parent-only edit, but some Atlassian deployments reject PUTs without a body. The skill MUST therefore GET the page first via `read-page`, capture title + current version + current body, then PUT with `parentId` swapped and `version.number` bumped — preserving body content is non-negotiable, this skill never edits PRD content. See `transition_prd` helper in Phase 3a for the canonical implementation.
 
-If the project does not yet use `prd-*` labels, this skill cannot run. Adopting the convention is a one-time setup the project owner does (see "Adoption" at the bottom of this file).
+If the project does not yet have the lifecycle parent pages provisioned, this skill cannot run. Provisioning is a one-time setup the project owner does (see "Adoption" at the bottom of this file).
 
 ## Phases
 
 ### Phase 1 — Resolve the scope
 
 1. Parse `$ARGUMENTS`:
-   - Space URL → extract space key from `/wiki/spaces/<KEY>`.
-   - Bare space key → use as-is.
-   - Parent page URL → extract numeric page ID from `/pages/<ID>/...`.
-   - Bare page ID → use as-is.
-2. Resolve Atlassian cloud ID via `mcp__atlassian__getAccessibleAtlassianResources` (downstream tools need it).
-3. Verify the scope is reachable:
-   - For a space: call `mcp__atlassian__getConfluenceSpaces` and confirm the key resolves.
-   - For a parent page: call `mcp__atlassian__getConfluencePage` on the ID and confirm it loads.
-
-### Phase 2 — Find Ready PRDs
-
-Build a CQL query and call `mcp__atlassian__searchConfluenceUsingCql`:
+   - Space URL → extract space key from `/wiki/spaces/<KEY>`. (Used only as a sanity check that the operator's scope matches the configured space.)
+   - Bare space key → same.
+   - Parent page URL → extract numeric page ID from `/pages/<ID>/...`; use as the override for `READY_PARENT` for this run.
+   - Bare page ID → same.
+   - Empty → use `confluence.parents.ready` from config as `READY_PARENT`.
+2. Confirm the configured Atlassian site by invoking `lisa:atlassian-access` `operation: list-sites` (it enforces connection match against `.lisa.config.json`).
+3. Verify `READY_PARENT` is reachable: invoke `lisa:atlassian-access` `operation: read-page id: $READY_PARENT` and confirm it loads. If 404, surface a provisioning error and exit.
 
-- For a space: `space = "<KEY>" AND label = "prd-ready" AND type = page`
-- For a parent: `ancestor = <PARENT-ID> AND label = "prd-ready" AND type = page`
+### Phase 2 — Find ready PRDs
 
-The query returns the list of candidate pages with IDs and titles. For each candidate, confirm the label set on the page (CQL hits should be authoritative, but a follow-up `getConfluencePage` with labels included guards against eventual-consistency lag) and ensure exactly one lifecycle label is present.
+Invoke `lisa:atlassian-access` `operation: read-page-descendants id: $READY_PARENT` and take the **direct children** (depth 1) of the ready lifecycle parent. Those are the PRDs currently in the `ready` state. Capture each child's id and title.
 
-If the result set is empty, run a secondary CQL to distinguish between a genuinely empty queue and a project that has not yet adopted the label convention:
+For each candidate, follow up with `lisa:atlassian-access` `operation: read-page id: <PAGE-ID>` and read its `parentId` to confirm it is still parented under `$READY_PARENT` (guards against eventual-consistency lag and concurrent re-parenting by another operator).
 
-- Secondary query (space scope): `space = "<KEY>" AND (label = "prd-ready" OR label = "prd-in-review" OR label = "prd-blocked" OR label = "prd-ticketed") AND type = page`
-- Secondary query (parent scope): `ancestor = <PARENT-ID> AND (label = "prd-ready" OR label = "prd-in-review" OR label = "prd-blocked" OR label = "prd-ticketed") AND type = page`
+If the result set is empty, run a sanity probe across the other lifecycle parents to distinguish between a genuinely empty queue and a project where the lifecycle scaffolding is misconfigured:
 
-If the secondary query also returns nothing → the `prd-*` label convention has not been adopted. Surface a misconfiguration message: `"No pages in this scope carry prd-* labels. If this is a new project, apply the prd-ready label to PRDs that are ready for ticketing (see Adoption section)."` Exit with an error — this is a setup issue, not a normal idle cycle.
+- For each of `IN_REVIEW_PARENT`, `BLOCKED_PARENT`, `TICKETED_PARENT`: invoke `read-page-descendants id: <parent>` and count direct children.
+- If every lifecycle parent has zero direct children → the lifecycle scaffolding is provisioned but unused, OR PRDs are still parented under the legacy structure. Surface: `"No PRDs found under any of the configured lifecycle parent pages (ready, in_review, blocked, ticketed). If this is a new project, move PRDs that are ready for ticketing under the configured 'ready' parent page (see Adoption section)."` Exit with an error — this is a setup / migration issue, not a normal idle cycle.
+- If any non-ready parent has children → the queue is genuinely empty (PRDs exist but are in `in_review`, `blocked`, `ticketed`, or `shipped`). Exit cleanly with `"No PRDs currently parented under the 'ready' lifecycle page. Nothing to do."`
 
-If the secondary query returns results → the queue is genuinely empty (all PRDs are already in-review, blocked, ticketed, or shipped). Exit cleanly with `"No PRDs labelled prd-ready. Nothing to do."`
+### Phase 3 — Process each ready PRD
 
-### Phase 3 — Process each Ready PRD
-
-For each PRD page (process serially to keep label transitions auditable):
+For each PRD page (process serially to keep transitions auditable):
 
 #### 3a. Claim
 
-Transition labels via `mcp__atlassian__updateConfluencePage`: remove `prd-ready`, add `prd-in-review`. This is the idempotency lock — a re-entrant cycle running concurrently won't see this PRD because its CQL query filters on `label = "prd-ready"`.
+Transition the PRD from `ready` to `in_review` by re-parenting it:
+
+```bash
+# Pseudo-code; the actual call is a Skill tool invocation of lisa:atlassian-access.
+#
+# NOTE: the v2 PUT endpoint that backs write-page requires:
+#   - id
+#   - title (unchanged)
+#   - version.number (current + 1)
+#   - parentId (the new lifecycle parent)
+#   - body (some deployments reject PUTs without a body; preserving the body
+#     also matches this skill's invariant of never editing PRD content)
+# We therefore GET-then-PUT: fetch via read-page to capture title, version,
+# and body, then write-page with parentId swapped.
+transition_prd() {
+  local prd_id="$1" target_role="$2"
+  local new_parent
+  new_parent=$(read_parent_id "$target_role")
+  # 1. read-page id: $prd_id  -> capture title, version.number (=N), body.storage.value
+  # 2. write-page payload: {
+  #      "id":       "$prd_id",
+  #      "title":    "<unchanged>",
+  #      "parentId": "$new_parent",
+  #      "version":  { "number": N+1 },
+  #      "body":     { "storage": { "value": "<unchanged>", "representation": "storage" } }
+  #    }
+}
+
+# Claim:
+transition_prd "$PRD_ID" in_review
+```
 
-If the update fails (permission error, version conflict / 409 race), log it and skip this PRD. Do not proceed to validation on a PRD you didn't successfully claim.
+This re-parent is the idempotency lock — a re-entrant cycle running concurrently won't see this PRD because `read-page-descendants id: $READY_PARENT` no longer includes it once parentId has moved.
 
-The `updateConfluencePage` call must preserve the page body; only the labels change. (If the MCP tool requires a full body in the update payload, fetch the current body via `getConfluencePage` immediately before the update and pass it back unchanged — preserving body content is non-negotiable, this skill never edits PRD content.)
+If the update fails (permission error, version conflict / 409 race), log it and skip this PRD. Do not proceed to validation on a PRD you didn't successfully claim.
 
 #### 3b. Dry-run validation
 
@@ -113,8 +188,8 @@ This call also indirectly invokes `lisa:tracker-source-artifacts` (artifact extr
 
 1. Re-invoke `lisa:confluence-to-tracker` with `dry_run: false` to actually write the tickets. This re-runs Phases 1-5 and runs the preservation gate (Phase 5.5).
 2. Capture the created ticket keys from the skill's output.
-3. Post a Confluence **footer comment** on the PRD via `mcp__atlassian__createConfluenceFooterComment` listing the created tickets (epic, stories, sub-tasks) with their JIRA URLs. Lead with: `"Ticketed by Claude. Created N JIRA issues — see below. Add the prd-shipped label after the work is delivered."`
-4. Transition labels: remove `prd-in-review`, add `prd-ticketed` via `updateConfluencePage`.
+3. Post a Confluence **footer comment** on the PRD via `lisa:atlassian-access` `operation: comment-page id: <PAGE-ID> kind: footer body: "..."` listing the created tickets (epic, stories, sub-tasks) with their JIRA URLs. Lead with: `"Ticketed by Claude. Created N JIRA issues — see below. Move this page under the 'shipped' lifecycle parent after the work is delivered."`
+4. Re-parent to `ticketed`: `transition_prd "$PRD_ID" ticketed`.
 5. **Run Phase 3e (coverage audit)** before considering this PRD done.
 
 **If `FAIL`** (one or more planned tickets failed one or more gates):
@@ -128,14 +203,14 @@ The audience for these comments is the **product team**, not engineers. They are
 
 ##### 3c.2 Render each comment
 
-For each anchored group, post via `mcp__atlassian__createConfluenceInlineComment` with:
-- `page_id`: the PRD page ID
-- `inline_text` (or whatever the MCP tool calls the selection-anchor parameter): the `prd_anchor` value
+For each anchored group, invoke `lisa:atlassian-access` `operation: comment-page kind: inline` with:
+- `id`: the PRD page ID
+- `anchor`: the `prd_anchor` value (the substring the inline comment will be attached to)
 - `body`: the comment body, formatted using the template below
 
-For the unanchored group, post a single footer comment via `mcp__atlassian__createConfluenceFooterComment` using the same template, prefixed with `Issues without a specific section anchor:` and one block per failure.
+For the unanchored group, post a single footer comment via `lisa:atlassian-access` `operation: comment-page kind: footer body: "..."` using the same template, prefixed with `Issues without a specific section anchor:` and one block per failure.
 
-If `createConfluenceInlineComment` returns "anchor not found" (the page text changed between fetch and post), fall back to a footer comment for that group. Do not silently drop the failure.
+If the inline comment call returns "anchor not found" (the page text changed between fetch and post), fall back to a footer comment for that group via the same access skill operation. Do not silently drop the failure.
 
 ##### 3c.3 Comment template
 
@@ -148,7 +223,7 @@ Each comment body MUST contain these four parts, in this order, no exceptions:
 
 **Recommendation:** <validator's `recommendation` field, verbatim — must contain 1–3 concrete options, never a generic "please clarify">
 
-**Action:** Update this section in the PRD, then replace the `prd-blocked` label with `prd-ready` and Claude will re-run intake.
+**Action:** Update this section in the PRD, then move the page back under the 'ready' lifecycle parent and Claude will re-run intake.
 ```
 
 If multiple failures share an anchor, render each as its own `**What's unclear:** ... **Recommendation:** ...` block within the same comment, separated by horizontal lines (`---`). Keep the single `[Category badge]` heading at the top using the most-severe / most-blocking category from the group.
@@ -177,15 +252,15 @@ Use these exact badge labels — they are the validator's category values transl
 - Engineering shorthand (`AC`, `OOS`, `repo`, `env var`).
 - "Clarify this" / "Please specify" without candidate resolutions. The validator is required to provide candidates; if `recommendation` is empty or vague, treat the failure as an Error and surface internally rather than posting a useless comment.
 
-##### 3c.6 Label transition
+##### 3c.6 Lifecycle transition
 
-After all comments are posted (anchored groups + the optional footer summary), transition labels: remove `prd-in-review`, add `prd-blocked` via `updateConfluencePage`. Do NOT write any JIRA tickets.
+After all comments are posted (anchored groups + the optional footer summary), re-parent the PRD to the `blocked` lifecycle parent: `transition_prd "$PRD_ID" blocked`. Do NOT write any destination tickets.
 
 #### 3d. Continue
 
-Move to the next Ready PRD. One PRD failing does not affect others.
+Move to the next ready PRD. One PRD failing does not affect others.
 
-#### 3e. Coverage audit (mandatory after prd-ticketed)
+#### 3e. Coverage audit (mandatory after re-parenting to `ticketed`)
 
 Per-ticket gates prove each ticket is well-formed; they do NOT prove the *set* of created tickets covers the *whole* PRD. Silent drops happen — invoke the `lisa:prd-ticket-coverage` skill to catch them.
 
@@ -194,71 +269,81 @@ Per-ticket gates prove each ticket is well-formed; they do NOT prove the *set* o
 
    | Verdict | Action |
    |---------|--------|
-   | `COMPLETE` | Done. Leave label as `prd-ticketed`. Move to next PRD. |
-   | `COMPLETE_WITH_SCOPE_CREEP` | Post an advisory footer comment naming the scope-creep tickets (so product can decide whether to close them as out-of-scope). Leave label as `prd-ticketed`. |
-   | `GAPS_FOUND` | The created ticket set is incomplete. (a) For each gap, post a comment using the same product-facing template as Phase 3c.3 — inline-anchored when `prd_anchor` is non-null, footer otherwise; category badge from the gap's `category` field; `What's unclear` and `Recommendation` from the audit report's `what` and `recommendation` fields. Apply the same forbidden-language rules from Phase 3c.5. (b) Post one footer summary comment listing the tickets that *were* successfully created (so product knows what to keep vs. what to extend). (c) Transition labels from `prd-ticketed` back to `prd-blocked` via `updateConfluencePage`. |
-   | `NO_TICKETS_FOUND` | Should not happen if step 2 succeeded. If it does, log it as an Error in the cycle summary and leave label as `prd-ticketed` with a comment flagging the audit failure for human review. |
+   | `COMPLETE` | Done. Leave PRD under `ticketed` parent. Move to next PRD. |
+   | `COMPLETE_WITH_SCOPE_CREEP` | Post an advisory footer comment naming the scope-creep tickets (so product can decide whether to close them as out-of-scope). Leave PRD under `ticketed` parent. |
+   | `GAPS_FOUND` | The created ticket set is incomplete. (a) For each gap, post a comment using the same product-facing template as Phase 3c.3 — inline-anchored when `prd_anchor` is non-null, footer otherwise; category badge from the gap's `category` field; `What's unclear` and `Recommendation` from the audit report's `what` and `recommendation` fields. Apply the same forbidden-language rules from Phase 3c.5. (b) Post one footer summary comment listing the tickets that *were* successfully created (so product knows what to keep vs. what to extend). (c) Re-parent the PRD from `ticketed` back to `blocked`: `transition_prd "$PRD_ID" blocked`. |
+   | `NO_TICKETS_FOUND` | Should not happen if step 2 succeeded. If it does, log it as an Error in the cycle summary and leave the PRD under `ticketed` with a comment flagging the audit failure for human review. |
 
 3. The created tickets remain in the destination tracker regardless of the verdict — they are valid in their own right. The audit only tells us whether *more* are needed.
 
 ### Phase 4 — Summary report
 
-After processing every Ready PRD, emit a summary:
+After processing every ready PRD, emit a summary:
 
 ```text
 ## confluence-prd-intake summary
 
-Scope: <space-key | parent-page-title> (<URL>)
+Scope: ready parent = <READY_PARENT> (<URL>)
 Cycle started: <ISO timestamp>
 Cycle completed: <ISO timestamp>
 
 PRDs processed: <n>
-- prd-ticketed: <n>
+- Ticketed: <n>
   - <PRD title> → <epic-key> + <story-count> stories + <subtask-count> sub-tasks (coverage: COMPLETE | COMPLETE_WITH_SCOPE_CREEP)
-- prd-blocked: <n>
+- Blocked: <n>
   - <PRD title> → <gate-failure-count> gate failures (pre-write) OR <gap-count> coverage gaps (post-write)
 - Errors (claim failed, etc): <n>
   - <PRD title> — <reason>
 
-Total JIRA tickets created: <n>
+Total destination tickets created: <n>
 Coverage audit summary: <n> COMPLETE / <n> COMPLETE_WITH_SCOPE_CREEP / <n> GAPS_FOUND
 ```
 
-Print to the agent's output. Do not write this summary to Confluence or JIRA — it's an operational record for the human.
+Print to the agent's output. Do not write this summary to Confluence or the destination tracker — it's an operational record for the human.
 
 ## Idempotency & safety
 
-- **Single-cycle scope**: this skill processes the `prd-ready` set as it exists at the start of Phase 2. New `prd-ready` PRDs added mid-cycle are picked up next run.
-- **No writes outside the lifecycle**: this skill only ever writes to the destination tracker via `lisa:confluence-to-tracker` (which delegates to `lisa:tracker-write`), and only ever changes Confluence labels among `prd-in-review`, `prd-blocked`, `prd-ticketed`. It never edits PRD body content, never touches `prd-draft` or `prd-shipped`, never deletes pages.
-- **Claim-first ordering**: the label flip to `prd-in-review` happens BEFORE validation runs, so a re-entrant call won't double-process.
-- **Failure isolation**: an exception processing one PRD must not stop the cycle. Catch, record under "Errors" in the summary, continue to the next PRD. The PRD that errored is left labelled `prd-in-review` — the human investigates from there.
-- **Single-label invariant**: after every transition, verify exactly one lifecycle label is present on the page. If two are present (rare race), surface as an Error and skip — do NOT auto-resolve, the human decides.
+- **Single-cycle scope**: this skill processes the ready set as it exists at the start of Phase 2. New PRDs moved under the `ready` parent mid-cycle are picked up next run.
+- **No writes outside the lifecycle**: this skill only ever writes to the destination tracker via `lisa:confluence-to-tracker` (which delegates to `lisa:tracker-write`), and only ever re-parents PRDs among `in_review`, `blocked`, and `ticketed` via `lisa:atlassian-access` `operation: write-page`. It never edits PRD body content, never re-parents into or out of `draft` / `shipped`, never deletes pages.
+- **Claim-first ordering**: the re-parent to `in_review` happens BEFORE validation runs, so a re-entrant call won't double-process.
+- **Failure isolation**: an exception processing one PRD must not stop the cycle. Catch, record under "Errors" in the summary, continue to the next PRD. The PRD that errored is left under whatever parent it currently occupies (usually `in_review` if claim succeeded) — the human investigates from there.
+- **Single-parent invariant**: a page has exactly one parent by construction in Confluence — the multi-state ambiguity that label-based systems can hit (two `prd-*` labels simultaneously) cannot occur here. After every transition, re-read the page and confirm `parentId` matches the expected role; if not, surface as an Error and skip.
 
 ## Configuration
 
 Same configuration as `lisa:confluence-to-tracker`. See that skill for the full table. Key items:
 
-- **From `.lisa.config.json`**: `atlassian.cloudId` (required for Confluence MCP), `confluence.spaceKey` and/or `confluence.parentPageId` (when `$ARGUMENTS` doesn't pin a specific page).
+- **From `.lisa.config.json`**: `atlassian.cloudId` (required), `confluence.spaceKey` and/or `confluence.parentPageId` (for breadth-of-scope sanity checks), and `confluence.parents.{draft,ready,in_review,blocked,ticketed,shipped}` for the lifecycle parent-page IDs.
 - **From environment variables**: `E2E_BASE_URL`, `E2E_TEST_PHONE`, `E2E_TEST_OTP`, `E2E_TEST_ORG`, `E2E_GRAPHQL_URL` (operational E2E test config).
 
 Destination tracker config (jira / github / linear) is consumed by `lisa:tracker-write` internally — this skill does NOT read it. If any required value is missing, surface the missing key(s) and exit this cycle — never invent values.
 
+| Field | Required | Purpose |
+|-------|----------|---------|
+| `.lisa.config.json` `confluence.parents.ready` | yes | Parent page id for "ready for ticketing" |
+| `.lisa.config.json` `confluence.parents.in_review` | yes | Parent page id for "claimed by the agent" |
+| `.lisa.config.json` `confluence.parents.blocked` | yes | Parent page id for "validation failure" |
+| `.lisa.config.json` `confluence.parents.ticketed` | yes | Parent page id for "successfully ticketed" |
+| `.lisa.config.json` `confluence.parents.draft` | recommended | Parent page id for PRDs still being drafted by product |
+| `.lisa.config.json` `confluence.parents.shipped` | recommended | Parent page id for delivered PRDs |
+
 ## Rules
 
 - Never write to the destination tracker outside of `lisa:confluence-to-tracker` → `lisa:tracker-write`. The validator's verdict gates progress; bypassing it produces broken tickets.
-- Never add or remove a label this skill doesn't own (`prd-in-review`, `prd-blocked`, `prd-ticketed`). Product owns `prd-draft`, `prd-ready`, `prd-shipped`.
-- Never edit the PRD's body. Communication with product happens only through Confluence comments. If `updateConfluencePage` requires a body in the payload, refetch and pass it back unchanged.
+- Never re-parent a PRD into a lifecycle parent this skill doesn't own (`in_review`, `blocked`, `ticketed`). Product owns `draft`, `ready` (as the entry signal), and `shipped`.
+- Never edit the PRD's body. Communication with product happens only through Confluence comments. The `write-page` call preserves the body verbatim — fetch then PUT with body unchanged.
 - Never post a single page-level dump of all gate failures. One inline comment per `prd_anchor` group (or one footer summary for unanchored failures only). Comments must be inline-anchored where possible, categorized, plain-language, and contain a concrete recommendation.
 - Never include a gate ID, internal skill name, or engineering shorthand in a comment body.
 - Never run more than one intake cycle concurrently against the same scope. This skill assumes serial execution.
-- If `lisa:confluence-to-tracker` returns errors, treat them as gate failures: comment + `prd-blocked`. Don't silently fail.
+- If `lisa:confluence-to-tracker` returns errors, treat them as gate failures: comment + re-parent to `blocked`. Don't silently fail.
 
 ## Adoption (one-time per project)
 
-Before this skill can run against a project, the project must adopt the `prd-*` label convention:
+Before this skill can run against a project, the project must adopt the lifecycle parent-page convention:
 
-1. Apply `prd-ready` to PRDs that are ready for ticketing (replaces the Notion `Status = Ready` flip).
-2. Reserve `prd-in-review`, `prd-blocked`, `prd-ticketed` for this skill — humans should not set them manually except to recover from an error.
-3. (Optional but recommended) Add `prd-draft` for in-progress PRDs and `prd-shipped` for delivered work, so the full lifecycle is visible at a glance.
+1. Create six pages in the project's Confluence space, one per lifecycle role: `Draft`, `Ready`, `In Review`, `Blocked`, `Ticketed`, `Shipped`. (Page titles are not significant — they exist to be re-parenting targets.)
+2. Record each page's numeric id in `.lisa.config.json` under `confluence.parents.<role>`. `/lisa:setup:confluence` automates this.
+3. Move each existing PRD page under the appropriate lifecycle parent based on its current state. Product moves PRDs from `draft` → `ready` when they are ready for ticketing (replaces the Notion `Status = Ready` flip).
+4. Reserve the `in_review`, `blocked`, and `ticketed` parents for this skill — humans should not re-parent PRDs into them manually except to recover from an error.
 
-If the project hasn't adopted these labels, the first run exits with a label-convention error (not the idle empty-set message) — this distinguishes a setup issue from a genuinely empty queue so operators know to apply the convention rather than assuming the queue is drained. See Phase 2 for how the skill detects this case.
+If the project hasn't adopted these parent pages, the first run exits with a provisioning error (not the idle empty-set message) — this distinguishes a setup issue from a genuinely empty queue so operators know to run `/lisa:setup:confluence` rather than assuming the queue is drained. See Phase 2 for how the skill detects this case.

package/plugins/lisa/skills/confluence-to-tracker/SKILL.md

@@ -7,11 +7,13 @@ description: >
   or similar. This skill mirrors `lisa:notion-to-tracker` for projects whose PRDs live in Confluence —
   the workflow, gates, dry-run mode, and validation rules are identical; only the source-of-truth tool
   surface differs (Confluence MCP instead of Notion MCP).
-allowed-tools: ["Skill", "Bash", "mcp__atlassian__getConfluencePage", "mcp__atlassian__getConfluencePageDescendants", "mcp__atlassian__getConfluencePageFooterComments", "mcp__atlassian__getConfluencePageInlineComments", "mcp__atlassian__getConfluenceCommentChildren", "mcp__atlassian__searchConfluenceUsingCql", "mcp__atlassian__getAccessibleAtlassianResources"]
+allowed-tools: ["Skill", "Bash"]
 ---
 
 # Confluence PRD to Tracker Breakdown
 
+All Atlassian operations in this skill go through `lisa:atlassian-access`. Do not call MCP tools or `acli` directly.
+
 Convert a Confluence PRD into a structured ticket hierarchy in the configured destination tracker (JIRA, GitHub Issues, or Linear per .lisa.config.json): Epics > Stories > Sub-tasks.
 Each sub-task is scoped to exactly one repo and includes an empirical verification plan.
 
@@ -29,8 +31,9 @@ This skill supports two modes, controlled by a `dry_run` flag in `$ARGUMENTS`:
 
 Dry-run output format is identical to `lisa:notion-to-tracker`'s. Reuse the same fields, including
 `prd_anchor` and `prd_section`. The only difference: `prd_anchor` is the inline-comment anchor text
-that `createConfluenceInlineComment` accepts (typically the full selected substring; truncate if it
-exceeds the tool's max anchor length and emit `null` if no resolvable anchor exists).
+that `lisa:atlassian-access` `operation: comment-page kind: inline` accepts (typically the full
+selected substring; truncate if it exceeds the substrate's max anchor length and emit `null` if no
+resolvable anchor exists).
 
 ```text
 ## confluence-to-tracker dry-run: <PRD title>
@@ -63,13 +66,21 @@ exceeds the tool's max anchor length and emit `null` if no resolvable anchor exi
 ### Total failures: <n>
 ```
 
-The dry-run mode never writes to JIRA and never calls `mcp__atlassian__createJiraIssue`. It also never
-modifies the source Confluence page, never adds/removes labels, and never posts comments — that is the
+The dry-run mode never writes to the destination tracker. It also never modifies the source Confluence
+page, never re-parents the PRD between lifecycle parents, and never posts comments — that is the
 orchestrating skill's responsibility (`lisa:confluence-prd-intake`).
 
+## PRD lifecycle is parent-page-based on Confluence
+
+Unlike GitHub and Linear (which use labels for PRD lifecycle state), Confluence encodes PRD lifecycle as **parent-page placement**: each lifecycle role (`draft`, `ready`, `in_review`, `blocked`, `ticketed`, `shipped`) corresponds to a dedicated parent page in the project's Confluence space, listed in `.lisa.config.json` under `confluence.parents.<role>`. A PRD's current state is determined by which of those parents it sits under; a "transition" is a `PUT /wiki/api/v2/pages/{id}` that swaps `parentId`.
+
+This skill itself does NOT transition the PRD between lifecycle parents — that is the orchestrating skill's job (`lisa:confluence-prd-intake`). This skill consumes the PRD content and produces tickets; lifecycle state changes (`ready` → `in_review`, `in_review` → `ticketed` / `blocked`) happen in the orchestrator, before and after this skill runs.
+
+Why parent-page-based, not label-based: scoped Atlassian API tokens cannot write Confluence labels via the v1 endpoint, and the v2 Label API group has no POST endpoint at all. Parent-id transitions, by contrast, are first-class in v2 and work with `write:page:confluence` scope. See `config-resolution` rule, section "Confluence PRD lifecycle uses parent pages, not labels," for the full rationale.
+
 ## Hard Rule: All Writes Go Through `lisa:tracker-write`
 
-**Every JIRA ticket created by this skill — every epic, story, and sub-task — MUST be created by invoking the `lisa:tracker-write` skill. Never call `mcp__atlassian__createJiraIssue`, `mcp__atlassian__editJiraIssue`, `mcp__atlassian__createIssueLink`, or any other Atlassian write tool directly from this skill or from any sub-agent it spawns.**
+**Every ticket created by this skill — every epic, story, and sub-task — MUST be created by invoking the `lisa:tracker-write` skill. Never invoke `lisa:atlassian-access` write operations (`write-ticket`, `link`, `comment`, `transition`) directly from this skill or from any sub-agent it spawns.**
 
 `lisa:tracker-write` enforces gates this skill does not:
 - 3-audience description (Context / Technical Approach / Acceptance Criteria)
@@ -80,7 +91,7 @@ orchestrating skill's responsibility (`lisa:confluence-prd-intake`).
 - Sign-in account and target environment recorded in description
 - Post-create verification
 
-Bypassing `lisa:tracker-write` produces thin tickets that the rest of the lifecycle (triage, ticket-verify, journey, evidence) treats as broken. The Atlassian read tools (`getJiraIssue`, `searchJiraIssuesUsingJql`, `getJiraIssueRemoteIssueLinks`, `getAccessibleAtlassianResources`, `getJiraProjectIssueTypesMetadata`, `getVisibleJiraProjects`, and the Confluence read endpoints listed in `allowed-tools` above) ARE allowed for context gathering and the Phase 5.5 preservation gate.
+Bypassing `lisa:tracker-write` produces thin tickets that the rest of the lifecycle (triage, ticket-verify, journey, evidence) treats as broken. Read operations on Atlassian (ticket reads, JQL search, Confluence page reads, comment fetches) are still performed in this skill — but ONLY via `lisa:atlassian-access` (`operation: read-ticket | search-issues | read-page | search-pages | list-sites`), never via direct MCP tool calls or `acli`.
 
 ## Input
 
@@ -130,14 +141,15 @@ If env vars are not available, ask the user to provide them explicitly before pr
 
 ### Phase 1: Fetch & Analyze the PRD
 
-1. **Resolve the Atlassian cloud ID** via `mcp__atlassian__getAccessibleAtlassianResources`. Confluence MCP calls require it.
-2. **Fetch the main PRD page** via `mcp__atlassian__getConfluencePage` with the page ID. Capture body, labels, and child page references.
-3. **Identify all Epic child pages** via `mcp__atlassian__getConfluencePageDescendants` (one level deep first; recurse if the PRD nests epics under a "Specs" parent).
-4. **Fetch all Epic pages** in parallel via `getConfluencePage`.
-5. **Fetch full comments** for the main page and every epic page in parallel:
-   - `mcp__atlassian__getConfluencePageFooterComments` — page-level threaded comments (equivalent to Notion's page-level discussions)
-   - `mcp__atlassian__getConfluencePageInlineComments` — block-anchored comments tied to specific text spans
-   - For any comment with replies, walk the tree via `mcp__atlassian__getConfluenceCommentChildren` until exhausted
+1. **Confirm the configured Atlassian site** by invoking `lisa:atlassian-access` `operation: list-sites` (it enforces connection match against `.lisa.config.json`).
+2. **Fetch the main PRD page** by invoking `lisa:atlassian-access` `operation: read-page id: <PAGE-ID>`. Capture body, parent page id (used by `lisa:confluence-prd-intake` to determine the PRD's lifecycle state — see "PRD lifecycle is parent-page-based" below), and child page references.
+3. **Identify all Epic child pages** by invoking `lisa:atlassian-access` `operation: read-page-descendants id: <PAGE-ID>` (one level deep first; recurse if the PRD nests epics under a "Specs" parent). If `atlassian-access` does not yet expose `read-page-descendants`, request its addition (see report at bottom).
+4. **Fetch all Epic pages** in parallel via `lisa:atlassian-access` `operation: read-page id: <EPIC-PAGE-ID>`.
+5. **Fetch full comments** for the main page and every epic page in parallel via `lisa:atlassian-access`:
+   - `operation: read-page-comments id: <PAGE-ID> kind: footer` — page-level threaded comments (equivalent to Notion's page-level discussions)
+   - `operation: read-page-comments id: <PAGE-ID> kind: inline` — block-anchored comments tied to specific text spans
+   - For any comment with replies, walk the tree via `operation: read-comment-children id: <COMMENT-ID>` until exhausted
+   (If any of these read-comment operations is not yet in `atlassian-access`'s dispatch table, request their addition — they are intentionally listed here so the access skill can be extended.)
 6. **Synthesize decisions and blockers** from the PRD content + all comments:
    - Decisions already confirmed by the team (look for agreement in comment threads)
    - Open questions that need product/engineering input
@@ -180,13 +192,13 @@ Identical to `lisa:notion-to-tracker` Phase 2. Two complementary inputs ground P
 
 Skip 2b only when the work is purely backend with no user-visible surface, or affects a screen that does not yet exist in dev/prod.
 
-Walkthrough findings are attached to the originating Confluence PRD as a **footer comment** (Confluence has no general "page-level discussion attached to a heading" — footer comments are the page-level equivalent), via `mcp__atlassian__createConfluenceFooterComment`. Title the comment "Current product walkthrough — `<route>`". Inherited onto the resulting epic / stories under a `## Current Product` subsection.
+Walkthrough findings are attached to the originating Confluence PRD as a **footer comment** (Confluence has no general "page-level discussion attached to a heading" — footer comments are the page-level equivalent), via `lisa:atlassian-access` `operation: comment-page id: <PAGE-ID> kind: footer body: "..."`. Title the comment "Current product walkthrough — `<route>`". Inherited onto the resulting epic / stories under a `## Current Product` subsection.
 
 ### Phase 3: Create Epics
 
 > **Mode guard**: In `dry_run: true` mode, do not invoke `lisa:tracker-write` in this phase. Instead, draft the epic spec (summary, description_body, artifacts) and validate it with `lisa:tracker-validate --spec-only`. Record the drafted spec (including a placeholder epic key like `DRY-RUN-EPIC-1`) for Phase 4 to use as parent references. In `dry_run: false` mode (default), proceed as described below.
 
-For each PRD epic, **invoke the `lisa:tracker-write` skill** (do not call `createJiraIssue` directly). Pass it everything it needs to enforce its quality gates:
+For each PRD epic, **invoke the `lisa:tracker-write` skill** (do not invoke `lisa:atlassian-access` write operations directly). Pass it everything it needs to enforce its quality gates:
 
 - `project_key`: resolved by `lisa:tracker-write` from `.lisa.config.json`
 - `issue_type`: `Epic`
@@ -236,7 +248,7 @@ Capture each returned story key — Phase 5 needs it as the parent for sub-tasks
 
 **Auto-split cross-repo work before delegation.** For each candidate sub-task, apply `lisa:task-decomposition` step 1.5: if the work touches more than one repo, split it into one sub-task per repo under the same parent Story (e.g., `[backend-api] Add field` + `[mobile-app] Display field`), and encode the producer-before-consumer ordering via dependencies. Work units that may span repos (Epic, Story, Spike) stay as planned; work units that must be single-repo (Bug, Task, Sub-task, Improvement) are split now. Splitting is this skill's responsibility — the validator's S10 gate is `product_relevant: false` because cross-repo failures are decomposition errors caught here, not product questions sent back to the PRD.
 
-Delegate sub-task creation to **parallel agents** (one per epic or batch of stories) for efficiency. **Every spawned agent must invoke `lisa:tracker-write` for each sub-task — no agent may call `createJiraIssue` directly.**
+Delegate sub-task creation to **parallel agents** (one per epic or batch of stories) for efficiency. **Every spawned agent must invoke `lisa:tracker-write` for each sub-task — no agent may invoke `lisa:atlassian-access` write operations directly.**
 
 Each sub-task MUST:
 1. **Be scoped to exactly ONE repo** — indicated in brackets in the summary: `[repo-name]`
@@ -293,16 +305,17 @@ When you encounter something the PRD + comments + codebase can't resolve:
 
 ## Agent Prompt Template for Sub-task Creation
 
-When delegating to agents, provide this context. **The "MUST invoke jira-write-ticket" instruction is load-bearing — do not edit it out when adapting this template.**
+When delegating to agents, provide this context. **The "MUST invoke lisa:tracker-write" instruction is load-bearing — do not edit it out when adapting this template.**
 
 ```text
-Create JIRA sub-tasks in the [PROJECT] project at [CLOUD_ID].
+Create sub-tasks in the [PROJECT] project.
 
 CRITICAL: For each sub-task, invoke the `lisa:tracker-write` skill via the Skill tool.
-Do NOT call `mcp__atlassian__createJiraIssue` directly. The `lisa:tracker-write` skill
-enforces required quality gates (Gherkin acceptance criteria, 3-audience description,
-single-repo scope, sign-in/environment fields, post-create verification). Bypassing it
-produces broken tickets that downstream skills (triage, journey, evidence) cannot use.
+Do NOT invoke `lisa:atlassian-access` write operations (write-ticket / link / comment /
+transition) directly. The `lisa:tracker-write` skill enforces required quality gates
+(Gherkin acceptance criteria, 3-audience description, single-repo scope,
+sign-in/environment fields, post-create verification). Bypassing it produces broken
+tickets that downstream skills (triage, journey, evidence) cannot use.
 
 For each sub-task, invoke `lisa:tracker-write` with:
 - issue_type: "Sub-task"
@@ -320,10 +333,10 @@ For each sub-task, invoke `lisa:tracker-write` with:
 Each sub-task must:
 1. Be scoped to ONE repo only — repo named in brackets in the summary
 2. Include the Empirical Verification Plan in the description
-3. Be created via `lisa:tracker-write`, not via direct MCP calls
+3. Be created via `lisa:tracker-write`, not via direct `lisa:atlassian-access` write operations
 
 If `lisa:tracker-write` rejects a sub-task, fix the input and re-invoke. Do NOT fall back
-to a direct `createJiraIssue` call to bypass the gate.
+to a direct `lisa:atlassian-access` `operation: write-ticket` call to bypass the gate.
 
 Test user info: [credentials from config]
 

package/plugins/lisa/skills/debrief/SKILL.md

@@ -10,14 +10,13 @@ Walk the original Plan for `$ARGUMENTS`, mine the completed work items and their
 
 ## Orchestration: agent team
 
-If you are NOT already operating inside an agent team (no prior `TeamCreate` in this session, not spawned via `Agent` with `team_name`), the very first thing you do is create the team. Two tool calls only, in this exact order:
+If you are NOT already operating inside an agent team (no prior successful team-creation tool call in this session, not spawned into a team context), the very first thing you do is establish team orchestration.
 
-1. `ToolSearch` with `query: "select:TeamCreate"` — `TeamCreate` is a deferred tool whose schema must be loaded before it can be invoked. A cold call returns `InputValidationError` and tempts a fallback to direct `Agent` calls, which bypasses the team.
-2. `TeamCreate` — actually create the team.
+Use `TeamCreate` if available. In Claude, if `TeamCreate` has not been loaded yet, first use `ToolSearch` with `query: "select:TeamCreate"` to load its schema. If `TeamCreate` is not available, use the current runtime's tool-discovery mechanism (for Codex, `tool_search`) to discover available multi-agent/team tools, then call the appropriate team creation tool. If no team creation tool is available, explicitly state that team orchestration is unavailable in this runtime, continue as the lead agent, and preserve the workflow's review, verification, and task-tracking obligations locally.
 
-Until `TeamCreate` returns successfully, do NOT call any of: `Agent`, `TaskCreate`, `Skill`, MCP tools (Atlassian / Linear / GitHub / Notion), `Read`, `Write`, `Edit`, `Bash`, `Grep`, `Glob`. Resolving the work-item set, fetching tickets, walking PRs — all of those are tasks for the team you are about to create, not for the lead session before the team exists.
+Until the team is established or the no-team fallback has been declared, do NOT call any of: `Agent`, `TaskCreate`, `Skill`, MCP tools (Atlassian / Linear / GitHub / Notion), `Read`, `Write`, `Edit`, `Bash`, `Grep`, `Glob`. Resolving the work-item set, fetching tickets, walking PRs — all of those are tasks for the team you are about to create, not for the lead session before orchestration exists.
 
-If you ARE already inside an agent team (e.g., a teammate invoked this skill via the Skill tool), do NOT call `TeamCreate` — the harness rejects double-creates. Continue within the existing team.
+If you ARE already inside an agent team (e.g., a teammate invoked this skill via the Skill tool), do NOT create a second team — many harnesses reject double-creates. Continue within the existing team.
 
 ## Input