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/IMPLEMENT-PLAN.md

@@ -2,7 +2,10 @@
 
 ## Purpose
 
-Execute an existing plan (created by `create-plan`) in an isolated git worktree, with iterative cross-model review at each milestone boundary. Milestones are implemented one-by-one with lint/typecheck/test gates, reviewed by a second model/provider, and committed locally until all are approved.
+Execute an existing plan (created by `create-plan`) in an isolated git worktree, with iterative
+cross-model review at each milestone boundary. Milestones are implemented one-by-one with
+lint/typecheck/test gates, reviewed by a second model/provider, and committed locally until all
+are approved.
 
 ## Requirements
 
@@ -19,7 +22,8 @@ Execute an existing plan (created by `create-plan`) in an isolated git worktree,
   - `superpowers:finishing-a-development-branch`
 - For Codex, native skill discovery must be configured:
   - `~/.agents/skills/superpowers -> ~/.codex/superpowers/skills`
-- Cursor can use the Cursor Superpowers plugin cache or manual `.cursor/skills/superpowers/skills` / `~/.cursor/skills/superpowers/skills` installs.
+- Cursor can use the Cursor Superpowers plugin cache or manual `.cursor/skills/superpowers/skills`
+  / `~/.cursor/skills/superpowers/skills` installs.
 - OpenCode can use `~/.agents/skills/superpowers` or `~/.config/opencode/skills/superpowers`.
 - Shared reviewer runtime must be installed beside agent skills when using reviewer CLIs:
   - Codex: `~/.codex/skills/reviewer-runtime/{run-review.sh,notify-telegram.sh}`
@@ -35,7 +39,9 @@ If dependencies are missing, stop and return:
 
 ### Reviewer CLI Requirements (Optional)
 
-To use the iterative milestone review feature, one of these CLIs must be installed:
+The canonical reviewer CLI support matrix is documented in
+[REVIEWERS.md](./REVIEWERS.md). To use the iterative milestone review feature, one of these CLIs
+must be installed:
 
 | Reviewer CLI | Install | Verify |
 |---|---|---|
@@ -45,9 +51,11 @@ To use the iterative milestone review feature, one of these CLIs must be install
 | `opencode` | `brew install opencode` or your package manager | `opencode --version` |
 | `pi` | Install Pi coding agent | `pi --version`; list models with `pi --list-models [search]` |
 
-The reviewer CLI is independent of which agent is running the implementation — e.g., Claude Code can send milestones to Codex for review, and vice versa.
+The reviewer CLI is independent of which agent is running the implementation — e.g., Claude Code
+can send milestones to Codex for review, and vice versa.
 
-**Additional dependency for `cursor` reviewer:** `jq` is required to parse Cursor's JSON output. Install via `brew install jq` (macOS) or your package manager. Verify: `jq --version`.
+**Additional dependency for `cursor` reviewer:** `jq` is required to parse Cursor's JSON output.
+Install via `brew install jq` (macOS) or your package manager. Verify: `jq --version`.
 
 ## Install
 
@@ -116,7 +124,7 @@ Recommended full Pi package install:
 Manual single-skill Pi install from the package mirror:
 
 ```bash
-./scripts/sync-pi-package-skills.sh
+pnpm run sync:pi
 mkdir -p .pi/skills/implement-plan
 cp -R pi-package/skills/implement-plan/* .pi/skills/implement-plan/
 mkdir -p .pi/skills/reviewer-runtime/pi
@@ -124,7 +132,8 @@ cp -R skills/reviewer-runtime/pi/* .pi/skills/reviewer-runtime/pi/
 chmod +x .pi/skills/reviewer-runtime/pi/*.sh
 ```
 
-Global manual installs use `~/.pi/agent/skills/implement-plan/` and `~/.pi/agent/skills/reviewer-runtime/pi/` instead of `.pi/skills/...`.
+Global manual installs use `~/.pi/agent/skills/implement-plan/` and
+`~/.pi/agent/skills/reviewer-runtime/pi/` instead of `.pi/skills/...`.
 
 Pi workflow skills also require Superpowers. See [PI-SUPERPOWERS.md](./PI-SUPERPOWERS.md) and [PI-COMMON-REVIEWER.md](./PI-COMMON-REVIEWER.md).
 
