@codyswann/lisa 2.61.0 → 2.62.0

package/plugins/lisa/skills/linear-write-issue/SKILL.md

@@ -203,7 +203,7 @@ If the item modifies an existing user-facing surface, a `lisa:product-walkthroug
 
 Before create/update, verify each field is populated where applicable:
 
-- **Labels**: include `status:ready` for new items; component labels (`component:<name>`); status / priority labels are NOT redundant with native fields — labels exist for portability and downstream queries.
+- **Labels**: include `status:ready` for a new **leaf** work unit (Bug / Task / Sub-task / Improvement with no child work) per `leaf-only-lifecycle`, **unless `build_ready: false`** (see the Build-ready control input below); component labels (`component:<name>`); status / priority labels are NOT redundant with native fields — labels exist for portability and downstream queries. A container (Epic Project / Story with sub-issues / Spike) never receives `status:ready`.
 - **Native priority field**: 0–4 per Linear's scale; explicit, not "unset".
 - **Native estimate**: per Linear's team-configured estimate scale (often 0–8 Fibonacci); skip for Epic / Spike.
 - **ProjectMilestone**: when the team uses dated milestones, set the milestone on the Project (Epic) or on the Issue (when an Issue belongs to a milestone).
@@ -212,6 +212,14 @@ Before create/update, verify each field is populated where applicable:
 
 For Bug / Task / Sub-task, ensure the summary is prefixed with `[<repo-name>]`.
 
+### Build-ready control input (`build_ready`)
+
+`build_ready` is an optional write-control input (default: **omitted**). It governs whether a **leaf** work unit's `status:ready` label is applied on create. It never overrides `leaf-only-lifecycle` — a container is never stamped build-ready regardless of `build_ready`. "Not build-ready" is not a special state: the Issue is still created with Linear's default native `Todo` state; it just lacks the `status:ready` **label** the build lifecycle keys off, so a human can promote it later.
+
+- **Omitted** → current behavior: a leaf work unit receives `status:ready`. Preserves what every existing caller (`lisa:plan`, the `*-to-tracker` skills) relies on.
+- **`build_ready: false`** → create the leaf **without** the `status:ready` label, so it sits in the backlog for a human to review and promote into the queue.
+- **`build_ready: true`** → ensure the leaf carries `status:ready` so `lisa:intake` / `lisa:linear-build-intake` auto-picks it up.
+
 ## Phase 5.5 — Validate (Pre-write Gate)
 
 Before any write, invoke `lisa:linear-validate-issue` with the full proposed spec assembled from Phases 2 / 3 / 4 / 5. Pass it as a YAML block per the `lisa:linear-validate-issue` schema, including `runtime_behavior_change`, `authenticated_surface`, and `artifacts_attached` flags so the right gates run.
@@ -236,7 +244,7 @@ If the validator reports `PASS`, continue to Phase 6.
 
 ### CREATE — Story / Task / Bug / Spike / Improvement (Issue with projectId)
 
-1. Resolve any required Issue labels (`status:ready`, `component:<name>`, `prd-intake-feedback` only if this is a sentinel issue, etc.) via `mcp__linear-server__list_issue_labels` (create via `create_issue_label` if missing).
+1. Resolve any required Issue labels (`component:<name>`, `prd-intake-feedback` only if this is a sentinel issue, etc.) via `mcp__linear-server__list_issue_labels` (create via `create_issue_label` if missing). Include `status:ready` in `labelIds` only for a **leaf** work unit and only when `build_ready` is not `false` (per the Build-ready control input) — omit it for a container, and for a `build_ready: false` leaf which then waits in the backlog for a human to promote it.
 2. Call `mcp__linear-server__save_issue` with: `team` (teamId), `title` (summary), `description` (markdown), `projectId` (the Epic Project), `priority` (0–4), `estimate`, `labelIds`, `assignee` if known.
 3. Capture the returned identifier (e.g. `ENG-123`) — Phase 4 sub-tasks need it as `parentId`.
 4. Add relationships from Phase 4b via `save_issue` (relations field) or paired relation calls.

package/plugins/lisa/skills/linear-write-prd/SKILL.md

@@ -0,0 +1,90 @@
+---
+name: linear-write-prd
+description: "Creates or idempotently updates a PRD as a Linear Project carrying exactly one PRD lifecycle project-label (`prd-draft` by default, or `prd-ready` when initial_role is ready so lisa:linear-prd-intake auto-claims it). The Linear PRD-source writer behind lisa:prd-source-write. Dedupes by a stable marker embedded in the Project description (matched by marker, never by name). Uses the Linear MCP."
+allowed-tools: ["Skill", "Bash", "mcp__linear-server__list_teams", "mcp__linear-server__list_projects", "mcp__linear-server__get_project", "mcp__linear-server__save_project", "mcp__linear-server__list_project_labels", "mcp__linear-server__create_project_label"]
+---
+
+# Write Linear PRD: $ARGUMENTS
+
+Create (or update) a PRD as a Linear **Project** in the configured workspace/team. Invoked by
+`lisa:prd-source-write` when `source = linear`; do not call directly from a vendor-neutral caller.
+
+Linear's PRD lifecycle uses **project-level labels** (`prd-*`), per `config-resolution`. (The Linear
+PRD source models a PRD as a Project — the same shape `lisa:linear-prd-intake` scans.)
+
+`$ARGUMENTS` carries the `lisa:prd-source-write` spec: `title`, `body` (full PRD markdown),
+`initial_role` (`draft` | `ready`, default `draft`), `dedupe_key`, `marker`, optional `source_ref`.
+
+## Phase 1 — Resolve workspace/team + PRD lifecycle labels
+
+```bash
+read_g() { local lv gv; lv=$(jq -r "$1 // empty" .lisa.config.local.json 2>/dev/null); gv=$(jq -r "$1 // empty" .lisa.config.json 2>/dev/null); echo "${lv:-${gv:-$2}}"; }
+WORKSPACE=$(read_g '.linear.workspace' '')
+TEAM=$(read_g '.linear.teamKey' '')
+# Resolve the FULL PRD lifecycle vocabulary from config (never hard-code names) so the one-of
+# reconcile and the past-ready check are correct even when a project renamed any label.
+PRD_DRAFT=$(read_g '.linear.labels.prd.draft' 'prd-draft')
+PRD_READY=$(read_g '.linear.labels.prd.ready' 'prd-ready')
+PRD_IN_REVIEW=$(read_g '.linear.labels.prd.in_review' 'prd-in-review')
+PRD_BLOCKED=$(read_g '.linear.labels.prd.blocked' 'prd-blocked')
+PRD_TICKETED=$(read_g '.linear.labels.prd.ticketed' 'prd-ticketed')
+PRD_SHIPPED=$(read_g '.linear.labels.prd.shipped' 'prd-shipped')
+PRD_VERIFIED=$(read_g '.linear.labels.prd.verified' 'prd-verified')
+ALL_PRD_LABELS=("$PRD_DRAFT" "$PRD_READY" "$PRD_IN_REVIEW" "$PRD_BLOCKED" "$PRD_TICKETED" "$PRD_SHIPPED" "$PRD_VERIFIED")
+PROGRESSED=("$PRD_IN_REVIEW" "$PRD_BLOCKED" "$PRD_TICKETED" "$PRD_SHIPPED" "$PRD_VERIFIED")
+[ -z "$WORKSPACE" ] && { echo "Error: linear.workspace not set in .lisa.config.json."; exit 1; }
+[ -z "$TEAM" ] && { echo "Error: linear.teamKey not set in .lisa.config.json. A team key is required to create or scope a Linear Project."; exit 1; }
+```
+
+Resolve the target project-label from `initial_role`: `ready` → `$PRD_READY`, else `$PRD_DRAFT`.
+Resolve its label id via `mcp__linear-server__list_project_labels` (create via
+`mcp__linear-server__create_project_label` if missing).
+
+## Phase 2 — Dedupe by marker (search before create)
+
+The `marker` is embedded in the Project description. Find an existing Project carrying it — match the
+marker, **never** the project name:
+
+1. `mcp__linear-server__list_projects` scoped to the team/workspace (filtered by the `prd-*` label
+   set when supported), then inspect each candidate's description via
+   `mcp__linear-server__get_project` for the marker. If `source_ref` was passed, target it directly.
+2. If a Project with the marker exists → **update**; else → **create**.
+
+## Phase 3 — Create or update
+
+**Marker normalization (both paths).** Before writing the `description`, ensure it contains
+**exactly one** marker line — inject the marker if the synthesized description lacks it. **Never write
+a markerless description** (including UPDATE / `source_ref`): that breaks future dedupe.
+
+**CREATE:** `mcp__linear-server__save_project` with:
+- `name`: `$TITLE`
+- `description`: the marker-normalized full PRD markdown
+- `teamIds`: `[<resolved team id>]`
+- `labelIds`: `[<role label id>]` (exactly one PRD lifecycle label)
+- `state`: Linear Project default (e.g. `backlog`)
+
+**UPDATE** (existing project or `source_ref`): `save_project` with the project id and **only** the
+changed fields — regenerate the marker-normalized `description`, and reconcile labels to **exactly
+one** PRD lifecycle label: add the role label, remove every other label in the resolved
+`${ALL_PRD_LABELS[@]}` set (config-resolved names, not a hard-coded list). Do **not** down-rank a
+Project whose current label is in the resolved `${PROGRESSED[@]}` set (already past `ready`) — leave
+it and report `reused (already past ready)`.
+
+## Phase 4 — Return
+
+```yaml
+ref: "<linear-project-id-or-slug>"
+url: "<project url>"
+role: draft | ready          # (or the Project's current role when reused past ready)
+marker: "<MARKER>"
+outcome: created | reused
+```
+
+## Rules
+
+- Exactly one PRD lifecycle project-label at all times.
+- Match dedupe by marker, never by project name.
+- Never down-rank a Project already past `ready`.
+- Source-side writer (`prd-*` project labels) — never touches issue-level build labels (`status:*`),
+  which are `lisa:linear-write-issue`'s lane (see `config-resolution` self-host separation).
+- Resolve label names from config (`linear.labels.prd.*`) — never hardcode.

package/plugins/lisa/skills/linear-write-prd/agents/openai.yaml

@@ -0,0 +1,4 @@
+display_name: "Linear Write PRD"
+short_description: "Creates or idempotently updates a PRD as a Linear Project carrying exactly one PRD lifecycle project-label (`prd-draft` by default, or…"
+default_prompt:
+  - "Use $linear-write-prd: Creates or idempotently updates a PRD as a Linear Project carrying exactly one PRD lifecycle project-label (`prd-draft` by default, or…."

package/plugins/lisa/skills/notion-access/SKILL.md

@@ -12,6 +12,7 @@ Single chokepoint for all Notion operations. Routes each op to a substrate, enfo
 
 ```text
 operation: read-page         id: <uuid>
