Skip to content

Commit 64847d0

Browse files
affaan-maffaan-m
authored
Merge pull request #986 from Infiniteyieldai/claude/evaluate-repo-comparison-ASZ9Y
docs: Add repo assessment, commands reference, and evaluation docs
2 parents a3fc90f + c865d4c commit 64847d0

File tree

4 files changed

+524
-0
lines changed

4 files changed

+524
-0
lines changed

‎.claude/rules/node.md‎

Lines changed: 47 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,47 @@
1+
# Node.js Rules for everything-claude-code
2+
3+
> Project-specific rules for the ECC codebase. Extends common rules.
4+
5+
## Stack
6+
7+
- **Runtime**: Node.js >=18 (no transpilation, plain CommonJS)
8+
- **Test runner**: `node tests/run-all.js` — individual files via `node tests/**/*.test.js`
9+
- **Linter**: ESLint (`@eslint/js`, flat config)
10+
- **Coverage**: c8
11+
- **Lint**: markdownlint-cli for `.md` files
12+
13+
## File Conventions
14+
15+
- `scripts/` — Node.js utilities, hooks. CommonJS (`require`/`module.exports`)
16+
- `agents/`, `commands/`, `skills/`, `rules/` — Markdown with YAML frontmatter
17+
- `tests/` — Mirror the `scripts/` structure. Test files named `*.test.js`
18+
- File naming: **lowercase with hyphens** (e.g. `session-start.js`, `post-edit-format.js`)
19+
20+
## Code Style
21+
22+
- CommonJS only — no ESM (`import`/`export`) unless file ends in `.mjs`
23+
- No TypeScript — plain `.js` throughout
24+
- Prefer `const` over `let`; never `var`
25+
- Keep hook scripts under 200 lines — extract helpers to `scripts/lib/`
26+
- All hooks must `exit 0` on non-critical errors (never block tool execution unexpectedly)
27+
28+
## Hook Development
29+
30+
- 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
31+
- Async hooks: mark `"async": true` in `settings.json` with a timeout ≤30s
32+
- Blocking hooks (PreToolUse, stop): keep fast (<200ms) — no network calls
33+
- Use `run-with-flags.js` wrapper for all hooks so `ECC_HOOK_PROFILE` and `ECC_DISABLED_HOOKS` runtime gating works
34+
- Always exit 0 on parse errors; log to stderr with `[HookName]` prefix
35+
36+
## Testing Requirements
37+
38+
- Run `node tests/run-all.js` before committing
39+
- New scripts in `scripts/lib/` require a matching test in `tests/lib/`
40+
- New hooks require at least one integration test in `tests/hooks/`
41+
42+
## Markdown / Agent Files
43+
44+
- Agents: YAML frontmatter with `name`, `description`, `tools`, `model`
45+
- Skills: sections — When to Use, How It Works, Examples
46+
- Commands: `description:` frontmatter line required
47+
- Run `npx markdownlint-cli '**/*.md' --ignore node_modules` before committing

‎COMMANDS-QUICK-REF.md‎

