64 lines
2.4 KiB
Markdown
64 lines
2.4 KiB
Markdown
# 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.
|