@codyswann/lisa 2.119.0 → 2.121.0

package/plugins/lisa-cursor/skills/doctor/SKILL.md

@@ -0,0 +1,317 @@
+---
+name: doctor
+description: "Audit whether the current repository is ready to use Lisa. Runs grouped read-only checks across project detection, Lisa config, runtime distribution surfaces, tracker/source preflight access, automation prerequisites, optional GitHub Project coordination, and optional wiki delegation, then reports PASS/WARN/FAIL/SKIP results plus an overall readiness verdict (`READY`, `READY_WITH_WARNINGS`, or `NOT_READY`)."
+allowed-tools: ["Skill", "Bash", "Read", "Glob", "Grep"]
+---
+
+# Doctor: $ARGUMENTS
+
+Run a read-only Lisa readiness audit for the current repository.
+
+## Purpose
+
+`/lisa:doctor` is the deterministic answer to "is this repo actually ready to use Lisa?" It audits
+the repository in grouped sections, reports each check as `PASS`, `WARN`, `FAIL`, or `SKIP`, and
+emits one overall verdict: `READY`, `READY_WITH_WARNINGS`, or `NOT_READY`.
+
+The command is repository-scoped. It validates only what can be observed from the current repo,
+current machine, and current runtime. It does **not** create automations, labels, tracker items, or
+other external state as part of the default audit path.
+
+## Inputs
+
+- Optional flags in `$ARGUMENTS` that narrow or tune read-only validation.
+- The current repository root and its Lisa config files (`.lisa.config.json`,
+  `.lisa.config.local.json`) when present.
+
+## Confirmation policy
+
+Do **not** ask whether to proceed. Once invoked, run the read-only audit, print the grouped
+results, emit the overall verdict, and stop.
+
+Specifically forbidden:
+
+- Previewing the number of checks and asking whether to continue.
+- Offering "run a few checks first" or "dry-run vs real run" choices. This skill is already the
+  read-only path.
+- Performing setup mutations just because a failing check discovered something missing.
+
+The only legitimate reasons to stop early are:
+
+- The current working directory cannot be resolved to a repository/root the audit can inspect.
+- The runtime blocks all required local reads needed to even classify the repo.
+
+## Audit contract
+
+Doctor reports grouped checks in a stable, human-readable structure. The grouped sections include,
+as applicable to the current repo:
+
+1. **Project detection and runtime basics** — detect the project root, package/runtime surface, and
+   whether Lisa is installed where the repo expects it.
+2. **Lisa config readiness** — read `.lisa.config.json` and `.lisa.config.local.json` using the
+   same local-overrides-global semantics defined by `config-resolution`; report missing required
+   keys, incompatible combinations, and committed-vs-local locality problems as findings rather
+   than mutating config.
+3. **Tracker/source preflight** — perform read-only readiness checks for the configured `tracker`
+   and `source` only. If a required CLI, MCP surface, or auth context is unavailable in the current
+   runtime, report that explicitly instead of pretending the repo is ready.
+4. **Runtime distribution surfaces** — confirm the command, skill, hook, and related distribution
+   surfaces relevant to this repo are present where Lisa expects them on the active runtime.
+5. **Automation readiness** — inspect whether the configured queue source/tracker and scheduling
+   prerequisites are observable, but do **not** create, edit, or delete automations during doctor.
+6. **Optional GitHub Project coordination** — when `github.projects.v2` is configured, delegate
+   the shared validation read to `github-project-v2` instead of reimplementing ad-hoc GraphQL
+   checks. Honor the `required=false` vs `required=true` semantics documented by
+   `config-resolution`: best-effort failures are `WARN`, required-mode failures are `FAIL`.
+7. **Optional wiki delegation** — when a repo-local `wiki/` exists, either summarize the
+   specialized `lisa-wiki-doctor` verdict or explicitly report that deeper wiki checks are
+   available there. The base doctor stays narrower than full wiki migration enforcement.
+
+If a check family is not applicable to the current repo, report `SKIP` with the reason.
+
+### Minimum config-readiness checks
+
+The Lisa config group is not just "does a file exist?" Doctor must audit the config contract in
+this order:
+
+1. **Presence + parseability**
+   - `FAIL` when `.lisa.config.json` is missing, empty, or invalid JSON.
+   - Read `.lisa.config.local.json` only when present; if present but invalid JSON, `FAIL`.
+2. **Merged effective config**
+   - Resolve every key with the same per-key local-overrides-global semantics documented by
+     `config-resolution`. Doctor must describe findings against the effective merged value, not by
+     pretending one file fully replaces the other.
+3. **Required top-level dispatch keys**
+   - `FAIL` when merged `tracker` is missing or is not one of `jira`, `github`, or `linear`.
+   - `FAIL` when merged `source` is present but is not one of `notion`, `confluence`, `linear`,
+     `github`, or `jira`.
+4. **Vendor required-key audit**
+   - `FAIL` when the configured tracker/source points at a vendor whose required keys are absent
+     after merge. Examples: `tracker=github` requires `github.org` + `github.repo`;
+     `tracker=jira` requires `atlassian.cloudId` + `jira.project`; `source=notion` requires
+     `notion.workspaceId` + `notion.prdDatabaseId`.
+   - Reuse the `config-resolution` vendor tables rather than inventing a second required-key list.
+5. **Local-vs-committed locality audit**
+   - `WARN` when developer-specific fields appear in committed config. At minimum enforce the
+     documented local-only examples: `atlassian.email`, `intake.assignee`, and
+     `jira.verified_workflow_hash`.
+   - `WARN` when project-wide shared fields exist only in `.lisa.config.local.json` and are absent
+     from `.lisa.config.json`, because the current machine may work while the repository remains
+     under-configured for teammates and automations. Examples include `tracker`, `source`,
+     `github.org`, `github.repo`, `atlassian.cloudId`, `atlassian.site`, `jira.project`,
+     `linear.workspace`, `linear.teamKey`, and `deploy.branches`.
+
+Locality findings are advisory unless the merged config is unusable. Missing shared keys after the
+merge are `FAIL`; shared keys that exist only locally are `WARN`.
+
+### Minimum tracker/source preflight checks
+
+After config readiness passes far enough to resolve the merged `tracker` and optional `source`,
+doctor must perform read-only preflight checks for the configured vendors only. It does not probe
+every vendor Lisa supports.
+
+1. **Scope the audit to configured vendors**
+   - Audit the merged `tracker`.
+   - Audit the merged `source` only when present and distinct from the tracker.
+   - Report every non-configured vendor as `SKIP` rather than pretending it was checked.
+2. **Prove a readable substrate exists**
+   - `tracker=github` or `source=github`: require `gh` CLI availability, a passing `gh auth status`,
+     and a read probe against the configured repo such as `gh repo view <org>/<repo>`.
+   - `tracker=jira`, `source=jira`, or `source=confluence`: follow the `atlassian-access`
+     substrate ladder and prove at least one read-capable path can see the configured
+     `atlassian.cloudId` and vendor scope. Acceptable substrates are `acli`, Atlassian MCP, or the
+     validated API-token/curl path documented by `config-resolution`.
+   - `tracker=linear` or `source=linear`: require either readable Linear MCP access or a valid
+     personal API-key probe against the configured workspace. When Linear is the tracker, doctor
+     must also prove the configured `linear.teamKey` is visible.
+   - `source=notion`: require either a Notion MCP identity match for `notion.workspaceId` or a
+     valid internal-integration token probe, plus read visibility to `notion.prdDatabaseId`.
+3. **Separate missing tooling from missing auth or scope**
+   - Missing executable / MCP substrate availability is a distinct observed fact, not the same as
+     "auth failed."
+   - When a probe runs and fails, preserve the exact read-only failure text or HTTP/GraphQL status
+     in the observed output so the operator can distinguish wrong workspace/site/repo from missing
+     credentials.
+4. **Severity ladder**
+   - `PASS` when at least one supported read-only substrate proves the configured vendor is
+     reachable with the required scope.
+   - `WARN` when the configured vendor is reachable, but an additional optional substrate is
+     unavailable and later Lisa flows would need to fall back.
+   - `FAIL` when no supported substrate can prove read access for the configured tracker/source, or
+     when the configured vendor target is unreadable from the current runtime.
+
+### Minimum GitHub Project coordination checks
+
+When `github.projects.v2` is configured, doctor must run one additional read-only coordination
+check instead of treating the config block as implicitly ready.
+
+1. **Delegate through the shared chokepoint**
+   - Call `lisa:github-project-v2` in read-only resolution mode:
+
+     ```text
+     operation: resolve-project
+     ```
+
+   - Do not inline ad-hoc Project GraphQL in doctor. Setup, doctor, writers, and linked-PR flows
+     must all read the same owner/access contract from the shared utility.
+2. **Preserve exact namespace + access failures**
+   - Enforce the v1 namespace rule exactly as documented by the shared utility. If
+     `github.projects.v2.owner.slug` does not match `github.org`, report:
+
+     ```yaml
+     code: project_namespace_mismatch
+     message: "github.projects.v2.owner.slug must match github.org in v1"
+     remediation: "Use a Project owned by <github.org> or remove github.projects.v2."
+     ```
+
+   - For owner-access or GraphQL failures, preserve the exact GitHub / GraphQL failure text in the
+     observed output. Examples include missing Project, `Resource not accessible by integration`,
+     unsupported owner kind, or a wrong owner/number pair.
+3. **Report exact remediation paths**
+   - Doctor must make the next operator action explicit. At minimum, say whether they need to:
+     1. choose a Project owned by the tracked repo namespace,
+     2. grant the token Project read/write access,
+     3. correct the configured Project number/owner, or
+     4. remove `github.projects.v2` when coordination is not required.
+4. **Map shared utility outcomes into doctor severity**
+   - `required: false` => doctor `WARN`. Repository-local GitHub issue/PR flows remain usable while
+     Project coordination is degraded.
+   - `required: true` => doctor `FAIL`. The same Project validation failure blocks Lisa readiness
+     because coordination was configured as required.
+
+Good output examples:
+
+```text
+WARN github.projects.v2: Resource not accessible by integration
+Observed: exact GitHub / GraphQL failure text preserved from resolve-project.
+Remediation: grant the token Project read/write access or remove github.projects.v2.required.
+Repository-local GitHub issue/PR flows remain usable; Project coordination is disabled.
+```
+
+```text
+FAIL github.projects.v2: github.projects.v2.owner.slug must match github.org in v1
+Remediation: use a Project owned by CodySwannGT or remove github.projects.v2.
+```
+
+### Minimum automation-readiness checks
+
+Doctor's automation-readiness group stays read-only: it audits whether this repo and runtime could
+support `/lisa:setup-automations` and the resulting recurring jobs, but it does **not** create,
+edit, delete, or reconcile automations on the default doctor path.
+
+1. **Resolve the queue inputs exactly as setup-automations would**
+   - Resolve the PRD queue from merged `source`.
+   - Resolve the build queue from merged `tracker`.
+   - Resolve the repair queue from the same queue-detection rules as `lisa:repair-intake`
+     (identical source-dispatch contract to `lisa:intake`).
+   - If any automation would require guessing because `source`, `tracker`, or their vendor keys are
+     still unresolved after the config-readiness audit, report that automation as `FAIL` rather
+     than pretending scheduling can proceed safely.
+2. **Audit the current runtime's native scheduler surface without mutating it**
+   - Codex: doctor should report whether the runtime exposes the native automations surface
+     (`automation_update`) needed by `/lisa:setup-automations`.
+   - Claude: doctor should report whether the runtime exposes `/schedule`.
+   - Other runtimes: doctor should explicitly say that no native Lisa scheduler is known for the
+     current runtime.
+   - This is observability only. Never create a placeholder automation just to prove the scheduler
+     works.
+3. **Check exploratory-automation support by shipped stack surface**
+   - `exploratory-bugs` is supported only when the project ships an `exploratory-qa` command
+     surface (the `expo`, `rails`, or `harper-fabric` stacks today). Reuse the same stack/support
+     rule documented by `setup-automations`; do not invent exploratory jobs for stacks that do not
+     ship that command.
+   - When the repo does not ship `exploratory-qa`, report `exploratory-bugs` as `SKIP` with the
+     reason.
+   - `exploratory-prds` remains applicable when the repo can run `/lisa:project-ideation`; if its
+     queue/config prerequisites are unresolved, report the exact blocking config fact.
+4. **Severity ladder**
+   - `PASS` when an automation's queue inputs are resolvable and the runtime exposes the required
+     native scheduler surface for that automation.
+   - `WARN` when Lisa remains usable manually, but the current runtime has no native scheduler
+     surface for unattended runs, so automation setup would be unavailable from here.
+   - `SKIP` when an optional automation is intentionally unsupported for this repo surface (for
+     example, `exploratory-bugs` on a stack with no `exploratory-qa` command).
+   - `FAIL` when the repo's config cannot resolve the queue that an automation needs, because that
+     would make unattended runs ambiguous or broken before scheduling even starts.
+
+### Minimum wiki-delegation checks
+
+When a repo-local `wiki/` directory exists, doctor must surface the specialized wiki-readiness path
+without turning the base doctor into a second `lisa-wiki-doctor`.
+
+1. **Detect whether wiki delegation applies**
+   - If no repo-local `wiki/` directory exists, report the entire wiki group as `SKIP` with the
+     reason that no wiki surface is present in this repository.
+   - If `wiki/` exists, keep the group present in the final report; do not silently omit it.
+2. **Prefer summary of an existing specialized verdict**
+   - If the repo already has a readable `wiki/state/migration/doctor-report.json`, doctor may
+     summarize the specialized verdict (`READY`, `READY_WITH_WARNINGS`, or `NOT_READY`) plus the
+     most relevant blocking/warning facts, clearly attributing them to `lisa-wiki-doctor`.
+   - Preserve the base doctor's narrower scope: summarize or quote the specialized verdict, but do
+     not inline the full migration/readiness checklist into the base doctor output.
+3. **Otherwise advertise the deeper follow-up explicitly**
+   - If `wiki/` exists but no specialized report is available yet, doctor must still tell the
+     operator that deeper wiki checks live behind `lisa-wiki-doctor`.
+   - The report should make the next action explicit, for example:
+
+     ```text
+     WARN wiki-follow-up: wiki/ detected; deeper wiki migration checks not yet summarized
+     Observed: wiki/ exists, but no wiki/state/migration/doctor-report.json was found.
+     Remediation: run lisa-wiki-doctor to produce the wiki-specific readiness verdict.
+     ```
+4. **Severity ladder**
+   - `SKIP` when `wiki/` is absent.
+   - `PASS` when `wiki/` exists and doctor successfully summarizes an existing
+     `lisa-wiki-doctor` verdict.
+   - `WARN` when `wiki/` exists and doctor can only advertise the specialized follow-up because no
+     persisted wiki verdict is available yet.
+   - `FAIL` only when `wiki/` exists but the repo cannot surface the specialized follow-up at all
+     (for example, the required `lisa-wiki-doctor` distribution surface is missing or the existing
+     report is unreadable/malformed enough that doctor cannot safely summarize it).
+5. **Keep wiki readiness optional for non-wiki repos**
+   - Never require a wiki plugin surface when `wiki/` is absent.
+   - Never let wiki-specific checks downgrade unrelated non-wiki repositories.
+
+## Output contract
+
+The final report must:
+
+- Separate observed facts from remediation advice.
+- Print every check with one of `PASS`, `WARN`, `FAIL`, or `SKIP`.
+- Emit exactly one overall verdict: `READY`, `READY_WITH_WARNINGS`, or `NOT_READY`.
+- Stay read-only by default.
+
+Render the report in grouped sections using the shared `scripts/doctor-report.mjs` contract:
+
+- Start with `Overall verdict: <VERDICT>` and one `Counts:` line covering `PASS`, `WARN`, `FAIL`,
+  and `SKIP`.
+- Then print each group as `<group-id>. <group-title>`.
+- Under each group, print one line per check as `- <STATUS> <check-id>: <summary>`.
+- When available, print `Observed:` and `Remediation:` lines beneath the check so the report keeps
+  facts separate from advice.
+- If a group has no applicable checks yet, render it as a grouped `SKIP` with the reason instead of
+  silently omitting the section.
+
+The verdict ladder is:
+
+- `READY` — no `FAIL` and no `WARN`.
+- `READY_WITH_WARNINGS` — no `FAIL`, but one or more `WARN`.
+- `NOT_READY` — one or more `FAIL`.
+
+## Delegation and reuse
+
+- Reuse `config-resolution` for config and lifecycle role defaults instead of inventing a second
+  schema.
+- Reuse the existing `github-project-v2` chokepoint for GitHub Project coordination checks instead
+  of inlining bespoke access logic.
+- Reuse ideas from `lisa-wiki-doctor` for grouped verdict rendering where they fit, while keeping
+  the Lisa-wide doctor narrower than the wiki-specific migration/readiness workflow.
+
+## Rules
+
+- Never mutate repository, tracker, or automation state on the default doctor path.
+- Never hardcode tracker/source label names outside the documented defaults plus configured
+  overrides from `config-resolution`.
+- Never silently treat an unavailable check surface as success; report `WARN`, `FAIL`, or `SKIP`
+  with the explicit missing dependency.
+- Never turn wiki-specific checks into a requirement for non-wiki repos.