Lines changed: 159 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,159 @@
1+
# Commands Quick Reference
2+
3+
> 59 slash commands installed globally. Type `/` in any Claude Code session to invoke.
4+
5+
---
6+
7+
## Core Workflow
8+
9+
| Command | What it does |
10+
|---------|-------------|
11+
| `/plan` | Restate requirements, assess risks, write step-by-step implementation plan — **waits for your confirm before touching code** |
12+
| `/tdd` | Enforce test-driven development: scaffold interface → write failing test → implement → verify 80%+ coverage |
13+
| `/code-review` | Full code quality, security, and maintainability review of changed files |
14+
| `/build-fix` | Detect and fix build errors — delegates to the right build-resolver agent automatically |
15+
| `/verify` | Run the full verification loop: build → lint → test → type-check |
16+
| `/quality-gate` | Quality gate check against project standards |
17+
18+
---
19+
20+
## Testing
21+
22+
| Command | What it does |
23+
|---------|-------------|
24+
| `/tdd` | Universal TDD workflow (any language) |
25+
| `/e2e` | Generate + run Playwright end-to-end tests, capture screenshots/videos/traces |
26+
| `/test-coverage` | Report test coverage, identify gaps |
27+
| `/go-test` | TDD workflow for Go (table-driven, 80%+ coverage with `go test -cover`) |
28+
| `/kotlin-test` | TDD for Kotlin (Kotest + Kover) |
29+
| `/rust-test` | TDD for Rust (cargo test, integration tests) |
30+
| `/cpp-test` | TDD for C++ (GoogleTest + gcov/lcov) |
31+
32+
---
33+
34+
## Code Review
35+
36+
| Command | What it does |
37+
|---------|-------------|
38+
| `/code-review` | Universal code review |
39+
| `/python-review` | Python — PEP 8, type hints, security, idiomatic patterns |
40+
| `/go-review` | Go — idiomatic patterns, concurrency safety, error handling |
41+
| `/kotlin-review` | Kotlin — null safety, coroutine safety, clean architecture |
42+
| `/rust-review` | Rust — ownership, lifetimes, unsafe usage |
43+
| `/cpp-review` | C++ — memory safety, modern idioms, concurrency |
44+
45+
---
46+
47+
## Build Fixers
48+
49+
| Command | What it does |
50+
|---------|-------------|
51+
| `/build-fix` | Auto-detect language and fix build errors |
52+
| `/go-build` | Fix Go build errors and `go vet` warnings |
53+
| `/kotlin-build` | Fix Kotlin/Gradle compiler errors |
54+
| `/rust-build` | Fix Rust build + borrow checker issues |
55+
| `/cpp-build` | Fix C++ CMake and linker problems |
56+
| `/gradle-build` | Fix Gradle errors for Android / KMP |
57+
58+
---
59+
60+
## Planning & Architecture
61+
62+
| Command | What it does |
63+
|---------|-------------|
64+
| `/plan` | Implementation plan with risk assessment |
65+
| `/multi-plan` | Multi-model collaborative planning |
66+
| `/multi-workflow` | Multi-model collaborative development |
67+
| `/multi-backend` | Backend-focused multi-model development |
68+
| `/multi-frontend` | Frontend-focused multi-model development |
69+
| `/multi-execute` | Multi-model collaborative execution |
70+
| `/orchestrate` | Guide for tmux/worktree multi-agent orchestration |
71+
| `/devfleet` | Orchestrate parallel Claude Code agents via DevFleet |
72+
73+
---
74+
75+
## Session Management
76+
77+
| Command | What it does |
78+
|---------|-------------|
79+
| `/save-session` | Save current session state to `~/.claude/session-data/` |
80+
| `/resume-session` | Load the most recent saved session from the canonical session store and resume from where you left off |
81+
| `/sessions` | Browse, search, and manage session history with aliases from `~/.claude/session-data/` (with legacy reads from `~/.claude/sessions/`) |
82+
| `/checkpoint` | Mark a checkpoint in the current session |
83+
| `/aside` | Answer a quick side question without losing current task context |
84+
| `/context-budget` | Analyse context window usage — find token overhead, optimise |
85+
86+
---
87+
88+
## Learning & Improvement
89+
90+
| Command | What it does |
91+
|---------|-------------|
92+
| `/learn` | Extract reusable patterns from the current session |
93+
| `/learn-eval` | Extract patterns + self-evaluate quality before saving |
94+
| `/evolve` | Analyse learned instincts, suggest evolved skill structures |
95+
| `/promote` | Promote project-scoped instincts to global scope |
96+
| `/instinct-status` | Show all learned instincts (project + global) with confidence scores |
97+
| `/instinct-export` | Export instincts to a file |
98+
| `/instinct-import` | Import instincts from a file or URL |
99+
| `/skill-create` | Analyse local git history → generate a reusable skill |
100+
| `/skill-health` | Skill portfolio health dashboard with analytics |
101+
| `/rules-distill` | Scan skills, extract cross-cutting principles, distill into rules |
102+
103+
---
104+
105+
## Refactoring & Cleanup
106+
107+
| Command | What it does |
108+
|---------|-------------|
109+
| `/refactor-clean` | Remove dead code, consolidate duplicates, clean up structure |
110+
| `/prompt-optimize` | Analyse a draft prompt and output an optimised ECC-enriched version |
111+
112+
---
113+
114+
## Docs & Research
115+
116+
| Command | What it does |
117+
|---------|-------------|
118+
| `/docs` | Look up current library/API documentation via Context7 |
119+
| `/update-docs` | Update project documentation |
120+
| `/update-codemaps` | Regenerate codemaps for the codebase |
121+
122+
---
123+
124+
## Loops & Automation
125+
126+
| Command | What it does |
127+
|---------|-------------|
128+
| `/loop-start` | Start a recurring agent loop on an interval |
129+
| `/loop-status` | Check status of running loops |
130+
| `/claw` | Start NanoClaw v2 — persistent REPL with model routing, skill hot-load, branching, and metrics |
131+
132+
---
133+
134+
## Project & Infrastructure
135+
136+
| Command | What it does |
137+
|---------|-------------|
138+
| `/projects` | List known projects and their instinct statistics |
139+
| `/harness-audit` | Audit the agent harness configuration for reliability and cost |
140+
| `/eval` | Run the evaluation harness |
141+
| `/model-route` | Route a task to the right model (Haiku / Sonnet / Opus) |
142+
| `/pm2` | PM2 process manager initialisation |
143+
| `/setup-pm` | Configure package manager (npm / pnpm / yarn / bun) |
144+
145+
---
146+
147+
## Quick Decision Guide
148+
149+
```
150+
Starting a new feature? → /plan first, then /tdd
151+
Code just written? → /code-review
152+
Build broken? → /build-fix
153+
Need live docs? → /docs <library>
154+
Session about to end? → /save-session or /learn-eval
155+
Resuming next day? → /resume-session
156+
Context getting heavy? → /context-budget then /checkpoint
157+
Want to extract what you learned? → /learn-eval then /evolve
158+
Running repeated tasks? → /loop-start
159+
```

