Update and Extend AI Instructions Built from One Source for Several AI Tools

## Find Which Part Owns a Behavior Before Editing Treat the repository as a set of owned layers rather than a loose collection of files. Identify which layer owns a requested behavior before editing: - source instructions define reusable user-facing operations; - shared references define cross-cutting contracts and schemas; - helper scripts implement repeatable processing; - adapters translate canonical instructions into platform-specific packages; - generated distributions contain rebuildable outputs; - hooks enforce repository and output rules; - architecture and operating manuals explain how the layers interact; - dependency and installation files define the supported runtime. Use the canonical source layer as the authority. Generated distributions are evidence that the build works, not independent sources of truth. Regenerate them through the documented build workflow instead of editing them directly. Trace the smallest authoritative file that controls the requested behavior, then identify every synchronized document, schema, test, and generated artifact that depends on it. ## Keep One Original and Let a Converter Build Each AI Tool's Version Keep reusable instructions in one platform-neutral source format. Let adapters perform the packaging and syntax translation required by each supported environment. An adapter may: - copy a compatible source without semantic changes; - emit one native skill package per operation; - assemble a shared engine with multiple entry points; - build a platform package with prompts and supporting skills; - generate a dispatcher and routing table from source metadata. Adapters must preserve the original behavior and constraints. Translate platform-specific tool names into neutral actions when the target environment uses different tools. Generate routing metadata from the canonical description rather than maintaining a second handwritten catalog. When adding an operation, edit its canonical source once. Use an explicit platform exclusion only when the operation cannot work on that platform. Rebuild all affected adapters and review their outputs for semantic drift. ## Mark Every Saved Note with Its Sources and How Sure It Is Every operation that writes knowledge artifacts must follow the repository's canonical write contract. Design artifacts for reliable future retrieval and reasoning, not merely for immediate human readability. Require each artifact to include: - a short preamble explaining its purpose to a future AI reader; - structured metadata such as artifact type, date, tags, and an explicit AI-first flag; - stable internal links for referenced people, projects, ideas, and decisions; - recency markers for claims that can become outdated; - source URLs preserved verbatim beside external claims; - confidence labels that distinguish stated facts, strong evidence, moderate evidence, and speculation. Do not remove metadata, links, provenance, or confidence signals to make an artifact look cleaner. If an operation introduces a new artifact type, extend the shared schema before producing that type. ## Use Writing Rules That Automatic Checks Can Confirm Use conventions that formatters and hooks can verify consistently: - write sentence-case Markdown headings; - keep decorative emoji out of instruction sources; - use ASCII punctuation instead of typographic substitutions unless a non-ASCII symbol carries distinct meaning; - use lowercase tag values and quote ambiguous metadata strings; - follow the configured language version, formatter, line-length limit, and dependency manager; - use imperative commit subjects and apply the repository's attribution policy. Treat the canonical formatter and validation hooks as the final authority for mechanical style. Do not bypass them or manually preserve formatting that they reject. Keep conventions narrow enough to enforce automatically. When a rule cannot be checked mechanically, document the review evidence required to confirm it. ## Add a New Task and Update the Manuals and Lists in the Same Change Use this sequence when adding a new operation: 1. Create the canonical instruction source with routing metadata and complete operating guidance. 2. Add a helper in the designated script area only when executable logic is required. 3. Reference the shared write contract from every path that can create or modify an artifact. 4. Extend the shared metadata schema before introducing a new artifact type. 5. Update the operating manual, capability inventory, architecture notes, and public command catalog. 6. Record the change in the unreleased changelog section. 7. Run the adapter build and inspect every affected platform output. Do not duplicate an operation in generated platform trees. A synchronized change updates the source, governing references, tests, and documentation together so later rebuilds cannot erase or contradict it. ## Test the Instructions and the Version-Building Process Separately Test the source behavior and the generation pipeline separately. Use an isolated test workspace or linked local checkout rather than a live knowledge store. For behavior validation: - invoke the changed operation against representative test data; - inspect the resulting artifacts; - verify required metadata, links, provenance, confidence labels, and other write-contract fields; - confirm that unknown facts remain explicitly unknown. For pipeline validation: - run the repository's smoke suite through the configured package runner; - verify adapter output locations and generated routing; - exercise helper-script interfaces and machine-readable output; - update the matching assertion in the same change when an intentional output layout changes. Run the narrowest relevant test first, then the affected smoke suite. Manual behavior checks complement automated tests; they do not replace them. ## Release a New Version Only After Checks Pass and With Permission Release only when continuous integration is green and the machine-oriented write contract remains satisfied. Use a controlled release sequence: 1. Move unreleased changelog entries under a dated version heading. 2. Update the version in the primary package file and every mirrored manifest or citation file. 3. Run drift checks that compare all version declarations. 4. Rebuild generated distributions and run the affected tests. 5. Confirm the publishing role and branch policy before tagging or pushing. 6. Publish release notes from the approved changelog entry. Protect shared default branches. Contributors should use the required review path. A maintainer may publish directly only when repository policy explicitly grants that authority and the same verification gates have passed. ## Never Make Up Missing Facts or Edit Generated Files by Hand Never weaken the system's retrieval contract for cosmetic reasons. Do not strip required preambles or metadata, rewrite machine-oriented artifacts merely to sound more human, or add decorative elements prohibited by the source conventions. Do not invent rates, dates, ownership, relationships, or other missing facts. Mark unknown values as `TBD` or with the repository's equivalent explicit unknown marker. Never edit generated output when a generator owns it. Do not bypass hooks, publish through an unauthorized branch, or claim success from source inspection alone. Before reporting completion: - review the complete intended diff for unrelated changes; - confirm canonical sources and generated outputs agree; - run the relevant formatter, hooks, tests, and adapter build; - verify synchronized schemas, manuals, catalogs, and changelog entries; - record any manual validation and any check that could not run; - confirm that the final publishing action matched the authorized role. Report the changed behavior, verification evidence, remaining limitations, and any decision still required.