Imported from haoh51918-lgtm/CogAlpha-remix (AGENTS.md). Install upstream with npx skills add haoh51918-lgtm/CogAlpha-remix. Copyright stays with the author.

CogAlpha Agent Guide

Active Project

The active milestone is CogAlpha Adaptive Skill Evolution. V1 proves a vertical, one-agent text-skill evolution loop before expanding it to the existing seven layers/21 domain agents.

Read these planning artifacts before phase work:

• .planning/PROJECT.md — intent, non-goals, and hard constraints.
• .planning/REQUIREMENTS.md — authoritative v1 requirements and phase mapping.
• .planning/ROADMAP.md — approved MVP phase order and success criteria.
• .planning/STATE.md — current focus and carried decisions.
• .planning/research/SUMMARY.md — architecture and risk controls.

V1 Non-Negotiable Controls

• Baseline skills/**/SKILL.md files are read-only during experiments. Candidate skills are immutable, content-addressed overlays with explicit agent/layer/base-version manifests.
• A SkillOpt-compatible adapter may propose bounded text patches only. It may not choose activation, alter baseline files, promote versions, or execute factor code.
• Gate 1 compares baseline and candidate under identical frozen inputs and sealed chronological factor-validation partitions. Promotion requires both predeclared IC and RankIC improvements plus existing CogAlpha safeguards.
• Gate 2 backtesting is authorized only by a durable Gate 1 promotion. A backtest cannot repair a Gate 1 failure or directly activate a skill.
• Preserve all existing CogAlpha guards, leakage detection, isolated execution, redaction, provenance, checkpoint, and resume semantics.
• Store redacted, hash-addressed trajectories and optimizer-safe feedback projections. Do not expose sealed observations, final backtest observations, raw factor code, raw provider traffic, or secrets to the optimizer.
• QuantaAlpha is a manifest-identified data/protocol baseline only. CogAlpha remains the authority for runtime control, metrics, factor combination, and backtesting.

Scope Boundary

• V1 includes independent overlays, bounded SkillOpt-compatible edits, two validation gates, replayable trajectories, all-21-agent expansion, and QuantaAlpha protocol governance.
• V2 defers the OHLCV/factor-only activation router and all economic knowledge retrieval/feedback.
• Do not introduce model-weight training, direct trading, mutable shared skills, backtesting every candidate, external knowledge as factor data, or ungoverned cross-protocol comparisons without an approved roadmap update.

Engineering Expectations

• Work in the roadmap order; keep each requirement mapped to exactly one phase.
• Start with deterministic offline fixtures and contract tests before any live LLM/provider integration.
• Make state transitions, rejections, retries, and rollbacks explicit, durable, and replayable.
• Treat missing identity, timing, provenance, or metric inputs as an explicit inconclusive/rejection path rather than silently recomputing.