thanh-kit 2.5.0 → 2.5.2

package/templates/skills/team/references/agent-teams-controls-and-modes.md

@@ -0,0 +1,107 @@
+# Agent Teams — Controls, Display Modes & Task Management
+
+> **Source:** https://code.claude.com/docs/en/agent-teams
+
+## Display Modes
+
+- **In-process** (default fallback): all teammates in one terminal. `Shift+Up/Down` to navigate. Works in any terminal.
+- **Split panes**: each teammate gets own pane. Requires tmux or iTerm2.
+
+Default is `"auto"` — uses split panes if already inside a tmux session, otherwise in-process. The `"tmux"` setting enables split-pane mode and auto-detects tmux vs iTerm2.
+
+```json
+{ "teammateMode": "in-process" }
+```
+
+Per-session override: `claude --teammate-mode in-process`
+
+Split panes NOT supported in: VS Code terminal, Windows Terminal, Ghostty.
+
+**tmux setup:** install via system package manager.
+**iTerm2 setup:** install `it2` CLI, enable Python API in iTerm2 > Settings > General > Magic.
+
+## Specify Teammates & Models
+
+Claude decides teammate count based on task, or you specify:
+
+```
+Create a team with 4 teammates to refactor these modules in parallel.
+Use Sonnet for each teammate.
+```
+
+## Plan Approval
+
+Require teammates to plan before implementing:
+
+```
+Spawn an architect teammate to refactor the auth module.
+Require plan approval before they make any changes.
+```
+
+**Flow:**
+1. Teammate works in read-only plan mode
+2. Teammate finishes planning → sends `plan_approval_request` to lead
+3. Lead reviews → approves via `SendMessage(type: "plan_approval_response", approve: true)`
+4. If rejected: teammate stays in plan mode, revises based on feedback, resubmits
+5. Once approved: teammate exits plan mode, begins implementation
+
+**Influence criteria:** "only approve plans that include test coverage" or "reject plans that modify the database schema"
+
+## Delegate Mode
+
+Restricts lead to coordination-only tools: spawning, messaging, shutting down teammates, and managing tasks. No code editing.
+
+Useful when lead should focus entirely on orchestration — breaking down work, assigning tasks, synthesizing results.
+
+**Enable:** Press `Shift+Tab` after team creation to cycle into delegate mode.
+
+## Direct Teammate Interaction
+
+- **In-process**: `Shift+Up/Down` select teammate, type to message. `Enter` view session. `Escape` interrupt current turn. `Ctrl+T` toggle task list.
+- **Split panes**: click into pane to interact directly. Each teammate has full terminal view.
+
+## Task Assignment & Claiming
+
+Three states: **pending** → **in_progress** → **completed**. Tasks can have dependencies — blocked until dependencies resolve.
+
+- **Lead assigns**: tell lead which task → which teammate
+- **Self-claim**: after finishing, teammate picks next unassigned, unblocked task automatically
+
+File locking prevents race conditions on simultaneous claiming.
+
+Task dependencies managed automatically — completing a blocking task unblocks dependents.
+
+## Shutdown
+
+```
+Ask the researcher teammate to shut down
+```
+
+Teammate can approve (exit) or reject with explanation. Teammates finish current request/tool call before shutting down — can be slow.
+
+## Cleanup
+
+After all teammates shut down, call `TeamDelete` (no parameters). Fails if active teammates still exist.
+
+Removes shared team resources (`~/.claude/teams/` and `~/.claude/tasks/` entries).
+
+## Hook-Based Orchestration (2.1.33+)
+
+### Event-Driven Monitoring
+
+Instead of polling TaskList, lead receives automatic context injection:
+
+- **TaskCompleted** — fires when any teammate completes a task. Lead gets progress counts.
+- **TeammateIdle** — fires when teammate turn ends. Lead gets available task info.
+
+CK hooks (`task-completed-handler.cjs`, `teammate-idle-handler.cjs`) process these events and inject summary into lead's context.
+
+### Recommended Pattern
+
+1. Lead creates tasks and spawns teammates
+2. TaskCompleted hook notifies lead as tasks finish (progress: N/M)
+3. TeammateIdle hook suggests reassignment or shutdown
+4. Lead acts on suggestions (spawn tester, shut down, reassign)
+5. Fallback: Check TaskList manually if no events received in 60s
+
+This replaces the "poll TaskList every 30s" pattern with reactive orchestration.

