chore: add gstack skill routing rules to CLAUDE.md
This commit is contained in:
114
CLAUDE.md
Normal file
114
CLAUDE.md
Normal file
@@ -0,0 +1,114 @@
|
||||
# CLAUDE.md
|
||||
|
||||
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
|
||||
|
||||
## Development commands
|
||||
|
||||
- **Editable install:** `pip install -e .`
|
||||
- **Run the CLI locally:** `python -m coinhunter --help`
|
||||
- **Install for end users:** `./scripts/install_local.sh` (creates `~/.local/bin/coinhunter`)
|
||||
- **Tests:** There is no test suite yet. The README lists next priorities as adding pytest coverage for runtime paths, state manager, and trigger analyzer.
|
||||
- **Lint / type-check:** Not configured yet.
|
||||
|
||||
## CLI command routing
|
||||
|
||||
`src/coinhunter/cli.py` is the single entrypoint. It resolves aliases to canonical commands, maps canonical commands to Python modules via `MODULE_MAP`, then imports the module and calls `module.main()` after mutating `sys.argv` to match the display name.
|
||||
|
||||
Active commands live in `src/coinhunter/commands/` and are thin adapters that delegate to `src/coinhunter/services/`. A few legacy commands (`review_context.py`, `review_engine.py`) still live at the `src/coinhunter/` root and are imported directly by `cli.py`. Root-level backward-compat facades (e.g., `precheck.py`, `smart_executor.py`) re-export the moved commands.
|
||||
|
||||
## Architecture
|
||||
|
||||
### Layer responsibilities
|
||||
|
||||
- **CLI (`cli.py`)** — argument parsing, alias resolution, module dispatch.
|
||||
- **Commands (`commands/`)** — thin, stateless adapters that call into services.
|
||||
- **Services (`services/`)** — orchestration, domain logic, and exchange interaction.
|
||||
- **Runtime (`runtime.py`)** — path resolution, env loading, hermes binary discovery.
|
||||
- **Logger (`logger.py`)** — structured JSONL logging to `~/.coinhunter/logs/`.
|
||||
|
||||
### Runtime and environment
|
||||
|
||||
`runtime.py` defines `RuntimePaths` and `get_runtime_paths()`. User data lives in `~/.coinhunter/` by default (override with `COINHUNTER_HOME`). Credentials are loaded from `~/.hermes/.env` by default (override with `COINHUNTER_ENV_FILE`). Many modules eagerly instantiate `PATHS = get_runtime_paths()` at import time.
|
||||
|
||||
### Smart executor (`exec`)
|
||||
|
||||
`commands/smart_executor.py` → `services/smart_executor_service.py` → `services/trade_execution.py`.
|
||||
|
||||
Supported verbs: `bal`, `overview`, `hold`, `buy SYMBOL USDT`, `flat SYMBOL`, `rotate FROM TO`.
|
||||
|
||||
- `smart_executor_parser.py` normalizes legacy argv and exposes `parse_cli_args()`.
|
||||
- `trade_common.py` holds a global dry-run flag (`set_dry_run` / `is_dry_run`).
|
||||
- `execution_state.py` tracks decision IDs in JSON to prevent duplicate executions.
|
||||
- `exchange_service.py` wraps `ccxt.binance` and handles symbol normalization.
|
||||
- `portfolio_service.py` manages `positions.json` load/save/reconcile.
|
||||
|
||||
### Precheck
|
||||
|
||||
`commands/precheck.py` → `services/precheck_service.py`.
|
||||
|
||||
The precheck workflow:
|
||||
1. Load and sanitize state (`precheck_state.py` — clears stale triggers and run requests).
|
||||
2. Build a market snapshot (`precheck_snapshot.py` → `snapshot_builder.py`).
|
||||
3. Analyze whether to trigger deep analysis (`precheck_analysis.py` → `trigger_analyzer.py`).
|
||||
4. Update and save state (`precheck_state.update_state_after_observation`).
|
||||
|
||||
State is stored in `~/.coinhunter/state/precheck_state.json`.
|
||||
|
||||
### Review commands
|
||||
|
||||
- `review N` (`review_context.py`) — generates review context for the last N hours.
|
||||
- `recap N` (`review_engine.py`) — generates a full review report by reading JSONL decision/trade/error logs, computing PnL estimates, missed opportunities, and saving a report to `~/.coinhunter/reviews/`.
|
||||
|
||||
### Logging model
|
||||
|
||||
`logger.py` writes JSONL to dated files in `~/.coinhunter/logs/`:
|
||||
- `decisions_YYYYMMDD.jsonl`
|
||||
- `trades_YYYYMMDD.jsonl`
|
||||
- `errors_YYYYMMDD.jsonl`
|
||||
- `snapshots_YYYYMMDD.jsonl`
|
||||
|
||||
Use `get_logs_last_n_hours(log_type, hours)` to query recent entries.
|
||||
|
||||
## Common command reference
|
||||
|
||||
```bash
|
||||
# Diagnostics
|
||||
python -m coinhunter diag
|
||||
python -m coinhunter paths
|
||||
python -m coinhunter api-check
|
||||
|
||||
# Execution (dry-run)
|
||||
python -m coinhunter exec bal
|
||||
python -m coinhunter exec overview
|
||||
python -m coinhunter exec buy ENJUSDT 50 --dry-run
|
||||
python -m coinhunter exec flat ENJUSDT --dry-run
|
||||
|
||||
# Precheck
|
||||
python -m coinhunter precheck
|
||||
python -m coinhunter precheck --ack "analysis completed"
|
||||
python -m coinhunter precheck --mark-run-requested "reason"
|
||||
|
||||
# Review
|
||||
python -m coinhunter review 12
|
||||
python -m coinhunter recap 12
|
||||
```
|
||||
|
||||
## Skill routing
|
||||
|
||||
When the user's request matches an available skill, ALWAYS invoke it using the Skill
|
||||
tool as your FIRST action. Do NOT answer directly, do NOT use other tools first.
|
||||
The skill has specialized workflows that produce better results than ad-hoc answers.
|
||||
|
||||
Key routing rules:
|
||||
- Product ideas, "is this worth building", brainstorming → invoke office-hours
|
||||
- Bugs, errors, "why is this broken", 500 errors → invoke investigate
|
||||
- Ship, deploy, push, create PR → invoke ship
|
||||
- QA, test the site, find bugs → invoke qa
|
||||
- Code review, check my diff → invoke review
|
||||
- Update docs after shipping → invoke document-release
|
||||
- Weekly retro → invoke retro
|
||||
- Design system, brand → invoke design-consultation
|
||||
- Visual audit, design polish → invoke design-review
|
||||
- Architecture review → invoke plan-eng-review
|
||||
- Save progress, checkpoint, resume → invoke checkpoint
|
||||
- Code quality, health check → invoke health
|
||||
Reference in New Issue
Block a user