feat: improved the Claude Kit as a plugin

2026-06-14 14:14:53 +03:00 · 2026-04-19 14:09:14 +07:00
parent 3103a8da1b
commit d1a6d2a2bc
186 changed files with 771 additions and 1691 deletions
@@ -0,0 +1,329 @@
+---
+name: dispatching-parallel-agents
+description: >
+  Use when facing 3 or more independent failures across different domains, when multiple subsystems are broken with no shared state, or when test failures span unrelated modules. Also activate whenever you see independent bugs in auth, cart, user, or other separate domains that can be fixed concurrently. Use for launching parallel background tasks like research, analysis, or code review across independent areas. Activate aggressively for any scenario where parallel work would reduce total resolution time without creating merge conflicts.
+---
+
+# Dispatching Parallel Agents
+
+## When to Use
+
+- Multiple subsystems broken independently
+- No shared state between failures
+- Each fix is self-contained
+- Parallel work won't create conflicts
+
+## When NOT to Use
+
+- Tasks with shared state or sequential dependencies where one fix affects another
+- Single-file changes that don't benefit from parallelization overhead
+- Sequential workflows where each step depends on the output of the previous step
+
+---
+
+## Core Principle
+
+**"Dispatch one agent per independent problem domain. Let them work concurrently."**
+
+### Why Parallel?
+
+- Faster resolution (3 problems in time of 1)
+- Focused context per agent
+- No context pollution between fixes
+- Easy to integrate results
+
+### Why Not Always Parallel?
+
+- Related problems need shared context
+- Exploration requires system-wide view
+- Conflicting changes cause merge issues
+- Some fixes depend on others
+
+---
+
+## Identification Pattern
+
+### Step 1: Group Failures by Domain
+
+```markdown
+Test failures:
+- src/auth/login.test.ts (3 failures) → Auth domain
+- src/cart/checkout.test.ts (2 failures) → Cart domain
+- src/user/profile.test.ts (1 failure) → User domain
+
+Each is independent - fixing one doesn't affect others.
+```
+
+### Step 2: Verify Independence
+
+```markdown
+Ask for each group:
+- Does it share state with other groups? NO
+- Does fixing it require changes to other groups? NO
+- Could fixes conflict with each other? NO
+
+If all NO → Parallel is safe
+If any YES → Sequential or combined approach
+```
+
+---
+
+## Task Creation Pattern
+
+Each agent receives:
+
+### 1. Specific Scope
+
+```markdown
+BAD: "Fix all the tests"
+GOOD: "Fix auth/login.test.ts - 3 failing tests"
+```
+
+### 2. Clear Goal
+
+```markdown
+BAD: "Make it work"
+GOOD: "Make all tests in auth/login.test.ts pass"
+```
+
+### 3. Constraints
+
+```markdown
+- Only modify files in src/auth/
+- Don't change the test expectations
+- Don't modify shared utilities
+```
+
+### 4. Expected Output
+
+```markdown
+Return:
+- Files modified
+- Tests now passing
+- Summary of changes
+- Any concerns
+```
+
+---
+
+## Execution Pattern
+
+### Dispatch Agents Concurrently
+
+```markdown
+Agent 1: Fix auth/login.test.ts
+Agent 2: Fix cart/checkout.test.ts
+Agent 3: Fix user/profile.test.ts
+
+All three run simultaneously.
+```
+
+### Monitor Progress
+
+```markdown
+While agents working:
+- Check for early failures
+- Watch for scope violations
+- Ready to pause if conflicts detected
+```
+
+---
+
+## Integration Pattern
+
+### Step 1: Collect Results
+
+```markdown
+Agent 1 returned:
+- Modified: src/auth/login-service.ts
+- Tests: 3/3 passing
+- Summary: Fixed token validation edge case
+
+Agent 2 returned:
+- Modified: src/cart/checkout-service.ts
+- Tests: 2/2 passing
+- Summary: Fixed price calculation rounding
+
+Agent 3 returned:
+- Modified: src/user/profile-service.ts
+- Tests: 1/1 passing
+- Summary: Fixed null handling in profile update
+```
+
+### Step 2: Verify No Conflicts
+
+```markdown
+Check:
+- No overlapping file modifications
+- No conflicting changes to shared types
+- No incompatible API changes
+```
+
+### Step 3: Run Full Test Suite
+
+```bash
+npm test
+# All tests should pass including:
+# - The 6 originally failing tests
+# - All other tests (no regressions)
+```
+
+### Step 4: Integrate Changes
+
+```bash
+# If all agents used branches
+git merge agent-1-auth-fixes
+git merge agent-2-cart-fixes
+git merge agent-3-user-fixes
+```
+
+---
+
+## Example Prompts
+
+### Agent Task Prompt Template
+
+```markdown
+## Task: Fix [specific test file]
+
+**Scope**: Only modify files in [directory]
+
+**Failing tests**:
+1. [test name 1]
+2. [test name 2]
+
+**Constraints**:
+- Do not modify test expectations
+- Do not change shared utilities in src/utils/
+- Do not modify types in src/types/
+
+**Goal**: Make all tests in [file] pass
+
+**Return**:
+- List of files modified
+- Summary of changes made
+- Number of tests now passing
+- Any concerns about the changes
+```
+
+### Result Collection Prompt
+
+```markdown
+## Parallel Agent Results
+
+**Agent 1 (Auth)**:
+[Paste agent 1 results]
+
+**Agent 2 (Cart)**:
+[Paste agent 2 results]
+
+**Agent 3 (User)**:
+[Paste agent 3 results]
+
+## Integration Checklist
+- [ ] No file conflicts
+- [ ] Full test suite passes
+- [ ] Changes are isolated to domains
+- [ ] Ready to merge
+```
+
+---
+
+## Example: Full-Stack Feature Dispatch
+
+A real-world example dispatching 3 agents for a new "orders" feature:
+
+### Independence check
+
+| | Agent 1 (Backend) | Agent 2 (Frontend) | Agent 3 (Database) |
+|---|---|---|---|
+| **Files** | `src/api/orders.py`, `tests/test_orders.py` | `src/components/order-form.tsx`, `*.test.tsx` | `migrations/003_orders.sql`, `tests/test_migration.py` |
+| **Test suite** | `pytest tests/test_orders.py` | `npm test -- order-form` | `pytest tests/test_migration.py` |
+| **Shared state?** | No | No | No |
+
+All three touch different files and different test suites — safe to parallelize.
+
+### Agent 1 — Backend (FastAPI)
+
+```markdown
+## Task: Implement POST /api/orders with validation
+
+**Context**: FastAPI + SQLAlchemy async + Pydantic v2
+**Files**: src/api/orders.py, src/schemas/order.py, tests/test_orders.py
+**Constraints**: Depends(get_db), return 201, RFC 9457 errors
+**Verify**: pytest tests/test_orders.py -v
+```
+
+### Agent 2 — Frontend (React/Next.js)
+
+```markdown
+## Task: Build OrderForm component with validation
+
+**Context**: Next.js App Router + react-hook-form + Zod + shadcn/ui
+**Files**: src/components/order-form.tsx, src/components/order-form.test.tsx
+**Constraints**: 'use client', Zod schema, accessible form fields
+**Verify**: npx vitest run src/components/order-form.test.tsx
+```
+
+### Agent 3 — Database (PostgreSQL)
+
+```markdown
+## Task: Create orders table migration
+
+**Context**: Alembic migrations, PostgreSQL
+**Files**: migrations/003_create_orders.sql, tests/test_orders_migration.py
+**Constraints**: Include indexes on user_id and created_at, add foreign key to users
+**Verify**: pytest tests/test_orders_migration.py -v
+```
+
+### Integration after all 3 complete
+
+```bash
+# 1. Run each agent's test suite to confirm
+pytest tests/test_orders.py tests/test_orders_migration.py -v
+npx vitest run src/components/order-form.test.tsx
+
+# 2. Run full test suite for regressions
+pytest -v && npm test
+
+# 3. Verify no file conflicts
+git diff --name-only  # should show no overlapping files between agents
+```
+
+---
+
+## Conflict Resolution
+
+If conflicts detected:
+
+```markdown
+1. STOP parallel execution
+2. Identify conflicting changes
+3. Decide which takes priority
+4. Continue sequentially from conflict point
+5. Learn: Update domain boundaries
+```
+
+---
+
+## Checklist
+
+Before parallel dispatch:
+- [ ] 3+ independent failures identified
+- [ ] Failures grouped by domain
+- [ ] Independence verified (no shared state)
+- [ ] Scope boundaries clear
+- [ ] Conflict potential assessed
+
+After parallel completion:
+- [ ] All agent results collected
+- [ ] No file conflicts detected
+- [ ] Full test suite passes
+- [ ] Changes integrated successfully
+
+---
+
+## Related Skills
+
+- `executing-plans` - Use executing-plans when tasks are sequential; use dispatching-parallel-agents when tasks are independent and can run concurrently
+- `writing-plans` - Write a plan first to identify which tasks are independent before dispatching parallel agents
@@ -0,0 +1,196 @@
+# Parallelization Patterns Reference
+
+How to decide what to parallelize and which pattern to use.
+
+## Core Principle
+
+Parallelize when tasks are **independent**: no shared mutable state, no ordering dependency, and results can be combined without conflict.
+
+## Pattern 1: Independent Tasks
+
+**When**: Two or more tasks share no state and have no ordering dependency.
+
+**Always parallel.** This is the simplest and most common case.
+
+### Examples
+
+- Linting + type checking + unit tests (different tools, same codebase, read-only)
+- Researching two unrelated libraries
+- Generating tests for unrelated modules
+- Reviewing separate files
+
+### Structure
+
+```
+[Dispatcher]
+    |--- Agent A: lint src/
+    |--- Agent B: typecheck src/
+    |--- Agent C: run tests
+    \--- Agent D: security scan
+[Collect all results]
+```
+
+### Decision Criteria
+
+- Do they read/write the same files? No -> parallel
+- Does one need output from another? No -> parallel
+- Can they run in any order? Yes -> parallel
+
+## Pattern 2: Fan-Out / Fan-In
+
+**When**: A single task can be split into N identical subtasks, then results are merged.
+
+### Examples
+
+- Process each file in a directory independently
+- Run the same analysis on multiple services
+- Test multiple configurations
+- Investigate multiple potential causes of a bug
+
+### Structure
+
+```
+[Dispatcher: split work into N chunks]
+    |--- Agent 1: process chunk 1
+    |--- Agent 2: process chunk 2
+    |--- Agent 3: process chunk 3
+    \--- Agent N: process chunk N
+[Collector: merge results from all agents]
+```
+
+### Implementation
+
+Split items across agents (round-robin, by directory, or by type), dispatch all simultaneously, collect results, handle failures by retrying individually, then merge into unified output.
+
+## Pattern 3: Pipeline (Sequential)
+
+**When**: Output of step N is input to step N+1.
+
+**Must be sequential.** Cannot parallelize.
+
+### Examples
+
+- Parse code -> analyze AST -> generate report
+- Fetch data -> transform -> validate -> persist
+- Write code -> run tests -> fix failures
+
+### Structure
+
+```
+[Step 1: parse] --> [Step 2: analyze] --> [Step 3: report]
+```
+
+### When Pipelines Contain Parallelizable Steps
+
+A pipeline stage itself might fan out:
+
+```
+[Step 1: identify files]
+    --> [Step 2: analyze each file in parallel (fan-out/fan-in)]
+    --> [Step 3: merge analysis into report]
+```
+
+## Pattern 4: Pipeline with Parallel Stages
+
+**When**: Some pipeline stages can run in parallel, others must be sequential.
+
+### Example: Feature Implementation
+
+```
+[Sequential: write plan]
+    --> [Parallel: implement module A, implement module B, implement module C]
+    --> [Sequential: integration test]
+    --> [Parallel: write docs, update changelog]
+    --> [Sequential: final review]
+```
+
+## Decision Matrix
+
+| Task Characteristic | Pattern | Parallelizable? |
+|---|---|---|
+| No shared state, no ordering | Independent | Yes |
+| Same operation on many items | Fan-out/fan-in | Yes |
+| Output feeds next step | Pipeline | No |
+| Mixed dependencies | Pipeline + parallel stages | Partially |
+| Shared mutable state | Sequential or lock-based | No (usually) |
+| Non-deterministic ordering matters | Sequential | No |
+
+## Common Parallel Task Patterns
+
+### File-Per-Agent
+
+Split work by file or directory. Each agent owns its files exclusively.
+
+```
+Agent 1: src/auth/**
+Agent 2: src/orders/**
+Agent 3: src/users/**
+```
+
+**Best for**: code review, refactoring, test generation, documentation.
+
+**Watch out for**: shared utilities, cross-module imports. Assign shared code to one agent or make it read-only for all.
+
+### Test Suite Splitting
+
+Split tests by module, type, or estimated runtime.
+
+```
+Agent 1: unit tests (fast)
+Agent 2: integration tests (medium)
+Agent 3: e2e tests (slow)
+```
+
+**Best for**: CI acceleration, pre-merge validation.
+
+### Multi-Service Investigation
+
+When debugging spans multiple services, assign one agent per service.
+
+```
+Agent 1: investigate auth service logs
+Agent 2: investigate order service logs
+Agent 3: investigate payment service logs
+```
+
+**Best for**: distributed system debugging, incident response.
+
+### Research Branches
+
+Explore multiple hypotheses or approaches simultaneously.
+
+```
+Agent 1: research approach A (Redis caching)
+Agent 2: research approach B (CDN edge caching)
+Agent 3: research approach C (application-level memoization)
+```
+
+**Best for**: technology evaluation, design exploration, root cause hypotheses.
+
+## Anti-Patterns
+
+| Anti-Pattern | Problem | Fix |
+|---|---|---|
+| Parallelizing dependent tasks | Race conditions, wrong results | Identify dependencies first, use pipeline |
+| Too many agents | Overhead exceeds benefit | 2-5 agents is typical sweet spot |
+| No merge strategy | Results conflict or duplicate | Define merge/dedup logic before dispatching |
+| Shared file writes | Corruption, lost changes | Assign file ownership to one agent |
+| No failure handling | One failure blocks everything | Collect partial results, retry individually |
+
+## Checklist Before Parallelizing
+
+1. **List all tasks** that need to happen
+2. **Draw dependencies** between them (which needs output from which?)
+3. **Group independent tasks** into parallel batches
+4. **Define the merge strategy** for collecting results
+5. **Assign ownership** so no two agents write the same file
+6. **Plan for failure** of individual agents
+7. **Estimate whether parallelism helps** (overhead vs time saved)
+
+## Quick Reference: Dispatch Decision
+
+- Single atomic operation -> just do it, no parallelism
+- Splittable into independent chunks -> fan-out/fan-in
+- Each step depends on previous output -> pipeline (sequential)
+- Mix of independent and dependent steps -> pipeline with parallel stages
+- Everything independent -> run all in parallel