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/do-task/opencode/.generated-manifest.json

@@ -0,0 +1,19 @@
+{
+  "$schema": "https://ai-coding-skills.dev/schemas/generated-manifest/v1.json",
+  "generator": "scripts/generate-skills.mjs",
+  "generatedRoot": "skills/do-task/opencode",
+  "files": [
+    {
+      "path": "SKILL.md",
+      "kind": "file",
+      "mode": "644",
+      "sha256": "ebbae7c050b3cfe0d1de8722cd71c8c10ba74de709adeec4ebb9645e2f770a03"
+    },
+    {
+      "path": "templates/task-plan.md",
+      "kind": "file",
+      "mode": "644",
+      "sha256": "a4c0ad9a9faaf738c503b403a285b6a005ee245b6b05f5af973c8e0224f6fefe"
+    }
+  ]
+}

skills/do-task/opencode/SKILL.md

@@ -3,6 +3,8 @@ name: do-task
 description: Execute a single user-supplied prompt end-to-end with two reviewer loops (plan review + implementation review) in OpenCode. ALWAYS invoke when the user says `/do-task`, "do this task", "do task ...", "execute this task", or "make it so". Also invoke on the hint phrase "just do ...". Do NOT invoke on "implement this" (that phrase is reserved for implement-plan).
 ---
 
+<!-- ⚠️ GENERATED FILE – do not edit directly. Edit the canonical source in skills/do-task/_source/opencode/ and run `pnpm run sync:pi`. -->
+
 # Do Task (OpenCode)
 
 Execute an ad-hoc user prompt end-to-end: parse → clarify → plan (with reviewer loop) → implement (TDD-first where applicable) → verify → implementation review loop → commit → optional push → notify.
@@ -14,6 +16,7 @@ This is a single-artifact sibling of `create-plan` + `implement-plan`. Unlike `i
 ## Prerequisite Check (MANDATORY)
 
 Required:
+
 - OpenCode CLI: `opencode --version` (install via your package manager or `brew install opencode`).
 - Superpowers repo: `https://github.com/obra/superpowers`
 - OpenCode Superpowers skills available at `~/.agents/skills/superpowers` or `~/.config/opencode/skills/superpowers`
@@ -50,6 +53,7 @@ If any required dependency is missing, stop immediately and return:
 ## Trigger Phrase Detection
 
 **Binding triggers** (always invoke this skill):
+
 - `/do-task`
 - "do this task"
 - "do task ..."
@@ -57,24 +61,29 @@ If any required dependency is missing, stop immediately and return:
 - "make it so"
 
 **Hint trigger** (invoke unless context clearly maps to another skill):
+
 - "just do ..."
 
 **Escape phrases** (skip the Phase 2 clarifying-question loop):
+
 - `--no-questions`
 - `"just do it:"`
 - `"just do this:"`
 - `"no questions:"`
 
 **Excluded** (do NOT trigger `do-task`):
+
 - "implement this" — reserved for `implement-plan`.
 
 **Dropped defaults** (explicitly NOT binding triggers):
+
 - "work on ..."
 - "handle this"
 - "take care of ..."
 - "get this done"
 
 **Worktree opt-in phrases** (Phase 4 takes the worktree branch):
+
 - "in a worktree"
 - "use a worktree"
 - "on an isolated branch"
@@ -133,7 +142,6 @@ Store `REVIEWER_CLI`, `REVIEWER_MODEL`, and `MAX_ROUNDS` for Phases 5 and 8.
 
 Reviewer CLI: `codex`, `claude`, `cursor`, `opencode`, `pi`, or `skip`.
 
-
 If `REVIEWER_CLI=pi`, verify the Pi reviewer binary before entering the review loop:
 
 ```bash
@@ -149,6 +157,7 @@ When `REVIEWER_CLI=pi`, the reviewer model is configured independently from the
 OpenCode has no plan-mode concept; there is no plan-mode guard here.
 
 Steps:
+
 1. Compute slug: `YYYY-MM-DD-<slug>` where `<slug>` is a kebab-case hash of the task goal (lowercase, alphanumeric + hyphens only).
 2. Compute plan folder: `ai_plan/<slug>/`.
 3. **Resume detection:** If the folder already exists, read `task-plan.md`:
@@ -170,7 +179,7 @@ If `REVIEWER_CLI=skip`, present `task-plan.md` to the user and proceed only afte
 
 Otherwise, invoke the Review Loop (Shared Subroutine) with:
 
-```
+```text
 REVIEW_KIND     = plan
 REVIEW_ID       = $(uuidgen | tr '[:upper:]' '[:lower:]' | head -c 8)
 PAYLOAD_PATH    = /tmp/do-task-plan-${REVIEW_ID}.md
@@ -208,11 +217,13 @@ Rules:
 ```
 
 On APPROVED:
