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
2026-05-04 04:41:34 +00:00
parent 2deab1c1b4
commit 251148c3ff
373 changed files with 28504 additions and 1281 deletions
@@ -0,0 +1,13 @@
+{
+  "$schema": "https://ai-coding-skills.dev/schemas/generated-manifest/v1.json",
+  "generator": "scripts/generate-skills.mjs",
+  "generatedRoot": "skills/implement-plan/cursor",
+  "files": [
+    {
+      "path": "SKILL.md",
+      "kind": "file",
+      "mode": "644",
+      "sha256": "8d4e198ccc3ade97ed968b04e07282e9fae56150407bb06e9ee87963f3051cb4"
+    }
+  ]
+}
@@ -3,6 +3,8 @@ name: implement-plan
 description: Use when a plan folder (from create-plan) exists and needs to be executed in an isolated git worktree with iterative cross-model milestone review in Cursor Agent CLI workflows. ALWAYS invoke when user says "implement the plan", "execute the plan", "start implementation", "resume the plan", or similar execution requests.
 ---

+<!-- ⚠️ GENERATED FILE – do not edit directly. Edit the canonical source in skills/implement-plan/_source/cursor/ and run `pnpm run sync:pi`. -->
+
 # Implement Plan (Cursor Agent CLI)

 Execute an existing plan (created by `create-plan`) in an isolated git worktree, with iterative cross-model review at each milestone boundary.
@@ -10,6 +12,7 @@ Execute an existing plan (created by `create-plan`) in an isolated git worktree,
 ## Overview

 This skill wraps the Superpowers execution flow for the Cursor Agent CLI (`cursor-agent`):
+
 1. Locate plan files under `ai_plan/`
 2. Set up an isolated git worktree
 3. Execute milestones one-by-one with lint/typecheck/test gates
@@ -21,6 +24,7 @@ This skill wraps the Superpowers execution flow for the Cursor Agent CLI (`curso
 ## Prerequisite Check (MANDATORY)

 Required:
+
 - Cursor Agent CLI: `cursor-agent --version` (install via `curl https://cursor.com/install -fsS | bash`). The binary is `cursor-agent` (installed to `~/.local/bin/`). Some environments alias it as `cursor agent` (subcommand of the Cursor IDE CLI) — both forms work, but this skill uses `cursor-agent` throughout.
 - `jq` (required only if using `cursor` as the reviewer CLI): `jq --version` (install via `brew install jq` or your package manager)
 - Plan folder exists under `ai_plan/` at project root
@@ -96,7 +100,6 @@ Store `REVIEWER_CLI`, `REVIEWER_MODEL`, and `MAX_ROUNDS`. These values are fixed

 Reviewer CLI: `codex`, `claude`, `cursor`, `opencode`, `pi`, or `skip`.

-
 If `REVIEWER_CLI=pi`, verify the Pi reviewer binary before entering the review loop:

 ```bash
@@ -134,6 +137,7 @@ Mark first story `in-dev` in `story-tracker.md`.
 #### Step 3: Implement Stories

 Execute each story in order. After completing each story:
+
 1. Mark `in-dev` -> `completed` in `story-tracker.md`
 2. Update counts
 3. Mark next story `in-dev`
@@ -168,6 +172,7 @@ git commit -m "feat(<scope>): implement milestone M<N> - <description>"
 ```

 Do NOT push. After committing:
+
 1. Backfill the commit hash into the Notes column for all stories in this milestone in `story-tracker.md`.
 2. Mark milestone as `approved` in `story-tracker.md`.
 3. Move to next milestone.
@@ -183,6 +188,7 @@ REVIEW_ID=$(uuidgen | tr '[:upper:]' '[:lower:]' | head -c 8)
 ```

 Use `REVIEW_ID` for all milestone review temp file paths:
+
 - `/tmp/milestone-${REVIEW_ID}.md`
 - `/tmp/milestone-review-${REVIEW_ID}.md`
 - `/tmp/milestone-review-${REVIEW_ID}.json`
@@ -263,6 +269,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.
@@ -285,7 +292,6 @@ Write the reviewer invocation to `/tmp/milestone-review-${REVIEW_ID}.sh` as a ba
 set -euo pipefail
 ```

-
 **If `REVIEWER_CLI` is `pi`:**

 Fresh call every round (Pi reviewer calls do not use session resume):
@@ -408,6 +414,7 @@ Rules:
 For `cursor`, the command script writes raw JSON to `/tmp/milestone-review-${REVIEW_ID}.json`. Do not run `jq` extraction until after the helper or fallback execution completes.

 Notes on Cursor flags:
+
 - `--mode=ask` — read-only mode, no file modifications
 - `--trust` — trust workspace without prompting (required for non-interactive use)
 - `-p` / `--print` — non-interactive mode, output to stdout
@@ -432,6 +439,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/milestone-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
@@ -457,14 +465,14 @@ Fallback is allowed only when the helper is missing or not executable.
   - `/tmp/milestone-review-${REVIEW_ID}.runner.out`
 3. Present review to the user:

-```
+```markdown
 ## Milestone 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 4 Step 6 (commit & approve)
   - **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
@@ -481,7 +489,7 @@ Fallback is allowed only when the helper is missing or not executable.

 Summarize revisions for the user:

-```
+```markdown
 ### Revisions (Round N)
 - [Change and reason, one bullet per issue addressed]
 ```
@@ -492,7 +500,6 @@ If a revision contradicts the user's explicit requirements, skip it and note it

 Rewrite `/tmp/milestone-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):
@@ -602,20 +609,20 @@ After all milestones are approved and committed:
 git merge implement/<plan-folder-name>
 ```

-4. Delete the worktree and its branch:
+1. Delete the worktree and its branch:

 ```bash
 git worktree remove <worktree-path>
 git branch -d implement/<plan-folder-name>
 ```

-5. Mark plan status as `completed` in `story-tracker.md`.
+1. Mark plan status as `completed` in `story-tracker.md`.

 ### Phase 7: Final Report

 Present summary:

-```
+```markdown
 ## Implementation Complete

 **Plan:** <plan-folder-name>
@@ -645,6 +652,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.
@@ -666,12 +674,14 @@ Rules:
 ## Tracker Discipline (MANDATORY)

 Before starting any story:
+
 1. Open `story-tracker.md`
 2. Mark story `in-dev`
 3. Add notes if relevant
 4. Then begin implementation

 After completing any story:
+
 1. Mark story `completed`
 2. Review pending stories
 3. Update Last Updated and Stories Complete counts