Add AI agents instructions

.agents/project.md

@@ -0,0 +1,4 @@
+# Project
+
+Read [../PROJECT.md](../PROJECT.md) for the `embed-code-go` project overview,
+package map, and documentation pointers.

.agents/skills/README.md

@@ -0,0 +1,10 @@
+# Skills
+
+This index is only a quick orientation aid. Each skill's frontmatter remains
+the routing source of truth.
+
+- `go-engineer`: Go implementation, debugging, refactoring, and behavior review.
+- `go-tester`: Go test authoring, fixture design, and test review.
+- `writer`: documentation authoring, editing, restructuring, and claim checks.
+- `review-docs`: documentation review for prose, examples, comments, and
+  agent instructions.

.agents/skills/go-engineer/SKILL.md

@@ -0,0 +1,170 @@
+---
+name: go-engineer
+description: >
+  Encodes the embed-code-go Go implementation policy and recurring pitfalls.
+  Use whenever writing, modifying, refactoring, debugging, or reviewing Go code
+  in this repository, especially CLI/config parsing, parser state transitions,
+  embedding behavior, fragmentation, filesystem handling, error reporting,
+  package APIs, formatting, vetting, and build verification.
+---
+
+# Go Engineering
+
+Baseline Go knowledge is assumed. This skill does not teach the language; it
+encodes the project policy, package boundaries, and traps that recur in `embed-code-go` work.
+
+## When to Use
+
+Use `go-engineer` for implementation work in Go:
+
+- Writing or changing `.go` files.
+- Debugging `embed` or `check` behavior.
+- Refactoring package APIs or shared helpers.
+- Reviewing Go code for correctness and maintainability.
+
+This skill is the baseline for production Go and helper code. Test-writing
+conventions live in `.agents/skills/go-tester/SKILL.md`; documentation review
+lives in `.agents/skills/review-docs/SKILL.md`.
+
+## Fast Path for Agents
+
+1. Read `AGENTS.md`, `PROJECT.md`, and relevant implementation files.
+2. Ask clarifying questions before editing if the requested outcome, scope,
+   compatibility constraints, or verification target is not explicit.
+3. Apply the MUST / MUST NOT rules while editing.
+4. Defer test structure and fixtures to `go-tester` for test changes.
+5. Verify with the narrowest relevant Go test first, then the repository-level
+   checks listed below.
+6. Follow the git-history policy in `AGENTS.md`.
+
+## Setup Check
+
+Run this before non-trivial Go changes or when the package baseline is unclear:
+
+1. **Go version** - target the version in `go.mod`.
+2. **Package owner** - identify whether the behavior belongs in `cli/`,
+   `configuration/`, `embedding/`, `embedding/parsing/`, `fragmentation/`, or a
+   support package.
+3. **Test owner** - identify the package test suite and fixtures that already
+   cover the behavior.
+4. **Commands** - plan `gofmt`, focused `go test`, `go vet ./...`, full
+   `go test ./...`, and `go build -trimpath main.go` when integration or CLI
+   behavior changes.
+
+## Processing Flow
+
+The normal execution path is:
+
+1. `main.go` reads arguments, configures logging, validates input, and dispatches
+   `embed` or `check` mode.
+2. `cli/` reads flags or YAML and produces one or more normalized
+   `configuration.Configuration` values.
+3. `embedding.EmbedAll` or `embedding.CheckUpToDate` selects documentation files
+   using include and exclude patterns.
+4. An `embedding.Processor` processes one document at a time.
+5. `embedding/parsing/` walks the document through explicit states, records each
+   instruction and its code fence, and preserves unrelated document content.
+6. A parsed `Instruction` resolves source content through `fragmentation/`,
+   optional line patterns, indentation normalization, and comment filtering.
+7. Embed mode writes changed documents. Check mode compares generated content
+   with existing content and must not modify documentation.
+
+When behavior changes, trace the complete path instead of patching only the
+first function that exposes the symptom.
+
+## MUST DO
+
+- **Preserve package ownership.** Keep process orchestration in `main.go`,
+  argument and YAML handling in `cli/`, normalized defaults in
+  `configuration/`, document orchestration in `embedding/`, syntax recognition
+  in `embedding/parsing/`, and source extraction in `fragmentation/`.
+- **Trace the full flow.** For behavior changes, walk
+  `main` -> `cli`/`configuration` -> `embedding` -> `embedding/parsing` and
+  `fragmentation` -> write or compare.
+- **Keep functions small and explicit.** Prefer direct code over broad helpers
+  unless an abstraction removes real duplication or clarifies a shared contract.
+- **Document every function and method.** Add concise doc comments to new or
+  changed functions, including unexported ones. Exported comments start with
+  the declaration name.
+- **Return actionable errors.** Add file, pattern, instruction, or operation
+  context where that context becomes known.
+- **Aggregate independent failures with `errors.Join`.** Continue processing
+  only when doing so produces a more complete and still safe result.
+- **Preserve deterministic behavior.** Document order, fragment order,
+  separators, writes, and reported stale files must stay stable.
+- **Use OS-aware paths.** Preserve cross-platform behavior for separators,
+  Windows drive paths, and file URLs.
+- **Format changed Go files with `gofmt`.**
+
+## MUST NOT DO
+
+- **No new panics in library packages.** Return errors; leave process exit and
+  panic recovery at the executable boundary.
+- **No broad utility dumping ground.** Do not move parser, filesystem,
+  fragmentation, and CLI behavior into a catch-all helper package.
+- **No single-use interface by default.** Introduce an interface only at a real
+  consumer, ownership, or test boundary.
+- **No speculative concurrency.** This CLI is document and filesystem heavy;
+  add concurrency only for a measured problem with deterministic aggregation
+  and write safety.
+- **No log-and-return in lower layers.** Return the error; log at the CLI
+  boundary or at intentional progress/warning points.
+- **No message-string error contracts.** Prefer typed errors, sentinels, or
+  `errors.Is` / `errors.As`.
+- **No dependency updates unless the confirmed task requires them.**
+- **No local history exceptions.** Follow the git-history policy in `AGENTS.md`.
+
+## Project Hotspots
+
+### Parser State Machine
+
+- Read `embedding/parsing/constants.go`, `state.go`, `context.go`, the affected
+  state, and `embedding/processor.go` together.
+- Preserve self-closing, paired, and multiline instruction forms.
+- Keep ordinary Markdown fences separate from embedding fences.
+- Preserve the opening fence's marker length and indentation when recognizing
+  the closing fence and rendering source lines.
+- Report malformed instructions at their start line with a concrete reason.
+- Prefer concrete parse reasons: missing tag end, missing closing tag, invalid
+  XML, missing code fence, or unclosed code fence.
+- Do not consume unrelated later content to recover from invalid XML.
+
+### Embedding And Check Modes
+
+- Embed mode may rewrite only documents whose generated content changed.
+- Check mode is read-only and reports stale documents.
+- Shared processing changes should preserve both modes.
+
+### Fragmentation
+
+- Preserve whole-file, named-fragment, exact-pattern, and range-pattern extraction.
+- Keep partition ordering, separator rendering, indentation normalization, and
+  comment filtering stable.
+- Keep source-root names and lookup errors actionable.
+
+## Verification
+
+Run the narrowest relevant checks first, then broaden:
+
+1. `gofmt -w <changed-go-files>`
+2. `go test ./<affected-package>`
+3. `go vet ./...`
+4. `go test ./...`
+5. `go build -trimpath main.go` when CLI, configuration, embedding, or package
+   integration behavior changed
+
+For user-visible CLI behavior, run a focused `go run ./main.go ...` scenario
+against existing fixtures when practical.
+
+## Output Format
+
+When producing code:
+
+1. A short plan after clarification.
+2. The code changes.
+3. A verification checklist with command results.
+4. A note about any remaining risk or unrun check.
+
+When reviewing code: call out MUST-DO / MUST-NOT violations explicitly and
+suggest the minimal fix. End with a one-line verdict: `APPROVE`,
+`APPROVE WITH CHANGES`, or `REQUEST CHANGES`.

