docs: Add repo assessment, commands reference, and evaluation docs #986
+524
−0
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,47 @@ | ||
| # 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 |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,159 @@ | ||
| # 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 | ||
| ``` | ||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change | ||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| @@ -0,0 +1,122 @@ | ||||||||||||||||||
| # Repo Evaluation vs Current Setup | ||||||||||||||||||
|
|
||||||||||||||||||
| **Date:** 2026-03-21 | ||||||||||||||||||
| **Branch:** `claude/evaluate-repo-comparison-ASZ9Y` | ||||||||||||||||||
|
Contributor
There was a problem hiding this comment.
Line 4 hard-codes
Suggested change
|
||||||||||||||||||
|
|
||||||||||||||||||
| --- | ||||||||||||||||||
|
|
||||||||||||||||||
| ## 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 | | ||||||||||||||||||
|
Comment on lines
+33
to
+45
Contributor
There was a problem hiding this comment.
The same discrepancy appears in |
||||||||||||||||||
|
|
||||||||||||||||||
| --- | ||||||||||||||||||
|
|
||||||||||||||||||
| ## 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. | ||||||||||||||||||
|
Comment on lines
+92
to
+98
Contributor
There was a problem hiding this comment.
The correct two-step invocation, consistent with The same problem applies to the full-profile block (
Suggested change
|
||||||||||||||||||
|
|
||||||||||||||||||
| ### 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. | ||||||||||||||||||
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
The header claims "59 slash commands", but
AGENTS.mdsays 60. More concretely,/tddappears in both Core Workflow (line 14) and Testing (line 25),/code-reviewin both Core Workflow (line 16) and Code Review (line 38), and/planin both Core Workflow (line 13) and Planning & Architecture (line 59). Each duplicate inflates the apparent command count without adding information.Consider either (a) removing the duplicates from "Core Workflow" and keeping them only in their category section, or (b) adding a note like (see Testing) to make the cross-listing intentional and clear.