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

scripts/verify-pi-resources.sh

@@ -1,6 +1,9 @@
 #!/usr/bin/env bash
 set -euo pipefail
 
+# shellcheck source=lib/portable.sh
+source "$(dirname "${BASH_SOURCE[0]}")/lib/portable.sh"
+
 REQUIRED_FILES=(
   "docs/PI-RESEARCH.md"
   "docs/PI.md"
@@ -18,7 +21,6 @@ REQUIRED_FILES=(
   "skills/reviewer-runtime/pi/run-review.sh"
   "skills/reviewer-runtime/pi/notify-telegram.sh"
   "scripts/install-pi-package.sh"
-  "scripts/sync-pi-package-skills.sh"
   "pi-package/skills/atlassian/SKILL.md"
   "pi-package/skills/create-plan/SKILL.md"
   "pi-package/skills/do-task/SKILL.md"
@@ -36,13 +38,13 @@ done
 test -x skills/reviewer-runtime/pi/run-review.sh
 test -x skills/reviewer-runtime/pi/notify-telegram.sh
 test -x scripts/install-pi-package.sh
-test -x scripts/sync-pi-package-skills.sh
 find skills/web-automation/pi/scripts -type f -print -quit | grep -q .
 find skills/atlassian/pi/scripts -type f -print -quit | grep -q .
 
 for file in skills/create-plan/pi/SKILL.md skills/do-task/pi/SKILL.md skills/implement-plan/pi/SKILL.md; do
   grep -q 'docs/PI-SUPERPOWERS.md' "$file"
   grep -q 'docs/PI-COMMON-REVIEWER.md' "$file"
+  # shellcheck disable=SC2016
   grep -q 'Reviewer CLI: `codex`, `claude`, `cursor`, `opencode`, `pi`, or `skip`' "$file"
   grep -q 'pi --no-session --no-skills --no-prompt-templates --no-extensions --no-context-files' "$file"
   grep -q -- '--tools read,grep,find,ls -p' "$file"
@@ -51,11 +53,13 @@ done
 
 grep -q 'reviewer model is configured independently' docs/PI-COMMON-REVIEWER.md
 grep -q 'provider-qualified model IDs' docs/PI-COMMON-REVIEWER.md
+# shellcheck disable=SC2016
 grep -q 'MUST NOT include `write`, `edit`, or `bash`' docs/PI-COMMON-REVIEWER.md
 grep -q 'Reviewer CLI | codex \\| claude \\| cursor \\| opencode \\| pi' skills/do-task/pi/templates/task-plan.md
 
 grep -q 'pi-package/skills/atlassian/scripts' skills/atlassian/pi/SKILL.md
 grep -q 'pi-package/skills/web-automation/scripts' skills/web-automation/pi/SKILL.md
+# shellcheck disable=SC2016
 grep -q 'local checkout package install keeps the runtime in `pi-package/skills/<skill>/scripts`' docs/PI.md
 
 grep -q 'install-pi-package.sh --global' docs/PI.md
@@ -78,22 +82,28 @@ for family in atlassian create-plan do-task implement-plan web-automation; do
   diff -qr \
     --exclude '.DS_Store' \
     --exclude 'node_modules' \
+    --exclude '.generated-manifest.json' \
+    --exclude 'package.json' \
     "$source_dir" "$mirror_dir" >/dev/null
 
   while IFS= read -r -d '' source_path; do
     rel_path=${source_path#"$source_dir"/}
     mirror_path="${mirror_dir}/${rel_path}"
     test -e "$mirror_path"
-    test "$(stat -f '%Lp' "$source_path")" = "$(stat -f '%Lp' "$mirror_path")"
+    test "$(portable_stat_perms "$source_path")" = "$(portable_stat_perms "$mirror_path")"
   done < <(find "$source_dir" \
     \( -name '.DS_Store' -o -name 'node_modules' \) -prune -o \
     -mindepth 1 -print0)
 done
 
-! grep -nE 'update_plan|plan mode|sub-agent|subagents' \
+# SC2251: restructured to avoid ! outside condition
+if grep -nE 'update_plan|plan mode|sub-agent|subagents' \
   skills/create-plan/pi/SKILL.md \
   skills/do-task/pi/SKILL.md \
-  skills/implement-plan/pi/SKILL.md
+  skills/implement-plan/pi/SKILL.md; then
+  echo "Error: pi SKILL.md files must not contain Codex-specific terms" >&2
+  exit 1
+fi
 
 node <<'EOF'
 const fs = require("fs");
@@ -126,7 +136,7 @@ for (const requiredFile of [
   "pi-package/skills",
   "docs/PI-COMMON-REVIEWER.md",
   "scripts/install-pi-package.sh",
-  "scripts/sync-pi-package-skills.sh",
+  "scripts/generate-skills.mjs",
 ]) {
   if (!pkg.files.includes(requiredFile)) {
     console.error(`package.json files must include ${requiredFile}`);