1 files changed, 65 insertions, 0 deletions
diff --git a/.agent/coding_standards.md b/.agent/coding_standards.md
new file mode 100644
index 0000000..955ec35
--- /dev/null
+++ b/.agent/coding_standards.md
@@ -0,0 +1,65 @@
+# Coding Standards — modal-shell
+
+## Shell
+
+- **Default shell:** bash. Shebang is always `#!/usr/bin/env bash`.
+- **Strict mode:** Every file starts with `set -euo pipefail`. No exceptions.
+- **No bashisms in base.sh:** `base.sh` must also be compatible with zsh (users may source it from their zsh config).
+- **Functions over repetition:** If the same logic appears in two modes, move it to `base.sh`.
+- **No global side effects in sourced files:** `base.sh` sets env vars; it does not print output, start processes, or modify files.
+
+## Naming
+
+- Mode files: lowercase, hyphen-separated, `.sh` suffix. e.g. `db.sh`, `build.sh`, `reset.sh`.
+- Variables in `base.sh`: `UPPER_SNAKE_CASE`. Exported.
+- Local variables in mode files: `lower_snake_case`. Use `local` inside functions.
+- The dispatcher: `ms` (no extension, executable).
+
+## Mode File Structure
+
+```sh
+#!/usr/bin/env bash
+# <one-line description of what this mode does>
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+source "$SCRIPT_DIR/base.sh"
+
+# mode logic here
+```
+
+## Confirmation Pattern for Destructive Modes
+
+```sh
+echo "This will destroy and rebuild the environment."
+read -rp "Continue? [y/N] " confirm
+[[ "$confirm" =~ ^[Yy]$ ]] || { echo "Aborted."; exit 1; }
+```
+
+## Error Handling
+
+- Let `set -e` do the work. Do not swallow errors with `|| true` unless intentional and commented.
+- On expected failure paths, print a helpful message to stderr before exiting: `echo "error: <message>" >&2`
+- Do not use `exit 0` at the end of scripts — implicit success is fine.
+
+## Testing
+
+- Syntax check: `bash -n modes/<name>.sh` before committing any mode file.
+- Dry-run: modes that exec into an environment can be tested with `bash -c 'source modes/base.sh && echo $PROJECT_ROOT'`.
+- No automated test framework required for this project's scope. Manual verification is acceptable.
+
+## The Dispatcher (`ms`)
+
+- Must stay under 40 lines.
+- No logic beyond: find the modes directory, match argument to filename, exec.
+- If no argument: list available modes (strip `.sh`, sort).
+- If unknown mode: print error to stderr, exit 1.
+- Never source the mode file — always exec it (so the mode can itself exec into a shell without forking).
+
+## What Not to Do
+
+- No `eval`.
+- No `set +e` blocks.
+- No hardcoded paths outside of `base.sh`.
+- No secrets in any file tracked by git.
+- No modes that call other modes.