@smartsoft001/pro-claude-plugins 0.8.0 → 0.10.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@smartsoft001/pro-claude-plugins",
-  "version": "0.8.0",
+  "version": "0.10.0",
   "publishConfig": {
     "access": "public"
   },

package/plugins/flow/.claude-plugin/plugin.json

@@ -1,5 +1,5 @@
 {
   "name": "flow",
   "description": "Development flow skills for Linear-driven development workflow",
-  "version": "0.8.0"
+  "version": "0.10.0"
 }

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

@@ -63,6 +63,7 @@ Execute each step in order. Do not skip any step marked as MANDATORY.
 - [ ] **9. Verify implementation** — run tests, lint, build check
 - [ ] **9.5. E2E tests (conditional)** — if `E2E_TESTS_RECOMMENDED: YES`, delegate to `test-e2e` skill
 - [ ] **10. Capture "after" screenshots** — if `UI_CHANGE_REQUIRED: YES`, capture + post comparison to Linear + cleanup
+- [ ] **10.5. Mockup fidelity check (conditional)** — if `UI_CHANGE_REQUIRED: YES` and `docs/mockups/` exists, compare the changed page against its mockup export and fix divergences (max 2 fix-and-recheck iterations) before the screenshot verification checkpoint (11); after any fix, re-run tests/lint/build on the touched projects
 - [ ] **11. MANDATORY: Screenshot verification** — output `SCREENSHOT_REQUIREMENT_MET: YES/NO`, block if missing
 - [ ] **12. Create completion comment** — delegate to `shared-impl-reporter`, post to Linear
 - [ ] **13. MANDATORY: Write reports in Polish** — all Linear comments must be in Polish language
@@ -260,6 +261,7 @@ Continue to Step 3.
    - Verify (lint, tests, build)
    - E2E tests (if UI)
    - Screenshots (if UI) — before + after + post to Linear
+   - Mockup fidelity check (if UI and docs/mockups/ exists) — compare against the export, max 2 fix-and-recheck iterations, re-run tests/lint/build after fixes
    - Create completion comment (shared-impl-reporter) — IN POLISH
    - Update status
 
@@ -623,6 +625,78 @@ The agent will:
 - After screenshots: ✅ COMPLETED & POSTED TO LINEAR
 ```
 
+Continue to Step 3e-mockup.
+
+#### Step 3e-mockup: Visual Fidelity Check Against Approved Mockups (CONDITIONAL)
+
+**⚠️ CONDITIONAL: Execute this step ONLY IF `UI_CHANGE_REQUIRED: YES` AND the workspace contains a `docs/mockups/` directory.** Otherwise skip to Step 3f-verify.
+
+Screenshots exist to be COMPARED, not only archived. A page can pass tests,
+lint and build while rendering the wrong component variant, a broken footer or
+raw translation keys — divergences that stay invisible until the screenshot is
+put NEXT TO the approved design. This step closes that loop while the context
+is still loaded, instead of leaving it to post-hoc review.
+
+**Process:**
+
+1. **Find the reference.** Match the page(s) from the Screenshot Plan to their
+   exports in `docs/mockups/` by file name (read the directory's README for
+   the route → file map; `-mobile` / `-kontrast` suffixes are viewport/contrast
+   variants). Some references are component-level exports (a single card, list
+   item or searchbar) — for those, compare that component within the page, not
+   the whole page. If the changed component is reused across pages, compare ONE
+   representative page. No matching export → record `Mockup check: N/A` in the
+   Screenshot Plan and skip to Step 3f-verify.
+2. **Capture local screenshots via the `screenshot-reporter` agent** in
+   capture-only mode (the skill's own tool list has no browser access — the
+   agent does). Do NOT rely on the uploaded "after" screenshots — they may
+   already be cleaned up.
+
+   ```
+   Capture FULL-PAGE screenshots (mockup exports are full-page frames —
+   a viewport-only shot would fake missing-section divergences):
+   - Page(s): [pages matched in item 1]
+   - Viewports: desktop (1920x1080); mobile (375x667) ONLY IF a -mobile
+     export exists for the page
+   - Phase: mockup-check — capture only: return local file paths,
+     do NOT upload, do NOT post to Linear, do NOT clean up
+   ```
+
+   `-kontrast` exports are out of scope for this loop unless the subtask
+   changed contrast/dark-mode styling — the high-contrast mode is owned by
+   the shared WCAG widget and dedicated a11y checks.
+3. **Read both images side by side** and list every divergence in: section
+   layout, component structure (thumbnail / metadata / action-button
+   arrangement), brand palette and tokens, typography, ornaments and
+   decorative assets, raw translation keys visible on screen.
+4. **Judge structure over theme, and scope to THIS subtask.** Component
+   exports may come from a shared, multi-project design system: the project's
+   own palette and typography win over the sample's theme. Ignore content
+   differences (mockups carry lorem-ipsum text and placeholder photos),
+   data-dependent counts, and sub-pixel rendering noise. A view-state mismatch
+   (grid vs list) counts only when the mockup depicts the same view state —
+   check the README's notes. A divergence caused by a page or module that a
+   DIFFERENT subtask owns (e.g. a section not implemented yet) is out of
+   scope: note it for the completion comment, do not fix it here.
+5. **Fix real divergences NOW**, re-capture, re-compare. **Hard bound: at most
+   2 fix-and-recheck iterations.** Whatever still diverges after the second
+   pass goes into the completion comment as an explicit list — do not keep
+   looping; structural and brand fidelity is the bar, pixel-perfection is not.
+   Fixes are code changes: after the loop, re-run the Step 3e verification
+   (tests / lint / build, scoped to the touched projects) — fixed code must
+   not reach "In Review" on stale results (Guideline: run tests before
+   marking complete). If any fix was applied, re-launch `screenshot-reporter`
+   for a final "after" capture and post an updated comparison to Linear — the
+   one posted in Step 3e-visual-after no longer shows the shipped state.
+
+**Update Screenshot Plan status:**
+
+```markdown
+### Screenshot Plan
+
+- Mockup check: [✅ MATCHES / ⚠️ divergences listed in completion comment / N/A (no matching export)]
+```
+
 #### Step 3f-verify: MANDATORY Screenshot Verification Checkpoint
 
 **⚠️ THIS VERIFICATION CANNOT BE SKIPPED**
@@ -641,6 +715,7 @@ Before creating the completion comment, verify the screenshot requirement:
 - [ ] Before screenshots captured: [YES with Task ID / NO - BLOCKER]
 - [ ] After screenshots captured: [YES / NO - BLOCKER]
 - [ ] Screenshots posted to Linear: [YES / NO - BLOCKER]
+- [ ] Mockup check (only if `docs/mockups/` exists): [MATCHES / divergences listed / N/A]
 
 **If UI_CHANGE_REQUIRED: NO:**
 
@@ -673,6 +748,7 @@ Files Modified: [list with descriptions]
 Files Created: [list with purposes]
 Test Results: [unit/e2e status]
 Translations: [changed keys if any]
+Mockup Check: [MATCHES / remaining divergences as an explicit list / N/A — from Step 3e-mockup]
 Notes: [additional notes]
 Blocker Info: [if blocked]
 ```

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