+operation: create-page       parent_database_id: <uuid> properties: {...} [children: [...]]  # create a new page (e.g. a PRD row) in a database; children is optional — omit to create a page without initial block content
 operation: write-page        payload: {...}        # update page properties
 operation: archive-page      id: <uuid>
 operation: query-database    id: <uuid> filter: {...} sort: {...}
@@ -164,6 +165,7 @@ Substrate columns: try the column matching `$substrate` first. If that column is
 |---|---|---|
 | **Pages** | | |
 | `read-page id:<I>` | `mcp__claude_ai_Notion__notion-fetch` | `GET /v1/pages/<I>` |
+| `create-page parent_database_id:<D> properties:<P> [children:<arr>]` | `mcp__claude_ai_Notion__notion-create-pages` | `POST /v1/pages` body `{ "parent": { "database_id": "<D>" }, "properties": <P>, "children": <arr?> }` (children optional per Notion API) |
 | `write-page payload:<P>` | `mcp__claude_ai_Notion__notion-update-page` | `PATCH /v1/pages/<I>` body `{ "properties": {...}, "archived": true/false }` |
 | `archive-page id:<I>` | `mcp__claude_ai_Notion__notion-update-page` (with `archived: true`) | `PATCH /v1/pages/<I>` body `{ "archived": true }` |
 | `append-blocks page_id:<P> children:<arr>` | (no direct equivalent) | `PATCH /v1/blocks/<P>/children` body `{ "children": <arr> }` |

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

