chore: prepare v1.9.0 release (#666)

- Bump version to 1.9.0 in package.json, package-lock.json, .opencode/package.json
- Add v1.9.0 changelog with 212 commits covering selective install architecture,
  6 new agents, 15+ new skills, session/state infrastructure, observer fixes,
  12 language ecosystems, and community contributions
- Update README with v1.9.0 release notes and complete agents tree (27 agents)
- Add pytorch-build-resolver to AGENTS.md agent table
- Update documentation counts to 27 agents, 109 skills, 57 commands
- Update version references in zh-CN README
- All 1421 tests passing, catalog counts verified

.agents/skills/bun-runtime/SKILL.md

@@ -0,0 +1,84 @@
+---
+name: bun-runtime
+description: Bun as runtime, package manager, bundler, and test runner. When to choose Bun vs Node, migration notes, and Vercel support.
+origin: ECC
+---
+
+# Bun Runtime
+
+Bun is a fast all-in-one JavaScript runtime and toolkit: runtime, package manager, bundler, and test runner.
+
+## When to Use
+
+- **Prefer Bun** for: new JS/TS projects, scripts where install/run speed matters, Vercel deployments with Bun runtime, and when you want a single toolchain (run + install + test + build).
+- **Prefer Node** for: maximum ecosystem compatibility, legacy tooling that assumes Node, or when a dependency has known Bun issues.
+
+Use when: adopting Bun, migrating from Node, writing or debugging Bun scripts/tests, or configuring Bun on Vercel or other platforms.
+
+## How It Works
+
+- **Runtime**: Drop-in Node-compatible runtime (built on JavaScriptCore, implemented in Zig).
+- **Package manager**: `bun install` is significantly faster than npm/yarn. Lockfile is `bun.lock` (text) by default in current Bun; older versions used `bun.lockb` (binary).
+- **Bundler**: Built-in bundler and transpiler for apps and libraries.
+- **Test runner**: Built-in `bun test` with Jest-like API.
+
+**Migration from Node**: Replace `node script.js` with `bun run script.js` or `bun script.js`. Run `bun install` in place of `npm install`; most packages work. Use `bun run` for npm scripts; `bun x` for npx-style one-off runs. Node built-ins are supported; prefer Bun APIs where they exist for better performance.
+
+**Vercel**: Set runtime to Bun in project settings. Build: `bun run build` or `bun build ./src/index.ts --outdir=dist`. Install: `bun install --frozen-lockfile` for reproducible deploys.
+
+## Examples
+
+### Run and install
+
+```bash
+# Install dependencies (creates/updates bun.lock or bun.lockb)
+bun install
+
+# Run a script or file
+bun run dev
+bun run src/index.ts
+bun src/index.ts
+```
+
+### Scripts and env
+
+```bash
+bun run --env-file=.env dev
+FOO=bar bun run script.ts
+```
+
+### Testing
+
+```bash
+bun test
+bun test --watch
+```
+
+```typescript
+// test/example.test.ts
+import { expect, test } from "bun:test";
+
+test("add", () => {
+  expect(1 + 2).toBe(3);
+});
+```
+
+### Runtime API
+
+```typescript
+const file = Bun.file("package.json");
+const json = await file.json();
+
+Bun.serve({
+  port: 3000,
+  fetch(req) {
+    return new Response("Hello");
+  },
+});
+```
+
+## Best Practices
+
+- Commit the lockfile (`bun.lock` or `bun.lockb`) for reproducible installs.
+- Prefer `bun run` for scripts. For TypeScript, Bun runs `.ts` natively.
+- Keep dependencies up to date; Bun and the ecosystem evolve quickly.

.agents/skills/bun-runtime/agents/openai.yaml

@@ -0,0 +1,7 @@
+interface:
+  display_name: "Bun Runtime"
+  short_description: "Bun as runtime, package manager, bundler, and test runner"
+  brand_color: "#FBF0DF"
+  default_prompt: "Use Bun for scripts, install, or run"
+policy:
+  allow_implicit_invocation: true

.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,188 @@
+---
+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 Activate
+
+- 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"
+
+## 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.)
+
+## Content Adaptation 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}
+        }
+    }
+)
+```
+
+### 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/documentation-lookup/SKILL.md

@@ -0,0 +1,90 @@
+---
+name: documentation-lookup
+description: Use up-to-date library and framework docs via Context7 MCP instead of training data. Activates for setup questions, API references, code examples, or when the user names a framework (e.g. React, Next.js, Prisma).
+origin: ECC
+---
+
+# Documentation Lookup (Context7)
+
+When the user asks about libraries, frameworks, or APIs, fetch current documentation via the Context7 MCP (tools `resolve-library-id` and `query-docs`) instead of relying on training data.
+
+## Core Concepts
+
+- **Context7**: MCP server that exposes live documentation; use it instead of training data for libraries and APIs.
+- **resolve-library-id**: Returns Context7-compatible library IDs (e.g. `/vercel/next.js`) from a library name and query.
+- **query-docs**: Fetches documentation and code snippets for a given library ID and question. Always call resolve-library-id first to get a valid library ID.
+
+## When to use
+
+Activate when the user:
+
+- Asks setup or configuration questions (e.g. "How do I configure Next.js middleware?")
+- Requests code that depends on a library ("Write a Prisma query for...")
+- Needs API or reference information ("What are the Supabase auth methods?")
+- Mentions specific frameworks or libraries (React, Vue, Svelte, Express, Tailwind, Prisma, Supabase, etc.)
+
+Use this skill whenever the request depends on accurate, up-to-date behavior of a library, framework, or API. Applies across harnesses that have the Context7 MCP configured (e.g. Claude Code, Cursor, Codex).
+
+## How it works
+
+### Step 1: Resolve the Library ID
+
+Call the **resolve-library-id** MCP tool with:
+
+- **libraryName**: The library or product name taken from the user's question (e.g. `Next.js`, `Prisma`, `Supabase`).
+- **query**: The user's full question. This improves relevance ranking of results.
+
+You must obtain a Context7-compatible library ID (format `/org/project` or `/org/project/version`) before querying docs. Do not call query-docs without a valid library ID from this step.
+
+### Step 2: Select the Best Match
+
+From the resolution results, choose one result using:
+
+- **Name match**: Prefer exact or closest match to what the user asked for.
+- **Benchmark score**: Higher scores indicate better documentation quality (100 is highest).
+- **Source reputation**: Prefer High or Medium reputation when available.
+- **Version**: If the user specified a version (e.g. "React 19", "Next.js 15"), prefer a version-specific library ID if listed (e.g. `/org/project/v1.2.0`).
+
+### Step 3: Fetch the Documentation
+
+Call the **query-docs** MCP tool with:
+
+- **libraryId**: The selected Context7 library ID from Step 2 (e.g. `/vercel/next.js`).
+- **query**: The user's specific question or task. Be specific to get relevant snippets.
+
+Limit: do not call query-docs (or resolve-library-id) more than 3 times per question. If the answer is unclear after 3 calls, state the uncertainty and use the best information you have rather than guessing.
+
+### Step 4: Use the Documentation
+
+- Answer the user's question using the fetched, current information.
+- Include relevant code examples from the docs when helpful.
+- Cite the library or version when it matters (e.g. "In Next.js 15...").
+
+## Examples
+
+### Example: Next.js middleware
+
+1. Call **resolve-library-id** with `libraryName: "Next.js"`, `query: "How do I set up Next.js middleware?"`.
+2. From results, pick the best match (e.g. `/vercel/next.js`) by name and benchmark score.
+3. Call **query-docs** with `libraryId: "/vercel/next.js"`, `query: "How do I set up Next.js middleware?"`.
+4. Use the returned snippets and text to answer; include a minimal `middleware.ts` example from the docs if relevant.
+
+### Example: Prisma query
+
+1. Call **resolve-library-id** with `libraryName: "Prisma"`, `query: "How do I query with relations?"`.
+2. Select the official Prisma library ID (e.g. `/prisma/prisma`).
+3. Call **query-docs** with that `libraryId` and the query.
+4. Return the Prisma Client pattern (e.g. `include` or `select`) with a short code snippet from the docs.
+
+### Example: Supabase auth methods
+
+1. Call **resolve-library-id** with `libraryName: "Supabase"`, `query: "What are the auth methods?"`.
+2. Pick the Supabase docs library ID.
+3. Call **query-docs**; summarize the auth methods and show minimal examples from the fetched docs.
+
+## Best Practices
+
+- **Be specific**: Use the user's full question as the query where possible for better relevance.
+- **Version awareness**: When users mention versions, use version-specific library IDs from the resolve step when available.
+- **Prefer official sources**: When multiple matches exist, prefer official or primary packages over community forks.
+- **No sensitive data**: Redact API keys, passwords, tokens, and other secrets from any query sent to Context7. Treat the user's question as potentially containing secrets before passing it to resolve-library-id or query-docs.

.agents/skills/documentation-lookup/agents/openai.yaml

@@ -0,0 +1,7 @@
+interface:
+  display_name: "Documentation Lookup"
+  short_description: "Fetch up-to-date library docs via Context7 MCP"
+  brand_color: "#6366F1"
+  default_prompt: "Look up docs for a library or API"
+policy:
+  allow_implicit_invocation: true

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

@@ -0,0 +1,170 @@
+---
+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"],
+  "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/mcp-server-patterns/SKILL.md

@@ -0,0 +1,67 @@
+---
+name: mcp-server-patterns
+description: Build MCP servers with Node/TypeScript SDK — tools, resources, prompts, Zod validation, stdio vs Streamable HTTP. Use Context7 or official MCP docs for latest API.
+origin: ECC
+---
+
+# MCP Server Patterns
+
+The Model Context Protocol (MCP) lets AI assistants call tools, read resources, and use prompts from your server. Use this skill when building or maintaining MCP servers. The SDK API evolves; check Context7 (query-docs for "MCP") or the official MCP documentation for current method names and signatures.
+
+## When to Use
+
+Use when: implementing a new MCP server, adding tools or resources, choosing stdio vs HTTP, upgrading the SDK, or debugging MCP registration and transport issues.
+
+## How It Works
+
+### Core concepts
+
+- **Tools**: Actions the model can invoke (e.g. search, run a command). Register with `registerTool()` or `tool()` depending on SDK version.
+- **Resources**: Read-only data the model can fetch (e.g. file contents, API responses). Register with `registerResource()` or `resource()`. Handlers typically receive a `uri` argument.
+- **Prompts**: Reusable, parameterised prompt templates the client can surface (e.g. in Claude Desktop). Register with `registerPrompt()` or equivalent.
+- **Transport**: stdio for local clients (e.g. Claude Desktop); Streamable HTTP is preferred for remote (Cursor, cloud). Legacy HTTP/SSE is for backward compatibility.
+
+The Node/TypeScript SDK may expose `tool()` / `resource()` or `registerTool()` / `registerResource()`; the official SDK has changed over time. Always verify against the current [MCP docs](https://modelcontextprotocol.io) or Context7.
+
+### Connecting with stdio
+
+For local clients, create a stdio transport and pass it to your server’s connect method. The exact API varies by SDK version (e.g. constructor vs factory). See the official MCP documentation or query Context7 for "MCP stdio server" for the current pattern.
+
+Keep server logic (tools + resources) independent of transport so you can plug in stdio or HTTP in the entrypoint.
+
+### Remote (Streamable HTTP)
+
+For Cursor, cloud, or other remote clients, use **Streamable HTTP** (single MCP HTTP endpoint per current spec). Support legacy HTTP/SSE only when backward compatibility is required.
+
+## Examples
+
+### Install and server setup
+
+```bash
+npm install @modelcontextprotocol/sdk zod
+```
+
+```typescript
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { z } from "zod";
+
+const server = new McpServer({ name: "my-server", version: "1.0.0" });
+```
+
+Register tools and resources using the API your SDK version provides: some versions use `server.tool(name, description, schema, handler)` (positional args), others use `server.tool({ name, description, inputSchema }, handler)` or `registerTool()`. Same for resources — include a `uri` in the handler when the API provides it. Check the official MCP docs or Context7 for the current `@modelcontextprotocol/sdk` signatures to avoid copy-paste errors.
+
+Use **Zod** (or the SDK’s preferred schema format) for input validation.
+
+## Best Practices
+
+- **Schema first**: Define input schemas for every tool; document parameters and return shape.
+- **Errors**: Return structured errors or messages the model can interpret; avoid raw stack traces.
+- **Idempotency**: Prefer idempotent tools where possible so retries are safe.
+- **Rate and cost**: For tools that call external APIs, consider rate limits and cost; document in the tool description.
+- **Versioning**: Pin SDK version in package.json; check release notes when upgrading.
+
+## Official SDKs and Docs
+
+- **JavaScript/TypeScript**: `@modelcontextprotocol/sdk` (npm). Use Context7 with library name "MCP" for current registration and transport patterns.
+- **Go**: Official Go SDK on GitHub (`modelcontextprotocol/go-sdk`).
+- **C#**: Official C# SDK for .NET.

.agents/skills/nextjs-turbopack/SKILL.md

@@ -0,0 +1,44 @@
+---
+name: nextjs-turbopack
+description: Next.js 16+ and Turbopack — incremental bundling, FS caching, dev speed, and when to use Turbopack vs webpack.
+origin: ECC
+---
+
+# Next.js and Turbopack
+
+Next.js 16+ uses Turbopack by default for local development: an incremental bundler written in Rust that significantly speeds up dev startup and hot updates.
+
+## When to Use
+
+- **Turbopack (default dev)**: Use for day-to-day development. Faster cold start and HMR, especially in large apps.
+- **Webpack (legacy dev)**: Use only if you hit a Turbopack bug or rely on a webpack-only plugin in dev. Disable with `--webpack` (or `--no-turbopack` depending on your Next.js version; check the docs for your release).
+- **Production**: Production build behavior (`next build`) may use Turbopack or webpack depending on Next.js version; check the official Next.js docs for your version.
+
+Use when: developing or debugging Next.js 16+ apps, diagnosing slow dev startup or HMR, or optimizing production bundles.
+
+## How It Works
+
+- **Turbopack**: Incremental bundler for Next.js dev. Uses file-system caching so restarts are much faster (e.g. 5–14x on large projects).
+- **Default in dev**: From Next.js 16, `next dev` runs with Turbopack unless disabled.
+- **File-system caching**: Restarts reuse previous work; cache is typically under `.next`; no extra config needed for basic use.
+- **Bundle Analyzer (Next.js 16.1+)**: Experimental Bundle Analyzer to inspect output and find heavy dependencies; enable via config or experimental flag (see Next.js docs for your version).
+
+## Examples
+
+### Commands
+
+```bash
+next dev
+next build
+next start
+```
+
+### Usage
+
+Run `next dev` for local development with Turbopack. Use the Bundle Analyzer (see Next.js docs) to optimize code-splitting and trim large dependencies. Prefer App Router and server components where possible.
+
+## Best Practices
+
+- Stay on a recent Next.js 16.x for stable Turbopack and caching behavior.
+- If dev is slow, ensure you're on Turbopack (default) and that the cache isn't being cleared unnecessarily.
+- For production bundle size issues, use the official Next.js bundle analysis tooling for your version.

.agents/skills/nextjs-turbopack/agents/openai.yaml

@@ -0,0 +1,7 @@
+interface:
+  display_name: "Next.js Turbopack"
+  short_description: "Next.js 16+ and Turbopack dev bundler"
+  brand_color: "#000000"
+  default_prompt: "Next.js dev, Turbopack, or bundle optimization"
+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-plugin/marketplace.json

@@ -14,7 +14,7 @@
       "name": "everything-claude-code",
       "source": "./",
       "description": "The most comprehensive Claude Code plugin — 14+ agents, 56+ skills, 33+ commands, and production-ready hooks for TDD, security scanning, code review, and continuous learning",
-      "version": "1.7.0",
+      "version": "1.8.0",
       "author": {
         "name": "Affaan Mustafa",
         "email": "me@affaanmustafa.com"

.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "everything-claude-code",
-  "version": "1.7.0",
+  "version": "1.8.0",
   "description": "Complete collection of battle-tested Claude Code configs from an Anthropic hackathon winner - agents, skills, hooks, and rules evolved over 10+ months of intensive daily use",
   "author": {
     "name": "Affaan Mustafa",

.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/adapter.js

@@ -29,13 +29,14 @@ function transformToClaude(cursorInput, overrides = {}) {
   return {
     tool_input: {
       command: cursorInput.command || cursorInput.args?.command || '',
-      file_path: cursorInput.path || cursorInput.file || '',
+      file_path: cursorInput.path || cursorInput.file || cursorInput.args?.filePath || '',
       ...overrides.tool_input,
     },
     tool_output: {
       output: cursorInput.output || cursorInput.result || '',
       ...overrides.tool_output,
     },
+    transcript_path: cursorInput.transcript_path || cursorInput.transcriptPath || cursorInput.session?.transcript_path || '',
     _cursor: {
       conversation_id: cursorInput.conversation_id,
       hook_event_name: cursorInput.hook_event_name,
@@ -59,4 +60,22 @@ function runExistingHook(scriptName, stdinData) {
   }
 }
 
-module.exports = { readStdin, getPluginRoot, transformToClaude, runExistingHook };
+function hookEnabled(hookId, allowedProfiles = ['standard', 'strict']) {
+  const rawProfile = String(process.env.ECC_HOOK_PROFILE || 'standard').toLowerCase();
+  const profile = ['minimal', 'standard', 'strict'].includes(rawProfile) ? rawProfile : 'standard';
+
+  const disabled = new Set(
+    String(process.env.ECC_DISABLED_HOOKS || '')
+      .split(',')
+      .map(v => v.trim().toLowerCase())
+      .filter(Boolean)
+  );
+
+  if (disabled.has(String(hookId || '').toLowerCase())) {
+    return false;
+  }
+
+  return allowedProfiles.includes(profile);
+}
+
+module.exports = { readStdin, getPluginRoot, transformToClaude, runExistingHook, hookEnabled };

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

@@ -1,13 +1,13 @@
 #!/usr/bin/env node
-const { readStdin } = require('./adapter');
+const { readStdin, hookEnabled } = require('./adapter');
+
 readStdin().then(raw => {
   try {
-    const input = JSON.parse(raw);
-    const cmd = input.command || '';
-    const output = input.output || input.result || '';
+    const input = JSON.parse(raw || '{}');
+    const cmd = String(input.command || input.args?.command || '');
+    const output = String(input.output || input.result || '');
 
-    // PR creation logging
-    if (/gh pr create/.test(cmd)) {
+    if (hookEnabled('post:bash:pr-created', ['standard', 'strict']) && /\bgh\s+pr\s+create\b/.test(cmd)) {
       const m = output.match(/https:\/\/github\.com\/[^/]+\/[^/]+\/pull\/\d+/);
       if (m) {
         console.error('[ECC] PR created: ' + m[0]);
@@ -17,10 +17,12 @@ readStdin().then(raw => {
       }
     }
 
-    // Build completion notice
-    if (/(npm run build|pnpm build|yarn build)/.test(cmd)) {
+    if (hookEnabled('post:bash:build-complete', ['standard', 'strict']) && /(npm run build|pnpm build|yarn build)/.test(cmd)) {
       console.error('[ECC] Build completed');
     }
-  } catch {}
+  } catch {
+    // noop
+  }
+
   process.stdout.write(raw);
 }).catch(() => process.exit(0));

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

@@ -1,27 +1,41 @@
 #!/usr/bin/env node
-const { readStdin } = require('./adapter');
-readStdin().then(raw => {
-  try {
-    const input = JSON.parse(raw);
-    const cmd = input.command || '';
+const { readStdin, hookEnabled } = require('./adapter');
+const { splitShellSegments } = require('../../scripts/lib/shell-split');
 
-    // 1. Block dev server outside tmux
-    if (process.platform !== 'win32' && /(npm run dev\b|pnpm( run)? dev\b|yarn dev\b|bun run dev\b)/.test(cmd)) {
-      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);
+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: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
     }
 
-    // 2. Tmux reminder for long-running commands
-    if (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');
-    }
-
-    // 3. Git push review reminder
-    if (/git push/.test(cmd)) {
-      console.error('[ECC] Review changes before push: git diff origin/main...HEAD');
-    }
-  } catch {}
-  process.stdout.write(raw);
-}).catch(() => process.exit(0));
+    process.stdout.write(raw);
+  })
+  .catch(() => process.exit(0));

.cursor/hooks/session-end.js

@@ -1,9 +1,10 @@
 #!/usr/bin/env node
-const { readStdin, runExistingHook, transformToClaude } = require('./adapter');
+const { readStdin, runExistingHook, transformToClaude, hookEnabled } = require('./adapter');
 readStdin().then(raw => {
-  const input = JSON.parse(raw);
+  const input = JSON.parse(raw || '{}');
   const claudeInput = transformToClaude(input);
-  runExistingHook('session-end.js', claudeInput);
-  runExistingHook('evaluate-session.js', claudeInput);
+  if (hookEnabled('session:end:marker', ['minimal', 'standard', 'strict'])) {
+    runExistingHook('session-end-marker.js', claudeInput);
+  }
   process.stdout.write(raw);
 }).catch(() => process.exit(0));

.cursor/hooks/session-start.js

@@ -1,8 +1,10 @@
 #!/usr/bin/env node
-const { readStdin, runExistingHook, transformToClaude } = require('./adapter');
+const { readStdin, runExistingHook, transformToClaude, hookEnabled } = require('./adapter');
 readStdin().then(raw => {
-  const input = JSON.parse(raw);
+  const input = JSON.parse(raw || '{}');
   const claudeInput = transformToClaude(input);
-  runExistingHook('session-start.js', claudeInput);
+  if (hookEnabled('session:start', ['minimal', 'standard', 'strict'])) {
+    runExistingHook('session-start.js', claudeInput);
+  }
   process.stdout.write(raw);
 }).catch(() => process.exit(0));

.cursor/hooks/stop.js

@@ -1,7 +1,21 @@
 #!/usr/bin/env node
-const { readStdin, runExistingHook, transformToClaude } = require('./adapter');
+const { readStdin, runExistingHook, transformToClaude, hookEnabled } = require('./adapter');
 readStdin().then(raw => {
-  const claudeInput = JSON.parse(raw || '{}');
-  runExistingHook('check-console-log.js', transformToClaude(claudeInput));
+  const input = JSON.parse(raw || '{}');
+  const claudeInput = transformToClaude(input);
+
+  if (hookEnabled('stop:check-console-log', ['standard', 'strict'])) {
+    runExistingHook('check-console-log.js', claudeInput);
+  }
+  if (hookEnabled('stop:session-end', ['minimal', 'standard', 'strict'])) {
+    runExistingHook('session-end.js', claudeInput);
+  }
+  if (hookEnabled('stop:evaluate-session', ['minimal', 'standard', 'strict'])) {
+    runExistingHook('evaluate-session.js', claudeInput);
+  }
+  if (hookEnabled('stop:cost-tracker', ['minimal', 'standard', 'strict'])) {
+    runExistingHook('cost-tracker.js', claudeInput);
+  }
+
   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.

.cursor/skills/bun-runtime/SKILL.md

@@ -0,0 +1,84 @@
+---
+name: bun-runtime
+description: Bun as runtime, package manager, bundler, and test runner. When to choose Bun vs Node, migration notes, and Vercel support.
+origin: ECC
+---
+
+# Bun Runtime
+
+Bun is a fast all-in-one JavaScript runtime and toolkit: runtime, package manager, bundler, and test runner.
+
+## When to Use
+
+- **Prefer Bun** for: new JS/TS projects, scripts where install/run speed matters, Vercel deployments with Bun runtime, and when you want a single toolchain (run + install + test + build).
+- **Prefer Node** for: maximum ecosystem compatibility, legacy tooling that assumes Node, or when a dependency has known Bun issues.
+
+Use when: adopting Bun, migrating from Node, writing or debugging Bun scripts/tests, or configuring Bun on Vercel or other platforms.
+
+## How It Works
+
+- **Runtime**: Drop-in Node-compatible runtime (built on JavaScriptCore, implemented in Zig).
+- **Package manager**: `bun install` is significantly faster than npm/yarn. Lockfile is `bun.lock` (text) by default in current Bun; older versions used `bun.lockb` (binary).
+- **Bundler**: Built-in bundler and transpiler for apps and libraries.
+- **Test runner**: Built-in `bun test` with Jest-like API.
+
+**Migration from Node**: Replace `node script.js` with `bun run script.js` or `bun script.js`. Run `bun install` in place of `npm install`; most packages work. Use `bun run` for npm scripts; `bun x` for npx-style one-off runs. Node built-ins are supported; prefer Bun APIs where they exist for better performance.
+
+**Vercel**: Set runtime to Bun in project settings. Build: `bun run build` or `bun build ./src/index.ts --outdir=dist`. Install: `bun install --frozen-lockfile` for reproducible deploys.
+
+## Examples
+
+### Run and install
+
+```bash
+# Install dependencies (creates/updates bun.lock or bun.lockb)
+bun install
+
+# Run a script or file
+bun run dev
+bun run src/index.ts
+bun src/index.ts
+```
+
+### Scripts and env
+
+```bash
+bun run --env-file=.env dev
+FOO=bar bun run script.ts
+```
+
+### Testing
+
+```bash
+bun test
+bun test --watch
+```
+
+```typescript
+// test/example.test.ts
+import { expect, test } from "bun:test";
+
+test("add", () => {
+  expect(1 + 2).toBe(3);
+});
+```
+
+### Runtime API
+
+```typescript
+const file = Bun.file("package.json");
+const json = await file.json();
+
+Bun.serve({
+  port: 3000,
+  fetch(req) {
+    return new Response("Hello");
+  },
+});
+```
+
+## Best Practices
+
+- Commit the lockfile (`bun.lock` or `bun.lockb`) for reproducible installs.
+- Prefer `bun run` for scripts. For TypeScript, Bun runs `.ts` natively.
+- Keep dependencies up to date; Bun and the ecosystem evolve quickly.

.cursor/skills/documentation-lookup/SKILL.md

@@ -0,0 +1,90 @@
+---
+name: documentation-lookup
+description: Use up-to-date library and framework docs via Context7 MCP instead of training data. Activates for setup questions, API references, code examples, or when the user names a framework (e.g. React, Next.js, Prisma).
+origin: ECC
+---
+
+# Documentation Lookup (Context7)
+
+When the user asks about libraries, frameworks, or APIs, fetch current documentation via the Context7 MCP (tools `resolve-library-id` and `query-docs`) instead of relying on training data.
+
+## Core Concepts
+
+- **Context7**: MCP server that exposes live documentation; use it instead of training data for libraries and APIs.
+- **resolve-library-id**: Returns Context7-compatible library IDs (e.g. `/vercel/next.js`) from a library name and query.
+- **query-docs**: Fetches documentation and code snippets for a given library ID and question. Always call resolve-library-id first to get a valid library ID.
+
+## When to use
+
+Activate when the user:
+
+- Asks setup or configuration questions (e.g. "How do I configure Next.js middleware?")
+- Requests code that depends on a library ("Write a Prisma query for...")
+- Needs API or reference information ("What are the Supabase auth methods?")
+- Mentions specific frameworks or libraries (React, Vue, Svelte, Express, Tailwind, Prisma, Supabase, etc.)
+
+Use this skill whenever the request depends on accurate, up-to-date behavior of a library, framework, or API. Applies across harnesses that have the Context7 MCP configured (e.g. Claude Code, Cursor, Codex).
+
+## How it works
+
+### Step 1: Resolve the Library ID
+
+Call the **resolve-library-id** MCP tool with:
+
+- **libraryName**: The library or product name taken from the user's question (e.g. `Next.js`, `Prisma`, `Supabase`).
+- **query**: The user's full question. This improves relevance ranking of results.
+
+You must obtain a Context7-compatible library ID (format `/org/project` or `/org/project/version`) before querying docs. Do not call query-docs without a valid library ID from this step.
+
+### Step 2: Select the Best Match
+
+From the resolution results, choose one result using:
+
+- **Name match**: Prefer exact or closest match to what the user asked for.
+- **Benchmark score**: Higher scores indicate better documentation quality (100 is highest).
+- **Source reputation**: Prefer High or Medium reputation when available.
+- **Version**: If the user specified a version (e.g. "React 19", "Next.js 15"), prefer a version-specific library ID if listed (e.g. `/org/project/v1.2.0`).
+
+### Step 3: Fetch the Documentation
+
+Call the **query-docs** MCP tool with:
+
+- **libraryId**: The selected Context7 library ID from Step 2 (e.g. `/vercel/next.js`).
+- **query**: The user's specific question or task. Be specific to get relevant snippets.
+
+Limit: do not call query-docs (or resolve-library-id) more than 3 times per question. If the answer is unclear after 3 calls, state the uncertainty and use the best information you have rather than guessing.
+
+### Step 4: Use the Documentation
+
+- Answer the user's question using the fetched, current information.
+- Include relevant code examples from the docs when helpful.
+- Cite the library or version when it matters (e.g. "In Next.js 15...").
+
+## Examples
+
+### Example: Next.js middleware
+
+1. Call **resolve-library-id** with `libraryName: "Next.js"`, `query: "How do I set up Next.js middleware?"`.
+2. From results, pick the best match (e.g. `/vercel/next.js`) by name and benchmark score.
+3. Call **query-docs** with `libraryId: "/vercel/next.js"`, `query: "How do I set up Next.js middleware?"`.
+4. Use the returned snippets and text to answer; include a minimal `middleware.ts` example from the docs if relevant.
+
+### Example: Prisma query
+
+1. Call **resolve-library-id** with `libraryName: "Prisma"`, `query: "How do I query with relations?"`.
+2. Select the official Prisma library ID (e.g. `/prisma/prisma`).
+3. Call **query-docs** with that `libraryId` and the query.
+4. Return the Prisma Client pattern (e.g. `include` or `select`) with a short code snippet from the docs.
+
+### Example: Supabase auth methods
+
+1. Call **resolve-library-id** with `libraryName: "Supabase"`, `query: "What are the auth methods?"`.
+2. Pick the Supabase docs library ID.
+3. Call **query-docs**; summarize the auth methods and show minimal examples from the fetched docs.
+
+## Best Practices
+
+- **Be specific**: Use the user's full question as the query where possible for better relevance.
+- **Version awareness**: When users mention versions, use version-specific library IDs from the resolve step when available.
+- **Prefer official sources**: When multiple matches exist, prefer official or primary packages over community forks.
+- **No sensitive data**: Redact API keys, passwords, tokens, and other secrets from any query sent to Context7. Treat the user's question as potentially containing secrets before passing it to resolve-library-id or query-docs.

.cursor/skills/mcp-server-patterns/SKILL.md

@@ -0,0 +1,67 @@
+---
+name: mcp-server-patterns
+description: Build MCP servers with Node/TypeScript SDK — tools, resources, prompts, Zod validation, stdio vs Streamable HTTP. Use Context7 or official MCP docs for latest API.
+origin: ECC
+---
+
+# MCP Server Patterns
+
+The Model Context Protocol (MCP) lets AI assistants call tools, read resources, and use prompts from your server. Use this skill when building or maintaining MCP servers. The SDK API evolves; check Context7 (query-docs for "MCP") or the official MCP documentation for current method names and signatures.
+
+## When to Use
+
+Use when: implementing a new MCP server, adding tools or resources, choosing stdio vs HTTP, upgrading the SDK, or debugging MCP registration and transport issues.
+
+## How It Works
+
+### Core concepts
+
+- **Tools**: Actions the model can invoke (e.g. search, run a command). Register with `registerTool()` or `tool()` depending on SDK version.
+- **Resources**: Read-only data the model can fetch (e.g. file contents, API responses). Register with `registerResource()` or `resource()`. Handlers typically receive a `uri` argument.
+- **Prompts**: Reusable, parameterised prompt templates the client can surface (e.g. in Claude Desktop). Register with `registerPrompt()` or equivalent.
+- **Transport**: stdio for local clients (e.g. Claude Desktop); Streamable HTTP is preferred for remote (Cursor, cloud). Legacy HTTP/SSE is for backward compatibility.
+
+The Node/TypeScript SDK may expose `tool()` / `resource()` or `registerTool()` / `registerResource()`; the official SDK has changed over time. Always verify against the current [MCP docs](https://modelcontextprotocol.io) or Context7.
+
+### Connecting with stdio
+
+For local clients, create a stdio transport and pass it to your server’s connect method. The exact API varies by SDK version (e.g. constructor vs factory). See the official MCP documentation or query Context7 for "MCP stdio server" for the current pattern.
+
+Keep server logic (tools + resources) independent of transport so you can plug in stdio or HTTP in the entrypoint.
+
+### Remote (Streamable HTTP)
+
+For Cursor, cloud, or other remote clients, use **Streamable HTTP** (single MCP HTTP endpoint per current spec). Support legacy HTTP/SSE only when backward compatibility is required.
+
+## Examples
+
+### Install and server setup
+
+```bash
+npm install @modelcontextprotocol/sdk zod
+```
+
+```typescript
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { z } from "zod";
+
+const server = new McpServer({ name: "my-server", version: "1.0.0" });
+```
+
+Register tools and resources using the API your SDK version provides: some versions use `server.tool(name, description, schema, handler)` (positional args), others use `server.tool({ name, description, inputSchema }, handler)` or `registerTool()`. Same for resources — include a `uri` in the handler when the API provides it. Check the official MCP docs or Context7 for the current `@modelcontextprotocol/sdk` signatures to avoid copy-paste errors.
+
+Use **Zod** (or the SDK’s preferred schema format) for input validation.
+
+## Best Practices
+
+- **Schema first**: Define input schemas for every tool; document parameters and return shape.
+- **Errors**: Return structured errors or messages the model can interpret; avoid raw stack traces.
+- **Idempotency**: Prefer idempotent tools where possible so retries are safe.
+- **Rate and cost**: For tools that call external APIs, consider rate limits and cost; document in the tool description.
+- **Versioning**: Pin SDK version in package.json; check release notes when upgrading.
+
+## Official SDKs and Docs
+
+- **JavaScript/TypeScript**: `@modelcontextprotocol/sdk` (npm). Use Context7 with library name "MCP" for current registration and transport patterns.
+- **Go**: Official Go SDK on GitHub (`modelcontextprotocol/go-sdk`).
+- **C#**: Official C# SDK for .NET.

.cursor/skills/nextjs-turbopack/SKILL.md

@@ -0,0 +1,44 @@
+---
+name: nextjs-turbopack
+description: Next.js 16+ and Turbopack — incremental bundling, FS caching, dev speed, and when to use Turbopack vs webpack.
+origin: ECC
+---
+
+# Next.js and Turbopack
+
+Next.js 16+ uses Turbopack by default for local development: an incremental bundler written in Rust that significantly speeds up dev startup and hot updates.
+
+## When to Use
+
+- **Turbopack (default dev)**: Use for day-to-day development. Faster cold start and HMR, especially in large apps.
+- **Webpack (legacy dev)**: Use only if you hit a Turbopack bug or rely on a webpack-only plugin in dev. Disable with `--webpack` (or `--no-turbopack` depending on your Next.js version; check the docs for your release).
+- **Production**: Production build behavior (`next build`) may use Turbopack or webpack depending on Next.js version; check the official Next.js docs for your version.
+
+Use when: developing or debugging Next.js 16+ apps, diagnosing slow dev startup or HMR, or optimizing production bundles.
+
+## How It Works
+
+- **Turbopack**: Incremental bundler for Next.js dev. Uses file-system caching so restarts are much faster (e.g. 5–14x on large projects).
+- **Default in dev**: From Next.js 16, `next dev` runs with Turbopack unless disabled.
+- **File-system caching**: Restarts reuse previous work; cache is typically under `.next`; no extra config needed for basic use.
+- **Bundle Analyzer (Next.js 16.1+)**: Experimental Bundle Analyzer to inspect output and find heavy dependencies; enable via config or experimental flag (see Next.js docs for your version).
+
+## Examples
+
+### Commands
+
+```bash
+next dev
+next build
+next start
+```
+
+### Usage
+
+Run `next dev` for local development with Turbopack. Use the Bundle Analyzer (see Next.js docs) to optimize code-splitting and trim large dependencies. Prefer App Router and server components where possible.
+
+## Best Practices
+
+- Stay on a recent Next.js 16.x for stable Turbopack and caching behavior.
+- If dev is slow, ensure you're on Turbopack (default) and that the cache isn't being cleared unnecessarily.
+- For production bundle size issues, use the official Next.js bundle analysis tooling for your version.

.env.example

@@ -0,0 +1,38 @@
+# .env.example — Canonical list of required environment variables
+# Copy this file to .env and fill in real values.
+# NEVER commit .env to version control.
+#
+# Usage:
+#   cp .env.example .env
+#   # Then edit .env with your actual values
+
+# ─── Anthropic ────────────────────────────────────────────────────────────────
+# Your Anthropic API key (https://console.anthropic.com)
+ANTHROPIC_API_KEY=
+
+# ─── GitHub ───────────────────────────────────────────────────────────────────
+# GitHub personal access token (for MCP GitHub server)
+GITHUB_TOKEN=
+
+# ─── Optional: Docker platform override ──────────────────────────────────────
+# DOCKER_PLATFORM=linux/arm64  # or linux/amd64 for Intel Macs / CI
+
+# ─── Optional: Package manager override ──────────────────────────────────────
+# CLAUDE_CODE_PACKAGE_MANAGER=npm  # npm | pnpm | yarn | bun
+
+# ─── Session & Security ─────────────────────────────────────────────────────
+# GitHub username (used by CI scripts for credential context)
+GITHUB_USER="your-github-username"
+
+# Primary development branch for CI diff-based checks
+DEFAULT_BASE_BRANCH="main"
+
+# Path to session-start.sh (used by test/test_session_start.sh)
+SESSION_SCRIPT="./session-start.sh"
+
+# Path to generated MCP configuration file
+CONFIG_FILE="./mcp-config.json"
+
+# ─── Optional: Verbose Logging ──────────────────────────────────────────────
+# Enable verbose logging for session and CI scripts
+ENABLE_VERBOSE_LOGGING="false"

.github/FUNDING.yml

@@ -1,15 +1,2 @@
-# These are supported funding model platforms
-
-github: [affaan-m]
-# patreon: # Replace with a single Patreon username
-# open_collective: # Replace with a single Open Collective username
-# ko_fi: # Replace with a single Ko-fi username
-# tidelift: # Replace with a single Tidelift platform-name/package-name e.g., npm/babel
-# community_bridge: # Replace with a single Community Bridge project-name e.g., cloud-hierarchical-namespace-controller
-# liberapay: # Replace with a single Liberapay username
-# issuehunt: # Replace with a single IssueHunt username
-# lfx_crowdfunding: # Replace with a single LFX Crowdfunding project-name e.g., cloud-hierarchical-namespace-controller
-# polar: # Replace with a single Polar username
-# buy_me_a_coffee: # Replace with a single Buy Me a Coffee username
-# thanks_dev: # Replace with a single thanks.dev username
+github: affaan-m
 custom: ['https://ecc.tools']

.github/ISSUE_TEMPLATE/copilot-task.md

@@ -0,0 +1,17 @@
+---
+name: Copilot Task
+about: Assign a coding task to GitHub Copilot agent
+title: "[Copilot] "
+labels: copilot
+assignees: copilot
+---
+
+## Task Description
+<!-- What should Copilot do? Be specific. -->
+
+## Acceptance Criteria
+- [ ] ...
+- [ ] ...
+
+## Context
+<!-- Any relevant files, APIs, or constraints Copilot should know about -->

.github/PULL_REQUEST_TEMPLATE.md

@@ -1,5 +1,14 @@
-## Description
-<!-- Brief description of changes -->
+## What Changed
+<!-- Describe the specific changes made in this PR -->
+
+## Why This Change
+<!-- Explain the motivation and context for this change -->
+
+## Testing Done
+<!-- Describe the testing you performed to validate your changes -->
+- [ ] Manual testing completed
+- [ ] Automated tests pass locally (`node tests/run-all.js`)
+- [ ] Edge cases considered and tested
 
 ## Type of Change
 - [ ] `fix:` Bug fix
@@ -10,8 +19,15 @@
 - [ ] `chore:` Maintenance/tooling
 - [ ] `ci:` CI/CD changes
 
-## Checklist
-- [ ] Tests pass locally (`node tests/run-all.js`)
-- [ ] Validation scripts pass
+## Security & Quality Checklist
+- [ ] No secrets or API keys committed (ghp_, sk-, AKIA, xoxb, xoxp patterns checked)
+- [ ] JSON files validate cleanly
+- [ ] Shell scripts pass shellcheck (if applicable)
+- [ ] Pre-commit hooks pass locally (if configured)
+- [ ] No sensitive data exposed in logs or output
 - [ ] Follows conventional commits format
+
+## Documentation
 - [ ] Updated relevant documentation
+- [ ] Added comments for complex logic
+- [ ] README updated (if needed)

.github/release.yml

@@ -0,0 +1,20 @@
+changelog:
+  categories:
+    - title: Core Harness
+      labels:
+        - enhancement
+        - feature
+    - title: Reliability & Bug Fixes
+      labels:
+        - bug
+        - fix
+    - title: Docs & Guides
+      labels:
+        - docs
+    - title: Tooling & CI
+      labels:
+        - ci
+        - chore
+  exclude:
+    labels:
+      - skip-changelog

.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
@@ -176,6 +179,10 @@ jobs:
         run: node scripts/ci/validate-rules.js
         continue-on-error: false
 
+      - name: Validate catalog counts
+        run: node scripts/ci/catalog.js --text
+        continue-on-error: false
+
   security:
     name: Security Scan
     runs-on: ubuntu-latest

.github/workflows/copilot-setup-steps.yml

@@ -1,18 +0,0 @@
-steps:
-  - name: Setup Go environment
-    uses: actions/setup-go@v6.2.0
-    with:
-      # The Go version to download (if necessary) and use. Supports semver spec and ranges. Be sure to enclose this option in single quotation marks.
-      go-version: # optional
-      # Path to the go.mod, go.work, .go-version, or .tool-versions file.
-      go-version-file: # optional
-      # Set this option to true if you want the action to always check for the latest available version that satisfies the version spec
-      check-latest: # optional
-      # Used to pull Go distributions from go-versions. Since there's a default, this is typically not supplied by the user. When running this action on github.com, the default value is sufficient. When running on GHES, you can pass a personal access token for github.com if you are experiencing rate limiting.
-      token: # optional, default is ${{ github.server_url == 'https://github.com' && github.token || '' }}
-      # Used to specify whether caching is needed. Set to true, if you'd like to enable caching.
-      cache: # optional, default is true
-      # Used to specify the path to a dependency file - go.sum
-      cache-dependency-path: # optional
-      # Target architecture for Go to use. Examples: x86, x64. Will use system architecture by default.
-      architecture: # optional

.github/workflows/monthly-metrics.yml

@@ -0,0 +1,185 @@
+name: Monthly Metrics Snapshot
+
+on:
+  schedule:
+    - cron: '0 14 1 * *' # Monthly on the 1st at 14:00 UTC
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  issues: write
+
+jobs:
+  snapshot:
+    name: Update metrics issue
+    runs-on: ubuntu-latest
+    steps:
+      - name: Update monthly metrics issue
+        uses: actions/github-script@v7
+        with:
+          script: |
+            const owner = context.repo.owner;
+            const repo = context.repo.repo;
+            const title = "Monthly Metrics Snapshot";
+            const label = "metrics-snapshot";
+            const monthKey = new Date().toISOString().slice(0, 7);
+
+            function parseLastPage(linkHeader) {
+              if (!linkHeader) return null;
+              const match = linkHeader.match(/&page=(\d+)>; rel="last"/);
+              return match ? Number(match[1]) : null;
+            }
+
+            function fmt(value) {
+              if (value === null || value === undefined) return "n/a";
+              return Number(value).toLocaleString("en-US");
+            }
+
+            async function getNpmDownloads(range, pkg) {
+              try {
+                const res = await fetch(`https://api.npmjs.org/downloads/point/${range}/${pkg}`);
+                if (!res.ok) return null;
+                const data = await res.json();
+                return data.downloads ?? null;
+              } catch {
+                return null;
+              }
+            }
+
+            async function getContributorsCount() {
+              try {
+                const resp = await github.rest.repos.listContributors({
+                  owner,
+                  repo,
+                  per_page: 1,
+                  anon: "false"
+                });
+                return parseLastPage(resp.headers.link) ?? resp.data.length;
+              } catch {
+                return null;
+              }
+            }
+
+            async function getReleasesCount() {
+              try {
+                const resp = await github.rest.repos.listReleases({
+                  owner,
+                  repo,
+                  per_page: 1
+                });
+                return parseLastPage(resp.headers.link) ?? resp.data.length;
+              } catch {
+                return null;
+              }
+            }
+
+            async function getTraffic(metric) {
+              try {
+                const route = metric === "clones"
+                  ? "GET /repos/{owner}/{repo}/traffic/clones"
+                  : "GET /repos/{owner}/{repo}/traffic/views";
+                const resp = await github.request(route, { owner, repo });
+                return resp.data?.count ?? null;
+              } catch {
+                return null;
+              }
+            }
+
+            const [
+              mainWeek,
+              shieldWeek,
+              mainMonth,
+              shieldMonth,
+              repoData,
+              contributors,
+              releases,
+              views14d,
+              clones14d
+            ] = await Promise.all([
+              getNpmDownloads("last-week", "ecc-universal"),
+              getNpmDownloads("last-week", "ecc-agentshield"),
+              getNpmDownloads("last-month", "ecc-universal"),
+              getNpmDownloads("last-month", "ecc-agentshield"),
+              github.rest.repos.get({ owner, repo }),
+              getContributorsCount(),
+              getReleasesCount(),
+              getTraffic("views"),
+              getTraffic("clones")
+            ]);
+
+            const stars = repoData.data.stargazers_count;
+            const forks = repoData.data.forks_count;
+
+            const tableHeader = [
+              "| Month (UTC) | ecc-universal (week) | ecc-agentshield (week) | ecc-universal (30d) | ecc-agentshield (30d) | Stars | Forks | Contributors | GitHub App installs (manual) | Views (14d) | Clones (14d) | Releases |",
+              "|---|---:|---:|---:|---:|---:|---:|---:|---:|---:|---:|---:|"
+            ].join("\n");
+
+            const row = `| ${monthKey} | ${fmt(mainWeek)} | ${fmt(shieldWeek)} | ${fmt(mainMonth)} | ${fmt(shieldMonth)} | ${fmt(stars)} | ${fmt(forks)} | ${fmt(contributors)} | n/a | ${fmt(views14d)} | ${fmt(clones14d)} | ${fmt(releases)} |`;
+
+            const intro = [
+              "# Monthly Metrics Snapshot",
+              "",
+              "Automated monthly snapshot for sponsor/partner reporting.",
+              "",
+              "- `GitHub App installs (manual)` is intentionally manual until a stable public API path is available.",
+              "- Traffic metrics are 14-day rolling windows from the GitHub traffic API and can show `n/a` if unavailable.",
+              "",
+              tableHeader
+            ].join("\n");
+
+            try {
+              await github.rest.issues.getLabel({ owner, repo, name: label });
+            } catch (error) {
+              if (error.status === 404) {
+                await github.rest.issues.createLabel({
+                  owner,
+                  repo,
+                  name: label,
+                  color: "0e8a16",
+                  description: "Automated monthly project metrics snapshots"
+                });
+              } else {
+                throw error;
+              }
+            }
+
+            const issuesResp = await github.rest.issues.listForRepo({
+              owner,
+              repo,
+              state: "open",
+              labels: label,
+              per_page: 100
+            });
+
+            let issue = issuesResp.data.find((item) => item.title === title);
+
+            if (!issue) {
+              const created = await github.rest.issues.create({
+                owner,
+                repo,
+                title,
+                labels: [label],
+                body: `${intro}\n${row}\n`
+              });
+              console.log(`Created issue #${created.data.number}`);
+              return;
+            }
+
+            const currentBody = issue.body || "";
+            if (currentBody.includes(`| ${monthKey} |`)) {
+              console.log(`Issue #${issue.number} already has snapshot row for ${monthKey}`);
+              return;
+            }
+
+            const body = currentBody.includes("| Month (UTC) |")
+              ? `${currentBody.trimEnd()}\n${row}\n`
+              : `${intro}\n${row}\n`;
+
+            await github.rest.issues.update({
+              owner,
+              repo,
+              issue_number: issue.number,
+              body
+            });
+            console.log(`Updated issue #${issue.number}`);