+
 - Set `Status: plan-approved`.
 - Append APPROVED row to Review History.
 - Proceed to Phase 6.
 
 On MAX_ROUNDS:
+
 - Set `Status: aborted-plan-review`.
 - Send Telegram summary before stopping.
 - Ask the user whether to override and proceed, restart, or abort.
@@ -238,16 +249,19 @@ Native orchestration — do not invoke `superpowers:executing-plans`.
 Invoke `superpowers/verification-before-completion` via OpenCode's native skill tool.
 
 Run the commands listed in the `Verification` section of `task-plan.md`:
+
 - Lint (changed files first).
 - Typecheck.
 - Tests (targeted first, then broader suite if quick).
 
 All must pass. If a command fails:
+
 - Fix the issue.
 - Re-run that command.
 - Increment `verification_attempts` in Runtime State.
 
 If `verification_attempts` exceeds 3 without green:
+
 - Set `Status: aborted-verification`.
 - Send Telegram summary.
 - Ask the user whether to retry, override, or abort.
@@ -258,7 +272,7 @@ If `REVIEWER_CLI=skip`, present a diff + verification summary to the user and pr
 
 Otherwise, invoke the Review Loop (Shared Subroutine) with:
 
-```
+```text
 REVIEW_KIND     = implementation
 REVIEW_ID       = $(uuidgen | tr '[:upper:]' '[:lower:]' | head -c 8)   # distinct from plan-review ID
 PAYLOAD_PATH    = /tmp/do-task-implementation-${REVIEW_ID}.md
@@ -314,11 +328,13 @@ Rules:
 ```
 
 On APPROVED:
+
 - Set `Status: implementation-approved`.
 - Append APPROVED row to Review History.
 - Proceed to Phase 9.
 
 On MAX_ROUNDS:
+
 - Set `Status: aborted-impl-review`.
 - Send Telegram summary.
 - Ask the user whether to override and commit anyway, restart, or abort.
@@ -353,6 +369,7 @@ fi
 ```
 
 Rules:
+
 - Telegram is the only supported notification path.
 - Notification failures are non-blocking but must be surfaced to the user.
 - Before stopping for any user interaction, approval, or manual decision, send a Telegram summary first if configured.
@@ -443,18 +460,19 @@ If `SCAN_MATCHES` is non-empty:
 1. **Redact the matched text before surfacing** — never echo the raw secret to the user, chat log, terminal scrollback, or any persistent file. Replace each matched substring with a fixed token that preserves only the fact of a match: `[REDACTED:<pattern-label>:<match-length>-chars]`. Example: a matched AWS key becomes `[REDACTED:aws-access-key:20-chars]`. Keep the file path and line number; they are useful for the user and not secret.
 2. Present the redacted match summary to the user using this exact wording:
 
