diff --git a/dot_claude/CLAUDE.md b/dot_claude/CLAUDE.md new file mode 100644 index 0000000..075c2ff --- /dev/null +++ b/dot_claude/CLAUDE.md @@ -0,0 +1,99 @@ +# Global Claude Configuration + +## Tool Preferences + +### Search & Navigation +- **Always use ripgrep** (`rg`) over grep for code search - it's faster and respects .gitignore +- **Use Grep tool** with specific patterns, not broad searches. Prefer `output_mode: "content"` with context lines when you need to understand surrounding code +- **Use Glob** for finding files by pattern, not `find` command +- **Prefer LSP** when available for: go-to-definition, find-references, rename symbols. The pyright-lsp and gopls-lsp plugins are enabled. + +### Code Manipulation +- **Read before editing** - always read the full file (or relevant section) before making changes +- **Use code structure** over text patterns when possible: + - For function signatures: search for `func Name(` or `def name(` + - For type definitions: search for `type X struct` or `class X` or `interface X` + - For imports: check the import block at file top +- **Atomic edits** - make the smallest edit that accomplishes the goal. Don't rewrite surrounding code. + +## Code Quality +- Prefer correct, complete implementations over minimal ones. +- Use appropriate data structures and algorithms — don't brute-force what has a known better solution. +- When fixing a bug, fix the root cause, not the symptom. +- If something I asked for requires error handling or validation to work reliably, include it without asking. + + +### Verification +- **Every change needs verification** - this is non-negotiable +- Verification can be: + - Running existing tests: `go test`, `pytest`, `npm test` + - Running a specific command that exercises the change + - Building the project to catch type/compile errors + - For frontend: screenshot comparison or playwright test +- **State verification method explicitly** in plans before implementing + +### MCP Tools +- **Playwright** - use for frontend verification, taking screenshots, testing user flows +- Use MCP tools when they provide better precision than shell commands + + + +## Workflow Principles + +### Research First +Before proposing changes to unfamiliar code: +1. Identify the relevant files and their relationships +2. Understand existing patterns in that area +3. Check for similar implementations elsewhere in the codebase +4. Look for tests that document expected behavior + +### Preserve Context +- Use subagents for exploratory searches (they don't pollute parent context) +- Compress findings into structured summaries + +## Active Rule Sets +Language rule sets, specialized agents, skills and hooks are **not** in this +repo. They live in a separate repository and are installed independently. This +file is deliberately limited to system-level conventions that should hold on +any machine, including a throwaway one with nothing else configured. + +## Shell +- Use zsh syntax when writing shell scripts or commands +- ~/.zshrc for shell configuration + +## Anti-Patterns (Do Not) +- Don't search broadly then read dozens of files - be precise +- Don't make changes without reading the code first +- Don't skip verification +- Don't rewrite code that doesn't need to change +- Don't add comments, docstrings, or type annotations to unchanged code + +## Obsidian vaults + +Two vaults, both on PATH-accessible tooling, both the user's long-term memory: + +- **`vault`** (CLI) + the **`obsidian-notes`** skill — everything except host changes. + `vault search ` is the **recall** path: run it before answering from + scratch about a work project or customer, the user's machines and home + network, or anything they may have solved before. `vault append` to add to an + existing note, `vault new` for a genuinely new subject. See the skill for the + full protocol and guardrails. +- **`sysjournal`** — host/environment changes only (below). + +`~/Documents/Obsidian25` is the frozen pre-split original. **Never write to it.** + +### System Knowledge Journal (sysjournal) + +Maintain a running journal of **host/environment** changes in the Obsidian vault at `Tech/Infrastructure/`, using the shared `sysjournal` helper (on PATH). This is for *system administration*, NOT ordinary work inside a code repo. + +**Trigger — the task changes the machine/environment, not just repo code:** system config; services/daemons (systemd/launchd/cron); networking/DNS/VPN/firewall; VMs & host-level containers; drivers/kernel/boot; disks/mounts; build toolchains & global/system package installs; or **wiring an app into the host** (a systemd unit, cron job, opened port, service account). + +**Do NOT journal** feature work, bug fixes, refactors, or tests *inside* a project repo. Discriminator: *does it change state outside the repo, on the host?* If no → skip. **Straddle case** (you build an app **and** install it as a service): journal only the **host-wiring** part (the unit/cron/port), not the app code. + +1. **Recall first.** Before diagnosing or acting on such a task, search the journal and read relevant hits: + `sysjournal search ` (e.g. `sysjournal search systemd relay port`) +2. **Journal after.** Once the change is made or the problem resolved: + `sysjournal new "Short Descriptive Title" --type change --status deployed --tags systemd,relay` + Then fill in the created note (its path is printed): **Why**, **What changed**, **Design decisions / gotchas**, **Verify** (command + observed result), **Status / follow-ups**. Link related notes with `[[wikilinks]]`. + +Keep it a real record — what changed, why, the gotcha you hit, how you verified. `sysjournal help` for the frontmatter schema (the `System Log MOC.md` Dataview index depends on it). diff --git a/dot_codex/AGENTS.md b/dot_codex/AGENTS.md new file mode 100644 index 0000000..b7a9df5 --- /dev/null +++ b/dot_codex/AGENTS.md @@ -0,0 +1,105 @@ +# Global Codex Configuration + +## Tool Preferences + +### Search And Navigation +- Always use `rg` over `grep` for code search. +- Prefer narrow searches over broad sweeps. +- Use precise file globs and code-aware navigation when available. +- Prefer MCP tools when they provide better precision than shell commands. + +### Code Manipulation +- Read the relevant code before editing. +- Prefer structural understanding over blind text replacement. +- Make the smallest change that solves the problem. +- Do not rewrite surrounding code without a concrete reason. + +### Verification +- Every change needs verification. +- Verification can be tests, a build, a targeted command, or frontend validation with Playwright. +- For non-trivial work, state the verification method before implementing. + +## Language Patterns + +### Python +- Prefer `black` or `ruff format` for formatting. +- Prefer `ruff` for linting. +- Use type hints on public code. +- Prefer `pytest`. +- Check for `.venv/` or `venv/` before assuming interpreter paths. + +### Go +- Use `gofmt`. +- Prefer `go vet` for linting and `go test ./...` for verification. +- Check `go.mod` for module structure. +- Do not ignore errors with `_` unless there is a defensible reason. + +### TypeScript +- Prefer `prettier` and `eslint` when present. +- Check `package.json` for the repo's actual test and build commands. +- Check `tsconfig.json` before changing compiler-sensitive code. +- Prefer strict typing patterns. + +## Workflow Principles + +### Research First +Before changing unfamiliar code: +1. Identify the relevant files and relationships. +2. Understand the local pattern in that area. +3. Check for similar implementations elsewhere. +4. Look for tests that define expected behavior. + +### Plan Before Implement +For non-trivial work: +1. State what is changing and why. +2. Name the files or components likely to change. +3. Define how the change will be verified. +4. Note obvious risks or breakpoints. + +### Preserve Context +- Keep findings compressed and structured. +- Reuse existing project artifacts like `.claude/progress.md`, `PITFALLS.md`, and project `CLAUDE.md` when they exist. +- If a repo already uses `.claude/` planning or checkpoint files, continue to respect them rather than inventing a second system. + +## Session Workflow + +### Starting A Session +1. Check for `.claude/progress.md` and load it as prior context when present. +2. Read `PITFALLS.md` if present. +3. Read project instructions from `AGENTS.md`. Codex is also configured to treat project `CLAUDE.md` as a fallback instruction file. + +### During Work +- Research unfamiliar areas before editing. +- Make plans for non-trivial work. +- Review changes before commit when risk is non-trivial. + +### Ending A Session +- If the repo uses `.claude/progress.md`, update it when useful. +- If there are uncommitted changes, leave the next session enough context to resume cleanly. + +## Shell +- Use zsh-compatible syntax when writing shell commands or scripts. +- Assume `~/.zshrc` can affect shell behavior. + +## Anti-Patterns +- Do not search broadly and read dozens of files without narrowing scope. +- Do not change code before understanding the local pattern. +- Do not skip verification. +- Do not rewrite code that does not need to change. +- Do not add comments, docstrings, or annotations to untouched code without a clear reason. + +## System Knowledge Journal (Obsidian) + +Maintain a running journal of **host/environment** changes in the Obsidian vault at `Tech/Infrastructure/`, using the shared `sysjournal` helper (on PATH). This is for *system administration*, NOT ordinary work inside a code repo. + +**Trigger — the task changes the machine/environment, not just repo code:** system config; services/daemons (systemd/launchd/cron); networking/DNS/VPN/firewall; VMs & host-level containers; drivers/kernel/boot; disks/mounts; build toolchains & global/system package installs; or **wiring an app into the host** (a systemd unit, cron job, opened port, service account). + +**Do NOT journal** feature work, bug fixes, refactors, or tests *inside* a project repo. Discriminator: *does it change state outside the repo, on the host?* If no → skip. **Straddle case** (you build an app **and** install it as a service): journal only the **host-wiring** part (the unit/cron/port), not the app code. + +1. **Recall first.** Before diagnosing or acting on such a task, search the journal and read relevant hits: + `sysjournal search ` (e.g. `sysjournal search systemd relay port`) +2. **Journal after.** Once the change is made or the problem resolved: + `sysjournal new "Short Descriptive Title" --type change --status deployed --tags systemd,relay` + Then fill in the created note (its path is printed): **Why**, **What changed**, **Design decisions / gotchas**, **Verify** (command + observed result), **Status / follow-ups**. Link related notes with `[[wikilinks]]`. + +Keep it a real record — what changed, why, the gotcha you hit, how you verified. `sysjournal help` for the frontmatter schema (the `System Log MOC.md` Dataview index depends on it). diff --git a/dot_pi/agent/AGENTS.md b/dot_pi/agent/AGENTS.md new file mode 100644 index 0000000..913c6de --- /dev/null +++ b/dot_pi/agent/AGENTS.md @@ -0,0 +1,25 @@ +# Global Pi Configuration + +Global instructions for the Pi coding agent, shared with the Claude Code and +Codex setups on this machine. Project-level `AGENTS.md` / `CLAUDE.md` files take +precedence for project-specific work. + +## Shell +- Use zsh-compatible syntax when writing shell commands or scripts. +- Assume `~/.zshrc` can affect shell behavior. + +## System Knowledge Journal (Obsidian) + +Maintain a running journal of **host/environment** changes in the Obsidian vault at `Tech/Infrastructure/`, using the shared `sysjournal` helper (on PATH). This is for *system administration*, NOT ordinary work inside a code repo. + +**Trigger — the task changes the machine/environment, not just repo code:** system config; services/daemons (systemd/launchd/cron); networking/DNS/VPN/firewall; VMs & host-level containers; drivers/kernel/boot; disks/mounts; build toolchains & global/system package installs; or **wiring an app into the host** (a systemd unit, cron job, opened port, service account). + +**Do NOT journal** feature work, bug fixes, refactors, or tests *inside* a project repo. Discriminator: *does it change state outside the repo, on the host?* If no → skip. **Straddle case** (you build an app **and** install it as a service): journal only the **host-wiring** part (the unit/cron/port), not the app code. + +1. **Recall first.** Before diagnosing or acting on such a task, search the journal and read relevant hits: + `sysjournal search ` (e.g. `sysjournal search systemd relay port`) +2. **Journal after.** Once the change is made or the problem resolved: + `sysjournal new "Short Descriptive Title" --type change --status deployed --tags systemd,relay` + Then fill in the created note (its path is printed): **Why**, **What changed**, **Design decisions / gotchas**, **Verify** (command + observed result), **Status / follow-ups**. Link related notes with `[[wikilinks]]`. + +Keep it a real record — what changed, why, the gotcha you hit, how you verified. `sysjournal help` for the frontmatter schema (the `System Log MOC.md` Dataview index depends on it).