@codyswann/lisa 4.74.9 → 4.75.0

package/plugins/lisa-devin/skills/lisa-linear-create/SKILL.md

@@ -0,0 +1,150 @@
+---
+name: lisa-linear-create
+description: "Creates Linear Projects (Epic-equivalent), Issues (Story / Task / Bug / Spike), and sub-Issues (Sub-task) from code files or descriptions. Analyzes the input, determines the appropriate hierarchy, and creates items with comprehensive quality requirements including test-first development and Validation Journey. The Linear counterpart of lisa-jira-create — delegates every write to lisa-linear-write-issue."
+allowed-tools: ["Read", "Glob", "LS", "Skill"]
+---
+
+# Create Linear Work Items from $ARGUMENTS
+
+Analyze the provided file(s) and plan a Linear hierarchy. **This skill plans structure only — every individual write is delegated to `lisa-linear-write-issue`.** Do not call `lisa-linear-access operation: save-project` or `lisa-linear-access operation: save-issue` from this skill; those write tools are intentionally not in `allowed-tools`.
+
+This skill is the destination of the `lisa-tracker-create` shim when `tracker = "linear"`.
+
+## Configuration
+
+Reads `linear.workspace`, `linear.teamKey` from `.lisa.config.json` (with `.local` override).
+
+## Process
+
+1. **Analyze**: Read `$ARGUMENTS` to understand scope.
+2. **Extract source artifacts**: invoke `lisa-tracker-source-artifacts`, then enumerate every external URL, embed, attachment, or example payload in the input and classify each by domain. Build the `artifacts` map (one entry per artifact: url, title, domain, source page, classification reason). See "Source Artifacts" below.
+3. **Walk the live product** (when applicable): if the work touches existing user-facing surfaces, invoke `lisa-product-walkthrough` to capture current behavior, design-vs-product divergence, and reuse candidates. Skip when the work is purely backend or affects a screen that does not yet exist.
+4. **Determine structure**:
+   - Project (Epic) needed if: multiple features, major changes, >3 related files
+   - Direct Issues if: bug fix, single file, minor change
+5. **Plan hierarchy**:
+   ```text
+   Project (Epic) → Issue (Story) → sub-Issue (Sub-task)
+   ```
+   Mapping per Linear best practices: Epic → Linear Project, Story → Issue with `projectId`, Sub-task → Issue with `parentId`. See `config-resolution.md` "Linear destination semantics".
+6. **Delegate every write to `lisa-linear-write-issue`** in dependency order (Project first, then Issues with `projectId` set, then sub-Issues with `parentId`). Pass artifacts (filtered by domain per `lisa-tracker-source-artifacts` inheritance rules) and walkthrough findings (under `## Current Product`).
+7. **Run the artifact preservation gate** (`lisa-tracker-source-artifacts` §8): after all writes complete, build the preservation matrix and verify every extracted artifact is reachable from the created items. 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
+
+Items that change runtime behavior should include a `## Validation Journey` section. This section is consumed by `lisa-linear-journey` to automate verification.
+
+### When to Include
+
+- API endpoint changes (new, modified, or removed routes)
+- Database schema changes (migrations, new columns, index changes)
+- Background job / queue processing changes
+- Library / utility function changes that affect exports
+- Security fixes (authentication, authorization, input validation)
+- Performance-critical changes requiring measurement
+
+### When to Skip
+
+- Documentation-only changes
+- Config-only changes (env vars, CI/CD, feature flags with no code)
+- Type-definition-only changes
+
+### How to Write
+
+Design the journey based on the **change type**. Place typed `[EVIDENCE: <artifact-type>: <name>]` markers at key verification points (types: `screenshot`, `recording`, `http-transcript`, `cli-output`, `log-snippet`, `db-query-output`, `perf-trace`, `test-run-log`, `deploy-log`, `state-dump` — see the `verification` rule).
+
+To point at evidence owned by another work item, use exactly `[EVIDENCE-REF: <work-item-ref> | <artifact-type>: <kebab-case-name>]`. It is non-claiming and cannot satisfy S14; never paste or quote the sibling's `[EVIDENCE: ...]` marker into this item.
+
+```markdown
+## Validation Journey
+
+### Prerequisites
+- Local dev server running
+- Database accessible
+- Required environment variables set
+
+### Steps
+1. Verify the current state before changes
+2. Apply the change (run migration, deploy, etc.)
+3. Verify the expected new state [EVIDENCE: http-transcript: state-after-change]
+4. Test error/edge cases [EVIDENCE: screenshot: error-state-rendered]
+5. Verify rollback or cleanup if applicable [EVIDENCE: db-query-output: rows-restored-after-rollback]
+
+### Assertions
+- Describe what must be true after verification
+- Each assertion is verified against the captured evidence
+```
+
+## Source Artifacts
+
+If `$ARGUMENTS` includes (or references) any external artifact — PRD, design doc, Figma URL, Lovable prototype, Loom walkthrough, screenshot, example payload — those references MUST be preserved as attachments / remote links on the created items. Silent artifact loss is the single most common quality failure in this pipeline.
+
+**Invoke `lisa-tracker-source-artifacts`** for the canonical rules: domains, per-tool classification, source precedence, conflict handling under `## Open Questions`, inheritance from Project → Issue → sub-Issue, and the existing-component reuse expectation. Do not restate the rules here — invoke the skill so any rule change propagates uniformly.
+
+When delegating actual writes to `lisa-linear-write-issue`, pass the extracted artifact list so its Phase 4c (Remote Links) step can attach them.
+
+## Live Product Walkthrough
+
+When the work touches existing user-facing surfaces, invoke `lisa-product-walkthrough` before drafting items. The walkthrough findings (current behavior, design-vs-product divergence, reuse candidates, behavioral surprises) become inputs to the item plan and surface under `## Current Product` on the resulting items. Skip only when the work is purely backend or affects a screen that does not yet exist.
+
+## Item Requirements
+
+Each item must clearly communicate to:
+
+- **Coding Assistants**: Implementation requirements
+- **Developers**: Technical approach
+- **Stakeholders**: Business value
+
+Default team: from `linear.teamKey` config (override via arguments).
+
+## Delegation to linear-write-issue
+
+**Mandatory.** Every item created by this skill MUST go through `lisa-linear-write-issue`. This skill never performs Linear save operations itself — those tools are intentionally excluded from `allowed-tools` so the gate cannot be bypassed.
+
+`lisa-linear-write-issue` enforces:
+- 3-audience description (Context / Technical Approach / Acceptance Criteria)
+- Gherkin acceptance criteria
+- Project parent for Stories; parentId for Sub-tasks
+- Explicit relationship discovery (`blocks` / `blocked_by` / `relates_to` / `duplicates`)
+- Remote links / attachments
+- Single-repo scope check for Bug / Task / Sub-task
+- Sign-in account and target environment recorded in description
+- Post-create verification
+
+### Invocation order
+
+Items must be created in parent-before-child order so each child can be passed its parent ID:
+
+1. Invoke `lisa-linear-write-issue` for the Epic (Project). Capture the returned Project ID.
+2. For each Story, invoke `lisa-linear-write-issue` with the Project ID as `parent_project_id`. Capture each Issue identifier.
+3. For each Sub-task, invoke `lisa-linear-write-issue` with the Story Issue ID as `parent_issue_id` and explicit `build_ready: true`.
+
+- **Declare readiness on every leaf write.** Per the `ready-role-filing` rule an omitted `build_ready` is **not build-ready** on any tracker, so pass `build_ready: true` on each Sub-task (the leaf work units this skill plans) and never on the Epic or Stories, which are containers per `leaf-only-lifecycle`. A leaf that is deliberately held instead passes `human_gate: "<why a human must judge this first>"`. Filing a leaf with neither is an incomplete handoff and `lisa-linear-write-issue` rejects it.
+
+### What to pass to each invocation
+
+For every delegated write, pass:
+- The summary, issue type, team key, and priority you decided
+- The 3-section description body you drafted (Context / Technical Approach / Acceptance Criteria)
+- Gherkin acceptance criteria
+- Parent ID (Project for Stories; Story for Sub-tasks)
+- The artifact list extracted in "Source Artifacts", filtered by domain per the inheritance rules
+- For items that change runtime behavior: the Validation Journey draft (or instruct it to call `lisa-linear-add-journey` after create)
+
+### What this skill is responsible for
+
+This skill owns:
+- Deciding the *shape* of the hierarchy (what's a Project vs. Issue vs. sub-Issue)
+- Drafting the description body and acceptance criteria from the input
+- Extracting and classifying source artifacts
+- Threading parent IDs through subsequent writes
+- Running the Phase 5.5-style preservation check after all writes complete
+
+It does not own the actual Linear write — that's `lisa-linear-write-issue`'s job.

package/plugins/lisa-devin/skills/lisa-linear-evidence/SKILL.md

@@ -0,0 +1,124 @@
+---
+name: lisa-linear-evidence
+description: "Uploads text evidence to the GitHub `pr-assets` release, updates the PR description, posts a comment on the originating Linear Issue with code blocks, and transitions the Issue from the configured `claimed` workflow state to the configured `review` workflow state. Reusable by any skill that captures evidence and generates evidence/comment.txt + evidence/code-blocks.md. Linear counterpart of lisa-jira-evidence and lisa-github-evidence."
+allowed-tools: ["Bash", "Skill"]
+---
+
+# Linear Evidence: $ARGUMENTS
+
+Post verification evidence to a Linear Issue and transition it from the configured `claimed` workflow **state** to the configured `review` workflow **state**. Linear's build lane is state-driven, not label-driven — `linear.labels.build.{ready,claimed,review,done}` is inert and nothing reads it (see `lisa-validate-tracker-mapping`). This skill is the destination of the `lisa-tracker-evidence` shim when `tracker = "linear"`.
+
+`$ARGUMENTS` is the Linear Issue identifier (e.g. `ENG-123`) and the path to the evidence directory. Caller passes both: `<IDENTIFIER> <evidence-dir>`.
+
+## Workflow resolution
+
+Resolve every lifecycle role through the shared resolver — never an inlined `read_role` helper. Twelve skills used to inline their own and produced **eleven different implementations**, which is how the vendors drifted apart on this exact contract.
+
+```bash
+resolve() {  # role, intent -> value on stdout; empty when an optional role is unset
+  node "${CLAUDE_PLUGIN_ROOT}/scripts/resolve-lifecycle-role.mjs" \
+    --role "$1" --vendor linear --intent "${2:-read}"
+}
+
+CLAIMED=$(resolve claimed write) || {
+  echo "ERROR: failed to resolve the required Linear claimed role" >&2
+  exit 1
+}
+[ -n "$CLAIMED" ] || {
+  echo "ERROR: the required Linear claimed role resolved empty" >&2
+  exit 1
+}
+REVIEW=$(resolve review write) || {
+  echo "ERROR: failed to resolve the optional Linear review role" >&2
+  exit 1
+}
+```
+
+**`review` is OPTIONAL and has no default.** An empty `REVIEW` means the project does not run an agent review step, and this skill **skips the transition entirely**, leaving the Issue in `claimed` — the same behaviour `lisa-jira-evidence/scripts/post-evidence.sh` has always had. Do not substitute `In Review`, and do not fall back to a state resolved by `type` or board position: a fallback may inform a read but must never supply a write target (`config-resolution`, R2). Resolving a state nobody configured is how agents reach human-only review lanes.
+
+## Configuration
+
+Reads `linear.workspace`, `linear.teamKey`, and `linear.workflow.*` from `.lisa.config.json` (with `.local` override).
+
+## Inputs (in `<evidence-dir>`)
+
+The caller must produce:
+
+- `evidence/comment.txt` — the human-readable comment body posted on the Linear Issue.
+- `evidence/code-blocks.md` — fenced code blocks (test outputs, command output, log excerpts) appended to the comment.
+- `evidence/files/` (optional) — any text files that should be uploaded to the GitHub `pr-assets` release for permalink-style references.
+
+If any of these are missing, stop and report.
+
+## Comment-body preflight (required)
+
+Before posting or updating anything, check the evidence body (`comment.md`, and `comment.txt` where this skill uses it):
+
+- It contains a `## Not established` heading. That heading is **never omitted and never blank** — when nothing is outstanding it still renders `None outstanding — reviewed`; otherwise it names, in plain operator language, what the verification did not prove.
+- The accompanying verdict carries `not_established_reviewed: true` (the list may be empty; the flag may never be omitted).
+- It contains a `## Artifact identity` heading carrying **values, not placeholders** — the repository, the `head_sha` the verification observed, the `environment`, and per artifact its `sha256` digest and `captured_at`. **Refuse to post** a body whose identity heading is absent or unpopulated, or whose recorded `artifact_head_sha` disagrees with the verdict's `artifact.head_sha` — report the evidence id and **both SHAs**. Definition: the `claim-evidence-mapping` rule.
+
+If either is missing, **refuse to post**: stop and report the missing Not-established review to the caller instead of publishing. Composing the body is `lisa-tracker-evidence`'s job (see its UI Evidence Checklist); this skill only refuses to publish one that omits the section. The section is defined by the `claim-evidence-mapping` rule and generalizes `lisa-improve-harness`'s required, never-empty `Known limits` field.
+
+## Phase 1 — Resolve Linear Issue
+
+1. Parse the identifier from `$ARGUMENTS`.
+2. Fetch via `lisa-linear-access operation: get-issue` to confirm it exists and capture its current state, label set, and Project membership.
+
+## Phase 2 — Upload Evidence Files (optional)
+
+If `evidence/files/` is non-empty, upload each text file to the GitHub `pr-assets` release on the current repo via `gh release upload`. The release is the permalink store — keeps the Linear comment lightweight while preserving large outputs.
+
+For each uploaded file, capture the public release URL.
+
+## Phase 3 — Update PR Description
+
+If a PR is open on the current branch (`gh pr view --json url,number,body 2>/dev/null`), append an "Evidence" section to its description with:
+
+- The Linear identifier and URL (constructed as `https://linear.app/<workspace>/issue/<IDENTIFIER>`).
+- Links to any uploaded evidence files.
+- A short summary line (first 2 lines of `evidence/comment.txt`).
+
+If no PR is open, skip this phase.
+
+## Phase 4 — Post Linear Comment
+
+Call `lisa-linear-access operation: save-comment({issueId: <id>, body: <body>})` where `<body>` is:
+
+```markdown
+[<comment.txt contents verbatim>]
+
+<details>
+<summary>Evidence</summary>
+
+[<code-blocks.md contents verbatim>]
+
+</details>
+
+[<bullet list of uploaded evidence file URLs, if any>]
+```
+
+Linear comments support markdown including `<details>` collapsibles, fenced code, and links — preserve the formatting.
+
+## Phase 5 — Transition Status
+
+**If `$REVIEW` is empty, skip this phase entirely** — post the evidence comment and leave the Issue in `$CLAIMED`. Report it plainly (`No linear.workflow.review configured; leaving <ID> in its current (claimed) state`) so the skip is visible rather than silent. This is a supported configuration, not a failure.
+
+When `$REVIEW` is non-empty, invoke `lisa-linear-access operation: save-issue lifecycle_role: review`. That is the whole transition: the Linear build lane is the native workflow **state**, so there is no accompanying label move — do not remove a `claimed` label or add a `review` one, and do not create either. Those keys are inert.
+
+The access layer resolves `$REVIEW`'s exact configured state itself and dispatches that ID; this skill never hands it one. Never resolve the state by searching the team for something review-shaped: on a board with more than one review-ish state that picks by position, not by intent, and the states most likely to be found that way are the human-only ones a project deliberately kept out of its config. The access layer refuses such a write outright — an unbound optional `review` is a refusal there, not a guess.
+
+## Phase 6 — Report
+
+Return:
+
+- Linear Issue URL with its new workflow state
+- PR URL (if updated)
+- List of uploaded evidence file URLs
+
+## Rules
+
+- Never modify the Issue description as part of evidence posting — comments only. Description edits go through `lisa-linear-write-issue`.
+- Never skip the transition when `review` is configured. An empty `$REVIEW` is the one sanctioned skip (Phase 5): post the evidence comment, leave the Issue in `$CLAIMED`, and report the skip. Whenever `$REVIEW` is non-empty, the configured native state transition is mandatory.
+- If `lisa-linear-access operation: save-comment` fails, retry once. If it fails again, surface the error — don't pretend the comment was posted.
+- Do not delete prior comments. The history is the audit trail.

package/plugins/lisa-devin/skills/lisa-linear-journey/SKILL.md

@@ -0,0 +1,147 @@
+---
+name: lisa-linear-journey
+description: "Parse a Linear Issue's Validation Journey section, execute the verification steps using appropriate tools (curl, test commands, database queries, Playwright), capture evidence at each typed [EVIDENCE: <artifact-type>: <name>] marker, and post to Linear + GitHub PR using the linear-evidence skill. Linear counterpart of lisa-jira-journey."
+allowed-tools: ["Bash", "Read", "Glob", "Grep", "Skill"]
+---
+
+# Linear Validation Journey
+
+Parse a Linear Issue's Validation Journey, execute the verification steps using the appropriate tools for the change type, capture evidence at each typed `[EVIDENCE: <artifact-type>: <name>]` marker, and post to Linear + GitHub PR.
+
+This skill is the destination of the `lisa-tracker-journey` shim when `tracker = "linear"`.
+
+## Configuration
+
+Reads `linear.workspace`, `linear.teamKey` from `.lisa.config.json` (with `.local` override).
+
+## Arguments
+
+`$ARGUMENTS`: `<IDENTIFIER> [PR_NUMBER]`
+
+- `IDENTIFIER` (required): Linear Issue identifier (e.g. `ENG-123`)
+- `PR_NUMBER` (optional): GitHub PR number to update description
+
+## Prerequisites
+
+- Linear MCP authenticated
+- `gh` CLI authenticated
+- Appropriate services running for the verification type (dev server, database, etc.)
+
+## Workflow
+
+### Step 1: Parse the Validation Journey
+
+Fetch the Issue via `lisa-linear-access operation: get-issue` and extract the `## Validation Journey` section from the markdown description. Parse:
+
+- `### Prerequisites` — list of required services / env / setup
+- `### Steps` — numbered steps, each potentially containing typed `[EVIDENCE: <artifact-type>: <name>]` markers
+- `### Assertions` — what must be true after verification
+
+If the section is missing or has no steps, report `"No Validation Journey on <IDENTIFIER>. Run /linear-add-journey first."` and stop.
+
+### Step 2: Satisfy Prerequisites
+
+Before executing steps, verify each prerequisite:
+
+1. Required services running (dev server, database, queue worker)
+2. Database connectivity if needed
+3. Environment variables set
+4. Run any setup commands mentioned in prerequisites
+
+Stop and report if any prerequisite is not satisfied.
+
+### Step 3: Execute Steps and Capture Evidence
+
+Execute each step sequentially. Determine the verification approach based on the step text and change type:
+
+- **API endpoints** → Run curl commands, capture HTTP response to `evidence/NN-name.txt` (or `.json` for structured data)
+- **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
+- **UI / frontend** → Playwright browser flow, capture screenshots / DOM state
+
+At each typed `[EVIDENCE: <artifact-type>: <name>]` marker, capture an artifact **of the declared type** — the type is the contract, not a suggestion:
+
+- `screenshot` / `recording` → an actual image/video file from the driven UI (Playwright, simulator), never a text description of what was seen
+- `http-transcript` → the exact request (curl command or client call) plus the full response
+- `cli-output` → the command plus stdout/stderr and exit code
+- `log-snippet` → the correlated log lines pulled from the running system
+- `db-query-output` → the query plus returned rows
+- `perf-trace` → the benchmark/frame-timing/profiler output with methodology (device profile, dataset size)
+- `test-run-log` → reporter output naming the spec and showing it ran and passed
+- `deploy-log` / `state-dump` → the deployment/health-check output or observed-state JSON
+
+A prose claim ("the error state rendered gracefully") satisfies no marker. Legacy untyped markers: infer the type from the step's action, capture accordingly, and note the inference. Write each artifact to a numbered file:
+
+Treat only exact `[EVIDENCE: ...]` markers (plus the legacy local `[SCREENSHOT: ...]` form) as capture instructions. Both the canonical `[EVIDENCE-REF: <work-item-ref> | <artifact-type>: <kebab-case-name>]` and the Lisa 2.223.0 legacy alias `[EVIDENCE-REF: <tracker-ref>: <artifact-type>: <kebab-case-name>]` point to another work item's artifact: preserve either as explanatory text, but do not capture it, assign it a sequence number, include it in duplicate-name checks, or count it as a local manifest entry. If a runtime-changing leaf has references but no local claiming marker, stop because S14 is unsatisfied.
+
+#### Evidence Naming Convention
+
+`{NN}-{evidence-name}.{ext}`
+
+- `NN`: zero-padded sequential number (`01`, `02`, `03`...)
+- `evidence-name`: the `<name>` part of the typed marker
+- `ext`: `.txt` for plain output, `.json` for structured data
+
+Example:
+
+```text
+evidence/
+  01-health-check.json
+  02-schema-after-migration.txt
+  03-rate-limit-response.txt
+  comment.txt
+  code-blocks.md
+```
+
+### Step 4: Generate Evidence Comment + Code Blocks
+
+After capturing all evidence, build:
+
+- `evidence/comment.txt` — human-readable summary of the verification (Linear comment body, markdown-supported)
+- `evidence/code-blocks.md` — fenced code blocks containing the captured evidence outputs (appended below `comment.txt` inside a `<details>` block)
+
+### Step 5: Post Evidence
+
+Invoke `lisa-linear-evidence` with `<IDENTIFIER> ./evidence` to:
+
+1. Upload large evidence files to the GitHub `pr-assets` release (if files present in `evidence/files/`).
+2. Update the GitHub PR description with an Evidence section (when a PR is open).
+3. Post the Linear comment (`comment.txt` + collapsible `code-blocks.md`).
+4. Transition labels: remove `In Progress`, add `In Review`.
+
+### Step 6: Verify
+
+Confirm:
+- Evidence appears as a comment on the Linear Issue.
+- The PR description shows the Evidence section.
+- The Issue's `status:*` label transitioned to `code-review`.
+
+## Verification Patterns Reference
+
+Use patterns from the project's `verification.md`:
+
+| 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 |
+| UI / frontend | Any capable interactive browser controller (in-app Browser/Chrome, Playwright MCP/API/ad hoc script, CDP, computer use, or equivalent) | Screenshot + DOM |
+
+## 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 `/linear-add-journey <IDENTIFIER>` to add one.
+
+### Label transition fails
+
+Ensure `In Progress` and `In Review` exist on the team. `lisa-linear-evidence` creates them on demand if missing.