@@ -1,6 +1,6 @@
 ---
 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.
+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. For medium/large tasks (more than 4-5 files, a new module), runs a Question Gate (open questions routed to Linear as a comment before implementation) and decomposes the issue into subtasks.
 allowed-tools:
   - Bash
   - Read
@@ -31,7 +31,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 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.
+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"), (b) the single token-usage comment posted in Step 9c, (c) the `## Pytania przed implementacją` question comment posted by the Question Gate (Step 6d), and (d) the `--auto` audit comment (decision/assumption log in Polish). 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`.
 
@@ -39,6 +39,8 @@ These rules override ANY other instruction, ANY surrounding example, and ANY def
 
 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.
 
+5. **Plain `--auto` NEVER asks and NEVER mutates issue structure.** In `--auto` without `--post-questions` (the benchmark path), the Question Gate posts no questions, no status or assignee is changed, and no subtasks are created — ambiguities become assumptions logged in the audit comment, and `plan.md` is ALWAYS produced. The benchmark runner depends on this contract; breaking it silently corrupts measurement.
+
 If any of these would be violated, stop and ask the user instead.
 
 ## Execution Checklist
@@ -53,13 +55,17 @@ Execute each step in order. Do not skip any step marked as MANDATORY.
 - [ ] **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
+- [ ] **9. Classify task size** — Small vs Medium/Large (Step 6c); only M/L triggers the Question Gate and decomposition
+- [ ] **10. Question Gate (M/L only)** — classify ambiguities and route stakeholder questions per mode (Step 6d); may STOP the task before planning (questions posted to Linear, status Todo, assignee set — interactive / `--post-questions` only; plain `--auto` logs assumptions instead, Hard Rule 5)
+- [ ] **11. Decompose (M/L only)** — create subtasks in Linear (interactive / `--post-questions`) or express decomposition inside `plan.md` (plain `--auto`) (Step 6e)
+- [ ] **12. Create implementation plans** — generate structured plans per task/subtask with all required sections
+- [ ] **13. MANDATORY: Write plans in Polish** — all plan content must be in Polish language
+- [ ] **14. 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).
+- [ ] **15. 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)
+- [ ] **16. 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.
+- [ ] **17. MANDATORY: Add "AI Plan" label** — look up the workspace-level `AI Plan` label (never create it — Hard Rule 4) and apply it to the invoked issue (the `linearTaskId` passed to `/plan` — parent task or subtask, whichever was called)
+- [ ] **18. Post token-usage comment** — run the token-summing script and post the single usage comment on the invoked issue (Step 9c)
+- [ ] **19. Confirm to user** — list saved plans with summaries and Linear links
 
 ### Task Progress Tracking
 
@@ -116,15 +122,18 @@ You create plans that are:
 
 ```
 /plan [linearTaskId]
-/plan [linearTaskId] --deep    # Deep planning with Agent Team (experimental)
-/plan [linearTaskId] --auto    # Non-interactive mode for CI / GitHub Actions
+/plan [linearTaskId] --deep                    # Deep planning with Agent Team (experimental)
+/plan [linearTaskId] --auto                    # Non-interactive mode for benchmark / fully autonomous runs
+/plan [linearTaskId] --auto --post-questions   # Non-interactive mode for the automated Claude Code development process
 ```
 
 ## 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` - 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 runs where no human is at the keyboard. Without `--post-questions` this is the **benchmark contract**: no questions posted, no status/assignee changes, no subtask creation, `plan.md` always produced (Hard Rule 5).
+- `--post-questions` - Modifier for `--auto` (ignored without it): headless runs of the Claude Code development process — NOT the benchmark. Stakeholder ambiguities found by the Question Gate are posted to Linear automatically (question comment + status `Todo` + assignee = issue creator) and the task exits without `plan.md` — and without creating subtasks — until answers arrive. When no stakeholder questions block the task (none found, or all answered on a re-run), M/L tasks are decomposed into real Linear subtasks automatically. The benchmark runner never passes this flag.
+- `--questions-assignee=<user>` - Optional, only with `--auto --post-questions`: overrides the addressee of posted questions (name or email resolvable in Linear). Default: the issue creator. Useful when issues are created by an integration/bot account.
 
 ## Auto Mode (`--auto`)
 
@@ -136,15 +145,17 @@ You create plans that are:
 | 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 |
+| `AskUserQuestion` for any decision                                | Use the option marked **(Recommended)**. If none is marked: in plain `--auto` pick the safest option, log it in the audit comment, and continue — plain `--auto` may NEVER exit without `plan.md` (Hard Rule 5); the fail-fast-with-Linear-comment exit is allowed only with `--post-questions` |
+| Question Gate: stakeholder questions (Step 6d)                    | Plain `--auto`: never posted — adopt the safest assumption per question and log ALL of them in the audit comment. With `--post-questions`: post the question comment + status `Todo` + assignee automatically; the task exits without `plan.md` and without creating subtasks |
+| Decomposition: subtask creation (Step 6e)                         | Plain `--auto`: never — decomposition stays inside `plan.md` as phases. With `--post-questions`: subtasks created automatically (and listed in the audit comment) ONLY when no stakeholder questions block the task |
 
 **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).
+**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) and with `--post-questions` (see Parameters).
 
 ## 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.
+You are tasked with creating an implementation plan for a Linear task and saving it as a `plan.md` attachment in Linear (Hard Rule 1 — never as a comment). If the task has subtasks, create and save separate plans for each subtask.
 
 ### Step 1: Fetch Linear Task Details
 
