wehub-resource-sync
102 lines
4.2 KiB
Markdown
102 lines
4.2 KiB
Markdown
# AGENTS.md
|
|
|
|
Repository guidance for Codex, Claude Code, Cursor, pi.dev, and other AI coding agents.
|
|
|
|
## Scope
|
|
|
|
This is the Composio SDK v3 monorepo. Most product code lives in `ts/` and `python/`; docs live in `docs/`. Branch new work from `next` and target PRs at `next` unless the user says otherwise.
|
|
|
|
## First Steps
|
|
|
|
1. Read the nearest nested `AGENTS.md` before editing a subtree.
|
|
2. Preserve unrelated dirty work. Do not revert, delete, or reformat files outside the requested scope.
|
|
3. Treat `.agents/skills` as the canonical local skill tree. `.claude/skills` is a compatibility symlink and must not be edited as a separate copy.
|
|
4. Do not edit generated SDK surfaces or vendor trees — see [Generated And Vendored Paths](#generated-and-vendored-paths).
|
|
5. Verify every command you write against the current `package.json`, `Makefile`, `noxfile.py`, or workflow file.
|
|
|
|
## Skill Routing
|
|
|
|
Use the smallest relevant skill:
|
|
|
|
- `repo-guidance`: repo layout, branch/PR workflow, changesets, generated files, or cross-repo maintenance.
|
|
- `skill-maintenance`: adding or changing local skills, skill references, compatibility mirrors, or validation.
|
|
- `bug-fixing`: fixing a defect and choosing regression tests.
|
|
- `cross-sdk-parity`: aligning TypeScript and Python behavior, generated client bumps, or API contract drift.
|
|
- `docs-decisions`: docs site work, changelogs, docs decisions, or docs automation.
|
|
- `eve`: durable backend AI agents built with the eve framework.
|
|
- `typescript-sdk`, `typescript-testing`, `typescript-providers`: TypeScript SDK/core/provider work.
|
|
- `cli-command`, `cli-e2e`: CLI design/implementation or CLI end-to-end tests.
|
|
- `python-sdk`, `python-testing`, `python-providers`, `python-release`: Python SDK/provider/testing/release work.
|
|
|
|
## Repository Map
|
|
|
|
```text
|
|
ts/ TypeScript SDK workspace
|
|
packages/core/ @composio/core
|
|
packages/providers/ TypeScript provider adapters
|
|
packages/cli/ Effect-based CLI
|
|
e2e-tests/ Docker runtime and CLI E2E tests
|
|
python/ Python SDK and provider packages
|
|
docs/ Fumadocs documentation site
|
|
.agents/skills/ Canonical local agent skills
|
|
docs/agent-guidance/ Neutral docs-agent context and workflow instructions
|
|
docs/decisions/ Neutral docs decisions and ADR-style records
|
|
```
|
|
|
|
## Generated And Vendored Paths
|
|
|
|
Do not hand-edit these. They are regenerated or vendored, and edits will be overwritten. They are also marked `linguist-generated`/`linguist-vendored` in `.gitattributes`.
|
|
|
|
- `ts/vendor/**` — vendored read-only snapshots of Effect and Clack (git submodules); reference only.
|
|
- `ts/packages/cli-local-tools/vendor/**` — vendored local-tool sources (git submodules).
|
|
- `ts/packages/core/generated/**`, `ts/packages/core/pack/generated/**` — generated SDK surfaces produced by `composio generate` / the build pipeline.
|
|
- `pnpm-lock.yaml`, `uv.lock`, `**/bun.lock` — package-manager lockfiles; change them by running the package manager, never by hand.
|
|
|
|
## Common Commands
|
|
|
|
Use `mise install` for the pinned toolchain. pnpm is managed through mise, not Corepack.
|
|
|
|
```bash
|
|
pnpm install
|
|
pnpm build
|
|
pnpm build:packages
|
|
pnpm lint
|
|
pnpm format
|
|
pnpm typecheck
|
|
pnpm test
|
|
pnpm test:e2e
|
|
pnpm test:e2e:cli
|
|
pnpm validate:agent-skills
|
|
pnpm validate:skill-routing
|
|
```
|
|
|
|
Python commands run from `python/` unless otherwise noted:
|
|
|
|
```bash
|
|
make env
|
|
source .venv/bin/activate
|
|
make fmt
|
|
make chk
|
|
make tst
|
|
make snt
|
|
make build
|
|
```
|
|
|
|
## Release And Package Notes
|
|
|
|
- TypeScript package releases use Changesets. Add a changeset only when published TypeScript packages change.
|
|
- Documentation-only and agent-guidance-only changes do not need a changeset.
|
|
- Python release metadata lives in `python/pyproject.toml`, `python/setup.py`, and `uv.lock`.
|
|
- Bumping generated clients is manual. Verify the package version is published before changing pins.
|
|
|
|
## Local Guidance Files
|
|
|
|
- TypeScript workspace: `ts/AGENTS.md`
|
|
- Core SDK: `ts/packages/core/AGENTS.md`
|
|
- TypeScript providers: `ts/packages/providers/AGENTS.md`
|
|
- CLI: `ts/packages/cli/AGENTS.md`
|
|
- E2E tests: `ts/e2e-tests/AGENTS.md`
|
|
- Python SDK: `python/AGENTS.md`
|
|
- Python providers: `python/providers/AGENTS.md`
|
|
- Docs: `docs/AGENTS.md`
|