zsp/everything-claude-code
1
0
Fork 0
mirror of https://github.com/affaan-m/everything-claude-code.git synced 2026-03-30 13:43:26 +08:00
Code Issues Packages Projects Releases Wiki Activity

Compare commits

base: zsp:affaan/laravel-plugin-discovery-refresh
Branches Tags
zsp:main zsp:fix/unicode-safety-eslint-regex zsp:fix/harness-audit-consumer-mode zsp:fix/trae-manifest-ownership zsp:fix/mcp-json-exa-type zsp:fix/stop-hook-inline-resolver zsp:fix/stop-hook-root zsp:fix/mcp-json-http-schema zsp:fix/codex-context7-compat-tests zsp:fix/clv2-config-override-rebase zsp:fix/token-budget-advisor-trigger-clarity zsp:fix/readme-agent-count-tree zsp:fix/token-budget-advisor-refresh zsp:fix/healthcare-eval-harness-followup zsp:affaan/laravel-plugin-discovery-refresh zsp:fix/yarn-lock-sync zsp:fix/ecc2-analysis-report-facts zsp:feat/hermes-generated-ops-skills zsp:ecc-tools/everything-claude-code-1774349083491 zsp:ecc-tools/everything-claude-code-1774349061959 zsp:ecc-tools/everything-claude-code-1774349055184 zsp:ecc-tools/everything-claude-code-1774349050387 zsp:ecc-tools/everything-claude-code-1774348792519
zsp:v1.9.0 zsp:v1.8.0 zsp:v1.7.0 zsp:v1.6.0 zsp:v1.5.0 zsp:v1.4.1 zsp:v1.4.0 zsp:v1.3.0 zsp:v1.2.0 zsp:v0.6.0 zsp:v1.1.0 zsp:v1.0.0
..
compare: zsp:148fc726cb20e1a0b592595c56a3adb9771c88db
Branches Tags
zsp:fix/unicode-safety-eslint-regex zsp:main zsp:fix/harness-audit-consumer-mode zsp:fix/trae-manifest-ownership zsp:fix/mcp-json-exa-type zsp:fix/stop-hook-inline-resolver zsp:fix/stop-hook-root zsp:fix/mcp-json-http-schema zsp:fix/codex-context7-compat-tests zsp:fix/clv2-config-override-rebase zsp:fix/token-budget-advisor-trigger-clarity zsp:fix/readme-agent-count-tree zsp:fix/token-budget-advisor-refresh zsp:fix/healthcare-eval-harness-followup zsp:affaan/laravel-plugin-discovery-refresh zsp:fix/yarn-lock-sync zsp:fix/ecc2-analysis-report-facts zsp:feat/hermes-generated-ops-skills zsp:ecc-tools/everything-claude-code-1774349083491 zsp:ecc-tools/everything-claude-code-1774349061959 zsp:ecc-tools/everything-claude-code-1774349055184 zsp:ecc-tools/everything-claude-code-1774349050387 zsp:ecc-tools/everything-claude-code-1774348792519
zsp:v1.9.0 zsp:v1.8.0 zsp:v1.7.0 zsp:v1.6.0 zsp:v1.5.0 zsp:v1.4.1 zsp:v1.4.0 zsp:v1.3.0 zsp:v1.2.0 zsp:v0.6.0 zsp:v1.1.0 zsp:v1.0.0

1 Commits
affaan/lar ... 148fc726cb

Author SHA1 Message Date
Affaan Mustafa
148fc726cb feat(ecc2): implement live output streaming per agent (#774) 
- PTY output capture via tokio::process with stdout/stderr piping
- Ring buffer (1000 lines) per session
- Output pane wired to show selected session with auto-scroll
- Broadcast channel for output events
 2026-03-24 03:54:15 -07:00
146 changed files with 1121 additions and 11154 deletions
Expand all files Collapse all files

20
.agents/plugins/marketplace.json
View File

@@ -1,20 +0,0 @@
{
"name": "everything-claude-code",
"interface": {
"displayName": "Everything Claude Code"
},
"plugins": [
{
"name": "everything-claude-code",
"source": {
"source": "local",
"path": "../.."
},
"policy": {
"installation": "AVAILABLE",
"authentication": "ON_INSTALL"
},
"category": "Productivity"
}
]
}

34
.claude-plugin/plugin.json
View File

@@ -21,37 +21,5 @@
"workflow",
"automation",
"best-practices"
],
"agents": [
"./agents/architect.md",
"./agents/build-error-resolver.md",
"./agents/chief-of-staff.md",
"./agents/code-reviewer.md",
"./agents/cpp-build-resolver.md",
"./agents/cpp-reviewer.md",
"./agents/database-reviewer.md",
"./agents/doc-updater.md",
"./agents/docs-lookup.md",
"./agents/e2e-runner.md",
"./agents/flutter-reviewer.md",
"./agents/go-build-resolver.md",
"./agents/go-reviewer.md",
"./agents/harness-optimizer.md",
"./agents/java-build-resolver.md",
"./agents/java-reviewer.md",
"./agents/kotlin-build-resolver.md",
"./agents/kotlin-reviewer.md",
"./agents/loop-operator.md",
"./agents/planner.md",
"./agents/python-reviewer.md",
"./agents/pytorch-build-resolver.md",
"./agents/refactor-cleaner.md",
"./agents/rust-build-resolver.md",
"./agents/rust-reviewer.md",
"./agents/security-reviewer.md",
"./agents/tdd-guide.md",
"./agents/typescript-reviewer.md"
],
"skills": ["./skills/"],
"commands": ["./commands/"]
]
}

47
.claude/rules/node.md
View File

@@ -1,47 +0,0 @@
# Node.js Rules for everything-claude-code
> Project-specific rules for the ECC codebase. Extends common rules.
## Stack
- **Runtime**: Node.js >=18 (no transpilation, plain CommonJS)
- **Test runner**: `node tests/run-all.js` — individual files via `node tests/**/*.test.js`
- **Linter**: ESLint (`@eslint/js`, flat config)
- **Coverage**: c8
- **Lint**: markdownlint-cli for `.md` files
## File Conventions
- `scripts/` — Node.js utilities, hooks. CommonJS (`require`/`module.exports`)
- `agents/`, `commands/`, `skills/`, `rules/` — Markdown with YAML frontmatter
- `tests/` — Mirror the `scripts/` structure. Test files named `*.test.js`
- File naming: **lowercase with hyphens** (e.g. `session-start.js`, `post-edit-format.js`)
## Code Style
- CommonJS only — no ESM (`import`/`export`) unless file ends in `.mjs`
- No TypeScript — plain `.js` throughout
- Prefer `const` over `let`; never `var`
- Keep hook scripts under 200 lines — extract helpers to `scripts/lib/`
- All hooks must `exit 0` on non-critical errors (never block tool execution unexpectedly)
## Hook Development
- Hook scripts normally receive JSON on stdin, but hooks routed through `scripts/hooks/run-with-flags.js` can export `run(rawInput)` and let the wrapper handle parsing/gating
- Async hooks: mark `"async": true` in `settings.json` with a timeout ≤30s
- Blocking hooks (PreToolUse, stop): keep fast (<200ms) — no network calls
- Use `run-with-flags.js` wrapper for all hooks so `ECC_HOOK_PROFILE` and `ECC_DISABLED_HOOKS` runtime gating works
- Always exit 0 on parse errors; log to stderr with `[HookName]` prefix
## Testing Requirements
- Run `node tests/run-all.js` before committing
- New scripts in `scripts/lib/` require a matching test in `tests/lib/`
- New hooks require at least one integration test in `tests/hooks/`
## Markdown / Agent Files
- Agents: YAML frontmatter with `name`, `description`, `tools`, `model`
- Skills: sections — When to Use, How It Works, Examples
- Commands: `description:` frontmatter line required
- Run `npx markdownlint-cli '**/*.md' --ignore node_modules` before committing

49
.codex-plugin/README.md
View File

@@ -1,49 +0,0 @@
# .codex-plugin — Codex Native Plugin for ECC
This directory contains the **Codex plugin manifest** for Everything Claude Code.
## Structure
```
.codex-plugin/
└── plugin.json — Codex plugin manifest (name, version, skills ref, MCP ref)
.mcp.json — MCP server configurations at plugin root (NOT inside .codex-plugin/)
```
## What This Provides
- **125 skills** from `./skills/` — reusable Codex workflows for TDD, security,
code review, architecture, and more
- **6 MCP servers** — GitHub, Context7, Exa, Memory, Playwright, Sequential Thinking
## Installation
Codex plugin support is currently in preview. Once generally available:
```bash
# Install from Codex CLI
codex plugin install affaan-m/everything-claude-code
# Or reference locally during development
codex plugin install ./
Run this from the repository root so `./` points to the repo root and `.mcp.json` resolves correctly.
```
## MCP Servers Included
| Server | Purpose |
|---|---|
| `github` | GitHub API access |
| `context7` | Live documentation lookup |
| `exa` | Neural web search |
| `memory` | Persistent memory across sessions |
| `playwright` | Browser automation & E2E testing |
| `sequential-thinking` | Step-by-step reasoning |
## Notes
- The `skills/` directory at the repo root is shared between Claude Code (`.claude-plugin/`)
and Codex (`.codex-plugin/`) — same source of truth, no duplication
- MCP server credentials are inherited from the launching environment (env vars)
- This manifest does **not** override `~/.codex/config.toml` settings

30
.codex-plugin/plugin.json
View File

@@ -1,30 +0,0 @@
{
"name": "everything-claude-code",
"version": "1.9.0",
"description": "Battle-tested Codex workflows — 125 skills, production-ready MCP configs, and agent definitions for TDD, security scanning, code review, and autonomous development.",
"author": {
"name": "Affaan Mustafa",
"email": "me@affaanmustafa.com",
"url": "https://x.com/affaanmustafa"
},
"homepage": "https://github.com/affaan-m/everything-claude-code",
"repository": "https://github.com/affaan-m/everything-claude-code",
"license": "MIT",
"keywords": ["codex", "agents", "skills", "tdd", "code-review", "security", "workflow", "automation"],
"skills": "./skills/",
"mcpServers": "./.mcp.json",
"interface": {
"displayName": "Everything Claude Code",
"shortDescription": "125 battle-tested skills for TDD, security, code review, and autonomous development.",
"longDescription": "Everything Claude Code (ECC) is a community-maintained collection of Codex skills and MCP configs evolved over 10+ months of intensive daily use. It covers TDD workflows, security scanning, code review, architecture decisions, and more — all in one installable plugin.",
"developerName": "Affaan Mustafa",
"category": "Productivity",
"capabilities": ["Read", "Write"],
"websiteURL": "https://github.com/affaan-m/everything-claude-code",
"defaultPrompt": [
"Use the tdd-workflow skill to write tests before implementation.",
"Use the security-review skill to scan for OWASP Top 10 vulnerabilities.",
"Use the code-review skill to review this PR for correctness and security."
]
}
}

3
.codex/AGENTS.md
View File

@@ -46,15 +46,12 @@ Available skills:
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.
ECC's canonical Codex section name is `[mcp_servers.context7]`. The launcher package remains `@upstash/context7-mcp`; only the TOML section name is normalized for consistency with `codex mcp list` and the reference config.
### Automatic config.toml merging
The sync script (`scripts/sync-ecc-to-codex.sh`) uses a Node-based TOML parser to safely merge ECC MCP servers into `~/.codex/config.toml`:
- **Add-only by default** — missing ECC servers are appended; existing servers are never modified or removed.
- **7 managed servers** — Supabase, Playwright, Context7, Exa, GitHub, Memory, Sequential Thinking.
- **Canonical naming** — ECC manages Context7 as `[mcp_servers.context7]`; legacy `[mcp_servers.context7-mcp]` entries are treated as aliases during updates.
- **Package-manager aware** — uses the project's configured package manager (npm/pnpm/yarn/bun) instead of hardcoding `pnpm`.
- **Drift warnings** — if an existing server's config differs from the ECC recommendation, the script logs a warning.
- **`--update-mcp`** — explicitly replaces all ECC-managed servers with the latest recommended config (safely removes subtables like `[mcp_servers.supabase.env]`).

12
.codex/config.toml
View File

@@ -27,10 +27,7 @@ notify = [
"-sound", "default",
]
# Persistent instructions are appended to every prompt (additive, unlike
# model_instructions_file which replaces AGENTS.md).
persistent_instructions = "Follow project AGENTS.md guidelines. Use available MCP servers when they can help."
# 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"
@@ -41,14 +38,10 @@ persistent_instructions = "Follow project AGENTS.md guidelines. Use available MC
[mcp_servers.github]
command = "npx"
args = ["-y", "@modelcontextprotocol/server-github"]
startup_timeout_sec = 30
[mcp_servers.context7]
command = "npx"
# Canonical Codex section name is `context7`; the package itself remains
# `@upstash/context7-mcp`.
args = ["-y", "@upstash/context7-mcp@latest"]
startup_timeout_sec = 30
[mcp_servers.exa]
url = "https://mcp.exa.ai/mcp"
@@ -56,17 +49,14 @@ url = "https://mcp.exa.ai/mcp"
[mcp_servers.memory]
command = "npx"
args = ["-y", "@modelcontextprotocol/server-memory"]
startup_timeout_sec = 30
[mcp_servers.playwright]
command = "npx"
args = ["-y", "@playwright/mcp@latest", "--extension"]
startup_timeout_sec = 30
[mcp_servers.sequential-thinking]
command = "npx"
args = ["-y", "@modelcontextprotocol/server-sequential-thinking"]
startup_timeout_sec = 30
# Additional MCP servers (uncomment as needed):
# [mcp_servers.supabase]

25
.github/workflows/ci.yml vendored
View File

@@ -44,20 +44,13 @@ jobs:
# Package manager setup
- name: Setup pnpm
if: matrix.pm == 'pnpm'
uses: pnpm/action-setup@fc06bc1257f339d1d5d8b3a19a8cae5388b55320 # v4
uses: pnpm/action-setup@v4
with:
version: latest
- name: Setup Yarn (via Corepack)
if: matrix.pm == 'yarn'
shell: bash
run: |
corepack enable
corepack prepare yarn@stable --activate
- name: Setup Bun
if: matrix.pm == 'bun'
uses: oven-sh/setup-bun@0c5077e51419868618aeaa5fe8019c62421857d6 # v2
uses: oven-sh/setup-bun@v2
# Cache configuration
- name: Get npm cache directory
@@ -121,18 +114,14 @@ jobs:
${{ runner.os }}-bun-
# Install dependencies
# COREPACK_ENABLE_STRICT=0 allows pnpm to install even though
# package.json declares "packageManager": "yarn@..."
- name: Install dependencies
shell: bash
env:
COREPACK_ENABLE_STRICT: '0'
run: |
case "${{ matrix.pm }}" in
npm) npm ci ;;
pnpm) pnpm install --no-frozen-lockfile ;;
# Yarn Berry (v4+) removed --ignore-engines; engine checking is no longer a core feature
yarn) yarn install ;;
pnpm) pnpm install ;;
# --ignore-engines required for Node 18 compat with some devDependencies (e.g., markdownlint-cli)
yarn) yarn install --ignore-engines ;;
bun) bun install ;;
*) echo "Unsupported package manager: ${{ matrix.pm }}" && exit 1 ;;
esac
@@ -186,10 +175,6 @@ jobs:
run: node scripts/ci/validate-skills.js
continue-on-error: false
- name: Validate install manifests
run: node scripts/ci/validate-install-manifests.js
continue-on-error: false
- name: Validate rules
run: node scripts/ci/validate-rules.js
continue-on-error: false

6
.github/workflows/release.yml vendored
View File

@@ -20,13 +20,11 @@ jobs:
- name: Validate version tag
run: |
if ! [[ "${REF_NAME}" =~ ^v[0-9]+\.[0-9]+\.[0-9]+$ ]]; then
if ! [[ "${{ github.ref_name }}" =~ ^v[0-9]+\.[0-9]+\.[0-9]+$ ]]; then
echo "Invalid version tag format. Expected vX.Y.Z"
exit 1
fi
env:
REF_NAME: ${{ github.ref_name }}
- name: Verify plugin.json version matches tag
env:
TAG_NAME: ${{ github.ref_name }}
@@ -63,7 +61,7 @@ jobs:
EOF
- name: Create GitHub Release
uses: softprops/action-gh-release@153bb8e04406b158c6c84fc1615b65b24149a1fe # v2
uses: softprops/action-gh-release@v2
with:
body_path: release_body.md
generate_release_notes: true

2
.github/workflows/reusable-release.yml vendored
View File

@@ -49,7 +49,7 @@ jobs:
EOF
- name: Create GitHub Release
uses: softprops/action-gh-release@153bb8e04406b158c6c84fc1615b65b24149a1fe # v2
uses: softprops/action-gh-release@v2
with:
tag_name: ${{ inputs.tag }}
body_path: release_body.md

20
.github/workflows/reusable-test.yml vendored
View File

@@ -36,20 +36,13 @@ jobs:
- name: Setup pnpm
if: inputs.package-manager == 'pnpm'
uses: pnpm/action-setup@fc06bc1257f339d1d5d8b3a19a8cae5388b55320 # v4
uses: pnpm/action-setup@v4
with:
version: latest
- name: Setup Yarn (via Corepack)
if: inputs.package-manager == 'yarn'
shell: bash
run: |
corepack enable
corepack prepare yarn@stable --activate
- name: Setup Bun
if: inputs.package-manager == 'bun'
uses: oven-sh/setup-bun@0c5077e51419868618aeaa5fe8019c62421857d6 # v2
uses: oven-sh/setup-bun@v2
- name: Get npm cache directory
if: inputs.package-manager == 'npm'
@@ -111,18 +104,13 @@ jobs:
restore-keys: |
${{ runner.os }}-bun-
# COREPACK_ENABLE_STRICT=0 allows pnpm to install even though
# package.json declares "packageManager": "yarn@..."
- name: Install dependencies
shell: bash
env:
COREPACK_ENABLE_STRICT: '0'
run: |
case "${{ inputs.package-manager }}" in
npm) npm ci ;;
pnpm) pnpm install --no-frozen-lockfile ;;
# Yarn Berry (v4+) removed --ignore-engines; engine checking is no longer a core feature
yarn) yarn install ;;
pnpm) pnpm install ;;
yarn) yarn install --ignore-engines ;;
bun) bun install ;;
*) echo "Unsupported package manager: ${{ inputs.package-manager }}" && exit 1 ;;
esac

3
.github/workflows/reusable-validate.yml vendored
View File

@@ -39,8 +39,5 @@ jobs:
- name: Validate skills
run: node scripts/ci/validate-skills.js
- name: Validate install manifests
run: node scripts/ci/validate-install-manifests.js
- name: Validate rules
run: node scripts/ci/validate-rules.js

3
.gitignore vendored
View File

@@ -83,9 +83,6 @@ temp/
*.bak
*.backup
# Observer temp files (continuous-learning-v2)
.observer-tmp/
# Rust build artifacts
ecc2/target/

27
.mcp.json
View File

@@ -1,27 +0,0 @@
{
"mcpServers": {
"github": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-github"]
},
"context7": {
"command": "npx",
"args": ["-y", "@upstash/context7-mcp@2.1.4"]
},
"exa": {
"url": "https://mcp.exa.ai/mcp"
},
"memory": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-memory"]
},
"playwright": {
"command": "npx",
"args": ["-y", "@playwright/mcp@0.0.68", "--extension"]
},
"sequential-thinking": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-sequential-thinking"]
}
}
}

1
.yarnrc.yml
View File

@@ -1 +0,0 @@
nodeLinker: node-modules

4
AGENTS.md
View File

@@ -1,6 +1,6 @@
# Everything Claude Code (ECC) — Agent Instructions
This is a **production-ready AI coding plugin** providing 28 specialized agents, 126 skills, 60 commands, and automated hook workflows for software development.
This is a **production-ready AI coding plugin** providing 28 specialized agents, 125 skills, 60 commands, and automated hook workflows for software development.
**Version:** 1.9.0
@@ -142,7 +142,7 @@ Troubleshoot failures: check test isolation → verify mocks → fix implementat
```
agents/ — 28 specialized subagents
skills/ — 126 workflow skills and domain knowledge
skills/ — 117 workflow skills and domain knowledge
commands/ — 60 slash commands
hooks/ — Trigger-based automations
rules/ — Always-follow guidelines (common + per-language)

159
COMMANDS-QUICK-REF.md
View File

@@ -1,159 +0,0 @@
# Commands Quick Reference
> 59 slash commands installed globally. Type `/` in any Claude Code session to invoke.
---
## Core Workflow
| Command | What it does |
|---------|-------------|
| `/plan` | Restate requirements, assess risks, write step-by-step implementation plan — **waits for your confirm before touching code** |
| `/tdd` | Enforce test-driven development: scaffold interface → write failing test → implement → verify 80%+ coverage |
| `/code-review` | Full code quality, security, and maintainability review of changed files |
| `/build-fix` | Detect and fix build errors — delegates to the right build-resolver agent automatically |
| `/verify` | Run the full verification loop: build → lint → test → type-check |
| `/quality-gate` | Quality gate check against project standards |
---
## Testing
| Command | What it does |
|---------|-------------|
| `/tdd` | Universal TDD workflow (any language) |
| `/e2e` | Generate + run Playwright end-to-end tests, capture screenshots/videos/traces |
| `/test-coverage` | Report test coverage, identify gaps |
| `/go-test` | TDD workflow for Go (table-driven, 80%+ coverage with `go test -cover`) |
| `/kotlin-test` | TDD for Kotlin (Kotest + Kover) |
| `/rust-test` | TDD for Rust (cargo test, integration tests) |
| `/cpp-test` | TDD for C++ (GoogleTest + gcov/lcov) |
---
## Code Review
| Command | What it does |
|---------|-------------|
| `/code-review` | Universal code review |
| `/python-review` | Python — PEP 8, type hints, security, idiomatic patterns |
| `/go-review` | Go — idiomatic patterns, concurrency safety, error handling |
| `/kotlin-review` | Kotlin — null safety, coroutine safety, clean architecture |
| `/rust-review` | Rust — ownership, lifetimes, unsafe usage |
| `/cpp-review` | C++ — memory safety, modern idioms, concurrency |
---
## Build Fixers
| Command | What it does |
|---------|-------------|
| `/build-fix` | Auto-detect language and fix build errors |
| `/go-build` | Fix Go build errors and `go vet` warnings |
| `/kotlin-build` | Fix Kotlin/Gradle compiler errors |
| `/rust-build` | Fix Rust build + borrow checker issues |
| `/cpp-build` | Fix C++ CMake and linker problems |
| `/gradle-build` | Fix Gradle errors for Android / KMP |
---
## Planning & Architecture
| Command | What it does |
|---------|-------------|
| `/plan` | Implementation plan with risk assessment |
| `/multi-plan` | Multi-model collaborative planning |
| `/multi-workflow` | Multi-model collaborative development |
| `/multi-backend` | Backend-focused multi-model development |
| `/multi-frontend` | Frontend-focused multi-model development |
| `/multi-execute` | Multi-model collaborative execution |
| `/orchestrate` | Guide for tmux/worktree multi-agent orchestration |
| `/devfleet` | Orchestrate parallel Claude Code agents via DevFleet |
---
## Session Management
| Command | What it does |
|---------|-------------|
| `/save-session` | Save current session state to `~/.claude/session-data/` |
| `/resume-session` | Load the most recent saved session from the canonical session store and resume from where you left off |
| `/sessions` | Browse, search, and manage session history with aliases from `~/.claude/session-data/` (with legacy reads from `~/.claude/sessions/`) |
| `/checkpoint` | Mark a checkpoint in the current session |
| `/aside` | Answer a quick side question without losing current task context |
| `/context-budget` | Analyse context window usage — find token overhead, optimise |
---
## Learning & Improvement
| Command | What it does |
|---------|-------------|
| `/learn` | Extract reusable patterns from the current session |
| `/learn-eval` | Extract patterns + self-evaluate quality before saving |
| `/evolve` | Analyse learned instincts, suggest evolved skill structures |
| `/promote` | Promote project-scoped instincts to global scope |
| `/instinct-status` | Show all learned instincts (project + global) with confidence scores |
| `/instinct-export` | Export instincts to a file |
| `/instinct-import` | Import instincts from a file or URL |
| `/skill-create` | Analyse local git history → generate a reusable skill |
| `/skill-health` | Skill portfolio health dashboard with analytics |
| `/rules-distill` | Scan skills, extract cross-cutting principles, distill into rules |
---
## Refactoring & Cleanup
| Command | What it does |
|---------|-------------|
| `/refactor-clean` | Remove dead code, consolidate duplicates, clean up structure |
| `/prompt-optimize` | Analyse a draft prompt and output an optimised ECC-enriched version |
---
## Docs & Research
| Command | What it does |
|---------|-------------|
| `/docs` | Look up current library/API documentation via Context7 |
| `/update-docs` | Update project documentation |
| `/update-codemaps` | Regenerate codemaps for the codebase |
---
## Loops & Automation
| Command | What it does |
|---------|-------------|
| `/loop-start` | Start a recurring agent loop on an interval |
| `/loop-status` | Check status of running loops |
| `/claw` | Start NanoClaw v2 — persistent REPL with model routing, skill hot-load, branching, and metrics |
---
## Project & Infrastructure
| Command | What it does |
|---------|-------------|
| `/projects` | List known projects and their instinct statistics |
| `/harness-audit` | Audit the agent harness configuration for reliability and cost |
| `/eval` | Run the evaluation harness |
| `/model-route` | Route a task to the right model (Haiku / Sonnet / Opus) |
| `/pm2` | PM2 process manager initialisation |
| `/setup-pm` | Configure package manager (npm / pnpm / yarn / bun) |
---
## Quick Decision Guide
```
Starting a new feature? → /plan first, then /tdd
Code just written? → /code-review
Build broken? → /build-fix
Need live docs? → /docs <library>
Session about to end? → /save-session or /learn-eval
Resuming next day? → /resume-session
Context getting heavy? → /context-budget then /checkpoint
Want to extract what you learned? → /learn-eval then /evolve
Running repeated tasks? → /loop-start
```

56
CONTRIBUTING.md
View File

@@ -73,13 +73,6 @@ git add . && git commit -m "feat: add my-skill" && git push -u origin feat/my-co
Skills are knowledge modules that Claude Code loads based on context.
> **📚 Comprehensive Guide:** For detailed guidance on creating effective skills, see [Skill Development Guide](docs/SKILL-DEVELOPMENT-GUIDE.md). It covers:
> - Skill architecture and categories
> - Writing effective content with examples
> - Best practices and common patterns
> - Testing and validation
> - Complete examples gallery
### Directory Structure
```
@@ -93,7 +86,7 @@ skills/
```markdown
---
name: your-skill-name
description: Brief description shown in skill list and used for auto-activation
description: Brief description shown in skill list
origin: ECC
---
@@ -101,10 +94,6 @@ origin: ECC
Brief overview of what this skill covers.
## When to Activate
Describe scenarios where Claude should use this skill. This is critical for auto-activation.
## Core Concepts
Explain key patterns and guidelines.
@@ -118,54 +107,33 @@ function example() {
}
\`\`\`
## Anti-Patterns
Show what NOT to do with examples.
## Best Practices
- Actionable guidelines
- Do's and don'ts
- Common pitfalls to avoid
## Related Skills
## When to Use
Link to complementary skills (e.g., `related-skill-1`, `related-skill-2`).
Describe scenarios where this skill applies.
```
### Skill Categories
| Category | Purpose | Examples |
|----------|---------|----------|
| **Language Standards** | Idioms, conventions, best practices | `python-patterns`, `golang-patterns` |
| **Framework Patterns** | Framework-specific guidance | `django-patterns`, `nextjs-patterns` |
| **Workflow** | Step-by-step processes | `tdd-workflow`, `refactoring-workflow` |
| **Domain Knowledge** | Specialized domains | `security-review`, `api-design` |
| **Tool Integration** | Tool/library usage | `docker-patterns`, `supabase-patterns` |
| **Template** | Project-specific skill templates | `project-guidelines-example` |
### Skill Checklist
- [ ] Focused on one domain/technology (not too broad)
- [ ] Includes "When to Activate" section for auto-activation
- [ ] Includes practical, copy-pasteable code examples
- [ ] Shows anti-patterns (what NOT to do)
- [ ] Under 500 lines (800 max)
- [ ] Focused on one domain/technology
- [ ] Includes practical code examples
- [ ] Under 500 lines
- [ ] Uses clear section headers
- [ ] Tested with Claude Code
- [ ] Links to related skills
- [ ] No sensitive data (API keys, tokens, paths)
### Example Skills
| Skill | Category | Purpose |
|-------|----------|---------|
| `coding-standards/` | Language Standards | TypeScript/JavaScript patterns |
| `frontend-patterns/` | Framework Patterns | React and Next.js best practices |
| `backend-patterns/` | Framework Patterns | API and database patterns |
| `security-review/` | Domain Knowledge | Security checklist |
| `tdd-workflow/` | Workflow | Test-driven development process |
| `project-guidelines-example/` | Template | Project-specific skill template |
| Skill | Purpose |
|-------|---------|
| `coding-standards/` | TypeScript/JavaScript patterns |
| `frontend-patterns/` | React and Next.js best practices |
| `backend-patterns/` | API and database patterns |
| `security-review/` | Security checklist |
---

122
EVALUATION.md
View File

@@ -1,122 +0,0 @@
# Repo Evaluation vs Current Setup
**Date:** 2026-03-21
**Branch:** `claude/evaluate-repo-comparison-ASZ9Y`
---
## Current Setup (`~/.claude/`)
The active Claude Code installation is near-minimal:
| Component | Current |
|-----------|---------|
| Agents | 0 |
| Skills | 0 installed |
| Commands | 0 |
| Hooks | 1 (Stop: git check) |
| Rules | 0 |
| MCP configs | 0 |
**Installed hooks:**
- `Stop` → `stop-hook-git-check.sh` — blocks session end if there are uncommitted changes or unpushed commits
**Installed permissions:**
- `Skill` — allows skill invocations
**Plugins:** Only `blocklist.json` (no active plugins installed)
---
## This Repo (`everything-claude-code` v1.9.0)
| Component | Repo |
|-----------|------|
| Agents | 28 |
| Skills | 116 |
| Commands | 59 |
| Rules sets | 12 languages + common (60+ rule files) |
| Hooks | Comprehensive system (PreToolUse, PostToolUse, SessionStart, Stop) |
| MCP configs | 1 (Context7 + others) |
| Schemas | 9 JSON validators |
| Scripts/CLI | 46+ Node.js modules + multiple CLIs |
| Tests | 58 test files |
| Install profiles | core, developer, security, research, full |
| Supported harnesses | Claude Code, Codex, Cursor, OpenCode |
---
## Gap Analysis
### Hooks
- **Current:** 1 Stop hook (git hygiene check)
- **Repo:** Full hook matrix covering:
- Dangerous command blocking (`rm -rf`, force pushes)
- Auto-formatting on file edits
- Dev server tmux enforcement
- Cost tracking
- Session evaluation and governance capture
- MCP health monitoring
### Agents (28 missing)
The repo provides specialized agents for every major workflow:
- Language reviewers: TypeScript, Python, Go, Java, Kotlin, Rust, C++, Flutter
- Build resolvers: Go, Java, Kotlin, Rust, C++, PyTorch
- Workflow agents: planner, tdd-guide, code-reviewer, security-reviewer, architect
- Automation: loop-operator, doc-updater, refactor-cleaner, harness-optimizer
### Skills (116 missing)
Domain knowledge modules covering:
- Language patterns (Python, Go, Kotlin, Rust, C++, Java, Swift, Perl, Laravel, Django)
- Testing strategies (TDD, E2E, coverage)
- Architecture patterns (backend, frontend, API design, database migrations)
- AI/ML workflows (Claude API, eval harness, agent loops, cost-aware pipelines)
- Business workflows (investor materials, market research, content engine)
### Commands (59 missing)
- `/tdd`, `/plan`, `/e2e`, `/code-review` — core dev workflows
- `/sessions`, `/save-session`, `/resume-session` — session persistence
- `/orchestrate`, `/multi-plan`, `/multi-execute` — multi-agent coordination
- `/learn`, `/skill-create`, `/evolve` — continuous improvement
- `/build-fix`, `/verify`, `/quality-gate` — build/quality automation
### Rules (60+ files missing)
Language-specific coding style, patterns, testing, and security guidelines for:
TypeScript, Python, Go, Java, Kotlin, Rust, C++, C#, Swift, Perl, PHP, and common/cross-language rules.
---
## Recommendations
### Immediate value (core install)
Run `ecc install --profile core` to get:
- Core agents (code-reviewer, planner, tdd-guide, security-reviewer)
- Essential skills (tdd-workflow, coding-standards, security-review)
- Key commands (/tdd, /plan, /code-review, /build-fix)
### Full install
Run `ecc install --profile full` to get all 28 agents, 116 skills, and 59 commands.
### Hooks upgrade
The current Stop hook is solid. The repo's `hooks.json` adds:
- Dangerous command blocking (safety)
- Auto-formatting (quality)
- Cost tracking (observability)
- Session evaluation (learning)
### Rules
Adding language rules (e.g., TypeScript, Python) provides always-on coding guidelines without relying on per-session prompts.
---
## What the Current Setup Does Well
- The `stop-hook-git-check.sh` Stop hook is production-quality and already enforces good git hygiene
- The `Skill` permission is correctly configured
- The setup is clean with no conflicts or cruft
---
## Summary
The current setup is essentially a blank slate with one well-implemented git hygiene hook. This repo provides a complete, production-tested enhancement layer covering agents, skills, commands, hooks, and rules — with a selective install system so you can add exactly what you need without bloating the configuration.

