awesome-quant Agent Skills & AI Rules

# AGENTS.md

## Project Overview

`awesome-quant` is a curated list of quantitative finance libraries, packages,
and resources. The source of truth is `README.md`; the static website is
generated into `site/index.html`.

The README is organized by category headings (`##`), not by language headings.
Project metadata is stored in inline backtick tags inside each entry. Tags commonly identify
languages, but may also identify runtimes, protocols, interfaces, data types, or domains.

## Architecture

1. `README.md` contains curated entries.
2. `parse.py` parses `README.md`, enriches GitHub/CRAN/PyPI metadata, and writes
   `site/projects.csv`.
3. `site/generate.py` reads `site/projects.csv` when present, otherwise parses
   `README.md` directly for local previews, then writes `site/index.html`.
4. `.github/workflows/build.yml` runs the parser and generator, then deploys
   `site/` to GitHub Pages.

## Work Tracking and Planning

- Linear is the system of record for issues, prioritization, specifications,
  designs, and implementation plans.
- Manage GitHub-originated issues through their synced Linear issues. Do not
  create a second internal tracker for the same work.
- Store each specification, design, and implementation plan as a Linear
  document attached to the corresponding Linear issue. Do not add task-specific
  planning documents to the repository.
- Keep repository documentation for durable project and user documentation only.
- GitHub remains the public contribution surface for pull requests and public
  issue discussion; use Linear for internal status, priority, and planning.

## Commands

```bash
# Install deps (requires Python 3.11+)
uv sync --no-install-project

# Validate README entries changed in a PR
uv run python scripts/validate_readme.py --diff-from origin/main

# Validate the full README; legacy format/duplicate/URL issues are warnings by default
uv run python scripts/validate_readme.py

# Run parser (requires GitHub token)
GITHUB_ACCESS_TOKEN=<token> uv run python parse.py

# Generate static site
uv run python site/generate.py
```

## Entry Format

The critical parser regex is:

```text
^\s*- \[(.*)\]\((.*)\) - (.*)$
```

Accepted entry examples:

```markdown
- [Project Name](https://github.com/owner/repo) - `Python` - Description ending with a period.
- [Project Name](https://github.com/owner/repo) - `Python` `Rust` - Description ending with a period.
- [Project Name](https://site.com) - `Python` - Description ending with a period. [GitHub](https://github.com/owner/repo)
- [Package Name](https://cran.r-project.org/package=pkg) - `R` - Description ending with a period.
- [package-name](https://pypi.org/project/pkg/) - `Python` - Description ending with a period.
```

Rules:

- New non-commercial entries must include one or more concise backtick tags followed by ` - `.
  Tags form a compact tag cloud and are not restricted to programming languages.
- Each tag must use its own backtick pair, for example `` `Python` `C++` `MCP` ``.
- Descriptions must end with a period before the optional `[GitHub](...)` link.
- URLs in new entries must use `https://`.
- A valid GitHub repository used as the main URL or exact `[GitHub](...)` suffix is preferred
  and is a strong positive relevance signal, but it is not universally required. Functional
  section placement requires a repository containing substantive implementation; a thin SDK,
  integration, examples, generated-data, or marketing repository does not qualify.
- Hosted commercial/proprietary products without substantive public source belong in
  `## Commercial & Proprietary Services`, even when a thin repository exists. Repository-less
  services qualify only under the permanent free tier and transparency rules in
  `CONTRIBUTING.md`.
- Treat a commercial service with only a thin SDK, integration, examples, generated-data, or
  marketing repository as repository-less for every eligibility check.
- Backtick tags are optional only for commercial services and other metadata-free
  sections such as `Related Lists`.
- `Historical & Archived Projects` is the documented exception to normal activity and
  archive-state requirements. Entries still require substantive, reachable, documented source
  and the `Historical` tag; use `CONTRIBUTING.md` for eligibility.
- Use `CONTRIBUTING.md` as the user-facing source for contribution rules.

## PR Review Workflow

This repo receives most contributions as pull requests adding README entries.
Use Codex repo skills for repeatable review workflows:

- `$sprr` - single PR reviewer.
- `$bprr` - bulk PR reviewer.
- `$update-pypi-dates` - refresh tracked PyPI last-updated dates.
- `$create-entry` - draft or add README entries from a URL, GitHub issue, or Linear issue.

Review requirements:

1. Only review the PRs the user asked you to review.
2. Use GitHub MCP tools for PR operations, not the `gh` CLI.
3. Present findings before any PR-modifying action.
4. Always ask the user before commenting, labeling, closing, or merging.
5. Check section placement, duplicates in `README.md`, entry format, URL format,
   and project activity/documentation. Give substantial positive weight to a verifiable
   GitHub repository mentioned as either the main URL or exact suffix, while confirming that
   functional-section repositories contain substantive implementation.
6. Manually assess commercial entries for free-tier usefulness, payment information,
   public pricing and limits, public documentation/methodology/examples, stable non-tracking
   URLs, concise factual description tone, and repository substance.
7. Commercial submissions without a qualifying permanent free tier—including paid-only,
   trial-only, demo-only, and waitlist-only offerings—are `REJECT`. Reserve `NEEDS CHANGES` for
   correctable evidence or disclosure, wording, URL, documentation, or placement defects when
   the underlying offering can qualify.
8. Use the `reviewed` label only after the user approves a review comment.

## GitHub MCP Tools

This project expects Codex to have a GitHub MCP server configured for PR work.
Useful tool capabilities include:

- List open pull requests.
- Get PR details, files, comments, labels, and diffs.
- Fetch `README.md` from the default branch for duplicate checks.
- Add PR comments and labels.
- Merge pull requests after explicit user approval.

See `docs/codex-setup.md` for local Codex setup notes. If GitHub MCP tools are
not available in a session, report that PR operations are blocked and ask the
user to configure the MCP server.

## Local Validation Notes

- `scripts/validate_readme.py --diff-from <ref>` is intended for PR checks. It
  validates only added README entries and treats duplicates/URL issues as errors
  for those additions.
- `scripts/validate_readme.py` validates the full README. Legacy format, duplicate, and
  URL problems are reported as warnings unless strict flags are used.
- `parse.py` requires `GITHUB_ACCESS_TOKEN`; `site/generate.py` can run without
  the token if `site/projects.csv` already exists or if it falls back to direct
  README parsing.