📝 docs: add improvement plan, AGENTS.md, .editorconfig; rewrite README

niketpathak · claude · niketpathak · commit 4bbd9befe691 · 2026-06-10T14:21:48.000+02:00
- docs/plans/2026-06-10-improvement-plan.md: findings, executed Phase 1,
  proposed Phase 2, decision record for de-vendoring git-prompt.sh
- AGENTS.md: repo map, hard rules and verification steps for agents
- README: layout table, install instructions, git-prompt update usage,
  CI badge and local check commands
- .editorconfig: UTF-8/LF/final-newline baseline

Co-Authored-By: Claude Fable 5 &lt;noreply@anthropic.com&gt;
diff --git a/.editorconfig b/.editorconfig
@@ -0,0 +1,16 @@
+# https://editorconfig.org
+root = true
+
+[*]
+charset = utf-8
+end_of_line = lf
+insert_final_newline = true
+trim_trailing_whitespace = true
+
+[*.{yml,yaml,toml}]
+indent_style = space
+indent_size = 2
+
+[*.md]
+# trailing double-space is meaningful in markdown
+trim_trailing_whitespace = false
diff --git a/AGENTS.md b/AGENTS.md
@@ -0,0 +1,74 @@
+# AGENTS.md
+
+Guidance for AI agents (and humans) working in this repository.
+
+## What this repository is
+
+Personal dotfiles / development-environment preferences. There is **no application code,
+no build step, and no test suite**. Every file here is configuration that gets copied or
+symlinked into `$HOME` on a developer machine. Mistakes ship silently — a broken
+`.zshrc` means a broken shell on the next machine provisioned from this repo, so treat
+small edits with the same care as production code.
+
+## Layout
+
+| Path                            | Maps to (typical)                          | Notes                                              |
+|---------------------------------|--------------------------------------------|----------------------------------------------------|
+| `bash/.bash_profile`            | `~/.bash_profile`                          | Login-shell setup, history, git-prompt wiring, starship |
+| `bash/.bash_aliases`            | `~/.bash_aliases` and `$ZSH_CUSTOM/aliases.zsh` | Shared between bash and zsh — keep it polyglot (no bashisms/zshisms) |
+| `zsh/.zshrc`                    | `~/.zshrc`                                 | Oh My Zsh, plugins, history options, starship       |
+| `zsh/.zshenv`                   | `~/.zshenv`                                | Cargo env only                                      |
+| `git/.gitconfig`                | `~/.gitconfig`                             | Aliases + defaults; `user` section is a placeholder on purpose |
+| `git/.gitignore_global`         | `~/.gitignore_global`                      | Referenced by `core.excludesfile`                   |
+| `starship/starship.toml`        | `~/.config/starship.toml`                  | Prompt config (used by both shells)                 |
+| `terminator/config`             | `~/.config/terminator/config`              | Terminal emulator                                   |
+| `lsd/*.yaml`                    | `~/.config/lsd/`                           | `ls` replacement config                             |
+| `scripts/update-git-prompt.sh`  | run, not installed                         | Fetches latest upstream `git-prompt.sh` to `~/.git-prompt.sh` |
+| `docs/plans/`                   | —                                          | Improvement plans / decision records                |
+
+## Hard rules
+
+1. **Do not vendor third-party scripts.** `git-prompt.sh` was vendored once and went
+   stale; it is now fetched by `scripts/update-git-prompt.sh`. If a new external script
+   is needed, add a fetch/update script instead of committing the file.
+2. **Never commit secrets or personal data.** The `user` section of `git/.gitconfig`
+   stays as a placeholder (`me@example.com`); real identity lives only on the machine.
+3. **ShellCheck must pass.** CI runs ShellCheck (bash dialect) on `bash/` and
+   `scripts/`. Prefer fixing findings; when a finding is a false positive (e.g. a
+   variable consumed by a sourced script), add a targeted
+   `# shellcheck disable=SCxxxx` directive *with a comment explaining why*.
+4. **zsh files cannot be ShellChecked** (unsupported dialect). Validate zsh changes with
+   `zsh -n zsh/.zshrc` instead.
+5. **Anything sourced at shell startup must be guarded.** Pattern:
+   `[ -f file ] && source file`. A missing optional file must never break the shell.
+6. **`bash/.bash_aliases` is shared with zsh.** Only use syntax valid in both shells.
+
+## Conventions
+
+- **Commits:** short imperative subject, optionally prefixed with a gitmoji + type, e.g.
+  `🔧 chore: update command timeout for starship`, `🩹 fix: pnpm path …`. Match the
+  existing `git log` style. Commits go directly to `master` (single-maintainer repo).
+- **Comments:** these files double as documentation; keep the explanatory comment style
+  (what an option does and why it is set).
+- **Indentation/whitespace:** governed by `.editorconfig`.
+
+## Verifying changes
+
+```sh
+# Lint bash + scripts (what CI runs)
+shellcheck -s bash bash/.bash_aliases bash/.bash_profile scripts/*.sh
+
+# Syntax-check zsh
+zsh -n zsh/.zshrc
+
+# Validate gitconfig parses and keys resolve
+git config -f git/.gitconfig --list
+
+# Try the git-prompt updater against a temp path
+GIT_PROMPT_DEST=$(mktemp) scripts/update-git-prompt.sh
+```
+
+## Pointers
+
+- Current improvement plan: `docs/plans/2026-06-10-improvement-plan.md`
+- CI: `.github/workflows/shellcheck.yml`
diff --git a/README.md b/README.md
@@ -1,10 +1,81 @@
 # Development Preferences
 