@@ -1,6 +1,6 @@
 ---
 name: notion-prd-intake
-description: "Scans a Notion PRD database for pages in the configured `ready` status and runs each one through the dry-run validation pipeline. PRDs that pass every gate get tickets written and the status flipped to the configured `ticketed` value; PRDs that fail get clarifying-question comments and the status flipped to the configured `blocked` value. The skill is the runtime for the ready → in_review → blocked|ticketed lifecycle. Composes existing skills (notion-to-tracker, tracker-validate, tracker-source-artifacts, product-walkthrough); does not reimplement their logic."
+description: "Scans a Notion PRD database for pages in the configured `ready` status and runs the first eligible one through the dry-run validation pipeline. A PRD that passes every gate gets tickets written and the status flipped to the configured `ticketed` value; a PRD that fails gets clarifying-question comments and the status flipped to the configured `blocked` value. The skill is the runtime for the ready → in_review → blocked|ticketed lifecycle. Composes existing skills (notion-to-tracker, tracker-validate, tracker-source-artifacts, product-walkthrough); does not reimplement their logic."
 allowed-tools: ["Skill", "Bash", "Read", "Write", "Edit", "AskUserQuestion"]
 ---
 
@@ -14,7 +14,7 @@ allowed-tools: ["Skill", "Bash", "Read", "Write", "Edit", "AskUserQuestion"]
 https://www.notion.so/geminisports/28fd00244d7d47c5866876f7de48c0fe?v=34eba63a2800815891a3000c643f0ea8
 ```
 
-Run one intake cycle against that database. Each PRD in the configured `ready` status is claimed, validated, and routed to either `blocked` (with clarifying comments) or `ticketed` (with destination tickets created).
+Run one intake cycle against that database. The first eligible PRD in the configured `ready` status is claimed, validated, routed to either `blocked` (with clarifying comments) or `ticketed` (with destination tickets created), then the cycle exits. Remaining ready PRDs stay queued for later scheduler invocations.
 
 ## Workflow resolution
 
@@ -56,7 +56,7 @@ This skill shares its PRD closure rollup phase (3f) with `lisa:github-prd-intake
 
 ## Confirmation policy
 
