Edit a Typed Monorepo Without Breaking It and Keep Its Wiki Current

## Find Which Packages, Tests, and Docs a Change Touches Treat the root agent guidance as the shared contract for every coding agent. Any tool-specific instruction file should remain thin and defer to that contract instead of duplicating it. - Identify where core packages, optional integrations, developer tools, ecosystem modules, examples, documentation, and tests live. - Expect tests and fixtures to sit near the package they exercise unless the repository states otherwise. - Read the nearest package guidance before editing a subsystem. - Trace a requested change to its owning package, public surface, tests, and documentation before touching files. - Prefer the smallest affected scope; do not turn a focused task into a repository-wide rewrite. ## Use the Repository's Own Package Manager and Scripts Use the package manager, workspace definition, runtime version, and scripts declared by the repository. Do not replace them with a familiar alternative merely because it is installed locally. - Use the documented install command to hydrate the workspace. - Use the root build, test, lint, and type-check scripts for full checks. - Use supported workspace filters for focused package work. - Preserve argument forwarding exactly when a wrapper passes options to an underlying tool. - Check repository configuration files before changing package-manager or runtime assumptions. - Record any prerequisite that a narrower command depends on. ## Run Tests in CI Order Without Stale Build Files Reproduce the continuous-integration order instead of inventing a local sequence. If CI installs dependencies and runs its validation command without building first, run tests the same way. - Do not build first when generated output can be discovered alongside source files. - Recognize duplicate registration, duplicate schema, or duplicate decorated-class errors as possible evidence that both source and generated files were loaded. - Remove only generated output directories under the documented source roots, while excluding dependencies, tests, and fixtures. - Never delete source directories to clear a generated-output failure. - Re-run the failing test after cleanup before changing implementation code. - If cleanup does not change the failure, resume ordinary debugging with the new evidence. ## Follow the Repo's Code Style and Keep App State Out of Globals Prefer established repository patterns over new abstractions. Use the module system, typed-language conventions, formatter, linter, and filename style already adopted by the codebase. - Keep filenames lowercase and hyphenated when that is the repository convention. - Make public API changes deliberate, covered by tests, and documented. - Keep application-specific mutable runtime state in an application-owned scope rather than a process-global singleton. - Use the framework's scoped storage for lifecycle utilities and other per-application services. - Re-enter the owning application scope for detached callbacks such as timers, event listeners, proxy handlers, and module-level escape points. - Do not add redundant scope wrappers around accessors already pinned to the correct application context. ## Keep Modules Loaded at Boot Safe for Startup Snapshots When a runtime can serialize a startup snapshot, assume that build-time boot may stop before normal application startup. Any module loaded during that phase must be safe to serialize. - Keep modules external when import-time or boot-time work creates non-serializable native state. - Treat HTTP parsers, HTTP/2 bindings, TLS contexts, DNS channels, WebAssembly instances, file watchers, native add-ons, and open sockets as high-risk snapshot dependencies. - Route externalized modules through the runtime's restore-time loading bridge. - Maintain one documented default list of modules that must remain lazy or external. - Extend that list through the repository's supported configuration rather than patching generated output. - Distinguish direct native-state creation from transitive network use: lazily externalized built-ins may already protect transitive dependencies, while a package that directly creates native or WebAssembly state still needs explicit treatment. - Add a snapshot build test when a framework dependency can touch the native or network stack during boot. ## Put Global Type Additions in Dedicated Type Modules Place package-wide global augmentations in a dedicated global type module. Shared augmentations that serve multiple packages belong in a shared typings package, not in a single consumer. - Keep declaration files as modules with an import, type-only import, or empty export. - Import the shared augmentation from the package entry point that needs the type surface. - Avoid ambient declarations that become global only because a file lacks module syntax. - Test both the defining package and at least one consuming package after moving shared types. - Document any public type-surface change. ## Run Targeted Tests and Check the Final Diff Before Reporting Run the most targeted checks that prove the behavior you changed, then expand only when the affected boundary requires it. - Add regression coverage for changes to loaders, application lifecycle, clustering, agents, HTTP handling, or process behavior. - Run formatting, linting, type checking, and relevant tests through repository scripts. - Use the repository's commit-message convention and keep the scope accurate. - Explain motivation, changed behavior, risk, and test evidence in the change description. - Review the final diff for unrelated edits, generated noise, and undocumented public changes. - Do not claim success until the relevant command has completed successfully. ## Keep Secrets Out of Commits and Stop Before Sharing Vulnerabilities Read the repository security policy before handling vulnerability-related work. Never commit secrets, credentials, private endpoints, or machine-specific configuration. - Keep local runtime and package-manager versions aligned with repository declarations. - Treat lockfiles and workspace configuration as coordinated inputs; change them only for an intentional dependency or toolchain update. - Use placeholders in examples and documentation instead of real credentials or private URLs. - Keep security-sensitive changes narrowly scoped and add regression coverage for the protected boundary. - Stop before publishing vulnerability details or changing protected external systems unless the task explicitly authorizes that action. ## Keep Code and Other Sources, the Wiki, and Agent Rules Separate Maintain three distinct knowledge layers. Raw sources are authoritative evidence, the wiki stores durable synthesis, and the root agent guidance defines shared workflow rules. - Treat code, user-facing documentation, root project files, explicit external artifacts, and imported raw material as source evidence. - Start from wiki summaries for orientation, but verify against raw sources when details, conflicts, or freshness matter. - Do not rewrite raw sources unless the task requires it. - Capture repeatedly used external evidence in the repository knowledge base. - Record conflicts instead of flattening them into a false consensus. - Keep tool-specific agent files thin and point them to the shared schema. ## Give Each Wiki Page One Topic and Its Source Files Give every substantive knowledge page one clear topic and a declared page type such as package, concept, workflow, decision, or source. - Use lowercase, hyphenated filenames. - Include frontmatter with a human-readable title, page type, one-line summary, major source paths, local calendar date, and freshness status. - List nontrivial claims with traceable source files. - Label non-obvious synthesis as an inference. - Mark stale or unresolved claims when freshness is uncertain. - Keep the wiki index concise and organized by category. - Use an append-only log for substantial ingestion, durable findings, material refactors, and changes that alter recorded understanding. - Do not log trivial typo-only edits. ## Read the Wiki Index First When Adding Sources or Answering Questions Use a predictable workflow when ingesting sources, answering repository questions, or linting the knowledge base. - For ingestion, read the index, find existing pages that should absorb the material, create or update a source page when warranted, update affected pages, refresh the index, and append a log entry for material changes. - For queries, read the index and relevant wiki pages first, verify against raw sources, write back durable new findings, and log material knowledge changes. - For linting, check for orphan pages, stale claims, duplicated concepts, missing source references, absent pages for frequently used areas, and contradictions. - Prefer restructuring overlapping pages over making them indefinitely longer. - Prioritize durable coverage for foundational packages, integrations, tools, lifecycle behavior, loading, testing, release work, and documentation maintenance. ## Update the Wiki When APIs or Workflows Change, Not for Every Edit Update the knowledge base when work materially changes public APIs, documentation structure, package responsibilities, architecture, repeated contributor workflows, testing expectations, or release procedures. - Avoid wiki churn for a code-only change that does not alter durable understanding. - Update contributor guidance in the same change when a new rule becomes broadly applicable. - Keep source paths and freshness dates synchronized with the facts they support. - Add a log entry only when the knowledge change is substantial enough to help future work. - Verify the final documentation against the implemented behavior before reporting completion.