@@ -157,14 +166,30 @@ Verify Superpowers execution dependencies exist in your agent skills root:
 - OpenCode: `~/.agents/skills/superpowers/using-git-worktrees/SKILL.md` or `~/.config/opencode/skills/superpowers/using-git-worktrees/SKILL.md`
 - OpenCode: `~/.agents/skills/superpowers/verification-before-completion/SKILL.md` or `~/.config/opencode/skills/superpowers/verification-before-completion/SKILL.md`
 - OpenCode: `~/.agents/skills/superpowers/finishing-a-development-branch/SKILL.md` or `~/.config/opencode/skills/superpowers/finishing-a-development-branch/SKILL.md`
-- Cursor: `.cursor/skills/superpowers/skills/executing-plans/SKILL.md`, `~/.cursor/skills/superpowers/skills/executing-plans/SKILL.md`, or the Cursor Superpowers plugin cache
-- Cursor: `.cursor/skills/superpowers/skills/using-git-worktrees/SKILL.md`, `~/.cursor/skills/superpowers/skills/using-git-worktrees/SKILL.md`, or the Cursor Superpowers plugin cache
-- Cursor: `.cursor/skills/superpowers/skills/verification-before-completion/SKILL.md`, `~/.cursor/skills/superpowers/skills/verification-before-completion/SKILL.md`, or the Cursor Superpowers plugin cache
-- Cursor: `.cursor/skills/superpowers/skills/finishing-a-development-branch/SKILL.md`, `~/.cursor/skills/superpowers/skills/finishing-a-development-branch/SKILL.md`, or the Cursor Superpowers plugin cache
-- Pi: `.pi/skills/superpowers/executing-plans/SKILL.md` or `~/.pi/agent/skills/superpowers/executing-plans/SKILL.md` or `~/.agents/skills/superpowers/executing-plans/SKILL.md`
-- Pi: `.pi/skills/superpowers/using-git-worktrees/SKILL.md` or `~/.pi/agent/skills/superpowers/using-git-worktrees/SKILL.md` or `~/.agents/skills/superpowers/using-git-worktrees/SKILL.md`
-- Pi: `.pi/skills/superpowers/verification-before-completion/SKILL.md` or `~/.pi/agent/skills/superpowers/verification-before-completion/SKILL.md` or `~/.agents/skills/superpowers/verification-before-completion/SKILL.md`
-- Pi: `.pi/skills/superpowers/finishing-a-development-branch/SKILL.md` or `~/.pi/agent/skills/superpowers/finishing-a-development-branch/SKILL.md` or `~/.agents/skills/superpowers/finishing-a-development-branch/SKILL.md`
+- Cursor: `.cursor/skills/superpowers/skills/executing-plans/SKILL.md`,
+  `~/.cursor/skills/superpowers/skills/executing-plans/SKILL.md`, or the Cursor Superpowers
+  plugin cache
+- Cursor: `.cursor/skills/superpowers/skills/using-git-worktrees/SKILL.md`,
+  `~/.cursor/skills/superpowers/skills/using-git-worktrees/SKILL.md`, or the Cursor Superpowers
+  plugin cache
+- Cursor: `.cursor/skills/superpowers/skills/verification-before-completion/SKILL.md`,
+  `~/.cursor/skills/superpowers/skills/verification-before-completion/SKILL.md`, or the Cursor
+  Superpowers plugin cache
+- Cursor: `.cursor/skills/superpowers/skills/finishing-a-development-branch/SKILL.md`,
+  `~/.cursor/skills/superpowers/skills/finishing-a-development-branch/SKILL.md`, or the Cursor
+  Superpowers plugin cache
+- Pi: `.pi/skills/superpowers/executing-plans/SKILL.md` or
+  `~/.pi/agent/skills/superpowers/executing-plans/SKILL.md` or
+  `~/.agents/skills/superpowers/executing-plans/SKILL.md`
+- Pi: `.pi/skills/superpowers/using-git-worktrees/SKILL.md` or
+  `~/.pi/agent/skills/superpowers/using-git-worktrees/SKILL.md` or
+  `~/.agents/skills/superpowers/using-git-worktrees/SKILL.md`
+- Pi: `.pi/skills/superpowers/verification-before-completion/SKILL.md` or
+  `~/.pi/agent/skills/superpowers/verification-before-completion/SKILL.md` or
+  `~/.agents/skills/superpowers/verification-before-completion/SKILL.md`
+- Pi: `.pi/skills/superpowers/finishing-a-development-branch/SKILL.md` or
+  `~/.pi/agent/skills/superpowers/finishing-a-development-branch/SKILL.md` or
+  `~/.agents/skills/superpowers/finishing-a-development-branch/SKILL.md`
 
 ## Key Behavior
 
