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

docs/PI.md

@@ -9,7 +9,8 @@ The Pi support surface has two layers:
 - editable source variants in `skills/<family>/pi/`
 - a package-facing mirror in `pi-package/skills/<skill>/`
 
-That split is intentional. Pi requires the immediate parent directory of `SKILL.md` to match the skill's frontmatter `name`, so the package cannot point directly at `skills/<family>/pi/`.
+That split is intentional. Pi requires the immediate parent directory of `SKILL.md` to match the
+skill's frontmatter `name`, so the package cannot point directly at `skills/<family>/pi/`.
 
 Related docs:
 
@@ -21,15 +22,18 @@ Related docs:
 
 ### Source Of Truth
 
-Author Pi variants under:
+Edit the **canonical sources** under:
 
-- `skills/atlassian/pi/`
-- `skills/create-plan/pi/`
-- `skills/do-task/pi/`
-- `skills/implement-plan/pi/`
-- `skills/web-automation/pi/`
+- `skills/atlassian/_source/pi/SKILL.md`
+- `skills/create-plan/_source/pi/` (SKILL.md + templates)
+- `skills/do-task/_source/pi/` (SKILL.md + templates)
+- `skills/implement-plan/_source/pi/SKILL.md`
+- `skills/web-automation/_source/pi/SKILL.md`
 
-These are the directories to edit by hand.
+After editing a canonical source, run `pnpm run sync:pi` to regenerate all
+agent-variant directories including `skills/<family>/pi/` and the package mirrors.
+Do not edit the generated `skills/<family>/pi/` directories directly — they are
+overwritten by the generator.
 
 ### Package Mirror
 
@@ -41,7 +45,9 @@ The package exposes:
 - `pi-package/skills/implement-plan/`
 - `pi-package/skills/web-automation/`
 
-Those directories are generated from the source variants by [`scripts/sync-pi-package-skills.sh`](../scripts/sync-pi-package-skills.sh).
+Those directories are generated from the canonical sources by
+[`scripts/generate-skills.mjs`](../scripts/generate-skills.mjs)
+(run via `pnpm run sync:pi`).
 
 ### Shared Setup Docs
 
@@ -92,7 +98,11 @@ That script:
 - fetches the CloakBrowser binary for `web-automation`
 - prints `pi list` at the end so the active install is visible immediately
 
-For this cloned-checkout flow, local checkout package install keeps the runtime in `pi-package/skills/<skill>/scripts`. Pi loads the skills from the package mirror in this repo; it does not copy them into `~/.pi/agent/skills/<skill>/` or `.pi/skills/<skill>/` unless you do a manual copy install.
+For this cloned-checkout flow,
+local checkout package install keeps the runtime in `pi-package/skills/<skill>/scripts`.
+Pi loads the skills from the package mirror in this repo;
+it does not copy them into `~/.pi/agent/skills/<skill>/` or `.pi/skills/<skill>/`
+unless you do a manual copy install.
 
 The package surface intentionally ships:
 
@@ -101,7 +111,7 @@ The package surface intentionally ships:
 - `docs/PI*.md`
 - `scripts/install-pi-package.sh`
 - `scripts/manage-skills.mjs` and `scripts/manage-skills.sh`
-- `scripts/sync-pi-package-skills.sh`
+- `scripts/generate-skills.mjs`
 - `scripts/verify-pi-resources.sh`
 - `scripts/verify-pi-workflows.sh`
 - `scripts/verify-reviewer-support.sh`
@@ -110,7 +120,8 @@ It intentionally does not ship `skills/<family>/pi/**` as package-discovered ski
 
 ## Single-Skill Copy Install
 
-If you only want one Pi skill without installing the whole package, copy from the package-facing mirror into a Pi skill root:
+If you only want one Pi skill without installing the whole package, copy from the package-facing
+mirror into a Pi skill root:
 
 ```bash
 mkdir -p .pi/skills/create-plan
@@ -124,13 +135,16 @@ Global installs use `~/.pi/agent/skills/<skill>/` instead of `.pi/skills/<skill>
 When a source Pi variant changes:
 
 ```bash
-./scripts/sync-pi-package-skills.sh
+pnpm run sync:pi
 npm run verify:pi
 npm run verify:reviewers
 npm pack --dry-run --json
 ```
 
-The focused `scripts/install-pi-package.sh` installer intentionally does not run sync. It assumes the checked-in `pi-package/skills/*` mirror is already current. The multi-client skill manager plans a sync step before manual Pi skill-copy operations so manual installs use the current package-facing mirror.
+The focused `scripts/install-pi-package.sh` installer intentionally does not run sync. It assumes
+the checked-in `pi-package/skills/*` mirror is already current. The multi-client skill manager
+plans a sync step before manual Pi skill-copy operations so manual installs use the current
+package-facing mirror.
 
 The verifier is responsible for catching: