Instructions and entry points for coding agents working on this repository. For the open format background, see agents.md.
Treat AGENTS.md as the agent-facing index for README.md, docs/CONTRIBUTING.md, docs/SECURITY.md, assets/help.md, and skills/degit/SKILL.md. Keep it aligned with those docs when workflow, release, or navigation facts change.
| Topic | Where to look |
|---|---|
| Keeping human docs and this file aligned | Documentation sync |
| User-facing behavior, CLI usage, examples | README.md, docs/USAGE.md |
| License text | LICENSE.md |
| Contributing flow, PR checks, commit style | docs/CONTRIBUTING.md |
| Security policy and reporting | docs/SECURITY.md |
| Community expectations | docs/CODE_OF_CONDUCT.md |
| Published CLI help text | assets/help.md |
| End-user degit agent skill | skills/degit/SKILL.md |
| CI and security workflows | .github/workflows/quality.yml, .github/workflows/verification.yml, .github/workflows/security.yml, .github/workflows/integration.yml, .github/workflows/performance.yml, .github/workflows/documentation-sync.yml, .github/workflows/anti-slop.yml, .github/workflows/publish.yml |
| Library and CLI implementation | src/index.ts, src/core/orchestrator.ts, src/shared/utils.ts, src/bin.ts |
| tsdown build | tsdown.config.ts |
| Tests and Vitest settings | test/, vitest.config.ts |
| npm scripts and package metadata | package.json |
See README.md for the user-facing overview and package.json for runtime/build metadata.
See README.md and docs/CONTRIBUTING.md for the standard setup flow; package.json is the source of truth for versions and scripts.
See package.json for the build, dev, and audit scripts. Source of truth for behavior is src/ plus tests; the published artifact is under dist/ after build.
Tests live in test/unit/**/*.test.ts and test/integration/**/*.test.ts (see vitest.config.ts). Use bun run test for the suite excluding test/integration/private.test.ts, and bun run test:integration for the integration network suite. Prefer updating or adding tests when changing behavior. Use bun run format:ci after edits that touch Markdown or JSON.
Test names should follow the it('X when Y') pattern so behavior and trigger are both obvious.
As a rule of thumb, keep one describe block per test file. If a file hits the max-lines rule, prefer a targeted suppression on that describe block instead of splitting it up just to satisfy the linter. Split into multiple describe blocks only when it actually improves readability.
The private integration suite in test/integration/private.test.ts keeps built-in private SSH fixtures behind SSH_PRIVATE_KEY; verification should not assume private repos are available unless that secret is set.
When verifying production-only bugs in the CLI, reproduce with the published degit package (for example npx degit@latest ...) instead of running the raw repository source directly.
See package.json for lint and format scripts, and docs/CONTRIBUTING.md for the contributor workflow and formatting expectations.
prepublishOnly runs bun run test. CI checks live in .github/workflows/quality.yml, .github/workflows/verification.yml, .github/workflows/security.yml, .github/workflows/performance.yml, and .github/workflows/publish.yml.
See docs/CONTRIBUTING.md for PR shape, single-commit guidance, tests on behavior changes, and Conventional Commits. Add unreleased notes only for package-facing changes such as features, fixes, or breaking changes; do not add changelog entries for repo-maintenance-only updates like CI workflow changes, dependency bumps, or documentation-only edits unless they affect the published package or user-facing behavior. Match the checks in .github/workflows/quality.yml, .github/workflows/verification.yml, and .github/workflows/security.yml before opening a PR.