AI instructions

This file contains maintenance instructions for this repository only. It is not part of the generated Codex or Claude Code configuration and must not be read or processed by build output.

Architecture

Keep the architecture as:

shared definitions -> client adapters -> generated output -> optional installation

Modify shared definitions first.
Keep adapters limited to client-specific formats and metadata.
Do not duplicate shared behavior in adapters.
Treat generated/ as reproducible build output.
Maintain equivalent support for both Codex and Claude Code.
Keep technology-specific rules in separate files under shared/rules/.
Generate those rule files beside AGENTS.md and CLAUDE.md; load them only when their subject applies.

Portability

Design scripts, hooks, generated configuration, and installation behavior for both Windows and Linux.
Use cross-platform tools and paths where practical.
When platform-specific behavior is necessary, provide an equivalent implementation or a safe no-op for the other supported platform.
Provide equivalent native Bash (.sh) and PowerShell (.ps1) entry points for every script and hook.
Support Windows PowerShell 5.1 and newer on Windows, and PowerShell 7 (pwsh) on Linux. Keep shared PowerShell syntax compatible with 5.1; Windows must not require PowerShell 7.
Validate relevant changes on both supported platforms when practical.

Language

Write all repository content, generated instructions, scripts, prompts, documentation, and user-facing script output in English.

Workflow

Run scripts/build.ps1 to validate every project change before completion.
Rebuild generated output after semantic changes.
Run scripts/doctor.ps1 when changes affect generated output, installation, client configuration, hooks, or environment validation.
Preserve backward compatibility where practical.
Keep changes focused on the requested configuration behavior.

Instruction sources

Define repository-maintenance rules only in AI-Instructions.md.
Keep the repository-root AGENTS.md and CLAUDE.md as pointer-only files.
Keep generated global instructions in shared/global-instructions.md; the build copies that file into each generated client package.
Do not include AI-Instructions.md in generated output.

Installation and security

Do not install global configuration automatically.
Perform global installation only after explicit user instruction, using scripts/install.ps1 so replaced managed files are backed up.
Do not add project-specific rules, secrets, credentials, authentication state, or generated runtime state.

Version control

Never commit changes unless explicitly instructed.
Preserve unrelated user changes.

2.7 KiB Raw Blame History