62
README.md
View File

@@ -180,11 +180,6 @@ cd everything-claude-code
npm install # or: pnpm install | yarn install | bun install
# macOS/Linux
# Recommended: install everything (full profile)
./install.sh --profile full
# Or install for specific languages only
./install.sh typescript # or python or golang or swift or php
# ./install.sh typescript python golang swift php
# ./install.sh --target cursor typescript
@@ -193,11 +188,6 @@ npm install # or: pnpm install | yarn install | bun install
```powershell
# Windows PowerShell
# Recommended: install everything (full profile)
.\install.ps1 --profile full
# Or install for specific languages only
.\install.ps1 typescript # or python or golang or swift or php
# .\install.ps1 typescript python golang swift php
# .\install.ps1 --target cursor typescript
@@ -207,7 +197,7 @@ npm install # or: pnpm install | yarn install | bun install
npx ecc-install typescript
```
For manual install instructions see the README in the `rules/` folder. When copying rules manually, copy the whole language directory (for example `rules/common` or `rules/golang`), not the files inside it, so relative references keep working and filenames do not collide.
For manual install instructions see the README in the `rules/` folder.
### Step 3: Start Using
@@ -222,21 +212,7 @@ For manual install instructions see the README in the `rules/` folder. When copy
/plugin list everything-claude-code@everything-claude-code
```
✨ **That's it!** You now have access to 28 agents, 126 skills, and 60 commands.
### Multi-model commands require additional setup
> ⚠️ `multi-*` commands are **not** covered by the base plugin/rules install above.
>
> To use `/multi-plan`, `/multi-execute`, `/multi-backend`, `/multi-frontend`, and `/multi-workflow`, you must also install the `ccg-workflow` runtime.
>
> Initialize it with `npx ccg-workflow`.
>
> That runtime provides the external dependencies these commands expect, including:
> - `~/.claude/bin/codeagent-wrapper`
> - `~/.claude/.ccg/prompts/*`
>
> Without `ccg-workflow`, these `multi-*` commands will not run correctly.
✨ **That's it!** You now have access to 28 agents, 125 skills, and 60 commands.
---
@@ -638,16 +614,16 @@ This gives you instant access to all commands, agents, skills, and hooks.
>
> # Option A: User-level rules (applies to all projects)
> mkdir -p ~/.claude/rules
> 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/
> 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/
>
> # Option B: Project-level rules (applies to current project only)
> mkdir -p .claude/rules
> 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/common/* .claude/rules/
> cp -r everything-claude-code/rules/typescript/* .claude/rules/ # pick your stack
> ```
---
@@ -663,13 +639,12 @@ git clone https://github.com/affaan-m/everything-claude-code.git
# Copy agents to your Claude config
cp everything-claude-code/agents/*.md ~/.claude/agents/
# Copy rules directories (common + language-specific)
mkdir -p ~/.claude/rules
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 rules (common + language-specific)
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/
@@ -875,8 +850,7 @@ Yes. Use Option 2 (manual installation) and copy only what you need:
cp everything-claude-code/agents/*.md ~/.claude/agents/
# Just rules
mkdir -p ~/.claude/rules/
cp -r everything-claude-code/rules/common ~/.claude/rules/
cp -r everything-claude-code/rules/common/* ~/.claude/rules/
```
Each component is fully independent.
@@ -1025,8 +999,6 @@ cp .codex/config.toml ~/.codex/config.toml
The sync script safely merges ECC MCP servers into your existing `~/.codex/config.toml` using an **add-only** strategy — it never removes or modifies your existing servers. Run with `--dry-run` to preview changes, or `--update-mcp` to force-refresh ECC servers to the latest recommended config.
For Context7, ECC uses the canonical Codex section name `[mcp_servers.context7]` while still launching the `@upstash/context7-mcp` package. If you already have a legacy `[mcp_servers.context7-mcp]` entry, `--update-mcp` migrates it to the canonical section name.
Codex macOS app:
- Open this repository as your workspace.
- The root `AGENTS.md` is auto-detected.
@@ -1113,7 +1085,7 @@ The configuration is automatically detected from `.opencode/opencode.json`.
|---------|-------------|----------|--------|
| Agents | ✅ 28 agents | ✅ 12 agents | **Claude Code leads** |
| Commands | ✅ 60 commands | ✅ 31 commands | **Claude Code leads** |
| Skills | ✅ 126 skills | ✅ 37 skills | **Claude Code leads** |
| Skills | ✅ 125 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** |

55
README.zh-CN.md
View File

@@ -82,17 +82,14 @@
# 首先克隆仓库
git clone https://github.com/affaan-m/everything-claude-code.git
# 复制规则目录（通用 + 语言特定）
mkdir -p ~/.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 -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/
```
复制规则时，请复制整个目录（例如 `rules/common`、`rules/golang`），而不是复制目录内的文件；这样可以保留相对引用，并避免不同规则集中的同名文件互相覆盖。
### 第三步：开始使用
```bash
@@ -108,20 +105,6 @@ cp -r everything-claude-code/rules/perl ~/.claude/rules/
✨ **完成！** 你现在可以使用 13 个代理、43 个技能和 31 个命令。
### multi-* 命令需要额外配置
> ⚠️ 上面的基础插件 / rules 安装**不包含** `multi-*` 命令所需的运行时。
>
> 如果要使用 `/multi-plan`、`/multi-execute`、`/multi-backend`、`/multi-frontend` 和 `/multi-workflow`，还需要额外安装 `ccg-workflow` 运行时。
>
> 可通过 `npx ccg-workflow` 完成初始化安装。
>
> 该运行时会提供这些命令依赖的关键组件，包括：
> - `~/.claude/bin/codeagent-wrapper`
> - `~/.claude/.ccg/prompts/*`
>
> 未安装 `ccg-workflow` 时，这些 `multi-*` 命令将无法正常运行。
---
## 🌐 跨平台支持
@@ -369,20 +352,11 @@ everything-claude-code/
> git clone https://github.com/affaan-m/everything-claude-code.git
>
> # 选项 A：用户级规则（应用于所有项目）
> mkdir -p ~/.claude/rules
> cp -r everything-claude-code/rules/common ~/.claude/rules/
> cp -r everything-claude-code/rules/typescript ~/.claude/rules/
> 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 -r everything-claude-code/rules/* ~/.claude/rules/
>
> # 选项 B：项目级规则（仅应用于当前项目）
> mkdir -p .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 -r everything-claude-code/rules/* .claude/rules/
> ```
---
@@ -398,13 +372,12 @@ git clone https://github.com/affaan-m/everything-claude-code.git
# 将代理复制到你的 Claude 配置
cp everything-claude-code/agents/*.md ~/.claude/agents/
# 复制规则目录（通用 + 语言特定）
mkdir -p ~/.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 -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/

196
REPO-ASSESSMENT.md
View File

@@ -1,196 +0,0 @@
# Repo & Fork Assessment + Setup Recommendations
**Date:** 2026-03-21
---
## What's Available
### Repo: `Infiniteyieldai/everything-claude-code`
This is a **fork of `affaan-m/everything-claude-code`** (the upstream project with 50K+ stars, 6K+ forks).
| Attribute | Value |
|-----------|-------|
| Version | 1.9.0 (current) |
| Status | Clean fork — 1 commit ahead of upstream `main` (the EVALUATION.md doc added in this session) |
| Remote branches | `main`, `claude/evaluate-repo-comparison-ASZ9Y` |
| Upstream sync | Fully synced — last upstream commit merged was the zh-CN docs PR (#728) |
| License | MIT |
**This is the right repo to work from.** It's the latest upstream version with no divergence or merge conflicts.
---
### Current `~/.claude/` Installation
| Component | Installed | Available in Repo |
|-----------|-----------|-------------------|
| Agents | 0 | 28 |
| Skills | 0 | 116 |
| Commands | 0 | 59 |
| Rules | 0 | 60+ files (12 languages) |
| Hooks | 1 (git Stop check) | Full PreToolUse/PostToolUse matrix |
| MCP configs | 0 | 1 (Context7) |
The existing Stop hook (`stop-hook-git-check.sh`) is solid — blocks session end on uncommitted/unpushed work. Keep it.
---
## Install Profile Recommendations
The repo ships 5 install profiles. Choose based on your primary use case:
### Profile: `core` (Minimum viable setup)
> Fastest to install. Gets you commands, core agents, hooks runtime, and quality workflow.
**Best for:** Trying ECC out, minimal footprint, or a constrained environment.
```bash
node scripts/install-plan.js --profile core
node scripts/install-apply.js
```
**Installs:** rules-core, agents-core, commands-core, hooks-runtime, platform-configs, workflow-quality
---
### Profile: `developer` (Recommended for daily dev work)
> The default engineering profile for most ECC users.
**Best for:** General software development across app codebases.
```bash
node scripts/install-plan.js --profile developer
node scripts/install-apply.js
```
**Adds over core:** framework-language skills, database patterns, orchestration commands
---
### Profile: `security`
> Baseline runtime + security-specific agents and rules.
**Best for:** Security-focused workflows, code audits, vulnerability reviews.
---
### Profile: `research`
> Investigation, synthesis, and publishing workflows.
**Best for:** Content creation, investor materials, market research, cross-posting.
---
### Profile: `full`
> Everything — all 18 modules.
**Best for:** Power users who want the complete toolkit.
```bash
node scripts/install-plan.js --profile full
node scripts/install-apply.js
```
---
## Priority Additions (High Value, Low Risk)
Regardless of profile, these components add immediate value:
### 1. Core Agents (highest ROI)
| Agent | Why it matters |
|-------|----------------|
| `planner.md` | Breaks complex tasks into implementation plans |
| `code-reviewer.md` | Quality and maintainability review |
| `tdd-guide.md` | TDD workflow (RED→GREEN→IMPROVE) |
| `security-reviewer.md` | Vulnerability detection |
| `architect.md` | System design & scalability decisions |
### 2. Key Commands
| Command | Why it matters |
|---------|----------------|
| `/plan` | Implementation planning before coding |
| `/tdd` | Test-driven workflow |
| `/code-review` | On-demand review |
| `/build-fix` | Automated build error resolution |
| `/learn` | Extract patterns from current session |
### 3. Hook Upgrades (from `hooks/hooks.json`)
The repo's hook system adds these over the current single Stop hook:
| Hook | Trigger | Value |
|------|---------|-------|
| `block-no-verify` | PreToolUse: Bash | Blocks `--no-verify` git flag abuse |
| `pre-bash-git-push-reminder` | PreToolUse: Bash | Pre-push review reminder |
| `doc-file-warning` | PreToolUse: Write | Warns on non-standard doc files |
| `suggest-compact` | PreToolUse: Edit/Write | Suggests compaction at logical intervals |
| Continuous learning observer | PreToolUse: * | Captures tool use patterns for skill improvement |
### 4. Rules (Always-on guidelines)
The `rules/common/` directory provides baseline guidelines that fire on every session:
- `security.md` — Security guardrails
- `testing.md` — 80%+ coverage requirement
- `git-workflow.md` — Conventional commits, branch strategy
- `coding-style.md` — Cross-language style standards
---
## What to Do With the Fork
### Option A: Use as upstream tracker (current state)
Keep the fork synced with `affaan-m/everything-claude-code` upstream. Periodically merge upstream changes:
```bash
git fetch upstream
git merge upstream/main
```
Install from the local clone. This is clean and maintainable.
### Option B: Customize the fork
Add personal skills, agents, or commands to the fork. Good for:
- Business-specific domain skills (your vertical)
- Team-specific coding conventions
- Custom hooks for your stack
The fork already has the EVALUATION.md and REPO-ASSESSMENT.md docs — that's fine for a working fork.
### Option C: Install from npm (simplest for fresh machines)
```bash
npx ecc-universal install --profile developer
```
No need to clone the repo. This is the recommended install method for most users.
---
## Recommended Setup Steps
1. **Keep the existing Stop hook** — it's doing its job
2. **Run the developer profile install** from the local fork:
```bash
cd /path/to/everything-claude-code
node scripts/install-plan.js --profile developer
node scripts/install-apply.js
```
3. **Add language rules** for your primary stack (TypeScript, Python, Go, etc.):
```bash
node scripts/install-plan.js --add rules/typescript
node scripts/install-apply.js
```
4. **Enable MCP Context7** for live documentation lookup:
- Copy `mcp-configs/mcp-servers.json` into your project's `.claude/` dir
5. **Review hooks** — enable the `hooks/hooks.json` additions selectively, starting with `block-no-verify` and `pre-bash-git-push-reminder`
---
## Summary
| Question | Answer |
|----------|--------|
| Is the fork healthy? | Yes — fully synced with upstream v1.9.0 |
| Other forks to consider? | None visible in this environment; upstream `affaan-m/everything-claude-code` is the source of truth |
| Best install profile? | `developer` for day-to-day dev work |
| Biggest gap in current setup? | 0 agents installed — add at minimum: planner, code-reviewer, tdd-guide, security-reviewer |
| Quickest win? | Run `node scripts/install-plan.js --profile core && node scripts/install-apply.js` |

19
commands/resume-session.md
View File

@@ -1,5 +1,5 @@
---
description: Load the most recent session file from ~/.claude/session-data/ and resume work with full context from where the last session ended.
description: Load the most recent session file from ~/.claude/sessions/ and resume work with full context from where the last session ended.
---
# Resume Session Command
@@ -17,10 +17,10 @@ This command is the counterpart to `/save-session`.
## Usage
```
/resume-session # loads most recent file in ~/.claude/session-data/
/resume-session # loads most recent file in ~/.claude/sessions/
/resume-session 2024-01-15 # loads most recent session for that date
/resume-session ~/.claude/session-data/2024-01-15-abc123de-session.tmp # loads a current short-id session file
/resume-session ~/.claude/sessions/2024-01-15-session.tmp # loads a specific legacy-format file
/resume-session ~/.claude/sessions/2024-01-15-session.tmp # loads a specific legacy-format file
/resume-session ~/.claude/sessions/2024-01-15-abc123de-session.tmp # loads a current short-id session file
```
## Process
@@ -29,20 +29,19 @@ This command is the counterpart to `/save-session`.
If no argument provided:
1. Check `~/.claude/session-data/`
1. Check `~/.claude/sessions/`
2. Pick the most recently modified `*-session.tmp` file
3. If the folder does not exist or has no matching files, tell the user:
```
No session files found in ~/.claude/session-data/
No session files found in ~/.claude/sessions/
Run /save-session at the end of a session to create one.
```
Then stop.
If an argument is provided:
- If it looks like a date (`YYYY-MM-DD`), search `~/.claude/session-data/` first, then the legacy
`~/.claude/sessions/`, for files matching `YYYY-MM-DD-session.tmp` (legacy format) or
`YYYY-MM-DD-<shortid>-session.tmp` (current format)
- If it looks like a date (`YYYY-MM-DD`), search `~/.claude/sessions/` for files matching
`YYYY-MM-DD-session.tmp` (legacy format) or `YYYY-MM-DD-<shortid>-session.tmp` (current format)
and load the most recently modified variant for that date
- If it looks like a file path, read that file directly
- If not found, report clearly and stop
@@ -115,7 +114,7 @@ Report: "Session file found but appears empty or unreadable. You may need to cre
## Example Output
```
SESSION LOADED: /Users/you/.claude/session-data/2024-01-15-abc123de-session.tmp
SESSION LOADED: /Users/you/.claude/sessions/2024-01-15-abc123de-session.tmp
════════════════════════════════════════════════
PROJECT: my-app — JWT Authentication

18
commands/save-session.md
View File

@@ -1,5 +1,5 @@
---
description: Save current session state to a dated file in ~/.claude/session-data/ so work can be resumed in a future session with full context.
description: Save current session state to a dated file in ~/.claude/sessions/ so work can be resumed in a future session with full context.
---
# Save Session Command
@@ -29,19 +29,19 @@ Before writing the file, collect:
Create the canonical sessions folder in the user's Claude home directory:
```bash
mkdir -p ~/.claude/session-data
mkdir -p ~/.claude/sessions
```
### Step 3: Write the session file
Create `~/.claude/session-data/YYYY-MM-DD-<short-id>-session.tmp`, using today's actual date and a short-id that satisfies the rules enforced by `SESSION_FILENAME_REGEX` in `session-manager.js`:
Create `~/.claude/sessions/YYYY-MM-DD-<short-id>-session.tmp`, using today's actual date and a short-id that satisfies the rules enforced by `SESSION_FILENAME_REGEX` in `session-manager.js`:
- Compatibility characters: letters `a-z` / `A-Z`, digits `0-9`, hyphens `-`, underscores `_`
- Compatibility minimum length: 1 character
- Recommended style for new files: lowercase letters, digits, and hyphens with 8+ characters to avoid collisions
- Allowed characters: lowercase `a-z`, digits `0-9`, hyphens `-`
- Minimum length: 8 characters
- No uppercase letters, no underscores, no spaces
Valid examples: `abc123de`, `a1b2c3d4`, `frontend-worktree-1`, `ChezMoi_2`
Avoid for new files: `A`, `test_id1`, `ABC123de`
Valid examples: `abc123de`, `a1b2c3d4`, `frontend-worktree-1`
Invalid examples: `ABC123de` (uppercase), `short` (under 8 chars), `test_id1` (underscore)
Full valid filename example: `2024-01-15-abc123de-session.tmp`
@@ -271,5 +271,5 @@ Then test with Postman — the response should include a `Set-Cookie` header.
- The "What Did NOT Work" section is the most critical — future sessions will blindly retry failed approaches without it
- If the user asks to save mid-session (not just at the end), save what's known so far and mark in-progress items clearly
- The file is meant to be read by Claude at the start of the next session via `/resume-session`
- Use the canonical global session store: `~/.claude/session-data/`
- Use the canonical global session store: `~/.claude/sessions/`
- Prefer the short-id filename form (`YYYY-MM-DD-<short-id>-session.tmp`) for any new session file

6
commands/sessions.md
View File

@@ -4,7 +4,7 @@ description: Manage Claude Code session history, aliases, and session metadata.
# Sessions Command
Manage Claude Code session history - list, load, alias, and edit sessions stored in `~/.claude/session-data/` with legacy reads from `~/.claude/sessions/`.
Manage Claude Code session history - list, load, alias, and edit sessions stored in `~/.claude/sessions/`.
## Usage
@@ -89,7 +89,7 @@ const size = sm.getSessionSize(session.sessionPath);
const aliases = aa.getAliasesForSession(session.filename);
console.log('Session: ' + session.filename);
console.log('Path: ' + session.sessionPath);
console.log('Path: ~/.claude/sessions/' + session.filename);
console.log('');
console.log('Statistics:');
console.log(' Lines: ' + stats.lineCount);
@@ -327,7 +327,7 @@ $ARGUMENTS:
## Notes
- Sessions are stored as markdown files in `~/.claude/session-data/` with legacy reads from `~/.claude/sessions/`
- Sessions are stored as markdown files in `~/.claude/sessions/`
- Aliases are stored in `~/.claude/session-aliases.json`
- Session IDs can be shortened (first 4-8 characters usually unique enough)
- Use aliases for frequently referenced sessions

919
docs/SKILL-DEVELOPMENT-GUIDE.md
View File

@@ -1,919 +0,0 @@
# Skill Development Guide
A comprehensive guide to creating effective skills for Everything Claude Code (ECC).
## Table of Contents
- [What Are Skills?](#what-are-skills)
- [Skill Architecture](#skill-architecture)
- [Creating Your First Skill](#creating-your-first-skill)
- [Skill Categories](#skill-categories)
- [Writing Effective Skill Content](#writing-effective-skill-content)
- [Best Practices](#best-practices)
- [Common Patterns](#common-patterns)
- [Testing Your Skill](#testing-your-skill)
- [Submitting Your Skill](#submitting-your-skill)
- [Examples Gallery](#examples-gallery)
---
## What Are Skills?
Skills are **knowledge modules** that Claude Code loads based on context. They provide:
- **Domain expertise**: Framework patterns, language idioms, best practices
- **Workflow definitions**: Step-by-step processes for common tasks
- **Reference material**: Code snippets, checklists, decision trees
- **Context injection**: Activate when specific conditions are met
Unlike **agents** (specialized subassistants) or **commands** (user-triggered actions), skills are passive knowledge that Claude Code references when relevant.
### When Skills Activate
Skills activate when:
- The user's task matches the skill's domain
- Claude Code detects relevant context
- A command references a skill
- An agent needs domain knowledge
### Skill vs Agent vs Command
| Component | Purpose | Activation |
|-----------|---------|------------|
| **Skill** | Knowledge repository | Context-based (automatic) |
| **Agent** | Task executor | Explicit delegation |
| **Command** | User action | User-invoked (`/command`) |
| **Hook** | Automation | Event-triggered |
| **Rule** | Always-on guidelines | Always active |
---
## Skill Architecture
### File Structure
```
skills/
└── your-skill-name/
├── SKILL.md # Required: Main skill definition
├── examples/ # Optional: Code examples
│ ├── basic.ts
│ └── advanced.ts
└── references/ # Optional: External references
└── links.md
```
### SKILL.md Format
```markdown
---
name: skill-name
description: Brief description shown in skill list and used for auto-activation
origin: ECC
---
# Skill Title
Brief overview of what this skill covers.
## When to Activate
Describe scenarios where Claude should use this skill.
## Core Concepts
Main patterns and guidelines.
## Code Examples
\`\`\`typescript
// Practical, tested examples
\`\`\`
## Anti-Patterns
Show what NOT to do with concrete examples.
## Best Practices
- Actionable guidelines
- Do's and don'ts
## Related Skills
Link to complementary skills.
```
### YAML Frontmatter Fields
| Field | Required | Description |
|-------|----------|-------------|
| `name` | Yes | Lowercase, hyphenated identifier (e.g., `react-patterns`) |
| `description` | Yes | One-line description for skill list and auto-activation |
| `origin` | No | Source identifier (e.g., `ECC`, `community`, project name) |
| `tags` | No | Array of tags for categorization |
| `version` | No | Skill version for tracking updates |
---
## Creating Your First Skill
### Step 1: Choose a Focus
Good skills are **focused and actionable**:
| ✅ Good Focus | ❌ Too Broad |
|---------------|--------------|
| `react-hook-patterns` | `react` |
| `postgresql-indexing` | `databases` |
| `pytest-fixtures` | `python-testing` |
| `nextjs-app-router` | `nextjs` |
### Step 2: Create the Directory
```bash
mkdir -p skills/your-skill-name
```
### Step 3: Write SKILL.md
Here's a minimal template:
```markdown
---
name: your-skill-name
description: Brief description of when to use this skill
---
# Your Skill Title
Brief overview (1-2 sentences).
## When to Activate
- Scenario 1
- Scenario 2
- Scenario 3
## Core Concepts
### Concept 1
Explanation with examples.
### Concept 2
Another pattern with code.
## Code Examples
\`\`\`typescript
// Practical example
\`\`\`
## Best Practices
- Do this
- Avoid that
## Related Skills
- `related-skill-1`
- `related-skill-2`
```
### Step 4: Add Content
Write content that Claude can **immediately use**:
- ✅ Copy-pasteable code examples
- ✅ Clear decision trees
- ✅ Checklists for verification
- ❌ Vague explanations without examples
- ❌ Long prose without actionable guidance
---
## Skill Categories
### Language Standards
Focus on idiomatic code, naming conventions, and language-specific patterns.
**Examples:** `python-patterns`, `golang-patterns`, `typescript-standards`
```markdown
---
name: python-patterns
description: Python idioms, best practices, and patterns for clean, idiomatic code.
---
# Python Patterns
## When to Activate
- Writing Python code
- Refactoring Python modules
- Python code review
## Core Concepts
### Context Managers
\`\`\`python
# Always use context managers for resources
with open('file.txt') as f:
content = f.read()
\`\`\`
```
### Framework Patterns
Focus on framework-specific conventions, common patterns, and anti-patterns.
**Examples:** `django-patterns`, `nextjs-patterns`, `springboot-patterns`
```markdown
---
name: django-patterns
description: Django best practices for models, views, URLs, and templates.
---
# Django Patterns
## When to Activate
- Building Django applications
- Creating models and views
- Django URL configuration
```
### Workflow Skills
Define step-by-step processes for common development tasks.
**Examples:** `tdd-workflow`, `code-review-workflow`, `deployment-checklist`
```markdown
---
name: code-review-workflow
description: Systematic code review process for quality and security.
---
# Code Review Workflow
## Steps
1. **Understand Context** - Read PR description and linked issues
2. **Check Tests** - Verify test coverage and quality
3. **Review Logic** - Analyze implementation for correctness
4. **Check Security** - Look for vulnerabilities
5. **Verify Style** - Ensure code follows conventions
```
### Domain Knowledge
Specialized knowledge for specific domains (security, performance, etc.).
**Examples:** `security-review`, `performance-optimization`, `api-design`
```markdown
---
name: api-design
description: REST and GraphQL API design patterns, versioning, and best practices.
---
# API Design Patterns
## RESTful Conventions
| Method | Endpoint | Purpose |
|--------|----------|---------|
| GET | /resources | List all |
| GET | /resources/:id | Get one |
| POST | /resources | Create |
```
### Tool Integration
Guidance for using specific tools, libraries, or services.
**Examples:** `supabase-patterns`, `docker-patterns`, `mcp-server-patterns`
---
## Writing Effective Skill Content
### 1. Start with "When to Activate"
This section is **critical** for auto-activation. Be specific:
```markdown
## When to Activate
- Creating new React components
- Refactoring existing components
- Debugging React state issues
- Reviewing React code for best practices
```
### 2. Use "Show, Don't Tell"
Bad:
```markdown
## Error Handling
Always handle errors properly in async functions.
```
Good:
```markdown
## Error Handling
\`\`\`typescript
async function fetchData(url: string) {
try {
const response = await fetch(url)
if (!response.ok) {
throw new Error(\`HTTP \${response.status}: \${response.statusText}\`)
}
return await response.json()
} catch (error) {
console.error('Fetch failed:', error)
throw new Error('Failed to fetch data')
}
}
\`\`\`
### Key Points
- Check \`response.ok\` before parsing
- Log errors for debugging
- Re-throw with user-friendly message
```
### 3. Include Anti-Patterns
Show what NOT to do:
```markdown
## Anti-Patterns
### ❌ Direct State Mutation
\`\`\`typescript
// NEVER do this
user.name = 'New Name'
items.push(newItem)
\`\`\`
### ✅ Immutable Updates
\`\`\`typescript
// ALWAYS do this
const updatedUser = { ...user, name: 'New Name' }
const updatedItems = [...items, newItem]
\`\`\`
```
### 4. Provide Checklists
Checklists are actionable and easy to follow:
```markdown
## Pre-Deployment Checklist
- [ ] All tests passing
- [ ] No console.log in production code
- [ ] Environment variables documented
- [ ] Secrets not hardcoded
- [ ] Error handling complete
- [ ] Input validation in place
```
### 5. Use Decision Trees
For complex decisions:
```markdown
## Choosing the Right Approach
\`\`\`
Need to fetch data?
├── Single request → use fetch directly
├── Multiple independent → Promise.all()
├── Multiple dependent → await sequentially
└── With caching → use SWR or React Query
\`\`\`
```
---
## Best Practices
### DO
| Practice | Example |
|----------|---------|
| **Be specific** | "Use \`useCallback\` for event handlers passed to child components" |
| **Show examples** | Include copy-pasteable code |
| **Explain WHY** | "Immutability prevents unexpected side effects in React state" |
| **Link related skills** | "See also: \`react-performance\`" |
| **Keep focused** | One skill = one domain/concept |
| **Use sections** | Clear headers for easy scanning |
### DON'T
| Practice | Why It's Bad |
|----------|--------------|
| **Be vague** | "Write good code" - not actionable |
| **Long prose** | Hard to parse, better as code |
| **Cover too much** | "Python, Django, and Flask patterns" - too broad |
| **Skip examples** | Theory without practice is less useful |
| **Ignore anti-patterns** | Learning what NOT to do is valuable |
### Content Guidelines
1. **Length**: 200-500 lines typical, 800 lines maximum
2. **Code blocks**: Include language identifier
3. **Headers**: Use `##` and `###` hierarchy
4. **Lists**: Use `-` for unordered, `1.` for ordered
5. **Tables**: For comparisons and references
---
## Common Patterns
### Pattern 1: Standards Skill
```markdown
---
name: language-standards
description: Coding standards and best practices for [language].
---
# [Language] Coding Standards
## When to Activate
- Writing [language] code
- Code review
- Setting up linting
## Naming Conventions
| Element | Convention | Example |
|---------|------------|---------|
| Variables | camelCase | userName |
| Constants | SCREAMING_SNAKE | MAX_RETRY |
| Functions | camelCase | fetchUser |
| Classes | PascalCase | UserService |
## Code Examples
[Include practical examples]
## Linting Setup
[Include configuration]
## Related Skills
- `language-testing`
- `language-security`
```
### Pattern 2: Workflow Skill
```markdown
---
name: task-workflow
description: Step-by-step workflow for [task].
---
# [Task] Workflow
## When to Activate
- [Trigger 1]
- [Trigger 2]
## Prerequisites
- [Requirement 1]
- [Requirement 2]
## Steps
### Step 1: [Name]
[Description]
\`\`\`bash
[Commands]
\`\`\`
### Step 2: [Name]
[Description]
## Verification
- [ ] [Check 1]
- [ ] [Check 2]
## Troubleshooting
| Problem | Solution |
|---------|----------|
| [Issue] | [Fix] |
```
### Pattern 3: Reference Skill
```markdown
---
name: api-reference
description: Quick reference for [API/Library].
---
# [API/Library] Reference
## When to Activate
- Using [API/Library]
- Looking up [API/Library] syntax
## Common Operations
### Operation 1
\`\`\`typescript
// Basic usage
\`\`\`
### Operation 2
\`\`\`typescript
// Advanced usage
\`\`\`
## Configuration
[Include config examples]
## Error Handling
[Include error patterns]
```
---
## Testing Your Skill
### Local Testing
1. **Copy to Claude Code skills directory**:
```bash
cp -r skills/your-skill-name ~/.claude/skills/
```
2. **Test with Claude Code**:
```
You: "I need to [task that should trigger your skill]"
Claude should reference your skill's patterns.
```
3. **Verify activation**:
- Ask Claude to explain a concept from your skill
- Check if it uses your examples and patterns
- Ensure it follows your guidelines
### Validation Checklist
- [ ] **YAML frontmatter valid** - No syntax errors
- [ ] **Name follows convention** - lowercase-with-hyphens
- [ ] **Description is clear** - Tells when to use
- [ ] **Examples work** - Code compiles and runs
- [ ] **Links valid** - Related skills exist
- [ ] **No sensitive data** - No API keys, tokens, paths
### Code Example Testing
Test all code examples:
```bash
# From the repo root
npx tsc --noEmit skills/your-skill-name/examples/*.ts
# Or from inside the skill directory
npx tsc --noEmit examples/*.ts
# From the repo root
python -m py_compile skills/your-skill-name/examples/*.py
# Or from inside the skill directory
python -m py_compile examples/*.py
# From the repo root
go build ./skills/your-skill-name/examples/...
# Or from inside the skill directory
go build ./examples/...
```
---
## Submitting Your Skill
### 1. Fork and Clone
```bash
gh repo fork affaan-m/everything-claude-code --clone
cd everything-claude-code
```
### 2. Create Branch
```bash
git checkout -b feat/skill-your-skill-name
```
### 3. Add Your Skill
```bash
mkdir -p skills/your-skill-name
# Create SKILL.md
```
### 4. Validate
```bash
# Check YAML frontmatter
head -10 skills/your-skill-name/SKILL.md
# Verify structure
ls -la skills/your-skill-name/
# Run tests if available
npm test
```
### 5. Commit and Push
```bash
git add skills/your-skill-name/
git commit -m "feat(skills): add your-skill-name skill"
git push -u origin feat/skill-your-skill-name
```
### 6. Create Pull Request
Use this PR template:
```markdown
## Summary
Brief description of the skill and why it's valuable.
## Skill Type
- [ ] Language standards
- [ ] Framework patterns
- [ ] Workflow
- [ ] Domain knowledge
- [ ] Tool integration
## Testing
How I tested this skill locally.
## Checklist
- [ ] YAML frontmatter valid
- [ ] Code examples tested
- [ ] Follows skill guidelines
- [ ] No sensitive data
- [ ] Clear activation triggers
```
---
## Examples Gallery
### Example 1: Language Standards
**File:** `skills/rust-patterns/SKILL.md`
```markdown
---
name: rust-patterns
description: Rust idioms, ownership patterns, and best practices for safe, idiomatic code.
origin: ECC
---
# Rust Patterns
## When to Activate
- Writing Rust code
- Handling ownership and borrowing
- Error handling with Result/Option
- Implementing traits
## Ownership Patterns
### Borrowing Rules
\`\`\`rust
// ✅ CORRECT: Borrow when you don't need ownership
fn process_data(data: &str) -> usize {
data.len()
}
// ✅ CORRECT: Take ownership when you need to modify or consume
fn consume_data(data: Vec<u8>) -> String {
String::from_utf8(data).unwrap()
}
\`\`\`
## Error Handling
### Result Pattern
\`\`\`rust
use thiserror::Error;
#[derive(Error, Debug)]
pub enum AppError {
#[error("IO error: {0}")]
Io(#[from] std::io::Error),
#[error("Parse error: {0}")]
Parse(#[from] std::num::ParseIntError),
}
pub type AppResult<T> = Result<T, AppError>;
\`\`\`
## Related Skills
- `rust-testing`
- `rust-security`
```
### Example 2: Framework Patterns
**File:** `skills/fastapi-patterns/SKILL.md`
```markdown
---
name: fastapi-patterns
description: FastAPI patterns for routing, dependency injection, validation, and async operations.
origin: ECC
---
# FastAPI Patterns
## When to Activate
- Building FastAPI applications
- Creating API endpoints
- Implementing dependency injection
- Handling async database operations
## Project Structure
\`\`\`
app/
├── main.py # FastAPI app entry point
├── routers/ # Route handlers
│ ├── users.py
│ └── items.py
├── models/ # Pydantic models
│ ├── user.py
│ └── item.py
├── services/ # Business logic
│ └── user_service.py
└── dependencies.py # Shared dependencies
\`\`\`
## Dependency Injection
\`\`\`python
from fastapi import Depends
from sqlalchemy.ext.asyncio import AsyncSession
async def get_db() -> AsyncSession:
async with AsyncSessionLocal() as session:
yield session
@router.get("/users/{user_id}")
async def get_user(
user_id: int,
db: AsyncSession = Depends(get_db)
):
# Use db session
pass
\`\`\`
## Related Skills
- `python-patterns`
- `pydantic-validation`
```
### Example 3: Workflow Skill
**File:** `skills/refactoring-workflow/SKILL.md`
```markdown
---
name: refactoring-workflow
description: Systematic refactoring workflow for improving code quality without changing behavior.
origin: ECC
---
# Refactoring Workflow
## When to Activate
- Improving code structure
- Reducing technical debt
- Simplifying complex code
- Extracting reusable components
## Prerequisites
- All tests passing
- Git working directory clean
- Feature branch created
## Workflow Steps
### Step 1: Identify Refactoring Target
- Look for code smells (long methods, duplicate code, large classes)
- Check test coverage for target area
- Document current behavior
### Step 2: Ensure Tests Exist
\`\`\`bash
# Run tests to verify current behavior
npm test
# Check coverage for target files
npm run test:coverage
\`\`\`
### Step 3: Make Small Changes
- One refactoring at a time
- Run tests after each change
- Commit frequently
### Step 4: Verify Behavior Unchanged
\`\`\`bash
# Run full test suite
npm test
# Run E2E tests
npm run test:e2e
\`\`\`
## Common Refactorings
| Smell | Refactoring |
|-------|-------------|
| Long method | Extract method |
| Duplicate code | Extract to shared function |
| Large class | Extract class |
| Long parameter list | Introduce parameter object |
## Checklist
- [ ] Tests exist for target code
- [ ] Made small, focused changes
- [ ] Tests pass after each change
- [ ] Behavior unchanged
- [ ] Committed with clear message
```
---
## Additional Resources
- [CONTRIBUTING.md](../CONTRIBUTING.md) - General contribution guidelines
- [project-guidelines-example](../skills/project-guidelines-example/SKILL.md) - Project-specific skill template
- [coding-standards](../skills/coding-standards/SKILL.md) - Example of standards skill
- [tdd-workflow](../skills/tdd-workflow/SKILL.md) - Example of workflow skill
- [security-review](../skills/security-review/SKILL.md) - Example of domain knowledge skill
---
**Remember**: A good skill is focused, actionable, and immediately useful. Write skills you'd want to use yourself.

2
docs/ja-JP/README.md
View File

@@ -409,7 +409,7 @@ claude --version
Claude Code v2.1+は、インストール済みプラグインの`hooks/hooks.json`（規約）を自動読み込みします。`plugin.json`で明示的に宣言するとエラーが発生します：
```
Duplicate hook file detected: ./hooks/hooks.json is already resolved to a loaded file
Duplicate hooks file detected: ./hooks/hooks.json resolves to already-loaded file
```
**背景:** これは本リポジトリで複数の修正/リバート循環を引き起こしました（[#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)）。Claude Codeバージョン間で動作が変わったため混乱がありました。今後を防ぐため回帰テストがあります。

6
docs/ja-JP/agents/code-reviewer.md
View File

@@ -77,9 +77,9 @@ model: opus
各問題について:
```
[CRITICAL] ハードコードされたAPIキー
ファイル: src/api/client.ts:42
問題: APIキーがソースコードに公開されている
修正: 環境変数に移動
File: src/api/client.ts:42
Issue: APIキーがソースコードに公開されている
Fix: 環境変数に移動
const apiKey = "sk-abc123"; // ❌ Bad
const apiKey = process.env.API_KEY; // ✓ Good

18
docs/ja-JP/agents/go-build-resolver.md
View File

@@ -341,20 +341,20 @@ x = x // 無意味な代入を削除
各修正試行後:
```text
[修正済] internal/handler/user.go:42
エラー: undefined: UserService
修正: import を追加 "project/internal/service"
[FIXED] internal/handler/user.go:42
Error: undefined: UserService
Fix: Added import "project/internal/service"
残りのエラー: 3
Remaining errors: 3
```
最終サマリー:
```text
ビルドステータス: SUCCESS/FAILED
修正済みエラー: N
Vet 警告修正済み: N
変更ファイル: list
残りの問題: list (ある場合)
Build Status: SUCCESS/FAILED
Errors Fixed: N
Vet Warnings Fixed: N
Files Modified: list
Remaining Issues: list (if any)
```
## 重要な注意事項

6
docs/ja-JP/agents/go-reviewer.md
View File

@@ -228,9 +228,9 @@ model: opus
各問題について:
```text
[CRITICAL] SQLインジェクション脆弱性
ファイル: internal/repository/user.go:42
問題: ユーザー入力がSQLクエリに直接連結されている
修正: パラメータ化クエリを使用
File: internal/repository/user.go:42
Issue: ユーザー入力がSQLクエリに直接連結されている
Fix: パラメータ化クエリを使用
query := "SELECT * FROM users WHERE id = " + userID // Bad
query := "SELECT * FROM users WHERE id = $1" // Good

6
docs/ja-JP/agents/python-reviewer.md
View File

@@ -399,9 +399,9 @@ model: opus
各問題について:
```text
[CRITICAL] SQLインジェクション脆弱性
ファイル: app/routes/user.py:42
問題: ユーザー入力がSQLクエリに直接補間されている
修正: パラメータ化クエリを使用
File: app/routes/user.py:42
Issue: ユーザー入力がSQLクエリに直接補間されている
Fix: パラメータ化クエリを使用
query = f"SELECT * FROM users WHERE id = {user_id}" # Bad
query = "SELECT * FROM users WHERE id = %s" # Good

18
docs/ja-JP/commands/checkpoint.md
View File

@@ -35,12 +35,12 @@ echo "$(date +%Y-%m-%d-%H:%M) | $CHECKPOINT_NAME | $(git rev-parse --short HEAD)
3. レポート：
```
チェックポイント比較: $NAME
CHECKPOINT COMPARISON: $NAME
============================
変更されたファイル: X
テスト: +Y 合格 / -Z 失敗
カバレッジ: +X% / -Y%
ビルド: [PASS/FAIL]
Files changed: X
Tests: +Y passed / -Z failed
Coverage: +X% / -Y%
Build: [PASS/FAIL]
```
## チェックポイント一覧表示
@@ -57,13 +57,13 @@ echo "$(date +%Y-%m-%d-%H:%M) | $CHECKPOINT_NAME | $(git rev-parse --short HEAD)
一般的なチェックポイント流：
```
[開始] --> /checkpoint create "feature-start"
[Start] --> /checkpoint create "feature-start"
|
[実装] --> /checkpoint create "core-done"
[Implement] --> /checkpoint create "core-done"
|
[テスト] --> /checkpoint verify "core-done"
[Test] --> /checkpoint verify "core-done"
|
[リファクタリング] --> /checkpoint create "refactor-done"
[Refactor] --> /checkpoint create "refactor-done"
|
[PR] --> /checkpoint verify "feature-start"
```

110
docs/ja-JP/commands/e2e.md
View File

@@ -38,24 +38,24 @@ e2e-runner エージェントは：
## 使用します示例
````
User: /e2e マーケット検索と表示フローをテスト
User: /e2e Test the market search and view flow
Agent (e2e-runner):
# E2Eテスト生成: マーケット検索と表示フロー
# E2E Test Generation: Market Search and View Flow
## 特定されたテストシナリオ
## Test Scenario Identified
**ユーザージャーニー:** マーケット検索 → 結果表示 → マーケットクリック → 詳細表示
**User Journey:** Market Search → View Results → Click Market → View Details
**テストカバレッジ:**
1. マーケットページに遷移
2. セマンティック検索を実行
3. 検索結果を検証
4. 最初の結果をクリック
5. マーケット詳細ページの読み込みを検証
6. チャートの描画を検証
**Test Coverage:**
1. Navigate to markets page
2. Perform semantic search
3. Verify search results
4. Click on first result
5. Verify market details page loads
6. Verify chart renders
## 生成されたテストコード
## Generated Test Code
```typescript
// tests/e2e/markets/search-and-view.spec.ts
@@ -160,7 +160,7 @@ test.describe('Market Search and View Flow', () => {
## テスト実行
```bash
# 生成されたテストを実行
# Run the generated test
npx playwright test tests/e2e/markets/search-and-view.spec.ts
Running 3 tests using 3 workers
@@ -181,54 +181,54 @@ Artifacts generated:
```
╔══════════════════════════════════════════════════════════════╗
║ E2Eテスト結果 ║
║ E2E Test Results ║
╠══════════════════════════════════════════════════════════════╣
║ ステータス: ✅ 全テスト合格 ║
║ 合計: 3テスト ║
║ 合格: 3 (100%) ║
║ 失敗: 0 ║
║ 不安定: 0 ║
║ 所要時間: 9.1s ║
║ Status: ✅ ALL TESTS PASSED ║
║ Total: 3 tests ║
║ Passed: 3 (100%) ║
║ Failed: 0 ║
║ Flaky: 0 ║
║ Duration: 9.1s ║
╚══════════════════════════════════════════════════════════════╝
アーティファクト:
📸 スクリーンショット: 2ファイル
📹 ビデオ: 0ファイル (失敗時のみ)
🔍 トレース: 0ファイル (失敗時のみ)
📊 HTMLレポート: playwright-report/index.html
Artifacts:
📸 Screenshots: 2 files
📹 Videos: 0 files (only on failure)
🔍 Traces: 0 files (only on failure)
📊 HTML Report: playwright-report/index.html
レポート表示: npx playwright show-report
View report: npx playwright show-report
```
✅ E2E テストスイートは CI/CD 統合の準備ができました！
````
## テストアーティファクト
## Test Artifacts
テスト実行時、以下のアーティファクトがキャプチャされます:
When tests run, the following artifacts are captured:
**全テスト共通:**
- タイムラインと結果を含むHTMLレポート
- CI統合用のJUnit XML
**On All Tests:**
- HTML Report with timeline and results
- JUnit XML for CI integration
**失敗時のみ:**
- 失敗状態のスクリーンショット
- テストのビデオ録画
- デバッグ用トレースファイル (ステップバイステップ再生)
- ネットワークログ
- コンソールログ
**On Failure Only:**
- Screenshot of the failing state
- Video recording of the test
- Trace file for debugging (step-by-step replay)
- Network logs
- Console logs
## アーティファクトの確認
## Viewing Artifacts
```bash
# ブラウザでHTMLレポートを表示
# View HTML report in browser
npx playwright show-report
# 特定のトレースファイルを表示
# View specific trace file
npx playwright show-trace artifacts/trace-abc123.zip
# スクリーンショットはartifacts/ディレクトリに保存
# Screenshots are saved in artifacts/ directory
open artifacts/search-results.png
````
@@ -239,18 +239,18 @@ open artifacts/search-results.png
```
⚠️ FLAKY TEST DETECTED: tests/e2e/markets/trade.spec.ts
テストは10回中7回合格 (合格率70%)
Test passed 7/10 runs (70% pass rate)
よくある失敗:
Common failure:
"Timeout waiting for element '[data-testid="confirm-btn"]'"
推奨修正:
1. 明示的な待機を追加: await page.waitForSelector('[data-testid="confirm-btn"]')
2. タイムアウトを増加: { timeout: 10000 }
3. コンポーネントの競合状態を確認
4. 要素がアニメーションで隠れていないか確認
Recommended fixes:
1. Add explicit wait: await page.waitForSelector('[data-testid="confirm-btn"]')
2. Increase timeout: { timeout: 10000 }
3. Check for race conditions in component
4. Verify element is not hidden by animation
隔離推奨: 修正されるまでtest.fixme()としてマーク
Quarantine recommendation: Mark as test.fixme() until fixed
```
## ブラウザ設定
@@ -350,21 +350,21 @@ PMX の場合、以下の E2E テストを優先：
## 快速命令
```bash
# 全E2Eテストを実行
# Run all E2E tests
npx playwright test
# 特定のテストファイルを実行
# Run specific test file
npx playwright test tests/e2e/markets/search.spec.ts
# ヘッドモードで実行 (ブラウザ表示)
# Run in headed mode (see browser)
npx playwright test --headed
# テストをデバッグ
# Debug test
npx playwright test --debug
# テストコードを生成
# Generate test code
npx playwright codegen http://localhost:3000
# レポートを表示
# View report
npx playwright show-report
```

20
docs/ja-JP/commands/evolve.md
View File

@@ -92,36 +92,36 @@ instinctsが分離の恩恵を受ける複雑な複数ステップのプロセ
## 出力フォーマット
```
🧬 進化分析
🧬 Evolve Analysis
==================
進化の準備ができた3つのクラスターを発見:
## クラスター1: データベースマイグレーションワークフロー
Instincts: new-table-migration, update-schema, regenerate-types
タイプ: Command
信頼度: 85%(12件の観測に基づく)
Type: Command
Confidence: 85%(12件の観測に基づく)
作成: /new-tableコマンド
ファイル:
Files:
- ~/.claude/homunculus/evolved/commands/new-table.md
## クラスター2: 関数型コードスタイル
Instincts: prefer-functional, use-immutable, avoid-classes, pure-functions
タイプ: Skill
信頼度: 78%(8件の観測に基づく)
Type: Skill
Confidence: 78%(8件の観測に基づく)
作成: functional-patternsスキル
ファイル:
Files:
- ~/.claude/homunculus/evolved/skills/functional-patterns.md
## クラスター3: デバッグプロセス
Instincts: debug-check-logs, debug-isolate, debug-reproduce, debug-verify
タイプ: Agent
信頼度: 72%(6件の観測に基づく)
Type: Agent
Confidence: 72%(6件の観測に基づく)
作成: debuggerエージェント
ファイル:
Files:
- ~/.claude/homunculus/evolved/agents/debugger.md
---

14
docs/ja-JP/commands/go-build.md
View File

@@ -62,9 +62,9 @@ internal/handler/api.go:58:2: missing return at end of function
## 修正1: 未定義の識別子
ファイル: internal/service/user.go:25
エラー: undefined: UserRepository
原因: インポート欠落
File: internal/service/user.go:25
Error: undefined: UserRepository
Cause: インポート欠落
```go
// インポートを追加
@@ -83,8 +83,8 @@ $ go build ./...
## 修正2: 型の不一致
ファイル: internal/handler/api.go:42
エラー: cannot use x (type string) as type int
File: internal/handler/api.go:42
Error: cannot use x (type string) as type int
```go
// 変更前
@@ -101,8 +101,8 @@ $ go build ./...
## 修正3: 戻り値の欠落
ファイル: internal/handler/api.go:58
エラー: missing return at end of function
File: internal/handler/api.go:58
Error: missing return at end of function
```go
func GetUser(id string) (*User, error) {

12
docs/ja-JP/commands/go-review.md
View File

@@ -85,8 +85,8 @@ Agent:
## 発見された問題
[CRITICAL] 競合状態
ファイル: internal/service/auth.go:45
問題: 同期化なしで共有マップにアクセス
File: internal/service/auth.go:45
Issue: 同期化なしで共有マップにアクセス
```go
var cache = map[string]*Session{} // 並行アクセス!
@@ -94,7 +94,7 @@ func GetSession(id string) *Session {
return cache[id] // 競合状態
}
```
修正: sync.RWMutexまたはsync.Mapを使用
Fix: sync.RWMutexまたはsync.Mapを使用
```go
var (
cache = map[string]*Session{}
@@ -109,12 +109,12 @@ func GetSession(id string) *Session {
```
[HIGH] エラーコンテキストの欠落
ファイル: internal/handler/user.go:28
問題: コンテキストなしでエラーを返す
File: internal/handler/user.go:28
Issue: コンテキストなしでエラーを返す
```go
return err // コンテキストなし
```
修正: コンテキストでラップ
Fix: コンテキストでラップ
```go
return fmt.Errorf("get user %s: %w", userID, err)
```

48
docs/ja-JP/commands/instinct-import.md
View File

@@ -45,40 +45,40 @@ python3 ~/.claude/skills/continuous-learning-v2/scripts/instinct-cli.py import <
## インポートプロセス
```
📥 instinctsをインポート中: team-instincts.yaml
📥 Importing instincts from: team-instincts.yaml
================================================
12件のinstinctsが見つかりました。
Found 12 instincts to import.
競合を分析中...
Analyzing conflicts...
## 新規instincts (8)
以下が追加されます:
## New Instincts (8)
These will be added:
✓ use-zod-validation (confidence: 0.7)
✓ prefer-named-exports (confidence: 0.65)
✓ test-async-functions (confidence: 0.8)
...
## 重複instincts (3)
類似のinstinctsが既に存在:
## Duplicate Instincts (3)
Already have similar instincts:
⚠️ prefer-functional-style
ローカル: 信頼度0.8, 12回の観測
インポート: 信頼度0.7
→ ローカルを保持 (信頼度が高い)
Local: 0.8 confidence, 12 observations
Import: 0.7 confidence
→ Keep local (higher confidence)
⚠️ test-first-workflow
ローカル: 信頼度0.75
インポート: 信頼度0.9
→ インポートに更新 (信頼度が高い)
Local: 0.75 confidence
Import: 0.9 confidence
→ Update to import (higher confidence)
## 競合instincts (1)
ローカルのinstinctsと矛盾:
## Conflicting Instincts (1)
These contradict local instincts:
❌ use-classes-for-services
競合: avoid-classes
→ スキップ (手動解決が必要)
Conflicts with: avoid-classes
→ Skip (requires manual resolution)
---
8件を新規追加、1件を更新、3件をスキップしますか?
Import 8 new, update 1, skip 3?
```
## マージ戦略
@@ -130,13 +130,13 @@ Skill Creatorからインポートする場合:
インポート後:
```
✅ インポート完了!
✅ Import complete!
追加: 8件のinstincts
更新: 1件のinstinct
スキップ: 3件のinstincts (2件の重複, 1件の競合)
Added: 8 instincts
Updated: 1 instinct
Skipped: 3 instincts (2 duplicates, 1 conflict)
新規instinctsの保存先: ~/.claude/homunculus/instincts/inherited/
New instincts saved to: ~/.claude/homunculus/instincts/inherited/
/instinct-statusを実行してすべてのinstinctsを確認できます。
Run /instinct-status to see all instincts.
```

44
docs/ja-JP/commands/instinct-status.md
View File

@@ -39,42 +39,42 @@ python3 ~/.claude/skills/continuous-learning-v2/scripts/instinct-cli.py status
## 出力形式
```
📊 instinctステータス
📊 Instinct Status
==================
## コードスタイル (4 instincts)
## Code Style (4 instincts)
### prefer-functional-style
トリガー: 新しい関数を書くとき
アクション: クラスより関数型パターンを使用
信頼度: ████████░░ 80%
ソース: session-observation | 最終更新: 2025-01-22
Trigger: when writing new functions
Action: Use functional patterns over classes
Confidence: ████████░░ 80%
Source: session-observation | Last updated: 2025-01-22
### use-path-aliases
トリガー: モジュールをインポートするとき
アクション: 相対インポートの代わりに@/パスエイリアスを使用
信頼度: ██████░░░░ 60%
ソース: repo-analysis (github.com/acme/webapp)
Trigger: when importing modules
Action: Use @/ path aliases instead of relative imports
Confidence: ██████░░░░ 60%
Source: repo-analysis (github.com/acme/webapp)
## テスト (2 instincts)
## Testing (2 instincts)
### test-first-workflow
トリガー: 新しい機能を追加するとき
アクション: テストを先に書き、次に実装
信頼度: █████████░ 90%
ソース: session-observation
Trigger: when adding new functionality
Action: Write test first, then implementation
Confidence: █████████░ 90%
Source: session-observation
## ワークフロー (3 instincts)
## Workflow (3 instincts)
### grep-before-edit
トリガー: コードを変更するとき
アクション: Grepで検索、Readで確認、次にEdit
信頼度: ███████░░░ 70%
ソース: session-observation
Trigger: when modifying code
Action: Search with Grep, confirm with Read, then Edit
Confidence: ███████░░░ 70%
Source: session-observation
---
合計: 9 instincts (4個人, 5継承)
オブザーバー: 実行中 (最終分析: 5分前)
Total: 9 instincts (4 personal, 5 inherited)
Observer: Running (last analysis: 5 min ago)
```
## フラグ

20
docs/ja-JP/commands/orchestrate.md
View File

@@ -99,36 +99,36 @@ security-reviewer -> code-reviewer -> architect
## 最終レポート形式
```
オーケストレーションレポート
ORCHESTRATION REPORT
====================
ワークフロー: feature
タスク: ユーザー認証の追加
エージェント: planner -> tdd-guide -> code-reviewer -> security-reviewer
Workflow: feature
Task: Add user authentication
Agents: planner -> tdd-guide -> code-reviewer -> security-reviewer
サマリー
SUMMARY
-------
[1段落の要約]
エージェント出力
AGENT OUTPUTS
-------------
Planner: [要約]
TDD Guide: [要約]
Code Reviewer: [要約]
Security Reviewer: [要約]
変更ファイル
FILES CHANGED
-------------
[変更されたすべてのファイルをリスト]
テスト結果
TEST RESULTS
------------
[テスト合格/不合格の要約]
セキュリティステータス
SECURITY STATUS
---------------
[セキュリティの発見事項]
推奨事項
RECOMMENDATION
--------------
[リリース可 / 要修正 / ブロック中]
```

24
docs/ja-JP/commands/python-review.md
View File

@@ -95,26 +95,26 @@ Agent:
## 発見された問題
[CRITICAL] SQLインジェクション脆弱性
ファイル: app/routes/user.py:42
問題: ユーザー入力が直接SQLクエリに挿入されている
File: app/routes/user.py:42
Issue: ユーザー入力が直接SQLクエリに挿入されている
```python
query = f"SELECT * FROM users WHERE id = {user_id}" # 悪い
```
修正: パラメータ化クエリを使用
Fix: パラメータ化クエリを使用
```python
query = "SELECT * FROM users WHERE id = %s" # 良い
cursor.execute(query, (user_id,))
```
[HIGH] 可変デフォルト引数
ファイル: app/services/auth.py:18
問題: 可変デフォルト引数が共有状態を引き起こす
File: app/services/auth.py:18
Issue: 可変デフォルト引数が共有状態を引き起こす
```python
def process_items(items=[]): # 悪い
items.append("new")
return items
```
修正: デフォルトにNoneを使用
Fix: デフォルトにNoneを使用
```python
def process_items(items=None): # 良い
if items is None:
@@ -124,27 +124,27 @@ def process_items(items=None): # 良い
```
[MEDIUM] 型ヒントの欠落
ファイル: app/services/auth.py:25
問題: 型アノテーションのない公開関数
File: app/services/auth.py:25
Issue: 型アノテーションのない公開関数
```python
def get_user(user_id): # 悪い
return db.find(user_id)
```
修正: 型ヒントを追加
Fix: 型ヒントを追加
```python
def get_user(user_id: str) -> Optional[User]: # 良い
return db.find(user_id)
```
[MEDIUM] コンテキストマネージャーを使用していない
ファイル: app/routes/user.py:55
問題: 例外時にファイルがクローズされない
File: app/routes/user.py:55
Issue: 例外時にファイルがクローズされない
```python
f = open("config.json") # 悪い
data = f.read()
f.close()
```
修正: コンテキストマネージャーを使用
Fix: コンテキストマネージャーを使用
```python
with open("config.json") as f: # 良い
data = f.read()

16
docs/ja-JP/commands/verify.md
View File

@@ -36,16 +36,16 @@
簡潔な検証レポートを生成します:
```
検証結果: [PASS/FAIL]
VERIFICATION: [PASS/FAIL]
ビルド: [OK/FAIL]
型: [OK/Xエラー]
Lint: [OK/X件の問題]
テスト: [X/Y合格, Z%カバレッジ]
シークレット: [OK/X件発見]
ログ: [OK/X件のconsole.log]
Build: [OK/FAIL]
Types: [OK/X errors]
Lint: [OK/X issues]
Tests: [X/Y passed, Z% coverage]
Secrets: [OK/X found]
Logs: [OK/X console.logs]
PR準備完了: [YES/NO]
Ready for PR: [YES/NO]
```
重大な問題がある場合は、修正案とともにリストアップします。

2
docs/ja-JP/examples/CLAUDE.md
View File

@@ -43,7 +43,7 @@
```
src/
|-- app/ # Next.js App Router
|-- app/ # Next.js app router
|-- components/ # 再利用可能なUIコンポーネント
|-- hooks/ # カスタムReactフック
|-- lib/ # ユーティリティライブラリ

50
docs/ja-JP/skills/coding-standards/SKILL.md
View File

@@ -234,14 +234,14 @@ setCount(count + 1) // Can be stale in async scenarios
### REST API規約
```
GET /api/markets # すべてのマーケットを一覧
GET /api/markets/:id # 特定のマーケットを取得
POST /api/markets # 新しいマーケットを作成
PUT /api/markets/:id # マーケットを更新（全体）
PATCH /api/markets/:id # マーケットを更新（部分）
DELETE /api/markets/:id # マーケットを削除
GET /api/markets # List all markets
GET /api/markets/:id # Get specific market
POST /api/markets # Create new market
PUT /api/markets/:id # Update market (full)
PATCH /api/markets/:id # Update market (partial)
DELETE /api/markets/:id # Delete market
# フィルタリング用クエリパラメータ
# Query parameters for filtering
GET /api/markets?status=active&limit=10&offset=0
```
@@ -312,29 +312,29 @@ export async function POST(request: Request) {
```
src/
├── app/ # Next.js App Router
│ ├── api/ # API ルート
│ ├── markets/ # マーケットページ
│ └── (auth)/ # 認証ページ（ルートグループ）
├── components/ # React コンポーネント
│ ├── ui/ # 汎用 UI コンポーネント
│ ├── forms/ # フォームコンポーネント
│ └── layouts/ # レイアウトコンポーネント
├── hooks/ # カスタム React フック
├── lib/ # ユーティリティと設定
│ ├── api/ # API クライアント
│ ├── utils/ # ヘルパー関数
│ └── constants/ # 定数
├── types/ # TypeScript 型定義
└── styles/ # グローバルスタイル
│ ├── api/ # API routes
│ ├── markets/ # Market pages
│ └── (auth)/ # Auth pages (route groups)
├── components/ # React components
│ ├── ui/ # Generic UI components
│ ├── forms/ # Form components
│ └── layouts/ # Layout components
├── hooks/ # Custom React hooks
├── lib/ # Utilities and configs
│ ├── api/ # API clients
│ ├── utils/ # Helper functions
│ └── constants/ # Constants
├── types/ # TypeScript types
└── styles/ # Global styles
```
### ファイル命名
```
components/Button.tsx # コンポーネントは PascalCase
hooks/useAuth.ts # フックは 'use' プレフィックス付き camelCase
lib/formatDate.ts # ユーティリティは camelCase
types/market.types.ts # 型定義は .types サフィックス付き camelCase
components/Button.tsx # PascalCase for components
hooks/useAuth.ts # camelCase with 'use' prefix
lib/formatDate.ts # camelCase for utilities
types/market.types.ts # camelCase with .types suffix
```
## コメントとドキュメント

4
docs/ja-JP/skills/continuous-learning-v2/SKILL.md
View File

@@ -51,13 +51,13 @@ source: "session-observation"
## 仕組み
```
セッションアクティビティ
Session Activity
│
│ フックがプロンプト + ツール使用をキャプチャ（100%信頼性）
▼
┌─────────────────────────────────────────┐
│ observations.jsonl │
│ （プロンプト、ツール呼び出し、結果） │
│ (prompts, tool calls, outcomes) │
└─────────────────────────────────────────┘
│
│ Observerエージェントが読み取り（バックグラウンド、Haiku）

68
docs/ja-JP/skills/eval-harness/SKILL.md
View File

@@ -22,24 +22,24 @@ Claude Codeセッションの正式な評価フレームワークで、評価駆
Claudeが以前できなかったことができるようになったかをテスト：
```markdown
[CAPABILITY EVAL: feature-name]
タスク: Claudeが達成すべきことの説明
成功基準:
Task: Claudeが達成すべきことの説明
Success Criteria:
- [ ] 基準1
- [ ] 基準2
- [ ] 基準3
期待される出力: 期待される結果の説明
Expected Output: 期待される結果の説明
```
### リグレッション評価
変更が既存の機能を破壊しないことを確認：
```markdown
[REGRESSION EVAL: feature-name]
ベースライン: SHAまたはチェックポイント名
テスト:
Baseline: SHAまたはチェックポイント名
Tests:
- existing-test-1: PASS/FAIL
- existing-test-2: PASS/FAIL
- existing-test-3: PASS/FAIL
結果: X/Y 成功（以前は Y/Y）
Result: X/Y passed (previously Y/Y)
```
## 評価者タイプ
@@ -67,17 +67,17 @@ Claudeを使用して自由形式の出力を評価：
3. エッジケースは処理されていますか？
4. エラー処理は適切ですか？
スコア: 1-5（1=不良、5=優秀）
理由: [説明]
Score: 1-5 (1=poor, 5=excellent)
Reasoning: [説明]
```
### 3. 人間評価者
手動レビューのためにフラグを立てる：
```markdown
[HUMAN REVIEW REQUIRED]
変更内容: 何が変更されたかの説明
理由: 人間のレビューが必要な理由
リスクレベル: LOW/MEDIUM/HIGH
Change: 何が変更されたかの説明
Reason: 人間のレビューが必要な理由
Risk Level: LOW/MEDIUM/HIGH
```
## メトリクス
@@ -98,21 +98,21 @@ Claudeを使用して自由形式の出力を評価：
### 1. 定義（コーディング前）
```markdown
## 評価定義: feature-xyz
## EVAL DEFINITION: feature-xyz
### 能力評価
### Capability Evals
1. 新しいユーザーアカウントを作成できる
2. メール形式を検証できる
3. パスワードを安全にハッシュ化できる
### リグレッション評価
### Regression Evals
1. 既存のログインが引き続き機能する
2. セッション管理が変更されていない
3. ログアウトフローが維持されている
### 成功メトリクス
- 能力評価で pass@3 > 90%
- リグレッション評価で pass^3 = 100%
### Success Metrics
- pass@3 > 90% for capability evals
- pass^3 = 100% for regression evals
```
### 2. 実装
@@ -131,26 +131,26 @@ npm test -- --testPathPattern="existing"
### 4. レポート
```markdown
評価レポート: feature-xyz
EVAL REPORT: feature-xyz
========================
能力評価:
Capability Evals:
create-user: PASS (pass@1)
validate-email: PASS (pass@2)
hash-password: PASS (pass@1)
全体: 3/3 成功
Overall: 3/3 passed
リグレッション評価:
Regression Evals:
login-flow: PASS
session-mgmt: PASS
logout-flow: PASS
全体: 3/3 成功
Overall: 3/3 passed
メトリクス:
Metrics:
pass@1: 67% (2/3)
pass@3: 100% (3/3)
ステータス: レビュー準備完了
Status: READY FOR REVIEW
```
## 統合パターン
@@ -199,29 +199,29 @@ npm test -- --testPathPattern="existing"
```markdown
## EVAL: add-authentication
### フェーズ 1: 定義（10分）
能力評価:
### Phase 1: Define (10 min)
Capability Evals:
- [ ] ユーザーはメール/パスワードで登録できる
- [ ] ユーザーは有効な資格情報でログインできる
- [ ] 無効な資格情報は適切なエラーで拒否される
- [ ] セッションはページリロード後も持続する
- [ ] ログアウトはセッションをクリアする
リグレッション評価:
Regression Evals:
- [ ] 公開ルートは引き続きアクセス可能
- [ ] APIレスポンスは変更されていない
- [ ] データベーススキーマは互換性がある
### フェーズ 2: 実装（可変）
### Phase 2: Implement (varies)
[コードを書く]
### フェーズ 3: 評価
### Phase 3: Evaluate
Run: /eval check add-authentication
### フェーズ 4: レポート
評価レポート: add-authentication
### Phase 4: Report
EVAL REPORT: add-authentication
==============================
能力: 5/5 成功（pass@3: 100%）
リグレッション: 3/3 成功（pass^3: 100%）
ステータス: 出荷可能
Capability: 5/5 passed (pass@3: 100%)
Regression: 3/3 passed (pass^3: 100%)
Status: SHIP IT
```

16
docs/ja-JP/skills/golang-patterns/SKILL.md
View File

@@ -368,17 +368,17 @@ func WriteAndFlush(w io.Writer, data []byte) error {
myproject/
├── cmd/
│ └── myapp/
│ └── main.go # エントリポイント
│ └── main.go # Entry point
├── internal/
│ ├── handler/ # HTTP ハンドラー
│ ├── service/ # ビジネスロジック
│ ├── repository/ # データアクセス
│ └── config/ # 設定
│ ├── handler/ # HTTP handlers
│ ├── service/ # Business logic
│ ├── repository/ # Data access
│ └── config/ # Configuration
├── pkg/
│ └── client/ # 公開 API クライアント
│ └── client/ # Public API client
├── api/
│ └── v1/ # API 定義（proto、OpenAPI）
├── testdata/ # テストフィクスチャ
│ └── v1/ # API definitions (proto, OpenAPI)
├── testdata/ # Test fixtures
├── go.mod
├── go.sum
└── Makefile

2
docs/ja-JP/skills/golang-testing/SKILL.md
View File

@@ -113,7 +113,7 @@ mypackage/
├── testdata/ # テストフィクスチャ
│ ├── valid_user.json
│ └── invalid_user.json
└── export_test.go # 内部テスト用の非公開エクスポート
└── export_test.go # 内部のテストのための非公開のエクスポート
```
### テストパッケージ

8
docs/ja-JP/skills/python-testing/SKILL.md
View File

@@ -594,18 +594,18 @@ def test_with_tmpdir(tmpdir):
```
tests/
├── conftest.py # 共有フィクスチャ
├── conftest.py # Shared fixtures
├── __init__.py
├── unit/ # ユニットテスト
├── unit/ # Unit tests
│ ├── __init__.py
│ ├── test_models.py
│ ├── test_utils.py
│ └── test_services.py
├── integration/ # 統合テスト
├── integration/ # Integration tests
│ ├── __init__.py
│ ├── test_api.py
│ └── test_database.py
└── e2e/ # エンドツーエンドテスト
└── e2e/ # End-to-end tests
├── __init__.py
└── test_user_flow.py
```

3
docs/zh-CN/skills/prompt-optimizer/SKILL.md
View File

@@ -1,7 +1,6 @@
---
name: prompt-optimizer
description: 分析原始提示，识别意图和差距，匹配ECC组件（技能/命令/代理/钩子），并输出一个可直接粘贴的优化提示。仅提供咨询角色——绝不自行执行任务。触发时机：当用户说“优化提示”、“改进我的提示”、“如何编写提示”、“帮我优化这个指令”或明确要求提高提示质量时。中文等效表达同样触发：“优化prompt”、“改进prompt”、“怎么写prompt”、“帮我优化这个指令”。不触发时机：当用户希望直接执行任务，或说“直接做”时。不触发时机：当用户说“优化代码”、“优化性能”、“optimize performance”、“optimize this code”时——这些是重构/性能优化任务，而非提示优化。
origin: community
description: 分析原始提示，识别意图和差距，匹配ECC组件（技能/命令/代理/钩子），并输出一个可直接粘贴的优化提示。仅提供咨询角色——绝不自行执行任务。触发时机：当用户说“优化提示”、“改进我的提示”、“如何编写提示”、“帮我优化这个指令”或明确要求提高提示质量时。中文等效表达同样触发：“优化prompt”、“改进prompt”、“怎么写prompt”、“帮我优化这个指令”。不触发时机：当用户希望直接执行任务，或说“直接做”时。不触发时机：当用户说“优化代码”、“优化性能”、“optimize performance”、“optimize this code”时——这些是重构/性能优化任务，而非提示优化。origin: community
metadata:
author: YannJY02
version: "1.0.0"

9
ecc2/Cargo.lock generated
View File

@@ -332,7 +332,6 @@ dependencies = [
"crossterm",
"dirs",
"git2",
"libc",
"ratatui",
"rusqlite",
"serde",
@@ -438,9 +437,9 @@ dependencies = [
[[package]]
name = "git2"
version = "0.20.4"
version = "0.19.0"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "7b88256088d75a56f8ecfa070513a775dd9107f6530ef14919dac831af9cfe2b"
checksum = "b903b73e45dc0c6c596f2d37eccece7c1c8bb6e4407b001096387c63d0d93724"
dependencies = [
"bitflags",
"libc",
@@ -725,9 +724,9 @@ checksum = "b5b646652bf6661599e1da8901b3b9522896f01e736bad5f723fe7a3a27f899d"
[[package]]
name = "libgit2-sys"
version = "0.18.3+1.9.2"
version = "0.17.0+1.8.1"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "c9b3acc4b91781bb0b3386669d325163746af5f6e4f73e6d2d630e09a35f3487"
checksum = "10472326a8a6477c3c20a64547b0059e4b0d086869eee31e6d7da728a8eb7224"
dependencies = [
"cc",
"libc",

3
ecc2/Cargo.toml
View File

@@ -19,7 +19,7 @@ tokio = { version = "1", features = ["full"] }
rusqlite = { version = "0.32", features = ["bundled"] }
# Git integration
git2 = "0.20"
git2 = "0.19"
# Serialization
serde = { version = "1", features = ["derive"] }
@@ -36,7 +36,6 @@ tracing-subscriber = { version = "0.3", features = ["env-filter"] }
# Error handling
anyhow = "1"
thiserror = "2"
libc = "0.2"
# Time
chrono = { version = "0.4", features = ["serde"] }

5
ecc2/src/comms/mod.rs
View File

@@ -13,10 +13,7 @@ pub enum MessageType {
/// Response to a query
Response { answer: String },
/// Notification of completion
Completed {
summary: String,
files_changed: Vec<String>,
},
Completed { summary: String, files_changed: Vec<String> },
/// Conflict detected (e.g., two agents editing the same file)
Conflict { file: String, description: String },
}

90
ecc2/src/config/mod.rs
View File

@@ -2,25 +2,7 @@ use anyhow::Result;
use serde::{Deserialize, Serialize};
use std::path::PathBuf;
#[derive(Debug, Clone, Copy, Default, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
pub enum PaneLayout {
#[default]
Horizontal,
Vertical,
Grid,
}
#[derive(Debug, Clone, Copy, PartialEq, Serialize, Deserialize)]
#[serde(default)]
pub struct RiskThresholds {
pub review: f64,
pub confirm: f64,
pub block: f64,
}
#[derive(Debug, Clone, Serialize, Deserialize)]
#[serde(default)]
pub struct Config {
pub db_path: PathBuf,
pub worktree_root: PathBuf,
@@ -29,11 +11,7 @@ pub struct Config {
pub session_timeout_secs: u64,
pub heartbeat_interval_secs: u64,
pub default_agent: String,
pub cost_budget_usd: f64,
pub token_budget: u64,
pub theme: Theme,
pub pane_layout: PaneLayout,
pub risk_thresholds: RiskThresholds,
}
#[derive(Debug, Clone, Serialize, Deserialize)]
@@ -53,22 +31,12 @@ impl Default for Config {
session_timeout_secs: 3600,
heartbeat_interval_secs: 30,
default_agent: "claude".to_string(),
cost_budget_usd: 10.0,
token_budget: 500_000,
theme: Theme::Dark,
pane_layout: PaneLayout::Horizontal,
risk_thresholds: Self::RISK_THRESHOLDS,
}
}
}
impl Config {
pub const RISK_THRESHOLDS: RiskThresholds = RiskThresholds {
review: 0.35,
confirm: 0.60,
block: 0.85,
};
pub fn load() -> Result<Self> {
let config_path = dirs::home_dir()
.unwrap_or_else(|| PathBuf::from("."))
@@ -84,61 +52,3 @@ impl Config {
}
}
}
impl Default for RiskThresholds {
fn default() -> Self {
Config::RISK_THRESHOLDS
}
}
#[cfg(test)]
mod tests {
use super::{Config, PaneLayout};
#[test]
fn default_includes_positive_budget_thresholds() {
let config = Config::default();
assert!(config.cost_budget_usd > 0.0);
assert!(config.token_budget > 0);
}
#[test]
fn missing_budget_fields_fall_back_to_defaults() {
let legacy_config = r#"
db_path = "/tmp/ecc2.db"
worktree_root = "/tmp/ecc-worktrees"
max_parallel_sessions = 8
max_parallel_worktrees = 6
session_timeout_secs = 3600
heartbeat_interval_secs = 30
default_agent = "claude"
theme = "Dark"
"#;
let config: Config = toml::from_str(legacy_config).unwrap();
let defaults = Config::default();
assert_eq!(config.cost_budget_usd, defaults.cost_budget_usd);
assert_eq!(config.token_budget, defaults.token_budget);
assert_eq!(config.pane_layout, defaults.pane_layout);
assert_eq!(config.risk_thresholds, defaults.risk_thresholds);
}
#[test]
fn default_pane_layout_is_horizontal() {
assert_eq!(Config::default().pane_layout, PaneLayout::Horizontal);
}
#[test]
fn pane_layout_deserializes_from_toml() {
let config: Config = toml::from_str(r#"pane_layout = "grid""#).unwrap();
assert_eq!(config.pane_layout, PaneLayout::Grid);
}
#[test]
fn default_risk_thresholds_are_applied() {
assert_eq!(Config::default().risk_thresholds, Config::RISK_THRESHOLDS);
}
}

60
ecc2/src/main.rs
View File

@@ -1,13 +1,12 @@
mod comms;
mod config;
mod observability;
mod session;
mod tui;
mod worktree;
mod observability;
mod comms;
use anyhow::Result;
use clap::Parser;
use std::path::PathBuf;
use tracing_subscriber::EnvFilter;
#[derive(Parser, Debug)]
@@ -45,24 +44,8 @@ enum Commands {
/// Session ID or alias
session_id: String,
},
/// Resume a failed or stopped session
Resume {
/// Session ID or alias
session_id: String,
},
/// Run as background daemon
Daemon,
#[command(hide = true)]
RunSession {
#[arg(long)]
session_id: String,
#[arg(long)]
task: String,
#[arg(long)]
agent: String,
#[arg(long)]
cwd: PathBuf,
},
}
#[tokio::main]
@@ -80,13 +63,10 @@ async fn main() -> Result<()> {
Some(Commands::Dashboard) | None => {
tui::app::run(db, cfg).await?;
}
Some(Commands::Start {
task,
agent,
worktree: use_worktree,
}) => {
let session_id =
session::manager::create_session(&db, &cfg, &task, &agent, use_worktree).await?;
Some(Commands::Start { task, agent, worktree: use_worktree }) => {
let session_id = session::manager::create_session(
&db, &cfg, &task, &agent, use_worktree,
).await?;
println!("Session started: {session_id}");
}
Some(Commands::Sessions) => {
@@ -104,39 +84,11 @@ async fn main() -> Result<()> {
session::manager::stop_session(&db, &session_id).await?;
println!("Session stopped: {session_id}");
}
Some(Commands::Resume { session_id }) => {
let resumed_id = session::manager::resume_session(&db, &session_id).await?;
println!("Session resumed: {resumed_id}");
}
Some(Commands::Daemon) => {
println!("Starting ECC daemon...");
session::daemon::run(db, cfg).await?;
}
Some(Commands::RunSession {
session_id,
task,
agent,
cwd,
}) => {
session::manager::run_session(&cfg, &session_id, &task, &agent, &cwd).await?;
}
}
Ok(())
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn cli_parses_resume_command() {
let cli = Cli::try_parse_from(["ecc", "resume", "deadbeef"])
.expect("resume subcommand should parse");
match cli.command {
Some(Commands::Resume { session_id }) => assert_eq!(session_id, "deadbeef"),
_ => panic!("expected resume subcommand"),
}
}
}

415
ecc2/src/observability/mod.rs
View File

@@ -1,7 +1,6 @@
use anyhow::{bail, Result};
use anyhow::Result;
use serde::{Deserialize, Serialize};
use crate::config::{Config, RiskThresholds};
use crate::session::store::StateStore;
#[derive(Debug, Clone, Serialize, Deserialize)]
@@ -14,396 +13,42 @@ pub struct ToolCallEvent {
pub risk_score: f64,
}
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct RiskAssessment {
pub score: f64,
pub reasons: Vec<String>,
pub suggested_action: SuggestedAction,
}
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
pub enum SuggestedAction {
Allow,
Review,
RequireConfirmation,
Block,
}
impl ToolCallEvent {
pub fn new(
session_id: impl Into<String>,
tool_name: impl Into<String>,
input_summary: impl Into<String>,
output_summary: impl Into<String>,
duration_ms: u64,
) -> Self {
let tool_name = tool_name.into();
let input_summary = input_summary.into();
/// Compute risk score based on tool type and input patterns.
pub fn compute_risk(tool_name: &str, input: &str) -> f64 {
let mut score: f64 = 0.0;
Self {
session_id: session_id.into(),
risk_score: Self::compute_risk(&tool_name, &input_summary, &Config::RISK_THRESHOLDS)
.score,
tool_name,
input_summary,
output_summary: output_summary.into(),
duration_ms,
}
}
/// Compute risk from the tool type and input characteristics.
pub fn compute_risk(
tool_name: &str,
input: &str,
thresholds: &RiskThresholds,
) -> RiskAssessment {
let normalized_tool = tool_name.to_ascii_lowercase();
let normalized_input = input.to_ascii_lowercase();
let mut score = 0.0;
let mut reasons = Vec::new();
let (base_score, base_reason) = base_tool_risk(&normalized_tool);
score += base_score;
if let Some(reason) = base_reason {
reasons.push(reason.to_string());
// Destructive tools get higher base risk
match tool_name {
"Bash" => score += 0.3,
"Write" => score += 0.2,
"Edit" => score += 0.1,
_ => score += 0.05,
}
let (file_sensitivity_score, file_sensitivity_reason) =
assess_file_sensitivity(&normalized_input);
score += file_sensitivity_score;
if let Some(reason) = file_sensitivity_reason {
reasons.push(reason);
// Dangerous patterns in bash commands
if tool_name == "Bash" {
if input.contains("rm -rf") || input.contains("--force") {
score += 0.4;
}
if input.contains("git push") || input.contains("git reset") {
score += 0.3;
}
if input.contains("sudo") || input.contains("chmod 777") {
score += 0.5;
}
}
let (blast_radius_score, blast_radius_reason) = assess_blast_radius(&normalized_input);
score += blast_radius_score;
if let Some(reason) = blast_radius_reason {
reasons.push(reason);
}
let (irreversibility_score, irreversibility_reason) =
assess_irreversibility(&normalized_input);
score += irreversibility_score;
if let Some(reason) = irreversibility_reason {
reasons.push(reason);
}
let score = score.clamp(0.0, 1.0);
let suggested_action = SuggestedAction::from_score(score, thresholds);
RiskAssessment {
score,
reasons,
suggested_action,
}
score.min(1.0)
}
}
impl SuggestedAction {
fn from_score(score: f64, thresholds: &RiskThresholds) -> Self {
if score >= thresholds.block {
Self::Block
} else if score >= thresholds.confirm {
Self::RequireConfirmation
} else if score >= thresholds.review {
Self::Review
} else {
Self::Allow
}
}
}
fn base_tool_risk(tool_name: &str) -> (f64, Option<&'static str>) {
match tool_name {
"bash" => (
0.20,
Some("shell execution can modify local or shared state"),
),
"write" | "multiedit" => (0.15, Some("writes files directly")),
"edit" => (0.10, Some("modifies existing files")),
_ => (0.05, None),
}
}
fn assess_file_sensitivity(input: &str) -> (f64, Option<String>) {
const SECRET_PATTERNS: &[&str] = &[
".env",
"secret",
"credential",
"token",
"api_key",
"apikey",
"auth",
"id_rsa",
".pem",
".key",
];
const SHARED_INFRA_PATTERNS: &[&str] = &[
"cargo.toml",
"package.json",
"dockerfile",
".github/workflows",
"schema",
"migration",
"production",
];
if contains_any(input, SECRET_PATTERNS) {
(
0.25,
Some("targets a sensitive file or credential surface".to_string()),
)
} else if contains_any(input, SHARED_INFRA_PATTERNS) {
(
0.15,
Some("targets shared infrastructure or release-critical files".to_string()),
)
} else {
(0.0, None)
}
}
fn assess_blast_radius(input: &str) -> (f64, Option<String>) {
const LARGE_SCOPE_PATTERNS: &[&str] = &[
"**",
"/*",
"--all",
"--recursive",
"entire repo",
"all files",
"across src/",
"find ",
" xargs ",
];
const SHARED_STATE_PATTERNS: &[&str] = &[
"git push --force",
"git push -f",
"origin main",
"origin master",
"rm -rf .",
"rm -rf /",
];
if contains_any(input, SHARED_STATE_PATTERNS) {
(
0.35,
Some("has a broad blast radius across shared state or history".to_string()),
)
} else if contains_any(input, LARGE_SCOPE_PATTERNS) {
(
0.25,
Some("has a broad blast radius across multiple files or directories".to_string()),
)
} else {
(0.0, None)
}
}
fn assess_irreversibility(input: &str) -> (f64, Option<String>) {
const HIGH_IRREVERSIBILITY_PATTERNS: &[&str] = &[
"rm -rf",
"git reset --hard",
"git clean -fd",
"drop database",
"drop table",
"truncate ",
"shred ",
];
const MODERATE_IRREVERSIBILITY_PATTERNS: &[&str] =
&["rm -f", "git push --force", "git push -f", "delete from"];
if contains_any(input, HIGH_IRREVERSIBILITY_PATTERNS) {
(
0.45,
Some("includes an irreversible or destructive operation".to_string()),
)
} else if contains_any(input, MODERATE_IRREVERSIBILITY_PATTERNS) {
(
0.40,
Some("includes an irreversible or difficult-to-undo operation".to_string()),
)
} else {
(0.0, None)
}
}
fn contains_any(input: &str, patterns: &[&str]) -> bool {
patterns.iter().any(|pattern| input.contains(pattern))
}
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
pub struct ToolLogEntry {
pub id: i64,
pub session_id: String,
pub tool_name: String,
pub input_summary: String,
pub output_summary: String,
pub duration_ms: u64,
pub risk_score: f64,
pub timestamp: String,
}
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
pub struct ToolLogPage {
pub entries: Vec<ToolLogEntry>,
pub page: u64,
pub page_size: u64,
pub total: u64,
}
pub struct ToolLogger<'a> {
db: &'a StateStore,
}
impl<'a> ToolLogger<'a> {
pub fn new(db: &'a StateStore) -> Self {
Self { db }
}
pub fn log(&self, event: &ToolCallEvent) -> Result<ToolLogEntry> {
let timestamp = chrono::Utc::now().to_rfc3339();
self.db.insert_tool_log(
&event.session_id,
&event.tool_name,
&event.input_summary,
&event.output_summary,
event.duration_ms,
event.risk_score,
&timestamp,
)
}
pub fn query(&self, session_id: &str, page: u64, page_size: u64) -> Result<ToolLogPage> {
if page_size == 0 {
bail!("page_size must be greater than 0");
}
self.db.query_tool_logs(session_id, page.max(1), page_size)
}
}
pub fn log_tool_call(db: &StateStore, event: &ToolCallEvent) -> Result<ToolLogEntry> {
ToolLogger::new(db).log(event)
}
#[cfg(test)]
mod tests {
use super::{SuggestedAction, ToolCallEvent, ToolLogger};
use crate::config::Config;
use crate::session::store::StateStore;
use crate::session::{Session, SessionMetrics, SessionState};
use std::path::PathBuf;
fn test_db_path() -> PathBuf {
std::env::temp_dir().join(format!("ecc2-observability-{}.db", uuid::Uuid::new_v4()))
}
fn test_session(id: &str) -> Session {
let now = chrono::Utc::now();
Session {
id: id.to_string(),
task: "test task".to_string(),
agent_type: "claude".to_string(),
state: SessionState::Pending,
pid: None,
worktree: None,
created_at: now,
updated_at: now,
metrics: SessionMetrics::default(),
}
}
#[test]
fn computes_sensitive_file_risk() {
let assessment = ToolCallEvent::compute_risk(
"Write",
"Update .env.production with rotated API token",
&Config::RISK_THRESHOLDS,
);
assert!(assessment.score >= Config::RISK_THRESHOLDS.review);
assert_eq!(assessment.suggested_action, SuggestedAction::Review);
assert!(assessment
.reasons
.iter()
.any(|reason| reason.contains("sensitive file")));
}
#[test]
fn computes_blast_radius_risk() {
let assessment = ToolCallEvent::compute_risk(
"Edit",
"Apply the same replacement across src/**/*.rs",
&Config::RISK_THRESHOLDS,
);
assert!(assessment.score >= Config::RISK_THRESHOLDS.review);
assert_eq!(assessment.suggested_action, SuggestedAction::Review);
assert!(assessment
.reasons
.iter()
.any(|reason| reason.contains("blast radius")));
}
#[test]
fn computes_irreversible_risk() {
let assessment = ToolCallEvent::compute_risk(
"Bash",
"rm -f /tmp/ecc-temp.txt",
&Config::RISK_THRESHOLDS,
);
assert!(assessment.score >= Config::RISK_THRESHOLDS.confirm);
assert_eq!(
assessment.suggested_action,
SuggestedAction::RequireConfirmation,
);
assert!(assessment
.reasons
.iter()
.any(|reason| reason.contains("irreversible")));
}
#[test]
fn blocks_combined_high_risk_operations() {
let assessment = ToolCallEvent::compute_risk(
"Bash",
"rm -rf . && git push --force origin main",
&Config::RISK_THRESHOLDS,
);
assert!(assessment.score >= Config::RISK_THRESHOLDS.block);
assert_eq!(assessment.suggested_action, SuggestedAction::Block);
}
#[test]
fn logger_persists_entries_and_paginates() -> anyhow::Result<()> {
let db_path = test_db_path();
let db = StateStore::open(&db_path)?;
db.insert_session(&test_session("sess-1"))?;
let logger = ToolLogger::new(&db);
logger.log(&ToolCallEvent::new("sess-1", "Read", "first", "ok", 5))?;
logger.log(&ToolCallEvent::new("sess-1", "Write", "second", "ok", 15))?;
logger.log(&ToolCallEvent::new("sess-1", "Bash", "third", "ok", 25))?;
let first_page = logger.query("sess-1", 1, 2)?;
assert_eq!(first_page.total, 3);
assert_eq!(first_page.entries.len(), 2);
assert_eq!(first_page.entries[0].tool_name, "Bash");
assert_eq!(first_page.entries[1].tool_name, "Write");
let second_page = logger.query("sess-1", 2, 2)?;
assert_eq!(second_page.total, 3);
assert_eq!(second_page.entries.len(), 1);
assert_eq!(second_page.entries[0].tool_name, "Read");
std::fs::remove_file(&db_path).ok();
Ok(())
}
pub fn log_tool_call(db: &StateStore, event: &ToolCallEvent) -> Result<()> {
db.send_message(
&event.session_id,
"observability",
&serde_json::to_string(event)?,
"tool_call",
)?;
Ok(())
}

