@codyswann/lisa 2.7.0 → 2.8.0

package/plugins/lisa/skills/github-evidence/SKILL.md

@@ -0,0 +1,116 @@
+---
+name: github-evidence
+description: "Upload text evidence to the GitHub `pr-assets` release, update PR description, post a GitHub Issue comment with code blocks, and relabel the issue to `status:code-review`. Reusable by any skill that captures evidence and generates evidence/comment.md (and optionally evidence/comment.txt). The GitHub counterpart of lisa:jira-evidence."
+allowed-tools: ["Bash"]
+---
+
+# GitHub Evidence Posting
+
+Upload captured evidence and generated templates to the GitHub PR description and the originating GitHub Issue. This skill is the posting step — it assumes evidence files and a comment template already exist in the evidence directory.
+
+## Arguments
+
+`$ARGUMENTS`: `<ISSUE_REF> <EVIDENCE_DIR> <PR_NUMBER>`
+
+- `ISSUE_REF` (required): GitHub issue ref — `org/repo#<number>` or full GitHub issue URL.
+- `EVIDENCE_DIR` (required): Directory containing evidence and templates (e.g., `./evidence`).
+- `PR_NUMBER` (required): GitHub PR number to update description.
+
+## Prerequisites
+
+- `gh` CLI authenticated (`gh auth status`).
+- Evidence directory containing:
+  - `NN-name.txt` or `NN-name.json` text evidence files (e.g., `01-health-check.json`)
+  - `comment.md` — GitHub markdown body for both the issue comment and the PR description's `## Evidence` section.
+  - (Optional) `comment.txt` — kept for parity with the JIRA path; not used here.
+
+## Workflow
+
+1. **Resolve refs**
+
+   Parse `ISSUE_REF` into `<issue-org>/<issue-repo>#<issue-number>`. Parse the local repo (where the PR lives) via `gh repo view --json nameWithOwner --jq '.nameWithOwner'`.
+
+2. **Ensure the `pr-assets` release exists in the IMPLEMENTATION repo**
+
+   The `pr-assets` release is the asset CDN for evidence files. Each PR's evidence is uploaded with the PR number prefix in the asset name to keep them addressable.
+
+   ```bash
+   gh release view pr-assets --repo <impl-org>/<impl-repo> >/dev/null 2>&1 \
+     || gh release create pr-assets --repo <impl-org>/<impl-repo> --title "PR Assets" --notes "CDN for PR evidence"
+   ```
+
+3. **Upload each evidence file**
+
+   ```bash
+   for f in "$EVIDENCE_DIR"/[0-9][0-9]-*.txt "$EVIDENCE_DIR"/[0-9][0-9]-*.json; do
+     [ -f "$f" ] || continue
+     name="pr-${PR_NUMBER}-$(basename "$f")"
+     gh release upload pr-assets --repo <impl-org>/<impl-repo> --clobber "$f#$name"
+   done
+   ```
+
+   The `#$name` syntax sets the asset name. `--clobber` lets re-runs overwrite.
+
+4. **Update the PR description**
+
+   Replace or append the `## Evidence` section in the PR body using `comment.md`:
+
+   ```bash
+   current_body=$(gh pr view "$PR_NUMBER" --repo <impl-org>/<impl-repo> --json body --jq '.body')
+   evidence_section=$(cat "$EVIDENCE_DIR/comment.md")
+   # Replace existing ## Evidence ... up to next ## or EOF; otherwise append.
+   ```
+
+   Use a Bash heredoc / temp file to compose the new body, then:
+
+   ```bash
+   gh pr edit "$PR_NUMBER" --repo <impl-org>/<impl-repo> --body-file /tmp/pr-body.md
+   ```
+
+5. **Post a comment on the originating issue**
+
+   The issue may live in a different repo than the PR (cross-repo work):
+
+   ```bash
+   gh issue comment <issue-number> --repo <issue-org>/<issue-repo> --body-file "$EVIDENCE_DIR/comment.md"
+   ```
+
+6. **Relabel the issue to `status:code-review`**
+
+   ```bash
+   gh issue edit <issue-number> --repo <issue-org>/<issue-repo> \
+     --remove-label status:in-progress \
+     --add-label status:code-review
+   ```
+
+   If the current label is already `status:code-review`, skip. If neither `status:in-progress` nor `status:code-review` is present, log a warning and continue without changing labels — the issue may have been hand-managed.
+
+## Evidence Naming Convention
+
+```text
+evidence/
+  01-health-check.json          uploaded
+  02-schema-after-migration.txt uploaded
+  03-rate-limit-response.txt    uploaded
+  comment.md                    used for issue comment + PR description
+```
+
+Asset names in the release are prefixed with `pr-<number>-` so multiple PRs' evidence coexists without collision.
+
+## Troubleshooting
+
+### Evidence not appearing in GitHub PR or issue
+
+Check:
+- `gh auth status` succeeds.
+- The PR / issue refs are correct.
+- The `pr-assets` release exists in the implementation repo.
+
+### `gh issue edit` returns 404
+
+The issue may live in a different repo than the PR — pass `--repo <issue-org>/<issue-repo>` explicitly. The implementation repo and the destination tracker repo can differ when `tracker = "github"` is set on a project that ships from a separate codebase.
+
+## Notes
+
+- This skill is symmetric with `lisa:jira-evidence` — the evidence directory layout and `comment.md` content are identical so a single template generator can serve both vendors.
+- The PR's `## Evidence` section is the canonical link for reviewers; the issue comment is for the PRD/PM thread.

