Personal shared configuration for Codex and Claude Code. Not intended for general use.

This repo is the canonical source of shared agent configuration. Its sanitized public downstream lives at yzhao062/anywhere-agents and ships the subset safe for general audiences — no USC-internal content, no reference-skills/, no archived planning artifacts.

Sibling repos in the same family:

• yzhao062/anywhere-agents: the public consumer and STRICT-parity mirror of ac for everything except maintainer-only docs (pack-architecture.md, vision.md, anywhere-agents.md, archive/). PyPI / npm distribution lives here.
• yzhao062/agent-style: the writing rule pack composed into every consumer's AGENTS.md by default. 21 rules (12 classic + 9 LLM-observed) with BAD -> GOOD examples per rule.
• yzhao062/agent-pack: public reference example for third-party pack authors. Declares 3 packs (profile passive, paper-workflow passive, acad-skills active) using the v2 manifest schema. Doubles as the v0.5.0 remote-fetch acceptance test for anywhere-agents. Personal context that used to live only in this repo's AGENTS.md section "User Profile" and section "Submodule Workflow" is migrating here so new projects can bootstrap from aa + agent-pack rather than from ac directly.

The two repos co-evolve. Most meaningful changes to shared components (bootstrap, implement-review, my-router, guard hook, writing defaults, Git safety rules, session checks) should land here first, then be backported into anywhere-agents on the next public release cut. Skipping the backport lets the public release drift — users stop getting improvements that the author is already using daily.

Read before touching either repo:

• anywhere-agents.md — canonical source rule, "what gets copied" table, 13-step release workflow, package/asset ownership.
• docs/specs/open-source-framework.md — the historical release plan plus the dated post-v1.0 update (npm/PyPI CLI policy).
• yzhao062/anywhere-agents/RELEASING.md — the public-facing release steps (tag → build → publish to PyPI + npm → verify). Use this after the backport is staged.

Every release of anywhere-agents is paired with a doc update here. If you change the two-repo policy (what gets copied, canonical-source rule, release workflow), update anywhere-agents.md in the same commit.

Other project repos bootstrap from this repo to get shared agent defaults and skills. The bootstrap script (defined in AGENTS.md) fetches:

• AGENTS.md — user profile, writing/formatting defaults, environment notes, skill-sharing rules
• CLAUDE.md and agents/codex.md — regenerated on every bootstrap run from AGENTS.md via scripts/generate_agent_configs.py
• skills/ — shared skills (e.g., dual-pass-workflow, bibref-filler)
• .claude/commands/ — Claude Code pointer commands for shared skills
• .claude/settings.json — shared Claude project defaults (permissions, attribution, etc.)
• user/settings.json — shared user-level Claude defaults (permissions, hook wiring, CLAUDE_CODE_EFFORT_LEVEL=max env entry that pins effort to max)
• scripts/guard.py — deployed to ~/.claude/hooks/guard.py as a PreToolUse hook (compound-cd guard, destructive Git/GitHub confirmation, writing-style deny on prose files, session-banner gate)
• scripts/session_bootstrap.py — deployed to ~/.claude/hooks/session_bootstrap.py as a SessionStart hook that re-runs bootstrap automatically on every session start

Paste the bootstrap block from AGENTS.md into the top of your project's AGENTS.md. The script will:

1. Download the latest AGENTS.md into .agent-config/.
2. Sparse-clone skills/ and the shared .claude/ files into .agent-config/repo/.
3. Copy shared commands into the project's .claude/commands/ (non-destructive).
4. Merge shared keys into the project's .claude/settings.json on every run; project-only keys are preserved.
5. Auto-add .agent-config/ to the project's .gitignore.

The copied block downloads the latest shared bootstrap.ps1 or bootstrap.sh at runtime. Those scripts refresh the consuming repo's root AGENTS.md to match the shared copy. If a project later needs local overrides, put them in AGENTS.local.md.

After pasting the bootstrap block into the project's AGENTS.md, tell the agent:

阅读 AGENTS.md 并执行其中的 bootstrap 脚本。

This repo includes zero-dependency validation tests for the bootstrap contract, skill layout, Claude/Codex wrappers, and temp-project smoke tests for the bootstrap flow.

Use any Python 3.12 interpreter to run them locally:

python -B -m unittest discover -s tests -p "test_*.py" -v

GitHub Actions runs the same test suite on Ubuntu, Windows, and macOS across Python 3.9-3.13 for every push and pull request.

A pre-push hook in .githooks/pre-push runs scripts/pre-push-smoke.sh when a push includes changes to agent-critical files (AGENTS.md, bootstrap/, scripts/, skills/). pre-push-smoke.sh validates the current checkout: regenerates the per-agent files and diffs against committed versions, then runs claude -p / codex exec in the repo root and asserts each response lists every skill under skills/. This catches regressions in how agents actually load the config — something mechanical tests cannot verify.

Enable it once per clone:

git config core.hooksPath .githooks

Pure doc / test / CI-workflow changes skip the smoke automatically. Use git push --no-verify to bypass when needed. Agent calls (claude -p, codex exec) are skipped gracefully if the corresponding CLI is not installed locally. (The separate scripts/remote-smoke.sh tests the published install path — different purpose, used for post-publish verification.)

Rule-file precedence (most specific wins):

1. CLAUDE.local.md / agents/codex.local.md — per-agent + project-local. Hand-authored; never touched by bootstrap.
2. AGENTS.local.md — cross-agent + project-local. Hand-authored; never touched by bootstrap.
3. CLAUDE.md / agents/codex.md — per-agent. Generated from AGENTS.md by scripts/generate_agent_configs.py on every bootstrap.
4. AGENTS.md — cross-agent baseline, synced from upstream on every bootstrap.

Other precedence:

• Project-local skills/<name>/SKILL.md overrides pack-deployed .claude/skills/<name>/SKILL.md and bootstrapped .agent-config/repo/skills/<name>/SKILL.md copies of the same skill.
• .claude/settings.local.json overrides shared keys in .claude/settings.json.
• Environment variable CLAUDE_CODE_EFFORT_LEVEL outranks persisted effortLevel; see AGENTS.md "Configuration Precedence" for the full chain.

See AGENTS.md "Configuration Precedence" for full details.

Codex can be used from within Claude Code as an MCP server. See AGENTS.md — Codex MCP Integration for full setup instructions (registration, Windows path, approval policy, Bitdefender workarounds).

After bootstrap, mention the skill name directly in the prompt. In Claude Code, the matching pointer command under .claude/commands/ provides the same entry point. Each skill's SKILL.md contains full usage instructions and examples.

AGENTS.md                          # Shared agent config (entry point)
CLAUDE.md                          # Generated from AGENTS.md for Claude Code
agents/codex.md                    # Generated from AGENTS.md for Codex
ONBOARDING.md                      # Maintainer one-page index (agent-config + anywhere-agents workflow)
bootstrap/
  bootstrap.ps1                    # Windows bootstrap logic
  bootstrap.sh                     # Unix bootstrap logic
