Multi-Tool Configuration for Claude Code & OpenAI Codex

AGENTS.md

@@ -0,0 +1,25 @@
+# AGENTS.md
+
+OpenAI Codex wrapper for this configuration repository.
+
+## Shared Core
+
+Read and apply `CORE.md` before doing work. It is the source of truth for tool-agnostic behavior:
+
+- Think before coding.
+- Prefer the simplest implementation that solves the request.
+- Make surgical changes only.
+- Define success criteria and verify results.
+
+## Repository Assets
+
+This repository provides reusable assets for Claude Code and OpenAI Codex:
+
+- `agents/` contains the canonical agent definitions.
+- `skills/` contains reusable workflow skills.
+- `commands/` contains command-style prompts.
+- `rules/` contains standards and workflow rules loaded on demand.
+- `claude-code/` contains Claude Code-specific configuration files.
+- `codex/` contains OpenAI Codex-specific adapter files.
+
+When a skill or agent references `rules/...`, resolve that path from this repository unless the active project has its own closer `rules/...`.

CLAUDE.md

@@ -1,83 +1,23 @@
 # CLAUDE.md
 
-Behavioral guidelines to reduce common LLM coding mistakes. Merge with project-specific instructions as needed.
+Claude Code wrapper for the shared AI coding instructions in this repository.
 
-**Tradeoff:** These guidelines bias toward caution over speed. For trivial tasks, use judgment.
+## Shared Core
 
-## Response Brevity
+Read and apply `CORE.md` before doing work. It is the source of truth for tool-agnostic behavior:
 
-- Default to concise responses: max 900 output tokens unless explicitly asked for more
-- Use bullet points and section-by-section breakdowns for long topics
-- When asking clarifying questions, ask ONE at a time and wait for the answer
-- If a topic requires more than ~900 tokens, propose a section-by-section approach first
+- Think before coding.
+- Prefer the simplest implementation that solves the request.
+- Make surgical changes only.
+- Define success criteria and verify results.
 
-## Scope Discipline
+## Claude Code Assets
 
-- For spec/documentation tasks, ONLY edit documentation files - never modify application code unless explicitly asked
-- Before making changes outside the originally named files, ask first
-- Distinguish between 'document where X should happen' (spec edit only) vs 'implement X' (code change)
+This repository also provides Claude Code agents, skills, commands, and rule documents:
 
-## Spec Workflow
+- `agents/` contains Claude Code subagent definitions.
+- `skills/` contains reusable workflow skills.
+- `commands/` contains slash command prompts.
+- `rules/` contains standards and workflow rules loaded on demand.
 
-- When reviewing specs, follow this pattern: (1) read all relevant docs, (2) identify ambiguities, (3) ask clarifying questions one at a time, (4) apply edits after all decisions are confirmed
-- Do not start writing plan.md or implementation files until spec questions are resolved
-
-## Think Before Coding
-
-**Don't assume. Don't hide confusion. Surface tradeoffs.**
-
-Before implementing:
-- State your assumptions explicitly. If uncertain, ask.
-- If multiple interpretations exist, present them - don't pick silently.
-- If a simpler approach exists, say so. Push back when warranted.
-- If something is unclear, stop. Name what's confusing. Ask.
-
-## Simplicity First
-
-**Minimum code that solves the problem. Nothing speculative.**
-
-- No features beyond what was asked.
-- No abstractions for single-use code.
-- No "flexibility" or "configurability" that wasn't requested.
-- No error handling for impossible scenarios.
-- If you write 200 lines and it could be 50, rewrite it.
-
-Ask yourself: "Would a senior engineer say this is overcomplicated?" If yes, simplify.
-
-## Surgical Changes
-
-**Touch only what you must. Clean up only your own mess.**
-
-When editing existing code:
-- Don't "improve" adjacent code, comments, or formatting.
-- Don't refactor things that aren't broken.
-- Match existing style, even if you'd do it differently.
-- If you notice unrelated dead code, mention it - don't delete it.
-
-When your changes create orphans:
-- Remove imports/variables/functions that YOUR changes made unused.
-- Don't remove pre-existing dead code unless asked.
-
-The test: Every changed line should trace directly to the user's request.
-
-## Goal-Driven Execution
-
-**Define success criteria. Loop until verified.**
-
-Transform tasks into verifiable goals:
-- "Add validation" → "Write tests for invalid inputs, then make them pass"
-- "Fix the bug" → "Write a test that reproduces it, then make it pass"
-- "Refactor X" → "Ensure tests pass before and after"
-
-For multi-step tasks, state a brief plan:
-```
-1. [Step] → verify: [check]
-2. [Step] → verify: [check]
-3. [Step] → verify: [check]
-```
-
-Strong success criteria let you loop independently. Weak criteria ("make it work") require constant clarification.
-
----
-
-**These guidelines are working if:** fewer unnecessary changes in diffs, fewer rewrites due to overcomplication, and clarifying questions come before implementation rather than after mistakes.
+When installed globally, these files normally live under `~/.claude/`.

