Add project instructions for AI agents and update related documentation (#205)

Author: yu-iskw

.agents/skills

@@ -0,0 +1 @@
+../.claude/skills

.claude/hooks/run-pre-commit.sh

@@ -0,0 +1,12 @@
+#!/usr/bin/env bash
+set -e
+
+cd "${CLAUDE_PROJECT_DIR:-.}"
+
+output=$(pre-commit run --all-files 2>&1)
+status=$?
+if [ "$status" -ne 0 ]; then
+  echo "$output" >&2
+  exit 2
+fi
+exit 0

.claude/settings.json

@@ -0,0 +1,15 @@
+{
+  "hooks": {
+    "Stop": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/run-pre-commit.sh",
+            "timeout": 180
+          }
+        ]
+      }
+    ]
+  }
+}

.claude/skills/dbt-parser-refresh/SKILL.md

@@ -0,0 +1,71 @@
+---
+name: dbt-parser-refresh
+description: Refreshes dbt artifact schemas from dbt-labs/dbt-core and regenerates Pydantic parser classes. Use when the user asks to update parsers, sync with upstream, download dbt schemas, or regenerate parser models.
+---
+
+# dbt Parser Refresh
+
+## Trigger scenarios
+
+Activate this skill when the user says or implies:
+
+- Refresh parsers, update parsers, sync parsers
+- Update from dbt-core, sync with upstream dbt-core
+- Download dbt schemas, pull schemas from dbt-core
+- Regenerate parser classes, regenerate parser models, run codegen
+
+## Scripts and paths
+
+- Run all commands from the **repository root**.
+- **Download:** `bash dev/download_dbt_schemas.sh [--ref REF] [artifact_type] [version ...]`
+- **Generate:** `bash dev/generate_parser_classes.sh [artifact_type] [version ...]`
+- **Artifact types:** `catalog`, `manifest`, `run-results`, `sources`
+- **Versions:** e.g. `v1`, `v7`. Omit args to process all types and versions.
+
+## Order rule
+
+When doing both download and generate, **always run download first**, then generate.
+
+## Three modes
+
+### 1. Download + generate (default)
+
+When the user wants to refresh or update parsers (e.g. "refresh parsers", "update from dbt-core"):
+
+1. Run `bash dev/download_dbt_schemas.sh` with any user-specified `--ref`, artifact_type, or versions.
+2. Then run `bash dev/generate_parser_classes.sh` with the same artifact_type and versions (no `--ref`).
+
+If the user did not specify scope, use no arguments for both (download all, then generate all).
+
+### 2. Download only
+
+When the user only wants to fetch schemas (e.g. "download dbt schemas", "pull schemas from dbt-core"):
+
+- Run only `bash dev/download_dbt_schemas.sh` with optional `--ref` and artifact_type/version.
+
+### 3. Generate only
+
+When schemas are already present and the user only wants to regenerate code (e.g. "regenerate parsers", "run codegen"):
+
+- Run only `bash dev/generate_parser_classes.sh` with optional artifact_type/version.
+
+## Passing through user intent
+
+- **Ref:** If the user specifies a ref (e.g. `main` or a branch), pass `--ref REF` only to the download script.
+- **Scope:** If they specify an artifact or version (e.g. "just manifest v7"), use the same artifact_type and version(s) for both scripts when running both.
+
+## Example
+
+Full refresh (all types and versions):
+
+```bash
+bash dev/download_dbt_schemas.sh
+bash dev/generate_parser_classes.sh
+```
+
+Refresh only manifest v7:
+
+```bash
+bash dev/download_dbt_schemas.sh manifest v7
+bash dev/generate_parser_classes.sh manifest v7
+```

AGENTS.md

