ben/dotfiles-public
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat: carry CLAUDE.md and AGENTS.md in the public tier

Browse Source 
Phase 3 excluded all of dot_claude/, but the plan always intended CLAUDE.md
to be the one agent file that ships publicly. Adds it plus the codex and pi
AGENTS.md, so a throwaway VM gets sane agent behaviour with no credential.

Specialized agents, skills, hooks and the language rule sets are deliberately
absent -- they live in a separate repository now. The Active Rule Sets section
is rewritten to say so rather than dangle a reference to a rules/ tree this
repo does not carry.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
This commit is contained in:
bcherb2
2026-08-17 00:32:39 -04:00
parent b487b0e855
commit e1332c67d8
3 changed files with 229 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
dot_claude/CLAUDE.md
+99
View File
@@ -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 <terms>` 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 <keywords>` (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).
dot_codex/AGENTS.md
+105
View File
@@ -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 <keywords>` (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).
dot_pi/agent/AGENTS.md
+25
View File
@@ -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 <keywords>` (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).