@@ -309,7 +320,7 @@ Check if the task requires changes to external library packages:
 - `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 NOT met** → Skip to Step 6c (size classification — the standard pipeline continues from there).
 
 **If prerequisites met:**
 
@@ -422,7 +433,7 @@ Check if the task requires changes to external library packages:
      - Ś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)
+5. **Continue with Step 6c** — the team's enriched analysis feeds size classification, the Question Gate, decomposition, and the final plan content (Step 7)
 
 6. **Cleanup team**
 
@@ -434,6 +445,108 @@ Check if the task requires changes to external library packages:
 
 **Fallback**: If env var not set or flag not provided, skill runs in standard sequential mode.
 
+### Step 6c: Task Size Classification
+
+Based on the findings from Steps 4–6a, classify the task as **Small** or **Medium/Large**:
+
+**Medium/Large (M/L)** if ANY of the following holds:
+
+- estimated affected files (modify + create) exceed **4–5**,
+- a **new module / package / domain area** is created,
+- the change spans **multiple layers or apps** (e.g. domain + backend + frontend),
+- the Linear estimate (if present) is M or higher.
+
+**Small** otherwise (isolated bugfix, copy change, single-component tweak).
+
+Routing:
+
+- **Small** → skip Steps 6d–6e entirely and continue with Step 7. Behavior is identical to the skill before the Question Gate existed.
+- **M/L** → run Step 6d (Question Gate), then Step 6e (Decomposition).
+- If the issue **already has subtasks**, treat decomposition as done: run Step 6d only, then continue with per-subtask planning as usual.
+
+State the classification and its trigger (e.g. `M/L — 9 plików, nowy moduł raportów`) in the chat (interactive) or in the audit comment (`--auto`).
+
+### Step 6d: Question Gate (M/L only)
+
+Surface ambiguities BEFORE the plan is written — key decisions should happen at the cheapest possible moment, and questions should travel to the person who can answer them instead of dying inside the session.
+
+#### 6d.1 — Collect and classify ambiguities
+
+Scan the task description, its comments, and your codebase findings for unknowns in four categories (one question = one category):
+
+1. **Blockers** — missing decisions or data without which the implementation would have to guess (e.g. which permission gates a view, where the data comes from)
+2. **Approach tradeoffs** — two or more viable designs with real consequences
+3. **Scope / priorities** — unclear boundaries ("does X belong to this task?")
+4. **Risky assumptions** — things you would otherwise assume silently
+
+**Never ask about anything checkable in the code, git history, or Linear** — check it instead. If there are NO ambiguities, note `brak pytań` and go straight to Step 6e.
+
+Split the resulting questions into:
+
+- **session-resolvable** — the operator at the keyboard can decide;
+- **stakeholder-needed** — requires product/data/another person. Default addressee: the **issue creator**.
+
+#### 6d.2 — Mode behavior
+
+| Mode                     | Session-resolvable                                                                                             | Stakeholder-needed                                                                                                                                          |
+| ------------------------ | -------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Interactive (default)    | one `AskUserQuestion` batch (1–4 questions, 2–4 disjoint options each, recommended option FIRST with "(Recommended)") | ask the developer first (gate below); on approval post the comment + status + assignee                                                                       |
+| `--auto --post-questions`| resolve with the recommended option; log in the audit comment                                                   | post the question comment + status **Todo** + assignee **automatically**; the task exits without `plan.md`; audit comment records what was posted            |
+| `--auto` (plain)         | resolve with the recommended option; log                                                                        | do NOT post; adopt the safest assumption per question; log ALL assumptions in the audit comment (`Założenia przyjęte automatycznie: ...`); `plan.md` ALWAYS produced |
+
+Interactive stakeholder gate — `AskUserQuestion`:
+
+> Wykryto N pytań wymagających odpowiedzi interesariusza. Dodać komentarz z pytaniami do `<linearTaskId>`, ustawić status Todo i przypisać do `<creator>`?
+
+- **"Tak, dodaj pytania i zmień status"** _(Recommended)_ — post per 6d.3–6d.4, then STOP for this task.
+- **"Nie — odpowiem teraz w sesji"** — ask the questions via `AskUserQuestion` batches and continue the pipeline.
+- **"Pomiń — przyjmij założenia"** — treat like plain `--auto` for these questions; record the assumptions in the plan's "Risks & Considerations" section.
+
+#### 6d.3 — Question comment format (Polish)
+
+Post ONE comment via `mcp__linear__save_comment`:
+
+```markdown
+## Pytania przed implementacją
+
+Odpowiedz pod tym komentarzem — wystarczy numer pytania i odpowiedź.
+
+**P1. [krótki tytuł]**
+[2–3 zdania kontekstu — samowystarczalne, bez ścieżek repo i żargonu wewnętrznego]
+Pytanie: [...]
+Blokuje: [co dokładnie stoi bez odpowiedzi]
+
+**P2. [...]**
+```
+
+- **Continuous numbering per issue**: scan existing comments for previous `## Pytania przed implementacją` sections and continue the numbering (P4, P5, ...). NEVER renumber existing questions — replies reference them by number.
+- **Reconciliation check before posting**: every **blocker** from 6d.1 maps to exactly one question (1:1); questions from the other three categories (tradeoffs, scope, assumptions) are allowed and must each trace back to a specific 6d.1 item. Fix mismatches before the post.
+
+#### 6d.4 — Status + assignee
+
+After posting the comment, call `mcp__linear__save_issue({ id, state: "Todo", assignee: <addressee> })` — status **Todo** (never In Progress; the task is explicitly waiting for a human). The addressee defaults to the **issue creator, taken from the `creator` field of the `mcp__linear__get_issue` response** (no extra user-lookup tool needed); overrides: interactively pick "Other" on the gate question and name the person, headless pass `--questions-assignee=<user>`. Then STOP: the halt covers the ENTIRE invoked issue — if it has subtasks, no `plan.md` is saved on any of them and no new subtasks are created; the status/assignee change lands on the invoked issue only. Print a short Polish summary listing the posted questions.
+
+#### 6d.5 — Re-run with answers
+
+When `/plan` runs again on an issue that carries a `## Pytania przed implementacją` comment:
+
+- **answers exist** (comments newer than the question comment): incorporate them — quote each decision in the plan's "Technical Analysis" or "Risks & Considerations" — and continue the pipeline;
+- **unanswered**: interactive → tell the user and ask (wait / answer now in session / proceed with assumptions); `--auto --post-questions` → exit cleanly with an audit comment (`Pytania z <data> wciąż bez odpowiedzi — plan nie został wygenerowany.`); plain `--auto` → proceed with logged assumptions (Hard Rule 5).
+
+### Step 6e: Decomposition into Subtasks (M/L only)
+
+Skip if the issue already has subtasks. Otherwise break the task into subtasks, each an independently implementable and reviewable unit:
+
+- each subtask = one coherent slice; layers (domain → BE/FE) live INSIDE a subtask, never as separate subtasks;
+- per subtask: imperative Polish title, 2–5-sentence description with scope + planned Files to Modify, and dependencies on other subtasks;
+- prefer 2–6 subtasks; merge any "subtask" smaller than roughly one file into a neighbor.
+
+Mode behavior:
+
+- **Interactive**: present the breakdown table (title, scope, files, depends-on) and ask via `AskUserQuestion`: `Utworzyć N podzadań w Linear?` with options **"Tak, utwórz podzadania"** _(Recommended)_ / **"Popraw podział"** (capture feedback, redo the breakdown) / **"Kontynuuj bez podzadań"** (single-task planning). On approval create each subtask via `mcp__linear__save_issue` (team and project inherited from the parent, state `Todo`, parent set to the invoked issue). Then continue with Step 7 using the "If subtasks exist" path.
+- **`--auto --post-questions`**: create the subtasks automatically and list them in the audit comment.
+- **`--auto` (plain)**: do NOT create subtasks — express the decomposition inside `plan.md` as phases in "Implementation Steps". Issue structure stays untouched (Hard Rule 5).
+
 ### Step 7: Create Implementation Plans
 
 #### If NO subtasks exist:
