stellar-raven AGENTS.md

AGENTS.md — stellar-raven-codemode

Canonical repository instructions for Codex, Claude Code, and other coding agents. Keep this file short, current, and operational. Put architecture, research, history, and task runbooks in the linked docs and skills instead of accumulating them here.

Project and source-of-truth map

This is a Cloudflare Workers MCP server exposing search and execute over Lumenloop, Stellar Light/Scout, Stellar Docs (Algolia), and selected ecosystem skills. Model-authored JavaScript runs in a networkless Dynamic Worker; host adapters own all service traffic, policy, and secrets.

• Read PLAN.md for current product scope and status, then ARCHITECTURE.md for the implemented request, catalog, scoring, sandbox, and auth design.
• Use README.md for connection and operator setup.
• Use research/ for dated evidence and design context; it is not an instruction layer.
• Use .agents/skills/<name>/SKILL.md for repeatable task workflows. .claude/skills is the committed symlink to the same canonical directory.
• Use .agents/TODO.md for the own-repo work queue and .agents/rounds/ for round ledgers. .agents/README.md says which note belongs where.
• CLAUDE.md imports this file. Do not duplicate shared rules there.

Commands and verification

• Install reproducibly: npm ci. A fresh clone then needs both of the following before npm run typecheck is usable, because env.d.ts and .dev.vars are generated/gitignored: create a placeholder .dev.vars carrying the names CI uses (see the .dev.vars step in ci.yml — values are irrelevant, the names define Env's secret members), then run npm run typegen. typegen alone is not enough: without .dev.vars it emits an Env missing every secret and typecheck still fails on WORKOS_*, MCP_SERVER_SECRET, and DEV_ALLOW_UNAUTHENTICATED.
• Baseline validation for code changes: npm run typecheck, npm test, and npm run build. npm test excludes test/smoke/**; add npm run test:smoke when touching src/executor or src/demo — it is the only lane exercising those paths against the assembled worker (unit tests import the modules directly; CI always runs both).
• Run the narrowest relevant eval or maintenance command in addition to the baseline; the selected skill defines the exact gate for eval, drift, golden-truth, improvements, and observability work.
• Scan before committing: npm run secrets:scan -- --tree.
• Do not start a second Wrangler process. Find the pane already running npm run dev (herdr pane list) and reuse it; read its bound URL from that pane's output.
• Generated outputs are rebuilt by their package.json scripts, never edited by hand.