@@ -173,14 +198,17 @@ Verify Superpowers execution dependencies exist in your agent skills root:
 - Executes milestones one-by-one, tracking stories in `story-tracker.md`.
 - Runs lint/typecheck/tests as a gate before each milestone review.
 - Sends each milestone to a reviewer CLI for approval (max rounds configurable, default 10).
-- Runs reviewer commands through `reviewer-runtime/run-review.sh` when available, with fallback to direct synchronous execution only if the helper is missing.
+- Runs reviewer commands through `reviewer-runtime/run-review.sh` when available, with fallback to
+  direct synchronous execution only if the helper is missing.
 - Waits as long as the reviewer runtime keeps emitting per-minute `In progress N` heartbeats.
 - Requires reviewer findings to be ordered `P0` through `P3`, with `P3` explicitly non-blocking.
-- Captures reviewer stderr and helper status logs for diagnostics and retains them on failed, empty-output, or operator-decision review rounds.
+- Captures reviewer stderr and helper status logs for diagnostics and retains them on failed,
+  empty-output, or operator-decision review rounds.
 - Commits each milestone locally only after reviewer approval (does not push).
 - After all milestones approved, merges worktree branch to parent and deletes worktree.
 - Supports resume: detects existing worktree and `in-dev`/`completed` stories.
-- Sends completion notifications through Telegram only when the shared setup in [TELEGRAM-NOTIFICATIONS.md](./TELEGRAM-NOTIFICATIONS.md) is installed and configured.
+- Sends completion notifications through Telegram only when the shared setup in
+  [TELEGRAM-NOTIFICATIONS.md](./TELEGRAM-NOTIFICATIONS.md) is installed and configured.
 
 ## Milestone Review Loop
 
@@ -189,7 +217,8 @@ After each milestone is implemented and verified, the skill sends it to a second
 1. **Configure** — user picks a reviewer CLI (`codex`, `claude`, `cursor`, `opencode`, `pi`) and model, or skips
 2. **Prepare** — milestone payload and a bash reviewer command script are written to temp files
 3. **Run** — the command script is executed through `reviewer-runtime/run-review.sh` when installed
-4. **Feedback** — reviewer evaluates correctness, acceptance criteria, code quality, test coverage, security, and returns `## Summary`, `## Findings`, and `## Verdict`
+4. **Feedback** — reviewer evaluates correctness, acceptance criteria, code quality, test coverage,
+   security, and returns `## Summary`, `## Findings`, and `## Verdict`
 5. **Prioritize** — findings are ordered `P0`, `P1`, `P2`, `P3`
 6. **Revise** — the implementing agent addresses findings in priority order, re-verifies, and re-submits
 7. **Repeat** — up to max rounds (default 10) until the reviewer returns `VERDICT: APPROVED`