.github/workflows/release.yml

@@ -37,23 +37,31 @@ jobs:
             exit 1
           fi
 
-      - name: Generate changelog
-        id: changelog
+      - name: Generate release highlights
+        id: highlights
+        env:
+          TAG_NAME: ${{ github.ref_name }}
         run: |
-          PREV_TAG=$(git describe --tags --abbrev=0 HEAD^ 2>/dev/null || echo "")
-          if [ -z "$PREV_TAG" ]; then
-            COMMITS=$(git log --pretty=format:"- %s" HEAD)
-          else
-            COMMITS=$(git log --pretty=format:"- %s" ${PREV_TAG}..HEAD)
-          fi
-          echo "commits<<EOF" >> $GITHUB_OUTPUT
-          echo "$COMMITS" >> $GITHUB_OUTPUT
-          echo "EOF" >> $GITHUB_OUTPUT
+          TAG_VERSION="${TAG_NAME#v}"
+          cat > release_body.md <<EOF
+          ## ECC ${TAG_VERSION}
+
+          ### What This Release Focuses On
+          - Harness reliability and hook stability across Claude Code, Cursor, OpenCode, and Codex
+          - Stronger eval-driven workflows and quality gates
+          - Better operator UX for autonomous loop execution
+
+          ### Notable Changes
+          - Session persistence and hook lifecycle fixes
+          - Expanded skills and command coverage for harness performance work
+          - Improved release-note generation and changelog hygiene
+
+          ### Notes
+          - For migration tips and compatibility notes, see README and CHANGELOG.
+          EOF
 
       - name: Create GitHub Release
         uses: softprops/action-gh-release@v2
         with:
