# Agent Guide

Guidance for anyone writing code in PureYAML.

## Rule Loading

At the start of a session, read this file and the rules under `docs/rules/` that
match the task. Confirm by replying with `rules-loaded` and name the files you
loaded.

For code changes, load at minimum:

- `docs/rules/code-style.md`
- `docs/rules/namespacing.md`
- `docs/rules/cross-platform.md`
- `docs/rules/testing.md`
- `docs/rules/verification.md`
- `docs/rules/commits.md`

## What PureYAML Is

PureYAML is a dependency-free YAML package written entirely in Swift.

The package must stay:

- pure Swift
- root Swift package layout, with `Package.swift` at repository root
- dependency-free
- Linux-compatible
- WebAssembly/WASI-compatible
- namespaced under `PureYAML`

The private `PureYAMLResearch` repo is for studying Yams and libyaml behavior.
Do not copy C code or upstream Yams source into this public package.
Keep attribution in `ATTRIBUTION.md` accurate when compatibility work references
Yams or CYaml behavior.

## Namespace Rules

Every public type lives under the `PureYAML` namespace tree and mirrors its
folder:

- `Sources/Model/Value.swift` declares `PureYAML.Model.Value`
- `Sources/Parsing/Parser.swift` declares `PureYAML.Parsing.Parser`
- `Sources/Emitting/Dumper.swift` declares `PureYAML.Emitting.Dumper`
- `Sources/Validation/Validator.swift` declares `PureYAML.Validation.Validator`

No top-level public concrete types except the root `public enum PureYAML`.

## Dependency Rules

`Package.swift` must keep `dependencies: []`.

Do not add external packages, C targets, system libraries, Foundation-only
workarounds, JavaScript tooling, or generated parser dependencies without an
explicit maintainer decision.

## Verification

Before claiming a change is complete, run and cite:

```sh
bash scripts/check-style.sh
bash scripts/check-namespacing.sh
bash scripts/check-changelog-touched.sh
swiftformat . --config .swiftformat --lint
swiftlint --config .swiftlint.yml --strict
swift build
swift test
bash scripts/check-linux.sh
bash scripts/check-wasm.sh
```

Enable local hooks:

```sh
git config core.hooksPath .githooks
```