@smartsoft001/pro-claude-plugins 0.2.0

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

@@ -0,0 +1,992 @@
+---
+name: impl
+description: Implement plans from `plan.md` attachments on Linear issues. Iteratively processes subtasks with TDD, UI classification, agent orchestration (saved as `orchestration.md` attachment), screenshot capture, and 3x3 rule checkpoints.
+allowed-tools:
+  - Bash
+  - Read
+  - Edit
+  - 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__list_issue_statuses
+  - mcp__linear__create_attachment
+  - mcp__linear__get_attachment
+  - mcp__linear__delete_attachment
+---
+
+# Implementation Skill
+
+Implement plans from `plan.md` attachments on Linear issues. For tasks with subtasks, iteratively implement each subtask that is in "To Do" status. The agent orchestration plan is saved as an `orchestration.md` attachment on each task being implemented.
+
+## 🚨 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. **Read `plan.md` ONLY via `mcp__linear__get_attachment({ id: <attachmentId> })`.** Do NOT use `WebFetch`, `Bash(curl ...)`, or any HTTP fetch on the attachment's `url`. The URL points to Linear-internal storage and may require auth — `get_attachment` is the only correct path. If you find yourself reaching for `curl` or `WebFetch` on a `https://uploads.linear.app/...` (or similar Linear) URL — STOP and use `get_attachment` with the attachment `id` instead.
+
+2. **`orchestration.md` is saved via `mcp__linear__create_attachment`, not as a comment.** Same rule as `/plan`: comments are NEVER used for plan/orchestration body content.
+
+3. **Find attachments via `mcp__linear__get_issue` (returns `attachments[]`).** Capture each attachment's `id` and `title`. There is no `list_attachments` tool — do not look for one.
+
+4. **Replace, don't duplicate.** Before creating a new `orchestration.md` attachment, delete the existing one (if any) via `mcp__linear__delete_attachment`. Same for re-running `/plan` (handled by `/plan` skill).
+
+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.
+
+### Initial Setup
+
+- [ ] **1. Fetch task and subtasks** — delegate to `shared-linear-subtask-iterator` agent
+
+### Per Subtask (repeat for each "To Do" subtask)
+
+- [ ] **2. Set status to "In Progress"** — update subtask status via MCP (subtasks only, not parent)
+- [ ] **3. Fetch implementation plan** — `mcp__linear__get_issue` to find `plan.md` attachment id, then `mcp__linear__get_attachment({ id })` to read content. **Do NOT use `WebFetch`/`curl` on the attachment URL.**
+- [ ] **4. MANDATORY: UI change classification** — delegate to `shared-ui-classifier` agent, output `UI_CHANGE_REQUIRED: YES/NO`
+- [ ] **5. MANDATORY: Agent orchestration plan** — delegate to `shared-impl-orchestrator`, save result as `orchestration.md` attachment via `mcp__linear__create_attachment` (replace any existing one). **Calling `mcp__linear__save_comment` with the orchestration body is FORBIDDEN.**
+- [ ] **6. Check external library blockers** — if blockers found, set status to Blocked and skip
+- [ ] **7. Capture "before" screenshots** — if `UI_CHANGE_REQUIRED: YES`, launch `screenshot-reporter` in background
+- [ ] **8. MANDATORY: Implement with 3x3 rule** — pause every 3 changes (skip pause in `--auto`, log checkpoint as Linear comment instead), use `shared-tdd-developer` for ALL code (RED → GREEN → REFACTOR)
+- [ ] **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
+- [ ] **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
+- [ ] **14. Update status** — delegate to `shared-linear-subtask-iterator` for status determination
+- [ ] **15. Agent evolution** — if user confirmed feedback, delegate to `shared-agent-evolver`
+- [ ] **16. Pause for user confirmation** — wait before proceeding to next subtask (skipped in `--auto`; post completion comment and continue)
+
+### Finalization
+
+- [ ] **17. Final summary** — present summary of all subtasks with statuses
+- [ ] **18. Session-wide evolution** — analyze all feedback across session
+- [ ] **19. ALWAYS pause** — wait for user confirmation at end (skipped in `--auto`; post final summary comment and exit)
+
+### 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 (parent or subtask):
+
+```
+<linearTaskId> <step description>
+```
+
+**At skill start**: Create tasks for the initial setup using `TaskCreate`:
+
+```
+TaskCreate({
+  subject: "MM-123 Fetch task and subtasks",
+  description: "Delegate to shared-linear-subtask-iterator agent",
+  activeForm: "MM-123 Fetching task and subtasks"
+})
+```
+
+**Per subtask**: Create a parent task for the subtask, then child tasks for each step — all prefixed with the subtask ID:
+
+```
+TaskCreate({
+  subject: "MM-123-1 Implement subtask",
+  description: "Full implementation cycle: classify → orchestrate → implement → verify",
+  activeForm: "MM-123-1 Implementing subtask"
+})
+TaskCreate({
+  subject: "MM-123-1 UI change classification",
+  description: "Delegate to shared-ui-classifier agent",
+  activeForm: "MM-123-1 Classifying UI changes"
+})
+TaskCreate({
+  subject: "MM-123-1 Verify implementation",
+  description: "Run tests, lint, build check",
+  activeForm: "MM-123-1 Verifying implementation"
+})
+```
+
+**During execution**:
+
+- Before starting a step → `TaskUpdate({ taskId, status: "in_progress" })`
+- After completing a step → `TaskUpdate({ taskId, status: "completed" })`
+- At 3x3 checkpoints → `TaskList` to show progress overview
+
+**At pause points**: Use `TaskList` to present a clear status summary to the user before waiting for confirmation.
+
+## Role
+
+**You are a highly experienced senior TypeScript developer** with:
+
+- Over 10 years of programming experience
+- **TypeScript expert** - advanced types, generics, decorators, type guards
+- **NestJS expert** - CQRS, modules, dependency injection, guards, interceptors, pipes
+- **Angular expert** - signals, standalone components, NgRx, RxJS, reactive forms
+- **Tailwind CSS expert** - utility-first approach, responsive design, custom configurations
+- Writing clean, readable, and well-tested code
+- Applying best practices and design patterns
+- Focus on performance and optimization
+- Understanding existing code and extending it without breaking conventions
+
+You implement code that is:
+
+- **Convention-compliant**: matches existing style and patterns in the project
+- **Well-typed**: full utilization of TypeScript's type system
+- **Testable**: easy to cover with unit tests
+- **Readable**: self-documenting with meaningful names
+- **Performant**: no unnecessary operations or re-renders
+
+## Usage
+
+```
+/impl [linearTaskId]
+/impl [linearTaskId] --team    # Agent Team mode (experimental)
+/impl [linearTaskId] --auto    # Non-interactive mode for CI / GitHub Actions
+```
+
+## Parameters
+
+- `linearTaskId` - Linear task ID (e.g., ENG-123)
+- `--team` - Enable parallel Implementation Squad mode (experimental, requires `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1`)
+- `--auto` - Non-interactive mode: skip ALL `AskUserQuestion` prompts, 3x3 checkpoint pauses, per-subtask pauses, and the final end pause. If `plan.md` attachment is missing, auto-invoke `/plan` flow to generate it instead of posting a "run /plan first" comment and skipping. 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                                                                                         |
+| -------------------------------------------------------- | --------------------------------------------------------------------------------------------------------- |
+| Post comment "no plan.md found, run /plan first" + skip  | Inline-invoke `/plan` flow for the task to generate `plan.md` attachment + `AI Plan` label, then continue |
+| 3x3 rule pauses every 3 changes asking "Continue?"       | Log the checkpoint summary as a status comment, then continue automatically                               |
+| Pause after each subtask waiting for user confirmation   | Post subtask completion comment, then proceed to next subtask                                             |
+| Final end pause "wait for user confirmation"             | Post final summary comment and exit cleanly                                                               |
+| `AskUserQuestion` for any decision                       | Use the option marked **(Recommended)**; if none, fail fast with a Linear comment explaining why          |
+| Confirmation before destructive ops (delete attachments) | Proceed without confirmation — replace old `orchestration.md` automatically                               |
+
+**Hard requirement in `--auto`**: every checkpoint, decision, or skip MUST be logged as a Linear comment in Polish so the run remains auditable after the fact. Comments replace the interactive prompts — they are the audit trail.
+
+**Detection**: The flag `--auto` is provided as a positional/named arg. Treat any of `--auto`, `--ci`, `--non-interactive` as equivalent. Combinable with `--team` (parallel squad mode runs without per-subtask approval).
+
+## Instructions
+
+You are tasked with implementing plans from `plan.md` attachments on Linear tasks. If the task has subtasks, you will iterate through subtasks in "To Do" status and implement them one by one. The agent orchestration plan is saved as an `orchestration.md` attachment on each task (not as a comment).
+
+### Step 1-2: Fetch Linear Task and Subtasks
+
+**Delegate to `shared-linear-subtask-iterator` agent:**
+
+```
+Action: fetch
+Linear Task ID: [linearTaskId]
+```
+
+The agent will:
+
+1. Fetch task details (title, description, status, labels)
+2. Check for subtasks and filter "To Do" status
+3. Return processing order and implementation plan location
+
+**Output:** Task structure with subtasks to process (or parent task if no subtasks)
+
+### Step 1b: Team Mode Decision (if --team flag provided)
+
+**Prerequisites**:
+
+- `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1` must be set
+- Task must have 2+ subtasks in "To Do" status
+- `--team` flag must be provided
+
+**If prerequisites NOT met** → Fall back to standard sequential mode (continue to Step 3).
+
+**If prerequisites met:**
+
+1. **Fetch all implementation plans** for all "To Do" subtasks (from Linear comments)
+
+2. **Delegate to `shared-subtask-dependency-analyzer`** with all subtask plans:
+
+   ```
+   Analyze dependencies for parallel implementation:
+   - Subtasks: [list of subtask IDs with titles]
+   - Plans: [files to modify/create per subtask]
+   ```
+
+3. **Review dependency analysis** — identify independent groups
+
+**If PARALLEL_ELIGIBLE: NO** (all subtasks share files or only 1 subtask):
+
+→ Fall back to sequential mode with message:
+
+```
+Subtaski mają współdzielone pliki — tryb sekwencyjny.
+```
+
+Continue to Step 3.
+
+**If PARALLEL_ELIGIBLE: YES:**
+
+4. **Create shared tasks** via TaskCreate for each subtask:
+
+   ```
+   [SQUAD] <parentTaskId>-<N> Implement subtask: [title]
+   ```
+
+   Set task dependencies using `TaskUpdate` with `addBlockedBy` for dependent groups.
+
+5. **Spawn teammates** — one `shared-impl-teammate` per independent group (max 4 teammates):
+
+   **Spawn prompt per teammate:**
+
+   ```
+   You are an Implementation Squad member working on subtask(s): [subtask IDs]
+
+   Linear Task: [parent task ID] - [title]
+   Your subtask(s): [subtask details with plans]
+
+   Follow the FULL per-subtask workflow:
+   - Set status to "In Progress"
+   - UI classification (shared-ui-classifier)
+   - Agent orchestration plan (shared-impl-orchestrator)
+   - Implement with TDD (shared-tdd-developer) — RED → GREEN → REFACTOR
+   - Verify (lint, tests, build)
+   - E2E tests (if UI)
+   - Screenshots (if UI) — before + after + post to Linear
+   - Create completion comment (shared-impl-reporter) — IN POLISH
+   - Update status
+
+   CRITICAL RULES:
+   - Do NOT modify files outside your assigned subtask scope
+   - Use shared-tdd-developer for ALL code implementation
+   - All Linear comments in Polish
+   - Mark task as completed when done
+   - Message the lead if you encounter blockers
+   ```
+
+6. **Monitor and coordinate**:
+
+   - Lead watches task completions via TaskList
+   - When dependent group becomes unblocked → spawn next wave of teammates
+   - Handle teammate errors: if teammate reports blocker, reassign or mark blocked
+
+7. **Synthesis after all teammates finish**:
+
+   - Collect all teammate reports
+   - Delegate to `shared-report-synthesizer` for final summary (team type: SQUAD)
+   - Post synthesized summary to parent Linear task
+   - Present final summary to user
+
+8. **Cleanup team** when all subtasks processed
+
+9. **Skip to Step 4** (Final Summary) — team mode bypasses the per-subtask sequential loop
+
+### Agent Team Mode (Experimental)
+
+**Prerequisite**: `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1` in settings.
+
+**Activation**: Add `--team` flag.
+
+**Fallback**: If env var not set or flag not provided, skill runs in standard sequential mode.
+
+### Step 3: Process Tasks Iteratively
+
+For each task to implement (subtasks in "To Do" status, or parent task if no subtasks):
+
+#### Step 3a: Set Status to "In Progress"
+
+**For subtasks only**: Use MCP Linear server to update the subtask status to "In Progress".
+
+Do NOT change status for parent tasks.
+
+#### Step 3b: Fetch Implementation Plan from `plan.md` Attachment
+
+**⛔ DO NOT use `WebFetch` or `Bash(curl)` on the attachment URL. Use `mcp__linear__get_attachment({ id })` only.** Re-read Hard Rule #1 if tempted.
+
+Two-step retrieval:
+
+1. `mcp__linear__get_issue({ id: taskId })` → response includes `attachments[]`. Find the entry where `title == "plan.md"` (or `filename == "plan.md"`) and capture its `id`. Do NOT use the `url` field for fetching.
+2. `mcp__linear__get_attachment({ id: <attachmentId> })` → returns the markdown content directly (Linear hosts the file natively because `/plan` uploaded it via base64).
+
+Parse the markdown for:
+
+- Implementation Steps
+- Files to Modify
+- New Files to create
+- Testing Strategy
+- External Library Changes (if any — these are blockers, not to be implemented)
+
+**If no `plan.md` attachment found**:
+
+- **Default mode**: Create a comment noting that no plan was found, suggest running `/plan <taskId>` first, and skip this task. Set status back to "To Do".
+- **`--auto` mode**: Inline-invoke the `/plan` skill flow for this task to generate `plan.md` attachment + `AI Plan` label, then proceed with implementation. Post a comment in Polish noting the plan was auto-generated. Do NOT skip the task.
+
+Do NOT fall back to reading plan content from comments — the attachment is the source of truth.
+
+#### Step 3b-classify: MANDATORY UI Change Classification
+
+**⚠️ CRITICAL - THIS STEP IS MANDATORY AND CANNOT BE SKIPPED**
+
+**Delegate to `shared-ui-classifier` agent:**
+
+```
+Task ID: [current task/subtask ID]
+Task Title: [title]
+Implementation Plan: [files to modify and steps summary]
+```
+
+The agent will:
+
+1. Analyze file extensions and paths
+2. Check for UI-related keywords
+3. Generate `🎯 Change Type Classification` block
+4. Determine if screenshots are required
+
+**Output:** Classification with `UI_CHANGE_REQUIRED: YES/NO` and Screenshot Plan if needed
+
+**If UI_CHANGE_REQUIRED: YES** → You MUST capture screenshots.
+**If UI_CHANGE_REQUIRED: NO** → Screenshots are skipped.
+
+#### Step 3b-orchestrate: MANDATORY Agent Orchestration Plan
+
+**⚠️ CRITICAL - THIS STEP IS MANDATORY AND CANNOT BE SKIPPED**
+
+Before starting implementation, you MUST create an **Agent Orchestration Plan**.
+
+**Delegate to `shared-impl-orchestrator` agent:**
+
+```
+Create orchestration plan for:
+- Linear Task ID: [current task/subtask ID]
+- Task Title: [title from Linear]
+- Implementation Plan: [summary of files to modify and steps]
+```
+
+The agent will:
+
+1. Analyze the implementation plan
+2. Identify required agents based on task type
+3. Define execution order (parallel vs sequential)
+4. Plan TDD cycles for each implementation unit
+5. Generate the orchestration plan in markdown format
+
+**After receiving the orchestration plan, save it as a native `orchestration.md` attachment on the Linear issue.**
+
+**⛔ Calling `mcp__linear__save_comment` with the orchestration body is FORBIDDEN. Use `mcp__linear__create_attachment` only.** Re-read Hard Rule #2 if tempted.
+
+1. **Check for existing `orchestration.md` attachment** on the task via `mcp__linear__get_issue` (the response includes an `attachments` array).
+   - If one exists, delete it via `mcp__linear__delete_attachment({ id: oldAttachmentId })`. Linear hosts the file natively, so nothing else needs cleanup.
+2. **Write locally**: use `Write` to save the orchestration markdown to `/tmp/claude-plans/<taskId>-orchestration.md`.
+3. **Base64-encode**: `b64=$(base64 -i /tmp/claude-plans/<taskId>-orchestration.md)`.
+4. **Create Linear attachment** via `mcp__linear__create_attachment`:
+   - `issue`: the task/subtask ID
+   - `filename`: `orchestration.md`
+   - `contentType`: `text/markdown`
+   - `title`: `orchestration.md` (exact — used for detection/replacement on the next `/impl` run)
+   - `subtitle`: `Plan orkiestracji wygenerowany przez Claude Code`
+   - `base64Content`: the base64 string from step 3
+5. **Clean up** the local `/tmp/claude-plans/<taskId>-orchestration.md` file after a successful attachment.
+6. **Follow the plan** — execute agents in the defined order.
+7. **Use TDD strictly** — `shared-tdd-developer` is MANDATORY for ALL code implementation.
+
+**IMPORTANT**:
+
+1. **`shared-tdd-developer` is MANDATORY** for ALL code implementation tasks
+2. Save the orchestration plan as an `orchestration.md` attachment on the Linear task BEFORE starting implementation — do NOT post it as a comment
+3. Follow the TDD cycle (RED → GREEN → REFACTOR) strictly
+4. Each code change must have a failing test FIRST
+
+#### Step 3c: Check for External Library Blockers
+
+If the plan contains **External Library Changes** section with uncompleted items:
+
+- These are blockers that must be resolved first
+- Create a comment noting the blockers
+- Set status to "Blocked" or back to "To Do"
+- Skip to next subtask
+
+#### Step 3c-visual-before: Capture "Before" Screenshots (MANDATORY for UI changes)
+
+**⚠️ CONDITIONAL ON CLASSIFICATION: Execute this step ONLY IF `UI_CHANGE_REQUIRED: YES` from Step 3b-classify**
+
+**If UI_CHANGE_REQUIRED: NO** → Skip to Step 3d.
+
+**If UI_CHANGE_REQUIRED: YES** → This step is **MANDATORY**. You CANNOT proceed without capturing "before" screenshots.
+
+**IMPORTANT**: Before making any code changes, capture screenshots of the current state to document the "before" state.
+
+**Screenshot capture process:**
+
+**Delegate to `screenshot-reporter` agent** (run in background for parallel execution):
+
+```
+Capture "before" screenshots for:
+- Page: /[page from Screenshot Plan in Step 3b-classify]
+- Viewports: desktop (1920x1080), mobile (375x667)
+- Modes: normal, dark (high contrast)
+- Phase: before
+- Linear Issue ID: [current task/subtask ID]
+```
+
+The agent will:
+
+1. Use `browser-capture` skill to ensure dev server is running
+2. Navigate to affected page
+3. Capture 4 screenshots: desktop normal, desktop dark, mobile normal, mobile dark
+4. Upload via `maia-files-upload` skill
+5. Return screenshot IDs and URLs
+
+**IMPORTANT**: Launch the `screenshot-reporter` agent in the background using `run_in_background: true`. This allows implementation to proceed in parallel while screenshots are being captured and uploaded.
+
+**Store the agent task ID** - you will need it for Step 3e-visual-after.
+
+**Update Screenshot Plan status:**
+
+```markdown
+### Screenshot Plan
+
+- Page(s) to capture: [pages]
+- Before screenshots: ✅ LAUNCHED (Task ID: [task_id])
+- After screenshots: PENDING
+```
+
+#### Step 3d: Implement the Plan (with 3x3 Rule)
+
+Follow the implementation steps from the plan, applying the **3x3 Rule**:
+
+**3x3 Rule**: After every 3 changes (file modifications, new files, or significant code changes), STOP and:
+
+1. Summarize what was completed in the last 3 changes
+2. Present the next 3 planned steps
+3. Wait for user confirmation before continuing
+
+This ensures:
+
+- User stays informed about progress
+- Mistakes are caught early
+- User can adjust direction if needed
+
+**Implementation flow:**
+
+1. **Read existing files** that need modification
+2. **Implement changes** according to the plan
+3. **Create new files** as specified
+4. **After every 3 changes** → PAUSE for 3x3 checkpoint
+5. **Run tests** as specified in Testing Strategy
+6. **Fix any issues** that arise during implementation
+
+Use tools:
+
+- `Read` to read existing files
+- `Edit` to modify files
+- `Write` to create new files
+- `Bash` to run tests and commands
+- `Glob` and `Grep` for additional exploration if needed
+
+**3x3 Checkpoint Format:**
+
+```markdown
+## Checkpoint (3x3)
+
+### Completed (last 3 changes)
+
+1. ✅ [Change 1 description] - `path/to/file1.ts`
+2. ✅ [Change 2 description] - `path/to/file2.ts`
+3. ✅ [Change 3 description] - `path/to/file3.ts`
+
+### Next 3 Steps
+
+1. [ ] [Next step 1]
+2. [ ] [Next step 2]
+3. [ ] [Next step 3]
+
+### Progress
+
+- Steps completed: X / Y
+- Remaining: Z steps
+
+Continue? (yes/no/adjust)
+```
+
+**Feedback Collection for Agent Evolution:**
+
+During 3x3 checkpoints, when the user provides corrections or suggestions about coding patterns, implementation approach, or agent behavior — **ASK the user explicitly** if they want to create a Linear issue for the improvement.
+
+**When user provides a correction or pattern suggestion, ASK:**
+
+```
+🔄 Detected potential improvement suggestion:
+"[summary of user's correction]"
+
+Would you like to create a Linear issue for this pattern improvement?
+- Yes - File as Linear issue in "Framework 2.0"
+- No - Note for this session only
+- Skip - Ignore this feedback
+```
+
+**Only feedback confirmed with "Yes"** should be collected as **evolution feedback items** and processed in Step 3g-evolve via `linear-suggestion` skill.
+
+Look for signals like: universal language ("always", "never"), pattern-level corrections, or explicit requests to update agent behavior.
+
+**IMPORTANT**: Also STOP and wait for user confirmation:
+
+- After completing each subtask (before moving to next)
+- After completing the entire task
+- When encountering unexpected issues or blockers
+
+#### Step 3e: Verify Implementation
+
+After implementing:
+
+1. **Run relevant tests**: Execute tests mentioned in the Testing Strategy
+2. **Run linting**: `nx lint` for affected projects
+3. **Build check**: Verify build doesn't break
+4. **Manual verification**: Check if implementation matches requirements
+
+#### Step 3e-e2e: E2E Tests (Conditional on E2E_TESTS_RECOMMENDED)
+
+**⚠️ CONDITIONAL ON CLASSIFICATION: Execute this step ONLY IF `E2E_TESTS_RECOMMENDED: YES` from Step 3b-classify**
+
+**If E2E_TESTS_RECOMMENDED: NO** → Skip to Step 3e-visual-after.
+
+**If E2E_TESTS_RECOMMENDED: YES** → Delegate to `test-e2e` skill:
+
+```
+/test-e2e [changed component files from implementation]
+```
+
+The skill will:
+
+1. Ensure E2E project exists (scaffold if missing)
+2. Inject `data-testid` attributes on changed component templates
+3. Write Page Objects and test specs with screenshot capture
+4. Run E2E tests to verify they pass
+
+**If E2E tests fail:** Fix issues before proceeding. Delegate back to `e2e-test-writer` if needed.
+
+**After E2E tests pass:** Continue to Step 3e-visual-after.
+
+#### Step 3e-visual-after: Capture "After" Screenshots (MANDATORY for UI changes)
+
+**⚠️ CONDITIONAL ON CLASSIFICATION: Execute this step ONLY IF `UI_CHANGE_REQUIRED: YES` from Step 3b-classify**
+
+**If UI_CHANGE_REQUIRED: NO** → Skip to Step 3f-verify.
+
+**If UI_CHANGE_REQUIRED: YES** → This step is **MANDATORY**. You CANNOT complete the task without capturing "after" screenshots.
+
+**Before capturing "after" screenshots:**
+
+1. **Wait for "before" screenshots** to complete (retrieve from background task)
+2. Retrieve "before" screenshot IDs from the background task result
+
+**Screenshot capture process:**
+
+**Delegate to `screenshot-reporter` agent**:
+
+```
+Capture "after" screenshots and post to Linear:
+- Linear Issue ID: [current task/subtask ID]
+- Page: /[page from Screenshot Plan in Step 3b-classify]
+- Viewports: desktop (1920x1080), mobile (375x667)
+- Modes: normal, dark (high contrast)
+- Phase: after
+- Before IDs: [IDs from "before" phase result]
+- Generate comparison report
+- Post to Linear as comment
+- Cleanup all files (before + after)
+```
+
+The agent will:
+
+1. Use `browser-capture` skill to ensure dev server is running
+2. Navigate to affected page
+3. Capture 4 screenshots: desktop normal, desktop dark, mobile normal, mobile dark
+4. Upload via `maia-files-upload` skill
+5. Generate comparison report with "before" screenshots
+6. Post the screenshot comparison as a comment to the Linear issue
+7. Clean up all uploaded files from the API
+
+**Update Screenshot Plan status:**
+
+```markdown
+### Screenshot Plan
+
+- Page(s) to capture: [pages]
+- Before screenshots: ✅ COMPLETED
+- After screenshots: ✅ COMPLETED & POSTED TO LINEAR
+```
+
+#### Step 3f-verify: MANDATORY Screenshot Verification Checkpoint
+
+**⚠️ THIS VERIFICATION CANNOT BE SKIPPED**
+
+Before creating the completion comment, verify the screenshot requirement:
+
+```markdown
+## 📸 Screenshot Verification
+
+**UI_CHANGE_REQUIRED**: [YES / NO] (from Step 3b-classify)
+
+### Verification Result
+
+**If UI_CHANGE_REQUIRED: YES:**
+
+- [ ] Before screenshots captured: [YES with Task ID / NO - BLOCKER]
+- [ ] After screenshots captured: [YES / NO - BLOCKER]
+- [ ] Screenshots posted to Linear: [YES / NO - BLOCKER]
+
+**If UI_CHANGE_REQUIRED: NO:**
+
+- [x] Screenshots not required (reason: [backend-only / config-only / test-only])
+
+### Status
+
+**SCREENSHOT_REQUIREMENT_MET: [YES / NO]**
+```
+
+**⛔ BLOCKER**: If `UI_CHANGE_REQUIRED: YES` but screenshots were not captured:
+
+1. **DO NOT proceed** to completion comment
+2. **GO BACK** to Step 3c-visual-before or Step 3e-visual-after
+3. **Capture missing screenshots** before continuing
+
+**✅ PASS**: Only proceed to Step 3f if `SCREENSHOT_REQUIREMENT_MET: YES`
+
+#### Step 3f: Create Completion Comment
+
+**Delegate to `shared-impl-reporter` agent:**
+
+```
+Task ID: [current task/subtask ID]
+Task Title: [title]
+Status: [Completed / Partially Completed / Blocked / Skipped]
+Completed Items: [list of completed items]
+Not Completed Items: [list with reasons, if any]
+Files Modified: [list with descriptions]
+Files Created: [list with purposes]
+Test Results: [unit/e2e status]
+Translations: [changed keys if any]
+Notes: [additional notes]
+Blocker Info: [if blocked]
+```
+
+The agent will generate a formatted Implementation Report and return it.
+
+**Post the report** as a comment on the Linear task/subtask.
+
+#### Step 3g: Update Status
+
+**Delegate to `shared-linear-subtask-iterator` agent:**
+
+```
+Action: update-status
+Subtask ID: [current subtask ID]
+Implementation Result: [Completed / Partial / Blocked]
+Test Results: [Pass / Fail]
+```
+
+The agent will determine the correct status and provide MCP command to execute.
+
+**Execute the status update** via MCP Linear server.
+
+#### Step 3g-evolve: Agent Evolution Checkpoint
+
+**Prerequisites**: Only execute this step if user confirmed at least one feedback item with "Yes" during 3x3 checkpoints.
+
+**Delegate to `shared-agent-evolver` agent:**
+
+```
+Analyze feedback from current subtask implementation:
+- Subtask ID: [current subtask ID]
+- User-confirmed corrections: [list of feedback items where user answered "Yes"]
+- Files that were implemented: [list of files modified/created]
+- Patterns the user corrected or suggested: [specific corrections]
+```
+
+The agent will:
+
+1. Classify each feedback item (IGNORE / EVOLVE_PATTERN / EVOLVE_RULE / EVOLVE_TEMPLATE / CREATE_AGENT / UPDATE_WORKFLOW)
+2. Generate proposals for non-IGNORE items
+3. File each proposal as a Linear issue in "Framework 2.0" via `linear-suggestion` skill
+4. Return Evolution Report with created issue IDs
+
+**IMPORTANT**:
+
+- Agent files are NOT modified directly — proposals are filed as Linear issues for manual review
+- **Only process feedback explicitly confirmed by user** — do not auto-collect without asking
+- If no user-confirmed feedback was collected during this subtask, skip this step
+- This step runs BEFORE the subtask pause (Step 3h) so evolution is complete before moving on
+- If Linear issue creation fails, continue silently — do not block the workflow
+
+#### Step 3h: Pause After Subtask Completion
+
+**Delegate to `shared-linear-subtask-iterator` agent:**
+
+```
+Action: get-next-subtask
+Current Subtask ID: [just completed]
+Completed Subtasks: [list of completed IDs]
+```
+
+The agent will provide:
+
+- Completion summary for current subtask
+- Next subtask details (if any)
+- Pause point for user confirmation
+
+**IMPORTANT**:
+
+- **Default mode**: ALWAYS wait for user confirmation before proceeding to next subtask.
+- **`--auto` mode**: Skip the wait. The completion comment from Step 3f is the audit trail; proceed directly to Step 3i.
+
+#### Step 3i: Move to Next Subtask
+
+Only after user confirms, repeat from Step 3a for the next subtask returned by the iterator.
+
+### Step 4: Final Summary and Pause
+
+**Delegate to `shared-linear-subtask-iterator` agent:**
+
+```
+Action: get-next-subtask
+Current Subtask ID: [last completed]
+Completed Subtasks: [all completed IDs]
+```
+
+When all subtasks are processed, the agent will return `🏁 Iteration Complete` with:
+
+- Final summary table of all subtasks and their statuses
+- Statistics (completed, partial, blocked)
+- Recommendations for follow-up
+
+**IMPORTANT**:
+
+- **Default mode**: ALWAYS pause and present the final summary to the user.
+- **`--auto` mode**: Post the final summary as a Linear comment in Polish on the parent task (or invoked task) and exit cleanly without pausing.
+
+### Step 4a: Session-Wide Agent Evolution
+
+After the final summary, perform a session-wide analysis for agent improvements.
+
+**Delegate to `shared-agent-evolver` agent:**
+
+```
+Session-wide evolution analysis:
+- All subtasks processed: [list of subtask IDs]
+- All user corrections across session: [aggregated feedback]
+- Recurring patterns: [patterns that appeared in multiple subtasks]
+- Implementation friction points: [areas where agents underperformed]
+```
+
+The agent will:
+
+1. Analyze all feedback from the entire session (not just last subtask)
+2. Identify recurring patterns that may have been missed per-subtask
+3. Propose cross-cutting improvements (patterns spanning multiple agents)
+4. File proposals as Linear issues in "Framework 2.0" via `linear-suggestion` skill
+5. Return final Evolution Report with created issue IDs
+
+**IMPORTANT**: This step catches improvements that only become visible across multiple subtasks. Skip if no actionable feedback exists.
+
+### Step 5: Cleanup Screenshots from API
+
+**Note**: Screenshot cleanup is now handled automatically by the `screenshot-reporter` agent as part of its workflow. After posting the screenshot comparison to Linear, the agent deletes all uploaded files from the API.
+
+**If using manual screenshot workflow** (not delegating to `screenshot-reporter`):
+
+1. **Collect all screenshot IDs** that were uploaded during implementation (both "before" and "after" screenshots)
+
+2. **Delete screenshots using `maia-files-delete` skill**:
+   - Delegate file deletion with all collected IDs
+
+**Note**: Screenshots are already embedded in Linear comments, so they will remain visible there. The API cleanup only removes the temporary storage.
+
+## Status Flow
+
+```
+To Do → In Progress → In Review (if completed)
+                   → To Do (if not completed)
+                   → Blocked (if external blockers)
+```
+
+## Pause Points (3x3 Rule)
+
+**ALWAYS stop and wait for user confirmation at these points** (skipped in `--auto` — see overrides):
+
+| Pause Point          | When                                | What to Show                              | `--auto` behavior                                             |
+| -------------------- | ----------------------------------- | ----------------------------------------- | ------------------------------------------------------------- |
+| **3x3 Checkpoint**   | After every 3 changes               | Summary of 3 changes + next 3 steps       | Post checkpoint as Linear comment, continue                   |
+| **Subtask Complete** | After finishing each subtask        | Subtask summary + next subtask info       | Post completion comment, continue to next subtask             |
+| **Task Complete**    | After finishing all subtasks        | Final summary with all results            | Post final summary comment, exit                              |
+| **Blocker Found**    | When external dependency found      | Blocker details + options                 | Set status to Blocked, post blocker comment, skip subtask     |
+| **Error/Issue**      | When unexpected problem occurs      | Error details + proposed solution         | Post error comment to Linear, fail the run with non-zero exit |
+| **Agent Evolution**  | After subtask / after final summary | Evolution report with filed Linear issues | Skip evolution prompt, file issues silently if any            |
+
+**In default mode, never proceed automatically** - always wait for explicit user confirmation before:
+
+- Continuing after 3x3 checkpoint
+- Moving to next subtask
+- Finishing the implementation session
+
+## Orchestration Principles
+
+This command follows orchestration patterns for efficient, reliable implementation.
+
+### Core Principles
+
+1. **Single Responsibility**: Each agent/task has ONE clear responsibility
+2. **Delegation Over Execution**: Delegate specialized tasks to appropriate agents
+3. **Automatic Progression**: Workflow advances automatically (pausing only at defined checkpoints)
+
+### Workflow Pattern
+
+```
+Classify → Orchestrate → Capture Before → Implement (TDD) → Verify → [E2E Tests] → Capture After → Evolve → Complete
+```
+
+### Agent Orchestration
+
+**⚠️ MANDATORY: Use `shared-impl-orchestrator` agent to create execution plan**
+
+The orchestrator agent handles:
+
+- Identifying required agents based on task type
+- Defining execution order (parallel vs sequential)
+- Planning TDD cycles for implementation
+- Generating the orchestration plan for Linear
+
+See `shared-impl-orchestrator` agent for full agent delegation matrix and execution patterns.
+
+### Key Rules
+
+1. **`shared-tdd-developer` is MANDATORY** for ALL code implementation
+2. **Save orchestration plan as `orchestration.md` attachment** on the Linear issue before starting implementation (not as a comment)
+3. **Follow TDD strictly** - RED → GREEN → REFACTOR cycle
+
+### Verification Pipeline
+
+Delegate comprehensive verification to `shared-verification-orchestrator` agent, which runs:
+
+1. Fast Feedback (lint + type-check) - PARALLEL
+2. Unit Testing + Coverage - SEQUENTIAL
+3. Build Verification - SEQUENTIAL
+4. E2E Testing (if applicable) - PARALLEL
+5. Performance Validation - ADVISORY
+
+### Error Recovery
+
+When verification fails, delegate to appropriate fix agent:
+
+| Failure Type  | Delegate To                |
+| ------------- | -------------------------- |
+| Lint errors   | shared-style-enforcer      |
+| Type errors   | shared-logic-implementer   |
+| Test failures | shared-test-fixer          |
+| Build errors  | shared-logic-implementer   |
+| E2E failures  | angular-test-diagnostician |
+
+## Guidelines
+
+1. **⚠️ MANDATORY: Classify UI changes first**: Before ANY implementation, output the `🎯 Change Type Classification` block with explicit `UI_CHANGE_REQUIRED: YES/NO` decision
+2. **⚠️ MANDATORY: Create Agent Orchestration Plan**: Before implementation, generate `🎭 Agent Orchestration Plan` and save it as an `orchestration.md` attachment on the Linear task (replacing any existing one). Do NOT post orchestration as a comment.
+3. **⚠️ MANDATORY: Use `shared-tdd-developer` for ALL code**: Every code implementation MUST use the `shared-tdd-developer` agent following strict TDD (RED → GREEN → REFACTOR)
+4. **⚠️ MANDATORY: Verify screenshots before completion**: Always output `📸 Screenshot Verification` block before creating completion comment - task CANNOT be completed if UI change detected but screenshots missing
+5. **Write comments in Polish**: All implementation reports must be written in Polish language
+6. **Follow the 3x3 Rule**: After every 3 changes, STOP and summarize progress + next 3 steps
+7. **Pause after each subtask**: Always wait for user confirmation before moving to next subtask
+8. **Pause after task completion**: Always wait for user confirmation after completing entire task
+9. **Process one subtask at a time**: Complete one subtask before moving to the next
+10. **Always create completion comments**: Document what was done even if partially completed
+11. **Don't modify parent task status**: Only subtask statuses should be changed
+12. **Respect external library blockers**: Don't try to implement changes that require library updates
+13. **Run tests before marking complete**: Ensure tests pass before setting "In Review" status
+14. **Be thorough in reports**: Document exactly what was changed and any issues encountered
+15. **Follow existing patterns**: Match the codebase conventions when implementing
+16. **Commit changes**: After each subtask implementation, consider if a commit is needed
+17. **Ask for clarification**: If implementation plan is unclear, ask before proceeding
+18. **Use `screenshot-reporter` agent for UI changes**: Delegate all screenshot operations (capture, upload, Linear comment, cleanup) to the `screenshot-reporter` agent
+19. **Capture before screenshots in background**: Launch `screenshot-reporter` agent with `run_in_background: true` BEFORE implementing UI changes to capture "before" state while implementation proceeds
+20. **Capture after screenshots + post to Linear**: After implementation, launch `screenshot-reporter` agent to capture "after" screenshots, generate comparison report, post to Linear, and cleanup
+21. **Document translations changes**: If `apps/web/public/translations.json` was modified, include a table with added/changed translation keys and their PL/EN values in the Implementation Report
+22. **Capture screenshots in both modes**: Agent captures screenshots in BOTH normal mode and dark mode (high contrast) for complete visual documentation
+23. **Ask before collecting feedback for agent evolution**: When user provides corrections or suggestions during implementation, **explicitly ask** if they want to create a Linear issue for the improvement. Only user-confirmed feedback (answered "Yes") should be processed at evolution checkpoints (Step 3g-evolve, Step 4a) via `shared-agent-evolver` agent.
+24. **Never modify agent files directly during implementation**: The `shared-agent-evolver` agent files all proposals as Linear issues for manual review — it does NOT modify agent, command, or skill files directly.
+25. **Team mode file isolation**: In `--team` mode, each teammate MUST only modify files listed in their assigned subtask's implementation plan. Before editing any file, verify it is in scope. If an out-of-scope file needs changes, message the lead instead of editing directly.
+
+## Example Flow
+
+### Task: ENG-456 with 3 subtasks
+
+**Initial state:**
+
+- ENG-456-1: To Do
+- ENG-456-2: To Do
+- ENG-456-3: To Do
+
+**Processing ENG-456-1 (UI change - avatar upload):**
+
+1. Set status: To Do → In Progress
+2. Download `plan.md` attachment from the task
+3. **🎯 CLASSIFY**: Output classification block → `UI_CHANGE_REQUIRED: YES` (modifies `.component.ts`)
+4. **📸 BEFORE**: Launch `screenshot-reporter` agent in background (Task ID: abc123)
+5. Implement avatar upload feature (in parallel with screenshot capture)
+6. Run tests - all pass
+7. **📸 AFTER**: Launch `screenshot-reporter` agent for "AFTER" screenshots + post to Linear
+8. **📸 VERIFY**: Confirm `SCREENSHOT_REQUIREMENT_MET: YES`
+9. Create Implementation Report comment
+10. Set status: In Progress → In Review
+11. **EVOLVE**: User corrected error handling pattern → filed Linear issue FRA-820 proposing pattern addition to `shared-error-handler`
+
+**Processing ENG-456-2 (blocked):**
+
+1. Set status: To Do → In Progress
+2. Download `plan.md` attachment from the task
+3. **🎯 CLASSIFY**: Output classification block → `UI_CHANGE_REQUIRED: YES`
+4. Plan has External Library Changes blocker
+5. Create comment noting blocker (screenshots not needed - blocked before implementation)
+6. Set status: In Progress → Blocked
+
+**Processing ENG-456-3 (backend-only - social links API):**
+
+1. Set status: To Do → In Progress
+2. Download `plan.md` attachment from the task
+3. **🎯 CLASSIFY**: Output classification block → `UI_CHANGE_REQUIRED: NO` (only `.service.ts` files)
+4. Implement social links service
+5. Run tests - 1 test fails
+6. Fix the failing test
+7. Run tests again - all pass
+8. **📸 VERIFY**: Confirm `SCREENSHOT_REQUIREMENT_MET: YES` (screenshots not required)
+9. Create completion comment
+10. Set status: In Progress → In Review
+11. **EVOLVE**: No reusable feedback collected → skip evolution
+
+**Final state:**
+
+- ENG-456-1: In Review
+- ENG-456-2: Blocked
+- ENG-456-3: In Review
+
+**Note**: Screenshot cleanup was handled automatically by `screenshot-reporter` agent after posting to Linear.
+
+## Handling Edge Cases
+
+Edge cases (No Plan Found, External Library Blocker, Partial Implementation) are handled by the `shared-impl-reporter` agent, which generates appropriate reports for each scenario.
+
+**Key edge cases:**
+
+| Scenario           | Status  | Agent Action                                                       |
+| ------------------ | ------- | ------------------------------------------------------------------ |
+| No plan found      | Skipped | Generate "Skipped" report with recommendation to run `/plan-local` |
+| External blocker   | Blocked | Generate "Blocked" report listing required library changes         |
+| Partial completion | To Do   | Generate "Partially Completed" report with remaining items         |
+
+---
+
+**Important**: Always confirm with the user before starting implementation if there are any questions about the plan.