agents-configs

Portable operating rules and skills for Codex, Claude Code, and other coding agents.

The repository keeps reusable behavior in one vendor-neutral core and exposes only thin tool-specific entrypoints. The intended default is simple:

Inspect the target repository, load the smallest relevant skill, follow its actual conventions, verify the result, and leave the workspace clean.

.agent-core/   canonical skills, scripts, and blueprints
.agents/       formal Agent Skills discovery adapters
.codex/        Codex workspace entrypoint
.claude/       Claude Code entrypoint and skill adapters
docs/          operating model and installation details
scripts/       bootstrap, diagnosis, and regression checks

The core covers repository discovery, implementation quality, testing, verification, branch lifecycle, reusable intent and taste capture, end-to-end Risk-to-Confidence delivery, and safe task cleanup.

Copy stable, project-owned configuration into a repository:

./scripts/bootstrap.sh all /path/to/project

Or link personal local projects back to this checkout so updates apply immediately:

./scripts/bootstrap.sh --link all /path/to/project

Install only one tool entrypoint when needed:

./scripts/bootstrap.sh codex /path/to/project
./scripts/bootstrap.sh claude /path/to/project

Preview any operation before writing:

./scripts/bootstrap.sh --dry-run --link all /path/to/project

Copy mode merges existing directories by default but refuses to follow a top-level symlink. --force replaces the selected top-level configuration directories, so use it only after reviewing the target. The bootstrap script rejects invalid modes, the filesystem root, and its own source checkout before writing.

See Symlink Installation for copy, link, and user-level discovery choices.

./scripts/doctor.sh /path/to/project all

Use codex or claude for a strict single-tool check. Omit the mode to require the common core while treating tool-specific entrypoints as optional.

Validate this source repository after changing bootstrap, discovery, or skill packaging:

./scripts/test.sh

The regression script exercises copy mode, link mode, dry-run behavior, destination safety, formal skill discovery, and both tool entrypoints on macOS and Linux CI.

1. Inspect the repository with .agent-core/scripts/inspect-repo.sh . or the smallest equivalent read.
2. Separate durable default-branch policy from current branch evidence.
3. State the intended behavior, uncertainty, and relevant risk.
4. Load only the matching skill from the skills index.
5. Make one coherent change using the repository's existing patterns.
6. Report generated and executed validation evidence separately.
7. Clear local test residue and clean delivered task resources only after preservation is proven.

For end-to-end non-trivial delivery, invoke Risk-to-Confidence explicitly or let an agent select it when the request genuinely spans planning, implementation, integration, and verification:

Codex:       $risk-to-confidence <request>
Claude Code: /risk-to-confidence <request>

An explicit invocation may stop at an earlier Risk Map or Contract gate. It does not authorize implementation by itself. See Risk-to-Confidence for artifacts and verdicts.

Repository evidence always wins. When no stronger policy exists, use an updated default branch, one short-lived branch per independently reviewable and reversible change, applicable review and checks, then cleanup after durable delivery.

A release-preparation branch is temporary. Merge version, changelog, manifest, and packaging updates back to the durable branch before tagging its exact commit. Add long-lived maintenance branches only when the project actively supports and backports to multiple release lines.

Direct default-branch work is allowed only when the user or repository explicitly authorizes it and no protection rule is bypassed. See Branch Lifecycle.

• Agent Operating Model
• Universal Skillset Blueprint
• Risk-to-Confidence Workflow
• Symlink Installation
• Agent Core
• Skills Index

• Keep project secrets, private domain details, volatile release state, and one-off branch names out of the portable core.
• Keep project-specific instructions in the target repository.
• Do not load every skill or turn this repository into one giant prompt.
• Treat generated tests and plans as proposals until they are executed or reviewed.
• Promote only human-accepted, reusable corrections into durable memory.

This is a personal public toolkit rather than a versioned runtime dependency. Its skills should evolve when repeated work proves that a rule removes real ambiguity or rework.