package/templates/skills/team/references/agent-teams-examples-and-best-practices.md

@@ -0,0 +1,182 @@
+# Agent Teams — Examples, Best Practices & Troubleshooting
+
+> **Source:** https://code.claude.com/docs/en/agent-teams
+
+## Use Case Examples
+
+### Parallel Code Review
+
+```
+Create an agent team to review PR #142. Spawn three reviewers:
+- One focused on security implications
+- One checking performance impact
+- One validating test coverage
+Have them each review and report findings.
+```
+
+Each reviewer applies different filter to same PR. Lead synthesizes across all three.
+
+### Competing Hypotheses Investigation
+
+```
+Users report the app exits after one message instead of staying connected.
+Spawn 5 agent teammates to investigate different hypotheses. Have them talk to
+each other to try to disprove each other's theories, like a scientific
+debate. Update the findings doc with whatever consensus emerges.
+```
+
+Adversarial debate structure fights anchoring bias — surviving theory is most likely correct.
+
+### Parallel Feature Implementation
+
+```
+Create a team to implement the new dashboard feature.
+Developer A owns src/api/* and src/models/*.
+Developer B owns src/components/* and src/pages/*.
+Tester writes tests after both devs finish.
+Require plan approval for developers.
+```
+
+Each developer works in isolation. Tester blocked until both complete.
+
+## Best Practices
+
+### Give Enough Context
+
+Teammates don't inherit lead's conversation. Include details in spawn prompt:
+
+```
+Spawn a security reviewer with prompt: "Review src/auth/ for vulnerabilities.
+Focus on token handling, session management, input validation.
+App uses JWT in httpOnly cookies. Report with severity ratings."
+```
+
+### Size Tasks Right
+
+- **Too small**: coordination overhead exceeds benefit
+- **Too large**: teammates work too long without check-ins
+- **Right**: self-contained units with clear deliverable (function, test file, review)
+
+### Start with Research/Review
+
+If new to agent teams, start with read-only tasks (reviewing PRs, researching libraries, investigating bugs). Shows parallel value without coordination challenges of parallel implementation.
+
+### Wait for Teammates
+
+If lead starts implementing instead of delegating:
+```
+Wait for your teammates to complete their tasks before proceeding
+```
+
+### Avoid File Conflicts
+
+Two teammates editing same file = overwrites. Each teammate must own distinct files. If shared file needed, lead handles it or restructure tasks.
+
+### Use Git Worktrees for Implementation Teams
+
+For implementation teams with multiple developers editing code:
+1. Create a worktree per developer: `git worktree add ../worktrees/<dev-name> -b <branch>`
+2. Each developer works in their own worktree — eliminates git conflicts
+3. Lead merges worktree branches after completion
+4. Cleanup: `git worktree remove ../worktrees/<dev-name>`
+
+This is the safest pattern for parallel code changes.
+
+### Monitor & Steer
+
+Check progress regularly. Redirect bad approaches. Synthesize findings as they arrive. Letting a team run unattended too long increases wasted effort risk.
+
+### File Ownership Enforcement
+
+- Define explicit file boundaries in each task description
+- Include glob patterns: `File ownership: src/api/*, src/models/*`
+- If two tasks need same file: escalate to lead, restructure, or have lead handle directly
+- Tester owns test files only; reads implementation files but never edits them
+
+### Leverage Event-Driven Hooks (2.1.33+)
+
+With `TaskCompleted` and `TeammateIdle` hooks enabled:
+
+- Lead is automatically notified when tasks complete — no manual polling needed
+- Progress is tracked via hook-injected context: "3/5 tasks done, 2 pending"
+- Idle teammates trigger suggestions: "worker-2 idle, 1 unblocked task available"
+- All tasks done triggers: "Consider shutting down teammates and synthesizing"
+
+**Cook workflow example:**
+```
+1. Lead spawns 3 devs + creates tasks
+2. TaskCompleted(dev-1, task #1) → "1/4 done"
+3. TaskCompleted(dev-2, task #2) → "2/4 done"
+4. TaskCompleted(dev-3, task #3) → "3/4 done"
+5. TaskCompleted(dev-1, task #4) → "4/4 done. All tasks completed."
+6. Lead spawns tester (reactively, no delay)
+```
+
+### Use Agent Memory for Long-Running Projects
+
+For projects with recurring team sessions:
+- Code reviewer learns project conventions, stops flagging known patterns
+- Debugger remembers past failures, faster root-cause identification
+- Tester tracks flaky tests, avoids re-investigating known issues
+- Researcher accumulates domain knowledge across projects (user scope)
+
+Memory persists after team cleanup — it's in `.claude/agent-memory/`, not `~/.claude/teams/`.
+
+### Restrict Sub-Agent Spawning
+
+Use `Task(agent_type)` in agent definitions to prevent:
+- Recursive agent chains (agent spawns agent spawns agent)
+- Cost escalation (haiku agent spawning opus sub-agent)
+- Scope creep (tester spawning developer to "fix" issues)
+
+Recommended: Most agents get `Task(Explore)` only. Planner gets `Task(Explore), Task(researcher)`.
+
+## Token Budget Guidance
+
+| Template | Estimated Tokens | Model Strategy |
+|----------|-----------------|----------------|
+| Research (3 teammates) | ~150K-300K | haiku for all researchers |
+| Cook (4 teammates) | ~400K-800K | sonnet for devs, haiku for tester |
+| Review (3 teammates) | ~100K-200K | haiku for all reviewers |
+| Debug (3 teammates) | ~200K-400K | sonnet for debuggers |
+
+Agent Teams use significantly more tokens than subagents. Use only when parallel exploration + discussion adds clear value. For routine tasks, single session is more cost-effective.
+
+## Troubleshooting
+
+### Teammates Not Appearing
+
+- In-process: press `Shift+Down` to cycle through active teammates
+- Task may not be complex enough — Claude decides based on task
+- Split panes: verify tmux installed and in PATH
+- iTerm2: verify `it2` CLI installed and Python API enabled
+
+### Too Many Permission Prompts
+
+Pre-approve common operations in permission settings before spawning.
+
+### Teammates Stopping on Errors
+
+Check output via `Shift+Up/Down` or clicking pane. Give additional instructions or spawn replacement.
+
+### Lead Shuts Down Early
+
+Tell lead to keep going or wait for teammates.
+
+### Orphaned tmux Sessions
+
+```
+tmux ls
+tmux kill-session -t <session-name>
+```
+
+## Limitations
+
+- **No session resumption**: `/resume` and `/rewind` don't restore in-process teammates
+- **Task status can lag**: teammates may not mark tasks completed; check manually
+- **Shutdown can be slow**: finishes current request first
+- **One team per session**: clean up before starting new one
+- **No nested teams**: only lead manages team
+- **Lead is fixed**: can't promote teammate or transfer leadership
+- **Permissions at spawn**: all inherit lead's mode; changeable after but not at spawn time
+- **Split panes**: require tmux or iTerm2 only