package/plugins/lisa-cursor/skills/epic-triage/SKILL.md

@@ -0,0 +1,28 @@
+---
+name: epic-triage
+description: "9-step epic triage and 5-step implementation workflow. Ensures epics are fully scoped, broken down, and ordered before execution begins."
+---
+
+# Epic Triage
+
+Follow this 9-step triage process before implementing any epic. Do not skip triage.
+
+## Triage Steps
+
+1. Verify you have all information needed to understand the full scope of this epic (goals, acceptance criteria, impacted systems, design specs, dependencies, etc.). Do not make assumptions. If anything is missing, stop and ask before proceeding.
+2. Verify the epic is broken down into concrete, well-scoped bugs, tasks, and/or stories that are each fully triaged. If ambiguities exist, stop and resolve them before breaking it down.
+3. Identify all cross-cutting concerns (auth, performance, security, data migrations, third-party integrations) that need to be addressed across the epic.
+4. Identify all dependencies between tasks within the epic, or on external epics, teams, or services. Determine the correct order of execution.
+5. Verify you have access to the tools, environments, and permissions needed to deploy and verify all tasks within this epic (e.g. CI/CD pipelines, deployment targets, logging/monitoring systems, API access, database access). If any are missing or inaccessible, stop and raise them before proceeding.
+6. Define the overall test strategy for the epic (unit, integration, end-to-end, load testing).
+7. Define the documentation that will need to be created or updated to cover the full scope of the epic so another developer understands the architecture, design decisions, and implementation.
+8. Define measurable acceptance criteria that confirm the epic is fully complete.
+9. Define how you will verify the epic is fully delivered beyond a shadow of a doubt (e.g. deploy to the target environment, walk through all acceptance criteria end-to-end, confirm all child tasks/stories are closed, confirm no regressions).
+
+## Implementation
+
+1. Use the output of the triage steps above as your guide. Do not skip triage.
+2. Work through each task and/or story in the order defined during triage, respecting dependencies.
+3. Apply the Bug Implementation and Task Implementation processes to each child bug or task, respectively, as you work through them.
+4. Continuously update the epic and its child issues in JIRA as progress is made.
+5. Do not consider the epic complete until all acceptance criteria are verified in the target environment and all child issues are resolved.

