chore: scaffold aura workspace and wire the skills dev-cycle
Cargo workspace aura-core -> aura-engine -> aura-cli (bin `aura`) plus nodes/ for hot-reloadable cdylib node crates. Crate bodies are intentionally API-free; types arrive from the first spec. Adds the skills profile (.claude/dev-cycle-profile.yml), the project CLAUDE.md with the eight domain invariants, and the design-ledger skeleton. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
This commit is contained in:
@@ -0,0 +1,82 @@
|
||||
# aura — project rules
|
||||
|
||||
aura is a "game engine for traders": a Rust framework **and** a playground to
|
||||
author trading nodes, backtest them deterministically and massively in parallel,
|
||||
compose them fractally, validate them (sweep / Monte-Carlo / walk-forward), and
|
||||
freeze a validated strategy into a standalone bot with a broker connection.
|
||||
|
||||
This file is the project sittenkodex. It imports the universal discipline from
|
||||
`~/dev/skills/templates/CLAUDE.md.fragment` and adds aura's domain invariants.
|
||||
The full architecture lives in the design ledger (`docs/design/`) and the specs
|
||||
(`docs/specs/`), not here.
|
||||
|
||||
## Roles
|
||||
|
||||
I am the **orchestrator**, not the implementer. The skills-plugin agents are my
|
||||
workers: I plan, design, decide, and integrate; they implement, refactor, test,
|
||||
and diagnose. Trivial mechanical edits I may do directly; anything needing broad
|
||||
reading or judgement goes to an agent. Agent reports describe intent, not
|
||||
outcome — I verify the diff and the test output myself before committing.
|
||||
|
||||
## Commit discipline and main-branch sanctity
|
||||
|
||||
- **Only the orchestrator commits.** No skill agent runs `git commit`; agents
|
||||
leave their output as unstaged working-tree changes for me to inspect and shape
|
||||
into commits.
|
||||
- **main HEAD is sacrosanct.** No `git reset`/`git revert` on main. main moves
|
||||
forward only via my commits. Wrong agent output is discarded with
|
||||
`git checkout -- <paths>`/`git stash`; a bad landing is fixed forward, never
|
||||
rewound.
|
||||
- When a commit closes a Gitea issue, reference it in the body: `closes #N`
|
||||
(or `refs #N` for non-final work).
|
||||
|
||||
## Design rationale ≠ implementation effort
|
||||
|
||||
Design choices are justified by substance — semantics, structural fit, what the
|
||||
design permits vs forbids, compositional clarity, future-proofing. Implementation
|
||||
effort ("approach A touches 250 sites, B touches 1") is an observation about the
|
||||
current code, not a rationale. Effort is at most a named tiebreaker after
|
||||
substantive reasons tie.
|
||||
|
||||
## Bug fixes — TDD, always
|
||||
|
||||
Bug fixes are RED-first and autonomous: the failing test exists in the working
|
||||
tree before any fix. The `debug` skill is mandatory for any observable
|
||||
misbehaviour (failing test, panic, wrong output).
|
||||
|
||||
## Domain invariants (load-bearing — never silently violate)
|
||||
|
||||
These are the contracts the whole design rests on. A change that breaks one is a
|
||||
design decision, not a refactor, and belongs in the ledger.
|
||||
|
||||
1. **Determinism.** A backtest is a deterministic, synchronous, non-concurrent
|
||||
event loop that reaches a unique state after each input tick. Same input →
|
||||
same run, reproducibly. Two backtests are fully disjoint → concurrently
|
||||
executable without locking. Parallelism is *across* sims, never within one.
|
||||
2. **Causality / no look-ahead.** A node sees only the past. Look-ahead is made
|
||||
structurally impossible (read-only input windows that end at the cursor;
|
||||
resamplers emit a bar only once it is complete), not merely discouraged.
|
||||
3. **One merge, at ingestion only.** Heterogeneous timestamped sources are
|
||||
k-way-merged into a single chronological cycle stream at the ingestion
|
||||
boundary. There is no merge / as-of join inside the graph.
|
||||
4. **The four scalar base types, streamed as SoA.** Only `i64`, `f64`, `bool`,
|
||||
`timestamp` are streamed, as columnar Structure-of-Arrays. Composite streams
|
||||
(e.g. OHLCV) are bundles of base columns. Non-scalars (String, Records,
|
||||
tables, calendars) exist as metadata beside the hot path, never in it.
|
||||
5. **Acyclic dataflow.** The graph is a DAG; the only feedback path is an
|
||||
explicit delay/state node (the RTL "register"). The "cycle" of the research
|
||||
workflow is not a dataflow cycle.
|
||||
6. **Record-then-replay determinism boundary.** Anything non-deterministic,
|
||||
external, or slow (LLM news agents, web sources) is materialized into a
|
||||
recorded, timestamped stream *before* it enters the engine. The sim never
|
||||
makes a live external call mid-replay. (See `~/.claude/CLAUDE.md` for the
|
||||
IONOS consent rule: external LLM calls happen at the recording/live-source
|
||||
edge, with explicit per-session consent, never inside a backtest.)
|
||||
7. **The broker is part of the strategy.** The broker node is fixed in a
|
||||
strategy and identical in sim and live (one accounting path → one equity
|
||||
curve shape). "Same strategy, different broker" = swap the broker *profile*
|
||||
it is parameterized with. Live order-routing/reconciliation is an external
|
||||
adapter outside the strategy graph.
|
||||
8. **Deploy artifacts are frozen.** Hot-reload (cdylib) is an authoring-loop
|
||||
tool only. The live bot is a statically-linked, versioned, frozen artifact —
|
||||
never hot-swapped (audit trail: this bot = this commit).
|
||||
Reference in New Issue
Block a user