@smartsoft001/pro-claude-plugins 0.2.0

package/plugins/flow/skills/push/SKILL.md

@@ -0,0 +1,759 @@
+---
+name: push
+description: Push local changes to remote repository, update Linear task status, monitor CI pipeline, verify QA deployment, and optionally create pull requests for feature branches.
+allowed-tools:
+  - Bash
+  - Read
+  - Glob
+  - Grep
+  - AskUserQuestion
+  - WebFetch
+  - TaskCreate
+  - TaskUpdate
+  - TaskList
+  - TaskGet
+  - mcp__linear__get_issue
+  - mcp__linear__list_issues
+  - mcp__linear__list_comments
+  - mcp__linear__save_comment
+  - mcp__linear__save_issue
+  - mcp__linear__list_issue_statuses
+---
+
+# Push Skill
+
+Push local changes to remote and optionally update Linear task status.
+
+## Execution Checklist
+
+Execute each step in order. Do not skip any step marked as MANDATORY.
+
+### Pre-Push
+
+- [ ] **1. Check git status** — verify branch, commits ahead, warn about uncommitted changes
+- [ ] **2. Get commits to push** — `git log origin/<branch>..HEAD --oneline`; exit if none
+- [ ] **3. Fetch Linear task** — get title, status, subtasks and their statuses via MCP
+- [ ] **4. Analyze subtasks** — classify completed vs incomplete, find reasons for incomplete ones
+- [ ] **5. MANDATORY: Show summary to user** — present commits + subtask status, ask about status change
+- [ ] **6. Update Linear status** — BEFORE push: set completed subtasks to "In Review", post summary comment in Polish
+- [ ] **7. MANDATORY: Write Linear comments in Polish** — all comments must be in Polish language
+
+### Push
+
+- [ ] **8. Push to remote** — `git push`; handle errors gracefully
+
+### Post-Push (branch-specific)
+
+#### If `development` branch:
+
+- [ ] **9a. Ask about deployment verification** — offer optional CI monitoring + QA check
+- [ ] **10a. Monitor CI pipeline** — poll `gh run view` every 30s until completion
+- [ ] **11a. Handle CI failure** — revert task to "To Do", post error comment to Linear
+- [ ] **12a. Verify package.json update** — `git pull`, compare versions
+- [ ] **13a. Verify QA deployment** — wait 5 min, check `<meta name="app-version">` matches
+
+#### If feature branch:
+
+- [ ] **9b. Check for existing PR** — `gh pr list --head <branch> --base development`
+- [ ] **10b. Ask about PR creation** — if no PR exists and subtasks are ready
+- [ ] **11b. Create PR** — `gh pr create` with structured summary
+
+### Final
+
+- [ ] **12. Show final status** — complete summary of all actions taken
+
+### Task Progress Tracking
+
+**MANDATORY**: Use Claude Code's built-in task tracking to provide real-time progress visibility.
+
+**Task naming convention**: Every task subject MUST be prefixed with the Linear task ID:
+
+```
+<linearTaskId> <step description>
+```
+
+**At skill start**: Create tasks for each checklist step using `TaskCreate`:
+
+```
+TaskCreate({
+  subject: "MM-123 Check git status",
+  description: "Verify branch, commits ahead, warn about uncommitted changes",
+  activeForm: "MM-123 Checking git status"
+})
+TaskCreate({
+  subject: "MM-123 Push to remote",
+  description: "Execute git push and handle errors",
+  activeForm: "MM-123 Pushing to remote"
+})
+```
+
+**During execution**:
+
+- Before starting a step → `TaskUpdate({ taskId, status: "in_progress" })`
+- After completing a step → `TaskUpdate({ taskId, status: "completed" })`
+- For branch-specific steps, only create tasks for the applicable branch path (development OR feature)
+
+**Before user decisions**: Use `TaskList` to show progress overview before asking user about status changes or PR creation.
+
+## Usage
+
+```
+/push-local [linearTaskId]
+```
+
+## Parameters
+
+- `linearTaskId` - Linear task ID (e.g., FRA-123)
+
+## Instructions
+
+You are tasked with pushing local changes to the remote repository, summarizing what was done, and optionally moving the Linear task to "In Review".
+
+### Step 1: Check Git Status
+
+Run `git status` to verify:
+
+- Current branch name
+- Number of commits ahead of remote
+- Any uncommitted changes (warn user if present)
+
+If there are uncommitted changes, warn the user and ask if they want to proceed or commit first.
+
+### Step 2: Get Commits to Push
+
+Run `git log origin/<branch>..HEAD --oneline` to get the list of commits that will be pushed.
+
+If no commits to push, inform the user and exit.
+
+### Step 3: Fetch Linear Task Details (if linearTaskId provided)
+
+If `linearTaskId` was provided, use MCP Linear server to fetch:
+
+- Task title
+- Current status
+- Subtasks (if any) and their statuses
+- Comments on subtasks (to find reasons for incomplete items)
+
+### Step 4: Analyze Subtasks Status
+
+For each subtask, determine:
+
+1. **Completed subtasks**: Status is "Done", "In Review", or has implementation completed
+2. **Incomplete subtasks**: Status is "To Do", "Blocked", or was not implemented
+
+For incomplete subtasks, find the reason by:
+
+- Reading comments on the subtask (look for "Analiza problemu", "Blocker", "Status: Blocked")
+- Checking if it was marked as backend issue, external dependency, etc.
+
+Build a summary of incomplete items with reasons.
+
+### Step 5: Show Summary and Ask About Status Update
+
+Show summary of what will be pushed and ask user:
+
+```markdown
+## Podsumowanie
+
+### Commity do wysłania (X)
+
+| Commit  | Opis                       |
+| ------- | -------------------------- |
+| abc1234 | feat(scope): description 1 |
+| def5678 | fix(scope): description 2  |
+
+### Podzadania
+
+#### Zrealizowane
+
+- ✅ FRA-549: Naprawić szerokość logo
+- ✅ FRA-550: Usunąć zdublowane zdjęcia
+
+#### Niezrealizowane
+
+- ⚠️ FRA-554: Obsłużyć zdjęcia PNG → Problem backendu
+
+---
+
+**Task**: [linearTaskId] - [Task Title]
+**Aktualny status**: [Current Status]
+
+Czy przenieść task do "In Review" i wysłać zmiany?
+```
+
+Use `AskUserQuestion` tool with options:
+
+- "Tak, przenieś do In Review i wyślij" (Recommended)
+- "Tylko wyślij, bez zmiany statusu"
+- "Anuluj"
+
+### Step 6: Update Linear Status (if confirmed)
+
+**BEFORE pushing**, if user confirmed status change:
+
+1. **For tasks with subtasks**: Update all completed subtasks to "In Review"
+2. **For tasks without subtasks**: Update the task itself to "In Review"
+
+**Before posting**, run the token-summing script and capture its output:
+
+```bash
+bash "$CLAUDE_PLUGIN_ROOT/scripts/compute-session-tokens.sh"
+```
+
+It prints four whitespace-separated integers on one line: `<INPUT> <OUTPUT> <CACHE_CREATE> <CACHE_READ>`. If no transcript can be located it prints `0 0 0 0` and exits non-zero — treat that as a graceful skip (still post the comment, with zeros in the table).
+
+Compute `<TOTAL> = <INPUT> + <OUTPUT> + <CACHE_CREATE> + <CACHE_READ>`. Append exactly one copy of the following Polish block to the bottom of the comment body, after the existing `_Raport wygenerowany przez Claude Code_` footer. Do not create a second Linear comment — the block belongs in **this** comment.
+
+```markdown
+## Zużycie tokenów — etap /push
+
+| Metryka        | Wartość        |
+| -------------- | -------------- |
+| Input          | <INPUT>        |
+| Output         | <OUTPUT>       |
+| Cache creation | <CACHE_CREATE> |
+| Cache read     | <CACHE_READ>   |
+| **Łącznie**    | **<TOTAL>**    |
+```
+
+Create a comment on the **parent task** summarizing:
+
+```markdown
+## Podsumowanie Implementacji
+
+### Branch
+
+`<branch-name>`
+
+### Zrealizowane Podzadania
+
+| Podzadanie | Tytuł                     | Status          |
+| ---------- | ------------------------- | --------------- |
+| FRA-549    | Naprawić szerokość logo   | ✅ Zrealizowane |
+| FRA-550    | Usunąć zdublowane zdjęcia | ✅ Zrealizowane |
+
+### Niezrealizowane Podzadania
+
+| Podzadanie | Tytuł                | Powód                                                   |
+| ---------- | -------------------- | ------------------------------------------------------- |
+| FRA-554    | Obsłużyć zdjęcia PNG | ⚠️ Problem backendu - wymaga naprawy po stronie serwera |
+
+### Commity
+
+| Commit  | Opis                       |
+| ------- | -------------------------- |
+| abc1234 | feat(scope): description 1 |
+| def5678 | fix(scope): description 2  |
+
+### Status
+
+Task przeniesiony do "In Review".
+
+---
+
+_Raport wygenerowany przez Claude Code_
+```
+
+**Important**: For each incomplete subtask, include:
+
+- The subtask ID and title
+- A clear reason why it wasn't completed (e.g., "Problem backendu", "Zewnętrzna zależność", "Brak planu implementacji")
+- Reference to any comments on the subtask that explain the issue
+
+### Step 7: Push to Remote
+
+Execute `git push` to push the commits to the remote repository.
+
+If push fails:
+
+- Show the error message
+- Suggest possible solutions (pull first, force push if appropriate, etc.)
+- Note: Linear status was already updated, may need to revert if push ultimately fails
+
+### Step 8: Final Confirmation
+
+Show final status to user:
+
+```markdown
+## Gotowe
+
+✅ Linear task [linearTaskId] przeniesiony do "In Review"
+✅ Zmiany wysłane do `origin/<branch-name>`
+
+### Następne kroki
+
+- Oczekiwanie na code review
+```
+
+### Step 9: Branch-Specific Post-Push Actions
+
+After successful push, determine the next action based on the current branch:
+
+1. **If branch is `development`**: Proceed to **Step 10** (Deployment Verification)
+2. **If branch is a feature branch** (matches Linear issue ID pattern like `FRA-123`, `mob-123`, etc.): Proceed to **Step 9a** (PR Workflow)
+
+#### Step 9a: Feature Branch - Check/Create Pull Request
+
+**Applicable only when on a feature branch (not `development`).**
+
+1. **Check if all subtasks are completed**:
+
+   Review the subtask analysis from Step 4. Consider a task "ready for PR" if:
+
+   - All subtasks are in "Done" or "In Review" status, OR
+   - Incomplete subtasks have documented reasons (backend issue, external dependency, etc.)
+
+2. **Check if PR already exists**:
+
+   ```bash
+   gh pr list --head <branch-name> --base development --json number,title,state,url
+   ```
+
+3. **If PR exists**:
+
+   ```markdown
+   ## Pull Request Already Exists
+
+   **PR**: #<number> - <title>
+   **Status**: <state>
+   **URL**: <url>
+
+   No action needed - PR already created.
+   ```
+
+4. **If PR does NOT exist**, ask user:
+
+   ```markdown
+   ## Create Pull Request?
+
+   Branch `<branch-name>` has no open PR to `development`.
+
+   ### Subtasks Status
+
+   - ✅ Completed: X
+   - ⚠️ Incomplete: Y (with documented reasons)
+
+   Do you want to create a Pull Request?
+   ```
+
+   Use `AskUserQuestion` tool with options:
+
+   - "Tak, utwórz PR do development" (Recommended)
+   - "Nie, zakończ bez PR"
+
+5. **If user confirms PR creation**:
+
+   Create PR using `gh pr create`:
+
+   ```bash
+   gh pr create --base development --head <branch-name> --title "<Linear-ID>: <Task Title>" --body "$(cat <<'EOF'
+   ## Summary
+
+   Implementation for [<Linear-ID>](https://linear.app/issue/<Linear-ID>)
+
+   ### Completed Subtasks
+
+   - ✅ <subtask-id>: <title>
+   - ✅ <subtask-id>: <title>
+
+   ### Incomplete Subtasks (with reasons)
+
+   - ⚠️ <subtask-id>: <title> → <reason>
+
+   ### Commits
+
+   | Commit | Description |
+   |--------|-------------|
+   | abc123 | feat: ... |
+
+   ---
+
+   🤖 Generated with [Claude Code](https://claude.com/claude-code)
+   EOF
+   )"
+   ```
+
+6. **Show PR creation result**:
+
+   ```markdown
+   ## ✅ Pull Request Created
+
+   **PR**: #<number> - <title>
+   **URL**: <url>
+   **Base**: development
+   **Head**: <branch-name>
+
+   ### Następne kroki
+
+   - Oczekiwanie na code review
+   - Po zatwierdzeniu: merge do development
+   ```
+
+   **End the command here for feature branches.**
+
+### Step 10: Ask About Deployment Verification (development branch only)
+
+**Applicable only when on `development` branch.**
+
+After successful push, ask the user if they want to verify deployment:
+
+```markdown
+## Deployment Verification
+
+Do you want to verify the deployment on QA environment?
+
+Verification process:
+
+1. Monitor GitHub Actions CI pipeline until completion
+2. Git pull and check if package.json was updated
+3. Wait 5 minutes for deployment
+4. Verify app version on QA site
+```
+
+Use `AskUserQuestion` tool with options:
+
+- "Yes, verify deployment" (Recommended)
+- "No, finish now"
+
+If user chooses not to verify, end the command here.
+
+### Step 11: Monitor CI Pipeline via GitHub Actions
+
+**Do NOT wait a fixed time.** Instead, actively monitor GitHub Actions workflows using `gh` CLI.
+
+1. **Get the latest workflow run for the current branch**:
+
+   ```bash
+   gh run list --branch <branch-name> --limit 1 --json databaseId,status,conclusion,workflowName
+   ```
+
+2. **Poll workflow status** every 30 seconds until it completes:
+
+   ```bash
+   gh run view <run-id> --json status,conclusion
+   ```
+
+   Or use `gh run watch <run-id>` to watch in real-time (but this blocks).
+
+3. **Show progress to user**:
+
+   ```markdown
+   ## CI/CD Pipeline Monitoring
+
+   🔄 Monitoring GitHub Actions workflow...
+
+   **Workflow**: <workflow-name>
+   **Run ID**: <run-id>
+   **Status**: in_progress | queued | completed
+   ```
+
+4. **Check workflow result**:
+
+**If workflow FAILED**:
+
+1. **Get failed job logs**:
+
+   ```bash
+   gh run view <run-id> --log-failed 2>&1 | tail -100
+   ```
+
+2. **Revert Linear task to "To Do"**:
+
+   If Linear task was provided and status was changed to "In Review":
+
+   - Move the parent task back to "To Do" status
+   - For tasks with subtasks: Move all subtasks that were changed to "In Review" back to "To Do"
+
+3. **Add error comment to Linear task**:
+
+   Create a comment on the **parent task** with CI error details:
+
+   ```markdown
+   ## ❌ CI Build Failed
+
+   ### Branch
+
+   `<branch-name>`
+
+   ### Workflow
+
+   **Name**: <workflow-name>
+   **Run ID**: <run-id>
+   **URL**: https://github.com/<owner>/<repo>/actions/runs/<run-id>
+
+   ### Error Details
+   ```
+
+   <last 50-100 lines of error logs from gh run view --log-failed>
+
+   ```
+
+   ### Status
+
+   Task przywrócony do "To Do" z powodu błędu CI.
+
+   ---
+
+   _Raport wygenerowany przez Claude Code_
+   ```
+
+4. **Show error to user**:
+
+   ```markdown
+   ## ❌ CI Pipeline Failed
+
+   **Workflow**: <workflow-name>
+   **Run ID**: <run-id>
+   **Conclusion**: failure
+
+   ### Linear Task Status
+
+   ⚠️ Task [linearTaskId] przywrócony do "To Do"
+   ✅ Komentarz z błędem dodany do taska
+
+   ### View logs
+
+   Run `gh run view <run-id> --log-failed` to see error details.
+
+   Or visit: https://github.com/<owner>/<repo>/actions/runs/<run-id>
+
+   ### Następne kroki
+
+   1. Przeanalizuj błędy w CI
+   2. Napraw problemy lokalnie
+   3. Uruchom `/push-local` ponownie
+   ```
+
+Stop here if workflow failed.
+
+**If workflow SUCCEEDED**, run:
+
+```bash
+git fetch origin
+git pull origin <branch-name>
+```
+
+Check if `package.json` version has changed:
+
+1. Read the current `package.json` version
+2. Compare with the version before push
+
+**If package.json was NOT updated** (version unchanged):
+
+```markdown
+## ❌ Pipeline Error
+
+**Problem**: CI/CD pipeline did not update the version in `package.json`.
+
+**Expected**: Automatic version bump after push
+**Current version**: X.X.X (unchanged)
+
+### Possible causes
+
+1. Version bump workflow not triggered
+2. Workflow succeeded but didn't bump version
+3. Auto-version configuration is not working
+
+### Recommended actions
+
+1. Check workflow logs: `gh run view <run-id> --log`
+2. Verify auto-versioning configuration
+```
+
+Stop here if package.json was not updated.
+
+**If package.json WAS updated**, save the new version and proceed to Step 12.
+
+### Step 12: Verify Deployment on QA (App Version Check)
+
+Wait 5 minutes for deployment to complete:
+
+```markdown
+## QA Deployment Verification
+
+⏳ Waiting 5 minutes for QA deployment...
+```
+
+Use `sleep 300` or equivalent to wait.
+
+After waiting, read SITE_URL from `.env.dev` file and fetch the page:
+
+```bash
+curl -s "<SITE_URL>" | grep -o '<meta name="app-version" content="[^"]*"'
+```
+
+Or use WebFetch to get the page and extract the `<meta name="app-version">` tag.
+
+Compare the deployed version with `package.json` version:
+
+**If versions MATCH**:
+
+```markdown
+## ✅ Deployment Successful
+
+**Version in package.json**: X.X.X
+**Version on QA**: X.X.X
+
+✅ Application was successfully deployed to QA environment.
+```
+
+**If versions DO NOT MATCH**:
+
+```markdown
+## ❌ Deployment Error
+
+**Problem**: App version on QA does not match the version in `package.json`.
+
+**Version in package.json**: X.X.X
+**Version on QA**: Y.Y.Y
+
+### Possible causes
+
+1. Deployment is still in progress (try again in a few minutes)
+2. Deployment pipeline failed with error
+3. CDN cache is serving old version
+4. Deployment configuration error
+
+### Recommended actions
+
+1. Check deployment pipeline status
+2. Review server logs
+3. Clear browser cache and check again
+4. Wait additional 5 minutes and run `/push-local --verify-only`
+```
+
+### Step 13: Final Deployment Status
+
+Show complete summary:
+
+```markdown
+## Complete Process Summary
+
+### Git
+
+✅ Changes pushed to `origin/<branch-name>`
+
+### Linear
+
+✅ Task [linearTaskId] moved to "In Review"
+
+### CI/CD Pipeline
+
+✅ Package.json updated to version X.X.X
+
+### QA Deployment
+
+✅ Application deployed to <SITE_URL>
+✅ Version: X.X.X
+```
+
+## Guidelines
+
+1. **Write comments in Polish**: All Linear comments must be written in Polish
+2. **Always confirm before status change**: Never change Linear status without user confirmation
+3. **Update Linear BEFORE push**: Status change happens before git push
+4. **Handle errors gracefully**: If push fails after status update, inform user
+5. **Warn about uncommitted changes**: Don't push if there are uncommitted changes without user acknowledgment
+6. **Show clear summaries**: Always show what commits will be pushed and subtask status
+7. **Document incomplete subtasks**: Always explain WHY a subtask wasn't completed
+8. **Deployment verification is optional**: Always ask user before starting the 10-minute verification process
+9. **Read SITE_URL from .env.dev**: Use the SITE_URL variable from `.env.dev` file for QA verification
+10. **Version comparison**: Compare `package.json` version with `<meta name="app-version">` tag on QA site
+11. **Revert on CI failure**: If CI pipeline fails, move task back to "To Do" and add error comment
+12. **Branch-specific post-push actions**:
+    - **`development` branch**: Offer deployment verification (CI monitoring + QA version check)
+    - **Feature branch (e.g., `FRA-123`)**: Check/create PR to `development` when all subtasks are ready
+
+## Example Flows
+
+### Example 1: Push to `development` branch (with deployment verification)
+
+```
+User: /push-local FRA-548
+(on branch: development)
+
+1. Check git status → 6 commits ahead, no uncommitted changes
+2. List commits to push → 6 commits shown
+3. Fetch FRA-548 details → "Druga lista uwag", 6 subtasks
+4. Analyze subtasks → 5 completed, 1 incomplete (backend issue)
+5. Show summary, ask user: "Move to In Review and push?" → User: "Yes"
+6. Update FRA-548 subtasks to "In Review", create summary comment
+7. git push → success
+8. Show final confirmation
+9. Branch is `development` → Ask user: "Verify deployment?" → User: "Yes"
+10. Monitor GitHub Actions (gh run list/view) → workflow completed ✅
+    → git pull → package.json version changed (0.136.0 → 0.137.0) ✅
+11. Wait 5 minutes → curl SITE_URL → meta app-version="0.137.0" ✅
+12. Show complete deployment summary
+```
+
+### Example 2: Push to feature branch (with PR creation)
+
+```
+User: /push-local FRA-560
+(on branch: FRA-560)
+
+1. Check git status → 3 commits ahead, no uncommitted changes
+2. List commits to push → 3 commits shown
+3. Fetch FRA-560 details → "Implement dark mode", 4 subtasks
+4. Analyze subtasks → 4 completed, 0 incomplete
+5. Show summary, ask user: "Move to In Review and push?" → User: "Yes"
+6. Update FRA-560 subtasks to "In Review", create summary comment
+7. git push → success
+8. Show final confirmation
+9. Branch is feature branch (FRA-560) → Check for existing PR
+   → gh pr list --head FRA-560 --base development → No PR found
+   → Ask user: "Create PR to development?" → User: "Yes"
+   → gh pr create --base development --title "FRA-560: Implement dark mode"
+   → Show PR created: #42 - URL: https://github.com/.../pull/42
+10. End command (no deployment verification for feature branches)
+```
+
+## Error Handling
+
+### Push Rejected (non-fast-forward)
+
+```markdown
+## Push Failed
+
+**Error**: Updates were rejected because the remote contains work that you do not have locally.
+
+**Uwaga**: Status w Linear został już zaktualizowany do "In Review".
+
+### Options
+
+1. `git pull --rebase` - Pull remote changes and rebase your commits on top
+2. `git pull` - Pull remote changes and merge
+3. `git push --force` - Force push (⚠️ overwrites remote changes)
+
+Which option do you want to use?
+```
+
+### No Commits to Push
+
+```markdown
+## Nothing to Push
+
+Your branch is up to date with `origin/<branch-name>`.
+
+No commits to push.
+```
+
+### Uncommitted Changes Present
+
+```markdown
+## Warning: Uncommitted Changes
+
+You have uncommitted changes in your working directory:
+
+- modified: path/to/file1.ts
+- modified: path/to/file2.ts
+
+### Options
+
+1. Commit changes first (`/commit`)
+2. Stash changes and push
+3. Proceed anyway (push existing commits only)
+
+What would you like to do?
+```