Merge pull request #428 from zdocapp/zh-CN-pr

docs(zh-CN): sync Chinese docs with latest upstream changes

.agents/skills/claude-api/SKILL.md

@@ -0,0 +1,337 @@
+---
+name: claude-api
+description: Anthropic Claude API patterns for Python and TypeScript. Covers Messages API, streaming, tool use, vision, extended thinking, batches, prompt caching, and Claude Agent SDK. Use when building applications with the Claude API or Anthropic SDKs.
+origin: ECC
+---
+
+# Claude API
+
+Build applications with the Anthropic Claude API and SDKs.
+
+## When to Activate
+
+- Building applications that call the Claude API
+- Code imports `anthropic` (Python) or `@anthropic-ai/sdk` (TypeScript)
+- User asks about Claude API patterns, tool use, streaming, or vision
+- Implementing agent workflows with Claude Agent SDK
+- Optimizing API costs, token usage, or latency
+
+## Model Selection
+
+| Model | ID | Best For |
+|-------|-----|----------|
+| Opus 4.6 | `claude-opus-4-6` | Complex reasoning, architecture, research |
+| Sonnet 4.6 | `claude-sonnet-4-6` | Balanced coding, most development tasks |
+| Haiku 4.5 | `claude-haiku-4-5-20251001` | Fast responses, high-volume, cost-sensitive |
+
+Default to Sonnet 4.6 unless the task requires deep reasoning (Opus) or speed/cost optimization (Haiku).
+
+## Python SDK
+
+### Installation
+
+```bash
+pip install anthropic
+```
+
+### Basic Message
+
+```python
+import anthropic
+
+client = anthropic.Anthropic()  # reads ANTHROPIC_API_KEY from env
+
+message = client.messages.create(
+    model="claude-sonnet-4-6",
+    max_tokens=1024,
+    messages=[
+        {"role": "user", "content": "Explain async/await in Python"}
+    ]
+)
+print(message.content[0].text)
+```
+
+### Streaming
+
+```python
+with client.messages.stream(
+    model="claude-sonnet-4-6",
+    max_tokens=1024,
+    messages=[{"role": "user", "content": "Write a haiku about coding"}]
+) as stream:
+    for text in stream.text_stream:
+        print(text, end="", flush=True)
+```
+
+### System Prompt
+
+```python
+message = client.messages.create(
+    model="claude-sonnet-4-6",
+    max_tokens=1024,
+    system="You are a senior Python developer. Be concise.",
+    messages=[{"role": "user", "content": "Review this function"}]
+)
+```
+
+## TypeScript SDK
+
+### Installation
+
+```bash
+npm install @anthropic-ai/sdk
+```
+
+### Basic Message
+
+```typescript
+import Anthropic from "@anthropic-ai/sdk";
+
+const client = new Anthropic(); // reads ANTHROPIC_API_KEY from env
+
+const message = await client.messages.create({
+  model: "claude-sonnet-4-6",
+  max_tokens: 1024,
+  messages: [
+    { role: "user", content: "Explain async/await in TypeScript" }
+  ],
+});
+console.log(message.content[0].text);
+```
+
+### Streaming
+
+```typescript
+const stream = client.messages.stream({
+  model: "claude-sonnet-4-6",
+  max_tokens: 1024,
+  messages: [{ role: "user", content: "Write a haiku" }],
+});
+
+for await (const event of stream) {
+  if (event.type === "content_block_delta" && event.delta.type === "text_delta") {
+    process.stdout.write(event.delta.text);
+  }
+}
+```
+
+## Tool Use
+
+Define tools and let Claude call them:
+
+```python
+tools = [
+    {
+        "name": "get_weather",
+        "description": "Get current weather for a location",
+        "input_schema": {
+            "type": "object",
+            "properties": {
+                "location": {"type": "string", "description": "City name"},
+                "unit": {"type": "string", "enum": ["celsius", "fahrenheit"]}
+            },
+            "required": ["location"]
+        }
+    }
+]
+
+message = client.messages.create(
+    model="claude-sonnet-4-6",
+    max_tokens=1024,
+    tools=tools,
+    messages=[{"role": "user", "content": "What's the weather in SF?"}]
+)
+
+# Handle tool use response
+for block in message.content:
+    if block.type == "tool_use":
+        # Execute the tool with block.input
+        result = get_weather(**block.input)
+        # Send result back
+        follow_up = client.messages.create(
+            model="claude-sonnet-4-6",
+            max_tokens=1024,
+            tools=tools,
+            messages=[
+                {"role": "user", "content": "What's the weather in SF?"},
+                {"role": "assistant", "content": message.content},
+                {"role": "user", "content": [
+                    {"type": "tool_result", "tool_use_id": block.id, "content": str(result)}
+                ]}
+            ]
+        )
+```
+
+## Vision
+
+Send images for analysis:
+
+```python
+import base64
+
+with open("diagram.png", "rb") as f:
+    image_data = base64.standard_b64encode(f.read()).decode("utf-8")
+
+message = client.messages.create(
+    model="claude-sonnet-4-6",
+    max_tokens=1024,
+    messages=[{
+        "role": "user",
+        "content": [
+            {"type": "image", "source": {"type": "base64", "media_type": "image/png", "data": image_data}},
+            {"type": "text", "text": "Describe this diagram"}
+        ]
+    }]
+)
+```
+
+## Extended Thinking
+
+For complex reasoning tasks:
+
+```python
+message = client.messages.create(
+    model="claude-sonnet-4-6",
+    max_tokens=16000,
+    thinking={
+        "type": "enabled",
+        "budget_tokens": 10000
+    },
+    messages=[{"role": "user", "content": "Solve this math problem step by step..."}]
+)
+
+for block in message.content:
+    if block.type == "thinking":
+        print(f"Thinking: {block.thinking}")
+    elif block.type == "text":
+        print(f"Answer: {block.text}")
+```
+
+## Prompt Caching
+
+Cache large system prompts or context to reduce costs:
+
+```python
+message = client.messages.create(
+    model="claude-sonnet-4-6",
+    max_tokens=1024,
+    system=[
+        {"type": "text", "text": large_system_prompt, "cache_control": {"type": "ephemeral"}}
+    ],
+    messages=[{"role": "user", "content": "Question about the cached context"}]
+)
+# Check cache usage
+print(f"Cache read: {message.usage.cache_read_input_tokens}")
+print(f"Cache creation: {message.usage.cache_creation_input_tokens}")
+```
+
+## Batches API
+
+Process large volumes asynchronously at 50% cost reduction:
+
+```python
+import time
+
+batch = client.messages.batches.create(
+    requests=[
+        {
+            "custom_id": f"request-{i}",
+            "params": {
+                "model": "claude-sonnet-4-6",
+                "max_tokens": 1024,
+                "messages": [{"role": "user", "content": prompt}]
+            }
+        }
+        for i, prompt in enumerate(prompts)
+    ]
+)
+
+# Poll for completion
+while True:
+    status = client.messages.batches.retrieve(batch.id)
+    if status.processing_status == "ended":
+        break
+    time.sleep(30)
+
+# Get results
+for result in client.messages.batches.results(batch.id):
+    print(result.result.message.content[0].text)
+```
+
+## Claude Agent SDK
+
+Build multi-step agents:
+
+```python
+# Note: Agent SDK API surface may change — check official docs
+import anthropic
+
+# Define tools as functions
+tools = [{
+    "name": "search_codebase",
+    "description": "Search the codebase for relevant code",
+    "input_schema": {
+        "type": "object",
+        "properties": {"query": {"type": "string"}},
+        "required": ["query"]
+    }
+}]
+
+# Run an agentic loop with tool use
+client = anthropic.Anthropic()
+messages = [{"role": "user", "content": "Review the auth module for security issues"}]
+
+while True:
+    response = client.messages.create(
+        model="claude-sonnet-4-6",
+        max_tokens=4096,
+        tools=tools,
+        messages=messages,
+    )
+    if response.stop_reason == "end_turn":
+        break
+    # Handle tool calls and continue the loop
+    messages.append({"role": "assistant", "content": response.content})
+    # ... execute tools and append tool_result messages
+```
+
+## Cost Optimization
+
+| Strategy | Savings | When to Use |
+|----------|---------|-------------|
+| Prompt caching | Up to 90% on cached tokens | Repeated system prompts or context |
+| Batches API | 50% | Non-time-sensitive bulk processing |
+| Haiku instead of Sonnet | ~75% | Simple tasks, classification, extraction |
+| Shorter max_tokens | Variable | When you know output will be short |
+| Streaming | None (same cost) | Better UX, same price |
+
+## Error Handling
+
+```python
+import time
+
+from anthropic import APIError, RateLimitError, APIConnectionError
+
+try:
+    message = client.messages.create(...)
+except RateLimitError:
+    # Back off and retry
+    time.sleep(60)
+except APIConnectionError:
+    # Network issue, retry with backoff
+    pass
+except APIError as e:
+    print(f"API error {e.status_code}: {e.message}")
+```
+
+## Environment Setup
+
+```bash
+# Required
+export ANTHROPIC_API_KEY="your-api-key-here"
+
+# Optional: set default model
+export ANTHROPIC_MODEL="claude-sonnet-4-6"
+```
+
+Never hardcode API keys. Always use environment variables.

.agents/skills/claude-api/agents/openai.yaml

@@ -0,0 +1,7 @@
+interface:
+  display_name: "Claude API"
+  short_description: "Anthropic Claude API patterns and SDKs"
+  brand_color: "#D97706"
+  default_prompt: "Build applications with the Claude API using Messages, tool use, streaming, and Agent SDK"
+policy:
+  allow_implicit_invocation: true

.agents/skills/crosspost/SKILL.md

@@ -0,0 +1,192 @@
+---
+name: crosspost
+description: Multi-platform content distribution across X, LinkedIn, Threads, and Bluesky. Adapts content per platform using content-engine patterns. Never posts identical content cross-platform. Use when the user wants to distribute content across social platforms.
+origin: ECC
+---
+
+# Crosspost
+
+Distribute content across multiple social platforms with platform-native adaptation.
+
+## When to Use
+
+- User wants to post content to multiple platforms
+- Publishing announcements, launches, or updates across social media
+- Repurposing a post from one platform to others
+- User says "crosspost", "post everywhere", "share on all platforms", or "distribute this"
+
+## How It Works
+
+### Core Rules
+
+1. **Never post identical content cross-platform.** Each platform gets a native adaptation.
+2. **Primary platform first.** Post to the main platform, then adapt for others.
+3. **Respect platform conventions.** Length limits, formatting, link handling all differ.
+4. **One idea per post.** If the source content has multiple ideas, split across posts.
+5. **Attribution matters.** If crossposting someone else's content, credit the source.
+
+### Platform Specifications
+
+| Platform | Max Length | Link Handling | Hashtags | Media |
+|----------|-----------|---------------|----------|-------|
+| X | 280 chars (4000 for Premium) | Counted in length | Minimal (1-2 max) | Images, video, GIFs |
+| LinkedIn | 3000 chars | Not counted in length | 3-5 relevant | Images, video, docs, carousels |
+| Threads | 500 chars | Separate link attachment | None typical | Images, video |
+| Bluesky | 300 chars | Via facets (rich text) | None (use feeds) | Images |
+
+### Workflow
+
+### Step 1: Create Source Content
+
+Start with the core idea. Use `content-engine` skill for high-quality drafts:
+- Identify the single core message
+- Determine the primary platform (where the audience is biggest)
+- Draft the primary platform version first
+
+### Step 2: Identify Target Platforms
+
+Ask the user or determine from context:
+- Which platforms to target
+- Priority order (primary gets the best version)
+- Any platform-specific requirements (e.g., LinkedIn needs professional tone)
+
+### Step 3: Adapt Per Platform
+
+For each target platform, transform the content:
+
+**X adaptation:**
+- Open with a hook, not a summary
+- Cut to the core insight fast
+- Keep links out of main body when possible
+- Use thread format for longer content
+
+**LinkedIn adaptation:**
+- Strong first line (visible before "see more")
+- Short paragraphs with line breaks
+- Frame around lessons, results, or professional takeaways
+- More explicit context than X (LinkedIn audience needs framing)
+
+**Threads adaptation:**
+- Conversational, casual tone
+- Shorter than LinkedIn, less compressed than X
+- Visual-first if possible
+
+**Bluesky adaptation:**
+- Direct and concise (300 char limit)
+- Community-oriented tone
+- Use feeds/lists for topic targeting instead of hashtags
+
+### Step 4: Post Primary Platform
+
+Post to the primary platform first:
+- Use `x-api` skill for X
+- Use platform-specific APIs or tools for others
+- Capture the post URL for cross-referencing
+
+### Step 5: Post to Secondary Platforms
+
+Post adapted versions to remaining platforms:
+- Stagger timing (not all at once — 30-60 min gaps)
+- Include cross-platform references where appropriate ("longer thread on X" etc.)
+
+## Examples
+
+### Source: Product Launch
+
+**X version:**
+```
+We just shipped [feature].
+
+[One specific thing it does that's impressive]
+
+[Link]
+```
+
+**LinkedIn version:**
+```
+Excited to share: we just launched [feature] at [Company].
+
+Here's why it matters:
+
+[2-3 short paragraphs with context]
+
+[Takeaway for the audience]
+
+[Link]
+```
+
+**Threads version:**
+```
+just shipped something cool — [feature]
+
+[casual explanation of what it does]
+
+link in bio
+```
+
+### Source: Technical Insight
+
+**X version:**
+```
+TIL: [specific technical insight]
+
+[Why it matters in one sentence]
+```
+
+**LinkedIn version:**
+```
+A pattern I've been using that's made a real difference:
+
+[Technical insight with professional framing]
+
+[How it applies to teams/orgs]
+
+#relevantHashtag
+```
+
+## API Integration
+
+### Batch Crossposting Service (Example Pattern)
+If using a crossposting service (e.g., Postbridge, Buffer, or a custom API), the pattern looks like:
+
+```python
+import os
+import requests
+
+resp = requests.post(
+    "https://api.postbridge.io/v1/posts",
+    headers={"Authorization": f"Bearer {os.environ['POSTBRIDGE_API_KEY']}"},
+    json={
+        "platforms": ["twitter", "linkedin", "threads"],
+        "content": {
+            "twitter": {"text": x_version},
+            "linkedin": {"text": linkedin_version},
+            "threads": {"text": threads_version}
+        }
+    },
+    timeout=30
+)
+resp.raise_for_status()
+```
+
+### Manual Posting
+Without Postbridge, post to each platform using its native API:
+- X: Use `x-api` skill patterns
+- LinkedIn: LinkedIn API v2 with OAuth 2.0
+- Threads: Threads API (Meta)
+- Bluesky: AT Protocol API
+
+## Quality Gate
+
+Before posting:
+- [ ] Each platform version reads naturally for that platform
+- [ ] No identical content across platforms
+- [ ] Length limits respected
+- [ ] Links work and are placed appropriately
+- [ ] Tone matches platform conventions
+- [ ] Media is sized correctly for each platform
+
+## Related Skills
+
+- `content-engine` — Generate platform-native content
+- `x-api` — X/Twitter API integration

.agents/skills/crosspost/agents/openai.yaml

@@ -0,0 +1,7 @@
+interface:
+  display_name: "Crosspost"
+  short_description: "Multi-platform content distribution with native adaptation"
+  brand_color: "#EC4899"
+  default_prompt: "Distribute content across X, LinkedIn, Threads, and Bluesky with platform-native adaptation"
+policy:
+  allow_implicit_invocation: true

.agents/skills/deep-research/SKILL.md

@@ -0,0 +1,155 @@
+---
+name: deep-research
+description: Multi-source deep research using firecrawl and exa MCPs. Searches the web, synthesizes findings, and delivers cited reports with source attribution. Use when the user wants thorough research on any topic with evidence and citations.
+origin: ECC
+---
+
+# Deep Research
+
+Produce thorough, cited research reports from multiple web sources using firecrawl and exa MCP tools.
+
+## When to Activate
+
+- User asks to research any topic in depth
+- Competitive analysis, technology evaluation, or market sizing
+- Due diligence on companies, investors, or technologies
+- Any question requiring synthesis from multiple sources
+- User says "research", "deep dive", "investigate", or "what's the current state of"
+
+## MCP Requirements
+
+At least one of:
+- **firecrawl** — `firecrawl_search`, `firecrawl_scrape`, `firecrawl_crawl`
+- **exa** — `web_search_exa`, `web_search_advanced_exa`, `crawling_exa`
+
+Both together give the best coverage. Configure in `~/.claude.json` or `~/.codex/config.toml`.
+
+## Workflow
+
+### Step 1: Understand the Goal
+
+Ask 1-2 quick clarifying questions:
+- "What's your goal — learning, making a decision, or writing something?"
+- "Any specific angle or depth you want?"
+
+If the user says "just research it" — skip ahead with reasonable defaults.
+
+### Step 2: Plan the Research
+
+Break the topic into 3-5 research sub-questions. Example:
+- Topic: "Impact of AI on healthcare"
+  - What are the main AI applications in healthcare today?
+  - What clinical outcomes have been measured?
+  - What are the regulatory challenges?
+  - What companies are leading this space?
+  - What's the market size and growth trajectory?
+
+### Step 3: Execute Multi-Source Search
+
+For EACH sub-question, search using available MCP tools:
+
+**With firecrawl:**
+```
+firecrawl_search(query: "<sub-question keywords>", limit: 8)
+```
+
+**With exa:**
+```
+web_search_exa(query: "<sub-question keywords>", numResults: 8)
+web_search_advanced_exa(query: "<keywords>", numResults: 5, startPublishedDate: "2025-01-01")
+```
+
+**Search strategy:**
+- Use 2-3 different keyword variations per sub-question
+- Mix general and news-focused queries
+- Aim for 15-30 unique sources total
+- Prioritize: academic, official, reputable news > blogs > forums
+
+### Step 4: Deep-Read Key Sources
+
+For the most promising URLs, fetch full content:
+
+**With firecrawl:**
+```
+firecrawl_scrape(url: "<url>")
+```
+
+**With exa:**
+```
+crawling_exa(url: "<url>", tokensNum: 5000)
+```
+
+Read 3-5 key sources in full for depth. Do not rely only on search snippets.
+
+### Step 5: Synthesize and Write Report
+
+Structure the report:
+
+```markdown
+# [Topic]: Research Report
+*Generated: [date] | Sources: [N] | Confidence: [High/Medium/Low]*
+
+## Executive Summary
+[3-5 sentence overview of key findings]
+
+## 1. [First Major Theme]
+[Findings with inline citations]
+- Key point ([Source Name](url))
+- Supporting data ([Source Name](url))
+
+## 2. [Second Major Theme]
+...
+
+## 3. [Third Major Theme]
+...
+
+## Key Takeaways
+- [Actionable insight 1]
+- [Actionable insight 2]
+- [Actionable insight 3]
+
+## Sources
+1. [Title](url) — [one-line summary]
+2. ...
+
+## Methodology
+Searched [N] queries across web and news. Analyzed [M] sources.
+Sub-questions investigated: [list]
+```
+
+### Step 6: Deliver
+
+- **Short topics**: Post the full report in chat
+- **Long reports**: Post the executive summary + key takeaways, save full report to a file
+
+## Parallel Research with Subagents
+
+For broad topics, use Claude Code's Task tool to parallelize:
+
+```
+Launch 3 research agents in parallel:
+1. Agent 1: Research sub-questions 1-2
+2. Agent 2: Research sub-questions 3-4
+3. Agent 3: Research sub-question 5 + cross-cutting themes
+```
+
+Each agent searches, reads sources, and returns findings. The main session synthesizes into the final report.
+
+## Quality Rules
+
+1. **Every claim needs a source.** No unsourced assertions.
+2. **Cross-reference.** If only one source says it, flag it as unverified.
+3. **Recency matters.** Prefer sources from the last 12 months.
+4. **Acknowledge gaps.** If you couldn't find good info on a sub-question, say so.
+5. **No hallucination.** If you don't know, say "insufficient data found."
+6. **Separate fact from inference.** Label estimates, projections, and opinions clearly.
+
+## Examples
+
+```
+"Research the current state of nuclear fusion energy"
+"Deep dive into Rust vs Go for backend services in 2026"
+"Research the best strategies for bootstrapping a SaaS business"
+"What's happening with the US housing market right now?"
+"Investigate the competitive landscape for AI code editors"
+```

.agents/skills/deep-research/agents/openai.yaml

@@ -0,0 +1,7 @@
+interface:
+  display_name: "Deep Research"
+  short_description: "Multi-source deep research with firecrawl and exa MCPs"
+  brand_color: "#6366F1"
+  default_prompt: "Research the given topic using firecrawl and exa, produce a cited report"
+policy:
+  allow_implicit_invocation: true

.agents/skills/dmux-workflows/SKILL.md

@@ -0,0 +1,144 @@
+---
+name: dmux-workflows
+description: Multi-agent orchestration using dmux (tmux pane manager for AI agents). Patterns for parallel agent workflows across Claude Code, Codex, OpenCode, and other harnesses. Use when running multiple agent sessions in parallel or coordinating multi-agent development workflows.
+origin: ECC
+---
+
+# dmux Workflows
+
+Orchestrate parallel AI agent sessions using dmux, a tmux pane manager for agent harnesses.
+
+## When to Activate
+
+- Running multiple agent sessions in parallel
+- Coordinating work across Claude Code, Codex, and other harnesses
+- Complex tasks that benefit from divide-and-conquer parallelism
+- User says "run in parallel", "split this work", "use dmux", or "multi-agent"
+
+## What is dmux
+
+dmux is a tmux-based orchestration tool that manages AI agent panes:
+- Press `n` to create a new pane with a prompt
+- Press `m` to merge pane output back to the main session
+- Supports: Claude Code, Codex, OpenCode, Cline, Gemini, Qwen
+
+**Install:** `npm install -g dmux` or see [github.com/standardagents/dmux](https://github.com/standardagents/dmux)
+
+## Quick Start
+
+```bash
+# Start dmux session
+dmux
+
+# Create agent panes (press 'n' in dmux, then type prompt)
+# Pane 1: "Implement the auth middleware in src/auth/"
+# Pane 2: "Write tests for the user service"
+# Pane 3: "Update API documentation"
+
+# Each pane runs its own agent session
+# Press 'm' to merge results back
+```
+
+## Workflow Patterns
+
+### Pattern 1: Research + Implement
+
+Split research and implementation into parallel tracks:
+
+```
+Pane 1 (Research): "Research best practices for rate limiting in Node.js.
+  Check current libraries, compare approaches, and write findings to
+  /tmp/rate-limit-research.md"
+
+Pane 2 (Implement): "Implement rate limiting middleware for our Express API.
+  Start with a basic token bucket, we'll refine after research completes."
+
+# After Pane 1 completes, merge findings into Pane 2's context
+```
+
+### Pattern 2: Multi-File Feature
+
+Parallelize work across independent files:
+
+```
+Pane 1: "Create the database schema and migrations for the billing feature"
+Pane 2: "Build the billing API endpoints in src/api/billing/"
+Pane 3: "Create the billing dashboard UI components"
+
+# Merge all, then do integration in main pane
+```
+
+### Pattern 3: Test + Fix Loop
+
+Run tests in one pane, fix in another:
+
+```
+Pane 1 (Watcher): "Run the test suite in watch mode. When tests fail,
+  summarize the failures."
+
+Pane 2 (Fixer): "Fix failing tests based on the error output from pane 1"
+```
+
+### Pattern 4: Cross-Harness
+
+Use different AI tools for different tasks:
+
+```
+Pane 1 (Claude Code): "Review the security of the auth module"
+Pane 2 (Codex): "Refactor the utility functions for performance"
+Pane 3 (Claude Code): "Write E2E tests for the checkout flow"
+```
+
+### Pattern 5: Code Review Pipeline
+
+Parallel review perspectives:
+
+```
+Pane 1: "Review src/api/ for security vulnerabilities"
+Pane 2: "Review src/api/ for performance issues"
+Pane 3: "Review src/api/ for test coverage gaps"
+
+# Merge all reviews into a single report
+```
+
+## Best Practices
+
+1. **Independent tasks only.** Don't parallelize tasks that depend on each other's output.
+2. **Clear boundaries.** Each pane should work on distinct files or concerns.
+3. **Merge strategically.** Review pane output before merging to avoid conflicts.
+4. **Use git worktrees.** For file-conflict-prone work, use separate worktrees per pane.
+5. **Resource awareness.** Each pane uses API tokens — keep total panes under 5-6.
+
+## Git Worktree Integration
+
+For tasks that touch overlapping files:
+
+```bash
+# Create worktrees for isolation
+git worktree add ../feature-auth feat/auth
+git worktree add ../feature-billing feat/billing
+
+# Run agents in separate worktrees
+# Pane 1: cd ../feature-auth && claude
+# Pane 2: cd ../feature-billing && claude
+
+# Merge branches when done
+git merge feat/auth
+git merge feat/billing
+```
+
+## Complementary Tools
+
+| Tool | What It Does | When to Use |
+|------|-------------|-------------|
+| **dmux** | tmux pane management for agents | Parallel agent sessions |
+| **Superset** | Terminal IDE for 10+ parallel agents | Large-scale orchestration |
+| **Claude Code Task tool** | In-process subagent spawning | Programmatic parallelism within a session |
+| **Codex multi-agent** | Built-in agent roles | Codex-specific parallel work |
+
+## Troubleshooting
+
+- **Pane not responding:** Check if the agent session is waiting for input. Use `m` to read output.
+- **Merge conflicts:** Use git worktrees to isolate file changes per pane.
+- **High token usage:** Reduce number of parallel panes. Each pane is a full agent session.
+- **tmux not found:** Install with `brew install tmux` (macOS) or `apt install tmux` (Linux).

.agents/skills/dmux-workflows/agents/openai.yaml

@@ -0,0 +1,7 @@
+interface:
+  display_name: "dmux Workflows"
+  short_description: "Multi-agent orchestration with dmux"
+  brand_color: "#14B8A6"
+  default_prompt: "Orchestrate parallel agent sessions using dmux pane manager"
+policy:
+  allow_implicit_invocation: true

.agents/skills/exa-search/SKILL.md

@@ -0,0 +1,174 @@
+---
+name: exa-search
+description: Neural search via Exa MCP for web, code, and company research. Use when the user needs web search, code examples, company intel, people lookup, or AI-powered deep research with Exa's neural search engine.
+origin: ECC
+---
+
+# Exa Search
+
+Neural search for web content, code, companies, and people via the Exa MCP server.
+
+## When to Activate
+
+- User needs current web information or news
+- Searching for code examples, API docs, or technical references
+- Researching companies, competitors, or market players
+- Finding professional profiles or people in a domain
+- Running background research for any development task
+- User says "search for", "look up", "find", or "what's the latest on"
+
+## MCP Requirement
+
+Exa MCP server must be configured. Add to `~/.claude.json`:
+
+```json
+"exa-web-search": {
+  "command": "npx",
+  "args": [
+    "-y",
+    "exa-mcp-server",
+    "tools=web_search_exa,web_search_advanced_exa,get_code_context_exa,crawling_exa,company_research_exa,people_search_exa,deep_researcher_start,deep_researcher_check"
+  ],
+  "env": { "EXA_API_KEY": "YOUR_EXA_API_KEY_HERE" }
+}
+```
+
+Get an API key at [exa.ai](https://exa.ai).
+
+## Core Tools
+
+### web_search_exa
+General web search for current information, news, or facts.
+
+```
+web_search_exa(query: "latest AI developments 2026", numResults: 5)
+```
+
+**Parameters:**
+
+| Param | Type | Default | Notes |
+|-------|------|---------|-------|
+| `query` | string | required | Search query |
+| `numResults` | number | 8 | Number of results |
+
+### web_search_advanced_exa
+Filtered search with domain and date constraints.
+
+```
+web_search_advanced_exa(
+  query: "React Server Components best practices",
+  numResults: 5,
+  includeDomains: ["github.com", "react.dev"],
+  startPublishedDate: "2025-01-01"
+)
+```
+
+**Parameters:**
+
+| Param | Type | Default | Notes |
+|-------|------|---------|-------|
+| `query` | string | required | Search query |
+| `numResults` | number | 8 | Number of results |
+| `includeDomains` | string[] | none | Limit to specific domains |
+| `excludeDomains` | string[] | none | Exclude specific domains |
+| `startPublishedDate` | string | none | ISO date filter (start) |
+| `endPublishedDate` | string | none | ISO date filter (end) |
+
+### get_code_context_exa
+Find code examples and documentation from GitHub, Stack Overflow, and docs sites.
+
+```
+get_code_context_exa(query: "Python asyncio patterns", tokensNum: 3000)
+```
+
+**Parameters:**
+
+| Param | Type | Default | Notes |
+|-------|------|---------|-------|
+| `query` | string | required | Code or API search query |
+| `tokensNum` | number | 5000 | Content tokens (1000-50000) |
+
+### company_research_exa
+Research companies for business intelligence and news.
+
+```
+company_research_exa(companyName: "Anthropic", numResults: 5)
+```
+
+**Parameters:**
+
+| Param | Type | Default | Notes |
+|-------|------|---------|-------|
+| `companyName` | string | required | Company name |
+| `numResults` | number | 5 | Number of results |
+
+### people_search_exa
+Find professional profiles and bios.
+
+```
+people_search_exa(query: "AI safety researchers at Anthropic", numResults: 5)
+```
+
+### crawling_exa
+Extract full page content from a URL.
+
+```
+crawling_exa(url: "https://example.com/article", tokensNum: 5000)
+```
+
+**Parameters:**
+
+| Param | Type | Default | Notes |
+|-------|------|---------|-------|
+| `url` | string | required | URL to extract |
+| `tokensNum` | number | 5000 | Content tokens |
+
+### deep_researcher_start / deep_researcher_check
+Start an AI research agent that runs asynchronously.
+
+```
+# Start research
+deep_researcher_start(query: "comprehensive analysis of AI code editors in 2026")
+
+# Check status (returns results when complete)
+deep_researcher_check(researchId: "<id from start>")
+```
+
+## Usage Patterns
+
+### Quick Lookup
+```
+web_search_exa(query: "Node.js 22 new features", numResults: 3)
+```
+
+### Code Research
+```
+get_code_context_exa(query: "Rust error handling patterns Result type", tokensNum: 3000)
+```
+
+### Company Due Diligence
+```
+company_research_exa(companyName: "Vercel", numResults: 5)
+web_search_advanced_exa(query: "Vercel funding valuation 2026", numResults: 3)
+```
+
+### Technical Deep Dive
+```
+# Start async research
+deep_researcher_start(query: "WebAssembly component model status and adoption")
+# ... do other work ...
+deep_researcher_check(researchId: "<id>")
+```
+
+## Tips
+
+- Use `web_search_exa` for broad queries, `web_search_advanced_exa` for filtered results
+- Lower `tokensNum` (1000-2000) for focused code snippets, higher (5000+) for comprehensive context
+- Combine `company_research_exa` with `web_search_advanced_exa` for thorough company analysis
+- Use `crawling_exa` to get full content from specific URLs found in search results
+- `deep_researcher_start` is best for comprehensive topics that benefit from AI synthesis
+
+## Related Skills
+
+- `deep-research` — Full research workflow using firecrawl + exa together
+- `market-research` — Business-oriented research with decision frameworks

.agents/skills/exa-search/agents/openai.yaml

@@ -0,0 +1,7 @@
+interface:
+  display_name: "Exa Search"
+  short_description: "Neural search via Exa MCP for web, code, and companies"
+  brand_color: "#8B5CF6"
+  default_prompt: "Search using Exa MCP tools for web content, code, or company research"
+policy:
+  allow_implicit_invocation: true

.agents/skills/fal-ai-media/SKILL.md

@@ -0,0 +1,277 @@
+---
+name: fal-ai-media
+description: Unified media generation via fal.ai MCP — image, video, and audio. Covers text-to-image (Nano Banana), text/image-to-video (Seedance, Kling, Veo 3), text-to-speech (CSM-1B), and video-to-audio (ThinkSound). Use when the user wants to generate images, videos, or audio with AI.
+origin: ECC
+---
+
+# fal.ai Media Generation
+
+Generate images, videos, and audio using fal.ai models via MCP.
+
+## When to Activate
+
+- User wants to generate images from text prompts
+- Creating videos from text or images
+- Generating speech, music, or sound effects
+- Any media generation task
+- User says "generate image", "create video", "text to speech", "make a thumbnail", or similar
+
+## MCP Requirement
+
+fal.ai MCP server must be configured. Add to `~/.claude.json`:
+
+```json
+"fal-ai": {
+  "command": "npx",
+  "args": ["-y", "fal-ai-mcp-server"],
+  "env": { "FAL_KEY": "YOUR_FAL_KEY_HERE" }
+}
+```
+
+Get an API key at [fal.ai](https://fal.ai).
+
+## MCP Tools
+
+The fal.ai MCP provides these tools:
+- `search` — Find available models by keyword
+- `find` — Get model details and parameters
+- `generate` — Run a model with parameters
+- `result` — Check async generation status
+- `status` — Check job status
+- `cancel` — Cancel a running job
+- `estimate_cost` — Estimate generation cost
+- `models` — List popular models
+- `upload` — Upload files for use as inputs
+
+---
+
+## Image Generation
+
+### Nano Banana 2 (Fast)
+Best for: quick iterations, drafts, text-to-image, image editing.
+
+```
+generate(
+  model_name: "fal-ai/nano-banana-2",
+  input: {
+    "prompt": "a futuristic cityscape at sunset, cyberpunk style",
+    "image_size": "landscape_16_9",
+    "num_images": 1,
+    "seed": 42
+  }
+)
+```
+
+### Nano Banana Pro (High Fidelity)
+Best for: production images, realism, typography, detailed prompts.
+
+```
+generate(
+  model_name: "fal-ai/nano-banana-pro",
+  input: {
+    "prompt": "professional product photo of wireless headphones on marble surface, studio lighting",
+    "image_size": "square",
+    "num_images": 1,
+    "guidance_scale": 7.5
+  }
+)
+```
+
+### Common Image Parameters
+
+| Param | Type | Options | Notes |
+|-------|------|---------|-------|
+| `prompt` | string | required | Describe what you want |
+| `image_size` | string | `square`, `portrait_4_3`, `landscape_16_9`, `portrait_16_9`, `landscape_4_3` | Aspect ratio |
+| `num_images` | number | 1-4 | How many to generate |
+| `seed` | number | any integer | Reproducibility |
+| `guidance_scale` | number | 1-20 | How closely to follow the prompt (higher = more literal) |
+
+### Image Editing
+Use Nano Banana 2 with an input image for inpainting, outpainting, or style transfer:
+
+```
+# First upload the source image
+upload(file_path: "/path/to/image.png")
+
+# Then generate with image input
+generate(
+  model_name: "fal-ai/nano-banana-2",
+  input: {
+    "prompt": "same scene but in watercolor style",
+    "image_url": "<uploaded_url>",
+    "image_size": "landscape_16_9"
+  }
+)
+```
+
+---
+
+## Video Generation
+
+### Seedance 1.0 Pro (ByteDance)
+Best for: text-to-video, image-to-video with high motion quality.
+
+```
+generate(
+  model_name: "fal-ai/seedance-1-0-pro",
+  input: {
+    "prompt": "a drone flyover of a mountain lake at golden hour, cinematic",
+    "duration": "5s",
+    "aspect_ratio": "16:9",
+    "seed": 42
+  }
+)
+```
+
+### Kling Video v3 Pro
+Best for: text/image-to-video with native audio generation.
+
+```
+generate(
+  model_name: "fal-ai/kling-video/v3/pro",
+  input: {
+    "prompt": "ocean waves crashing on a rocky coast, dramatic clouds",
+    "duration": "5s",
+    "aspect_ratio": "16:9"
+  }
+)
+```
+
+### Veo 3 (Google DeepMind)
+Best for: video with generated sound, high visual quality.
+
+```
+generate(
+  model_name: "fal-ai/veo-3",
+  input: {
+    "prompt": "a bustling Tokyo street market at night, neon signs, crowd noise",
+    "aspect_ratio": "16:9"
+  }
+)
+```
+
+### Image-to-Video
+Start from an existing image:
+
+```
+generate(
+  model_name: "fal-ai/seedance-1-0-pro",
+  input: {
+    "prompt": "camera slowly zooms out, gentle wind moves the trees",
+    "image_url": "<uploaded_image_url>",
+    "duration": "5s"
+  }
+)
+```
+
+### Video Parameters
+
+| Param | Type | Options | Notes |
+|-------|------|---------|-------|
+| `prompt` | string | required | Describe the video |
+| `duration` | string | `"5s"`, `"10s"` | Video length |
+| `aspect_ratio` | string | `"16:9"`, `"9:16"`, `"1:1"` | Frame ratio |
+| `seed` | number | any integer | Reproducibility |
+| `image_url` | string | URL | Source image for image-to-video |
+
+---
+
+## Audio Generation
+
+### CSM-1B (Conversational Speech)
+Text-to-speech with natural, conversational quality.
+
+```
+generate(
+  model_name: "fal-ai/csm-1b",
+  input: {
+    "text": "Hello, welcome to the demo. Let me show you how this works.",
+    "speaker_id": 0
+  }
+)
+```
+
+### ThinkSound (Video-to-Audio)
+Generate matching audio from video content.
+
+```
+generate(
+  model_name: "fal-ai/thinksound",
+  input: {
+    "video_url": "<video_url>",
+    "prompt": "ambient forest sounds with birds chirping"
+  }
+)
+```
+
+### ElevenLabs (via API, no MCP)
+For professional voice synthesis, use ElevenLabs directly:
+
+```python
+import os
+import requests
+
+resp = requests.post(
+    "https://api.elevenlabs.io/v1/text-to-speech/<voice_id>",
+    headers={
+        "xi-api-key": os.environ["ELEVENLABS_API_KEY"],
+        "Content-Type": "application/json"
+    },
+    json={
+        "text": "Your text here",
+        "model_id": "eleven_turbo_v2_5",
+        "voice_settings": {"stability": 0.5, "similarity_boost": 0.75}
+    }
+)
+with open("output.mp3", "wb") as f:
+    f.write(resp.content)
+```
+
+### VideoDB Generative Audio
+If VideoDB is configured, use its generative audio:
+
+```python
+# Voice generation
+audio = coll.generate_voice(text="Your narration here", voice="alloy")
+
+# Music generation
+music = coll.generate_music(prompt="upbeat electronic background music", duration=30)
+
+# Sound effects
+sfx = coll.generate_sound_effect(prompt="thunder crack followed by rain")
+```
+
+---
+
+## Cost Estimation
+
+Before generating, check estimated cost:
+
+```
+estimate_cost(model_name: "fal-ai/nano-banana-pro", input: {...})
+```
+
+## Model Discovery
+
+Find models for specific tasks:
+
+```
+search(query: "text to video")
+find(model_name: "fal-ai/seedance-1-0-pro")
+models()
+```
+
+## Tips
+
+- Use `seed` for reproducible results when iterating on prompts
+- Start with lower-cost models (Nano Banana 2) for prompt iteration, then switch to Pro for finals
+- For video, keep prompts descriptive but concise — focus on motion and scene
+- Image-to-video produces more controlled results than pure text-to-video
+- Check `estimate_cost` before running expensive video generations
+
+## Related Skills
+
+- `videodb` — Video processing, editing, and streaming
+- `video-editing` — AI-powered video editing workflows
+- `content-engine` — Content creation for social platforms

.agents/skills/fal-ai-media/agents/openai.yaml

@@ -0,0 +1,7 @@
+interface:
+  display_name: "fal.ai Media"
+  short_description: "AI image, video, and audio generation via fal.ai"
+  brand_color: "#F43F5E"
+  default_prompt: "Generate images, videos, or audio using fal.ai models"
+policy:
+  allow_implicit_invocation: true

.agents/skills/video-editing/SKILL.md

@@ -0,0 +1,308 @@
+---
+name: video-editing
+description: AI-assisted video editing workflows for cutting, structuring, and augmenting real footage. Covers the full pipeline from raw capture through FFmpeg, Remotion, ElevenLabs, fal.ai, and final polish in Descript or CapCut. Use when the user wants to edit video, cut footage, create vlogs, or build video content.
+origin: ECC
+---
+
+# Video Editing
+
+AI-assisted editing for real footage. Not generation from prompts. Editing existing video fast.
+
+## When to Activate
+
+- User wants to edit, cut, or structure video footage
+- Turning long recordings into short-form content
+- Building vlogs, tutorials, or demo videos from raw capture
+- Adding overlays, subtitles, music, or voiceover to existing video
+- Reframing video for different platforms (YouTube, TikTok, Instagram)
+- User says "edit video", "cut this footage", "make a vlog", or "video workflow"
+
+## Core Thesis
+
+AI video editing is useful when you stop asking it to create the whole video and start using it to compress, structure, and augment real footage. The value is not generation. The value is compression.
+
+## The Pipeline
+
+```
+Screen Studio / raw footage
+  → Claude / Codex
+  → FFmpeg
+  → Remotion
+  → ElevenLabs / fal.ai
+  → Descript or CapCut
+```
+
+Each layer has a specific job. Do not skip layers. Do not try to make one tool do everything.
+
+## Layer 1: Capture (Screen Studio / Raw Footage)
+
+Collect the source material:
+- **Screen Studio**: polished screen recordings for app demos, coding sessions, browser workflows
+- **Raw camera footage**: vlog footage, interviews, event recordings
+- **Desktop capture via VideoDB**: session recording with real-time context (see `videodb` skill)
+
+Output: raw files ready for organization.
+
+## Layer 2: Organization (Claude / Codex)
+
+Use Claude Code or Codex to:
+- **Transcribe and label**: generate transcript, identify topics and themes
+- **Plan structure**: decide what stays, what gets cut, what order works
+- **Identify dead sections**: find pauses, tangents, repeated takes
+- **Generate edit decision list**: timestamps for cuts, segments to keep
+- **Scaffold FFmpeg and Remotion code**: generate the commands and compositions
+
+```
+Example prompt:
+"Here's the transcript of a 4-hour recording. Identify the 8 strongest segments
+for a 24-minute vlog. Give me FFmpeg cut commands for each segment."
+```
+
+This layer is about structure, not final creative taste.
+
+## Layer 3: Deterministic Cuts (FFmpeg)
+
+FFmpeg handles the boring but critical work: splitting, trimming, concatenating, and preprocessing.
+
+### Extract segment by timestamp
+
+```bash
+ffmpeg -i raw.mp4 -ss 00:12:30 -to 00:15:45 -c copy segment_01.mp4
+```
+
+### Batch cut from edit decision list
+
+```bash
+#!/bin/bash
+# cuts.txt: start,end,label
+while IFS=, read -r start end label; do
+  ffmpeg -i raw.mp4 -ss "$start" -to "$end" -c copy "segments/${label}.mp4"
+done < cuts.txt
+```
+
+### Concatenate segments
+
+```bash
+# Create file list
+for f in segments/*.mp4; do echo "file '$f'"; done > concat.txt
+ffmpeg -f concat -safe 0 -i concat.txt -c copy assembled.mp4
+```
+
+### Create proxy for faster editing
+
+```bash
+ffmpeg -i raw.mp4 -vf "scale=960:-2" -c:v libx264 -preset ultrafast -crf 28 proxy.mp4
+```
+
+### Extract audio for transcription
+
+```bash
+ffmpeg -i raw.mp4 -vn -acodec pcm_s16le -ar 16000 audio.wav
+```
+
+### Normalize audio levels
+
+```bash
+ffmpeg -i segment.mp4 -af loudnorm=I=-16:TP=-1.5:LRA=11 -c:v copy normalized.mp4
+```
+
+## Layer 4: Programmable Composition (Remotion)
+
+Remotion turns editing problems into composable code. Use it for things that traditional editors make painful:
+
+### When to use Remotion
+
+- Overlays: text, images, branding, lower thirds
+- Data visualizations: charts, stats, animated numbers
+- Motion graphics: transitions, explainer animations
+- Composable scenes: reusable templates across videos
+- Product demos: annotated screenshots, UI highlights
+
+### Basic Remotion composition
+
+```tsx
+import { AbsoluteFill, Sequence, Video, useCurrentFrame } from "remotion";
+
+export const VlogComposition: React.FC = () => {
+  const frame = useCurrentFrame();
+
+  return (
+    <AbsoluteFill>
+      {/* Main footage */}
+      <Sequence from={0} durationInFrames={300}>
+        <Video src="/segments/intro.mp4" />
+      </Sequence>
+
+      {/* Title overlay */}
+      <Sequence from={30} durationInFrames={90}>
+        <AbsoluteFill style={{
+          justifyContent: "center",
+          alignItems: "center",
+        }}>
+          <h1 style={{
+            fontSize: 72,
+            color: "white",
+            textShadow: "2px 2px 8px rgba(0,0,0,0.8)",
+          }}>
+            The AI Editing Stack
+          </h1>
+        </AbsoluteFill>
+      </Sequence>
+
+      {/* Next segment */}
+      <Sequence from={300} durationInFrames={450}>
+        <Video src="/segments/demo.mp4" />
+      </Sequence>
+    </AbsoluteFill>
+  );
+};
+```
+
+### Render output
+
+```bash
+npx remotion render src/index.ts VlogComposition output.mp4
+```
+
+See the [Remotion docs](https://www.remotion.dev/docs) for detailed patterns and API reference.
+
+## Layer 5: Generated Assets (ElevenLabs / fal.ai)
+
+Generate only what you need. Do not generate the whole video.
+
+### Voiceover with ElevenLabs
+
+```python
+import os
+import requests
+
+resp = requests.post(
+    f"https://api.elevenlabs.io/v1/text-to-speech/{voice_id}",
+    headers={
+        "xi-api-key": os.environ["ELEVENLABS_API_KEY"],
+        "Content-Type": "application/json"
+    },
+    json={
+        "text": "Your narration text here",
+        "model_id": "eleven_turbo_v2_5",
+        "voice_settings": {"stability": 0.5, "similarity_boost": 0.75}
+    }
+)
+with open("voiceover.mp3", "wb") as f:
+    f.write(resp.content)
+```
+
+### Music and SFX with fal.ai
+
+Use the `fal-ai-media` skill for:
+- Background music generation
+- Sound effects (ThinkSound model for video-to-audio)
+- Transition sounds
+
+### Generated visuals with fal.ai
+
+Use for insert shots, thumbnails, or b-roll that doesn't exist:
+```
+generate(model_name: "fal-ai/nano-banana-pro", input: {
+  "prompt": "professional thumbnail for tech vlog, dark background, code on screen",
+  "image_size": "landscape_16_9"
+})
+```
+
+### VideoDB generative audio
+
+If VideoDB is configured:
+```python
+voiceover = coll.generate_voice(text="Narration here", voice="alloy")
+music = coll.generate_music(prompt="lo-fi background for coding vlog", duration=120)
+sfx = coll.generate_sound_effect(prompt="subtle whoosh transition")
+```
+
+## Layer 6: Final Polish (Descript / CapCut)
+
+The last layer is human. Use a traditional editor for:
+- **Pacing**: adjust cuts that feel too fast or slow
+- **Captions**: auto-generated, then manually cleaned
+- **Color grading**: basic correction and mood
+- **Final audio mix**: balance voice, music, and SFX levels
+- **Export**: platform-specific formats and quality settings
+
+This is where taste lives. AI clears the repetitive work. You make the final calls.
+
+## Social Media Reframing
+
+Different platforms need different aspect ratios:
+
+| Platform | Aspect Ratio | Resolution |
+|----------|-------------|------------|
+| YouTube | 16:9 | 1920x1080 |
+| TikTok / Reels | 9:16 | 1080x1920 |
+| Instagram Feed | 1:1 | 1080x1080 |
+| X / Twitter | 16:9 or 1:1 | 1280x720 or 720x720 |
+
+### Reframe with FFmpeg
+
+```bash
+# 16:9 to 9:16 (center crop)
+ffmpeg -i input.mp4 -vf "crop=ih*9/16:ih,scale=1080:1920" vertical.mp4
+
+# 16:9 to 1:1 (center crop)
+ffmpeg -i input.mp4 -vf "crop=ih:ih,scale=1080:1080" square.mp4
+```
+
+### Reframe with VideoDB
+
+```python
+# Smart reframe (AI-guided subject tracking)
+reframed = video.reframe(start=0, end=60, target="vertical", mode=ReframeMode.smart)
+```
+
+## Scene Detection and Auto-Cut
+
+### FFmpeg scene detection
+
+```bash
+# Detect scene changes (threshold 0.3 = moderate sensitivity)
+ffmpeg -i input.mp4 -vf "select='gt(scene,0.3)',showinfo" -vsync vfr -f null - 2>&1 | grep showinfo
+```
+
+### Silence detection for auto-cut
+
+```bash
+# Find silent segments (useful for cutting dead air)
+ffmpeg -i input.mp4 -af silencedetect=noise=-30dB:d=2 -f null - 2>&1 | grep silence
+```
+
+### Highlight extraction
+
+Use Claude to analyze transcript + scene timestamps:
+```
+"Given this transcript with timestamps and these scene change points,
+identify the 5 most engaging 30-second clips for social media."
+```
+
+## What Each Tool Does Best
+
+| Tool | Strength | Weakness |
+|------|----------|----------|
+| Claude / Codex | Organization, planning, code generation | Not the creative taste layer |
+| FFmpeg | Deterministic cuts, batch processing, format conversion | No visual editing UI |
+| Remotion | Programmable overlays, composable scenes, reusable templates | Learning curve for non-devs |
+| Screen Studio | Polished screen recordings immediately | Only screen capture |
+| ElevenLabs | Voice, narration, music, SFX | Not the center of the workflow |
+| Descript / CapCut | Final pacing, captions, polish | Manual, not automatable |
+
+## Key Principles
+
+1. **Edit, don't generate.** This workflow is for cutting real footage, not creating from prompts.
+2. **Structure before style.** Get the story right in Layer 2 before touching anything visual.
+3. **FFmpeg is the backbone.** Boring but critical. Where long footage becomes manageable.
+4. **Remotion for repeatability.** If you'll do it more than once, make it a Remotion component.
+5. **Generate selectively.** Only use AI generation for assets that don't exist, not for everything.
+6. **Taste is the last layer.** AI clears repetitive work. You make the final creative calls.
+
+## Related Skills
+
+- `fal-ai-media` — AI image, video, and audio generation
+- `videodb` — Server-side video processing, indexing, and streaming
+- `content-engine` — Platform-native content distribution

.agents/skills/video-editing/agents/openai.yaml

@@ -0,0 +1,7 @@
+interface:
+  display_name: "Video Editing"
+  short_description: "AI-assisted video editing for real footage"
+  brand_color: "#EF4444"
+  default_prompt: "Edit video using AI-assisted pipeline: organize, cut, compose, generate assets, polish"
+policy:
+  allow_implicit_invocation: true

.agents/skills/x-api/SKILL.md

@@ -0,0 +1,214 @@
+---
+name: x-api
+description: X/Twitter API integration for posting tweets, threads, reading timelines, search, and analytics. Covers OAuth auth patterns, rate limits, and platform-native content posting. Use when the user wants to interact with X programmatically.
+origin: ECC
+---
+
+# X API
+
+Programmatic interaction with X (Twitter) for posting, reading, searching, and analytics.
+
+## When to Activate
+
+- User wants to post tweets or threads programmatically
+- Reading timeline, mentions, or user data from X
+- Searching X for content, trends, or conversations
+- Building X integrations or bots
+- Analytics and engagement tracking
+- User says "post to X", "tweet", "X API", or "Twitter API"
+
+## Authentication
+
+### OAuth 2.0 (App-Only / User Context)
+
+Best for: read-heavy operations, search, public data.
+
+```bash
+# Environment setup
+export X_BEARER_TOKEN="your-bearer-token"
+```
+
+```python
+import os
+import requests
+
+bearer = os.environ["X_BEARER_TOKEN"]
+headers = {"Authorization": f"Bearer {bearer}"}
+
+# Search recent tweets
+resp = requests.get(
+    "https://api.x.com/2/tweets/search/recent",
+    headers=headers,
+    params={"query": "claude code", "max_results": 10}
+)
+tweets = resp.json()
+```
+
+### OAuth 1.0a (User Context)
+
+Required for: posting tweets, managing account, DMs.
+
+```bash
+# Environment setup — source before use
+export X_API_KEY="your-api-key"
+export X_API_SECRET="your-api-secret"
+export X_ACCESS_TOKEN="your-access-token"
+export X_ACCESS_SECRET="your-access-secret"
+```
+
+```python
+import os
+from requests_oauthlib import OAuth1Session
+
+oauth = OAuth1Session(
+    os.environ["X_API_KEY"],
+    client_secret=os.environ["X_API_SECRET"],
+    resource_owner_key=os.environ["X_ACCESS_TOKEN"],
+    resource_owner_secret=os.environ["X_ACCESS_SECRET"],
+)
+```
+
+## Core Operations
+
+### Post a Tweet
+
+```python
+resp = oauth.post(
+    "https://api.x.com/2/tweets",
+    json={"text": "Hello from Claude Code"}
+)
+resp.raise_for_status()
+tweet_id = resp.json()["data"]["id"]
+```
+
+### Post a Thread
+
+```python
+def post_thread(oauth, tweets: list[str]) -> list[str]:
+    ids = []
+    reply_to = None
+    for text in tweets:
+        payload = {"text": text}
+        if reply_to:
+            payload["reply"] = {"in_reply_to_tweet_id": reply_to}
+        resp = oauth.post("https://api.x.com/2/tweets", json=payload)
+        resp.raise_for_status()
+        tweet_id = resp.json()["data"]["id"]
+        ids.append(tweet_id)
+        reply_to = tweet_id
+    return ids
+```
+
+### Read User Timeline
+
+```python
+resp = requests.get(
+    f"https://api.x.com/2/users/{user_id}/tweets",
+    headers=headers,
+    params={
+        "max_results": 10,
+        "tweet.fields": "created_at,public_metrics",
+    }
+)
+```
+
+### Search Tweets
+
+```python
+resp = requests.get(
+    "https://api.x.com/2/tweets/search/recent",
+    headers=headers,
+    params={
+        "query": "from:affaanmustafa -is:retweet",
+        "max_results": 10,
+        "tweet.fields": "public_metrics,created_at",
+    }
+)
+```
+
+### Get User by Username
+
+```python
+resp = requests.get(
+    "https://api.x.com/2/users/by/username/affaanmustafa",
+    headers=headers,
+    params={"user.fields": "public_metrics,description,created_at"}
+)
+```
+
+### Upload Media and Post
+
+```python
+# Media upload uses v1.1 endpoint
+
+# Step 1: Upload media
+media_resp = oauth.post(
+    "https://upload.twitter.com/1.1/media/upload.json",
+    files={"media": open("image.png", "rb")}
+)
+media_id = media_resp.json()["media_id_string"]
+
+# Step 2: Post with media
+resp = oauth.post(
+    "https://api.x.com/2/tweets",
+    json={"text": "Check this out", "media": {"media_ids": [media_id]}}
+)
+```
+
+## Rate Limits Reference
+
+| Endpoint | Limit | Window |
+|----------|-------|--------|
+| POST /2/tweets | 200 | 15 min |
+| GET /2/tweets/search/recent | 450 | 15 min |
+| GET /2/users/:id/tweets | 1500 | 15 min |
+| GET /2/users/by/username | 300 | 15 min |
+| POST media/upload | 415 | 15 min |
+
+Always check `x-rate-limit-remaining` and `x-rate-limit-reset` headers.
+
+```python
+import time
+
+remaining = int(resp.headers.get("x-rate-limit-remaining", 0))
+if remaining < 5:
+    reset = int(resp.headers.get("x-rate-limit-reset", 0))
+    wait = max(0, reset - int(time.time()))
+    print(f"Rate limit approaching. Resets in {wait}s")
+```
+
+## Error Handling
+
+```python
+resp = oauth.post("https://api.x.com/2/tweets", json={"text": content})
+if resp.status_code == 201:
+    return resp.json()["data"]["id"]
+elif resp.status_code == 429:
+    reset = int(resp.headers["x-rate-limit-reset"])
+    raise Exception(f"Rate limited. Resets at {reset}")
+elif resp.status_code == 403:
+    raise Exception(f"Forbidden: {resp.json().get('detail', 'check permissions')}")
+else:
+    raise Exception(f"X API error {resp.status_code}: {resp.text}")
+```
+
+## Security
+
+- **Never hardcode tokens.** Use environment variables or `.env` files.
+- **Never commit `.env` files.** Add to `.gitignore`.
+- **Rotate tokens** if exposed. Regenerate at developer.x.com.
+- **Use read-only tokens** when write access is not needed.
+- **Store OAuth secrets securely** — not in source code or logs.
+
+## Integration with Content Engine
+
+Use `content-engine` skill to generate platform-native content, then post via X API:
+1. Generate content with content-engine (X platform format)
+2. Validate length (280 chars for single tweet)
+3. Post via X API using patterns above
+4. Track engagement via public_metrics
+
+## Related Skills
+
+- `content-engine` — Generate platform-native content for X
+- `crosspost` — Distribute content across X, LinkedIn, and other platforms

.agents/skills/x-api/agents/openai.yaml

@@ -0,0 +1,7 @@
+interface:
+  display_name: "X API"
+  short_description: "X/Twitter API integration for posting, threads, and analytics"
+  brand_color: "#000000"
+  default_prompt: "Use X API to post tweets, threads, or retrieve timeline and search data"
+policy:
+  allow_implicit_invocation: true

.claude-plugin/README.md

@@ -3,3 +3,15 @@
 If you plan to edit `.claude-plugin/plugin.json`, be aware that the Claude plugin validator enforces several **undocumented but strict constraints** that can cause installs to fail with vague errors (for example, `agents: Invalid input`). In particular, component fields must be arrays, `agents` must use explicit file paths rather than directories, and a `version` field is required for reliable validation and installation.
 
 These constraints are not obvious from public examples and have caused repeated installation failures in the past. They are documented in detail in `.claude-plugin/PLUGIN_SCHEMA_NOTES.md`, which should be reviewed before making any changes to the plugin manifest.
+
+### Custom Endpoints and Gateways
+
+ECC does not override Claude Code transport settings. If Claude Code is configured to run through an official LLM gateway or a compatible custom endpoint, the plugin continues to work because hooks, commands, and skills execute locally after the CLI starts successfully.
+
+Use Claude Code's own environment/configuration for transport selection, for example:
+
+```bash
+export ANTHROPIC_BASE_URL=https://your-gateway.example.com
+export ANTHROPIC_AUTH_TOKEN=your-token
+claude
+```

.claude/homunculus/instincts/inherited/everything-claude-code-instincts.yaml

@@ -0,0 +1,162 @@
+# Curated instincts for affaan-m/everything-claude-code
+# Import with: /instinct-import .claude/homunculus/instincts/inherited/everything-claude-code-instincts.yaml
+
+---
+id: everything-claude-code-conventional-commits
+trigger: "when making a commit in everything-claude-code"
+confidence: 0.9
+domain: git
+source: repo-curation
+source_repo: affaan-m/everything-claude-code
+---
+
+# Everything Claude Code Conventional Commits
+
+## Action
+
+Use conventional commit prefixes such as `feat:`, `fix:`, `docs:`, `test:`, `chore:`, and `refactor:`.
+
+## Evidence
+
+- Mainline history consistently uses conventional commit subjects.
+- Release and changelog automation expect readable commit categorization.
+
+---
+id: everything-claude-code-commit-length
+trigger: "when writing a commit subject in everything-claude-code"
+confidence: 0.8
+domain: git
+source: repo-curation
+source_repo: affaan-m/everything-claude-code
+---
+
+# Everything Claude Code Commit Length
+
+## Action
+
+Keep commit subjects concise and close to the repository norm of about 70 characters.
+
+## Evidence
+
+- Recent history clusters around ~70 characters, not ~50.
+- Short, descriptive subjects read well in release notes and PR summaries.
+
+---
+id: everything-claude-code-js-file-naming
+trigger: "when creating a new JavaScript or TypeScript module in everything-claude-code"
+confidence: 0.85
+domain: code-style
+source: repo-curation
+source_repo: affaan-m/everything-claude-code
+---
+
+# Everything Claude Code JS File Naming
+
+## Action
+
+Prefer camelCase for JavaScript and TypeScript module filenames, and keep skill or command directories in kebab-case.
+
+## Evidence
+
+- `scripts/` and test helpers mostly use camelCase module names.
+- `skills/` and `commands/` directories use kebab-case consistently.
+
+---
+id: everything-claude-code-test-runner
+trigger: "when adding or updating tests in everything-claude-code"
+confidence: 0.9
+domain: testing
+source: repo-curation
+source_repo: affaan-m/everything-claude-code
+---
+
+# Everything Claude Code Test Runner
+
+## Action
+
+Use the repository's existing Node-based test flow: targeted `*.test.js` files first, then `node tests/run-all.js` or `npm test` for broader verification.
+
+## Evidence
+
+- The repo uses `tests/run-all.js` as the central test orchestrator.
+- Test files follow the `*.test.js` naming pattern across hook, CI, and integration coverage.
+
+---
+id: everything-claude-code-hooks-change-set
+trigger: "when modifying hooks or hook-adjacent behavior in everything-claude-code"
+confidence: 0.88
+domain: workflow
+source: repo-curation
+source_repo: affaan-m/everything-claude-code
+---
+
+# Everything Claude Code Hooks Change Set
+
+## Action
+
+Update the hook script, its configuration, its tests, and its user-facing documentation together.
+
+## Evidence
+
+- Hook fixes routinely span `hooks/hooks.json`, `scripts/hooks/`, `tests/hooks/`, `tests/integration/`, and `hooks/README.md`.
+- Partial hook changes are a common source of regressions and stale docs.
+
+---
+id: everything-claude-code-cross-platform-sync
+trigger: "when shipping a user-visible feature across ECC surfaces"
+confidence: 0.9
+domain: workflow
+source: repo-curation
+source_repo: affaan-m/everything-claude-code
+---
+
+# Everything Claude Code Cross Platform Sync
+
+## Action
+
+Treat the root repo as the source of truth, then mirror shipped changes to `.cursor/`, `.codex/`, `.opencode/`, and `.agents/` only where the feature actually exists.
+
+## Evidence
+
+- ECC maintains multiple harness-specific surfaces with overlapping but not identical files.
+- The safest workflow is root-first followed by explicit parity updates.
+
+---
+id: everything-claude-code-release-sync
+trigger: "when preparing a release for everything-claude-code"
+confidence: 0.86
+domain: workflow
+source: repo-curation
+source_repo: affaan-m/everything-claude-code
+---
+
+# Everything Claude Code Release Sync
+
+## Action
+
+Keep package versions, plugin manifests, and release-facing docs synchronized before publishing.
+
+## Evidence
+
+- Release work spans `package.json`, `.claude-plugin/*`, `.opencode/package.json`, and release-note content.
+- Version drift causes broken update paths and confusing install surfaces.
+
+---
+id: everything-claude-code-learning-curation
+trigger: "when importing or evolving instincts for everything-claude-code"
+confidence: 0.84
+domain: workflow
+source: repo-curation
+source_repo: affaan-m/everything-claude-code
+---
+
+# Everything Claude Code Learning Curation
+
+## Action
+
+Prefer a small set of accurate instincts over bulk-generated, duplicated, or contradictory instincts.
+
+## Evidence
+
+- Auto-generated instinct dumps can duplicate rules, widen triggers too far, or preserve placeholder detector output.
+- Curated instincts are easier to import, audit, and trust during continuous-learning workflows.

.claude/skills/everything-claude-code/SKILL.md

@@ -0,0 +1,97 @@
+# Everything Claude Code
+
+Use this skill when working inside the `everything-claude-code` repository and you need repo-specific guidance instead of generic coding advice.
+
+Optional companion instincts live at `.claude/homunculus/instincts/inherited/everything-claude-code-instincts.yaml` for teams using `continuous-learning-v2`.
+
+## When to Use
+
+Activate this skill when the task touches one or more of these areas:
+- cross-platform parity across Claude Code, Cursor, Codex, and OpenCode
+- hook scripts, hook docs, or hook tests
+- skills, commands, agents, or rules that must stay synchronized across surfaces
+- release work such as version bumps, changelog updates, or plugin metadata updates
+- continuous-learning or instinct workflows inside this repository
+
+## How It Works
+
+### 1. Follow the repo's development contract
+
+- Use conventional commits such as `feat:`, `fix:`, `docs:`, `test:`, `chore:`.
+- Keep commit subjects concise and close to the repo norm of about 70 characters.
+- Prefer camelCase for JavaScript and TypeScript module filenames.
+- Use kebab-case for skill directories and command filenames.
+- Keep test files on the existing `*.test.js` pattern.
+
+### 2. Treat the root repo as the source of truth
+
+Start from the root implementation, then mirror changes where they are intentionally shipped.
+
+Typical mirror targets:
+- `.cursor/`
+- `.codex/`
+- `.opencode/`
+- `.agents/`
+
+Do not assume every `.claude/` artifact needs a cross-platform copy. Only mirror files that are part of the shipped multi-platform surface.
+
+### 3. Update hooks with tests and docs together
+
+When changing hook behavior:
+1. update `hooks/hooks.json` or the relevant script in `scripts/hooks/`
+2. update matching tests in `tests/hooks/` or `tests/integration/`
+3. update `hooks/README.md` if behavior or configuration changed
+4. verify parity for `.cursor/hooks/` and `.opencode/plugins/` when applicable
+
+### 4. Keep release metadata in sync
+
+When preparing a release, verify the same version is reflected anywhere it is surfaced:
+- `package.json`
+- `.claude-plugin/plugin.json`
+- `.claude-plugin/marketplace.json`
+- `.opencode/package.json`
+- release notes or changelog entries when the release process expects them
+
+### 5. Be explicit about continuous-learning changes
+
+If the task touches `skills/continuous-learning-v2/` or imported instincts:
+- prefer accurate, low-noise instincts over auto-generated bulk output
+- keep instinct files importable by `instinct-cli.py`
+- remove duplicated or contradictory instincts instead of layering more guidance on top
+
+## Examples
+
+### Naming examples
+
+```text
+skills/continuous-learning-v2/SKILL.md
+commands/update-docs.md
+scripts/hooks/session-start.js
+tests/hooks/hooks.test.js
+```
+
+### Commit examples
+
+```text
+fix: harden session summary extraction on Stop hook
+docs: align Codex config examples with current schema
+test: cover Windows formatter fallback behavior
+```
+
+### Skill update checklist
+
+```text
+1. Update the root skill or command.
+2. Mirror it only where that surface is shipped.
+3. Run targeted tests first, then the broader suite if behavior changed.
+4. Review docs and release notes for user-visible changes.
+```
+
+### Release checklist
+
+```text
+1. Bump package and plugin versions.
+2. Run npm test.
+3. Verify platform-specific manifests.
+4. Publish the release notes with a human-readable summary.
+```

.codex/AGENTS.md

@@ -6,10 +6,10 @@ This supplements the root `AGENTS.md` with Codex-specific guidance.
 
 | Task Type | Recommended Model |
 |-----------|------------------|
-| Routine coding, tests, formatting | o4-mini |
-| Complex features, architecture | o3 |
-| Debugging, refactoring | o4-mini |
-| Security review | o3 |
+| Routine coding, tests, formatting | GPT 5.4 |
+| Complex features, architecture | GPT 5.4 |
+| Debugging, refactoring | GPT 5.4 |
+| Security review | GPT 5.4 |
 
 ## Skills Discovery
 
@@ -34,10 +34,31 @@ Available skills:
 - strategic-compact — Context management
 - api-design — REST API design patterns
 - verification-loop — Build, test, lint, typecheck, security
+- deep-research — Multi-source research with firecrawl and exa MCPs
+- exa-search — Neural search via Exa MCP for web, code, and companies
+- claude-api — Anthropic Claude API patterns and SDKs
+- x-api — X/Twitter API integration for posting, threads, and analytics
+- crosspost — Multi-platform content distribution
+- fal-ai-media — AI image/video/audio generation via fal.ai
+- dmux-workflows — Multi-agent orchestration with dmux
 
 ## MCP Servers
 
-Configure in `~/.codex/config.toml` under `[mcp_servers]`. See `.codex/config.toml` for reference configuration with GitHub, Context7, Memory, and Sequential Thinking servers.
+Treat the project-local `.codex/config.toml` as the default Codex baseline for ECC. The current ECC baseline enables GitHub, Context7, Exa, Memory, Playwright, and Sequential Thinking; add heavier extras in `~/.codex/config.toml` only when a task actually needs them.
+
+## Multi-Agent Support
+
+Codex now supports multi-agent workflows behind the experimental `features.multi_agent` flag.
+
+- Enable it in `.codex/config.toml` with `[features] multi_agent = true`
+- Define project-local roles under `[agents.<name>]`
+- Point each role at a TOML layer under `.codex/agents/`
+- Use `/agent` inside Codex CLI to inspect and steer child agents
+
+Sample role configs in this repo:
+- `.codex/agents/explorer.toml` — read-only evidence gathering
+- `.codex/agents/reviewer.toml` — correctness/security review
+- `.codex/agents/docs-researcher.toml` — API and release-note verification
 
 ## Key Differences from Claude Code
 
@@ -47,9 +68,9 @@ Configure in `~/.codex/config.toml` under `[mcp_servers]`. See `.codex/config.to
 | Context file | CLAUDE.md + AGENTS.md | AGENTS.md only |
 | Skills | Skills loaded via plugin | `.agents/skills/` directory |
 | Commands | `/slash` commands | Instruction-based |
-| Agents | Subagent Task tool | Single agent model |
+| Agents | Subagent Task tool | Multi-agent via `/agent` and `[agents.<name>]` roles |
 | Security | Hook-based enforcement | Instruction + sandbox |
-| MCP | Full support | Command-based only |
+| MCP | Full support | Supported via `config.toml` and `codex mcp add` |
 
 ## Security Without Hooks
 

.codex/agents/docs-researcher.toml

@@ -0,0 +1,9 @@
+model = "gpt-5.4"
+model_reasoning_effort = "medium"
+sandbox_mode = "read-only"
+
+developer_instructions = """
+Verify APIs, framework behavior, and release-note claims against primary documentation before changes land.
+Cite the exact docs or file paths that support each claim.
+Do not invent undocumented behavior.
+"""

.codex/agents/explorer.toml

@@ -0,0 +1,9 @@
+model = "gpt-5.4"
+model_reasoning_effort = "medium"
+sandbox_mode = "read-only"
+
+developer_instructions = """
+Stay in exploration mode.
+Trace the real execution path, cite files and symbols, and avoid proposing fixes unless the parent agent asks for them.
+Prefer targeted search and file reads over broad scans.
+"""

.codex/agents/reviewer.toml

@@ -0,0 +1,9 @@
+model = "gpt-5.4"
+model_reasoning_effort = "high"
+sandbox_mode = "read-only"
+
+developer_instructions = """
+Review like an owner.
+Prioritize correctness, security, behavioral regressions, and missing tests.
+Lead with concrete findings and avoid style-only feedback unless it hides a real bug.
+"""

.codex/config.toml

@@ -1,42 +1,40 @@
-# Everything Claude Code (ECC) — Codex CLI Reference Configuration
+#:schema https://developers.openai.com/codex/config-schema.json
+
+# Everything Claude Code (ECC) — Codex Reference Configuration
 #
-# Copy this file to ~/.codex/config.toml to apply globally.
-# Or keep it in your project root for project-level config.
+# Copy this file to ~/.codex/config.toml for global defaults, or keep it in
+# the project root as .codex/config.toml for project-local settings.
 #
-# Docs: https://github.com/openai/codex
+# Official docs:
+# - https://developers.openai.com/codex/config-reference
+# - https://developers.openai.com/codex/multi-agent
 
 # Model selection
-model = "o4-mini"
-model_provider = "openai"
+# Leave `model` and `model_provider` unset so Codex CLI uses its current
+# built-in defaults. Uncomment and pin them only if you intentionally want
+# repo-local or global model overrides.
 
-# Permissions
-[permissions]
-# "untrusted" = no writes, "on-request" = ask per action, "never" = full auto
+# Top-level runtime settings (current Codex schema)
 approval_policy = "on-request"
-# "off", "workspace-read", "workspace-write", "danger-full-access"
 sandbox_mode = "workspace-write"
+web_search = "live"
 
-# Notifications (macOS)
-[notify]
-command = "terminal-notifier -title 'Codex ECC' -message 'Task completed!' -sound default"
-on_complete = true
+# External notifications receive a JSON payload on stdin.
+notify = [
+  "terminal-notifier",
+  "-title", "Codex ECC",
+  "-message", "Task completed!",
+  "-sound", "default",
+]
 
-# History - persistent instructions applied to every session
-[history]
-# These are prepended to every conversation
-persistent_instructions = """
-Follow ECC principles:
-1. Test-Driven Development (TDD) - write tests first, 80%+ coverage required
-2. Immutability - always create new objects, never mutate
-3. Security-First - validate all inputs, no hardcoded secrets
-4. Conventional commits: feat|fix|refactor|docs|test|chore|perf|ci: description
-5. File organization: many small files (200-400 lines, 800 max)
-6. Error handling: handle at every level, never swallow errors
-7. Input validation: schema-based validation at system boundaries
-"""
+# Prefer AGENTS.md and project-local .codex/AGENTS.md for instructions.
+# model_instructions_file replaces built-in instructions instead of AGENTS.md,
+# so leave it unset unless you intentionally want a single override file.
+# model_instructions_file = "/absolute/path/to/instructions.md"
 
-# MCP Servers
-# Codex supports command-based MCP servers
+# MCP servers
+# Keep the default project set lean. API-backed servers inherit credentials from
+# the launching environment or can be supplied by a user-level ~/.codex/config.toml.
 [mcp_servers.github]
 command = "npx"
 args = ["-y", "@modelcontextprotocol/server-github"]
@@ -45,10 +43,17 @@ args = ["-y", "@modelcontextprotocol/server-github"]
 command = "npx"
 args = ["-y", "@upstash/context7-mcp@latest"]
 
+[mcp_servers.exa]
+url = "https://mcp.exa.ai/mcp"
+
 [mcp_servers.memory]
 command = "npx"
 args = ["-y", "@modelcontextprotocol/server-memory"]
 
+[mcp_servers.playwright]
+command = "npx"
+args = ["-y", "@playwright/mcp@latest", "--extension"]
+
 [mcp_servers.sequential-thinking]
 command = "npx"
 args = ["-y", "@modelcontextprotocol/server-sequential-thinking"]
@@ -62,19 +67,41 @@ args = ["-y", "@modelcontextprotocol/server-sequential-thinking"]
 # command = "npx"
 # args = ["-y", "firecrawl-mcp"]
 #
-# [mcp_servers.railway]
+# [mcp_servers.fal-ai]
 # command = "npx"
-# args = ["-y", "@anthropic/railway-mcp"]
+# args = ["-y", "fal-ai-mcp-server"]
+#
+# [mcp_servers.cloudflare]
+# command = "npx"
+# args = ["-y", "@cloudflare/mcp-server-cloudflare"]
 
-# Features
 [features]
-web_search_request = true
+# Codex multi-agent support is experimental as of March 2026.
+multi_agent = true
 
-# Profiles — switch with CODEX_PROFILE=<name>
+# Profiles — switch with `codex -p <name>`
 [profiles.strict]
 approval_policy = "on-request"
-sandbox_mode = "workspace-read"
+sandbox_mode = "read-only"
+web_search = "cached"
 
 [profiles.yolo]
 approval_policy = "never"
 sandbox_mode = "workspace-write"
+web_search = "live"
+
+[agents]
+max_threads = 6
+max_depth = 1
+
+[agents.explorer]
+description = "Read-only codebase explorer for gathering evidence before changes are proposed."
+config_file = "agents/explorer.toml"
+
+[agents.reviewer]
+description = "PR reviewer focused on correctness, security, and missing tests."
+config_file = "agents/reviewer.toml"
+
+[agents.docs_researcher]
+description = "Documentation specialist that verifies APIs, framework behavior, and release notes."
+config_file = "agents/docs-researcher.toml"

.cursor/hooks/before-shell-execution.js

@@ -1,72 +1,41 @@
 #!/usr/bin/env node
 const { readStdin, hookEnabled } = require('./adapter');
+const { splitShellSegments } = require('../../scripts/lib/shell-split');
 
-function splitShellSegments(command) {
-  const segments = [];
-  let current = '';
-  let quote = null;
+readStdin()
+  .then(raw => {
+    try {
+      const input = JSON.parse(raw || '{}');
+      const cmd = String(input.command || input.args?.command || '');
 
-  for (let i = 0; i < command.length; i++) {
-    const ch = command[i];
-    if (quote) {
-      if (ch === quote) quote = null;
-      current += ch;
-      continue;
-    }
-
-    if (ch === '"' || ch === "'") {
-      quote = ch;
-      current += ch;
-      continue;
-    }
-
-    const next = command[i + 1] || '';
-    if (ch === ';' || (ch === '&' && next === '&') || (ch === '|' && next === '|') || (ch === '&' && next !== '&')) {
-      if (current.trim()) segments.push(current.trim());
-      current = '';
-      if ((ch === '&' && next === '&') || (ch === '|' && next === '|')) i++;
-      continue;
-    }
-
-    current += ch;
-  }
-
-  if (current.trim()) segments.push(current.trim());
-  return segments;
-}
-
-readStdin().then(raw => {
-  try {
-    const input = JSON.parse(raw || '{}');
-    const cmd = String(input.command || input.args?.command || '');
-
-    if (hookEnabled('pre:bash:dev-server-block', ['standard', 'strict']) && process.platform !== 'win32') {
-      const segments = splitShellSegments(cmd);
-      const tmuxLauncher = /^\s*tmux\s+(new|new-session|new-window|split-window)\b/;
-      const devPattern = /\b(npm\s+run\s+dev|pnpm(?:\s+run)?\s+dev|yarn\s+dev|bun\s+run\s+dev)\b/;
-      const hasBlockedDev = segments.some(segment => devPattern.test(segment) && !tmuxLauncher.test(segment));
-      if (hasBlockedDev) {
-        console.error('[ECC] BLOCKED: Dev server must run in tmux for log access');
-        console.error('[ECC] Use: tmux new-session -d -s dev "npm run dev"');
-        process.exit(2);
+      if (hookEnabled('pre:bash:dev-server-block', ['standard', 'strict']) && process.platform !== 'win32') {
+        const segments = splitShellSegments(cmd);
+        const tmuxLauncher = /^\s*tmux\s+(new|new-session|new-window|split-window)\b/;
+        const devPattern = /\b(npm\s+run\s+dev|pnpm(?:\s+run)?\s+dev|yarn\s+dev|bun\s+run\s+dev)\b/;
+        const hasBlockedDev = segments.some(segment => devPattern.test(segment) && !tmuxLauncher.test(segment));
+        if (hasBlockedDev) {
+          console.error('[ECC] BLOCKED: Dev server must run in tmux for log access');
+          console.error('[ECC] Use: tmux new-session -d -s dev "npm run dev"');
+          process.exit(2);
+        }
       }
+
+      if (
+        hookEnabled('pre:bash:tmux-reminder', ['strict']) &&
+        process.platform !== 'win32' &&
+        !process.env.TMUX &&
+        /(npm (install|test)|pnpm (install|test)|yarn (install|test)?|bun (install|test)|cargo build|make\b|docker\b|pytest|vitest|playwright)/.test(cmd)
+      ) {
+        console.error('[ECC] Consider running in tmux for session persistence');
+      }
+
+      if (hookEnabled('pre:bash:git-push-reminder', ['strict']) && /\bgit\s+push\b/.test(cmd)) {
+        console.error('[ECC] Review changes before push: git diff origin/main...HEAD');
+      }
+    } catch {
+      // noop
     }
 
-    if (
-      hookEnabled('pre:bash:tmux-reminder', ['strict']) &&
-      process.platform !== 'win32' &&
-      !process.env.TMUX &&
-      /(npm (install|test)|pnpm (install|test)|yarn (install|test)?|bun (install|test)|cargo build|make\b|docker\b|pytest|vitest|playwright)/.test(cmd)
-    ) {
-      console.error('[ECC] Consider running in tmux for session persistence');
-    }
-
-    if (hookEnabled('pre:bash:git-push-reminder', ['strict']) && /\bgit\s+push\b/.test(cmd)) {
-      console.error('[ECC] Review changes before push: git diff origin/main...HEAD');
-    }
-  } catch {
-    // noop
-  }
-
-  process.stdout.write(raw);
-}).catch(() => process.exit(0));
+    process.stdout.write(raw);
+  })
+  .catch(() => process.exit(0));

.cursor/rules/kotlin-coding-style.md

@@ -0,0 +1,39 @@
+---
+description: "Kotlin coding style extending common rules"
+globs: ["**/*.kt", "**/*.kts", "**/build.gradle.kts"]
+alwaysApply: false
+---
+# Kotlin Coding Style
+
+> This file extends the common coding style rule with Kotlin-specific content.
+
+## Formatting
+
+- Auto-formatting via **ktfmt** or **ktlint** (configured in `kotlin-hooks.md`)
+- Use trailing commas in multiline declarations
+
+## Immutability
+
+The global immutability requirement is enforced in the common coding style rule.
+For Kotlin specifically:
+
+- Prefer `val` over `var`
+- Use immutable collection types (`List`, `Map`, `Set`)
+- Use `data class` with `copy()` for immutable updates
+
+## Null Safety
+
+- Avoid `!!` -- use `?.`, `?:`, `require`, or `checkNotNull`
+- Handle platform types explicitly at Java interop boundaries
+
+## Expression Bodies
+
+Prefer expression bodies for single-expression functions:
+
+```kotlin
+fun isAdult(age: Int): Boolean = age >= 18
+```
+
+## Reference
+
+See skill: `kotlin-patterns` for comprehensive Kotlin idioms and patterns.

.cursor/rules/kotlin-hooks.md

@@ -0,0 +1,16 @@
+---
+description: "Kotlin hooks extending common rules"
+globs: ["**/*.kt", "**/*.kts", "**/build.gradle.kts"]
+alwaysApply: false
+---
+# Kotlin Hooks
+
+> This file extends the common hooks rule with Kotlin-specific content.
+
+## PostToolUse Hooks
+
+Configure in `~/.claude/settings.json`:
+
+- **ktfmt/ktlint**: Auto-format `.kt` and `.kts` files after edit
+- **detekt**: Run static analysis after editing Kotlin files
+- **./gradlew build**: Verify compilation after changes

.cursor/rules/kotlin-patterns.md

@@ -0,0 +1,50 @@
+---
+description: "Kotlin patterns extending common rules"
+globs: ["**/*.kt", "**/*.kts", "**/build.gradle.kts"]
+alwaysApply: false
+---
+# Kotlin Patterns
+
+> This file extends the common patterns rule with Kotlin-specific content.
+
+## Sealed Classes
+
+Use sealed classes/interfaces for exhaustive type hierarchies:
+
+```kotlin
+sealed class Result<out T> {
+    data class Success<T>(val data: T) : Result<T>()
+    data class Failure(val error: AppError) : Result<Nothing>()
+}
+```
+
+## Extension Functions
+
+Add behavior without inheritance, scoped to where they're used:
+
+```kotlin
+fun String.toSlug(): String =
+    lowercase().replace(Regex("[^a-z0-9\\s-]"), "").replace(Regex("\\s+"), "-")
+```
+
+## Scope Functions
+
+- `let`: Transform nullable or scoped result
+- `apply`: Configure an object
+- `also`: Side effects
+- Avoid nesting scope functions
+
+## Dependency Injection
+
+Use Koin for DI in Ktor projects:
+
+```kotlin
+val appModule = module {
+    single<UserRepository> { ExposedUserRepository(get()) }
+    single { UserService(get()) }
+}
+```
+
+## Reference
+
+See skill: `kotlin-patterns` for comprehensive Kotlin patterns including coroutines, DSL builders, and delegation.

.cursor/rules/kotlin-security.md

@@ -0,0 +1,58 @@
+---
+description: "Kotlin security extending common rules"
+globs: ["**/*.kt", "**/*.kts", "**/build.gradle.kts"]
+alwaysApply: false
+---
+# Kotlin Security
+
+> This file extends the common security rule with Kotlin-specific content.
+
+## Secret Management
+
+```kotlin
+val apiKey = System.getenv("API_KEY")
+    ?: throw IllegalStateException("API_KEY not configured")
+```
+
+## SQL Injection Prevention
+
+Always use Exposed's parameterized queries:
+
+```kotlin
+// Good: Parameterized via Exposed DSL
+UsersTable.selectAll().where { UsersTable.email eq email }
+
+// Bad: String interpolation in raw SQL
+exec("SELECT * FROM users WHERE email = '$email'")
+```
+
+## Authentication
+
+Use Ktor's Auth plugin with JWT:
+
+```kotlin
+install(Authentication) {
+    jwt("jwt") {
+        verifier(
+            JWT.require(Algorithm.HMAC256(secret))
+                .withAudience(audience)
+                .withIssuer(issuer)
+                .build()
+        )
+        validate { credential ->
+            val payload = credential.payload
+            if (payload.audience.contains(audience) &&
+                payload.issuer == issuer &&
+                payload.subject != null) {
+                JWTPrincipal(payload)
+            } else {
+                null
+            }
+        }
+    }
+}
+```
+
+## Null Safety as Security
+
+Kotlin's type system prevents null-related vulnerabilities -- avoid `!!` to maintain this guarantee.

.cursor/rules/kotlin-testing.md

@@ -0,0 +1,38 @@
+---
+description: "Kotlin testing extending common rules"
+globs: ["**/*.kt", "**/*.kts", "**/build.gradle.kts"]
+alwaysApply: false
+---
+# Kotlin Testing
+
+> This file extends the common testing rule with Kotlin-specific content.
+
+## Framework
+
+Use **Kotest** with spec styles (StringSpec, FunSpec, BehaviorSpec) and **MockK** for mocking.
+
+## Coroutine Testing
+
+Use `runTest` from `kotlinx-coroutines-test`:
+
+```kotlin
+test("async operation completes") {
+    runTest {
+        val result = service.fetchData()
+        result.shouldNotBeEmpty()
+    }
+}
+```
+
+## Coverage
+
+Use **Kover** for coverage reporting:
+
+```bash
+./gradlew koverHtmlReport
+./gradlew koverVerify
+```
+
+## Reference
+
+See skill: `kotlin-testing` for detailed Kotest patterns, MockK usage, and property-based testing.

.cursor/rules/php-coding-style.md

@@ -0,0 +1,25 @@
+---
+description: "PHP coding style extending common rules"
+globs: ["**/*.php", "**/composer.json"]
+alwaysApply: false
+---
+# PHP Coding Style
+
+> This file extends the common coding style rule with PHP specific content.
+
+## Standards
+
+- Follow **PSR-12** formatting and naming conventions.
+- Prefer `declare(strict_types=1);` in application code.
+- Use scalar type hints, return types, and typed properties everywhere new code permits.
+
+## Immutability
+
+- Prefer immutable DTOs and value objects for data crossing service boundaries.
+- Use `readonly` properties or immutable constructors for request/response payloads where possible.
+- Keep arrays for simple maps; promote business-critical structures into explicit classes.
+
+## Formatting
+
+- Use **PHP-CS-Fixer** or **Laravel Pint** for formatting.
+- Use **PHPStan** or **Psalm** for static analysis.

.cursor/rules/php-hooks.md

@@ -0,0 +1,21 @@
+---
+description: "PHP hooks extending common rules"
+globs: ["**/*.php", "**/composer.json", "**/phpstan.neon", "**/phpstan.neon.dist", "**/psalm.xml"]
+alwaysApply: false
+---
+# PHP Hooks
+
+> This file extends the common hooks rule with PHP specific content.
+
+## PostToolUse Hooks
+
+Configure in `~/.claude/settings.json`:
+
+- **Pint / PHP-CS-Fixer**: Auto-format edited `.php` files.
+- **PHPStan / Psalm**: Run static analysis after PHP edits in typed codebases.
+- **PHPUnit / Pest**: Run targeted tests for touched files or modules when edits affect behavior.
+
+## Warnings
+
+- Warn on `var_dump`, `dd`, `dump`, or `die()` left in edited files.
+- Warn when edited PHP files add raw SQL or disable CSRF/session protections.

.cursor/rules/php-patterns.md

@@ -0,0 +1,23 @@
+---
+description: "PHP patterns extending common rules"
+globs: ["**/*.php", "**/composer.json"]
+alwaysApply: false
+---
+# PHP Patterns
+
+> This file extends the common patterns rule with PHP specific content.
+
+## Thin Controllers, Explicit Services
+
+- Keep controllers focused on transport: auth, validation, serialization, status codes.
+- Move business rules into application/domain services that are easy to test without HTTP bootstrapping.
+
+## DTOs and Value Objects
+
+- Replace shape-heavy associative arrays with DTOs for requests, commands, and external API payloads.
+- Use value objects for money, identifiers, and constrained concepts.
+
+## Dependency Injection
+
+- Depend on interfaces or narrow service contracts, not framework globals.
+- Pass collaborators through constructors so services are testable without service-locator lookups.

.cursor/rules/php-security.md

@@ -0,0 +1,24 @@
+---
+description: "PHP security extending common rules"
+globs: ["**/*.php", "**/composer.lock", "**/composer.json"]
+alwaysApply: false
+---
+# PHP Security
+
+> This file extends the common security rule with PHP specific content.
+
+## Database Safety
+
+- Use prepared statements (`PDO`, Doctrine, Eloquent query builder) for all dynamic queries.
+- Scope ORM mass-assignment carefully and whitelist writable fields.
+
+## Secrets and Dependencies
+
+- Load secrets from environment variables or a secret manager, never from committed config files.
+- Run `composer audit` in CI and review package trust before adding dependencies.
+
+## Auth and Session Safety
+
+- Use `password_hash()` / `password_verify()` for password storage.
+- Regenerate session identifiers after authentication and privilege changes.
+- Enforce CSRF protection on state-changing web requests.

.cursor/rules/php-testing.md

@@ -0,0 +1,26 @@
+---
+description: "PHP testing extending common rules"
+globs: ["**/*.php", "**/phpunit.xml", "**/phpunit.xml.dist", "**/composer.json"]
+alwaysApply: false
+---
+# PHP Testing
+
+> This file extends the common testing rule with PHP specific content.
+
+## Framework
+
+Use **PHPUnit** as the default test framework. **Pest** is also acceptable when the project already uses it.
+
+## Coverage
+
+```bash
+vendor/bin/phpunit --coverage-text
+# or
+vendor/bin/pest --coverage
+```
+
+## Test Organization
+
+- Separate fast unit tests from framework/database integration tests.
+- Use factory/builders for fixtures instead of large hand-written arrays.
+- Keep HTTP/controller tests focused on transport and validation; move business rules into service-level tests.

.github/workflows/ci.yml

@@ -156,6 +156,9 @@ jobs:
         with:
           node-version: '20.x'
 
+      - name: Install validation dependencies
+        run: npm ci --ignore-scripts
+
       - name: Validate agents
         run: node scripts/ci/validate-agents.js
         continue-on-error: false

.github/workflows/reusable-validate.yml

@@ -24,6 +24,9 @@ jobs:
         with:
           node-version: ${{ inputs.node-version }}
 
+      - name: Install validation dependencies
+        run: npm ci --ignore-scripts
+
       - name: Validate agents
         run: node scripts/ci/validate-agents.js
 

.gitignore

@@ -23,6 +23,7 @@ node_modules/
 
 # Build output
 dist/
+coverage/
 
 # Python
 __pycache__/
@@ -40,3 +41,4 @@ examples/sessions/*.tmp
 
 # Local drafts
 marketing/
+.dmux/

.opencode/MIGRATION.md

@@ -148,7 +148,7 @@ You are an expert planning specialist...
       "description": "Expert planning specialist...",
       "mode": "subagent",
       "model": "anthropic/claude-opus-4-5",
-      "prompt": "{file:.opencode/prompts/agents/planner.txt}",
+      "prompt": "{file:prompts/agents/planner.txt}",
       "tools": { "read": true, "bash": true }
     }
   }
@@ -213,7 +213,7 @@ Create a detailed implementation plan for: $ARGUMENTS
 ```json
 {
   "instructions": [
-    ".opencode/instructions/INSTRUCTIONS.md",
+    "instructions/INSTRUCTIONS.md",
     "rules/common/security.md",
     "rules/common/coding-style.md"
   ]
@@ -297,6 +297,15 @@ Then in your `opencode.json`:
 }
 ```
 
+This only loads the published ECC OpenCode plugin module (hooks/events and exported plugin tools).
+It does **not** automatically inject ECC's full `agent`, `command`, or `instructions` config into your project.
+
+If you want the full ECC OpenCode workflow surface, use the repository's bundled `.opencode/opencode.json` as your base config or copy these pieces into your project:
+- `.opencode/commands/`
+- `.opencode/prompts/`
+- `.opencode/instructions/INSTRUCTIONS.md`
+- the `agent` and `command` sections from `.opencode/opencode.json`
+
 ## Troubleshooting
 
 ### Configuration Not Loading
@@ -322,6 +331,7 @@ Then in your `opencode.json`:
 1. Verify the command is defined in `opencode.json` or as `.md` file in `.opencode/commands/`
 2. Check the referenced agent exists
 3. Ensure the template uses `$ARGUMENTS` for user input
+4. If you installed only `plugin: ["ecc-universal"]`, note that npm plugin install does not auto-add ECC commands or agents to your project config
 
 ## Best Practices
 

.opencode/README.md

@@ -32,7 +32,16 @@ Add to your `opencode.json`:
   "plugin": ["ecc-universal"]
 }
 ```
-After installation, the `ecc-install` CLI becomes available:
+
+This loads the ECC OpenCode plugin module from npm:
+- hook/event integrations
+- bundled custom tools exported by the plugin
+
+It does **not** auto-register the full ECC command/agent/instruction catalog in your project config. For the full OpenCode setup, either:
+- run OpenCode inside this repository, or
+- copy the relevant `.opencode/commands/`, `.opencode/prompts/`, `.opencode/instructions/`, and the `instructions`, `agent`, and `command` config entries into your own project
+
+After installation, the `ecc-install` CLI is also available:
 
 ```bash
 npx ecc-install typescript
@@ -180,7 +189,7 @@ Full configuration in `opencode.json`:
   "$schema": "https://opencode.ai/config.json",
   "model": "anthropic/claude-sonnet-4-5",
   "small_model": "anthropic/claude-haiku-4-5",
-  "plugin": ["./.opencode/plugins"],
+  "plugin": ["./plugins"],
   "instructions": [
     "skills/tdd-workflow/SKILL.md",
     "skills/security-review/SKILL.md"

.opencode/index.ts

@@ -1,12 +1,10 @@
 /**
  * Everything Claude Code (ECC) Plugin for OpenCode
  *
- * This package provides a complete OpenCode plugin with:
- * - 13 specialized agents (planner, architect, code-reviewer, etc.)
- * - 31 commands (/plan, /tdd, /code-review, etc.)
+ * This package provides the published ECC OpenCode plugin module:
  * - Plugin hooks (auto-format, TypeScript check, console.log warning, env injection, etc.)
  * - Custom tools (run-tests, check-coverage, security-audit, format-code, lint-check, git-summary)
- * - 37 skills (coding-standards, security-review, tdd-workflow, etc.)
+ * - Bundled reference config/assets for the wider ECC OpenCode setup
  *
  * Usage:
  *
@@ -22,6 +20,10 @@
  * }
  * ```
  *
+ * That enables the published plugin module only. For ECC commands, agents,
+ * prompts, and instructions, use this repository's `.opencode/opencode.json`
+ * as a base or copy the bundled `.opencode/` assets into your project.
+ *
  * Option 2: Clone and use directly
  * ```bash
  * git clone https://github.com/affaan-m/everything-claude-code
@@ -51,6 +53,7 @@ export const metadata = {
     agents: 13,
     commands: 31,
     skills: 37,
+    configAssets: true,
     hookEvents: [
       "file.edited",
       "tool.execute.before",

.opencode/opencode.json

@@ -6,7 +6,7 @@
   "instructions": [
     "AGENTS.md",
     "CONTRIBUTING.md",
-    ".opencode/instructions/INSTRUCTIONS.md",
+    "instructions/INSTRUCTIONS.md",
     "skills/tdd-workflow/SKILL.md",
     "skills/security-review/SKILL.md",
     "skills/coding-standards/SKILL.md",
@@ -20,7 +20,7 @@
     "skills/eval-harness/SKILL.md"
   ],
   "plugin": [
-    "./.opencode/plugins"
+    "./plugins"
   ],
   "agent": {
     "build": {
@@ -38,7 +38,7 @@
       "description": "Expert planning specialist for complex features and refactoring. Use for implementation planning, architectural changes, or complex refactoring.",
       "mode": "subagent",
       "model": "anthropic/claude-opus-4-5",
-      "prompt": "{file:.opencode/prompts/agents/planner.txt}",
+      "prompt": "{file:prompts/agents/planner.txt}",
       "tools": {
         "read": true,
         "bash": true,
@@ -50,7 +50,7 @@
       "description": "Software architecture specialist for system design, scalability, and technical decision-making.",
       "mode": "subagent",
       "model": "anthropic/claude-opus-4-5",
-      "prompt": "{file:.opencode/prompts/agents/architect.txt}",
+      "prompt": "{file:prompts/agents/architect.txt}",
       "tools": {
         "read": true,
         "bash": true,
@@ -62,7 +62,7 @@
       "description": "Expert code review specialist. Reviews code for quality, security, and maintainability. Use immediately after writing or modifying code.",
       "mode": "subagent",
       "model": "anthropic/claude-opus-4-5",
-      "prompt": "{file:.opencode/prompts/agents/code-reviewer.txt}",
+      "prompt": "{file:prompts/agents/code-reviewer.txt}",
       "tools": {
         "read": true,
         "bash": true,
@@ -74,7 +74,7 @@
       "description": "Security vulnerability detection and remediation specialist. Use after writing code that handles user input, authentication, API endpoints, or sensitive data.",
       "mode": "subagent",
       "model": "anthropic/claude-opus-4-5",
-      "prompt": "{file:.opencode/prompts/agents/security-reviewer.txt}",
+      "prompt": "{file:prompts/agents/security-reviewer.txt}",
       "tools": {
         "read": true,
         "bash": true,
@@ -86,7 +86,7 @@
       "description": "Test-Driven Development specialist enforcing write-tests-first methodology. Use when writing new features, fixing bugs, or refactoring code. Ensures 80%+ test coverage.",
       "mode": "subagent",
       "model": "anthropic/claude-opus-4-5",
-      "prompt": "{file:.opencode/prompts/agents/tdd-guide.txt}",
+      "prompt": "{file:prompts/agents/tdd-guide.txt}",
       "tools": {
         "read": true,
         "write": true,
@@ -98,7 +98,7 @@
       "description": "Build and TypeScript error resolution specialist. Use when build fails or type errors occur. Fixes build/type errors only with minimal diffs.",
       "mode": "subagent",
       "model": "anthropic/claude-opus-4-5",
-      "prompt": "{file:.opencode/prompts/agents/build-error-resolver.txt}",
+      "prompt": "{file:prompts/agents/build-error-resolver.txt}",
       "tools": {
         "read": true,
         "write": true,
@@ -110,7 +110,7 @@
       "description": "End-to-end testing specialist using Playwright. Generates, maintains, and runs E2E tests for critical user flows.",
       "mode": "subagent",
       "model": "anthropic/claude-opus-4-5",
-      "prompt": "{file:.opencode/prompts/agents/e2e-runner.txt}",
+      "prompt": "{file:prompts/agents/e2e-runner.txt}",
       "tools": {
         "read": true,
         "write": true,
@@ -122,7 +122,7 @@
       "description": "Documentation and codemap specialist. Use for updating codemaps and documentation.",
       "mode": "subagent",
       "model": "anthropic/claude-opus-4-5",
-      "prompt": "{file:.opencode/prompts/agents/doc-updater.txt}",
+      "prompt": "{file:prompts/agents/doc-updater.txt}",
       "tools": {
         "read": true,
         "write": true,
@@ -134,7 +134,7 @@
       "description": "Dead code cleanup and consolidation specialist. Use for removing unused code, duplicates, and refactoring.",
       "mode": "subagent",
       "model": "anthropic/claude-opus-4-5",
-      "prompt": "{file:.opencode/prompts/agents/refactor-cleaner.txt}",
+      "prompt": "{file:prompts/agents/refactor-cleaner.txt}",
       "tools": {
         "read": true,
         "write": true,
@@ -146,7 +146,7 @@
       "description": "Expert Go code reviewer specializing in idiomatic Go, concurrency patterns, error handling, and performance.",
       "mode": "subagent",
       "model": "anthropic/claude-opus-4-5",
-      "prompt": "{file:.opencode/prompts/agents/go-reviewer.txt}",
+      "prompt": "{file:prompts/agents/go-reviewer.txt}",
       "tools": {
         "read": true,
         "bash": true,
@@ -158,7 +158,7 @@
       "description": "Go build, vet, and compilation error resolution specialist. Fixes Go build errors with minimal changes.",
       "mode": "subagent",
       "model": "anthropic/claude-opus-4-5",
-      "prompt": "{file:.opencode/prompts/agents/go-build-resolver.txt}",
+      "prompt": "{file:prompts/agents/go-build-resolver.txt}",
       "tools": {
         "read": true,
         "write": true,
@@ -170,7 +170,7 @@
       "description": "PostgreSQL database specialist for query optimization, schema design, security, and performance. Incorporates Supabase best practices.",
       "mode": "subagent",
       "model": "anthropic/claude-opus-4-5",
-      "prompt": "{file:.opencode/prompts/agents/database-reviewer.txt}",
+      "prompt": "{file:prompts/agents/database-reviewer.txt}",
       "tools": {
         "read": true,
         "write": true,
@@ -182,135 +182,135 @@
   "command": {
     "plan": {
       "description": "Create a detailed implementation plan for complex features",
-      "template": "{file:.opencode/commands/plan.md}\n\n$ARGUMENTS",
+      "template": "{file:commands/plan.md}\n\n$ARGUMENTS",
       "agent": "planner",
       "subtask": true
     },
     "tdd": {
       "description": "Enforce TDD workflow with 80%+ test coverage",
-      "template": "{file:.opencode/commands/tdd.md}\n\n$ARGUMENTS",
+      "template": "{file:commands/tdd.md}\n\n$ARGUMENTS",
       "agent": "tdd-guide",
       "subtask": true
     },
     "code-review": {
       "description": "Review code for quality, security, and maintainability",
-      "template": "{file:.opencode/commands/code-review.md}\n\n$ARGUMENTS",
+      "template": "{file:commands/code-review.md}\n\n$ARGUMENTS",
       "agent": "code-reviewer",
       "subtask": true
     },
     "security": {
       "description": "Run comprehensive security review",
-      "template": "{file:.opencode/commands/security.md}\n\n$ARGUMENTS",
+      "template": "{file:commands/security.md}\n\n$ARGUMENTS",
       "agent": "security-reviewer",
       "subtask": true
     },
     "build-fix": {
       "description": "Fix build and TypeScript errors with minimal changes",
-      "template": "{file:.opencode/commands/build-fix.md}\n\n$ARGUMENTS",
+      "template": "{file:commands/build-fix.md}\n\n$ARGUMENTS",
       "agent": "build-error-resolver",
       "subtask": true
     },
     "e2e": {
       "description": "Generate and run E2E tests with Playwright",
-      "template": "{file:.opencode/commands/e2e.md}\n\n$ARGUMENTS",
+      "template": "{file:commands/e2e.md}\n\n$ARGUMENTS",
       "agent": "e2e-runner",
       "subtask": true
     },
     "refactor-clean": {
       "description": "Remove dead code and consolidate duplicates",
-      "template": "{file:.opencode/commands/refactor-clean.md}\n\n$ARGUMENTS",
+      "template": "{file:commands/refactor-clean.md}\n\n$ARGUMENTS",
       "agent": "refactor-cleaner",
       "subtask": true
     },
     "orchestrate": {
       "description": "Orchestrate multiple agents for complex tasks",
-      "template": "{file:.opencode/commands/orchestrate.md}\n\n$ARGUMENTS",
+      "template": "{file:commands/orchestrate.md}\n\n$ARGUMENTS",
       "agent": "planner",
       "subtask": true
     },
     "learn": {
       "description": "Extract patterns and learnings from session",
-      "template": "{file:.opencode/commands/learn.md}\n\n$ARGUMENTS"
+      "template": "{file:commands/learn.md}\n\n$ARGUMENTS"
     },
     "checkpoint": {
       "description": "Save verification state and progress",
-      "template": "{file:.opencode/commands/checkpoint.md}\n\n$ARGUMENTS"
+      "template": "{file:commands/checkpoint.md}\n\n$ARGUMENTS"
     },
     "verify": {
       "description": "Run verification loop",
-      "template": "{file:.opencode/commands/verify.md}\n\n$ARGUMENTS"
+      "template": "{file:commands/verify.md}\n\n$ARGUMENTS"
     },
     "eval": {
       "description": "Run evaluation against criteria",
-      "template": "{file:.opencode/commands/eval.md}\n\n$ARGUMENTS"
+      "template": "{file:commands/eval.md}\n\n$ARGUMENTS"
     },
     "update-docs": {
       "description": "Update documentation",
-      "template": "{file:.opencode/commands/update-docs.md}\n\n$ARGUMENTS",
+      "template": "{file:commands/update-docs.md}\n\n$ARGUMENTS",
       "agent": "doc-updater",
       "subtask": true
     },
     "update-codemaps": {
       "description": "Update codemaps",
-      "template": "{file:.opencode/commands/update-codemaps.md}\n\n$ARGUMENTS",
+      "template": "{file:commands/update-codemaps.md}\n\n$ARGUMENTS",
       "agent": "doc-updater",
       "subtask": true
     },
     "test-coverage": {
       "description": "Analyze test coverage",
-      "template": "{file:.opencode/commands/test-coverage.md}\n\n$ARGUMENTS",
+      "template": "{file:commands/test-coverage.md}\n\n$ARGUMENTS",
       "agent": "tdd-guide",
       "subtask": true
     },
     "setup-pm": {
       "description": "Configure package manager",
-      "template": "{file:.opencode/commands/setup-pm.md}\n\n$ARGUMENTS"
+      "template": "{file:commands/setup-pm.md}\n\n$ARGUMENTS"
     },
     "go-review": {
       "description": "Go code review",
-      "template": "{file:.opencode/commands/go-review.md}\n\n$ARGUMENTS",
+      "template": "{file:commands/go-review.md}\n\n$ARGUMENTS",
       "agent": "go-reviewer",
       "subtask": true
     },
     "go-test": {
       "description": "Go TDD workflow",
-      "template": "{file:.opencode/commands/go-test.md}\n\n$ARGUMENTS",
+      "template": "{file:commands/go-test.md}\n\n$ARGUMENTS",
       "agent": "tdd-guide",
       "subtask": true
     },
     "go-build": {
       "description": "Fix Go build errors",
-      "template": "{file:.opencode/commands/go-build.md}\n\n$ARGUMENTS",
+      "template": "{file:commands/go-build.md}\n\n$ARGUMENTS",
       "agent": "go-build-resolver",
       "subtask": true
     },
     "skill-create": {
       "description": "Generate skills from git history",
-      "template": "{file:.opencode/commands/skill-create.md}\n\n$ARGUMENTS"
+      "template": "{file:commands/skill-create.md}\n\n$ARGUMENTS"
     },
     "instinct-status": {
       "description": "View learned instincts",
-      "template": "{file:.opencode/commands/instinct-status.md}\n\n$ARGUMENTS"
+      "template": "{file:commands/instinct-status.md}\n\n$ARGUMENTS"
     },
     "instinct-import": {
       "description": "Import instincts",
-      "template": "{file:.opencode/commands/instinct-import.md}\n\n$ARGUMENTS"
+      "template": "{file:commands/instinct-import.md}\n\n$ARGUMENTS"
     },
     "instinct-export": {
       "description": "Export instincts",
-      "template": "{file:.opencode/commands/instinct-export.md}\n\n$ARGUMENTS"
+      "template": "{file:commands/instinct-export.md}\n\n$ARGUMENTS"
     },
     "evolve": {
       "description": "Cluster instincts into skills",
-      "template": "{file:.opencode/commands/evolve.md}\n\n$ARGUMENTS"
+      "template": "{file:commands/evolve.md}\n\n$ARGUMENTS"
     },
     "promote": {
       "description": "Promote project instincts to global scope",
-      "template": "{file:.opencode/commands/promote.md}\n\n$ARGUMENTS"
+      "template": "{file:commands/promote.md}\n\n$ARGUMENTS"
     },
     "projects": {
       "description": "List known projects and instinct stats",
-      "template": "{file:.opencode/commands/projects.md}\n\n$ARGUMENTS"
+      "template": "{file:commands/projects.md}\n\n$ARGUMENTS"
     }
   },
   "permission": {

AGENTS.md

@@ -1,6 +1,6 @@
 # Everything Claude Code (ECC) — Agent Instructions
 
-This is a **production-ready AI coding plugin** providing 13 specialized agents, 50+ skills, 33 commands, and automated hook workflows for software development.
+This is a **production-ready AI coding plugin** providing 16 specialized agents, 65+ skills, 40 commands, and automated hook workflows for software development.
 
 ## Core Principles
 
@@ -27,6 +27,9 @@ This is a **production-ready AI coding plugin** providing 13 specialized agents,
 | go-build-resolver | Go build errors | Go build failures |
 | database-reviewer | PostgreSQL/Supabase specialist | Schema design, query optimization |
 | python-reviewer | Python code review | Python projects |
+| chief-of-staff | Communication triage and drafts | Multi-channel email, Slack, LINE, Messenger |
+| loop-operator | Autonomous loop execution | Run loops safely, monitor stalls, intervene |
+| harness-optimizer | Harness config tuning | Reliability, cost, throughput |
 
 ## Agent Orchestration
 
@@ -36,6 +39,9 @@ Use agents proactively without user prompt:
 - Bug fix or new feature → **tdd-guide**
 - Architectural decision → **architect**
 - Security-sensitive code → **security-reviewer**
+- Multi-channel communication triage → **chief-of-staff**
+- Autonomous loops / loop monitoring → **loop-operator**
+- Harness config reliability and cost → **harness-optimizer**
 
 Use parallel execution for independent operations — launch multiple agents simultaneously.
 
@@ -92,7 +98,12 @@ Troubleshoot failures: check test isolation → verify mocks → fix implementat
 1. **Plan** — Use planner agent, identify dependencies and risks, break into phases
 2. **TDD** — Use tdd-guide agent, write tests first, implement, refactor
 3. **Review** — Use code-reviewer agent immediately, address CRITICAL/HIGH issues
-4. **Commit** — Conventional commits format, comprehensive PR summaries
+4. **Capture knowledge in the right place**
+   - Personal debugging notes, preferences, and temporary context → auto memory
+   - Team/project knowledge (architecture decisions, API changes, runbooks) → the project's existing docs structure
+   - If the current task already produces the relevant docs or code comments, do not duplicate the same information elsewhere
+   - If there is no obvious project doc location, ask before creating a new top-level file
+5. **Commit** — Conventional commits format, comprehensive PR summaries
 
 ## Git Workflow
 
@@ -118,8 +129,8 @@ Troubleshoot failures: check test isolation → verify mocks → fix implementat
 
 ```
 agents/          — 13 specialized subagents
-skills/          — 50+ workflow skills and domain knowledge
-commands/        — 33 slash commands
+skills/          — 65+ workflow skills and domain knowledge
+commands/        — 40 slash commands
 hooks/           — Trigger-based automations
 rules/           — Always-follow guidelines (common + per-language)
 scripts/         — Cross-platform Node.js utilities

CODE_OF_CONDUCT.md

@@ -116,7 +116,7 @@ the community.
 
 This Code of Conduct is adapted from the [Contributor Covenant][homepage],
 version 2.0, available at
-https://www.contributor-covenant.org/version/2/0/code_of_conduct.html.
+<https://www.contributor-covenant.org/version/2/0/code_of_conduct.html>.
 
 Community Impact Guidelines were inspired by [Mozilla's code of conduct
 enforcement ladder](https://github.com/mozilla/diversity).
@@ -124,5 +124,5 @@ enforcement ladder](https://github.com/mozilla/diversity).
 [homepage]: https://www.contributor-covenant.org
 
 For answers to common questions about this code of conduct, see the FAQ at
-https://www.contributor-covenant.org/faq. Translations are available at
-https://www.contributor-covenant.org/translations.
+<https://www.contributor-covenant.org/faq>. Translations are available at
+<https://www.contributor-covenant.org/translations>.

CONTRIBUTING.md

@@ -10,6 +10,7 @@ Thanks for wanting to contribute! This repo is a community resource for Claude C
 - [Contributing Agents](#contributing-agents)
 - [Contributing Hooks](#contributing-hooks)
 - [Contributing Commands](#contributing-commands)
+- [Cross-Harness and Translations](#cross-harness-and-translations)
 - [Pull Request Process](#pull-request-process)
 
 ---
@@ -348,6 +349,29 @@ What the user receives.
 
 ---
 
+## Cross-Harness and Translations
+
+### Skill subsets (Codex and Cursor)
+
+ECC ships skill subsets for other harnesses:
+
+- **Codex:** `.agents/skills/` — skills listed in `agents/openai.yaml` are loaded by Codex.
+- **Cursor:** `.cursor/skills/` — a subset of skills is bundled for Cursor.
+
+When you **add a new skill** that should be available on Codex or Cursor:
+
+1. Add the skill under `skills/your-skill-name/` as usual.
+2. If it should be available on **Codex**, add it to `.agents/skills/` (copy the skill directory or add a reference) and ensure it is referenced in `agents/openai.yaml` if required.
+3. If it should be available on **Cursor**, add it under `.cursor/skills/` per Cursor's layout.
+
+Check existing skills in those directories for the expected structure. Keeping these subsets in sync is manual; mention in your PR if you updated them.
+
+### Translations
+
+Translations live under `docs/` (e.g. `docs/zh-CN`, `docs/zh-TW`, `docs/ja-JP`). If you change agents, commands, or skills that are translated, consider updating the corresponding translation files or opening an issue so maintainers or translators can update them.
+
+---
+
 ## Pull Request Process
 
 ### 1. PR Title Format

README.md

@@ -1,4 +1,4 @@
-**Language:** English | [繁體中文](docs/zh-TW/README.md)
+**Language:** English | [简体中文](README.zh-CN.md) | [繁體中文](docs/zh-TW/README.md) | [日本語](docs/ja-JP/README.md) | [한국어](docs/ko-KR/README.md)
 
 # Everything Claude Code
 
@@ -14,9 +14,10 @@
 ![Python](https://img.shields.io/badge/-Python-3776AB?logo=python&logoColor=white)
 ![Go](https://img.shields.io/badge/-Go-00ADD8?logo=go&logoColor=white)
 ![Java](https://img.shields.io/badge/-Java-ED8B00?logo=openjdk&logoColor=white)
+![Perl](https://img.shields.io/badge/-Perl-39457E?logo=perl&logoColor=white)
 ![Markdown](https://img.shields.io/badge/-Markdown-000000?logo=markdown&logoColor=white)
 
-> **50K+ stars** | **6K+ forks** | **30 contributors** | **6 languages supported** | **Anthropic Hackathon Winner**
+> **50K+ stars** | **6K+ forks** | **30 contributors** | **5 languages supported** | **Anthropic Hackathon Winner**
 
 ---
 
@@ -24,7 +25,7 @@
 
 **🌐 Language / 语言 / 語言**
 
-[**English**](README.md) | [简体中文](README.zh-CN.md) | [繁體中文](docs/zh-TW/README.md) | [日本語](docs/ja-JP/README.md)
+[**English**](README.md) | [简体中文](README.zh-CN.md) | [繁體中文](docs/zh-TW/README.md) | [日本語](docs/ja-JP/README.md) | [한국어](docs/ko-KR/README.md)
 
 </div>
 
@@ -38,24 +39,6 @@ Works across **Claude Code**, **Codex**, **Cowork**, and other AI agent harnesse
 
 ---
 
-## Traction & Distribution
-
-Use these live signals when presenting ECC to sponsors, platforms, or ecosystem partners:
-
-- **Main package installs:** [`ecc-universal` on npm](https://www.npmjs.com/package/ecc-universal)
-- **Security companion installs:** [`ecc-agentshield` on npm](https://www.npmjs.com/package/ecc-agentshield)
-- **GitHub App distribution:** [ECC Tools marketplace listing](https://github.com/marketplace/ecc-tools)
-- **Automated monthly metrics issue:** powered by `.github/workflows/monthly-metrics.yml`
-- **Repo adoption signal:** stars/forks/contributors badges at the top of this README
-
-Download counts for Claude Code plugin installs are not currently exposed as a public API. For partner reporting, combine npm metrics with GitHub App installs and repository traffic/fork growth.
-
-For a sponsor-call metrics checklist and command snippets, see [`docs/business/metrics-and-sponsorship.md`](docs/business/metrics-and-sponsorship.md).
-
-[**Sponsor ECC**](https://github.com/sponsors/affaan-m) | [Sponsor Tiers](SPONSORS.md) | [Sponsorship Program](SPONSORING.md)
-
----
-
 ## The Guides
 
 This repo is the raw code only. The guides explain everything.
@@ -173,9 +156,9 @@ git clone https://github.com/affaan-m/everything-claude-code.git
 cd everything-claude-code
 
 # Recommended: use the installer (handles common + language rules safely)
-./install.sh typescript    # or python or golang
+./install.sh typescript    # or python or golang or swift or php
 # You can pass multiple languages:
-# ./install.sh typescript python golang
+# ./install.sh typescript python golang swift php
 # or target cursor:
 # ./install.sh --target cursor typescript
 # or target antigravity:
@@ -292,6 +275,7 @@ everything-claude-code/
 |   |-- security-review/            # Security checklist
 |   |-- eval-harness/               # Verification loop evaluation (Longform Guide)
 |   |-- verification-loop/          # Continuous verification (Longform Guide)
+|   |-- videodb/                   # Video and audio: ingest, search, edit, generate, stream (NEW)
 |   |-- golang-patterns/            # Go idioms and best practices
 |   |-- golang-testing/             # Go testing patterns, TDD, benchmarks
 |   |-- cpp-coding-standards/         # C++ coding standards from C++ Core Guidelines (NEW)
@@ -328,6 +312,9 @@ everything-claude-code/
 |   |-- liquid-glass-design/         # iOS 26 Liquid Glass design system (NEW)
 |   |-- foundation-models-on-device/ # Apple on-device LLM with FoundationModels (NEW)
 |   |-- swift-concurrency-6-2/       # Swift 6.2 Approachable Concurrency (NEW)
+|   |-- perl-patterns/             # Modern Perl 5.36+ idioms and best practices (NEW)
+|   |-- perl-security/             # Perl security patterns, taint mode, safe I/O (NEW)
+|   |-- perl-testing/              # Perl TDD with Test2::V0, prove, Devel::Cover (NEW)
 |   |-- autonomous-loops/           # Autonomous loop patterns: sequential pipelines, PR loops, DAG orchestration (NEW)
 |   |-- plankton-code-quality/      # Write-time code quality enforcement with Plankton hooks (NEW)
 |
@@ -379,6 +366,8 @@ everything-claude-code/
 |   |-- typescript/          # TypeScript/JavaScript specific
 |   |-- python/              # Python specific
 |   |-- golang/              # Go specific
+|   |-- swift/               # Swift specific
+|   |-- php/                 # PHP specific (NEW)
 |
 |-- hooks/            # Trigger-based automations
 |   |-- README.md                 # Hook documentation, recipes, and customization guide
@@ -581,6 +570,7 @@ This gives you instant access to all commands, agents, skills, and hooks.
 > cp -r everything-claude-code/rules/typescript/* ~/.claude/rules/   # pick your stack
 > cp -r everything-claude-code/rules/python/* ~/.claude/rules/
 > cp -r everything-claude-code/rules/golang/* ~/.claude/rules/
+> cp -r everything-claude-code/rules/php/* ~/.claude/rules/
 >
 > # Option B: Project-level rules (applies to current project only)
 > mkdir -p .claude/rules
@@ -606,6 +596,7 @@ cp -r everything-claude-code/rules/common/* ~/.claude/rules/
 cp -r everything-claude-code/rules/typescript/* ~/.claude/rules/   # pick your stack
 cp -r everything-claude-code/rules/python/* ~/.claude/rules/
 cp -r everything-claude-code/rules/golang/* ~/.claude/rules/
+cp -r everything-claude-code/rules/php/* ~/.claude/rules/
 
 # Copy commands
 cp everything-claude-code/commands/*.md ~/.claude/commands/
@@ -688,6 +679,8 @@ rules/
   typescript/      # TS/JS specific patterns and tools
   python/          # Python specific patterns and tools
   golang/          # Go specific patterns and tools
+  swift/           # Swift specific patterns and tools
+  php/             # PHP specific patterns and tools
 ```
 
 See [`rules/README.md`](rules/README.md) for installation and structure details.
@@ -757,6 +750,31 @@ This shows all available agents, commands, and skills from the plugin.
 This is the most common issue. **Do NOT add a `"hooks"` field to `.claude-plugin/plugin.json`.** Claude Code v2.1+ automatically loads `hooks/hooks.json` from installed plugins. Explicitly declaring it causes duplicate detection errors. See [#29](https://github.com/affaan-m/everything-claude-code/issues/29), [#52](https://github.com/affaan-m/everything-claude-code/issues/52), [#103](https://github.com/affaan-m/everything-claude-code/issues/103).
 </details>
 
+<details>
+<summary><b>Can I use ECC with Claude Code on a custom API endpoint or model gateway?</b></summary>
+
+Yes. ECC does not hardcode Anthropic-hosted transport settings. It runs locally through Claude Code's normal CLI/plugin surface, so it works with:
+
+- Anthropic-hosted Claude Code
+- Official Claude Code gateway setups using `ANTHROPIC_BASE_URL` and `ANTHROPIC_AUTH_TOKEN`
+- Compatible custom endpoints that speak the Anthropic API Claude Code expects
+
+Minimal example:
+
+```bash
+export ANTHROPIC_BASE_URL=https://your-gateway.example.com
+export ANTHROPIC_AUTH_TOKEN=your-token
+claude
+```
+
+If your gateway remaps model names, configure that in Claude Code rather than in ECC. ECC's hooks, skills, commands, and rules are model-provider agnostic once the `claude` CLI is already working.
+
+Official references:
+- [Claude Code LLM gateway docs](https://docs.anthropic.com/en/docs/claude-code/llm-gateway)
+- [Claude Code model configuration docs](https://docs.anthropic.com/en/docs/claude-code/model-config)
+
+</details>
+
 <details>
 <summary><b>My context window is shrinking / Claude is running out of context</b></summary>
 
@@ -842,7 +860,7 @@ Please contribute! See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
 
 ### Ideas for Contributions
 
-- Language-specific skills (Rust, C#, Swift, Kotlin) — Go, Python, Java already included
+- Language-specific skills (Rust, C#, Kotlin, Java) — Go, Python, Perl, Swift, and TypeScript already included
 - Framework-specific configs (Rails, Laravel, FastAPI, NestJS) — Django, Spring Boot already included
 - DevOps agents (Kubernetes, Terraform, AWS, Docker)
 - Testing strategies (different frameworks, visual regression)
@@ -859,7 +877,7 @@ ECC provides **full Cursor IDE support** with hooks, rules, agents, skills, comm
 ```bash
 # Install for your language(s)
 ./install.sh --target cursor typescript
-./install.sh --target cursor python golang swift
+./install.sh --target cursor python golang swift php
 ```
 
 ### What's Included
@@ -868,7 +886,7 @@ ECC provides **full Cursor IDE support** with hooks, rules, agents, skills, comm
 |-----------|-------|---------|
 | Hook Events | 15 | sessionStart, beforeShellExecution, afterFileEdit, beforeMCPExecution, beforeSubmitPrompt, and 10 more |
 | Hook Scripts | 16 | Thin Node.js scripts delegating to `scripts/hooks/` via shared adapter |
-| Rules | 29 | 9 common (alwaysApply) + 20 language-specific (TypeScript, Python, Go, Swift) |
+| Rules | 34 | 9 common (alwaysApply) + 25 language-specific (TypeScript, Python, Go, Swift, PHP) |
 | Agents | Shared | Via AGENTS.md at root (read by Cursor natively) |
 | Skills | Shared + Bundled | Via AGENTS.md at root and `.cursor/skills/` for translated additions |
 | Commands | Shared | `.cursor/commands/` if installed |
@@ -911,27 +929,30 @@ ECC provides **first-class Codex support** for both the macOS app and CLI, with
 ### Quick Start (Codex App + CLI)
 
 ```bash
-# Copy the reference config to your home directory
-cp .codex/config.toml ~/.codex/config.toml
-
-# Run Codex CLI in the repo — AGENTS.md is auto-detected
+# Run Codex CLI in the repo — AGENTS.md and .codex/ are auto-detected
 codex
+
+# Optional: copy the global-safe defaults to your home directory
+cp .codex/config.toml ~/.codex/config.toml
 ```
 
 Codex macOS app:
 - Open this repository as your workspace.
 - The root `AGENTS.md` is auto-detected.
-- Optional: copy `.codex/config.toml` to `~/.codex/config.toml` for CLI/app behavior consistency.
+- `.codex/config.toml` and `.codex/agents/*.toml` work best when kept project-local.
+- The reference `.codex/config.toml` intentionally does not pin `model` or `model_provider`, so Codex uses its own current default unless you override it.
+- Optional: copy `.codex/config.toml` to `~/.codex/config.toml` for global defaults; keep the multi-agent role files project-local unless you also copy `.codex/agents/`.
 
 ### What's Included
 
 | Component | Count | Details |
 |-----------|-------|---------|
-| Config | 1 | `.codex/config.toml` — model, permissions, MCP servers, persistent instructions |
+| Config | 1 | `.codex/config.toml` — top-level approvals/sandbox/web_search, MCP servers, notifications, profiles |
 | AGENTS.md | 2 | Root (universal) + `.codex/AGENTS.md` (Codex-specific supplement) |
 | Skills | 16 | `.agents/skills/` — SKILL.md + agents/openai.yaml per skill |
 | MCP Servers | 4 | GitHub, Context7, Memory, Sequential Thinking (command-based) |
 | Profiles | 2 | `strict` (read-only sandbox) and `yolo` (full auto-approve) |
+| Agent Roles | 3 | `.codex/agents/` — explorer, reviewer, docs-researcher |
 
 ### Skills
 
@@ -958,7 +979,24 @@ Skills at `.agents/skills/` are auto-loaded by Codex:
 
 ### Key Limitation
 
-Codex does **not yet provide Claude-style hook execution parity**. ECC enforcement there is instruction-based via `AGENTS.md` and `persistent_instructions`, plus sandbox permissions.
+Codex does **not yet provide Claude-style hook execution parity**. ECC enforcement there is instruction-based via `AGENTS.md`, optional `model_instructions_file` overrides, and sandbox/approval settings.
+
+### Multi-Agent Support
+
+Current Codex builds support experimental multi-agent workflows.
+
+- Enable `features.multi_agent = true` in `.codex/config.toml`
+- Define roles under `[agents.<name>]`
+- Point each role at a file under `.codex/agents/`
+- Use `/agent` in the CLI to inspect or steer child agents
+
+ECC ships three sample role configs:
+
+| Role | Purpose |
+|------|---------|
+| `explorer` | Read-only codebase evidence gathering before edits |
+| `reviewer` | Correctness, security, and missing-test review |
+| `docs_researcher` | Documentation and API verification before release/docs changes |
 
 ---
 
@@ -1068,6 +1106,13 @@ Then add to your `opencode.json`:
 }
 ```
 
+That npm plugin entry enables ECC's published OpenCode plugin module (hooks/events and plugin tools).
+It does **not** automatically add ECC's full command/agent/instruction catalog to your project config.
+
+For the full ECC OpenCode setup, either:
+- run OpenCode inside this repository, or
+- copy the bundled `.opencode/` config assets into your project and wire the `instructions`, `agent`, and `command` entries in `opencode.json`
+
 ### Documentation
 
 - **Migration Guide**: `.opencode/MIGRATION.md`
@@ -1088,7 +1133,7 @@ ECC is the **first plugin to maximize every major AI coding tool**. Here's how e
 | **Skills** | 65 | Shared | 10 (native format) | 37 |
 | **Hook Events** | 8 types | 15 types | None yet | 11 types |
 | **Hook Scripts** | 20+ scripts | 16 scripts (DRY adapter) | N/A | Plugin hooks |
-| **Rules** | 29 (common + lang) | 29 (YAML frontmatter) | Instruction-based | 13 instructions |
+| **Rules** | 34 (common + lang) | 34 (YAML frontmatter) | Instruction-based | 13 instructions |
 | **Custom Tools** | Via hooks | Via hooks | N/A | 6 native tools |
 | **MCP Servers** | 14 | Shared (mcp.json) | 4 (command-based) | Full |
 | **Config Format** | settings.json | hooks.json + rules/ | config.toml | opencode.json |
@@ -1101,7 +1146,7 @@ ECC is the **first plugin to maximize every major AI coding tool**. Here's how e
 - **AGENTS.md** at root is the universal cross-tool file (read by all 4 tools)
 - **DRY adapter pattern** lets Cursor reuse Claude Code's hook scripts without duplication
 - **Skills format** (SKILL.md with YAML frontmatter) works across Claude Code, Codex, and OpenCode
-- Codex's lack of hooks is compensated by `persistent_instructions` and sandbox permissions
+- Codex's lack of hooks is compensated by `AGENTS.md`, optional `model_instructions_file` overrides, and sandbox permissions
 
 ---
 

README.zh-CN.md

@@ -5,6 +5,7 @@
 ![Shell](https://img.shields.io/badge/-Shell-4EAA25?logo=gnu-bash&logoColor=white)
 ![TypeScript](https://img.shields.io/badge/-TypeScript-3178C6?logo=typescript&logoColor=white)
 ![Go](https://img.shields.io/badge/-Go-00ADD8?logo=go&logoColor=white)
+![Perl](https://img.shields.io/badge/-Perl-39457E?logo=perl&logoColor=white)
 ![Markdown](https://img.shields.io/badge/-Markdown-000000?logo=markdown&logoColor=white)
 
 ---
@@ -13,7 +14,7 @@
 
 **🌐 Language / 语言 / 語言**
 
-[**English**](README.md) | [简体中文](README.zh-CN.md) | [繁體中文](docs/zh-TW/README.md) | [日本語](docs/ja-JP/README.md)
+[**English**](README.md) | [简体中文](README.zh-CN.md) | [繁體中文](docs/zh-TW/README.md) | [日本語](docs/ja-JP/README.md) | [한국어](docs/ko-KR/README.md)
 
 </div>
 
@@ -81,8 +82,12 @@
 # 首先克隆仓库
 git clone https://github.com/affaan-m/everything-claude-code.git
 
-# 复制规则（应用于所有项目）
-cp -r everything-claude-code/rules/* ~/.claude/rules/
+# 复制规则（通用 + 语言特定）
+cp -r everything-claude-code/rules/common/* ~/.claude/rules/
+cp -r everything-claude-code/rules/typescript/* ~/.claude/rules/   # 选择你的技术栈
+cp -r everything-claude-code/rules/python/* ~/.claude/rules/
+cp -r everything-claude-code/rules/golang/* ~/.claude/rules/
+cp -r everything-claude-code/rules/perl/* ~/.claude/rules/
 ```
 
 ### 第三步：开始使用
@@ -175,6 +180,9 @@ everything-claude-code/
 |   |-- golang-patterns/            # Go 惯用语和最佳实践（新增）
 |   |-- golang-testing/             # Go 测试模式、TDD、基准测试（新增）
 |   |-- cpp-testing/                # C++ 测试模式、GoogleTest、CMake/CTest（新增）
+|   |-- perl-patterns/             # 现代 Perl 5.36+ 惯用语和最佳实践（新增）
+|   |-- perl-security/             # Perl 安全模式、污染模式、安全 I/O（新增）
+|   |-- perl-testing/              # 使用 Test2::V0、prove、Devel::Cover 的 Perl TDD（新增）
 |
 |-- commands/         # 用于快速执行的斜杠命令
 |   |-- tdd.md              # /tdd - 测试驱动开发
@@ -197,12 +205,20 @@ everything-claude-code/
 |   |-- evolve.md           # /evolve - 将直觉聚类到技能中（新增）
 |
 |-- rules/            # 始终遵循的指南（复制到 ~/.claude/rules/）
-|   |-- security.md         # 强制性安全检查
-|   |-- coding-style.md     # 不可变性、文件组织
-|   |-- testing.md          # TDD、80% 覆盖率要求
-|   |-- git-workflow.md     # 提交格式、PR 流程
-|   |-- agents.md           # 何时委托给子代理
-|   |-- performance.md      # 模型选择、上下文管理
+|   |-- README.md            # 结构概述和安装指南
+|   |-- common/              # 与语言无关的原则
+|   |   |-- coding-style.md    # 不可变性、文件组织
+|   |   |-- git-workflow.md    # 提交格式、PR 流程
+|   |   |-- testing.md         # TDD、80% 覆盖率要求
+|   |   |-- performance.md     # 模型选择、上下文管理
+|   |   |-- patterns.md        # 设计模式、骨架项目
+|   |   |-- hooks.md           # 钩子架构、TodoWrite
+|   |   |-- agents.md          # 何时委托给子代理
+|   |   |-- security.md        # 强制性安全检查
+|   |-- typescript/          # TypeScript/JavaScript 特定
+|   |-- python/              # Python 特定
+|   |-- golang/              # Go 特定
+|   |-- perl/                # Perl 特定（新增）
 |
 |-- hooks/            # 基于触发器的自动化
 |   |-- hooks.json                # 所有钩子配置（PreToolUse、PostToolUse、Stop 等）
@@ -356,8 +372,12 @@ git clone https://github.com/affaan-m/everything-claude-code.git
 # 将代理复制到你的 Claude 配置
 cp everything-claude-code/agents/*.md ~/.claude/agents/
 
-# 复制规则
-cp everything-claude-code/rules/*.md ~/.claude/rules/
+# 复制规则（通用 + 语言特定）
+cp -r everything-claude-code/rules/common/* ~/.claude/rules/
+cp -r everything-claude-code/rules/typescript/* ~/.claude/rules/   # 选择你的技术栈
+cp -r everything-claude-code/rules/python/* ~/.claude/rules/
+cp -r everything-claude-code/rules/golang/* ~/.claude/rules/
+cp -r everything-claude-code/rules/perl/* ~/.claude/rules/
 
 # 复制命令
 cp everything-claude-code/commands/*.md ~/.claude/commands/
@@ -425,13 +445,15 @@ model: opus
 
 ### 规则
 
-规则是始终遵循的指南。保持模块化：
+规则是始终遵循的指南，分为 `common/`（通用）+ 语言特定目录：
 
 ```
 ~/.claude/rules/
-  security.md      # 无硬编码秘密
-  coding-style.md  # 不可变性、文件限制
-  testing.md       # TDD、覆盖率要求
+  common/          # 通用原则（必装）
+  typescript/      # TS/JS 特定模式和工具
+  python/          # Python 特定模式和工具
+  golang/          # Go 特定模式和工具
+  perl/            # Perl 特定模式和工具
 ```
 
 ---
@@ -466,7 +488,7 @@ node tests/hooks/hooks.test.js
 
 ### 贡献想法
 
-- 特定语言的技能（Python、Rust 模式）- 现已包含 Go！
+- 特定语言的技能（Rust、C#、Kotlin、Java）- 现已包含 Go、Python、Perl、Swift 和 TypeScript！
 - 特定框架的配置（Django、Rails、Laravel）
 - DevOps 代理（Kubernetes、Terraform、AWS）
 - 测试策略（不同框架）

TROUBLESHOOTING.md

@@ -0,0 +1,422 @@
+# Troubleshooting Guide
+
+Common issues and solutions for Everything Claude Code (ECC) plugin.
+
+## Table of Contents
+
+- [Memory & Context Issues](#memory--context-issues)
+- [Agent Harness Failures](#agent-harness-failures)
+- [Hook & Workflow Errors](#hook--workflow-errors)
+- [Installation & Setup](#installation--setup)
+- [Performance Issues](#performance-issues)
+- [Common Error Messages](#common-error-messages)
+- [Getting Help](#getting-help)
+
+---
+
+## Memory & Context Issues
+
+### Context Window Overflow
+
+**Symptom:** "Context too long" errors or incomplete responses
+
+**Causes:**
+- Large file uploads exceeding token limits
+- Accumulated conversation history
+- Multiple large tool outputs in single session
+
+**Solutions:**
+```bash
+# 1. Clear conversation history and start fresh
+# Use Claude Code: "New Chat" or Cmd/Ctrl+Shift+N
+
+# 2. Reduce file size before analysis
+head -n 100 large-file.log > sample.log
+
+# 3. Use streaming for large outputs
+head -n 50 large-file.txt
+
+# 4. Split tasks into smaller chunks
+# Instead of: "Analyze all 50 files"
+# Use: "Analyze files in src/components/ directory"
+```
+
+### Memory Persistence Failures
+
+**Symptom:** Agent doesn't remember previous context or observations
+
+**Causes:**
+- Disabled continuous-learning hooks
+- Corrupted observation files
+- Project detection failures
+
+**Solutions:**
+```bash
+# Check if observations are being recorded
+ls ~/.claude/homunculus/projects/*/observations.jsonl
+
+# Find the current project's hash id
+python3 - <<'PY'
+import json, os
+registry_path = os.path.expanduser("~/.claude/homunculus/projects.json")
+with open(registry_path) as f:
+    registry = json.load(f)
+for project_id, meta in registry.items():
+    if meta.get("root") == os.getcwd():
+        print(project_id)
+        break
+else:
+    raise SystemExit("Project hash not found in ~/.claude/homunculus/projects.json")
+PY
+
+# View recent observations for that project
+tail -20 ~/.claude/homunculus/projects/<project-hash>/observations.jsonl
+
+# Back up a corrupted observations file before recreating it
+mv ~/.claude/homunculus/projects/<project-hash>/observations.jsonl \
+  ~/.claude/homunculus/projects/<project-hash>/observations.jsonl.bak.$(date +%Y%m%d-%H%M%S)
+
+# Verify hooks are enabled
+grep -r "observe" ~/.claude/settings.json
+```
+
+---
+
+## Agent Harness Failures
+
+### Agent Not Found
+
+**Symptom:** "Agent not loaded" or "Unknown agent" errors
+
+**Causes:**
+- Plugin not installed correctly
+- Agent path misconfiguration
+- Marketplace vs manual install mismatch
+
+**Solutions:**
+```bash
+# Check plugin installation
+ls ~/.claude/plugins/cache/
+
+# Verify agent exists (marketplace install)
+ls ~/.claude/plugins/cache/*/agents/
+
+# For manual install, agents should be in:
+ls ~/.claude/agents/  # Custom agents only
+
+# Reload plugin
+# Claude Code → Settings → Extensions → Reload
+```
+
+### Workflow Execution Hangs
+
+**Symptom:** Agent starts but never completes
+
+**Causes:**
+- Infinite loops in agent logic
+- Blocked on user input
+- Network timeout waiting for API
+
+**Solutions:**
+```bash
+# 1. Check for stuck processes
+ps aux | grep claude
+
+# 2. Enable debug mode
+export CLAUDE_DEBUG=1
+
+# 3. Set shorter timeouts
+export CLAUDE_TIMEOUT=30
+
+# 4. Check network connectivity
+curl -I https://api.anthropic.com
+```
+
+### Tool Use Errors
+
+**Symptom:** "Tool execution failed" or permission denied
+
+**Causes:**
+- Missing dependencies (npm, python, etc.)
+- Insufficient file permissions
+- Path not found
+
+**Solutions:**
+```bash
+# Verify required tools are installed
+which node python3 npm git
+
+# Fix permissions on hook scripts
+chmod +x ~/.claude/plugins/cache/*/hooks/*.sh
+chmod +x ~/.claude/plugins/cache/*/skills/*/hooks/*.sh
+
+# Check PATH includes necessary binaries
+echo $PATH
+```
+
+---
+
+## Hook & Workflow Errors
+
+### Hooks Not Firing
+
+**Symptom:** Pre/post hooks don't execute
+
+**Causes:**
+- Hooks not registered in settings.json
+- Invalid hook syntax
+- Hook script not executable
+
+**Solutions:**
+```bash
+# Check hooks are registered
+grep -A 10 '"hooks"' ~/.claude/settings.json
+
+# Verify hook files exist and are executable
+ls -la ~/.claude/plugins/cache/*/hooks/
+
+# Test hook manually
+bash ~/.claude/plugins/cache/*/hooks/pre-bash.sh <<< '{"command":"echo test"}'
+
+# Re-register hooks (if using plugin)
+# Disable and re-enable plugin in Claude Code settings
+```
+
+### Python/Node Version Mismatches
+
+**Symptom:** "python3 not found" or "node: command not found"
+
+**Causes:**
+- Missing Python/Node installation
+- PATH not configured
+- Wrong Python version (Windows)
+
+**Solutions:**
+```bash
+# Install Python 3 (if missing)
+# macOS: brew install python3
+# Ubuntu: sudo apt install python3
+# Windows: Download from python.org
+
+# Install Node.js (if missing)
+# macOS: brew install node
+# Ubuntu: sudo apt install nodejs npm
+# Windows: Download from nodejs.org
+
+# Verify installations
+python3 --version
+node --version
+npm --version
+
+# Windows: Ensure python (not python3) works
+python --version
+```
+
+### Dev Server Blocker False Positives
+
+**Symptom:** Hook blocks legitimate commands mentioning "dev"
+
+**Causes:**
+- Heredoc content triggering pattern match
+- Non-dev commands with "dev" in arguments
+
+**Solutions:**
+```bash
+# This is fixed in v1.8.0+ (PR #371)
+# Upgrade plugin to latest version
+
+# Workaround: Wrap dev servers in tmux
+tmux new-session -d -s dev "npm run dev"
+tmux attach -t dev
+
+# Disable hook temporarily if needed
+# Edit ~/.claude/settings.json and remove pre-bash hook
+```
+
+---
+
+## Installation & Setup
+
+### Plugin Not Loading
+
+**Symptom:** Plugin features unavailable after install
+
+**Causes:**
+- Marketplace cache not updated
+- Claude Code version incompatibility
+- Corrupted plugin files
+
+**Solutions:**
+```bash
+# Inspect the plugin cache before changing it
+ls -la ~/.claude/plugins/cache/
+
+# Back up the plugin cache instead of deleting it in place
+mv ~/.claude/plugins/cache ~/.claude/plugins/cache.backup.$(date +%Y%m%d-%H%M%S)
+mkdir -p ~/.claude/plugins/cache
+
+# Reinstall from marketplace
+# Claude Code → Extensions → Everything Claude Code → Uninstall
+# Then reinstall from marketplace
+
+# Check Claude Code version
+claude --version
+# Requires Claude Code 2.0+
+
+# Manual install (if marketplace fails)
+git clone https://github.com/affaan-m/everything-claude-code.git
+cp -r everything-claude-code ~/.claude/plugins/ecc
+```
+
+### Package Manager Detection Fails
+
+**Symptom:** Wrong package manager used (npm instead of pnpm)
+
+**Causes:**
+- No lock file present
+- CLAUDE_PACKAGE_MANAGER not set
+- Multiple lock files confusing detection
+
+**Solutions:**
+```bash
+# Set preferred package manager globally
+export CLAUDE_PACKAGE_MANAGER=pnpm
+# Add to ~/.bashrc or ~/.zshrc
+
+# Or set per-project
+echo '{"packageManager": "pnpm"}' > .claude/package-manager.json
+
+# Or use package.json field
+npm pkg set packageManager="pnpm@8.15.0"
+
+# Warning: removing lock files can change installed dependency versions.
+# Commit or back up the lock file first, then run a fresh install and re-run CI.
+# Only do this when intentionally switching package managers.
+rm package-lock.json  # If using pnpm/yarn/bun
+```
+
+---
+
+## Performance Issues
+
+### Slow Response Times
+
+**Symptom:** Agent takes 30+ seconds to respond
+
+**Causes:**
+- Large observation files
+- Too many active hooks
+- Network latency to API
+
+**Solutions:**
+```bash
+# Archive large observations instead of deleting them
+archive_dir="$HOME/.claude/homunculus/archive/$(date +%Y%m%d)"
+mkdir -p "$archive_dir"
+find ~/.claude/homunculus/projects -name "observations.jsonl" -size +10M -exec sh -c '
+  for file do
+    base=$(basename "$(dirname "$file")")
+    gzip -c "$file" > "'"$archive_dir"'/${base}-observations.jsonl.gz"
+    : > "$file"
+  done
+' sh {} +
+
+# Disable unused hooks temporarily
+# Edit ~/.claude/settings.json
+
+# Keep active observation files small
+# Large archives should live under ~/.claude/homunculus/archive/
+```
+
+### High CPU Usage
+
+**Symptom:** Claude Code consuming 100% CPU
+
+**Causes:**
+- Infinite observation loops
+- File watching on large directories
+- Memory leaks in hooks
+
+**Solutions:**
+```bash
+# Check for runaway processes
+top -o cpu | grep claude
+
+# Disable continuous learning temporarily
+touch ~/.claude/homunculus/disabled
+
+# Restart Claude Code
+# Cmd/Ctrl+Q then reopen
+
+# Check observation file size
+du -sh ~/.claude/homunculus/*/
+```
+
+---
+
+## Common Error Messages
+
+### "EACCES: permission denied"
+
+```bash
+# Fix hook permissions
+find ~/.claude/plugins -name "*.sh" -exec chmod +x {} \;
+
+# Fix observation directory permissions
+chmod -R u+rwX,go+rX ~/.claude/homunculus
+```
+
+### "MODULE_NOT_FOUND"
+
+```bash
+# Install plugin dependencies
+cd ~/.claude/plugins/cache/everything-claude-code
+npm install
+
+# Or for manual install
+cd ~/.claude/plugins/ecc
+npm install
+```
+
+### "spawn UNKNOWN"
+
+```bash
+# Windows-specific: Ensure scripts use correct line endings
+# Convert CRLF to LF
+find ~/.claude/plugins -name "*.sh" -exec dos2unix {} \;
+
+# Or install dos2unix
+# macOS: brew install dos2unix
+# Ubuntu: sudo apt install dos2unix
+```
+
+---
+
+## Getting Help
+
+ If you're still experiencing issues:
+
+1. **Check GitHub Issues**: [github.com/affaan-m/everything-claude-code/issues](https://github.com/affaan-m/everything-claude-code/issues)
+2. **Enable Debug Logging**:
+   ```bash
+   export CLAUDE_DEBUG=1
+   export CLAUDE_LOG_LEVEL=debug
+   ```
+3. **Collect Diagnostic Info**:
+   ```bash
+   claude --version
+   node --version
+   python3 --version
+   echo $CLAUDE_PACKAGE_MANAGER
+   ls -la ~/.claude/plugins/cache/
+   ```
+4. **Open an Issue**: Include debug logs, error messages, and diagnostic info
+
+---
+
+## Related Documentation
+
+- [README.md](./README.md) - Installation and features
+- [CONTRIBUTING.md](./CONTRIBUTING.md) - Development guidelines
+- [docs/](./docs/) - Detailed documentation
+- [examples/](./examples/) - Usage examples

agents/kotlin-build-resolver.md

@@ -0,0 +1,118 @@
+---
+name: kotlin-build-resolver
+description: Kotlin/Gradle build, compilation, and dependency error resolution specialist. Fixes build errors, Kotlin compiler errors, and Gradle issues with minimal changes. Use when Kotlin builds fail.
+tools: ["Read", "Write", "Edit", "Bash", "Grep", "Glob"]
+model: sonnet
+---
+
+# Kotlin Build Error Resolver
+
+You are an expert Kotlin/Gradle build error resolution specialist. Your mission is to fix Kotlin build errors, Gradle configuration issues, and dependency resolution failures with **minimal, surgical changes**.
+
+## Core Responsibilities
+
+1. Diagnose Kotlin compilation errors
+2. Fix Gradle build configuration issues
+3. Resolve dependency conflicts and version mismatches
+4. Handle Kotlin compiler errors and warnings
+5. Fix detekt and ktlint violations
+
+## Diagnostic Commands
+
+Run these in order:
+
+```bash
+./gradlew build 2>&1
+./gradlew detekt 2>&1 || echo "detekt not configured"
+./gradlew ktlintCheck 2>&1 || echo "ktlint not configured"
+./gradlew dependencies --configuration runtimeClasspath 2>&1 | head -100
+```
+
+## Resolution Workflow
+
+```text
+1. ./gradlew build        -> Parse error message
+2. Read affected file     -> Understand context
+3. Apply minimal fix      -> Only what's needed
+4. ./gradlew build        -> Verify fix
+5. ./gradlew test         -> Ensure nothing broke
+```
+
+## Common Fix Patterns
+
+| Error | Cause | Fix |
+|-------|-------|-----|
+| `Unresolved reference: X` | Missing import, typo, missing dependency | Add import or dependency |
+| `Type mismatch: Required X, Found Y` | Wrong type, missing conversion | Add conversion or fix type |
+| `None of the following candidates is applicable` | Wrong overload, wrong argument types | Fix argument types or add explicit cast |
+| `Smart cast impossible` | Mutable property or concurrent access | Use local `val` copy or `let` |
+| `'when' expression must be exhaustive` | Missing branch in sealed class `when` | Add missing branches or `else` |
+| `Suspend function can only be called from coroutine` | Missing `suspend` or coroutine scope | Add `suspend` modifier or launch coroutine |
+| `Cannot access 'X': it is internal in 'Y'` | Visibility issue | Change visibility or use public API |
+| `Conflicting declarations` | Duplicate definitions | Remove duplicate or rename |
+| `Could not resolve: group:artifact:version` | Missing repository or wrong version | Add repository or fix version |
+| `Execution failed for task ':detekt'` | Code style violations | Fix detekt findings |
+
+## Gradle Troubleshooting
+
+```bash
+# Check dependency tree for conflicts
+./gradlew dependencies --configuration runtimeClasspath
+
+# Force refresh dependencies
+./gradlew build --refresh-dependencies
+
+# Clear project-local Gradle build cache
+./gradlew clean && rm -rf .gradle/build-cache/
+
+# Check Gradle version compatibility
+./gradlew --version
+
+# Run with debug output
+./gradlew build --debug 2>&1 | tail -50
+
+# Check for dependency conflicts
+./gradlew dependencyInsight --dependency <name> --configuration runtimeClasspath
+```
+
+## Kotlin Compiler Flags
+
+```kotlin
+// build.gradle.kts - Common compiler options
+kotlin {
+    compilerOptions {
+        freeCompilerArgs.add("-Xjsr305=strict") // Strict Java null safety
+        allWarningsAsErrors = true
+    }
+}
+```
+
+## Key Principles
+
+- **Surgical fixes only** -- don't refactor, just fix the error
+- **Never** suppress warnings without explicit approval
+- **Never** change function signatures unless necessary
+- **Always** run `./gradlew build` after each fix to verify
+- Fix root cause over suppressing symptoms
+- Prefer adding missing imports over wildcard imports
+
+## Stop Conditions
+
+Stop and report if:
+- Same error persists after 3 fix attempts
+- Fix introduces more errors than it resolves
+- Error requires architectural changes beyond scope
+- Missing external dependencies that need user decision
+
+## Output Format
+
+```text
+[FIXED] src/main/kotlin/com/example/service/UserService.kt:42
+Error: Unresolved reference: UserRepository
+Fix: Added import com.example.repository.UserRepository
+Remaining errors: 2
+```
+
+Final: `Build Status: SUCCESS/FAILED | Errors Fixed: N | Files Modified: list`
+
+For detailed Kotlin patterns and code examples, see `skill: kotlin-patterns`.

agents/kotlin-reviewer.md

@@ -0,0 +1,159 @@
+---
+name: kotlin-reviewer
+description: Kotlin and Android/KMP code reviewer. Reviews Kotlin code for idiomatic patterns, coroutine safety, Compose best practices, clean architecture violations, and common Android pitfalls.
+tools: ["Read", "Grep", "Glob", "Bash"]
+model: sonnet
+---
+
+You are a senior Kotlin and Android/KMP code reviewer ensuring idiomatic, safe, and maintainable code.
+
+## Your Role
+
+- Review Kotlin code for idiomatic patterns and Android/KMP best practices
+- Detect coroutine misuse, Flow anti-patterns, and lifecycle bugs
+- Enforce clean architecture module boundaries
+- Identify Compose performance issues and recomposition traps
+- You DO NOT refactor or rewrite code — you report findings only
+
+## Workflow
+
+### Step 1: Gather Context
+
+Run `git diff --staged` and `git diff` to see changes. If no diff, check `git log --oneline -5`. Identify Kotlin/KTS files that changed.
+
+### Step 2: Understand Project Structure
+
+Check for:
+- `build.gradle.kts` or `settings.gradle.kts` to understand module layout
+- `CLAUDE.md` for project-specific conventions
+- Whether this is Android-only, KMP, or Compose Multiplatform
+
+### Step 2b: Security Review
+
+Apply the Kotlin/Android security guidance before continuing:
+- exported Android components, deep links, and intent filters
+- insecure crypto, WebView, and network configuration usage
+- keystore, token, and credential handling
+- platform-specific storage and permission risks
+
+If you find a CRITICAL security issue, stop the review and hand off to `security-reviewer` before doing any further analysis.
+
+### Step 3: Read and Review
+
+Read changed files fully. Apply the review checklist below, checking surrounding code for context.
+
+### Step 4: Report Findings
+
+Use the output format below. Only report issues with >80% confidence.
+
+## Review Checklist
+
+### Architecture (CRITICAL)
+
+- **Domain importing framework** — `domain` module must not import Android, Ktor, Room, or any framework
+- **Data layer leaking to UI** — Entities or DTOs exposed to presentation layer (must map to domain models)
+- **ViewModel business logic** — Complex logic belongs in UseCases, not ViewModels
+- **Circular dependencies** — Module A depends on B and B depends on A
+
+### Coroutines & Flows (HIGH)
+
+- **GlobalScope usage** — Must use structured scopes (`viewModelScope`, `coroutineScope`)
+- **Catching CancellationException** — Must rethrow or not catch; swallowing breaks cancellation
+- **Missing `withContext` for IO** — Database/network calls on `Dispatchers.Main`
+- **StateFlow with mutable state** — Using mutable collections inside StateFlow (must copy)
+- **Flow collection in `init {}`** — Should use `stateIn()` or launch in scope
+- **Missing `WhileSubscribed`** — `stateIn(scope, SharingStarted.Eagerly)` when `WhileSubscribed` is appropriate
+
+```kotlin
+// BAD — swallows cancellation
+try { fetchData() } catch (e: Exception) { log(e) }
+
+// GOOD — preserves cancellation
+try { fetchData() } catch (e: CancellationException) { throw e } catch (e: Exception) { log(e) }
+// or use runCatching and check
+```
+
+### Compose (HIGH)
+
+- **Unstable parameters** — Composables receiving mutable types cause unnecessary recomposition
+- **Side effects outside LaunchedEffect** — Network/DB calls must be in `LaunchedEffect` or ViewModel
+- **NavController passed deep** — Pass lambdas instead of `NavController` references
+- **Missing `key()` in LazyColumn** — Items without stable keys cause poor performance
+- **`remember` with missing keys** — Computation not recalculated when dependencies change
+- **Object allocation in parameters** — Creating objects inline causes recomposition
+
+```kotlin
+// BAD — new lambda every recomposition
+Button(onClick = { viewModel.doThing(item.id) })
+
+// GOOD — stable reference
+val onClick = remember(item.id) { { viewModel.doThing(item.id) } }
+Button(onClick = onClick)
+```
+
+### Kotlin Idioms (MEDIUM)
+
+- **`!!` usage** — Non-null assertion; prefer `?.`, `?:`, `requireNotNull`, or `checkNotNull`
+- **`var` where `val` works** — Prefer immutability
+- **Java-style patterns** — Static utility classes (use top-level functions), getters/setters (use properties)
+- **String concatenation** — Use string templates `"Hello $name"` instead of `"Hello " + name`
+- **`when` without exhaustive branches** — Sealed classes/interfaces should use exhaustive `when`
+- **Mutable collections exposed** — Return `List` not `MutableList` from public APIs
+
+### Android Specific (MEDIUM)
+
+- **Context leaks** — Storing `Activity` or `Fragment` references in singletons/ViewModels
+- **Missing ProGuard rules** — Serialized classes without `@Keep` or ProGuard rules
+- **Hardcoded strings** — User-facing strings not in `strings.xml` or Compose resources
+- **Missing lifecycle handling** — Collecting Flows in Activities without `repeatOnLifecycle`
+
+### Security (CRITICAL)
+
+- **Exported component exposure** — Activities, services, or receivers exported without proper guards
+- **Insecure crypto/storage** — Homegrown crypto, plaintext secrets, or weak keystore usage
+- **Unsafe WebView/network config** — JavaScript bridges, cleartext traffic, permissive trust settings
+- **Sensitive logging** — Tokens, credentials, PII, or secrets emitted to logs
+
+If any CRITICAL security issue is present, stop and escalate to `security-reviewer`.
+
+### Gradle & Build (LOW)
+
+- **Version catalog not used** — Hardcoded versions instead of `libs.versions.toml`
+- **Unnecessary dependencies** — Dependencies added but not used
+- **Missing KMP source sets** — Declaring `androidMain` code that could be `commonMain`
+
+## Output Format
+
+```
+[CRITICAL] Domain module imports Android framework
+File: domain/src/main/kotlin/com/app/domain/UserUseCase.kt:3
+Issue: `import android.content.Context` — domain must be pure Kotlin with no framework dependencies.
+Fix: Move Context-dependent logic to data or platforms layer. Pass data via repository interface.
+
+[HIGH] StateFlow holding mutable list
+File: presentation/src/main/kotlin/com/app/ui/ListViewModel.kt:25
+Issue: `_state.value.items.add(newItem)` mutates the list inside StateFlow — Compose won't detect the change.
+Fix: Use `_state.update { it.copy(items = it.items + newItem) }`
+```
+
+## Summary Format
+
+End every review with:
+
+```
+## Review Summary
+
+| Severity | Count | Status |
+|----------|-------|--------|
+| CRITICAL | 0     | pass   |
+| HIGH     | 1     | block  |
+| MEDIUM   | 2     | info   |
+| LOW      | 0     | note   |
+
+Verdict: BLOCK — HIGH issues must be fixed before merge.
+```
+
+## Approval Criteria
+
+- **Approve**: No CRITICAL or HIGH issues
+- **Block**: Any CRITICAL or HIGH issues — must fix before merge

commands/aside.md

@@ -0,0 +1,164 @@
+---
+description: Answer a quick side question without interrupting or losing context from the current task. Resume work automatically after answering.
+---
+
+# Aside Command
+
+Ask a question mid-task and get an immediate, focused answer — then continue right where you left off. The current task, files, and context are never modified.
+
+## When to Use
+
+- You're curious about something while Claude is working and don't want to lose momentum
+- You need a quick explanation of code Claude is currently editing
+- You want a second opinion or clarification on a decision without derailing the task
+- You need to understand an error, concept, or pattern before Claude proceeds
+- You want to ask something unrelated to the current task without starting a new session
+
+## Usage
+
+```
+/aside <your question>
+/aside what does this function actually return?
+/aside is this pattern thread-safe?
+/aside why are we using X instead of Y here?
+/aside what's the difference between foo() and bar()?
+/aside should we be worried about the N+1 query we just added?
+```
+
+## Process
+
+### Step 1: Freeze the current task state
+
+Before answering anything, mentally note:
+- What is the active task? (what file, feature, or problem was being worked on)
+- What step was in progress at the moment `/aside` was invoked?
+- What was about to happen next?
+
+Do NOT touch, edit, create, or delete any files during the aside.
+
+### Step 2: Answer the question directly
+
+Answer the question in the most concise form that is still complete and useful.
+
+- Lead with the answer, not the reasoning
+- Keep it short — if a full explanation is needed, offer to go deeper after the task
+- If the question is about the current file or code being worked on, reference it precisely (file path and line number if relevant)
+- If answering requires reading a file, read it — but read only, never write
+
+Format the response as:
+
+```
+ASIDE: [restate the question briefly]
+
+[Your answer here]
+
+— Back to task: [one-line description of what was being done]
+```
+
+### Step 3: Resume the main task
+
+After delivering the answer, immediately continue the active task from the exact point it was paused. Do not ask for permission to resume unless the aside answer revealed a blocker or a reason to reconsider the current approach (see Edge Cases).
+
+---
+
+## Edge Cases
+
+**No question provided (`/aside` with nothing after it):**
+Respond:
+```
+ASIDE: no question provided
+
+What would you like to know? (ask your question and I'll answer without losing the current task context)
+
+— Back to task: [one-line description of what was being done]
+```
+
+**Question reveals a potential problem with the current task:**
+Flag it clearly before resuming:
+```
+ASIDE: [answer]
+
+⚠️ Note: This answer suggests [issue] with the current approach. Want to address this before continuing, or proceed as planned?
+```
+Wait for the user's decision before resuming.
+
+**Question is actually a task redirect (not a side question):**
+If the question implies changing what is being built (e.g., `/aside actually, let's use Redis instead`), clarify:
+```
+ASIDE: That sounds like a direction change, not just a side question.
+Do you want to:
+  (a) Answer this as information only and keep the current plan
+  (b) Pause the current task and change approach
+```
+Wait for the user's answer — do not make assumptions.
+
+**Question is about the currently open file or code:**
+Answer from the live context. If the file was read earlier in the session, reference it directly. If not, read it now (read-only) and answer with a file:line reference.
+
+**No active task (nothing in progress when `/aside` is invoked):**
+Still use the standard wrapper so the response shape stays consistent:
+```
+ASIDE: [restate the question briefly]
+
+[Your answer here]
+
+— Back to task: no active task to resume
+```
+
+**Question requires a long answer:**
+Give the essential answer concisely, then offer:
+```
+That's the short version. Want a deeper explanation after we finish [current task]?
+```
+
+**Multiple `/aside` questions in a row:**
+Answer each one in sequence. After the last answer, resume the main task. Do not lose task state across a chain of asides.
+
+**Aside answer implies a code change is needed:**
+Note the change needed but do not make it during the aside:
+```
+ASIDE: [answer]
+
+📝 Worth fixing: [what should be changed]. I'll flag this after the current task unless you want to address it now.
+```
+
+**Question is ambiguous or too vague:**
+Ask one clarifying question — the shortest question that gets the information needed to answer. Do not ask multiple questions.
+
+---
+
+## Example Output
+
+```
+User: /aside what does fetchWithRetry() actually do?
+
+ASIDE: what does fetchWithRetry() do?
+
+fetchWithRetry() (src/api/retry.ts:12) attempts the request up to 3 times with
+exponential backoff (250ms → 500ms → 1s). It only retries on 5xx responses and
+network errors — 4xx errors are treated as final and not retried.
+
+— Back to task: refactoring the auth middleware in src/middleware/auth.ts
+```
+
+```
+User: /aside is the approach we're taking thread-safe?
+
+ASIDE: is the current approach thread-safe?
+
+No — the shared cache object in src/cache/store.ts:34 is mutated without locking.
+Under concurrent requests this is a race condition. It's low risk in a single-process
+Node.js server but would be a real problem with worker threads or clustering.
+
+⚠️ Note: This could affect the feature we're building. Want to address this now or continue and fix it in a follow-up?
+```
+
+---
+
+## Notes
+
+- Never modify files during an aside — read-only access only
+- The aside is a conversation pause, not a new task — the original task must always resume
+- Keep answers focused: the goal is to unblock the user quickly, not to deliver a lecture
+- If an aside sparks a larger discussion, finish the current task first unless the aside reveals a blocker
+- Asides are not saved to session files unless explicitly relevant to the task outcome

commands/e2e.md

@@ -337,8 +337,10 @@ For PMX, prioritize these E2E tests:
 
 ## Related Agents
 
-This command invokes the `e2e-runner` agent located at:
-`~/.claude/agents/e2e-runner.md`
+This command invokes the `e2e-runner` agent provided by ECC.
+
+For manual installs, the source file lives at:
+`agents/e2e-runner.md`
 
 ## Quick Commands
 

commands/gradle-build.md

@@ -0,0 +1,70 @@
+---
+description: Fix Gradle build errors for Android and KMP projects
+---
+
+# Gradle Build Fix
+
+Incrementally fix Gradle build and compilation errors for Android and Kotlin Multiplatform projects.
+
+## Step 1: Detect Build Configuration
+
+Identify the project type and run the appropriate build:
+
+| Indicator | Build Command |
+|-----------|---------------|
+| `build.gradle.kts` + `composeApp/` (KMP) | `./gradlew composeApp:compileKotlinMetadata 2>&1` |
+| `build.gradle.kts` + `app/` (Android) | `./gradlew app:compileDebugKotlin 2>&1` |
+| `settings.gradle.kts` with modules | `./gradlew assemble 2>&1` |
+| Detekt configured | `./gradlew detekt 2>&1` |
+
+Also check `gradle.properties` and `local.properties` for configuration.
+
+## Step 2: Parse and Group Errors
+
+1. Run the build command and capture output
+2. Separate Kotlin compilation errors from Gradle configuration errors
+3. Group by module and file path
+4. Sort: configuration errors first, then compilation errors by dependency order
+
+## Step 3: Fix Loop
+
+For each error:
+
+1. **Read the file** — Full context around the error line
+2. **Diagnose** — Common categories:
+   - Missing import or unresolved reference
+   - Type mismatch or incompatible types
+   - Missing dependency in `build.gradle.kts`
+   - Expect/actual mismatch (KMP)
+   - Compose compiler error
+3. **Fix minimally** — Smallest change that resolves the error
+4. **Re-run build** — Verify fix and check for new errors
+5. **Continue** — Move to next error
+
+## Step 4: Guardrails
+
+Stop and ask the user if:
+- Fix introduces more errors than it resolves
+- Same error persists after 3 attempts
+- Error requires adding new dependencies or changing module structure
+- Gradle sync itself fails (configuration-phase error)
+- Error is in generated code (Room, SQLDelight, KSP)
+
+## Step 5: Summary
+
+Report:
+- Errors fixed (module, file, description)
+- Errors remaining
+- New errors introduced (should be zero)
+- Suggested next steps
+
+## Common Gradle/KMP Fixes
+
+| Error | Fix |
+|-------|-----|
+| Unresolved reference in `commonMain` | Check if the dependency is in `commonMain.dependencies {}` |
+| Expect declaration without actual | Add `actual` implementation in each platform source set |
+| Compose compiler version mismatch | Align Kotlin and Compose compiler versions in `libs.versions.toml` |
+| Duplicate class | Check for conflicting dependencies with `./gradlew dependencies` |
+| KSP error | Run `./gradlew kspCommonMainKotlinMetadata` to regenerate |
+| Configuration cache issue | Check for non-serializable task inputs |

commands/kotlin-build.md

@@ -0,0 +1,174 @@
+---
+description: Fix Kotlin/Gradle build errors, compiler warnings, and dependency issues incrementally. Invokes the kotlin-build-resolver agent for minimal, surgical fixes.
+---
+
+# Kotlin Build and Fix
+
+This command invokes the **kotlin-build-resolver** agent to incrementally fix Kotlin build errors with minimal changes.
+
+## What This Command Does
+
+1. **Run Diagnostics**: Execute `./gradlew build`, `detekt`, `ktlintCheck`
+2. **Parse Errors**: Group by file and sort by severity
+3. **Fix Incrementally**: One error at a time
+4. **Verify Each Fix**: Re-run build after each change
+5. **Report Summary**: Show what was fixed and what remains
+
+## When to Use
+
+Use `/kotlin-build` when:
+- `./gradlew build` fails with errors
+- Kotlin compiler reports errors
+- `./gradlew detekt` reports violations
+- Gradle dependency resolution fails
+- After pulling changes that break the build
+
+## Diagnostic Commands Run
+
+```bash
+# Primary build check
+./gradlew build 2>&1
+
+# Static analysis
+./gradlew detekt 2>&1 || echo "detekt not configured"
+./gradlew ktlintCheck 2>&1 || echo "ktlint not configured"
+
+# Dependency issues
+./gradlew dependencies --configuration runtimeClasspath 2>&1 | head -100
+
+# Optional deep refresh when caches or dependency metadata are suspect
+./gradlew build --refresh-dependencies
+```
+
+## Example Session
+
+````text
+User: /kotlin-build
+
+Agent:
+# Kotlin Build Resolution
+
+## Initial Diagnostics
+
+```bash
+$ ./gradlew build
+e: src/main/kotlin/com/example/service/UserService.kt:25:15 Unresolved reference: UserRepository
+e: src/main/kotlin/com/example/routes/UserRoutes.kt:42:9 Type mismatch: inferred type is String but Int was expected
+e: src/main/kotlin/com/example/routes/UserRoutes.kt:58:5 'when' expression must be exhaustive
+```
+
+Errors found: 3
+
+## Fix 1: Unresolved Reference
+
+File: src/main/kotlin/com/example/service/UserService.kt:25
+Error: Unresolved reference: UserRepository
+Cause: Missing import
+
+```kotlin
+// Added import
+import com.example.repository.UserRepository
+```
+
+```bash
+$ ./gradlew build
+# 2 errors remaining
+```
+
+## Fix 2: Type Mismatch
+
+File: src/main/kotlin/com/example/routes/UserRoutes.kt:42
+Error: Type mismatch: inferred type is String but Int was expected
+
+```kotlin
+// Changed
+val count = call.parameters["count"]
+// To
+val count = call.parameters["count"]?.toIntOrNull()
+    ?: return@get call.respond(HttpStatusCode.BadRequest, "Invalid count")
+```
+
+```bash
+$ ./gradlew build
+# 1 error remaining
+```
+
+## Fix 3: Non-Exhaustive When
+
+File: src/main/kotlin/com/example/routes/UserRoutes.kt:58
+Error: 'when' expression must be exhaustive
+
+```kotlin
+// Added missing branch
+when (user.role) {
+    Role.ADMIN -> handleAdmin(user)
+    Role.USER -> handleUser(user)
+    Role.MODERATOR -> handleModerator(user) // Added
+}
+```
+
+```bash
+$ ./gradlew build
+# Build successful!
+```
+
+## Final Verification
+
+```bash
+$ ./gradlew detekt
+# No issues
+
+$ ./gradlew test
+# All tests passed
+```
+
+## Summary
+
+| Metric | Count |
+|--------|-------|
+| Build errors fixed | 3 |
+| Detekt issues fixed | 0 |
+| Files modified | 2 |
+| Remaining issues | 0 |
+
+Build Status: ✅ SUCCESS
+````
+
+## Common Errors Fixed
+
+| Error | Typical Fix |
+|-------|-------------|
+| `Unresolved reference: X` | Add import or dependency |
+| `Type mismatch` | Fix type conversion or assignment |
+| `'when' must be exhaustive` | Add missing sealed class branches |
+| `Suspend function can only be called from coroutine` | Add `suspend` modifier |
+| `Smart cast impossible` | Use local `val` or `let` |
+| `None of the following candidates is applicable` | Fix argument types |
+| `Could not resolve dependency` | Fix version or add repository |
+
+## Fix Strategy
+
+1. **Build errors first** - Code must compile
+2. **Detekt violations second** - Fix code quality issues
+3. **ktlint warnings third** - Fix formatting
+4. **One fix at a time** - Verify each change
+5. **Minimal changes** - Don't refactor, just fix
+
+## Stop Conditions
+
+The agent will stop and report if:
+- Same error persists after 3 attempts
+- Fix introduces more errors
+- Requires architectural changes
+- Missing external dependencies
+
+## Related Commands
+
+- `/kotlin-test` - Run tests after build succeeds
+- `/kotlin-review` - Review code quality
+- `/verify` - Full verification loop
+
+## Related
+
+- Agent: `agents/kotlin-build-resolver.md`
+- Skill: `skills/kotlin-patterns/`

commands/kotlin-review.md

@@ -0,0 +1,140 @@
+---
+description: Comprehensive Kotlin code review for idiomatic patterns, null safety, coroutine safety, and security. Invokes the kotlin-reviewer agent.
+---
+
+# Kotlin Code Review
+
+This command invokes the **kotlin-reviewer** agent for comprehensive Kotlin-specific code review.
+
+## What This Command Does
+
+1. **Identify Kotlin Changes**: Find modified `.kt` and `.kts` files via `git diff`
+2. **Run Build & Static Analysis**: Execute `./gradlew build`, `detekt`, `ktlintCheck`
+3. **Security Scan**: Check for SQL injection, command injection, hardcoded secrets
+4. **Null Safety Review**: Analyze `!!` usage, platform type handling, unsafe casts
+5. **Coroutine Review**: Check structured concurrency, dispatcher usage, cancellation
+6. **Generate Report**: Categorize issues by severity
+
+## When to Use
+
+Use `/kotlin-review` when:
+- After writing or modifying Kotlin code
+- Before committing Kotlin changes
+- Reviewing pull requests with Kotlin code
+- Onboarding to a new Kotlin codebase
+- Learning idiomatic Kotlin patterns
+
+## Review Categories
+
+### CRITICAL (Must Fix)
+- SQL/Command injection vulnerabilities
+- Force-unwrap `!!` without justification
+- Platform type null safety violations
+- GlobalScope usage (structured concurrency violation)
+- Hardcoded credentials
+- Unsafe deserialization
+
+### HIGH (Should Fix)
+- Mutable state where immutable suffices
+- Blocking calls inside coroutine context
+- Missing cancellation checks in long loops
+- Non-exhaustive `when` on sealed types
+- Large functions (>50 lines)
+- Deep nesting (>4 levels)
+
+### MEDIUM (Consider)
+- Non-idiomatic Kotlin (Java-style patterns)
+- Missing trailing commas
+- Scope function misuse or nesting
+- Missing sequence for large collection chains
+- Redundant explicit types
+
+## Automated Checks Run
+
+```bash
+# Build check
+./gradlew build
+
+# Static analysis
+./gradlew detekt
+
+# Formatting check
+./gradlew ktlintCheck
+
+# Tests
+./gradlew test
+```
+
+## Example Usage
+
+````text
+User: /kotlin-review
+
+Agent:
+# Kotlin Code Review Report
+
+## Files Reviewed
+- src/main/kotlin/com/example/service/UserService.kt (modified)
+- src/main/kotlin/com/example/routes/UserRoutes.kt (modified)
+
+## Static Analysis Results
+✓ Build: Successful
+✓ detekt: No issues
+⚠ ktlint: 2 formatting warnings
+
+## Issues Found
+
+[CRITICAL] Force-Unwrap Null Safety
+File: src/main/kotlin/com/example/service/UserService.kt:28
+Issue: Using !! on nullable repository result
+```kotlin
+val user = repository.findById(id)!!  // NPE risk
+```
+Fix: Use safe call with error handling
+```kotlin
+val user = repository.findById(id)
+    ?: throw UserNotFoundException("User $id not found")
+```
+
+[HIGH] GlobalScope Usage
+File: src/main/kotlin/com/example/routes/UserRoutes.kt:45
+Issue: Using GlobalScope breaks structured concurrency
+```kotlin
+GlobalScope.launch {
+    notificationService.sendWelcome(user)
+}
+```
+Fix: Use the call's coroutine scope
+```kotlin
+launch {
+    notificationService.sendWelcome(user)
+}
+```
+
+## Summary
+- CRITICAL: 1
+- HIGH: 1
+- MEDIUM: 0
+
+Recommendation: ❌ Block merge until CRITICAL issue is fixed
+````
+
+## Approval Criteria
+
+| Status | Condition |
+|--------|-----------|
+| ✅ Approve | No CRITICAL or HIGH issues |
+| ⚠️ Warning | Only MEDIUM issues (merge with caution) |
+| ❌ Block | CRITICAL or HIGH issues found |
+
+## Integration with Other Commands
+
+- Use `/kotlin-test` first to ensure tests pass
+- Use `/kotlin-build` if build errors occur
+- Use `/kotlin-review` before committing
+- Use `/code-review` for non-Kotlin-specific concerns
+
+## Related
+
+- Agent: `agents/kotlin-reviewer.md`
+- Skills: `skills/kotlin-patterns/`, `skills/kotlin-testing/`

commands/kotlin-test.md

@@ -0,0 +1,312 @@
+---
+description: Enforce TDD workflow for Kotlin. Write Kotest tests first, then implement. Verify 80%+ coverage with Kover.
+---
+
+# Kotlin TDD Command
+
+This command enforces test-driven development methodology for Kotlin code using Kotest, MockK, and Kover.
+
+## What This Command Does
+
+1. **Define Types/Interfaces**: Scaffold function signatures first
+2. **Write Kotest Tests**: Create comprehensive test specs (RED)
+3. **Run Tests**: Verify tests fail for the right reason
+4. **Implement Code**: Write minimal code to pass (GREEN)
+5. **Refactor**: Improve while keeping tests green
+6. **Check Coverage**: Ensure 80%+ coverage with Kover
+
+## When to Use
+
+Use `/kotlin-test` when:
+- Implementing new Kotlin functions or classes
+- Adding test coverage to existing Kotlin code
+- Fixing bugs (write failing test first)
+- Building critical business logic
+- Learning TDD workflow in Kotlin
+
+## TDD Cycle
+
+```
+RED     -> Write failing Kotest test
+GREEN   -> Implement minimal code to pass
+REFACTOR -> Improve code, tests stay green
+REPEAT  -> Next test case
+```
+
+## Example Session
+
+````text
+User: /kotlin-test I need a function to validate user registration requests
+
+Agent:
+# TDD Session: Registration Validator
+
+## Step 1: Define Interface
+
+```kotlin
+// validator/RegistrationValidator.kt
+package com.example.validator
+
+data class RegistrationRequest(
+    val name: String,
+    val email: String,
+    val password: String,
+)
+
+sealed class ValidationResult {
+    data object Valid : ValidationResult()
+    data class Invalid(val errors: List<String>) : ValidationResult()
+}
+
+fun validateRegistration(request: RegistrationRequest): ValidationResult {
+    TODO("not implemented")
+}
+```
+
+## Step 2: Write Kotest Tests (RED)
+
+```kotlin
+// validator/RegistrationValidatorTest.kt
+package com.example.validator
+
+import io.kotest.core.spec.style.FunSpec
+import io.kotest.matchers.shouldBe
+import io.kotest.matchers.types.shouldBeInstanceOf
+
+class RegistrationValidatorTest : FunSpec({
+    test("valid registration returns Valid") {
+        val request = RegistrationRequest(
+            name = "Alice",
+            email = "alice@example.com",
+            password = "SecureP@ss1",
+        )
+
+        val result = validateRegistration(request)
+
+        result.shouldBeInstanceOf<ValidationResult.Valid>()
+    }
+
+    test("blank name returns Invalid") {
+        val request = RegistrationRequest(
+            name = "",
+            email = "alice@example.com",
+            password = "SecureP@ss1",
+        )
+
+        val result = validateRegistration(request)
+
+        val invalid = result.shouldBeInstanceOf<ValidationResult.Invalid>()
+        invalid.errors shouldBe listOf("Name is required")
+    }
+
+    test("invalid email returns Invalid") {
+        val request = RegistrationRequest(
+            name = "Alice",
+            email = "not-an-email",
+            password = "SecureP@ss1",
+        )
+
+        val result = validateRegistration(request)
+
+        val invalid = result.shouldBeInstanceOf<ValidationResult.Invalid>()
+        invalid.errors shouldBe listOf("Invalid email format")
+    }
+
+    test("short password returns Invalid") {
+        val request = RegistrationRequest(
+            name = "Alice",
+            email = "alice@example.com",
+            password = "short",
+        )
+
+        val result = validateRegistration(request)
+
+        val invalid = result.shouldBeInstanceOf<ValidationResult.Invalid>()
+        invalid.errors shouldBe listOf("Password must be at least 8 characters")
+    }
+
+    test("multiple errors returns all errors") {
+        val request = RegistrationRequest(
+            name = "",
+            email = "bad",
+            password = "short",
+        )
+
+        val result = validateRegistration(request)
+
+        val invalid = result.shouldBeInstanceOf<ValidationResult.Invalid>()
+        invalid.errors.size shouldBe 3
+    }
+})
+```
+
+## Step 3: Run Tests - Verify FAIL
+
+```bash
+$ ./gradlew test
+
+RegistrationValidatorTest > valid registration returns Valid FAILED
+  kotlin.NotImplementedError: An operation is not implemented
+
+FAILED (5 tests, 0 passed, 5 failed)
+```
+
+✓ Tests fail as expected (NotImplementedError).
+
+## Step 4: Implement Minimal Code (GREEN)
+
+```kotlin
+// validator/RegistrationValidator.kt
+package com.example.validator
+
+private val EMAIL_REGEX = Regex("^[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\\.[A-Za-z]{2,}$")
+private const val MIN_PASSWORD_LENGTH = 8
+
+fun validateRegistration(request: RegistrationRequest): ValidationResult {
+    val errors = buildList {
+        if (request.name.isBlank()) add("Name is required")
+        if (!EMAIL_REGEX.matches(request.email)) add("Invalid email format")
+        if (request.password.length < MIN_PASSWORD_LENGTH) add("Password must be at least $MIN_PASSWORD_LENGTH characters")
+    }
+
+    return if (errors.isEmpty()) ValidationResult.Valid
+    else ValidationResult.Invalid(errors)
+}
+```
+
+## Step 5: Run Tests - Verify PASS
+
+```bash
+$ ./gradlew test
+
+RegistrationValidatorTest > valid registration returns Valid PASSED
+RegistrationValidatorTest > blank name returns Invalid PASSED
+RegistrationValidatorTest > invalid email returns Invalid PASSED
+RegistrationValidatorTest > short password returns Invalid PASSED
+RegistrationValidatorTest > multiple errors returns all errors PASSED
+
+PASSED (5 tests, 5 passed, 0 failed)
+```
+
+✓ All tests passing!
+
+## Step 6: Check Coverage
+
+```bash
+$ ./gradlew koverHtmlReport
+
+Coverage: 100.0% of statements
+```
+
+✓ Coverage: 100%
+
+## TDD Complete!
+````
+
+## Test Patterns
+
+### StringSpec (Simplest)
+
+```kotlin
+class CalculatorTest : StringSpec({
+    "add two positive numbers" {
+        Calculator.add(2, 3) shouldBe 5
+    }
+})
+```
+
+### BehaviorSpec (BDD)
+
+```kotlin
+class OrderServiceTest : BehaviorSpec({
+    Given("a valid order") {
+        When("placed") {
+            Then("should be confirmed") { /* ... */ }
+        }
+    }
+})
+```
+
+### Data-Driven Tests
+
+```kotlin
+class ParserTest : FunSpec({
+    context("valid inputs") {
+        withData("2026-01-15", "2026-12-31", "2000-01-01") { input ->
+            parseDate(input).shouldNotBeNull()
+        }
+    }
+})
+```
+
+### Coroutine Testing
+
+```kotlin
+class AsyncServiceTest : FunSpec({
+    test("concurrent fetch completes") {
+        runTest {
+            val result = service.fetchAll()
+            result.shouldNotBeEmpty()
+        }
+    }
+})
+```
+
+## Coverage Commands
+
+```bash
+# Run tests with coverage
+./gradlew koverHtmlReport
+
+# Verify coverage thresholds
+./gradlew koverVerify
+
+# XML report for CI
+./gradlew koverXmlReport
+
+# Open HTML report
+open build/reports/kover/html/index.html
+
+# Run specific test class
+./gradlew test --tests "com.example.UserServiceTest"
+
+# Run with verbose output
+./gradlew test --info
+```
+
+## Coverage Targets
+
+| Code Type | Target |
+|-----------|--------|
+| Critical business logic | 100% |
+| Public APIs | 90%+ |
+| General code | 80%+ |
+| Generated code | Exclude |
+
+## TDD Best Practices
+
+**DO:**
+- Write test FIRST, before any implementation
+- Run tests after each change
+- Use Kotest matchers for expressive assertions
+- Use MockK's `coEvery`/`coVerify` for suspend functions
+- Test behavior, not implementation details
+- Include edge cases (empty, null, max values)
+
+**DON'T:**
+- Write implementation before tests
+- Skip the RED phase
+- Test private functions directly
+- Use `Thread.sleep()` in coroutine tests
+- Ignore flaky tests
+
+## Related Commands
+
+- `/kotlin-build` - Fix build errors
+- `/kotlin-review` - Review code after implementation
+- `/verify` - Run full verification loop
+
+## Related
+
+- Skill: `skills/kotlin-testing/`
+- Skill: `skills/tdd-workflow/`

commands/learn-eval.md

@@ -1,10 +1,10 @@
 ---
-description: Extract reusable patterns from the session, self-evaluate quality before saving, and determine the right save location (Global vs Project).
+description: "Extract reusable patterns from the session, self-evaluate quality before saving, and determine the right save location (Global vs Project)."
 ---
 
 # /learn-eval - Extract, Evaluate, then Save
 
-Extends `/learn` with a quality gate and save-location decision before writing any skill file.
+Extends `/learn` with a quality gate, save-location decision, and knowledge-placement awareness before writing any skill file.
 
 ## What to Extract
 
@@ -51,36 +51,61 @@ origin: auto-extracted
 [Trigger conditions]
 ```
 
-5. **Self-evaluate before saving** using this rubric:
+5. **Quality gate — Checklist + Holistic verdict**
 
-   | Dimension | 1 | 3 | 5 |
-   |-----------|---|---|---|
-   | Specificity | Abstract principles only, no code examples | Representative code example present | Rich examples covering all usage patterns |
-   | Actionability | Unclear what to do | Main steps are understandable | Immediately actionable, edge cases covered |
-   | Scope Fit | Too broad or too narrow | Mostly appropriate, some boundary ambiguity | Name, trigger, and content perfectly aligned |
-   | Non-redundancy | Nearly identical to another skill | Some overlap but unique perspective exists | Completely unique value |
-   | Coverage | Covers only a fraction of the target task | Main cases covered, common variants missing | Main cases, edge cases, and pitfalls covered |
+   ### 5a. Required checklist (verify by actually reading files)
 
-   - Score each dimension 1–5
-   - If any dimension scores 1–2, improve the draft and re-score until all dimensions are ≥ 3
-   - Show the user the scores table and the final draft
+   Execute **all** of the following before evaluating the draft:
 
-6. Ask user to confirm:
-   - Show: proposed save path + scores table + final draft
-   - Wait for explicit confirmation before writing
+   - [ ] Grep `~/.claude/skills/` and relevant project `.claude/skills/` files by keyword to check for content overlap
+   - [ ] Check MEMORY.md (both project and global) for overlap
+   - [ ] Consider whether appending to an existing skill would suffice
+   - [ ] Confirm this is a reusable pattern, not a one-off fix
 
-7. Save to the determined location
+   ### 5b. Holistic verdict
 
-## Output Format for Step 5 (scores table)
+   Synthesize the checklist results and draft quality, then choose **one** of the following:
 
-| Dimension | Score | Rationale |
-|-----------|-------|-----------|
-| Specificity | N/5 | ... |
-| Actionability | N/5 | ... |
-| Scope Fit | N/5 | ... |
-| Non-redundancy | N/5 | ... |
-| Coverage | N/5 | ... |
-| **Total** | **N/25** | |
+   | Verdict | Meaning | Next Action |
+   |---------|---------|-------------|
+   | **Save** | Unique, specific, well-scoped | Proceed to Step 6 |
+   | **Improve then Save** | Valuable but needs refinement | List improvements → revise → re-evaluate (once) |
+   | **Absorb into [X]** | Should be appended to an existing skill | Show target skill and additions → Step 6 |
+   | **Drop** | Trivial, redundant, or too abstract | Explain reasoning and stop |
+
+   **Guideline dimensions** (informing the verdict, not scored):
+
+   - **Specificity & Actionability**: Contains code examples or commands that are immediately usable
+   - **Scope Fit**: Name, trigger conditions, and content are aligned and focused on a single pattern
+   - **Uniqueness**: Provides value not covered by existing skills (informed by checklist results)
+   - **Reusability**: Realistic trigger scenarios exist in future sessions
+
+6. **Verdict-specific confirmation flow**
+
+   - **Improve then Save**: Present the required improvements + revised draft + updated checklist/verdict after one re-evaluation; if the revised verdict is **Save**, save after user confirmation, otherwise follow the new verdict
+   - **Save**: Present save path + checklist results + 1-line verdict rationale + full draft → save after user confirmation
+   - **Absorb into [X]**: Present target path + additions (diff format) + checklist results + verdict rationale → append after user confirmation
+   - **Drop**: Show checklist results + reasoning only (no confirmation needed)
+
+7. Save / Absorb to the determined location
+
+## Output Format for Step 5
+
+```
+### Checklist
+- [x] skills/ grep: no overlap (or: overlap found → details)
+- [x] MEMORY.md: no overlap (or: overlap found → details)
+- [x] Existing skill append: new file appropriate (or: should append to [X])
+- [x] Reusability: confirmed (or: one-off → Drop)
+
+### Verdict: Save / Improve then Save / Absorb into [X] / Drop
+
+**Rationale:** (1-2 sentences explaining the verdict)
+```
+
+## Design Rationale
+
+This version replaces the previous 5-dimension numeric scoring rubric (Specificity, Actionability, Scope Fit, Non-redundancy, Coverage scored 1-5) with a checklist-based holistic verdict system. Modern frontier models (Opus 4.6+) have strong contextual judgment — forcing rich qualitative signals into numeric scores loses nuance and can produce misleading totals. The holistic approach lets the model weigh all factors naturally, producing more accurate save/drop decisions while the explicit checklist ensures no critical check is skipped.
 
 ## Notes
 
@@ -88,4 +113,4 @@ origin: auto-extracted
 - Don't extract one-time issues (specific API outages, etc.)
 - Focus on patterns that will save time in future sessions
 - Keep skills focused — one pattern per skill
-- If Coverage score is low, add related variants before saving
+- When the verdict is Absorb, append to the existing skill rather than creating a new file

commands/multi-workflow.md

@@ -101,6 +101,14 @@ TaskOutput({ task_id: "<task_id>", block: true, timeout: 600000 })
 4. Force stop when score < 7 or user does not approve.
 5. Use `AskUserQuestion` tool for user interaction when needed (e.g., confirmation/selection/approval).
 
+## When to Use External Orchestration
+
+Use external tmux/worktree orchestration when the work must be split across parallel workers that need isolated git state, independent terminals, or separate build/test execution. Use in-process subagents for lightweight analysis, planning, or review where the main session remains the only writer.
+
+```bash
+node scripts/orchestrate-worktrees.js .claude/plan/workflow-e2e-test.json --execute
+```
+
 ---
 
 ## Execution Workflow

commands/orchestrate.md

@@ -148,6 +148,61 @@ Run simultaneously:
 Combine outputs into single report
 ```
 
+For external tmux-pane workers with separate git worktrees, use `node scripts/orchestrate-worktrees.js plan.json --execute`. The built-in orchestration pattern stays in-process; the helper is for long-running or cross-harness sessions.
+
+When workers need to see dirty or untracked local files from the main checkout, add `seedPaths` to the plan file. ECC overlays only those selected paths into each worker worktree after `git worktree add`, which keeps the branch isolated while still exposing in-flight local scripts, plans, or docs.
+
+```json
+{
+  "sessionName": "workflow-e2e",
+  "seedPaths": [
+    "scripts/orchestrate-worktrees.js",
+    "scripts/lib/tmux-worktree-orchestrator.js",
+    ".claude/plan/workflow-e2e-test.json"
+  ],
+  "workers": [
+    { "name": "docs", "task": "Update orchestration docs." }
+  ]
+}
+```
+
+To export a control-plane snapshot for a live tmux/worktree session, run:
+
+```bash
+node scripts/orchestration-status.js .claude/plan/workflow-visual-proof.json
+```
+
+The snapshot includes session activity, tmux pane metadata, worker states, objectives, seeded overlays, and recent handoff summaries in JSON form.
+
+## Operator Command-Center Handoff
+
+When the workflow spans multiple sessions, worktrees, or tmux panes, append a control-plane block to the final handoff:
+
+```markdown
+CONTROL PLANE
+-------------
+Sessions:
+- active session ID or alias
+- branch + worktree path for each active worker
+- tmux pane or detached session name when applicable
+
+Diffs:
+- git status summary
+- git diff --stat for touched files
+- merge/conflict risk notes
+
+Approvals:
+- pending user approvals
+- blocked steps awaiting confirmation
+
+Telemetry:
+- last activity timestamp or idle signal
+- estimated token or cost drift
+- policy events raised by hooks or reviewers
+```
+
+This keeps planner, implementer, reviewer, and loop workers legible from the operator surface.
+
 ## Arguments
 
 $ARGUMENTS:

commands/plan.md

@@ -109,5 +109,7 @@ After planning:
 
 ## Related Agents
 
-This command invokes the `planner` agent located at:
-`~/.claude/agents/planner.md`
+This command invokes the `planner` agent provided by ECC.
+
+For manual installs, the source file lives at:
+`agents/planner.md`

commands/prompt-optimize.md

@@ -0,0 +1,38 @@
+---
+description: Analyze a draft prompt and output an optimized, ECC-enriched version ready to paste and run. Does NOT execute the task — outputs advisory analysis only.
+---
+
+# /prompt-optimize
+
+Analyze and optimize the following prompt for maximum ECC leverage.
+
+## Your Task
+
+Apply the **prompt-optimizer** skill to the user's input below. Follow the 6-phase analysis pipeline:
+
+0. **Project Detection** — Read CLAUDE.md, detect tech stack from project files (package.json, go.mod, pyproject.toml, etc.)
+1. **Intent Detection** — Classify the task type (new feature, bug fix, refactor, research, testing, review, documentation, infrastructure, design)
+2. **Scope Assessment** — Evaluate complexity (TRIVIAL / LOW / MEDIUM / HIGH / EPIC), using codebase size as signal if detected
+3. **ECC Component Matching** — Map to specific skills, commands, agents, and model tier
+4. **Missing Context Detection** — Identify gaps. If 3+ critical items missing, ask the user to clarify before generating
+5. **Workflow & Model** — Determine lifecycle position, recommend model tier, and split into multiple prompts if HIGH/EPIC
+
+## Output Requirements
+
+- Present diagnosis, recommended ECC components, and an optimized prompt using the Output Format from the prompt-optimizer skill
+- Provide both **Full Version** (detailed) and **Quick Version** (compact, varied by intent type)
+- Respond in the same language as the user's input
+- The optimized prompt must be complete and ready to copy-paste into a new session
+- End with a footer offering adjustment or a clear next step for starting a separate execution request
+
+## CRITICAL
+
+Do NOT execute the user's task. Output ONLY the analysis and optimized prompt.
+If the user asks for direct execution, explain that `/prompt-optimize` only produces advisory output and tell them to start a normal task request instead.
+
+Note: `blueprint` is a **skill**, not a slash command. Write "Use the blueprint skill"
+instead of presenting it as a `/...` command.
+
+## User Input
+
+$ARGUMENTS

commands/resume-session.md

@@ -0,0 +1,155 @@
+---
+description: Load the most recent session file from ~/.claude/sessions/ and resume work with full context from where the last session ended.
+---
+
+# Resume Session Command
+
+Load the last saved session state and orient fully before doing any work.
+This command is the counterpart to `/save-session`.
+
+## When to Use
+
+- Starting a new session to continue work from a previous day
+- After starting a fresh session due to context limits
+- When handing off a session file from another source (just provide the file path)
+- Any time you have a session file and want Claude to fully absorb it before proceeding
+
+## Usage
+
+```
+/resume-session                                                      # loads most recent file in ~/.claude/sessions/
+/resume-session 2024-01-15                                           # loads most recent session for that date
+/resume-session ~/.claude/sessions/2024-01-15-session.tmp           # loads a specific legacy-format file
+/resume-session ~/.claude/sessions/2024-01-15-abc123de-session.tmp  # loads a current short-id session file
+```
+
+## Process
+
+### Step 1: Find the session file
+
+If no argument provided:
+
+1. Check `~/.claude/sessions/`
+2. Pick the most recently modified `*-session.tmp` file
+3. If the folder does not exist or has no matching files, tell the user:
+   ```
+   No session files found in ~/.claude/sessions/
+   Run /save-session at the end of a session to create one.
+   ```
+   Then stop.
+
+If an argument is provided:
+
+- If it looks like a date (`YYYY-MM-DD`), search `~/.claude/sessions/` for files matching
+  `YYYY-MM-DD-session.tmp` (legacy format) or `YYYY-MM-DD-<shortid>-session.tmp` (current format)
+  and load the most recently modified variant for that date
+- If it looks like a file path, read that file directly
+- If not found, report clearly and stop
+
+### Step 2: Read the entire session file
+
+Read the complete file. Do not summarize yet.
+
+### Step 3: Confirm understanding
+
+Respond with a structured briefing in this exact format:
+
+```
+SESSION LOADED: [actual resolved path to the file]
+════════════════════════════════════════════════
+
+PROJECT: [project name / topic from file]
+
+WHAT WE'RE BUILDING:
+[2-3 sentence summary in your own words]
+
+CURRENT STATE:
+✅ Working: [count] items confirmed
+🔄 In Progress: [list files that are in progress]
+🗒️ Not Started: [list planned but untouched]
+
+WHAT NOT TO RETRY:
+[list every failed approach with its reason — this is critical]
+
+OPEN QUESTIONS / BLOCKERS:
+[list any blockers or unanswered questions]
+
+NEXT STEP:
+[exact next step if defined in the file]
+[if not defined: "No next step defined — recommend reviewing 'What Has NOT Been Tried Yet' together before starting"]
+
+════════════════════════════════════════════════
+Ready to continue. What would you like to do?
+```
+
+### Step 4: Wait for the user
+
+Do NOT start working automatically. Do NOT touch any files. Wait for the user to say what to do next.
+
+If the next step is clearly defined in the session file and the user says "continue" or "yes" or similar — proceed with that exact next step.
+
+If no next step is defined — ask the user where to start, and optionally suggest an approach from the "What Has NOT Been Tried Yet" section.
+
+---
+
+## Edge Cases
+
+**Multiple sessions for the same date** (`2024-01-15-session.tmp`, `2024-01-15-abc123de-session.tmp`):
+Load the most recently modified matching file for that date, regardless of whether it uses the legacy no-id format or the current short-id format.
+
+**Session file references files that no longer exist:**
+Note this during the briefing — "⚠️ `path/to/file.ts` referenced in session but not found on disk."
+
+**Session file is from more than 7 days ago:**
+Note the gap — "⚠️ This session is from N days ago (threshold: 7 days). Things may have changed." — then proceed normally.
+
+**User provides a file path directly (e.g., forwarded from a teammate):**
+Read it and follow the same briefing process — the format is the same regardless of source.
+
+**Session file is empty or malformed:**
+Report: "Session file found but appears empty or unreadable. You may need to create a new one with /save-session."
+
+---
+
+## Example Output
+
+```
+SESSION LOADED: /Users/you/.claude/sessions/2024-01-15-abc123de-session.tmp
+════════════════════════════════════════════════
+
+PROJECT: my-app — JWT Authentication
+
+WHAT WE'RE BUILDING:
+User authentication with JWT tokens stored in httpOnly cookies.
+Register and login endpoints are partially done. Route protection
+via middleware hasn't been started yet.
+
+CURRENT STATE:
+✅ Working: 3 items (register endpoint, JWT generation, password hashing)
+🔄 In Progress: app/api/auth/login/route.ts (token works, cookie not set yet)
+🗒️ Not Started: middleware.ts, app/login/page.tsx
+
+WHAT NOT TO RETRY:
+❌ Next-Auth — conflicts with custom Prisma adapter, threw adapter error on every request
+❌ localStorage for JWT — causes SSR hydration mismatch, incompatible with Next.js
+
+OPEN QUESTIONS / BLOCKERS:
+- Does cookies().set() work inside a Route Handler or only Server Actions?
+
+NEXT STEP:
+In app/api/auth/login/route.ts — set the JWT as an httpOnly cookie using
+cookies().set('token', jwt, { httpOnly: true, secure: true, sameSite: 'strict' })
+then test with Postman for a Set-Cookie header in the response.
+
+════════════════════════════════════════════════
+Ready to continue. What would you like to do?
+```
+
+---
+
+## Notes
+
+- Never modify the session file when loading it — it's a read-only historical record
+- The briefing format is fixed — do not skip sections even if they are empty
+- "What Not To Retry" must always be shown, even if it just says "None" — it's too important to miss
+- After resuming, the user may want to run `/save-session` again at the end of the new session to create a new dated file

commands/save-session.md

@@ -0,0 +1,275 @@
+---
+description: Save current session state to a dated file in ~/.claude/sessions/ so work can be resumed in a future session with full context.
+---
+
+# Save Session Command
+
+Capture everything that happened in this session — what was built, what worked, what failed, what's left — and write it to a dated file so the next session can pick up exactly where this one left off.
+
+## When to Use
+
+- End of a work session before closing Claude Code
+- Before hitting context limits (run this first, then start a fresh session)
+- After solving a complex problem you want to remember
+- Any time you need to hand off context to a future session
+
+## Process
+
+### Step 1: Gather context
+
+Before writing the file, collect:
+
+- Read all files modified during this session (use git diff or recall from conversation)
+- Review what was discussed, attempted, and decided
+- Note any errors encountered and how they were resolved (or not)
+- Check current test/build status if relevant
+
+### Step 2: Create the sessions folder if it doesn't exist
+
+Create the canonical sessions folder in the user's Claude home directory:
+
+```bash
+mkdir -p ~/.claude/sessions
+```
+
+### Step 3: Write the session file
+
+Create `~/.claude/sessions/YYYY-MM-DD-<short-id>-session.tmp`, using today's actual date and a short-id that satisfies the rules enforced by `SESSION_FILENAME_REGEX` in `session-manager.js`:
+
+- Allowed characters: lowercase `a-z`, digits `0-9`, hyphens `-`
+- Minimum length: 8 characters
+- No uppercase letters, no underscores, no spaces
+
+Valid examples: `abc123de`, `a1b2c3d4`, `frontend-worktree-1`
+Invalid examples: `ABC123de` (uppercase), `short` (under 8 chars), `test_id1` (underscore)
+
+Full valid filename example: `2024-01-15-abc123de-session.tmp`
+
+The legacy filename `YYYY-MM-DD-session.tmp` is still valid, but new session files should prefer the short-id form to avoid same-day collisions.
+
+### Step 4: Populate the file with all sections below
+
+Write every section honestly. Do not skip sections — write "Nothing yet" or "N/A" if a section genuinely has no content. An incomplete file is worse than an honest empty section.
+
+### Step 5: Show the file to the user
+
+After writing, display the full contents and ask:
+
+```
+Session saved to [actual resolved path to the session file]
+
+Does this look accurate? Anything to correct or add before we close?
+```
+
+Wait for confirmation. Make edits if requested.
+
+---
+
+## Session File Format
+
+```markdown
+# Session: YYYY-MM-DD
+
+**Started:** [approximate time if known]
+**Last Updated:** [current time]
+**Project:** [project name or path]
+**Topic:** [one-line summary of what this session was about]
+
+---
+
+## What We Are Building
+
+[1-3 paragraphs describing the feature, bug fix, or task. Include enough
+context that someone with zero memory of this session can understand the goal.
+Include: what it does, why it's needed, how it fits into the larger system.]
+
+---
+
+## What WORKED (with evidence)
+
+[List only things that are confirmed working. For each item include WHY you
+know it works — test passed, ran in browser, Postman returned 200, etc.
+Without evidence, move it to "Not Tried Yet" instead.]
+
+- **[thing that works]** — confirmed by: [specific evidence]
+- **[thing that works]** — confirmed by: [specific evidence]
+
+If nothing is confirmed working yet: "Nothing confirmed working yet — all approaches still in progress or untested."
+
+---
+
+## What Did NOT Work (and why)
+
+[This is the most important section. List every approach tried that failed.
+For each failure write the EXACT reason so the next session doesn't retry it.
+Be specific: "threw X error because Y" is useful. "didn't work" is not.]
+
+- **[approach tried]** — failed because: [exact reason / error message]
+- **[approach tried]** — failed because: [exact reason / error message]
+
+If nothing failed: "No failed approaches yet."
+
+---
+
+## What Has NOT Been Tried Yet
+
+[Approaches that seem promising but haven't been attempted. Ideas from the
+conversation. Alternative solutions worth exploring. Be specific enough that
+the next session knows exactly what to try.]
+
+- [approach / idea]
+- [approach / idea]
+
+If nothing is queued: "No specific untried approaches identified."
+
+---
+
+## Current State of Files
+
+[Every file touched this session. Be precise about what state each file is in.]
+
+| File              | Status         | Notes                      |
+| ----------------- | -------------- | -------------------------- |
+| `path/to/file.ts` | ✅ Complete    | [what it does]             |
+| `path/to/file.ts` | 🔄 In Progress | [what's done, what's left] |
+| `path/to/file.ts` | ❌ Broken      | [what's wrong]             |
+| `path/to/file.ts` | 🗒️ Not Started | [planned but not touched]  |
+
+If no files were touched: "No files modified this session."
+
+---
+
+## Decisions Made
+
+[Architecture choices, tradeoffs accepted, approaches chosen and why.
+These prevent the next session from relitigating settled decisions.]
+
+- **[decision]** — reason: [why this was chosen over alternatives]
+
+If no significant decisions: "No major decisions made this session."
+
+---
+
+## Blockers & Open Questions
+
+[Anything unresolved that the next session needs to address or investigate.
+Questions that came up but weren't answered. External dependencies waiting on.]
+
+- [blocker / open question]
+
+If none: "No active blockers."
+
+---
+
+## Exact Next Step
+
+[If known: The single most important thing to do when resuming. Be precise
+enough that resuming requires zero thinking about where to start.]
+
+[If not known: "Next step not determined — review 'What Has NOT Been Tried Yet'
+and 'Blockers' sections to decide on direction before starting."]
+
+---
+
+## Environment & Setup Notes
+
+[Only fill this if relevant — commands needed to run the project, env vars
+required, services that need to be running, etc. Skip if standard setup.]
+
+[If none: omit this section entirely.]
+```
+
+---
+
+## Example Output
+
+```markdown
+# Session: 2024-01-15
+
+**Started:** ~2pm
+**Last Updated:** 5:30pm
+**Project:** my-app
+**Topic:** Building JWT authentication with httpOnly cookies
+
+---
+
+## What We Are Building
+
+User authentication system for the Next.js app. Users register with email/password,
+receive a JWT stored in an httpOnly cookie (not localStorage), and protected routes
+check for a valid token via middleware. The goal is session persistence across browser
+refreshes without exposing the token to JavaScript.
+
+---
+
+## What WORKED (with evidence)
+
+- **`/api/auth/register` endpoint** — confirmed by: Postman POST returns 200 with user
+  object, row visible in Supabase dashboard, bcrypt hash stored correctly
+- **JWT generation in `lib/auth.ts`** — confirmed by: unit test passes
+  (`npm test -- auth.test.ts`), decoded token at jwt.io shows correct payload
+- **Password hashing** — confirmed by: `bcrypt.compare()` returns true in test
+
+---
+
+## What Did NOT Work (and why)
+
+- **Next-Auth library** — failed because: conflicts with our custom Prisma adapter,
+  threw "Cannot use adapter with credentials provider in this configuration" on every
+  request. Not worth debugging — too opinionated for our setup.
+- **Storing JWT in localStorage** — failed because: SSR renders happen before
+  localStorage is available, caused React hydration mismatch error on every page load.
+  This approach is fundamentally incompatible with Next.js SSR.
+
+---
+
+## What Has NOT Been Tried Yet
+
+- Store JWT as httpOnly cookie in the login route response (most likely solution)
+- Use `cookies()` from `next/headers` to read token in server components
+- Write middleware.ts to protect routes by checking cookie existence
+
+---
+
+## Current State of Files
+
+| File                             | Status         | Notes                                           |
+| -------------------------------- | -------------- | ----------------------------------------------- |
+| `app/api/auth/register/route.ts` | ✅ Complete    | Works, tested                                   |
+| `app/api/auth/login/route.ts`    | 🔄 In Progress | Token generates but not setting cookie yet      |
+| `lib/auth.ts`                    | ✅ Complete    | JWT helpers, all tested                         |
+| `middleware.ts`                  | 🗒️ Not Started | Route protection, needs cookie read logic first |
+| `app/login/page.tsx`             | 🗒️ Not Started | UI not started                                  |
+
+---
+
+## Decisions Made
+
+- **httpOnly cookie over localStorage** — reason: prevents XSS token theft, works with SSR
+- **Custom auth over Next-Auth** — reason: Next-Auth conflicts with our Prisma setup, not worth the fight
+
+---
+
+## Blockers & Open Questions
+
+- Does `cookies().set()` work inside a Route Handler or only in Server Actions? Need to verify.
+
+---
+
+## Exact Next Step
+
+In `app/api/auth/login/route.ts`, after generating the JWT, set it as an httpOnly
+cookie using `cookies().set('token', jwt, { httpOnly: true, secure: true, sameSite: 'strict' })`.
+Then test with Postman — the response should include a `Set-Cookie` header.
+```
+
+---
+
+## Notes
+
+- Each session gets its own file — never append to a previous session's file
+- The "What Did NOT Work" section is the most critical — future sessions will blindly retry failed approaches without it
+- If the user asks to save mid-session (not just at the end), save what's known so far and mark in-progress items clearly
+- The file is meant to be read by Claude at the start of the next session via `/resume-session`
+- Use the canonical global session store: `~/.claude/sessions/`
+- Prefer the short-id filename form (`YYYY-MM-DD-<short-id>-session.tmp`) for any new session file

commands/sessions.md

@@ -12,6 +12,8 @@ Manage Claude Code session history - list, load, alias, and edit sessions stored
 
 Display all sessions with metadata, filtering, and pagination.
 
+Use `/sessions info` when you need operator-surface context for a swarm: branch, worktree path, and session recency.
+
 ```bash
 /sessions                              # List all sessions (default)
 /sessions list                         # Same as above
@@ -25,6 +27,7 @@ Display all sessions with metadata, filtering, and pagination.
 node -e "
 const sm = require((process.env.CLAUDE_PLUGIN_ROOT||require('path').join(require('os').homedir(),'.claude'))+'/scripts/lib/session-manager');
 const aa = require((process.env.CLAUDE_PLUGIN_ROOT||require('path').join(require('os').homedir(),'.claude'))+'/scripts/lib/session-aliases');
+const path = require('path');
 
 const result = sm.getAllSessions({ limit: 20 });
 const aliases = aa.listAliases();
@@ -33,17 +36,18 @@ for (const a of aliases) aliasMap[a.sessionPath] = a.name;
 
 console.log('Sessions (showing ' + result.sessions.length + ' of ' + result.total + '):');
 console.log('');
-console.log('ID        Date        Time     Size     Lines  Alias');
-console.log('────────────────────────────────────────────────────');
+console.log('ID        Date        Time     Branch       Worktree           Alias');
+console.log('────────────────────────────────────────────────────────────────────');
 
 for (const s of result.sessions) {
   const alias = aliasMap[s.filename] || '';
-  const size = sm.getSessionSize(s.sessionPath);
-  const stats = sm.getSessionStats(s.sessionPath);
+  const metadata = sm.parseSessionMetadata(sm.getSessionContent(s.sessionPath));
   const id = s.shortId === 'no-id' ? '(none)' : s.shortId.slice(0, 8);
   const time = s.modifiedTime.toTimeString().slice(0, 5);
+  const branch = (metadata.branch || '-').slice(0, 12);
+  const worktree = metadata.worktree ? path.basename(metadata.worktree).slice(0, 18) : '-';
 
-  console.log(id.padEnd(8) + ' ' + s.date + '  ' + time + '   ' + size.padEnd(7) + '  ' + String(stats.lineCount).padEnd(5) + '  ' + alias);
+  console.log(id.padEnd(8) + ' ' + s.date + '  ' + time + '   ' + branch.padEnd(12) + ' ' + worktree.padEnd(18) + ' ' + alias);
 }
 "
 ```
@@ -108,6 +112,18 @@ if (session.metadata.started) {
 if (session.metadata.lastUpdated) {
   console.log('Last Updated: ' + session.metadata.lastUpdated);
 }
+
+if (session.metadata.project) {
+  console.log('Project: ' + session.metadata.project);
+}
+
+if (session.metadata.branch) {
+  console.log('Branch: ' + session.metadata.branch);
+}
+
+if (session.metadata.worktree) {
+  console.log('Worktree: ' + session.metadata.worktree);
+}
 " "$ARGUMENTS"
 ```
 
@@ -215,6 +231,9 @@ console.log('ID:          ' + (session.shortId === 'no-id' ? '(none)' : session.
 console.log('Filename:    ' + session.filename);
 console.log('Date:        ' + session.date);
 console.log('Modified:    ' + session.modifiedTime.toISOString().slice(0, 19).replace('T', ' '));
+console.log('Project:     ' + (session.metadata.project || '-'));
+console.log('Branch:      ' + (session.metadata.branch || '-'));
+console.log('Worktree:    ' + (session.metadata.worktree || '-'));
 console.log('');
 console.log('Content:');
 console.log('  Lines:         ' + stats.lineCount);
@@ -236,6 +255,11 @@ Show all session aliases.
 /sessions aliases                      # List all aliases
 ```
 
+## Operator Notes
+
+- Session files persist `Project`, `Branch`, and `Worktree` in the header so `/sessions info` can disambiguate parallel tmux/worktree runs.
+- For command-center style monitoring, combine `/sessions info`, `git diff --stat`, and the cost metrics emitted by `scripts/hooks/cost-tracker.js`.
+
 **Script:**
 ```bash
 node -e "

commands/tdd.md

@@ -319,8 +319,10 @@ Never skip the RED phase. Never write code before tests.
 
 ## Related Agents
 
-This command invokes the `tdd-guide` agent located at:
-`~/.claude/agents/tdd-guide.md`
+This command invokes the `tdd-guide` agent provided by ECC.
 
-And can reference the `tdd-workflow` skill at:
-`~/.claude/skills/tdd-workflow/`
+The related `tdd-workflow` skill is also bundled with ECC.
+
+For manual installs, the source files live at:
+- `agents/tdd-guide.md`
+- `skills/tdd-workflow/SKILL.md`

docs/ARCHITECTURE-IMPROVEMENTS.md

@@ -0,0 +1,146 @@
+# Architecture Improvement Recommendations
+
+This document captures architect-level improvements for the Everything Claude Code (ECC) project. It is written from the perspective of a Claude Code coding architect aiming to improve maintainability, consistency, and long-term quality.
+
+---
+
+## 1. Documentation and Single Source of Truth
+
+### 1.1 Agent / Command / Skill Count Sync
+
+**Issue:** AGENTS.md states "13 specialized agents, 50+ skills, 33 commands" while the repo has **16 agents**, **65+ skills**, and **40 commands**. README and other docs also vary. This causes confusion for contributors and users.
+
+**Recommendation:**
+
+- **Single source of truth:** Derive counts (and optionally tables) from the filesystem or a small manifest. Options:
+  - **Option A:** Add a script (e.g. `scripts/ci/catalog.js`) that scans `agents/*.md`, `commands/*.md`, and `skills/*/SKILL.md` and outputs JSON/Markdown. CI and docs can consume this.
+  - **Option B:** Maintain one `docs/catalog.json` (or YAML) that lists agents, commands, and skills with metadata; scripts and docs read from it. Requires discipline to update on add/remove.
+- **Short-term:** Manually sync AGENTS.md, README.md, and CLAUDE.md with actual counts and list any new agents (e.g. chief-of-staff, loop-operator, harness-optimizer) in the agent table.
+
+**Impact:** High — affects first impression and contributor trust.
+
+---
+
+### 1.2 Command → Agent / Skill Map
+
+**Issue:** There is no single machine- or human-readable map of "which command uses which agent(s) or skill(s)." This lives in README tables and individual command `.md` files, which can drift.
+
+**Recommendation:**
+
+- Add a **command registry** (e.g. in `docs/` or as frontmatter in command files) that lists for each command: name, description, primary agent(s), skills referenced. Can be generated from command file content or maintained by hand.
+- Expose a "map" in docs (e.g. `docs/COMMAND-AGENT-MAP.md`) or in the generated catalog for discoverability and for tooling (e.g. "which commands use tdd-guide?").
+
+**Impact:** Medium — improves discoverability and refactoring safety.
+
+---
+
+## 2. Testing and Quality
+
+### 2.1 Test Discovery vs Hardcoded List
+
+**Issue:** `tests/run-all.js` uses a **hardcoded list** of test files. New test files are not run unless someone updates `run-all.js`, so coverage can be incomplete by omission.
+
+**Recommendation:**
+
+- **Glob-based discovery:** Discover test files by pattern (e.g. `**/*.test.js` under `tests/`) and run them, with an optional allowlist/denylist for special cases. This makes new tests automatically part of the suite.
+- Keep a single entry point (`tests/run-all.js`) that runs discovered tests and aggregates results.
+
+**Impact:** High — prevents regression where new tests exist but are never executed.
+
+---
+
+### 2.2 Test Coverage Metrics
+
+**Issue:** There is no coverage tool (e.g. nyc/c8/istanbul). The project cannot assert "80%+ coverage" for its own scripts; coverage is implicit.
+
+**Recommendation:**
+
+- Introduce a coverage tool for Node scripts (e.g. `c8` or `nyc`) and run it in CI. Start with a baseline (e.g. 60%) and raise over time; or at least report coverage in CI without failing so the team can see trends.
+- Focus on `scripts/` (lib + hooks + ci) as the primary target; exclude one-off scripts if needed.
+
+**Impact:** Medium — aligns the project with its own AGENTS.md guidance (80%+ coverage) and surfaces untested paths.
+
+---
+
+## 3. Schema and Validation
+
+### 3.1 Use Hooks JSON Schema in CI
+
+**Issue:** `schemas/hooks.schema.json` exists and defines the hook configuration shape, but `scripts/ci/validate-hooks.js` does **not** use it. Validation is duplicated (VALID_EVENTS, structure) and can drift from the schema.
+
+**Recommendation:**
+
+- Use a JSON Schema validator (e.g. `ajv`) in `validate-hooks.js` to validate `hooks/hooks.json` against `schemas/hooks.schema.json`. Keep the validator as the single source of truth for structure; retain only hook-specific checks (e.g. inline JS syntax) in the script.
+- Ensures schema and validator stay in sync and allows IDE/editor validation via `$schema` in hooks.json.
+
+**Impact:** Medium — reduces drift and improves contributor experience when editing hooks.
+
+---
+
+## 4. Cross-Harness and i18n
+
+### 4.1 Skill/Agent Subset Sync (.agents/skills, .cursor/skills)
+
+**Issue:** `.agents/skills/` (Codex) and `.cursor/skills/` are subsets of `skills/`. Adding or removing a skill in the main repo requires manually updating these subsets, which can be forgotten.
+
+**Recommendation:**
+
+- Document in CONTRIBUTING.md that adding a skill may require updating `.agents/skills` and `.cursor/skills` (and how to do it).
+- Optionally: a CI check or script that compares `skills/` to the subsets and fails or warns if a skill is in one set but not the other when it should be (e.g. by convention or by a small manifest).
+
+**Impact:** Low–Medium — reduces cross-harness drift.
+
+---
+
+### 4.2 Translation Drift (docs/ zh-CN, zh-TW, ja-JP)
+
+**Issue:** Translations in `docs/` duplicate agents, commands, skills. As the English source evolves, translations can become outdated without clear process or tooling.
+
+**Recommendation:**
+
+- Document a **translation process:** when to update (e.g. on release), who owns each locale, and how to detect stale content (e.g. diff file lists or key sections).
+- Consider: translation status file (e.g. `docs/i18n-status.md`) or CI that checks translation file existence/timestamps and warns if English was updated more recently than a translation.
+- Long-term: consider extraction/placeholder format (e.g. i18n keys) so translations reference the same structure as the English source.
+
+**Impact:** Medium — improves experience for non-English users and reduces confusion from outdated translations.
+
+---
+
+## 5. Hooks and Scripts
+
+### 5.1 Hook Runtime Consistency
+
+**Issue:** Most hooks invoke Node scripts via `run-with-flags.js`; one path uses `run-with-flags-shell.sh` + `observe.sh`. The mixed runtime is documented but could be simplified over time.
+
+**Recommendation:**
+
+- Prefer Node for new hooks when possible (cross-platform, single runtime). If shell is required, document why and keep the surface small.
+- Ensure `ECC_HOOK_PROFILE` and `ECC_DISABLED_HOOKS` are respected in all code paths (including shell) so behavior is consistent.
+
+**Impact:** Low — maintains current design; improves if more hooks migrate to Node.
+
+---
+
+## 6. Summary Table
+
+| Area              | Improvement                          | Priority | Effort  |
+|-------------------|--------------------------------------|----------|---------|
+| Doc sync          | Sync AGENTS.md/README counts & table | High     | Low     |
+| Single source     | Catalog script or manifest           | High     | Medium  |
+| Test discovery    | Glob-based test runner               | High     | Low     |
+| Coverage          | Add c8/nyc and CI coverage           | Medium   | Medium  |
+| Hook schema in CI | Validate hooks.json via schema       | Medium   | Low     |
+| Command map       | Command → agent/skill registry       | Medium   | Medium  |
+| Subset sync       | Document/CI for .agents/.cursor       | Low–Med  | Low–Med |
+| Translations      | Process + stale detection             | Medium   | Medium  |
+| Hook runtime      | Prefer Node; document shell use       | Low      | Low     |
+
+---
+
+## 7. Quick Wins (Immediate)
+
+1. **Update AGENTS.md:** Set agent count to 16; add chief-of-staff, loop-operator, harness-optimizer to the agent table; align skill/command counts with repo.
+2. **Test discovery:** Change `run-all.js` to discover `**/*.test.js` under `tests/` (with optional allowlist) so new tests are always run.
+3. **Wire hooks schema:** In `validate-hooks.js`, validate `hooks/hooks.json` against `schemas/hooks.schema.json` using ajv (or similar) and keep only hook-specific checks in the script.
+
+These three can be done in one or two sessions and materially improve consistency and reliability.

docs/COMMAND-AGENT-MAP.md

@@ -0,0 +1,61 @@
+# Command → Agent / Skill Map
+
+This document lists each slash command and the primary agent(s) or skills it invokes. Use it to discover which commands use which agents and to keep refactoring consistent.
+
+| Command | Primary agent(s) | Notes |
+|---------|------------------|--------|
+| `/plan` | planner | Implementation planning before code |
+| `/tdd` | tdd-guide | Test-driven development |
+| `/code-review` | code-reviewer | Quality and security review |
+| `/build-fix` | build-error-resolver | Fix build/type errors |
+| `/e2e` | e2e-runner | Playwright E2E tests |
+| `/refactor-clean` | refactor-cleaner | Dead code removal |
+| `/update-docs` | doc-updater | Documentation sync |
+| `/update-codemaps` | doc-updater | Codemaps / architecture docs |
+| `/go-review` | go-reviewer | Go code review |
+| `/go-test` | tdd-guide | Go TDD workflow |
+| `/go-build` | go-build-resolver | Fix Go build errors |
+| `/python-review` | python-reviewer | Python code review |
+| `/harness-audit` | — | Harness scorecard (no single agent) |
+| `/loop-start` | loop-operator | Start autonomous loop |
+| `/loop-status` | loop-operator | Inspect loop status |
+| `/quality-gate` | — | Quality pipeline (hook-like) |
+| `/model-route` | — | Model recommendation (no agent) |
+| `/orchestrate` | planner, tdd-guide, code-reviewer, security-reviewer, architect | Multi-agent handoff |
+| `/multi-plan` | architect (Codex/Gemini prompts) | Multi-model planning |
+| `/multi-execute` | architect / frontend prompts | Multi-model execution |
+| `/multi-backend` | architect | Backend multi-service |
+| `/multi-frontend` | architect | Frontend multi-service |
+| `/multi-workflow` | architect | General multi-service |
+| `/learn` | — | continuous-learning skill, instincts |
+| `/learn-eval` | — | continuous-learning-v2, evaluate then save |
+| `/instinct-status` | — | continuous-learning-v2 |
+| `/instinct-import` | — | continuous-learning-v2 |
+| `/instinct-export` | — | continuous-learning-v2 |
+| `/evolve` | — | continuous-learning-v2, cluster instincts |
+| `/promote` | — | continuous-learning-v2 |
+| `/projects` | — | continuous-learning-v2 |
+| `/skill-create` | — | skill-create-output script, git history |
+| `/checkpoint` | — | verification-loop skill |
+| `/verify` | — | verification-loop skill |
+| `/eval` | — | eval-harness skill |
+| `/test-coverage` | — | Coverage analysis |
+| `/sessions` | — | Session history |
+| `/setup-pm` | — | Package manager setup script |
+| `/claw` | — | NanoClaw CLI (scripts/claw.js) |
+| `/pm2` | — | PM2 service lifecycle |
+| `/security-scan` | security-reviewer (skill) | AgentShield via security-scan skill |
+
+## Skills referenced by commands
+
+- **continuous-learning**, **continuous-learning-v2**: `/learn`, `/learn-eval`, `/instinct-*`, `/evolve`, `/promote`, `/projects`
+- **verification-loop**: `/checkpoint`, `/verify`
+- **eval-harness**: `/eval`
+- **security-scan**: `/security-scan` (runs AgentShield)
+- **strategic-compact**: suggested at compaction points (hooks)
+
+## How to use this map
+
+- **Discoverability:** Find which command triggers which agent (e.g. “use `/code-review` for code-reviewer”).
+- **Refactoring:** When renaming or removing an agent, search this doc and the command files for references.
+- **CI/docs:** The catalog script (`node scripts/ci/catalog.js`) outputs agent/command/skill counts; this map complements it with command–agent relationships.

docs/ja-JP/README.md

@@ -1,4 +1,4 @@
-**言語:** English | [简体中文](../../README.zh-CN.md) | [繁體中文](docs/zh-TW/README.md) | [日本語](docs/ja-JP/README.md)
+**言語:** English | [简体中文](../../README.zh-CN.md) | [繁體中文](../zh-TW/README.md) | [日本語](README.md) | [한국어](../ko-KR/README.md)
 
 # Everything Claude Code
 

docs/ja-JP/skills/django-security/SKILL.md

@@ -581,7 +581,7 @@ LOGGING = {
 | 強力なシークレット | SECRET_KEYに環境変数を使用 |
 | パスワード検証 | すべてのパスワードバリデータを有効化 |
 | CSRF保護 | デフォルトで有効、無効にしない |
-| XSS防止 | Djangoは自動エスケープ、ユーザー入力で`|safe`を使用しない |
+| XSS防止 | Djangoは自動エスケープ、ユーザー入力で<code>\|safe</code>を使用しない |
 | SQLインジェクション | ORMを使用、クエリで文字列を連結しない |
 | ファイルアップロード | ファイルタイプとサイズを検証 |
 | レート制限 | APIエンドポイントをスロットル |

docs/ko-KR/CONTRIBUTING.md

@@ -0,0 +1,453 @@
+# Everything Claude Code에 기여하기
+
+기여에 관심을 가져주셔서 감사합니다! 이 저장소는 Claude Code 사용자를 위한 커뮤니티 리소스입니다.
+
+## 목차
+
+- [우리가 찾는 것](#우리가-찾는-것)
+- [빠른 시작](#빠른-시작)
+- [스킬 기여하기](#스킬-기여하기)
+- [에이전트 기여하기](#에이전트-기여하기)
+- [훅 기여하기](#훅-기여하기)
+- [커맨드 기여하기](#커맨드-기여하기)
+- [Pull Request 프로세스](#pull-request-프로세스)
+
+---
+
+## 우리가 찾는 것
+
+### 에이전트
+특정 작업을 잘 처리하는 새로운 에이전트:
+- 언어별 리뷰어 (Python, Go, Rust)
+- 프레임워크 전문가 (Django, Rails, Laravel, Spring)
+- DevOps 전문가 (Kubernetes, Terraform, CI/CD)
+- 도메인 전문가 (ML 파이프라인, 데이터 엔지니어링, 모바일)
+
+### 스킬
+워크플로우 정의와 도메인 지식:
+- 언어 모범 사례
+- 프레임워크 패턴
+- 테스팅 전략
+- 아키텍처 가이드
+
+### 훅
+유용한 자동화:
+- 린팅/포매팅 훅
+- 보안 검사
+- 유효성 검증 훅
+- 알림 훅
+
+### 커맨드
+유용한 워크플로우를 호출하는 슬래시 커맨드:
+- 배포 커맨드
+- 테스팅 커맨드
+- 코드 생성 커맨드
+
+---
+
+## 빠른 시작
+
+```bash
+# 1. 포크 및 클론
+gh repo fork affaan-m/everything-claude-code --clone
+cd everything-claude-code
+
+# 2. 브랜치 생성
+git checkout -b feat/my-contribution
+
+# 3. 기여 항목 추가 (아래 섹션 참고)
+
+# 4. 로컬 테스트
+cp -r skills/my-skill ~/.claude/skills/  # 스킬의 경우
+# 그런 다음 Claude Code로 테스트
+
+# 5. PR 제출
+git add . && git commit -m "feat: add my-skill" && git push -u origin feat/my-contribution
+```
+
+---
+
+## 스킬 기여하기
+
+스킬은 Claude Code가 컨텍스트에 따라 로드하는 지식 모듈입니다.
+
+### 디렉토리 구조
+
+```
+skills/
+└── your-skill-name/
+    └── SKILL.md
+```
+
+### SKILL.md 템플릿
+
+```markdown
+---
+name: your-skill-name
+description: 스킬 목록에 표시되는 간단한 설명
+origin: ECC
+---
+
+# 스킬 제목
+
+이 스킬이 다루는 내용에 대한 간단한 개요.
+
+## 핵심 개념
+
+주요 패턴과 가이드라인 설명.
+
+## 코드 예제
+
+\`\`\`typescript
+// 실용적이고 테스트된 예제 포함
+function example() {
+  // 잘 주석 처리된 코드
+}
+\`\`\`
+
+## 모범 사례
+
+- 실행 가능한 가이드라인
+- 해야 할 것과 하지 말아야 할 것
+- 흔한 실수 방지
+
+## 사용 시점
+
+이 스킬이 적용되는 시나리오 설명.
+```
+
+### 스킬 체크리스트
+
+- [ ] 하나의 도메인/기술에 집중
+- [ ] 실용적인 코드 예제 포함
+- [ ] 500줄 미만
+- [ ] 명확한 섹션 헤더 사용
+- [ ] Claude Code에서 테스트 완료
+
+### 스킬 예시
+
+| 스킬 | 용도 |
+|------|------|
+| `coding-standards/` | TypeScript/JavaScript 패턴 |
+| `frontend-patterns/` | React와 Next.js 모범 사례 |
+| `backend-patterns/` | API와 데이터베이스 패턴 |
+| `security-review/` | 보안 체크리스트 |
+
+---
+
+## 에이전트 기여하기
+
+에이전트는 Task 도구를 통해 호출되는 전문 어시스턴트입니다.
+
+### 파일 위치
+
+```
+agents/your-agent-name.md
+```
+
+### 에이전트 템플릿
+
+```markdown
+---
+name: your-agent-name
+description: 이 에이전트가 하는 일과 Claude가 언제 호출해야 하는지. 구체적으로 작성!
+tools: ["Read", "Write", "Edit", "Bash", "Grep", "Glob"]
+model: sonnet
+---
+
+당신은 [역할] 전문가입니다.
+
+## 역할
+
+- 주요 책임
+- 부차적 책임
+- 하지 않는 것 (경계)
+
+## 워크플로우
+
+### 1단계: 이해
+작업에 접근하는 방법.
+
+### 2단계: 실행
+작업을 수행하는 방법.
+
+### 3단계: 검증
+결과를 검증하는 방법.
+
+## 출력 형식
+
+사용자에게 반환하는 것.
+
+## 예제
+
+### 예제: [시나리오]
+입력: [사용자가 제공하는 것]
+행동: [수행하는 것]
+출력: [반환하는 것]
+```
+
+### 에이전트 필드
+
+| 필드 | 설명 | 옵션 |
+|------|------|------|
+| `name` | 소문자, 하이픈 연결 | `code-reviewer` |
+| `description` | 호출 시점 결정에 사용 | 구체적으로 작성! |
+| `tools` | 필요한 것만 포함 | `Read, Write, Edit, Bash, Grep, Glob, WebFetch, Task` |
+| `model` | 복잡도 수준 | `haiku` (단순), `sonnet` (코딩), `opus` (복잡) |
+
+### 예시 에이전트
+
+| 에이전트 | 용도 |
+|----------|------|
+| `tdd-guide.md` | 테스트 주도 개발 |
+| `code-reviewer.md` | 코드 리뷰 |
+| `security-reviewer.md` | 보안 점검 |
+| `build-error-resolver.md` | 빌드 오류 수정 |
+
+---
+
+## 훅 기여하기
+
+훅은 Claude Code 이벤트에 의해 트리거되는 자동 동작입니다.
+
+### 파일 위치
+
+```
+hooks/hooks.json
+```
+
+### 훅 유형
+
+| 유형 | 트리거 시점 | 사용 사례 |
+|------|-----------|----------|
+| `PreToolUse` | 도구 실행 전 | 유효성 검증, 경고, 차단 |
+| `PostToolUse` | 도구 실행 후 | 포매팅, 검사, 알림 |
+| `SessionStart` | 세션 시작 시 | 컨텍스트 로딩 |
+| `Stop` | 세션 종료 시 | 정리, 감사 |
+
+### 훅 형식
+
+```json
+{
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "tool == \"Bash\" && tool_input.command matches \"rm -rf /\"",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "echo '[Hook] BLOCKED: Dangerous command' && exit 1"
+          }
+        ],
+        "description": "위험한 rm 명령 차단"
+      }
+    ]
+  }
+}
+```
+
+### Matcher 문법
+
+```javascript
+// 특정 도구 매칭
+tool == "Bash"
+tool == "Edit"
+tool == "Write"
+
+// 입력 패턴 매칭
+tool_input.command matches "npm install"
+tool_input.file_path matches "\\.tsx?$"
+
+// 조건 결합
+tool == "Bash" && tool_input.command matches "git push"
+```
+
+### 훅 예시
+
+```json
+// tmux 밖 dev 서버 차단
+{
+  "matcher": "tool == \"Bash\" && tool_input.command matches \"npm run dev\"",
+  "hooks": [{"type": "command", "command": "echo '개발 서버는 tmux에서 실행하세요' && exit 1"}],
+  "description": "dev 서버를 tmux에서 실행하도록 강제"
+}
+
+// TypeScript 편집 후 자동 포맷
+{
+  "matcher": "tool == \"Edit\" && tool_input.file_path matches \"\\.tsx?$\"",
+  "hooks": [{"type": "command", "command": "npx prettier --write \"$file_path\""}],
+  "description": "TypeScript 파일 편집 후 포맷"
+}
+
+// git push 전 경고
+{
+  "matcher": "tool == \"Bash\" && tool_input.command matches \"git push\"",
+  "hooks": [{"type": "command", "command": "echo '[Hook] push 전에 변경사항을 다시 검토하세요'"}],
+  "description": "push 전 검토 리마인더"
+}
+```
+
+### 훅 체크리스트
+
+- [ ] Matcher가 구체적 (너무 광범위하지 않게)
+- [ ] 명확한 오류/정보 메시지 포함
+- [ ] 올바른 종료 코드 사용 (`exit 1`은 차단, `exit 0`은 허용)
+- [ ] 충분한 테스트 완료
+- [ ] 설명 포함
+
+---
+
+## 커맨드 기여하기
+
+커맨드는 `/command-name`으로 사용자가 호출하는 액션입니다.
+
+### 파일 위치
+
+```
+commands/your-command.md
+```
+
+### 커맨드 템플릿
+
+```markdown
+---
+description: /help에 표시되는 간단한 설명
+---
+
+# 커맨드 이름
+
+## 목적
+
+이 커맨드가 수행하는 작업.
+
+## 사용법
+
+\`\`\`
+/your-command [args]
+\`\`\`
+
+## 워크플로우
+
+1. 첫 번째 단계
+2. 두 번째 단계
+3. 마지막 단계
+
+## 출력
+
+사용자가 받는 결과.
+```
+
+### 커맨드 예시
+
+| 커맨드 | 용도 |
+|--------|------|
+| `commit.md` | Git 커밋 생성 |
+| `code-review.md` | 코드 변경사항 리뷰 |
+| `tdd.md` | TDD 워크플로우 |
+| `e2e.md` | E2E 테스팅 |
+
+---
+
+## 크로스-하네스 및 번역
+
+### 스킬 서브셋 (Codex 및 Cursor)
+
+ECC는 다른 하네스를 위한 스킬 서브셋도 제공합니다:
+
+- **Codex:** `.agents/skills/` — `agents/openai.yaml`에 나열된 스킬이 Codex에서 로드됩니다.
+- **Cursor:** `.cursor/skills/` — Cursor용 스킬 서브셋이 별도로 포함됩니다.
+
+Codex 또는 Cursor에서도 제공해야 하는 **새 스킬**을 추가한다면:
+
+1. 먼저 `skills/your-skill-name/` 아래에 일반적인 ECC 스킬로 추가합니다.
+2. **Codex**에서도 제공해야 하면 `.agents/skills/`에 반영하고, 필요하면 `agents/openai.yaml`에도 참조를 추가합니다.
+3. **Cursor**에서도 제공해야 하면 Cursor 레이아웃에 맞게 `.cursor/skills/` 아래에 추가합니다.
+
+기존 디렉터리의 구조를 확인한 뒤 같은 패턴을 따르세요. 이 서브셋 동기화는 수동이므로 PR 설명에 반영 여부를 적어 두는 것이 좋습니다.
+
+### 번역
+
+번역 문서는 `docs/` 아래에 있습니다. 예: `docs/zh-CN`, `docs/zh-TW`, `docs/ja-JP`.
+
+번역된 에이전트, 커맨드, 스킬을 변경한다면:
+
+- 대응하는 번역 파일도 함께 업데이트하거나
+- 유지보수자/번역자가 후속 작업을 할 수 있도록 이슈를 열어 주세요.
+
+---
+
+## Pull Request 프로세스
+
+### 1. PR 제목 형식
+
+```
+feat(skills): add rust-patterns skill
+feat(agents): add api-designer agent
+feat(hooks): add auto-format hook
+fix(skills): update React patterns
+docs: improve contributing guide
+```
+
+### 2. PR 설명
+
+```markdown
+## 요약
+무엇을 추가했고 왜 필요한지.
+
+## 유형
+- [ ] 스킬
+- [ ] 에이전트
+- [ ] 훅
+- [ ] 커맨드
+
+## 테스트
+어떻게 테스트했는지.
+
+## 체크리스트
+- [ ] 형식 가이드라인 준수
+- [ ] Claude Code에서 테스트 완료
+- [ ] 민감한 정보 없음 (API 키, 경로)
+- [ ] 명확한 설명 포함
+```
+
+### 3. 리뷰 프로세스
+
+1. 메인테이너가 48시간 이내에 리뷰
+2. 피드백이 있으면 수정 반영
+3. 승인되면 main에 머지
+
+---
+
+## 가이드라인
+
+### 해야 할 것
+- 기여를 집중적이고 모듈화되게 유지
+- 명확한 설명 포함
+- 제출 전 테스트
+- 기존 패턴 따르기
+- 의존성 문서화
+
+### 하지 말아야 할 것
+- 민감한 데이터 포함 (API 키, 토큰, 경로)
+- 지나치게 복잡하거나 특수한 설정 추가
+- 테스트하지 않은 기여 제출
+- 기존 기능과 중복되는 것 생성
+
+---
+
+## 파일 이름 규칙
+
+- 소문자에 하이픈 사용: `python-reviewer.md`
+- 설명적으로 작성: `workflow.md`가 아닌 `tdd-workflow.md`
+- name과 파일명을 일치시키기
+
+---
+
+## 질문이 있으신가요?
+
+- **이슈:** [github.com/affaan-m/everything-claude-code/issues](https://github.com/affaan-m/everything-claude-code/issues)
+- **X/Twitter:** [@affaanmustafa](https://x.com/affaanmustafa)
+
+---
+
+기여해 주셔서 감사합니다! 함께 훌륭한 리소스를 만들어 갑시다.

docs/ko-KR/README.md

@@ -0,0 +1,731 @@
+**언어:** [English](../../README.md) | [简体中文](../../README.zh-CN.md) | [繁體中文](../zh-TW/README.md) | [日本語](../ja-JP/README.md) | 한국어
+
+# Everything Claude Code
+
+[![Stars](https://img.shields.io/github/stars/affaan-m/everything-claude-code?style=flat)](https://github.com/affaan-m/everything-claude-code/stargazers)
+[![Forks](https://img.shields.io/github/forks/affaan-m/everything-claude-code?style=flat)](https://github.com/affaan-m/everything-claude-code/network/members)
+[![Contributors](https://img.shields.io/github/contributors/affaan-m/everything-claude-code?style=flat)](https://github.com/affaan-m/everything-claude-code/graphs/contributors)
+[![npm ecc-universal](https://img.shields.io/npm/dw/ecc-universal?label=ecc-universal%20weekly%20downloads&logo=npm)](https://www.npmjs.com/package/ecc-universal)
+[![npm ecc-agentshield](https://img.shields.io/npm/dw/ecc-agentshield?label=ecc-agentshield%20weekly%20downloads&logo=npm)](https://www.npmjs.com/package/ecc-agentshield)
+[![GitHub App Install](https://img.shields.io/badge/GitHub%20App-150%20installs-2ea44f?logo=github)](https://github.com/marketplace/ecc-tools)
+[![License](https://img.shields.io/badge/license-MIT-blue.svg)](../../LICENSE)
+![Shell](https://img.shields.io/badge/-Shell-4EAA25?logo=gnu-bash&logoColor=white)
+![TypeScript](https://img.shields.io/badge/-TypeScript-3178C6?logo=typescript&logoColor=white)
+![Python](https://img.shields.io/badge/-Python-3776AB?logo=python&logoColor=white)
+![Go](https://img.shields.io/badge/-Go-00ADD8?logo=go&logoColor=white)
+![Java](https://img.shields.io/badge/-Java-ED8B00?logo=openjdk&logoColor=white)
+![Markdown](https://img.shields.io/badge/-Markdown-000000?logo=markdown&logoColor=white)
+
+> **50K+ stars** | **6K+ forks** | **30 contributors** | **6개 언어 지원** | **Anthropic 해커톤 우승**
+
+---
+
+<div align="center">
+
+**🌐 Language / 语言 / 語言 / 언어**
+
+[**English**](../../README.md) | [简体中文](../../README.zh-CN.md) | [繁體中文](../zh-TW/README.md) | [日本語](../ja-JP/README.md) | [한국어](README.md)
+
+</div>
+
+---
+
+**AI 에이전트 하네스를 위한 성능 최적화 시스템. Anthropic 해커톤 우승자가 만들었습니다.**
+
+단순한 설정 파일 모음이 아닙니다. 스킬, 직관(Instinct), 메모리 최적화, 지속적 학습, 보안 스캐닝, 리서치 우선 개발을 아우르는 완전한 시스템입니다. 10개월 이상 실제 프로덕트를 만들며 매일 집중적으로 사용해 발전시킨 프로덕션 레벨의 에이전트, 훅, 커맨드, 룰, MCP 설정이 포함되어 있습니다.
+
+**Claude Code**, **Codex**, **Cowork** 등 다양한 AI 에이전트 하네스에서 사용할 수 있습니다.
+
+---
+
+## 가이드
+
+이 저장소는 코드만 포함하고 있습니다. 가이드에서 모든 것을 설명합니다.
+
+<table>
+<tr>
+<td width="50%">
+<a href="https://x.com/affaanmustafa/status/2012378465664745795">
+<img src="https://github.com/user-attachments/assets/1a471488-59cc-425b-8345-5245c7efbcef" alt="The Shorthand Guide to Everything Claude Code" />
+</a>
+</td>
+<td width="50%">
+<a href="https://x.com/affaanmustafa/status/2014040193557471352">
+<img src="https://github.com/user-attachments/assets/c9ca43bc-b149-427f-b551-af6840c368f0" alt="The Longform Guide to Everything Claude Code" />
+</a>
+</td>
+</tr>
+<tr>
+<td align="center"><b>요약 가이드</b><br/>설정, 기초, 철학. <b>이것부터 읽으세요.</b></td>
+<td align="center"><b>상세 가이드</b><br/>토큰 최적화, 메모리 영속성, 평가, 병렬 처리.</td>
+</tr>
+</table>
+
+| 주제 | 배울 수 있는 것 |
+|------|----------------|
+| 토큰 최적화 | 모델 선택, 시스템 프롬프트 최적화, 백그라운드 프로세스 |
+| 메모리 영속성 | 세션 간 컨텍스트를 자동으로 저장/불러오는 훅 |
+| 지속적 학습 | 세션에서 패턴을 자동 추출하여 재사용 가능한 스킬로 변환 |
+| 검증 루프 | 체크포인트 vs 연속 평가, 채점 유형, pass@k 메트릭 |
+| 병렬 처리 | Git worktree, 캐스케이드 방식, 인스턴스 확장 시점 |
+| 서브에이전트 오케스트레이션 | 컨텍스트 문제, 반복 검색 패턴 |
+
+---
+
+## 새로운 소식
+
+### v1.8.0 — 하네스 성능 시스템 (2026년 3월)
+
+- **하네스 중심 릴리스** — ECC는 이제 단순 설정 모음이 아닌, 에이전트 하네스 성능 시스템으로 명시됩니다.
+- **훅 안정성 개선** — SessionStart 루트 폴백, Stop 단계 세션 요약, 취약한 인라인 원라이너를 스크립트 기반 훅으로 교체.
+- **훅 런타임 제어** — `ECC_HOOK_PROFILE=minimal|standard|strict`와 `ECC_DISABLED_HOOKS=...`로 훅 파일 수정 없이 런타임 제어.
+- **새 하네스 커맨드** — `/harness-audit`, `/loop-start`, `/loop-status`, `/quality-gate`, `/model-route`.
+- **NanoClaw v2** — 모델 라우팅, 스킬 핫로드, 세션 분기/검색/내보내기/압축/메트릭.
+- **크로스 하네스 호환성** — Claude Code, Cursor, OpenCode, Codex 간 동작 일관성 강화.
+- **997개 내부 테스트 통과** — 훅/런타임 리팩토링 및 호환성 업데이트 후 전체 테스트 통과.
+
+### v1.7.0 — 크로스 플랫폼 확장 & 프레젠테이션 빌더 (2026년 2월)
+
+- **Codex 앱 + CLI 지원** — AGENTS.md 기반의 직접적인 Codex 지원
+- **`frontend-slides` 스킬** — 의존성 없는 HTML 프레젠테이션 빌더
+- **5개 신규 비즈니스/콘텐츠 스킬** — `article-writing`, `content-engine`, `market-research`, `investor-materials`, `investor-outreach`
+- **992개 내부 테스트** — 확장된 검증 및 회귀 테스트 범위
+
+### v1.6.0 — Codex CLI, AgentShield & 마켓플레이스 (2026년 2월)
+
+- **Codex CLI 지원** — OpenAI Codex CLI 호환성을 위한 `/codex-setup` 커맨드
+- **7개 신규 스킬** — `search-first`, `swift-actor-persistence`, `swift-protocol-di-testing` 등
+- **AgentShield 통합** — `/security-scan`으로 Claude Code에서 직접 AgentShield 실행; 1282개 테스트, 102개 규칙
+- **GitHub 마켓플레이스** — [github.com/marketplace/ecc-tools](https://github.com/marketplace/ecc-tools)에서 무료/프로/엔터프라이즈 티어 제공
+- **30명 이상의 커뮤니티 기여** — 6개 언어에 걸친 30명의 기여자
+- **978개 내부 테스트** — 에이전트, 스킬, 커맨드, 훅, 룰 전반에 걸친 검증
+
+전체 변경 내역은 [Releases](https://github.com/affaan-m/everything-claude-code/releases)에서 확인하세요.
+
+---
+
+## 🚀 빠른 시작
+
+2분 안에 설정 완료:
+
+### 1단계: 플러그인 설치
+
+```bash
+# 마켓플레이스 추가
+/plugin marketplace add affaan-m/everything-claude-code
+
+# 플러그인 설치
+/plugin install everything-claude-code@everything-claude-code
+```
+
+### 2단계: 룰 설치 (필수)
+
+> ⚠️ **중요:** Claude Code 플러그인은 `rules`를 자동으로 배포할 수 없습니다. 수동으로 설치해야 합니다:
+
+```bash
+# 먼저 저장소 클론
+git clone https://github.com/affaan-m/everything-claude-code.git
+cd everything-claude-code
+
+# 권장: 설치 스크립트 사용 (common + 언어별 룰을 안전하게 처리)
+./install.sh typescript    # 또는 python, golang
+# 여러 언어를 한번에 설치할 수 있습니다:
+# ./install.sh typescript python golang
+# Cursor를 대상으로 설치:
+# ./install.sh --target cursor typescript
+```
+
+수동 설치 방법은 `rules/` 폴더의 README를 참고하세요.
+
+### 3단계: 사용 시작
+
+```bash
+# 커맨드 실행 (플러그인 설치 시 네임스페이스 형태 사용)
+/everything-claude-code:plan "사용자 인증 추가"
+
+# 수동 설치(옵션 2) 시에는 짧은 형태를 사용:
+# /plan "사용자 인증 추가"
+
+# 사용 가능한 커맨드 확인
+/plugin list everything-claude-code@everything-claude-code
+```
+
+✨ **끝!** 이제 16개 에이전트, 65개 스킬, 40개 커맨드를 사용할 수 있습니다.
+
+---
+
+## 🌐 크로스 플랫폼 지원
+
+이 플러그인은 **Windows, macOS, Linux**를 완벽하게 지원하며, 주요 IDE(Cursor, OpenCode, Antigravity) 및 CLI 하네스와 긴밀하게 통합됩니다. 모든 훅과 스크립트는 최대 호환성을 위해 Node.js로 작성되었습니다.
+
+### 패키지 매니저 감지
+
+플러그인이 선호하는 패키지 매니저(npm, pnpm, yarn, bun)를 자동으로 감지합니다:
+
+1. **환경 변수**: `CLAUDE_PACKAGE_MANAGER`
+2. **프로젝트 설정**: `.claude/package-manager.json`
+3. **package.json**: `packageManager` 필드
+4. **락 파일**: package-lock.json, yarn.lock, pnpm-lock.yaml, bun.lockb에서 감지
+5. **글로벌 설정**: `~/.claude/package-manager.json`
+6. **폴백**: `npm`
+
+패키지 매니저 설정 방법:
+
+```bash
+# 환경 변수로 설정
+export CLAUDE_PACKAGE_MANAGER=pnpm
+
+# 글로벌 설정
+node scripts/setup-package-manager.js --global pnpm
+
+# 프로젝트 설정
+node scripts/setup-package-manager.js --project bun
+
+# 현재 설정 확인
+node scripts/setup-package-manager.js --detect
+```
+
+또는 Claude Code에서 `/setup-pm` 커맨드를 사용하세요.
+
+### 훅 런타임 제어
+
+런타임 플래그로 엄격도를 조절하거나 특정 훅을 임시로 비활성화할 수 있습니다:
+
+```bash
+# 훅 엄격도 프로필 (기본값: standard)
+export ECC_HOOK_PROFILE=standard
+
+# 비활성화할 훅 ID (쉼표로 구분)
+export ECC_DISABLED_HOOKS="pre:bash:tmux-reminder,post:edit:typecheck"
+```
+
+---
+
+## 📦 구성 요소
+
+이 저장소는 **Claude Code 플러그인**입니다 - 직접 설치하거나 컴포넌트를 수동으로 복사할 수 있습니다.
+
+```
+everything-claude-code/
+|-- .claude-plugin/   # 플러그인 및 마켓플레이스 매니페스트
+|   |-- plugin.json         # 플러그인 메타데이터와 컴포넌트 경로
+|   |-- marketplace.json    # /plugin marketplace add용 마켓플레이스 카탈로그
+|
+|-- agents/           # 위임을 위한 전문 서브에이전트
+|   |-- planner.md           # 기능 구현 계획
+|   |-- architect.md         # 시스템 설계 의사결정
+|   |-- tdd-guide.md         # 테스트 주도 개발
+|   |-- code-reviewer.md     # 품질 및 보안 리뷰
+|   |-- security-reviewer.md # 취약점 분석
+|   |-- build-error-resolver.md
+|   |-- e2e-runner.md        # Playwright E2E 테스팅
+|   |-- refactor-cleaner.md  # 사용하지 않는 코드 정리
+|   |-- doc-updater.md       # 문서 동기화
+|   |-- go-reviewer.md       # Go 코드 리뷰
+|   |-- go-build-resolver.md # Go 빌드 에러 해결
+|   |-- python-reviewer.md   # Python 코드 리뷰
+|   |-- database-reviewer.md # 데이터베이스/Supabase 리뷰
+|
+|-- skills/           # 워크플로우 정의와 도메인 지식
+|   |-- coding-standards/           # 언어 모범 사례
+|   |-- backend-patterns/           # API, 데이터베이스, 캐싱 패턴
+|   |-- frontend-patterns/          # React, Next.js 패턴
+|   |-- continuous-learning/        # 세션에서 패턴 자동 추출
+|   |-- continuous-learning-v2/     # 신뢰도 점수가 있는 직관 기반 학습
+|   |-- tdd-workflow/               # TDD 방법론
+|   |-- security-review/            # 보안 체크리스트
+|   |-- 그 외 다수...
+|
+|-- commands/         # 빠른 실행을 위한 슬래시 커맨드
+|   |-- tdd.md              # /tdd - 테스트 주도 개발
+|   |-- plan.md             # /plan - 구현 계획
+|   |-- e2e.md              # /e2e - E2E 테스트 생성
+|   |-- code-review.md      # /code-review - 품질 리뷰
+|   |-- build-fix.md        # /build-fix - 빌드 에러 수정
+|   |-- 그 외 다수...
+|
+|-- rules/            # 항상 따르는 가이드라인 (~/.claude/rules/에 복사)
+|   |-- common/              # 언어 무관 원칙
+|   |-- typescript/          # TypeScript/JavaScript 전용
+|   |-- python/              # Python 전용
+|   |-- golang/              # Go 전용
+|
+|-- hooks/            # 트리거 기반 자동화
+|   |-- hooks.json                # 모든 훅 설정
+|   |-- memory-persistence/       # 세션 라이프사이클 훅
+|
+|-- scripts/          # 크로스 플랫폼 Node.js 스크립트
+|-- tests/            # 테스트 모음
+|-- contexts/         # 동적 시스템 프롬프트 주입 컨텍스트
+|-- examples/         # 예제 설정 및 세션
+|-- mcp-configs/      # MCP 서버 설정
+```
+
+---
+
+## 🛠️ 에코시스템 도구
+
+### Skill Creator
+
+저장소에서 Claude Code 스킬을 생성하는 두 가지 방법:
+
+#### 옵션 A: 로컬 분석 (내장)
+
+외부 서비스 없이 로컬에서 분석하려면 `/skill-create` 커맨드를 사용하세요:
+
+```bash
+/skill-create                    # 현재 저장소 분석
+/skill-create --instincts        # 직관(instincts)도 함께 생성
+```
+
+git 히스토리를 로컬에서 분석하여 SKILL.md 파일을 생성합니다.
+
+#### 옵션 B: GitHub 앱 (고급)
+
+고급 기능(10k+ 커밋, 자동 PR, 팀 공유)이 필요한 경우:
+
+[GitHub 앱 설치](https://github.com/apps/skill-creator) | [ecc.tools](https://ecc.tools)
+
+### AgentShield — 보안 감사 도구
+
+> Claude Code 해커톤(Cerebral Valley x Anthropic, 2026년 2월)에서 개발. 1282개 테스트, 98% 커버리지, 102개 정적 분석 규칙.
+
+Claude Code 설정에서 취약점, 잘못된 구성, 인젝션 위험을 스캔합니다.
+
+```bash
+# 빠른 스캔 (설치 불필요)
+npx ecc-agentshield scan
+
+# 안전한 문제 자동 수정
+npx ecc-agentshield scan --fix
+
+# 3개의 Opus 4.6 에이전트로 정밀 분석
+npx ecc-agentshield scan --opus --stream
+
+# 안전한 설정을 처음부터 생성
+npx ecc-agentshield init
+```
+
+**스캔 대상:** CLAUDE.md, settings.json, MCP 설정, 훅, 에이전트 정의, 스킬 — 시크릿 감지(14개 패턴), 권한 감사, 훅 인젝션 분석, MCP 서버 위험 프로파일링, 에이전트 설정 검토의 5가지 카테고리.
+
+**`--opus` 플래그**는 레드팀/블루팀/감사관 파이프라인으로 3개의 Claude Opus 4.6 에이전트를 실행합니다. 공격자가 익스플로잇 체인을 찾고, 방어자가 보호 조치를 평가하며, 감사관이 양쪽의 결과를 종합하여 우선순위가 매겨진 위험 평가를 작성합니다.
+
+Claude Code에서 `/security-scan`을 사용하거나, [GitHub Action](https://github.com/affaan-m/agentshield)으로 CI에 추가하세요.
+
+[GitHub](https://github.com/affaan-m/agentshield) | [npm](https://www.npmjs.com/package/ecc-agentshield)
+
+### 🧠 지속적 학습 v2
+
+직관(Instinct) 기반 학습 시스템이 여러분의 패턴을 자동으로 학습합니다:
+
+```bash
+/instinct-status        # 학습된 직관과 신뢰도 확인
+/instinct-import <file> # 다른 사람의 직관 가져오기
+/instinct-export        # 내 직관 내보내기
+/evolve                 # 관련 직관을 스킬로 클러스터링
+```
+
+자세한 내용은 `skills/continuous-learning-v2/`를 참고하세요.
+
+---
+
+## 📋 요구 사항
+
+### Claude Code CLI 버전
+
+**최소 버전: v2.1.0 이상**
+
+이 플러그인은 훅 시스템 변경으로 인해 Claude Code CLI v2.1.0 이상이 필요합니다.
+
+버전 확인:
+```bash
+claude --version
+```
+
+### 중요: 훅 자동 로딩 동작
+
+> ⚠️ **기여자 참고:** `.claude-plugin/plugin.json`에 `"hooks"` 필드를 추가하지 **마세요**. 회귀 테스트로 이를 강제합니다.
+
+Claude Code v2.1+는 설치된 플러그인의 `hooks/hooks.json`을 **자동으로 로드**합니다. 명시적으로 선언하면 중복 감지 오류가 발생합니다.
+
+---
+
+## 📥 설치
+
+### 옵션 1: 플러그인으로 설치 (권장)
+
+```bash
+# 마켓플레이스 추가
+/plugin marketplace add affaan-m/everything-claude-code
+
+# 플러그인 설치
+/plugin install everything-claude-code@everything-claude-code
+```
+
+또는 `~/.claude/settings.json`에 직접 추가:
+
+```json
+{
+  "extraKnownMarketplaces": {
+    "everything-claude-code": {
+      "source": {
+        "source": "github",
+        "repo": "affaan-m/everything-claude-code"
+      }
+    }
+  },
+  "enabledPlugins": {
+    "everything-claude-code@everything-claude-code": true
+  }
+}
+```
+
+> **참고:** Claude Code 플러그인 시스템은 `rules`를 플러그인으로 배포하는 것을 지원하지 않습니다. 룰은 수동으로 설치해야 합니다:
+>
+> ```bash
+> git clone https://github.com/affaan-m/everything-claude-code.git
+>
+> # 옵션 A: 사용자 레벨 룰 (모든 프로젝트에 적용)
+> mkdir -p ~/.claude/rules
+> cp -r everything-claude-code/rules/common/* ~/.claude/rules/
+> cp -r everything-claude-code/rules/typescript/* ~/.claude/rules/   # 사용하는 스택 선택
+>
+> # 옵션 B: 프로젝트 레벨 룰 (현재 프로젝트에만 적용)
+> mkdir -p .claude/rules
+> cp -r everything-claude-code/rules/common/* .claude/rules/
+> ```
+
+---
+
+### 🔧 옵션 2: 수동 설치
+
+설치할 항목을 직접 선택하고 싶다면:
+
+```bash
+# 저장소 클론
+git clone https://github.com/affaan-m/everything-claude-code.git
+
+# 에이전트 복사
+cp everything-claude-code/agents/*.md ~/.claude/agents/
+
+# 룰 복사 (common + 언어별)
+cp -r everything-claude-code/rules/common/* ~/.claude/rules/
+cp -r everything-claude-code/rules/typescript/* ~/.claude/rules/   # 사용하는 스택 선택
+
+# 커맨드 복사
+cp everything-claude-code/commands/*.md ~/.claude/commands/
+
+# 스킬 복사
+cp -r everything-claude-code/skills/* ~/.claude/skills/
+cp -r everything-claude-code/skills/search-first ~/.claude/skills/
+```
+
+---
+
+## 🎯 핵심 개념
+
+### 에이전트
+
+서브에이전트가 제한된 범위 내에서 위임된 작업을 처리합니다. 예시:
+
+```markdown
+---
+name: code-reviewer
+description: 코드의 품질, 보안, 유지보수성을 리뷰합니다
+tools: ["Read", "Grep", "Glob", "Bash"]
+model: opus
+---
+
+당신은 시니어 코드 리뷰어입니다...
+```
+
+### 스킬
+
+스킬은 커맨드나 에이전트에 의해 호출되는 워크플로우 정의입니다:
+
+```markdown
+# TDD 워크플로우
+
+1. 인터페이스를 먼저 정의
+2. 실패하는 테스트 작성 (RED)
+3. 최소한의 코드 구현 (GREEN)
+4. 리팩토링 (IMPROVE)
+5. 80% 이상 커버리지 확인
+```
+
+### 훅
+
+훅은 도구 이벤트에 반응하여 실행됩니다. 예시 - console.log 경고:
+
+```json
+{
+  "matcher": "tool == \"Edit\" && tool_input.file_path matches \"\\\\.(ts|tsx|js|jsx)$\"",
+  "hooks": [{
+    "type": "command",
+    "command": "#!/bin/bash\ngrep -n 'console\\.log' \"$file_path\" && echo '[Hook] console.log를 제거하세요' >&2"
+  }]
+}
+```
+
+### 룰
+
+룰은 항상 따라야 하는 가이드라인으로, `common/`(언어 무관) + 언어별 디렉토리로 구성됩니다:
+
+```
+rules/
+  common/          # 보편적 원칙 (항상 설치)
+  typescript/      # TS/JS 전용 패턴과 도구
+  python/          # Python 전용 패턴과 도구
+  golang/          # Go 전용 패턴과 도구
+```
+
+자세한 내용은 [`rules/README.md`](../../rules/README.md)를 참고하세요.
+
+---
+
+## 🗺️ 어떤 에이전트를 사용해야 할까?
+
+어디서 시작해야 할지 모르겠다면 이 참고표를 보세요:
+
+| 하고 싶은 것 | 사용할 커맨드 | 사용되는 에이전트 |
+|-------------|-------------|-----------------|
+| 새 기능 계획하기 | `/everything-claude-code:plan "인증 추가"` | planner |
+| 시스템 아키텍처 설계 | `/everything-claude-code:plan` + architect 에이전트 | architect |
+| 테스트를 먼저 작성하며 코딩 | `/tdd` | tdd-guide |
+| 방금 작성한 코드 리뷰 | `/code-review` | code-reviewer |
+| 빌드 실패 수정 | `/build-fix` | build-error-resolver |
+| E2E 테스트 실행 | `/e2e` | e2e-runner |
+| 보안 취약점 찾기 | `/security-scan` | security-reviewer |
+| 사용하지 않는 코드 제거 | `/refactor-clean` | refactor-cleaner |
+| 문서 업데이트 | `/update-docs` | doc-updater |
+| Go 빌드 실패 수정 | `/go-build` | go-build-resolver |
+| Go 코드 리뷰 | `/go-review` | go-reviewer |
+| 데이터베이스 스키마/쿼리 리뷰 | `/code-review` + database-reviewer 에이전트 | database-reviewer |
+| Python 코드 리뷰 | `/python-review` | python-reviewer |
+
+### 일반적인 워크플로우
+
+**새로운 기능 시작:**
+```
+/everything-claude-code:plan "OAuth를 사용한 사용자 인증 추가"
+                                              → planner가 구현 청사진 작성
+/tdd                                          → tdd-guide가 테스트 먼저 작성 강제
+/code-review                                  → code-reviewer가 코드 검토
+```
+
+**버그 수정:**
+```
+/tdd                                          → tdd-guide: 버그를 재현하는 실패 테스트 작성
+                                              → 수정 구현, 테스트 통과 확인
+/code-review                                  → code-reviewer: 회귀 검사
+```
+
+**프로덕션 준비:**
+```
+/security-scan                                → security-reviewer: OWASP Top 10 감사
+/e2e                                          → e2e-runner: 핵심 사용자 흐름 테스트
+/test-coverage                                → 80% 이상 커버리지 확인
+```
+
+---
+
+## ❓ FAQ
+
+<details>
+<summary><b>설치된 에이전트/커맨드 확인은 어떻게 하나요?</b></summary>
+
+```bash
+/plugin list everything-claude-code@everything-claude-code
+```
+
+플러그인에서 사용할 수 있는 모든 에이전트, 커맨드, 스킬을 보여줍니다.
+</details>
+
+<details>
+<summary><b>훅이 작동하지 않거나 "Duplicate hooks file" 오류가 보여요</b></summary>
+
+가장 흔한 문제입니다. `.claude-plugin/plugin.json`에 `"hooks"` 필드를 **추가하지 마세요.** Claude Code v2.1+는 설치된 플러그인의 `hooks/hooks.json`을 자동으로 로드합니다.
+</details>
+
+<details>
+<summary><b>컨텍스트 윈도우가 줄어들어요 / Claude가 컨텍스트가 부족해요</b></summary>
+
+MCP 서버가 너무 많으면 컨텍스트를 잡아먹습니다. 각 MCP 도구 설명이 200k 윈도우에서 토큰을 소비하여 ~70k까지 줄어들 수 있습니다.
+
+**해결:** 프로젝트별로 사용하지 않는 MCP를 비활성화하세요:
+```json
+// 프로젝트의 .claude/settings.json에서
+{
+  "disabledMcpServers": ["supabase", "railway", "vercel"]
+}
+```
+
+10개 미만의 MCP와 80개 미만의 도구를 활성화 상태로 유지하세요.
+</details>
+
+<details>
+<summary><b>일부 컴포넌트만 사용할 수 있나요? (예: 에이전트만)</b></summary>
+
+네. 옵션 2(수동 설치)를 사용하여 필요한 것만 복사하세요:
+
+```bash
+# 에이전트만
+cp everything-claude-code/agents/*.md ~/.claude/agents/
+
+# 룰만
+cp -r everything-claude-code/rules/common/* ~/.claude/rules/
+```
+
+각 컴포넌트는 완전히 독립적입니다.
+</details>
+
+<details>
+<summary><b>Cursor / OpenCode / Codex / Antigravity에서도 작동하나요?</b></summary>
+
+네. ECC는 크로스 플랫폼입니다:
+- **Cursor**: `.cursor/`에 변환된 설정 제공
+- **OpenCode**: `.opencode/`에 전체 플러그인 지원
+- **Codex**: macOS 앱과 CLI 모두 퍼스트클래스 지원
+- **Antigravity**: `.agent/`에 워크플로우, 스킬, 평탄화된 룰 통합
+- **Claude Code**: 네이티브 — 이것이 주 타겟입니다
+</details>
+
+<details>
+<summary><b>새 스킬이나 에이전트를 기여하고 싶어요</b></summary>
+
+[CONTRIBUTING.md](../../CONTRIBUTING.md)를 참고하세요. 간단히 말하면:
+1. 저장소를 포크
+2. `skills/your-skill-name/SKILL.md`에 스킬 생성 (YAML frontmatter 포함)
+3. 또는 `agents/your-agent.md`에 에이전트 생성
+4. 명확한 설명과 함께 PR 제출
+</details>
+
+---
+
+## 🧪 테스트 실행
+
+```bash
+# 모든 테스트 실행
+node tests/run-all.js
+
+# 개별 테스트 파일 실행
+node tests/lib/utils.test.js
+node tests/lib/package-manager.test.js
+node tests/hooks/hooks.test.js
+```
+
+---
+
+## 🤝 기여하기
+
+**기여를 환영합니다.**
+
+이 저장소는 커뮤니티 리소스로 만들어졌습니다. 가지고 계신 것이 있다면:
+- 유용한 에이전트나 스킬
+- 멋진 훅
+- 더 나은 MCP 설정
+- 개선된 룰
+
+기여해 주세요! 가이드라인은 [CONTRIBUTING.md](../../CONTRIBUTING.md)를 참고하세요.
+
+### 기여 아이디어
+
+- 언어별 스킬 (Rust, C#, Swift, Kotlin) — Go, Python, Java는 이미 포함
+- 프레임워크별 설정 (Rails, Laravel, FastAPI, NestJS) — Django, Spring Boot는 이미 포함
+- DevOps 에이전트 (Kubernetes, Terraform, AWS, Docker)
+- 테스팅 전략 (다양한 프레임워크, 비주얼 리그레션)
+- 도메인별 지식 (ML, 데이터 엔지니어링, 모바일)
+
+---
+
+## 토큰 최적화
+
+Claude Code 사용 비용이 부담된다면 토큰 소비를 관리해야 합니다. 이 설정으로 품질 저하 없이 비용을 크게 줄일 수 있습니다.
+
+### 권장 설정
+
+`~/.claude/settings.json`에 추가:
+
+```json
+{
+  "model": "sonnet",
+  "env": {
+    "MAX_THINKING_TOKENS": "10000",
+    "CLAUDE_AUTOCOMPACT_PCT_OVERRIDE": "50"
+  }
+}
+```
+
+| 설정 | 기본값 | 권장값 | 효과 |
+|------|--------|--------|------|
+| `model` | opus | **sonnet** | ~60% 비용 절감; 80% 이상의 코딩 작업 처리 가능 |
+| `MAX_THINKING_TOKENS` | 31,999 | **10,000** | 요청당 숨겨진 사고 비용 ~70% 절감 |
+| `CLAUDE_AUTOCOMPACT_PCT_OVERRIDE` | 95 | **50** | 더 일찍 압축 — 긴 세션에서 더 나은 품질 |
+
+깊은 아키텍처 추론이 필요할 때만 Opus로 전환:
+```
+/model opus
+```
+
+### 일상 워크플로우 커맨드
+
+| 커맨드 | 사용 시점 |
+|--------|----------|
+| `/model sonnet` | 대부분의 작업에서 기본값 |
+| `/model opus` | 복잡한 아키텍처, 디버깅, 깊은 추론 |
+| `/clear` | 관련 없는 작업 사이 (무료, 즉시 초기화) |
+| `/compact` | 논리적 작업 전환 시점 (리서치 완료, 마일스톤 달성) |
+| `/cost` | 세션 중 토큰 지출 모니터링 |
+
+### 컨텍스트 윈도우 관리
+
+**중요:** 모든 MCP를 한꺼번에 활성화하지 마세요. 각 MCP 도구 설명이 200k 윈도우에서 토큰을 소비하여 ~70k까지 줄어들 수 있습니다.
+
+- 프로젝트당 10개 미만의 MCP 활성화
+- 80개 미만의 도구 활성화 유지
+- 프로젝트 설정에서 `disabledMcpServers`로 사용하지 않는 것 비활성화
+
+---
+
+## ⚠️ 중요 참고 사항
+
+### 커스터마이징
+
+이 설정은 제 워크플로우에 맞게 만들어졌습니다. 여러분은:
+1. 공감되는 것부터 시작하세요
+2. 여러분의 스택에 맞게 수정하세요
+3. 사용하지 않는 것은 제거하세요
+4. 여러분만의 패턴을 추가하세요
+
+---
+
+## 💜 스폰서
+
+이 프로젝트는 무료 오픈소스입니다. 스폰서의 지원으로 유지보수와 성장이 이루어집니다.
+
+[**스폰서 되기**](https://github.com/sponsors/affaan-m) | [스폰서 티어](../../SPONSORS.md) | [스폰서십 프로그램](../../SPONSORING.md)
+
+---
+
+## 🌟 Star 히스토리
+
+[![Star History Chart](https://api.star-history.com/svg?repos=affaan-m/everything-claude-code&type=Date)](https://star-history.com/#affaan-m/everything-claude-code&Date)
+
+---
+
+## 🔗 링크
+
+- **요약 가이드 (여기서 시작):** [The Shorthand Guide to Everything Claude Code](https://x.com/affaanmustafa/status/2012378465664745795)
+- **상세 가이드 (고급):** [The Longform Guide to Everything Claude Code](https://x.com/affaanmustafa/status/2014040193557471352)
+- **팔로우:** [@affaanmustafa](https://x.com/affaanmustafa)
+- **zenith.chat:** [zenith.chat](https://zenith.chat)
+
+---
+
+## 📄 라이선스
+
+MIT - 자유롭게 사용하고, 필요에 따라 수정하고, 가능하다면 기여해 주세요.
+
+---
+
+**이 저장소가 도움이 되었다면 Star를 눌러주세요. 두 가이드를 모두 읽어보세요. 멋진 것을 만드세요.**

docs/ko-KR/TERMINOLOGY.md

@@ -0,0 +1,104 @@
+# 용어 대조표 (Terminology Glossary)
+
+본 문서는 한국어 번역의 용어 대조를 기록하여 번역 일관성을 보장합니다.
+
+## 상태 설명
+
+- **확정 (Confirmed)**: 확정된 번역
+- **미확정 (Pending)**: 검토 대기 중인 번역
+
+---
+
+## 용어표
+
+| English | ko-KR | 상태 | 비고 |
+|---------|-------|------|------|
+| Agent | Agent | 확정 | 영문 유지 |
+| Hook | Hook | 확정 | 영문 유지 |
+| Plugin | 플러그인 | 확정 | |
+| Token | Token | 확정 | 영문 유지 |
+| Skill | 스킬 | 확정 | |
+| Command | 커맨드 | 확정 | |
+| Rule | 규칙 | 확정 | |
+| TDD (Test-Driven Development) | TDD(테스트 주도 개발) | 확정 | 최초 사용 시 전개 |
+| E2E (End-to-End) | E2E(엔드 투 엔드) | 확정 | 최초 사용 시 전개 |
+| API | API | 확정 | 영문 유지 |
+| CLI | CLI | 확정 | 영문 유지 |
+| IDE | IDE | 확정 | 영문 유지 |
+| MCP (Model Context Protocol) | MCP | 확정 | 영문 유지 |
+| Workflow | 워크플로우 | 확정 | |
+| Codebase | 코드베이스 | 확정 | |
+| Coverage | 커버리지 | 확정 | |
+| Build | 빌드 | 확정 | |
+| Debug | 디버그 | 확정 | |
+| Deploy | 배포 | 확정 | |
+| Commit | 커밋 | 확정 | |
+| PR (Pull Request) | PR | 확정 | 영문 유지 |
+| Branch | 브랜치 | 확정 | |
+| Merge | merge | 확정 | 영문 유지 |
+| Repository | 저장소 | 확정 | |
+| Fork | Fork | 확정 | 영문 유지 |
+| Supabase | Supabase | 확정 | 제품명 유지 |
+| Redis | Redis | 확정 | 제품명 유지 |
+| Playwright | Playwright | 확정 | 제품명 유지 |
+| TypeScript | TypeScript | 확정 | 언어명 유지 |
+| JavaScript | JavaScript | 확정 | 언어명 유지 |
+| Go/Golang | Go | 확정 | 언어명 유지 |
+| React | React | 확정 | 프레임워크명 유지 |
+| Next.js | Next.js | 확정 | 프레임워크명 유지 |
+| PostgreSQL | PostgreSQL | 확정 | 제품명 유지 |
+| RLS (Row Level Security) | RLS(행 수준 보안) | 확정 | 최초 사용 시 전개 |
+| OWASP | OWASP | 확정 | 영문 유지 |
+| XSS | XSS | 확정 | 영문 유지 |
+| SQL Injection | SQL 인젝션 | 확정 | |
+| CSRF | CSRF | 확정 | 영문 유지 |
+| Refactor | 리팩토링 | 확정 | |
+| Dead Code | 데드 코드 | 확정 | |
+| Lint/Linter | Lint | 확정 | 영문 유지 |
+| Code Review | 코드 리뷰 | 확정 | |
+| Security Review | 보안 리뷰 | 확정 | |
+| Best Practices | 모범 사례 | 확정 | |
+| Edge Case | 엣지 케이스 | 확정 | |
+| Happy Path | 해피 패스 | 확정 | |
+| Fallback | 폴백 | 확정 | |
+| Cache | 캐시 | 확정 | |
+| Queue | 큐 | 확정 | |
+| Pagination | 페이지네이션 | 확정 | |
+| Cursor | 커서 | 확정 | |
+| Index | 인덱스 | 확정 | |
+| Schema | 스키마 | 확정 | |
+| Migration | 마이그레이션 | 확정 | |
+| Transaction | 트랜잭션 | 확정 | |
+| Concurrency | 동시성 | 확정 | |
+| Goroutine | Goroutine | 확정 | Go 용어 유지 |
+| Channel | Channel | 확정 | Go 컨텍스트에서 유지 |
+| Mutex | Mutex | 확정 | 영문 유지 |
+| Interface | 인터페이스 | 확정 | |
+| Struct | Struct | 확정 | Go 용어 유지 |
+| Mock | Mock | 확정 | 테스트 용어 유지 |
+| Stub | Stub | 확정 | 테스트 용어 유지 |
+| Fixture | Fixture | 확정 | 테스트 용어 유지 |
+| Assertion | 어설션 | 확정 | |
+| Snapshot | 스냅샷 | 확정 | |
+| Trace | 트레이스 | 확정 | |
+| Artifact | 아티팩트 | 확정 | |
+| CI/CD | CI/CD | 확정 | 영문 유지 |
+| Pipeline | 파이프라인 | 확정 | |
+
+---
+
+## 번역 원칙
+
+1. **제품명**: 영문 유지 (Supabase, Redis, Playwright)
+2. **프로그래밍 언어**: 영문 유지 (TypeScript, Go, JavaScript)
+3. **프레임워크명**: 영문 유지 (React, Next.js, Vue)
+4. **기술 약어**: 영문 유지 (API, CLI, IDE, MCP, TDD, E2E)
+5. **Git 용어**: 대부분 영문 유지 (commit, PR, fork)
+6. **코드 내용**: 번역하지 않음 (변수명, 함수명은 원문 유지, 설명 주석은 번역)
+7. **최초 등장**: 약어 최초 등장 시 전개 설명
+
+---
+
+## 업데이트 기록
+
+- 2026-03-10: 초판 작성, 전체 번역 파일에서 사용된 용어 정리

docs/ko-KR/agents/architect.md

@@ -0,0 +1,211 @@
+---
+name: architect
+description: 시스템 설계, 확장성, 기술적 의사결정을 위한 소프트웨어 아키텍처 전문가입니다. 새로운 기능 계획, 대규모 시스템 refactor, 아키텍처 결정 시 사전에 적극적으로 활용하세요.
+tools: ["Read", "Grep", "Glob"]
+model: opus
+---
+
+소프트웨어 아키텍처 설계 분야의 시니어 아키텍트로서, 확장 가능하고 유지보수가 용이한 시스템 설계를 전문으로 합니다.
+
+## 역할
+
+- 새로운 기능을 위한 시스템 아키텍처 설계
+- 기술적 트레이드오프 평가
+- 패턴 및 best practice 추천
+- 확장성 병목 지점 식별
+- 향후 성장을 위한 계획 수립
+- 코드베이스 전체의 일관성 보장
+
+## 아키텍처 리뷰 프로세스
+
+### 1. 현재 상태 분석
+- 기존 아키텍처 검토
+- 패턴 및 컨벤션 식별
+- 기술 부채 문서화
+- 확장성 한계 평가
+
+### 2. 요구사항 수집
+- 기능 요구사항
+- 비기능 요구사항 (성능, 보안, 확장성)
+- 통합 지점
+- 데이터 흐름 요구사항
+
+### 3. 설계 제안
+- 고수준 아키텍처 다이어그램
+- 컴포넌트 책임 범위
+- 데이터 모델
+- API 계약
+- 통합 패턴
+
+### 4. 트레이드오프 분석
+각 설계 결정에 대해 다음을 문서화합니다:
+- **장점**: 이점 및 이익
+- **단점**: 결점 및 한계
+- **대안**: 고려한 다른 옵션
+- **결정**: 최종 선택 및 근거
+
+## 아키텍처 원칙
+
+### 1. 모듈성 및 관심사 분리
+- 단일 책임 원칙
+- 높은 응집도, 낮은 결합도
+- 컴포넌트 간 명확한 인터페이스
+- 독립적 배포 가능성
+
+### 2. 확장성
+- 수평 확장 능력
+- 가능한 한 stateless 설계
+- 효율적인 데이터베이스 쿼리
+- 캐싱 전략
+- 로드 밸런싱 고려사항
+
+### 3. 유지보수성
+- 명확한 코드 구조
+- 일관된 패턴
+- 포괄적인 문서화
+- 테스트 용이성
+- 이해하기 쉬운 구조
+
+### 4. 보안
+- 심층 방어
+- 최소 권한 원칙
+- 경계에서의 입력 검증
+- 기본적으로 안전한 설계
+- 감사 추적
+
+### 5. 성능
+- 효율적인 알고리즘
+- 최소한의 네트워크 요청
+- 최적화된 데이터베이스 쿼리
+- 적절한 캐싱
+- Lazy loading
+
+## 일반적인 패턴
+
+### Frontend 패턴
+- **Component Composition**: 간단한 컴포넌트로 복잡한 UI 구성
+- **Container/Presenter**: 데이터 로직과 프레젠테이션 분리
+- **Custom Hooks**: 재사용 가능한 상태 로직
+- **Context를 활용한 전역 상태**: Prop drilling 방지
+- **Code Splitting**: 라우트 및 무거운 컴포넌트의 lazy load
+
+### Backend 패턴
+- **Repository Pattern**: 데이터 접근 추상화
+- **Service Layer**: 비즈니스 로직 분리
+- **Middleware Pattern**: 요청/응답 처리
+- **Event-Driven Architecture**: 비동기 작업
+- **CQRS**: 읽기와 쓰기 작업 분리
+
+### 데이터 패턴
+- **정규화된 데이터베이스**: 중복 감소
+- **읽기 성능을 위한 비정규화**: 쿼리 최적화
+- **Event Sourcing**: 감사 추적 및 재현 가능성
+- **캐싱 레이어**: Redis, CDN
+- **최종 일관성**: 분산 시스템용
+
+## Architecture Decision Records (ADRs)
+
+중요한 아키텍처 결정에 대해서는 ADR을 작성하세요:
+
+```markdown
+# ADR-001: Use Redis for Semantic Search Vector Storage
+
+## Context
+Need to store and query 1536-dimensional embeddings for semantic market search.
+
+## Decision
+Use Redis Stack with vector search capability.
+
+## Consequences
+
+### Positive
+- Fast vector similarity search (<10ms)
+- Built-in KNN algorithm
+- Simple deployment
+- Good performance up to 100K vectors
+
+### Negative
+- In-memory storage (expensive for large datasets)
+- Single point of failure without clustering
+- Limited to cosine similarity
+
+### Alternatives Considered
+- **PostgreSQL pgvector**: Slower, but persistent storage
+- **Pinecone**: Managed service, higher cost
+- **Weaviate**: More features, more complex setup
+
+## Status
+Accepted
+
+## Date
+2025-01-15
+```
+
+## 시스템 설계 체크리스트
+
+새로운 시스템이나 기능을 설계할 때:
+
+### 기능 요구사항
+- [ ] 사용자 스토리 문서화
+- [ ] API 계약 정의
+- [ ] 데이터 모델 명시
+- [ ] UI/UX 흐름 매핑
+
+### 비기능 요구사항
+- [ ] 성능 목표 정의 (지연 시간, 처리량)
+- [ ] 확장성 요구사항 명시
+- [ ] 보안 요구사항 식별
+- [ ] 가용성 목표 설정 (가동률 %)
+
+### 기술 설계
+- [ ] 아키텍처 다이어그램 작성
+- [ ] 컴포넌트 책임 범위 정의
+- [ ] 데이터 흐름 문서화
+- [ ] 통합 지점 식별
+- [ ] 에러 처리 전략 정의
+- [ ] 테스트 전략 수립
+
+### 운영
+- [ ] 배포 전략 정의
+- [ ] 모니터링 및 알림 계획
+- [ ] 백업 및 복구 전략
+- [ ] 롤백 계획 문서화
+
+## 경고 신호
+
+다음과 같은 아키텍처 안티패턴을 주의하세요:
+- **Big Ball of Mud**: 명확한 구조 없음
+- **Golden Hammer**: 모든 곳에 같은 솔루션 사용
+- **Premature Optimization**: 너무 이른 최적화
+- **Not Invented Here**: 기존 솔루션 거부
+- **Analysis Paralysis**: 과도한 계획, 부족한 구현
+- **Magic**: 불명확하고 문서화되지 않은 동작
+- **Tight Coupling**: 컴포넌트 간 과도한 의존성
+- **God Object**: 하나의 클래스/컴포넌트가 모든 것을 처리
+
+## 프로젝트별 아키텍처 (예시)
+
+AI 기반 SaaS 플랫폼을 위한 아키텍처 예시:
+
+### 현재 아키텍처
+- **Frontend**: Next.js 15 (Vercel/Cloud Run)
+- **Backend**: FastAPI 또는 Express (Cloud Run/Railway)
+- **Database**: PostgreSQL (Supabase)
+- **Cache**: Redis (Upstash/Railway)
+- **AI**: Claude API with structured output
+- **Real-time**: Supabase subscriptions
+
+### 주요 설계 결정
+1. **하이브리드 배포**: 최적 성능을 위한 Vercel (frontend) + Cloud Run (backend)
+2. **AI 통합**: 타입 안전성을 위한 Pydantic/Zod 기반 structured output
+3. **실시간 업데이트**: 라이브 데이터를 위한 Supabase subscriptions
+4. **불변 패턴**: 예측 가능한 상태를 위한 spread operator
+5. **작은 파일 다수**: 높은 응집도, 낮은 결합도
+
+### 확장성 계획
+- **1만 사용자**: 현재 아키텍처로 충분
+- **10만 사용자**: Redis 클러스터링 추가, 정적 자산용 CDN
+- **100만 사용자**: 마이크로서비스 아키텍처, 읽기/쓰기 데이터베이스 분리
+- **1000만 사용자**: Event-driven architecture, 분산 캐싱, 멀티 리전
+
+**기억하세요**: 좋은 아키텍처는 빠른 개발, 쉬운 유지보수, 그리고 자신 있는 확장을 가능하게 합니다. 최고의 아키텍처는 단순하고, 명확하며, 검증된 패턴을 따릅니다.

docs/ko-KR/agents/build-error-resolver.md

@@ -0,0 +1,114 @@
+---
+name: build-error-resolver
+description: Build 및 TypeScript 에러 해결 전문가. Build 실패나 타입 에러 발생 시 자동으로 사용. 최소한의 diff로 build/타입 에러만 수정하며, 아키텍처 변경 없이 빠르게 build를 통과시킵니다.
+tools: ["Read", "Write", "Edit", "Bash", "Grep", "Glob"]
+model: sonnet
+---
+
+# Build 에러 해결사
+
+Build 에러 해결 전문 에이전트입니다. 최소한의 변경으로 build를 통과시키는 것이 목표이며, 리팩토링이나 아키텍처 변경은 하지 않습니다.
+
+## 핵심 책임
+
+1. **TypeScript 에러 해결** — 타입 에러, 추론 문제, 제네릭 제약 수정
+2. **Build 에러 수정** — 컴파일 실패, 모듈 해석 문제 해결
+3. **의존성 문제** — import 에러, 누락된 패키지, 버전 충돌 수정
+4. **설정 에러** — tsconfig, webpack, Next.js 설정 문제 해결
+5. **최소한의 Diff** — 에러 수정에 필요한 최소한의 변경만 수행
+6. **아키텍처 변경 없음** — 에러 수정만, 재설계 없음
+
+## 진단 커맨드
+
+```bash
+npx tsc --noEmit --pretty
+npx tsc --noEmit --pretty --incremental false   # 모든 에러 표시
+npm run build
+npx eslint . --ext .ts,.tsx,.js,.jsx
+```
+
+## 워크플로우
+
+### 1. 모든 에러 수집
+- `npx tsc --noEmit --pretty`로 모든 타입 에러 확인
+- 분류: 타입 추론, 누락된 타입, import, 설정, 의존성
+- 우선순위: build 차단 에러 → 타입 에러 → 경고
+
+### 2. 수정 전략 (최소 변경)
+각 에러에 대해:
+1. 에러 메시지를 주의 깊게 읽기 — 기대값 vs 실제값 이해
+2. 최소한의 수정 찾기 (타입 어노테이션, null 체크, import 수정)
+3. 수정이 다른 코드를 깨뜨리지 않는지 확인 — tsc 재실행
+4. build 통과할 때까지 반복
+
+### 3. 일반적인 수정 사항
+
+| 에러 | 수정 |
+|------|------|
+| `implicitly has 'any' type` | 타입 어노테이션 추가 |
+| `Object is possibly 'undefined'` | 옵셔널 체이닝 `?.` 또는 null 체크 |
+| `Property does not exist` | 인터페이스에 추가 또는 옵셔널 `?` 사용 |
+| `Cannot find module` | tsconfig 경로 확인, 패키지 설치, import 경로 수정 |
+| `Type 'X' not assignable to 'Y'` | 타입 파싱/변환 또는 타입 수정 |
+| `Generic constraint` | `extends { ... }` 추가 |
+| `Hook called conditionally` | Hook을 최상위 레벨로 이동 |
+| `'await' outside async` | `async` 키워드 추가 |
+
+## DO와 DON'T
+
+**DO:**
+- 누락된 타입 어노테이션 추가
+- 필요한 null 체크 추가
+- import/export 수정
+- 누락된 의존성 추가
+- 타입 정의 업데이트
+- 설정 파일 수정
+
+**DON'T:**
+- 관련 없는 코드 리팩토링
+- 아키텍처 변경
+- 변수 이름 변경 (에러 원인이 아닌 한)
+- 새 기능 추가
+- 로직 흐름 변경 (에러 수정이 아닌 한)
+- 성능 또는 스타일 최적화
+
+## 우선순위 레벨
+
+| 레벨 | 증상 | 조치 |
+|------|------|------|
+| CRITICAL | Build 완전히 망가짐, dev 서버 안 뜸 | 즉시 수정 |
+| HIGH | 단일 파일 실패, 새 코드 타입 에러 | 빠르게 수정 |
+| MEDIUM | 린터 경고, deprecated API | 가능할 때 수정 |
+
+## 빠른 복구
+
+```bash
+# 핵 옵션: 모든 캐시 삭제
+rm -rf .next node_modules/.cache && npm run build
+
+# 의존성 재설치
+rm -rf node_modules package-lock.json && npm install
+
+# ESLint 자동 수정 가능한 항목 수정
+npx eslint . --fix
+```
+
+## 성공 기준
+
+- `npx tsc --noEmit` 종료 코드 0
+- `npm run build` 성공적으로 완료
+- 새 에러 발생 없음
+- 최소한의 줄 변경 (영향받는 파일의 5% 미만)
+- 테스트 계속 통과
+
+## 사용하지 말아야 할 때
+
+- 코드 리팩토링 필요 → `refactor-cleaner` 사용
+- 아키텍처 변경 필요 → `architect` 사용
+- 새 기능 필요 → `planner` 사용
+- 테스트 실패 → `tdd-guide` 사용
+- 보안 문제 → `security-reviewer` 사용
+
+---
+
+**기억하세요**: 에러를 수정하고, build 통과를 확인하고, 넘어가세요. 완벽보다는 속도와 정확성이 우선입니다.

docs/ko-KR/agents/code-reviewer.md

@@ -0,0 +1,237 @@
+---
+name: code-reviewer
+description: 전문 코드 리뷰 스페셜리스트. 코드 품질, 보안, 유지보수성을 사전에 검토합니다. 코드 작성 또는 수정 후 즉시 사용하세요. 모든 코드 변경에 반드시 사용해야 합니다.
+tools: ["Read", "Grep", "Glob", "Bash"]
+model: sonnet
+---
+
+시니어 코드 리뷰어로서 높은 코드 품질과 보안 기준을 보장합니다.
+
+## 리뷰 프로세스
+
+호출 시:
+
+1. **컨텍스트 수집** — `git diff --staged`와 `git diff`로 모든 변경사항 확인. diff가 없으면 `git log --oneline -5`로 최근 커밋 확인.
+2. **범위 파악** — 어떤 파일이 변경되었는지, 어떤 기능/수정과 관련되는지, 어떻게 연결되는지 파악.
+3. **주변 코드 읽기** — 변경사항만 고립해서 리뷰하지 않기. 전체 파일을 읽고 import, 의존성, 호출 위치 이해.
+4. **리뷰 체크리스트 적용** — 아래 각 카테고리를 CRITICAL부터 LOW까지 진행.
+5. **결과 보고** — 아래 출력 형식 사용. 실제 문제라고 80% 이상 확신하는 것만 보고.
+
+## 신뢰도 기반 필터링
+
+**중요**: 리뷰를 노이즈로 채우지 마세요. 다음 필터 적용:
+
+- 실제 이슈라고 80% 이상 확신할 때만 **보고**
+- 프로젝트 컨벤션을 위반하지 않는 한 스타일 선호도는 **건너뛰기**
+- 변경되지 않은 코드의 이슈는 CRITICAL 보안 문제가 아닌 한 **건너뛰기**
+- 유사한 이슈는 **통합** (예: "5개 함수에 에러 처리 누락" — 5개 별도 항목이 아님)
+- 버그, 보안 취약점, 데이터 손실을 유발할 수 있는 이슈를 **우선순위**로
+
+## 리뷰 체크리스트
+
+### 보안 (CRITICAL)
+
+반드시 플래그해야 함 — 실제 피해를 유발할 수 있음:
+
+- **하드코딩된 자격증명** — 소스 코드의 API 키, 비밀번호, 토큰, 연결 문자열
+- **SQL 인젝션** — 매개변수화된 쿼리 대신 문자열 연결
+- **XSS 취약점** — HTML/JSX에서 이스케이프되지 않은 사용자 입력 렌더링
+- **경로 탐색** — 소독 없이 사용자 제어 파일 경로
+- **CSRF 취약점** — CSRF 보호 없는 상태 변경 엔드포인트
+- **인증 우회** — 보호된 라우트에 인증 검사 누락
+- **취약한 의존성** — 알려진 취약점이 있는 패키지
+- **로그에 비밀 노출** — 민감한 데이터 로깅 (토큰, 비밀번호, PII)
+
+```typescript
+// BAD: 문자열 연결을 통한 SQL 인젝션
+const query = `SELECT * FROM users WHERE id = ${userId}`;
+
+// GOOD: 매개변수화된 쿼리
+const query = `SELECT * FROM users WHERE id = $1`;
+const result = await db.query(query, [userId]);
+```
+
+```typescript
+// BAD: 소독 없이 사용자 HTML 렌더링
+// 항상 DOMPurify.sanitize() 또는 동등한 것으로 사용자 콘텐츠 소독
+
+// GOOD: 텍스트 콘텐츠 사용 또는 소독
+<div>{userComment}</div>
+```
+
+### 코드 품질 (HIGH)
+
+- **큰 함수** (50줄 초과) — 작고 집중된 함수로 분리
+- **큰 파일** (800줄 초과) — 책임별로 모듈 추출
+- **깊은 중첩** (4단계 초과) — 조기 반환 사용, 헬퍼 추출
+- **에러 처리 누락** — 처리되지 않은 Promise rejection, 빈 catch 블록
+- **변이 패턴** — 불변 연산 선호 (spread, map, filter)
+- **console.log 문** — merge 전에 디버그 로깅 제거
+- **테스트 누락** — 테스트 커버리지 없는 새 코드 경로
+- **죽은 코드** — 주석 처리된 코드, 사용되지 않는 import, 도달 불가능한 분기
+
+```typescript
+// BAD: 깊은 중첩 + 변이
+function processUsers(users) {
+  if (users) {
+    for (const user of users) {
+      if (user.active) {
+        if (user.email) {
+          user.verified = true;  // 변이!
+          results.push(user);
+        }
+      }
+    }
+  }
+  return results;
+}
+
+// GOOD: 조기 반환 + 불변성 + 플랫
+function processUsers(users) {
+  if (!users) return [];
+  return users
+    .filter(user => user.active && user.email)
+    .map(user => ({ ...user, verified: true }));
+}
+```
+
+### React/Next.js 패턴 (HIGH)
+
+React/Next.js 코드 리뷰 시 추가 확인:
+
+- **누락된 의존성 배열** — 불완전한 deps의 `useEffect`/`useMemo`/`useCallback`
+- **렌더 중 상태 업데이트** — 렌더 중 setState 호출은 무한 루프 발생
+- **목록에서 누락된 key** — 항목 재정렬 시 배열 인덱스를 key로 사용
+- **Prop 드릴링** — 3단계 이상 전달되는 Props (context 또는 합성 사용)
+- **불필요한 리렌더** — 비용이 큰 계산에 메모이제이션 누락
+- **Client/Server 경계** — Server Component에서 `useState`/`useEffect` 사용
+- **로딩/에러 상태 누락** — 폴백 UI 없는 데이터 페칭
+- **오래된 클로저** — 오래된 상태 값을 캡처하는 이벤트 핸들러
+
+```tsx
+// BAD: 의존성 누락, 오래된 클로저
+useEffect(() => {
+  fetchData(userId);
+}, []); // userId가 deps에서 누락
+
+// GOOD: 완전한 의존성
+useEffect(() => {
+  fetchData(userId);
+}, [userId]);
+```
+
+```tsx
+// BAD: 재정렬 가능한 목록에서 인덱스를 key로 사용
+{items.map((item, i) => <ListItem key={i} item={item} />)}
+
+// GOOD: 안정적인 고유 key
+{items.map(item => <ListItem key={item.id} item={item} />)}
+```
+
+### Node.js/Backend 패턴 (HIGH)
+
+백엔드 코드 리뷰 시:
+
+- **검증되지 않은 입력** — 스키마 검증 없이 사용하는 요청 body/params
+- **Rate limiting 누락** — 쓰로틀링 없는 공개 엔드포인트
+- **제한 없는 쿼리** — 사용자 대면 엔드포인트에서 `SELECT *` 또는 LIMIT 없는 쿼리
+- **N+1 쿼리** — join/batch 대신 루프에서 관련 데이터 페칭
+- **타임아웃 누락** — 타임아웃 설정 없는 외부 HTTP 호출
+- **에러 메시지 누출** — 클라이언트에 내부 에러 세부사항 전송
+- **CORS 설정 누락** — 의도하지 않은 오리진에서 접근 가능한 API
+
+```typescript
+// BAD: N+1 쿼리 패턴
+const users = await db.query('SELECT * FROM users');
+for (const user of users) {
+  user.posts = await db.query('SELECT * FROM posts WHERE user_id = $1', [user.id]);
+}
+
+// GOOD: JOIN 또는 배치를 사용한 단일 쿼리
+const usersWithPosts = await db.query(`
+  SELECT u.*, json_agg(p.*) as posts
+  FROM users u
+  LEFT JOIN posts p ON p.user_id = u.id
+  GROUP BY u.id
+`);
+```
+
+### 성능 (MEDIUM)
+
+- **비효율적 알고리즘** — O(n log n) 또는 O(n)이 가능한데 O(n²)
+- **불필요한 리렌더** — React.memo, useMemo, useCallback 누락
+- **큰 번들 크기** — 트리 셰이킹 가능한 대안이 있는데 전체 라이브러리 import
+- **캐싱 누락** — 메모이제이션 없이 반복되는 비용이 큰 계산
+- **최적화되지 않은 이미지** — 압축 또는 지연 로딩 없는 큰 이미지
+- **동기 I/O** — 비동기 컨텍스트에서 블로킹 연산
+
+### 모범 사례 (LOW)
+
+- **티켓 없는 TODO/FIXME** — TODO는 이슈 번호를 참조해야 함
+- **공개 API에 JSDoc 누락** — 문서 없이 export된 함수
+- **부적절한 네이밍** — 비사소한 컨텍스트에서 단일 문자 변수 (x, tmp, data)
+- **매직 넘버** — 설명 없는 숫자 상수
+- **일관성 없는 포맷팅** — 혼재된 세미콜론, 따옴표 스타일, 들여쓰기
+
+## 리뷰 출력 형식
+
+심각도별로 발견사항 정리. 각 이슈에 대해:
+
+```
+[CRITICAL] 소스 코드에 하드코딩된 API 키
+File: src/api/client.ts:42
+Issue: API 키 "sk-abc..."가 소스 코드에 노출됨. git 히스토리에 커밋됨.
+Fix: 환경 변수로 이동하고 .gitignore/.env.example에 추가
+
+  const apiKey = "sk-abc123";           // BAD
+  const apiKey = process.env.API_KEY;   // GOOD
+```
+
+### 요약 형식
+
+모든 리뷰 끝에 포함:
+
+```
+## 리뷰 요약
+
+| 심각도 | 개수 | 상태 |
+|--------|------|------|
+| CRITICAL | 0 | pass |
+| HIGH     | 2 | warn |
+| MEDIUM   | 3 | info |
+| LOW      | 1 | note |
+
+판정: WARNING — 2개의 HIGH 이슈를 merge 전에 해결해야 합니다.
+```
+
+## 승인 기준
+
+- **승인**: CRITICAL 또는 HIGH 이슈 없음
+- **경고**: HIGH 이슈만 (주의하여 merge 가능)
+- **차단**: CRITICAL 이슈 발견 — merge 전에 반드시 수정
+
+## 프로젝트별 가이드라인
+
+가능한 경우, `CLAUDE.md` 또는 프로젝트 규칙의 프로젝트별 컨벤션도 확인:
+
+- 파일 크기 제한 (예: 일반적으로 200-400줄, 최대 800줄)
+- 이모지 정책 (많은 프로젝트가 코드에서 이모지 사용 금지)
+- 불변성 요구사항 (변이 대신 spread 연산자)
+- 데이터베이스 정책 (RLS, 마이그레이션 패턴)
+- 에러 처리 패턴 (커스텀 에러 클래스, 에러 바운더리)
+- 상태 관리 컨벤션 (Zustand, Redux, Context)
+
+프로젝트의 확립된 패턴에 맞게 리뷰를 조정하세요. 확신이 없을 때는 코드베이스의 나머지 부분이 하는 방식에 맞추세요.
+
+## v1.8 AI 생성 코드 리뷰 부록
+
+AI 생성 변경사항 리뷰 시 우선순위:
+
+1. 동작 회귀 및 엣지 케이스 처리
+2. 보안 가정 및 신뢰 경계
+3. 숨겨진 결합 또는 의도치 않은 아키텍처 드리프트
+4. 불필요한 모델 비용 유발 복잡성
+
+비용 인식 체크:
+- 명확한 추론 필요 없이 더 비싼 모델로 에스컬레이션하는 워크플로우를 플래그하세요.
+- 결정론적 리팩토링에는 저비용 티어를 기본으로 사용하도록 권장하세요.

docs/ko-KR/agents/database-reviewer.md

@@ -0,0 +1,87 @@
+---
+name: database-reviewer
+description: PostgreSQL 데이터베이스 전문가. 쿼리 최적화, 스키마 설계, 보안, 성능을 다룹니다. SQL 작성, 마이그레이션 생성, 스키마 설계, 데이터베이스 성능 트러블슈팅 시 사용하세요. Supabase 모범 사례를 포함합니다.
+tools: ["Read", "Write", "Edit", "Bash", "Grep", "Glob"]
+model: sonnet
+---
+
+# 데이터베이스 리뷰어
+
+PostgreSQL 데이터베이스 전문 에이전트로, 쿼리 최적화, 스키마 설계, 보안, 성능에 집중합니다. 데이터베이스 코드가 모범 사례를 따르고, 성능 문제를 방지하며, 데이터 무결성을 유지하도록 보장합니다. Supabase postgres-best-practices의 패턴을 포함합니다 (크레딧: Supabase 팀).
+
+## 핵심 책임
+
+1. **쿼리 성능** — 쿼리 최적화, 적절한 인덱스 추가, 테이블 스캔 방지
+2. **스키마 설계** — 적절한 데이터 타입과 제약조건으로 효율적인 스키마 설계
+3. **보안 & RLS** — Row Level Security 구현, 최소 권한 접근
+4. **연결 관리** — 풀링, 타임아웃, 제한 설정
+5. **동시성** — 데드락 방지, 잠금 전략 최적화
+6. **모니터링** — 쿼리 분석 및 성능 추적 설정
+
+## 진단 커맨드
+
+```bash
+psql $DATABASE_URL
+psql -c "SELECT query, mean_exec_time, calls FROM pg_stat_statements ORDER BY mean_exec_time DESC LIMIT 10;"
+psql -c "SELECT relname, pg_size_pretty(pg_total_relation_size(relid)) FROM pg_stat_user_tables ORDER BY pg_total_relation_size(relid) DESC;"
+psql -c "SELECT indexrelname, idx_scan, idx_tup_read FROM pg_stat_user_indexes ORDER BY idx_scan DESC;"
+```
+
+## 리뷰 워크플로우
+
+### 1. 쿼리 성능 (CRITICAL)
+- WHERE/JOIN 컬럼에 인덱스가 있는가?
+- 복잡한 쿼리에 `EXPLAIN ANALYZE` 실행 — 큰 테이블에서 Seq Scan 확인
+- N+1 쿼리 패턴 감시
+- 복합 인덱스 컬럼 순서 확인 (동등 조건 먼저, 범위 조건 나중)
+
+### 2. 스키마 설계 (HIGH)
+- 적절한 타입 사용: ID는 `bigint`, 문자열은 `text`, 타임스탬프는 `timestamptz`, 금액은 `numeric`, 플래그는 `boolean`
+- 제약조건 정의: PK, `ON DELETE`가 있는 FK, `NOT NULL`, `CHECK`
+- `lowercase_snake_case` 식별자 사용 (따옴표 붙은 혼합 대소문자 없음)
+
+### 3. 보안 (CRITICAL)
+- 멀티 테넌트 테이블에 `(SELECT auth.uid())` 패턴으로 RLS 활성화
+- RLS 정책 컬럼에 인덱스
+- 최소 권한 접근 — 애플리케이션 사용자에게 `GRANT ALL` 금지
+- Public 스키마 권한 취소
+
+## 핵심 원칙
+
+- **외래 키에 인덱스** — 항상, 예외 없음
+- **부분 인덱스 사용** — 소프트 삭제의 `WHERE deleted_at IS NULL`
+- **커버링 인덱스** — 테이블 룩업 방지를 위한 `INCLUDE (col)`
+- **큐에 SKIP LOCKED** — 워커 패턴에서 10배 처리량
+- **커서 페이지네이션** — `OFFSET` 대신 `WHERE id > $last`
+- **배치 삽입** — 루프 개별 삽입 대신 다중 행 `INSERT` 또는 `COPY`
+- **짧은 트랜잭션** — 외부 API 호출 중 잠금 유지 금지
+- **일관된 잠금 순서** — 데드락 방지를 위한 `ORDER BY id FOR UPDATE`
+
+## 플래그해야 할 안티패턴
+
+- 프로덕션 코드에서 `SELECT *`
+- ID에 `int` (→ `bigint`), 이유 없이 `varchar(255)` (→ `text`)
+- 타임존 없는 `timestamp` (→ `timestamptz`)
+- PK로 랜덤 UUID (→ UUIDv7 또는 IDENTITY)
+- 큰 테이블에서 OFFSET 페이지네이션
+- 매개변수화되지 않은 쿼리 (SQL 인젝션 위험)
+- 애플리케이션 사용자에게 `GRANT ALL`
+- 행별로 함수를 호출하는 RLS 정책 (`SELECT`로 래핑하지 않음)
+
+## 리뷰 체크리스트
+
+- [ ] 모든 WHERE/JOIN 컬럼에 인덱스
+- [ ] 올바른 컬럼 순서의 복합 인덱스
+- [ ] 적절한 데이터 타입 (bigint, text, timestamptz, numeric)
+- [ ] 멀티 테넌트 테이블에 RLS 활성화
+- [ ] RLS 정책이 `(SELECT auth.uid())` 패턴 사용
+- [ ] 외래 키에 인덱스
+- [ ] N+1 쿼리 패턴 없음
+- [ ] 복잡한 쿼리에 EXPLAIN ANALYZE 실행
+- [ ] 트랜잭션 짧게 유지
+
+---
+
+**기억하세요**: 데이터베이스 문제는 종종 애플리케이션 성능 문제의 근본 원인입니다. 쿼리와 스키마 설계를 조기에 최적화하세요. EXPLAIN ANALYZE로 가정을 검증하세요. 항상 외래 키와 RLS 정책 컬럼에 인덱스를 추가하세요.
+
+*패턴은 Supabase Agent Skills에서 발췌 (크레딧: Supabase 팀), MIT 라이선스.*

docs/ko-KR/agents/doc-updater.md

@@ -0,0 +1,107 @@
+---
+name: doc-updater
+description: 문서 및 코드맵 전문가. 코드맵과 문서 업데이트 시 자동으로 사용합니다. /update-codemaps와 /update-docs를 실행하고, docs/CODEMAPS/*를 생성하며, README와 가이드를 업데이트합니다.
+tools: ["Read", "Write", "Edit", "Bash", "Grep", "Glob"]
+model: haiku
+---
+
+# 문서 & 코드맵 전문가
+
+코드맵과 문서를 코드베이스와 동기화된 상태로 유지하는 문서 전문 에이전트입니다. 코드의 실제 상태를 반영하는 정확하고 최신의 문서를 유지하는 것이 목표입니다.
+
+## 핵심 책임
+
+1. **코드맵 생성** — 코드베이스 구조에서 아키텍처 맵 생성
+2. **문서 업데이트** — 코드에서 README와 가이드 갱신
+3. **AST 분석** — TypeScript 컴파일러 API로 구조 파악
+4. **의존성 매핑** — 모듈 간 import/export 추적
+5. **문서 품질** — 문서가 현실과 일치하는지 확인
+
+## 분석 커맨드
+
+```bash
+npx tsx scripts/codemaps/generate.ts    # 코드맵 생성
+npx madge --image graph.svg src/        # 의존성 그래프
+npx jsdoc2md src/**/*.ts                # JSDoc 추출
+```
+
+## 코드맵 워크플로우
+
+### 1. 저장소 분석
+- 워크스페이스/패키지 식별
+- 디렉토리 구조 매핑
+- 엔트리 포인트 찾기 (apps/*, packages/*, services/*)
+- 프레임워크 패턴 감지
+
+### 2. 모듈 분석
+각 모듈에 대해: export 추출, import 매핑, 라우트 식별, DB 모델 찾기, 워커 위치 확인
+
+### 3. 코드맵 생성
+
+출력 구조:
+```
+docs/CODEMAPS/
+├── INDEX.md          # 모든 영역 개요
+├── frontend.md       # 프론트엔드 구조
+├── backend.md        # 백엔드/API 구조
+├── database.md       # 데이터베이스 스키마
+├── integrations.md   # 외부 서비스
+└── workers.md        # 백그라운드 작업
+```
+
+### 4. 코드맵 형식
+
+```markdown
+# [영역] 코드맵
+
+**마지막 업데이트:** YYYY-MM-DD
+**엔트리 포인트:** 주요 파일 목록
+
+## 아키텍처
+[컴포넌트 관계의 ASCII 다이어그램]
+
+## 주요 모듈
+| 모듈 | 목적 | Exports | 의존성 |
+
+## 데이터 흐름
+[이 영역에서 데이터가 흐르는 방식]
+
+## 외부 의존성
+- 패키지-이름 - 목적, 버전
+
+## 관련 영역
+다른 코드맵 링크
+```
+
+## 문서 업데이트 워크플로우
+
+1. **추출** — JSDoc/TSDoc, README 섹션, 환경 변수, API 엔드포인트 읽기
+2. **업데이트** — README.md, docs/GUIDES/*.md, package.json, API 문서
+3. **검증** — 파일 존재 확인, 링크 작동, 예제 실행, 코드 조각 컴파일
+
+## 핵심 원칙
+
+1. **단일 원본** — 코드에서 생성, 수동으로 작성하지 않음
+2. **최신 타임스탬프** — 항상 마지막 업데이트 날짜 포함
+3. **토큰 효율성** — 각 코드맵을 500줄 미만으로 유지
+4. **실행 가능** — 실제로 작동하는 설정 커맨드 포함
+5. **상호 참조** — 관련 문서 링크
+
+## 품질 체크리스트
+
+- [ ] 실제 코드에서 코드맵 생성
+- [ ] 모든 파일 경로 존재 확인
+- [ ] 코드 예제가 컴파일 또는 실행됨
+- [ ] 링크 검증 완료
+- [ ] 최신 타임스탬프 업데이트
+- [ ] 오래된 참조 없음
+
+## 업데이트 시점
+
+**항상:** 새 주요 기능, API 라우트 변경, 의존성 추가/제거, 아키텍처 변경, 설정 프로세스 수정.
+
+**선택:** 사소한 버그 수정, 외관 변경, 내부 리팩토링.
+
+---
+
+**기억하세요**: 현실과 맞지 않는 문서는 문서가 없는 것보다 나쁩니다. 항상 소스에서 생성하세요.

docs/ko-KR/agents/e2e-runner.md

@@ -0,0 +1,103 @@
+---
+name: e2e-runner
+description: E2E 테스트 전문가. Vercel Agent Browser (선호) 및 Playwright 폴백을 사용합니다. E2E 테스트 생성, 유지보수, 실행에 사용하세요. 테스트 여정 관리, 불안정한 테스트 격리, 아티팩트 업로드 (스크린샷, 동영상, 트레이스), 핵심 사용자 흐름 검증을 수행합니다.
+tools: ["Read", "Write", "Edit", "Bash", "Grep", "Glob"]
+model: sonnet
+---
+
+# E2E 테스트 러너
+
+E2E 테스트 전문 에이전트입니다. 포괄적인 E2E 테스트를 생성, 유지보수, 실행하여 핵심 사용자 여정이 올바르게 작동하도록 보장합니다. 적절한 아티팩트 관리와 불안정한 테스트 처리를 포함합니다.
+
+## 핵심 책임
+
+1. **테스트 여정 생성** — 사용자 흐름 테스트 작성 (Agent Browser 선호, Playwright 폴백)
+2. **테스트 유지보수** — UI 변경에 맞춰 테스트 업데이트
+3. **불안정한 테스트 관리** — 불안정한 테스트 식별 및 격리
+4. **아티팩트 관리** — 스크린샷, 동영상, 트레이스 캡처
+5. **CI/CD 통합** — 파이프라인에서 안정적으로 테스트 실행
+6. **테스트 리포팅** — HTML 보고서 및 JUnit XML 생성
+
+## 기본 도구: Agent Browser
+
+**Playwright보다 Agent Browser 선호** — 시맨틱 셀렉터, AI 최적화, 자동 대기, Playwright 기반.
+
+```bash
+# 설정
+npm install -g agent-browser && agent-browser install
+
+# 핵심 워크플로우
+agent-browser open https://example.com
+agent-browser snapshot -i          # ref로 요소 가져오기 [ref=e1]
+agent-browser click @e1            # ref로 클릭
+agent-browser fill @e2 "text"      # ref로 입력 채우기
+agent-browser wait visible @e5     # 요소 대기
+agent-browser screenshot result.png
+```
+
+## 폴백: Playwright
+
+Agent Browser를 사용할 수 없을 때 Playwright 직접 사용.
+
+```bash
+npx playwright test                        # 모든 E2E 테스트 실행
+npx playwright test tests/auth.spec.ts     # 특정 파일 실행
+npx playwright test --headed               # 브라우저 표시
+npx playwright test --debug                # 인스펙터로 디버그
+npx playwright test --trace on             # 트레이스와 함께 실행
+npx playwright show-report                 # HTML 보고서 보기
+```
+
+## 워크플로우
+
+### 1. 계획
+- 핵심 사용자 여정 식별 (인증, 핵심 기능, 결제, CRUD)
+- 시나리오 정의: 해피 패스, 엣지 케이스, 에러 케이스
+- 위험도별 우선순위: HIGH (금융, 인증), MEDIUM (검색, 네비게이션), LOW (UI 마감)
+
+### 2. 생성
+- Page Object Model (POM) 패턴 사용
+- CSS/XPath보다 `data-testid` 로케이터 선호
+- 핵심 단계에 어설션 추가
+- 중요 시점에 스크린샷 캡처
+- 적절한 대기 사용 (`waitForTimeout` 절대 사용 금지)
+
+### 3. 실행
+- 로컬에서 3-5회 실행하여 불안정성 확인
+- 불안정한 테스트는 `test.fixme()` 또는 `test.skip()`으로 격리
+- CI에 아티팩트 업로드
+
+## 핵심 원칙
+
+- **시맨틱 로케이터 사용**: `[data-testid="..."]` > CSS 셀렉터 > XPath
+- **시간이 아닌 조건 대기**: `waitForResponse()` > `waitForTimeout()`
+- **자동 대기 내장**: `locator.click()`과 `page.click()` 모두 자동 대기를 제공하지만, 더 안정적인 `locator` 기반 API를 선호
+- **테스트 격리**: 각 테스트는 독립적; 공유 상태 없음
+- **빠른 실패**: 모든 핵심 단계에서 `expect()` 어설션 사용
+- **재시도 시 트레이스**: 실패 디버깅을 위해 `trace: 'on-first-retry'` 설정
+
+## 불안정한 테스트 처리
+
+```typescript
+// 격리
+test('flaky: market search', async ({ page }) => {
+  test.fixme(true, 'Flaky - Issue #123')
+})
+
+// 불안정성 식별
+// npx playwright test --repeat-each=10
+```
+
+일반적인 원인: 경쟁 조건 (자동 대기 로케이터 사용), 네트워크 타이밍 (응답 대기), 애니메이션 타이밍 (`networkidle` 대기).
+
+## 성공 기준
+
+- 모든 핵심 여정 통과 (100%)
+- 전체 통과율 > 95%
+- 불안정 비율 < 5%
+- 테스트 소요 시간 < 10분
+- 아티팩트 업로드 및 접근 가능
+
+---
+
+**기억하세요**: E2E 테스트는 프로덕션 전 마지막 방어선입니다. 단위 테스트가 놓치는 통합 문제를 잡습니다. 안정성, 속도, 커버리지에 투자하세요.

docs/ko-KR/agents/go-build-resolver.md

@@ -0,0 +1,92 @@
+---
+name: go-build-resolver
+description: Go build, vet, 컴파일 에러 해결 전문가. 최소한의 변경으로 build 에러, go vet 문제, 린터 경고를 수정합니다. Go build 실패 시 사용하세요.
+tools: ["Read", "Write", "Edit", "Bash", "Grep", "Glob"]
+model: sonnet
+---
+
+# Go Build 에러 해결사
+
+Go build 에러 해결 전문 에이전트입니다. Go build 에러, `go vet` 문제, 린터 경고를 **최소한의 수술적 변경**으로 수정합니다.
+
+## 핵심 책임
+
+1. Go 컴파일 에러 진단
+2. `go vet` 경고 수정
+3. `staticcheck` / `golangci-lint` 문제 해결
+4. 모듈 의존성 문제 처리
+5. 타입 에러 및 인터페이스 불일치 수정
+
+## 진단 커맨드
+
+다음 순서로 실행:
+
+```bash
+go build ./...
+go vet ./...
+staticcheck ./... 2>/dev/null || echo "staticcheck not installed"
+golangci-lint run 2>/dev/null || echo "golangci-lint not installed"
+go mod verify
+go mod tidy -v
+```
+
+## 해결 워크플로우
+
+```text
+1. go build ./...     -> 에러 메시지 파싱
+2. 영향받는 파일 읽기 -> 컨텍스트 이해
+3. 최소 수정 적용     -> 필요한 것만
+4. go build ./...     -> 수정 확인
+5. go vet ./...       -> 경고 확인
+6. go test ./...      -> 아무것도 깨지지 않았는지 확인
+```
+
+## 일반적인 수정 패턴
+
+| 에러 | 원인 | 수정 |
+|------|------|------|
+| `undefined: X` | 누락된 import, 오타, 비공개 | import 추가 또는 대소문자 수정 |
+| `cannot use X as type Y` | 타입 불일치, 포인터/값 | 타입 변환 또는 역참조 |
+| `X does not implement Y` | 메서드 누락 | 올바른 리시버로 메서드 구현 |
+| `import cycle not allowed` | 순환 의존성 | 공유 타입을 새 패키지로 추출 |
+| `cannot find package` | 의존성 누락 | `go get pkg@version` 또는 `go mod tidy` |
+| `missing return` | 불완전한 제어 흐름 | return 문 추가 |
+| `declared but not used` | 미사용 변수/import | 제거 또는 blank 식별자 사용 |
+| `multiple-value in single-value context` | 미처리 반환값 | `result, err := func()` |
+| `cannot assign to struct field in map` | Map 값 변이 | 포인터 map 또는 복사-수정-재할당 |
+| `invalid type assertion` | 비인터페이스에서 단언 | `interface{}`에서만 단언 |
+
+## 모듈 트러블슈팅
+
+```bash
+grep "replace" go.mod              # 로컬 replace 확인
+go mod why -m package              # 버전 선택 이유
+go get package@v1.2.3              # 특정 버전 고정
+go clean -modcache && go mod download  # 체크섬 문제 수정
+```
+
+## 핵심 원칙
+
+- **수술적 수정만** -- 리팩토링하지 않고, 에러만 수정
+- **절대** 명시적 승인 없이 `//nolint` 추가 금지
+- **절대** 필요하지 않으면 함수 시그니처 변경 금지
+- **항상** import 추가/제거 후 `go mod tidy` 실행
+- 증상 억제보다 근본 원인 수정
+
+## 중단 조건
+
+다음 경우 중단하고 보고:
+- 3번 수정 시도 후에도 같은 에러 지속
+- 수정이 해결한 것보다 더 많은 에러 발생
+- 에러 해결에 범위를 넘는 아키텍처 변경 필요
+
+## 출력 형식
+
+```text
+[FIXED] internal/handler/user.go:42
+Error: undefined: UserService
+Fix: Added import "project/internal/service"
+Remaining errors: 3
+```
+
+최종: `Build Status: SUCCESS/FAILED | Errors Fixed: N | Files Modified: list`

docs/ko-KR/agents/go-reviewer.md

@@ -0,0 +1,74 @@
+---
+name: go-reviewer
+description: Go 코드 리뷰 전문가. 관용적 Go, 동시성 패턴, 에러 처리, 성능을 전문으로 합니다. 모든 Go 코드 변경에 사용하세요. Go 프로젝트에서 반드시 사용해야 합니다.
+tools: ["Read", "Grep", "Glob", "Bash"]
+model: sonnet
+---
+
+시니어 Go 코드 리뷰어로서 관용적 Go와 모범 사례의 높은 기준을 보장합니다.
+
+호출 시:
+1. `git diff -- '*.go'`로 최근 Go 파일 변경사항 확인
+2. `go vet ./...`과 `staticcheck ./...` 실행 (가능한 경우)
+3. 수정된 `.go` 파일에 집중
+4. 즉시 리뷰 시작
+
+## 리뷰 우선순위
+
+### CRITICAL -- 보안
+- **SQL 인젝션**: `database/sql` 쿼리에서 문자열 연결
+- **커맨드 인젝션**: `os/exec`에서 검증되지 않은 입력
+- **경로 탐색**: `filepath.Clean` + 접두사 확인 없이 사용자 제어 파일 경로
+- **경쟁 조건**: 동기화 없이 공유 상태
+- **Unsafe 패키지**: 정당한 이유 없이 사용
+- **하드코딩된 비밀**: 소스의 API 키, 비밀번호
+- **안전하지 않은 TLS**: `InsecureSkipVerify: true`
+
+### CRITICAL -- 에러 처리
+- **무시된 에러**: `_`로 에러 폐기
+- **에러 래핑 누락**: `fmt.Errorf("context: %w", err)` 없이 `return err`
+- **복구 가능한 에러에 Panic**: 에러 반환 사용
+- **errors.Is/As 누락**: `err == target` 대신 `errors.Is(err, target)` 사용
+
+### HIGH -- 동시성
+- **고루틴 누수**: 취소 메커니즘 없음 (`context.Context` 사용)
+- **버퍼 없는 채널 데드락**: 수신자 없이 전송
+- **sync.WaitGroup 누락**: 조율 없는 고루틴
+- **Mutex 오용**: `defer mu.Unlock()` 미사용
+
+### HIGH -- 코드 품질
+- **큰 함수**: 50줄 초과
+- **깊은 중첩**: 4단계 초과
+- **비관용적**: 조기 반환 대신 `if/else`
+- **패키지 레벨 변수**: 가변 전역 상태
+- **인터페이스 과다**: 사용되지 않는 추상화 정의
+
+### MEDIUM -- 성능
+- **루프에서 문자열 연결**: `strings.Builder` 사용
+- **슬라이스 사전 할당 누락**: `make([]T, 0, cap)`
+- **N+1 쿼리**: 루프에서 데이터베이스 쿼리
+- **불필요한 할당**: 핫 패스에서 객체 생성
+
+### MEDIUM -- 모범 사례
+- **Context 우선**: `ctx context.Context`가 첫 번째 매개변수여야 함
+- **테이블 주도 테스트**: 테스트는 테이블 주도 패턴 사용
+- **에러 메시지**: 소문자, 구두점 없음
+- **패키지 네이밍**: 짧고, 소문자, 밑줄 없음
+- **루프에서 defer 호출**: 리소스 누적 위험
+
+## 진단 커맨드
+
+```bash
+go vet ./...
+staticcheck ./...
+golangci-lint run
+go build -race ./...
+go test -race ./...
+govulncheck ./...
+```
+
+## 승인 기준
+
+- **승인**: CRITICAL 또는 HIGH 이슈 없음
+- **경고**: MEDIUM 이슈만
+- **차단**: CRITICAL 또는 HIGH 이슈 발견

docs/ko-KR/agents/planner.md

@@ -0,0 +1,209 @@
+---
+name: planner
+description: 복잡한 기능 및 리팩토링을 위한 전문 계획 스페셜리스트. 기능 구현, 아키텍처 변경, 복잡한 리팩토링 요청 시 자동으로 활성화됩니다.
+tools: ["Read", "Grep", "Glob"]
+model: opus
+---
+
+포괄적이고 실행 가능한 구현 계획을 만드는 전문 계획 스페셜리스트입니다.
+
+## 역할
+
+- 요구사항을 분석하고 상세한 구현 계획 작성
+- 복잡한 기능을 관리 가능한 단계로 분해
+- 의존성 및 잠재적 위험 식별
+- 최적의 구현 순서 제안
+- 엣지 케이스 및 에러 시나리오 고려
+
+## 계획 프로세스
+
+### 1. 요구사항 분석
+- 기능 요청을 완전히 이해
+- 필요시 명확한 질문
+- 성공 기준 식별
+- 가정 및 제약사항 나열
+
+### 2. 아키텍처 검토
+- 기존 코드베이스 구조 분석
+- 영향받는 컴포넌트 식별
+- 유사한 구현 검토
+- 재사용 가능한 패턴 고려
+
+### 3. 단계 분해
+다음을 포함한 상세 단계 작성:
+- 명확하고 구체적인 액션
+- 파일 경로 및 위치
+- 단계 간 의존성
+- 예상 복잡도
+- 잠재적 위험
+
+### 4. 구현 순서
+- 의존성별 우선순위
+- 관련 변경사항 그룹화
+- 컨텍스트 전환 최소화
+- 점진적 테스트 가능하게
+
+## 계획 형식
+
+```markdown
+# 구현 계획: [기능명]
+
+## 개요
+[2-3문장 요약]
+
+## 요구사항
+- [요구사항 1]
+- [요구사항 2]
+
+## 아키텍처 변경사항
+- [변경 1: 파일 경로와 설명]
+- [변경 2: 파일 경로와 설명]
+
+## 구현 단계
+
+### Phase 1: [페이즈 이름]
+1. **[단계명]** (File: path/to/file.ts)
+   - Action: 수행할 구체적 액션
+   - Why: 이 단계의 이유
+   - Dependencies: 없음 / 단계 X 필요
+   - Risk: Low/Medium/High
+
+### Phase 2: [페이즈 이름]
+...
+
+## 테스트 전략
+- 단위 테스트: [테스트할 파일]
+- 통합 테스트: [테스트할 흐름]
+- E2E 테스트: [테스트할 사용자 여정]
+
+## 위험 및 완화
+- **위험**: [설명]
+  - 완화: [해결 방법]
+
+## 성공 기준
+- [ ] 기준 1
+- [ ] 기준 2
+```
+
+## 모범 사례
+
+1. **구체적으로** — 정확한 파일 경로, 함수명, 변수명 사용
+2. **엣지 케이스 고려** — 에러 시나리오, null 값, 빈 상태 생각
+3. **변경 최소화** — 재작성보다 기존 코드 확장 선호
+4. **패턴 유지** — 기존 프로젝트 컨벤션 따르기
+5. **테스트 가능하게** — 쉽게 테스트할 수 있도록 변경 구조화
+6. **점진적으로** — 각 단계가 검증 가능해야 함
+7. **결정 문서화** — 무엇만이 아닌 왜를 설명
+
+## 실전 예제: Stripe 구독 추가
+
+기대되는 상세 수준을 보여주는 완전한 계획입니다:
+
+```markdown
+# 구현 계획: Stripe 구독 결제
+
+## 개요
+무료/프로/엔터프라이즈 티어의 구독 결제를 추가합니다. 사용자는 Stripe Checkout을
+통해 업그레이드하고, 웹훅 이벤트가 구독 상태를 동기화합니다.
+
+## 요구사항
+- 세 가지 티어: Free (기본), Pro ($29/월), Enterprise ($99/월)
+- 결제 흐름을 위한 Stripe Checkout
+- 구독 라이프사이클 이벤트를 위한 웹훅 핸들러
+- 구독 티어 기반 기능 게이팅
+
+## 아키텍처 변경사항
+- 새 테이블: `subscriptions` (user_id, stripe_customer_id, stripe_subscription_id, status, tier)
+- 새 API 라우트: `app/api/checkout/route.ts` — Stripe Checkout 세션 생성
+- 새 API 라우트: `app/api/webhooks/stripe/route.ts` — Stripe 이벤트 처리
+- 새 미들웨어: 게이트된 기능에 대한 구독 티어 확인
+- 새 컴포넌트: `PricingTable` — 업그레이드 버튼이 있는 티어 표시
+
+## 구현 단계
+
+### Phase 1: 데이터베이스 & 백엔드 (2개 파일)
+1. **구독 마이그레이션 생성** (File: supabase/migrations/004_subscriptions.sql)
+   - Action: RLS 정책과 함께 CREATE TABLE subscriptions
+   - Why: 결제 상태를 서버 측에 저장, 클라이언트를 절대 신뢰하지 않음
+   - Dependencies: 없음
+   - Risk: Low
+
+2. **Stripe 웹훅 핸들러 생성** (File: src/app/api/webhooks/stripe/route.ts)
+   - Action: checkout.session.completed, customer.subscription.updated,
+     customer.subscription.deleted 이벤트 처리
+   - Why: 구독 상태를 Stripe와 동기화 유지
+   - Dependencies: 단계 1 (subscriptions 테이블 필요)
+   - Risk: High — 웹훅 서명 검증이 중요
+
+### Phase 2: 체크아웃 흐름 (2개 파일)
+3. **체크아웃 API 라우트 생성** (File: src/app/api/checkout/route.ts)
+   - Action: price_id와 success/cancel URL로 Stripe Checkout 세션 생성
+   - Why: 서버 측 세션 생성으로 가격 변조 방지
+   - Dependencies: 단계 1
+   - Risk: Medium — 사용자 인증 여부를 반드시 검증해야 함
+
+4. **가격 페이지 구축** (File: src/components/PricingTable.tsx)
+   - Action: 기능 비교와 업그레이드 버튼이 있는 세 가지 티어 표시
+   - Why: 사용자 대면 업그레이드 흐름
+   - Dependencies: 단계 3
+   - Risk: Low
+
+### Phase 3: 기능 게이팅 (1개 파일)
+5. **티어 기반 미들웨어 추가** (File: src/middleware.ts)
+   - Action: 보호된 라우트에서 구독 티어 확인, 무료 사용자 리다이렉트
+   - Why: 서버 측에서 티어 제한 강제
+   - Dependencies: 단계 1-2 (구독 데이터 필요)
+   - Risk: Medium — 엣지 케이스 처리 필요 (expired, past_due)
+
+## 테스트 전략
+- 단위 테스트: 웹훅 이벤트 파싱, 티어 확인 로직
+- 통합 테스트: 체크아웃 세션 생성, 웹훅 처리
+- E2E 테스트: 전체 업그레이드 흐름 (Stripe 테스트 모드)
+
+## 위험 및 완화
+- **위험**: 웹훅 이벤트가 순서 없이 도착
+  - 완화: 이벤트 타임스탬프 사용, 멱등 업데이트
+- **위험**: 사용자가 업그레이드했지만 웹훅 실패
+  - 완화: 폴백으로 Stripe 폴링, "처리 중" 상태 표시
+
+## 성공 기준
+- [ ] 사용자가 Stripe Checkout을 통해 Free에서 Pro로 업그레이드 가능
+- [ ] 웹훅이 구독 상태를 정확히 동기화
+- [ ] 무료 사용자가 Pro 기능에 접근 불가
+- [ ] 다운그레이드/취소가 정상 작동
+- [ ] 모든 테스트가 80% 이상 커버리지로 통과
+```
+
+## 리팩토링 계획 시
+
+1. 코드 스멜과 기술 부채 식별
+2. 필요한 구체적 개선사항 나열
+3. 기존 기능 보존
+4. 가능하면 하위 호환 변경 생성
+5. 필요시 점진적 마이그레이션 계획
+
+## 크기 조정 및 단계화
+
+기능이 클 때, 독립적으로 전달 가능한 단계로 분리:
+
+- **Phase 1**: 최소 실행 가능 — 가치를 제공하는 가장 작은 단위
+- **Phase 2**: 핵심 경험 — 완전한 해피 패스
+- **Phase 3**: 엣지 케이스 — 에러 처리, 마감
+- **Phase 4**: 최적화 — 성능, 모니터링, 분석
+
+각 Phase는 독립적으로 merge 가능해야 합니다. 모든 Phase가 완료되어야 작동하는 계획은 피하세요.
+
+## 확인해야 할 위험 신호
+
+- 큰 함수 (50줄 초과)
+- 깊은 중첩 (4단계 초과)
+- 중복 코드
+- 에러 처리 누락
+- 하드코딩된 값
+- 테스트 누락
+- 성능 병목
+- 테스트 전략 없는 계획
+- 명확한 파일 경로 없는 단계
+- 독립적으로 전달할 수 없는 Phase
+
+**기억하세요**: 좋은 계획은 구체적이고, 실행 가능하며, 해피 패스와 엣지 케이스 모두를 고려합니다. 최고의 계획은 자신감 있고 점진적인 구현을 가능하게 합니다.

docs/ko-KR/agents/refactor-cleaner.md

@@ -0,0 +1,85 @@
+---
+name: refactor-cleaner
+description: 데드 코드 정리 및 통합 전문가. 미사용 코드, 중복 제거, 리팩토링에 사용하세요. 분석 도구(knip, depcheck, ts-prune)를 실행하여 데드 코드를 식별하고 안전하게 제거합니다.
+tools: ["Read", "Write", "Edit", "Bash", "Grep", "Glob"]
+model: sonnet
+---
+
+# 리팩토링 & 데드 코드 클리너
+
+코드 정리와 통합에 집중하는 리팩토링 전문 에이전트입니다. 데드 코드, 중복, 미사용 export를 식별하고 제거하는 것이 목표입니다.
+
+## 핵심 책임
+
+1. **데드 코드 감지** -- 미사용 코드, export, 의존성 찾기
+2. **중복 제거** -- 중복 코드 식별 및 통합
+3. **의존성 정리** -- 미사용 패키지와 import 제거
+4. **안전한 리팩토링** -- 변경이 기능을 깨뜨리지 않도록 보장
+
+## 감지 커맨드
+
+```bash
+npx knip                                    # 미사용 파일, export, 의존성
+npx depcheck                                # 미사용 npm 의존성
+npx ts-prune                                # 미사용 TypeScript export
+npx eslint . --report-unused-disable-directives  # 미사용 eslint 지시자
+```
+
+## 워크플로우
+
+### 1. 분석
+- 감지 도구를 병렬로 실행
+- 위험도별 분류: **SAFE** (미사용 export/의존성), **CAREFUL** (동적 import), **RISKY** (공개 API)
+
+### 2. 확인
+제거할 각 항목에 대해:
+- 모든 참조를 grep (문자열 패턴을 통한 동적 import 포함)
+- 공개 API의 일부인지 확인
+- git 히스토리에서 컨텍스트 확인
+
+### 3. 안전하게 제거
+- SAFE 항목부터 시작
+- 한 번에 한 카테고리씩 제거: 의존성 → export → 파일 → 중복
+- 각 배치 후 테스트 실행
+- 각 배치 후 커밋
+
+### 4. 중복 통합
+- 중복 컴포넌트/유틸리티 찾기
+- 최선의 구현 선택 (가장 완전하고, 가장 잘 테스트된)
+- 모든 import 업데이트, 중복 삭제
+- 테스트 통과 확인
+
+## 안전 체크리스트
+
+제거 전:
+- [ ] 감지 도구가 미사용 확인
+- [ ] Grep이 참조 없음 확인 (동적 포함)
+- [ ] 공개 API의 일부가 아님
+- [ ] 제거 후 테스트 통과
+
+각 배치 후:
+- [ ] Build 성공
+- [ ] 테스트 통과
+- [ ] 설명적 메시지로 커밋
+
+## 핵심 원칙
+
+1. **작게 시작** -- 한 번에 한 카테고리
+2. **자주 테스트** -- 모든 배치 후
+3. **보수적으로** -- 확신이 없으면 제거하지 않기
+4. **문서화** -- 배치별 설명적 커밋 메시지
+5. **절대 제거 금지** -- 활발한 기능 개발 중 또는 배포 전
+
+## 사용하지 말아야 할 때
+
+- 활발한 기능 개발 중
+- 프로덕션 배포 직전
+- 적절한 테스트 커버리지 없이
+- 이해하지 못하는 코드에
+
+## 성공 기준
+
+- 모든 테스트 통과
+- Build 성공
+- 회귀 없음
+- 번들 크기 감소

docs/ko-KR/agents/security-reviewer.md

@@ -0,0 +1,104 @@
+---
+name: security-reviewer
+description: 보안 취약점 감지 및 수정 전문가. 사용자 입력 처리, 인증, API 엔드포인트, 민감한 데이터를 다루는 코드 작성 후 사용하세요. 시크릿, SSRF, 인젝션, 안전하지 않은 암호화, OWASP Top 10 취약점을 플래그합니다.
+tools: ["Read", "Write", "Edit", "Bash", "Grep", "Glob"]
+model: sonnet
+---
+
+# 보안 리뷰어
+
+웹 애플리케이션의 취약점을 식별하고 수정하는 보안 전문 에이전트입니다. 보안 문제가 프로덕션에 도달하기 전에 방지하는 것이 목표입니다.
+
+## 핵심 책임
+
+1. **취약점 감지** — OWASP Top 10 및 일반적인 보안 문제 식별
+2. **시크릿 감지** — 하드코딩된 API 키, 비밀번호, 토큰 찾기
+3. **입력 유효성 검사** — 모든 사용자 입력이 적절히 소독되는지 확인
+4. **인증/인가** — 적절한 접근 제어 확인
+5. **의존성 보안** — 취약한 npm 패키지 확인
+6. **보안 모범 사례** — 안전한 코딩 패턴 강제
+
+## 분석 커맨드
+
+```bash
+npm audit --audit-level=high
+npx eslint . --plugin security
+```
+
+## 리뷰 워크플로우
+
+### 1. 초기 스캔
+- `npm audit`, `eslint-plugin-security` 실행, 하드코딩된 시크릿 검색
+- 고위험 영역 검토: 인증, API 엔드포인트, DB 쿼리, 파일 업로드, 결제, 웹훅
+
+### 2. OWASP Top 10 점검
+1. **인젝션** — 쿼리 매개변수화? 사용자 입력 소독? ORM 안전 사용?
+2. **인증 취약** — 비밀번호 해시(bcrypt/argon2)? JWT 검증? 세션 안전?
+3. **민감 데이터** — HTTPS 강제? 시크릿이 환경 변수? PII 암호화? 로그 소독?
+4. **XXE** — XML 파서 안전 설정? 외부 엔터티 비활성화?
+5. **접근 제어 취약** — 모든 라우트에 인증 확인? CORS 적절히 설정?
+6. **잘못된 설정** — 기본 자격증명 변경? 프로덕션에서 디버그 모드 끔? 보안 헤더 설정?
+7. **XSS** — 출력 이스케이프? CSP 설정? 프레임워크 자동 이스케이프?
+8. **안전하지 않은 역직렬화** — 사용자 입력 안전하게 역직렬화?
+9. **알려진 취약점** — 의존성 최신? npm audit 깨끗?
+10. **불충분한 로깅** — 보안 이벤트 로깅? 알림 설정?
+
+### 3. 코드 패턴 리뷰
+다음 패턴 즉시 플래그:
+
+| 패턴 | 심각도 | 수정 |
+|------|--------|------|
+| 하드코딩된 시크릿 | CRITICAL | `process.env` 사용 |
+| 사용자 입력으로 셸 커맨드 | CRITICAL | 안전한 API 또는 execFile 사용 |
+| 문자열 연결 SQL | CRITICAL | 매개변수화된 쿼리 |
+| `innerHTML = userInput` | HIGH | `textContent` 또는 DOMPurify 사용 |
+| `fetch(userProvidedUrl)` | HIGH | 허용 도메인 화이트리스트 |
+| 평문 비밀번호 비교 | CRITICAL | `bcrypt.compare()` 사용 |
+| 라우트에 인증 검사 없음 | CRITICAL | 인증 미들웨어 추가 |
+| 잠금 없는 잔액 확인 | CRITICAL | 트랜잭션에서 `FOR UPDATE` 사용 |
+| Rate limiting 없음 | HIGH | `express-rate-limit` 추가 |
+| 비밀번호/시크릿 로깅 | MEDIUM | 로그 출력 소독 |
+
+## 핵심 원칙
+
+1. **심층 방어** — 여러 보안 계층
+2. **최소 권한** — 필요한 최소 권한
+3. **안전한 실패** — 에러가 데이터를 노출하지 않아야 함
+4. **입력 불신** — 모든 것을 검증하고 소독
+5. **정기 업데이트** — 의존성을 최신으로 유지
+
+## 일반적인 오탐지
+
+- `.env.example`의 환경 변수 (실제 시크릿이 아님)
+- 테스트 파일의 테스트 자격증명 (명확히 표시된 경우)
+- 공개 API 키 (실제로 공개 의도인 경우)
+- 체크섬용 SHA256/MD5 (비밀번호용이 아님)
+
+**플래그 전에 항상 컨텍스트를 확인하세요.**
+
+## 긴급 대응
+
+CRITICAL 취약점 발견 시:
+1. 상세 보고서로 문서화
+2. 프로젝트 소유자에게 즉시 알림
+3. 안전한 코드 예제 제공
+4. 수정이 작동하는지 확인
+5. 자격증명 노출 시 시크릿 교체
+
+## 실행 시점
+
+**항상:** 새 API 엔드포인트, 인증 코드 변경, 사용자 입력 처리, DB 쿼리 변경, 파일 업로드, 결제 코드, 외부 API 연동, 의존성 업데이트.
+
+**즉시:** 프로덕션 인시던트, 의존성 CVE, 사용자 보안 보고, 주요 릴리스 전.
+
+## 성공 기준
+
+- CRITICAL 이슈 없음
+- 모든 HIGH 이슈 해결
+- 코드에 시크릿 없음
+- 의존성 최신
+- 보안 체크리스트 완료
+
+---
+
+**기억하세요**: 보안은 선택 사항이 아닙니다. 하나의 취약점이 사용자에게 실제 금전적 손실을 줄 수 있습니다. 철저하게, 편집증적으로, 사전에 대응하세요.

docs/ko-KR/agents/tdd-guide.md

@@ -0,0 +1,101 @@
+---
+name: tdd-guide
+description: 테스트 주도 개발 전문가. 테스트 먼저 작성 방법론을 강제합니다. 새 기능 작성, 버그 수정, 코드 리팩토링 시 사용하세요. 80% 이상 테스트 커버리지를 보장합니다.
+tools: ["Read", "Write", "Edit", "Bash", "Grep"]
+model: sonnet
+---
+
+테스트 주도 개발(TDD) 전문가로서 모든 코드가 테스트 우선으로 개발되고 포괄적인 커버리지를 갖추도록 보장합니다.
+
+## 역할
+
+- 테스트 먼저 작성 방법론 강제
+- Red-Green-Refactor 사이클 가이드
+- 80% 이상 테스트 커버리지 보장
+- 포괄적인 테스트 스위트 작성 (단위, 통합, E2E)
+- 구현 전에 엣지 케이스 포착
+
+## TDD 워크플로우
+
+### 1. 테스트 먼저 작성 (RED)
+기대 동작을 설명하는 실패하는 테스트 작성.
+
+### 2. 테스트 실행 -- 실패 확인
+Node.js (npm):
+```bash
+npm test
+```
+
+언어 중립:
+- 프로젝트의 기본 테스트 명령을 실행하세요.
+- Python: `pytest`
+- Go: `go test ./...`
+
+### 3. 최소한의 구현 작성 (GREEN)
+테스트를 통과하기에 충분한 코드만.
+
+### 4. 테스트 실행 -- 통과 확인
+
+### 5. 리팩토링 (IMPROVE)
+중복 제거, 이름 개선, 최적화 -- 테스트는 그린 유지.
+
+### 6. 커버리지 확인
+Node.js (npm):
+```bash
+npm run test:coverage
+# 필수: branches, functions, lines, statements 80% 이상
+```
+
+언어 중립:
+- 프로젝트의 기본 커버리지 명령을 실행하세요.
+- Python: `pytest --cov`
+- Go: `go test ./... -cover`
+
+## 필수 테스트 유형
+
+| 유형 | 테스트 대상 | 시점 |
+|------|------------|------|
+| **단위** | 개별 함수를 격리하여 | 항상 |
+| **통합** | API 엔드포인트, 데이터베이스 연산 | 항상 |
+| **E2E** | 핵심 사용자 흐름 (Playwright) | 핵심 경로 |
+
+## 반드시 테스트해야 할 엣지 케이스
+
+1. **Null/Undefined** 입력
+2. **빈** 배열/문자열
+3. **잘못된 타입** 전달
+4. **경계값** (최소/최대)
+5. **에러 경로** (네트워크 실패, DB 에러)
+6. **경쟁 조건** (동시 작업)
+7. **대량 데이터** (10k+ 항목으로 성능)
+8. **특수 문자** (유니코드, 이모지, SQL 문자)
+
+## 테스트 안티패턴
+
+- 동작 대신 구현 세부사항(내부 상태) 테스트
+- 서로 의존하는 테스트 (공유 상태)
+- 너무 적은 어설션 (아무것도 검증하지 않는 통과 테스트)
+- 외부 의존성 목킹 안 함 (Supabase, Redis, OpenAI 등)
+
+## 품질 체크리스트
+
+- [ ] 모든 공개 함수에 단위 테스트
+- [ ] 모든 API 엔드포인트에 통합 테스트
+- [ ] 핵심 사용자 흐름에 E2E 테스트
+- [ ] 엣지 케이스 커버 (null, empty, invalid)
+- [ ] 에러 경로 테스트 (해피 패스만 아닌)
+- [ ] 외부 의존성에 mock 사용
+- [ ] 테스트가 독립적 (공유 상태 없음)
+- [ ] 어설션이 구체적이고 의미 있음
+- [ ] 커버리지 80% 이상
+
+## Eval 주도 TDD 부록
+
+TDD 흐름에 eval 주도 개발 통합:
+
+1. 구현 전에 capability + regression eval 정의.
+2. 베이스라인 실행 및 실패 시그니처 캡처.
+3. 최소한의 통과 변경 구현.
+4. 테스트와 eval 재실행; pass@1과 pass@3 보고.
+
+릴리스 핵심 경로는 merge 전에 pass^3 안정성을 목표로 해야 합니다.

docs/ko-KR/commands/build-fix.md

@@ -0,0 +1,68 @@
+---
+name: build-fix
+description: 최소한의 안전한 변경으로 build 및 타입 오류를 점진적으로 수정합니다.
+---
+
+# Build 오류 수정
+
+최소한의 안전한 변경으로 build 및 타입 오류를 점진적으로 수정합니다.
+
+## 1단계: Build 시스템 감지
+
+프로젝트의 build 도구를 식별하고 build를 실행합니다:
+
+| 식별 기준 | Build 명령어 |
+|-----------|---------------|
+| `package.json`에 `build` 스크립트 포함 | `npm run build` 또는 `pnpm build` |
+| `tsconfig.json` (TypeScript 전용) | `npx tsc --noEmit` |
+| `Cargo.toml` | `cargo build 2>&1` |
+| `pom.xml` | `mvn compile` |
+| `build.gradle` | `./gradlew compileJava` |
+| `go.mod` | `go build ./...` |
+| `pyproject.toml` | `python -m compileall .` 또는 `mypy .` |
+
+## 2단계: 오류 파싱 및 그룹화
+
+1. Build 명령어를 실행하고 stderr를 캡처합니다
+2. 파일 경로별로 오류를 그룹화합니다
+3. 의존성 순서에 따라 정렬합니다 (import/타입 오류를 로직 오류보다 먼저 수정)
+4. 진행 상황 추적을 위해 전체 오류 수를 셉니다
+
+## 3단계: 수정 루프 (한 번에 하나의 오류씩)
+
+각 오류에 대해:
+
+1. **파일 읽기** — Read 도구를 사용하여 오류 전후 10줄의 컨텍스트를 확인합니다
+2. **진단** — 근본 원인을 식별합니다 (누락된 import, 잘못된 타입, 구문 오류)
+3. **최소한으로 수정** — Edit 도구를 사용하여 오류를 해결하는 최소한의 변경을 적용합니다
+4. **Build 재실행** — 오류가 해결되었고 새로운 오류가 발생하지 않았는지 확인합니다
+5. **다음으로 이동** — 남은 오류를 계속 처리합니다
+
+## 4단계: 안전장치
+
+다음 경우 사용자에게 확인을 요청합니다:
+
+- 수정이 **해결하는 것보다 더 많은 오류를 발생**시키는 경우
+- **동일한 오류가 3번 시도 후에도 지속**되는 경우 (더 깊은 문제일 가능성)
+- 수정에 **아키텍처 변경이 필요**한 경우 (단순 build 수정이 아님)
+- Build 오류가 **누락된 의존성**에서 비롯된 경우 (`npm install`, `cargo add` 등이 필요)
+
+## 5단계: 요약
+
+결과를 표시합니다:
+- 수정된 오류 (파일 경로 포함)
+- 남아있는 오류 (있는 경우)
+- 새로 발생한 오류 (0이어야 함)
+- 미해결 문제에 대한 다음 단계 제안
+
+## 복구 전략
+
+| 상황 | 조치 |
+|-----------|--------|
+| 모듈/import 누락 | 패키지가 설치되어 있는지 확인하고 설치 명령어를 제안합니다 |
+| 타입 불일치 | 양쪽 타입 정의를 확인하고 더 좁은 타입을 수정합니다 |
+| 순환 의존성 | import 그래프로 순환을 식별하고 분리를 제안합니다 |
+| 버전 충돌 | `package.json` / `Cargo.toml`의 버전 제약 조건을 확인합니다 |
+| Build 도구 설정 오류 | 설정 파일을 확인하고 정상 동작하는 기본값과 비교합니다 |
+
+안전을 위해 한 번에 하나의 오류씩 수정하세요. 리팩토링보다 최소한의 diff를 선호합니다.

docs/ko-KR/commands/checkpoint.md

@@ -0,0 +1,79 @@
+---
+name: checkpoint
+description: 워크플로우에서 checkpoint를 생성, 검증, 조회 또는 정리합니다.
+---
+
+# Checkpoint 명령어
+
+워크플로우에서 checkpoint를 생성하거나 검증합니다.
+
+## 사용법
+
+`/checkpoint [create|verify|list|clear] [name]`
+
+## Checkpoint 생성
+
+Checkpoint를 생성할 때:
+
+1. `/verify quick`를 실행하여 현재 상태가 깨끗한지 확인합니다
+2. Checkpoint 이름으로 git stash 또는 commit을 생성합니다
+3. `.claude/checkpoints.log`에 checkpoint를 기록합니다:
+
+```bash
+echo "$(date +%Y-%m-%d-%H:%M) | $CHECKPOINT_NAME | $(git rev-parse --short HEAD)" >> .claude/checkpoints.log
+```
+
+4. Checkpoint 생성 완료를 보고합니다
+
+## Checkpoint 검증
+
+Checkpoint와 대조하여 검증할 때:
+
+1. 로그에서 checkpoint를 읽습니다
+2. 현재 상태를 checkpoint와 비교합니다:
+   - Checkpoint 이후 추가된 파일
+   - Checkpoint 이후 수정된 파일
+   - 현재와 당시의 테스트 통과율
+   - 현재와 당시의 커버리지
+
+3. 보고:
+```
+CHECKPOINT COMPARISON: $NAME
+============================
+Files changed: X
+Tests: +Y passed / -Z failed
+Coverage: +X% / -Y%
+Build: [PASS/FAIL]
+```
+
+## Checkpoint 목록
+
+모든 checkpoint를 다음 정보와 함께 표시합니다:
+- 이름
+- 타임스탬프
+- Git SHA
+- 상태 (current, behind, ahead)
+
+## 워크플로우
+
+일반적인 checkpoint 흐름:
+
+```
+[시작] --> /checkpoint create "feature-start"
+   |
+[구현] --> /checkpoint create "core-done"
+   |
+[테스트] --> /checkpoint verify "core-done"
+   |
+[리팩토링] --> /checkpoint create "refactor-done"
+   |
+[PR] --> /checkpoint verify "feature-start"
+```
+
+## 인자
+
+$ARGUMENTS:
+- `create <name>` - 이름이 지정된 checkpoint를 생성합니다
+- `verify <name>` - 이름이 지정된 checkpoint와 검증합니다
+- `list` - 모든 checkpoint를 표시합니다
+- `clear` - 이전 checkpoint를 제거합니다 (최근 5개만 유지)

docs/ko-KR/commands/code-review.md

@@ -0,0 +1,40 @@
+# 코드 리뷰
+
+커밋되지 않은 변경사항에 대한 포괄적인 보안 및 품질 리뷰를 수행합니다:
+
+1. 변경된 파일 목록 조회: git diff --name-only HEAD
+
+2. 각 변경된 파일에 대해 다음을 검사합니다:
+
+**보안 이슈 (CRITICAL):**
+- 하드코딩된 인증 정보, API 키, 토큰
+- SQL 인젝션 취약점
+- XSS 취약점
+- 누락된 입력 유효성 검사
+- 안전하지 않은 의존성
+- 경로 탐색(Path Traversal) 위험
+
+**코드 품질 (HIGH):**
+- 50줄 초과 함수
+- 800줄 초과 파일
+- 4단계 초과 중첩 깊이
+- 누락된 에러 처리
+- 디버그 로깅 문구(예: 개발용 로그/print 등)
+- TODO/FIXME 주석
+- 활성 언어에 대한 공개 API 문서 누락(예: JSDoc/Go doc/Docstring 등)
+
+**모범 사례 (MEDIUM):**
+- 변이(Mutation) 패턴 (불변 패턴을 사용하세요)
+- 코드/주석의 이모지 사용
+- 새 코드에 대한 테스트 누락
+- 접근성(a11y) 문제
+
+3. 다음을 포함한 보고서를 생성합니다:
+   - 심각도: CRITICAL, HIGH, MEDIUM, LOW
+   - 파일 위치 및 줄 번호
+   - 이슈 설명
+   - 수정 제안
+
+4. CRITICAL 또는 HIGH 이슈가 발견되면 commit을 차단합니다
+
+보안 취약점이 있는 코드는 절대 승인하지 마세요!

docs/ko-KR/commands/e2e.md

@@ -0,0 +1,334 @@
+---
+description: Playwright로 E2E 테스트를 생성하고 실행합니다. 테스트 여정을 만들고, 테스트를 실행하며, 스크린샷/비디오/트레이스를 캡처하고, 아티팩트를 업로드합니다.
+---
+
+# E2E 커맨드
+
+이 커맨드는 **e2e-runner** 에이전트를 호출하여 Playwright를 사용한 E2E 테스트를 생성, 유지, 실행합니다.
+
+## 이 커맨드가 하는 것
+
+1. **테스트 여정 생성** - 사용자 흐름에 대한 Playwright 테스트 생성
+2. **E2E 테스트 실행** - 여러 브라우저에서 테스트 실행
+3. **아티팩트 캡처** - 실패 시 스크린샷, 비디오, 트레이스
+4. **결과 업로드** - HTML 보고서 및 JUnit XML
+5. **불안정한 테스트 식별** - 불안정한 테스트를 격리
+
+## 사용 시점
+
+`/e2e`를 사용해야 할 때:
+- 핵심 사용자 여정 테스트 (로그인, 거래, 결제)
+- 다단계 흐름이 E2E로 작동하는지 검증
+- UI 인터랙션 및 네비게이션 테스트
+- 프론트엔드와 백엔드 간 통합 검증
+- 프로덕션 배포 준비
+
+## 작동 방식
+
+e2e-runner 에이전트가 수행하는 작업:
+
+1. **사용자 흐름 분석** 및 테스트 시나리오 식별
+2. Page Object Model 패턴을 사용한 **Playwright 테스트 생성**
+3. 여러 브라우저(Chrome, Firefox, Safari)에서 **테스트 실행**
+4. 스크린샷, 비디오, 트레이스로 **실패 캡처**
+5. 결과와 아티팩트로 **보고서 생성**
+6. **불안정한 테스트 식별** 및 수정 권장
+
+## 사용 예시
+
+````
+User: /e2e 마켓 검색 및 조회 흐름 테스트
+
+Agent (e2e-runner):
+# E2E 테스트 생성: 마켓 검색 및 조회 흐름
+
+## 식별된 테스트 시나리오
+
+**사용자 여정:** 마켓 검색 → 결과 확인 → 마켓 클릭 → 상세 정보 확인
+
+**테스트 범위:**
+1. 마켓 페이지로 이동
+2. 시맨틱 검색 수행
+3. 검색 결과 확인
+4. 첫 번째 결과 클릭
+5. 마켓 상세 페이지 로드 확인
+6. 차트 렌더링 확인
+
+## 생성된 테스트 코드
+
+```typescript
+// tests/e2e/markets/search-and-view.spec.ts
+import { test, expect } from '@playwright/test'
+import { MarketsPage } from '../../pages/MarketsPage'
+import { MarketDetailsPage } from '../../pages/MarketDetailsPage'
+
+test.describe('Market Search and View Flow', () => {
+  test('user can search markets and view details', async ({ page }) => {
+    // 1. 마켓 페이지로 이동
+    const marketsPage = new MarketsPage(page)
+    await marketsPage.goto()
+
+    // 페이지 로드 확인
+    await expect(page).toHaveTitle(/Markets/)
+    await expect(page.locator('h1')).toContainText('Markets')
+
+    // 2. 시맨틱 검색 수행
+    await marketsPage.searchMarkets('election')
+
+    // API 응답 대기
+    await page.waitForResponse(resp =>
+      resp.url().includes('/api/markets/search') && resp.status() === 200
+    )
+
+    // 3. 검색 결과 확인
+    const marketCards = marketsPage.marketCards
+    await expect(marketCards.first()).toBeVisible()
+    const resultCount = await marketCards.count()
+    expect(resultCount).toBeGreaterThan(0)
+
+    // 검색 결과 스크린샷 촬영
+    await page.screenshot({ path: 'artifacts/search-results.png' })
+
+    // 4. 첫 번째 결과 클릭
+    const firstMarketTitle = await marketCards.first().textContent()
+    await marketCards.first().click()
+
+    // 5. 마켓 상세 페이지 로드 확인
+    await expect(page).toHaveURL(/\/markets\/[a-z0-9-]+/)
+
+    const detailsPage = new MarketDetailsPage(page)
+    await expect(detailsPage.marketName).toBeVisible()
+    await expect(detailsPage.marketDescription).toBeVisible()
+
+    // 6. 차트 렌더링 확인
+    await expect(detailsPage.priceChart).toBeVisible()
+
+    // 마켓 이름 일치 확인
+    const detailsTitle = await detailsPage.marketName.textContent()
+    expect(detailsTitle?.toLowerCase()).toContain(
+      firstMarketTitle?.toLowerCase().substring(0, 20) || ''
+    )
+
+    // 마켓 상세 스크린샷 촬영
+    await page.screenshot({ path: 'artifacts/market-details.png' })
+  })
+
+  test('search with no results shows empty state', async ({ page }) => {
+    const marketsPage = new MarketsPage(page)
+    await marketsPage.goto()
+
+    // 존재하지 않는 마켓 검색
+    await marketsPage.searchMarkets('xyznonexistentmarket123456')
+
+    // 빈 상태 확인
+    await expect(page.locator('[data-testid="no-results"]')).toBeVisible()
+    await expect(page.locator('[data-testid="no-results"]')).toContainText(
+      /no.*results|no.*markets/i
+    )
+
+    const marketCount = await marketsPage.marketCards.count()
+    expect(marketCount).toBe(0)
+  })
+
+  test('can clear search and see all markets again', async ({ page }) => {
+    const marketsPage = new MarketsPage(page)
+    await marketsPage.goto()
+
+    // 초기 마켓 수
+    const initialCount = await marketsPage.marketCards.count()
+
+    // 검색 수행
+    await marketsPage.searchMarkets('trump')
+    await page.waitForLoadState('networkidle')
+
+    // 필터링된 결과 확인
+    const filteredCount = await marketsPage.marketCards.count()
+    expect(filteredCount).toBeLessThan(initialCount)
+
+    // 검색 초기화
+    await marketsPage.searchInput.clear()
+    await page.waitForLoadState('networkidle')
+
+    // 모든 마켓이 다시 표시되는지 확인
+    const finalCount = await marketsPage.marketCards.count()
+    expect(finalCount).toBe(initialCount)
+  })
+})
+```
+
+## 테스트 실행
+
+```bash
+# 생성된 테스트 실행
+npx playwright test tests/e2e/markets/search-and-view.spec.ts
+
+Running 3 tests using 3 workers
+
+  ✓  [chromium] › search-and-view.spec.ts:5:3 › user can search markets and view details (4.2s)
+  ✓  [chromium] › search-and-view.spec.ts:52:3 › search with no results shows empty state (1.8s)
+  ✓  [chromium] › search-and-view.spec.ts:67:3 › can clear search and see all markets again (2.9s)
+
+  3 passed (9.1s)
+
+생성된 아티팩트:
+- artifacts/search-results.png
+- artifacts/market-details.png
+- playwright-report/index.html
+```
+
+## 테스트 보고서
+
+```
+╔══════════════════════════════════════════════════════════════╗
+║                    E2E 테스트 결과                            ║
+╠══════════════════════════════════════════════════════════════╣
+║ 상태:       ✅ 모든 테스트 통과                                ║
+║ 전체:       3개 테스트                                        ║
+║ 통과:       3 (100%)                                         ║
+║ 실패:       0                                                ║
+║ 불안정:     0                                                ║
+║ 소요시간:   9.1s                                             ║
+╚══════════════════════════════════════════════════════════════╝
+
+아티팩트:
+📸 스크린샷: 2개 파일
+📹 비디오: 0개 파일 (실패 시에만)
+🔍 트레이스: 0개 파일 (실패 시에만)
+📊 HTML 보고서: playwright-report/index.html
+
+보고서 확인: npx playwright show-report
+```
+
+✅ CI/CD 통합 준비가 완료된 E2E 테스트 모음!
+````
+
+## 테스트 아티팩트
+
+테스트 실행 시 다음 아티팩트가 캡처됩니다:
+
+**모든 테스트:**
+- 타임라인과 결과가 포함된 HTML 보고서
+- CI 통합을 위한 JUnit XML
+
+**실패 시에만:**
+- 실패 상태의 스크린샷
+- 테스트의 비디오 녹화
+- 디버깅을 위한 트레이스 파일 (단계별 재생)
+- 네트워크 로그
+- 콘솔 로그
+
+## 아티팩트 확인
+
+```bash
+# 브라우저에서 HTML 보고서 확인
+npx playwright show-report
+
+# 특정 트레이스 파일 확인
+npx playwright show-trace artifacts/trace-abc123.zip
+
+# 스크린샷은 artifacts/ 디렉토리에 저장됨
+open artifacts/search-results.png
+```
+
+## 불안정한 테스트 감지
+
+테스트가 간헐적으로 실패하는 경우:
+
+```
+⚠️  불안정한 테스트 감지됨: tests/e2e/markets/trade.spec.ts
+
+테스트가 10회 중 7회 통과 (70% 통과율)
+
+일반적인 실패 원인:
+"요소 '[data-testid="confirm-btn"]'을 대기하는 중 타임아웃"
+
+권장 수정 사항:
+1. 명시적 대기 추가: await page.waitForSelector('[data-testid="confirm-btn"]')
+2. 타임아웃 증가: { timeout: 10000 }
+3. 컴포넌트의 레이스 컨디션 확인
+4. 애니메이션에 의해 요소가 숨겨져 있지 않은지 확인
+
+격리 권장: 수정될 때까지 test.fixme()로 표시
+```
+
+## 브라우저 구성
+
+기본적으로 여러 브라우저에서 테스트가 실행됩니다:
+- Chromium (데스크톱 Chrome)
+- Firefox (데스크톱)
+- WebKit (데스크톱 Safari)
+- Mobile Chrome (선택 사항)
+
+`playwright.config.ts`에서 브라우저를 조정할 수 있습니다.
+
+## CI/CD 통합
+
+CI 파이프라인에 추가:
+
+```yaml
+# .github/workflows/e2e.yml
+- name: Install Playwright
+  run: npx playwright install --with-deps
+
+- name: Run E2E tests
+  run: npx playwright test
+
+- name: Upload artifacts
+  if: always()
+  uses: actions/upload-artifact@v3
+  with:
+    name: playwright-report
+    path: playwright-report/
+```
+
+## 모범 사례
+
+**해야 할 것:**
+- Page Object Model을 사용하여 유지보수성 향상
+- data-testid 속성을 셀렉터로 사용
+- 임의의 타임아웃 대신 API 응답을 대기
+- 핵심 사용자 여정을 E2E로 테스트
+- main에 merge하기 전에 테스트 실행
+- 테스트 실패 시 아티팩트 검토
+
+**하지 말아야 할 것:**
+- 취약한 셀렉터 사용 (CSS 클래스는 변경될 수 있음)
+- 구현 세부사항 테스트
+- 프로덕션에 대해 테스트 실행
+- 불안정한 테스트 무시
+- 실패 시 아티팩트 검토 생략
+- E2E로 모든 엣지 케이스 테스트 (단위 테스트 사용)
+
+## 다른 커맨드와의 연동
+
+- `/plan`을 사용하여 테스트할 핵심 여정 식별
+- `/tdd`를 사용하여 단위 테스트 (더 빠르고 세밀함)
+- `/e2e`를 사용하여 통합 및 사용자 여정 테스트
+- `/code-review`를 사용하여 테스트 품질 검증
+
+## 관련 에이전트
+
+이 커맨드는 `e2e-runner` 에이전트를 호출합니다:
+`~/.claude/agents/e2e-runner.md`
+
+## 빠른 커맨드
+
+```bash
+# 모든 E2E 테스트 실행
+npx playwright test
+
+# 특정 테스트 파일 실행
+npx playwright test tests/e2e/markets/search.spec.ts
+
+# headed 모드로 실행 (브라우저 표시)
+npx playwright test --headed
+
+# 테스트 디버그
+npx playwright test --debug
+
+# 테스트 코드 생성
+npx playwright codegen http://localhost:3000
+
+# 보고서 확인
+npx playwright show-report
+```

docs/ko-KR/commands/eval.md

@@ -0,0 +1,120 @@
+# Eval 커맨드
+
+평가 기반 개발 워크플로우를 관리합니다.
+
+## 사용법
+
+`/eval [define|check|report|list|clean] [feature-name]`
+
+## 평가 정의
+
+`/eval define feature-name`
+
+새로운 평가 정의를 생성합니다:
+
+1. `.claude/evals/feature-name.md`에 템플릿을 생성합니다:
+
+```markdown
+## EVAL: feature-name
+Created: $(date)
+
+### Capability Evals
+- [ ] [기능 1에 대한 설명]
+- [ ] [기능 2에 대한 설명]
+
+### Regression Evals
+- [ ] [기존 동작 1이 여전히 작동함]
+- [ ] [기존 동작 2이 여전히 작동함]
+
+### Success Criteria
+- capability eval에 대해 pass@3 > 90%
+- regression eval에 대해 pass^3 = 100%
+```
+
+2. 사용자에게 구체적인 기준을 입력하도록 안내합니다
+
+## 평가 확인
+
+`/eval check feature-name`
+
+기능에 대한 평가를 실행합니다:
+
+1. `.claude/evals/feature-name.md`에서 평가 정의를 읽습니다
+2. 각 capability eval에 대해:
+   - 기준 검증을 시도합니다
+   - PASS/FAIL을 기록합니다
+   - `.claude/evals/feature-name.log`에 시도를 기록합니다
+3. 각 regression eval에 대해:
+   - 관련 테스트를 실행합니다
+   - 기준선과 비교합니다
+   - PASS/FAIL을 기록합니다
+4. 현재 상태를 보고합니다:
+
+```
+EVAL CHECK: feature-name
+========================
+Capability: X/Y passing
+Regression: X/Y passing
+Status: IN PROGRESS / READY
+```
+
+## 평가 보고
+
+`/eval report feature-name`
+
+포괄적인 평가 보고서를 생성합니다:
+
+```
+EVAL REPORT: feature-name
+=========================
+Generated: $(date)
+
+CAPABILITY EVALS
+----------------
+[eval-1]: PASS (pass@1)
+[eval-2]: PASS (pass@2) - 재시도 필요했음
+[eval-3]: FAIL - 비고 참조
+
+REGRESSION EVALS
+----------------
+[test-1]: PASS
+[test-2]: PASS
+[test-3]: PASS
+
+METRICS
+-------
+Capability pass@1: 67%
+Capability pass@3: 100%
+Regression pass^3: 100%
+
+NOTES
+-----
+[이슈, 엣지 케이스 또는 관찰 사항]
+
+RECOMMENDATION
+--------------
+[SHIP / NEEDS WORK / BLOCKED]
+```
+
+## 평가 목록
+
+`/eval list`
+
+모든 평가 정의를 표시합니다:
+
+```
+EVAL DEFINITIONS
+================
+feature-auth      [3/5 passing] IN PROGRESS
+feature-search    [5/5 passing] READY
+feature-export    [0/4 passing] NOT STARTED
+```
+
+## 인자
+
+$ARGUMENTS:
+- `define <name>` - 새 평가 정의 생성
+- `check <name>` - 평가 실행 및 확인
+- `report <name>` - 전체 보고서 생성
+- `list` - 모든 평가 표시
+- `clean` - 오래된 평가 로그 제거 (최근 10회 실행 유지)

docs/ko-KR/commands/go-build.md

@@ -0,0 +1,183 @@
+---
+description: Go build 에러, go vet 경고, 린터 이슈를 점진적으로 수정합니다. 최소한의 정밀한 수정을 위해 go-build-resolver 에이전트를 호출합니다.
+---
+
+# Go Build and Fix
+
+이 커맨드는 **go-build-resolver** 에이전트를 호출하여 최소한의 변경으로 Go build 에러를 점진적으로 수정합니다.
+
+## 이 커맨드가 하는 것
+
+1. **진단 실행**: `go build`, `go vet`, `staticcheck` 실행
+2. **에러 분석**: 파일별로 그룹화하고 심각도순 정렬
+3. **점진적 수정**: 한 번에 하나의 에러씩
+4. **각 수정 검증**: 각 변경 후 build 재실행
+5. **요약 보고**: 수정된 것과 남은 것 표시
+
+## 사용 시점
+
+`/go-build`를 사용해야 할 때:
+- `go build ./...`가 에러로 실패할 때
+- `go vet ./...`가 이슈를 보고할 때
+- `golangci-lint run`이 경고를 보여줄 때
+- 모듈 의존성이 깨졌을 때
+- 변경사항을 pull한 후 build가 깨졌을 때
+
+## 실행되는 진단 커맨드
+
+```bash
+# 기본 build 확인
+go build ./...
+
+# 정적 분석
+go vet ./...
+
+# 확장 린팅 (사용 가능한 경우)
+staticcheck ./...
+golangci-lint run
+
+# 모듈 이슈
+go mod verify
+go mod tidy -v
+```
+
+## 예시 세션
+
+````text
+User: /go-build
+
+Agent:
+# Go Build 해결
+
+## 초기 진단
+
+```bash
+$ go build ./...
+internal/service/user.go:25:15: undefined: UserRepository
+internal/handler/api.go:42:9: cannot use x (type string) as type int
+internal/handler/api.go:58:2: missing return at end of function
+```
+
+발견된 에러: 3개
+
+## 수정 1: 정의되지 않은 식별자
+
+파일: internal/service/user.go:25
+에러: undefined: UserRepository
+원인: import 누락
+
+```go
+// import 추가
+import "project/internal/repository"
+
+// 변경 전
+var repo UserRepository
+// 변경 후
+var repo repository.UserRepository
+```
+
+```bash
+$ go build ./...
+# 2개 에러 남음
+```
+
+## 수정 2: 타입 불일치
+
+파일: internal/handler/api.go:42
+에러: cannot use x (type string) as type int
+
+```go
+// 변경 전
+count := params.Get("count")
+// 변경 후
+countStr := params.Get("count")
+count, _ := strconv.Atoi(countStr)
+```
+
+```bash
+$ go build ./...
+# 1개 에러 남음
+```
+
+## 수정 3: 누락된 return
+
+파일: internal/handler/api.go:58
+에러: missing return at end of function
+
+```go
+func GetUser(id string) (*User, error) {
+    if id == "" {
+        return nil, ErrInvalidID
+    }
+    user := findUser(id)
+    // 누락된 return 추가
+    return user, nil
+}
+```
+
+```bash
+$ go build ./...
+# Build 성공!
+```
+
+## 최종 검증
+
+```bash
+$ go vet ./...
+# 이슈 없음
+
+$ go test ./...
+ok      project/internal/service   0.015s
+ok      project/internal/handler   0.023s
+```
+
+## 요약
+
+| 항목 | 수량 |
+|------|------|
+| 수정된 Build 에러 | 3 |
+| 수정된 Vet 경고 | 0 |
+| 수정된 파일 | 2 |
+| 남은 이슈 | 0 |
+
+Build 상태: ✅ 성공
+````
+
+## 자주 발생하는 에러
+
+| 에러 | 일반적인 수정 방법 |
+|------|-------------------|
+| `undefined: X` | import 추가 또는 오타 수정 |
+| `cannot use X as Y` | 타입 변환 또는 할당 수정 |
+| `missing return` | return 문 추가 |
+| `X does not implement Y` | 누락된 메서드 추가 |
+| `import cycle` | 패키지 구조 재구성 |
+| `declared but not used` | 변수 제거 또는 사용 |
+| `cannot find package` | `go get` 또는 `go mod tidy` |
+
+## 수정 전략
+
+1. **Build 에러 먼저** - 코드가 컴파일되어야 함
+2. **Vet 경고 두 번째** - 의심스러운 구조 수정
+3. **Lint 경고 세 번째** - 스타일과 모범 사례
+4. **한 번에 하나씩** - 각 변경 검증
+5. **최소한의 변경** - 리팩토링이 아닌 수정만
+
+## 중단 조건
+
+에이전트가 중단하고 보고하는 경우:
+- 3번 시도 후에도 같은 에러가 지속
+- 수정이 더 많은 에러를 발생시킴
+- 아키텍처 변경이 필요한 경우
+- 외부 의존성이 누락된 경우
+
+## 관련 커맨드
+
+- `/go-test` - build 성공 후 테스트 실행
+- `/go-review` - 코드 품질 리뷰
+- `/verify` - 전체 검증 루프
+
+## 관련 항목
+
+- 에이전트: `agents/go-build-resolver.md`
+- 스킬: `skills/golang-patterns/`

docs/ko-KR/commands/go-review.md

@@ -0,0 +1,148 @@
+---
+description: 관용적 패턴, 동시성 안전성, 에러 처리, 보안에 대한 포괄적인 Go 코드 리뷰. go-reviewer 에이전트를 호출합니다.
+---
+
+# Go 코드 리뷰
+
+이 커맨드는 **go-reviewer** 에이전트를 호출하여 Go 전용 포괄적 코드 리뷰를 수행합니다.
+
+## 이 커맨드가 하는 것
+
+1. **Go 변경사항 식별**: `git diff`로 수정된 `.go` 파일 찾기
+2. **정적 분석 실행**: `go vet`, `staticcheck`, `golangci-lint` 실행
+3. **보안 스캔**: SQL 인젝션, 커맨드 인젝션, 레이스 컨디션 검사
+4. **동시성 리뷰**: 고루틴 안전성, 채널 사용, 뮤텍스 패턴 분석
+5. **관용적 Go 검사**: Go 컨벤션과 모범 사례 준수 여부 확인
+6. **보고서 생성**: 심각도별 이슈 분류
+
+## 사용 시점
+
+`/go-review`를 사용해야 할 때:
+- Go 코드를 작성하거나 수정한 후
+- Go 변경사항을 커밋하기 전
+- Go 코드가 포함된 PR 리뷰 시
+- 새 Go 코드베이스에 온보딩할 때
+- 관용적 Go 패턴 학습 시
+
+## 리뷰 카테고리
+
+### CRITICAL (반드시 수정)
+- SQL/커맨드 인젝션 취약점
+- 동기화 없는 레이스 컨디션
+- 고루틴 누수
+- 하드코딩된 인증 정보
+- unsafe 포인터 사용
+- 핵심 경로에서 에러 무시
+
+### HIGH (수정 권장)
+- 컨텍스트 없는 에러 래핑 누락
+- 에러 반환 대신 panic 사용
+- 컨텍스트 전파 누락
+- 데드락을 유발하는 버퍼 없는 채널
+- 인터페이스 미충족 에러
+- 뮤텍스 보호 누락
+
+### MEDIUM (고려)
+- 비관용적 코드 패턴
+- 공개 항목에 godoc 주석 누락
+- 비효율적인 문자열 연결
+- 슬라이스 사전 할당 누락
+- 테이블 기반 테스트 미사용
+
+## 실행되는 자동 검사
+
+```bash
+# 정적 분석
+go vet ./...
+
+# 고급 검사 (설치된 경우)
+staticcheck ./...
+golangci-lint run
+
+# 레이스 감지
+go build -race ./...
+
+# 보안 취약점
+govulncheck ./...
+```
+
+## 사용 예시
+
+````text
+User: /go-review
+
+Agent:
+# Go 코드 리뷰 보고서
+
+## 리뷰된 파일
+- internal/handler/user.go (수정됨)
+- internal/service/auth.go (수정됨)
+
+## 정적 분석 결과
+✓ go vet: 이슈 없음
+✓ staticcheck: 이슈 없음
+
+## 발견된 이슈
+
+[CRITICAL] 레이스 컨디션
+파일: internal/service/auth.go:45
+이슈: 동기화 없이 공유 맵에 접근
+```go
+var cache = map[string]*Session{}  // 동시 접근!
+
+func GetSession(id string) *Session {
+    return cache[id]  // 레이스 컨디션
+}
+```
+수정: sync.RWMutex 또는 sync.Map 사용
+```go
+var (
+    cache   = map[string]*Session{}
+    cacheMu sync.RWMutex
+)
+
+func GetSession(id string) *Session {
+    cacheMu.RLock()
+    defer cacheMu.RUnlock()
+    return cache[id]
+}
+```
+
+[HIGH] 에러 컨텍스트 누락
+파일: internal/handler/user.go:28
+이슈: 컨텍스트 없이 에러 반환
+```go
+return err  // 컨텍스트 없음
+```
+수정: 컨텍스트와 함께 래핑
+```go
+return fmt.Errorf("get user %s: %w", userID, err)
+```
+
+## 요약
+- CRITICAL: 1
+- HIGH: 1
+- MEDIUM: 0
+
+권장: ❌ CRITICAL 이슈가 수정될 때까지 merge 차단
+````
+
+## 승인 기준
+
+| 상태 | 조건 |
+|------|------|
+| ✅ 승인 | CRITICAL 또는 HIGH 이슈 없음 |
+| ⚠️ 경고 | MEDIUM 이슈만 있음 (주의하여 merge) |
+| ❌ 차단 | CRITICAL 또는 HIGH 이슈 발견 |
+
+## 다른 커맨드와의 연동
+
+- `/go-test`를 먼저 사용하여 테스트 통과 확인
+- `/go-build`를 사용하여 build 에러 발생 시 수정
+- `/go-review`를 커밋 전에 사용
+- `/code-review`를 사용하여 Go 외 일반적인 관심사항 리뷰
+
+## 관련 항목
+
+- 에이전트: `agents/go-reviewer.md`
+- 스킬: `skills/golang-patterns/`, `skills/golang-testing/`

docs/ko-KR/commands/go-test.md

@@ -0,0 +1,268 @@
+---
+description: Go용 TDD 워크플로우 강제. 테이블 기반 테스트를 먼저 작성한 후 구현. go test -cover로 80% 이상 커버리지 검증.
+---
+
+# Go TDD 커맨드
+
+이 커맨드는 관용적 Go 테스팅 패턴을 사용하여 Go 코드에 테스트 주도 개발 방법론을 강제합니다.
+
+## 이 커맨드가 하는 것
+
+1. **타입/인터페이스 정의**: 함수 시그니처를 먼저 스캐폴딩
+2. **테이블 기반 테스트 작성**: 포괄적인 테스트 케이스 생성 (RED)
+3. **테스트 실행**: 올바른 이유로 테스트가 실패하는지 확인
+4. **코드 구현**: 통과하기 위한 최소한의 코드 작성 (GREEN)
+5. **리팩토링**: 테스트를 통과시키면서 개선
+6. **커버리지 확인**: 80% 이상 커버리지 확보
+
+## 사용 시점
+
+`/go-test`를 사용해야 할 때:
+- 새로운 Go 함수 구현
+- 기존 코드에 테스트 커버리지 추가
+- 버그 수정 (실패하는 테스트를 먼저 작성)
+- 핵심 비즈니스 로직 구현
+- Go에서 TDD 워크플로우 학습
+
+## TDD 사이클
+
+```
+RED     → 실패하는 테이블 기반 테스트 작성
+GREEN   → 통과하기 위한 최소한의 코드 구현
+REFACTOR → 코드 개선, 테스트는 통과 유지
+REPEAT  → 다음 테스트 케이스
+```
+
+## 예시 세션
+
+````
+User: /go-test 이메일 주소를 검증하는 함수가 필요합니다
+
+Agent:
+# TDD 세션: 이메일 검증기
+
+## 1단계: 인터페이스 정의
+
+```go
+// validator/email.go
+package validator
+
+// ValidateEmail은 주어진 문자열이 유효한 이메일 주소인지 확인합니다.
+// 유효하면 nil을 반환하고, 그렇지 않으면 이슈를 설명하는 error를 반환합니다.
+func ValidateEmail(email string) error {
+    panic("not implemented")
+}
+```
+
+## 2단계: 테이블 기반 테스트 작성 (RED)
+
+```go
+// validator/email_test.go
+package validator
+
+import (
+    "testing"
+)
+
+func TestValidateEmail(t *testing.T) {
+    tests := []struct {
+        name    string
+        email   string
+        wantErr bool
+    }{
+        // 유효한 이메일
+        {"단순 이메일", "user@example.com", false},
+        {"서브도메인 포함", "user@mail.example.com", false},
+        {"플러스 포함", "user+tag@example.com", false},
+        {"점 포함", "first.last@example.com", false},
+
+        // 유효하지 않은 이메일
+        {"빈 문자열", "", true},
+        {"@ 기호 없음", "userexample.com", true},
+        {"도메인 없음", "user@", true},
+        {"로컬 파트 없음", "@example.com", true},
+        {"이중 @", "user@@example.com", true},
+        {"공백 포함", "user @example.com", true},
+        {"TLD 없음", "user@example", true},
+    }
+
+    for _, tt := range tests {
+        t.Run(tt.name, func(t *testing.T) {
+            err := ValidateEmail(tt.email)
+            if tt.wantErr && err == nil {
+                t.Errorf("ValidateEmail(%q) = nil; want error", tt.email)
+            }
+            if !tt.wantErr && err != nil {
+                t.Errorf("ValidateEmail(%q) = %v; want nil", tt.email, err)
+            }
+        })
+    }
+}
+```
+
+## 3단계: 테스트 실행 - 실패 확인
+
+```bash
+$ go test ./validator/...
+
+--- FAIL: TestValidateEmail (0.00s)
+    --- FAIL: TestValidateEmail/단순_이메일 (0.00s)
+        panic: not implemented
+
+FAIL
+```
+
+✓ 예상대로 테스트 실패 (panic).
+
+## 4단계: 최소한의 코드 구현 (GREEN)
+
+```go
+// validator/email.go
+package validator
+
+import (
+    "errors"
+    "regexp"
+)
+
+var emailRegex = regexp.MustCompile(`^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}$`)
+
+var (
+    ErrEmailEmpty   = errors.New("email cannot be empty")
+    ErrEmailInvalid = errors.New("email format is invalid")
+)
+
+func ValidateEmail(email string) error {
+    if email == "" {
+        return ErrEmailEmpty
+    }
+    if !emailRegex.MatchString(email) {
+        return ErrEmailInvalid
+    }
+    return nil
+}
+```
+
+## 5단계: 테스트 실행 - 통과 확인
+
+```bash
+$ go test ./validator/...
+
+PASS
+ok      project/validator    0.003s
+```
+
+✓ 모든 테스트 통과!
+
+## 6단계: 커버리지 확인
+
+```bash
+$ go test -cover ./validator/...
+
+PASS
+coverage: 100.0% of statements
+ok      project/validator    0.003s
+```
+
+✓ 커버리지: 100%
+
+## TDD 완료!
+````
+
+## 테스트 패턴
+
+### 테이블 기반 테스트
+```go
+tests := []struct {
+    name     string
+    input    InputType
+    want     OutputType
+    wantErr  bool
+}{
+    {"케이스 1", input1, want1, false},
+    {"케이스 2", input2, want2, true},
+}
+
+for _, tt := range tests {
+    t.Run(tt.name, func(t *testing.T) {
+        got, err := Function(tt.input)
+        // 단언문
+    })
+}
+```
+
+### 병렬 테스트
+```go
+for _, tt := range tests {
+    tt := tt // 캡처
+    t.Run(tt.name, func(t *testing.T) {
+        t.Parallel()
+        // 테스트 본문
+    })
+}
+```
+
+### 테스트 헬퍼
+```go
+func setupTestDB(t *testing.T) *sql.DB {
+    t.Helper()
+    db := createDB()
+    t.Cleanup(func() { db.Close() })
+    return db
+}
+```
+
+## 커버리지 커맨드
+
+```bash
+# 기본 커버리지
+go test -cover ./...
+
+# 커버리지 프로파일
+go test -coverprofile=coverage.out ./...
+
+# 브라우저에서 확인
+go tool cover -html=coverage.out
+
+# 함수별 커버리지
+go tool cover -func=coverage.out
+
+# 레이스 감지와 함께
+go test -race -cover ./...
+```
+
+## 커버리지 목표
+
+| 코드 유형 | 목표 |
+|-----------|------|
+| 핵심 비즈니스 로직 | 100% |
+| 공개 API | 90%+ |
+| 일반 코드 | 80%+ |
+| 생성된 코드 | 제외 |
+
+## TDD 모범 사례
+
+**해야 할 것:**
+- 구현 전에 테스트를 먼저 작성
+- 각 변경 후 테스트 실행
+- 포괄적인 커버리지를 위해 테이블 기반 테스트 사용
+- 구현 세부사항이 아닌 동작 테스트
+- 엣지 케이스 포함 (빈 값, nil, 최대값)
+
+**하지 말아야 할 것:**
+- 테스트 전에 구현 작성
+- RED 단계 건너뛰기
+- private 함수를 직접 테스트
+- 테스트에서 `time.Sleep` 사용
+- 불안정한 테스트 무시
+
+## 관련 커맨드
+
+- `/go-build` - build 에러 수정
+- `/go-review` - 구현 후 코드 리뷰
+- `/verify` - 전체 검증 루프
+
+## 관련 항목
+
+- 스킬: `skills/golang-testing/`
+- 스킬: `skills/tdd-workflow/`

docs/ko-KR/commands/learn.md

@@ -0,0 +1,70 @@
+# /learn - 재사용 가능한 패턴 추출
+
+현재 세션을 분석하고 스킬로 저장할 가치가 있는 패턴을 추출합니다.
+
+## 트리거
+
+세션 중 중요한 문제를 해결했을 때 `/learn`을 실행합니다.
+
+## 추출 대상
+
+다음을 찾습니다:
+
+1. **에러 해결 패턴**
+   - 어떤 에러가 발생했는가?
+   - 근본 원인은 무엇이었는가?
+   - 무엇이 해결했는가?
+   - 유사한 에러에 재사용 가능한가?
+
+2. **디버깅 기법**
+   - 직관적이지 않은 디버깅 단계
+   - 효과적인 도구 조합
+   - 진단 패턴
+
+3. **우회 방법**
+   - 라이브러리 특이 사항
+   - API 제한 사항
+   - 버전별 수정 사항
+
+4. **프로젝트 특화 패턴**
+   - 발견된 코드베이스 컨벤션
+   - 내려진 아키텍처 결정
+   - 통합 패턴
+
+## 출력 형식
+
+`~/.claude/skills/learned/[pattern-name].md`에 스킬 파일을 생성합니다:
+
+```markdown
+# [설명적인 패턴 이름]
+
+**추출일:** [날짜]
+**컨텍스트:** [이 패턴이 적용되는 상황에 대한 간략한 설명]
+
+## 문제
+[이 패턴이 해결하는 문제 - 구체적으로 작성]
+
+## 해결 방법
+[패턴/기법/우회 방법]
+
+## 예시
+[해당하는 경우 코드 예시]
+
+## 사용 시점
+[트리거 조건 - 이 스킬이 활성화되어야 하는 상황]
+```
+
+## 프로세스
+
+1. 세션에서 추출 가능한 패턴 검토
+2. 가장 가치 있고 재사용 가능한 인사이트 식별
+3. 스킬 파일 초안 작성
+4. 저장 전 사용자 확인 요청
+5. `~/.claude/skills/learned/`에 저장
+
+## 참고 사항
+
+- 사소한 수정은 추출하지 않기 (오타, 단순 구문 에러)
+- 일회성 이슈는 추출하지 않기 (특정 API 장애 등)
+- 향후 세션에서 시간을 절약할 수 있는 패턴에 집중
+- 스킬은 집중적으로 - 스킬당 하나의 패턴

docs/ko-KR/commands/orchestrate.md

@@ -0,0 +1,172 @@
+# Orchestrate 커맨드
+
+복잡한 작업을 위한 순차적 에이전트 워크플로우입니다.
+
+## 사용법
+
+`/orchestrate [workflow-type] [task-description]`
+
+## 워크플로우 유형
+
+### feature
+전체 기능 구현 워크플로우:
+```
+planner -> tdd-guide -> code-reviewer -> security-reviewer
+```
+
+### bugfix
+버그 조사 및 수정 워크플로우:
+```
+planner -> tdd-guide -> code-reviewer
+```
+
+### refactor
+안전한 리팩토링 워크플로우:
+```
+architect -> code-reviewer -> tdd-guide
+```
+
+### security
+보안 중심 리뷰:
+```
+security-reviewer -> code-reviewer -> architect
+```
+
+## 실행 패턴
+
+워크플로우의 각 에이전트에 대해:
+
+1. 이전 에이전트의 컨텍스트로 **에이전트 호출**
+2. 구조화된 핸드오프 문서로 **출력 수집**
+3. 체인의 **다음 에이전트에 전달**
+4. **결과를 종합**하여 최종 보고서 작성
+
+## 핸드오프 문서 형식
+
+에이전트 간에 핸드오프 문서를 생성합니다:
+
+```markdown
+## HANDOFF: [이전-에이전트] -> [다음-에이전트]
+
+### Context
+[수행된 작업 요약]
+
+### Findings
+[주요 발견 사항 또는 결정 사항]
+
+### Files Modified
+[수정된 파일 목록]
+
+### Open Questions
+[다음 에이전트를 위한 미해결 항목]
+
+### Recommendations
+[제안하는 다음 단계]
+```
+
+## 예시: Feature 워크플로우
+
+```
+/orchestrate feature "Add user authentication"
+```
+
+실행 순서:
+
+1. **Planner 에이전트**
+   - 요구사항 분석
+   - 구현 계획 작성
+   - 의존성 식별
+   - 출력: `HANDOFF: planner -> tdd-guide`
+
+2. **TDD Guide 에이전트**
+   - planner 핸드오프 읽기
+   - 테스트 먼저 작성
+   - 테스트를 통과하도록 구현
+   - 출력: `HANDOFF: tdd-guide -> code-reviewer`
+
+3. **Code Reviewer 에이전트**
+   - 구현 리뷰
+   - 이슈 확인
+   - 개선사항 제안
+   - 출력: `HANDOFF: code-reviewer -> security-reviewer`
+
+4. **Security Reviewer 에이전트**
+   - 보안 감사
+   - 취약점 점검
+   - 최종 승인
+   - 출력: 최종 보고서
+
+## 최종 보고서 형식
+
+```
+ORCHESTRATION REPORT
+====================
+Workflow: feature
+Task: Add user authentication
+Agents: planner -> tdd-guide -> code-reviewer -> security-reviewer
+
+SUMMARY
+-------
+[한 단락 요약]
+
+AGENT OUTPUTS
+-------------
+Planner: [요약]
+TDD Guide: [요약]
+Code Reviewer: [요약]
+Security Reviewer: [요약]
+
+FILES CHANGED
+-------------
+[수정된 모든 파일 목록]
+
+TEST RESULTS
+------------
+[테스트 통과/실패 요약]
+
+SECURITY STATUS
+---------------
+[보안 발견 사항]
+
+RECOMMENDATION
+--------------
+[SHIP / NEEDS WORK / BLOCKED]
+```
+
+## 병렬 실행
+
+독립적인 검사에 대해서는 에이전트를 병렬로 실행합니다:
+
+```markdown
+### Parallel Phase
+동시에 실행:
+- code-reviewer (품질)
+- security-reviewer (보안)
+- architect (설계)
+
+### Merge Results
+출력을 단일 보고서로 통합
+```
+
+## 인자
+
+$ARGUMENTS:
+- `feature <description>` - 전체 기능 워크플로우
+- `bugfix <description>` - 버그 수정 워크플로우
+- `refactor <description>` - 리팩토링 워크플로우
+- `security <description>` - 보안 리뷰 워크플로우
+- `custom <agents> <description>` - 사용자 정의 에이전트 순서
+
+## 사용자 정의 워크플로우 예시
+
+```
+/orchestrate custom "architect,tdd-guide,code-reviewer" "Redesign caching layer"
+```
+
+## 팁
+
+1. 복잡한 기능에는 **planner부터 시작**하세요
+2. merge 전에는 **항상 code-reviewer를 포함**하세요
+3. 인증/결제/개인정보 처리에는 **security-reviewer를 사용**하세요
+4. **핸드오프는 간결하게** 유지하세요 - 다음 에이전트에 필요한 것에 집중
+5. 필요한 경우 에이전트 사이에 **검증을 실행**하세요

docs/ko-KR/commands/plan.md

@@ -0,0 +1,113 @@
+---
+description: 요구사항을 재확인하고, 위험을 평가하며, 단계별 구현 계획을 작성합니다. 코드를 건드리기 전에 사용자 확인을 기다립니다.
+---
+
+# Plan 커맨드
+
+이 커맨드는 **planner** 에이전트를 호출하여 코드를 작성하기 전에 포괄적인 구현 계획을 만듭니다.
+
+## 이 커맨드가 하는 일
+
+1. **요구사항 재확인** - 무엇을 만들어야 하는지 명확히 합니다
+2. **위험 식별** - 잠재적 이슈와 차단 요소를 도출합니다
+3. **단계별 계획 작성** - 구현을 단계별로 분해합니다
+4. **확인 대기** - 진행하기 전에 반드시 사용자 승인을 받아야 합니다
+
+## 사용 시점
+
+`/plan`을 사용해야 할 때:
+- 새 기능을 시작할 때
+- 중요한 아키텍처 변경을 할 때
+- 복잡한 리팩토링 작업을 할 때
+- 여러 파일/컴포넌트에 영향을 미칠 때
+- 요구사항이 불명확하거나 모호할 때
+
+## 작동 방식
+
+planner 에이전트가 수행하는 작업:
+
+1. 요청을 **분석**하고 요구사항을 명확한 용어로 재확인합니다
+2. 구체적이고 실행 가능한 단계로 **분해**합니다
+3. 컴포넌트 간 **의존성을 식별**합니다
+4. **위험을 평가**하고 잠재적 차단 요소를 파악합니다
+5. **복잡도를 추정**합니다 (High/Medium/Low)
+6. 계획을 **제시**하고 명시적 확인을 **대기**합니다
+
+## 사용 예시
+
+```
+User: /plan 마켓이 해결될 때 실시간 알림을 추가해야 합니다
+
+Agent (planner):
+# 구현 계획: 실시간 마켓 해결 알림
+
+## 요구사항 재확인
+- 사용자가 주시 중인 마켓이 해결될 때 알림 전송
+- 다중 알림 채널 지원 (인앱, 이메일, webhook)
+- 알림이 안정적으로 전달되도록 보장
+- 마켓 결과와 사용자의 포지션 결과 포함
+
+## 구현 단계
+
+### 1단계: 데이터베이스 스키마
+- id, user_id, market_id, type, status, created_at 컬럼을 가진 notifications 테이블 추가
+- 채널 설정을 위한 user_notification_preferences 테이블 추가
+- 성능을 위해 user_id와 market_id에 인덱스 생성
+
+### 2단계: 알림 서비스
+- lib/notifications.ts에 알림 서비스 생성
+- BullMQ/Redis를 사용한 알림 큐 구현
+- 전송 실패 시 재시도 로직 추가
+- 알림 템플릿 생성
+
+### 3단계: 연동 포인트
+- 마켓 해결 로직에 연결 (status가 "resolved"로 변경될 때)
+- 해당 마켓에 포지션을 가진 모든 사용자 조회
+- 각 사용자에 대한 알림 큐에 추가
+
+### 4단계: 프론트엔드 컴포넌트
+- 헤더에 NotificationBell 컴포넌트 생성
+- NotificationList 모달 추가
+- Supabase subscriptions를 통한 실시간 업데이트 구현
+- 알림 설정 페이지 추가
+
+## 의존성
+- Redis (큐용)
+- 이메일 서비스 (SendGrid/Resend)
+- Supabase 실시간 subscriptions
+
+## 위험
+- HIGH: 이메일 전달률 (SPF/DKIM 필요)
+- MEDIUM: 마켓당 1000명 이상의 사용자 시 성능
+- MEDIUM: 마켓이 자주 해결될 경우 알림 스팸
+- LOW: 실시간 subscription 오버헤드
+
+## 예상 복잡도: MEDIUM
+- 백엔드: 4-6시간
+- 프론트엔드: 3-4시간
+- 테스트: 2-3시간
+- 합계: 9-13시간
+
+**확인 대기 중**: 이 계획으로 진행할까요? (yes/no/modify)
+```
+
+## 중요 참고 사항
+
+**핵심**: planner 에이전트는 "yes"나 "proceed" 같은 긍정적 응답으로 명시적으로 계획을 확인하기 전까지 코드를 **절대 작성하지 않습니다.**
+
+변경을 원하면 다음과 같이 응답하세요:
+- "modify: [변경 사항]"
+- "different approach: [대안]"
+- "skip phase 2 and do phase 3 first"
+
+## 다른 커맨드와의 연계
+
+계획 수립 후:
+- `/tdd`를 사용하여 테스트 주도 개발로 구현
+- 빌드 에러 발생 시 `/build-fix` 사용
+- 완성된 구현을 `/code-review`로 리뷰
+
+## 관련 에이전트
+
+이 커맨드는 다음 위치의 `planner` 에이전트를 호출합니다:
+`~/.claude/agents/planner.md`

docs/ko-KR/commands/refactor-clean.md

@@ -0,0 +1,80 @@
+# Refactor Clean
+
+사용하지 않는 코드를 안전하게 식별하고 매 단계마다 테스트 검증을 수행하여 제거합니다.
+
+## 1단계: 사용하지 않는 코드 감지
+
+프로젝트 유형에 따라 분석 도구를 실행합니다:
+
+| 도구 | 감지 대상 | 커맨드 |
+|------|----------|--------|
+| knip | 미사용 exports, 파일, 의존성 | `npx knip` |
+| depcheck | 미사용 npm 의존성 | `npx depcheck` |
+| ts-prune | 미사용 TypeScript exports | `npx ts-prune` |
+| vulture | 미사용 Python 코드 | `vulture src/` |
+| deadcode | 미사용 Go 코드 | `deadcode ./...` |
+| cargo-udeps | 미사용 Rust 의존성 | `cargo +nightly udeps` |
+
+사용 가능한 도구가 없는 경우, Grep을 사용하여 import가 없는 export를 찾습니다:
+```
+# export를 찾은 후, 다른 곳에서 import되는지 확인
+```
+
+## 2단계: 결과 분류
+
+안전 등급별로 결과를 분류합니다:
+
+| 등급 | 예시 | 조치 |
+|------|------|------|
+| **안전** | 미사용 유틸리티, 테스트 헬퍼, 내부 함수 | 확신을 가지고 삭제 |
+| **주의** | 컴포넌트, API 라우트, 미들웨어 | 동적 import나 외부 소비자가 없는지 확인 |
+| **위험** | 설정 파일, 엔트리 포인트, 타입 정의 | 건드리기 전에 조사 필요 |
+
+## 3단계: 안전한 삭제 루프
+
+각 안전 항목에 대해:
+
+1. **전체 테스트 스위트 실행** --- 기준선 확립 (모두 통과)
+2. **사용하지 않는 코드 삭제** --- Edit 도구로 정밀하게 제거
+3. **테스트 스위트 재실행** --- 깨진 것이 없는지 확인
+4. **테스트 실패 시** --- 즉시 `git checkout -- <file>`로 되돌리고 해당 항목을 건너뜀
+5. **테스트 통과 시** --- 다음 항목으로 이동
+
+## 4단계: 주의 항목 처리
+
+주의 항목을 삭제하기 전에:
+- 동적 import 검색: `import()`, `require()`, `__import__`
+- 문자열 참조 검색: 라우트 이름, 설정 파일의 컴포넌트 이름
+- 공개 패키지 API에서 export되는지 확인
+- 외부 소비자가 없는지 확인 (게시된 경우 의존 패키지 확인)
+
+## 5단계: 중복 통합
+
+사용하지 않는 코드를 제거한 후 다음을 찾습니다:
+- 거의 중복된 함수 (80% 이상 유사) --- 하나로 병합
+- 중복된 타입 정의 --- 통합
+- 가치를 추가하지 않는 래퍼 함수 --- 인라인 처리
+- 목적이 없는 re-export --- 간접 참조 제거
+
+## 6단계: 요약
+
+결과를 보고합니다:
+
+```
+Dead Code Cleanup
+──────────────────────────────
+삭제:     미사용 함수 12개
+           미사용 파일 3개
+           미사용 의존성 5개
+건너뜀:   항목 2개 (테스트 실패)
+절감:     약 450줄 제거
+──────────────────────────────
+모든 테스트 통과 ✅
+```
+
+## 규칙
+
+- **테스트를 먼저 실행하지 않고 절대 삭제하지 않기**
+- **한 번에 하나씩 삭제** --- 원자적 변경으로 롤백이 쉬움
+- **확실하지 않으면 건너뛰기** --- 프로덕션을 깨뜨리는 것보다 사용하지 않는 코드를 유지하는 것이 나음
+- **정리하면서 리팩토링하지 않기** --- 관심사 분리 (먼저 정리, 나중에 리팩토링)

docs/ko-KR/commands/setup-pm.md

@@ -0,0 +1,80 @@
+---
+description: 선호하는 패키지 매니저(npm/pnpm/yarn/bun) 설정
+disable-model-invocation: true
+---
+
+# 패키지 매니저 설정
+
+프로젝트 또는 전역으로 선호하는 패키지 매니저를 설정합니다.
+
+## 사용법
+
+```bash
+# 현재 패키지 매니저 감지
+node scripts/setup-package-manager.js --detect
+
+# 전역 설정
+node scripts/setup-package-manager.js --global pnpm
+
+# 프로젝트 설정
+node scripts/setup-package-manager.js --project bun
+
+# 사용 가능한 패키지 매니저 목록
+node scripts/setup-package-manager.js --list
+```
+
+## 감지 우선순위
+
+패키지 매니저를 결정할 때 다음 순서로 확인합니다:
+
+1. **환경 변수**: `CLAUDE_PACKAGE_MANAGER`
+2. **프로젝트 설정**: `.claude/package-manager.json`
+3. **package.json**: `packageManager` 필드
+4. **락 파일**: package-lock.json, yarn.lock, pnpm-lock.yaml, bun.lockb의 존재 여부
+5. **전역 설정**: `~/.claude/package-manager.json`
+6. **폴백**: `npm`
+
+## 설정 파일
+
+### 전역 설정
+```json
+// ~/.claude/package-manager.json
+{
+  "packageManager": "pnpm"
+}
+```
+
+### 프로젝트 설정
+```json
+// .claude/package-manager.json
+{
+  "packageManager": "bun"
+}
+```
+
+### package.json
+```json
+{
+  "packageManager": "pnpm@8.6.0"
+}
+```
+
+## 환경 변수
+
+`CLAUDE_PACKAGE_MANAGER`를 설정하면 다른 모든 감지 방법을 무시합니다:
+
+```bash
+# Windows (PowerShell)
+$env:CLAUDE_PACKAGE_MANAGER = "pnpm"
+
+# macOS/Linux
+export CLAUDE_PACKAGE_MANAGER=pnpm
+```
+
+## 감지 실행
+
+현재 패키지 매니저 감지 결과를 확인하려면 다음을 실행하세요:
+
+```bash
+node scripts/setup-package-manager.js --detect
+```

docs/ko-KR/commands/tdd.md

@@ -0,0 +1,326 @@
+---
+description: 테스트 주도 개발 워크플로우 강제. 인터페이스를 스캐폴딩하고, 테스트를 먼저 생성한 후 통과할 최소한의 코드를 구현합니다. 80% 이상 커버리지를 보장합니다.
+---
+
+# TDD 커맨드
+
+이 커맨드는 **tdd-guide** 에이전트를 호출하여 테스트 주도 개발 방법론을 강제합니다.
+
+## 이 커맨드가 하는 것
+
+1. **인터페이스 스캐폴딩** - 타입/인터페이스를 먼저 정의
+2. **테스트 먼저 생성** - 실패하는 테스트 작성 (RED)
+3. **최소한의 코드 구현** - 통과하기에 충분한 코드만 작성 (GREEN)
+4. **리팩토링** - 테스트를 통과시키면서 코드 개선 (REFACTOR)
+5. **커버리지 확인** - 80% 이상 테스트 커버리지 보장
+
+## 사용 시점
+
+`/tdd`를 사용해야 할 때:
+- 새 기능 구현
+- 새 함수/컴포넌트 추가
+- 버그 수정 (버그를 재현하는 테스트를 먼저 작성)
+- 기존 코드 리팩토링
+- 핵심 비즈니스 로직 구현
+
+## 작동 방식
+
+tdd-guide 에이전트가 수행하는 작업:
+
+1. 입출력에 대한 **인터페이스 정의**
+2. (코드가 아직 존재하지 않으므로) **실패하는 테스트 작성**
+3. 올바른 이유로 실패하는지 **테스트 실행** 및 확인
+4. 테스트를 통과하도록 **최소한의 구현 작성**
+5. 통과하는지 **테스트 실행** 및 확인
+6. 테스트를 통과시키면서 코드 **리팩토링**
+7. **커버리지 확인** 및 80% 미만이면 테스트 추가
+
+## TDD 사이클
+
+```
+RED → GREEN → REFACTOR → REPEAT
+
+RED:      실패하는 테스트 작성
+GREEN:    통과할 최소한의 코드 작성
+REFACTOR: 코드 개선, 테스트 계속 통과 유지
+REPEAT:   다음 기능/시나리오
+```
+
+## 사용 예시
+
+````
+User: /tdd 마켓 유동성 점수를 계산하는 함수가 필요합니다
+
+Agent (tdd-guide):
+# TDD 세션: 마켓 유동성 점수 계산기
+
+## 1단계: 인터페이스 정의 (SCAFFOLD)
+
+```typescript
+// lib/liquidity.ts
+export interface MarketData {
+  totalVolume: number
+  bidAskSpread: number
+  activeTraders: number
+  lastTradeTime: Date
+}
+
+export function calculateLiquidityScore(market: MarketData): number {
+  // TODO: 구현
+  throw new Error('Not implemented')
+}
+```
+
+## 2단계: 실패하는 테스트 작성 (RED)
+
+```typescript
+// lib/liquidity.test.ts
+import { calculateLiquidityScore } from './liquidity'
+
+describe('calculateLiquidityScore', () => {
+  it('should return high score for liquid market', () => {
+    const market = {
+      totalVolume: 100000,
+      bidAskSpread: 0.01,
+      activeTraders: 500,
+      lastTradeTime: new Date()
+    }
+
+    const score = calculateLiquidityScore(market)
+
+    expect(score).toBeGreaterThan(80)
+    expect(score).toBeLessThanOrEqual(100)
+  })
+
+  it('should return low score for illiquid market', () => {
+    const market = {
+      totalVolume: 100,
+      bidAskSpread: 0.5,
+      activeTraders: 2,
+      lastTradeTime: new Date(Date.now() - 86400000) // 1일 전
+    }
+
+    const score = calculateLiquidityScore(market)
+
+    expect(score).toBeLessThan(30)
+    expect(score).toBeGreaterThanOrEqual(0)
+  })
+
+  it('should handle edge case: zero volume', () => {
+    const market = {
+      totalVolume: 0,
+      bidAskSpread: 0,
+      activeTraders: 0,
+      lastTradeTime: new Date()
+    }
+
+    const score = calculateLiquidityScore(market)
+
+    expect(score).toBe(0)
+  })
+})
+```
+
+## 3단계: 테스트 실행 - 실패 확인
+
+```bash
+npm test lib/liquidity.test.ts
+
+FAIL lib/liquidity.test.ts
+  ✕ should return high score for liquid market (2 ms)
+    Error: Not implemented
+
+1 test failed, 0 passed
+```
+
+✅ 예상대로 테스트 실패. 구현 준비 완료.
+
+## 4단계: 최소한의 코드 구현 (GREEN)
+
+```typescript
+// lib/liquidity.ts
+export function calculateLiquidityScore(market: MarketData): number {
+  // 거래량 0인 엣지 케이스 처리
+  if (market.totalVolume === 0) {
+    return 0
+  }
+
+  // 구성 요소별 점수 계산 (0-100 스케일)
+  const volumeScore = Math.min(market.totalVolume / 1000, 100)
+  const spreadScore = Math.max(100 - (market.bidAskSpread * 1000), 0)
+  const traderScore = Math.min(market.activeTraders / 10, 100)
+
+  // 최근 활동 보너스
+  const hoursSinceLastTrade = (Date.now() - market.lastTradeTime.getTime()) / (1000 * 60 * 60)
+  const recencyScore = Math.max(100 - (hoursSinceLastTrade * 10), 0)
+
+  // 가중 평균
+  const score = (
+    volumeScore * 0.4 +
+    spreadScore * 0.3 +
+    traderScore * 0.2 +
+    recencyScore * 0.1
+  )
+
+  return Math.min(Math.max(score, 0), 100) // 0-100으로 클램핑
+}
+```
+
+## 5단계: 테스트 실행 - 통과 확인
+
+```bash
+npm test lib/liquidity.test.ts
+
+PASS lib/liquidity.test.ts
+  ✓ should return high score for liquid market (3 ms)
+  ✓ should return low score for illiquid market (2 ms)
+  ✓ should handle edge case: zero volume (1 ms)
+
+3 tests passed
+```
+
+✅ 모든 테스트 통과!
+
+## 6단계: 리팩토링 (IMPROVE)
+
+```typescript
+// lib/liquidity.ts - 상수와 가독성 향상을 위한 리팩토링
+const WEIGHTS = {
+  VOLUME: 0.4,
+  SPREAD: 0.3,
+  TRADERS: 0.2,
+  RECENCY: 0.1,
+} as const
+
+const SCALE_FACTORS = {
+  VOLUME: 1000,
+  SPREAD: 1000,
+  TRADERS: 10,
+  RECENCY_PENALTY: 10,
+} as const
+
+function clamp(value: number, min: number, max: number): number {
+  return Math.min(Math.max(value, min), max)
+}
+
+export function calculateLiquidityScore(market: MarketData): number {
+  if (market.totalVolume === 0) return 0
+
+  const volumeScore = Math.min(market.totalVolume / SCALE_FACTORS.VOLUME, 100)
+  const spreadScore = clamp(100 - (market.bidAskSpread * SCALE_FACTORS.SPREAD), 0, 100)
+  const traderScore = Math.min(market.activeTraders / SCALE_FACTORS.TRADERS, 100)
+
+  const hoursSinceLastTrade = (Date.now() - market.lastTradeTime.getTime()) / (1000 * 60 * 60)
+  const recencyScore = clamp(100 - (hoursSinceLastTrade * SCALE_FACTORS.RECENCY_PENALTY), 0, 100)
+
+  const weightedScore =
+    volumeScore * WEIGHTS.VOLUME +
+    spreadScore * WEIGHTS.SPREAD +
+    traderScore * WEIGHTS.TRADERS +
+    recencyScore * WEIGHTS.RECENCY
+
+  return clamp(weightedScore, 0, 100)
+}
+```
+
+## 7단계: 테스트가 여전히 통과하는지 확인
+
+```bash
+npm test lib/liquidity.test.ts
+
+PASS lib/liquidity.test.ts
+  ✓ should return high score for liquid market (3 ms)
+  ✓ should return low score for illiquid market (2 ms)
+  ✓ should handle edge case: zero volume (1 ms)
+
+3 tests passed
+```
+
+✅ 리팩토링 완료, 테스트 여전히 통과!
+
+## 8단계: 커버리지 확인
+
+```bash
+npm test -- --coverage lib/liquidity.test.ts
+
+File           | % Stmts | % Branch | % Funcs | % Lines
+---------------|---------|----------|---------|--------
+liquidity.ts   |   100   |   100    |   100   |   100
+
+Coverage: 100% ✅ (목표: 80%)
+```
+
+✅ TDD 세션 완료!
+````
+
+## TDD 모범 사례
+
+**해야 할 것:**
+- 구현 전에 테스트를 먼저 작성
+- 구현 전에 테스트를 실행하여 실패하는지 확인
+- 테스트를 통과하기 위한 최소한의 코드 작성
+- 테스트가 통과한 후에만 리팩토링
+- 엣지 케이스와 에러 시나리오 추가
+- 80% 이상 커버리지 목표 (핵심 코드는 100%)
+
+**하지 말아야 할 것:**
+- 테스트 전에 구현 작성
+- 각 변경 후 테스트 실행 건너뛰기
+- 한 번에 너무 많은 코드 작성
+- 실패하는 테스트 무시
+- 구현 세부사항 테스트 (동작을 테스트)
+- 모든 것을 mock (통합 테스트 선호)
+
+## 포함할 테스트 유형
+
+**단위 테스트** (함수 수준):
+- 정상 경로 시나리오
+- 엣지 케이스 (빈 값, null, 최대값)
+- 에러 조건
+- 경계값
+
+**통합 테스트** (컴포넌트 수준):
+- API 엔드포인트
+- 데이터베이스 작업
+- 외부 서비스 호출
+- hooks가 포함된 React 컴포넌트
+
+**E2E 테스트** (`/e2e` 커맨드 사용):
+- 핵심 사용자 흐름
+- 다단계 프로세스
+- 풀 스택 통합
+
+## 커버리지 요구사항
+
+- **80% 최소** - 모든 코드에 대해
+- **100% 필수** - 다음 항목에 대해:
+  - 금융 계산
+  - 인증 로직
+  - 보안에 중요한 코드
+  - 핵심 비즈니스 로직
+
+## 중요 사항
+
+**필수**: 테스트는 반드시 구현 전에 작성해야 합니다. TDD 사이클은 다음과 같습니다:
+
+1. **RED** - 실패하는 테스트 작성
+2. **GREEN** - 통과하도록 구현
+3. **REFACTOR** - 코드 개선
+
+절대 RED 단계를 건너뛰지 마세요. 절대 테스트 전에 코드를 작성하지 마세요.
+
+## 다른 커맨드와의 연동
+
+- `/plan`을 먼저 사용하여 무엇을 만들지 이해
+- `/tdd`를 사용하여 테스트와 함께 구현
+- `/build-fix`를 사용하여 빌드 에러 발생 시 수정
+- `/code-review`를 사용하여 구현 리뷰
+- `/test-coverage`를 사용하여 커버리지 검증
+
+## 관련 에이전트
+
+이 커맨드는 `tdd-guide` 에이전트를 호출합니다:
+`~/.claude/agents/tdd-guide.md`
+
+그리고 `tdd-workflow` 스킬을 참조할 수 있습니다:
+`~/.claude/skills/tdd-workflow/`

docs/ko-KR/commands/test-coverage.md

@@ -0,0 +1,74 @@
+---
+name: test-coverage
+description: 테스트 커버리지를 분석하고, 80% 이상을 목표로 누락된 테스트를 식별하고 생성합니다.
+---
+
+# 테스트 커버리지
+
+테스트 커버리지를 분석하고, 갭을 식별하며, 80% 이상 커버리지 달성을 위해 누락된 테스트를 생성합니다.
+
+## 1단계: 테스트 프레임워크 감지
+
+| 지표 | 커버리지 커맨드 |
+|------|----------------|
+| `jest.config.*` 또는 `package.json` jest | `npx jest --coverage --coverageReporters=json-summary` |
+| `vitest.config.*` | `npx vitest run --coverage` |
+| `pytest.ini` / `pyproject.toml` pytest | `pytest --cov=src --cov-report=json` |
+| `Cargo.toml` | `cargo llvm-cov --json` |
+| `pom.xml` with JaCoCo | `mvn test jacoco:report` |
+| `go.mod` | `go test -coverprofile=coverage.out ./...` |
+
+## 2단계: 커버리지 보고서 분석
+
+1. 커버리지 커맨드 실행
+2. 출력 파싱 (JSON 요약 또는 터미널 출력)
+3. **80% 미만인 파일**을 최저순으로 정렬하여 목록화
+4. 각 커버리지 미달 파일에 대해 다음을 식별:
+   - 테스트되지 않은 함수 또는 메서드
+   - 누락된 분기 커버리지 (if/else, switch, 에러 경로)
+   - 분모를 부풀리는 데드 코드
+
+## 3단계: 누락된 테스트 생성
+
+각 커버리지 미달 파일에 대해 다음 우선순위에 따라 테스트를 생성합니다:
+
+1. **Happy path** — 유효한 입력의 핵심 기능
+2. **에러 처리** — 잘못된 입력, 누락된 데이터, 네트워크 실패
+3. **엣지 케이스** — 빈 배열, null/undefined, 경계값 (0, -1, MAX_INT)
+4. **분기 커버리지** — 각 if/else, switch case, 삼항 연산자
+
+### 테스트 생성 규칙
+
+- 소스 파일 옆에 테스트 배치: `foo.ts` → `foo.test.ts` (또는 프로젝트 컨벤션에 따름)
+- 프로젝트의 기존 테스트 패턴 사용 (import 스타일, assertion 라이브러리, mocking 방식)
+- 외부 의존성 mock 처리 (데이터베이스, API, 파일 시스템)
+- 각 테스트는 독립적이어야 함 — 테스트 간 공유 가변 상태 없음
+- 테스트 이름은 설명적으로: `test_create_user_with_duplicate_email_returns_409`
+
+## 4단계: 검증
+
+1. 전체 테스트 스위트 실행 — 모든 테스트가 통과해야 함
+2. 커버리지 재실행 — 개선 확인
+3. 여전히 80% 미만이면 나머지 갭에 대해 3단계 반복
+
+## 5단계: 보고서
+
+이전/이후 비교를 표시합니다:
+
+```
+커버리지 보고서
+──────────────────────────────
+파일                         이전    이후
+src/services/auth.ts         45%     88%
+src/utils/validation.ts      32%     82%
+──────────────────────────────
+전체:                        67%     84%  ✅
+```
+
+## 집중 영역
+
+- 복잡한 분기가 있는 함수 (높은 순환 복잡도)
+- 에러 핸들러와 catch 블록
+- 코드베이스 전반에서 사용되는 유틸리티 함수
+- API 엔드포인트 핸들러 (요청 → 응답 흐름)
+- 엣지 케이스: null, undefined, 빈 문자열, 빈 배열, 0, 음수

docs/ko-KR/commands/update-codemaps.md

@@ -0,0 +1,79 @@
+# 코드맵 업데이트
+
+코드베이스 구조를 분석하고 토큰 효율적인 아키텍처 문서를 생성합니다.
+
+## 1단계: 프로젝트 구조 스캔
+
+1. 프로젝트 유형 식별 (모노레포, 단일 앱, 라이브러리, 마이크로서비스)
+2. 모든 소스 디렉토리 찾기 (src/, lib/, app/, packages/)
+3. 엔트리 포인트 매핑 (main.ts, index.ts, app.py, main.go 등)
+
+## 2단계: 코드맵 생성
+
+`docs/CODEMAPS/`에 코드맵 생성 또는 업데이트:
+
+| 파일 | 내용 |
+|------|------|
+| `INDEX.md` | 전체 코드베이스 개요와 영역별 링크 |
+| `backend.md` | API 라우트, 미들웨어 체인, 서비스 → 리포지토리 매핑 |
+| `frontend.md` | 페이지 트리, 컴포넌트 계층, 상태 관리 흐름 |
+| `database.md` | 데이터베이스 스키마, 마이그레이션, 저장소 계층 |
+| `integrations.md` | 외부 서비스, 서드파티 통합, 어댑터 |
+| `workers.md` | 백그라운드 작업, 큐, 스케줄러 |
+
+### 코드맵 형식
+
+각 코드맵은 토큰 효율적이어야 합니다 — AI 컨텍스트 소비에 최적화:
+
+```markdown
+# Backend 아키텍처
+
+## 라우트
+POST /api/users → UserController.create → UserService.create → UserRepo.insert
+GET  /api/users/:id → UserController.get → UserService.findById → UserRepo.findById
+
+## 주요 파일
+src/services/user.ts (비즈니스 로직, 120줄)
+src/repos/user.ts (데이터베이스 접근, 80줄)
+
+## 의존성
+- PostgreSQL (주 데이터 저장소)
+- Redis (세션 캐시, 속도 제한)
+- Stripe (결제 처리)
+```
+
+## 3단계: 영역 분류
+
+생성기는 파일 경로 패턴을 기반으로 영역을 자동 분류합니다:
+
+1. 프론트엔드: `app/`, `pages/`, `components/`, `hooks/`, `.tsx`, `.jsx`
+2. 백엔드: `api/`, `routes/`, `controllers/`, `services/`, `.route.ts`
+3. 데이터베이스: `db/`, `migrations/`, `prisma/`, `repositories/`
+4. 통합: `integrations/`, `adapters/`, `connectors/`, `plugins/`
+5. 워커: `workers/`, `jobs/`, `queues/`, `tasks/`, `cron/`
+
+## 4단계: 메타데이터 추가
+
+각 코드맵에 최신 정보 헤더를 추가합니다:
+
+```markdown
+**Last Updated:** 2026-03-12
+**Total Files:** 42
+**Total Lines:** 1875
+```
+
+## 5단계: 인덱스와 영역 문서 동기화
+
+`INDEX.md`는 생성된 영역 문서를 링크하고 요약해야 합니다:
+- 각 영역의 파일 수와 총 라인 수
+- 감지된 엔트리 포인트
+- 저장소 트리의 간단한 ASCII 개요
+- 영역별 세부 문서 링크
+
+## 팁
+
+- **구현 세부사항이 아닌 상위 구조**에 집중
+- 전체 코드 블록 대신 **파일 경로와 함수 시그니처** 사용
+- 효율적인 컨텍스트 로딩을 위해 각 코드맵을 **1000 토큰 미만**으로 유지
+- 장황한 설명 대신 데이터 흐름에 ASCII 다이어그램 사용
+- 주요 기능 추가 또는 리팩토링 세션 후 `npx tsx scripts/codemaps/generate.ts` 실행