-          body: |
-            ## Changes
-            ${{ steps.changelog.outputs.commits }}
-          generate_release_notes: false
+          body_path: release_body.md
+          generate_release_notes: true

.github/workflows/reusable-release.yml

@@ -34,26 +34,23 @@ jobs:
             exit 1
           fi
 
-      - name: Generate changelog
-        id: changelog
+      - name: Generate release highlights
+        env:
+          TAG_NAME: ${{ inputs.tag }}
         run: |
-          PREV_TAG=$(git describe --tags --abbrev=0 HEAD^ 2>/dev/null || echo "")
-          if [ -z "$PREV_TAG" ]; then
-            COMMITS=$(git log --pretty=format:"- %s" HEAD)
-          else
-            COMMITS=$(git log --pretty=format:"- %s" ${PREV_TAG}..HEAD)
-          fi
-          # Use unique delimiter to prevent truncation if commit messages contain EOF
-          DELIMITER="COMMITS_END_$(date +%s)"
-          echo "commits<<${DELIMITER}" >> $GITHUB_OUTPUT
-          echo "$COMMITS" >> $GITHUB_OUTPUT
-          echo "${DELIMITER}" >> $GITHUB_OUTPUT
+          TAG_VERSION="${TAG_NAME#v}"
+          cat > release_body.md <<EOF
+          ## ECC ${TAG_VERSION}
+
+          ### What This Release Focuses On
+          - Harness reliability and cross-platform compatibility
+          - Eval-driven quality improvements
+          - Better workflow and operator ergonomics
+          EOF
 
       - name: Create GitHub Release
         uses: softprops/action-gh-release@v2
         with:
           tag_name: ${{ inputs.tag }}
-          body: |
-            ## Changes
-            ${{ steps.changelog.outputs.commits }}
+          body_path: release_body.md
           generate_release_notes: ${{ inputs.generate-notes }}

.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

@@ -2,27 +2,61 @@
 .env
 .env.local
 .env.*.local
+.env.development
+.env.test
+.env.production
 
-# API keys
+# API keys and secrets
 *.key
 *.pem
 secrets.json
+config/secrets.yml
+.secrets
 
 # OS files
 .DS_Store
+.DS_Store?
+._*
+.Spotlight-V100
+.Trashes
+ehthumbs.db
 Thumbs.db
+Desktop.ini
 
 # Editor files
 .idea/
 .vscode/
 *.swp
 *.swo
+*~
+.project
+.classpath
+.settings/
+*.sublime-project
+*.sublime-workspace
 
 # Node
 node_modules/
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+.pnpm-debug.log*
+.yarn/
+lerna-debug.log*
 
-# Build output
+# Build outputs
 dist/
+build/
+*.tsbuildinfo
+.cache/
+
+# Test coverage
+coverage/
+.nyc_output/
+
+# Logs
+logs/
+*.log
 
 # Python
 __pycache__/