package/plugins/lisa-cursor/skills/fix-linter-error/SKILL.md

@@ -0,0 +1,45 @@
+---
+name: fix-linter-error
+description: This skill should be used when fixing all violations of one or more ESLint rules across the codebase. It runs the linter, groups violations by rule and file, generates a brief with fix strategies, and creates a plan with tasks to implement the fixes.
+allowed-tools: ["Read", "Bash", "Glob", "Grep"]
+
+---
+
+# Fix Linter Errors
+
+Target rules: $ARGUMENTS
+
+If no arguments provided, prompt the user for at least one lint rule name.
+
+## Step 1: Gather Requirements
+
+1. **Parse rules** from $ARGUMENTS (space-separated)
+2. **Run linter** to collect all violations:
+   ```bash
+   bun run lint 2>&1
+   ```
+3. **Group violations** by rule, then by file, noting:
+   - File path and line numbers
+   - Violation count per file
+   - Sample error messages
+
+## Step 2: Compile Brief and Delegate
+
+Compile the gathered information into a structured brief:
+
+```
+Fix ESLint violations for rules: $ARGUMENTS
+
+Violations by rule:
+- [rule-name-1]: X total violations across Y files
+  - [file]: N violations (lines: ...)
+  - ...
+- [rule-name-2]: X total violations across Y files
+  - ...
+
+Fix strategies: extract functions, early returns, apply formatting, add types
+
+Verification: `bun run lint 2>&1 | grep -E "($ARGUMENTS)" | wc -l` → Expected: 0
+```
+
+Invoke `/implement` with this brief to create the implementation plan.

