docs: add development workflow guide

Introduce DEVELOPMENT.md as the shared source of truth for repository workflow and document responsibilities, and align README, ARCHITECTURE, and AGENTS with the new split.

Author: blauerberg

AGENTS.md

@@ -12,11 +12,8 @@ to review.
 
 ## Workflow
 
-- Use Conventional Commits for commit messages.
-- Do not create pull requests by default.
-- For small changes, commit directly on the default branch.
-- For larger changes, create a short-lived branch, finish the work there, merge
-  it back into the default branch locally, then push.
+For shared repository workflow such as verification, commit conventions, branch
+usage, and documentation boundaries, follow `DEVELOPMENT.md`.
 
 ## Testing
 
@@ -39,6 +36,7 @@ to review.
 
 ## Documentation
 
+- Shared documentation responsibilities are defined in `DEVELOPMENT.md`.
 - `README.md` is the human-facing entry point: keep it focused on overview,
   setup, and a small amount of stable operational guidance such as local file
   locations when that improves usability.

ARCHITECTURE.md

@@ -2,7 +2,7 @@
 
 This document is the canonical description of the repository's structure and
 runtime behavior. `README.md` stays focused on the human-facing entry point and
-setup flow.
+setup flow, and `DEVELOPMENT.md` covers development workflow and verification.
 
 ## Responsibility
 
@@ -81,13 +81,3 @@ These files are created if missing and are intentionally not managed here:
 - `~/.zshrc.local`: machine-specific shell settings and secrets.
 - `~/.zshrc.env`: early shell environment settings loaded before Oh My Zsh.
 - `~/.gitconfig_local`: machine-specific Git includes and identities.
-
-## Verification
-
-Use the repository shell checks as a lightweight contract test for the dotfiles
-loader and integrations:
-
-```sh
-for test in tests/*.sh; do sh "$test"; done
-zsh -n zsh/zshrc
-```

DEVELOPMENT.md

@@ -0,0 +1,54 @@
+# Development
+
+This document is the canonical description of how to make and verify changes in
+this repository. `README.md` is the human-facing entry point,
+`ARCHITECTURE.md` covers repository structure and runtime behavior, and
+`AGENTS.md` adds agent-specific operating rules.
+
+## Change Scope
+
+Keep changes small, practical, and easy to review. Prefer the existing
+structure, naming, and patterns in the repository over new abstractions or
+incidental cleanup.
+
+## Verification
+
+Keep verification lightweight and relevant. Use the smallest command that
+exercises the changed behavior.
+
+- For documentation-only changes, proofreading and `git diff --check` are
+  enough.
+- For repository-wide shell checks, run:
+
+```sh
+for test in tests/*.sh; do sh "$test"; done
+zsh -n zsh/zshrc
+```
+
+Prefer testing dotfiles contracts such as loader behavior, public environment
+controls, conditional branches, bootstrap effects, and a small representative
+sample over exhaustive configuration catalogs.
+
+## Git Workflow
+
+Use Conventional Commits, and write commit messages in English.
+
+Do not create pull requests by default.
+
+For small changes, commit directly on the default branch. For larger changes,
+create a short-lived branch, finish the work there, merge it back into the
+default branch locally, then push.
+
+## Documentation
+
+Prefer SSOT. When a detail already lives in config, scripts, CI definitions, or
+source files, docs should point to that authority instead of restating volatile
+implementation detail.
+
+- `README.md`: human-facing entry point, overview, setup, and a small amount of
+  stable operational guidance.
+- `ARCHITECTURE.md`: repository structure, runtime behavior, and stable system
+  contracts shared by humans and agents.
+- `DEVELOPMENT.md`: shared development workflow, verification, documentation
+  boundaries, and git conventions.
+- `AGENTS.md`: agent-specific operating constraints and editing guidance.

README.md

@@ -3,8 +3,9 @@
 My dotfiles.
 
 This repository links and loads configuration, and may install zsh plugins
-managed by this repository. For architecture and repository conventions, see
-[ARCHITECTURE.md](ARCHITECTURE.md).
+managed by this repository. For architecture, see
+[ARCHITECTURE.md](ARCHITECTURE.md). For development workflow and documentation
+responsibilities, see [DEVELOPMENT.md](DEVELOPMENT.md).
 
 ## Supported Environments