@@ -40,3 +74,16 @@ examples/sessions/*.tmp
 
 # Local drafts
 marketing/
+.dmux/
+
+# Temporary files
+tmp/
+temp/
+*.tmp
+*.bak
+*.backup
+
+# Bootstrap pipeline outputs
+# Generated lock files in tool subdirectories
+.opencode/package-lock.json
+.opencode/node_modules/

.markdownlint.json

@@ -1,5 +1,7 @@
 {
+  "globs": ["**/*.md", "!**/node_modules/**"],
   "default": true,
+  "MD009": { "br_spaces": 2, "strict": false },
   "MD013": false,
   "MD033": false,
   "MD041": false,
@@ -14,4 +16,4 @@
   "MD024": {
     "siblings_only": true
   }
-}
+}

.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"
   ]
@@ -258,6 +258,8 @@ After migration, ALL 23 commands are available:
 | `/instinct-import` | Import instincts |
 | `/instinct-export` | Export instincts |
 | `/evolve` | Cluster instincts into skills |
+| `/promote` | Promote project instincts to global scope |
+| `/projects` | List known projects and instinct stats |
 
 ## Available Agents
 
@@ -295,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
@@ -320,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
@@ -67,7 +76,7 @@ opencode
 | go-build-resolver | Go build errors |
 | database-reviewer | Database optimization |
 
-### Commands (24)
+### Commands (31)
 
 | Command | Description |
 |---------|-------------|
@@ -95,6 +104,13 @@ opencode
 | `/instinct-import` | Import instincts |
 | `/instinct-export` | Export instincts |
 | `/evolve` | Cluster instincts |
+| `/promote` | Promote project instincts |
+| `/projects` | List known projects |
+| `/harness-audit` | Audit harness reliability and eval readiness |
+| `/loop-start` | Start controlled agentic loops |
+| `/loop-status` | Check loop state and checkpoints |
+| `/quality-gate` | Run quality gates on file/repo scope |
+| `/model-route` | Route tasks by model and budget |
 
 ### Plugin Hooks
 
@@ -128,6 +144,18 @@ OpenCode's plugin system maps to Claude Code hooks:
 
 OpenCode has 20+ additional events not available in Claude Code.
 
+### Hook Runtime Controls
+
+OpenCode plugin hooks honor the same runtime controls used by Claude Code/Cursor:
+
+```bash
+export ECC_HOOK_PROFILE=standard
+export ECC_DISABLED_HOOKS="pre:bash:tmux-reminder,post:edit:typecheck"
+```
+
+- `ECC_HOOK_PROFILE`: `minimal`, `standard` (default), `strict`
+- `ECC_DISABLED_HOOKS`: comma-separated hook IDs to disable
+
 ## Skills
 
 The default OpenCode config loads 11 curated ECC skills via the `instructions` array:
@@ -161,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/commands/evolve.md

@@ -1,112 +1,36 @@
 ---
-description: Cluster instincts into skills
+description: Analyze instincts and suggest or generate evolved structures
 agent: build
 ---
 
 # Evolve Command
 
-Cluster related instincts into structured skills: $ARGUMENTS
+Analyze and evolve instincts in continuous-learning-v2: $ARGUMENTS
 
 ## Your Task
 
-Analyze instincts and promote clusters to skills.
+Run:
 
-## Evolution Process
-
-### Step 1: Analyze Instincts
-
-Group instincts by:
-- Trigger similarity
-- Action patterns
-- Category tags
-- Confidence levels
-
-### Step 2: Identify Clusters
-
-```
-Cluster: Error Handling
-├── Instinct: Catch specific errors (0.85)
-├── Instinct: Wrap errors with context (0.82)
-├── Instinct: Log errors with stack trace (0.78)
-└── Instinct: Return meaningful error messages (0.80)
+```bash
+python3 "${CLAUDE_PLUGIN_ROOT}/skills/continuous-learning-v2/scripts/instinct-cli.py" evolve $ARGUMENTS
 ```
 
-### Step 3: Generate Skill
+If `CLAUDE_PLUGIN_ROOT` is unavailable, use:
 
-When cluster has:
-- 3+ instincts
-- Average confidence > 0.75
-- Cohesive theme
-
-Generate SKILL.md:
-
-```markdown
-# Error Handling Skill
-
-## Overview
-Patterns for robust error handling learned from session observations.
-
-## Patterns
-
-### 1. Catch Specific Errors
-**Trigger**: When catching errors with generic catch
-**Action**: Use specific error types
-
-### 2. Wrap Errors with Context
-**Trigger**: When re-throwing errors
-**Action**: Add context with fmt.Errorf or Error.cause
-
-### 3. Log with Stack Trace
-**Trigger**: When logging errors
-**Action**: Include stack trace for debugging
-
-### 4. Meaningful Messages
-**Trigger**: When returning errors to users
-**Action**: Provide actionable error messages
+```bash
+python3 ~/.claude/skills/continuous-learning-v2/scripts/instinct-cli.py evolve $ARGUMENTS
 ```
 
-### Step 4: Archive Instincts
+## Supported Args (v2.1)
 
-Move evolved instincts to `archived/` with reference to skill.
+- no args: analysis only
+- `--generate`: also generate files under `evolved/{skills,commands,agents}`
 
-## Evolution Report
+## Behavior Notes
 
-```
-Evolution Summary
-=================
-
-Clusters Found: X
-
-Cluster 1: Error Handling
-- Instincts: 5
-- Avg Confidence: 0.82
-- Status: ✅ Promoted to skill
-
-Cluster 2: Testing Patterns
-- Instincts: 3
-- Avg Confidence: 0.71
-- Status: ⏳ Needs more confidence
-
-Cluster 3: Git Workflow
-- Instincts: 2
-- Avg Confidence: 0.88
-- Status: ⏳ Needs more instincts
-
-Skills Created:
-- skills/error-handling/SKILL.md
-
-Instincts Archived: 5
-Remaining Instincts: 12
-```
-
-## Thresholds
-
-| Metric | Threshold |
-|--------|-----------|
-| Min instincts per cluster | 3 |
-| Min average confidence | 0.75 |
-| Min cluster cohesion | 0.6 |
-
----
-
-**TIP**: Run `/evolve` periodically to graduate instincts to skills as confidence grows.
+- Uses project + global instincts for analysis.
+- Shows skill/command/agent candidates from trigger and domain clustering.
+- Shows project -> global promotion candidates.
+- With `--generate`, output path is:
+  - project context: `~/.claude/homunculus/projects/<project-id>/evolved/`
+  - global fallback: `~/.claude/homunculus/evolved/`

.opencode/commands/harness-audit.md

@@ -0,0 +1,71 @@
+# Harness Audit Command
+
+Run a deterministic repository harness audit and return a prioritized scorecard.
+
+## Usage
+
+`/harness-audit [scope] [--format text|json]`
+
+- `scope` (optional): `repo` (default), `hooks`, `skills`, `commands`, `agents`
+- `--format`: output style (`text` default, `json` for automation)
+
+## Deterministic Engine
+
+Always run:
+
+```bash
+node scripts/harness-audit.js <scope> --format <text|json>
+```
+
+This script is the source of truth for scoring and checks. Do not invent additional dimensions or ad-hoc points.
+
+Rubric version: `2026-03-16`.
+
+The script computes 7 fixed categories (`0-10` normalized each):
+
+1. Tool Coverage
+2. Context Efficiency
+3. Quality Gates
+4. Memory Persistence
+5. Eval Coverage
+6. Security Guardrails
+7. Cost Efficiency
+
+Scores are derived from explicit file/rule checks and are reproducible for the same commit.
+
+## Output Contract
+
+Return:
+
+1. `overall_score` out of `max_score` (70 for `repo`; smaller for scoped audits)
+2. Category scores and concrete findings
+3. Failed checks with exact file paths
+4. Top 3 actions from the deterministic output (`top_actions`)
+5. Suggested ECC skills to apply next
+
+## Checklist
+
+- Use script output directly; do not rescore manually.
+- If `--format json` is requested, return the script JSON unchanged.
+- If text is requested, summarize failing checks and top actions.
+- Include exact file paths from `checks[]` and `top_actions[]`.
+
+## Example Result
+
+```text
+Harness Audit (repo): 66/70
+- Tool Coverage: 10/10 (10/10 pts)
+- Context Efficiency: 9/10 (9/10 pts)
+- Quality Gates: 10/10 (10/10 pts)
+
+Top 3 Actions:
+1) [Security Guardrails] Add prompt/tool preflight security guards in hooks/hooks.json. (hooks/hooks.json)
+2) [Tool Coverage] Sync commands/harness-audit.md and .opencode/commands/harness-audit.md. (.opencode/commands/harness-audit.md)
+3) [Eval Coverage] Increase automated test coverage across scripts/hooks/lib. (tests/)
+```
+
+## Arguments
+
+$ARGUMENTS:
+- `repo|hooks|skills|commands|agents` (optional scope)
+- `--format text|json` (optional output format)

.opencode/commands/instinct-status.md

@@ -1,75 +1,29 @@
 ---
-description: View learned instincts with confidence scores
+description: Show learned instincts (project + global) with confidence
 agent: build
 ---
 
 # Instinct Status Command
 
-Display learned instincts and their confidence scores: $ARGUMENTS
+Show instinct status from continuous-learning-v2: $ARGUMENTS
 
 ## Your Task
 
-Read and display instincts from the continuous-learning-v2 system.
+Run:
 
-## Instinct Location
-
-Global: `~/.claude/instincts/`
-Project: `.claude/instincts/`
-
-## Status Display
-
-### Instinct Summary
-
-| Category | Count | Avg Confidence |
-|----------|-------|----------------|
-| Coding | X | 0.XX |
-| Testing | X | 0.XX |
-| Security | X | 0.XX |
-| Git | X | 0.XX |
-
-### High Confidence Instincts (>0.8)
-
-```
-[trigger] → [action] (confidence: 0.XX)
+```bash
+python3 "${CLAUDE_PLUGIN_ROOT}/skills/continuous-learning-v2/scripts/instinct-cli.py" status
 ```
 
-### Learning Progress
+If `CLAUDE_PLUGIN_ROOT` is unavailable, use:
 
-- Total instincts: X
-- This session: X
-- Promoted to skills: X
-
-### Recent Instincts
-
-Last 5 instincts learned:
-
-1. **[timestamp]** - [trigger] → [action]
-2. **[timestamp]** - [trigger] → [action]
-...
-
-## Instinct Structure
-
-```json
-{
-  "id": "instinct-123",
-  "trigger": "When I see a try-catch without specific error type",
-  "action": "Suggest using specific error types for better handling",
-  "confidence": 0.75,
-  "applications": 5,
-  "successes": 4,
-  "source": "session-observation",
-  "timestamp": "2025-01-15T10:30:00Z"
-}
+```bash
+python3 ~/.claude/skills/continuous-learning-v2/scripts/instinct-cli.py status
 ```
 
-## Confidence Calculation
+## Behavior Notes
 
-```
-confidence = (successes + 1) / (applications + 2)
-```
-
-Bayesian smoothing ensures new instincts don't have extreme confidence.
-
----
-
-**TIP**: Use `/evolve` to cluster related instincts into skills when confidence is high.
+- Output includes both project-scoped and global instincts.
+- Project instincts override global instincts when IDs conflict.
+- Output is grouped by domain with confidence bars.
+- This command does not support extra filters in v2.1.

.opencode/commands/loop-start.md

@@ -0,0 +1,32 @@
+# Loop Start Command
+
+Start a managed autonomous loop pattern with safety defaults.
+
+## Usage
+
+`/loop-start [pattern] [--mode safe|fast]`
+
+- `pattern`: `sequential`, `continuous-pr`, `rfc-dag`, `infinite`
+- `--mode`:
+  - `safe` (default): strict quality gates and checkpoints
+  - `fast`: reduced gates for speed
+
+## Flow
+
+1. Confirm repository state and branch strategy.
+2. Select loop pattern and model tier strategy.
+3. Enable required hooks/profile for the chosen mode.
+4. Create loop plan and write runbook under `.claude/plans/`.
+5. Print commands to start and monitor the loop.
+
+## Required Safety Checks
+
+- Verify tests pass before first loop iteration.
+- Ensure `ECC_HOOK_PROFILE` is not disabled globally.
+- Ensure loop has explicit stop condition.
+
+## Arguments
+
+$ARGUMENTS:
+- `<pattern>` optional (`sequential|continuous-pr|rfc-dag|infinite`)
+- `--mode safe|fast` optional

.opencode/commands/loop-status.md

@@ -0,0 +1,24 @@
+# Loop Status Command
+
+Inspect active loop state, progress, and failure signals.
+
+## Usage
+
+`/loop-status [--watch]`
+
+## What to Report
+
+- active loop pattern
+- current phase and last successful checkpoint
+- failing checks (if any)
+- estimated time/cost drift
+- recommended intervention (continue/pause/stop)
+
+## Watch Mode
+
+When `--watch` is present, refresh status periodically and surface state changes.
+
+## Arguments
+
+$ARGUMENTS:
+- `--watch` optional

.opencode/commands/model-route.md

@@ -0,0 +1,26 @@
+# Model Route Command
+
+Recommend the best model tier for the current task by complexity and budget.
+
+## Usage
+
+`/model-route [task-description] [--budget low|med|high]`
+
+## Routing Heuristic
+
+- `haiku`: deterministic, low-risk mechanical changes
+- `sonnet`: default for implementation and refactors
+- `opus`: architecture, deep review, ambiguous requirements
+
+## Required Output
+
+- recommended model
+- confidence level
+- why this model fits
+- fallback model if first attempt fails
+
+## Arguments
+
+$ARGUMENTS:
+- `[task-description]` optional free-text
+- `--budget low|med|high` optional

.opencode/commands/projects.md

@@ -0,0 +1,23 @@
+---
+description: List registered projects and instinct counts
+agent: build
+---
+
+# Projects Command
+
+Show continuous-learning-v2 project registry and stats: $ARGUMENTS
+
+## Your Task
+
+Run:
+
+```bash
+python3 "${CLAUDE_PLUGIN_ROOT}/skills/continuous-learning-v2/scripts/instinct-cli.py" projects
+```
+
+If `CLAUDE_PLUGIN_ROOT` is unavailable, use:
+
+```bash
+python3 ~/.claude/skills/continuous-learning-v2/scripts/instinct-cli.py projects
+```
+

.opencode/commands/promote.md

@@ -0,0 +1,23 @@
+---
+description: Promote project instincts to global scope
+agent: build
+---
+
+# Promote Command
+
+Promote instincts in continuous-learning-v2: $ARGUMENTS
+
+## Your Task
+
+Run:
+
+```bash
+python3 "${CLAUDE_PLUGIN_ROOT}/skills/continuous-learning-v2/scripts/instinct-cli.py" promote $ARGUMENTS
+```
+
+If `CLAUDE_PLUGIN_ROOT` is unavailable, use:
+
+```bash
+python3 ~/.claude/skills/continuous-learning-v2/scripts/instinct-cli.py promote $ARGUMENTS
+```
+

.opencode/commands/quality-gate.md

@@ -0,0 +1,29 @@
+# Quality Gate Command
+
+Run the ECC quality pipeline on demand for a file or project scope.
+
+## Usage
+
+`/quality-gate [path|.] [--fix] [--strict]`
+
+- default target: current directory (`.`)
+- `--fix`: allow auto-format/fix where configured
+- `--strict`: fail on warnings where supported
+
+## Pipeline
+
+1. Detect language/tooling for target.
+2. Run formatter checks.
+3. Run lint/type checks when available.
+4. Produce a concise remediation list.
+
+## Notes
+
+This command mirrors hook behavior but is operator-invoked.
+
+## Arguments
+
+$ARGUMENTS:
+- `[path|.]` optional target path
+- `--fix` optional
+- `--strict` optional

.opencode/commands/rust-build.md

@@ -0,0 +1,78 @@
+---
+description: Fix Rust build errors and borrow checker issues
+agent: rust-build-resolver
+subtask: true
+---
+
+# Rust Build Command
+
+Fix Rust build, clippy, and dependency errors: $ARGUMENTS
+
+## Your Task
+
+1. **Run cargo check**: `cargo check 2>&1`
+2. **Run cargo clippy**: `cargo clippy -- -D warnings 2>&1`
+3. **Fix errors** one at a time
+4. **Verify fixes** don't introduce new errors
+
+## Common Rust Errors
+
+### Borrow Checker
+```
+cannot borrow `x` as mutable because it is also borrowed as immutable
+```
+**Fix**: Restructure to end immutable borrow first; clone only if justified
+
+### Type Mismatch
+```
+mismatched types: expected `T`, found `U`
+```
+**Fix**: Add `.into()`, `as`, or explicit type conversion
+
+### Missing Import
+```
+unresolved import `crate::module`
+```
+**Fix**: Fix the `use` path or declare the module (add Cargo.toml deps only for external crates)
+
+### Lifetime Errors
+```
+does not live long enough
+```
+**Fix**: Use owned type or add lifetime annotation
+
+### Trait Not Implemented
+```
+the trait `X` is not implemented for `Y`
+```
+**Fix**: Add `#[derive(Trait)]` or implement manually
+
+## Fix Order
+
+1. **Build errors** - Code must compile
+2. **Clippy warnings** - Fix suspicious constructs
+3. **Formatting** - `cargo fmt` compliance
+
+## Build Commands
+
+```bash
+cargo check 2>&1
+cargo clippy -- -D warnings 2>&1
+cargo fmt --check 2>&1
+cargo tree --duplicates
+cargo test
+```
+
+## Verification
+
+After fixes:
+```bash
+cargo check                  # Should succeed
+cargo clippy -- -D warnings  # No warnings allowed
+cargo fmt --check            # Formatting should pass
+cargo test                   # Tests should pass
+```
+
+---
+
+**IMPORTANT**: Fix errors only. No refactoring, no improvements. Get the build green with minimal changes.

.opencode/commands/rust-review.md

@@ -0,0 +1,65 @@
+---
+description: Rust code review for ownership, safety, and idiomatic patterns
+agent: rust-reviewer
+subtask: true
+---
+
+# Rust Review Command
+
+Review Rust code for idiomatic patterns and best practices: $ARGUMENTS
+
+## Your Task
+
+1. **Analyze Rust code** for idioms and patterns
+2. **Check ownership** - borrowing, lifetimes, unnecessary clones
+3. **Review error handling** - proper `?` propagation, no unwrap in production
+4. **Verify safety** - unsafe usage, injection, secrets
+
+## Review Checklist
+
+### Safety (CRITICAL)
+- [ ] No unchecked `unwrap()`/`expect()` in production paths
+- [ ] `unsafe` blocks have `// SAFETY:` comments
+- [ ] No SQL/command injection
+- [ ] No hardcoded secrets
+
+### Ownership (HIGH)
+- [ ] No unnecessary `.clone()` to satisfy borrow checker
+- [ ] `&str` preferred over `String` in function parameters
+- [ ] `&[T]` preferred over `Vec<T>` in function parameters
+- [ ] No excessive lifetime annotations where elision works
+
+### Error Handling (HIGH)
+- [ ] Errors propagated with `?`; use `.context()` in `anyhow`/`eyre` application code
+- [ ] No silenced errors (`let _ = result;`)
+- [ ] `thiserror` for library errors, `anyhow` for applications
+
+### Concurrency (HIGH)
+- [ ] No blocking in async context
+- [ ] Bounded channels preferred
+- [ ] `Mutex` poisoning handled
+- [ ] `Send`/`Sync` bounds correct
+
+### Code Quality (MEDIUM)
+- [ ] Functions under 50 lines
+- [ ] No deep nesting (>4 levels)
+- [ ] Exhaustive matching on business enums
+- [ ] Clippy warnings addressed
+
+## Report Format
+
+### CRITICAL Issues
+- [file:line] Issue description
+  Suggestion: How to fix
+
+### HIGH Issues
+- [file:line] Issue description
+  Suggestion: How to fix
+
+### MEDIUM Issues
+- [file:line] Issue description
+  Suggestion: How to fix
+
+---
+
+**TIP**: Run `cargo clippy -- -D warnings` and `cargo fmt --check` for automated checks.

.opencode/commands/rust-test.md

@@ -0,0 +1,104 @@
+---
+description: Rust TDD workflow with unit and property tests
+agent: tdd-guide
+subtask: true
+---
+
+# Rust Test Command
+
+Implement using Rust TDD methodology: $ARGUMENTS
+
+## Your Task
+
+Apply test-driven development with Rust idioms:
+
+1. **Define types** - Structs, enums, traits
+2. **Write tests** - Unit tests in `#[cfg(test)]` modules
+3. **Implement minimal code** - Pass the tests
+4. **Check coverage** - Target 80%+
+
+## TDD Cycle for Rust
+
+### Step 1: Define Interface
+```rust
+pub struct Input {
+    // fields
+}
+
+pub fn process(input: &Input) -> Result<Output, Error> {
+    todo!()
+}
+```
+
+### Step 2: Write Tests
+```rust
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn valid_input_succeeds() {
+        let input = Input { /* ... */ };
+        let result = process(&input);
+        assert!(result.is_ok());
+    }
+
+    #[test]
+    fn invalid_input_returns_error() {
+        let input = Input { /* ... */ };
+        let result = process(&input);
+        assert!(result.is_err());
+    }
+}
+```
+
+### Step 3: Run Tests (RED)
+```bash
+cargo test
+```
+
+### Step 4: Implement (GREEN)
+```rust
+pub fn process(input: &Input) -> Result<Output, Error> {
+    // Minimal implementation that handles both paths
+    validate(input)?;
+    Ok(Output { /* ... */ })
+}
+```
+
+### Step 5: Check Coverage
+```bash
+cargo llvm-cov
+cargo llvm-cov --fail-under-lines 80
+```
+
+## Rust Testing Commands
+
+```bash
+cargo test                        # Run all tests
+cargo test -- --nocapture         # Show println output
+cargo test test_name              # Run specific test
+cargo test --no-fail-fast         # Don't stop on first failure
+cargo test --lib                  # Unit tests only
+cargo test --test integration     # Integration tests only
+cargo test --doc                  # Doc tests only
+cargo bench                       # Run benchmarks
+```
+
+## Test File Organization
+
+```
+src/
+├── lib.rs             # Library root
+├── service.rs         # Implementation
+└── service/
+    └── tests.rs       # Or inline #[cfg(test)] mod tests {}
+tests/
+└── integration.rs     # Integration tests
+benches/
+└── benchmark.rs       # Criterion benchmarks
+```
+
+---
+
+**TIP**: Use `rstest` for parameterized tests and `proptest` for property-based testing.

.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,127 +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:commands/promote.md}\n\n$ARGUMENTS"
+    },
+    "projects": {
+      "description": "List known projects and instinct stats",
+      "template": "{file:commands/projects.md}\n\n$ARGUMENTS"
     }
   },
   "permission": {

.opencode/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ecc-universal",
-  "version": "1.7.0",
+  "version": "1.9.0",
   "description": "Everything Claude Code (ECC) plugin for OpenCode - agents, commands, hooks, and skills",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

.opencode/plugins/ecc-hooks.ts

@@ -21,6 +21,8 @@ export const ECCHooksPlugin = async ({
   directory,
   worktree,
 }: PluginInput) => {
+  type HookProfile = "minimal" | "standard" | "strict"
+
   // Track files edited in current session for console.log audit
   const editedFiles = new Set<string>()
 
@@ -28,6 +30,40 @@ export const ECCHooksPlugin = async ({
   const log = (level: "debug" | "info" | "warn" | "error", message: string) =>
     client.app.log({ body: { service: "ecc", level, message } })
 
+  const normalizeProfile = (value: string | undefined): HookProfile => {
+    if (value === "minimal" || value === "strict") return value
+    return "standard"
+  }
+
+  const currentProfile = normalizeProfile(process.env.ECC_HOOK_PROFILE)
+  const disabledHooks = new Set(
+    (process.env.ECC_DISABLED_HOOKS || "")
+      .split(",")
+      .map((item) => item.trim())
+      .filter(Boolean)
+  )
+
+  const profileOrder: Record<HookProfile, number> = {
+    minimal: 0,
+    standard: 1,
+    strict: 2,
+  }
+
+  const profileAllowed = (required: HookProfile | HookProfile[]): boolean => {
+    if (Array.isArray(required)) {
+      return required.some((entry) => profileOrder[currentProfile] >= profileOrder[entry])
+    }
+    return profileOrder[currentProfile] >= profileOrder[required]
+  }
+
+  const hookEnabled = (
+    hookId: string,
+    requiredProfile: HookProfile | HookProfile[] = "standard"
+  ): boolean => {
+    if (disabledHooks.has(hookId)) return false
+    return profileAllowed(requiredProfile)
+  }
+
   return {
     /**
      * Prettier Auto-Format Hook
@@ -41,7 +77,7 @@ export const ECCHooksPlugin = async ({
       editedFiles.add(event.path)
 
       // Auto-format JS/TS files
-      if (event.path.match(/\.(ts|tsx|js|jsx)$/)) {
+      if (hookEnabled("post:edit:format", ["standard", "strict"]) && event.path.match(/\.(ts|tsx|js|jsx)$/)) {
         try {
           await $`prettier --write ${event.path} 2>/dev/null`
           log("info", `[ECC] Formatted: ${event.path}`)
@@ -51,7 +87,7 @@ export const ECCHooksPlugin = async ({
       }
 
       // Console.log warning check
-      if (event.path.match(/\.(ts|tsx|js|jsx)$/)) {
+      if (hookEnabled("post:edit:console-warn", ["standard", "strict"]) && event.path.match(/\.(ts|tsx|js|jsx)$/)) {
         try {
           const result = await $`grep -n "console\\.log" ${event.path} 2>/dev/null`.text()
           if (result.trim()) {
@@ -80,6 +116,7 @@ export const ECCHooksPlugin = async ({
     ) => {
       // Check if a TypeScript file was edited
       if (
+        hookEnabled("post:edit:typecheck", ["standard", "strict"]) &&
         input.tool === "edit" &&
         input.args?.filePath?.match(/\.tsx?$/)
       ) {
@@ -98,7 +135,11 @@ export const ECCHooksPlugin = async ({
       }
 
       // PR creation logging
-      if (input.tool === "bash" && input.args?.toString().includes("gh pr create")) {
+      if (
+        hookEnabled("post:bash:pr-created", ["standard", "strict"]) &&
+        input.tool === "bash" &&
+        input.args?.toString().includes("gh pr create")
+      ) {
         log("info", "[ECC] PR created - check GitHub Actions status")
       }
     },
@@ -115,6 +156,7 @@ export const ECCHooksPlugin = async ({
     ) => {
       // Git push review reminder
       if (
+        hookEnabled("pre:bash:git-push-reminder", "strict") &&
         input.tool === "bash" &&
         input.args?.toString().includes("git push")
       ) {
@@ -126,6 +168,7 @@ export const ECCHooksPlugin = async ({
 
       // Block creation of unnecessary documentation files
       if (
+        hookEnabled("pre:write:doc-file-warning", ["standard", "strict"]) &&
         input.tool === "write" &&
         input.args?.filePath &&
         typeof input.args.filePath === "string"
@@ -146,7 +189,7 @@ export const ECCHooksPlugin = async ({
       }
 
       // Long-running command reminder
-      if (input.tool === "bash") {
+      if (hookEnabled("pre:bash:tmux-reminder", "strict") && input.tool === "bash") {
         const cmd = String(input.args?.command || input.args || "")
         if (
           cmd.match(/^(npm|pnpm|yarn|bun)\s+(install|build|test|run)/) ||
@@ -169,7 +212,9 @@ export const ECCHooksPlugin = async ({
      * Action: Loads context and displays welcome message
      */
     "session.created": async () => {
-      log("info", "[ECC] Session started - Everything Claude Code hooks active")
+      if (!hookEnabled("session:start", ["minimal", "standard", "strict"])) return
+
+      log("info", `[ECC] Session started - profile=${currentProfile}`)
 
       // Check for project-specific context files
       try {
@@ -190,6 +235,7 @@ export const ECCHooksPlugin = async ({
      * Action: Runs console.log audit on all edited files
      */
     "session.idle": async () => {
+      if (!hookEnabled("stop:check-console-log", ["minimal", "standard", "strict"])) return
       if (editedFiles.size === 0) return
 
       log("info", "[ECC] Session idle - running console.log audit")
@@ -244,6 +290,7 @@ export const ECCHooksPlugin = async ({
      * Action: Final cleanup and state saving
      */
     "session.deleted": async () => {
+      if (!hookEnabled("session:end-marker", ["minimal", "standard", "strict"])) return
       log("info", "[ECC] Session ended - cleaning up")
       editedFiles.clear()
     },
@@ -285,8 +332,10 @@ export const ECCHooksPlugin = async ({
      */
     "shell.env": async () => {
       const env: Record<string, string> = {
-        ECC_VERSION: "1.6.0",
+        ECC_VERSION: "1.8.0",
         ECC_PLUGIN: "true",
+        ECC_HOOK_PROFILE: currentProfile,
+        ECC_DISABLED_HOOKS: process.env.ECC_DISABLED_HOOKS || "",
         PROJECT_ROOT: worktree || directory,
       }
 
@@ -343,7 +392,7 @@ export const ECCHooksPlugin = async ({
       const contextBlock = [
         "# ECC Context (preserve across compaction)",
         "",
-        "## Active Plugin: Everything Claude Code v1.6.0",
+        "## Active Plugin: Everything Claude Code v1.8.0",
         "- Hooks: file.edited, tool.execute.before/after, session.created/idle/deleted, shell.env, compacting, permission.ask",
         "- Tools: run-tests, check-coverage, security-audit, format-code, lint-check, git-summary",
         "- Agents: 13 specialized (planner, architect, tdd-guide, code-reviewer, security-reviewer, build-error-resolver, e2e-runner, refactor-cleaner, doc-updater, go-reviewer, go-build-resolver, database-reviewer, python-reviewer)",

.opencode/prompts/agents/rust-build-resolver.txt

@@ -0,0 +1,93 @@
+# Rust Build Error Resolver
+
+You are an expert Rust build error resolution specialist. Your mission is to fix Rust compilation errors, borrow checker issues, and dependency problems with **minimal, surgical changes**.
+
+## Core Responsibilities
+
+1. Diagnose `cargo build` / `cargo check` errors
+2. Fix borrow checker and lifetime errors
+3. Resolve trait implementation mismatches
+4. Handle Cargo dependency and feature issues
+5. Fix `cargo clippy` warnings
+
+## Diagnostic Commands
+
+Run these in order:
+
+```bash
+cargo check 2>&1
+cargo clippy -- -D warnings 2>&1
+cargo fmt --check 2>&1
+cargo tree --duplicates
+if command -v cargo-audit >/dev/null; then cargo audit; else echo "cargo-audit not installed"; fi
+```
+
+## Resolution Workflow
+
+```text
+1. cargo check          -> Parse error message and error code
+2. Read affected file   -> Understand ownership and lifetime context
+3. Apply minimal fix    -> Only what's needed
+4. cargo check          -> Verify fix
+5. cargo clippy         -> Check for warnings
+6. cargo fmt --check    -> Verify formatting
+7. cargo test           -> Ensure nothing broke
+```
+
+## Common Fix Patterns
+
+| Error | Cause | Fix |
+|-------|-------|-----|
+| `cannot borrow as mutable` | Immutable borrow active | Restructure to end immutable borrow first, or use `Cell`/`RefCell` |
+| `does not live long enough` | Value dropped while still borrowed | Extend lifetime scope, use owned type, or add lifetime annotation |
+| `cannot move out of` | Moving from behind a reference | Use `.clone()`, `.to_owned()`, or restructure to take ownership |
+| `mismatched types` | Wrong type or missing conversion | Add `.into()`, `as`, or explicit type conversion |
+| `trait X is not implemented for Y` | Missing impl or derive | Add `#[derive(Trait)]` or implement trait manually |
+| `unresolved import` | Missing dependency or wrong path | Add to Cargo.toml or fix `use` path |
+| `unused variable` / `unused import` | Dead code | Remove or prefix with `_` |
+
+## Borrow Checker Troubleshooting
+
+```rust
+// Problem: Cannot borrow as mutable because also borrowed as immutable
+// Fix: Restructure to end immutable borrow before mutable borrow
+let value = map.get("key").cloned();
+if value.is_none() {
+    map.insert("key".into(), default_value);
+}
+
+// Problem: Value does not live long enough
+// Fix: Move ownership instead of borrowing
+fn get_name() -> String {
+    let name = compute_name();
+    name  // Not &name (dangling reference)
+}
+```
+
+## Key Principles
+
+- **Surgical fixes only** — don't refactor, just fix the error
+- **Never** add `#[allow(unused)]` without explicit approval
+- **Never** use `unsafe` to work around borrow checker errors
+- **Never** add `.unwrap()` to silence type errors — propagate with `?`
+- **Always** run `cargo check` after every fix attempt
+- Fix root cause over suppressing symptoms
+
+## 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
+- Borrow checker error requires redesigning data ownership model
+
+## Output Format
+
+```text
+[FIXED] src/handler/user.rs:42
+Error: E0502 — cannot borrow `map` as mutable because it is also borrowed as immutable
+Fix: Cloned value from immutable borrow before mutable insert
+Remaining errors: 3
+```
+
+Final: `Build Status: SUCCESS/FAILED | Errors Fixed: N | Files Modified: list`