@@ -0,0 +1,34 @@
+# Project instructions for AI agents
+
+This file is the single source of project expectations for Codex, Cursor, and other AI agents. Claude Code uses [CLAUDE.md](CLAUDE.md), which references this file.
+
+## Project overview
+
+dbt-artifacts-parser is a Python package that parses dbt artifacts (catalog, manifest, run-results, sources) as Python objects. Pydantic models are generated from the official dbt artifact JSON schemas (from dbt-labs/dbt-core). We do not manually edit generated parser models; we use dbt artifacts from stable dbt versions only; we support only artifacts whose JSON schemas are publicly available.
+
+See [README.md](README.md) for usage and [CONTRIBUTING.md](CONTRIBUTING.md) for full contribution and implementation policy.
+
+## Setup and commands
+
+Run from the **repository root**.
+
+- **Setup:** `make setup` — installs dependencies and pre-commit hooks.
+- **Test:** `make test`
+- **Lint:** `make lint` (runs pre-commit on all files)
+- **Build:** `make build` — clean, lint, test, then build the package.
+
+## Code and contribution
+
+- Follow the implementation policy in [CONTRIBUTING.md](CONTRIBUTING.md): no manual changes to generated Pydantic models; use the download and generate scripts for any parser updates.
+- Parser codegen: download schemas with [dev/download_dbt_schemas.sh](dev/download_dbt_schemas.sh), then generate classes with [dev/generate_parser_classes.sh](dev/generate_parser_classes.sh).
+
+## Parser refresh workflow
+
+When updating or adding parsers (syncing with dbt-core, regenerating Pydantic models):
+
+1. **Download first:** `bash dev/download_dbt_schemas.sh [--ref REF] [artifact_type] [version ...]`
+2. **Then generate:** `bash dev/generate_parser_classes.sh [artifact_type] [version ...]`
+
+Artifact types: `catalog`, `manifest`, `run-results`, `sources`. Omit arguments to process all types and versions. If the user specifies a ref (e.g. branch), pass `--ref REF` only to the download script.
+
+A project skill **dbt-parser-refresh** encodes this workflow in detail. Skills live in `.claude/skills/` (Cursor and Claude Code). Codex users: this repo provides `.agents/skills` as a symlink to `.claude/skills`, so the same skill is available there.

CLAUDE.md

@@ -0,0 +1,4 @@
+See [AGENTS.md](AGENTS.md) for project overview, setup, commands, and parser refresh workflow.
+
+- When using Claude Code, pre-commit runs as a quality gate on Stop via [.claude/hooks/run-pre-commit.sh](.claude/hooks/run-pre-commit.sh) (configured in [.claude/settings.json](.claude/settings.json)).
+- Use the **dbt-parser-refresh** skill when updating parsers: `.claude/skills/dbt-parser-refresh/SKILL.md` or invoke `/dbt-parser-refresh`.

CONTRIBUTING.md

@@ -56,6 +56,8 @@ It installs the dependencies and set up the pre-commit hooks.
 make setup
 ```
 
+When using [Claude Code](https://code.claude.com/), this repo runs pre-commit as a quality gate when Claude is about to stop. Config lives in [.claude/settings.json](.claude/settings.json) and [.claude/hooks/](.claude/hooks/).
+
 ## How to generate Pydantic models
 
 These are the steps to generate the Pydantic models from dbt artifacts in this package.
@@ -68,3 +70,9 @@ We manage the downloaded JSON schemas in the directory of [dbt_artifacts_parser/
 
 [dev/generate_parser_classes.sh](./dev/generate_parser_classes.sh) is a script to generate Pydantic models from the JSON schemas of dbt artifacts.
 If we want to add new dbt artifact(s), we need to modify the script to generate the new pydantic models.
+
+## AI agents and tools
+
+Project instructions for AI agents (Codex, Cursor, Claude Code) are in [AGENTS.md](./AGENTS.md). Claude Code also uses [CLAUDE.md](./CLAUDE.md), which references AGENTS.md.
+
+Skills live in [.claude/skills/](./.claude/skills/). Cursor and Claude Code load them from there. Codex reads skills from `.agents/skills`; in this repo that path is a symlink to `.claude/skills`, so the same skills are available. The `.cursor/` directory is reserved for future Cursor-specific rules if needed.