package/templates/skills/team/references/agent-teams-official-docs.md

@@ -0,0 +1,175 @@
+# Agent Teams — Overview & Architecture
+
+> **Canonical source:** https://code.claude.com/docs/en/agent-teams
+> **Version captured:** Claude Code (Feb 2026)
+> **Update policy:** Re-fetch canonical URL when Claude Code releases new Agent Teams features.
+
+This is a **self-contained knowledge base** — AI agents should NOT need to re-fetch the URL.
+
+## Overview
+
+Agent Teams coordinate multiple Claude Code instances working together. One session acts as the team lead, coordinating work, assigning tasks, and synthesizing results. Teammates work independently, each in its own context window, and communicate directly with each other.
+
+Unlike subagents (run within a single session, report back only), teammates are full independent sessions you can interact with directly.
+
+## When to Use
+
+Best for tasks where parallel exploration adds real value:
+
+- **Research and review**: multiple teammates investigate different aspects, share and challenge findings
+- **New modules or features**: teammates each own a separate piece without conflicts
+- **Debugging with competing hypotheses**: test different theories in parallel
+- **Cross-layer coordination**: changes spanning frontend, backend, tests — each owned by different teammate
+
+**Not suitable for:** sequential tasks, same-file edits, work with many dependencies.
+
+### Subagents vs Agent Teams
+
+| | Subagents | Agent Teams |
+|---|---|---|
+| **Context** | Own window; results return to caller | Own window; fully independent |
+| **Communication** | Report back to main agent only | Message each other directly |
+| **Coordination** | Main agent manages all work | Shared task list, self-coordination |
+| **Best for** | Focused tasks, result-only | Complex work requiring discussion |
+| **Token cost** | Lower | Higher (each teammate = separate instance) |
+
+## Enable
+
+Still experimental — requires opt-in:
+
+```json
+{ "env": { "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1" } }
+```
+
+Set in shell environment or settings.json.
+
+## How Teams Start
+
+Two paths:
+1. **You request**: describe task + ask for agent team. Claude creates based on instructions.
+2. **Claude proposes**: suggests team if task benefits from parallel work.
+
+Both require your confirmation. Claude won't create a team without approval.
+
+## Architecture
+
+| Component | Role |
+|-----------|------|
+| **Team lead** | Main session — creates team, spawns teammates, coordinates |
+| **Teammates** | Separate Claude Code instances with own context windows |
+| **Task list** | Shared work items at `~/.claude/tasks/{team-name}/` |
+| **Mailbox** | Messaging system for inter-agent communication |
+
+Storage:
+- **Team config**: `~/.claude/teams/{team-name}/config.json` (members array with name, agent ID, type)
+- **Task list**: `~/.claude/tasks/{team-name}/`
+
+Task dependencies managed automatically — completing a blocking task unblocks dependents without manual intervention.
+
+## Tools API Surface
+
+### TeamCreate
+
+Create team + task list. Params: `team_name`, `description`.
+
+### TeamDelete
+
+Remove team/task dirs. **Takes NO parameters** — just call `TeamDelete` with empty params. Fails if active teammates still exist.
+
+### SendMessage Types
+
+| Type | Purpose |
+|------|---------|
+| `message` | DM to one teammate (requires `recipient`) |
+| `broadcast` | Send to ALL teammates (use sparingly — costs scale with N) |
+| `shutdown_request` | Ask teammate to gracefully exit |
+| `shutdown_response` | Teammate approves/rejects shutdown (requires `request_id`) |
+| `plan_approval_response` | Lead approves/rejects teammate plan (requires `request_id`) |
+
+### Task System Fields
+
+| Field | Values/Purpose |
+|-------|---------------|
+| `status` | `pending` → `in_progress` → `completed` (or `deleted`) |
+| `owner` | Agent name assigned to task |
+| `blocks` | Task IDs this task blocks (read via TaskGet) |
+| `blockedBy` | Task IDs that must complete first (read via TaskGet) |
+| `addBlocks` | Set blocking relations (write via TaskUpdate) |
+| `addBlockedBy` | Set dependency relations (write via TaskUpdate) |
+| `metadata` | Arbitrary key-value pairs |
+| `subject` | Brief imperative title |
+| `description` | Full requirements and context |
+
+Task claiming uses file locking to prevent race conditions.
+
+## Hook Events (2.1.33+)
+
+### TaskCompleted
+
+Fires when teammate calls `TaskUpdate` with `status: "completed"`.
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `task_id` | string | Completed task ID |
+| `task_subject` | string | Task title |
+| `task_description` | string | Full task description |
+| `teammate_name` | string | Who completed it |
+| `team_name` | string | Team name |
+
+Note: Does NOT include `permission_mode`.
+
+### TeammateIdle
+
+Fires after `SubagentStop` for team members.
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `teammate_name` | string | Idle teammate name |
+| `team_name` | string | Team name |
+
+Note: Includes `permission_mode`. Always pairs with SubagentStop.
+
+### Event Lifecycle
+
+```
+SubagentStart(worker) → TaskCompleted(task) → SubagentStop(worker) → TeammateIdle(worker)
+```
+
+TaskCompleted fires BEFORE SubagentStop/TeammateIdle.
+
+## Agent Memory
+
+Agents can declare `memory` in frontmatter for persistent cross-session learning.
+
+| Scope | Location | Persists across |
+|-------|----------|-----------------|
+| `user` | `~/.claude/agent-memory/<name>/` | All projects |
+| `project` | `.claude/agent-memory/<name>/` | Sessions in same project |
+
+First 200 lines of `MEMORY.md` auto-injected into system prompt.
+
+## Task(agent_type) Restrictions
+
+Limit which sub-agents an agent can spawn:
+
+```yaml
+tools: Read, Grep, Bash, Task(Explore)
+```
+
+This agent can only spawn `Explore` sub-agents. Restricts recursive spawning and cost escalation.
+
+## Context & Communication
+
+Each teammate loads: CLAUDE.md, MCP servers, skills, agents. Receives spawn prompt from lead. Lead's conversation history does NOT carry over.
+
+- **Automatic message delivery** — no polling needed
+- **Idle notifications** — teammates notify lead when turn ends
+- **Shared task list** — all agents see status and claim work
+
+## Permissions
+
+Teammates inherit lead's permission settings at spawn. If lead uses `--dangerously-skip-permissions`, all teammates do too. Can change individually after spawning but not at spawn time.
+
+## Token Usage
+
+Scales with active teammates. Worth it for research/review/features. Single session more cost-effective for routine tasks.