.opencode/prompts/agents/rust-reviewer.txt

@@ -0,0 +1,61 @@
+You are a senior Rust code reviewer ensuring high standards of safety, idiomatic patterns, and performance.
+
+When invoked:
+1. Run `cargo check`, `cargo clippy -- -D warnings`, `cargo fmt --check`, and `cargo test` — if any fail, stop and report
+2. Run `git diff HEAD~1 -- '*.rs'` (or `git diff main...HEAD -- '*.rs'` for PR review) to see recent Rust file changes
+3. Focus on modified `.rs` files
+4. Begin review
+
+## Security Checks (CRITICAL)
+
+- **SQL Injection**: String interpolation in queries
+  ```rust
+  // Bad
+  format!("SELECT * FROM users WHERE id = {}", user_id)
+  // Good: use parameterized queries via sqlx, diesel, etc.
+  sqlx::query("SELECT * FROM users WHERE id = $1").bind(user_id)
+  ```
+
+- **Command Injection**: Unvalidated input in `std::process::Command`
+  ```rust
+  // Bad
+  Command::new("sh").arg("-c").arg(format!("echo {}", user_input))
+  // Good
+  Command::new("echo").arg(user_input)
+  ```
+
+- **Unsafe without justification**: Missing `// SAFETY:` comment
+- **Hardcoded secrets**: API keys, passwords, tokens in source
+- **Use-after-free via raw pointers**: Unsafe pointer manipulation
+
+## Error Handling (CRITICAL)
+
+- **Silenced errors**: `let _ = result;` on `#[must_use]` types
+- **Missing error context**: `return Err(e)` without `.context()` or `.map_err()`
+- **Panic in production**: `panic!()`, `todo!()`, `unreachable!()` in production paths
+- **`Box<dyn Error>` in libraries**: Use `thiserror` for typed errors
+
+## Ownership and Lifetimes (HIGH)
+
+- **Unnecessary cloning**: `.clone()` to satisfy borrow checker without understanding root cause
+- **String instead of &str**: Taking `String` when `&str` suffices
+- **Vec instead of slice**: Taking `Vec<T>` when `&[T]` suffices
+
+## Concurrency (HIGH)
+
+- **Blocking in async**: `std::thread::sleep`, `std::fs` in async context
+- **Unbounded channels**: `mpsc::channel()`/`tokio::sync::mpsc::unbounded_channel()` need justification — prefer bounded channels
+- **`Mutex` poisoning ignored**: Not handling `PoisonError`
+- **Missing `Send`/`Sync` bounds**: Types shared across threads
+
+## Code Quality (HIGH)
+
+- **Large functions**: Over 50 lines
+- **Wildcard match on business enums**: `_ =>` hiding new variants
+- **Dead code**: Unused functions, imports, variables
+
+## Approval Criteria
+
+- **Approve**: No CRITICAL or HIGH issues
+- **Warning**: MEDIUM issues only
+- **Block**: CRITICAL or HIGH issues found