@@ -224,13 +253,17 @@ ts=<ISO-8601> level=<info|warn|error> state=<running-silent|running-active|in-pr
 ```
 
 `in-progress` is the liveness heartbeat emitted roughly once per minute with `note="In progress N"`.
-`stall-warning` is a non-terminal status-log state only. It does not mean the caller should stop waiting if `in-progress` heartbeats continue.
+`stall-warning` is a non-terminal status-log state only. It does not mean the caller should stop
+waiting if `in-progress` heartbeats continue.
 
 ### Failure Handling
 
-- `completed-empty-output` means the reviewer exited without producing review text; surface `.stderr` and `.status`, then retry only after diagnosing the cause.
-- `needs-operator-decision` means the helper reached hard-timeout escalation; surface `.status` and decide whether to extend the timeout, abort, or retry with different parameters.
-- Successful rounds clean up temp artifacts. Failed, empty-output, and operator-decision rounds should retain `.stderr`, `.status`, and `.runner.out` until diagnosed.
+- `completed-empty-output` means the reviewer exited without producing review text; surface
+  `.stderr` and `.status`, then retry only after diagnosing the cause.
+- `needs-operator-decision` means the helper reached hard-timeout escalation; surface `.status`
+  and decide whether to extend the timeout, abort, or retry with different parameters.
+- Successful rounds clean up temp artifacts. Failed, empty-output, and operator-decision rounds
+  should retain `.stderr`, `.status`, and `.runner.out` until diagnosed.
 - As long as fresh `in-progress` heartbeats continue to arrive roughly once per minute, the caller should keep waiting.
 
 ### Supported Reviewer CLIs
@@ -249,15 +282,21 @@ For all supported reviewer CLIs, the preferred execution path is:
 2. run that script through `reviewer-runtime/run-review.sh`
 3. fall back to direct synchronous execution only if the helper is missing or not executable
 
-
-
 ## Pi Reviewer Support
 
-All workflow variants can use Pi itself as a reviewer CLI. Use `pi/<pi-model-name>` shorthand, for example `pi/claude-opus-4-7`; this means `REVIEWER_CLI=pi` and `REVIEWER_MODEL=claude-opus-4-7`. Provider-qualified or multi-slash Pi model IDs are preserved after the first `pi/` prefix, for example `pi/anthropic/claude-opus-4-7`.
+All workflow variants can use Pi itself as a reviewer CLI. Use `pi/<pi-model-name>` shorthand, for
+example `pi/claude-opus-4-7`; this means `REVIEWER_CLI=pi` and `REVIEWER_MODEL=claude-opus-4-7`.
+Provider-qualified or multi-slash Pi model IDs are preserved after the first `pi/` prefix, for
+example `pi/anthropic/claude-opus-4-7`.
 
-The canonical isolated read-only Pi reviewer flag contract lives in [PI-COMMON-REVIEWER.md](./PI-COMMON-REVIEWER.md). This workflow passes the milestone review payload at `/tmp/milestone-${REVIEW_ID}.md` and expects the standard `## Summary`, `## Findings`, and `## Verdict` response. Pi reviewer output is captured as markdown stdout, not JSON.
+The canonical isolated read-only Pi reviewer flag contract lives in
+[PI-COMMON-REVIEWER.md](./PI-COMMON-REVIEWER.md). This workflow passes the milestone review
+payload at `/tmp/milestone-${REVIEW_ID}.md` and expects the standard `## Summary`,
+`## Findings`, and `## Verdict` response. Pi reviewer output is captured as markdown stdout,
+not JSON.
 
-If the Pi reviewer model or provider is unavailable, surface the helper stderr/status and use `pi --list-models [search]` to inspect configured models.
+If the Pi reviewer model or provider is unavailable, surface the helper stderr/status and use
+`pi --list-models [search]` to inspect configured models.
 
 ## Notifications
 
@@ -282,7 +321,7 @@ run-review.sh \
 
 ## Variant Hardening Notes
 
-### Claude Code
+### Claude Code Hardening
 
 - Must invoke explicit required sub-skills:
   - `superpowers:executing-plans`
@@ -290,7 +329,7 @@ run-review.sh \
   - `superpowers:verification-before-completion`
   - `superpowers:finishing-a-development-branch`
 
-### Codex
+### Codex Hardening
 
 - Must use native skill discovery from `~/.agents/skills/` (no CLI wrappers).
 - Must verify Superpowers skills symlink: `~/.agents/skills/superpowers -> ~/.codex/superpowers/skills`
@@ -298,7 +337,7 @@ run-review.sh \
 - Must track checklist-driven skills with `update_plan` todos.
 - Deprecated CLI commands (`superpowers-codex bootstrap`, `use-skill`) must NOT be used.
 
-### OpenCode
+### OpenCode Hardening
 
 - Must use OpenCode native skill tool (not Claude/Codex invocation syntax).
 - Must verify Superpowers skill discovery under:
@@ -306,7 +345,7 @@ run-review.sh \
   - `~/.config/opencode/skills/superpowers`
 - Must explicitly load all four execution sub-skills.
 
-### Cursor
+### Cursor Hardening
 
 - Must use Cursor-native discovery from `.cursor/skills/`, `~/.cursor/skills/`, or installed Cursor plugin cache entries.
 - Must announce skill usage explicitly before invocation.