On Windows 10/11 without Python installed from the Microsoft Store, the
"App Execution Alias" stubs at %LOCALAPPDATA%\Microsoft\WindowsApps\python.exe
and python3.exe are symlinks to AppInstallerPythonRedirector.exe. These
stubs neither launch Python nor honor `-c`; calls print a bare "Python "
line and exit, silently breaking every JSON-parsing step in observe.sh.
Net effect: observations.jsonl is never written, CLV2 appears installed
correctly, and the only residual artifact is `.last-purge`.
This commit:
1. Adds `_is_windows_app_installer_stub` helper that detects the stub
via `command -v` output and optional `readlink -f` resolution.
2. Teaches `resolve_python_cmd` to skip stub candidates and fall
through to the next real interpreter (typically C:\...\Python3xx\python.exe).
3. Exports the stub-aware CLV2_PYTHON_CMD before sourcing
detect-project.sh, which already honors an already-set value,
so the shared helper does not re-resolve and re-select the stub.
POSIX-compatible. No behavior change on macOS / Linux / WSL where no
such stub exists.
Refs: observations.jsonl empty on Windows Claude Desktop users.
The merged hero was being clipped at the bottom by the Puppeteer capture
because the HTML body used flex-centering with 24px padding, shifting the
stage below the viewport top.
- Captures now flush to (0,0) via a min-width 1300px media-query wrapper
so the in-browser preview keeps its padding but the capture viewport
does not.
- Shortens bottom-row labels so the stats row no longer overlaps the foot
line at 1200px:
Catalog, Harnesses, Rust plane, MIT / npm: ecc-universal · AgentShield
No other content changes.
Co-authored-by: livlign <livlign@users.noreply.github.com>
* fix: resolve Claude Code Bash hook "cannot execute binary file" on Windows
Root cause in ~/.claude/settings.local.json (user-global):
1. UTF-8 BOM + CRLF line endings left by patch_settings_cl_v2_simple.ps1
2. Double-wrapped command "\"bash.exe\" \"wrapper.sh\"" broke Windows
argument splitting on the space in "Program Files", making bash.exe
try to execute itself as a script.
Fix:
- Rewrite settings.local.json as UTF-8 (no BOM), LF, with the hook command
pointing directly at observe-wrapper.sh and passing "pre"/"post" as a
positional arg so HOOK_PHASE is populated correctly in observe.sh.
Docs:
- docs/fixes/HOOK-FIX-20260421.md — full root-cause analysis.
- docs/fixes/apply-hook-fix.sh — idempotent applier script.
* docs: addendum for HOOK-FIX-20260421 (v2.1.116 argv duplication detail)
- Documents Claude Code v2.1.116 argv duplication bug as the underlying
cause of the bash.exe:bash.exe:cannot execute binary file error
- Records night-session fix variant using explicit `bash <path>` prefix
(matches hooks.json observer pattern, avoids EFTYPE on Node spawn)
- Keeps morning commit 527c18b intact; both variants are now documented
---------
Co-authored-by: suusuu0927 <sugi.go.go.gm@gmail.com>
The SessionStart hook injects the most recent *-session.tmp as
additionalContext labelled only with 'Previous session summary:'.
After a /compact boundary, the model frequently re-executes stale
slash-skill invocations it finds inside that summary, re-running
ARGUMENTS-bearing skills (e.g. /fw-task-new, /fw-raise-pr) with the
last ARGUMENTS they saw.
Observed on claude-opus-4-7 with ECC v1.9.0 on a firmware project:
after compaction resume, the model spontaneously re-enters the prior
skill with stale ARGUMENTS, duplicating GitHub issues, Notion tasks,
and branches for work that is already merged.
ECC cannot fix Claude Code's skill-state replay across compactions,
but it can stop amplifying it. Wrap the injected summary in an
explicit HISTORICAL REFERENCE ONLY preamble with a STALE-BY-DEFAULT
contract and delimit the block with BEGIN/END markers so the model
treats everything inside as frozen reference material.
Tests: update the two hooks.test.js cases that asserted on the old
'Previous session summary' literal to assert on the new guard
preamble, the STALE-BY-DEFAULT contract, and both delimiters. 219/219
tests pass locally.
Tracked at: #1534
* fix(gateguard): rewrite routineBashMsg to use fact-presentation pattern
The imperative 'Quote user's instruction verbatim. Then retry.' phrasing
triggers Claude Code's runtime anti-prompt-injection filter, deadlocking
the first Bash call of every session. The sibling gates (edit, write,
destructive) use multi-point fact-list framing that the runtime accepts.
Align routineBashMsg with that pattern to restore the gate's intended
behavior without changing run(), state schema, or any public API.
Closes#1530
* docs(gateguard): sync SKILL.md routine gate spec with new message format
CodeRabbit flagged that skills/gateguard/SKILL.md still described the
pre-fix imperative message. Update the Routine Bash Gate section to
match the numbered fact-list format used by the new routineBashMsg().
Fixes#1469.
On Windows the `claude` binary installed via `npm i -g @anthropic-ai/claude-code`
is `claude.cmd`, and Node's spawn() cannot resolve .cmd wrappers via PATH
without shell: true. The call failed with `spawn claude ENOENT` and claw.js
returned an error string to the caller.
Mirrors the fix pattern applied in PR #1456 for the MCP health-check hook.
'claude' is a hardcoded literal (not user input), so enabling shell on Windows
only is safe.
`ConvertFrom-Json -AsHashtable` is PowerShell 7+ only, and the Windows 11
reference machine used to validate this PR ships with Windows PowerShell
5.1 only (no `pwsh` on PATH). Without this follow-up, running the
installer on stock Windows fails at the parse step and leaves the
installation half-applied.
- Fall back to a manual `PSCustomObject` -> `Hashtable` conversion when
`-AsHashtable` raises, so the script parses the existing
settings.local.json on both PS 5.1 and PS 7+.
- Normalize both hook buckets (`PreToolUse`, `PostToolUse`) and their
inner `hooks` arrays as `System.Collections.ArrayList` before
serialization. PS 5.1 `ConvertTo-Json` otherwise collapses
single-element arrays into bare objects, which breaks the canonical
PR #1524 shape.
- Create the `skills/continuous-learning/hooks` destination directory
when it does not exist yet, and emit a clearer error if
settings.local.json is missing entirely.
- Update `INSTALL-HOOK-WRAPPER-FIX-20260422.md` to document the PS 5.1
compatibility guarantee and to cross-link PR #1542 (companion simple
patcher).
Verified on Windows 11 / Windows PowerShell 5.1.26100.8115 by running
`powershell -NoProfile -ExecutionPolicy Bypass -File
docs/fixes/install_hook_wrapper.ps1` against a sandbox `$env:USERPROFILE`
and against the real settings.local.json. Both produce the canonical
PR #1524 shape with LF-only output.
- Use PATH-resolved `bash` as first token instead of quoted `.exe` path
so Claude Code v2.1.116 argv duplication does not feed a binary to
bash as its $0 (repro: exit 126 "cannot execute binary file").
- Point the command at `observe-wrapper.sh` and pass distinct `pre` /
`post` positional arguments so PreToolUse and PostToolUse are
registered as separate entries.
- Normalize the wrapper path to forward slashes before embedding in the
hook command to avoid MSYS backslash surprises.
- Write UTF-8 (no BOM) with CRLF normalized to LF so downstream JSON
parsers never see mixed line endings.
- Preserve existing hooks (legacy `observe.sh`, third-party entries)
by appending only when the canonical command string is not already
registered. Re-runs are idempotent ([SKIP] both phases).
- Keep the script compatible with Windows PowerShell 5.1: fall back to
a manual PSCustomObject → Hashtable conversion when
`ConvertFrom-Json -AsHashtable` is unavailable, and materialize hook
arrays as `System.Collections.ArrayList` so single-element arrays
survive PS 5.1 `ConvertTo-Json` serialization.
Companion to PR #1524 (settings.local.json shape fix) and PR #1540
(install_hook_wrapper.ps1 argv-dup fix).
Under Claude Code v2.1.116 the first argv token of a hook command is
duplicated. When the token is a quoted Windows .exe path, bash.exe is
re-invoked with itself as script (exit 126). PR #1524 fixed the shape
of settings.local.json; this script keeps the installer consistent so
re-running it does not regenerate the broken form.
Changes:
- First token is now PATH-resolved `bash` instead of the quoted bash.exe
- Wrapper path is normalized to forward slashes for MSYS safety
- PreToolUse and PostToolUse get distinct pre/post positional arguments
- JSON output is written with LF endings (no mixed CRLF/LF)
Companion doc: docs/fixes/INSTALL-HOOK-WRAPPER-FIX-20260422.md
Re-renders hero.png without the baked-in stars (163k) and forks (25k) numbers
that were drifting from the README's own dynamic badges. Bottom stats now show
repo-derived catalog counts that don't rot: 310 total items (183 skills + 48
agents + 79 commands), 7 harnesses, ECC 2.0α, MIT.
Also shrinks the file from 534 KB to ~131 KB via tighter pngquant settings.
Addresses review comments from cubic and greptile (stat drift) and CodeRabbit
(file size).
Two bugs in skills/continuous-learning-v2/scripts/detect-project.sh that
silently split the same project into multiple project_id records:
1. Locale-dependent SHA-256 input (HIGH)
The project_id hash was computed with
printf '%s' "$hash_input" | python -c 'sys.stdin.buffer.read()'
which ships shell-locale-encoded bytes to Python. On a system with a
non-UTF-8 LC_ALL (e.g. ja_JP.CP932 / CP1252) the same project root
produced a different 12-char hash than the UTF-8 locale would produce,
so observations/instincts were silently written under a separate
project directory. Fixed by passing the value via an env var and
encoding as UTF-8 inside Python, making the hash locale-independent.
2. basename cannot split Windows backslash paths (MEDIUM)
basename "C:\Users\...\ECC作成" returns the whole string on POSIX
bash, so project_name was garbled whenever CLAUDE_PROJECT_DIR was
passed as a native Windows path. Normalize backslashes to forward
slashes before calling basename.
Both the primary project_id hash and the legacy-compat fallback hash
are updated to use the env-var / UTF-8 approach.
Verified: id is stable across en_US.UTF-8, ja_JP.UTF-8, ja_JP.CP932, C,
and POSIX locales; Windows-path input yields project_name=ECC作成;
ASCII-only paths regress-free.
Previously the env fallback ran only when JSON.parse threw. If stdin was valid
JSON but omitted transcript_path or provided a non-string/empty value, the
script dropped to the getSessionIdShort() fallback path, re-introducing the
collision this PR targets.
Validate the parsed transcript_path and apply the env-var fallback for any
unusable value, not just malformed JSON. Matches coderabbit's outside-diff
suggestion and keeps both input-source paths equivalent.
Refs #1494
- Route the transcript-derived shortId through sanitizeSessionId so the
fallback and transcript branches remain byte-for-byte equivalent for any
non-UUID session IDs that still land in CLAUDE_SESSION_ID (greptile P1).
- Clarify the inline comment in the first regression test: clearing
CLAUDE_SESSION_ID exercises the transcript_path branch, not the
getSessionIdShort() fallback (coderabbit P2).
Refs #1494
- Use last-8 chars of transcript UUID instead of first-8, matching
getSessionIdShort()'s .slice(-8) convention. Same session now produces the
same filename whether shortId comes from CLAUDE_SESSION_ID or transcript_path,
so existing .tmp files are not orphaned on upgrade.
- Normalize extracted hex prefix to lowercase to avoid case-driven filename
divergence from sanitizeSessionId()'s lowercase output.
- Explicitly clear CLAUDE_SESSION_ID in the first regression test so the env
leak from parent test runs cannot hide the fallback path.
- Add regression tests for the lowercase-normalization path and for the case
where CLAUDE_SESSION_ID and transcript_path refer to the same UUID (backward
compat guarantee).
Refs #1494
When session-end.js runs and CLAUDE_SESSION_ID is unset, getSessionIdShort()
falls back to the project/worktree name. If any other Stop-hook in the chain
spawns a claude subprocess (e.g. an AI-summary generator using 'claude -p'),
the subprocess also fires the full Stop chain and writes to the same project-
name-based filename, clobbering the parent's valid session summary with a
summary of the summarization prompt itself.
Fix: when stdin JSON (or CLAUDE_TRANSCRIPT_PATH) provides a transcript_path,
extract the first 8 hex chars of the session UUID from the filename and use
that as shortId. Falls back to the original getSessionIdShort() when no
transcript_path is available, so existing behavior is preserved for all
callers that do not set it.
Adds a regression test in tests/hooks/hooks.test.js.
Refs #1494
The Claude Code plugin validator rejects the "agents" field entirely.
Remove it from the manifest, schema, and tests. Update schema notes
to document this as a known constraint alongside the hooks field.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
`findPluginInstall()` in `scripts/harness-audit.js` scans two candidate
roots:
{rootDir}/.claude/plugins/
{HOME}/.claude/plugins/
Current Claude Code marketplace installs live one directory deeper:
{HOME}/.claude/plugins/marketplaces/{ecc,everything-claude-code}/...
As a result, running `node scripts/harness-audit.js repo` on any
consumer project reports `consumer-plugin-install: false` even when ECC
is fully installed via marketplace, costing 4 points from Tool Coverage.
Add the `marketplaces/` intermediate directory to `candidateRoots` so
both legacy and current install layouts are recognized. The change is
purely additive: existing candidate paths still resolve, and the new
ones only match when the marketplace layout is present.
Reproduction:
1. Install ECC via Claude Code plugin marketplace
2. cd into any consumer project
3. node ~/.claude/plugins/marketplaces/everything-claude-code/scripts/harness-audit.js repo
4. Observe consumer-plugin-install=false despite a working install
P2: Description now says "Edit/Write/Bash (including MultiEdit)"
instead of listing MultiEdit as a separate top-level gate
P2: Write Gate and Anti-Patterns now use same "redacted or synthetic
values" wording as Edit Gate (was still "cat one real record")
All 3 gate doc sections now consistent. 9/9 tests pass.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
P1: Gate message asked for raw production data records — changed to
"redacted or synthetic values" to prevent sensitive data exfiltration
P2: SKILL.md description now includes MultiEdit (was missing after
MultiEdit gate was added in previous commit)
P2: Session key pruning now caps __prefixed keys at 50 to prevent
unbounded growth even in theoretical edge cases
9/9 tests pass.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
- isChecked() no longer calls saveState() — read-only operation
should not write to disk (was causing 3x writes per tool call)
- Test cleanup uses fs.rmSync(recursive) instead of fs.rmdirSync
which failed with ENOTEMPTY when .tmp files remained
9/9 tests pass.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
P1 (cubic-dev-ai): Test process PID differs from spawned hook PID,
so test was seeding/clearing wrong state file. Fix: pass fixed
CLAUDE_SESSION_ID='gateguard-test-session' to spawned hooks.
P2 (cubic-dev-ai): Pruning checked array could evict __bash_session__
and other session keys, causing gates to re-fire mid-session. Fix:
preserve __prefixed keys during pruning, only evict file-path entries.
9/9 tests pass.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
P1 bug reported by greptile-apps: MultiEdit uses toolInput.edits[].file_path,
not toolInput.file_path. The gate was silently allowing all MultiEdit calls.
Fix: separate MultiEdit into its own branch that iterates edits array
and gates on the first unchecked file_path.
9/9 tests pass.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Addresses reviewer feedback from @affaan-m:
1. State keyed by CLAUDE_SESSION_ID / ECC_SESSION_ID
- Falls back to pid-based isolation when env vars absent
- State file: state-{sessionId}.json (was .session_state.json)
2. Atomic write+rename semantics
- Write to temp file, then fs.renameSync to final path
- Prevents partial reads from concurrent hooks
3. Bounded checked list (MAX_CHECKED_ENTRIES = 500)
- Prunes to last 500 entries when cap exceeded
- Stale session files auto-deleted after 1 hour
9/9 tests pass.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
- Add `minimal` profile so the security hook runs in all profiles
- Scope -n/--no-verify flag check to the detected subcommand region,
preventing false positives on chained commands (e.g. `git log -n 10`)
- Guard stdin listeners with `require.main === module` so require()
from run-with-flags.js does not register unnecessary listeners
- Verify subcommand token is preceded only by flags/flag-args after
"git", preventing misclassification of argument values as subcommands
- Add integration tests for block-no-verify hook
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Replace inline `npx block-no-verify@1.1.2` with a standalone Node.js
script routed through `run-with-flags.js`, matching every other hook.
Fixes two bugs:
1. npx inherits the project cwd and triggers EBADDEVENGINES in
pnpm-only projects that set devEngines.packageManager.onFail=error.
2. The hook bypassed run-with-flags.js so ECC_DISABLED_HOOKS had no
effect — the isHookEnabled() check never ran.
The new script replicates the full block-no-verify@1.1.2 detection
logic (--no-verify, -n shorthand for commit, core.hooksPath override)
with zero external dependencies.
Closes#1378
Fix two lint issues that cause `npm run lint` to exit non-zero:
1. README.md (MD028): Two consecutive blockquotes separated by a bare
blank line. Markdownlint treats this as one blockquote with an
illegal blank line inside. Replace the blank line with a `>`
continuation so both paragraphs stay in the same blockquote.
2. session-activity-tracker.js (eqeqeq): Three instances of `== null`
replaced with explicit `=== null || === undefined` guards to satisfy
the repo's `eqeqeq: warn` ESLint rule.
Closes#1366
The marketplace is registered externally as `everything-claude-code`,
so the Claude Code CLI looks for a plugin named `everything-claude-code`
within it. Both `.claude-plugin/marketplace.json` and
`.claude-plugin/plugin.json` used the short alias `ecc` for the plugin
`name` field, causing a lookup miss at install/update time:
Error: Plugin everything-claude-code not found in marketplace everything-claude-code
Change the `name` field in both files to match the external identifier.
MultiEdit was bypassing the fact-forcing gate because only Edit and
Write were checked. Now MultiEdit triggers the same edit gate (list
importers, public API, data schemas) before allowing file modifications.
Updated both the hook logic and hooks.json matcher pattern.
Addresses coderabbit/greptile/cubic-dev: "MultiEdit bypasses gate"
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Destructive bash gate previously denied every invocation with no
isChecked call, creating an infinite deny loop. Now gates per-command
on first attempt and allows retry after the model presents the required
facts (targets, rollback plan, user instruction).
Addresses greptile P1: "Destructive bash gate permanently blocks"
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
- GATEGUARD_STATE_DIR env var for test isolation (hook + tests)
- Exit code assertions on all 9 tests (no vacuous passes)
- Non-vacuous allow-path assertions (verify pass-through preserves input)
- Robust newline-injection assertion
- clearState() now reports errors instead of swallowing
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
1. Use run-with-flags.js wrapper (supports ECC_HOOK_PROFILE, ECC_DISABLED_HOOKS)
2. Add session timeout (30min inactivity = state reset, fixes "once ever" bug)
3. Add 9 integration tests (deny/allow/timeout/sanitize/disable)
Refactored hook to module.exports.run() pattern for direct require() by
run-with-flags.js (~50-100ms faster per invocation).
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
- Add ecc_dashboard.py - Tkinter-based GUI for exploring ECC components
- Implement dark/light theme toggle in Settings tab
- Add font family and size customization
- Display project logo in header and taskbar
- Open in maximized window with native title bar
- Add 'dashboard' script to package.json
- Update README with dashboard documentation
Closes #XXX
- Add ecc_dashboard.py - a Tkinter-based GUI for exploring ECC components
- Implement dark/light theme toggle in Settings tab
- Add font family and size customization
- Display project logo in header and taskbar
- Open in maximized window with native title bar
- Add 'dashboard' script to package.json for easy launch
A PreToolUse hook that forces Claude to investigate before editing.
Instead of self-evaluation ("are you sure?"), it demands concrete facts:
importers, public API, data schemas, user instruction.
A/B tested: +2.25 quality points (9.0 vs 6.75) across two independent tasks.
- scripts/hooks/gateguard-fact-force.js — standalone Node.js hook
- skills/gateguard/SKILL.md — skill documentation
- hooks/hooks.json — PreToolUse entries for Edit|Write and Bash
Full package with config: pip install gateguard-ai
Repo: https://github.com/zunoworks/gateguard
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* docs: Enhance README.zh-CN.md with badges and instructions
Updated README.zh-CN.md to include additional badges, improved descriptions, and added new sections for installation and usage instructions.
* Update README.zh-CN.md
Co-authored-by: greptile-apps[bot] <165735046+greptile-apps[bot]@users.noreply.github.com>
* Update README.zh-CN.md
Co-authored-by: greptile-apps[bot] <165735046+greptile-apps[bot]@users.noreply.github.com>
* Update security guide link in README.zh-CN.md
---------
Co-authored-by: greptile-apps[bot] <165735046+greptile-apps[bot]@users.noreply.github.com>
description: Structured self-debugging workflow for AI agent failures using capture, diagnosis, contained recovery, and introspection reports.
---
# Agent Introspection Debugging
Use this skill when an agent run is failing repeatedly, consuming tokens without progress, looping on the same tools, or drifting away from the intended task.
This is a workflow skill, not a hidden runtime. It teaches the agent to debug itself systematically before escalating to a human.
## When to Activate
- Maximum tool call / loop-limit failures
- Repeated retries with no forward progress
- Context growth or prompt drift that starts degrading output quality
- File-system or environment state mismatch between expectation and reality
- Tool failures that are likely recoverable with diagnosis and a smaller corrective action
## Scope Boundaries
Activate this skill for:
- capturing failure state before retrying blindly
- diagnosing common agent-specific failure patterns
- applying contained recovery actions
- producing a structured human-readable debug report
Do not use this skill as the primary source for:
- feature verification after code changes; use `verification-loop`
- framework-specific debugging when a narrower ECC skill already exists
- runtime promises the current harness cannot enforce automatically
## Four-Phase Loop
### Phase 1: Failure Capture
Before trying to recover, record the failure precisely.
Capture:
- error type, message, and stack trace when available
- last meaningful tool call sequence
- what the agent was trying to do
- current context pressure: repeated prompts, oversized pasted logs, duplicated plans, or runaway notes
- current environment assumptions: cwd, branch, relevant service state, expected files
Minimum capture template:
```markdown
## Failure Capture
- Session / task:
- Goal in progress:
- Error:
- Last successful step:
- Last failed tool / command:
- Repeated pattern seen:
- Environment assumptions to verify:
```
### Phase 2: Root-Cause Diagnosis
Match the failure to a known pattern before changing anything.
| Pattern | Likely Cause | Check |
| --- | --- | --- |
| Maximum tool calls / repeated same command | loop or no-exit observer path | inspect the last N tool calls for repetition |
| `ECONNREFUSED` / timeout | service unavailable or wrong port | verify service health, URL, and port assumptions |
| `429` / quota exhaustion | retry storm or missing backoff | count repeated calls and inspect retry spacing |
| file missing after write / stale diff | race, wrong cwd, or branch drift | re-check path, cwd, git status, and actual file existence |
| tests still failing after “fix” | wrong hypothesis | isolate the exact failing test and re-derive the bug |
Diagnosis questions:
- is this a logic failure, state failure, environment failure, or policy failure?
- did the agent lose the real objective and start optimizing the wrong subtask?
- is the failure deterministic or transient?
- what is the smallest reversible action that would validate the diagnosis?
### Phase 3: Contained Recovery
Recover with the smallest action that changes the diagnosis surface.
Safe recovery actions:
- stop repeated retries and restate the hypothesis
- trim low-signal context and keep only the active goal, blockers, and evidence
- re-check the actual filesystem / branch / process state
- narrow the task to one failing command, one file, or one test
- switch from speculative reasoning to direct observation
- escalate to a human when the failure is high-risk or externally blocked
Do not claim unsupported auto-healing actions like “reset agent state” or “update harness config” unless you are actually doing them through real tools in the current environment.
Contained recovery checklist:
```markdown
## Recovery Action
- Diagnosis chosen:
- Smallest action taken:
- Why this is safe:
- What evidence would prove the fix worked:
```
### Phase 4: Introspection Report
End with a report that makes the recovery legible to the next agent or human.
```markdown
## Agent Self-Debug Report
- Session / task:
- Failure:
- Root cause:
- Recovery action:
- Result: success | partial | blocked
- Token / time burn risk:
- Follow-up needed:
- Preventive change to encode later:
```
## Recovery Heuristics
Prefer these interventions in order:
1. Restate the real objective in one sentence.
2. Verify the world state instead of trusting memory.
3. Shrink the failing scope.
4. Run one discriminating check.
5. Only then retry.
Bad pattern:
- retrying the same action three times with slightly different wording
Good pattern:
- capture failure
- classify the pattern
- run one direct check
- change the plan only if the check supports it
## Integration with ECC
- Use `verification-loop` after recovery if code was changed.
- Use `continuous-learning-v2` when the failure pattern is worth turning into an instinct or later skill.
- Use `council` when the issue is not technical failure but decision ambiguity.
- Use `workspace-surface-audit` if the failure came from conflicting local state or repo drift.
## Output Standard
When this skill is active, do not end with “I fixed it” alone.
Always provide:
- the failure pattern
- the root-cause hypothesis
- the recovery action
- the evidence that the situation is now better or still blocked
description: Build an evidence-backed ECC install plan for a specific repo by sorting skills, commands, rules, hooks, and extras into DAILY vs LIBRARY buckets using parallel repo-aware review passes. Use when ECC should be trimmed to what a project actually needs instead of loading the full bundle.
---
# Agent Sort
Use this skill when a repo needs a project-specific ECC surface instead of the default full install.
The goal is not to guess what "feels useful." The goal is to classify ECC components with evidence from the actual codebase.
## When to Use
- A project only needs a subset of ECC and full installs are too noisy
- The repo stack is clear, but nobody wants to hand-curate skills one by one
- A team wants a repeatable install decision backed by grep evidence instead of opinion
- You need to separate always-loaded daily workflow surfaces from searchable library/reference surfaces
- A repo has drifted into the wrong language, rule, or hook set and needs cleanup
## Non-Negotiable Rules
- Use the current repository as the source of truth, not generic preferences
- Every DAILY decision must cite concrete repo evidence
- LIBRARY does not mean "delete"; it means "keep accessible without loading by default"
- Do not install hooks, rules, or scripts that the current repo cannot use
- Prefer ECC-native surfaces; do not introduce a second install system
## Outputs
Produce these artifacts in order:
1. DAILY inventory
2. LIBRARY inventory
3. install plan
4. verification report
5. optional `skill-library` router if the project wants one
## Classification Model
Use two buckets only:
-`DAILY`
- should load every session for this repo
- strongly matched to the repo's language, framework, workflow, or operator surface
-`LIBRARY`
- useful to retain, but not worth loading by default
- should remain reachable through search, router skill, or selective manual use
## Evidence Sources
Use repo-local evidence before making any classification:
description: REST API design patterns including resource naming, status codes, pagination, filtering, error responses, versioning, and rate limiting for production APIs.
description: Write articles, guides, blog posts, tutorials, newsletter issues, and other long-form content in a distinctive voice derived from supplied examples or brand guidance. Use when the user wants polished written content longer than a paragraph, especially when voice consistency, structure, and credibility matter.
description: Backend architecture patterns, API design, database optimization, and server-side best practices for Node.js, Express, and Next.js API routes.
description: Build a source-derived writing style profile from real posts, essays, launch notes, docs, or site copy, then reuse that profile across content, outreach, and social workflows. Use when the user wants voice consistency without generic AI writing tropes.
description: Anthropic Claude API patterns for Python and TypeScript. Covers Messages API, streaming, tool use, vision, extended thinking, batches, prompt caching, and Claude Agent SDK. Use when building applications with the Claude API or Anthropic SDKs.
description: Universal coding standards, best practices, and patterns for TypeScript, JavaScript, React, and Node.js development.
origin: ECC
description: Baseline cross-project coding conventions for naming, readability, immutability, and code-quality review. Use detailed frontend or backend skills for framework-specific patterns.
---
# Coding Standards & Best Practices
Universal coding standards applicable across all projects.
Baseline coding conventions applicable across projects.
This skill is the shared floor, not the detailed framework playbook.
- Use `frontend-patterns` for React, state, forms, rendering, and UI architecture.
- Use `backend-patterns` or `api-design` for repository/service layers, endpoint design, validation, and server-specific concerns.
- Use `rules/common/coding-style.md` when you need the shortest reusable rule layer instead of a full skill walkthrough.
## When to Activate
@@ -17,6 +22,19 @@ Universal coding standards applicable across all projects.
- Setting up linting, formatting, or type-checking rules
- Onboarding new contributors to coding conventions
## Scope Boundaries
Activate this skill for:
- descriptive naming
- immutability defaults
- readability, KISS, DRY, and YAGNI enforcement
- error-handling expectations and code-smell review
Do not use this skill as the primary source for:
- React composition, hooks, or rendering patterns
- backend architecture, API design, or database layering
- domain-specific framework guidance when a narrower ECC skill already exists
description: Create platform-native content systems for X, LinkedIn, TikTok, YouTube, newsletters, and repurposed multi-platform campaigns. Use when the user wants social posts, threads, scripts, content calendars, or one source asset adapted cleanly across platforms.
description: Multi-platform content distribution across X, LinkedIn, Threads, and Bluesky. Adapts content per platform using content-engine patterns. Never posts identical content cross-platform. Use when the user wants to distribute content across social platforms.
description: Multi-source deep research using firecrawl and exa MCPs. Searches the web, synthesizes findings, and delivers cited reports with source attribution. Use when the user wants thorough research on any topic with evidence and citations.
description: Multi-agent orchestration using dmux (tmux pane manager for AI agents). Patterns for parallel agent workflows across Claude Code, Codex, OpenCode, and other harnesses. Use when running multiple agent sessions in parallel or coordinating multi-agent development workflows.
description: Use up-to-date library and framework docs via Context7 MCP instead of training data. Activates for setup questions, API references, code examples, or when the user names a framework (e.g. React, Next.js, Prisma).
description: Neural search via Exa MCP for web, code, and company research. Use when the user needs web search, code examples, company intel, people lookup, or AI-powered deep research with Exa's neural search engine.
description: Unified media generation via fal.ai MCP — image, video, and audio. Covers text-to-image (Nano Banana), text/image-to-video (Seedance, Kling, Veo 3), text-to-speech (CSM-1B), and video-to-audio (ThinkSound). Use when the user wants to generate images, videos, or audio with AI.
description: Create distinctive, production-grade frontend interfaces with high design quality. Use when the user asks to build web components, pages, or applications and the visual direction matters as much as the code quality.
---
# Frontend Design
Use this when the task is not just "make it work" but "make it look designed."
This skill is for product pages, dashboards, app shells, components, or visual systems that need a clear point of view instead of generic AI-looking UI.
## When To Use
- building a landing page, dashboard, or app surface from scratch
- upgrading a bland interface into something intentional and memorable
- translating a product concept into a concrete visual direction
- implementing a frontend where typography, composition, and motion matter
## Core Principle
Pick a direction and commit to it.
Safe-average UI is usually worse than a strong, coherent aesthetic with a few bold choices.
## Design Workflow
### 1. Frame the interface first
Before coding, settle:
- purpose
- audience
- emotional tone
- visual direction
- one thing the user should remember
Possible directions:
- brutally minimal
- editorial
- industrial
- luxury
- playful
- geometric
- retro-futurist
- soft and organic
- maximalist
Do not mix directions casually. Choose one and execute it cleanly.
### 2. Build the visual system
Define:
- type hierarchy
- color variables
- spacing rhythm
- layout logic
- motion rules
- surface / border / shadow treatment
Use CSS variables or the project's token system so the interface stays coherent as it grows.
### 3. Compose with intention
Prefer:
- asymmetry when it sharpens hierarchy
- overlap when it creates depth
- strong whitespace when it clarifies focus
- dense layouts only when the product benefits from density
Avoid defaulting to a symmetrical card grid unless it is clearly the right fit.
### 4. Make motion meaningful
Use animation to:
- reveal hierarchy
- stage information
- reinforce user action
- create one or two memorable moments
Do not scatter generic micro-interactions everywhere. One well-directed load sequence is usually stronger than twenty random hover effects.
## Strong Defaults
### Typography
- pick fonts with character
- pair a distinctive display face with a readable body face when appropriate
- avoid generic defaults when the page is design-led
### Color
- commit to a clear palette
- one dominant field with selective accents usually works better than evenly weighted rainbow palettes
- avoid cliché purple-gradient-on-white unless the product genuinely calls for it
### Background
Use atmosphere:
- gradients
- meshes
- textures
- subtle noise
- patterns
- layered transparency
Flat empty backgrounds are rarely the best answer for a product-facing page.
### Layout
- break the grid when the composition benefits from it
- use diagonals, offsets, and grouping intentionally
- keep reading flow obvious even when the layout is unconventional
## Anti-Patterns
Never default to:
- interchangeable SaaS hero sections
- generic card piles with no hierarchy
- random accent colors without a system
- placeholder-feeling typography
- motion that exists only because animation was easy to add
## Execution Rules
- preserve the established design system when working inside an existing product
- match technical complexity to the visual idea
- keep accessibility and responsiveness intact
- frontends should feel deliberate on desktop and mobile
## Quality Gate
Before delivering:
- the interface has a clear visual point of view
- typography and spacing feel intentional
- color and motion support the product instead of decorating it randomly
- the result does not read like generic AI UI
- the implementation is production-grade, not just visually interesting
description: Create stunning, animation-rich HTML presentations from scratch or by converting PowerPoint files. Use when the user wants to build a presentation, convert a PPT/PPTX to web, or create slides for a talk/pitch. Helps non-designers discover their aesthetic through visual exploration rather than abstract choices.
description: Create and update pitch decks, one-pagers, investor memos, accelerator applications, financial models, and fundraising materials. Use when the user needs investor-facing documents, projections, use-of-funds tables, milestone plans, or materials that must stay internally consistent across multiple fundraising assets.
description: Draft cold emails, warm intro blurbs, follow-ups, update emails, and investor communications for fundraising. Use when the user wants outreach to angels, VCs, strategic investors, or accelerators and needs concise, personalized, investor-facing messaging.
description: Conduct market research, competitive analysis, investor due diligence, and industry intelligence with source attribution and decision-oriented summaries. Use when the user wants market sizing, competitor comparisons, fund research, technology scans, or research that informs business decisions.
description: Build MCP servers with Node/TypeScript SDK — tools, resources, prompts, Zod validation, stdio vs Streamable HTTP. Use Context7 or official MCP docs for latest API.
description: Translate PRD intent, roadmap asks, or product discussions into an implementation-ready capability plan that exposes constraints, invariants, interfaces, and unresolved decisions before multi-service work starts. Use when the user needs an ECC-native PRD-to-SRS lane instead of vague planning prose.
---
# Product Capability
This skill turns product intent into explicit engineering constraints.
Use it when the gap is not "what should we build?" but "what exactly must be true before implementation starts?"
## When to Use
- A PRD, roadmap item, discussion, or founder note exists, but the implementation constraints are still implicit
- A feature crosses multiple services, repos, or teams and needs a capability contract before coding
- Product intent is clear, but architecture, data, lifecycle, or policy implications are still fuzzy
- Senior engineers keep restating the same hidden assumptions during review
- You need a reusable artifact that can survive across harnesses and sessions
## Canonical Artifact
If the repo has a durable product-context file such as `PRODUCT.md`, `docs/product/`, or a program-spec directory, update it there.
If no capability manifest exists yet, create one using the template at:
-`docs/examples/product-capability-template.md`
The goal is not to create another planning stack. The goal is to make hidden capability constraints durable and reusable.
## Non-Negotiable Rules
- Do not invent product truth. Mark unresolved questions explicitly.
- Separate user-visible promises from implementation details.
- Call out what is fixed policy, what is architecture preference, and what is still open.
- If the request conflicts with existing repo constraints, say so clearly instead of smoothing it over.
- Prefer one reusable capability artifact over scattered ad hoc notes.
description: Use this skill when adding authentication, handling user input, working with secrets, creating API endpoints, or implementing payment/sensitive features. Provides comprehensive security checklist and patterns.
description: Use this skill when writing new features, fixing bugs, or refactoring code. Enforces test-driven development with 80%+ coverage including unit, integration, and E2E tests.
description: AI-assisted video editing workflows for cutting, structuring, and augmenting real footage. Covers the full pipeline from raw capture through FFmpeg, Remotion, ElevenLabs, fal.ai, and final polish in Descript or CapCut. Use when the user wants to edit video, cut footage, create vlogs, or build video content.
description: X/Twitter API integration for posting tweets, threads, reading timelines, search, and analytics. Covers OAuth auth patterns, rate limits, and platform-native content posting. Use when the user wants to interact with X programmatically.
Even if there is only one entry, **strings are not accepted**.
### Invalid
```json
{
"agents":"./agents"
}
```
### Valid
```json
{
"agents":["./agents/planner.md"]
}
```
This applies consistently across all component path fields.
---
## Path Resolution Rules (Critical)
## The `agents` Field: DO NOT ADD
### Agents MUST use explicit file paths
> WARNING: **CRITICAL:** Do NOT add an `"agents"` field to `plugin.json`. The Claude Code plugin validator rejects it entirely.
The validator **does not accept directory paths for `agents`**.
### Why This Matters
Even the following will fail:
The `agents` field is not part of the Claude Code plugin manifest schema. Any form of it -- string path, array of paths, or array of directories -- causes a validation error:
```json
{
"agents":["./agents/"]
}
```
agents: Invalid input
```
Instead, you must enumerate agent files explicitly:
Agent `.md` files under `agents/` are discovered automatically by convention (similar to hooks). They do not need to be declared in the manifest.
```json
{
"agents":[
"./agents/planner.md",
"./agents/architect.md",
"./agents/code-reviewer.md"
]
}
```
### History
This is the most common source of validation errors.
Previously this repo listed agents explicitly in `plugin.json` as an array of file paths. This passed the repo's own schema but failed Claude Code's actual validator, which does not recognize the field. Removed in #1459.
---
## Path Resolution Rules
### Commands and Skills
@@ -160,7 +137,7 @@ The test `plugin.json does NOT have explicit hooks declaration` in `tests/hooks/
These look correct but are rejected:
* String values instead of arrays
*Arrays of directories for `agents`
***Adding `"agents"` in any form** - not a recognized manifest field, causes `Invalid input`
* Missing `version`
* Relying on inferred paths
* Assuming marketplace behavior matches local validation
@@ -175,10 +152,6 @@ Avoid cleverness. Be explicit.
```json
{
"version":"1.1.0",
"agents":[
"./agents/planner.md",
"./agents/code-reviewer.md"
],
"commands":["./commands/"],
"skills":["./skills/"]
}
@@ -186,7 +159,7 @@ Avoid cleverness. Be explicit.
This structure has been validated against the Claude plugin validator.
**Important:** Notice there is NO `"hooks"` field. The `hooks/hooks.json` file is loaded automatically by convention. Adding it explicitly causes a duplicate error.
**Important:** Notice there is NO `"hooks"` field and NO `"agents"` field. Both are loaded automatically by convention. Adding either explicitly causes errors.
---
@@ -194,9 +167,9 @@ This structure has been validated against the Claude plugin validator.
Before submitting changes that touch `plugin.json`:
1.Use explicit file paths for agents
2.Ensure all component fields are arrays
3.Include a `version`
1.Ensure all component fields are arrays
2.Include a `version`
3.Do NOT add `agents` or `hooks` fields (both are auto-loaded by convention)
If you plan to edit `.claude-plugin/plugin.json`, be aware that the Claude plugin validator enforces several **undocumented but strict constraints** that can cause installs to fail with vague errors (for example, `agents: Invalid input`). In particular, component fields must be arrays, `agents`must use explicit file paths rather than directories, and a `version` field is required for reliable validation and installation.
If you plan to edit `.claude-plugin/plugin.json`, be aware that the Claude plugin validator enforces several **undocumented but strict constraints** that can cause installs to fail with vague errors (for example, `agents: Invalid input`). In particular, component fields must be arrays, `agents`is not a supported manifest field and must not be included in plugin.json, and a `version` field is required for reliable validation and installation.
These constraints are not obvious from public examples and have caused repeated installation failures in the past. They are documented in detail in `.claude-plugin/PLUGIN_SCHEMA_NOTES.md`, which should be reviewed before making any changes to the plugin manifest.
"description":"Battle-tested Claude Code configurations from an Anthropic hackathon winner — agents, skills, hooks, rules, and legacy command shims evolved over 10+ months of intensive daily use",
"owner":{
"name":"Affaan Mustafa",
"email":"me@affaanmustafa.com"
@@ -13,8 +11,8 @@
{
"name":"everything-claude-code",
"source":"./",
"description":"The most comprehensive Claude Code plugin — 38 agents, 156 skills, 72 legacy command shims, selective install profiles, and production-ready hooks for TDD, security scanning, code review, and continuous learning",
"version":"1.10.0",
"description":"The most comprehensive Claude Code plugin — 48 agents, 184 skills, 79 legacy command shims, selective install profiles, and production-ready hooks for TDD, security scanning, code review, and continuous learning",
description: Create implementation plan with risk assessment
agent: planner
agent: everything-claude-code:planner
subtask: true
---
Some files were not shown because too many files have changed in this diff
Show More
Reference in New Issue
Block a user
Blocking a user prevents them from interacting with repositories, such as opening or commenting on pull requests or issues. Learn more about blocking a user.