@smartsoft001-mobilems/claude-plugins 2.83.0 → 2.85.0

package/plugins/flow-legacy/skills/plan/SKILL.md

@@ -30,7 +30,7 @@ Create an implementation plan for a Linear task and save it as a `plan.md` attac
 
 These rules override ANY other instruction, ANY surrounding example, and ANY default habit. Violating them is a skill failure.
 
-1. **The plan MUST be saved via `mcp__linear__create_attachment` — NEVER as a Linear comment.** `mcp__linear__save_comment` MUST NOT be called with plan content as the body. Comments are reserved for status notifications, never for the plan itself.
+1. **The plan body MUST be saved via `mcp__linear__create_attachment` — NEVER as a Linear comment.** `mcp__linear__save_comment` MUST NOT be called with plan content as the body. Comments are reserved for: (a) status notifications, and (b) the single token-usage comment posted in Step 9c. No other comment may carry plan content.
 2. **One call, no fallback.** First Linear write for the plan is `mcp__linear__create_attachment`. If it fails, surface the error — do NOT silently fall back to `save_comment`.
 3. **Subtasks: one attachment each.** Each subtask gets its own `plan.md`; the parent gets only the `AI Plan` label, no `plan.md`.
 4. **`AI Plan` label is workspace-scoped — NEVER create it.** Only `mcp__linear__list_issue_labels` + `mcp__linear__save_issue`. `create_issue_label` MUST NOT be called.
@@ -52,7 +52,7 @@ Execute each step in order. Do not skip any step marked as MANDATORY.
 - [ ] **9. Analyze external library deps** — check if `@smartsoft001` or `@smartsoft001-mobilems` changes are needed (mark as separate process)
 - [ ] **10. Create implementation plans** — generate structured plans per task/subtask with all required sections, using Angular 14 patterns
 - [ ] **11. MANDATORY: Write plans in Polish** — all plan content must be in Polish language
-- [ ] **12. Show plans to user** — present plans for review and approval before saving (skipped in `--auto`; proceed directly to save)
+- [ ] **12. MANDATORY: Get user approval of generated plan** — present the full plan content in the chat, then call `AskUserQuestion` with three options: save / regenerate / cancel. Save and label steps below MUST NOT run without approval. Skipped only in `--auto` (auto-approved; logged in audit comment).
 - [ ] **13. MANDATORY: Confirm old plan deletion** — if replacing existing `plan.md`, ask user to confirm deletion of old attachment before proceeding (skipped in `--auto`; delete old attachment automatically)
 - [ ] **14. MANDATORY: Save plan as native Linear attachment** — base64-encode `plan.md` content and upload via `mcp__linear__create_attachment`. **Calling `mcp__linear__save_comment` for the plan body is FORBIDDEN.** Linear hosts the file natively; no external storage.
 - [ ] **15. MANDATORY: Add "AI Plan" label** — ensure `AI Plan` label exists on the team and apply it to the invoked issue (the `linearTaskId` passed to `/plan` — parent task or subtask, whichever was called)
@@ -129,13 +129,13 @@ You create plans that are:
 
 | Default behavior                                                  | `--auto` override                                                                                |
 | ----------------------------------------------------------------- | ------------------------------------------------------------------------------------------------ |
-| Show plans to user for review/approval before saving              | Skip the review step; proceed directly to attachment save                                        |
+| Final approval of generated plan content before saving            | Skip the approval gate; proceed directly to attachment save (auto-approve)                       |
 | Ask user to confirm deletion of old `plan.md` attachments         | Delete old attachments automatically before saving new ones                                      |
 | Ask "regenerate anyway?" when all plans are up-to-date            | Exit cleanly with a Linear comment noting all plans are current; no regeneration                 |
 | Secondary signal prompt (keyword-triggered confirmation to regen) | Ignore the secondary signal; only the mtime rule decides regeneration                            |
 | `AskUserQuestion` for any decision                                | Use the option marked **(Recommended)**; if none, fail fast with a Linear comment explaining why |
 