133
ecc2/src/session/daemon.rs
View File

@@ -10,7 +10,6 @@ use crate::config::Config;
/// and cleans up stale resources.
pub async fn run(db: StateStore, cfg: Config) -> Result<()> {
tracing::info!("ECC daemon started");
resume_crashed_sessions(&db)?;
let heartbeat_interval = Duration::from_secs(cfg.heartbeat_interval_secs);
let timeout = Duration::from_secs(cfg.session_timeout_secs);
@@ -24,43 +23,6 @@ pub async fn run(db: StateStore, cfg: Config) -> Result<()> {
}
}
pub fn resume_crashed_sessions(db: &StateStore) -> Result<()> {
let failed_sessions = resume_crashed_sessions_with(db, pid_is_alive)?;
if failed_sessions > 0 {
tracing::warn!("Marked {failed_sessions} crashed sessions as failed during daemon startup");
}
Ok(())
}
fn resume_crashed_sessions_with<F>(db: &StateStore, is_pid_alive: F) -> Result<usize>
where
F: Fn(u32) -> bool,
{
let sessions = db.list_sessions()?;
let mut failed_sessions = 0;
for session in sessions {
if session.state != SessionState::Running {
continue;
}
let is_alive = session.pid.is_some_and(&is_pid_alive);
if is_alive {
continue;
}
tracing::warn!(
"Session {} was left running with stale pid {:?}; marking it failed",
session.id,
session.pid
);
db.update_state_and_pid(&session.id, &SessionState::Failed, None)?;
failed_sessions += 1;
}
Ok(failed_sessions)
}
fn check_sessions(db: &StateStore, timeout: Duration) -> Result<()> {
let sessions = db.list_sessions()?;
@@ -76,102 +38,9 @@ fn check_sessions(db: &StateStore, timeout: Duration) -> Result<()> {
if elapsed > timeout {
tracing::warn!("Session {} timed out after {:?}", session.id, elapsed);
db.update_state_and_pid(&session.id, &SessionState::Failed, None)?;
db.update_state(&session.id, &SessionState::Failed)?;
}
}
Ok(())
}
#[cfg(unix)]
fn pid_is_alive(pid: u32) -> bool {
if pid == 0 {
return false;
}
// SAFETY: kill(pid, 0) probes process existence without delivering a signal.
let result = unsafe { libc::kill(pid as libc::pid_t, 0) };
if result == 0 {
return true;
}
matches!(
std::io::Error::last_os_error().raw_os_error(),
Some(code) if code == libc::EPERM
)
}
#[cfg(not(unix))]
fn pid_is_alive(_pid: u32) -> bool {
false
}
#[cfg(test)]
mod tests {
use super::*;
use crate::session::{Session, SessionMetrics, SessionState};
use std::path::PathBuf;
fn temp_db_path() -> PathBuf {
std::env::temp_dir().join(format!("ecc2-daemon-test-{}.db", uuid::Uuid::new_v4()))
}
fn sample_session(id: &str, state: SessionState, pid: Option<u32>) -> Session {
let now = chrono::Utc::now();
Session {
id: id.to_string(),
task: "Recover crashed worker".to_string(),
agent_type: "claude".to_string(),
state,
pid,
worktree: None,
created_at: now,
updated_at: now,
metrics: SessionMetrics::default(),
}
}
#[test]
fn resume_crashed_sessions_marks_dead_running_sessions_failed() -> Result<()> {
let path = temp_db_path();
let store = StateStore::open(&path)?;
store.insert_session(&sample_session(
"deadbeef",
SessionState::Running,
Some(4242),
))?;
resume_crashed_sessions_with(&store, |_| false)?;
let session = store
.get_session("deadbeef")?
.expect("session should still exist");
assert_eq!(session.state, SessionState::Failed);
assert_eq!(session.pid, None);
let _ = std::fs::remove_file(path);
Ok(())
}
#[test]
fn resume_crashed_sessions_keeps_live_running_sessions_running() -> Result<()> {
let path = temp_db_path();
let store = StateStore::open(&path)?;
store.insert_session(&sample_session(
"alive123",
SessionState::Running,
Some(7777),
))?;
resume_crashed_sessions_with(&store, |_| true)?;
let session = store
.get_session("alive123")?
.expect("session should still exist");
assert_eq!(session.state, SessionState::Running);
assert_eq!(session.pid, Some(7777));
let _ = std::fs::remove_file(path);
Ok(())
}
}