.opencode/tools/format-code.ts

@@ -1,66 +1,68 @@
 /**
  * ECC Custom Tool: Format Code
  *
- * Language-aware code formatter that auto-detects the project's formatter.
- * Supports: Biome/Prettier (JS/TS), Black (Python), gofmt (Go), rustfmt (Rust)
+ * Returns the formatter command that should be run for a given file.
+ * This avoids shell execution assumptions while still giving precise guidance.
  */
 
-import { tool } from "@opencode-ai/plugin"
-import { z } from "zod"
+import { tool } from "@opencode-ai/plugin/tool"
+import * as path from "path"
+import * as fs from "fs"
+
+type Formatter = "biome" | "prettier" | "black" | "gofmt" | "rustfmt"
 
 export default tool({
-  name: "format-code",
-  description: "Format a file using the project's configured formatter. Auto-detects Biome, Prettier, Black, gofmt, or rustfmt.",
-  parameters: z.object({
-    filePath: z.string().describe("Path to the file to format"),
-    formatter: z.string().optional().describe("Override formatter: biome, prettier, black, gofmt, rustfmt (default: auto-detect)"),
-  }),
-  execute: async ({ filePath, formatter }, { $ }) => {
-    const ext = filePath.split(".").pop()?.toLowerCase() || ""
-
-    // Auto-detect formatter based on file extension and config files
-    let detected = formatter
-    if (!detected) {
-      if (["ts", "tsx", "js", "jsx", "json", "css", "scss"].includes(ext)) {
-        // Check for Biome first, then Prettier
-        try {
-          await $`test -f biome.json || test -f biome.jsonc`
-          detected = "biome"
-        } catch {
-          detected = "prettier"
-        }
-      } else if (["py", "pyi"].includes(ext)) {
-        detected = "black"
-      } else if (ext === "go") {
-        detected = "gofmt"
-      } else if (ext === "rs") {
-        detected = "rustfmt"
-      }
-    }
+  description:
+    "Detect formatter for a file and return the exact command to run (Biome, Prettier, Black, gofmt, rustfmt).",
+  args: {
+    filePath: tool.schema.string().describe("Path to the file to format"),
+    formatter: tool.schema
+      .enum(["biome", "prettier", "black", "gofmt", "rustfmt"])
+      .optional()
+      .describe("Optional formatter override"),
+  },
+  async execute(args, context) {
+    const cwd = context.worktree || context.directory
+    const ext = args.filePath.split(".").pop()?.toLowerCase() || ""
+    const detected = args.formatter || detectFormatter(cwd, ext)
 
     if (!detected) {
-      return { formatted: false, message: `No formatter detected for .${ext} files` }
+      return JSON.stringify({
+        success: false,
+        message: `No formatter detected for .${ext} files`,
+      })
     }
 
-    const commands: Record<string, string> = {
-      biome: `npx @biomejs/biome format --write ${filePath}`,
-      prettier: `npx prettier --write ${filePath}`,
-      black: `black ${filePath}`,
-      gofmt: `gofmt -w ${filePath}`,
-      rustfmt: `rustfmt ${filePath}`,
-    }
-
-    const cmd = commands[detected]
-    if (!cmd) {
-      return { formatted: false, message: `Unknown formatter: ${detected}` }
-    }
-
-    try {
-      const result = await $`${cmd}`.text()
-      return { formatted: true, formatter: detected, output: result }
-    } catch (error: unknown) {
-      const err = error as { stderr?: string }
-      return { formatted: false, formatter: detected, error: err.stderr || "Format failed" }
-    }
+    const command = buildFormatterCommand(detected, args.filePath)
+    return JSON.stringify({
+      success: true,
+      formatter: detected,
+      command,
+      instructions: `Run this command:\n\n${command}`,
+    })
   },
 })
+
+function detectFormatter(cwd: string, ext: string): Formatter | null {
+  if (["ts", "tsx", "js", "jsx", "json", "css", "scss", "md", "yaml", "yml"].includes(ext)) {
+    if (fs.existsSync(path.join(cwd, "biome.json")) || fs.existsSync(path.join(cwd, "biome.jsonc"))) {
+      return "biome"
+    }
+    return "prettier"
+  }
+  if (["py", "pyi"].includes(ext)) return "black"
+  if (ext === "go") return "gofmt"
+  if (ext === "rs") return "rustfmt"
+  return null
+}
+
+function buildFormatterCommand(formatter: Formatter, filePath: string): string {
+  const commands: Record<Formatter, string> = {
+    biome: `npx @biomejs/biome format --write ${filePath}`,
+    prettier: `npx prettier --write ${filePath}`,
+    black: `black ${filePath}`,
+    gofmt: `gofmt -w ${filePath}`,
+    rustfmt: `rustfmt ${filePath}`,
+  }
+  return commands[formatter]
+}

.opencode/tools/git-summary.ts

@@ -1,56 +1,54 @@
 /**
  * ECC Custom Tool: Git Summary
  *
- * Provides a comprehensive git status including branch info, status,
- * recent log, and diff against base branch.
+ * Returns branch/status/log/diff details for the active repository.
  */
 
-import { tool } from "@opencode-ai/plugin"
-import { z } from "zod"
+import { tool } from "@opencode-ai/plugin/tool"
+import { execSync } from "child_process"
 
 export default tool({
-  name: "git-summary",
-  description: "Get comprehensive git summary: branch, status, recent log, and diff against base branch.",
-  parameters: z.object({
-    depth: z.number().optional().describe("Number of recent commits to show (default: 5)"),
-    includeDiff: z.boolean().optional().describe("Include diff against base branch (default: true)"),
-    baseBranch: z.string().optional().describe("Base branch for comparison (default: main)"),
-  }),
-  execute: async ({ depth = 5, includeDiff = true, baseBranch = "main" }, { $ }) => {
-    const results: Record<string, string> = {}
+  description:
+    "Generate git summary with branch, status, recent commits, and optional diff stats.",
+  args: {
+    depth: tool.schema
+      .number()
+      .optional()
+      .describe("Number of recent commits to include (default: 5)"),
+    includeDiff: tool.schema
+      .boolean()
+      .optional()
+      .describe("Include diff stats against base branch (default: true)"),
+    baseBranch: tool.schema
+      .string()
+      .optional()
+      .describe("Base branch for diff comparison (default: main)"),
+  },
+  async execute(args, context) {
+    const cwd = context.worktree || context.directory
+    const depth = args.depth ?? 5
+    const includeDiff = args.includeDiff ?? true
+    const baseBranch = args.baseBranch ?? "main"
 
-    try {
-      results.branch = (await $`git branch --show-current`.text()).trim()
-    } catch {
-      results.branch = "unknown"
-    }
-
-    try {
-      results.status = (await $`git status --short`.text()).trim()
-    } catch {
-      results.status = "unable to get status"
-    }
-
-    try {
-      results.log = (await $`git log --oneline -${depth}`.text()).trim()
-    } catch {
-      results.log = "unable to get log"
+    const result: Record<string, string> = {
+      branch: run("git branch --show-current", cwd) || "unknown",
+      status: run("git status --short", cwd) || "clean",
+      log: run(`git log --oneline -${depth}`, cwd) || "no commits found",
     }
 
     if (includeDiff) {
-      try {
-        results.stagedDiff = (await $`git diff --cached --stat`.text()).trim()
-      } catch {
-        results.stagedDiff = ""
-      }
-
-      try {
-        results.branchDiff = (await $`git diff ${baseBranch}...HEAD --stat`.text()).trim()
-      } catch {
-        results.branchDiff = `unable to diff against ${baseBranch}`
-      }
+      result.stagedDiff = run("git diff --cached --stat", cwd) || ""
+      result.branchDiff = run(`git diff ${baseBranch}...HEAD --stat`, cwd) || `unable to diff against ${baseBranch}`
     }
 
-    return results
+    return JSON.stringify(result)
   },
 })
+
+function run(command: string, cwd: string): string {
+  try {
+    return execSync(command, { cwd, encoding: "utf-8", stdio: ["ignore", "pipe", "pipe"] }).trim()
+  } catch {
+    return ""
+  }
+}

.opencode/tools/lint-check.ts

@@ -1,74 +1,85 @@
 /**
  * ECC Custom Tool: Lint Check
  *
- * Multi-language linter that auto-detects the project's linting tool.
- * Supports: ESLint/Biome (JS/TS), Pylint/Ruff (Python), golangci-lint (Go)
+ * Detects the appropriate linter and returns a runnable lint command.
  */
 
-import { tool } from "@opencode-ai/plugin"
-import { z } from "zod"
+import { tool } from "@opencode-ai/plugin/tool"
+import * as path from "path"
+import * as fs from "fs"
+
+type Linter = "biome" | "eslint" | "ruff" | "pylint" | "golangci-lint"
 
 export default tool({
-  name: "lint-check",
-  description: "Run linter on files or directories. Auto-detects ESLint, Biome, Ruff, Pylint, or golangci-lint.",
-  parameters: z.object({
-    target: z.string().optional().describe("File or directory to lint (default: current directory)"),
-    fix: z.boolean().optional().describe("Auto-fix issues if supported (default: false)"),
-    linter: z.string().optional().describe("Override linter: eslint, biome, ruff, pylint, golangci-lint (default: auto-detect)"),
-  }),
-  execute: async ({ target = ".", fix = false, linter }, { $ }) => {
-    // Auto-detect linter
-    let detected = linter
-    if (!detected) {
-      try {
-        await $`test -f biome.json || test -f biome.jsonc`
-        detected = "biome"
-      } catch {
-        try {
-          await $`test -f .eslintrc.json || test -f .eslintrc.js || test -f .eslintrc.cjs || test -f eslint.config.js || test -f eslint.config.mjs`
-          detected = "eslint"
-        } catch {
-          try {
-            await $`test -f pyproject.toml && grep -q "ruff" pyproject.toml`
-            detected = "ruff"
-          } catch {
-            try {
-              await $`test -f .golangci.yml || test -f .golangci.yaml`
-              detected = "golangci-lint"
-            } catch {
-              // Fall back based on file extensions in target
-              detected = "eslint"
-            }
-          }
-        }
-      }
-    }
+  description:
+    "Detect linter for a target path and return command for check/fix runs.",
+  args: {
+    target: tool.schema
+      .string()
+      .optional()
+      .describe("File or directory to lint (default: current directory)"),
+    fix: tool.schema
+      .boolean()
+      .optional()
+      .describe("Enable auto-fix mode"),
+    linter: tool.schema
+      .enum(["biome", "eslint", "ruff", "pylint", "golangci-lint"])
+      .optional()
+      .describe("Optional linter override"),
+  },
+  async execute(args, context) {
+    const cwd = context.worktree || context.directory
+    const target = args.target || "."
+    const fix = args.fix ?? false
+    const detected = args.linter || detectLinter(cwd)
 
-    const fixFlag = fix ? " --fix" : ""
-    const commands: Record<string, string> = {
-      biome: `npx @biomejs/biome lint${fix ? " --write" : ""} ${target}`,
-      eslint: `npx eslint${fixFlag} ${target}`,
-      ruff: `ruff check${fixFlag} ${target}`,
-      pylint: `pylint ${target}`,
-      "golangci-lint": `golangci-lint run${fixFlag} ${target}`,
-    }
-
-    const cmd = commands[detected]
-    if (!cmd) {
-      return { success: false, message: `Unknown linter: ${detected}` }
-    }
-
-    try {
-      const result = await $`${cmd}`.text()
-      return { success: true, linter: detected, output: result, issues: 0 }
-    } catch (error: unknown) {
-      const err = error as { stdout?: string; stderr?: string }
-      return {
-        success: false,
-        linter: detected,
-        output: err.stdout || "",
-        errors: err.stderr || "",
-      }
-    }
+    const command = buildLintCommand(detected, target, fix)
+    return JSON.stringify({
+      success: true,
+      linter: detected,
+      command,
+      instructions: `Run this command:\n\n${command}`,
+    })
   },
 })
+
+function detectLinter(cwd: string): Linter {
+  if (fs.existsSync(path.join(cwd, "biome.json")) || fs.existsSync(path.join(cwd, "biome.jsonc"))) {
+    return "biome"
+  }
+
+  const eslintConfigs = [
+    ".eslintrc.json",
+    ".eslintrc.js",
+    ".eslintrc.cjs",
+    "eslint.config.js",
+    "eslint.config.mjs",
+  ]
+  if (eslintConfigs.some((name) => fs.existsSync(path.join(cwd, name)))) {
+    return "eslint"
+  }
+
+  const pyprojectPath = path.join(cwd, "pyproject.toml")
+  if (fs.existsSync(pyprojectPath)) {
+    try {
+      const content = fs.readFileSync(pyprojectPath, "utf-8")
+      if (content.includes("ruff")) return "ruff"
+    } catch {
+      // ignore read errors and keep fallback logic
+    }
+  }
+
+  if (fs.existsSync(path.join(cwd, ".golangci.yml")) || fs.existsSync(path.join(cwd, ".golangci.yaml"))) {
+    return "golangci-lint"
+  }
+
+  return "eslint"
+}
+
+function buildLintCommand(linter: Linter, target: string, fix: boolean): string {
+  if (linter === "biome") return `npx @biomejs/biome lint${fix ? " --write" : ""} ${target}`
+  if (linter === "eslint") return `npx eslint${fix ? " --fix" : ""} ${target}`
+  if (linter === "ruff") return `ruff check${fix ? " --fix" : ""} ${target}`
+  if (linter === "pylint") return `pylint ${target}`
+  return `golangci-lint run ${target}`
+}

.prettierrc

@@ -0,0 +1,8 @@
+{
+  "singleQuote": true,
+  "trailingComma": "none",
+  "semi": true,
+  "tabWidth": 2,
+  "printWidth": 200,
+  "arrowParens": "avoid"
+}

.tool-versions

@@ -0,0 +1,6 @@
+# .tool-versions — Tool version pins for asdf (https://asdf-vm.com)
+# Install asdf, then run: asdf install
+# These versions are also compatible with mise (https://mise.jdx.dev).
+
+nodejs 20.19.0
+python 3.12.8

AGENTS.md

@@ -1,6 +1,8 @@
 # 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 27 specialized agents, 109 skills, 57 commands, and automated hook workflows for software development.
+
+**Version:** 1.9.0
 
 ## Core Principles
 
@@ -23,10 +25,24 @@ This is a **production-ready AI coding plugin** providing 13 specialized agents,
 | e2e-runner | End-to-end Playwright testing | Critical user flows |
 | refactor-cleaner | Dead code cleanup | Code maintenance |
 | doc-updater | Documentation and codemaps | Updating docs |
+| docs-lookup | Documentation and API reference research | Library/API documentation questions |
+| cpp-reviewer | C++ code review | C++ projects |
+| cpp-build-resolver | C++ build errors | C++ build failures |
 | go-reviewer | Go code review | Go projects |
 | go-build-resolver | Go build errors | Go build failures |
+| kotlin-reviewer | Kotlin code review | Kotlin/Android/KMP projects |
+| kotlin-build-resolver | Kotlin/Gradle build errors | Kotlin build failures |
 | database-reviewer | PostgreSQL/Supabase specialist | Schema design, query optimization |
 | python-reviewer | Python code review | Python projects |
+| java-reviewer | Java and Spring Boot code review | Java/Spring Boot projects |
+| java-build-resolver | Java/Maven/Gradle build errors | Java build failures |
+| 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 |
+| rust-reviewer | Rust code review | Rust projects |
+| rust-build-resolver | Rust build errors | Rust build failures |
+| pytorch-build-resolver | PyTorch runtime/CUDA/training errors | PyTorch build/training failures |
+| typescript-reviewer | TypeScript/JavaScript code review | TypeScript/JavaScript projects |
 
 ## Agent Orchestration
 
@@ -36,6 +52,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 +111,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
 
@@ -117,9 +141,9 @@ Troubleshoot failures: check test isolation → verify mocks → fix implementat
 ## Project Structure
 
 ```
-agents/          — 13 specialized subagents
-skills/          — 50+ workflow skills and domain knowledge
-commands/        — 33 slash commands
+agents/          — 27 specialized subagents
+skills/          — 109 workflow skills and domain knowledge
+commands/        — 57 slash commands
 hooks/           — Trigger-based automations
 rules/           — Always-follow guidelines (common + per-language)
 scripts/         — Cross-platform Node.js utilities

CHANGELOG.md

@@ -0,0 +1,149 @@
+# Changelog
+
+## 1.9.0 - 2026-03-20
+
+### Highlights
+
+- Selective install architecture with manifest-driven pipeline and SQLite state store.
+- Language coverage expanded to 10+ ecosystems with 6 new agents and language-specific rules.
+- Observer reliability hardened with memory throttling, sandbox fixes, and 5-layer loop guard.
+- Self-improving skills foundation with skill evolution and session adapters.
+
+### New Agents
+
+- `typescript-reviewer` — TypeScript/JavaScript code review specialist (#647)
+- `pytorch-build-resolver` — PyTorch runtime, CUDA, and training error resolution (#549)
+- `java-build-resolver` — Maven/Gradle build error resolution (#538)
+- `java-reviewer` — Java and Spring Boot code review (#528)
+- `kotlin-reviewer` — Kotlin/Android/KMP code review (#309)
+- `kotlin-build-resolver` — Kotlin/Gradle build errors (#309)
+- `rust-reviewer` — Rust code review (#523)
+- `rust-build-resolver` — Rust build error resolution (#523)
+- `docs-lookup` — Documentation and API reference research (#529)
+
+### New Skills
+
+- `pytorch-patterns` — PyTorch deep learning workflows (#550)
+- `documentation-lookup` — API reference and library doc research (#529)
+- `bun-runtime` — Bun runtime patterns (#529)
+- `nextjs-turbopack` — Next.js Turbopack workflows (#529)
+- `mcp-server-patterns` — MCP server design patterns (#531)
+- `data-scraper-agent` — AI-powered public data collection (#503)
+- `team-builder` — Team composition skill (#501)
+- `ai-regression-testing` — AI regression test workflows (#433)
+- `claude-devfleet` — Multi-agent orchestration (#505)
+- `blueprint` — Multi-session construction planning
+- `everything-claude-code` — Self-referential ECC skill (#335)
+- `prompt-optimizer` — Prompt optimization skill (#418)
+- 8 Evos operational domain skills (#290)
+- 3 Laravel skills (#420)
+- VideoDB skills (#301)
+
+### New Commands
+
+- `/docs` — Documentation lookup (#530)
+- `/aside` — Side conversation (#407)
+- `/prompt-optimize` — Prompt optimization (#418)
+- `/resume-session`, `/save-session` — Session management
+- `learn-eval` improvements with checklist-based holistic verdict
+
+### New Rules
+
+- Java language rules (#645)
+- PHP rule pack (#389)
+- Perl language rules and skills (patterns, security, testing)
+- Kotlin/Android/KMP rules (#309)
+- C++ language support (#539)
+- Rust language support (#523)
+
+### Infrastructure
+
+- Selective install architecture with manifest resolution (`install-plan.js`, `install-apply.js`) (#509, #512)
+- SQLite state store with query CLI for tracking installed components (#510)
+- Session adapters for structured session recording (#511)
+- Skill evolution foundation for self-improving skills (#514)
+- Orchestration harness with deterministic scoring (#524)
+- Catalog count enforcement in CI (#525)
+- Install manifest validation for all 109 skills (#537)
+- PowerShell installer wrapper (#532)
+- Antigravity IDE support via `--target antigravity` flag (#332)
+- Codex CLI customization scripts (#336)
+
+### Bug Fixes
+
+- Resolved 19 CI test failures across 6 files (#519)
+- Fixed 8 test failures in install pipeline, orchestrator, and repair (#564)
+- Observer memory explosion with throttling, re-entrancy guard, and tail sampling (#536)
+- Observer sandbox access fix for Haiku invocation (#661)
+- Worktree project ID mismatch fix (#665)
+- Observer lazy-start logic (#508)
+- Observer 5-layer loop prevention guard (#399)
+- Hook portability and Windows .cmd support
+- Biome hook optimization — eliminated npx overhead (#359)
+- InsAIts security hook made opt-in (#370)
+- Windows spawnSync export fix (#431)
+- UTF-8 encoding fix for instinct CLI (#353)
+- Secret scrubbing in hooks (#348)
+
+### Translations
+
+- Korean (ko-KR) translation — README, agents, commands, skills, rules (#392)
+- Chinese (zh-CN) documentation sync (#428)
+
+### Credits
+
+- @ymdvsymd — observer sandbox and worktree fixes
+- @pythonstrup — biome hook optimization
+- @Nomadu27 — InsAIts security hook
+- @hahmee — Korean translation
+- @zdocapp — Chinese translation sync
+- @cookiee339 — Kotlin ecosystem
+- @pangerlkr — CI workflow fixes
+- @0xrohitgarg — VideoDB skills
+- @nocodemf — Evos operational skills
+- @swarnika-cmd — community contributions
+
+## 1.8.0 - 2026-03-04
+
+### Highlights
+
+- Harness-first release focused on reliability, eval discipline, and autonomous loop operations.
+- Hook runtime now supports profile-based control and targeted hook disabling.
+- NanoClaw v2 adds model routing, skill hot-load, branching, search, compaction, export, and metrics.
+
+### Core
+
+- Added new commands: `/harness-audit`, `/loop-start`, `/loop-status`, `/quality-gate`, `/model-route`.
+- Added new skills:
+  - `agent-harness-construction`
+  - `agentic-engineering`
+  - `ralphinho-rfc-pipeline`
+  - `ai-first-engineering`
+  - `enterprise-agent-ops`
+  - `nanoclaw-repl`
+  - `continuous-agent-loop`
+- Added new agents:
+  - `harness-optimizer`
+  - `loop-operator`
+
+### Hook Reliability
+
+- Fixed SessionStart root resolution with robust fallback search.
+- Moved session summary persistence to `Stop` where transcript payload is available.
+- Added quality-gate and cost-tracker hooks.
+- Replaced fragile inline hook one-liners with dedicated script files.
+- Added `ECC_HOOK_PROFILE` and `ECC_DISABLED_HOOKS` controls.
+
+### Cross-Platform
+
+- Improved Windows-safe path handling in doc warning logic.
+- Hardened observer loop behavior to avoid non-interactive hangs.
+
+### Notes
+
+- `autonomous-loops` is kept as a compatibility alias for one release; `continuous-agent-loop` is the canonical name.
+
+### Credits
+
+- inspired by [zarazhangrui](https://github.com/zarazhangrui)
+- homunculus-inspired by [humanplane](https://github.com/humanplane)

CODE_OF_CONDUCT.md

@@ -0,0 +1,128 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our
+community a harassment-free experience for everyone, regardless of age, body
+size, visible or invisible disability, ethnicity, sex characteristics, gender
+identity and expression, level of experience, education, socio-economic status,
+nationality, personal appearance, race, religion, or sexual identity
+and orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming,
+diverse, inclusive, and healthy community.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment for our
+community include:
+
+* Demonstrating empathy and kindness toward other people
+* Being respectful of differing opinions, viewpoints, and experiences
+* Giving and gracefully accepting constructive feedback
+* Accepting responsibility and apologizing to those affected by our mistakes,
+  and learning from the experience
+* Focusing on what is best not just for us as individuals, but for the
+  overall community
+
+Examples of unacceptable behavior include:
+
+* The use of sexualized language or imagery, and sexual attention or
+  advances of any kind
+* Trolling, insulting or derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or email
+  address, without their explicit permission
+* Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+## Enforcement Responsibilities
+
+Community leaders are responsible for clarifying and enforcing our standards of
+acceptable behavior and will take appropriate and fair corrective action in
+response to any behavior that they deem inappropriate, threatening, offensive,
+or harmful.
+
+Community leaders have the right and responsibility to remove, edit, or reject
+comments, commits, code, wiki edits, issues, and other contributions that are
+not aligned to this Code of Conduct, and will communicate reasons for moderation
+decisions when appropriate.
+
+## Scope
+
+This Code of Conduct applies within all community spaces, and also applies when
+an individual is officially representing the community in public spaces.
+Examples of representing our community include using an official e-mail address,
+posting via an official social media account, or acting as an appointed
+representative at an online or offline event.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported to the community leaders responsible for enforcement at
+.
+All complaints will be reviewed and investigated promptly and fairly.
+
+All community leaders are obligated to respect the privacy and security of the
+reporter of any incident.
+
+## Enforcement Guidelines
+
+Community leaders will follow these Community Impact Guidelines in determining
+the consequences for any action they deem in violation of this Code of Conduct:
+
+### 1. Correction
+
+**Community Impact**: Use of inappropriate language or other behavior deemed
+unprofessional or unwelcome in the community.
+
+**Consequence**: A private, written warning from community leaders, providing
+clarity around the nature of the violation and an explanation of why the
+behavior was inappropriate. A public apology may be requested.
+
+### 2. Warning
+
+**Community Impact**: A violation through a single incident or series
+of actions.
+
+**Consequence**: A warning with consequences for continued behavior. No
+interaction with the people involved, including unsolicited interaction with
+those enforcing the Code of Conduct, for a specified period of time. This
+includes avoiding interactions in community spaces as well as external channels
+like social media. Violating these terms may lead to a temporary or
+permanent ban.
+
+### 3. Temporary Ban
+
+**Community Impact**: A serious violation of community standards, including
+sustained inappropriate behavior.
+
+**Consequence**: A temporary ban from any sort of interaction or public
+communication with the community for a specified period of time. No public or
+private interaction with the people involved, including unsolicited interaction
+with those enforcing the Code of Conduct, is allowed during this period.
+Violating these terms may lead to a permanent ban.
+
+### 4. Permanent Ban
+
+**Community Impact**: Demonstrating a pattern of violation of community
+standards, including sustained inappropriate behavior,  harassment of an
+individual, or aggression toward or disparagement of classes of individuals.
+
+**Consequence**: A permanent ban from any sort of public interaction within
+the community.
+
+## Attribution
+
+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>.
+
+Community Impact Guidelines were inspired by [Mozilla's code of conduct
+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>.

CONTRIBUTING.md

@@ -10,6 +10,8 @@ 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)
+- [MCP and documentation (e.g. Context7)](#mcp-and-documentation-eg-context7)
+- [Cross-Harness and Translations](#cross-harness-and-translations)
 - [Pull Request Process](#pull-request-process)
 
 ---
@@ -62,7 +64,7 @@ cp -r skills/my-skill ~/.claude/skills/  # for skills
 # Then test with Claude Code
 
 # 5. Submit PR
-git add . && git commit -m "feat: add my-skill" && git push
+git add . && git commit -m "feat: add my-skill" && git push -u origin feat/my-contribution
 ```
 
 ---
@@ -192,7 +194,7 @@ Output: [what you return]
 |-------|-------------|---------|
 | `name` | Lowercase, hyphenated | `code-reviewer` |
 | `description` | Used to decide when to invoke | Be specific! |
-| `tools` | Only what's needed | `Read, Write, Edit, Bash, Grep, Glob, WebFetch, Task` |
+| `tools` | Only what's needed | `Read, Write, Edit, Bash, Grep, Glob, WebFetch, Task`, or MCP tool names (e.g. `mcp__context7__resolve-library-id`, `mcp__context7__query-docs`) when the agent uses MCP |
 | `model` | Complexity level | `haiku` (simple), `sonnet` (coding), `opus` (complex) |
 
 ### Example Agents
@@ -348,6 +350,40 @@ What the user receives.
 
 ---
 
+## MCP and documentation (e.g. Context7)
+
+Skills and agents can use **MCP (Model Context Protocol)** tools to pull in up-to-date data instead of relying only on training data. This is especially useful for documentation.
+
+- **Context7** is an MCP server that exposes `resolve-library-id` and `query-docs`. Use it when the user asks about libraries, frameworks, or APIs so answers reflect current docs and code examples.
+- When contributing **skills** that depend on live docs (e.g. setup, API usage), describe how to use the relevant MCP tools (e.g. resolve the library ID, then query docs) and point to the `documentation-lookup` skill or Context7 as the pattern.
+- When contributing **agents** that answer docs/API questions, include the Context7 MCP tool names (e.g. `mcp__context7__resolve-library-id`, `mcp__context7__query-docs`) in the agent's tools and document the resolve → query workflow.
+- **mcp-configs/mcp-servers.json** includes a Context7 entry; users enable it in their harness (e.g. Claude Code, Cursor) to use the documentation-lookup skill (in `skills/documentation-lookup/`) and the `/docs` command.
+
+---
+
+## 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,19 +1,23 @@
-**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
 
 [![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)
+![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**
 
 ---
 
@@ -21,15 +25,17 @@
 
 **🌐 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>
 
 ---
 
-**The complete collection of Claude Code configs from an Anthropic hackathon winner.**
+**The performance optimization system for AI agent harnesses. From an Anthropic hackathon winner.**
 
-Production-ready agents, skills, hooks, commands, rules, and MCP configurations evolved over 10+ months of intensive daily use building real products.
+Not just configs. A complete system: skills, instincts, memory optimization, continuous learning, security scanning, and research-first development. Production-ready agents, hooks, commands, rules, and MCP configurations evolved over 10+ months of intensive daily use building real products.
+
+Works across **Claude Code**, **Codex**, **Cowork**, and other AI agent harnesses.
 
 ---
 
@@ -69,6 +75,28 @@ This repo is the raw code only. The guides explain everything.
 
 ## What's New
 
+### v1.9.0 — Selective Install & Language Expansion (Mar 2026)
+
+- **Selective install architecture** — Manifest-driven install pipeline with `install-plan.js` and `install-apply.js` for targeted component installation. State store tracks what's installed and enables incremental updates.
+- **6 new agents** — `typescript-reviewer`, `pytorch-build-resolver`, `java-build-resolver`, `java-reviewer`, `kotlin-reviewer`, `kotlin-build-resolver` expand language coverage to 10 languages.
+- **New skills** — `pytorch-patterns` for deep learning workflows, `documentation-lookup` for API reference research, `bun-runtime` and `nextjs-turbopack` for modern JS toolchains, plus 8 operational domain skills and `mcp-server-patterns`.
+- **Session & state infrastructure** — SQLite state store with query CLI, session adapters for structured recording, skill evolution foundation for self-improving skills.
+- **Orchestration overhaul** — Harness audit scoring made deterministic, orchestration status and launcher compatibility hardened, observer loop prevention with 5-layer guard.
+- **Observer reliability** — Memory explosion fix with throttling and tail sampling, sandbox access fix, lazy-start logic, and re-entrancy guard.
+- **12 language ecosystems** — New rules for Java, PHP, Perl, Kotlin/Android/KMP, C++, and Rust join existing TypeScript, Python, Go, and common rules.
+- **Community contributions** — Korean and Chinese translations, InsAIts security hook, biome hook optimization, VideoDB skills, Evos operational skills, PowerShell installer, Antigravity IDE support.
+- **CI hardening** — 19 test failure fixes, catalog count enforcement, install manifest validation, and full test suite green.
+
+### v1.8.0 — Harness Performance System (Mar 2026)
+
+- **Harness-first release** — ECC is now explicitly framed as an agent harness performance system, not just a config pack.
+- **Hook reliability overhaul** — SessionStart root fallback, Stop-phase session summaries, and script-based hooks replacing fragile inline one-liners.
+- **Hook runtime controls** — `ECC_HOOK_PROFILE=minimal|standard|strict` and `ECC_DISABLED_HOOKS=...` for runtime gating without editing hook files.
+- **New harness commands** — `/harness-audit`, `/loop-start`, `/loop-status`, `/quality-gate`, `/model-route`.
+- **NanoClaw v2** — model routing, skill hot-load, session branch/search/export/compact/metrics.
+- **Cross-harness parity** — behavior tightened across Claude Code, Cursor, OpenCode, and Codex app/CLI.
+- **997 internal tests passing** — full suite green after hook/runtime refactor and compatibility updates.
+
 ### v1.7.0 — Cross-Platform Expansion & Presentation Builder (Feb 2026)
 
 - **Codex app + CLI support** — Direct `AGENTS.md`-based Codex support, installer targeting, and Codex docs
@@ -139,12 +167,25 @@ Get up and running in under 2 minutes:
 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
-# You can pass multiple languages:
-# ./install.sh typescript python golang
-# or target cursor:
+# Install dependencies (pick your package manager)
+npm install        # or: pnpm install | yarn install | bun install
+
+# macOS/Linux
+./install.sh typescript    # or python or golang or swift or php
+# ./install.sh typescript python golang swift php
 # ./install.sh --target cursor typescript
+# ./install.sh --target antigravity typescript
+```
+
+```powershell
+# Windows PowerShell
+.\install.ps1 typescript   # or python or golang or swift or php
+# .\install.ps1 typescript python golang swift php
+# .\install.ps1 --target cursor typescript
+# .\install.ps1 --target antigravity typescript
+
+# npm-installed compatibility entrypoint also works cross-platform
+npx ecc-install typescript
 ```
 
 For manual install instructions see the README in the `rules/` folder.
@@ -162,13 +203,13 @@ For manual install instructions see the README in the `rules/` folder.
 /plugin list everything-claude-code@everything-claude-code
 ```
 
-✨ **That's it!** You now have access to 13 agents, 56 skills, and 32 commands.
+✨ **That's it!** You now have access to 27 agents, 109 skills, and 57 commands.
 
 ---
 
 ## 🌐 Cross-Platform Support
 
-This plugin now fully supports **Windows, macOS, and Linux**. All hooks and scripts have been rewritten in Node.js for maximum compatibility.
+This plugin now fully supports **Windows, macOS, and Linux**, alongside tight integration across major IDEs (Cursor, OpenCode, Antigravity) and CLI harnesses. All hooks and scripts have been rewritten in Node.js for maximum compatibility.
 
 ### Package Manager Detection
 
@@ -199,6 +240,18 @@ node scripts/setup-package-manager.js --detect
 
 Or use the `/setup-pm` command in Claude Code.
 
+### Hook Runtime Controls
+
+Use runtime flags to tune strictness or disable specific hooks temporarily:
+
+```bash
+# Hook strictness profile (default: standard)
+export ECC_HOOK_PROFILE=standard
+
+# Comma-separated hook IDs to disable
+export ECC_DISABLED_HOOKS="pre:bash:tmux-reminder,post:edit:typecheck"
+```
+
 ---
 
 ## 📦 What's Inside
@@ -211,7 +264,7 @@ everything-claude-code/
 |   |-- plugin.json         # Plugin metadata and component paths
 |   |-- marketplace.json    # Marketplace catalog for /plugin marketplace add
 |
-|-- agents/           # Specialized subagents for delegation
+|-- agents/           # 27 specialized subagents for delegation
 |   |-- planner.md           # Feature implementation planning
 |   |-- architect.md         # System design decisions
 |   |-- tdd-guide.md         # Test-driven development
@@ -221,10 +274,24 @@ everything-claude-code/
 |   |-- e2e-runner.md        # Playwright E2E testing
 |   |-- refactor-cleaner.md  # Dead code cleanup
 |   |-- doc-updater.md       # Documentation sync
+|   |-- docs-lookup.md       # Documentation/API lookup
+|   |-- chief-of-staff.md    # Communication triage and drafts
+|   |-- loop-operator.md     # Autonomous loop execution
+|   |-- harness-optimizer.md # Harness config tuning
+|   |-- cpp-reviewer.md      # C++ code review
+|   |-- cpp-build-resolver.md # C++ build error resolution
 |   |-- go-reviewer.md       # Go code review
 |   |-- go-build-resolver.md # Go build error resolution
-|   |-- python-reviewer.md   # Python code review (NEW)
-|   |-- database-reviewer.md # Database/Supabase review (NEW)
+|   |-- python-reviewer.md   # Python code review
+|   |-- database-reviewer.md # Database/Supabase review
+|   |-- typescript-reviewer.md # TypeScript/JavaScript code review
+|   |-- java-reviewer.md     # Java/Spring Boot code review
+|   |-- java-build-resolver.md # Java/Maven/Gradle build errors
+|   |-- kotlin-reviewer.md   # Kotlin/Android/KMP code review
+|   |-- kotlin-build-resolver.md # Kotlin/Gradle build errors
+|   |-- rust-reviewer.md     # Rust code review
+|   |-- rust-build-resolver.md # Rust build error resolution
+|   |-- pytorch-build-resolver.md # PyTorch/CUDA training errors
 |
 |-- skills/           # Workflow definitions and domain knowledge
 |   |-- coding-standards/           # Language best practices
@@ -245,6 +312,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)
@@ -253,6 +321,10 @@ everything-claude-code/
 |   |-- django-security/            # Django security best practices (NEW)
 |   |-- django-tdd/                 # Django TDD workflow (NEW)
 |   |-- django-verification/        # Django verification loops (NEW)
+|   |-- laravel-patterns/           # Laravel architecture patterns (NEW)
+|   |-- laravel-security/           # Laravel security best practices (NEW)
+|   |-- laravel-tdd/                # Laravel TDD workflow (NEW)
+|   |-- laravel-verification/       # Laravel verification loops (NEW)
 |   |-- python-patterns/            # Python idioms and best practices (NEW)
 |   |-- python-testing/             # Python testing with pytest (NEW)
 |   |-- springboot-patterns/        # Java Spring Boot patterns (NEW)
@@ -281,6 +353,11 @@ 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)
 |
 |-- commands/         # Slash commands for quick execution
 |   |-- tdd.md              # /tdd - Test-driven development
@@ -330,6 +407,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
@@ -365,6 +444,7 @@ everything-claude-code/
 |   |-- saas-nextjs-CLAUDE.md   # Real-world SaaS (Next.js + Supabase + Stripe)
 |   |-- go-microservice-CLAUDE.md # Real-world Go microservice (gRPC + PostgreSQL)
 |   |-- django-api-CLAUDE.md      # Real-world Django REST API (DRF + Celery)
+|   |-- laravel-api-CLAUDE.md     # Real-world Laravel API (PostgreSQL + Redis) (NEW)
 |   |-- rust-api-CLAUDE.md        # Real-world Rust API (Axum + SQLx + PostgreSQL) (NEW)
 |
 |-- mcp-configs/      # MCP server configurations
@@ -440,6 +520,10 @@ Use `/security-scan` in Claude Code to run it, or add to CI with the [GitHub Act
 
 [GitHub](https://github.com/affaan-m/agentshield) | [npm](https://www.npmjs.com/package/ecc-agentshield)
 
+### 🔬 Plankton — Write-Time Code Quality Enforcement
+
+Plankton (credit: @alxfazio) is a recommended companion for write-time code quality enforcement. It runs formatters and 20+ linters on every file edit via PostToolUse hooks, then spawns Claude subprocesses (routed to Haiku/Sonnet/Opus by violation complexity) to fix issues the main agent missed. Three-phase architecture: auto-format silently (40-50% of issues), collect remaining violations as structured JSON, delegate fixes to a subprocess. Includes config protection hooks that prevent agents from modifying linter configs to pass instead of fixing code. Supports Python, TypeScript, Shell, YAML, JSON, TOML, Markdown, and Dockerfile. Use alongside AgentShield for security + quality coverage. See `skills/plankton-code-quality/` for full integration guide.
+
 ### 🧠 Continuous Learning v2
 
 The instinct-based learning system automatically learns your patterns:
@@ -528,6 +612,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
@@ -553,12 +638,20 @@ 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/
 
-# Copy skills
-cp -r everything-claude-code/skills/* ~/.claude/skills/
+# Copy skills (core vs niche)
+# Recommended (new users): core/general skills only
+cp -r everything-claude-code/.agents/skills/* ~/.claude/skills/
+cp -r everything-claude-code/skills/search-first ~/.claude/skills/
+
+# Optional: add niche/framework-specific skills only when needed
+# for s in django-patterns django-tdd laravel-patterns springboot-patterns; do
+#   cp -r everything-claude-code/skills/$s ~/.claude/skills/
+# done
 ```
 
 #### Add hooks to settings.json
@@ -628,6 +721,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.
@@ -651,6 +746,7 @@ Not sure where to start? Use this quick reference:
 | Update documentation | `/update-docs` | doc-updater |
 | Review Go code | `/go-review` | go-reviewer |
 | Review Python code | `/python-review` | python-reviewer |
+| Review TypeScript/JavaScript code | *(invoke `typescript-reviewer` directly)* | typescript-reviewer |
 | Audit database queries | *(auto-delegated)* | database-reviewer |
 
 ### Common Workflows
@@ -697,6 +793,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>
 
@@ -730,12 +851,13 @@ Each component is fully independent.
 </details>
 
 <details>
-<summary><b>Does this work with Cursor / OpenCode / Codex?</b></summary>
+<summary><b>Does this work with Cursor / OpenCode / Codex / Antigravity?</b></summary>
 
 Yes. ECC is cross-platform:
 - **Cursor**: Pre-translated configs in `.cursor/`. See [Cursor IDE Support](#cursor-ide-support).
 - **OpenCode**: Full plugin support in `.opencode/`. See [OpenCode Support](#-opencode-support).
-- **Codex**: First-class support with adapter drift guards and SessionStart fallback. See PR [#257](https://github.com/affaan-m/everything-claude-code/pull/257).
+- **Codex**: First-class support for both macOS app and CLI, with adapter drift guards and SessionStart fallback. See PR [#257](https://github.com/affaan-m/everything-claude-code/pull/257).
+- **Antigravity**: Tightly integrated setup for workflows, skills, and flattened rules in `.agent/`. See [Antigravity Guide](docs/ANTIGRAVITY-GUIDE.md).
 - **Claude Code**: Native — this is the primary target.
 </details>
 
@@ -781,8 +903,8 @@ Please contribute! See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
 
 ### Ideas for Contributions
 
-- Language-specific skills (Rust, C#, Swift, Kotlin) — Go, Python, Java already included
-- Framework-specific configs (Rails, Laravel, FastAPI, NestJS) — Django, Spring Boot already included
+- Language-specific skills (Rust, C#, Kotlin, Java) — Go, Python, Perl, Swift, and TypeScript already included
+- Framework-specific configs (Rails, FastAPI, NestJS) — Django, Spring Boot, Laravel already included
 - DevOps agents (Kubernetes, Terraform, AWS, Docker)
 - Testing strategies (different frameworks, visual regression)
 - Domain-specific knowledge (ML, data engineering, mobile)
@@ -796,9 +918,15 @@ ECC provides **full Cursor IDE support** with hooks, rules, agents, skills, comm
 ### Quick Start (Cursor)
 
 ```bash
-# Install for your language(s)
+# macOS/Linux
 ./install.sh --target cursor typescript
-./install.sh --target cursor python golang swift
+./install.sh --target cursor python golang swift php
+```
+
+```powershell
+# Windows PowerShell
+.\install.ps1 --target cursor typescript
+.\install.ps1 --target cursor python golang swift php
 ```
 
 ### What's Included
@@ -807,7 +935,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 |
@@ -843,29 +971,37 @@ alwaysApply: false
 
 ---
 
-## Codex CLI Support
+## Codex macOS App + CLI Support
 
-ECC provides **first-class Codex CLI support** with a reference configuration, Codex-specific AGENTS.md supplement, and 16 ported skills.
+ECC provides **first-class Codex support** for both the macOS app and CLI, with a reference configuration, Codex-specific AGENTS.md supplement, and shared skills.
 
-### Quick Start (Codex)
+### Quick Start (Codex App + CLI)
 
 ```bash
-# Copy the reference config to your home directory
-cp .codex/config.toml ~/.codex/config.toml
-
-# Run Codex 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.
+- `.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
 
@@ -892,7 +1028,24 @@ Skills at `.agents/skills/` are auto-loaded by Codex:
 
 ### Key Limitation
 
-Codex CLI does **not yet support hooks** ([GitHub Issue #2109](https://github.com/openai/codex/issues/2109), 430+ upvotes). Security enforcement is instruction-based via `persistent_instructions` in config.toml and the sandbox permission system.
+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 |
 
 ---
 
@@ -916,9 +1069,9 @@ The configuration is automatically detected from `.opencode/opencode.json`.
 
 | Feature | Claude Code | OpenCode | Status |
 |---------|-------------|----------|--------|
-| Agents | ✅ 13 agents | ✅ 12 agents | **Claude Code leads** |
-| Commands | ✅ 33 commands | ✅ 24 commands | **Claude Code leads** |
-| Skills | ✅ 50+ skills | ✅ 37 skills | **Claude Code leads** |
+| Agents | ✅ 27 agents | ✅ 12 agents | **Claude Code leads** |
+| Commands | ✅ 57 commands | ✅ 31 commands | **Claude Code leads** |
+| Skills | ✅ 109 skills | ✅ 37 skills | **Claude Code leads** |
 | Hooks | ✅ 8 event types | ✅ 11 events | **OpenCode has more!** |
 | Rules | ✅ 29 rules | ✅ 13 instructions | **Claude Code leads** |
 | MCP Servers | ✅ 14 servers | ✅ Full | **Full parity** |
@@ -938,7 +1091,7 @@ OpenCode's plugin system is MORE sophisticated than Claude Code with 20+ event t
 
 **Additional OpenCode events**: `file.edited`, `file.watcher.updated`, `message.updated`, `lsp.client.diagnostics`, `tui.toast.show`, and more.
 
-### Available Commands (32)
+### Available Commands (31+)
 
 | Command | Description |
 |---------|-------------|
@@ -972,8 +1125,15 @@ OpenCode's plugin system is MORE sophisticated than Claude Code with 20+ event t
 | `/instinct-import` | Import instincts |
 | `/instinct-export` | Export instincts |
 | `/evolve` | Cluster instincts into skills |
+| `/promote` | Promote project instincts to global scope |
+| `/projects` | List known projects and instinct stats |
 | `/learn-eval` | Extract and evaluate patterns before saving |
 | `/setup-pm` | Configure package manager |
+| `/harness-audit` | Audit harness reliability, eval readiness, and risk posture |
+| `/loop-start` | Start controlled agentic loop execution pattern |
+| `/loop-status` | Inspect active loop status and checkpoints |
+| `/quality-gate` | Run quality gate checks for paths or entire repo |
+| `/model-route` | Route tasks to models by complexity and budget |
 
 ### Plugin Installation
 
@@ -995,6 +1155,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`
@@ -1010,25 +1177,25 @@ ECC is the **first plugin to maximize every major AI coding tool**. Here's how e
 
 | Feature | Claude Code | Cursor IDE | Codex CLI | OpenCode |
 |---------|------------|------------|-----------|----------|
-| **Agents** | 13 | Shared (AGENTS.md) | Shared (AGENTS.md) | 12 |
-| **Commands** | 33 | Shared | Instruction-based | 24 |
-| **Skills** | 50+ | Shared | 10 (native format) | 37 |
+| **Agents** | 21 | Shared (AGENTS.md) | Shared (AGENTS.md) | 12 |
+| **Commands** | 52 | Shared | Instruction-based | 31 |
+| **Skills** | 102 | Shared | 10 (native format) | 37 |
 | **Hook Events** | 8 types | 15 types | None yet | 11 types |
-| **Hook Scripts** | 9 scripts | 16 scripts (DRY adapter) | N/A | Plugin hooks |
-| **Rules** | 29 (common + lang) | 29 (YAML frontmatter) | Instruction-based | 13 instructions |
+| **Hook Scripts** | 20+ scripts | 16 scripts (DRY adapter) | N/A | Plugin hooks |
+| **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 |
 | **Context File** | CLAUDE.md + AGENTS.md | AGENTS.md | AGENTS.md | AGENTS.md |
 | **Secret Detection** | Hook-based | beforeSubmitPrompt hook | Sandbox-based | Hook-based |
 | **Auto-Format** | PostToolUse hook | afterFileEdit hook | N/A | file.edited hook |
-| **Version** | Plugin | Plugin | Reference config | 1.6.0 |
+| **Version** | Plugin | Plugin | Reference config | 1.9.0 |
 
 **Key architectural decisions:**
 - **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
 
 ---
 
@@ -1038,6 +1205,11 @@ I've been using Claude Code since the experimental rollout. Won the Anthropic x
 
 These configs are battle-tested across multiple production applications.
 
+## Inspiration Credits
+
+- inspired by [zarazhangrui](https://github.com/zarazhangrui)
+- homunculus-inspired by [humanplane](https://github.com/humanplane)
+
 ---
 
 ## Token Optimization
@@ -1142,7 +1314,7 @@ These configs work for my workflow. You should:
 
 This project is free and open source. Sponsors help keep it maintained and growing.
 
-[**Become a Sponsor**](https://github.com/sponsors/affaan-m) | [Sponsor Tiers](SPONSORS.md)
+[**Become a Sponsor**](https://github.com/sponsors/affaan-m) | [Sponsor Tiers](SPONSORS.md) | [Sponsorship Program](SPONSORING.md)
 
 ---
 

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 等）
@@ -287,6 +303,8 @@ everything-claude-code/
 /instinct-import <file> # 从他人导入直觉
 /instinct-export        # 导出你的直觉以供分享
 /evolve                 # 将相关直觉聚类到技能中
+/promote                # 将项目级直觉提升为全局直觉
+/projects               # 查看已识别项目与直觉统计
 ```
 
 完整文档见 `skills/continuous-learning-v2/`。
@@ -354,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/
@@ -423,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 特定模式和工具
 ```
 
 ---
@@ -464,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）
 - 测试策略（不同框架）

SPONSORING.md

@@ -0,0 +1,43 @@
+# Sponsoring ECC
+
+ECC is maintained as an open-source agent harness performance system across Claude Code, Cursor, OpenCode, and Codex app/CLI.
+
+## Why Sponsor
+
+Sponsorship directly funds:
+
+- Faster bug-fix and release cycles
+- Cross-platform parity work across harnesses
+- Public docs, skills, and reliability tooling that remain free for the community
+
+## Sponsorship Tiers
+
+These are practical starting points and can be adjusted for partnership scope.
+
+| Tier | Price | Best For | Includes |
+|------|-------|----------|----------|
+| Pilot Partner | $200/mo | First sponsor engagement | Monthly metrics update, roadmap preview, prioritized maintainer feedback |
+| Growth Partner | $500/mo | Teams actively adopting ECC | Pilot benefits + monthly office-hours sync + workflow integration guidance |
+| Strategic Partner | $1,000+/mo | Platform/ecosystem partnerships | Growth benefits + coordinated launch support + deeper maintainer collaboration |
+
+## Sponsor Reporting
+
+Metrics shared monthly can include:
+
+- npm downloads (`ecc-universal`, `ecc-agentshield`)
+- Repository adoption (stars, forks, contributors)
+- GitHub App install trend
+- Release cadence and reliability milestones
+
+For exact command snippets and a repeatable pull process, see [`docs/business/metrics-and-sponsorship.md`](docs/business/metrics-and-sponsorship.md).
+
+## Expectations and Scope
+
+- Sponsorship supports maintenance and acceleration; it does not transfer project ownership.
+- Feature requests are prioritized based on sponsor tier, ecosystem impact, and maintenance risk.
+- Security and reliability fixes take precedence over net-new features.
+
+## Sponsor Here
+
+- GitHub Sponsors: [https://github.com/sponsors/affaan-m](https://github.com/sponsors/affaan-m)
+- Project site: [https://ecc.tools](https://ecc.tools)

SPONSORS.md

@@ -29,6 +29,17 @@ Your sponsorship helps:
 - **Better support** — Sponsors get priority responses
 - **Shape the roadmap** — Pro+ sponsors vote on features
 
+## Sponsor Readiness Signals
+
+Use these proof points in sponsor conversations:
+
+- Live npm install/download metrics for `ecc-universal` and `ecc-agentshield`
+- GitHub App distribution via Marketplace installs
+- Public adoption signals: stars, forks, contributors, release cadence
+- Cross-harness support: Claude Code, Cursor, OpenCode, Codex app/CLI
+
+See [`docs/business/metrics-and-sponsorship.md`](docs/business/metrics-and-sponsorship.md) for a copy/paste metrics pull workflow.
+
 ## Sponsor Tiers
 
 | Tier | Price | Benefits |
@@ -37,6 +48,7 @@ Your sponsorship helps:
 | Builder | $10/mo | Premium tools access |
 | Pro | $25/mo | Priority support, office hours |
 | Team | $100/mo | 5 seats, team configs |
+| Harness Partner | $200/mo | Monthly roadmap sync, prioritized maintainer feedback, release-note mention |
 | Business | $500/mo | 25 seats, consulting credit |
 | Enterprise | $2K/mo | Unlimited seats, custom tools |
 

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