feat: carry CLAUDE.md and AGENTS.md in the public tier
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
@@ -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).
|
||||
@@ -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).
|
||||
@@ -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).
|
||||
Reference in New Issue
Block a user