660
ecc2/src/session/manager.rs
View File

@@ -1,15 +1,9 @@
use anyhow::{Context, Result};
use anyhow::Result;
use std::fmt;
use std::path::{Path, PathBuf};
use std::process::Stdio;
use tokio::process::Command;
use super::output::SessionOutputStore;
use super::runtime::capture_command_output;
use super::store::StateStore;
use super::{Session, SessionMetrics, SessionState};
use super::store::StateStore;
use crate::config::Config;
use crate::observability::{log_tool_call, ToolCallEvent, ToolLogEntry, ToolLogPage, ToolLogger};
use crate::worktree;
pub async fn create_session(
@@ -19,9 +13,28 @@ pub async fn create_session(
agent_type: &str,
use_worktree: bool,
) -> Result<String> {
let repo_root =
std::env::current_dir().context("Failed to resolve current working directory")?;
queue_session_in_dir(db, cfg, task, agent_type, use_worktree, &repo_root).await
let id = uuid::Uuid::new_v4().to_string()[..8].to_string();
let now = chrono::Utc::now();
let wt = if use_worktree {
Some(worktree::create_for_session(&id, cfg)?)
} else {
None
};
let session = Session {
id: id.clone(),
task: task.to_string(),
agent_type: agent_type.to_string(),
state: SessionState::Pending,
worktree: wt,
created_at: now,
updated_at: now,
metrics: SessionMetrics::default(),
};
db.insert_session(&session)?;
Ok(id)
}
pub fn list_sessions(db: &StateStore) -> Result<Vec<Session>> {
@@ -29,345 +42,17 @@ pub fn list_sessions(db: &StateStore) -> Result<Vec<Session>> {
}
pub fn get_status(db: &StateStore, id: &str) -> Result<SessionStatus> {
let session = resolve_session(db, id)?;
let session = db
.get_session(id)?
.ok_or_else(|| anyhow::anyhow!("Session not found: {id}"))?;
Ok(SessionStatus(session))
}
pub async fn stop_session(db: &StateStore, id: &str) -> Result<()> {
stop_session_with_options(db, id, true).await
}
pub fn record_tool_call(
db: &StateStore,
session_id: &str,
tool_name: &str,
input_summary: &str,
output_summary: &str,
duration_ms: u64,
) -> Result<ToolLogEntry> {
let session = db
.get_session(session_id)?
.ok_or_else(|| anyhow::anyhow!("Session not found: {session_id}"))?;
let event = ToolCallEvent::new(
session.id.clone(),
tool_name,
input_summary,
output_summary,
duration_ms,
);
let entry = log_tool_call(db, &event)?;
db.increment_tool_calls(&session.id)?;
Ok(entry)
}
pub fn query_tool_calls(
db: &StateStore,
session_id: &str,
page: u64,
page_size: u64,
) -> Result<ToolLogPage> {
let session = db
.get_session(session_id)?
.ok_or_else(|| anyhow::anyhow!("Session not found: {session_id}"))?;
ToolLogger::new(db).query(&session.id, page, page_size)
}
pub async fn resume_session(db: &StateStore, id: &str) -> Result<String> {
let session = resolve_session(db, id)?;
if session.state == SessionState::Completed {
anyhow::bail!("Completed sessions cannot be resumed: {}", session.id);
}
if session.state == SessionState::Running {
anyhow::bail!("Session is already running: {}", session.id);
}
db.update_state_and_pid(&session.id, &SessionState::Pending, None)?;
Ok(session.id)
}
fn agent_program(agent_type: &str) -> Result<PathBuf> {
match agent_type {
"claude" => Ok(PathBuf::from("claude")),
other => anyhow::bail!("Unsupported agent type: {other}"),
}
}
fn resolve_session(db: &StateStore, id: &str) -> Result<Session> {
let session = if id == "latest" {
db.get_latest_session()?
} else {
db.get_session(id)?
};
session.ok_or_else(|| anyhow::anyhow!("Session not found: {id}"))
}
pub async fn run_session(
cfg: &Config,
session_id: &str,
task: &str,
agent_type: &str,
working_dir: &Path,
) -> Result<()> {
let db = StateStore::open(&cfg.db_path)?;
let session = resolve_session(&db, session_id)?;
if session.state != SessionState::Pending {
tracing::info!(
"Skipping run_session for {} because state is {}",
session_id,
session.state
);
return Ok(());
}
let agent_program = agent_program(agent_type)?;
let command = build_agent_command(&agent_program, task, session_id, working_dir);
capture_command_output(
cfg.db_path.clone(),
session_id.to_string(),
command,
SessionOutputStore::default(),
)
.await?;
db.update_state(id, &SessionState::Stopped)?;
Ok(())
}
async fn queue_session_in_dir(
db: &StateStore,
cfg: &Config,
task: &str,
agent_type: &str,
use_worktree: bool,
repo_root: &Path,
) -> Result<String> {
let session = build_session_record(task, agent_type, use_worktree, cfg, repo_root)?;
db.insert_session(&session)?;
let working_dir = session
.worktree
.as_ref()
.map(|worktree| worktree.path.as_path())
.unwrap_or(repo_root);
match spawn_session_runner(task, &session.id, agent_type, working_dir).await {
Ok(()) => Ok(session.id),
Err(error) => {
db.update_state(&session.id, &SessionState::Failed)?;
if let Some(worktree) = session.worktree.as_ref() {
let _ = crate::worktree::remove(&worktree.path);
}
Err(error.context(format!("Failed to queue session {}", session.id)))
}
}
}
fn build_session_record(
task: &str,
agent_type: &str,
use_worktree: bool,
cfg: &Config,
repo_root: &Path,
) -> Result<Session> {
let id = uuid::Uuid::new_v4().to_string()[..8].to_string();
let now = chrono::Utc::now();
let worktree = if use_worktree {
Some(worktree::create_for_session_in_repo(&id, cfg, repo_root)?)
} else {
None
};
Ok(Session {
id,
task: task.to_string(),
agent_type: agent_type.to_string(),
state: SessionState::Pending,
pid: None,
worktree,
created_at: now,
updated_at: now,
metrics: SessionMetrics::default(),
})
}
async fn create_session_in_dir(
db: &StateStore,
cfg: &Config,
task: &str,
agent_type: &str,
use_worktree: bool,
repo_root: &Path,
agent_program: &Path,
) -> Result<String> {
let session = build_session_record(task, agent_type, use_worktree, cfg, repo_root)?;
db.insert_session(&session)?;
let working_dir = session
.worktree
.as_ref()
.map(|worktree| worktree.path.as_path())
.unwrap_or(repo_root);
match spawn_claude_code(agent_program, task, &session.id, working_dir).await {
Ok(pid) => {
db.update_pid(&session.id, Some(pid))?;
db.update_state(&session.id, &SessionState::Running)?;
Ok(session.id)
}
Err(error) => {
db.update_state(&session.id, &SessionState::Failed)?;
if let Some(worktree) = session.worktree.as_ref() {
let _ = crate::worktree::remove(&worktree.path);
}
Err(error.context(format!("Failed to start session {}", session.id)))
}
}
}
async fn spawn_session_runner(
task: &str,
session_id: &str,
agent_type: &str,
working_dir: &Path,
) -> Result<()> {
let current_exe = std::env::current_exe().context("Failed to resolve ECC executable path")?;
let child = Command::new(&current_exe)
.arg("run-session")
.arg("--session-id")
.arg(session_id)
.arg("--task")
.arg(task)
.arg("--agent")
.arg(agent_type)
.arg("--cwd")
.arg(working_dir)
.stdin(Stdio::null())
.stdout(Stdio::null())
.stderr(Stdio::null())
.spawn()
.with_context(|| {
format!(
"Failed to spawn ECC runner from {}",
current_exe.display()
)
})?;
child
.id()
.ok_or_else(|| anyhow::anyhow!("ECC runner did not expose a process id"))?;
Ok(())
}
fn build_agent_command(agent_program: &Path, task: &str, session_id: &str, working_dir: &Path) -> Command {
let mut command = Command::new(agent_program);
command
.arg("--print")
.arg("--name")
.arg(format!("ecc-{session_id}"))
.arg(task)
.current_dir(working_dir)
.stdin(Stdio::null());
command
}
async fn spawn_claude_code(
agent_program: &Path,
task: &str,
session_id: &str,
working_dir: &Path,
) -> Result<u32> {
let mut command = build_agent_command(agent_program, task, session_id, working_dir);
let child = command
.stdout(Stdio::null())
.stderr(Stdio::null())
.spawn()
.with_context(|| {
format!(
"Failed to spawn Claude Code from {}",
agent_program.display()
)
})?;
child
.id()
.ok_or_else(|| anyhow::anyhow!("Claude Code did not expose a process id"))
}
async fn stop_session_with_options(
db: &StateStore,
id: &str,
cleanup_worktree: bool,
) -> Result<()> {
let session = resolve_session(db, id)?;
if let Some(pid) = session.pid {
kill_process(pid).await?;
}
db.update_pid(&session.id, None)?;
db.update_state(&session.id, &SessionState::Stopped)?;
if cleanup_worktree {
if let Some(worktree) = session.worktree.as_ref() {
crate::worktree::remove(&worktree.path)?;
}
}
Ok(())
}
#[cfg(unix)]
async fn kill_process(pid: u32) -> Result<()> {
send_signal(pid, libc::SIGTERM)?;
tokio::time::sleep(std::time::Duration::from_millis(1200)).await;
send_signal(pid, libc::SIGKILL)?;
Ok(())
}
#[cfg(unix)]
fn send_signal(pid: u32, signal: i32) -> Result<()> {
let outcome = unsafe { libc::kill(pid as i32, signal) };
if outcome == 0 {
return Ok(());
}
let error = std::io::Error::last_os_error();
if error.raw_os_error() == Some(libc::ESRCH) {
return Ok(());
}
Err(error).with_context(|| format!("Failed to kill process {pid}"))
}
#[cfg(not(unix))]
async fn kill_process(pid: u32) -> Result<()> {
let status = Command::new("taskkill")
.args(["/F", "/PID", &pid.to_string()])
.stdin(Stdio::null())
.stdout(Stdio::null())
.stderr(Stdio::null())
.status()
.await
.with_context(|| format!("Failed to invoke taskkill for process {pid}"))?;
if status.success() {
Ok(())
} else {
anyhow::bail!("taskkill failed for process {pid}");
}
}
pub struct SessionStatus(Session);
impl fmt::Display for SessionStatus {
@@ -377,9 +62,6 @@ impl fmt::Display for SessionStatus {
writeln!(f, "Task: {}", s.task)?;
writeln!(f, "Agent: {}", s.agent_type)?;
writeln!(f, "State: {}", s.state)?;
if let Some(pid) = s.pid {
writeln!(f, "PID: {}", pid)?;
}
if let Some(ref wt) = s.worktree {
writeln!(f, "Branch: {}", wt.branch)?;
writeln!(f, "Worktree: {}", wt.path.display())?;
@@ -392,289 +74,3 @@ impl fmt::Display for SessionStatus {
write!(f, "Updated: {}", s.updated_at)
}
}
#[cfg(test)]
mod tests {
use super::*;
use crate::config::{Config, PaneLayout, Theme};
use crate::session::{Session, SessionMetrics, SessionState};
use anyhow::{Context, Result};
use chrono::{Duration, Utc};
use std::fs;
use std::os::unix::fs::PermissionsExt;
use std::path::{Path, PathBuf};
use std::process::Command as StdCommand;
use std::thread;
use std::time::Duration as StdDuration;
struct TestDir {
path: PathBuf,
}
impl TestDir {
fn new(label: &str) -> Result<Self> {
let path =
std::env::temp_dir().join(format!("ecc2-{}-{}", label, uuid::Uuid::new_v4()));
fs::create_dir_all(&path)?;
Ok(Self { path })
}
fn path(&self) -> &Path {
&self.path
}
}
impl Drop for TestDir {
fn drop(&mut self) {
let _ = fs::remove_dir_all(&self.path);
}
}
fn build_config(root: &Path) -> Config {
Config {
db_path: root.join("state.db"),
worktree_root: root.join("worktrees"),
max_parallel_sessions: 4,
max_parallel_worktrees: 4,
session_timeout_secs: 60,
heartbeat_interval_secs: 5,
default_agent: "claude".to_string(),
cost_budget_usd: 10.0,
token_budget: 500_000,
theme: Theme::Dark,
pane_layout: PaneLayout::Horizontal,
risk_thresholds: Config::RISK_THRESHOLDS,
}
}
fn build_session(id: &str, state: SessionState, updated_at: chrono::DateTime<Utc>) -> Session {
Session {
id: id.to_string(),
task: format!("task-{id}"),
agent_type: "claude".to_string(),
state,
pid: None,
worktree: None,
created_at: updated_at - Duration::minutes(1),
updated_at,
metrics: SessionMetrics::default(),
}
}
fn init_git_repo(path: &Path) -> Result<()> {
fs::create_dir_all(path)?;
run_git(path, ["init", "-q"])?;
fs::write(path.join("README.md"), "hello\n")?;
run_git(path, ["add", "README.md"])?;
run_git(
path,
[
"-c",
"user.name=ECC Tests",
"-c",
"user.email=ecc-tests@example.com",
"commit",
"-qm",
"init",
],
)?;
Ok(())
}
fn run_git<const N: usize>(path: &Path, args: [&str; N]) -> Result<()> {
let status = StdCommand::new("git")
.args(args)
.current_dir(path)
.status()
.with_context(|| format!("failed to run git in {}", path.display()))?;
if !status.success() {
anyhow::bail!("git command failed in {}", path.display());
}
Ok(())
}
fn write_fake_claude(root: &Path) -> Result<(PathBuf, PathBuf)> {
let script_path = root.join("fake-claude.sh");
let log_path = root.join("fake-claude.log");
let script = format!(
"#!/usr/bin/env python3\nimport os\nimport pathlib\nimport signal\nimport sys\nimport time\n\nlog_path = pathlib.Path(r\"{}\")\nlog_path.write_text(os.getcwd() + \"\\n\", encoding=\"utf-8\")\nwith log_path.open(\"a\", encoding=\"utf-8\") as handle:\n handle.write(\" \".join(sys.argv[1:]) + \"\\n\")\n\ndef handle_term(signum, frame):\n raise SystemExit(0)\n\nsignal.signal(signal.SIGTERM, handle_term)\nwhile True:\n time.sleep(0.1)\n",
log_path.display()
);
fs::write(&script_path, script)?;
let mut permissions = fs::metadata(&script_path)?.permissions();
permissions.set_mode(0o755);
fs::set_permissions(&script_path, permissions)?;
Ok((script_path, log_path))
}
fn wait_for_file(path: &Path) -> Result<String> {
for _ in 0..50 {
if path.exists() {
return fs::read_to_string(path)
.with_context(|| format!("failed to read {}", path.display()));
}
thread::sleep(StdDuration::from_millis(20));
}
anyhow::bail!("timed out waiting for {}", path.display());
}
#[tokio::test(flavor = "current_thread")]
async fn create_session_spawns_process_and_marks_session_running() -> Result<()> {
let tempdir = TestDir::new("manager-create-session")?;
let repo_root = tempdir.path().join("repo");
init_git_repo(&repo_root)?;
let cfg = build_config(tempdir.path());
let db = StateStore::open(&cfg.db_path)?;
let (fake_claude, log_path) = write_fake_claude(tempdir.path())?;
let session_id = create_session_in_dir(
&db,
&cfg,
"implement lifecycle",
"claude",
false,
&repo_root,
&fake_claude,
)
.await?;
let session = db
.get_session(&session_id)?
.context("session should exist")?;
assert_eq!(session.state, SessionState::Running);
assert!(
session.pid.is_some(),
"spawned session should persist a pid"
);
let log = wait_for_file(&log_path)?;
assert!(log.contains(repo_root.to_string_lossy().as_ref()));
assert!(log.contains("--print"));
assert!(log.contains("implement lifecycle"));
stop_session_with_options(&db, &session_id, false).await?;
Ok(())
}
#[tokio::test(flavor = "current_thread")]
async fn stop_session_kills_process_and_optionally_cleans_worktree() -> Result<()> {
let tempdir = TestDir::new("manager-stop-session")?;
let repo_root = tempdir.path().join("repo");
init_git_repo(&repo_root)?;
let cfg = build_config(tempdir.path());
let db = StateStore::open(&cfg.db_path)?;
let (fake_claude, _) = write_fake_claude(tempdir.path())?;
let keep_id = create_session_in_dir(
&db,
&cfg,
"keep worktree",
"claude",
true,
&repo_root,
&fake_claude,
)
.await?;
let keep_session = db.get_session(&keep_id)?.context("keep session missing")?;
keep_session.pid.context("keep session pid missing")?;
let keep_worktree = keep_session
.worktree
.clone()
.context("keep session worktree missing")?
.path;
stop_session_with_options(&db, &keep_id, false).await?;
let stopped_keep = db
.get_session(&keep_id)?
.context("stopped keep session missing")?;
assert_eq!(stopped_keep.state, SessionState::Stopped);
assert_eq!(stopped_keep.pid, None);
assert!(
keep_worktree.exists(),
"worktree should remain when cleanup is disabled"
);
let cleanup_id = create_session_in_dir(
&db,
&cfg,
"cleanup worktree",
"claude",
true,
&repo_root,
&fake_claude,
)
.await?;
let cleanup_session = db
.get_session(&cleanup_id)?
.context("cleanup session missing")?;
let cleanup_worktree = cleanup_session
.worktree
.clone()
.context("cleanup session worktree missing")?
.path;
stop_session_with_options(&db, &cleanup_id, true).await?;
assert!(
!cleanup_worktree.exists(),
"worktree should be removed when cleanup is enabled"
);
Ok(())
}
#[tokio::test(flavor = "current_thread")]
async fn resume_session_requeues_failed_session() -> Result<()> {
let tempdir = TestDir::new("manager-resume-session")?;
let cfg = build_config(tempdir.path());
let db = StateStore::open(&cfg.db_path)?;
let now = Utc::now();
db.insert_session(&Session {
id: "deadbeef".to_string(),
task: "resume previous task".to_string(),
agent_type: "claude".to_string(),
state: SessionState::Failed,
pid: Some(31337),
worktree: None,
created_at: now - Duration::minutes(1),
updated_at: now,
metrics: SessionMetrics::default(),
})?;
let resumed_id = resume_session(&db, "deadbeef").await?;
let resumed = db
.get_session(&resumed_id)?
.context("resumed session should exist")?;
assert_eq!(resumed.state, SessionState::Pending);
assert_eq!(resumed.pid, None);
Ok(())
}
#[test]
fn get_status_supports_latest_alias() -> Result<()> {
let tempdir = TestDir::new("manager-latest-status")?;
let cfg = build_config(tempdir.path());
let db = StateStore::open(&cfg.db_path)?;
let older = Utc::now() - Duration::minutes(2);
let newer = Utc::now();
db.insert_session(&build_session("older", SessionState::Running, older))?;
db.insert_session(&build_session("newer", SessionState::Idle, newer))?;
let status = get_status(&db, "latest")?;
assert_eq!(status.0.id, "newer");
Ok(())
}
}

43
ecc2/src/session/mod.rs
View File

@@ -15,14 +15,13 @@ pub struct Session {
pub task: String,
pub agent_type: String,
pub state: SessionState,
pub pid: Option<u32>,
pub worktree: Option<WorktreeInfo>,
pub created_at: DateTime<Utc>,
pub updated_at: DateTime<Utc>,
pub metrics: SessionMetrics,
}
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
pub enum SessionState {
Pending,
Running,
@@ -45,46 +44,6 @@ impl fmt::Display for SessionState {
}
}
impl SessionState {
pub fn can_transition_to(&self, next: &Self) -> bool {
if self == next {
return true;
}
matches!(
(self, next),
(
SessionState::Pending,
SessionState::Running | SessionState::Failed | SessionState::Stopped
) | (
SessionState::Running,
SessionState::Idle
| SessionState::Completed
| SessionState::Failed
| SessionState::Stopped
) | (
SessionState::Idle,
SessionState::Running
| SessionState::Completed
| SessionState::Failed
| SessionState::Stopped
) | (SessionState::Completed, SessionState::Stopped)
| (SessionState::Failed, SessionState::Stopped)
)
}
pub fn from_db_value(value: &str) -> Self {
match value {
"running" => SessionState::Running,
"idle" => SessionState::Idle,
"completed" => SessionState::Completed,
"failed" => SessionState::Failed,
"stopped" => SessionState::Stopped,
_ => SessionState::Pending,
}
}
}
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct WorktreeInfo {
pub path: PathBuf,

174
ecc2/src/session/runtime.rs
View File

@@ -1,128 +1,21 @@
use std::path::PathBuf;
use std::process::{ExitStatus, Stdio};
use std::path::{Path, PathBuf};
use std::process::ExitStatus;
use std::process::Stdio;
use anyhow::{Context, Result};
use tokio::io::{AsyncBufReadExt, AsyncRead, BufReader};
use tokio::process::Command;
use tokio::sync::{mpsc, oneshot};
use super::output::{OutputStream, SessionOutputStore};
use super::store::StateStore;
use super::SessionState;
type DbAck = std::result::Result<(), String>;
enum DbMessage {
UpdateState {
state: SessionState,
ack: oneshot::Sender<DbAck>,
},
UpdatePid {
pid: Option<u32>,
ack: oneshot::Sender<DbAck>,
},
AppendOutputLine {
stream: OutputStream,
line: String,
ack: oneshot::Sender<DbAck>,
},
}
#[derive(Clone)]
struct DbWriter {
tx: mpsc::UnboundedSender<DbMessage>,
}
impl DbWriter {
fn start(db_path: PathBuf, session_id: String) -> Self {
let (tx, rx) = mpsc::unbounded_channel();
std::thread::spawn(move || run_db_writer(db_path, session_id, rx));
Self { tx }
}
async fn update_state(&self, state: SessionState) -> Result<()> {
self.send(|ack| DbMessage::UpdateState { state, ack }).await
}
async fn update_pid(&self, pid: Option<u32>) -> Result<()> {
self.send(|ack| DbMessage::UpdatePid { pid, ack }).await
}
async fn append_output_line(&self, stream: OutputStream, line: String) -> Result<()> {
self.send(|ack| DbMessage::AppendOutputLine { stream, line, ack })
.await
}
async fn send<F>(&self, build: F) -> Result<()>
where
F: FnOnce(oneshot::Sender<DbAck>) -> DbMessage,
{
let (ack_tx, ack_rx) = oneshot::channel();
self.tx
.send(build(ack_tx))
.map_err(|_| anyhow::anyhow!("DB writer channel closed"))?;
match ack_rx.await {
Ok(Ok(())) => Ok(()),
Ok(Err(error)) => Err(anyhow::anyhow!(error)),
Err(_) => Err(anyhow::anyhow!("DB writer acknowledgement dropped")),
}
}
}
fn run_db_writer(
db_path: PathBuf,
session_id: String,
mut rx: mpsc::UnboundedReceiver<DbMessage>,
) {
let (opened, open_error) = match StateStore::open(&db_path) {
Ok(db) => (Some(db), None),
Err(error) => (None, Some(error.to_string())),
};
while let Some(message) = rx.blocking_recv() {
match message {
DbMessage::UpdateState { state, ack } => {
let result = match opened.as_ref() {
Some(db) => db.update_state(&session_id, &state).map_err(|error| error.to_string()),
None => Err(open_error
.clone()
.unwrap_or_else(|| "Failed to open state store".to_string())),
};
let _ = ack.send(result);
}
DbMessage::UpdatePid { pid, ack } => {
let result = match opened.as_ref() {
Some(db) => db.update_pid(&session_id, pid).map_err(|error| error.to_string()),
None => Err(open_error
.clone()
.unwrap_or_else(|| "Failed to open state store".to_string())),
};
let _ = ack.send(result);
}
DbMessage::AppendOutputLine { stream, line, ack } => {
let result = match opened.as_ref() {
Some(db) => db
.append_output_line(&session_id, stream, &line)
.map_err(|error| error.to_string()),
None => Err(open_error
.clone()
.unwrap_or_else(|| "Failed to open state store".to_string())),
};
let _ = ack.send(result);
}
}
}
}
pub async fn capture_command_output(
db_path: PathBuf,
session_id: String,
mut command: Command,
output_store: SessionOutputStore,
) -> Result<ExitStatus> {
let db_writer = DbWriter::start(db_path, session_id.clone());
let result = async {
let mut child = command
.stdout(Stdio::piped())
@@ -130,42 +23,24 @@ pub async fn capture_command_output(
.spawn()
.with_context(|| format!("Failed to start process for session {}", session_id))?;
let stdout = match child.stdout.take() {
Some(stdout) => stdout,
None => {
let _ = child.kill().await;
let _ = child.wait().await;
anyhow::bail!("Child stdout was not piped");
}
};
let stderr = match child.stderr.take() {
Some(stderr) => stderr,
None => {
let _ = child.kill().await;
let _ = child.wait().await;
anyhow::bail!("Child stderr was not piped");
}
};
update_session_state(&db_path, &session_id, SessionState::Running)?;
let pid = child
.id()
.ok_or_else(|| anyhow::anyhow!("Spawned process did not expose a process id"))?;
db_writer.update_pid(Some(pid)).await?;
db_writer.update_state(SessionState::Running).await?;
let stdout = child.stdout.take().context("Child stdout was not piped")?;
let stderr = child.stderr.take().context("Child stderr was not piped")?;
let stdout_task = tokio::spawn(capture_stream(
db_path.clone(),
session_id.clone(),
stdout,
OutputStream::Stdout,
output_store.clone(),
db_writer.clone(),
));
let stderr_task = tokio::spawn(capture_stream(
db_path.clone(),
session_id.clone(),
stderr,
OutputStream::Stderr,
output_store,
db_writer.clone(),
));
let status = child.wait().await?;
@@ -177,27 +52,25 @@ pub async fn capture_command_output(
} else {
SessionState::Failed
};
db_writer.update_pid(None).await?;
db_writer.update_state(final_state).await?;
update_session_state(&db_path, &session_id, final_state)?;
Ok(status)
}
.await;
if result.is_err() {
let _ = db_writer.update_pid(None).await;
let _ = db_writer.update_state(SessionState::Failed).await;
let _ = update_session_state(&db_path, &session_id, SessionState::Failed);
}
result
}
async fn capture_stream<R>(
db_path: PathBuf,
session_id: String,
reader: R,
stream: OutputStream,
output_store: SessionOutputStore,
db_writer: DbWriter,
) -> Result<()>
where
R: AsyncRead + Unpin,
@@ -205,15 +78,30 @@ where
let mut lines = BufReader::new(reader).lines();
while let Some(line) = lines.next_line().await? {
db_writer
.append_output_line(stream, line.clone())
.await?;
output_store.push_line(&session_id, stream, line);
output_store.push_line(&session_id, stream, line.clone());
append_output_line(&db_path, &session_id, stream, &line)?;
}
Ok(())
}
fn append_output_line(
db_path: &Path,
session_id: &str,
stream: OutputStream,
line: &str,
) -> Result<()> {
let db = StateStore::open(db_path)?;
db.append_output_line(session_id, stream, line)?;
Ok(())
}
fn update_session_state(db_path: &Path, session_id: &str, state: SessionState) -> Result<()> {
let db = StateStore::open(db_path)?;
db.update_state(session_id, &state)?;
Ok(())
}
#[cfg(test)]
mod tests {
use std::collections::HashSet;
@@ -241,7 +129,6 @@ mod tests {
task: "stream output".to_string(),
agent_type: "test".to_string(),
state: SessionState::Pending,
pid: None,
worktree: None,
created_at: now,
updated_at: now,
@@ -266,7 +153,6 @@ mod tests {
.get_session(&session_id)?
.expect("session should still exist");
assert_eq!(session.state, SessionState::Completed);
assert_eq!(session.pid, None);
let lines = db.get_output_lines(&session_id, OUTPUT_BUFFER_LIMIT)?;
let texts: HashSet<_> = lines.iter().map(|line| line.text.as_str()).collect();

347
ecc2/src/session/store.rs
View File

@@ -1,10 +1,8 @@
use anyhow::{Context, Result};
use rusqlite::{Connection, OptionalExtension};
use std::path::{Path, PathBuf};
use anyhow::Result;
use rusqlite::Connection;
use std::path::Path;
use std::time::Duration;
use crate::observability::{ToolLogEntry, ToolLogPage};
use super::output::{OutputLine, OutputStream, OUTPUT_BUFFER_LIMIT};
use super::{Session, SessionMetrics, SessionState};
@@ -15,7 +13,6 @@ pub struct StateStore {
impl StateStore {
pub fn open(path: &Path) -> Result<Self> {
let conn = Connection::open(path)?;
conn.execute_batch("PRAGMA foreign_keys = ON;")?;
conn.busy_timeout(Duration::from_secs(5))?;
let store = Self { conn };
store.init_schema()?;
@@ -30,7 +27,6 @@ impl StateStore {
task TEXT NOT NULL,
agent_type TEXT NOT NULL,
state TEXT NOT NULL DEFAULT 'pending',
pid INTEGER,
worktree_path TEXT,
worktree_branch TEXT,
worktree_base TEXT,
@@ -79,44 +75,19 @@ impl StateStore {
ON session_output(session_id, id);
",
)?;
self.ensure_session_columns()?;
Ok(())
}
fn ensure_session_columns(&self) -> Result<()> {
if !self.has_column("sessions", "pid")? {
self.conn
.execute("ALTER TABLE sessions ADD COLUMN pid INTEGER", [])
.context("Failed to add pid column to sessions table")?;
}
Ok(())
}
fn has_column(&self, table: &str, column: &str) -> Result<bool> {
let pragma = format!("PRAGMA table_info({table})");
let mut stmt = self.conn.prepare(&pragma)?;
let columns = stmt
.query_map([], |row| row.get::<_, String>(1))?
.collect::<std::result::Result<Vec<_>, _>>()?;
Ok(columns.iter().any(|existing| existing == column))
}
pub fn insert_session(&self, session: &Session) -> Result<()> {
self.conn.execute(
"INSERT INTO sessions (id, task, agent_type, state, pid, worktree_path, worktree_branch, worktree_base, created_at, updated_at)
VALUES (?1, ?2, ?3, ?4, ?5, ?6, ?7, ?8, ?9, ?10)",
"INSERT INTO sessions (id, task, agent_type, state, worktree_path, worktree_branch, worktree_base, created_at, updated_at)
VALUES (?1, ?2, ?3, ?4, ?5, ?6, ?7, ?8, ?9)",
rusqlite::params![
session.id,
session.task,
session.agent_type,
session.state.to_string(),
session.pid.map(i64::from),
session
.worktree
.as_ref()
.map(|w| w.path.to_string_lossy().to_string()),
session.worktree.as_ref().map(|w| w.path.to_string_lossy().to_string()),
session.worktree.as_ref().map(|w| w.branch.clone()),
session.worktree.as_ref().map(|w| w.base_branch.clone()),
session.created_at.to_rfc3339(),
@@ -126,50 +97,8 @@ impl StateStore {
Ok(())
}
pub fn update_state_and_pid(
&self,
session_id: &str,
state: &SessionState,
pid: Option<u32>,
) -> Result<()> {
let updated = self.conn.execute(
"UPDATE sessions SET state = ?1, pid = ?2, updated_at = ?3 WHERE id = ?4",
rusqlite::params![
state.to_string(),
pid.map(i64::from),
chrono::Utc::now().to_rfc3339(),
session_id,
],
)?;
if updated == 0 {
anyhow::bail!("Session not found: {session_id}");
}
Ok(())
}
pub fn update_state(&self, session_id: &str, state: &SessionState) -> Result<()> {
let current_state = self
.conn
.query_row(
"SELECT state FROM sessions WHERE id = ?1",
[session_id],
|row| row.get::<_, String>(0),
)
.optional()?
.map(|raw| SessionState::from_db_value(&raw))
.ok_or_else(|| anyhow::anyhow!("Session not found: {session_id}"))?;
if !current_state.can_transition_to(state) {
anyhow::bail!(
"Invalid session state transition: {} -> {}",
current_state,
state
);
}
let updated = self.conn.execute(
self.conn.execute(
"UPDATE sessions SET state = ?1, updated_at = ?2 WHERE id = ?3",
rusqlite::params![
state.to_string(),
@@ -177,28 +106,6 @@ impl StateStore {
session_id,
],
)?;
if updated == 0 {
anyhow::bail!("Session not found: {session_id}");
}
Ok(())
}
pub fn update_pid(&self, session_id: &str, pid: Option<u32>) -> Result<()> {
let updated = self.conn.execute(
"UPDATE sessions SET pid = ?1, updated_at = ?2 WHERE id = ?3",
rusqlite::params![
pid.map(i64::from),
chrono::Utc::now().to_rfc3339(),
session_id,
],
)?;
if updated == 0 {
anyhow::bail!("Session not found: {session_id}");
}
Ok(())
}
@@ -218,17 +125,9 @@ impl StateStore {
Ok(())
}
pub fn increment_tool_calls(&self, session_id: &str) -> Result<()> {
self.conn.execute(
"UPDATE sessions SET tool_calls = tool_calls + 1, updated_at = ?1 WHERE id = ?2",
rusqlite::params![chrono::Utc::now().to_rfc3339(), session_id],
)?;
Ok(())
}
pub fn list_sessions(&self) -> Result<Vec<Session>> {
let mut stmt = self.conn.prepare(
"SELECT id, task, agent_type, state, pid, worktree_path, worktree_branch, worktree_base,
"SELECT id, task, agent_type, state, worktree_path, worktree_branch, worktree_base,
tokens_used, tool_calls, files_changed, duration_secs, cost_usd,
created_at, updated_at
FROM sessions ORDER BY updated_at DESC",
@@ -237,24 +136,30 @@ impl StateStore {
let sessions = stmt
.query_map([], |row| {
let state_str: String = row.get(3)?;
let state = SessionState::from_db_value(&state_str);
let state = match state_str.as_str() {
"running" => SessionState::Running,
"idle" => SessionState::Idle,
"completed" => SessionState::Completed,
"failed" => SessionState::Failed,
"stopped" => SessionState::Stopped,
_ => SessionState::Pending,
};
let worktree_path: Option<String> = row.get(5)?;
let worktree = worktree_path.map(|path| super::WorktreeInfo {
path: PathBuf::from(path),
branch: row.get::<_, String>(6).unwrap_or_default(),
base_branch: row.get::<_, String>(7).unwrap_or_default(),
let worktree_path: Option<String> = row.get(4)?;
let worktree = worktree_path.map(|p| super::WorktreeInfo {
path: std::path::PathBuf::from(p),
branch: row.get::<_, String>(5).unwrap_or_default(),
base_branch: row.get::<_, String>(6).unwrap_or_default(),
});
let created_str: String = row.get(13)?;
let updated_str: String = row.get(14)?;
let created_str: String = row.get(12)?;
let updated_str: String = row.get(13)?;
Ok(Session {
id: row.get(0)?,
task: row.get(1)?,
agent_type: row.get(2)?,
state,
pid: row.get::<_, Option<u32>>(4)?,
worktree,
created_at: chrono::DateTime::parse_from_rfc3339(&created_str)
.unwrap_or_default()
@@ -263,11 +168,11 @@ impl StateStore {
.unwrap_or_default()
.with_timezone(&chrono::Utc),
metrics: SessionMetrics {
tokens_used: row.get(8)?,
tool_calls: row.get(9)?,
files_changed: row.get(10)?,
duration_secs: row.get(11)?,
cost_usd: row.get(12)?,
tokens_used: row.get(7)?,
tool_calls: row.get(8)?,
files_changed: row.get(9)?,
duration_secs: row.get(10)?,
cost_usd: row.get(11)?,
},
})
})?
@@ -276,15 +181,11 @@ impl StateStore {
Ok(sessions)
}
pub fn get_latest_session(&self) -> Result<Option<Session>> {
Ok(self.list_sessions()?.into_iter().next())
}
pub fn get_session(&self, id: &str) -> Result<Option<Session>> {
let sessions = self.list_sessions()?;
Ok(sessions
.into_iter()
.find(|session| session.id == id || session.id.starts_with(id)))
.find(|s| s.id == id || s.id.starts_with(id)))
}
pub fn send_message(&self, from: &str, to: &str, content: &str, msg_type: &str) -> Result<()> {
@@ -358,193 +259,24 @@ impl StateStore {
Ok(lines)
}
pub fn insert_tool_log(
&self,
session_id: &str,
tool_name: &str,
input_summary: &str,
output_summary: &str,
duration_ms: u64,
risk_score: f64,
timestamp: &str,
) -> Result<ToolLogEntry> {
self.conn.execute(
"INSERT INTO tool_log (session_id, tool_name, input_summary, output_summary, duration_ms, risk_score, timestamp)
VALUES (?1, ?2, ?3, ?4, ?5, ?6, ?7)",
rusqlite::params![
session_id,
tool_name,
input_summary,
output_summary,
duration_ms,
risk_score,
timestamp,
],
)?;
Ok(ToolLogEntry {
id: self.conn.last_insert_rowid(),
session_id: session_id.to_string(),
tool_name: tool_name.to_string(),
input_summary: input_summary.to_string(),
output_summary: output_summary.to_string(),
duration_ms,
risk_score,
timestamp: timestamp.to_string(),
})
}
pub fn query_tool_logs(
&self,
session_id: &str,
page: u64,
page_size: u64,
) -> Result<ToolLogPage> {
let page = page.max(1);
let offset = (page - 1) * page_size;
let total: u64 = self.conn.query_row(
"SELECT COUNT(*) FROM tool_log WHERE session_id = ?1",
rusqlite::params![session_id],
|row| row.get(0),
)?;
let mut stmt = self.conn.prepare(
"SELECT id, session_id, tool_name, input_summary, output_summary, duration_ms, risk_score, timestamp
FROM tool_log
WHERE session_id = ?1
ORDER BY timestamp DESC, id DESC
LIMIT ?2 OFFSET ?3",
)?;
let entries = stmt
.query_map(rusqlite::params![session_id, page_size, offset], |row| {
Ok(ToolLogEntry {
id: row.get(0)?,
session_id: row.get(1)?,
tool_name: row.get(2)?,
input_summary: row.get::<_, Option<String>>(3)?.unwrap_or_default(),
output_summary: row.get::<_, Option<String>>(4)?.unwrap_or_default(),
duration_ms: row.get::<_, Option<u64>>(5)?.unwrap_or_default(),
risk_score: row.get::<_, Option<f64>>(6)?.unwrap_or_default(),
timestamp: row.get(7)?,
})
})?
.collect::<Result<Vec<_>, _>>()?;
Ok(ToolLogPage {
entries,
page,
page_size,
total,
})
}
}
#[cfg(test)]
mod tests {
use super::*;
use chrono::{Duration as ChronoDuration, Utc};
use std::fs;
use std::env;
struct TestDir {
path: PathBuf,
}
use anyhow::Result;
use chrono::Utc;
use uuid::Uuid;
impl TestDir {
fn new(label: &str) -> Result<Self> {
let path =
std::env::temp_dir().join(format!("ecc2-{}-{}", label, uuid::Uuid::new_v4()));
fs::create_dir_all(&path)?;
Ok(Self { path })
}
fn path(&self) -> &Path {
&self.path
}
}
impl Drop for TestDir {
fn drop(&mut self) {
let _ = fs::remove_dir_all(&self.path);
}
}
fn build_session(id: &str, state: SessionState) -> Session {
let now = Utc::now();
Session {
id: id.to_string(),
task: "task".to_string(),
agent_type: "claude".to_string(),
state,
pid: None,
worktree: None,
created_at: now - ChronoDuration::minutes(1),
updated_at: now,
metrics: SessionMetrics::default(),
}
}
#[test]
fn update_state_rejects_invalid_terminal_transition() -> Result<()> {
let tempdir = TestDir::new("store-invalid-transition")?;
let db = StateStore::open(&tempdir.path().join("state.db"))?;
db.insert_session(&build_session("done", SessionState::Completed))?;
let error = db
.update_state("done", &SessionState::Running)
.expect_err("completed sessions must not transition back to running");
assert!(error
.to_string()
.contains("Invalid session state transition"));
Ok(())
}
#[test]
fn open_migrates_existing_sessions_table_with_pid_column() -> Result<()> {
let tempdir = TestDir::new("store-migration")?;
let db_path = tempdir.path().join("state.db");
let conn = Connection::open(&db_path)?;
conn.execute_batch(
"
CREATE TABLE sessions (
id TEXT PRIMARY KEY,
task TEXT NOT NULL,
agent_type TEXT NOT NULL,
state TEXT NOT NULL DEFAULT 'pending',
worktree_path TEXT,
worktree_branch TEXT,
worktree_base TEXT,
tokens_used INTEGER DEFAULT 0,
tool_calls INTEGER DEFAULT 0,
files_changed INTEGER DEFAULT 0,
duration_secs INTEGER DEFAULT 0,
cost_usd REAL DEFAULT 0.0,
created_at TEXT NOT NULL,
updated_at TEXT NOT NULL
);
",
)?;
drop(conn);
let db = StateStore::open(&db_path)?;
let mut stmt = db.conn.prepare("PRAGMA table_info(sessions)")?;
let column_names = stmt
.query_map([], |row| row.get::<_, String>(1))?
.collect::<std::result::Result<Vec<_>, _>>()?;
assert!(column_names.iter().any(|column| column == "pid"));
Ok(())
}
use super::StateStore;
use crate::session::output::{OutputStream, OUTPUT_BUFFER_LIMIT};
use crate::session::{Session, SessionMetrics, SessionState};
#[test]
fn append_output_line_keeps_latest_buffer_window() -> Result<()> {
let tempdir = TestDir::new("store-output")?;
let db = StateStore::open(&tempdir.path().join("state.db"))?;
let db_path = env::temp_dir().join(format!("ecc2-store-{}.db", Uuid::new_v4()));
let db = StateStore::open(&db_path)?;
let now = Utc::now();
db.insert_session(&Session {
@@ -552,7 +284,6 @@ mod tests {
task: "buffer output".to_string(),
agent_type: "claude".to_string(),
state: SessionState::Running,
pid: None,
worktree: None,
created_at: now,
updated_at: now,
@@ -571,6 +302,8 @@ mod tests {
let expected_last_line = format!("line-{}", OUTPUT_BUFFER_LIMIT + 4);
assert_eq!(texts.last().copied(), Some(expected_last_line.as_str()));
let _ = std::fs::remove_file(db_path);
Ok(())
}
}

4
ecc2/src/tui/app.rs
View File

@@ -32,10 +32,6 @@ pub async fn run(db: StateStore, cfg: Config) -> Result<()> {
(_, KeyCode::Char('q')) => break,
(_, KeyCode::Tab) => dashboard.next_pane(),
(KeyModifiers::SHIFT, KeyCode::BackTab) => dashboard.prev_pane(),
(_, KeyCode::Char('+')) | (_, KeyCode::Char('=')) => {
dashboard.increase_pane_size()
}
(_, KeyCode::Char('-')) => dashboard.decrease_pane_size(),
(_, KeyCode::Char('j')) | (_, KeyCode::Down) => dashboard.scroll_down(),
(_, KeyCode::Char('k')) | (_, KeyCode::Up) => dashboard.scroll_up(),
(_, KeyCode::Char('n')) => dashboard.new_session(),

1137
ecc2/src/tui/dashboard.rs
View File

File diff suppressed because it is too large Load Diff

287
ecc2/src/tui/widgets.rs
View File

@@ -1,281 +1,6 @@
use ratatui::{
prelude::*,
text::{Line, Span},
widgets::{Gauge, Paragraph, Widget},
};
pub(crate) const WARNING_THRESHOLD: f64 = 0.8;
#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord)]
pub(crate) enum BudgetState {
Unconfigured,
Normal,
Warning,
OverBudget,
}
impl BudgetState {
pub(crate) const fn is_warning(self) -> bool {
matches!(self, Self::Warning | Self::OverBudget)
}
fn badge(self) -> Option<&'static str> {
match self {
Self::Warning => Some("warning"),
Self::OverBudget => Some("over budget"),
Self::Unconfigured => Some("no budget"),
Self::Normal => None,
}
}
pub(crate) fn style(self) -> Style {
let base = Style::default().fg(match self {
Self::Unconfigured => Color::DarkGray,
Self::Normal => Color::DarkGray,
Self::Warning => Color::Yellow,
Self::OverBudget => Color::Red,
});
if self.is_warning() {
base.add_modifier(Modifier::BOLD)
} else {
base
}
}
}
#[derive(Debug, Clone, Copy)]
enum MeterFormat {
Tokens,
Currency,
}
#[derive(Debug, Clone)]
pub(crate) struct TokenMeter<'a> {
title: &'a str,
used: f64,
budget: f64,
format: MeterFormat,
}
impl<'a> TokenMeter<'a> {
pub(crate) fn tokens(title: &'a str, used: u64, budget: u64) -> Self {
Self {
title,
used: used as f64,
budget: budget as f64,
format: MeterFormat::Tokens,
}
}
pub(crate) fn currency(title: &'a str, used: f64, budget: f64) -> Self {
Self {
title,
used,
budget,
format: MeterFormat::Currency,
}
}
pub(crate) fn state(&self) -> BudgetState {
budget_state(self.used, self.budget)
}
fn ratio(&self) -> f64 {
budget_ratio(self.used, self.budget)
}
fn clamped_ratio(&self) -> f64 {
self.ratio().clamp(0.0, 1.0)
}
fn title_line(&self) -> Line<'static> {
let mut spans = vec![Span::styled(
self.title.to_string(),
Style::default()
.fg(Color::Gray)
.add_modifier(Modifier::BOLD),
)];
if let Some(badge) = self.state().badge() {
spans.push(Span::raw(" "));
spans.push(Span::styled(format!("[{badge}]"), self.state().style()));
}
Line::from(spans)
}
fn display_label(&self) -> String {
if self.budget <= 0.0 {
return match self.format {
MeterFormat::Tokens => format!("{} tok used | no budget", self.used_label()),
MeterFormat::Currency => format!("{} spent | no budget", self.used_label()),
};
}
format!(
"{} / {}{} ({}%)",
self.used_label(),
self.budget_label(),
self.unit_suffix(),
(self.ratio() * 100.0).round() as u64
)
}
fn used_label(&self) -> String {
match self.format {
MeterFormat::Tokens => format_token_count(self.used.max(0.0).round() as u64),
MeterFormat::Currency => format_currency(self.used.max(0.0)),
}
}
fn budget_label(&self) -> String {
match self.format {
MeterFormat::Tokens => format_token_count(self.budget.max(0.0).round() as u64),
MeterFormat::Currency => format_currency(self.budget.max(0.0)),
}
}
fn unit_suffix(&self) -> &'static str {
match self.format {
MeterFormat::Tokens => " tok",
MeterFormat::Currency => "",
}
}
}
impl Widget for TokenMeter<'_> {
fn render(self, area: Rect, buf: &mut Buffer) {
if area.is_empty() {
return;
}
let mut gauge_area = area;
if area.height > 1 {
let chunks = Layout::default()
.direction(Direction::Vertical)
.constraints([Constraint::Length(1), Constraint::Min(1)])
.split(area);
Paragraph::new(self.title_line()).render(chunks[0], buf);
gauge_area = chunks[1];
}
Gauge::default()
.ratio(self.clamped_ratio())
.label(self.display_label())
.gauge_style(
Style::default()
.fg(gradient_color(self.ratio()))
.add_modifier(Modifier::BOLD),
)
.style(Style::default().fg(Color::DarkGray))
.use_unicode(true)
.render(gauge_area, buf);
}
}
pub(crate) fn budget_ratio(used: f64, budget: f64) -> f64 {
if budget <= 0.0 {
0.0
} else {
used / budget
}
}
pub(crate) fn budget_state(used: f64, budget: f64) -> BudgetState {
if budget <= 0.0 {
BudgetState::Unconfigured
} else if used / budget >= 1.0 {
BudgetState::OverBudget
} else if used / budget >= WARNING_THRESHOLD {
BudgetState::Warning
} else {
BudgetState::Normal
}
}
pub(crate) fn gradient_color(ratio: f64) -> Color {
const GREEN: (u8, u8, u8) = (34, 197, 94);
const YELLOW: (u8, u8, u8) = (234, 179, 8);
const RED: (u8, u8, u8) = (239, 68, 68);
let clamped = ratio.clamp(0.0, 1.0);
if clamped <= WARNING_THRESHOLD {
interpolate_rgb(GREEN, YELLOW, clamped / WARNING_THRESHOLD)
} else {
interpolate_rgb(
YELLOW,
RED,
(clamped - WARNING_THRESHOLD) / (1.0 - WARNING_THRESHOLD),
)
}
}
pub(crate) fn format_currency(value: f64) -> String {
format!("${value:.2}")
}
pub(crate) fn format_token_count(value: u64) -> String {
let digits = value.to_string();
let mut formatted = String::with_capacity(digits.len() + digits.len() / 3);
for (index, ch) in digits.chars().rev().enumerate() {
if index != 0 && index % 3 == 0 {
formatted.push(',');
}
formatted.push(ch);
}
formatted.chars().rev().collect()
}
fn interpolate_rgb(from: (u8, u8, u8), to: (u8, u8, u8), ratio: f64) -> Color {
let ratio = ratio.clamp(0.0, 1.0);
let channel = |start: u8, end: u8| -> u8 {
(f64::from(start) + (f64::from(end) - f64::from(start)) * ratio).round() as u8
};
Color::Rgb(
channel(from.0, to.0),
channel(from.1, to.1),
channel(from.2, to.2),
)
}
#[cfg(test)]
mod tests {
use ratatui::{buffer::Buffer, layout::Rect, style::Color, widgets::Widget};
use super::{gradient_color, BudgetState, TokenMeter};
#[test]
fn warning_state_starts_at_eighty_percent() {
let meter = TokenMeter::tokens("Token Budget", 80, 100);
assert_eq!(meter.state(), BudgetState::Warning);
}
#[test]
fn gradient_runs_from_green_to_yellow_to_red() {
assert_eq!(gradient_color(0.0), Color::Rgb(34, 197, 94));
assert_eq!(gradient_color(0.8), Color::Rgb(234, 179, 8));
assert_eq!(gradient_color(1.0), Color::Rgb(239, 68, 68));
}
#[test]
fn token_meter_renders_compact_usage_label() {
let meter = TokenMeter::tokens("Token Budget", 4_000, 10_000);
let area = Rect::new(0, 0, 48, 2);
let mut buffer = Buffer::empty(area);
meter.render(area, &mut buffer);
let rendered = buffer
.content()
.chunks(area.width as usize)
.flat_map(|row| row.iter().map(|cell| cell.symbol()))
.collect::<String>();
assert!(rendered.contains("4,000 / 10,000 tok (40%)"));
}
}
// Custom TUI widgets for ECC 2.0
// TODO: Implement custom widgets:
// - TokenMeter: visual token usage bar with budget threshold
// - DiffViewer: side-by-side syntax-highlighted diff display
// - ProgressTimeline: session timeline with tool call markers
// - AgentTree: hierarchical view of parent/child agent sessions

29
ecc2/src/worktree/mod.rs
View File

@@ -1,5 +1,5 @@
use anyhow::{Context, Result};
use std::path::Path;
use std::path::PathBuf;
use std::process::Command;
use crate::config::Config;
@@ -7,27 +7,16 @@ use crate::session::WorktreeInfo;
/// Create a new git worktree for an agent session.
pub fn create_for_session(session_id: &str, cfg: &Config) -> Result<WorktreeInfo> {
let repo_root = std::env::current_dir().context("Failed to resolve repository root")?;
create_for_session_in_repo(session_id, cfg, &repo_root)
}
pub(crate) fn create_for_session_in_repo(
session_id: &str,
cfg: &Config,
repo_root: &Path,
) -> Result<WorktreeInfo> {
let branch = format!("ecc/{session_id}");
let path = cfg.worktree_root.join(session_id);
// Get current branch as base
let base = get_current_branch(repo_root)?;
let base = get_current_branch()?;
std::fs::create_dir_all(&cfg.worktree_root)
.context("Failed to create worktree root directory")?;
let output = Command::new("git")
.arg("-C")
.arg(repo_root)
.args(["worktree", "add", "-b", &branch])
.arg(&path)
.arg("HEAD")
@@ -39,11 +28,7 @@ pub(crate) fn create_for_session_in_repo(
anyhow::bail!("git worktree add failed: {stderr}");
}
tracing::info!(
"Created worktree at {} on branch {}",
path.display(),
branch
);
tracing::info!("Created worktree at {} on branch {}", path.display(), branch);
Ok(WorktreeInfo {
path,
@@ -53,10 +38,8 @@ pub(crate) fn create_for_session_in_repo(
}
/// Remove a worktree and its branch.
pub fn remove(path: &Path) -> Result<()> {
pub fn remove(path: &PathBuf) -> Result<()> {
let output = Command::new("git")
.arg("-C")
.arg(path)
.args(["worktree", "remove", "--force"])
.arg(path)
.output()
@@ -87,10 +70,8 @@ pub fn list() -> Result<Vec<String>> {
Ok(worktrees)
}
fn get_current_branch(repo_root: &Path) -> Result<String> {
fn get_current_branch() -> Result<String> {
let output = Command::new("git")
.arg("-C")
.arg(repo_root)
.args(["rev-parse", "--abbrev-ref", "HEAD"])
.output()
.context("Failed to get current branch")?;

1
hooks/README.md
View File

@@ -48,7 +48,6 @@ User request → Claude picks a tool → PreToolUse hook runs → Tool executes
| **Session summary** | `Stop` | Persists session state when transcript path is available |
| **Pattern extraction** | `Stop` | Evaluates session for extractable patterns (continuous learning) |
| **Cost tracker** | `Stop` | Emits lightweight run-cost telemetry markers |
| **Desktop notify** | `Stop` | Sends macOS desktop notification with task summary (standard+) |
| **Session end marker** | `SessionEnd` | Lifecycle marker and cleanup log |
## Customizing Hooks

14
hooks/hooks.json
View File

@@ -136,7 +136,7 @@
"hooks": [
{
"type": "command",
"command": "node -e \"const fs=require('fs');const path=require('path');const {spawnSync}=require('child_process');const raw=fs.readFileSync(0,'utf8');const rel=path.join('scripts','hooks','run-with-flags.js');const hasRunnerRoot=candidate=>{const value=typeof candidate==='string'?candidate.trim():'';return value.length>0&&fs.existsSync(path.join(path.resolve(value),rel));};const root=(()=>{const envRoot=process.env.CLAUDE_PLUGIN_ROOT||'';if(hasRunnerRoot(envRoot))return path.resolve(envRoot.trim());const home=require('os').homedir();const claudeDir=path.join(home,'.claude');if(hasRunnerRoot(claudeDir))return claudeDir;for(const candidate of [path.join(claudeDir,'plugins','everything-claude-code'),path.join(claudeDir,'plugins','everything-claude-code@everything-claude-code'),path.join(claudeDir,'plugins','marketplace','everything-claude-code')]){if(hasRunnerRoot(candidate))return candidate;}try{const cacheBase=path.join(claudeDir,'plugins','cache','everything-claude-code');for(const org of fs.readdirSync(cacheBase,{withFileTypes:true})){if(!org.isDirectory())continue;for(const version of fs.readdirSync(path.join(cacheBase,org.name),{withFileTypes:true})){if(!version.isDirectory())continue;const candidate=path.join(cacheBase,org.name,version.name);if(hasRunnerRoot(candidate))return candidate;}}}catch{}return claudeDir;})();const script=path.join(root,rel);if(fs.existsSync(script)){const result=spawnSync(process.execPath,[script,'session:start','scripts/hooks/session-start.js','minimal,standard,strict'],{input:raw,encoding:'utf8',env:process.env,cwd:process.cwd(),timeout:30000});const stdout=typeof result.stdout==='string'?result.stdout:'';if(stdout)process.stdout.write(stdout);else process.stdout.write(raw);if(result.stderr)process.stderr.write(result.stderr);if(result.error||result.status===null||result.signal){const reason=result.error?result.error.message:(result.signal?'signal '+result.signal:'missing exit status');process.stderr.write('[SessionStart] ERROR: session-start hook failed: '+reason+String.fromCharCode(10));process.exit(1);}process.exit(Number.isInteger(result.status)?result.status:0);}process.stderr.write('[SessionStart] WARNING: could not resolve ECC plugin root; skipping session-start hook'+String.fromCharCode(10));process.stdout.write(raw);\""
"command": "bash -lc 'input=$(cat); for root in \"${CLAUDE_PLUGIN_ROOT:-}\" \"$HOME/.claude/plugins/everything-claude-code\" \"$HOME/.claude/plugins/everything-claude-code@everything-claude-code\" \"$HOME/.claude/plugins/marketplace/everything-claude-code\"; do if [ -n \"$root\" ] && [ -f \"$root/scripts/hooks/run-with-flags.js\" ]; then printf \"%s\" \"$input\" | node \"$root/scripts/hooks/run-with-flags.js\" \"session:start\" \"scripts/hooks/session-start.js\" \"minimal,standard,strict\"; exit $?; fi; done; for parent in \"$HOME/.claude/plugins\" \"$HOME/.claude/plugins/marketplace\"; do if [ -d \"$parent\" ]; then candidate=$(find \"$parent\" -maxdepth 2 -type f -path \"*/scripts/hooks/run-with-flags.js\" 2>/dev/null | head -n 1); if [ -n \"$candidate\" ]; then root=$(dirname \"$(dirname \"$(dirname \"$candidate\")\")\"); printf \"%s\" \"$input\" | node \"$root/scripts/hooks/run-with-flags.js\" \"session:start\" \"scripts/hooks/session-start.js\" \"minimal,standard,strict\"; exit $?; fi; fi; done; echo \"[SessionStart] WARNING: could not resolve ECC plugin root; skipping session-start hook\" >&2; printf \"%s\" \"$input\"; exit 0'"
}
],
"description": "Load previous context and detect package manager on new session"
@@ -289,18 +289,6 @@
}
],
"description": "Track token and cost metrics per session"
},
{
"matcher": "*",
"hooks": [
{
"type": "command",
"command": "node \"${CLAUDE_PLUGIN_ROOT}/scripts/hooks/run-with-flags.js\" \"stop:desktop-notify\" \"scripts/hooks/desktop-notify.js\" \"standard,strict\"",
"async": true,
"timeout": 10
}
],
"description": "Send macOS desktop notification with task summary when Claude responds"
}
],
"SessionEnd": [

15
install.ps1
View File

@@ -34,20 +34,5 @@ while ($true) {
$scriptDir = Split-Path -Parent $scriptPath
$installerScript = Join-Path -Path (Join-Path -Path $scriptDir -ChildPath 'scripts') -ChildPath 'install-apply.js'
# Auto-install Node dependencies when running from a git clone
$nodeModules = Join-Path -Path $scriptDir -ChildPath 'node_modules'
if (-not (Test-Path -LiteralPath $nodeModules)) {
Write-Host '[ECC] Installing dependencies...'
Push-Location $scriptDir
try {
& npm install --no-audit --no-fund --loglevel=error
if ($LASTEXITCODE -ne 0) {
Write-Error "npm install failed with exit code $LASTEXITCODE"
exit $LASTEXITCODE
}
}
finally { Pop-Location }
}
& node $installerScript @args
exit $LASTEXITCODE

6
install.sh
View File

@@ -14,10 +14,4 @@ while [ -L "$SCRIPT_PATH" ]; do
done
SCRIPT_DIR="$(cd "$(dirname "$SCRIPT_PATH")" && pwd)"
# Auto-install Node dependencies when running from a git clone
if [ ! -d "$SCRIPT_DIR/node_modules" ]; then
echo "[ECC] Installing dependencies..."
(cd "$SCRIPT_DIR" && npm install --no-audit --no-fund --loglevel=error)
fi
exec node "$SCRIPT_DIR/scripts/install-apply.js" "$@"

4
manifests/install-modules.json
View File

@@ -63,8 +63,7 @@
"description": "Runtime hook configs and hook script helpers.",
"paths": [
"hooks",
"scripts/hooks",
"scripts/lib"
"scripts/hooks"
],
"targets": [
"claude",
@@ -125,7 +124,6 @@
"skills/kotlin-ktor-patterns",
"skills/kotlin-patterns",
"skills/kotlin-testing",
"skills/laravel-plugin-discovery",
"skills/laravel-patterns",
"skills/laravel-tdd",
"skills/laravel-verification",

5
mcp-configs/mcp-servers.json
View File

@@ -133,11 +133,6 @@
"args": ["-y", "token-optimizer-mcp"],
"description": "Token optimization for 95%+ context reduction via content deduplication and compression"
},
"laraplugins": {
"type": "http",
"url": "https://laraplugins.io/mcp/plugins",
"description": "Laravel plugin discovery — search packages by keyword, health score, Laravel/PHP version compatibility. Use with laravel-plugin-discovery skill."
},
"confluence": {
"command": "npx",
"args": ["-y", "confluence-mcp-server"],

13
package-lock.json generated
View File

@@ -11,7 +11,6 @@
"license": "MIT",
"dependencies": {
"@iarna/toml": "^2.2.5",
"ajv": "^8.18.0",
"sql.js": "^1.14.1"
},
"bin": {
@@ -20,6 +19,7 @@
},
"devDependencies": {
"@eslint/js": "^9.39.2",
"ajv": "^8.18.0",
"c8": "^10.1.2",
"eslint": "^9.39.2",
"globals": "^17.1.0",
@@ -449,6 +449,7 @@
"version": "8.18.0",
"resolved": "https://registry.npmjs.org/ajv/-/ajv-8.18.0.tgz",
"integrity": "sha512-PlXPeEWMXMZ7sPYOHqmDyCJzcfNrUr3fGNKtezX14ykXOEIvyK81d+qydx89KY5O71FKMPaQ2vBfBFI5NHR63A==",
"dev": true,
"license": "MIT",
"dependencies": {
"fast-deep-equal": "^3.1.3",
@@ -1042,6 +1043,7 @@
"version": "3.1.3",
"resolved": "https://registry.npmjs.org/fast-deep-equal/-/fast-deep-equal-3.1.3.tgz",
"integrity": "sha512-f3qQ9oQy9j2AhBe/H9VC91wLmKBCCU/gDOnKNAYG5hswO7BLKj09Hc5HYNz9cGI++xlpDCIgDaitVs03ATR84Q==",
"dev": true,
"license": "MIT"
},
"node_modules/fast-json-stable-stringify": {
@@ -1062,6 +1064,7 @@
"version": "3.1.0",
"resolved": "https://registry.npmjs.org/fast-uri/-/fast-uri-3.1.0.tgz",
"integrity": "sha512-iPeeDKJSWf4IEOasVVrknXpaBV0IApz/gp7S2bb7Z4Lljbl2MGJRqInZiUrQwV16cpzw/D3S5j5Julj/gT52AA==",
"dev": true,
"funding": [
{
"type": "github",
@@ -1488,6 +1491,7 @@
"version": "1.0.0",
"resolved": "https://registry.npmjs.org/json-schema-traverse/-/json-schema-traverse-1.0.0.tgz",
"integrity": "sha512-NM8/P9n3XjXhIZn1lLhkFaACTOURQXjWhV4BA/RnOv8xvgqtqpAX9IO4mRQxSx1Rlo4tqzeqb0sOlruaOy3dug==",
"dev": true,
"license": "MIT"
},
"node_modules/json-stable-stringify-without-jsonify": {
@@ -2453,9 +2457,9 @@
}
},
"node_modules/picomatch": {
"version": "4.0.4",
"resolved": "https://registry.npmjs.org/picomatch/-/picomatch-4.0.4.tgz",
"integrity": "sha512-QP88BAKvMam/3NxH6vj2o21R6MjxZUAd6nlwAS/pnGvN9IVLocLHxGYIzFhg6fUQ+5th6P4dv4eW9jX3DSIj7A==",
"version": "4.0.3",
"resolved": "https://registry.npmjs.org/picomatch/-/picomatch-4.0.3.tgz",
"integrity": "sha512-5gTmgEY/sqK6gFXLIsQNH19lWb4ebPDLA4SdLP7dsWkIXHWlG66oPuVvXSGFPppYZz8ZDZq0dYYrbHfBCVUb1Q==",
"dev": true,
"license": "MIT",
"engines": {
@@ -2508,6 +2512,7 @@
"version": "2.0.2",
"resolved": "https://registry.npmjs.org/require-from-string/-/require-from-string-2.0.2.tgz",
"integrity": "sha512-Xf0nWe6RseziFMu+Ap9biiUbmplq6S9/p+7w7YXP/JBHhrUDDUhwa+vANyubuqfZWTveU//DYVGsDG7RKL/vEw==",
"dev": true,
"license": "MIT",
"engines": {
"node": ">=0.10.0"

8
package.json
View File

@@ -89,9 +89,6 @@
"AGENTS.md",
".claude-plugin/plugin.json",
".claude-plugin/README.md",
".codex-plugin/plugin.json",
".codex-plugin/README.md",
".mcp.json",
"install.sh",
"install.ps1",
"llms.txt"
@@ -113,11 +110,11 @@
},
"dependencies": {
"@iarna/toml": "^2.2.5",
"ajv": "^8.18.0",
"sql.js": "^1.14.1"
},
"devDependencies": {
"@eslint/js": "^9.39.2",
"ajv": "^8.18.0",
"c8": "^10.1.2",
"eslint": "^9.39.2",
"globals": "^17.1.0",
@@ -125,6 +122,5 @@
},
"engines": {
"node": ">=18"
},
"packageManager": "yarn@4.9.2+sha512.1fc009bc09d13cfd0e19efa44cbfc2b9cf6ca61482725eb35bbc5e257e093ebf4130db6dfe15d604ff4b79efd8e1e8e99b25fa7d0a6197c9f9826358d4d65c3c"
}
}

172
research/ecc2-codebase-analysis.md
View File

@@ -1,172 +0,0 @@
# ECC2 Codebase Research Report
**Date:** 2026-03-26
**Subject:** `ecc-tui` v0.1.0 — Agentic IDE Control Plane
**Total Lines:** 4,417 across 15 `.rs` files
## 1. Architecture Overview
ECC2 is a Rust TUI application that orchestrates AI coding agent sessions. It uses:
- **ratatui 0.29** + **crossterm 0.28** for terminal UI
- **rusqlite 0.32** (bundled) for local state persistence
- **tokio 1** (full) for async runtime
- **clap 4** (derive) for CLI
### Module Breakdown
| Module | Lines | Purpose |
|--------|------:|---------|
| `session/` | 1,974 | Session lifecycle, persistence, runtime, output |
| `tui/` | 1,613 | Dashboard, app loop, custom widgets |
| `observability/` | 409 | Tool call risk scoring and logging |
| `config/` | 144 | Configuration (TOML file) |
| `main.rs` | 142 | CLI entry point |
| `worktree/` | 99 | Git worktree management |
| `comms/` | 36 | Inter-agent messaging (send only) |
### Key Architectural Patterns
- **DbWriter thread** in `session/runtime.rs` — dedicated OS thread for SQLite writes from async context via `mpsc::unbounded_channel` with oneshot acknowledgements. Clean solution to the "SQLite from async" problem.
- **Session state machine** with enforced transitions: `Pending → {Running, Failed, Stopped}`, `Running → {Idle, Completed, Failed, Stopped}`, etc.
- **Ring buffer** for session output — `OUTPUT_BUFFER_LIMIT = 1000` lines per session with automatic eviction.
- **Risk scoring** on tool calls — 4-axis analysis (base tool risk, file sensitivity, blast radius, irreversibility) producing composite 0.0–1.0 scores with suggested actions (Allow/Review/RequireConfirmation/Block).
## 2. Code Quality Metrics
| Metric | Value |
|--------|-------|
| Total lines | 4,417 |
| Test functions | 29 |
| `unwrap()` calls | 3 |
| `unsafe` blocks | 0 |
| TODO/FIXME comments | 0 |
| Max file size | 1,273 lines (`dashboard.rs`) |
**Assessment:** The codebase is clean. Only 3 `unwrap()` calls (2 in tests, 1 in config `default()`), zero `unsafe`, and all modules use proper `anyhow::Result` error propagation. The `dashboard.rs` file at 1,273 lines exceeds the repo's 800-line max-file guideline, but it is still manageable at the current scope.
## 3. Identified Gaps
### 3.1 Comms Module — Send Without Receive
`comms/mod.rs` (36 lines) has `send()` but no `receive()`, `poll()`, `inbox()`, or `subscribe()`. The `messages` table exists in SQLite, but nothing reads from it. The inter-agent messaging story is half-built.
**Impact:** Agents cannot coordinate. The `TaskHandoff`, `Query`, `Response`, and `Conflict` message types are defined but unusable.
### 3.2 New Session Dialog — Stub
`dashboard.rs:495` — `new_session()` logs `"New session dialog requested"` but does nothing. Users must use the CLI (`ecc start --task "..."`) to create sessions; the TUI dashboard cannot.
### 3.3 Single Agent Support
`session/manager.rs` — `agent_program()` only supports `"claude"`. The CLI accepts `--agent` but anything other than `"claude"` fails. No codex, opencode, or custom agent support.
### 3.4 Config — File-Only
`Config::load()` reads `~/.claude/ecc2.toml` only. The implementation lacks environment variable overrides (e.g., `ECC_DB_PATH`, `ECC_WORKTREE_ROOT`) and CLI flags for configuration.
### 3.5 Legacy Dependency Candidate: `git2`
`git2 = "0.20"` is still declared in `Cargo.toml`, but the `worktree` module shells out to the `git` CLI instead. That makes `git2` a strong removal candidate rather than an already-completed cleanup.
### 3.6 No Metrics Aggregation
`SessionMetrics` tracks tokens, cost, duration, tool_calls, files_changed per session. But there's no aggregate view: total cost across sessions, average duration, top tools by usage, etc. The Metrics pane in the dashboard shows per-session detail only.
### 3.7 Daemon — No Health Reporting
`session/daemon.rs` runs an infinite loop checking session timeouts. No health endpoint, no log rotation, no PID file, no signal handling for graceful shutdown. `Ctrl+C` during daemon mode kills the process uncleanly.
## 4. Test Coverage Analysis
34 test functions across 10 source modules:
| Module | Tests | Coverage Focus |
|--------|------:|----------------|
| `main.rs` | 1 | CLI parsing |
| `config/mod.rs` | 5 | Defaults, deserialization, legacy fallback |
| `observability/mod.rs` | 5 | Risk scoring, persistence, pagination |
| `session/daemon.rs` | 2 | Crash recovery / liveness handling |
| `session/manager.rs` | 4 | Session lifecycle, resume, stop, latest status |
| `session/output.rs` | 2 | Ring buffer, broadcast |
| `session/runtime.rs` | 1 | Output capture persistence/events |
| `session/store.rs` | 3 | Buffer window, migration, state transitions |
| `tui/dashboard.rs` | 8 | Rendering, selection, pane navigation, scrolling |
| `tui/widgets.rs` | 3 | Token meter rendering and thresholds |
**Direct coverage gaps:**
- `comms/mod.rs` — 0 tests
- `worktree/mod.rs` — 0 tests
The core I/O-heavy paths are no longer completely untested: `manager.rs`, `runtime.rs`, and `daemon.rs` each have targeted tests. The remaining gap is breadth rather than total absence, especially around `comms/`, `worktree/`, and more adversarial process/worktree failure cases.
## 5. Security Observations
- **No secrets in code.** Config reads from TOML file, no hardcoded credentials.
- **Process spawning** uses `tokio::process::Command` with explicit `Stdio::piped()` — no shell injection vectors.
- **Risk scoring** is a strong feature — catches `rm -rf`, `git push --force origin main`, file access to `.env`/secrets.
- **No input sanitization on session task strings.** The task string is passed directly to `claude --print`. If the task contains shell metacharacters, it could be exploited depending on how `Command` handles argument quoting. Currently safe (arguments are not shell-interpreted), but worth auditing.
## 6. Dependency Health
| Crate | Version | Latest | Notes |
|-------|---------|--------|-------|
| ratatui | 0.29 | **0.30.0** | Update available |
| crossterm | 0.28 | **0.29.0** | Update available |
| rusqlite | 0.32 | **0.39.0** | Update available |
| tokio | 1 | **1.50.0** | Update available |
| serde | 1 | **1.0.228** | Update available |
| clap | 4 | **4.6.0** | Update available |
| chrono | 0.4 | **0.4.44** | Update available |
| uuid | 1 | **1.22.0** | Update available |
`git2` is still present in `Cargo.toml` even though the `worktree` module shells out to the `git` CLI. Several other dependencies are outdated; either remove `git2` or start using it before the next release.
## 7. Recommendations (Prioritized)
### P0 — Quick Wins
1. **Add environment variable support to `Config::load()`** — `ECC_DB_PATH`, `ECC_WORKTREE_ROOT`, `ECC_DEFAULT_AGENT`. Standard practice for CLI tools.
### P1 — Feature Completions
2. **Implement `comms::receive()` / `comms::poll()`** — read unread messages from the `messages` table, optionally with a `broadcast` channel for real-time delivery. Wire it into the dashboard.
3. **Build the new-session dialog in the TUI** — modal form with task input, agent selector, worktree toggle. Should call `session::manager::create_session()`.
4. **Add aggregate metrics** — total cost, average session duration, tool call frequency, cost per session. Show in the Metrics pane.
### P2 — Robustness
5. **Expand integration coverage for `manager.rs`, `runtime.rs`, and `daemon.rs`** — the repo now has baseline tests here, but it still needs failure-path coverage around process crashes, timeouts, and cleanup edge cases.
6. **Add first-party tests for `worktree/mod.rs` and `comms/mod.rs`** — these are still uncovered and back important orchestration features.
7. **Add daemon health reporting** — PID file, structured logging, graceful shutdown via signal handler.
8. **Task string security audit** — The session task uses `claude --print` via `tokio::process::Command`. Verify arguments are never shell-interpreted. Checklist: confirm `Command` arg usage, threat-model metacharacter injection, input validation/escaping strategy, logging of raw inputs, and automated tests. Re-audit if invocation code changes.
9. **Break up `dashboard.rs`** — extract SessionsPane, OutputPane, MetricsPane, LogPane into separate files under `tui/panes/`.
### P3 — Extensibility
10. **Multi-agent support** — make `agent_program()` pluggable. Add `codex`, `opencode`, `custom` agent types.
11. **Config validation** — validate risk thresholds sum correctly, budget values are positive, paths exist.
## 8. Comparison with Ratatui 0.29 Best Practices
The codebase follows ratatui conventions well:
- Uses `TableState` for stateful selection (correct pattern)
- Custom `Widget` trait implementation for `TokenMeter` (idiomatic)
- `tick()` method for periodic state sync (standard)
- `broadcast::channel` for real-time output events (appropriate)
**Minor deviations:**
- The `Dashboard` struct directly holds `StateStore` (SQLite connection). Ratatui best practice is to keep the state store behind an `Arc<Mutex<>>` to allow background updates. Currently the TUI owns the DB exclusively, which blocks adding a background metrics refresh task.
- No `Clear` widget usage when rendering the help overlay — could cause rendering artifacts on some terminals.
## 9. Risk Assessment
| Risk | Likelihood | Impact | Mitigation |
|------|-----------|--------|------------|
| Dashboard file exceeds 1500 lines (projected) | High | Medium | At 1,273 lines currently (Section 2); extract panes into modules before it grows further |
| SQLite lock contention | Low | High | DbWriter pattern already handles this |
| No agent diversity | Medium | Medium | Pluggable agent support |
| Task-string handling assumptions drift over time | Medium | Medium | Keep `Command` argument handling shell-free, document the threat model, and add regression tests for metacharacter-heavy task input |
---
**Bottom line:** ECC2 is a well-structured Rust project with clean error handling, good separation of concerns, and strong security features (risk scoring). The main gaps are incomplete features (comms, new-session dialog, single agent) rather than architectural problems. The codebase is ready for feature work on top of the solid foundation.

124
rules/common/code-review.md
View File

@@ -1,124 +0,0 @@
# Code Review Standards
## Purpose
Code review ensures quality, security, and maintainability before code is merged. This rule defines when and how to conduct code reviews.
## When to Review
**MANDATORY review triggers:**
- After writing or modifying code
- Before any commit to shared branches
- When security-sensitive code is changed (auth, payments, user data)
- When architectural changes are made
- Before merging pull requests
**Pre-Review Requirements:**
Before requesting review, ensure:
- All automated checks (CI/CD) are passing
- Merge conflicts are resolved
- Branch is up to date with target branch
## Review Checklist
Before marking code complete:
- [ ] Code is readable and well-named
- [ ] Functions are focused (<50 lines)
- [ ] Files are cohesive (<800 lines)
- [ ] No deep nesting (>4 levels)
- [ ] Errors are handled explicitly
- [ ] No hardcoded secrets or credentials
- [ ] No console.log or debug statements
- [ ] Tests exist for new functionality
- [ ] Test coverage meets 80% minimum
## Security Review Triggers
**STOP and use security-reviewer agent when:**
- Authentication or authorization code
- User input handling
- Database queries
- File system operations
- External API calls
- Cryptographic operations
- Payment or financial code
## Review Severity Levels
| Level | Meaning | Action |
|-------|---------|--------|
| CRITICAL | Security vulnerability or data loss risk | **BLOCK** - Must fix before merge |
| HIGH | Bug or significant quality issue | **WARN** - Should fix before merge |
| MEDIUM | Maintainability concern | **INFO** - Consider fixing |
| LOW | Style or minor suggestion | **NOTE** - Optional |
## Agent Usage
Use these agents for code review:
| Agent | Purpose |
|-------|---------|
| **code-reviewer** | General code quality, patterns, best practices |
| **security-reviewer** | Security vulnerabilities, OWASP Top 10 |
| **typescript-reviewer** | TypeScript/JavaScript specific issues |
| **python-reviewer** | Python specific issues |
| **go-reviewer** | Go specific issues |
| **rust-reviewer** | Rust specific issues |
## Review Workflow
```
1. Run git diff to understand changes
2. Check security checklist first
3. Review code quality checklist
4. Run relevant tests
5. Verify coverage >= 80%
6. Use appropriate agent for detailed review
```
## Common Issues to Catch
### Security
- Hardcoded credentials (API keys, passwords, tokens)
- SQL injection (string concatenation in queries)
- XSS vulnerabilities (unescaped user input)
- Path traversal (unsanitized file paths)
- CSRF protection missing
- Authentication bypasses
### Code Quality
- Large functions (>50 lines) - split into smaller
- Large files (>800 lines) - extract modules
- Deep nesting (>4 levels) - use early returns
- Missing error handling - handle explicitly
- Mutation patterns - prefer immutable operations
- Missing tests - add test coverage
### Performance
- N+1 queries - use JOINs or batching
- Missing pagination - add LIMIT to queries
- Unbounded queries - add constraints
- Missing caching - cache expensive operations
## Approval Criteria
- **Approve**: No CRITICAL or HIGH issues
- **Warning**: Only HIGH issues (merge with caution)
- **Block**: CRITICAL issues found
## Integration with Other Rules
This rule works with:
- [testing.md](testing.md) - Test coverage requirements
- [security.md](security.md) - Security checklist
- [git-workflow.md](git-workflow.md) - Commit standards
- [agents.md](agents.md) - Agent delegation

6
rules/common/development-workflow.md
View File

@@ -36,9 +36,3 @@ The Feature Implementation Workflow describes the development pipeline: research
- Detailed commit messages
- Follow conventional commits format
- See [git-workflow.md](./git-workflow.md) for commit message format and PR process
5. **Pre-Review Checks**
- Verify all automated checks (CI/CD) are passing
- Resolve any merge conflicts
- Ensure branch is up to date with target branch
- Only request review after these checks pass

108
rules/zh/README.md
View File

@@ -1,108 +0,0 @@
# 规则
## 结构
规则按**通用**层和**语言特定**目录组织：
```
rules/
├── common/ # 语言无关的原则（始终安装）
│ ├── coding-style.md
│ ├── git-workflow.md
│ ├── testing.md
│ ├── performance.md
│ ├── patterns.md
│ ├── hooks.md
│ ├── agents.md
│ ├── security.md
│ ├── code-review.md
│ └── development-workflow.md
├── zh/ # 中文翻译版本
│ ├── coding-style.md
│ ├── git-workflow.md
│ ├── testing.md
│ ├── performance.md
│ ├── patterns.md
│ ├── hooks.md
│ ├── agents.md
│ ├── security.md
│ ├── code-review.md
│ └── development-workflow.md
├── typescript/ # TypeScript/JavaScript 特定
├── python/ # Python 特定
├── golang/ # Go 特定
├── swift/ # Swift 特定
└── php/ # PHP 特定
```
- **common/** 包含通用原则 — 无语言特定的代码示例。
- **zh/** 包含 common 目录的中文翻译版本。
- **语言目录** 扩展通用规则，包含框架特定的模式、工具和代码示例。每个文件引用其对应的通用版本。
## 安装
### 选项 1：安装脚本（推荐）
```bash
# 安装通用 + 一个或多个语言特定的规则集
./install.sh typescript
./install.sh python
./install.sh golang
./install.sh swift
./install.sh php
# 同时安装多种语言
./install.sh typescript python
```
### 选项 2：手动安装
> **重要提示：** 复制整个目录 — 不要使用 `/*` 展开。
> 通用和语言特定目录包含同名文件。
> 将它们展开到一个目录会导致语言特定文件覆盖通用规则，
> 并破坏语言特定文件使用的 `../common/` 相对引用。
```bash
# 创建目标目录
mkdir -p ~/.claude/rules
# 安装通用规则（所有项目必需）
cp -r rules/common ~/.claude/rules/common
# 安装中文翻译版本（可选）
cp -r rules/zh ~/.claude/rules/zh
# 根据项目技术栈安装语言特定规则
cp -r rules/typescript ~/.claude/rules/typescript
cp -r rules/python ~/.claude/rules/python
cp -r rules/golang ~/.claude/rules/golang
cp -r rules/swift ~/.claude/rules/swift
cp -r rules/php ~/.claude/rules/php
```
## 规则 vs 技能
- **规则** 定义广泛适用的标准、约定和检查清单（如"80% 测试覆盖率"、"禁止硬编码密钥"）。
- **技能**（`skills/` 目录）为特定任务提供深入、可操作的参考材料（如 `python-patterns`、`golang-testing`）。
语言特定的规则文件在适当的地方引用相关技能。规则告诉你*做什么*；技能告诉你*怎么做*。
## 规则优先级
当语言特定规则与通用规则冲突时，**语言特定规则优先**（特定覆盖通用）。这遵循标准的分层配置模式（类似于 CSS 特异性或 `.gitignore` 优先级）。
- `rules/common/` 定义适用于所有项目的通用默认值。
- `rules/golang/`、`rules/python/`、`rules/swift/`、`rules/php/`、`rules/typescript/` 等在语言习惯不同时覆盖这些默认值。
- `rules/zh/` 是通用规则的中文翻译，与英文版本内容一致。
### 示例
`common/coding-style.md` 推荐不可变性作为默认原则。语言特定的 `golang/coding-style.md` 可以覆盖这一点：
> 惯用的 Go 使用指针接收器进行结构体变更 — 参见 [common/coding-style.md](../common/coding-style.md) 了解通用原则，但这里首选符合 Go 习惯的变更方式。
### 带覆盖说明的通用规则
`rules/common/` 中可能被语言特定文件覆盖的规则会被标记：
> **语言说明**：此规则可能会被语言特定规则覆盖；对于某些语言，该模式可能并不符合惯用写法。

50
rules/zh/agents.md
View File

@@ -1,50 +0,0 @@
# 代理编排
## 可用代理
位于 `~/.claude/agents/`：
| 代理 | 用途 | 何时使用 |
|-------|---------|------------|
| planner | 实现规划 | 复杂功能、重构 |
| architect | 系统设计 | 架构决策 |
| tdd-guide | 测试驱动开发 | 新功能、bug 修复 |
| code-reviewer | 代码审查 | 编写代码后 |
| security-reviewer | 安全分析 | 提交前 |
| build-error-resolver | 修复构建错误 | 构建失败时 |
| e2e-runner | E2E 测试 | 关键用户流程 |
| refactor-cleaner | 死代码清理 | 代码维护 |
| doc-updater | 文档 | 更新文档 |
| rust-reviewer | Rust 代码审查 | Rust 项目 |
## 立即使用代理
无需用户提示：
1. 复杂功能请求 - 使用 **planner** 代理
2. 刚编写/修改的代码 - 使用 **code-reviewer** 代理
3. Bug 修复或新功能 - 使用 **tdd-guide** 代理
4. 架构决策 - 使用 **architect** 代理
## 并行任务执行
对独立操作始终使用并行 Task 执行：
```markdown
# 好：并行执行
同时启动 3 个代理：
1. 代理 1：认证模块安全分析
2. 代理 2：缓存系统性能审查
3. 代理 3：工具类型检查
# 坏：不必要的顺序
先代理 1，然后代理 2，然后代理 3
```
## 多视角分析
对于复杂问题，使用分角色子代理：
- 事实审查者
- 高级工程师
- 安全专家
- 一致性审查者
- 冗余检查者

124
rules/zh/code-review.md
View File

@@ -1,124 +0,0 @@
# 代码审查标准
## 目的
代码审查确保代码合并前的质量、安全性和可维护性。此规则定义何时以及如何进行代码审查。
## 何时审查
**强制审查触发条件：**
- 编写或修改代码后
- 提交到共享分支之前
- 更改安全敏感代码时（认证、支付、用户数据）
- 进行架构更改时
- 合并 pull request 之前
**审查前要求：**
在请求审查之前，确保：
- 所有自动化检查（CI/CD）已通过
- 合并冲突已解决
- 分支已与目标分支同步
## 审查检查清单
在标记代码完成之前：
- [ ] 代码可读且命名良好
- [ ] 函数聚焦（<50 行）
- [ ] 文件内聚（<800 行）
- [ ] 无深层嵌套（>4 层）
- [ ] 错误显式处理
- [ ] 无硬编码密钥或凭据
- [ ] 无 console.log 或调试语句
- [ ] 新功能有测试
- [ ] 测试覆盖率满足 80% 最低要求
## 安全审查触发条件
**停止并使用 security-reviewer 代理当：**
- 认证或授权代码
- 用户输入处理
- 数据库查询
- 文件系统操作
- 外部 API 调用
- 加密操作
- 支付或金融代码
## 审查严重级别
| 级别 | 含义 | 行动 |
|-------|---------|--------|
| CRITICAL（关键） | 安全漏洞或数据丢失风险 | **阻止** - 合并前必须修复 |
| HIGH（高） | Bug 或重大质量问题 | **警告** - 合并前应修复 |
| MEDIUM（中） | 可维护性问题 | **信息** - 考虑修复 |
| LOW（低） | 风格或次要建议 | **注意** - 可选 |
## 代理使用
使用这些代理进行代码审查：
| 代理 | 用途 |
|-------|--------|
| **code-reviewer** | 通用代码质量、模式、最佳实践 |
| **security-reviewer** | 安全漏洞、OWASP Top 10 |
| **typescript-reviewer** | TypeScript/JavaScript 特定问题 |
| **python-reviewer** | Python 特定问题 |
| **go-reviewer** | Go 特定问题 |
| **rust-reviewer** | Rust 特定问题 |
## 审查工作流
```
1. 运行 git diff 了解更改
2. 先检查安全检查清单
3. 审查代码质量检查清单
4. 运行相关测试
5. 验证覆盖率 >= 80%
6. 使用适当的代理进行详细审查
```
## 常见问题捕获
### 安全
- 硬编码凭据（API 密钥、密码、令牌）
- SQL 注入（查询中的字符串拼接）
- XSS 漏洞（未转义的用户输入）
- 路径遍历（未净化的文件路径）
- CSRF 保护缺失
- 认证绕过
### 代码质量
- 大函数（>50 行）- 拆分为更小的
- 大文件（>800 行）- 提取模块
- 深层嵌套（>4 层）- 使用提前返回
- 缺少错误处理 - 显式处理
- 变更模式 - 优先使用不可变操作
- 缺少测试 - 添加测试覆盖
### 性能
- N+1 查询 - 使用 JOIN 或批处理
- 缺少分页 - 给查询添加 LIMIT
- 无界查询 - 添加约束
- 缺少缓存 - 缓存昂贵操作
## 批准标准
- **批准**：无关键或高优先级问题
- **警告**：仅有高优先级问题（谨慎合并）
- **阻止**：发现关键问题
## 与其他规则的集成
此规则与以下规则配合：
- [testing.md](testing.md) - 测试覆盖率要求
- [security.md](security.md) - 安全检查清单
- [git-workflow.md](git-workflow.md) - 提交标准
- [agents.md](agents.md) - 代理委托

48
rules/zh/coding-style.md
View File

@@ -1,48 +0,0 @@
# 编码风格
## 不可变性（关键）
始终创建新对象，永远不要修改现有对象：
```
// 伪代码
错误: modify(original, field, value) → 就地修改 original
正确: update(original, field, value) → 返回带有更改的新副本
```
原理：不可变数据防止隐藏的副作用，使调试更容易，并启用安全的并发。
## 文件组织
多个小文件 > 少量大文件：
- 高内聚，低耦合
- 典型 200-400 行，最多 800 行
- 从大模块中提取工具函数
- 按功能/领域组织，而非按类型
## 错误处理
始终全面处理错误：
- 在每一层显式处理错误
- 在面向 UI 的代码中提供用户友好的错误消息
- 在服务器端记录详细的错误上下文
- 永远不要静默吞掉错误
## 输入验证
始终在系统边界验证：
- 处理前验证所有用户输入
- 在可用的情况下使用基于模式的验证
- 快速失败并给出清晰的错误消息
- 永远不要信任外部数据（API 响应、用户输入、文件内容）
## 代码质量检查清单
在标记工作完成前：
- [ ] 代码可读且命名良好
- [ ] 函数很小（<50 行）
- [ ] 文件聚焦（<800 行）
- [ ] 没有深层嵌套（>4 层）
- [ ] 正确的错误处理
- [ ] 没有硬编码值（使用常量或配置）
- [ ] 没有变更（使用不可变模式）

44
rules/zh/development-workflow.md
View File

@@ -1,44 +0,0 @@
# 开发工作流
> 此文件扩展 [common/git-workflow.md](./git-workflow.md)，包含 git 操作之前的完整功能开发流程。
功能实现工作流描述了开发管道：研究、规划、TDD、代码审查，然后提交到 git。
## 功能实现工作流
0. **研究与重用** _(任何新实现前必需)_
- **GitHub 代码搜索优先：** 在编写任何新代码之前，运行 `gh search repos` 和 `gh search code` 查找现有实现、模板和模式。
- **库文档其次：** 使用 Context7 或主要供应商文档确认 API 行为、包使用和版本特定细节。
- **仅当前两者不足时使用 Exa：** 在 GitHub 搜索和主要文档之后，使用 Exa 进行更广泛的网络研究或发现。
- **检查包注册表：** 在编写工具代码之前搜索 npm、PyPI、crates.io 和其他注册表。首选久经考验的库而非手工编写的解决方案。
- **搜索可适配的实现：** 寻找解决问题 80%+ 且可以分支、移植或包装的开源项目。
- 当满足需求时，优先采用或移植经验证的方法而非从头编写新代码。
1. **先规划**
- 使用 **planner** 代理创建实现计划
- 编码前生成规划文档：PRD、架构、系统设计、技术文档、任务列表
- 识别依赖和风险
- 分解为阶段
2. **TDD 方法**
- 使用 **tdd-guide** 代理
- 先写测试（RED）
- 实现以通过测试（GREEN）
- 重构（IMPROVE）
- 验证 80%+ 覆盖率
3. **代码审查**
- 编写代码后立即使用 **code-reviewer** 代理
- 解决关键和高优先级问题
- 尽可能修复中优先级问题
4. **提交与推送**
- 详细的提交消息
- 遵循约定式提交格式
- 参见 [git-workflow.md](./git-workflow.md) 了解提交消息格式和 PR 流程
5. **审查前检查**
- 验证所有自动化检查（CI/CD）已通过
- 解决任何合并冲突
- 确保分支已与目标分支同步
- 仅在这些检查通过后请求审查

24
rules/zh/git-workflow.md
View File

@@ -1,24 +0,0 @@
# Git 工作流
## 提交消息格式
```
<类型>: <描述>
<可选正文>
```
类型：feat, fix, refactor, docs, test, chore, perf, ci
注意：通过 ~/.claude/settings.json 全局禁用归属。
## Pull Request 工作流
创建 PR 时：
1. 分析完整提交历史（不仅是最新提交）
2. 使用 `git diff [base-branch]...HEAD` 查看所有更改
3. 起草全面的 PR 摘要
4. 包含带有 TODO 的测试计划
5. 如果是新分支，使用 `-u` 标志推送
> 对于 git 操作之前的完整开发流程（规划、TDD、代码审查），
> 参见 [development-workflow.md](./development-workflow.md)。

30
rules/zh/hooks.md
View File

@@ -1,30 +0,0 @@
# 钩子系统
## 钩子类型
- **PreToolUse**：工具执行前（验证、参数修改）
- **PostToolUse**：工具执行后（自动格式化、检查）
- **Stop**：会话结束时（最终验证）
## 自动接受权限
谨慎使用：
- 为可信、定义明确的计划启用
- 探索性工作时禁用
- 永远不要使用 dangerously-skip-permissions 标志
- 改为在 `~/.claude.json` 中配置 `allowedTools`
## TodoWrite 最佳实践
使用 TodoWrite 工具：
- 跟踪多步骤任务的进度
- 验证对指令的理解
- 启用实时引导
- 显示细粒度的实现步骤
待办列表揭示：
- 顺序错误的步骤
- 缺失的项目
- 多余的不必要项目
- 错误的粒度
- 误解的需求

31
rules/zh/patterns.md
View File

@@ -1,31 +0,0 @@
# 常用模式
## 骨架项目
实现新功能时：
1. 搜索久经考验的骨架项目
2. 使用并行代理评估选项：
- 安全性评估
- 可扩展性分析
- 相关性评分
- 实现规划
3. 克隆最佳匹配作为基础
4. 在经验证的结构内迭代
## 设计模式
### 仓储模式
将数据访问封装在一致的接口后面：
- 定义标准操作：findAll、findById、create、update、delete
- 具体实现处理存储细节（数据库、API、文件等）
- 业务逻辑依赖抽象接口，而非存储机制
- 便于轻松切换数据源，并简化使用模拟的测试
### API 响应格式
对所有 API 响应使用一致的信封：
- 包含成功/状态指示器
- 包含数据负载（错误时可为空）
- 包含错误消息字段（成功时可为空）
- 包含分页响应的元数据（total、page、limit）

55
rules/zh/performance.md
View File

@@ -1,55 +0,0 @@
# 性能优化
## 模型选择策略
**Haiku 4.5**（Sonnet 90% 的能力，3 倍成本节省）：
- 频繁调用的轻量级代理
- 结对编程和代码生成
- 多代理系统中的工作者代理
**Sonnet 4.6**（最佳编码模型）：
- 主要开发工作
- 编排多代理工作流
- 复杂编码任务
**Opus 4.5**（最深度推理）：
- 复杂架构决策
- 最大推理需求
- 研究和分析任务
## 上下文窗口管理
避免在上下文窗口的最后 20% 进行以下操作：
- 大规模重构
- 跨多个文件的功能实现
- 调试复杂交互
上下文敏感度较低的任务：
- 单文件编辑
- 独立工具创建
- 文档更新
- 简单 bug 修复
## 扩展思考 + 规划模式
扩展思考默认启用，为内部推理保留最多 31,999 个 token。
通过以下方式控制扩展思考：
- **切换**：Option+T（macOS）/ Alt+T（Windows/Linux）
- **配置**：在 `~/.claude/settings.json` 中设置 `alwaysThinkingEnabled`
- **预算上限**：`export MAX_THINKING_TOKENS=10000`
- **详细模式**：Ctrl+O 查看思考输出
对于需要深度推理的复杂任务：
1. 确保扩展思考已启用（默认开启）
2. 启用**规划模式**进行结构化方法
3. 使用多轮审查进行彻底分析
4. 使用分角色子代理获得多样化视角
## 构建排查
如果构建失败：
1. 使用 **build-error-resolver** 代理
2. 分析错误消息
3. 增量修复
4. 每次修复后验证

29
rules/zh/security.md
View File

@@ -1,29 +0,0 @@
# 安全指南
## 强制安全检查
在任何提交之前：
- [ ] 无硬编码密钥（API 密钥、密码、令牌）
- [ ] 所有用户输入已验证
- [ ] SQL 注入防护（参数化查询）
- [ ] XSS 防护（净化 HTML）
- [ ] CSRF 保护已启用
- [ ] 认证/授权已验证
- [ ] 所有端点启用速率限制
- [ ] 错误消息不泄露敏感数据
## 密钥管理
- 永远不要在源代码中硬编码密钥
- 始终使用环境变量或密钥管理器
- 启动时验证所需的密钥是否存在
- 轮换任何可能已暴露的密钥
## 安全响应协议
如果发现安全问题：
1. 立即停止
2. 使用 **security-reviewer** 代理
3. 在继续之前修复关键问题
4. 轮换任何已暴露的密钥
5. 审查整个代码库中的类似问题

29
rules/zh/testing.md
View File

@@ -1,29 +0,0 @@
# 测试要求
## 最低测试覆盖率：80%
测试类型（全部必需）：
1. **单元测试** - 单个函数、工具、组件
2. **集成测试** - API 端点、数据库操作
3. **E2E 测试** - 关键用户流程（框架根据语言选择）
## 测试驱动开发
强制工作流：
1. 先写测试（RED）
2. 运行测试 - 应该失败
3. 编写最小实现（GREEN）
4. 运行测试 - 应该通过
5. 重构（IMPROVE）
6. 验证覆盖率（80%+）
## 测试失败排查
1. 使用 **tdd-guide** 代理
2. 检查测试隔离
3. 验证模拟是否正确
4. 修复实现，而非测试（除非测试有误）
## 代理支持
- **tdd-guide** - 主动用于新功能，强制先写测试

186
scripts/catalog.js
View File

@@ -1,186 +0,0 @@
#!/usr/bin/env node
const {
getInstallComponent,
listInstallComponents,
listInstallProfiles,
} = require('./lib/install-manifests');
const FAMILY_ALIASES = Object.freeze({
baseline: 'baseline',
baselines: 'baseline',
language: 'language',
languages: 'language',
lang: 'language',
framework: 'framework',
frameworks: 'framework',
capability: 'capability',
capabilities: 'capability',
agent: 'agent',
agents: 'agent',
skill: 'skill',
skills: 'skill',
});
function showHelp(exitCode = 0) {
console.log(`
Discover ECC install components and profiles
Usage:
node scripts/catalog.js profiles [--json]
node scripts/catalog.js components [--family <family>] [--target <target>] [--json]
node scripts/catalog.js show <component-id> [--json]
Examples:
node scripts/catalog.js profiles
node scripts/catalog.js components --family language
node scripts/catalog.js show framework:nextjs
`);
process.exit(exitCode);
}
function normalizeFamily(value) {
if (!value) {
return null;
}
const normalized = String(value).trim().toLowerCase();
return FAMILY_ALIASES[normalized] || normalized;
}
function parseArgs(argv) {
const args = argv.slice(2);
const parsed = {
command: null,
componentId: null,
family: null,
target: null,
json: false,
help: false,
};
if (args.length === 0 || args[0] === '--help' || args[0] === '-h') {
parsed.help = true;
return parsed;
}
parsed.command = args[0];
for (let index = 1; index < args.length; index += 1) {
const arg = args[index];
if (arg === '--help' || arg === '-h') {
parsed.help = true;
} else if (arg === '--json') {
parsed.json = true;
} else if (arg === '--family') {
if (!args[index + 1]) {
throw new Error('Missing value for --family');
}
parsed.family = normalizeFamily(args[index + 1]);
index += 1;
} else if (arg === '--target') {
if (!args[index + 1]) {
throw new Error('Missing value for --target');
}
parsed.target = args[index + 1];
index += 1;
} else if (parsed.command === 'show' && !parsed.componentId) {
parsed.componentId = arg;
} else {
throw new Error(`Unknown argument: ${arg}`);
}
}
return parsed;
}
function printProfiles(profiles) {
console.log('Install profiles:\n');
for (const profile of profiles) {
console.log(`- ${profile.id} (${profile.moduleCount} modules)`);
console.log(` ${profile.description}`);
}
}
function printComponents(components) {
console.log('Install components:\n');
for (const component of components) {
console.log(`- ${component.id} [${component.family}]`);
console.log(` targets=${component.targets.join(', ')} modules=${component.moduleIds.join(', ')}`);
console.log(` ${component.description}`);
}
}
function printComponent(component) {
console.log(`Install component: ${component.id}\n`);
console.log(`Family: ${component.family}`);
console.log(`Targets: ${component.targets.join(', ')}`);
console.log(`Modules: ${component.moduleIds.join(', ')}`);
console.log(`Description: ${component.description}`);
if (component.modules.length > 0) {
console.log('\nResolved modules:');
for (const module of component.modules) {
console.log(`- ${module.id} [${module.kind}]`);
console.log(
` targets=${module.targets.join(', ')} default=${module.defaultInstall} cost=${module.cost} stability=${module.stability}`
);
console.log(` ${module.description}`);
}
}
}
function main() {
try {
const options = parseArgs(process.argv);
if (options.help) {
showHelp(0);
}
if (options.command === 'profiles') {
const profiles = listInstallProfiles();
if (options.json) {
console.log(JSON.stringify({ profiles }, null, 2));
} else {
printProfiles(profiles);
}
return;
}
if (options.command === 'components') {
const components = listInstallComponents({
family: options.family,
target: options.target,
});
if (options.json) {
console.log(JSON.stringify({ components }, null, 2));
} else {
printComponents(components);
}
return;
}
if (options.command === 'show') {
if (!options.componentId) {
throw new Error('Catalog show requires an install component ID');
}
const component = getInstallComponent(options.componentId);
if (options.json) {
console.log(JSON.stringify(component, null, 2));
} else {
printComponent(component);
}
return;
}
throw new Error(`Unknown catalog command: ${options.command}`);
} catch (error) {
console.error(`Error: ${error.message}`);
process.exit(1);
}
}
main();

24
scripts/codex/check-codex-global-state.sh Executable file → Normal file
View File

@@ -11,7 +11,7 @@ CODEX_HOME="${CODEX_HOME:-$HOME/.codex}"
CONFIG_FILE="$CODEX_HOME/config.toml"
AGENTS_FILE="$CODEX_HOME/AGENTS.md"
PROMPTS_DIR="$CODEX_HOME/prompts"
SKILLS_DIR="${AGENTS_HOME:-$HOME/.agents}/skills"
SKILLS_DIR="$CODEX_HOME/skills"
HOOKS_DIR_EXPECT="${ECC_GLOBAL_HOOKS_DIR:-$CODEX_HOME/git-hooks}"
failures=0
@@ -89,13 +89,7 @@ fi
if [[ -f "$CONFIG_FILE" ]]; then
check_config_pattern '^multi_agent\s*=\s*true' "multi_agent is enabled"
check_config_absent '^\s*collab\s*=' "deprecated collab flag is absent"
# persistent_instructions is recommended but optional; warn instead of fail
# so users who rely on AGENTS.md alone are not blocked (#967).
if rg -n '^[[:space:]]*persistent_instructions\s*=' "$CONFIG_FILE" >/dev/null 2>&1; then
ok "persistent_instructions is configured"
else
warn "persistent_instructions is not set (recommended but optional)"
fi
check_config_pattern '^persistent_instructions\s*=' "persistent_instructions is configured"
check_config_pattern '^\[profiles\.strict\]' "profiles.strict exists"
check_config_pattern '^\[profiles\.yolo\]' "profiles.yolo exists"
@@ -103,7 +97,7 @@ if [[ -f "$CONFIG_FILE" ]]; then
'mcp_servers.github' \
'mcp_servers.memory' \
'mcp_servers.sequential-thinking' \
'mcp_servers.context7'
'mcp_servers.context7-mcp'
do
if rg -n "^\[$section\]" "$CONFIG_FILE" >/dev/null 2>&1; then
ok "MCP section [$section] exists"
@@ -112,10 +106,10 @@ if [[ -f "$CONFIG_FILE" ]]; then
fi
done
if rg -n '^\[mcp_servers\.context7-mcp\]' "$CONFIG_FILE" >/dev/null 2>&1; then
warn "Legacy [mcp_servers.context7-mcp] exists (context7 is preferred)"
if rg -n '^\[mcp_servers\.context7\]' "$CONFIG_FILE" >/dev/null 2>&1; then
warn "Duplicate [mcp_servers.context7] exists (context7-mcp is preferred)"
else
ok "No legacy [mcp_servers.context7-mcp] section"
ok "No duplicate [mcp_servers.context7] section"
fi
fi
@@ -150,12 +144,12 @@ if [[ -d "$SKILLS_DIR" ]]; then
done
if [[ "$missing_skills" -eq 0 ]]; then
ok "All 16 ECC skills are present in $SKILLS_DIR"
ok "All 16 ECC Codex skills are present"
else
warn "$missing_skills ECC skills missing from $SKILLS_DIR (install via ECC installer or npx skills)"
fail "$missing_skills required skills are missing"
fi
else
warn "Skills directory missing ($SKILLS_DIR) — install via ECC installer or npx skills"
fail "Skills directory missing ($SKILLS_DIR)"
fi
if [[ -f "$PROMPTS_DIR/ecc-prompts-manifest.txt" ]]; then

20
scripts/codex/install-global-git-hooks.sh Executable file → Normal file
View File

@@ -24,11 +24,9 @@ log() {
run_or_echo() {
if [[ "$MODE" == "dry-run" ]]; then
printf '[dry-run]'
printf ' %q' "$@"
printf '\n'
printf '[dry-run] %s\n' "$*"
else
"$@"
eval "$*"
fi
}
@@ -43,14 +41,14 @@ log "Global hooks destination: $DEST_DIR"
if [[ -d "$DEST_DIR" ]]; then
log "Backing up existing hooks directory to $BACKUP_DIR"
run_or_echo mkdir -p "$BACKUP_DIR"
run_or_echo cp -R "$DEST_DIR" "$BACKUP_DIR/hooks"
run_or_echo "mkdir -p \"$BACKUP_DIR\""
run_or_echo "cp -R \"$DEST_DIR\" \"$BACKUP_DIR/hooks\""
fi
run_or_echo mkdir -p "$DEST_DIR"
run_or_echo cp "$SOURCE_DIR/pre-commit" "$DEST_DIR/pre-commit"
run_or_echo cp "$SOURCE_DIR/pre-push" "$DEST_DIR/pre-push"
run_or_echo chmod +x "$DEST_DIR/pre-commit" "$DEST_DIR/pre-push"
run_or_echo "mkdir -p \"$DEST_DIR\""
run_or_echo "cp \"$SOURCE_DIR/pre-commit\" \"$DEST_DIR/pre-commit\""
run_or_echo "cp \"$SOURCE_DIR/pre-push\" \"$DEST_DIR/pre-push\""
run_or_echo "chmod +x \"$DEST_DIR/pre-commit\" \"$DEST_DIR/pre-push\""
if [[ "$MODE" == "apply" ]]; then
prev_hooks_path="$(git config --global core.hooksPath || true)"
@@ -58,7 +56,7 @@ if [[ "$MODE" == "apply" ]]; then
log "Previous global hooksPath: $prev_hooks_path"
fi
fi
run_or_echo git config --global core.hooksPath "$DEST_DIR"
run_or_echo "git config --global core.hooksPath \"$DEST_DIR\""
log "Installed ECC global git hooks."
log "Disable per repo by creating .ecc-hooks-disable in project root."

23
scripts/codex/merge-mcp-config.js
View File

@@ -83,23 +83,20 @@ function dlxServer(name, pkg, extraFields, extraToml) {
}
/** Each entry: key = section name under mcp_servers, value = { toml, fields } */
const DEFAULT_MCP_STARTUP_TIMEOUT_SEC = 30;
const DEFAULT_MCP_STARTUP_TIMEOUT_TOML = `startup_timeout_sec = ${DEFAULT_MCP_STARTUP_TIMEOUT_SEC}`;
const ECC_SERVERS = {
supabase: dlxServer('supabase', '@supabase/mcp-server-supabase@latest', { startup_timeout_sec: 20.0, tool_timeout_sec: 120.0 }, 'startup_timeout_sec = 20.0\ntool_timeout_sec = 120.0'),
playwright: dlxServer('playwright', '@playwright/mcp@latest', { startup_timeout_sec: DEFAULT_MCP_STARTUP_TIMEOUT_SEC }, DEFAULT_MCP_STARTUP_TIMEOUT_TOML),
context7: dlxServer('context7', '@upstash/context7-mcp@latest', { startup_timeout_sec: DEFAULT_MCP_STARTUP_TIMEOUT_SEC }, DEFAULT_MCP_STARTUP_TIMEOUT_TOML),
playwright: dlxServer('playwright', '@playwright/mcp@latest'),
'context7-mcp': dlxServer('context7-mcp', '@upstash/context7-mcp'),
exa: {
fields: { url: 'https://mcp.exa.ai/mcp' },
toml: `[mcp_servers.exa]\nurl = "https://mcp.exa.ai/mcp"`
},
github: {
fields: { command: 'bash', args: ['-lc', GH_BOOTSTRAP], startup_timeout_sec: DEFAULT_MCP_STARTUP_TIMEOUT_SEC },
toml: `[mcp_servers.github]\ncommand = "bash"\nargs = ["-lc", ${JSON.stringify(GH_BOOTSTRAP)}]\n${DEFAULT_MCP_STARTUP_TIMEOUT_TOML}`
fields: { command: 'bash', args: ['-lc', GH_BOOTSTRAP] },
toml: `[mcp_servers.github]\ncommand = "bash"\nargs = ["-lc", ${JSON.stringify(GH_BOOTSTRAP)}]`
},
memory: dlxServer('memory', '@modelcontextprotocol/server-memory', { startup_timeout_sec: DEFAULT_MCP_STARTUP_TIMEOUT_SEC }, DEFAULT_MCP_STARTUP_TIMEOUT_TOML),
'sequential-thinking': dlxServer('sequential-thinking', '@modelcontextprotocol/server-sequential-thinking', { startup_timeout_sec: DEFAULT_MCP_STARTUP_TIMEOUT_SEC }, DEFAULT_MCP_STARTUP_TIMEOUT_TOML)
memory: dlxServer('memory', '@modelcontextprotocol/server-memory'),
'sequential-thinking': dlxServer('sequential-thinking', '@modelcontextprotocol/server-sequential-thinking')
};
// Append --features arg for supabase after dlxServer builds the base
@@ -107,9 +104,9 @@ ECC_SERVERS.supabase.fields.args.push('--features=account,docs,database,debuggin
ECC_SERVERS.supabase.toml = ECC_SERVERS.supabase.toml.replace(/^(args = \[.*)\]$/m, '$1, "--features=account,docs,database,debugging,development,functions,storage,branching"]');
// Legacy section names that should be treated as an existing ECC server.
// e.g. older configs shipped [mcp_servers.context7-mcp] instead of [mcp_servers.context7].
// e.g. old configs shipped [mcp_servers.context7] instead of [mcp_servers.context7-mcp].
const LEGACY_ALIASES = {
context7: ['context7-mcp']
'context7-mcp': ['context7']
};
// ---------------------------------------------------------------------------
@@ -257,10 +254,6 @@ function main() {
if (resolvedLabel !== name) {
raw = removeServerFromText(raw, name, existing);
}
if (legacyName && hasCanonical) {
toRemoveLog.push(`mcp_servers.${legacyName}`);
raw = removeServerFromText(raw, legacyName, existing);
}
toAppend.push(spec.toml);
} else {
// Add-only mode: skip, but warn about drift

3
scripts/doctor.js
View File

@@ -1,6 +1,5 @@
#!/usr/bin/env node
const os = require('os');
const { buildDoctorReport } = require('./lib/install-lifecycle');
const { SUPPORTED_INSTALL_TARGETS } = require('./lib/install-manifests');
@@ -89,7 +88,7 @@ function main() {
const report = buildDoctorReport({
repoRoot: require('path').join(__dirname, '..'),
homeDir: process.env.HOME || os.homedir(),
homeDir: process.env.HOME,
projectRoot: process.cwd(),
targets: options.targets,
});

8
scripts/ecc.js Executable file → Normal file
View File

@@ -13,10 +13,6 @@ const COMMANDS = {
script: 'install-plan.js',
description: 'Inspect selective-install manifests and resolved plans',
},
catalog: {
script: 'catalog.js',
description: 'Discover install profiles and component IDs',
},
'install-plan': {
script: 'install-plan.js',
description: 'Alias for plan',
@@ -54,7 +50,6 @@ const COMMANDS = {
const PRIMARY_COMMANDS = [
'install',
'plan',
'catalog',
'list-installed',
'doctor',
'repair',
@@ -84,9 +79,6 @@ Examples:
ecc typescript
ecc install --profile developer --target claude
ecc plan --profile core --target cursor
ecc catalog profiles
ecc catalog components --family language
ecc catalog show framework:nextjs
ecc list-installed --json
ecc doctor --target cursor
ecc repair --dry-run

59
scripts/hooks/config-protection.js
View File

@@ -61,34 +61,11 @@ const PROTECTED_FILES = new Set([
'.markdownlintrc',
]);
function parseInput(inputOrRaw) {
if (typeof inputOrRaw === 'string') {
try {
return inputOrRaw.trim() ? JSON.parse(inputOrRaw) : {};
} catch {
return {};
}
}
return inputOrRaw && typeof inputOrRaw === 'object' ? inputOrRaw : {};
}
/**
* Exportable run() for in-process execution via run-with-flags.js.
* Avoids the ~50-100ms spawnSync overhead when available.
*/
function run(inputOrRaw, options = {}) {
if (options.truncated) {
return {
exitCode: 2,
stderr:
`BLOCKED: Hook input exceeded ${options.maxStdin || MAX_STDIN} bytes. ` +
'Refusing to bypass config-protection on a truncated payload. ' +
'Retry with a smaller edit or disable the config-protection hook temporarily.'
};
}
const input = parseInput(inputOrRaw);
function run(input) {
const filePath = input?.tool_input?.file_path || input?.tool_input?.file || '';
if (!filePath) return { exitCode: 0 };
@@ -98,9 +75,9 @@ function run(inputOrRaw, options = {}) {
exitCode: 2,
stderr:
`BLOCKED: Modifying ${basename} is not allowed. ` +
'Fix the source code to satisfy linter/formatter rules instead of ' +
'weakening the config. If this is a legitimate config change, ' +
'disable the config-protection hook temporarily.',
`Fix the source code to satisfy linter/formatter rules instead of ` +
`weakening the config. If this is a legitimate config change, ` +
`disable the config-protection hook temporarily.`,
};
}
@@ -110,7 +87,7 @@ function run(inputOrRaw, options = {}) {
module.exports = { run };
// Stdin fallback for spawnSync execution
let truncated = /^(1|true|yes)$/i.test(String(process.env.ECC_HOOK_INPUT_TRUNCATED || ''));
let truncated = false;
process.stdin.setEncoding('utf8');
process.stdin.on('data', chunk => {
if (raw.length < MAX_STDIN) {
@@ -123,17 +100,25 @@ process.stdin.on('data', chunk => {
});
process.stdin.on('end', () => {
const result = run(raw, {
truncated,
maxStdin: Number(process.env.ECC_HOOK_INPUT_MAX_BYTES) || MAX_STDIN,
});
if (result.stderr) {
process.stderr.write(result.stderr + '\n');
// If stdin was truncated, the JSON is likely malformed. Fail open but
// log a warning so the issue is visible. The run() path (used by
// run-with-flags.js in-process) is not affected by this.
if (truncated) {
process.stderr.write('[config-protection] Warning: stdin exceeded 1MB, skipping check\n');
process.stdout.write(raw);
return;
}
if (result.exitCode === 2) {
process.exit(2);
try {
const input = raw.trim() ? JSON.parse(raw) : {};
const result = run(input);
if (result.exitCode === 2) {
process.stderr.write(result.stderr + '\n');
process.exit(2);
}
} catch {
// Keep hook non-blocking on parse errors.
}
process.stdout.write(raw);

94
scripts/hooks/desktop-notify.js
View File

@@ -1,94 +0,0 @@
#!/usr/bin/env node
/**
* Desktop Notification Hook (Stop)
*
* Sends a native desktop notification with the task summary when Claude
* finishes responding. Currently supports macOS (osascript); other
* platforms exit silently. Windows (PowerShell) and Linux (notify-send)
* support is planned.
*
* Hook ID : stop:desktop-notify
* Profiles: standard, strict
*/
'use strict';
const { spawnSync } = require('child_process');
const { isMacOS, log } = require('../lib/utils');
const TITLE = 'Claude Code';
const MAX_BODY_LENGTH = 100;
/**
* Extract a short summary from the last assistant message.
* Takes the first non-empty line and truncates to MAX_BODY_LENGTH chars.
*/
function extractSummary(message) {
if (!message || typeof message !== 'string') return 'Done';
const firstLine = message
.split('\n')
.map(l => l.trim())
.find(l => l.length > 0);
if (!firstLine) return 'Done';
return firstLine.length > MAX_BODY_LENGTH
? `${firstLine.slice(0, MAX_BODY_LENGTH)}...`
: firstLine;
}
/**
* Send a macOS notification via osascript.
* AppleScript strings do not support backslash escapes, so we replace
* double quotes with curly quotes and strip backslashes before embedding.
*/
function notifyMacOS(title, body) {
const safeBody = body.replace(/\\/g, '').replace(/"/g, '\u201C');
const safeTitle = title.replace(/\\/g, '').replace(/"/g, '\u201C');
const script = `display notification "${safeBody}" with title "${safeTitle}"`;
const result = spawnSync('osascript', ['-e', script], { stdio: 'ignore', timeout: 5000 });
if (result.error || result.status !== 0) {
log(`[DesktopNotify] osascript failed: ${result.error ? result.error.message : `exit ${result.status}`}`);
}
}
// TODO: future platform support
// function notifyWindows(title, body) { ... }
// function notifyLinux(title, body) { ... }
/**
* Fast-path entry point for run-with-flags.js (avoids extra process spawn).
*/
function run(raw) {
try {
if (!isMacOS) return raw;
const input = raw.trim() ? JSON.parse(raw) : {};
const summary = extractSummary(input.last_assistant_message);
notifyMacOS(TITLE, summary);
} catch (err) {
log(`[DesktopNotify] Error: ${err.message}`);
}
return raw;
}
module.exports = { run };
// Legacy stdin path (when invoked directly rather than via run-with-flags)
if (require.main === module) {
const MAX_STDIN = 1024 * 1024;
let data = '';
process.stdin.setEncoding('utf8');
process.stdin.on('data', chunk => {
if (data.length < MAX_STDIN) {
data += chunk.substring(0, MAX_STDIN - data.length);
}
});
process.stdin.on('end', () => {
const output = run(data);
if (output) process.stdout.write(output);
});
}

78
scripts/hooks/governance-capture.js
View File

@@ -10,7 +10,6 @@
* - policy_violation: Actions that violate configured policies
* - security_finding: Security-relevant tool invocations
* - approval_requested: Operations requiring explicit approval
* - hook_input_truncated: Hook input exceeded the safe inspection limit
*
* Enable: Set ECC_GOVERNANCE_CAPTURE=1
* Configure session: Set ECC_SESSION_ID for session correlation
@@ -102,37 +101,6 @@ function detectSensitivePath(filePath) {
return SENSITIVE_PATHS.some(pattern => pattern.test(filePath));
}
function fingerprintCommand(command) {
if (!command || typeof command !== 'string') return null;
return crypto.createHash('sha256').update(command).digest('hex').slice(0, 12);
}
function summarizeCommand(command) {
if (!command || typeof command !== 'string') {
return {
commandName: null,
commandFingerprint: null,
};
}
const trimmed = command.trim();
if (!trimmed) {
return {
commandName: null,
commandFingerprint: null,
};
}
return {
commandName: trimmed.split(/\s+/)[0] || null,
commandFingerprint: fingerprintCommand(trimmed),
};
}
function emitGovernanceEvent(event) {
process.stderr.write(`[governance] ${JSON.stringify(event)}\n`);
}
/**
* Analyze a hook input payload and return governance events to capture.
*
@@ -178,7 +146,6 @@ function analyzeForGovernanceEvents(input, context = {}) {
if (toolName === 'Bash') {
const command = toolInput.command || '';
const approvalFindings = detectApprovalRequired(command);
const commandSummary = summarizeCommand(command);
if (approvalFindings.length > 0) {
events.push({
@@ -188,7 +155,7 @@ function analyzeForGovernanceEvents(input, context = {}) {
payload: {
toolName,
hookPhase,
...commandSummary,
command: command.slice(0, 200),
matchedPatterns: approvalFindings.map(f => f.pattern),
severity: 'high',
},
@@ -221,7 +188,6 @@ function analyzeForGovernanceEvents(input, context = {}) {
if (SECURITY_RELEVANT_TOOLS.has(toolName) && hookPhase === 'post') {
const command = toolInput.command || '';
const hasElevated = /sudo\s/.test(command) || /chmod\s/.test(command) || /chown\s/.test(command);
const commandSummary = summarizeCommand(command);
if (hasElevated) {
events.push({
@@ -231,7 +197,7 @@ function analyzeForGovernanceEvents(input, context = {}) {
payload: {
toolName,
hookPhase,
...commandSummary,
command: command.slice(0, 200),
reason: 'elevated_privilege_command',
severity: 'medium',
},
@@ -250,32 +216,16 @@ function analyzeForGovernanceEvents(input, context = {}) {
* @param {string} rawInput - Raw JSON string from stdin
* @returns {string} The original input (pass-through)
*/
function run(rawInput, options = {}) {
function run(rawInput) {
// Gate on feature flag
if (String(process.env.ECC_GOVERNANCE_CAPTURE || '').toLowerCase() !== '1') {
return rawInput;
}
const sessionId = process.env.ECC_SESSION_ID || null;
const hookPhase = process.env.CLAUDE_HOOK_EVENT_NAME || 'unknown';
if (options.truncated) {
emitGovernanceEvent({
id: generateEventId(),
sessionId,
eventType: 'hook_input_truncated',
payload: {
hookPhase: hookPhase.startsWith('Pre') ? 'pre' : 'post',
sizeLimitBytes: options.maxStdin || MAX_STDIN,
severity: 'warning',
},
resolvedAt: null,
resolution: null,
});
}
try {
const input = JSON.parse(rawInput);
const sessionId = process.env.ECC_SESSION_ID || null;
const hookPhase = process.env.CLAUDE_HOOK_EVENT_NAME || 'unknown';
const events = analyzeForGovernanceEvents(input, {
sessionId,
@@ -283,8 +233,13 @@ function run(rawInput, options = {}) {
});
if (events.length > 0) {
// Write events to stderr as JSON-lines for the caller to capture.
// The state store write is async and handled by a separate process
// to avoid blocking the hook pipeline.
for (const event of events) {
emitGovernanceEvent(event);
process.stderr.write(
`[governance] ${JSON.stringify(event)}\n`
);
}
}
} catch {
@@ -297,25 +252,16 @@ function run(rawInput, options = {}) {
// ── stdin entry point ────────────────────────────────
if (require.main === module) {
let raw = '';
let truncated = /^(1|true|yes)$/i.test(String(process.env.ECC_HOOK_INPUT_TRUNCATED || ''));
process.stdin.setEncoding('utf8');
process.stdin.on('data', chunk => {
if (raw.length < MAX_STDIN) {
const remaining = MAX_STDIN - raw.length;
raw += chunk.substring(0, remaining);
if (chunk.length > remaining) {
truncated = true;
}
} else {
truncated = true;
}
});
process.stdin.on('end', () => {
const result = run(raw, {
truncated,
maxStdin: Number(process.env.ECC_HOOK_INPUT_MAX_BYTES) || MAX_STDIN,
});
const result = run(raw);
process.stdout.write(result);
});
}

39
scripts/hooks/mcp-health-check.js
View File

@@ -99,21 +99,15 @@ function saveState(filePath, state) {
function readRawStdin() {
return new Promise(resolve => {
let raw = '';
let truncated = /^(1|true|yes)$/i.test(String(process.env.ECC_HOOK_INPUT_TRUNCATED || ''));
process.stdin.setEncoding('utf8');
process.stdin.on('data', chunk => {
if (raw.length < MAX_STDIN) {
const remaining = MAX_STDIN - raw.length;
raw += chunk.substring(0, remaining);
if (chunk.length > remaining) {
truncated = true;
}
} else {
truncated = true;
}
});
process.stdin.on('end', () => resolve({ raw, truncated }));
process.stdin.on('error', () => resolve({ raw, truncated }));
process.stdin.on('end', () => resolve(raw));
process.stdin.on('error', () => resolve(raw));
});
}
@@ -161,18 +155,6 @@ function extractMcpTarget(input) {
};
}
function extractMcpTargetFromRaw(raw) {
const toolNameMatch = raw.match(/"(?:tool_name|name)"\s*:\s*"([^"]+)"/);
const serverMatch = raw.match(/"(?:server|mcp_server|connector)"\s*:\s*"([^"]+)"/);
const toolMatch = raw.match(/"(?:tool|mcp_tool)"\s*:\s*"([^"]+)"/);
return extractMcpTarget({
tool_name: toolNameMatch ? toolNameMatch[1] : '',
server: serverMatch ? serverMatch[1] : undefined,
tool: toolMatch ? toolMatch[1] : undefined
});
}
function resolveServerConfig(serverName) {
for (const filePath of configPaths()) {
const data = readJsonFile(filePath);
@@ -577,9 +559,9 @@ async function handlePostToolUseFailure(rawInput, input, target, statePathValue,
}
async function main() {
const { raw: rawInput, truncated } = await readRawStdin();
const rawInput = await readRawStdin();
const input = safeParse(rawInput);
const target = extractMcpTarget(input) || (truncated ? extractMcpTargetFromRaw(rawInput) : null);
const target = extractMcpTarget(input);
if (!target) {
process.stdout.write(rawInput);
@@ -587,19 +569,6 @@ async function main() {
return;
}
if (truncated) {
const limit = Number(process.env.ECC_HOOK_INPUT_MAX_BYTES) || MAX_STDIN;
const logs = [
shouldFailOpen()
? `[MCPHealthCheck] Hook input exceeded ${limit} bytes while checking ${target.server}; allowing ${target.tool || 'tool'} because fail-open mode is enabled`
: `[MCPHealthCheck] Hook input exceeded ${limit} bytes while checking ${target.server}; blocking ${target.tool || 'tool'} to avoid bypassing MCP health checks`
];
emitLogs(logs);
process.stdout.write(rawInput);
process.exit(shouldFailOpen() ? 0 : 2);
return;
}
const eventName = process.env.CLAUDE_HOOK_EVENT_NAME || 'PreToolUse';
const now = Date.now();
const statePathValue = stateFilePath();

81
scripts/hooks/run-with-flags.js
View File

@@ -18,66 +18,18 @@ const MAX_STDIN = 1024 * 1024;
function readStdinRaw() {
return new Promise(resolve => {
let raw = '';
let truncated = false;
process.stdin.setEncoding('utf8');
process.stdin.on('data', chunk => {
if (raw.length < MAX_STDIN) {
const remaining = MAX_STDIN - raw.length;
raw += chunk.substring(0, remaining);
if (chunk.length > remaining) {
truncated = true;
}
} else {
truncated = true;
}
});
process.stdin.on('end', () => resolve({ raw, truncated }));
process.stdin.on('error', () => resolve({ raw, truncated }));
process.stdin.on('end', () => resolve(raw));
process.stdin.on('error', () => resolve(raw));
});
}
function writeStderr(stderr) {
if (typeof stderr !== 'string' || stderr.length === 0) {
return;
}
process.stderr.write(stderr.endsWith('\n') ? stderr : `${stderr}\n`);
}
function emitHookResult(raw, output) {
if (typeof output === 'string' || Buffer.isBuffer(output)) {
process.stdout.write(String(output));
return 0;
}
if (output && typeof output === 'object') {
writeStderr(output.stderr);
if (Object.prototype.hasOwnProperty.call(output, 'stdout')) {
process.stdout.write(String(output.stdout ?? ''));
} else if (!Number.isInteger(output.exitCode) || output.exitCode === 0) {
process.stdout.write(raw);
}
return Number.isInteger(output.exitCode) ? output.exitCode : 0;
}
process.stdout.write(raw);
return 0;
}
function writeLegacySpawnOutput(raw, result) {
const stdout = typeof result.stdout === 'string' ? result.stdout : '';
if (stdout) {
process.stdout.write(stdout);
return;
}
if (Number.isInteger(result.status) && result.status === 0) {
process.stdout.write(raw);
}
}
function getPluginRoot() {
if (process.env.CLAUDE_PLUGIN_ROOT && process.env.CLAUDE_PLUGIN_ROOT.trim()) {
return process.env.CLAUDE_PLUGIN_ROOT;
@@ -87,7 +39,7 @@ function getPluginRoot() {
async function main() {
const [, , hookId, relScriptPath, profilesCsv] = process.argv;
const { raw, truncated } = await readStdinRaw();
const raw = await readStdinRaw();
if (!hookId || !relScriptPath) {
process.stdout.write(raw);
@@ -137,8 +89,8 @@ async function main() {
if (hookModule && typeof hookModule.run === 'function') {
try {
const output = hookModule.run(raw, { truncated, maxStdin: MAX_STDIN });
process.exit(emitHookResult(raw, output));
const output = hookModule.run(raw);
if (output !== null && output !== undefined) process.stdout.write(output);
} catch (runErr) {
process.stderr.write(`[Hook] run() error for ${hookId}: ${runErr.message}\n`);
process.stdout.write(raw);
@@ -147,32 +99,19 @@ async function main() {
}
// Legacy path: spawn a child Node process for hooks without run() export
const result = spawnSync(process.execPath, [scriptPath], {
const result = spawnSync('node', [scriptPath], {
input: raw,
encoding: 'utf8',
env: {
...process.env,
ECC_HOOK_INPUT_TRUNCATED: truncated ? '1' : '0',
ECC_HOOK_INPUT_MAX_BYTES: String(MAX_STDIN)
},
env: process.env,
cwd: process.cwd(),
timeout: 30000
});
writeLegacySpawnOutput(raw, result);
if (result.stdout) process.stdout.write(result.stdout);
if (result.stderr) process.stderr.write(result.stderr);
if (result.error || result.signal || result.status === null) {
const failureDetail = result.error
? result.error.message
: result.signal
? `terminated by signal ${result.signal}`
: 'missing exit status';
writeStderr(`[Hook] legacy hook execution failed for ${hookId}: ${failureDetail}`);
process.exit(1);
}
process.exit(Number.isInteger(result.status) ? result.status : 0);
const code = Number.isInteger(result.status) ? result.status : 0;
process.exit(code);
}
main().catch(err => {

79
scripts/hooks/session-start.js
View File

@@ -11,59 +11,28 @@
const {
getSessionsDir,
getSessionSearchDirs,
getLearnedSkillsDir,
findFiles,
ensureDir,
readFile,
stripAnsi,
log
log,
output
} = require('../lib/utils');
const { getPackageManager, getSelectionPrompt } = require('../lib/package-manager');
const { listAliases } = require('../lib/session-aliases');
const { detectProjectType } = require('../lib/project-detect');
const path = require('path');
function dedupeRecentSessions(searchDirs) {
const recentSessionsByName = new Map();
for (const [dirIndex, dir] of searchDirs.entries()) {
const matches = findFiles(dir, '*-session.tmp', { maxAge: 7 });
for (const match of matches) {
const basename = path.basename(match.path);
const current = {
...match,
basename,
dirIndex,
};
const existing = recentSessionsByName.get(basename);
if (
!existing
|| current.mtime > existing.mtime
|| (current.mtime === existing.mtime && current.dirIndex < existing.dirIndex)
) {
recentSessionsByName.set(basename, current);
}
}
}
return Array.from(recentSessionsByName.values())
.sort((left, right) => right.mtime - left.mtime || left.dirIndex - right.dirIndex);
}
async function main() {
const sessionsDir = getSessionsDir();
const learnedDir = getLearnedSkillsDir();
const additionalContextParts = [];
// Ensure directories exist
ensureDir(sessionsDir);
ensureDir(learnedDir);
// Check for recent session files (last 7 days)
const recentSessions = dedupeRecentSessions(getSessionSearchDirs());
const recentSessions = findFiles(sessionsDir, '*-session.tmp', { maxAge: 7 });
if (recentSessions.length > 0) {
const latest = recentSessions[0];
@@ -74,7 +43,7 @@ async function main() {
const content = stripAnsi(readFile(latest.path));
if (content && !content.includes('[Session context goes here]')) {
// Only inject if the session has actual content (not the blank template)
additionalContextParts.push(`Previous session summary:\n${content}`);
output(`Previous session summary:\n${content}`);
}
}
@@ -115,49 +84,15 @@ async function main() {
parts.push(`frameworks: ${projectInfo.frameworks.join(', ')}`);
}
log(`[SessionStart] Project detected — ${parts.join('; ')}`);
additionalContextParts.push(`Project type: ${JSON.stringify(projectInfo)}`);
output(`Project type: ${JSON.stringify(projectInfo)}`);
} else {
log('[SessionStart] No specific project type detected');
}
await writeSessionStartPayload(additionalContextParts.join('\n\n'));
}
function writeSessionStartPayload(additionalContext) {
return new Promise((resolve, reject) => {
let settled = false;
const payload = JSON.stringify({
hookSpecificOutput: {
hookEventName: 'SessionStart',
additionalContext
}
});
const handleError = (err) => {
if (settled) return;
settled = true;
if (err) {
log(`[SessionStart] stdout write error: ${err.message}`);
}
reject(err || new Error('stdout stream error'));
};
process.stdout.once('error', handleError);
process.stdout.write(payload, (err) => {
process.stdout.removeListener('error', handleError);
if (settled) return;
settled = true;
if (err) {
log(`[SessionStart] stdout write error: ${err.message}`);
reject(err);
return;
}
resolve();
});
});
process.exit(0);
}
main().catch(err => {
console.error('[SessionStart] Error:', err.message);
process.exitCode = 0; // Don't block on errors
process.exit(0); // Don't block on errors
});

24
scripts/install-apply.js Executable file → Normal file
View File

@@ -6,7 +6,6 @@
* target-specific mutation logic into testable Node code.
*/
const os = require('os');
const {
SUPPORTED_INSTALL_TARGETS,
listLegacyCompatibilityLanguages,
@@ -17,10 +16,10 @@ const {
parseInstallArgs,
} = require('./lib/install/request');
function getHelpText() {
function showHelp(exitCode = 0) {
const languages = listLegacyCompatibilityLanguages();
return `
console.log(`
Usage: install.sh [--target <${LEGACY_INSTALL_TARGETS.join('|')}>] [--dry-run] [--json] <language> [<language> ...]
install.sh [--target <${SUPPORTED_INSTALL_TARGETS.join('|')}>] [--dry-run] [--json] --profile <name> [--with <component>]... [--without <component>]...
install.sh [--target <${SUPPORTED_INSTALL_TARGETS.join('|')}>] [--dry-run] [--json] --modules <id,id,...> [--with <component>]... [--without <component>]...
@@ -44,11 +43,8 @@ Options:
Available languages:
${languages.map(language => ` - ${language}`).join('\n')}
`;
}
`);
function showHelp(exitCode = 0) {
console.log(getHelpText());
process.exit(exitCode);
}
@@ -104,25 +100,19 @@ function main() {
showHelp(0);
}
const {
findDefaultInstallConfigPath,
loadInstallConfig,
} = require('./lib/install/config');
const { loadInstallConfig } = require('./lib/install/config');
const { applyInstallPlan } = require('./lib/install-executor');
const { createInstallPlanFromRequest } = require('./lib/install/runtime');
const defaultConfigPath = options.configPath || options.languages.length > 0
? null
: findDefaultInstallConfigPath({ cwd: process.cwd() });
const config = options.configPath
? loadInstallConfig(options.configPath, { cwd: process.cwd() })
: (defaultConfigPath ? loadInstallConfig(defaultConfigPath, { cwd: process.cwd() }) : null);
: null;
const request = normalizeInstallRequest({
...options,
config,
});
const plan = createInstallPlanFromRequest(request, {
projectRoot: process.cwd(),
homeDir: process.env.HOME || os.homedir(),
homeDir: process.env.HOME,
claudeRulesDir: process.env.CLAUDE_RULES_DIR || null,
});
@@ -142,7 +132,7 @@ function main() {
printHumanPlan(result, false);
}
} catch (error) {
process.stderr.write(`Error: ${error.message}${getHelpText()}`);
console.error(`Error: ${error.message}`);
process.exit(1);
}
}

18
scripts/install-plan.js
View File

@@ -9,10 +9,7 @@ const {
listInstallProfiles,
resolveInstallPlan,
} = require('./lib/install-manifests');
const {
findDefaultInstallConfigPath,
loadInstallConfig,
} = require('./lib/install/config');
const { loadInstallConfig } = require('./lib/install/config');
const { normalizeInstallRequest } = require('./lib/install/request');
function showHelp() {
@@ -189,7 +186,7 @@ function main() {
try {
const options = parseArgs(process.argv);
if (options.help) {
if (options.help || process.argv.length <= 2) {
showHelp();
process.exit(0);
}
@@ -227,18 +224,9 @@ function main() {
return;
}
const defaultConfigPath = options.configPath
? null
: findDefaultInstallConfigPath({ cwd: process.cwd() });
const config = options.configPath
? loadInstallConfig(options.configPath, { cwd: process.cwd() })
: (defaultConfigPath ? loadInstallConfig(defaultConfigPath, { cwd: process.cwd() }) : null);
if (process.argv.length <= 2 && !config) {
showHelp();
process.exit(0);
}
: null;
const request = normalizeInstallRequest({
...options,
languages: [],

Some files were not shown because too many files have changed in this diff Show More