-These are my personal preferences while doing development.
+[![ShellCheck](https://github.com/niketpathak/devpreferences/actions/workflows/shellcheck.yml/badge.svg)](https://github.com/niketpathak/devpreferences/actions/workflows/shellcheck.yml)
 
-### [Reference article](http://digitalfortress.tech/tricks/creating-a-global-gitignore/) to setup a **global .gitignore** file
+Personal development environment preferences (dotfiles), organised per tool.
 
-### [Reference article](https://digitalfortress.tech/tutorial/create-global-gitconfig-git-alias/) to setup a **global .gitconfig** file as well as **git alias**
+## Layout
 
+| Path                           | Installs to (typical)                           | Purpose                                  |
+|--------------------------------|--------------------------------------------------|------------------------------------------|
+| `bash/.bash_profile`           | `~/.bash_profile`                                | Bash login shell: history, git prompt, starship |
+| `bash/.bash_aliases`           | `~/.bash_aliases` **and** `$ZSH_CUSTOM/aliases.zsh` | Aliases shared between bash and zsh   |
+| `zsh/.zshrc`                   | `~/.zshrc`                                       | Oh My Zsh, plugins, history, starship    |
+| `zsh/.zshenv`                  | `~/.zshenv`                                      | Cargo environment                        |
+| `git/.gitconfig`               | `~/.gitconfig`                                   | Git aliases and sensible defaults        |
+| `git/.gitignore_global`        | `~/.gitignore_global`                            | Global gitignore (wired via `core.excludesfile`) |
+| `starship/starship.toml`       | `~/.config/starship.toml`                        | [Starship](https://starship.rs) prompt   |
+| `terminator/config`            | `~/.config/terminator/config`                    | Terminator terminal                      |
+| `lsd/config.yaml`, `lsd/icons.yaml` | `~/.config/lsd/`                            | [lsd](https://github.com/lsd-rs/lsd) (`ls` replacement) |
+| `scripts/update-git-prompt.sh` | — (run it, don't install it)                     | Fetches the latest upstream `git-prompt.sh` |
 
-#### The default .gitconfig file is located at *~/.gitconfig* (For Unix systems alone. See above article for other OS's).
+## Installation
+
+Symlink (preferred — edits in the repo apply immediately) or copy the files to the
+locations above. Example:
+
+```sh
+ln -s "$PWD/git/.gitconfig"        ~/.gitconfig
+ln -s "$PWD/git/.gitignore_global" ~/.gitignore_global
+ln -s "$PWD/zsh/.zshrc"            ~/.zshrc
+ln -s "$PWD/bash/.bash_aliases"    ~/.bash_aliases
+ln -s "$PWD/bash/.bash_aliases"    "$HOME/.oh-my-zsh/custom/aliases.zsh"
+ln -s "$PWD/starship/starship.toml" ~/.config/starship.toml
+```
+
+Then set your identity locally (the committed `.gitconfig` ships a placeholder):
+
+```sh
+git config --global user.name  "Your Name"
+git config --global user.email "you@example.com"
+```
+
+> Note: `git config --global` writes through the symlink into this repo's
+> `git/.gitconfig` — if you symlinked it, set your identity by hand in a separate
+> machine-local file instead, e.g. keep `~/.gitconfig` as a 3-line file that sets
+> `user.*` and uses `[include] path = /path/to/devpreferences/git/.gitconfig`.
+
+## git-prompt.sh
+
+`~/.git-prompt.sh` (used by `bash/.bash_profile` for `__git_ps1`) is **not vendored in
+this repo** — it used to be, and went stale. Install or update it with:
+
+```sh
+scripts/update-git-prompt.sh
+```
+
+This downloads the canonical version from
+[git/git `contrib/completion/git-prompt.sh`](https://github.com/git/git/blob/master/contrib/completion/git-prompt.sh)
+to `~/.git-prompt.sh` (override the destination with `GIT_PROMPT_DEST=/path`).
+Re-run it whenever you want to pick up upstream changes. The decision record is in
+[docs/plans/2026-06-10-improvement-plan.md](docs/plans/2026-06-10-improvement-plan.md).
+
+## Quality checks
+
+CI runs ShellCheck on the bash files and `scripts/`, plus a `zsh -n` syntax check on the
+zsh files (see `.github/workflows/shellcheck.yml`). Run locally:
+
+```sh
+shellcheck -s bash bash/.bash_aliases bash/.bash_profile
+shellcheck scripts/*.sh
+zsh -n zsh/.zshrc
+```
+
+Contributor/agent conventions live in [AGENTS.md](AGENTS.md); improvement plans live in
+[docs/plans/](docs/plans/).
+
+## References
+
+- [Reference article](https://digitalfortress.tech/tricks/creating-a-global-gitignore/) to setup a **global .gitignore** file
+- [Reference article](https://digitalfortress.tech/tutorial/create-global-gitconfig-git-alias/) to setup a **global .gitconfig** file as well as **git alias**
+- The default `.gitconfig` file is located at `~/.gitconfig` (for Unix systems; see the article above for other OSes)
diff --git a/docs/plans/2026-06-10-improvement-plan.md b/docs/plans/2026-06-10-improvement-plan.md
@@ -0,0 +1,106 @@
+# Improvement Plan — devpreferences
+
+**Date:** 2026-06-10
+**Status:** Phase 1 executed; Phase 2 proposed
+**Scope:** Repository hygiene, CI, dependency management for vendored scripts, documentation, and shell-config correctness.
+
+## 1. Repository overview
+
+This repository holds personal development environment preferences (dotfiles), organised by tool:
+
+| Directory     | Contents                                                        |
+|---------------|-----------------------------------------------------------------|
+| `bash/`       | `.bash_profile`, `.bash_aliases` (aliases shared with zsh)      |
+| `zsh/`        | `.zshrc` (Oh My Zsh + starship), `.zshenv` (cargo env)          |
+| `git/`        | `.gitconfig` (aliases + sensible defaults), `.gitignore_global` |
+| `starship/`   | `starship.toml` prompt configuration                            |
+| `terminator/` | Terminator terminal emulator configuration                      |
+| `lsd/`        | `config.yaml`, `icons.yaml` for lsd (ls replacement)            |
+
+There is no build system, no tests, and (before this plan) no CI. Files are consumed by manually copying or symlinking them into `$HOME`.
+
+## 2. Findings
+
+### 2.1 Bugs / correctness
+
+1. **`git/.gitconfig` — invalid config key (silent failure).**
+   `[core] excludefile = ~/.gitignore_global` uses a non-existent key. The correct key is
+   `excludesfile` (`core.excludesFile`). Git ignores unknown keys silently, so the global
+   gitignore referenced by the README has never actually been active through this file.
+
+2. **`git/.git-prompt.sh` is a stale vendored copy.**
+   The header claims "Aug 2024", but comparison of git blob SHAs against
+   `git/git@master:contrib/completion/git-prompt.sh` shows the local copy
+   (blob `a187b63…` after stripping the two local header lines) differs from upstream
+   (blob `6186c47…`, 21,338 bytes vs ~18,660 locally). The local copy predates the
+   2024-08-20 upstream batch which added custom 0-width PS1 marker support and several
+   portability/quoting fixes (`fbcdfab`, `0dbe3d3`, `29bcec8`, `b732e08`, `fe445a1`).
+   Vendoring third-party scripts with no update mechanism guarantees this kind of drift.
+
+3. **`zsh/.zshrc` — unguarded source.**
+   `source $ZSH_CUSTOM/aliases.zsh` aborts with an error on any machine where that file
+   has not been symlinked yet, producing a noisy (and partially broken) shell startup.
+
+### 2.2 Hygiene / industry standards gaps
+
+4. **No CI.** Shell config files are exactly the kind of artifact that benefits from
+   ShellCheck: errors are silent and only discovered on the next machine you provision.
+5. **No agent/contributor entry point.** No `AGENTS.md`; the README does not describe
+   the repo layout, installation, or conventions (e.g. gitmoji-style commit subjects).
+6. **No `.editorconfig`.** Mixed editors across machines can introduce whitespace drift.
+7. **ShellCheck findings in `bash/.bash_profile`.** A mix of false positives
+   (`GIT_PS1_*` variables consumed by the sourced `git-prompt.sh`; color variables used
+   by the deprecated-but-kept `color_my_prompt`) and one legitimate style issue
+   (`SC2155` declare-and-assign). These need inline directives with justification so CI
+   can run at default severity instead of being watered down globally.
+8. **No automated update for GitHub Actions versions.** Once CI exists, action versions
+   should be kept current (Dependabot).
+
+## 3. Plan
+
+### Phase 1 — executed now
+
+| # | Action | Details |
+|---|--------|---------|
+| 1 | **Fix `core.excludesfile` typo** | `excludefile` → `excludesfile` in `git/.gitconfig`. |
+| 2 | **De-vendor `git-prompt.sh`** | Delete `git/.git-prompt.sh`. Add `scripts/update-git-prompt.sh` which downloads the latest upstream version from `git/git@master` to `~/.git-prompt.sh` (configurable destination, fails loudly, validates the download looks like the real script before installing). `bash/.bash_profile` already sources `~/.git-prompt.sh` only if present, so no change needed there. |
+| 3 | **Add ShellCheck CI** | `.github/workflows/shellcheck.yml`: runs on push/PR, checks `bash/` dotfiles and `scripts/*.sh` with bash dialect. zsh files are excluded (ShellCheck does not support zsh). |
+| 4 | **Make bash files ShellCheck-clean** | Add `# shellcheck shell=bash` headers, targeted `disable` directives with reasons (SC2034 for externally-consumed vars, SC1090/SC1091 for runtime sources), and fix the real SC2155 finding. |
+| 5 | **Guard zsh alias sourcing** | `[ -f "$ZSH_CUSTOM/aliases.zsh" ] && source …` so a fresh machine still gets a working shell. |
+| 6 | **Add `AGENTS.md`** | Repo map, conventions, what is safe to change, how files map to `$HOME`, CI expectations. |
+| 7 | **Add `.editorconfig`** | UTF-8, LF, final newline, 2-space indent for YAML/TOML, tabs preserved where files already use them. |
+| 8 | **Add Dependabot config** | Weekly updates for GitHub Actions. |
+| 9 | **Rewrite `README.md`** | Layout table, installation/symlink instructions, git-prompt update script usage, link to plans and AGENTS.md. Keep the existing reference-article links. |
+
+### Phase 2 — proposed (not executed)
+
+| # | Action | Rationale |
+|---|--------|-----------|
+| 1 | **`install.sh` or GNU Stow adoption** | Symlinking by hand is error-prone. GNU Stow is the de-facto standard for dotfiles (`stow bash git zsh …`); the current per-tool directory layout is almost Stow-compatible already (files would need to mirror `$HOME`-relative paths, e.g. `lsd/.config/lsd/config.yaml`). Decide between Stow and a small idempotent `install.sh`; either should back up existing files before linking. |
+| 2 | **Add a LICENSE** | The repo is public; without a license it is "all rights reserved" by default. MIT is typical for dotfiles. Left as a deliberate owner decision. |
+| 3 | **zsh syntax check in CI** | ShellCheck cannot lint zsh; a cheap `zsh -n zsh/.zshrc` job catches syntax errors. |
+| 4 | **Scheduled CI freshness check for git-prompt** | A monthly workflow comparing upstream blob SHA against a recorded one, opening an issue when upstream moves. Complements the update script. |
+| 5 | **Pre-commit hooks** | `pre-commit` with `shellcheck` + whitespace hooks for local feedback before CI. |
+| 6 | **Retire deprecated prompt code** | `color_my_prompt` and the color variables in `bash/.bash_profile` are dead since starship took over the prompt; once confident, delete them (they are the main source of ShellCheck noise). |
+| 7 | **Pin starship/lsd minimum versions in docs** | Configs assume features of specific tool versions; documenting them avoids surprises on older distros. |
+
+## 4. git-prompt.sh strategy (decision record)
+
+**Options considered:**
+
+- **A. Keep vendoring, update manually** — status quo; proven to drift (header said
+  "Aug 2024" yet was already behind other Aug 2024 commits).
+- **B. Git submodule of `git/git`** — pulls a ~250 MB repository for one 21 KB file;
+  rejected.
+- **C. Fetch-on-demand script (chosen)** — `scripts/update-git-prompt.sh` downloads the
+  canonical file from `https://raw.githubusercontent.com/git/git/master/contrib/completion/git-prompt.sh`
+  into `~/.git-prompt.sh`. Pros: always current on demand, removes 612 lines of
+  third-party code from the repo, no merge noise on updates. Cons: requires network on
+  first setup; mitigated by clear error messages. The script validates the downloaded
+  content (shebang-less but must contain `__git_ps1`) and is atomic (temp file + `mv`).
+
+## 5. Verification
+
+- `shellcheck` (v0.9.0, bash dialect) passes locally on all checked files at default severity.
+- `scripts/update-git-prompt.sh` exercised locally against a temp destination.
+- `git -c include.path=… config core.excludesfile` resolves after the typo fix.