package/plugins/lisa/skills/github-journey/SKILL.md

@@ -0,0 +1,121 @@
+---
+name: github-journey
+description: "Parse a GitHub Issue's Validation Journey section, execute the verification steps using appropriate tools (curl, test commands, database queries), capture evidence at each marker, and post results via lisa:github-evidence. The GitHub counterpart of lisa:jira-journey."
+allowed-tools: ["Bash", "Read", "Glob", "Grep", "Skill"]
+---
+
+# GitHub Validation Journey
+
+Parse a GitHub Issue's Validation Journey, execute the verification steps using the appropriate tools for the change type, capture evidence at each `[EVIDENCE: <name>]` marker, and post to the issue + GitHub PR.
+
+## Arguments
+
+`$ARGUMENTS`: `<ISSUE_REF> [PR_NUMBER]`
+
+- `ISSUE_REF` (required): GitHub issue ref — `org/repo#<number>` or full GitHub issue URL.
+- `PR_NUMBER` (optional): GitHub PR number for the implementation PR. If omitted, the skill auto-detects the PR from `lisa:github-read-issue`'s linked-PR list (preferring the most recent open PR).
+
+## Prerequisites
+
+- `gh` CLI authenticated.
+- Appropriate services running for the verification type (dev server, database, etc.).
+
+## Workflow
+
+### Step 1: Parse the Validation Journey
+
+```bash
+gh issue view <number> --repo <org>/<repo> --json body --jq '.body'
+```
+
+Extract the `## Validation Journey` section (plus its `### Prerequisites`, `### Steps`, and `### Assertions` sub-sections). Parse each step into a structured form: `{ index, text, evidence_marker (or null) }`.
+
+If the issue has no Validation Journey, stop and instruct the caller to run `/github-add-journey <issue-ref>` first.
+
+### Step 2: Satisfy Prerequisites
+
+Before starting the journey, verify each prerequisite:
+
+1. Check if required services are running (`curl localhost:<port>/health`, `pg_isready`, etc.).
+2. Verify database connectivity if the journey touches data.
+3. Ensure environment variables are set.
+4. Run any setup commands mentioned in `### Prerequisites`.
+
+### Step 3: Execute Steps and Capture Evidence
+
+Execute each step sequentially. Determine the verification approach based on the step text and the issue's change type (inferred from `type:` label, `component:` labels, and the body):
+
+- **API endpoints** → Run curl commands, capture HTTP response to `evidence/NN-name.txt` (or `.json`).
+- **Database changes** → Run psql/migration commands, capture schema output.
+- **Background jobs** → Trigger the job, check queue/state, capture logs.
+- **Library/utility changes** → Run tests, capture output.
+- **Security fixes** → Reproduce exploit attempt, verify fix, capture output.
+
+At each `[EVIDENCE: name]` marker, capture stdout/stderr to a numbered file:
+
+#### Evidence Naming Convention
+
+`{NN}-{evidence-name}.txt` (or `.json` for structured data):
+
+- `NN`: zero-padded sequential number (01, 02, 03...).
+- `evidence-name`: the value from `[EVIDENCE: <name>]` (kebab-case).
+
+Example:
+
+```text
+evidence/
+  01-health-check.json
+  02-schema-after-migration.txt
+  03-rate-limit-response.txt
+  comment.md
+```
+
+### Step 4: Generate Evidence Templates
+
+Compose `evidence/comment.md` with:
+
+- The issue ref + title.
+- The PR ref.
+- Each evidence marker rendered as a GitHub markdown section with a fenced code block of the captured file.
+- An "Assertions verified" subsection mapping each `### Assertions` line to "PASS / FAIL".
+
+This template generator is shared with `lisa:jira-journey` (the JIRA path renders the same content as wiki markup). When the markdown comment is the canonical artifact, both vendors stay aligned.
+
+### Step 5: Post Evidence
+
+Use `lisa:github-evidence` to post everything:
+
+```bash
+# Equivalent of: bash scripts/post-evidence.sh — but invoked via the Skill tool
+```
+
+Invoke the skill with `<ISSUE_REF> ./evidence <PR_NUMBER>`. It uploads the files to the `pr-assets` release, edits the PR's `## Evidence` section, posts a comment on the issue, and relabels the issue to `status:code-review`.
+
+### Step 6: Verify
+
+Confirm:
+- Evidence files exist as release assets named `pr-<PR>-NN-name.{txt,json}`.
+- The PR description contains the `## Evidence` section with code-block embeds.
+- The issue has a new comment whose body matches `comment.md`.
+- The issue's labels include `status:code-review` and not `status:in-progress`.
+
+## Verification Patterns Reference
+
+| Change Type | Verification Method | Evidence Format |
+|---|---|---|
+| API endpoint | `curl -s localhost:PORT/endpoint` | JSON response |
+| Database migration | `psql -c "\d table"` or migration output | Schema text |
+| Background job | Trigger + check state | Log output |
+| Library/utility | `bun run test -- path/to/test` | Test output |
+| Security fix | Reproduce + verify fix | Request/response |
+| Auth/authz | Multi-role verification | Status codes per role |
+
+## Troubleshooting
+
+### Evidence file is empty
+
+Ensure the command succeeded and produced output. Use `2>&1` to capture both stdout and stderr.
+
+### Parser returns no steps
+
+The issue may not have a Validation Journey section — run `/github-add-journey <ISSUE_REF>` first.

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

