61 lines
3.7 KiB
Markdown
61 lines
3.7 KiB
Markdown
# 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 each language, framework, and library in its own directory under `shared/rules/`, with an index and focused Markdown rules. Keep security in `shared/rules/security/` and cross-cutting rules such as Git and Microsoft directly 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 PowerShell and Bash.
|
|
- Name configuration choices and generated packages after their shell, not the operating system.
|
|
- Use portable tools and paths where practical.
|
|
- When shell-specific behavior is necessary, provide an equivalent implementation or a safe no-op for the other supported shell.
|
|
- Provide equivalent native Bash (`.sh`) and PowerShell (`.ps1`) entry points for every script and hook.
|
|
- Keep shared PowerShell syntax compatible with 5.1 and support PowerShell 7 (`pwsh`) as well.
|
|
- Preserve operating-system API names and upstream schema keys when their exact spelling is required.
|
|
- Validate relevant changes with both supported shells when practical.
|
|
|
|
## Language
|
|
|
|
Write all repository content, generated instructions, scripts, prompts, documentation, and user-facing script output in English.
|
|
|
|
## Workflow
|
|
|
|
- Choose the smallest sufficient verification based on the change's behavior, affected consumers, risk, and remaining uncertainty. Inspection may suffice for low-risk changes; full builds, test suites, and independent reviews are not automatic.
|
|
- Run `scripts/commands/build.ps1 -Summary` to regenerate packages when shared definitions, adapters, or generation logic change. This generates configuration packages; it does not require building applications that use them.
|
|
- Run `scripts/commands/doctor.ps1 -Summary` when installation, client configuration, hooks, or environment changes need its checks. Changes to instruction wording alone do not require it.
|
|
- Run focused script tests when script behavior changes. Broaden or repeat checks only when failures, affected dependencies, or unresolved risks justify it.
|
|
- 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
|
|
|
|
- Keep all task changes inside this repository. Never install, update, or remove configuration, skills, plugins, packages, or settings on the local machine, and never modify files outside the repository. You may change repository code that defines installation behavior, but do not execute it; if a task requires an out-of-repository write, stop and report it.
|
|
- 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.
|