[Feature]: Add /init slash command — deep project scan & AGENTS.md auto-generation (like Claude Code /init)

[ZaneGzg]

Problem or Use Case

When starting work on an unfamiliar codebase — whether it is a new project, a colleague repo, or a legacy codebase — there is a significant cognitive ramp-up cost. The agent does not know the projects structure, conventions, build commands, dependency patterns, or coding style.

Currently, the user has to manually tell the agent about the project, or the agent discovers things incrementally over multiple turns. Claude Code solves this with /init — a single command that scans the entire project tree, reads key config files, infers the tech stack and conventions, and generates a CLAUDE.md that is then auto-loaded into every subsequent session.

Hermes already has the foundation:

• ✅ Auto-loads AGENTS.md / CLAUDE.md / .cursorrules at session start
• ✅ Has codebase-inspection skill for LOC stats
• ✅ Can read and analyze project files

But there is no single, standardised command that does the full deep-scan + generation workflow automatically.

---

Proposed Solution

New slash command: /init

When a user types /init in a Hermes session (or hermes init from CLI), the agent should:

Phase 1 — Deep Project Scan

1. Detect project root — look for AGENTS.md / CLAUDE.md / .cursorrules first; if exists, skip or offer to re-generate
2. Walk the directory tree — skip .git, node_modules, venv, dist, build, .next, pycache etc.
3. Read key configuration files:
   • package.json → npm scripts, dependencies, type: module/commonjs
   • pyproject.toml / setup.py / requirements.txt → Python deps and metadata
   • Cargo.toml → Rust project info
   • go.mod → Go module info
   • tsconfig.json, .eslintrc, vite.config.ts, webpack.config.js → build tooling
   • Dockerfile, docker-compose.yml, .github/workflows/ → deployment/CI
   • .env.example → expected env vars (NOT .env itself — privacy)
4. Run pygount or equivalent for language breakdown (lines of code per language, file counts)
5. Detect test framework (jest, pytest, vitest, etc.)
6. Identify key entry points (main.ts, app.py, index.js, src/main.rs)

Phase 2 — Generate AGENTS.md

Write a structured AGENTS.md in the project root with:

• Project name and description
• Tech stack (languages, frameworks, build tools, testing, package manager)
• Project structure overview
• Key commands (dev, build, test)
• Coding conventions detected from code
• Key dependencies

Phase 3 — Automatic Loading

Once generated, the file is auto-respected by Hermes existing AGENTS.md / CLAUDE.md loading behavior — no extra config needed.

Additional Considerations

• Idempotent: If AGENTS.md already exists, ask to update or regenerate
• Configurable depth: hermes config set init.scan_depth deep|standard|quick
• Privacy-aware: Skip .env and credential files
• Language-agnostic: Works with any project type

---

Feature Type

CLI improvement (new slash command + optional hermes init CLI subcommand)

Scope

Medium (few files, < 300 lines):

• New handler in cli.py / slash command in commands.py (/init)
• New tool module: tools/init_scanner.py for the scan logic
• Integration test in tests/

Alternatives Considered

• Manual instructions: Wastes turns, inconsistent across projects
• Relying on skills index: Skills are task-specific, project context is project-specific
• Plugin-based scanner: Too heavy for a core UX improvement
• Third-party tool: Fragmented ecosystem, no Hermes-native AGENTS.md format guarantees

Contribution

I am not able to implement this myself at this time, but I hope this spec helps the community or maintainers pick it up quickly.