From 002fde6169f580949021e1a168f8ec6d9e6cfb05 Mon Sep 17 00:00:00 2001
From: Feror <contact@feror.fr>
Date: Fri, 29 May 2026 19:16:50 +0200
Subject: [PATCH] Add agent instructions

---
 AGENTS.md | 64 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 64 insertions(+)
 create mode 100644 AGENTS.md

diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 0000000..052aa6f
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,64 @@
+# Agent Instructions
+
+## Project Snapshot
+
+Sapling is a local-first, Git-native Markdown workspace built with Swift Package Manager. The package root is the source of truth; open `Package.swift` in Xcode when a GUI workflow is needed.
+
+Primary targets:
+
+- `SaplingApp`: SwiftUI app entry point and composition root.
+- `SaplingCore`: shared domain models and business rules.
+- `SaplingWorkspace`: workspace and file tree management.
+- `SaplingGit`: Git protocols and provider implementations.
+- `SaplingEditor`: hybrid Markdown editor MVVM surface.
+- `SaplingRenderer`: Markdown rendering abstractions.
+- `SaplingStorage`: configuration and metadata persistence.
+- `SaplingLogging`: logging support.
+- `SaplingUI`: shared SwiftUI components.
+
+## Development Commands
+
+Run commands from the repository root:
+
+```sh
+swift build
+swift test
+make validate
+```
+
+`make validate` runs formatting, linting, build, and tests. Use it before handing off substantial work when time permits.
+
+Formatting and linting are available through:
+
+```sh
+make format
+make lint
+```
+
+## Git Discipline
+
+- Commit after every significant change unless the user explicitly asks not to commit.
+- Keep commits focused on one coherent change.
+- Check `git status --short` before editing and before committing.
+- Do not include unrelated user changes in a commit.
+- If the worktree already has changes you did not make, leave them in place and work around them.
+- Never discard, reset, or overwrite user changes unless the user explicitly asks for that.
+- Mention any uncommitted unrelated changes in the final handoff.
+
+## Coding Guidelines
+
+- Prefer the existing module boundaries and architecture described in `README` and `Docs/Architecture.md`.
+- Keep changes narrowly scoped to the request.
+- Use protocol-first seams already present in the codebase rather than adding global state or direct platform dependencies.
+- Add or update tests when changing domain logic, editor behavior, Git behavior, or storage semantics.
+- Keep Swift code formatted with the repository scripts.
+- Avoid unrelated refactors while implementing a feature or fix.
+
+## Handoff Expectations
+
+Before finishing:
+
+- Run the most relevant validation command you can afford for the change.
+- Report exactly what was changed.
+- Report which validation commands passed or why they were not run.
+- If a significant change was made, ensure it is committed and include the commit hash in the handoff.