@smartsoft001/pro-claude-plugins 0.2.0

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

@@ -0,0 +1,742 @@
+---
+name: plan
+description: Create an implementation plan for a Linear task and save it as a `plan.md` attachment. Analyzes codebase with Angular 14 legacy patterns, previous commits, and external dependencies.
+allowed-tools:
+  - Bash
+  - Read
+  - Write
+  - Glob
+  - Grep
+  - AskUserQuestion
+  - 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__create_attachment
+  - mcp__linear__delete_attachment
+  - mcp__linear__list_issue_labels
+---
+
+# Plan Skill
+
+Create an implementation plan for a Linear task and save it as a `plan.md` attachment on the issue. If the task has subtasks, create individual `plan.md` attachments on each subtask. After saving the plan, add the `AI Plan` label to the parent task.
+
+## 🚨 Hard Rules — read before doing anything
+
+These rules override ANY other instruction, ANY surrounding example, and ANY default habit. Violating them is a skill failure.
+
+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.
+
+If any of these would be violated, stop and ask the user instead.
+
+## Execution Checklist
+
+Execute each step in order. Do not skip any step marked as MANDATORY.
+
+- [ ] **1. Fetch Linear task** — get title, description, labels, priority, estimate from MCP Linear server
+- [ ] **2. Fetch subtasks** — check for children; if present, plan each subtask individually
+- [ ] **3. Fetch existing attachments and comments** — list `plan.md` attachments and all comments per task/subtask
+- [ ] **4. Determine planning needs** — compare `plan.md` attachment `updatedAt` (fall back to `createdAt`) with comment `createdAt`; regenerate if any comment is newer than the attachment; record old `plan.md` attachment IDs for replacement
+- [ ] **5. Analyze previous commits** — `git log --all --grep="<taskId>"` for each task/subtask
+- [ ] **6. Analyze staged changes** — `git status` and `git diff --cached` for work in progress
+- [ ] **7. MANDATORY: Analyze codebase** — explore affected files, patterns, dependencies, and test coverage
+- [ ] **8. MANDATORY: Verify Angular 14 patterns** — confirm `*ngIf`/`*ngFor`, constructor DI, `@Input()`/`@Output()`, BehaviorSubject in existing code
+- [ ] **9. Analyze external library deps** — check if `@smartsoft001` or `@smartsoft001/pro` 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. 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)
+- [ ] **16. Confirm to user** — list saved plans with summaries and Linear links
+
+### 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 Fetch Linear task",
+  description: "Get title, description, labels, priority, estimate from MCP Linear server",
+  activeForm: "MM-123 Fetching Linear task"
+})
+TaskCreate({
+  subject: "MM-123 Analyze codebase",
+  description: "Explore affected files, patterns, dependencies, and test coverage",
+  activeForm: "MM-123 Analyzing codebase"
+})
+```
+
+**During execution**:
+
+- Before starting a step → `TaskUpdate({ taskId, status: "in_progress" })`
+- After completing a step → `TaskUpdate({ taskId, status: "completed" })`
+
+**Before user review**: Use `TaskList` to show progress overview before presenting plans for approval.
+
+## Role
+
+**You are a highly experienced software architect** with:
+
+- Over 15 years of experience in system design
+- Deep knowledge of design patterns and architectural patterns
+- Expertise in **Angular 14** patterns (NgModules, `*ngIf`/`*ngFor`, constructor DI, `@Input`/`@Output`)
+- Ability to break down complex tasks into smaller, understandable steps
+- Experience planning tasks for development teams in a clear and precise manner
+- Skill in anticipating potential problems and risks
+- Focus on architectural consistency and alignment with existing project patterns
+- Thinking about scalability, maintainability, and testability of solutions
+
+You create plans that are:
+
+- **Specific**: each step is clearly defined
+- **Actionable**: the developer knows exactly what to do
+- **Complete**: nothing is omitted
+- **Realistic**: they account for constraints and dependencies
+- **Legacy-compatible**: they use Angular 14 patterns (no signals, no standalone components)
+
+## Usage
+
+```
+/plan [linearTaskId]
+/plan [linearTaskId] --auto    # Non-interactive mode for CI / GitHub Actions
+```
+
+## Parameters
+
+- `linearTaskId` - Linear task ID (e.g., ENG-123)
+- `--auto` - Non-interactive mode: skip ALL `AskUserQuestion` prompts. Auto-approve plans before saving (no review step), auto-delete stale `plan.md` attachments without confirmation, and silently skip when all plans are up to date (no "regenerate anyway?" prompt). Designed for CI / GitHub Actions runs where no human is at the keyboard.
+
+## Auto Mode (`--auto`)
+
+**When `--auto` is set, the skill MUST run end-to-end without any human-in-the-loop prompts.** Apply these overrides:
+
+| Default behavior                                                  | `--auto` override                                                                                |
+| ----------------------------------------------------------------- | ------------------------------------------------------------------------------------------------ |
+| 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.
+
+**Detection**: The flag `--auto` is provided as a positional/named arg. Treat any of `--auto`, `--ci`, `--non-interactive` as equivalent.
+
+## Angular 14 Legacy Patterns
+
+When creating plans, always use these legacy patterns:
+
+### Components
+
+- Use `@Component` with `NgModule` (NOT standalone)
+- Use `*ngIf` and `*ngFor` (NOT `@if` and `@for`)
+- Use constructor injection (NOT `inject()`)
+- Use `@Input()` and `@Output()` decorators (NOT `input()`, `output()`)
+
+### Services
+
+- Use `BehaviorSubject` and `Observable` (NOT signals)
+- Use constructor injection
+- Use `@Injectable({ providedIn: 'root' })` or module providers
+
+### State Management
+
+- Use NgRx Store/Effects or BehaviorSubject patterns
+- NO signals, computed(), or effect()
+
+## Instructions
+
+You are tasked with creating an implementation plan for a Linear task and saving it as a comment in Linear. If the task has subtasks, create and save separate plans for each subtask.
+
+### Step 1: Fetch Linear Task Details
+
+Use the MCP Linear server to fetch task details for the provided `linearTaskId`. Extract:
+
+- Task title
+- Task description
+- Task labels/type (bug, feature, etc.)
+- Acceptance criteria (if available)
+- Task priority
+- Task estimate (if available)
+
+### Step 2: Fetch Subtasks
+
+Use the MCP Linear server to check if the task has subtasks (children). If subtasks exist:
+
+- Fetch details for each subtask (title, description, labels, priority)
+- Note the subtask IDs for later comment creation
+- The main task becomes the "parent context" for all subtask plans
+
+**Important**: If subtasks exist, you will create individual plans for each subtask, not for the parent task.
+
+### Step 3: Fetch Task Attachments and Comments
+
+Use the MCP Linear server to fetch, for the parent task and each subtask:
+
+- Attachments via `mcp__linear__get_issue` (attachments included in response) — look for one titled exactly `plan.md`
+- Comments via `mcp__linear__list_comments` — keep `id`, `createdAt`, body text
+
+### Step 3a: Determine Which Tasks Need Planning
+
+For each task/subtask, use the **attachment mtime vs comment ctime** rule:
+
+#### Inputs per task
+
+- `planAttachment`: the Linear attachment titled `plan.md` (or `null`)
+- `planAttachment.updatedAt` (fall back to `createdAt`): when the plan was last written
+- `comments`: list of all comments with `createdAt`
+
+#### Decision logic
+
+**Create a NEW plan if:**
+
+1. `planAttachment == null`, OR
+2. there is at least one comment where `comment.createdAt > planAttachment.updatedAt`
+
+**SKIP planning if:**
+
+1. `planAttachment` exists AND no comment is newer than it.
+
+#### Secondary signal (optional)
+
+If `planAttachment` exists and no comment is newer than it, but the user's latest prompt mentions plan-change keywords ("zmień plan", "zaktualizuj plan", "popraw plan", "nowy plan", "uwagi do planu"), ask the user explicitly — do **not** regenerate silently on keyword alone.
+
+#### Output:
+
+- `tasksNeedingPlan`: Array of task IDs that need a new or updated plan
+- `tasksWithExistingPlan`: Array of task IDs with up-to-date plans
+- `oldPlanAttachments`: Map of task ID → `attachmentId` for plans being replaced
+
+**Important**: If ALL tasks already have up-to-date plans:
+
+- **Default mode**: Inform the user and ask if they want to regenerate anyway.
+- **`--auto` mode**: Exit cleanly with a Linear comment in Polish noting all plans are current; do NOT regenerate.
+
+### Step 4: Analyze Previous Commits
+
+Search for previous commits related to this Linear task by looking for the `linearTaskId` (and subtask IDs if applicable) in commit messages:
+
+```bash
+# For parent task
+git log --all --grep="<linearTaskId>" --oneline
+
+# For each subtask
+git log --all --grep="<subtaskId>" --oneline
+```
+
+For each found commit, analyze:
+
+1. **Commit message**: What was the purpose of the change
+2. **Changed files**: Run `git show --stat <commit-hash>` to see affected files
+3. **Detailed changes**: Run `git show <commit-hash>` if needed to understand specific changes
+
+This helps to:
+
+- Understand what work has already been completed
+- Identify patterns and approaches already established
+- Avoid duplicating already implemented features
+- Build upon existing implementation
+
+### Step 5: Analyze Staged Changes
+
+Check what's currently staged in Git:
+
+```bash
+git status
+git diff --cached
+```
+
+Analyze staged changes to understand:
+
+- What work is in progress but not yet committed
+- Files that are being modified as part of this task
+- Current implementation direction
+
+### Step 6: Analyze the Codebase
+
+Based on the task requirements (and each subtask if applicable), explore the codebase to understand:
+
+1. **Affected areas**: Identify which files, components, or modules will need changes
+2. **Existing patterns**: Understand current implementation patterns to maintain consistency
+3. **Dependencies**: Identify any dependencies or related code that might be affected
+4. **Test coverage**: Check existing tests that might need updates
+
+Use tools like:
+
+- `Glob` to find relevant files
+- `Grep` to search for related code patterns
+- `Read` to understand specific implementations
+
+**Important**: Always check for Angular 14 patterns in existing code:
+
+- Look for `*ngIf`, `*ngFor` usage (NOT `@if`, `@for`)
+- Look for constructor injection patterns
+- Look for `@Input()`, `@Output()` decorators
+- Look for `BehaviorSubject`, `Observable` patterns (NOT signals)
+
+### Step 6a: Analyze External Library Dependencies
+
+Check if the task requires changes to external library packages:
+
+#### @smartsoft001 libraries
+
+- **Repository location**: `../smartsoft001`
+- **Package path**: `../smartsoft001/packages/`
+- If changes are needed in `@smartsoft001/*` packages, explore the library repository to understand:
+  - Current implementation of the relevant package
+  - API surface that needs to be modified or extended
+  - Existing patterns and conventions in the library
+
+#### @smartsoft001/pro libraries
+
+- **Repository location**: `../smartsoft001-pro`
+- **Package path**: `../smartsoft001-pro/packages/`
+- If changes are needed in `@smartsoft001/pro-*` packages, explore the library repository to understand:
+  - Current implementation of the relevant package
+  - API surface that needs to be modified or extended
+  - Existing patterns and conventions in the library
+
+**Important**: Changes to these external libraries are NOT part of this task's implementation. They require a separate process:
+
+1. Create a separate task/PR in the library repository
+2. Publish new version of the library
+3. Update dependency version in this project
+4. Then implement the changes in this project that depend on the library updates
+
+### Step 7: Create Implementation Plans
+
+#### If NO subtasks exist:
+
+Create a single detailed implementation plan for the parent task with:
+
+1. **Summary**: Brief overview of what needs to be done
+2. **Already Completed**: Work done in previous commits (with commit references)
+3. **Currently In Progress**: Work visible in staged changes
+4. **Remaining Work**: What still needs to be implemented
+5. **Technical Analysis**: Key findings from codebase exploration
+6. **Implementation Steps**: Numbered list of specific remaining tasks
+7. **Files to Modify**: List of files that will need changes
+8. **New Files**: List of any new files that need to be created
+9. **External Library Changes**: Changes needed in @smartsoft001 or @smartsoft001/pro (separate process)
+10. **Testing Strategy**: How the changes will be tested
+11. **Risks & Considerations**: Any potential issues or things to watch out for
+12. **Estimated Complexity**: Low / Medium / High
+
+#### If subtasks exist:
+
+Create a **separate plan for each subtask** that includes:
+
+1. **Parent Context**: Reference to parent task and its overall goal
+2. **Subtask Summary**: What this specific subtask needs to accomplish
+3. **Already Completed**: Work done in previous commits for this subtask
+4. **Currently In Progress**: Staged changes related to this subtask
+5. **Remaining Work**: What still needs to be done for this subtask
+6. **Technical Analysis**: Findings specific to this subtask
+7. **Implementation Steps**: Steps specific to this subtask
+8. **Files to Modify**: Files affected by this subtask
+9. **New Files**: New files needed for this subtask
+10. **External Library Changes**: Changes in @smartsoft001 or @smartsoft001/pro (separate process)
+11. **Dependencies**: Other subtasks this depends on or blocks
+12. **Testing Strategy**: Testing specific to this subtask
+13. **Estimated Complexity**: Low / Medium / High
+
+### Step 8: Format the Plans
+
+#### Format for task WITHOUT subtasks:
+
+```markdown
+## Implementation Plan
+
+### Summary
+
+[Brief overview]
+
+### Already Completed
+
+[List of work done in previous commits - skip if no previous commits]
+
+- `abc1234` - [commit message / description of changes]
+- `def5678` - [commit message / description of changes]
+
+**Files modified in previous commits:**
+
+- `path/to/file1.ts`
+- `path/to/file2.ts`
+
+### Currently In Progress
+
+[Description of staged changes - skip if nothing staged]
+
+- [File/change description]
+
+### Remaining Work
+
+[What still needs to be done based on task requirements]
+
+- [ ] [Remaining item 1]
+- [ ] [Remaining item 2]
+
+### Technical Analysis
+
+[Key findings from codebase exploration]
+
+**Angular 14 patterns to follow:**
+
+- Use `*ngIf` / `*ngFor` for control flow
+- Use constructor injection for DI
+- Use `@Input()` / `@Output()` for component communication
+- Use `BehaviorSubject` / `Observable` for state management
+
+### Implementation Steps
+
+1. [Step 1]
+2. [Step 2]
+3. [Step 3]
+   ...
+
+### Files to Modify
+
+- `path/to/file1.ts` - [reason]
+- `path/to/file2.ts` - [reason]
+
+### New Files
+
+- `path/to/new-file.ts` - [purpose]
+
+### External Library Changes (separate process)
+
+[Skip this section if no library changes are needed]
+
+**@smartsoft001 (repo: ../smartsoft001)**
+
+- [ ] `packages/[package-name]` - [description of required changes]
+
+**@smartsoft001/pro (repo: ../smartsoft001-pro)**
+
+- [ ] `packages/[package-name]` - [description of required changes]
+
+> **Note**: These changes are NOT part of this task implementation. They require:
+>
+> 1. Separate task/PR in the library repository
+> 2. Library version publication
+> 3. Dependency update in this project
+
+### Testing Strategy
+
+- [ ] Unit tests for [component/service]
+- [ ] E2E tests for [feature]
+- [ ] Manual testing: [scenarios]
+
+### Risks & Considerations
+
+- [Risk 1]
+- [Risk 2]
+
+### Estimated Complexity
+
+[Low / Medium / High]
+
+---
+
+_Plan generated by Claude Code (flow-legacy)_
+```
+
+#### Format for SUBTASK plan:
+
+```markdown
+## Implementation Plan for Subtask
+
+**Parent Task**: [Parent task ID] - [Parent task title]
+
+### Subtask Summary
+
+[What this specific subtask needs to accomplish]
+
+### Already Completed
+
+[Work done in previous commits for this subtask - skip if none]
+
+- `abc1234` - [commit message / description of changes]
+
+**Files modified:**
+
+- `path/to/file1.ts`
+
+### Currently In Progress
+
+[Staged changes related to this subtask - skip if none]
+
+- [File/change description]
+
+### Remaining Work
+
+- [ ] [Remaining item 1]
+- [ ] [Remaining item 2]
+
+### Technical Analysis
+
+[Findings specific to this subtask]
+
+**Angular 14 patterns to follow:**
+
+- Use `*ngIf` / `*ngFor` for control flow
+- Use constructor injection for DI
+- Use `@Input()` / `@Output()` for component communication
+
+### Implementation Steps
+
+1. [Step 1]
+2. [Step 2]
+   ...
+
+### Files to Modify
+
+- `path/to/file1.ts` - [reason]
+
+### New Files
+
+- `path/to/new-file.ts` - [purpose]
+
+### External Library Changes (separate process)
+
+[Skip this section if no library changes are needed]
+
+**@smartsoft001 (repo: ../smartsoft001)**
+
+- [ ] `packages/[package-name]` - [description of required changes]
+
+**@smartsoft001/pro (repo: ../smartsoft001-pro)**
+
+- [ ] `packages/[package-name]` - [description of required changes]
+
+> **Note**: These changes are NOT part of this subtask. Separate process required.
+
+### Dependencies
+
+- **Depends on**: [List subtask IDs this depends on, or "None"]
+- **Blocks**: [List subtask IDs this blocks, or "None"]
+
+### Testing Strategy
+
+- [ ] [Test specific to this subtask]
+
+### Estimated Complexity
+
+[Low / Medium / High]
+
+---
+
+_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): 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
+
+Następujące załączniki `plan.md` zostaną usunięte i zastąpione nowymi:
+
+| Task      | Stary załącznik (ID) |
+| --------- | -------------------- |
+| <task-id> | <attachment-id>      |
+
+Czy potwierdzasz usunięcie starych planów i zapisanie nowych?
+```
+
+Use `AskUserQuestion` with options:
+
+- "Tak, usuń stare plany i zapisz nowe" (Recommended)
+- "Anuluj"
+
+**If user confirms:**
+
+1. For each entry in `oldPlanAttachments`, delete the Linear attachment via `mcp__linear__delete_attachment({ id: attachmentId })`.
+2. Proceed to Step 9a.
+
+**If user cancels:** Stop the process, do not save any plans.
+
+### 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.** (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 the plan content to `/tmp/claude-plans/<taskId>-plan.md`.
+
+#### 9a.2 — Base64-encode
+
+```bash
+b64=$(base64 -i /tmp/claude-plans/<taskId>-plan.md)
+```
+
+On macOS `base64 -i <file>` outputs without line-wrapping. On Linux, pipe through `tr -d '\n'` if needed.
+
+#### 9a.3 — Create Linear attachment
+
+Call `mcp__linear__create_attachment` with:
+
+- `issue`: the task/subtask ID
+- `filename`: `plan.md`
+- `contentType`: `text/markdown`
+- `title`: `plan.md` (exact — used for detection in Step 3 and by `/impl`)
+- `subtitle`: `Plan wygenerowany przez Claude Code (legacy)`
+- `base64Content`: the base64 string from 9a.2
+
+Linear hosts the file on its own infrastructure.
+
+#### 9a.4 — Clean up local file
+
+Delete `/tmp/claude-plans/<taskId>-plan.md` after the attachment is created. `/push` does NOT delete Linear attachments — they stay on the issue.
+
+#### Scope rule
+
+- No subtasks → attach `plan.md` to parent.
+- Has subtasks → attach `plan.md` to each subtask needing planning. Do NOT attach on the parent.
+
+### Step 9b: Add "AI Plan" Label
+
+Apply the `AI Plan` label to the **invoked issue** — i.e. the `linearTaskId` passed to `/plan`:
+
+- `/plan FRA-123` (parent) → label on `FRA-123`. Subtasks receive `plan.md` attachments but no label.
+- `/plan FRA-123-1` (subtask) → label on `FRA-123-1` directly; parent untouched.
+
+**`AI Plan` is a workspace-level (organization-wide) label that already exists** — do NOT create it.
+
+1. Look up label `AI Plan` via `mcp__linear__list_issue_labels` (workspace-wide). If not found for any reason, surface the error — do NOT create a team-scoped duplicate.
+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:
+
+- List all tasks/subtasks where `plan.md` was attached (with Linear attachment URL)
+- Show plan summaries
+- Confirm `AI Plan` label added to parent task
+- Provide Linear links
+
+## Guidelines
+
+1. **Write plans in Polish**: All implementation plans must be written in Polish language
+2. **Be thorough but concise**: Include all necessary details without being verbose
+3. **Be specific**: Reference actual file paths and code patterns found in the codebase
+4. **Consider edge cases**: Think about error handling, validation, and edge cases
+5. **Follow project conventions**: Ensure the plan aligns with project architecture and patterns
+6. **Identify dependencies**: Note if any tasks depend on others or external factors
+7. **Ask for clarification**: If requirements are unclear, use `AskUserQuestion` before creating the plan
+8. **Track progress accurately**: Clearly distinguish between completed, in-progress, and remaining work
+9. **Reference commits**: Always include commit hashes when mentioning previous work
+10. **Keep subtask plans focused**: Each subtask plan should only cover that subtask's scope
+11. **Identify cross-subtask dependencies**: Note which subtasks depend on or block others
+12. **Identify external library changes**: Always check if task requires changes in `@smartsoft001` (repo: `../smartsoft001`) or `@smartsoft001/pro` (repo: `../smartsoft001-pro`). Mark these as separate process items, not part of current implementation
+13. **Skip tasks with up-to-date plans**: Only regenerate when the `plan.md` attachment is missing or stale (any comment newer than `plan.md.updatedAt`).
+14. **Mtime rule is authoritative**: Regeneration driven by attachment `updatedAt` vs comment `createdAt`. Keyword detection triggers an explicit user confirmation only — never a silent regen.
+15. **Use Angular 14 patterns**: Always plan for `*ngIf`/`*ngFor`, constructor DI, `@Input()`/`@Output()`, BehaviorSubject - NOT signals, `@if`/`@for`, or `inject()`
+16. **Delete old plans cleanly**: When replacing, ask user to confirm, then delete the old Linear attachment via `mcp__linear__delete_attachment`.
+17. **Always add "AI Plan" label**: After saving plan attachments, apply the workspace-level `AI Plan` label (already configured organization-wide — do NOT create a team-scoped duplicate) to the invoked issue.
+
+---
+
+**Important**:
+
+- **Default mode**: Before saving the plans as attachments, show them to the user for review and approval.
+- **`--auto` mode**: Skip the review step; proceed directly to saving the attachments.
+
+The plan content is written to `/tmp/claude-plans/<taskId>-plan.md`, base64-encoded, and uploaded as a native Linear attachment via `mcp__linear__create_attachment`. After that, the `AI Plan` label is applied to the invoked issue.