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

skills/create-plan/codex/SKILL.md

@@ -3,6 +3,8 @@ name: create-plan
 description: Use when a user asks to create or maintain a structured implementation plan in Codex, including milestones, bite-sized stories, and resumable local planning artifacts under ai_plan.
 ---
 
+<!-- ⚠️ GENERATED FILE – do not edit directly. Edit the canonical source in skills/create-plan/_source/codex/ and run `pnpm run sync:pi`. -->
+
 # Create Plan (Codex Native Superpowers)
 
 Create and maintain a local plan workspace under `ai_plan/` at project root.
@@ -10,6 +12,7 @@ Create and maintain a local plan workspace under `ai_plan/` at project root.
 ## Overview
 
 This skill wraps the current Superpowers flow for Codex:
+
 1. Design first with `superpowers:brainstorming`
 2. Then build an implementation plan with `superpowers:writing-plans`
 3. Review the plan iteratively with a second model/provider
@@ -20,6 +23,7 @@ This skill wraps the current Superpowers flow for Codex:
 ## Prerequisite Check (MANDATORY)
 
 Required:
+
 - Superpowers skills symlink: `~/.agents/skills/superpowers -> ~/.codex/superpowers/skills`
 - `superpowers:brainstorming`
 - `superpowers:writing-plans`
@@ -50,9 +54,11 @@ If any dependency is missing, stop and return:
 ## Process
 
 ### Phase 1: Analyze
+
 - Explore the codebase and existing patterns.
 
 ### Phase 2: Gather Requirements
+
 - Ask questions one at a time until user says ready.
 - Confirm scope, constraints, success criteria, dependencies.
 
@@ -70,7 +76,6 @@ For shorthand `pi/<pi-model-name>`, split only on the first slash when the prefi
 
 When `REVIEWER_CLI=pi`, the reviewer model is configured independently from the model running this workflow. If the model/provider is unavailable, surface helper stderr/status and use `pi --list-models [search]` to inspect configured models.
 
-
 If the user has already specified a reviewer CLI and model (e.g., "create a plan, review with claude sonnet"), use those values. Otherwise, ask:
 
 1. **Which CLI should review the plan?**
@@ -111,6 +116,7 @@ REVIEW_ID=$(uuidgen | tr '[:upper:]' '[:lower:]' | head -c 8)
 ```
 
 Use for temp artifacts:
+
 - `/tmp/plan-${REVIEW_ID}.md` - plan payload
 - `/tmp/plan-review-${REVIEW_ID}.md` - normalized review text presented to the user
 - `/tmp/plan-review-${REVIEW_ID}.json` - raw Cursor JSON (only for `cursor`)
@@ -166,6 +172,7 @@ VERDICT: APPROVED
 ```
 
 Rules:
+
 - Order findings from `P0` to `P3`.
 - `P0` = total blocker, `P1` = major risk, `P2` = must-fix before approval, `P3` = cosmetic / nice to have.
 - Use `- None.` when a severity has no findings.
@@ -188,7 +195,6 @@ Write the reviewer invocation to `/tmp/plan-review-${REVIEW_ID}.sh` as a bash sc
 set -euo pipefail
 ```
 
-
 **If `REVIEWER_CLI` is `pi`:**
 
 Fresh call every round (Pi reviewer calls do not use session resume):
@@ -321,6 +327,7 @@ fi
 Run the helper in the foreground and watch its live stdout for `state=in-progress` heartbeats. If your agent environment buffers command output until exit, start the helper in the background and poll `/tmp/plan-review-${REVIEW_ID}.status` separately instead of treating heartbeats as post-hoc-only data.
 
 After the command completes:
+
 - If `REVIEWER_CLI=cursor`, extract the final review text:
 
 ```bash
@@ -346,14 +353,14 @@ Fallback is allowed only when the helper is missing or not executable.
    - `/tmp/plan-review-${REVIEW_ID}.runner.out`
 3. Present review to the user:
 
-```
+```markdown
 ## Plan Review — Round N (reviewer: ${REVIEWER_CLI} / ${REVIEWER_MODEL})
 
 [Reviewer feedback]
 ```
 
-4. While the reviewer is still running, keep waiting as long as fresh `state=in-progress note="In progress N"` heartbeats continue to appear roughly once per minute.
-5. Check verdict:
+1. While the reviewer is still running, keep waiting as long as fresh `state=in-progress note="In progress N"` heartbeats continue to appear roughly once per minute.
+2. Check verdict:
    - **VERDICT: APPROVED** with no `P0`, `P1`, or `P2` findings → proceed to Phase 7 (Initialize workspace)
    - **VERDICT: APPROVED** with only `P3` findings → optionally fix the `P3` items if they are cheap and safe, then proceed
    - **VERDICT: REVISE** or any `P0`, `P1`, or `P2` finding → go to Step 5
@@ -368,7 +375,7 @@ Address the reviewer findings in priority order (`P0` → `P1` → `P2`, then `P
 
 Summarize revisions for the user:
 
-```
+```markdown
 ### Revisions (Round N)
 - [Change and reason, one bullet per issue addressed]
 ```
@@ -379,7 +386,6 @@ If a revision contradicts the user's explicit requirements, skip it and note it
 
 Rewrite `/tmp/plan-review-${REVIEW_ID}.sh` for the next round. The script should contain the reviewer invocation only; do not run it directly.
 
-
 **If `REVIEWER_CLI` is `pi`:**
 
 Fresh call with prior-round context (Pi reviewer calls do not use session resume):
@@ -463,7 +469,7 @@ Return to Step 4.
 
 #### Step 7: Present Final Result
 
-```
+```markdown
 ## Plan Review — Final (reviewer: ${REVIEWER_CLI} / ${REVIEWER_MODEL})
 
 **Status:** Approved after N round(s)
@@ -490,16 +496,19 @@ If the round failed, produced empty output, or reached operator-decision timeout
 ### Phase 7: Initialize Local Plan Workspace (MANDATORY)
 
 At project root:
+
 1. Ensure `ai_plan/` exists. Create it if missing.
 2. Ensure `.gitignore` contains `/ai_plan/`.
 3. If `.gitignore` was changed, commit that change immediately (local commit only).
 
 Recommended commit message:
+
 - `chore(gitignore): ignore ai_plan local planning artifacts`
 
 ### Phase 8: Generate Plan Files (MANDATORY)
 
 Create `ai_plan/YYYY-MM-DD-<short-title>/` with all files below:
+
 1. `original-plan.md` - copy of original planner-generated plan.
 2. `final-transcript.md` - copy of final planning transcript used to reach approved plan.
 3. `milestone-plan.md` - full implementation spec (from template).
@@ -532,6 +541,7 @@ fi
 ```
 
 Rules:
+
 - Telegram is the only supported notification path. Do not use desktop notifications, `say`, email, or any other notifier.
 - Notification failures are non-blocking, but they must be surfaced to the user.
 - Before stopping for any user interaction, approval, or manual decision, send a Telegram summary first if configured.