gracefullight__stock-checker/AGENTS.md

Repository Guidelines

Project Structure & Module Organization

• src/index.ts: CLI entry; fetches quotes, computes indicators, writes CSV, optional Slack alerts.
• public/: Dated CSV outputs (e.g., stock_data_20250824.csv).
• .github/workflows/daily-data.yml: Nightly scheduler that runs the CLI and commits new CSVs.
• tsconfig.json: TypeScript config (strict mode, ESNext target, CommonJS).

Build, Test, and Development Commands

• bun install: Install dependencies (Bun 1 required).
• bun start --ticker=TSLA,PLTR --sort=asc: Run locally via bun (no build step). Writes/updates public/stock_data_YYYYMMDD.csv.
• bun start:pretty: Same as above, pretty log output via pino-pretty.
• Slack alerts: SLACK_WEBHOOK_URL=... bun start --ticker=AAPL --sort=desc or --slack-webhook=....

Coding Style & Naming Conventions

• Language: TypeScript with strict: true, esModuleInterop: true.
• Modules: CommonJS (module: "CommonJS").
• Indentation: 2 spaces; keep lines focused and typed.
• Naming: lowerCamelCase for vars/functions, UpperCamelCase for types/interfaces, UPPER_SNAKE_CASE for constants.
• Logging: Use pino (avoid console.log).
• Structure: Keep the CLI thin; factor helpers into small functions within src/ as needed.

Testing Guidelines

• Current status: No formal test suite. Contributions adding tests are welcome.
• Recommendation: vitest with *.test.ts colocated under src/ or in tests/.
• Scope: Cover indicator computations, opinion scoring, CSV row formatting, and Slack payload formatting.

Commit & Pull Request Guidelines

• Commits: Follow Conventional Commits (feat:, fix:, docs:, chore:). Examples in history: feat: add INTC and UPST tickers, fix: notify slack after csv write.
• PRs: Include a concise description, linked issue (if any), and a sample run (command used plus snippet of CSV output or logs). Note any changes affecting the GH Action.
• CI: Ensure the nightly workflow continues to succeed without extra setup (no new required secrets).

Security & Configuration Tips

• Do not commit secrets. Pass Slack webhooks via env vars or GitHub Secrets.
• Network calls: Uses public Yahoo Finance API and alternative.me FGI; handle failures gracefully (already logged) and avoid adding rate-limited loops.

oh-my-agent

Architecture

• SSOT: .agents/ directory (do not modify directly)
• Response language: Follows language in .agents/oma-config.yaml
• Skills: .agents/skills/ (domain specialists)
• Workflows: .agents/workflows/ (multi-step orchestration)
• Subagents: Same-vendor native dispatch via Codex custom agents in .codex/agents/{name}.toml; cross-vendor fallback via oma agent:spawn

Per-Agent Dispatch

1. Resolve target_vendor_for_agent from .agents/oma-config.yaml.
2. If target_vendor_for_agent === current_runtime_vendor, use the runtime's native subagent path.
3. If vendors differ, or native subagents are unavailable, use oma agent:spawn for that agent only.

Code Search

Prefer serena MCP tools over native find/grep when locating code — they are symbol-aware and faster on large repos. Fall back to native Read / Glob / Grep only when serena is unavailable or for plain file content reads.

Task	Preferred tool
Locate a symbol definition (class / function / variable)	find_symbol
Find references / callers of a symbol	find_referencing_symbols
Outline a file's top-level symbols	get_symbols_overview
Pattern or regex search across the codebase	search_for_pattern
Find a file by name	find_file
List directory contents	list_dir

Workflows

Execute by naming the workflow in your prompt. Keywords are auto-detected via hooks.

Workflow	File	Description
orchestrate	orchestrate.md	Parallel subagents + Review Loop
work	work.md	Step-by-step with remediation loop
ultrawork	ultrawork.md	5-Phase Gate Loop (11 reviews)
ralph	ralph.md	Persistent loop wrapping ultrawork with an independent judge
plan	plan.md	PM task breakdown
brainstorm	brainstorm.md	Design-first ideation
architecture	architecture.md	Architecture diagnosis, comparison, ADR
design	design.md	Design system + DESIGN.md with anti-pattern enforcement
review	review.md	QA audit
debug	debug.md	Root cause + minimal fix
deepsec	deepsec.md	Drive oma-deepsec end-to-end (setup / scan / pr-review / matchers / triage)
scm	scm.md	SCM + Git operations + Conventional Commits
docs	docs.md	Documentation drift verify + sync
recap	recap.md	Daily / period AI conversation recap
deepinit	deepinit.md	Project harness init (AGENTS.md / ARCHITECTURE.md / docs/)
pdf	pdf.md	PDF → Markdown via opendataloader-pdf
video	video.md	Brief → script → assets → render-spec → Remotion (oma-video)

(tools and stack-set are slash-invoked utilities, intentionally excluded from keyword detection.)

To execute: read and follow .agents/workflows/{name}.md step by step.

Auto-Detection

Hooks: UserPromptSubmit (keyword detection), PreToolUse, Stop (persistent mode) Keywords defined in .agents/hooks/core/triggers.json (multi-language). Persistent workflows (orchestrate, ultrawork, work, ralph) block termination until complete. Deactivate: say "workflow done".

Rules

1. Do not modify .agents/ files (SSOT protection).
2. Workflows execute via keyword detection or explicit naming, never self-initiated.
3. Response language follows .agents/oma-config.yaml

Project Rules

Read the relevant file from .agents/rules/ when working on matching code.

Rule	File	Scope
backend	.agents/rules/backend.md	on request
commit	.agents/rules/commit.md	on request
database	.agents/rules/database.md	**/*.{sql,prisma}
debug	.agents/rules/debug.md	on request
design	.agents/rules/design.md	on request
dev-workflow	.agents/rules/dev-workflow.md	on request
frontend	.agents/rules/frontend.md	**/*.{tsx,jsx,css,scss}
i18n-guide	.agents/rules/i18n-guide.md	always
infrastructure	.agents/rules/infrastructure.md	**/*.{tf,tfvars,hcl}
market	.agents/rules/market.md	on request
mobile	.agents/rules/mobile.md	**/*.{dart,swift,kt}
quality	.agents/rules/quality.md	on request