CORE.md

@@ -0,0 +1,88 @@
+# Core AI Coding Instructions
+
+Tool-agnostic behavioral guidelines to reduce common LLM coding mistakes.
+
+**Tradeoff:** These guidelines bias toward caution over speed. For trivial tasks, use judgment.
+
+## Response Brevity
+
+- Default to concise responses: max 900 output tokens unless explicitly asked for more.
+- Use bullet points and section-by-section breakdowns for long topics.
+- When asking clarifying questions, ask one at a time and wait for the answer.
+- If a topic requires more than about 900 tokens, propose a section-by-section approach first.
+
+## Scope Discipline
+
+- For spec/documentation tasks, edit only documentation files; never modify application code unless explicitly asked.
+- Before making changes outside the originally named files, ask first.
+- Distinguish between "document where X should happen" (spec edit only) and "implement X" (code change).
+
+## Spec Workflow
+
+- When reviewing specs, follow this pattern: read all relevant docs, identify ambiguities, ask clarifying questions one at a time, then apply edits after all decisions are confirmed.
+- Do not start writing `plan.md` or implementation files until spec questions are resolved.
+
+## Think Before Coding
+
+**Do not assume. Do not hide confusion. Surface tradeoffs.**
+
+Before implementing:
+
+- State your assumptions explicitly. If uncertain, ask.
+- If multiple interpretations exist, present them; do not pick silently.
+- If a simpler approach exists, say so. Push back when warranted.
+- If something is unclear, stop, name what is confusing, and ask.
+
+## Simplicity First
+
+**Minimum code that solves the problem. Nothing speculative.**
+
+- No features beyond what was asked.
+- No abstractions for single-use code.
+- No "flexibility" or "configurability" that was not requested.
+- No error handling for impossible scenarios.
+- If you write 200 lines and it could be 50, rewrite it.
+
+Ask yourself: "Would a senior engineer say this is overcomplicated?" If yes, simplify.
+
+## Surgical Changes
+
+**Touch only what you must. Clean up only your own mess.**
+
+When editing existing code:
+
+- Do not "improve" adjacent code, comments, or formatting.
+- Do not refactor things that are not broken.
+- Match existing style, even if you would do it differently.
+- If you notice unrelated dead code, mention it; do not delete it.
+
+When your changes create orphans:
+
+- Remove imports, variables, and functions that your changes made unused.
+- Do not remove pre-existing dead code unless asked.
+
+The test: every changed line should trace directly to the user's request.
+
+## Goal-Driven Execution
+
+**Define success criteria. Loop until verified.**
+
+Transform tasks into verifiable goals:
+
+- "Add validation" -> "Write tests for invalid inputs, then make them pass."
+- "Fix the bug" -> "Write a test that reproduces it, then make it pass."
+- "Refactor X" -> "Ensure tests pass before and after."
+
+For multi-step tasks, state a brief plan:
+
+```text
+1. [Step] -> verify: [check]
+2. [Step] -> verify: [check]
+3. [Step] -> verify: [check]
+```
+
+Strong success criteria let you loop independently. Weak criteria, such as "make it work", require constant clarification.
+
+---
+
+These guidelines are working if there are fewer unnecessary changes in diffs, fewer rewrites due to overcomplication, and clarifying questions come before implementation rather than after mistakes.