package/templates/skills/template-skill/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: template-skill
+name: ck:template-skill
 description: Replace with description of the skill and when Claude should use it.
 ---
 

package/templates/skills/test/SKILL.md

@@ -0,0 +1,109 @@
+---
+name: ck:test
+description: "Run unit, integration, e2e, and UI tests. Use for test execution, coverage analysis, build verification, visual regression, and QA reports."
+argument-hint: "[context] OR ui [url]"
+version: 1.0.0
+---
+
+# Testing & Quality Assurance
+
+Comprehensive testing framework covering code-level testing (unit, integration, e2e), UI/visual testing via browser automation, coverage analysis, and structured QA reporting.
+
+## Default (No Arguments)
+
+If invoked with context (test scope), proceed with testing. If invoked WITHOUT arguments, use `AskUserQuestion` to present available test operations:
+
+| Operation | Description |
+|-----------|-------------|
+| `(default)` | Run unit/integration/e2e tests |
+| `ui` | Run UI tests on a website |
+
+Present as options via `AskUserQuestion` with header "Test Operation", question "What would you like to do?".
+
+## Core Principle
+
+**NEVER IGNORE FAILING TESTS.** Fix root causes, not symptoms. No mocks/cheats/tricks to pass builds.
+
+## When to Use
+
+- **After implementation**: Validate new features or bug fixes
+- **Coverage checks**: Ensure coverage meets project thresholds (80%+)
+- **UI verification**: Visual regression, responsive layout, accessibility
+- **Build validation**: Verify build process, dependencies, CI/CD compatibility
+- **Pre-commit/push**: Final quality gate
+
+## Workflows
+
+### 1. Code Testing (`references/test-execution-workflow.md`)
+
+Execute test suites, analyze results, generate coverage. Supports JS/TS (Jest/Vitest/Mocha), Python (pytest), Go, Rust, Flutter. Includes working process, quality standards, and tool commands.
+
+**Load when:** Running unit/integration/e2e tests, checking coverage, validating builds
+
+### 2. UI Testing (`references/ui-testing-workflow.md`)
+
+Browser-based visual testing via `ck:chrome-devtools` skill. Screenshots, responsive checks, accessibility audits, form automation, console error collection. Includes auth injection for protected routes.
+
+**Load when:** Visual regression testing, UI bugs, responsive layout checks, accessibility audits
+
+### 3. Report Format (`references/report-format.md`)
+
+Structured QA report template: test results overview, coverage metrics, failed tests, performance, build status, recommendations.
+
+**Load when:** Generating test summary reports
+
+## Quick Reference
+
+```
+Code tests     → test-execution-workflow.md
+  npm test / pytest / go test / cargo test / flutter test
+  Coverage: npm run test:coverage / pytest --cov
+
+UI tests       → ui-testing-workflow.md
+  Screenshots, responsive, a11y, forms, console errors
+  Auth: inject-auth.js for protected routes
+
+Reports        → report-format.md
+  Structured QA summary with metrics & recommendations
+```
+
+## Working Process
+
+1. Identify testing scope from recent changes or requirements
+2. Run typecheck/analyze commands to catch syntax errors first
+3. Execute appropriate test suites
+4. Analyze results — focus on failures
+5. Generate coverage reports if applicable
+6. For frontend: run UI tests via `ck:chrome-devtools` skill
+7. Produce structured summary report
+
+## Tools Integration
+
+- **Test runners**: Jest, Vitest, Mocha, pytest, go test, cargo test, flutter test
+- **Coverage**: Istanbul/c8/nyc, pytest-cov, go cover
+- **Browser**: `ck:chrome-devtools` skill for UI testing (screenshots, ARIA, console, network)
+- **Analysis**: `ck:ai-multimodal` skill for screenshot analysis
+- **Debugging**: `ck:debug` skill when tests reveal bugs requiring investigation
+- **Thinking**: `ck:sequential-thinking` skill for complex test failure analysis
+
+## Quality Standards
+
+- All critical paths must have test coverage
+- Validate happy path AND error scenarios
+- Ensure test isolation — no interdependencies
+- Tests must be deterministic and reproducible
+- Clean up test data after execution
+- Never ignore failing tests to pass the build
+
+## Report Output
+
+Use naming pattern from `## Naming` section injected by hooks.
+
+## Team Mode
+
+When operating as teammate:
+1. On start: check `TaskList`, claim assigned/next unblocked task via `TaskUpdate`
+2. Read full task description via `TaskGet` before starting
+3. Wait for blocked tasks (implementation) to complete before testing
+4. Respect file ownership — only create/edit test files assigned
+5. When done: `TaskUpdate(status: "completed")` then `SendMessage` results to lead

