ears init
- Repo stars 0
- Author repo skills-registry
- Domain
- Other
- Author-declared agents
- No explicit declaration found; this is not inferred or tested compatibility
- Static check
- 88 / 100 · heuristic scan, not runtime safety proof
- Runtime evidence
- Not run; no isolated runtime test evidence is currently recorded
- Author / version / license
- @tomevault-io · no license declared
- Token usage
- Lean
- Setup complexity
- Guided setup
- External API key
- Not required
- Operating systems
- macOS · Linux · Windows
- Runtime requirements
- Node.js · Python
- Detected file/system behavior
-
- Read-only
- Write / modify
- Network behavior
- Local-only
- Install commands
- None (reference only)
Heads up: Tool permissions are not declared; actual access depends on the runtime.
Scan the project to build a profile: Detect language and framework: Look for `package.json` → Node.js/TypeScript Look for `pyproject.toml` or `setup.py` or `requirements.txt` → Python Look for `Cargo.toml` → Rust
Use the project analysis to fill in a CLAUDE.md. Use the template from this plugin's `templates/PROJECT-CLAUDE.md` as the base structure. If CLAUDE.md already exists: Read it fully Check if it has an EARS section If no EARS section: offer to append the EARS block
Create the directory structure and files: `traces/` directory — create if missing Initial trace.md — ask user for the current task name, create `traces/<task-name>/trace.md`: `KNOWN_ISSUES.md` — create from template if missing `LEARNING.md` — create if missing:
Ask the user: "Do you use Cursor or Codex for this project? I can generate EARS rules for them too." If Cursor is used: Generate `.cursor/rules/ears-project.mdc` (create `.cursor/rules/` if needed): Use the `templates/cursor-ears.mdc` template Fill in project name and tech stack
Check if `~/.claude/scripts/ears-trace.py` exists If it exists, inform the user about the improved hook in the Synapse plugin Offer to install/upgrade: Copy `hooks/ears-trace.py` from the plugin to `~/.claude/scripts/ears-trace.py` Verify `~/.claude/settings.json` has PostToolUse hooks configured
# EARS Init: Project-Aware EARS Initialization
Analyze the current project and generate customized EARS configuration files so that Claude Code (and optionally Cursor and Codex) can capture knowledge effectively.
## When to Use
- Starting work on a new project that has no EARS setup
- Onboarding a project that another developer started
- Upgrading a project from generic EARS to project-specific EARS
- After significant project restructuring
## Workflow
### Phase 1: Project Analysis
Scan the project to build a profile:
1. **Detect language and framework:**
- Look for `package.json` → Node.js/TypeScript
- Look for `pyproject.toml` or `setup.py` or `requirements.txt` → Python
- Look for `Cargo.toml` → Rust
- Look for `go.mod` → Go
- Look for `pom.xml` or `build.gradle` → Java/Kotlin
- Look for `*.sln` or `*.csproj` → C#/.NET
- Look for `Makefile` + `*.c`/`*.cpp`/`*.h` → C/C++
- Look for `Gemfile` → Ruby
- Look for `mix.exs` → Elixir
- Multiple matches = polyglot project
2. **Detect build commands:**
- `package.json` → read `scripts` (build, test, dev, start)
- `pyproject.toml` → read `[project.scripts]` and `[tool.pytest]`
- `Makefile` → list top-level targets
- `Cargo.toml` → `cargo build`, `cargo test`
- `go.mod` → `go build`, `go test`
3. **Detect test commands:**
- Python: `pytest`, `python -m unittest`, `tox`
- Node.js: `jest`, `vitest`, `mocha`, `npm test`
- Rust: `cargo test`
- Go: `go test ./...`
- Java: `mvn test`, `gradle test`
4. **Understand architecture:**
- List top-level directories with brief descriptions
- Read existing README.md for project overview
- Identify key patterns (monorepo, MVC, microservices, library, CLI tool, etc.)
5. **Check for existing EARS artifacts:**
- `CLAUDE.md` → exists? has EARS section?
- `KNOWN_ISSUES.md` → exists?
- `LEARNING.md` → exists?
- `traces/` → exists? has content?
- `ears-config.json` → exists?
- `.cursor/rules/` → has EARS rules?
- `AGENTS.md` → exists?
### Phase 2: Generate Project CLAUDE.md
Use the project analysis to fill in a CLAUDE.md. Use the template from this plugin's `templates/PROJECT-CLAUDE.md` as the base structure.
**If CLAUDE.md already exists:**
- Read it fully
- Check if it has an EARS section
- If no EARS section: offer to append the EARS block
- If has EARS section: compare and offer to update
- NEVER overwrite existing content without asking
**If CLAUDE.md does not exist:**
- Generate a complete one using the template
- Fill in all placeholders from the analysis:
- Project name from package manifest or directory name
- Overview from README.md or directory structure
- Build & test commands from detected tools
- Architecture from directory scan
- EARS section fully populated
**The EARS section must include:**
- PostToolUse hook behavior explanation
- All three entry formats (Error, Checkpoint, Dead End) with examples
- Four-tier knowledge architecture with promotion rules
- "How to respond" guidance when seeing `[EARS]` prompts
- Project-specific error patterns to watch for
### Phase 3: Create EARS Skeleton
Create the directory structure and files:
1. **`traces/` directory** — create if missing
2. **Initial trace.md** — ask user for the current task name, create `traces/<task-name>/trace.md`:
```markdown
# Trace: <task-name>
Started: <current timestamp>
```
3. **`KNOWN_ISSUES.md`** — create from template if missing
4. **`LEARNING.md`** — create if missing:
```markdown
# Learning Log
Tech decisions, new concepts, mistakes, and lessons for this project.
```
5. **`ears-config.json`** — create with project-specific error patterns:
For **Python** projects:
```json
{
"error_patterns": [
"Traceback (most recent call last)",
"SyntaxError:", "TypeError:", "ValueError:", "KeyError:",
"IndexError:", "AttributeError:", "ImportError:",
"ModuleNotFoundError:", "FileNotFoundError:", "RuntimeError:",
"AssertionError:", "PermissionError:", "ConnectionError:"
],
"checkpoint_interval": 10,
"error_cooldown_seconds": 120,
"checkpoint_cooldown_seconds": 600,
"ignore_paths": [".claude/", ".git/", "__pycache__/", ".venv/", ".mypy_cache/"]
}
```
For **Node.js/TypeScript** projects:
```json
{
"error_patterns": [
"ReferenceError:", "TypeError:", "SyntaxError:", "RangeError:",
"ENOENT:", "EACCES:", "ECONNREFUSED:", "ERR_MODULE_NOT_FOUND",
"Cannot find module", "Unexpected token", "FATAL ERROR:",
"UnhandledPromiseRejection"
],
"checkpoint_interval": 10,
"error_cooldown_seconds": 120,
"checkpoint_cooldown_seconds": 600,
"ignore_paths": [".git/", "node_modules/", "dist/", ".next/", "coverage/"]
}
```
For **Rust** projects:
```json
{
"error_patterns": [
"error[E", "panicked at", "fatal runtime error",
"thread 'main' panicked", "cannot find", "mismatched types",
"borrow of moved value", "lifetime"
],
"checkpoint_interval": 10,
"error_cooldown_seconds": 120,
"checkpoint_cooldown_seconds": 600,
"ignore_paths": [".git/", "target/"]
}
```
For **Go** projects:
```json
{
"error_patterns": [
"panic:", "fatal error:", "undefined:", "cannot use",
"too many arguments", "not enough arguments",
"imported and not used", "declared and not used"
],
"checkpoint_interval": 10,
"error_cooldown_seconds": 120,
"checkpoint_cooldown_seconds": 600,
"ignore_paths": [".git/", "vendor/"]
}
```
For **other/mixed** projects: use the default patterns from the hook.
### Phase 4: Multi-Tool Setup (Optional)
Ask the user: "Do you use Cursor or Codex for this project? I can generate EARS rules for them too."
**If Cursor is used:**
Generate `.cursor/rules/ears-project.mdc` (create `.cursor/rules/` if needed):
- Use the `templates/cursor-ears.mdc` template
- Fill in project name and tech stack
- Set `alwaysApply: true`
**If Codex is used:**
Generate project-level `AGENTS.md`:
- Use the `templates/PROJECT-AGENTS.md` template
- Fill in project overview, build/test commands, architecture
- Include EARS instructions
### Phase 5: Hook Check (Optional)
1. Check if `~/.claude/scripts/ears-trace.py` exists
2. If it exists, inform the user about the improved hook in the Synapse plugin
3. Offer to install/upgrade:
- Copy `hooks/ears-trace.py` from the plugin to `~/.claude/scripts/ears-trace.py`
- Verify `~/.claude/settings.json` has PostToolUse hooks configured
4. If the user declines, that's fine — the existing hook works, just without auto-discovery
## Output Summary
After completion, display a summary:
```
EARS initialized for <project-name>:
- CLAUDE.md: <created | updated | already exists>
- traces/<task>/trace.md: created
- KNOWN_ISSUES.md: <created | already exists>
- LEARNING.md: <created | already exists>
- ears-config.json: created (<tech-stack> patterns)
- Cursor rules: <created | skipped>
- Codex AGENTS.md: <created | skipped>
- Hook: <upgraded | current | skipped>
You're ready to go. EARS will automatically prompt you to record
errors, checkpoints, discoveries, and dead ends as you work.
```
## Important Principles
- **Never overwrite** existing files without asking
- **Merge, don't replace** — append EARS sections to existing CLAUDE.md
- **Project-specific** — error patterns, ignore paths, and commands should reflect the actual project
- **Minimal by default** — only create what's needed, ask before adding optional pieces
- **Respect existing setup** — if the project already has EARS, offer upgrades, don't force changes
---
> Source: [CHOSENX-GPU/synapse](https://github.com/CHOSENX-GPU/synapse) — distributed by [TomeVault](https://tomevault.io).
<!-- tomevault:4.0:skill_md:2026-05-23 -->
Listed in source order.
sections -> When to Use → Workflow → Phase 1: Project Analysis → Phase 2: Generate Project CLAUDE.md → Phase 3: Create EARS Skeleton → Phase 4: Multi-Tool Setup (Optional)
terms -> Detect language and framework · Detect build commands · Detect test commands · Understand architecture · Check for existing EARS artifacts · If CLAUDE.md already exists · If CLAUDE.md does not exist · The EARS section must include
files/cmd -> package.json · pyproject.toml · setup.py · requirements.txt · Cargo.toml · go.mod · pom.xml · build.gradle
body sha256 -> 1bf50150c137
When to Use
Starting work on a new project that has no EARS setup Onboarding a project that another developer started Upgrading a project from generic EARS to project-specific EARS After significant project restructuring
Phase 1: Project Analysis
Scan the project to build a profile: Detect language and framework: Look for
package.json→ Node.js/TypeScript Look forpyproject.tomlorsetup.pyorrequirements.txt→ Python Look forCargo.toml→ RustPhase 2: Generate Project CLAUDE.md
Use the project analysis to fill in a CLAUDE.md. Use the template from this plugin's
templates/PROJECT-CLAUDE.mdas the base structure. If CLAUDE.md already exists: Read it fully Check if it has an EARS section If no EARS section: offer to append the EARS blockPhase 3: Create EARS Skeleton
Create the directory structure and files:
traces/directory — create if missing Initial trace.md — ask user for the current task name, createtraces/<task-name>/trace.md:KNOWN_ISSUES.md— create from template if missingLEARNING.md— create if missing:Phase 4: Multi-Tool Setup (Optional)
Ask the user: "Do you use Cursor or Codex for this project? I can generate EARS rules for them too." If Cursor is used: Generate
.cursor/rules/ears-project.mdc(create.cursor/rules/if needed): Use thetemplates/cursor-ears.mdctemplate Fill in project name and tech stack