@codyswann/lisa 4.74.9 → 4.75.0

package/plugins/lisa-rails-devin/skills/jira-evidence/scripts/post-evidence.sh

@@ -0,0 +1,262 @@
+#!/usr/bin/env bash
+# post-evidence.sh — Upload evidence and post to JIRA + GitHub PR description
+#
+# Usage:
+#   bash post-evidence.sh <TICKET_ID> <EVIDENCE_DIR> <PR_NUMBER>
+#
+# Prerequisites:
+#   - JIRA_API_TOKEN env var set
+#   - a jira-cli config, resolved in this order (see "CONFIG RESOLUTION" below):
+#       1. ${PROJECT_DIR}/.lisa/jira-cli/.config.yml  (written by the
+#          setup-jira-cli SessionStart hook from the JIRA_* environment)
+#       2. ~/.config/.jira/.config.yml                (a developer's own
+#          `jira init` config; announced on stderr when it is used)
+#   - gh CLI authenticated
+#
+# What it does:
+#   1. Uploads evidence files to the 'pr-assets' GitHub release
+#   2. Updates the GitHub PR description with evidence/comment.md
+#   3. Uploads image evidence as JIRA attachments
+#   4. Posts/updates the JIRA comment with evidence/comment.txt
+#   5. Moves the JIRA ticket to the configured jira.workflow.review status
+#      (skipped entirely when review is unconfigured — stays in claimed)
+
+set -euo pipefail
+
+TICKET_ID="${1:?Usage: post-evidence.sh <TICKET_ID> <EVIDENCE_DIR> <PR_NUMBER>}"
+EVIDENCE_DIR="${2:?Usage: post-evidence.sh <TICKET_ID> <EVIDENCE_DIR> <PR_NUMBER>}"
+PR_NUMBER="${3:?Usage: post-evidence.sh <TICKET_ID> <EVIDENCE_DIR> <PR_NUMBER>}"
+
+# ─────────────────────────────────────────────────────────────────────────────
+# CONFIG RESOLUTION
+#
+# The setup-jira-cli SessionStart hook writes ${PROJECT_DIR}/.lisa/jira-cli/
+# .config.yml. Nothing read it — this script looked only at the developer's own
+# ~/.config/.jira/.config.yml and exited 1 telling the operator to run
+# `jira init`, so on a headless JIRA project the hook was an inert control.
+# See CodySwannGT/lisa#2767.
+#
+# PROJECT_DIR is resolved with the same rule as the hook that writes the file,
+# deliberately character-for-character: CLAUDE_PROJECT_DIR (the harness's own
+# declaration of the root, inert on harnesses that never set it), then the git
+# toplevel, then pwd. A session launched from a subdirectory otherwise reads a
+# directory it never wrote — the #2768 defect, on the read side.
+#
+# Nothing here writes to ~/.config/.jira. That file is a developer's personal
+# jira-cli state; it is read as a fallback and never created or modified.
+#
+# NOTE: the `.lisa.config.json` reads in Step 5 below are still resolved from
+# the process working directory. That is pre-existing and out of scope here.
+# ─────────────────────────────────────────────────────────────────────────────
+PROJECT_DIR="${CLAUDE_PROJECT_DIR:-}"
+if [[ -z "${PROJECT_DIR}" || ! -d "${PROJECT_DIR}" ]]; then
+  PROJECT_DIR="$(git rev-parse --show-toplevel 2>/dev/null || pwd)"
+fi
+PROJECT_JIRA_CONFIG="${PROJECT_DIR}/.lisa/jira-cli/.config.yml"
+HOME_JIRA_CONFIG="${HOME}/.config/.jira/.config.yml"
+
+if [[ -f "$PROJECT_JIRA_CONFIG" ]]; then
+  JIRA_CONFIG="$PROJECT_JIRA_CONFIG"
+elif [[ -f "$HOME_JIRA_CONFIG" ]]; then
+  # Announced, never silent. A silent fall-through to the developer's own file
+  # is precisely how the Lisa-written config stayed unconsumed without anyone
+  # noticing, and on a headless runner there is no such file to fall back to.
+  echo "NOTE: no Lisa-written jira-cli config at $PROJECT_JIRA_CONFIG" >&2
+  echo "      falling back to the developer config at $HOME_JIRA_CONFIG" >&2
+  JIRA_CONFIG="$HOME_JIRA_CONFIG"
+else
+  echo "ERROR: jira-cli config not found." >&2
+  echo "  Lisa-written config (expected): $PROJECT_JIRA_CONFIG" >&2
+  echo "  developer config (fallback):    $HOME_JIRA_CONFIG" >&2
+  echo "  Fix: export JIRA_SERVER, JIRA_LOGIN (and JIRA_INSTALLATION," >&2
+  echo "  JIRA_PROJECT) and start a new session so the setup-jira-cli hook" >&2
+  echo "  writes the project config — or run 'jira init' locally." >&2
+  exit 1
+fi
+JIRA_SERVER=$(sed -n 's/^server:[[:space:]]*//p' "$JIRA_CONFIG")
+JIRA_USER=$(grep '^login:' "$JIRA_CONFIG" | awk '{print $2}')
+# Validate before constructing credentials; use only the approved HTTPS origin.
+JIRA_SERVER=$(python3 - "$JIRA_SERVER" <<'PY_ORIGIN'
+import ipaddress
+import re
+import sys
+from urllib.parse import urlsplit
+
+raw = sys.argv[1]
+try:
+    if not raw or any(c <= " " or c >= "\x7f" for c in raw):
+        raise ValueError()
+    url = urlsplit(raw)
+    if (url.scheme != "https" or "@" in url.netloc or "?" in raw
+            or "#" in raw or url.path not in ("", "/") or not url.hostname):
+        raise ValueError()
+    host = url.hostname
+    if url.netloc.startswith("["):
+        host = f"[{ipaddress.IPv6Address(host).compressed}]"
+    elif not re.fullmatch(r"[a-z0-9]([a-z0-9-]*[a-z0-9])?(\.[a-z0-9]([a-z0-9-]*[a-z0-9])?)*", host):
+        raise ValueError()
+    port = url.port
+    if port == 0:
+        raise ValueError()
+    suffix = f":{port}" if port is not None and port != 443 else ""
+    print(f"https://{host}{suffix}")
+except ValueError:
+    sys.exit("ERROR: JIRA_SERVER must be a bare HTTPS origin without userinfo, path, query or fragment.")
+PY_ORIGIN
+)
+
+GH_REPO=$(gh repo view --json nameWithOwner --jq '.nameWithOwner')
+RELEASE_TAG="pr-assets"
+
+if [[ -z "${JIRA_API_TOKEN:-}" ]]; then
+  echo "ERROR: JIRA_API_TOKEN environment variable is not set" >&2
+  exit 1
+fi
+
+# Collect numbered evidence files (images + text)
+SCREENSHOTS=()
+while IFS= read -r -d '' f; do
+  SCREENSHOTS+=("$f")
+done < <(find "$EVIDENCE_DIR" -maxdepth 1 -name '[0-9][0-9]-*.png' -print0 | sort -z)
+
+TEXT_EVIDENCE=()
+while IFS= read -r -d '' f; do
+  TEXT_EVIDENCE+=("$f")
+done < <(find "$EVIDENCE_DIR" -maxdepth 1 \( -name '[0-9][0-9]-*.txt' -o -name '[0-9][0-9]-*.json' \) ! -name 'comment.txt' -print0 | sort -z)
+
+# Bash 3.2 treats an empty array as unset under nounset.
+ALL_EVIDENCE=(${SCREENSHOTS[@]+"${SCREENSHOTS[@]}"} ${TEXT_EVIDENCE[@]+"${TEXT_EVIDENCE[@]}"})
+
+if [[ ${#ALL_EVIDENCE[@]} -eq 0 ]]; then
+  echo "ERROR: No numbered evidence files found in $EVIDENCE_DIR (expected NN-*.png, NN-*.txt, or NN-*.json)" >&2
+  exit 1
+fi
+
+echo "Found ${#SCREENSHOTS[@]} screenshots and ${#TEXT_EVIDENCE[@]} text evidence files to upload"
+
+# Compute JIRA auth early (used in steps 3 and 4)
+JIRA_AUTH=$(printf '%s' "$JIRA_USER:$JIRA_API_TOKEN" | base64 | tr -d '\n')
+
+# ── Step 1: Upload to GitHub pr-assets release ──────────────────────────────
+echo ""
+echo "==> Uploading to GitHub release '$RELEASE_TAG'..."
+
+for FILE in "${ALL_EVIDENCE[@]}"; do
+  FILENAME=$(basename "$FILE")
+  echo "  ↑ $FILENAME"
+  gh release upload "$RELEASE_TAG" "$FILE" --repo "$GH_REPO" --clobber
+done
+
+echo "  ✓ GitHub release assets uploaded"
+
+# ── Step 2: Update GitHub PR description with evidence ──────────────────────
+COMMENT_MD="$EVIDENCE_DIR/comment.md"
+if [[ ! -f "$COMMENT_MD" ]]; then
+  echo "ERROR: $COMMENT_MD not found — run generate-templates.py first" >&2
+  exit 1
+fi
+
+echo ""
+echo "==> Updating GitHub PR #$PR_NUMBER description..."
+
+CURRENT_BODY=$(gh pr view "$PR_NUMBER" --json body --jq '.body')
+
+# Replace or append the Evidence section
+if echo "$CURRENT_BODY" | grep -q "^## Evidence"; then
+  # Replace from "## Evidence" to end of file
+  NEW_BODY=$(echo "$CURRENT_BODY" | sed '/^## Evidence/,$d')
+  EVIDENCE_SECTION=$(cat "$COMMENT_MD")
+  UPDATED_BODY="${NEW_BODY}
+${EVIDENCE_SECTION}"
+else
+  EVIDENCE_SECTION=$(cat "$COMMENT_MD")
+  UPDATED_BODY="${CURRENT_BODY}
+
+${EVIDENCE_SECTION}"
+fi
+
+gh pr edit "$PR_NUMBER" --body "$UPDATED_BODY"
+echo "  ✓ PR description updated with evidence"
+
+# ── Step 3: Upload image evidence as JIRA attachments ───────────────────────
+if [[ ${#SCREENSHOTS[@]} -gt 0 ]]; then
+  echo ""
+  echo "==> Uploading image attachments to JIRA $TICKET_ID..."
+
+  for IMG in "${SCREENSHOTS[@]}"; do
+    FILENAME=$(basename "$IMG")
+    echo "  ↑ $FILENAME"
+    RESP=$(curl -s -w "\nHTTP_CODE:%{http_code}" \
+      -X POST \
+      -H "Authorization: Basic $JIRA_AUTH" \
+      -H "X-Atlassian-Token: no-check" \
+      -F "file=@$IMG" \
+      "$JIRA_SERVER/rest/api/3/issue/$TICKET_ID/attachments")
+    HTTP_CODE=$(echo "$RESP" | grep "HTTP_CODE:" | cut -d: -f2)
+    if [[ "$HTTP_CODE" != "200" ]]; then
+      echo "  WARNING: Failed to upload $FILENAME (HTTP $HTTP_CODE)" >&2
+    fi
+  done
+
+  echo "  ✓ JIRA attachments uploaded"
+fi
+
+# ── Step 4: Post JIRA comment ────────────────────────────────────────────────
+COMMENT_TXT="$EVIDENCE_DIR/comment.txt"
+if [[ ! -f "$COMMENT_TXT" ]]; then
+  echo "ERROR: $COMMENT_TXT not found — run generate-templates.py first" >&2
+  exit 1
+fi
+
+echo ""
+echo "==> Posting JIRA comment on $TICKET_ID..."
+
+COMMENT_BODY=$(cat "$COMMENT_TXT")
+COMMENT_JSON=$(python3 -c "import sys, json; print(json.dumps(sys.stdin.read()))" <<< "$COMMENT_BODY")
+
+RESP=$(curl -s -w "\nHTTP_CODE:%{http_code}" \
+  -X POST \
+  -H "Authorization: Basic $JIRA_AUTH" \
+  -H "Content-Type: application/json" \
+  "$JIRA_SERVER/rest/api/2/issue/$TICKET_ID/comment" \
+  -d "{\"body\": $COMMENT_JSON}")
+HTTP_CODE=$(echo "$RESP" | grep "HTTP_CODE:" | cut -d: -f2)
+
+if [[ "$HTTP_CODE" == "201" ]]; then
+  echo "  ✓ JIRA comment posted"
+else
+  echo "  WARNING: JIRA comment returned HTTP $HTTP_CODE" >&2
+  echo "$RESP" | grep -v "HTTP_CODE:" | head -3
+fi
+
+# ── Step 5: Move ticket to the configured review status (if any) ────────────
+# A transition may target only a status named in .lisa.config.json jira.workflow.
+# `review` is OPTIONAL: when it is not configured, the build lifecycle stays in
+# `claimed` until `done` — do NOT invent a transition. (See config-resolution.md.)
+REVIEW=""
+if [ -f .lisa.config.json ]; then
+  _cfg=$(jq -r '.jira.workflow.review // .jira.workflow.code_review // empty' .lisa.config.json 2>/dev/null)
+  [ -n "$_cfg" ] && REVIEW="$_cfg"
+fi
+if [ -f .lisa.config.local.json ]; then
+  _local=$(jq -r '.jira.workflow.review // .jira.workflow.code_review // empty' .lisa.config.local.json 2>/dev/null)
+  [ -n "$_local" ] && REVIEW="$_local"
+fi
+echo ""
+if [ -n "$REVIEW" ]; then
+  echo "==> Moving $TICKET_ID to $REVIEW..."
+  # --config pins jira-cli to the same file this script parsed above.
+  # jira-cli resolves --config > JIRA_CONFIG_FILE > ~/.config/.jira/
+  # .config.yml, and a --config path that does not exist fails closed
+  # rather than falling back (measured against jira-cli v1.7.0). The flag
+  # needs no environment export, so this works identically on every
+  # harness — see the harness note in the setup-jira-cli hook.
+  jira --config "$JIRA_CONFIG" issue move "$TICKET_ID" "$REVIEW" 2>&1 && echo "  ✓ Ticket moved to $REVIEW" || echo "  WARNING: Could not move ticket to $REVIEW (not a valid transition?); leaving in current status" >&2
+else
+  echo "==> No jira.workflow.review configured; leaving $TICKET_ID in its current (claimed) status per config-resolution."
+fi
+
+echo ""
+echo "==> Done!"
+echo "    JIRA:   $JIRA_SERVER/browse/$TICKET_ID"
+echo "    GitHub: https://github.com/$GH_REPO/pull/$PR_NUMBER"

package/plugins/lisa-rails-devin/skills/jira-journey/SKILL.md

@@ -0,0 +1,65 @@
+---
+name: jira-journey
+description: "Parse a JIRA ticket's Validation Journey section, execute the verification steps, capture evidence, and post to JIRA + GitHub PR using the jira-evidence skill."
+---
+
+# JIRA Validation Journey
+
+Parse a JIRA ticket's Validation Journey, execute the verification steps using the project's appropriate tools, capture evidence at each marker, and post to JIRA + GitHub PR.
+
+## Arguments
+
+`$ARGUMENTS`: `<TICKET_ID> [PR_NUMBER]`
+
+- `TICKET_ID` (required): JIRA ticket key (e.g., `PROJ-123`)
+- `PR_NUMBER` (optional): GitHub PR number to update description
+
+## Prerequisites
+
+- `JIRA_API_TOKEN` environment variable set
+- `jira-cli` configured — `.lisa/jira-cli/.config.yml` (written by the
+  `setup-jira-cli` SessionStart hook) or `~/.config/.jira/.config.yml`
+- `gh` CLI authenticated
+
+## Workflow
+
+### Step 1: Parse the Validation Journey
+
+Run the parser script to extract the Validation Journey from the JIRA ticket description:
+
+```bash
+python3 .claude/skills/jira-journey/scripts/parse-plan.py <TICKET_ID>
+```
+
+The script outputs JSON with: `ticket`, `prerequisites`, `steps`, `viewports`, `assertions`.
+
+### Step 2: Satisfy Prerequisites
+
+Before starting the journey, verify each prerequisite listed in the parsed output.
+
+### Step 3: Execute Steps
+
+Execute each step sequentially. At each step with an evidence marker (`[SCREENSHOT: name]`, or typed `[EVIDENCE: <artifact-type>: <name>]` per the `verification` rule — `[SCREENSHOT: name]` is shorthand for `[EVIDENCE: screenshot: name]`), capture an artifact of the declared type.
+
+The execution method depends on the project type:
+- **UI projects**: Use Playwright MCP browser tools, capture screenshots at each viewport
+- **API projects**: Use curl or test commands, capture stdout/stderr
+- **Library projects**: Run tests, capture output
+
+Stack-specific overrides provide the actual execution implementation.
+
+### Step 4: Generate Evidence Templates
+
+After capturing all evidence, run the template generator to format evidence for JIRA and GitHub.
+
+### Step 5: Post Evidence
+
+Use the `/jira-evidence` skill to post everything:
+
+```bash
+bash .claude/skills/jira-evidence/scripts/post-evidence.sh <TICKET_ID> ./evidence <PR_NUMBER>
+```
+
+### Step 6: Verify
+
+Confirm evidence renders at both the JIRA ticket and GitHub PR.

package/plugins/lisa-rails-devin/skills/jira-verify/SKILL.md

@@ -0,0 +1,26 @@
+---
+name: jira-verify
+description: This skill should be used when verifying that a JIRA ticket meets organizational standards for epic relationships and description quality. It fetches the live ticket and delegates the gate checks to jira-validate-ticket so the bar matches what jira-write-ticket enforces pre-write.
+allowed-tools: ["Skill", "mcp__atlassian__getJiraIssue", "mcp__atlassian__getAccessibleAtlassianResources"]
+---
+
+# Verify JIRA Ticket: $ARGUMENTS
+
+Verify that the existing JIRA ticket `$ARGUMENTS` meets organizational standards. This skill is a thin post-write wrapper around `lisa:jira-validate-ticket`: it fetches the live ticket and asks `lisa:jira-validate-ticket` to run the gates against the fetched state.
+
+This indirection exists so the gate definitions live in exactly one place (`lisa:jira-validate-ticket`). When the bar changes, change it there — `lisa:jira-verify`, `lisa:jira-write-ticket` (Phase 5.5 pre-write), and `lisa:notion-to-tracker` (PRD dry-run) all pick it up.
+
+## Process
+
+1. Resolve cloud ID via `mcp__atlassian__getAccessibleAtlassianResources`.
+2. Fetch the ticket via `mcp__atlassian__getJiraIssue` for `$ARGUMENTS`.
+3. Invoke `lisa:jira-validate-ticket` and pass the ticket key. The validator runs every gate (Specification + Feasibility) against the live state.
+4. Surface the validator's report verbatim.
+
+## Output
+
+Pass through `lisa:jira-validate-ticket`'s structured output unchanged. Downstream callers parse the gate lines.
+
+## Notes
+
+- This skill is read-only. It never edits the ticket, posts comments, or changes status.

package/plugins/lisa-rails-devin/skills/ops-check-logs/SKILL.md

@@ -0,0 +1,191 @@
+---
+name: ops-check-logs
+description: Check application logs from local Docker Compose or remote AWS CloudWatch for Rails applications. Supports log tailing, filtering, and error searching.
+allowed-tools:
+  - Bash
+  - Read
+---
+
+# Ops: Check Logs
+
+View and search logs across local and remote environments.
+
+**Argument**: `$ARGUMENTS` — target and optional filter (e.g., `local`, `local worker`, `staging errors`, `production 500`, `staging slow-queries`)
+
+## Discovery
+
+1. Read `config/deploy.yml` to discover the service name (used in CloudWatch log group naming)
+2. Read `docker-compose.yml` to identify local service names for targeted log viewing
+3. Discover the AWS region from deploy config or environment variables
+
+## Local Logs (Docker Compose)
+
+### All Services
+
+```bash
+docker compose logs --tail=100
+```
+
+### Follow Mode (tail)
+
+```bash
+docker compose logs -f --tail=50
+```
+
+### Specific Service
+
+```bash
+# Rails web server
+docker compose logs --tail=100 web
+
+# Solid Queue worker
+docker compose logs --tail=100 worker
+
+# PostgreSQL
+docker compose logs --tail=100 postgres
+```
+
+### Filter for Errors
+
+```bash
+docker compose logs --tail=500 web 2>&1 | grep -iE "(error|exception|fatal|500)"
+```
+
+### Rails Development Log (if running outside Docker)
+
+```bash
+tail -n 100 log/development.log
+```
+
+### Filter Rails Log for Slow Queries
+
+```bash
+grep -E "SLOW|ms\)" log/development.log | tail -20
+```
+
+## Remote Logs (Kamal)
+
+### Tail Application Logs
+
+```bash
+kamal app logs -d {environment}
+```
+
+### Follow Mode
+
+```bash
+kamal app logs -d {environment} -f
+```
+
+### Specific Role
+
+```bash
+# Web role
+kamal app logs --roles=web -d {environment}
+
+# Worker role (Solid Queue)
+kamal app logs --roles=worker -d {environment}
+```
+
+## Remote Logs (CloudWatch via AWS CLI)
+
+For advanced filtering and historical log access, use the AWS CLI directly.
+
+### Discover Log Groups
+
+```bash
+aws logs describe-log-groups \
+  --region {aws-region} \
+  --query 'logGroups[].logGroupName' \
+  --output text | tr '\t' '\n' | grep -i "{app_name}"
+```
+
+### Filter for Errors (last 30 minutes)
+
+```bash
+aws logs filter-log-events \
+  --region {aws-region} \
+  --log-group-name "{log-group}" \
+  --start-time $(( ($(date +%s) - 1800) * 1000 )) \
+  --filter-pattern "ERROR" \
+  --query 'events[].message' \
+  --output text
+```
+
+### Filter for 500 Errors
+
+```bash
+aws logs filter-log-events \
+  --region {aws-region} \
+  --log-group-name "{log-group}" \
+  --start-time $(( ($(date +%s) - 1800) * 1000 )) \
+  --filter-pattern '"status=500"' \
+  --query 'events[].message' \
+  --output text
+```
+
+### Filter for Slow Requests (> 1 second)
+
+```bash
+aws logs filter-log-events \
+  --region {aws-region} \
+  --log-group-name "{log-group}" \
+  --start-time $(( ($(date +%s) - 3600) * 1000 )) \
+  --filter-pattern '"duration" "1000"' \
+  --query 'events[].message' \
+  --output text
+```
+
+### Tail Live Logs
+
+```bash
+aws logs tail "{log-group}" \
+  --region {aws-region} \
+  --follow \
+  --since 10m
+```
+
+### Specific Time Range
+
+```bash
+aws logs filter-log-events \
+  --region {aws-region} \
+  --log-group-name "{log-group}" \
+  --start-time $(date -d "{start-time}" +%s000) \
+  --end-time $(date -d "{end-time}" +%s000) \
+  --query 'events[].message' \
+  --output text
+```
+
+## ECS Task Logs
+
+For container-level logs (useful when the application fails to start):
+
+```bash
+# List recent tasks
+aws ecs list-tasks \
+  --cluster {cluster-name} \
+  --service-name {service-name} \
+  --region {aws-region} \
+  --query 'taskArns[]' --output text
+
+# Describe a task to find the log stream
+aws ecs describe-tasks \
+  --cluster {cluster-name} \
+  --tasks {task-arn} \
+  --region {aws-region} \
+  --query 'tasks[0].containers[].{Name:name,Status:lastStatus,ExitCode:exitCode}' \
+  --output table
+```
+
+## Output Format
+
+Report log findings as:
+
+| Source | Timestamp | Level | Context | Message |
+|--------|-----------|-------|---------|---------|
+| CloudWatch | 2026-03-18T10:30:00Z | ERROR | web | ActiveRecord::ConnectionTimeoutError |
+| Docker | — | ERROR | worker | SolidQueue::ProcessMissingError |
+| Rails log | — | WARN | N/A | DEPRECATION WARNING: ... |
+
+Include a summary of findings: total errors, warnings, and any patterns observed.

package/plugins/lisa-rails-devin/skills/ops-deploy/SKILL.md

@@ -0,0 +1,153 @@
+---
+name: ops-deploy
+description: Deploy Rails applications via Kamal or CI/CD branch push to staging or production environments.
+allowed-tools:
+  - Bash
+  - Read
+---
+
+# Ops: Deploy
+
+Deploy the Rails application to remote environments.
+
+**Argument**: `$ARGUMENTS` — environment (`staging`, `production`) and optional method (`kamal`, `ci`; default: `kamal`)
+
+## Safety
+
+**CRITICAL**: Production deployments require explicit human confirmation before proceeding. Always ask for confirmation when `$ARGUMENTS` contains `production`.
+
+## Discovery
+
+1. Read `config/deploy.yml` to discover the Kamal configuration: service name, registry, image, servers, accessories
+2. Read `config/deploy.staging.yml` and `config/deploy.production.yml` for environment-specific overrides
+3. Verify the specific environment-variable keys needed for the deploy are present in `.env.staging` / `.env.production` (or in SSM) without printing secret values
+4. Read `Dockerfile` to understand the Docker build stages
+
+## CI/CD Path (Preferred)
+
+The standard deployment path is via CI/CD — pushing to environment branches triggers auto-deploy.
+
+```bash
+# Deploy to staging via CI/CD
+git push origin HEAD:staging
+
+# Deploy to production via CI/CD (requires human confirmation first)
+git push origin HEAD:production
+```
+
+Monitor the deployment via GitHub Actions:
+
+```bash
+gh run list --branch {environment} --limit 3
+gh run watch {run-id}
+```
+
+## Kamal Deployment (Manual)
+
+### Pre-Deploy Checks
+
+1. **Verify Kamal is installed**:
+   ```bash
+   kamal version
+   ```
+
+2. **Verify Docker builds locally**:
+   ```bash
+   docker build -t {app_name}:test .
+   ```
+
+3. **Check current deployment state**:
+   ```bash
+   kamal details -d {environment}
+   ```
+
+4. **Check for deploy lock**:
+   ```bash
+   kamal lock status -d {environment}
+   ```
+   If locked from a previous interrupted deploy: `kamal lock release -d {environment}`
+
+### Deploy to Staging
+
+```bash
+kamal deploy -d staging
+```
+
+### Deploy to Production
+
+**Requires explicit human confirmation.**
+
+```bash
+kamal deploy -d production
+```
+
+### Deploy with Specific Git Ref
+
+```bash
+kamal deploy -d {environment} --version {git-sha-or-tag}
+```
+
+### Rollback
+
+If a deploy causes issues, roll back to the previous version:
+
+```bash
+# List available versions
+kamal app containers -d {environment}
+
+# Rollback to previous version
+kamal rollback {previous-version} -d {environment}
+```
+
+## Post-Deploy Verification
+
+After any deployment:
+
+1. **Health check** the deployed environment:
+   ```bash
+   curl -sf -o /dev/null -w "HTTP %{http_code} in %{time_total}s" https://{app_host}/up
+   ```
+
+2. **Verify ECS service stability** (running count matches desired count):
+   ```bash
+   aws ecs describe-services \
+     --cluster {cluster-name} \
+     --services {service-name} \
+     --region {aws-region} \
+     --query 'services[0].{Running:runningCount,Desired:desiredCount,Status:status}' \
+     --output table
+   ```
+
+3. **Check for migration status** (if migrations were included):
+   ```bash
+   kamal app exec --roles=web "bin/rails db:migrate:status" -d {environment}
+   ```
+
+4. **Check logs** for errors in the first 5 minutes (use `ops-check-logs` skill)
+
+5. **Verify Solid Queue workers** are running (use `ops-verify-jobs` skill)
+
+6. **Verify OpenTelemetry traces** are being exported (use `ops-verify-telemetry` skill)
+
+## Kamal Utility Commands
+
+| Command | Purpose |
+|---------|---------|
+| `kamal details -d {env}` | Show current deployment details |
+| `kamal app logs -d {env}` | Tail application logs |
+| `kamal app exec --roles=web "bin/rails console" -d {env}` | Open Rails console on remote |
+| `kamal audit -d {env}` | Show deploy audit log |
+| `kamal env push -d {env}` | Push updated environment variables |
+| `kamal lock status -d {env}` | Check deploy lock status |
+| `kamal lock release -d {env}` | Release a stale deploy lock |
+| `kamal traefik reboot -d {env}` | Restart the Traefik proxy |
+
+## Output Format
+
+Report deployment result as a table:
+
+| Target | Environment | Method | Status | Verification |
+|--------|-------------|--------|--------|-------------|
+| Rails app | staging | Kamal | SUCCESS/FAIL | /up returns 200 |
+| ECS tasks | staging | N/A | STABLE/UNSTABLE | running == desired |
+| Solid Queue | staging | N/A | RUNNING/DOWN | workers have heartbeat |