Extending KISS My Agent

Scope

Extend the repository only when a current recurring ambiguity is not covered. The goal is better decisions with less mechanism, not a larger handbook.

Choose the Owner

Change AGENTS.md only for a short, permanent, broadly applicable boundary.
Change a Rule when several current situations need the same reusable decision method.
Add or revise a Case when one concrete contrast makes an existing Rule easier to apply.
Change a standalone role TOML only when role ownership or real runtime needs change. Its name field is identity; the filename is only a convention.
Change setup logic only when the explicit project/global managed scope or conflict policy changes.
Change developer docs when installation, configuration, testing, security, or contribution facts change.

Do not duplicate one fact across owners. Rules extend AGENTS.md; Cases illustrate Rules without redefining them.

Preserve Precise Routing

The plugin-owned kiss-my-agent Skill must remain non-catch-all. Routine implementation, mechanical edits, tests, builds, Git operations, lookups, and formatting stay outside the Skill. One ambiguity routes to one Rule and, only when useful, one Case. Keep kiss-my-agent-setup separate and limited to explicit setup/check/configure/remove operations.

Add a Rule

Identify at least two current situations needing the same method and explain why a permanent AGENTS boundary is insufficient. Keep the addition incremental, link it from the Skill only when the trigger can select it precisely, and avoid repeating existing failure, evidence, or ownership guidance.

Add a Case

A Case keeps this exact section order:

Goal
Consumer
Minimum mechanism to retain
Mechanism to reject
Deletion counterfactual
Legitimate exception

It illustrates an existing Rule and creates no new requirement. Revise an existing Case when the same semantic contrast is already present.

Update Runtime and Docs

When changing public switches, standalone role discovery, or setup scope, keep .codex/config.toml, .codex/agents/, plugin metadata, the Agent-native setup references, Configuration, Installation, Testing, both READMEs, and the annotated example consistent. .codex/config.toml supplies missing Astra/high and feature defaults, including experimental context; config never enumerates role files. The editable fresh-setup seeds set model = "gpt-6-astra" and set model_reasoning_effort = "medium" for explorer, coder, and reviewer. Plugin cache seeds do not automatically enter the Host catalog. They are not a closed catalog: fresh setup creates missing starters, and every role that already exists is user-owned, so setup and Plugin updates never overwrite, migrate, or version-classify it. Use the existing-role wizard or manual TOML edits for model or effort changes. Do not add model fallback, permission fallback, preset matrices, or compatibility wrappers without a current consumer.

When changing an English developer document, update its Simplified Chinese companion with the same explicit anchor IDs, section order, and fenced command blocks. Codex-facing AGENTS, Skill, Rules, Cases, role TOML, LICENSE, and CODE_OF_CONDUCT.md remain English.

Validate

Plugin/Skill-only changes can run the dependency-free local core checks. Pull-request CI owns the complete cross-platform and site suite:

python3 scripts/validate.py
python3 -m unittest tests.test_setup -v

Inspect rendered Markdown when navigation, tables, badges, Mermaid, or assets change. Use a trusted new Codex session for discovery changes; old sessions are not guaranteed to hot-load.

For Pages changes, inspect the isolated build produced by the suite before deployment, then verify the deployed English root and Chinese zh-CN/ URLs. Keep README language links pointed at verified Pages URLs; do not replace them with unverified deployment targets.

Stop Boundary

Stop after the ambiguity is resolved with the smallest clear addition. Do not add adjacent governance, telemetry, scoring, release machinery, or speculative compatibility. New setup behavior needs a current installation consumer and must preserve explicit scope, collision safety, and reversible ownership.