Tacit Lab
d1737cdcb8
SKILL.md - Add triggers/mode to frontmatter for better skill routing - Add mandatory JSON decision skeleton before every trade - Add multi-source confirmation rule and common-mistakes guardrails - Add prediction logging to hourly review workflow - Restructure References into an explicit routing table CLAUDE.md - Add Reference routing table for agent context - Fix remaining Hermes-only wording in gate description references/user-data-layout.md - Add complete log schema: decisions, trades, predictions, errors - Document predictions_YYYYMMDD.jsonl for calibration feedback loop README.md - Mention prediction tracking in "Why it works" - Update runtime directory layout to include predictions.jsonl references/shim-templates.md - Show platform cron config usage examples
121 lines
6.6 KiB
Markdown
121 lines
6.6 KiB
Markdown
# CLAUDE.md
|
||
|
||
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
|
||
|
||
## Repository purpose
|
||
|
||
This is a **cross-platform skill package** for a short-term crypto trading framework called Coin Hunter. It runs on Hermes, OpenClaw, and compatible cron-based runtimes. It contains the skill specification, reference playbooks, and runtime shim templates.
|
||
|
||
The actual trading CLI is an **external dependency**: the `coinhunter` package on PyPI. All execution flows through the installed `coinhunter` command. This repository does **not** contain the CLI source code or a build system.
|
||
|
||
## Repository structure
|
||
|
||
- `SKILL.md` — The canonical behavior specification. This is the source of truth for the trading framework, including the scientific checklist, execution workflow, review workflow, auto-trading architecture, low-cost gate design, production hardening rules, and troubleshooting notes.
|
||
- `README.md` — User-facing quick-start and overview.
|
||
- `references/` — Trading playbooks and templates:
|
||
- `short-term-trading-framework.md` — Hybrid strategy (70% mainstream scalping / 30% meme rotation) and position-sizing rules.
|
||
- `provider-playbook.md` — Data source hierarchy (Bybit → DexScreener → Birdeye → CoinGecko) and token identity hygiene.
|
||
- `user-data-layout.md` — Schema for private runtime state under `~/.coinhunter/`.
|
||
- `review-template.md` — Hourly review report structure.
|
||
- `scam-signals.md` — Red flags and classification guidance for meme-coin evaluation.
|
||
- `auto-trading-guide.md` — Legacy-oriented guide for deploying `auto_trader.py` and Binance API setup.
|
||
- `scripts/` — Thin shim scripts meant to be copied to your platform's scripts directory (e.g. `~/.hermes/scripts/` or `~/.openclaw/scripts/`). Currently contains:
|
||
- `coinhunter_shim.py` — Unified cross-platform shim that runs any `coinhunter` subcommand (`pre`, `gate`, `review`, `rotate-log`).
|
||
|
||
There is no `pyproject.toml`, `Makefile`, or test suite in this repository.
|
||
|
||
## Key architectural concepts
|
||
|
||
### Skill vs runtime separation
|
||
- **Skill code/docs** live in this repository.
|
||
- **Private user state** lives under `~/.coinhunter/` (positions, balances, logs, reviews, cache, gate state). Never commit user data into this repo.
|
||
- **Platform cron scripts** are copied from `scripts/` to your runtime's scripts directory (e.g. `~/.hermes/scripts/` or `~/.openclaw/scripts/`) and invoke the installed `coinhunter` CLI.
|
||
|
||
### Low-cost trigger architecture
|
||
The framework is designed to minimize LLM invocations:
|
||
1. A lightweight local Python precheck script decides whether market conditions have changed materially.
|
||
2. If `should_analyze=false`, the cron job emits `[SILENT]` and exits.
|
||
3. If `should_analyze=true`, the LLM performs deep analysis and may execute trades.
|
||
4. An optional external gate (system crontab) can run the precheck every 5 minutes and trigger the platform cron only on true events.
|
||
|
||
See `SKILL.md` (sections "Low-cost cron architecture" and "Building your own gate") for the full pseudocode, file layout, state schema, and troubleshooting.
|
||
|
||
### Trading workflow
|
||
1. **Portfolio-first rule** — Always read `~/.coinhunter/positions.json`, `accounts.json`, and recent logs before giving trade advice.
|
||
2. **Scientific checklist** (mandatory before every decision) — trend posture, volume-price fit, key levels, BTC/ETH context, opportunity cost, time window.
|
||
3. **Execution** — Decide HOLD / SELL_ALL / REBALANCE / BUY. Use `coinhunter exec` for order execution.
|
||
4. **Review** — Run `coinhunter recap` hourly to analyze decision quality and tune parameters.
|
||
|
||
### Production hardening requirements
|
||
When modifying or adding trading scripts, these safeguards from `SKILL.md` must be respected:
|
||
- **Idempotency** — every decision carries a `decision_id`; check `~/.coinhunter/executions.json` before submitting orders.
|
||
- **Exchange reconciliation** — pull real balances before every run; do not trust local state alone.
|
||
- **Atomic writes** — update `positions.json` and `executions.json` under a file lock with temp-file + rename.
|
||
- **Order precision validation** — read exchange `lotSize`, `stepSize`, and `minNotional` filters via ccxt before any order.
|
||
- **Fee buffer** — keep 2%–5% USDT unallocated.
|
||
- **Structured logging** — write JSONL under `~/.coinhunter/logs/` with `schema_version` and `decision_id`.
|
||
- **Platform config atomic writes** — if you create or modify `~/.coinhunter/platform.json`, write to a temp file and rename it into place, just like `positions.json` and `executions.json`.
|
||
|
||
### Safety rules
|
||
- No leverage/futures when capital < $200.
|
||
- When capital < $50, concentrate into **1 position only**.
|
||
- Blacklist updates should be driven by review findings.
|
||
|
||
## Common commands
|
||
|
||
- **Install the CLI tool:**
|
||
```bash
|
||
pipx install coinhunter
|
||
# verify
|
||
coinhunter --version
|
||
```
|
||
|
||
- **Validate the shim after editing:**
|
||
```bash
|
||
python3 -m py_compile scripts/coinhunter_shim.py
|
||
```
|
||
|
||
- **Copy the shim to your platform's scripts directory:**
|
||
```bash
|
||
cp scripts/coinhunter_shim.py ~/.hermes/scripts/coinhunter_shim.py
|
||
# or: cp scripts/coinhunter_shim.py ~/.openclaw/scripts/coinhunter_shim.py
|
||
```
|
||
|
||
- **Inspect user state:**
|
||
```bash
|
||
cat ~/.coinhunter/positions.json
|
||
cat ~/.coinhunter/accounts.json
|
||
ls ~/.coinhunter/logs/
|
||
ls ~/.coinhunter/reviews/
|
||
```
|
||
|
||
- **Common trading CLI commands:**
|
||
```bash
|
||
coinhunter pre
|
||
coinhunter exec
|
||
coinhunter recap
|
||
coinhunter review
|
||
coinhunter probe bybit-ticker
|
||
```
|
||
|
||
## Reference routing
|
||
|
||
When working on Coin Hunter, read the relevant reference file at the right moment:
|
||
|
||
| Task context | File to read |
|
||
|--------------|--------------|
|
||
| Active trade decision (mainstream coin) | `references/short-term-trading-framework.md` |
|
||
| Active trade decision (meme coin) | `references/short-term-trading-framework.md` + `references/scam-signals.md` |
|
||
| Data source conflict / ambiguity | `references/provider-playbook.md` |
|
||
| Hourly review formatting | `references/review-template.md` |
|
||
| Runtime state / log schema questions | `references/user-data-layout.md` |
|
||
| Binance API / auto-trading setup | `references/auto-trading-guide.md` |
|
||
| Output format / report templates | `references/output-templates.md` |
|
||
| Proactive discovery scan workflow | `references/search-workflow.md` |
|
||
|
||
## When making changes
|
||
|
||
- If you change `SKILL.md`, check whether `README.md` needs corresponding updates.
|
||
- If you change shim templates, validate them with `python3 -m py_compile` before copying to your platform's scripts directory.
|
||
- Keep the separation between this repo and `~/.coinhunter/` — never write personal account data or logs into the skill directory.
|