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

README.md

@@ -16,69 +16,36 @@ This repo is organized similarly to `obra/superpowers` and is designed to scale
 ```text
 ai-coding-skills/
 ├── README.md
-├── docs/
-│   ├── README.md
-│   ├── INSTALLER.md
-│   ├── CODEX.md
-│   ├── CLAUDE-CODE.md
-│   ├── CURSOR.md
-│   ├── OPENCODE.md
-│   ├── ATLASSIAN.md
-│   ├── CREATE-PLAN.md
-│   ├── DO-TASK.md
-│   ├── IMPLEMENT-PLAN.md
-│   ├── PI.md
-│   ├── PI-COMMON-REVIEWER.md
-│   ├── PI-RESEARCH.md
-│   ├── PI-SUPERPOWERS.md
-│   ├── TELEGRAM-NOTIFICATIONS.md
-│   └── WEB-AUTOMATION.md
+├── docs/                          — user-facing docs (see docs/README.md)
 ├── skills/
-│   ├── _template/
-│   │   └── SKILL.md
 │   ├── atlassian/
-│   │   ├── codex/
-│   │   ├── claude-code/
-│   │   ├── cursor/
-│   │   ├── opencode/
-│   │   ├── pi/
-│   │   └── shared/
+│   │   ├── codex/   claude-code/   cursor/   opencode/   pi/   shared/
 │   ├── create-plan/
-│   │   ├── codex/
-│   │   ├── claude-code/
-│   │   ├── opencode/
-│   │   ├── cursor/
-│   │   └── pi/
+│   │   ├── codex/   claude-code/   cursor/   opencode/   pi/
 │   ├── do-task/
-│   │   ├── codex/
-│   │   ├── claude-code/
-│   │   ├── opencode/
-│   │   ├── cursor/
-│   │   └── pi/
+│   │   ├── codex/   claude-code/   cursor/   opencode/   pi/
 │   ├── implement-plan/
-│   │   ├── codex/
-│   │   ├── claude-code/
-│   │   ├── opencode/
-│   │   ├── cursor/
-│   │   └── pi/
+│   │   ├── codex/   claude-code/   cursor/   opencode/   pi/
 │   ├── reviewer-runtime/
-│   │   ├── pi/
-│   │   └── tests/
+│   │   ├── pi/        — Pi-specific run-review.sh + notify-telegram.sh
+│   │   └── tests/     — reviewer-runtime smoke tests
 │   └── web-automation/
-│       ├── codex/
-│       ├── claude-code/
-│       ├── cursor/
-│       ├── opencode/
-│       └── pi/
-├── .codex/
-├── .claude-plugin/
-├── .opencode/
-│   └── plugins/
-├── commands/
-├── hooks/
-└── tests/
+│       ├── codex/   claude-code/   cursor/   opencode/   pi/
+├── pi-package/
+│   └── skills/                    — Pi-facing mirror synced by sync:pi
+├── scripts/
+│   ├── lib/                       — shared Node helpers + portable.sh
+│   └── tests/                     — Node.js unit tests
+├── package.json
+└── pnpm-workspace.yaml
 ```
 
+## Where to Read Next
+
+See **[docs/README.md](docs/README.md)** for the full documentation index with
+ordered reading flow, one-line summaries for every doc, and links to per-agent
+install guides, skill docs, Pi docs, Telegram setup, and development notes.
+
 ## Skills
 
 | Skill | Agent Variant | Purpose | Status | Docs |
@@ -150,9 +117,11 @@ node scripts/manage-skills.mjs --client pi --scope packageGlobal --pi-package --
 node scripts/manage-skills.mjs --client pi --scope packageLocal --pi-package --action install --yes
 ```
 
-The wizard detects Codex, Claude Code, Cursor, OpenCode, and Pi, previews operations, checks Superpowers dependencies for workflow skills, and prints a final operation report.
+The wizard detects Codex, Claude Code, Cursor, OpenCode, and Pi, previews operations, checks
+Superpowers dependencies for workflow skills, and prints a final operation report.
 
-`ai_plan/` is gitignored local planning state used by `create-plan` and `do-task`. The skill manager does not install, sync, or publish `ai_plan/` contents.
+`ai_plan/` is gitignored local planning state used by `create-plan` and `do-task`. The skill
+manager does not install, sync, or publish `ai_plan/` contents.
 
 ## Pi Package
 
@@ -162,7 +131,7 @@ The repo root now includes a pi package manifest that ships only the pi-specific
 - `skills/reviewer-runtime/pi/`
 - `docs/PI*.md`
 - `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`
@@ -190,10 +159,30 @@ The repo pins its pnpm version in `package.json` so Corepack-backed installs res
 Before publishing or sharing a tarball, run:
 
 ```bash
-./scripts/sync-pi-package-skills.sh
+pnpm run sync:pi
 npm run verify:pi
 npm run verify:reviewers
 npm pack --dry-run --json
 ```
 
 Additional pi-specific guidance lives in [docs/PI.md](docs/PI.md).
+
+For development prerequisites, quality tooling, and the `pnpm run check`
+contract, see [docs/DEVELOPMENT.md](docs/DEVELOPMENT.md).
+
+## Contributing / Development
+
+See **[docs/DEVELOPMENT.md](docs/DEVELOPMENT.md)** for the full development guide.
+
+Quick reference — the single quality gate every contributor must pass:
+
+```bash
+pnpm install
+pnpm run check      # lint · typecheck · test · verify:pi · verify:reviewers · verify:docs · verify:generated
+```
+
+Prerequisites: Node.js 20+, pnpm 10+, `shellcheck` (brew / apt), `ripgrep` (brew / apt).
+
+CI runs the same `pnpm run check` command on both `ubuntu-latest` and `macos-latest`
+(see `.github/workflows/check.yml`).  External link checking runs separately on a
+weekly schedule (`.github/workflows/check-online.yml`).