@@ -756,7 +869,7 @@ Use `AskUserQuestion` tool with options:
 
 ### 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.)
+**⛔ 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.** (The allowed `save_comment` exceptions are listed in Hard Rule 1 — token usage in Step 9c, Question Gate questions, audit comments.)
 
 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.
 
@@ -856,7 +969,7 @@ 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
+- Confirm that `AI Plan` label was added to the invoked issue
 - Provide Linear task links
 - Mention any important considerations or questions
 
@@ -868,7 +981,7 @@ After successfully saving the plans, confirm to the user:
 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
+7. **Ask for clarification**: for M/L tasks the Question Gate (Step 6d) is the mandatory mechanism — stakeholder questions go to Linear, not into silent assumptions; for Small tasks keep the pre-existing behavior: an ad-hoc `AskUserQuestion` in interactive mode only (in any `--auto` mode adopt the safest assumption and log it — Hard Rule 5)
 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

package/plugins/flow-external/.claude-plugin/plugin.json

@@ -1,5 +1,5 @@
 {
   "name": "flow-external",
   "description": "Development flow skills for standalone Angular 6-11 projects without framework (Angular CLI, Karma/Jasmine, Bootstrap 4)",
-  "version": "0.8.0"
+  "version": "0.10.0"
 }

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

@@ -1,6 +1,6 @@
 ---
 name: plan
-description: Create implementation plan and save it as a `plan.md` attachment on the Linear issue. Analyzes codebase, understands task requirements, and generates structured plan.
+description: Create implementation plan and save it as a `plan.md` attachment on the Linear issue. Analyzes codebase, understands task requirements, and generates structured plan. For medium/large tasks (more than 4-5 files, a new module), runs a Question Gate (open questions routed to Linear as a comment before implementation) and decomposes the issue into subtasks.
 allowed-tools:
   - Bash
   - Read
@@ -13,7 +13,6 @@ allowed-tools:
   - mcp__linear__list_comments
   - mcp__linear__save_comment
   - mcp__linear__save_issue
-  - mcp__linear__save_issue
   - mcp__linear__create_attachment
   - mcp__linear__delete_attachment
   - mcp__linear__list_issue_labels
@@ -27,13 +26,16 @@ Create a structured implementation plan for a Linear task and save it as a `plan
 
 ```
 /plan <linearTaskId>