package/plugins/lisa-cursor/skills/git-commit/SKILL.md

@@ -0,0 +1,48 @@
+---
+name: git-commit
+description: This skill should be used when creating conventional commits for current changes. It groups related changes into logical commits, ensures all files are committed, and verifies the working directory is clean afterward.
+allowed-tools: ["Bash"]
+---
+
+# Git Commit Workflow
+
+Create conventional commits for current changes. Optional hint: $ARGUMENTS
+
+## Workflow
+
+### See what has changed
+
+!git status
+!git diff --stat
+
+### Apply these requirements
+
+1. **Branch Check**: If on `dev`, `staging`, or `main`, create a feature branch named after the changes
+2. **Commit Strategy**: Group related changes into logical conventional commits (feat, fix, chore, docs, etc.)
+3. **Commit ALL Files**: Every file must be assigned to a commit group - no file gets left out or unstaged
+4. **Commit Creation**: Stage and commit each group with clear messages
+5. **Verification**: Run `git status` to confirm working directory is clean - must show "nothing to commit"
+
+### Use conventional commit format
+
+- `feat:` for new features
+- `fix:` for bug fixes
+- `docs:` for documentation
+- `chore:` for maintenance
+- `style:` for formatting
+- `refactor:` for code restructuring
+- `test:` for test additions
+
+### Never
+
+- use `--no-verify` flag
+- attempt to bypass tests or quality checks
+- skip tests or quality checks
+- stash changes - ALL changes must be committed
+- skip or exclude any files from the commit - even if they're unrelated
+- leave uncommitted changes in the working directory
+- ask the user which files to commit - commit everything
+
+## Execute
+
+Execute the workflow now.