.agents/skills/go-engineer/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Go Engineer"
+  short_description: "Implement Go changes for embed-code-go"
+  default_prompt: "Use $go-engineer after reading AGENTS.md and PROJECT.md to implement a scoped Go change in embed-code-go."

.agents/skills/go-tester/SKILL.md

@@ -0,0 +1,138 @@
+---
+name: go-tester
+description: >
+  The embed-code-go authority on writing and reviewing Go tests. Use when
+  adding, restructuring, or reviewing tests for Go production code, parser
+  behavior, embedding flows, fragmentation, CLI/config validation, fixtures,
+  malformed inputs, regression coverage, focused go test commands, or full
+  suite verification. go-engineer remains the baseline for Go inside test
+  helper code.
+---
+
+# Go tester
+
+This skill is the single source of truth for how tests are written in
+`embed-code-go`. It does not decide what behavior to change; it decides how to
+cover the known behavior once the cases are identified.
+
+Two companions own neighboring concerns:
+
+- `.agents/skills/go-engineer/SKILL.md` - Go implementation policy and production code correctness.
+- `.agents/skills/review-docs/SKILL.md` - documentation review for test fixtures and
+  Markdown docs when prose changes are part of the task.
+
+## Core Policy
+
+1. **Follow existing Ginkgo/Gomega style.** Packages use `Describe` and `It`
+   suites with Gomega expectations. Match the surrounding package before adding
+   a new style.
+2. **Test behavior at the owning package.** Put the focused regression test near
+   the package that owns the bug or feature.
+3. **Use fixtures for document behavior.** Parser and embedding changes should
+   add or update files under `test/resources/` when source or document shape is
+   part of the contract.
+4. **Cover both success and failure when parser behavior changes.** Malformed
+   instruction tests are as important as successful embedding tests.
+5. **Keep tests deterministic and portable.** Avoid machine-specific absolute
+   paths, map iteration order, hidden local files, and OS-specific separators
+   unless the code intentionally emits them.
+6. **Follow git-history policy.** Do not commit or rewrite history unless
+   `AGENTS.md` allows it.
+
+## Workflow
+
+1. **Read first.** Read the code under test, its package tests, and relevant
+   fixtures in full.
+2. **Identify the owning suite.** Prefer extending an existing `Describe` block
+   over creating a parallel test structure.
+3. **Choose the level.** Use package-level unit tests for pure helpers, parser
+   tests for state-machine behavior, and embedding tests for end-to-end
+   document rewrites or stale checks.
+4. **Add the minimal fixture.** Create or update only the source and document
+   fixture needed to express the behavior.
+5. **Assert behavior, not implementation trivia.** Prefer outputs, changed-file
+   lists, typed errors, and line numbers over private state.
+6. **Run the narrowest test first.** Broaden only after the focused test passes.
+
+## Naming And Structure
+
+- Keep test files beside the package they test, using the existing `_test.go`
+  naming pattern.
+- Match the package's current package name. Do not switch between internal and
+  external test packages without a reason.
+- Use `Describe` for the unit or component under test and `It` for the behavior sentence.
+- Keep setup close to the test unless the package already has a clear helper pattern.
+- Use `BeforeEach` only when it reduces duplication without hiding essential state.
+- Avoid broad helper functions that make the fixture harder to read.
+
+## Assertions
+
+- Use Gomega matchers already used by the package.
+- Prefer exact content assertions for rendered snippets when formatting is the contract.
+- Prefer typed error checks with `errors.As` when the code exposes a typed error.
+- Verify line numbers for malformed instructions, especially when the bug is an
+  EOF or later-fence misreport.
+- Avoid matching full error strings unless the user-facing message itself is
+  the behavior under test.
+
+## Fixture Guidance
+
+### Documentation Fixtures
+
+- Put documentation files under `test/resources/docs/`.
+- Keep one behavior per fixture unless a multi-case document is already the
+  package convention.
+- Name malformed fixtures after the malformed condition, not the expected implementation fix.
+- Preserve indentation and code-fence marker details when those are part of the behavior.
+
+### Source Fixtures
+
+- Put source files under the existing language folder in `test/resources/code/`.
+- Add the smallest source file or fragment marker needed for the behavior.
+- Reuse existing Java, Kotlin, plain-text, or literal-pattern fixtures when
+  doing so keeps the test clearer.
+
+### Prepared Fragments
+
+- Use `test/resources/prepared-fragments/` only for behavior that already relies
+  on prepared expected content.
+- Keep expected files stable and easy to diff.
+
+## Verification
+
+Use the smallest useful command while iterating:
+
+- Parser changes: `go test ./embedding/parsing`
+- Embedding behavior: `go test ./embedding`
+- Fragment extraction: `go test ./fragmentation`
+- CLI/config behavior: `go test ./cli`
+- Shared or uncertain behavior: `go test ./...`
+
+After Go test code changes, run:
+
+1. `gofmt -w <changed-go-files>`
+2. the focused package test
+3. `go test ./...`
+
+Run `go vet ./...` when the test change also changes helper code, exported
+test support, or production code.
+
+## Repo Notes
+
+- Tests use the repository fixtures heavily; prefer a focused fixture over a
+  large inline string when document shape matters.
+- Do not rely on local absolute paths except where the code intentionally emits
+  a `file://` reference.
+- If the implementation change is still unclear, return to `go-engineer`
+  before writing tests.
+
+## Output Format
+
+When writing tests:
+
+1. State the behavior being covered.
+2. List fixtures added or changed.
+3. Report focused and full test commands run.
+
+When reviewing tests: group findings as `Must fix`, `Should fix`, and `Nits`.
+End with `APPROVE`, `APPROVE WITH CHANGES`, or `REQUEST CHANGES`.

.agents/skills/go-tester/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Go Tester"
+  short_description: "Write embed-code-go Go tests"
+  default_prompt: "Use $go-tester after reading AGENTS.md and PROJECT.md to add or review tests in embed-code-go."