package/templates/skills/test/references/report-format.md

@@ -0,0 +1,58 @@
+# Test Report Format
+
+Structured QA report template. Sacrifice grammar for concision.
+
+## Template
+
+```markdown
+# Test Report — {date} — {scope}
+
+## Test Results Overview
+- **Total**: X tests
+- **Passed**: X | **Failed**: X | **Skipped**: X
+- **Duration**: Xs
+
+## Coverage Metrics
+| Metric   | Value | Threshold | Status |
+|----------|-------|-----------|--------|
+| Lines    | X%    | 80%       | PASS/FAIL |
+| Branches | X%    | 70%       | PASS/FAIL |
+| Functions| X%    | 80%       | PASS/FAIL |
+
+## Failed Tests
+### `test/path/file.test.ts` — TestName
+- **Error**: Error message
+- **Stack**: Relevant stack trace (truncated)
+- **Cause**: Brief root cause analysis
+- **Fix**: Suggested resolution
+
+## UI Test Results (if applicable)
+- **Pages tested**: X
+- **Screenshots**: ./screenshots/
+- **Console errors**: none | [list]
+- **Responsive**: checked at [viewports] | skipped
+- **Performance**: LCP Xs, FID Xms, CLS X
+
+## Build Status
+- **Build**: PASS/FAIL
+- **Warnings**: none | [list]
+- **Dependencies**: all resolved | [issues]
+
+## Critical Issues
+1. [Blocking issue description + impact]
+
+## Recommendations
+1. [Actionable improvement with priority]
+
+## Unresolved Questions
+- [Any open questions, if any]
+```
+
+## Guidelines
+
+- Include ALL failed tests with error messages — don't summarize away details
+- Coverage: highlight specific uncovered files/functions, not just percentages
+- Screenshots: embed paths directly in report for easy access
+- Recommendations: prioritize by impact (critical > high > medium > low)
+- Keep report under 200 lines — split into sections if larger scope needed
+- Save report using naming pattern from `## Naming` section injected by hooks