@smartsoft001/pro-claude-plugins 0.2.0

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

@@ -0,0 +1,1033 @@
+---
+name: plan
+description: Create an implementation plan for a Linear task and save it as a `plan.md` attachment. Analyzes codebase, previous commits, and external dependencies to generate detailed plans for tasks and subtasks.
+allowed-tools:
+  - Bash
+  - Read
+  - Write
+  - Glob
+  - Grep
+  - AskUserQuestion
+  - Task
+  - 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 issue.
+
+## 🚨 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 (e.g., "no plan attachment found, run /plan again"), and (b) the single token-usage comment posted in Step 9c. No other comment may carry plan content. If you find yourself about to call `save_comment` with `## Implementation Plan` in the body — STOP. That's a bug.
+
+2. **One call, no fallback.** The first Linear write for the plan is `mcp__linear__create_attachment`. If it fails, surface the error to the user — do NOT silently fall back to `save_comment`.
+
+3. **Subtasks: one attachment each.** If the parent has subtasks, each subtask gets its own `plan.md` attachment. The parent gets only the `AI Plan` label, no `plan.md` attachment.
+
+4. **`AI Plan` label is workspace-scoped — NEVER create it.** Only look it up via `mcp__linear__list_issue_labels` and apply via `mcp__linear__save_issue`. `mcp__linear__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. Analyze external library deps** — check if `@smartsoft001` or `@smartsoft001/pro` changes are needed (mark as separate process)
+- [ ] **9. Create implementation plans** — generate structured plans per task/subtask with all required sections
+- [ ] **10. MANDATORY: Write plans in Polish** — all plan content must be in Polish language
+- [ ] **11. 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).
+- [ ] **12. 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)
+- [ ] **13. 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.
+- [ ] **14. 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)
+- [ ] **15. 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
+- 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
+
+## Usage
+
+```
+/plan [linearTaskId]
+/plan [linearTaskId] --deep    # Deep planning with Agent Team (experimental)
+/plan [linearTaskId] --auto    # Non-interactive mode for CI / GitHub Actions
+```
+
+## Parameters
+
+- `linearTaskId` - Linear task ID (e.g., ENG-123)
+- `--deep` - Enable deep planning with Agent Team (experimental, requires `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1`)
+- `--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. Combinable with `--deep` (deep team mode runs without the final approval prompt).
+
+## 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 (if any):
+
+- Attachments via `mcp__linear__get_issue({ id })` — the response includes an `attachments` array; look for one where `title == "plan.md"` (or filename — whichever field the MCP surfaces)
+- Comments via `mcp__linear__list_comments({ issueId })` — keep `id`, `createdAt`, body text
+
+This is used to:
+
+- Detect whether a plan already exists (attachment `plan.md`)
+- Determine whether the plan is stale (any comment is newer than the attachment)
+- Record old attachment IDs for replacement
+
+### Step 3a: Determine Which Tasks Need Planning
+
+For each task/subtask, use the following decision logic driven by **attachment modification time vs comment creation time**:
+
+#### Inputs per task
+
+- `planAttachment`: the Linear attachment titled `plan.md` (or `null` if none)
+- `planAttachment.createdAt` / `planAttachment.updatedAt`: when the plan was last written
+- `comments`: list of all comments with `createdAt`
+
+#### Decision logic
+
+**Create a NEW plan if:**
+
+1. **No plan attachment exists**: `planAttachment == null`
+2. **Plan is stale**: there is at least one comment where `comment.createdAt > planAttachment.updatedAt` (use `updatedAt`; fall back to `createdAt` if `updatedAt` is unavailable). Every comment newer than the attachment counts as "feedback on the plan" — we intentionally do NOT try to filter acknowledgments, because the filesystem-style mtime rule is the source of truth the user asked for.
+
+**SKIP planning if:**
+
+1. `planAttachment` exists AND no comment is newer than it.
+
+#### Secondary signal (optional, do not override mtime rule)
+
+If `planAttachment` exists and no comment is newer than it, but the user's latest message mentions plan-change keywords ("zmień plan", "zaktualizuj plan", "popraw plan", "nowy plan", "uwagi do planu", etc.), ask the user explicitly whether to regenerate. Do **not** regenerate silently based on keywords alone.
+
+#### Output:
+
+Create a list of tasks/subtasks that need planning:
+
+- `tasksNeedingPlan`: Array of task IDs that need a new or updated plan
+- `tasksWithExistingPlan`: Array of task IDs with valid, up-to-date plans (skip these)
+- `oldPlanAttachments`: Map of task ID → `attachmentId` for plans that will be replaced (needed for deletion in Step 9)
+
+**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
+
+### 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 6b: Deep Planning Mode (if --deep flag provided)
+
+**Prerequisites**:
+
+- `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1` must be set
+- `--deep` flag must be provided
+
+**If prerequisites NOT met** → Skip to Step 7 (standard planning).
+
+**If prerequisites met:**
+
+1. **Create Planning Team** with 3 perspective teammates:
+
+   **Teammate "Architect"** — spawn `shared-plan-perspective` agent with prompt:
+
+   ```
+   You are the Architect perspective in a planning team for Linear task [taskId].
+
+   Task: [title + description]
+   Codebase analysis: [findings from Steps 4-6a]
+
+   YOUR FOCUS:
+   - Analyze architecture impact (Nx dependency graph, package boundaries)
+   - Check cross-package dependencies (tsconfig paths, barrel exports)
+   - Verify layer compliance (domain → shell flow, no reverse deps)
+   - Evaluate if proposed changes fit existing patterns
+   - Identify affected downstream consumers
+
+   OUTPUT: Structured architecture analysis in Polish with:
+   - Impact assessment (which packages affected)
+   - Pattern compliance (does it follow existing conventions?)
+   - Dependency risks (circular deps, breaking changes)
+   - Recommended approach with file-level details
+   ```
+
+   **Teammate "Implementor"** — spawn `shared-plan-perspective` agent with prompt:
+
+   ```
+   You are the Implementor perspective in a planning team for Linear task [taskId].
+
+   Task: [title + description]
+   Codebase analysis: [findings from Steps 4-6a]
+
+   YOUR FOCUS:
+   - Propose concrete implementation steps
+   - List exact files to modify/create with rationale
+   - Estimate complexity per file (LOC changes, risk level)
+   - Define TDD strategy (which tests first, what to mock)
+   - Identify reusable code/patterns in existing codebase
+
+   OUTPUT: Detailed implementation proposal in Polish with:
+   - Step-by-step implementation plan
+   - File change matrix (file, action, complexity, risk)
+   - TDD strategy per component
+   - Estimated total complexity (Low/Medium/High)
+   ```
+
+   **Teammate "Devil's Advocate"** — spawn `shared-plan-perspective` agent with prompt:
+
+   ```
+   You are the Devil's Advocate in a planning team for Linear task [taskId].
+
+   Task: [title + description]
+   Codebase analysis: [findings from Steps 4-6a]
+
+   WAIT for Architect and Implementor to complete their analyses.
+   Then CRITICALLY review their proposals:
+
+   YOUR FOCUS:
+   - Find holes in the Architect's analysis (missed dependencies, wrong patterns)
+   - Challenge the Implementor's estimates (hidden complexity, missing edge cases)
+   - Identify breaking changes that could affect production
+   - Check for regression risks in existing tests
+   - Look for security implications
+   - Consider performance impact
+
+   OUTPUT: Critical review in Polish with:
+   - Issues found in Architect's analysis
+   - Issues found in Implementor's proposal
+   - Edge cases not covered
+   - Risks with severity ratings (CRITICAL/HIGH/MEDIUM/LOW)
+   - Alternative approaches (if proposed approach is risky)
+   ```
+
+2. **Task dependencies**:
+
+   ```
+   TaskCreate: [PLAN-TEAM] <taskId> Architect analysis       → no dependencies
+   TaskCreate: [PLAN-TEAM] <taskId> Implementor proposal     → no dependencies
+   TaskCreate: [PLAN-TEAM] <taskId> Devil's Advocate review  → blocked by Architect + Implementor
+   ```
+
+   Use `TaskUpdate` to set `addBlockedBy` for Devil's Advocate task.
+
+3. **After Devil's Advocate completes**:
+
+   - Broadcast Devil's Advocate findings to Architect and Implementor
+   - Allow one round of **response** (each teammate addresses concerns raised)
+   - Collect all responses
+
+4. **Lead synthesizes final plan**:
+
+   - Delegate to `shared-report-synthesizer` with all three perspectives + responses
+   - Team type: PLAN-TEAM
+   - Generate plan with additional **"Risks & Mitigations"** section:
+
+     ```markdown
+     ### Ryzyka i mitygacje
+
+     | Ryzyko        | Ważność | Źródło         | Mitygacja             |
+     | ------------- | ------- | -------------- | --------------------- |
+     | [opis ryzyka] | HIGH    | Adwokat Diabła | [strategia mitygacji] |
+     ```
+
+   - Add **"Consensus Rating"**: 1-5 scale based on agreement between teammates
+   - Add **"Confidence Level"**: Based on Devil's Advocate severity findings
+     - WYSOKA: no CRITICAL/HIGH findings
+     - ŚREDNIA: HIGH findings but addressed in responses
+     - NISKA: CRITICAL findings or unresolved HIGH findings
+
+5. **Present enriched plan to user** (Step 7 continues with enhanced plan content)
+
+6. **Cleanup team**
+
+### Agent Team Mode (Experimental)
+
+**Prerequisite**: `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1` in settings.
+
+**Activation**: Add `--deep` flag.
+
+**Fallback**: If env var not set or flag not provided, skill runs in standard sequential mode.
+
+### 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]
+
+### 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_
+```
+
+#### 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]
+
+### 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_
+```
+
+#### Additional sections for --deep mode
+
+When using `--deep` flag and the Planning Team has completed its analysis, append these sections to each plan:
+
+```markdown
+### Analiza wpływu architektonicznego
+
+[From Architect teammate — architecture impact, package dependencies, pattern compliance]
+
+### Ryzyka i mitygacje
+
+| Ryzyko        | Ważność | Źródło         | Mitygacja             |
+| ------------- | ------- | -------------- | --------------------- |
+| [opis ryzyka] | HIGH    | Adwokat Diabła | [strategia mitygacji] |
+
+### Ocena konsensusu: [1-5] / Pewność: [WYSOKA/ŚREDNIA/NISKA]
+
+[Podsumowanie na podstawie debaty zespołowej — zgodność między perspektywami]
+```
+
+**Consensus Rating scale:**
+
+- 5: Full agreement between all three perspectives
+- 4: Minor disagreements, all addressed in response round
+- 3: Some unresolved concerns, but overall direction agreed
+- 2: Significant disagreements on approach
+- 1: Fundamental disagreements — plan needs revision
+
+### 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** (i.e., `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` tool with options:
+
+- "Tak, usuń stare plany i zapisz nowe" (Recommended)
+- "Anuluj"
+
+**If user confirms deletion:**
+
+1. For each task in `oldPlanAttachments`, delete the Linear attachment via `mcp__linear__delete_attachment({ id: attachmentId })`.
+2. Then proceed to Step 9a.
+
+**If user cancels:**
+
+- Stop the entire process, do not save any plans.
+
+### Step 9a: Save Plan as 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 via `mcp__linear__create_attachment` — Linear hosts the file itself, no intermediate storage.
+
+#### 9a.1 — Prepare plan content
+
+The plan content is exactly the markdown produced in Step 8 (the same block that would previously have been posted as a comment). Write it to the temp file:
+
+```bash
+mkdir -p /tmp/claude-plans
+```
+
+Use the `Write` tool to save the plan markdown to `/tmp/claude-plans/<taskId>-plan.md`.
+
+#### 9a.2 — Base64-encode the content
+
+```bash
+b64=$(base64 -i /tmp/claude-plans/<taskId>-plan.md)
+```
+
+On macOS `base64 -i <file>` outputs without line-wrapping (which is what the Linear MCP expects). If you ever switch to GNU coreutils, pipe through `tr -d '\n'` to strip wraps.
+
+#### 9a.3 — Create the Linear attachment
+
+Call `mcp__linear__create_attachment` with:
+
+- `issue`: the task or subtask ID (e.g. `FRA-123`)
+- `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`
+- `base64Content`: the base64 string from 9a.2
+
+Linear stores the file on its own infrastructure and surfaces it in the issue's Attachments pane.
+
+#### 9a.4 — Clean up local file
+
+Delete `/tmp/claude-plans/<taskId>-plan.md` after the attachment is created successfully. `/push` leaves Linear attachments in place — they stay on the issue as permanent artifacts.
+
+#### Scope rule
+
+- If the parent task has **no subtasks** → create one `plan.md` attachment on the parent task.
+- If the parent task **has subtasks** → create a `plan.md` attachment on **each subtask** that needs planning. Do NOT create a `plan.md` on the parent task.
+
+### Step 9b: Add "AI Plan" Label
+
+After all plan attachments are saved, apply the `AI Plan` label to the **invoked issue** — i.e. the exact `linearTaskId` passed to `/plan`:
+
+- `/plan FRA-123` (parent) → label goes on `FRA-123`. Subtasks receive `plan.md` attachments but no label.
+- `/plan FRA-123-1` (subtask) → label goes on `FRA-123-1` directly. Do NOT touch the parent.
+
+**`AI Plan` is a workspace-level (organization-wide) label that already exists in this Linear workspace** — it must NOT be created. Do not call `create_issue_label`.
+
+Steps:
+
+1. **Locate the label**:
+
+   - Use `mcp__linear__list_issue_labels` (no team filter, or workspace-wide scope) to find the label named exactly `AI Plan`.
+   - If for any reason the label cannot be located (rate limit, unexpected API response), surface the error and stop the labeling step — do NOT create a team-scoped duplicate.
+
+2. **Apply to the invoked issue**:
+
+   - Use `mcp__linear__save_issue({ id: invokedTaskId, labelIds: [...existingLabelIds, aiPlanLabelId] })`.
+   - Preserve existing labels — do NOT replace them. Fetch current labels first if needed and concatenate.
+   - If the label is already on the issue, skip the update.
+
+3. **Failure handling**: if label lookup/apply fails, surface the error but do not roll back the plan attachment. The plan is the primary deliverable; the label is a marker.
+
+### 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 successfully saving the plans, confirm to the user:
+
+- List all tasks/subtasks where `plan.md` was attached (include Linear attachment URL)
+- Show a summary of each plan
+- Confirm that `AI Plan` label was added to the parent task
+- Provide Linear task links
+- Mention any important considerations or questions
+
+## 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`'s `updatedAt`). Don't regenerate plans unnecessarily.
+14. **Mtime rule is authoritative**: Regeneration is driven by comparing `plan.md` attachment `updatedAt` against comment `createdAt`. Keyword detection in comments is only a secondary hint that triggers an explicit user confirmation — never a silent regen.
+15. **Delete old plans cleanly**: When replacing, ask the user to confirm, then delete the old Linear attachment via `mcp__linear__delete_attachment`. Record attachment IDs during Step 3a for use in Step 9.
+16. **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.
+
+## Example with Subtasks
+
+For Linear task "ENG-456: User profile improvements" with subtasks:
+
+- ENG-456-1: Add avatar upload
+- ENG-456-2: Add profile bio field
+- ENG-456-3: Add social links section
+
+**Attachment `plan.md` saved on ENG-456-1:**
+
+```markdown
+## Implementation Plan for Subtask
+
+**Parent Task**: ENG-456 - User profile improvements
+
+### Subtask Summary
+
+Add avatar upload functionality to user profile, allowing users to upload and display profile pictures.
+
+### Already Completed
+
+- `a1b2c3d` - feat(shared-angular): add file upload base component
+
+**Files modified:**
+
+- `libs/shared/angular/src/lib/components/file-upload/file-upload.component.ts`
+
+### Currently In Progress
+
+None
+
+### Remaining Work
+
+- [ ] Integrate file-upload into user profile
+- [ ] Add avatar display with fallback
+- [ ] Connect to storage API
+
+### Technical Analysis
+
+- File upload component already exists and can be reused
+- Need to add avatar-specific validation (image types, dimensions)
+
+### Implementation Steps
+
+1. Add avatar upload section to profile form
+2. Implement image preview before upload
+3. Connect to avatar storage endpoint
+4. Add avatar display component
+
+### Files to Modify
+
+- `libs/shared/angular/src/lib/components/user-profile/user-profile.component.ts`
+
+### New Files
+
+- `libs/shared/angular/src/lib/components/avatar-display/avatar-display.component.ts`
+
+### External Library Changes (separate process)
+
+**@smartsoft001/pro (repo: ../smartsoft001-pro)**
+
+- [ ] `packages/angular` - Add `SmartAvatarComponent` with image cropping support
+
+> **Note**: These changes are NOT part of this subtask. Separate process required.
+
+### Dependencies
+
+- **Depends on**: None (but blocked by library changes above)
+- **Blocks**: None
+
+### Testing Strategy
+
+- [ ] Unit tests for avatar upload integration
+- [ ] E2E test for upload flow
+
+### Estimated Complexity
+
+Medium
+
+---
+
+_Plan generated by Claude Code_
+```
+
+**Attachment `plan.md` saved on ENG-456-2:**
+
+```markdown
+## Implementation Plan for Subtask
+
+**Parent Task**: ENG-456 - User profile improvements
+
+### Subtask Summary
+
+Add a bio/description field to the user profile allowing users to write about themselves.
+
+### Already Completed
+
+None
+
+### Currently In Progress
+
+None
+
+### Remaining Work
+
+- [ ] Add bio field to user model
+- [ ] Add textarea to profile form
+- [ ] Implement character limit validation
+
+### Technical Analysis
+
+- User model at `libs/shared/angular/src/lib/models/user.model.ts`
+- Profile form uses reactive forms pattern
+
+### Implementation Steps
+
+1. Add `bio` field to user model
+2. Add textarea with character counter to profile form
+3. Update user service to handle bio field
+
+### Files to Modify
+
+- `libs/shared/angular/src/lib/models/user.model.ts`
+- `libs/shared/angular/src/lib/components/user-profile/user-profile.component.ts`
+- `libs/shared/angular/src/lib/services/user.service.ts`
+
+### New Files
+
+None
+
+### Dependencies
+
+- **Depends on**: None
+- **Blocks**: None
+
+### Testing Strategy
+
+- [ ] Unit test for bio validation
+- [ ] E2E test for bio save flow
+
+### Estimated Complexity
+
+Low
+
+---
+
+_Plan generated by Claude Code_
+```
+
+---
+
+**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.