AGENTS.md · Rich-Harris/degit

Sections

1. Documentation sync
2. Agent index
3. Project overview
4. Setup commands
5. Development workflow
6. Testing instructions
7. Lint and format
8. Build and release
9. Pull requests and commits

First lines (shown under the repo's MIT license)

# AGENTS.md

Instructions and entry points for coding agents working on this repository. For the open format background, see [agents.md](https://agents.md/).

## Documentation sync

Treat **AGENTS.md** as the agent-facing index for [README.md](README.md), [docs/CONTRIBUTING.md](docs/CONTRIBUTING.md), [docs/SECURITY.md](docs/SECURITY.md), [assets/help.md](assets/help.md), and [skills/degit/SKILL.md](skills/degit/SKILL.md). Keep it aligned with those docs when workflow, release, or navigation facts change.

## Agent index

| Topic                                      | Where to look                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| ------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Keeping human docs and this file aligned   | [Documentation sync](#documentation-sync)                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| User-facing behavior, CLI usage, examples  | [README.md](README.md), [docs/USAGE.md](docs/USAGE.md)                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| License text                               | [LICENSE.md](LICENSE.md)                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| Contributing flow, PR checks, commit style | [docs/CONTRIBUTING.md](docs/CONTRIBUTING.md)                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| Security policy and reporting              | [docs/SECURITY.md](docs/SECURITY.md)                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| Community expectations                     | [docs/CODE_OF_CONDUCT.md](docs/CODE_OF_CONDUCT.md)                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| Published CLI help text                    | [assets/help.md](assets/help.md)                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| End-user degit agent skill                 | [skills/degit/SKILL.md](skills/degit/SKILL.md)                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| CI and security workflows                  | [.github/workflows/quality.yml](.github/workflows/quality.yml), [.github/workflows/verification.yml](.github/workflows/verification.yml), [.github/workflows/security.yml](.github/workflows/security.yml), [.github/workflows/integration.yml](.github/workflows/integration.yml), [.github/workflows/performance.yml](.github/workflows/performance.yml), [.github/workflows/anti-slop.yml](.github/workflows/anti-slop.yml), [.github/workflows/publish.yml](.github/workflows/publish.yml) |
| Library and CLI implementation             | [src/index.ts](src/index.ts), [src/core/orchestrator.ts](src/core/orchestrator.ts), [src/shared/utils.ts](src/shared/utils.ts), [src/bin.ts](src/bin.ts)                                                                                                                                                                                                                                                                                                                                       |
| tsdown build                               | [tsdown.config.ts](tsdown.config.ts)                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| Tests and Vitest settings                  | [test/](test/), [vitest.config.ts](vitest.config.ts)                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| npm scripts and package metadata           | [package.json](package.json)                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |

## Project overview

See [README.md](README.md) for the user-facing overview and [package.json](package.json) for runtime/build metadata.

## Setup commands

See [README.md](README.md) and [docs/CONTRIBUTING.md](docs/CONTRIBUTING.md) for the standard setup flow; [package.json](package.json) is the source of truth for versions and scripts.

## Development workflow

See [package.json](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.

## Testing instructions

Tests live in `test/unit/**/*.test.ts` and `test/integration/**/*.test.ts` (see [vitest.config.ts](vitest.config.ts)). Use `nub run test` for the suite excluding `test/integration/private.test.ts`, and `nub run test:integration` for the integration network suite. Prefer updating or adding tests when changing behavior. Use `nub 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.

## Lint and format

See [package.json](package.json) for lint and format scripts, and [docs/CONTRIBUTING.md](docs/CONTRIBUTING.md) for the contributor workflow and formatting expectations.

## Build and release

`prepublishOnly` runs `nub run test`. CI checks live in [.github/workflows/quality.yml](.github/workflows/quality.yml), [.github/workflows/verification.yml](.github/workflows/verification.yml), [.github/workflows/security.yml](.github/workflows/security.yml), [.github/workflows/performance.yml](.github/workflows/performance.yml), and [.github/workflows/publish.yml](.github/workflows/publish.yml).

## Pull requests and commits

See [docs/CONTRIBUTING.md](docs/CONTRIBUTING.md) for PR shape, single-commit guidance, tests on behavior changes, and Conventional Commits. A `commit-msg` hook requires `feat`/`fix`/`perf`/`revert` commits touching `src/` to stage at least one human-facing doc (`docs/*.md`, `README.md`, `assets/help.md`) and one agent-facing doc (`AGENTS.md`, `llms.txt`, `skills/*/SKILL.md`); opt out per set with `[skip-human-docs]`/`[skip-agent-docs]` or both with `[skip-docs]` in the message. 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/quality.yml), [.github/workflows/verification.yml](.github/workflows/verification.yml), and [.github/workflows/security.yml](.github/workflows/security.yml) before opening a PR.