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:

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:

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.

2.4 KiB Raw Permalink Blame History