‎EVALUATION.md‎

Lines changed: 122 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,122 @@
1+
# Repo Evaluation vs Current Setup
2+
3+
**Date:** 2026-03-21
4+
**Branch:** `claude/evaluate-repo-comparison-ASZ9Y`
5+
6+
---
7+
8+
## Current Setup (`~/.claude/`)
9+
10+
The active Claude Code installation is near-minimal:
11+
12+
| Component | Current |
13+
|-----------|---------|
14+
| Agents | 0 |
15+
| Skills | 0 installed |
16+
| Commands | 0 |
17+
| Hooks | 1 (Stop: git check) |
18+
| Rules | 0 |
19+
| MCP configs | 0 |
20+
21+
**Installed hooks:**
22+
- `Stop` → `stop-hook-git-check.sh` — blocks session end if there are uncommitted changes or unpushed commits
23+
24+
**Installed permissions:**
25+
- `Skill` — allows skill invocations
26+
27+
**Plugins:** Only `blocklist.json` (no active plugins installed)
28+
29+
---
30+
31+
## This Repo (`everything-claude-code` v1.9.0)
32+
33+
| Component | Repo |
34+
|-----------|------|
35+
| Agents | 28 |
36+
| Skills | 116 |
37+
| Commands | 59 |
38+
| Rules sets | 12 languages + common (60+ rule files) |
39+
| Hooks | Comprehensive system (PreToolUse, PostToolUse, SessionStart, Stop) |
40+
| MCP configs | 1 (Context7 + others) |
41+
| Schemas | 9 JSON validators |
42+
| Scripts/CLI | 46+ Node.js modules + multiple CLIs |
43+
| Tests | 58 test files |
44+
| Install profiles | core, developer, security, research, full |
45+
| Supported harnesses | Claude Code, Codex, Cursor, OpenCode |
46+
47+
---
48+
49+
## Gap Analysis
50+
51+
### Hooks
52+
- **Current:** 1 Stop hook (git hygiene check)
53+
- **Repo:** Full hook matrix covering:
54+
- Dangerous command blocking (`rm -rf`, force pushes)
55+
- Auto-formatting on file edits
56+
- Dev server tmux enforcement
57+
- Cost tracking
58+
- Session evaluation and governance capture
59+
- MCP health monitoring
60+
61+
### Agents (28 missing)
62+
The repo provides specialized agents for every major workflow:
63+
- Language reviewers: TypeScript, Python, Go, Java, Kotlin, Rust, C++, Flutter
64+
- Build resolvers: Go, Java, Kotlin, Rust, C++, PyTorch
65+
- Workflow agents: planner, tdd-guide, code-reviewer, security-reviewer, architect
66+
- Automation: loop-operator, doc-updater, refactor-cleaner, harness-optimizer
67+
68+
### Skills (116 missing)
69+
Domain knowledge modules covering:
70+
- Language patterns (Python, Go, Kotlin, Rust, C++, Java, Swift, Perl, Laravel, Django)
71+
- Testing strategies (TDD, E2E, coverage)
72+
- Architecture patterns (backend, frontend, API design, database migrations)
73+
- AI/ML workflows (Claude API, eval harness, agent loops, cost-aware pipelines)
74+
- Business workflows (investor materials, market research, content engine)
75+
76+
### Commands (59 missing)
77+
- `/tdd`, `/plan`, `/e2e`, `/code-review` — core dev workflows
78+
- `/sessions`, `/save-session`, `/resume-session` — session persistence
79+
- `/orchestrate`, `/multi-plan`, `/multi-execute` — multi-agent coordination
80+
- `/learn`, `/skill-create`, `/evolve` — continuous improvement
81+
- `/build-fix`, `/verify`, `/quality-gate` — build/quality automation
82+
83+
### Rules (60+ files missing)
84+
Language-specific coding style, patterns, testing, and security guidelines for:
85+
TypeScript, Python, Go, Java, Kotlin, Rust, C++, C#, Swift, Perl, PHP, and common/cross-language rules.
86+
87+
---
88+
89+
## Recommendations
90+
91+
### Immediate value (core install)
92+
Run `ecc install --profile core` to get:
93+
- Core agents (code-reviewer, planner, tdd-guide, security-reviewer)
94+
- Essential skills (tdd-workflow, coding-standards, security-review)
95+
- Key commands (/tdd, /plan, /code-review, /build-fix)
96+
97+
### Full install
98+
Run `ecc install --profile full` to get all 28 agents, 116 skills, and 59 commands.
99+
100+
### Hooks upgrade
101+
The current Stop hook is solid. The repo's `hooks.json` adds:
102+
- Dangerous command blocking (safety)
103+
- Auto-formatting (quality)
104+
- Cost tracking (observability)
105+
- Session evaluation (learning)
106+
107+
### Rules
108+
Adding language rules (e.g., TypeScript, Python) provides always-on coding guidelines without relying on per-session prompts.
109+
110+
---
111+
112+
## What the Current Setup Does Well
113+
114+
- The `stop-hook-git-check.sh` Stop hook is production-quality and already enforces good git hygiene
115+
- The `Skill` permission is correctly configured
116+
- The setup is clean with no conflicts or cruft
117+
118+
---
119+
120+
## Summary
121+
122+
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.

0 commit comments

Comments
 (0)