@@ -0,0 +1,286 @@
+---
+name: github-prd-intake
+description: "Scans a GitHub repository for issues labeled `prd-ready` and runs each one through the dry-run validation pipeline. PRDs that pass every gate get tickets written (to whatever destination tracker is configured — JIRA or GitHub Issues itself) and the label flipped to `prd-ticketed`; PRDs that fail get clarifying-question comments and the label flipped to `prd-blocked`. The GitHub counterpart of lisa:notion-prd-intake / lisa:confluence-prd-intake / lisa:linear-prd-intake. Composes existing skills (github-to-tracker, tracker-validate, jira-source-artifacts, product-walkthrough)."
+allowed-tools: ["Skill", "Bash"]
+---
+
+# GitHub PRD Intake: $ARGUMENTS
+
+`$ARGUMENTS` is one of:
+
+- A GitHub `org/repo` token (e.g., `acme/product-prds`) — scans the repo for issues labeled `prd-ready`.
+- A full GitHub repo URL (e.g., `https://github.com/acme/product-prds`).
+- The literal token `github` — falls back to `.lisa.config.json` (`github.org` / `github.repo`).
+
+Run one intake cycle against that repo. Each issue with the `prd-ready` label is claimed, validated, and routed to either `prd-blocked` (with clarifying comments) or `prd-ticketed` (with destination tickets created).
+
+This skill is the GitHub counterpart of `lisa:notion-prd-intake`, `lisa:confluence-prd-intake`, and `lisa:linear-prd-intake`. Phases, gates, comment templates, and rules are identical — the only differences are (1) the lifecycle is encoded as **issue labels** (mirroring Linear's project labels and Confluence's page labels), (2) the fetch / update tools are the `gh` CLI, and (3) clarifying-question comments land directly on the source PRD issue (because GitHub Issues *do* have native comments — no sentinel issue required, unlike Linear). Keep all four skills behaviorally aligned: when changing intake logic, change them together.
+
+## Confirmation policy
+
+Do NOT ask the caller whether to proceed. Once invoked with a repo, run the cycle to completion — claim, validate, branch to `prd-blocked` or `prd-ticketed`, write the summary. The caller has already authorized the run by invoking the skill; re-prompting defeats the purpose of a background batch.
+
+Specifically forbidden:
+
+- Previewing projected scope 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.
+- Pausing because the dry-run validation looks expensive.
+
+The only legitimate reasons to stop early:
+
+- Missing repo argument or required configuration. Surface and exit.
+- Repo unreachable, or the labelling convention not yet adopted (no issue carries any of `prd-ready` / `prd-in-review` / `prd-blocked` / `prd-ticketed`). Surface and exit.
+- Empty `prd-ready` set. Exit cleanly with `"No GitHub issues labeled prd-ready in <org>/<repo>. Nothing to do."`
+
+## Lifecycle assumed
+
+The PRD lifecycle is encoded as **issue labels**:
+
+```text
+prd-draft → prd-ready → prd-in-review → prd-blocked | prd-ticketed → prd-shipped
+            (product)    (us)            (us)                          (product)
+```
+
+Exactly one of these labels is expected on a PRD issue at any time.
+
+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)
+- `prd-ticketed` → `prd-blocked` (post-write coverage gaps from Phase 3e)
+
+It never adds, removes, or touches `prd-draft` or `prd-shipped`. Those labels are owned by product.
+
+A "transition" means: remove the old lifecycle label and add the new one (`gh issue edit <num> --remove-label <old> --add-label <new>`). The skill MUST verify exactly one lifecycle label is present after the update.
+
+If the repo has not yet adopted `prd-*` labels, this skill cannot run. See "Adoption" at the bottom.
+
+**Label namespace separation:** the PRD lifecycle uses the `prd-*` namespace. The build-queue lifecycle (used by `lisa:github-build-intake`) uses the `status:*` namespace. The two never overlap. When the destination tracker is also GitHub Issues (self-host case), the same repo can host both — but a single issue is either a PRD (carrying a `prd-*` label) or a build ticket (carrying a `status:*` label), never both.
+
+## Phases
+
+### Phase 1 — Resolve the repo
+
+1. Parse `$ARGUMENTS`:
+   - `org/repo` token → use as-is.
+   - GitHub URL → extract `org` and `repo`.
+   - Literal `github` → resolve from `.lisa.config.json`; error if not set.
+2. Confirm `gh auth status` succeeds.
+3. Confirm the repo is reachable: `gh repo view <org>/<repo> --json name`.
+4. Verify the `prd-*` label set exists:
+   ```bash
+   gh label list --repo <org>/<repo> --json name --jq '[.[] | select(startswith("prd-"))] | sort'
+   ```
+   If none of `prd-ready` / `prd-in-review` / `prd-blocked` / `prd-ticketed` are present, surface a label-convention error and exit (see "Adoption").
+
+### Phase 2 — Find Ready PRDs
+
+```bash
+gh issue list --repo <org>/<repo> --label prd-ready --state open --limit 100 \
+  --json number,title,body,labels,author,milestone,createdAt,updatedAt,url
+```
+
+For each candidate, confirm exactly one lifecycle label is present (the `--label` filter selects `prd-ready` matches, but a PRD could have ended up with two labels by hand — that's a misconfiguration, not a normal queue entry).
+
+If empty, run a secondary check:
+
+```bash
+gh issue list --repo <org>/<repo> --state open --limit 100 --json number,labels --jq '[.[] | .labels[] | select(.name | startswith("prd-")) | .name] | unique'
+```
+
+If no `prd-*` labels appear on any open issue → convention not adopted; surface error and exit. If `prd-*` labels exist but none are `prd-ready` → genuinely empty queue, exit cleanly with the idle message.
+
+### Phase 3 — Process each Ready PRD
+
+Process serially to keep label transitions auditable.
+
+#### 3a. Claim
+
+```bash
+gh issue edit <num> --repo <org>/<repo> --remove-label prd-ready --add-label prd-in-review
+```
+
+This is the idempotency lock — a re-entrant cycle's `--label prd-ready` filter won't see this issue again.
+
+If the relabel fails (permission, race), log and skip. Do not proceed to validation on a PRD you didn't successfully claim.
+
+This skill never edits the PRD body. Communication with product happens only through comments.
+
+#### 3b. Dry-run validation
+
+Invoke the `lisa:github-to-tracker` skill with `dry_run: true` and the PRD issue ref. The skill returns a structured report containing:
+- The planned ticket hierarchy
+- Per-ticket validation verdicts and remediation
+- An overall PASS / FAIL verdict
+- A failure count
+
+This call indirectly invokes `lisa:jira-source-artifacts` (artifact extraction + classification) and `lisa:product-walkthrough` (when the PRD touches existing user-facing surfaces). All gate logic lives in `lisa:tracker-validate` (which dispatches to `lisa:jira-validate-ticket` or `lisa:github-validate-issue` depending on the configured destination).
+
+#### 3c. Branch on the verdict
+
+**If `PASS`** (every planned ticket passed every applicable gate):
+
+1. Re-invoke `lisa:github-to-tracker` with `dry_run: false` to actually write tickets. This re-runs the planning phases and the preservation gate.
+2. Capture the created ticket refs.
+3. Post a comment on the PRD issue listing the created tickets with their URLs:
+   ```bash
+   gh issue comment <prd-num> --repo <org>/<repo> --body-file /tmp/ticketed-comment.md
+   ```
+   Lead with: `"Ticketed by Claude. Created N tickets in <destination> — see below. Add the prd-shipped label after the work is delivered."` The destination is named (JIRA / GitHub Issues) so product knows where to look.
+4. Transition labels: `gh issue edit <prd-num> --remove-label prd-in-review --add-label prd-ticketed`.
+5. **Run Phase 3e (coverage audit)** before considering this PRD done.
+
+**If `FAIL`**:
+
+The audience is the **product team**, not engineers. Follow the strict comment rules below.
+
+##### 3c.1 Partition failures
+
+1. Drop every failure where `product_relevant = false`. Internal data-quality problems — the agent should fix its own spec, not ask product. Record dropped failures under `Errors` in the cycle summary.
+2. Group remaining product-relevant failures by `prd_anchor` (a section heading or a `selection_with_ellipsis` snippet from the PRD body). Failures sharing an anchor become one comment.
+
+##### 3c.2 Render each comment
+
+GitHub Issues do not have selection-anchored comments (unlike Confluence inline comments). Approximate by quoting the relevant body excerpt at the top of each comment:
+
+```bash
+gh issue comment <prd-num> --repo <org>/<repo> --body-file /tmp/anchored-comment-N.md
+```
+
+Each comment template MUST contain these parts in this order, no exceptions:
+
+```text
+[<Category badge>] <prd_section heading text>
+
+> <quoted excerpt from the PRD body, ~10–30 words around the anchor — this stands in for inline anchoring>
+
+**What's unclear:** <validator's `what` field, verbatim — already product-readable>
+
+**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` on the issue 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 `---`. Keep the single `[Category badge]` heading at the top.
+
+For unanchored failures (`prd_anchor: null`), post one rollup comment prefixed with `Issues without a specific section anchor:`.
+
+##### 3c.3 Category badges
+
+| Validator category | Badge label |
+|---------------------|-------------|
+| `product-clarity` | `[Product clarity]` |
+| `acceptance-criteria` | `[Acceptance criteria]` |
+| `design-ux` | `[Design / UX]` |
+| `scope` | `[Scope]` |
+| `dependency` | `[Dependency]` |
+| `data` | `[Data]` |
+| `technical` | `[Technical]` |
+
+`structural` failures must never reach this step (filtered in 3c.1).
+
+##### 3c.4 Forbidden in product comments
+
+- Gate IDs (`S4`, `F2`, etc.).
+- GitHub-Issues-specific terminology (`gh`, `sub-issue`, `label namespace`) — paraphrase before posting.
+- Internal skill names (`lisa:tracker-validate`, `github-to-tracker`).
+- Engineering shorthand (`AC`, `OOS`, `repo`, `env var`).
+- "Clarify this" / "Please specify" without candidate resolutions.
+
+##### 3c.5 Label transition
+
+After all comments are posted, transition: `gh issue edit <num> --remove-label prd-in-review --add-label prd-blocked`. Do NOT write any tickets.
+
+#### 3d. Continue
+
+Move to the next Ready PRD. One PRD failing does not affect others.
+
+#### 3e. Coverage audit (mandatory after prd-ticketed)
+
+Per-ticket gates prove each ticket is well-formed; they do NOT prove the *set* of tickets covers the *whole* PRD. Invoke `lisa:prd-ticket-coverage` to catch silent drops.
+
+1. Invoke `lisa:prd-ticket-coverage` with `<PRD URL> tickets=[<created refs from 3c step 2>]`. The coverage skill auto-detects the PRD vendor from the URL host (`github.com` → GitHub).
+2. Read the verdict:
+
+   | Verdict | Action |
+   |---------|--------|
+   | `COMPLETE` | Done. Leave label as `prd-ticketed`. Move to next PRD. |
+   | `COMPLETE_WITH_SCOPE_CREEP` | Post an advisory comment on the PRD issue naming the scope-creep tickets. 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.2 — anchored when `prd_anchor` is non-null. (b) Post one summary comment listing the tickets that *were* successfully created. (c) Transition labels from `prd-ticketed` back to `prd-blocked`. |
+   | `NO_TICKETS_FOUND` | Should not happen if step 2 succeeded. Log as Error; leave label as `prd-ticketed` with a flag comment. |
+
+3. The created tickets remain in the destination tracker regardless of the verdict. The audit only tells us whether *more* are needed.
+
+### Phase 4 — Summary report
+
+```text
+## github-prd-intake summary
+
+Repo: <org>/<repo> (<URL>)
+Cycle started: <ISO timestamp>
+Cycle completed: <ISO timestamp>
+
+PRDs processed: <n>
+- prd-ticketed: <n>
+  - <issue-ref> "<title>" → <epic-ref> + <story-count> stories + <subtask-count> sub-tasks (coverage: COMPLETE | COMPLETE_WITH_SCOPE_CREEP)
+- prd-blocked: <n>
+  - <issue-ref> "<title>" → <gate-failure-count> gate failures (pre-write) OR <gap-count> coverage gaps (post-write)
+- Errors (claim failed, etc): <n>
+  - <issue-ref> "<title>" — <reason>
+
+Total 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 GitHub.
+
+## Self-host edge case (PRD repo = destination repo)
+
+When the configured destination tracker is GitHub Issues AND the PRD repo is the same as the destination repo, both reads and writes hit the same place. Disambiguation rules:
+
+- A PRD issue carries a `prd-*` label. Built tickets carry a `type:*` + `status:*` label set, but never a `prd-*` label.
+- The "Ticketed by Claude" comment on the PRD links to the destination ticket numbers (which live in the same repo, so the links are simple `#<n>` refs).
+- `lisa:prd-ticket-coverage` filters out the source PRD itself when listing destination tickets — the PRD is never a ticket of its own work.
+
+## Idempotency & safety
+
+- **Single-cycle scope**: this skill processes the `prd-ready` set as it exists at the start of Phase 2. New `prd-ready` issues added mid-cycle are picked up next run.
+- **No writes outside the lifecycle**: this skill only ever writes to the destination tracker via `lisa:github-to-tracker` (which delegates to `lisa:tracker-write`), only ever changes labels among `prd-in-review`, `prd-blocked`, `prd-ticketed`, only ever comments on the source PRD issue. It never edits PRD bodies, never touches `prd-draft` or `prd-shipped`, never closes or deletes PRD issues.
+- **Claim-first ordering**: the label flip to `prd-in-review` happens BEFORE validation runs.
+- **Failure isolation**: an exception processing one PRD must not stop the cycle. Catch, record under "Errors" in the summary, continue. The PRD that errored is left labeled `prd-in-review` — humans investigate from there.
+- **Single-label invariant**: after every transition, verify exactly one lifecycle label is present.
+
+## Configuration
+
+Same env vars as `lisa:github-to-tracker` plus `.lisa.config.json` `github.org` / `github.repo`. If any required value is missing, surface and exit — never invent values.
+
+## Rules
+
+- Never write to the destination tracker outside of `lisa:github-to-tracker` → `lisa:tracker-write`.
+- 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 a PRD's body. Communication with product happens only via comments.
+- Never post a single dump of all gate failures on one comment. One comment per `prd_anchor` group, plus one rollup for unanchored failures.
+- 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 repo.
+- If `lisa:github-to-tracker` returns errors, treat them as gate failures: comment + `prd-blocked`. Don't silently fail.
+
+## Adoption (one-time per repo)
+
+Before this skill can run, the repo must adopt the `prd-*` issue-label convention:
+
+1. Create the labels:
+   ```bash
+   gh label create prd-draft --color C5DEF5 --description "PRD in progress (product owns)" --repo <org>/<repo>
+   gh label create prd-ready --color FBCA04 --description "PRD ready for ticketing" --repo <org>/<repo>
+   gh label create prd-in-review --color 5319E7 --description "Claude is reviewing this PRD" --repo <org>/<repo>
+   gh label create prd-blocked --color D93F0B --description "PRD blocked — see comments" --repo <org>/<repo>
+   gh label create prd-ticketed --color 0E8A16 --description "Tickets created — see comments" --repo <org>/<repo>
+   gh label create prd-shipped --color 1D76DB --description "Work delivered (product owns)" --repo <org>/<repo>
+   ```
+2. Apply `prd-ready` to issues that are ready for ticketing.
+3. Reserve `prd-in-review`, `prd-blocked`, `prd-ticketed` for this skill — humans should not set them manually except to recover from an error.
+4. Keep the `prd-*` namespace strictly separate from the build-queue `status:*` namespace owned by `lisa:github-build-intake`.
+
+If the repo hasn't adopted these labels, the first run exits with a label-convention error (not the idle empty-set message) — this distinguishes setup from a genuinely empty queue.