-/plan <linearTaskId> --auto    # Non-interactive mode for CI / GitHub Actions
+/plan <linearTaskId> --auto                    # Non-interactive mode for fully autonomous runs
+/plan <linearTaskId> --auto --post-questions   # Non-interactive mode for the automated Claude Code development process
 ```
 
 ## Parameters
 
 - `linearTaskId` - Linear task ID (e.g., FRA-123)
-- `--auto` - Non-interactive mode: skip ALL `AskUserQuestion` prompts. Auto-approve plan before saving, auto-delete stale `plan.md` attachment without confirmation, and silently skip when the existing plan is up to date. Designed for CI / GitHub Actions runs where no human is at the keyboard.
+- `--auto` - Non-interactive mode: skip ALL `AskUserQuestion` prompts. Auto-approve plan before saving, auto-delete stale `plan.md` attachment without confirmation, and silently skip when the existing plan is up to date. Designed for runs where no human is at the keyboard. Without `--post-questions` this is the fully-autonomous contract: no questions posted, no status/assignee changes, no subtask creation, `plan.md` always produced (Hard Rule 4).
+- `--post-questions` - Modifier for `--auto` (ignored without it): headless runs of the Claude Code development process. Stakeholder ambiguities found by the Question Gate are posted to Linear automatically (question comment + status `Todo` + assignee = issue creator) and the task exits without `plan.md` — and without creating subtasks — until answers arrive. When no stakeholder questions block the task (none found, or all answered on a re-run), M/L tasks are decomposed into real Linear subtasks automatically.
+- `--questions-assignee=<user>` - Optional, only with `--auto --post-questions`: overrides the addressee of posted questions (name or email resolvable in Linear). Default: the issue creator. Useful when issues are created by an integration/bot account.
 
 ## Auto Mode (`--auto`)
 
@@ -43,8 +45,10 @@ When `--auto` is set, the skill MUST run end-to-end without any human-in-the-loo
 | ------------------------------------------------------------- | ------------------------------------------------------------------------------------ |
 | Ask user to confirm deletion of old `plan.md` attachment      | Delete old attachment automatically before saving the new one                        |
 | Ask "regenerate?" when plan is up-to-date but keywords detect | Ignore the secondary signal; only the mtime rule decides regeneration                |
-| Final approval of generated plan content before saving        | Skip the approval gate (Step 4a); proceed directly to attachment save (auto-approve) |
-| Any `AskUserQuestion`                                         | Use the **(Recommended)** option; if none, fail fast with a Linear comment           |
+| Final approval of generated plan content before saving        | Skip the approval gate (Step 4a); auto-approve and continue the pipeline from Step 5 |
+| Any `AskUserQuestion`                                         | Use the **(Recommended)** option. If none is marked: in plain `--auto` pick the safest option, log it in the audit comment, and continue — plain `--auto` may NEVER exit without `plan.md` (Hard Rule 4); the fail-fast-with-Linear-comment exit is allowed only with `--post-questions` |
+| Question Gate: stakeholder questions (Step 3b)                | Plain `--auto`: never posted — adopt the safest assumption per question and log ALL of them in the audit comment. With `--post-questions`: post the question comment + status `Todo` + assignee automatically; the task exits without `plan.md` and without creating subtasks |
+| Decomposition: subtask creation (Step 5)                      | Plain `--auto`: never — decomposition stays inside `plan.md` (section "Podzadania"). With `--post-questions`: subtasks created automatically (and listed in the audit comment) ONLY when no stakeholder questions block the task |
 
 Every decision MUST be logged as a Linear comment in Polish (audit trail). The mtime rule remains authoritative.
 
@@ -54,9 +58,10 @@ Every decision MUST be logged as a Linear comment in Polish (audit trail). The m
 
 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 7b. No other comment may carry plan content.
+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, (b) the single token-usage comment posted in Step 7b, (c) the `## Pytania przed implementacją` question comment posted by the Question Gate (Step 3b), and (d) the `--auto` audit comment (decision/assumption log in Polish). 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. **`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.
+4. **Plain `--auto` NEVER asks and NEVER mutates issue structure.** In `--auto` without `--post-questions`, the Question Gate posts no questions, no status or assignee is changed, and no subtasks are created — ambiguities become assumptions logged in the audit comment, and `plan.md` is ALWAYS produced. Headless callers (CI, benchmark) depend on this contract; breaking it silently corrupts automation.
 
 If any of these would be violated, stop and ask the user instead.
 
@@ -118,6 +123,94 @@ Based on the task:
 3. Check for existing patterns to follow
 4. Identify NgModules that need updating
 
+### Step 3a: Task Size Classification
+
+Based on the findings from Steps 2–3, classify the task as **Small** or **Medium/Large**:
+
+**Medium/Large (M/L)** if ANY of the following holds:
+
+- estimated affected files (modify + create) exceed **4–5**,
+- a **new module / feature area** is created,
+- the change spans multiple NgModules or apps,
+- the Linear estimate (if present) is M or higher.
+
+**Small** otherwise (isolated bugfix, copy change, single-component tweak).
+
+Routing:
+
+- **Small** → skip Step 3b and the subtask creation in Step 5; continue with Step 4. Behavior is identical to the skill before the Question Gate existed.
+- **M/L** → run Step 3b (Question Gate), then continue with Step 4; Step 5 handles decomposition.
+- If the issue **already has subtasks**, treat decomposition as done: run Step 3b, then continue with Step 4; skip the subtask creation in Step 5.
+
+State the classification and its trigger (e.g. `M/L — 9 plików, nowy moduł raportów`) in the chat (interactive) or in the audit comment (`--auto`).
+
+### Step 3b: Question Gate (M/L only)
+
+Surface ambiguities BEFORE the plan is written — key decisions should happen at the cheapest possible moment, and questions should travel to the person who can answer them instead of dying inside the session.
+
+#### 3b.1 — Collect and classify ambiguities
+
+Scan the task description, its comments, and your codebase findings for unknowns in four categories (one question = one category):
+
+1. **Blockers** — missing decisions or data without which the implementation would have to guess
+2. **Approach tradeoffs** — two or more viable designs with real consequences
+3. **Scope / priorities** — unclear boundaries ("does X belong to this task?")
+4. **Risky assumptions** — things you would otherwise assume silently
+
+**Never ask about anything checkable in the code, git history, or Linear** — check it instead. If there are NO ambiguities, note `brak pytań` and go straight to Step 4.
+
+Split the resulting questions into:
+
+- **session-resolvable** — the operator at the keyboard can decide;
+- **stakeholder-needed** — requires product/data/another person. Default addressee: the **issue creator**.
+
+#### 3b.2 — Mode behavior
+
+| Mode                     | Session-resolvable                                                                                             | Stakeholder-needed                                                                                                                                          |
+| ------------------------ | -------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Interactive (default)    | one `AskUserQuestion` batch (1–4 questions, 2–4 disjoint options each, recommended option FIRST with "(Recommended)") | ask the developer first (gate below); on approval post the comment + status + assignee                                                                       |
+| `--auto --post-questions`| resolve with the recommended option; log in the audit comment                                                   | post the question comment + status **Todo** + assignee **automatically**; the task exits without `plan.md`; audit comment records what was posted            |
+| `--auto` (plain)         | resolve with the recommended option; log                                                                        | do NOT post; adopt the safest assumption per question; log ALL assumptions in the audit comment (`Założenia przyjęte automatycznie: ...`); `plan.md` ALWAYS produced |
+
+Interactive stakeholder gate — `AskUserQuestion`:
+
+> Wykryto N pytań wymagających odpowiedzi interesariusza. Dodać komentarz z pytaniami do `<linearTaskId>`, ustawić status Todo i przypisać do `<creator>`?
+
+- **"Tak, dodaj pytania i zmień status"** _(Recommended)_ — post per 3b.3–3b.4, then STOP for this task.
+- **"Nie — odpowiem teraz w sesji"** — ask the questions via `AskUserQuestion` batches and continue the pipeline.
+- **"Pomiń — przyjmij założenia"** — treat like plain `--auto` for these questions; record the assumptions in the plan.
+
+#### 3b.3 — Question comment format (Polish)
+
+Post ONE comment via `mcp__linear__save_comment`:
+
+```markdown
+## Pytania przed implementacją
+
+Odpowiedz pod tym komentarzem — wystarczy numer pytania i odpowiedź.
+
+**P1. [krótki tytuł]**
+[2–3 zdania kontekstu — samowystarczalne, bez ścieżek repo i żargonu wewnętrznego]
+Pytanie: [...]
+Blokuje: [co dokładnie stoi bez odpowiedzi]
+
+**P2. [...]**
+```
+
+- **Continuous numbering per issue**: scan existing comments for previous `## Pytania przed implementacją` sections and continue the numbering (P4, P5, ...). NEVER renumber existing questions — replies reference them by number.
+- **Reconciliation check before posting**: every **blocker** from 3b.1 maps to exactly one question (1:1); questions from the other three categories (tradeoffs, scope, assumptions) are allowed and must each trace back to a specific 3b.1 item. Fix mismatches before the post.
+
+#### 3b.4 — Status + assignee
+
+After posting the comment, call `mcp__linear__save_issue({ id, state: "Todo", assignee: <addressee> })` — status **Todo** (never In Progress; the task is explicitly waiting for a human). The addressee defaults to the **issue creator, taken from the `creator` field of the `mcp__linear__get_issue` response** (no extra user-lookup tool needed); overrides: interactively pick "Other" on the gate question and name the person, headless pass `--questions-assignee=<user>`. Then STOP: do NOT create subtasks, do NOT save `plan.md`; the status/assignee change lands on the invoked issue only. Print a short Polish summary listing the posted questions.
+
+#### 3b.5 — Re-run with answers
+
+When `/plan` runs again on an issue that carries a `## Pytania przed implementacją` comment:
+
+- **answers exist** (comments newer than the question comment): incorporate them — quote each decision in the plan's "Analiza" section — and continue the pipeline;
+- **unanswered**: interactive → tell the user and ask (wait / answer now in session / proceed with assumptions); `--auto --post-questions` → exit cleanly with an audit comment (`Pytania z <data> wciąż bez odpowiedzi — plan nie został wygenerowany.`); plain `--auto` → proceed with logged assumptions (Hard Rule 4).
+
 ### Step 4: Create Implementation Plan
 
 Structure the plan as follows:
@@ -218,12 +311,16 @@ This file is the source for the Linear attachment in Step 6 and is NOT deleted
 
 4. **State invariant on entry to Step 5**: the only path that reaches Step 5 is the explicit "Tak, zapisz plan do Linear" choice (or `--auto`). Treat plan content as final.
 
-### Step 5: Create Subtasks (if needed)
+### Step 5: Create Subtasks (M/L only)
+
+Runs only for tasks classified **M/L** in Step 3a, after plan approval (Step 4a), and only when the issue does not already have subtasks. Each subtask = one coherent, independently implementable slice mapped to a plan step ("Podzadania" table); imperative Polish title, short scope description; prefer 2–6 subtasks.
 
-For complex tasks, create subtasks in Linear:
+Mode behavior:
 
-- Use `mcp__linear__save_issue` with parent task ID
-- Each subtask should map to a plan step
+- **Interactive**: the subtask breakdown was part of the approved plan (Step 4a) — create each subtask via `mcp__linear__save_issue` (team and project inherited from the parent, state `Todo`, parent set to the invoked issue).
+- **`--auto --post-questions`**: create the subtasks automatically and list them in the audit comment — ONLY when no stakeholder questions block the task (Step 3b).
+- **`--auto` (plain)**: do NOT create subtasks — the decomposition stays inside `plan.md` as the "Podzadania" table. Issue structure stays untouched (Hard Rule 4).
+- **Small tasks**: skip this step entirely.
 
 ### Step 6: Save Plan as Native Linear Attachment
 
@@ -337,3 +434,4 @@ Uruchom `/impl [linearTaskId]` aby rozpocząć implementację.
 9. **Use Angular CLI commands** not Nx commands
 10. **Mtime rule is authoritative**: only regenerate `plan.md` when the attachment is missing or a comment is newer than `plan.md.updatedAt`. Keyword detection triggers an explicit user confirmation only.
 11. **Always add "AI Plan" label** after saving the `plan.md` attachment. The label is workspace-level and pre-configured organization-wide — do NOT create a team-scoped duplicate.
+12. **Ask for clarification**: for M/L tasks the Question Gate (Step 3b) is the mandatory mechanism — stakeholder questions go to Linear, not into silent assumptions; for Small tasks use an ad-hoc `AskUserQuestion` in interactive mode only (in any `--auto` mode adopt the safest assumption and log it — Hard Rule 4)

package/plugins/flow-legacy/.claude-plugin/plugin.json

@@ -1,5 +1,5 @@
 {
   "name": "flow-legacy",
   "description": "Development flow skills for legacy Angular 14 projects with Linear-driven workflow",
-  "version": "0.8.0"
+  "version": "0.10.0"
 }

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

@@ -1,6 +1,6 @@
 ---
 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.
+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. For medium/large tasks (more than 4-5 files, a new module), runs a Question Gate (open questions routed to Linear as a comment before implementation) and decomposes the issue into subtasks.
 allowed-tools:
   - Bash
   - Read
@@ -24,17 +24,19 @@ allowed-tools:
 
 # 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.
+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 invoked 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, and (b) the single token-usage comment posted in Step 9c. No other comment may carry plan content.
+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, (b) the single token-usage comment posted in Step 9c, (c) the `## Pytania przed implementacją` question comment posted by the Question Gate (Step 6d), and (d) the `--auto` audit comment (decision/assumption log in Polish). 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.
 
+5. **Plain `--auto` NEVER asks and NEVER mutates issue structure.** In `--auto` without `--post-questions`, the Question Gate posts no questions, no status or assignee is changed, and no subtasks are created — ambiguities become assumptions logged in the audit comment, and `plan.md` is ALWAYS produced. Headless callers (CI, benchmark) depend on this contract; breaking it silently corrupts automation.
+
 If any of these would be violated, stop and ask the user instead.
 
 ## Execution Checklist
@@ -50,13 +52,17 @@ Execute each step in order. Do not skip any step marked as MANDATORY.
 - [ ] **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