-   ```
+   ```text
    SECRET-SCAN MATCH in outbound reviewer payload (loop: ${REVIEW_KIND}, round: N):
    <file>:<line>: [REDACTED:<pattern-label>:<match-length>-chars]
    ...
    Proceed with sending this payload to ${REVIEWER_CLI}? (yes / no / redact)
    ```
+
    Pattern labels: `aws-access-key`, `gcp-service-account`, `github-token`, `slack-token`, `openai-key`, `anthropic-key`, `pem-private-key`, `dotenv-style`, `jwt`.
 
-2. Wait for user response.
-3. On `yes`: record `last_scan_outcome_${REVIEW_KIND}=user-approved-with-matches` in Runtime State, and proceed.
-4. On `redact`: ask the user to supply redactions, apply them to `PAYLOAD_PATH`, re-scan (this step), record `last_scan_outcome_${REVIEW_KIND}=redacted-and-approved`.
-5. On `no`: stop the loop, set `Status: failed`, send Telegram, return to the user.
+3. Wait for user response.
+4. On `yes`: record `last_scan_outcome_${REVIEW_KIND}=user-approved-with-matches` in Runtime State, and proceed.
+5. On `redact`: ask the user to supply redactions, apply them to `PAYLOAD_PATH`, re-scan (this step), record `last_scan_outcome_${REVIEW_KIND}=redacted-and-approved`.
+6. On `no`: stop the loop, set `Status: failed`, send Telegram, return to the user.
 
 If `SCAN_MATCHES` is empty, record `last_scan_outcome_${REVIEW_KIND}=clean` and proceed.
 
@@ -467,7 +485,6 @@ Write the reviewer invocation to `/tmp/do-task-${REVIEW_KIND}-review-${REVIEW_ID
 set -euo pipefail
 ```
 
-
 **If `REVIEWER_CLI` is `pi`:**
 
 Fresh call every round (Pi reviewer calls do not use session resume):
@@ -671,15 +688,19 @@ After the command completes:
 
 - `cursor`: already promoted in Step 2 via `jq -r '.result' ...`. Also capture `session_id` if first round.
 - `codex`: extract `CODEX_SESSION_ID` from `/tmp/do-task-${REVIEW_KIND}-review-${REVIEW_ID}.runner.out` after the helper or fallback run. If the review text lives only in `.runner.out`, `cp` it into the `.md` file:
+
   ```bash
   cp /tmp/do-task-${REVIEW_KIND}-review-${REVIEW_ID}.runner.out \
      /tmp/do-task-${REVIEW_KIND}-review-${REVIEW_ID}.md
   ```
+
 - `claude` or `pi`: promote `.runner.out` into the `.md` file:
+
   ```bash
   cp /tmp/do-task-${REVIEW_KIND}-review-${REVIEW_ID}.runner.out \
      /tmp/do-task-${REVIEW_KIND}-review-${REVIEW_ID}.md
   ```
+
 - `opencode`: already promoted in Step 2 via `jq` on the JSON stream. If opt-in session-resume is active and the JSON includes a stable session id, capture it and persist to `${SESSION_ID_VAR}`.
 
 On Round 1, persist the captured session ID (if any) into `task-plan.md`'s Runtime State under `${SESSION_ID_VAR}`.
@@ -737,6 +758,7 @@ If the round failed, produced empty output, or reached operator-decision timeout
 1. Detect existing plan folder by slug at Phase 4.
 2. Read `task-plan.md` → `Status`.
 3. Decide next action:
+
    | Status | Action |
    |--------|--------|
    | `draft` | Resume at Phase 5 (plan review) |
@@ -745,6 +767,7 @@ If the round failed, produced empty output, or reached operator-decision timeout
    | `implementation-approved` | Resume at Phase 9 (commit + push ask) |
    | `pushed` \| `local-only` | Ask user: new suffix, abort, or replay for reference only |
    | `aborted-*` \| `failed` | Offer new suffix or full restart |
+
 4. When resuming, read Runtime State for `CODEX_PLAN_SESSION_ID`, `CODEX_IMPL_SESSION_ID`, `CURSOR_PLAN_SESSION_ID`, `CURSOR_IMPL_SESSION_ID`, `OPENCODE_PLAN_SESSION_ID`, `OPENCODE_IMPL_SESSION_ID`, and the round counters. If a session ID is populated, use it for the first revision round in that loop (Round 2) via `codex exec resume`, `cursor-agent --resume`, or `opencode run -s <id>` as applicable.
 
 ---
@@ -754,10 +777,12 @@ If the round failed, produced empty output, or reached operator-decision timeout
 **ALWAYS update `task-plan.md` before/after each phase transition. NEVER proceed with stale state.**
 
 Before starting any phase:
+
 1. Update `Status` if it transitions.
 2. Update `last_phase_entered` in Runtime State.
 
 After completing any phase:
+
 1. Update `Status` if it transitions.
 2. Append notes to the relevant section of `task-plan.md`.
 

skills/do-task/opencode/templates/task-plan.md

@@ -1,3 +1,4 @@
+<!-- ⚠️ GENERATED FILE – do not edit directly. Edit the canonical source in skills/do-task/_source/opencode/ and run `pnpm run sync:pi`. -->
 # Task Plan: [Short Title]
 
 > **Variant guardrail (OpenCode):** Sub-skills (`brainstorming`, `test-driven-development`, `verification-before-completion`, `finishing-a-development-branch`, `using-git-worktrees`) MUST be invoked through OpenCode's native skill tool from `~/.config/opencode/skills/superpowers/<skill>/SKILL.md`. Phase 1 MUST include the Bootstrap Superpowers Context step. Opencode reviewer calls MUST use `--agent plan` to stay read-only.
@@ -132,7 +133,6 @@ tdd_used: false
   - Notes (anything the user should know when revisiting)
 -->
 
-
 ---
 
 ## Guardrails (do NOT remove)