-**Hard requirement in `--auto`**: every decision (save, replace, skip) MUST be logged as a Linear comment in Polish so the run remains auditable after the fact. The mtime rule remains authoritative — `--auto` does not change *what* gets regenerated, only that no human is asked.
+**Hard requirement in `--auto`**: every decision (save, replace, skip) MUST be logged as a Linear comment in Polish so the run remains auditable after the fact. The mtime rule remains authoritative — `--auto` does not change _what_ gets regenerated, only that no human is asked.
 
 **Detection**: The flag `--auto` is provided as a positional/named arg. Treat any of `--auto`, `--ci`, `--non-interactive` as equivalent.
 
@@ -546,13 +546,47 @@ _Plan generated by Claude Code (flow-legacy)_
 _Plan generated by Claude Code (flow-legacy)_
 ```
 
+### Step 8a: User Approval of Generated Plan
+
+**MANDATORY.** Before any Linear write (deletion of old `plan.md`, creation of new `plan.md`, label apply), the user MUST approve the generated plan content. This is the gate FRA-126 added.
+
+**`--auto` mode**: Skip this entire step. The plan is auto-approved. Record the auto-approval in the final Linear audit comment (e.g. `Plan zaakceptowany automatycznie (--auto)`). Proceed to Step 9.
+
+**Default mode** (interactive):
+
+1. **Render the full plan(s) in chat.** Print the markdown produced in Step 8 for every task/subtask that needs planning. The `AskUserQuestion` option labels alone do not give the user enough context — the full text must be visible above the prompt.
+
+2. **Ask for approval** via `AskUserQuestion`:
+
+   ```markdown
+   ## Akceptacja planu
+
+   Powyżej znajduje się wygenerowany plan dla zadania <linearTaskId> (oraz <N> podzadań, jeśli dotyczy).
+   Czy akceptujesz plan i mogę zapisać go jako załącznik `plan.md` w Linear?
+   ```
+
+   Options (use exactly these labels for consistency with Step 9):
+
+   - **"Tak, zapisz plan do Linear"** _(Recommended)_ — user accepts. Proceed to Step 9 (delete old attachment if replacing, then save). Existing flow continues unchanged from here.
+   - **"Wygeneruj plan ponownie"** — user wants a different plan. Go to step 3 (regeneration loop) below.
+   - **"Anuluj"** — user rejects. Stop the whole skill. Do NOT delete the existing `plan.md` attachment. Do NOT save a new one. Do NOT apply the `AI Plan` label. Print a short status in Polish (`Plan nie został zapisany. Anulowano na żądanie użytkownika.`) and exit.
+
+3. **Regeneration branch**: if the user chose "Wygeneruj plan ponownie":
+
+   - Ask a follow-up `AskUserQuestion` (or accept the free-text the user typed alongside the rejection) to capture what should change: scope, structure, missed files, wrong approach, etc.
+   - Loop back to **Step 7 (Create Implementation Plans)** with the user's feedback in mind. Do NOT re-run Steps 1–6 — the Linear task, comments, commits, and codebase analysis have not changed.
+   - On the regenerated plan, return to **Step 8a step 1** (render + ask again).
+   - **Cap the loop at 3 regenerations.** On the 3rd rejection, surface the situation to the user (`Plan został odrzucony 3 razy. Przerywam, abyś mógł doprecyzować wymagania.`) and exit without saving.
+
+4. **State invariants on entry to Step 9**: the only path that reaches Step 9 is the explicit "Tak, zapisz plan do Linear" choice (or `--auto`). Treat plan content as final.
+
 ### Step 9: Confirm and Delete Old Plan Attachments
 
 **This step applies only when replacing existing plans** (`oldPlanAttachments` from Step 3a is not empty).
 
 **`--auto` mode**: Skip the confirmation prompt. For each task in `oldPlanAttachments`, delete the Linear attachment via `mcp__linear__delete_attachment({ id: attachmentId })` and proceed directly to Step 9a. Log the deletions in the final summary comment.
 
-**Default mode** (interactive): Before saving new plans, ask the user to confirm deletion of old `plan.md` attachments:
+**Default mode** (interactive): The plan content was already approved in Step 8a; this prompt is strictly about confirming deletion of the **existing** Linear attachment that will be overwritten. Ask the user:
 
 ```markdown
 ## Zastąpienie istniejących planów