+- [ ] **10. Classify task size** — Small vs Medium/Large (Step 6c); only M/L triggers the Question Gate and decomposition
+- [ ] **11. Question Gate (M/L only)** — classify ambiguities and route stakeholder questions per mode (Step 6d); may STOP the task before planning (questions posted to Linear, status Todo, assignee set — interactive / `--post-questions` only; plain `--auto` logs assumptions instead, Hard Rule 5)
+- [ ] **12. Decompose (M/L only)** — create subtasks in Linear (interactive / `--post-questions`) or express decomposition inside `plan.md` (plain `--auto`) (Step 6e)
+- [ ] **13. Create implementation plans** — generate structured plans per task/subtask with all required sections, using Angular 14 patterns
+- [ ] **14. MANDATORY: Write plans in Polish** — all plan content must be in Polish language
+- [ ] **15. 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).
+- [ ] **16. 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)
+- [ ] **17. 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.
+- [ ] **18. MANDATORY: Add "AI Plan" label** — look up the workspace-level `AI Plan` label (never create it — Hard Rule 4) and apply it to the invoked issue (the `linearTaskId` passed to `/plan` — parent task or subtask, whichever was called)
+- [ ] **19. Post token-usage comment** — run the token-summing script and post the single usage comment on the invoked issue (Step 9c)
+- [ ] **20. Confirm to user** — list saved plans with summaries and Linear links
 
 ### Task Progress Tracking
 
@@ -115,13 +121,16 @@ You create plans that are:
 
 ```
 /plan [linearTaskId]
-/plan [linearTaskId] --auto    # Non-interactive mode for CI / GitHub Actions
+/plan [linearTaskId] --auto                    # Non-interactive mode for fully autonomous runs
+/plan [linearTaskId] --auto --post-questions   # Non-interactive mode for the automated Claude Code development process
 ```
 
 ## 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` - 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 runs where no human is at the keyboard. Without `--post-questions` this is the fully-autonomous contract: no questions posted, no status/assignee changes, no subtask creation, `plan.md` always produced (Hard Rule 5).
+- `--post-questions` - Modifier for `--auto` (ignored without it): headless runs of the Claude Code development process. Stakeholder ambiguities found by the Question Gate are posted to Linear automatically (question comment + status `Todo` + assignee = issue creator) and the task exits without `plan.md` — and without creating subtasks — until answers arrive. When no stakeholder questions block the task (none found, or all answered on a re-run), M/L tasks are decomposed into real Linear subtasks automatically.
+- `--questions-assignee=<user>` - Optional, only with `--auto --post-questions`: overrides the addressee of posted questions (name or email resolvable in Linear). Default: the issue creator. Useful when issues are created by an integration/bot account.
 
 ## Auto Mode (`--auto`)
 
@@ -133,11 +142,13 @@ You create plans that are:
 | 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 |
+| `AskUserQuestion` for any decision                                | Use the option marked **(Recommended)**. If none is marked: in plain `--auto` pick the safest option, log it in the audit comment, and continue — plain `--auto` may NEVER exit without `plan.md` (Hard Rule 5); the fail-fast-with-Linear-comment exit is allowed only with `--post-questions` |
+| Question Gate: stakeholder questions (Step 6d)                    | Plain `--auto`: never posted — adopt the safest assumption per question and log ALL of them in the audit comment. With `--post-questions`: post the question comment + status `Todo` + assignee automatically; the task exits without `plan.md` and without creating subtasks |
+| Decomposition: subtask creation (Step 6e)                         | Plain `--auto`: never — decomposition stays inside `plan.md` as phases. With `--post-questions`: subtasks created automatically (and listed in the audit comment) ONLY when no stakeholder questions block the task |
 
 **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.
+**Detection**: The flag `--auto` is provided as a positional/named arg. Treat any of `--auto`, `--ci`, `--non-interactive` as equivalent. Combinable with `--post-questions` (see Parameters).
 
 ## Angular 14 Legacy Patterns
 
@@ -163,7 +174,7 @@ When creating plans, always use these legacy patterns:
 
 ## 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.
+You are tasked with creating an implementation plan for a Linear task and saving it as a `plan.md` attachment in Linear (Hard Rule 1 — never as a comment). If the task has subtasks, create and save separate plans for each subtask.
 
 ### Step 1: Fetch Linear Task Details
 
@@ -320,6 +331,108 @@ Check if the task requires changes to external library packages:
 3. Update dependency version in this project
 4. Then implement the changes in this project that depend on the library updates
 
