Perform code optimization and document cleanup (#1)

## Summary
- add repository-wide quality tooling and verification scaffolding, including CI workflows, pnpm workspace setup, ESLint/Prettier/markdown checks, and generated-output verification helpers
- reorganize skill sources and generation flow by introducing canonical `_source` variants, generator/manifests, reusable helper abstractions, and shared web-automation/browser utilities
- clean up and expand documentation so the root README flows into docs and skill docs, with clearer development, reviewer, installer, and workflow guidance

## Notable changes
- docs flow and consistency cleanup across `README.md`, `docs/README.md`, and related docs
- new scripts for `check`, docs verification, generated-file verification, shell portability, and safe directory replacement
- refactors in Atlassian and web-automation skill runtimes to reduce duplication and centralize reusable code
- changelog, development documentation, and CI surface updates

## Test Plan
- [ ] `pnpm run check`
- [ ] review generated/manifests and skill sync outputs
- [ ] smoke-check docs flow from `README.md` to `docs/README.md` to skill docs

## Notes
- this branch currently includes tracked `skills/web-automation/shared/node_modules` content that should be reviewed carefully as potentially noisy/accidental committed artifacts

Co-authored-by: Stefano Fiorini <stefano.fiorini@firsthorizon.com>
Reviewed-on: #1

skills/reviewer-runtime/pi/.generated-manifest.json

@@ -0,0 +1,19 @@
+{
+  "$schema": "https://ai-coding-skills.dev/schemas/generated-manifest/v1.json",
+  "generator": "scripts/generate-skills.mjs",
+  "generatedRoot": "skills/reviewer-runtime/pi",
+  "files": [
+    {
+      "path": "notify-telegram.sh",
+      "kind": "file",
+      "mode": "755",
+      "sha256": "d7e52e3d2f7de83691470467ff3fec230bea10f128d5b188604e1bb5883d6d58"
+    },
+    {
+      "path": "run-review.sh",
+      "kind": "file",
+      "mode": "755",
+      "sha256": "1af5076f0e4451c0870109216ee5780553ef7d402ec1359f38afefdaf53627c1"
+    }
+  ]
+}

skills/reviewer-runtime/pi/notify-telegram.sh

@@ -1,8 +1,7 @@
 #!/usr/bin/env bash
+# ⚠️ GENERATED FILE – do not edit directly. Edit the canonical source in skills/reviewer-runtime/notify-telegram.sh and run `pnpm run sync:pi`.
 set -euo pipefail
 
-# Keep this file in sync with skills/reviewer-runtime/notify-telegram.sh.
-
 DEFAULT_API_BASE_URL="https://api.telegram.org"
 DEFAULT_PARSE_MODE="HTML"
 MAX_MESSAGE_LENGTH=4096

skills/reviewer-runtime/pi/run-review.sh

@@ -1,8 +1,7 @@
 #!/usr/bin/env bash
+# ⚠️ GENERATED FILE – do not edit directly. Edit the canonical source in skills/reviewer-runtime/run-review.sh and run `pnpm run sync:pi`.
 set -euo pipefail
 
-# Keep this file in sync with skills/reviewer-runtime/run-review.sh.
-
 DEFAULT_POLL_SECONDS=10
 DEFAULT_HEARTBEAT_SECONDS=60
 DEFAULT_SOFT_TIMEOUT_SECONDS=600
@@ -146,6 +145,7 @@ kill_child_process_group() {
   fi
 }
 
+# shellcheck disable=SC2317,SC2329
 handle_signal() {
   local signal_name=$1
   INTERRUPTED=1
@@ -265,7 +265,6 @@ main() {
   local last_output_change_time=$START_TIME
   local last_heartbeat_time=$START_TIME
   local soft_timeout_logged=0
-  local stall_warning_logged=0
   local heartbeat_count=0
 
   while kill -0 "$CHILD_PID" 2>/dev/null; do
@@ -285,7 +284,6 @@ main() {
 
     if [[ "$stdout_bytes" -ne "$last_stdout_bytes" || "$stderr_bytes" -ne "$last_stderr_bytes" ]]; then
       last_output_change_time=$now
-      stall_warning_logged=0
       state=running-active
       level=info
       note="reviewer output changed"
@@ -296,7 +294,6 @@ main() {
         state=stall-warning
         level=warn
         note="no output growth for ${silent_for}s; process still alive"
-        stall_warning_logged=1
       else
         state=running-silent
         level=info
@@ -328,10 +325,9 @@ main() {
   set -e
   trap - EXIT
 
-  local final_stdout_bytes final_stderr_bytes
+  local final_stdout_bytes
   local success_file success_bytes
   final_stdout_bytes=$(file_bytes "$STDOUT_FILE")
-  final_stderr_bytes=$(file_bytes "$STDERR_FILE")
 
   if [[ "$child_exit_code" -eq 0 ]]; then
     if [[ "$final_stdout_bytes" -gt 0 ]]; then

skills/reviewer-runtime/run-review.sh

@@ -144,6 +144,7 @@ kill_child_process_group() {
   fi
 }
 
+# shellcheck disable=SC2317,SC2329
 handle_signal() {
   local signal_name=$1
   INTERRUPTED=1
@@ -263,7 +264,6 @@ main() {
   local last_output_change_time=$START_TIME
   local last_heartbeat_time=$START_TIME
   local soft_timeout_logged=0
-  local stall_warning_logged=0
   local heartbeat_count=0
 
   while kill -0 "$CHILD_PID" 2>/dev/null; do
@@ -283,7 +283,6 @@ main() {
 
     if [[ "$stdout_bytes" -ne "$last_stdout_bytes" || "$stderr_bytes" -ne "$last_stderr_bytes" ]]; then
       last_output_change_time=$now
-      stall_warning_logged=0
       state=running-active
       level=info
       note="reviewer output changed"
@@ -294,7 +293,6 @@ main() {
         state=stall-warning
         level=warn
         note="no output growth for ${silent_for}s; process still alive"
-        stall_warning_logged=1
       else
         state=running-silent
         level=info
@@ -326,10 +324,9 @@ main() {
   set -e
   trap - EXIT
 
-  local final_stdout_bytes final_stderr_bytes
+  local final_stdout_bytes
   local success_file success_bytes
   final_stdout_bytes=$(file_bytes "$STDOUT_FILE")
-  final_stderr_bytes=$(file_bytes "$STDERR_FILE")
 
   if [[ "$child_exit_code" -eq 0 ]]; then
     if [[ "$final_stdout_bytes" -gt 0 ]]; then

skills/reviewer-runtime/tests/claude-review-template-guard.sh

@@ -31,6 +31,7 @@ check_skill_file() {
   local file=$1
 
   assert_contains "$file" "claude -p \\"
+  # shellcheck disable=SC2016
   assert_contains "$file" '$(cat /tmp/'
   assert_contains "$file" "--strict-mcp-config"
   assert_contains "$file" "--setting-sources user"

skills/reviewer-runtime/tests/smoke-test.sh

@@ -328,7 +328,9 @@ main() {
 
   local tmp_dir
   tmp_dir=$(mktemp -d)
-  trap "rm -rf '$tmp_dir'" EXIT
+  # Use SMOKE_TMP as a module-level var so the single-quoted trap expands lazily
+  SMOKE_TMP="$tmp_dir"
+  trap 'rm -rf "$SMOKE_TMP"' EXIT
 
   test_delayed_success "$tmp_dir"
   test_soft_timeout_continues "$tmp_dir"

skills/reviewer-runtime/tests/telegram-notify-test.sh

@@ -144,7 +144,9 @@ main() {
 
   local tmp_dir
   tmp_dir=$(mktemp -d)
-  trap "rm -rf '$tmp_dir'" EXIT
+  # Use TG_TEST_TMP as a module-level var so the single-quoted trap expands lazily
+  TG_TEST_TMP="$tmp_dir"
+  trap 'rm -rf "$TG_TEST_TMP"' EXIT
 
   test_missing_credentials "$tmp_dir"
   test_rejects_message_and_message_file_together "$tmp_dir"