package/plugins/lisa-cursor/skills/git-prune/SKILL.md

@@ -0,0 +1,35 @@
+---
+name: git-prune
+description: This skill should be used when pruning local branches that have been deleted on the remote. It fetches remote changes, identifies stale local branches, and safely deletes them.
+allowed-tools: ["Bash"]
+---
+
+# Git Prune Local Branches
+
+Remove local branches whose upstream tracking branches have been deleted on remote.
+
+## Workflow
+
+### Fetch and prune remote-tracking references
+
+!git fetch --prune
+
+### Find and delete stale local branches
+
+!git branch -vv | grep ': gone]' | awk '{print $1}'
+
+### Apply these requirements
+
+1. **Preview**: Show which branches will be deleted before deleting
+2. **Safe Delete**: Use `-d` (safe delete) which refuses to delete unmerged branches
+3. **Report**: Show summary of deleted branches
+
+### Never
+
+- Force delete (`-D`) without user confirmation
+- Delete the current branch
+- Delete protected branches (dev, staging, main)
+
+## Execute
+
+Execute the workflow now.

package/plugins/lisa-cursor/skills/git-submit-pr/SKILL.md

@@ -0,0 +1,105 @@
+---
+name: git-submit-pr
+description: This skill should be used when pushing changes and creating or updating a pull request. It verifies the branch state, pushes to remote, creates or updates a PR with a comprehensive description, optionally coordinates the resulting Pull Request into the configured GitHub ProjectV2, and enables auto-merge.
+allowed-tools: ["Bash", "Skill", "mcp__github__create_pull_request", "mcp__github__get_pull_request", "mcp__github__update_pull_request"]
+---
+
+# Submit Pull Request Workflow
+
+Push current branch and create or update a pull request. Optional hint: $ARGUMENTS
+
+Recognized optional hints:
+
+- `work_item_ref=<ref>` — source tracker item for native development linkage. Examples: `CodySwannGT/lisa#614`, `https://github.com/CodySwannGT/lisa/issues/614`, `ENG-123`, `PROJ-456`.
+- `target_branch=<branch>` or `base=<branch>` — intended PR base branch, used to decide whether a GitHub closing keyword is safe.
+- `tracker_provider=<github|linear|jira|none>` — explicit provider when the ref shape is ambiguous.
+
+## Workflow
+
+### Check current state
+
+!git status
+!git log --oneline -10
+
+### Apply these requirements
+
+1. **Branch Check**: Verify not on `dev`, `staging`, or `main` (cannot create PR from protected branches)
+2. **Commit Check**: Ensure all changes are committed before pushing
+3. **Push**: Push current branch to remote with `-u` flag and the following environment variable - GIT_SSH_COMMAND="ssh -o ServerAliveInterval=30 -o ServerAliveCountMax=5"
+4. **PR Management**:
+   - Check for existing PR on this branch
+   - If exists: Update description with latest changes
+   - If not: Create PR with comprehensive description (not a draft)
+   - Include native development linkage for the source work item when `work_item_ref` can be inferred from `$ARGUMENTS`, the current branch name, an existing PR body, or the issue/ticket context passed by the caller.
+   - After the PR exists, re-resolve the live Pull Request node id and, when `github.projects.v2` is enabled, invoke `lisa:github-project-v2` with `operation: ensure-item` and `content_node_id: <pull-request-node-id>` so linked pull requests join the configured shared Project without replacing the PR as the durable review/merge surface.
+5. **Auto-merge**: Choose merge strategy by PR type:
+   - **Promotion PRs** (env → env, e.g. `dev` → `staging`): use `gh pr merge --auto --merge` (never squash). Squashing flattens the constituent `chore(release): X.Y.Z [skip ci]` commits into one commit titled with the PR title, stripping the `[skip ci]` markers and breaking the release workflow's promotion-detection regex — the destination branch then double-bumps its version. `--merge` keeps each `chore(release)` commit (and its `[skip ci]` marker) intact under a clean merge commit subject the workflow can recognize.
+   - **Feature PRs** (anything → `dev`): use `gh pr merge --auto --merge`.
+6. **Drive to merge**: Opening the PR and enabling auto-merge is not terminal. Continue monitoring until the PR is actually `MERGED`, `CLOSED`, or a required check/review gate fails and must be fixed.
+   - **Auto-merge capability fallback**: If `gh pr merge --auto --merge` fails because the repository does not allow auto-merge, keep watching the required checks and review decision. Once checks are green, the review gate is clear, and the PR is mergeable, run `gh pr merge --merge` directly. Never fall back to squash.
+   - **BEHIND re-sync**: Poll `gh pr view <pr> --json mergeStateStatus,statusCheckRollup,reviewDecision,mergeable,state`. If `mergeStateStatus == BEHIND` after required checks are green, run `gh pr update-branch <pr>` and continue watching the new head while checks rerun.
+   - **Sync conflict path**: If `gh pr update-branch` reports a conflict or cannot update the branch, surface the conflicting files, fetch the base branch locally, merge the base into the PR branch, resolve conflicts, run the relevant checks, and push. If the conflict needs broader design input, escalate through the agent-team fix-task pattern with the file list and current merge state. Do not leave a PR silently stalled in an ambiguous sync state.
+   - **Review-gate stall**: If `reviewDecision == CHANGES_REQUESTED`, inspect unresolved review threads and blocking reviews. After the requested changes are addressed and threads are resolved, clear stale bot review blocks by dismissing the obsolete `CHANGES_REQUESTED` review where repository policy permits, or re-request review when dismissal is not allowed. A later `COMMENTED` review does not clear GitHub's prior `CHANGES_REQUESTED` state by itself.
+   - **Loop terminal states**: Continue the loop until the PR is `MERGED`, is `CLOSED`, checks fail, the review gate remains blocked by unresolved human feedback, or a sync conflict cannot be resolved locally. On check failures, use the existing PR watch/fix path: inspect logs, fix, commit, push, and resume the loop.
+   - **Harness-agnostic commands**: Use plain `gh` and `git` commands for this loop so Claude and Codex agents execute the same behavior from the shared skill.
+
+### Native Development Linkage
+
+Add provider-appropriate linkage to the PR title and/or body without changing the status lifecycle:
+
+- **GitHub Issues**:
+  - If `work_item_ref` is a GitHub issue URL, `org/repo#<n>`, or `#<n>`, add a dedicated issue reference line to the PR body.
+  - Use a closing keyword such as `Closes #<n>` only when merging this PR to the base branch represents terminal delivery for that issue. This is true when the target branch is the repository default branch or the configured production branch from `.lisa.config.json` `deploy.branches.production`.
+  - If the target branch is a non-terminal environment branch such as `dev` or `staging`, use a non-closing reference such as `Refs #<n>` so GitHub links the PR in the issue's Development / linked pull requests surface without prematurely closing the issue.
+  - For cross-repo issue refs, use the fully qualified form, for example `Closes CodySwannGT/lisa#614` or `Refs CodySwannGT/lisa#614`.
+- **Linear**:
+  - Ensure the Linear issue identifier appears in the branch name when the branch is created upstream by `lisa:implement`.
+  - Include the identifier in the PR title or body, for example `Linear: ENG-123`, so Linear's GitHub integration can attach the PR.
+- **JIRA**:
+  - Ensure the JIRA issue key appears in the branch name when the branch is created upstream by `lisa:implement`.
+  - Include the key in the PR title or body, for example `JIRA: PROJ-456`, so the GitHub-JIRA integration can attach the PR.
+- **No supported provider**: Skip this section without error; do not invent references.
+
+When updating an existing PR, preserve any existing linkage line unless the new `work_item_ref` is more specific. Do not duplicate equivalent references.
+
+### GitHub ProjectV2 Coordination
+
+After PR creation or update, resolve the live Pull Request node id:
+
+```bash
+gh pr view <pr-number> --json id,url --jq '{ id, url }'
+```
+
+When `github.projects.v2` is enabled, delegate membership to `lisa:github-project-v2`:
+
+```text
+operation: ensure-item
+content_node_id: <pull-request-node-id>
+```
+
+Branch on the shared utility outcome exactly as GitHub Issue writers do:
+
+- `outcome: disabled` — no Project configured; continue normally.
+- `outcome: added` or `outcome: reused` — PR membership is now present; continue normally.
+- `outcome: warning` with `required: false` — preserve the exact Project error, keep the underlying PR creation/update as the durable success, and continue the normal auto-merge/watch flow.
+- `outcome: blocked` with `required: true` — surface the exact Project failure and treat the submit flow as blocked even if the PR already exists, so operators can fix Project access/config before reporting full success.
+
+Never inline separate `gh api graphql` ProjectV2 mutations here. All Pull Request membership coordination goes through `lisa:github-project-v2` so linked-PR flows and Issue writers stay in parity.
+
+### PR Description Format
+
+Include in the PR description:
+
+- **Summary**: Brief overview of changes (1-3 bullet points)
+- **Test plan**: How to verify the changes work correctly
+- **Issue / Tracker link**: The provider-specific native linkage line when a source work item is available, placed after the summary and before the test plan.
+
+### Never
+
+- use `--force` push without explicit user request
+- create PR from protected branches (dev, staging, main)
+- skip pushing before PR creation
+
+## Execute
+
+Execute the workflow now.