+### Step 6c: Task Size Classification
+
+Based on the findings from Steps 4–6a, classify the task as **Small** or **Medium/Large**:
+
+**Medium/Large (M/L)** if ANY of the following holds:
+
+- estimated affected files (modify + create) exceed **4–5**,
+- a **new module / package / domain area** is created,
+- the change spans **multiple layers or apps** (e.g. domain + backend + frontend),
+- the Linear estimate (if present) is M or higher.
+
+**Small** otherwise (isolated bugfix, copy change, single-component tweak).
+
+Routing:
+
+- **Small** → skip Steps 6d–6e entirely and continue with Step 7. Behavior is identical to the skill before the Question Gate existed.
+- **M/L** → run Step 6d (Question Gate), then Step 6e (Decomposition).
+- If the issue **already has subtasks**, treat decomposition as done: run Step 6d only, then continue with per-subtask planning as usual.
+
+State the classification and its trigger (e.g. `M/L — 9 plików, nowy moduł raportów`) in the chat (interactive) or in the audit comment (`--auto`).
+
+### Step 6d: Question Gate (M/L only)
+
+Surface ambiguities BEFORE the plan is written — key decisions should happen at the cheapest possible moment, and questions should travel to the person who can answer them instead of dying inside the session.
+
+#### 6d.1 — Collect and classify ambiguities
+
+Scan the task description, its comments, and your codebase findings for unknowns in four categories (one question = one category):
+
+1. **Blockers** — missing decisions or data without which the implementation would have to guess (e.g. which permission gates a view, where the data comes from)
+2. **Approach tradeoffs** — two or more viable designs with real consequences
+3. **Scope / priorities** — unclear boundaries ("does X belong to this task?")
+4. **Risky assumptions** — things you would otherwise assume silently
+
+**Never ask about anything checkable in the code, git history, or Linear** — check it instead. If there are NO ambiguities, note `brak pytań` and go straight to Step 6e.
+
+Split the resulting questions into:
+
+- **session-resolvable** — the operator at the keyboard can decide;
+- **stakeholder-needed** — requires product/data/another person. Default addressee: the **issue creator**.
+
+#### 6d.2 — Mode behavior
+
+| Mode                     | Session-resolvable                                                                                             | Stakeholder-needed                                                                                                                                          |
+| ------------------------ | -------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Interactive (default)    | one `AskUserQuestion` batch (1–4 questions, 2–4 disjoint options each, recommended option FIRST with "(Recommended)") | ask the developer first (gate below); on approval post the comment + status + assignee                                                                       |
+| `--auto --post-questions`| resolve with the recommended option; log in the audit comment                                                   | post the question comment + status **Todo** + assignee **automatically**; the task exits without `plan.md`; audit comment records what was posted            |
+| `--auto` (plain)         | resolve with the recommended option; log                                                                        | do NOT post; adopt the safest assumption per question; log ALL assumptions in the audit comment (`Założenia przyjęte automatycznie: ...`); `plan.md` ALWAYS produced |
+
+Interactive stakeholder gate — `AskUserQuestion`:
+
+> Wykryto N pytań wymagających odpowiedzi interesariusza. Dodać komentarz z pytaniami do `<linearTaskId>`, ustawić status Todo i przypisać do `<creator>`?
+
+- **"Tak, dodaj pytania i zmień status"** _(Recommended)_ — post per 6d.3–6d.4, then STOP for this task.
+- **"Nie — odpowiem teraz w sesji"** — ask the questions via `AskUserQuestion` batches and continue the pipeline.
+- **"Pomiń — przyjmij założenia"** — treat like plain `--auto` for these questions; record the assumptions in the plan's "Risks & Considerations" section.
+
+#### 6d.3 — Question comment format (Polish)
+
+Post ONE comment via `mcp__linear__save_comment`:
+
+```markdown
+## Pytania przed implementacją
+
+Odpowiedz pod tym komentarzem — wystarczy numer pytania i odpowiedź.
+
+**P1. [krótki tytuł]**
+[2–3 zdania kontekstu — samowystarczalne, bez ścieżek repo i żargonu wewnętrznego]
+Pytanie: [...]
+Blokuje: [co dokładnie stoi bez odpowiedzi]
+
+**P2. [...]**
+```
+
+- **Continuous numbering per issue**: scan existing comments for previous `## Pytania przed implementacją` sections and continue the numbering (P4, P5, ...). NEVER renumber existing questions — replies reference them by number.
+- **Reconciliation check before posting**: every **blocker** from 6d.1 maps to exactly one question (1:1); questions from the other three categories (tradeoffs, scope, assumptions) are allowed and must each trace back to a specific 6d.1 item. Fix mismatches before the post.
+
+#### 6d.4 — Status + assignee
+
+After posting the comment, call `mcp__linear__save_issue({ id, state: "Todo", assignee: <addressee> })` — status **Todo** (never In Progress; the task is explicitly waiting for a human). The addressee defaults to the **issue creator, taken from the `creator` field of the `mcp__linear__get_issue` response** (no extra user-lookup tool needed); overrides: interactively pick "Other" on the gate question and name the person, headless pass `--questions-assignee=<user>`. Then STOP: the halt covers the ENTIRE invoked issue — if it has subtasks, no `plan.md` is saved on any of them and no new subtasks are created; the status/assignee change lands on the invoked issue only. Print a short Polish summary listing the posted questions.
+
+#### 6d.5 — Re-run with answers
+
+When `/plan` runs again on an issue that carries a `## Pytania przed implementacją` comment:
+
+- **answers exist** (comments newer than the question comment): incorporate them — quote each decision in the plan's "Technical Analysis" or "Risks & Considerations" — and continue the pipeline;
+- **unanswered**: interactive → tell the user and ask (wait / answer now in session / proceed with assumptions); `--auto --post-questions` → exit cleanly with an audit comment (`Pytania z <data> wciąż bez odpowiedzi — plan nie został wygenerowany.`); plain `--auto` → proceed with logged assumptions (Hard Rule 5).
+
+### Step 6e: Decomposition into Subtasks (M/L only)
+
+Skip if the issue already has subtasks. Otherwise break the task into subtasks, each an independently implementable and reviewable unit:
+
+- each subtask = one coherent slice; layers (domain → BE/FE) live INSIDE a subtask, never as separate subtasks;
+- per subtask: imperative Polish title, 2–5-sentence description with scope + planned Files to Modify, and dependencies on other subtasks;
+- prefer 2–6 subtasks; merge any "subtask" smaller than roughly one file into a neighbor.
+
+Mode behavior:
+
+- **Interactive**: present the breakdown table (title, scope, files, depends-on) and ask via `AskUserQuestion`: `Utworzyć N podzadań w Linear?` with options **"Tak, utwórz podzadania"** _(Recommended)_ / **"Popraw podział"** (capture feedback, redo the breakdown) / **"Kontynuuj bez podzadań"** (single-task planning). On approval create each subtask via `mcp__linear__save_issue` (team and project inherited from the parent, state `Todo`, parent set to the invoked issue). Then continue with Step 7 using the "If subtasks exist" path.
+- **`--auto --post-questions`**: create the subtasks automatically and list them in the audit comment.
+- **`--auto` (plain)**: do NOT create subtasks — express the decomposition inside `plan.md` as phases in "Implementation Steps". Issue structure stays untouched (Hard Rule 5).
+
 ### Step 7: Create Implementation Plans
 
 #### If NO subtasks exist:
@@ -714,7 +827,7 @@ 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
+- Confirm `AI Plan` label added to the invoked issue
 - Provide Linear links
 
 ## Guidelines
@@ -725,7 +838,7 @@ After saving:
 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
+7. **Ask for clarification**: for M/L tasks the Question Gate (Step 6d) is the mandatory mechanism — stakeholder questions go to Linear, not into silent assumptions; for Small tasks keep the pre-existing behavior: an ad-hoc `AskUserQuestion` in interactive mode only (in any `--auto` mode adopt the safest assumption and log it — Hard Rule 5)
 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

package/plugins/smart-pro/.claude-plugin/plugin.json

@@ -1,5 +1,5 @@
 {
   "name": "smart-pro",
   "description": "Smart-pro integration - safety validation, audit logging, and auto-formatting hooks",
-  "version": "0.8.0"
+  "version": "0.10.0"
 }