skills/                            # Shared skills (bootstrapped to all projects)
  bibref-filler/
    SKILL.md                       # Skill definition
    agents/openai.yaml             # Codex wrapper
    assets/working.bib             # Starter template for machine-added entries
    references/citation-rules.md   # Density, placement, and storage guidance
    scripts/check_cite_keys.py     # Local cite-key validation helper
  bibref-verify/
    SKILL.md                       # Skill definition
    agents/openai.yaml             # Codex wrapper
    scripts/verify-bib-s2.py       # S2 cross-verification helper
  ci-mockup-figure/
    SKILL.md                       # Skill definition
    agents/openai.yaml             # Codex wrapper
  dual-pass-workflow/
    SKILL.md                       # Skill definition (single source of truth)
    agents/openai.yaml             # Codex wrapper
    references/                    # contracts.md, task-mappings.md
    assets/                        # workflow.yaml, handoff.md, audit.md, reconcile.md
  figure-prompt-builder/
    SKILL.md                       # Skill definition
    agents/openai.yaml             # Codex wrapper
    assets/reference-bank/         # Portable donor figures bundled with the skill
    references/                    # figure-archetypes, reference-bank, prompt-design, tool-selection, external-handoff
    scripts/init_figure_spec.py    # Figure brief scaffold helper
  implement-review/
    SKILL.md                       # Skill definition
    agents/openai.yaml             # Codex wrapper
    references/review-lenses.md    # Framework-grounded review criteria (Google, NeurIPS, NSF, NIH)
  my-router/
    SKILL.md                       # Context-aware dispatcher for academic tasks
    agents/openai.yaml             # Codex wrapper
    references/routing-table.md    # Quick-reference routing table and lens selection
  prun/
    SKILL.md                       # Skill definition
    agents/openai.yaml             # Codex wrapper
    scripts/                       # dispatch-task, gather, monitor (.sh + .ps1)
  readme-polish/
    SKILL.md                       # Audit + rewrite a GitHub README with modern patterns
    agents/openai.yaml             # Codex wrapper
    references/patterns.md         # Copyable snippets for every modern pattern
    references/checklist.md        # Pre-publish audit grid
reference-skills/                  # Domain skills (copied manually into project repos)
  condense-cv/                     # CV preparation
  cs-meta-review/                  # Area chair meta-review
  cs-paper-review/                 # Peer review of CS papers
  deck-assembler/                  # Slide deck assembly
  nsf-bibref-filler/               # NSF-specific citation filling
  nsf-figure-builder/              # NSF-specific figure building
  nsf-proposal-composer/           # NSF proposal section drafting
  nsf-proposal-guardrail/          # NSF compliance checking
  nsf-thrust-refiner/              # NSF thrust polishing
  paper-to-beamer/                 # Paper to Beamer slides
  profile-intro-slides/            # Intro/profile presentations
  usc-reimbursement/               # Travel/expense claims
figure-references/                 # Reusable reference figures organized by visual job
  index.md                         # Annotated index with role, density, and trait labels
scripts/
  guard.py                         # PreToolUse hook: compound cd, destructive git/gh, writing-style, banner gates
  session_bootstrap.py             # SessionStart hook: runs bootstrap automatically
  generate_agent_configs.py        # Generator: AGENTS.md -> CLAUDE.md + agents/codex.md
user/
  settings.json                    # User-level Claude Code settings (permissions, hooks)
tests/                             # Validation tests (run in CI on Ubuntu, Windows, macOS)
  test_repo.py                     # Bootstrap contract, skill layout, smoke tests
  test_bibref_filler.py            # Cite-key validation script tests
  test_figure_prompt_builder.py    # Figure spec scaffold script tests
  test_guard.py                    # Guard hook tests
  test_session_bootstrap.py        # SessionStart hook tests
  test_generator.py                # AGENTS.md -> per-agent generator tests
anywhere-agents.md                 # Two-repo relationship, "what gets copied" table, release workflow
pack-architecture.md               # Pack composition architecture and release trajectory
vision.md                          # Ecosystem vision and parked design ideas
docs/
  migrations.md                    # Bootstrap-cache seed refresh + ac to aa upstream switch runbooks
  claude-code-tips.md              # Workflows and best practices
  claude-code-reference.md         # Keyboard shortcuts, slash commands, vim mode
  claude-code-extras.md            # Buddy/companion, plugins
.claude/commands/                  # Claude Code pointer commands for shared skills
  bibref-filler.md
  bibref-verify.md
  ci-mockup-figure.md
  dual-pass-workflow.md
  figure-prompt-builder.md
  implement-review.md
  my-router.md
  prun.md
  readme-polish.md
.claude/settings.json              # Shared Claude project defaults (permissions, attribution, etc.)
user/settings.json                 # Shared user-level defaults (permissions, hooks, CLAUDE_CODE_EFFORT_LEVEL=max env entry)