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/README.md

@@ -1,31 +1,72 @@
 # Skills Documentation
 
-This directory contains user-facing docs for each skill.
+This directory contains user-facing docs for all skills, agents, and tooling
+in the `ai-coding-skills` repository.
 
-## Recommended Reading Flow
+## Reading Order
 
-1. Use [INSTALLER.md](./INSTALLER.md) for the guided install/update/remove wizard (`./scripts/manage-skills.sh`).
-2. Use the client docs ([CODEX.md](./CODEX.md), [CLAUDE-CODE.md](./CLAUDE-CODE.md), [CURSOR.md](./CURSOR.md), [OPENCODE.md](./OPENCODE.md)) for manual installs, and [PI.md](./PI.md) for Pi overview, package install, and manual single-skill copy.
-3. Use the skill docs below for skill-specific requirements, runtime setup, verification, and examples.
-4. For Pi workflow skills, also consult [PI-SUPERPOWERS.md](./PI-SUPERPOWERS.md) and [PI-COMMON-REVIEWER.md](./PI-COMMON-REVIEWER.md).
+Work through the sections below in order on a first read. Return to individual
+sections as needed.
 
-## Index
+### 1. Getting Started
 
-- [INSTALLER.md](./INSTALLER.md) — Skill manager wizard for installing, updating/reinstalling, and removing repo skills across supported clients.
-- [CODEX.md](./CODEX.md) — Manual install instructions for Codex variants.
-- [CLAUDE-CODE.md](./CLAUDE-CODE.md) — Manual install instructions for Claude Code variants.
-- [CURSOR.md](./CURSOR.md) — Manual install instructions for Cursor variants.
-- [OPENCODE.md](./OPENCODE.md) — Manual install instructions for OpenCode variants.
-- [ATLASSIAN.md](./ATLASSIAN.md) — Includes requirements, generated bundle sync, install, auth, safety rules, and usage examples for the Atlassian skill.
-- [CREATE-PLAN.md](./CREATE-PLAN.md) — Includes requirements, install, verification, and execution workflow for create-plan.
-- [DO-TASK.md](./DO-TASK.md) — Single-prompt end-to-end execution with dual reviewer loops (plan + implementation), TDD-first, single task commit. Sibling of create-plan/implement-plan scoped to ad-hoc tasks.
-- [IMPLEMENT-PLAN.md](./IMPLEMENT-PLAN.md) — Includes requirements, install, verification, and milestone review workflow for implement-plan.
-- [PI.md](./PI.md) — Pi support overview, source-vs-package layout, install flow, and extension decision.
-- [PI-RESEARCH.md](./PI-RESEARCH.md) — Source-backed pi findings that inform the repo's pi variants and packaging choices.
-- [PI-SUPERPOWERS.md](./PI-SUPERPOWERS.md) — How to install or verify Obra Superpowers for Pi.
-- [PI-COMMON-REVIEWER.md](./PI-COMMON-REVIEWER.md) — How to install or verify the shared reviewer-runtime helpers for Pi workflow skills.
-- [TELEGRAM-NOTIFICATIONS.md](./TELEGRAM-NOTIFICATIONS.md) — Shared Telegram notification setup used by reviewer-driven skills.
-- [WEB-AUTOMATION.md](./WEB-AUTOMATION.md) — Includes requirements, install, dependency verification, and usage examples for web-automation.
+- [INSTALLER.md](./INSTALLER.md) — Guided install/update/remove wizard
+  (`./scripts/manage-skills.sh`). **Start here** if you want the fastest path
+  to installed skills.
+
+### 2. Per-Agent Manual Install
+
+Use these guides to install specific skills manually for a single agent:
+
+- [CODEX.md](./CODEX.md) — Manual install for Codex variants.
+- [CLAUDE-CODE.md](./CLAUDE-CODE.md) — Manual install for Claude Code variants.
+- [CURSOR.md](./CURSOR.md) — Manual install for Cursor variants.
+- [OPENCODE.md](./OPENCODE.md) — Manual install for OpenCode variants.
+- [PI.md](./PI.md) — Pi overview, source-vs-package layout, and manual install.
+
+### 3. Skill Guides
+
+Reference docs for each skill family:
+
+- [ATLASSIAN.md](./ATLASSIAN.md) — Jira/Confluence CLI: requirements, generated
+  bundle sync, install, auth, safety rules, and usage examples.
+- [CREATE-PLAN.md](./CREATE-PLAN.md) — Structured planning with milestones,
+  cross-model review, and reviewer CLI requirements.
+- [DO-TASK.md](./DO-TASK.md) — Single-prompt end-to-end execution with dual
+  reviewer loops, TDD-first, single task commit.
+- [IMPLEMENT-PLAN.md](./IMPLEMENT-PLAN.md) — Worktree-isolated plan execution
+  with iterative cross-model milestone review.
+- [WEB-AUTOMATION.md](./WEB-AUTOMATION.md) — CloakBrowser-backed browsing,
+  scraping, auth, and flow automation.
+
+### 4. Pi-Specific Docs
+
+- [PI-RESEARCH.md](./PI-RESEARCH.md) — Source-backed Pi findings that inform
+  repo Pi variants and packaging choices.
+- [PI-SUPERPOWERS.md](./PI-SUPERPOWERS.md) — How to install or verify Obra
+  Superpowers for Pi.
+- [PI-COMMON-REVIEWER.md](./PI-COMMON-REVIEWER.md) — Shared reviewer-runtime
+  helpers for Pi workflow skills; canonical Pi reviewer flag contract.
+
+### 5. Telegram Notifications
+
+- [TELEGRAM-NOTIFICATIONS.md](./TELEGRAM-NOTIFICATIONS.md) — Shared Telegram
+  notification setup for Codex, Claude Code, OpenCode, Cursor, and Pi.
+
+### 6. Reviewer Matrix
+
+- [REVIEWERS.md](./REVIEWERS.md) — Canonical reviewer CLI support matrix;
+  single source of truth for all workflow variants.
+
+### 7. Development
+
+- [DEVELOPMENT.md](./DEVELOPMENT.md) — Prerequisites, `pnpm run check`,
+  workspace policy, generation workflow, cross-platform shell support, and the
+  quality contract.
+- [CLEANUP-BASELINE.md](./CLEANUP-BASELINE.md) — As-is quality baseline
+  captured at M1, updated through subsequent milestones.
+- [../CHANGELOG.md](../CHANGELOG.md) — Milestone-by-milestone change record
+  (includes M3 package-metadata rename table).
 
 ## Repo Setup