-Do NOT ask the caller whether to proceed. Once invoked with a database URL, run the cycle to completion — claim, validate, branch to `blocked` or `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 with a database URL, run the cycle to completion for the first eligible PRD — claim, validate, branch to `blocked` or `ticketed`, write the summary, and exit. The caller (a human or a cron) has already authorized the run by invoking the skill; re-prompting defeats the purpose of a background queue.
 
 Specifically forbidden:
 
@@ -82,7 +82,7 @@ draft → ready → in_review → blocked | ticketed → shipped → verified
 
 (Default status values: `Draft` / `Ready` / `In Review` / `Blocked` / `Ticketed` / `Shipped` / `Verified`.)
 
-`verified` is the terminal status after `shipped`: it means the shipped product has been empirically checked against the PRD (set by `/lisa:verify-prd`, not by this intake skill). A failed post-ship verification reuses `blocked` rather than introducing a separate `verifying` / `verification-failed` status. Like `draft` and `shipped`, `verified` is **product-owned** — this intake skill never sets, clears, or otherwise touches it. See the "PRD-level verification vs ticket verification" section of the `prd-lifecycle-rollup` rule.
+`verified` is the terminal status after `shipped`: it means the shipped product has been empirically checked against the PRD (set by `/lisa:verify-prd`, not by this intake skill). A failed post-ship verification does **not** use `blocked`; `/lisa:verify-prd` re-opens the PRD `shipped → ticketed` and creates build-ready fix tickets that auto-build and trigger a re-verify (the self-healing loop), introducing no `verifying` / `verification-failed` status. Like `draft` and `shipped`, `verified` is **product-owned** — this intake skill never sets, clears, or otherwise touches it. See the "PRD-level verification vs ticket verification" section of the `prd-lifecycle-rollup` rule.
 
 This skill transitions `ready → in_review`, then `in_review → blocked` or `in_review → ticketed`, then (via the rollup phase 3f) `ticketed → shipped`. It never touches `draft` or `verified` — those statuses are owned by product (`verified` is set by `/lisa:verify-prd` after empirical PRD-level acceptance). The `shipped` status is set by this skill's **rollup phase (3f)** when, and only when, the PRD's generated top-level work is all terminal — per the `prd-lifecycle-rollup` rule; product may also set it by hand. Rollup never advances a PRD to `shipped` on partial completion, and never archives a PRD page unless `notion.rollup.closeOnShipped` is configured `true` (default `false` → set `$SHIPPED`, leave the page active).
 
@@ -110,9 +110,9 @@ For a `select`-type property substitute `"select"` for `"status"`. The response
 
 If the result set is empty, stop and report `"No PRDs with $STATUS_PROP=$READY. Nothing to do."` Exit cleanly — this is the common idle case for a scheduled run.
 
-### Phase 3 — Process each ready PRD
+### Phase 3 — Process the first eligible ready PRD
 
-For each PRD page (process serially to keep status transitions auditable):
+Select the first ready PRD page returned by Phase 2 and process only that page. Later scheduler invocations process the remaining ready PRDs.
 
 #### 3a. Claim
 
@@ -155,7 +155,7 @@ Per-ticket gates prove each ticket is well-formed; they do NOT prove the *set* o
 
    | Verdict | Action |
    |---------|--------|
-   | `COMPLETE` | Done. Leave `$STATUS_PROP = $TICKETED`. Move to next PRD. |
+   | `COMPLETE` | Done. Leave `$STATUS_PROP = $TICKETED`. End the cycle. |
    | `COMPLETE_WITH_SCOPE_CREEP` | Post an advisory Notion comment naming the scope-creep tickets (so product can decide whether to close them as out-of-scope). Leave `$STATUS_PROP = $TICKETED`. |
    | `GAPS_FOUND` | The created ticket set is incomplete. (a) For each gap, post a Notion comment using the same product-facing template as Phase 3c.3 — block-anchored when `prd_anchor` is non-null, page-level 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 summary comment listing the tickets that *were* successfully created (so product knows what to keep vs. what to extend). (c) Transition `$STATUS_PROP` from `$TICKETED` back to `$BLOCKED` by invoking `lisa:notion-access` operation `write-page` with the blocked-status payload. |
    | `NO_TICKETS_FOUND` | Should not happen if step 2 succeeded. If it does, log it as an Error in the cycle summary and leave `$STATUS_PROP = $TICKETED` with a comment flagging the audit failure for human review. |
@@ -239,9 +239,9 @@ rich_text: <Notion rich_text array — the comment body>
 
 The access skill resolves a `prd_anchor` substring to the matching block ID by paging through the PRD's children and posts the comment with `discussion_id` or `parent: { block_id }` as appropriate. If `block_anchor` is `null`, the access skill posts a page-level comment via `parent: { page_id }`.
 
-#### 3d. Continue
+#### 3d. Stop
 
-Move to the next ready PRD. One PRD failing does not affect others.
+Stop immediately after the claimed PRD is ticketed, blocked, or recorded as an error.
 
 #### 3f. PRD closure rollup (config-gated)
 
@@ -298,9 +298,19 @@ The set of **required** children for the all-terminal check is the top-level chi
 
 This phase implements exactly one PRD-lifecycle hop — `$TICKETED → $SHIPPED` — and the optional config-gated archive that follows it. All terminal-state semantics, the generated-top-level-work boundary, and the dedupe-by-child-ref idempotency come from the `prd-lifecycle-rollup` rule; this skill is its Notion implementation, not a second source of truth.
 
+#### 3g. PRD verification dispatch (close the loop on shipped PRDs)
+
+`shipped` and `verified` are distinct facts about a PRD (see the `prd-lifecycle-rollup` rule's "PRD-level verification vs ticket verification" and "Closing the loop" sections). Rollup (3f) only reaches `$SHIPPED`; the `shipped → verified` (pass) / `shipped → ticketed` (fail) hops are owned by `/lisa:verify-prd`. This phase **closes that loop** by dispatching the initiative-level acceptance gate for shipped PRDs. It never performs the verification transition itself — the "never sets the verification outcome" invariant holds: `lisa:verify-prd`, not this skill, sets `verified` (or, on failure, re-opens the PRD to `ticketed`).
+
+Re-query the PRDs currently in the `$SHIPPED` status via `lisa:notion-access` `operation: query-database` filtered on `$STATUS_PROP = $SHIPPED`. Pick the **first** one and invoke `lisa:verify-prd <PRD-page-url>`. Process **one shipped PRD per cycle** — `lisa:verify-prd` is a heavy full flow (spec-conformance + empirical verification + fix-issue creation), so it is bounded exactly like the single-ready-PRD claim in Phase 3; the scheduler drains the rest.
+
+**Per-cycle combined bound:** each scheduler cycle dispatches at most one ready PRD (the Phase 3 single-ready-PRD claim) **and** at most one shipped PRD for verification (this Phase 3g dispatch), for a maximum of two PRD operations per cycle. Ready intake runs first (Phase 3), then shipped verify (Phase 3g).
+
+`lisa:verify-prd` owns the outcome: on a CONFORMS verdict with all empirical checks passing it transitions `$SHIPPED → verified` and posts evidence; on a conformance miss or a failing/unavailable check it **re-opens the PRD `$SHIPPED → ticketed`** (never `blocked`) and creates **build-ready** fix tickets registered as the PRD's generated work, then posts a failure report — the fix tickets auto-build, rollup (3f) re-ships the PRD once they are terminal, and a later cycle re-verifies (the self-healing loop). Either branch moves the PRD out of `$SHIPPED`, so it is not re-picked this cycle; a PRD whose generated work is not actually terminal is guard-stopped by `lisa:verify-prd` (left `$SHIPPED`) — that is verify-prd's gate, not this skill's. A PRD archived on ship (`notion.rollup.closeOnShipped = true`) is out of the open verification queue. This phase, like 3f, is **behaviorally identical across all four intake skills** (`github-prd-intake`, `linear-prd-intake`, `notion-prd-intake`, `confluence-prd-intake`) — only the `$SHIPPED` query surface differs; keep them aligned. Record the dispatched PRD + verify-prd's verdict in the summary.
+
 ### Phase 4 — Summary report
 
-After processing every ready PRD, emit a summary:
+After processing the single selected PRD, emit a summary:
 
 ```text
 ## notion-prd-intake summary
@@ -325,10 +335,10 @@ Print to the agent's output. Do not write this summary to Notion or the destinat
 
 ## Idempotency & safety
 
-- **Single-cycle scope**: this skill processes the ready set as it exists at the start of Phase 2. New ready PRDs added mid-cycle are picked up next run.
+- **One item per cycle**: this skill processes the first eligible ready PRD from Phase 2, then exits. New or remaining ready PRDs are picked up by later scheduler invocations.
 - **No writes outside the lifecycle**: this skill only ever writes to the destination tracker via `lisa:notion-to-tracker` (which delegates to `lisa:tracker-write`), and only ever changes the Notion status property to `$IN_REVIEW`, `$BLOCKED`, `$TICKETED`, or `$SHIPPED` (the last via the rollup phase 3f only). It never edits PRD content, never touches `$DRAFT`, never deletes pages. It sets `$SHIPPED` and may archive the PRD page **only** through the config-gated rollup phase (3f).
 - **Claim-first ordering**: the status flip to `$IN_REVIEW` is set 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 in `$IN_REVIEW` — the human investigates from there.
+- **Failure handling**: an exception processing the selected PRD is caught and recorded under "Errors" in the summary, then the cycle exits. The PRD that errored is left in `$IN_REVIEW` — the human investigates from there.
 - **Rollup idempotency**: rollup (Phase 3f) is a no-op on a PRD already in `$STATUS_PROP = $SHIPPED` (and already archived when `closeOnShipped` is `true`) — no duplicate transition, no duplicate archive, no duplicate comment. The all-terminal condition is a pure function of the children's current states (deduped by child-ref identity), so recomputing it is safe to re-run. Archival NEVER precedes the all-terminal condition.
 
 ## Configuration