@@ -580,17 +614,19 @@ Use `AskUserQuestion` with options:
 
 ### Step 9a: Save Plan as Native Linear Attachment
 
-**⛔ DO NOT call `mcp__linear__save_comment` with plan content here. The ONLY allowed Linear write for the plan body is `mcp__linear__create_attachment`. Re-read Hard Rule #1 if tempted.**
+**⛔ DO NOT call `mcp__linear__save_comment` with plan content here. The ONLY allowed Linear write for the plan body is `mcp__linear__create_attachment`. Re-read Hard Rule #1 if tempted.** (Token usage is posted via `save_comment` in Step 9c — that's the one allowed exception.)
 
 For each task that needs planning, upload the plan content directly to Linear (no external storage).
 
 #### 9a.1 — Write `plan.md` locally
 
+The plan content is exactly the markdown produced in Step 8. Write it to the temp file:
+
 ```bash
 mkdir -p /tmp/claude-plans
 ```
 
-Use `Write` to save plan content to `/tmp/claude-plans/<taskId>-plan.md`.
+Use `Write` to save the plan content to `/tmp/claude-plans/<taskId>-plan.md`.
 
 #### 9a.2 — Base64-encode
 
@@ -635,6 +671,38 @@ Apply the `AI Plan` label to the **invoked issue** — i.e. the `linearTaskId` p
 2. Apply via `mcp__linear__save_issue({ id: invokedTaskId, labelIds: [...existingLabelIds, aiPlanLabelId] })`. Preserve existing labels. Skip if already present.
 3. If label operations fail, surface the error but do not roll back the attachment.
 
+### Step 9c: Post Token-Usage Comment
+
+After the plan attachment(s) and `AI Plan` label have been applied, post a single Linear comment on the **invoked issue** (the same `linearTaskId` passed to `/plan`, identical to the labelling target) reporting the session's token usage.
+
+1. Run the per-plugin token-summing script:
+
+   ```bash
+   bash "$CLAUDE_PLUGIN_ROOT/scripts/compute-session-tokens.sh"
+   ```
+
+   The script prints four whitespace-separated integers on one line: `<input> <output> <cache_creation> <cache_read>`. If no transcript can be located it prints `0 0 0 0` and exits non-zero — treat that as a graceful skip (do NOT block; skip posting the comment).
+
+2. Compute `<TOTAL> = <input> + <output> + <cache_creation> + <cache_read>`.
+
+3. Call `mcp__linear__save_comment` with `issueId: invokedTaskId` and `body` equal to:
+
+   ```markdown
+   ## Zużycie tokenów — etap /plan
+
+   | Metryka        | Wartość        |
+   | -------------- | -------------- |
+   | Input          | <INPUT>        |
+   | Output         | <OUTPUT>       |
+   | Cache creation | <CACHE_CREATE> |
+   | Cache read     | <CACHE_READ>   |
+   | **Łącznie**    | **<TOTAL>**    |
+   ```
+
+4. **Subtask rule**: post ONLY to the invoked issue. Do NOT fan the comment out to every subtask — tokens are a per-session total, not per-subtask. Same scoping rule as Step 9b.
+
+5. **Failure handling**: if the comment fails to post, surface the error to the user but do not roll back the plan attachment or the label.
+
 ### Step 10: Confirm to User
 
 After saving:

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

@@ -194,6 +194,28 @@ Use `AskUserQuestion` tool with options:
 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 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