@codyswann/lisa 2.6.4 → 2.8.0

package/plugins/src/base/skills/github-build-intake/SKILL.md

@@ -0,0 +1,188 @@
+---
+name: github-build-intake
+description: "GitHub counterpart to lisa:jira-build-intake. Scans a GitHub repository for issues labeled `status:ready`, claims each by relabeling to `status:in-progress`, runs the implementation/build flow via lisa:github-agent, and relabels to `status:on-dev` on completion. The `status:ready` label is the human-flipped signal that an issue is truly ready for development — mirroring how Notion PRDs work product Draft → Ready → (us) In Review → Blocked|Ticketed."
+allowed-tools: ["Skill", "Bash"]
+---
+
+# GitHub Build Intake: $ARGUMENTS
+
+`$ARGUMENTS` is one of:
+
+1. A GitHub `org/repo` token (e.g., `acme/frontend-v2`).
+2. A full GitHub repo URL (e.g., `https://github.com/acme/frontend-v2`).
+3. The literal token `github` — falls back to `.lisa.config.json` (`github.org` / `github.repo`).
+
+Run one build-intake cycle. Each `status:ready` issue is claimed, built via the `lisa:github-agent` flow, and relabeled to `status:on-dev` (or the equivalent next-label for that repo). The cycle is the symmetric mirror of `lisa:notion-prd-intake`: humans flip `status:ready`, agents pick up and progress.
+
+## Confirmation policy
+
+Do NOT ask the caller whether to proceed. Once invoked with a repo, run the cycle to completion — claim, dispatch each issue through `lisa:github-agent`, relabel successful builds to `status:on-dev`, 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 (issue count, projected PR count, build duration) and asking whether to continue.
+- Offering A/B/C-style choices like "proceed / skip a few / dry-run only".
+- Pausing because the queue is large, issues look complex, or issues are likely to be `Blocked` by `lisa:github-agent`'s pre-flight gate. Pre-flight `Blocked` is a valid terminal state of the per-issue lifecycle, not a failure mode.
+- Pausing because the build flow looks expensive.
+
+The only legitimate reasons to stop early:
+
+- Missing repo or required configuration. Surface the missing value and exit.
+- Label namespace not adopted (no issue carries any of `status:ready` / `status:in-progress` / `status:code-review` / `status:on-dev` / `status:done`). Surface a label-convention error and exit (this is setup, not a normal idle cycle — see "Adoption" at the bottom).
+- Empty `status:ready` set. Exit cleanly with `"No GitHub issues labeled status:ready in <org>/<repo>. Nothing to do."`
+
+## Lifecycle assumed
+
+The GitHub Issues build lifecycle uses **labels** (we deliberately do NOT key off open/closed alone — closed issues aren't always the right post-build state):
+
+```text
+status:ready → status:in-progress → status:code-review → status:on-dev → status:done
+   (human)       (us claim)            (us / PR opens)        (us done; PR ready)   (downstream / merge)
+```
+
+This skill ONLY transitions:
+
+- `status:ready` → `status:in-progress` (claim)
+- `status:in-progress` → `status:on-dev` (build complete, PR ready)
+
+It never touches `status:code-review` (set by the agent / PR open hook), `status:done` (set by merge automation or PM), or any other status.
+
+A "transition" means: remove the old `status:*` label and add the new one, in two `gh issue edit` calls (`--remove-label` + `--add-label`) or one combined call. The skill MUST verify exactly one `status:*` label is present after the update — having two simultaneously breaks idempotency.
+
+**Pre-flight check**: at the start of each cycle, confirm at least one of the `status:*` labels exists on the repo via `gh label list --repo <org>/<repo> --json name`. If none exist, the convention has not been adopted — surface the label-convention error and exit.
+
+## 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` (`github.org`, `github.repo`); error if not set.
+2. Confirm `gh auth status` succeeds.
+3. Confirm the repo is reachable: `gh repo view <org>/<repo> --json name --jq '.name'`.
+
+### Phase 2 — Find Ready issues
+
+```bash
+gh issue list --repo <org>/<repo> --label status:ready --state open --json number,title,labels,assignees,milestone,createdAt --limit 100
+```
+
+If empty, run a secondary check to distinguish a genuinely empty queue from an unconfigured repo:
+
+```bash
+gh label list --repo <org>/<repo> --json name --jq '.[] | select(startswith("status:")) | .name'
+```
+
+If no `status:*` labels exist → label namespace not adopted, surface a setup error and exit. If `status:*` labels exist but none are `status:ready` on any open issue → genuinely empty queue, exit cleanly with `"No GitHub issues labeled status:ready. Nothing to do."`
+
+### Phase 3 — Process each Ready issue (serial)
+
+#### 3a. Claim
+
+```bash
+gh issue edit <number> --repo <org>/<repo> --remove-label status:ready --add-label status:in-progress
+gh issue comment <number> --repo <org>/<repo> --body "[claude-build-intake] Claimed by Claude. Starting build."
+```
+
+This is the idempotency lock — a re-entrant cycle's `--label status:ready` filter will not see this issue again.
+
+If the relabel fails (permission, race), log under "Errors" in the cycle summary and skip this issue. **Do not invoke the build flow on an issue you didn't successfully claim.**
+
+#### 3b. Run the build flow
+
+Invoke `lisa:github-agent` (the per-issue lifecycle agent) with the issue ref. `lisa:github-agent` owns:
+- Reading the full issue graph (`lisa:github-read-issue`)
+- Running its own pre-flight quality gate (`lisa:github-verify`)
+- Running issue triage (`lisa:ticket-triage`)
+- Routing to the appropriate flow (Build / Fix / Investigate / Improve based on `type:` label)
+- Posting progress comments via `lisa:github-sync`
+- Posting evidence via `lisa:github-evidence`
+
+Wait for `lisa:github-agent` to return. Capture its outcome:
+
+- **Success** — PR is ready (open or merged); evidence posted; ready for next status.
+- **Blocked by github-verify pre-flight gate** — `lisa:github-agent` itself relabels the issue to `status:blocked` (or removes `status:in-progress` and reassigns to the original author). This is correct and expected — let it stand. Record and move on.
+- **Blocked by ticket-triage ambiguities** — `lisa:github-agent` posts findings and stops. The issue stays in `status:in-progress`. Surface to human; do not auto-relabel. Record under "Errors".
+- **Errored** — exception, missing config, etc. Leave the issue in `status:in-progress` for human investigation. Record under "Errors".
+
+#### 3c. Transition to On Dev (only on Success)
+
+If `lisa:github-agent` returned Success:
+
+```bash
+gh issue edit <number> --repo <org>/<repo> --remove-label status:in-progress --add-label status:on-dev
+gh issue comment <number> --repo <org>/<repo> --body "[claude-build-intake] Build complete. PR <URL>. Transitioned to status:on-dev."
+```
+
+For any non-Success outcome, do NOT transition. The issue sits in `status:in-progress` (or wherever `lisa:github-agent` left it) — humans take it from there.
+
+#### 3d. Continue
+
+Move to the next Ready issue. One issue failing does not stop others.
+
+### Phase 4 — Summary report
+
+```text
+## github-build-intake summary
+
+Repo: <org>/<repo>
+Cycle started: <ISO timestamp>
+Cycle completed: <ISO timestamp>
+
+Issues processed: <n>
+- status:on-dev (build complete, PR ready): <n>
+  - <org>/<repo>#<number> <title> → PR <URL>
+- Blocked (pre-flight verify failed): <n>
+  - <org>/<repo>#<number> <title> — see issue comments
+- Held (triage found ambiguities): <n>
+  - <org>/<repo>#<number> <title> — see issue comments
+- Errors: <n>
+  - <org>/<repo>#<number> <title> — <reason>
+
+Total PRs opened: <n>
+```
+
+## Idempotency & safety
+
+- **Claim-first ordering**: `status:in-progress` set BEFORE `lisa:github-agent` invocation — no double-pickup.
+- **No writes outside the lifecycle**: this skill only relabels `status:ready → status:in-progress` and `status:in-progress → status:on-dev`. Every other label change is owned by `lisa:github-agent`.
+- **Failure isolation**: per-issue exceptions caught and recorded; the cycle continues.
+- **Single cycle per repo**: do not run two `lisa:github-build-intake` cycles in parallel against the same repo — concurrent claims could race. The scheduling layer is responsible for serialization.
+- **Single-label invariant**: after every transition, verify exactly one `status:*` label is present on the issue. If two are present (rare race), surface as an Error and skip — do NOT auto-resolve.
+
+## Configuration
+
+| Variable | Default | Purpose |
+|----------|---------|---------|
+| `.lisa.config.json` `github.org` | (from `$ARGUMENTS`) | GitHub org for the default queue |
+| `.lisa.config.json` `github.repo` | (from `$ARGUMENTS`) | GitHub repo for the default queue |
+| Label: queue | `status:ready` | The label that signals "human says this is buildable" |
+| Label: claim | `status:in-progress` | The label set on pickup |
+| Label: done | `status:on-dev` | The label set after a successful build |
+
+If the repo has not adopted the `status:*` label namespace, this skill cannot run. The remediation is to create the labels — `gh label create status:ready --color FBCA04 --description "Ready for build"` and similar — typically a one-time setup.
+
+## Rules
+
+- Never relabel an issue the cycle didn't claim. The `status:in-progress` label is the signature of cycle ownership.
+- Never bypass `lisa:github-agent` to do build work directly. `lisa:github-agent` owns the per-issue lifecycle.
+- Never auto-transition past `status:on-dev`. Downstream labels (`status:done`, etc.) are owned by QA / PM / merge automation.
+- If the issue has no Validation Journey or no sign-in credentials, `lisa:github-agent`'s pre-flight verify will catch it — **don't try to fix the issue from here**.
+- On any unexpected response from `lisa:github-agent` (status it doesn't claim, missing PR URL on success), record as Error and surface — never assume.
+
+## Adoption (one-time per repo)
+
+Before this skill can run, the repo must adopt the `status:*` label namespace:
+
+1. Create the labels:
+   ```bash
+   gh label create status:ready --color FBCA04 --description "Ready for build" --repo <org>/<repo>
+   gh label create status:in-progress --color 0E8A16 --description "Build in progress" --repo <org>/<repo>
+   gh label create status:code-review --color 5319E7 --description "PR open, awaiting review" --repo <org>/<repo>
+   gh label create status:on-dev --color 1D76DB --description "Built, deployed to dev" --repo <org>/<repo>
+   gh label create status:done --color 0E8A16 --description "Shipped" --repo <org>/<repo>
+   ```
+2. Apply `status:ready` to issues that are ready for development.
+3. Reserve `status:in-progress`, `status:on-dev` for this skill — humans should not set them manually except to recover from an error.
+4. PRD-source labels (`prd-ready`, `prd-in-review`, etc.) are a SEPARATE namespace owned by `lisa:github-prd-intake`. Don't conflate.

package/plugins/src/base/skills/github-create/SKILL.md

@@ -0,0 +1,101 @@
+---
+name: github-create
+description: This skill should be used when creating GitHub Issue Epics, Stories, and Sub-tasks from code files or descriptions. It analyzes the provided input, determines the appropriate issue hierarchy, and creates issues with comprehensive quality requirements including test-first development and documentation. The GitHub counterpart of lisa:jira-create.
+allowed-tools: ["Read", "Glob", "LS", "Skill", "Bash"]
+---
+
+# Create GitHub Issues from $ARGUMENTS
+
+Analyze the provided file(s) and plan a GitHub Issue hierarchy. **This skill plans structure only — every individual issue write is delegated to `lisa:github-write-issue` (which itself goes through the `lisa:tracker-write` shim when invoked from a vendor-neutral caller).** Do not call `gh issue create` from this skill; the necessary write invocations belong to the writer skill so the gates can never be bypassed.
+
+## Process
+
+1. **Analyze**: Read `$ARGUMENTS` to understand scope.
+2. **Extract source artifacts**: invoke the `lisa:jira-source-artifacts` skill (vendor-neutral), then enumerate every external URL, embed, attachment, or example payload in the input and classify each by domain per its rules. Build the `artifacts` map (one entry per artifact: url, title, domain, source page, classification reason).
+3. **Walk the live product** (when applicable): if the work touches existing user-facing surfaces, invoke the `lisa:product-walkthrough` skill.
+4. **Determine structure**:
+   - Epic needed if: multiple features, major changes, >3 related files.
+   - Direct Tasks if: bug fix, single file, minor change.
+5. **Plan hierarchy**:
+
+   ```text
+   Epic → Story → Sub-tasks (test, implement, document, cleanup)
+   ```
+
+6. **Delegate every write to `lisa:github-write-issue`** in dependency order (Epic first, then Stories with the Epic as parent sub-issue, then Sub-tasks with their Story as parent). Pass artifacts (filtered by domain per `lisa:jira-source-artifacts` inheritance rules) and walkthrough findings (under `## Current Product`).
+7. **Run the artifact preservation gate** (`lisa:jira-source-artifacts` §8): after all writes complete, build the preservation matrix and verify every extracted artifact is reachable from the created issues. Fail loudly if anything was dropped.
+
+## Mandatory for Every Code Issue
+
+**Test-First**: Write tests before implementation
+**Quality Gates**: All tests/checks must pass, no SonarCloud violations
+**Documentation**: Check existing, update/create new, remove obsolete
+**Cleanup**: Remove temporary code, scripts, dev configs
+
+## Validation Journey
+
+Issues that change runtime behavior should include a `## Validation Journey` section. This section is consumed by `lisa:github-journey` to automate verification. Use `lisa:github-add-journey` to draft + append the section after creation.
+
+## Source Artifacts
+
+If `$ARGUMENTS` references any external artifact — PRD, design doc, Figma URL, Lovable prototype, Loom walkthrough, screenshot, example payload — those references MUST be preserved as `## Links` and `## Source Artifacts` sections on the created issues. Silent artifact loss is the single most common quality failure in this pipeline.
+
+**Invoke `lisa:jira-source-artifacts`** for the canonical rules: domains, per-tool classification, source precedence, conflict handling under `## Open Questions`, inheritance from epic → story → sub-task, and the existing-component reuse expectation. This skill is vendor-neutral and used by both the JIRA and the GitHub paths.
+
+When delegating actual writes to `lisa:github-write-issue`, pass the extracted artifact list so its Phase 4c (Remote Links / Source Artifacts) step attaches them.
+
+## Live Product Walkthrough
+
+When the work touches existing user-facing surfaces, invoke `lisa:product-walkthrough` before drafting issues. The findings become inputs to the issue plan and surface under `## Current Product` on the resulting issues.
+
+## Issue Requirements
+
+Each issue must clearly communicate to:
+
+- **Coding Assistants**: Implementation requirements
+- **Developers**: Technical approach
+- **Stakeholders**: Business value
+
+Default repo: from `.lisa.config.json` `github.org` / `github.repo` (override via arguments).
+
+## Delegation to github-write-issue
+
+**Mandatory.** Every issue created by this skill MUST go through `lisa:github-write-issue`. This skill never calls `gh issue create` itself — that invocation belongs to the writer.
+
+`lisa:github-write-issue` enforces:
+- 3-audience description (Context / Technical Approach / Acceptance Criteria)
+- Gherkin acceptance criteria
+- Parent sub-issue validation (non-bug, non-epic types)
+- Explicit relationship discovery (`Blocks` / `Blocked by` / `Relates to` / `Duplicates` / `Cloned from`)
+- Remote links (PRs, Confluence, dashboards)
+- Single-repo scope check for Bug / Task / Sub-task
+- Sign-in account and target environment recorded in body
+- Post-create verification
+
+### Invocation order
+
+Issues must be created in parent-before-child order:
+
+1. Invoke `lisa:github-write-issue` for the Epic. Capture the returned issue number.
+2. For each Story, invoke `lisa:github-write-issue` with the Epic ref as `parent_ref`. Capture each Story number.
+3. For each Sub-task, invoke `lisa:github-write-issue` with the Story ref as `parent_ref`.
+
+### What to pass to each invocation
+
+For every delegated write, pass:
+- The summary, issue type, repo (org/repo), and priority you decided
+- The body with all sections drafted (Context / Technical Approach / Acceptance Criteria / Out of Scope / etc.)
+- Gherkin acceptance criteria
+- `parent_ref` (Epic ref for Stories; Story ref for Sub-tasks)
+- The artifact list extracted in "Source Artifacts", filtered by domain per the inheritance rules — `lisa:github-write-issue` Phase 4c attaches them
+- For runtime-behavior issues: instruct the writer to call `lisa:github-add-journey` after create
+
+### What this skill is responsible for
+
+- Deciding the *shape* of the hierarchy (what's an Epic vs. Story vs. Sub-task).
+- Drafting the body and acceptance criteria from the input.
+- Extracting and classifying source artifacts.
+- Threading parent refs through subsequent writes.
+- Running the preservation check after all writes complete.
+
+It does not own the actual `gh issue create` call — that's `lisa:github-write-issue`'s job.

package/plugins/src/base/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/src/base/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.