package/plugins/lisa/skills/notion-prd-intake/agents/openai.yaml

@@ -1,4 +1,4 @@
 display_name: "Notion PRD Intake"
-short_description: "Scans a Notion PRD database for pages in the configured `ready` status and runs each one through the dry-run validation pipeline"
+short_description: "Scans a Notion PRD database for pages in the configured `ready` status and runs the first eligible one through the dry-run validation…"
 default_prompt:
-  - "Use $notion-prd-intake: Scans a Notion PRD database for pages in the configured `ready` status and runs each one through the dry-run validation pipeline."
+  - "Use $notion-prd-intake: Scans a Notion PRD database for pages in the configured `ready` status and runs the first eligible one through the dry-run validation…."

package/plugins/lisa/skills/notion-write-prd/SKILL.md

@@ -0,0 +1,107 @@
+---
+name: notion-write-prd
+description: "Creates or idempotently updates a PRD as a page in the configured Notion PRD database, setting the lifecycle Status property to the draft value by default (or the ready value when initial_role is ready so lisa:notion-prd-intake auto-claims it). The Notion PRD-source writer behind lisa:prd-source-write. Dedupes by a stable marker embedded in the page (matched by marker, never by title). All Notion access goes through lisa:notion-access — never call the Notion API or MCP directly."
+allowed-tools: ["Skill", "Bash"]
+---
+
+# Write Notion PRD: $ARGUMENTS
+
+Create (or update) a PRD page in the configured Notion PRD database. Invoked by
+`lisa:prd-source-write` when `source = notion`; do not call directly from a vendor-neutral caller.
+**All Notion operations go through `lisa:notion-access`** (the access chokepoint) — never curl the
+Notion API or call a `mcp__*notion*` tool yourself.
+
+`$ARGUMENTS` carries the `lisa:prd-source-write` spec: `title`, `body` (full PRD markdown),
+`initial_role` (`draft` | `ready`, default `draft`), `dedupe_key`, `marker`, optional `source_ref`.
+
+## Phase 1 — Resolve database + Status vocabulary
+
+```bash
+read_g() { local lv gv; lv=$(jq -r "$1 // empty" .lisa.config.local.json 2>/dev/null); gv=$(jq -r "$1 // empty" .lisa.config.json 2>/dev/null); echo "${lv:-${gv:-$2}}"; }
+PRD_DB=$(read_g '.notion.prdDatabaseId' '')
+[ -z "$PRD_DB" ] && { echo "Error: notion.prdDatabaseId not set in .lisa.config.json."; exit 1; }
+STATUS_PROP=$(read_g '.notion.statusProperty' 'Status')
+# Resolve the FULL PRD Status vocabulary from config (never hard-code) so the past-ready check is
+# correct even when a project renamed any Status value.
+DRAFT=$(read_g '.notion.values.draft' 'Draft')
+READY=$(read_g '.notion.values.ready' 'Ready')
+IN_REVIEW=$(read_g '.notion.values.in_review' 'In Review')
+BLOCKED=$(read_g '.notion.values.blocked' 'Blocked')
+TICKETED=$(read_g '.notion.values.ticketed' 'Ticketed')
+SHIPPED=$(read_g '.notion.values.shipped' 'Shipped')
+VERIFIED=$(read_g '.notion.values.verified' 'Verified')
+# "Progressed past ready" set (never down-rank): the resolved in_review/blocked/ticketed/shipped/verified.
+PROGRESSED=("$IN_REVIEW" "$BLOCKED" "$TICKETED" "$SHIPPED" "$VERIFIED")
+```
+
+Resolve the target Status value from `initial_role`: `ready` → `$READY`, otherwise `$DRAFT`.
+
+## Phase 2 — Dedupe by marker (search before create)
+
+The `marker` is embedded in the page (as the first body block). Find an existing PRD page in the DB
+carrying it — match the marker, **never** the title:
+
+1. `lisa:notion-access` `operation: search query: "<marker>"` (Notion indexes page content).
+2. Filter results to pages whose parent is `$PRD_DB`. If `source_ref` was passed, target that page
+   directly and skip the search.
+3. If a matching page is found, this is an **update** — reuse it. If none is found, **create**.
+   Note: Notion search is eventually consistent; if a just-created page isn't found yet, the marker
+   still lives in the page so a later run will dedupe — surface "dedupe degraded (search lag)" rather
+   than silently creating a duplicate when uncertain.
+
+## Phase 3 — Create or update
+
+**Markdown → Notion blocks (conversion boundary).** Convert the PRD markdown to Notion block objects:
+`#`/`##`/`###` → `heading_1/2/3`, paragraphs → `paragraph`, `-`/`*` → `bulleted_list_item`, `1.` →
+`numbered_list_item`, fenced code → `code`. The Notion API caps a single request at **100 blocks**
+and ~2000 characters of rich text per block: split long paragraphs across blocks, and if the PRD
+exceeds 100 blocks, create the page with the first ≤100 blocks then add the remainder with batched
+`operation: append-blocks` calls (≤100 each). When the MCP substrate is active, `create-page` may
+accept the markdown content directly (it performs this conversion) — prefer that; the explicit block
+conversion is the curl-substrate path.
+
+**Marker normalization (both paths).** The page must always carry **exactly one** marker. On CREATE
+the marker is the first body block; on UPDATE never remove it. Never write a markerless page.
+
+**CREATE:**
+
+1. Build the page body as Notion blocks per the conversion above: the **first block is the marker**
+   (a paragraph/callout containing `<!-- $MARKER -->`), then the converted PRD blocks.
+2. Invoke `lisa:notion-access` `operation: create-page` with:
+   ```json
+   { "parent_database_id": "<PRD_DB>",
+     "properties": { "<title-prop>": { "title": [{ "text": { "content": "<TITLE>" } }] },
+                     "<STATUS_PROP>": { "status": { "name": "<ROLE_VALUE>" } } },
+     "children": [ <marker block>, <PRD body blocks> ] }
+   ```
+   Use the DB's actual title property name (read it via `operation: read-database id: <PRD_DB>` if
+   unknown) and the correct property type for `$STATUS_PROP` (`status` vs `select`).
+3. Capture the returned page id + URL.
+
+**UPDATE** (existing page or `source_ref`):
+
+1. Set the Status to the resolved role via `lisa:notion-access` `operation: write-page payload: { "id": "<page-id>", "properties": { "<STATUS_PROP>": { "status": { "name": "<ROLE_VALUE>" } } } }` — **unless** the page's current Status is in the resolved `${PROGRESSED[@]}` set (already past `ready`), in which case leave the Status and report `reused (already past ready)`.
+2. Refresh the canonical spec, not append-only notes: keep the existing marker block, then make the
+   managed PRD body current — archive the previously generated body blocks below the marker
+   (`operation: archive-page` is page-level, so for blocks delete via the blocks API through
+   `notion-access` or, where block deletion isn't available, replace their text in place) and
+   `operation: append-blocks` the regenerated blocks. Do not duplicate the whole spec as a dated
+   note, and never drop the marker.
+
+## Phase 4 — Return
+
+```yaml
+ref: "<notion-page-id>"
+url: "<page url>"
+role: draft | ready          # (or the page's current Status role when reused past ready)
+marker: "<MARKER>"
+outcome: created | reused
+```
+
+## Rules
+
+- All access via `lisa:notion-access`; never touch the Notion API/MCP directly.
+- Match dedupe by marker, never by title.
+- Never down-rank a PRD whose Status is already past `ready`.
+- Resolve the Status vocabulary from config (`notion.statusProperty`, `notion.values.*`) — never
+  hardcode value names.

package/plugins/lisa/skills/notion-write-prd/agents/openai.yaml

@@ -0,0 +1,4 @@
+display_name: "Notion Write PRD"
+short_description: "Creates or idempotently updates a PRD as a page in the configured Notion PRD database, setting the lifecycle Status property to the draft…"
+default_prompt:
+  - "Use $notion-write-prd: Creates or idempotently updates a PRD as a page in the configured Notion PRD database, setting the lifecycle Status property to the draft…."

package/plugins/lisa/skills/prd-source-write/SKILL.md

@@ -0,0 +1,80 @@
+---
+name: prd-source-write
+description: "Vendor-neutral wrapper for creating (or idempotently updating) a PRD in the configured PRD source. The PRD-side sibling of lisa:tracker-write. Resolves `source` from .lisa.config.local.json first (then .lisa.config.json — local overrides global) and dispatches to lisa:notion-write-prd, lisa:confluence-write-prd, lisa:github-write-prd, or lisa:linear-write-prd. Callers (notably lisa:research) MUST invoke this skill instead of a vendor PRD writer directly — that is what makes the PRD source switchable per project. Accepts an `initial_role` of `draft` (default) or `ready` so a freshly created PRD either waits for human promotion or is immediately picked up by lisa:intake; and a stable dedupe marker so re-runs reference the existing PRD instead of creating a duplicate. The PRD lives in the source — there is no separate document artifact."
+allowed-tools: ["Skill", "Bash", "Read"]
+---
+
+# PRD Source Write: $ARGUMENTS
+
+Thin dispatcher. Resolves the configured PRD `source` and delegates to the matching vendor PRD
+writer, which owns the concrete create/update, the lifecycle-role application, and the marker-based
+dedupe. This skill only routes — it never talks to a source API itself.
+
+See the `config-resolution` rule for the full configuration schema and the PRD lifecycle roles.
+
+## Input contract
+
+Callers pass a single structured spec:
+
+```yaml
+operation: create_or_update          # the only operation; create unless the marker already exists
+title: "<PRD title>"
+body: "<full PRD markdown — the entire spec>"
+initial_role: draft | ready          # default: draft. ready = picked up by lisa:intake's PRD scan
+dedupe_key: "<stable-key>"           # e.g. project-ideation's idea key
+marker: "[lisa-project-ideation] idea=<stable-key>"   # embedded in the PRD body for dedupe
+origin: { tool: project-ideation | research | manual }
+source_ref: "<optional existing PRD ref to force an update>"
+```
+
+`initial_role` semantics are uniform across vendors (the role STRINGS resolve per vendor from
+`config-resolution`):
+
+- **`draft`** (default) → the PRD is created in the source's `draft` PRD role. It waits for a human
+  (or a later `ready` promotion) before any intake claims it.
+- **`ready`** → the PRD is created in the source's `ready` PRD role (`prd-ready`), so the PRD-side of
+  `lisa:intake` / the `*-prd-intake` scanner auto-claims it on the next cycle.
+
+There is no "omitted = legacy behavior" mode (unlike the ticket-side `build_ready`): there was no
+prior PRD-source-write behavior to preserve, so omitted means `draft`.
+
+## Workflow
+
+1. **Resolve the source.** Read `.lisa.config.local.json` first (if present), then
+   `.lisa.config.json`. Local overrides global per key. Use `jq` — never hand-parse JSON.
+
+   ```bash
+   local_source=$(jq -r '.source // empty' .lisa.config.local.json 2>/dev/null)
+   global_source=$(jq -r '.source // empty' .lisa.config.json 2>/dev/null)
+   source="${local_source:-${global_source}}"
+   if [ -z "$source" ]; then
+     echo "Error: 'source' is not set in .lisa.config.json. A PRD source (notion / confluence / github / linear) is required to create a PRD. Run /lisa:setup:notion (or :confluence, :github, :linear)." >&2
+     exit 1
+   fi
+   ```
+
+2. **Validate the value and dispatch** (pass the spec verbatim):
+
+   - `notion` → confirm `notion.workspaceId` and `notion.prdDatabaseId` are present, then invoke
+     `lisa:notion-write-prd`.
+   - `confluence` → confirm `atlassian.cloudId` and (`confluence.spaceKey` or
+     `confluence.parents.draft`/`.ready`) are present, then invoke `lisa:confluence-write-prd`.
+   - `github` → confirm `github.org` and `github.repo` are present, then invoke
+     `lisa:github-write-prd`.
+   - `linear` → confirm `linear.workspace` (and team for project placement) is present, then invoke
+     `lisa:linear-write-prd`.
+   - `jira` → **stop and fail loudly**: `"source=jira is not a supported PRD source — config-resolution defines no JIRA PRD lifecycle roles. Use notion / confluence / github / linear, or set source accordingly."` (JIRA is a destination tracker, not a PRD source.)
+   - Any other value (including `file`) → stop and report: `"Unknown PRD source '<value>'. Expected one of: notion, confluence, github, linear."`
+
+3. **Surface the vendor writer's output unchanged.** It returns the created/reused PRD ref + URL,
+   the applied role (`draft`/`ready`), the dedupe marker, and whether it was created or reused.
+   Downstream callers (research, project-ideation) parse this — do not paraphrase.
+
+## Rules
+
+- Never bypass dispatch — a vendor-neutral caller calling a `*-write-prd` skill directly defeats the
+  per-project source switch (exactly the `tracker-write` discipline, mirrored).
+- Never accept a source outside `{notion, confluence, github, linear}`. `jira` and `file` fail loudly.
+- Never mutate the spec between layers. The vendor writers define their own create/dedupe contract.
+- Never invent a PRD lifecycle role string — resolve every role from `config-resolution` per vendor.
+- Idempotency is the vendor writer's job (marker search before create); this shim only routes.

package/plugins/lisa/skills/prd-source-write/agents/openai.yaml

@@ -0,0 +1,4 @@
+display_name: "PRD Source Write"
+short_description: "Vendor-neutral wrapper for creating (or idempotently updating) a PRD in the configured PRD source"
+default_prompt:
+  - "Use $prd-source-write: Vendor-neutral wrapper for creating (or idempotently updating) a PRD in the configured PRD source."