Keep an AI Coding Agent Within Your Request in a Layered App Repository

## Rank instructions, and trust current code over memory The current checkout is the source of truth for current behavior. A user request can define a desired behavior change, but it does not turn a historical assumption into fact and does not grant permission for an unrelated external action. ### Instruction order Follow applicable higher-level instructions first, then the nearest scoped agent instruction file, then the latest user request. At the same authority level, the newer explicit instruction wins. ### Evidence order For current checkout behavior, prefer current source and tests, then repository-local workflows and scripts, then documentation. For current runtime state, live evidence counts only after the working directory, artifact, branch, or equivalent provenance ties it to the intended checkout. An unproven process from another checkout does not override source facts. Prior memory and subagent reports rank below inspected evidence, and inference ranks last. ### Memory discipline Treat prior memory and subagent output as potentially stale leads. Verify consequential claims against the current checkout, and never let memory authorize a mutation or an external action. Do not write durable memory about the repository unless the user explicitly asks for it. Never carry secrets or user data into memory. ## Pick the app edition by its real setting and keep removed features out Some behavior is a product contract rather than an implementation detail. Do not change it as a side effect of another task. ### Select behavior by the real runtime signal An edition or mode must be selected by its documented runtime property or build environment variable. A final artifact name changes the artifact name only and is never a runtime-mode signal. New runtime branches must read the real signal; never infer mode from an archive name, application name, port, or artifact path. ### Keep the shipped edition boundary Do not reintroduce gateway forwarding, cloud accounts, subscriptions, payment, commercial licensing, or an alternative desktop runtime into an edition that removed them. Hidden frontend UI is not backend isolation: remote calls, headers, cookies, controllers, and service registration must respect the edition boundary too. ### Keep compatible semantics Preserve public API, storage, datasource, namespace, console, task, and layout-position semantics unless an explicit compatibility or migration change is requested. Where the packaged desktop build supports updates from inside the application, keep the renderer update UI and state, the native update handlers, updater metadata, packaged payloads, and any elevated updater helper aligned whenever the release format changes. ## Use the code index for structure and text search for literal strings ### Structural questions When a structural code index is initialized and its tools are available, start with a context query for a feature, architecture, or bug path, then explore the related source once. Use symbol lookup for names, caller and callee queries for call paths, and an impact query before changing a shared symbol. Use the indexed file listing for source-tree exploration and the status command for index health. ### Literal questions Use text search for literal strings, configuration keys, log lines, comments, generated flags, and command lines. Do not repeat an index result with a second search-and-read loop. ### Limits of the index The index can lag recent writes, and the build tools remain the correctness authority. If the index is unavailable, use focused file reads and text search without pretending indexed results exist. If the repository has no initialized index, ask before creating one. ## Tell read-only requests from change requests before acting - Answer, explain, review, diagnose, and status requests are read-only by default. Use non-mutating inspection and report evidence. Do not edit files, run mutation-heavy builds, or implement a fix unless asked. - Change, fix, and cleanup requests authorize local source edits and the relevant local commands within the named scope. - A build request authorizes build commands, dependency caches, and generated output only. It does not authorize source repair unless the user also asks for a fix. - Commit, push, tag, workflow dispatch, publication, deployment, signing, and any action touching production or customer data require explicit authorization for that specific external effect. ## Finish an approved change end to end in the smallest scope For an authorized implementation task, deliver the requested outcome end to end within the smallest coherent scope. - Confirm the exact repository, branch, status, and existing user changes. - Read the nearest implementation, tests, configuration, and workflow before editing. Trace cross-layer behavior when a change spans frontend, backend, storage, containers, or desktop packaging. - Classify the change by affected surface and choose verification accordingly. - Edit narrowly, following existing module ownership and local conventions. - Run the relevant checks, inspect the final diff, and distinguish verification you actually executed from checks that were not available. - Report the result, the remaining risk, and the exact uncommitted or unpushed state. ## Keep server and client code in their own layers and modules ### Server side Keep controllers and transport adapters thin. Business behavior belongs in domain services, and persistence belongs behind storage APIs or providers. Preserve the module dependency direction and the documented contracts; do not bypass domain APIs with new coupling from the web layer straight into storage. Use the project's existing language level and frameworks instead of introducing a parallel framework or a utility abstraction for behavior a module already owns. Keep database-specific SQL, metadata, completion, and type behavior inside its owning plugin, and add focused plugin tests for dialect changes. ### Client side Use the existing frontend stack, project components, and service helpers. Derive edition conditions from the current runtime-edition helpers or the documented build environment variable instead of scattering unrelated environment checks. Do not add a duplicate desktop bridge or a second renderer transport; use the existing bridge wrappers. Preserve service response contracts and storage keys, because removing UI does not authorize deleting a backend contract another path still uses. Keep user-facing strings in the existing localization system when the surrounding feature is localized. ### High-risk surfaces Changes to shared request context, identity, isolation boundaries, storage routing, AI services, or desktop startup require explicit call-path and regression review. ## Keep secrets and generated files out of commits ### Never commit sensitive or reproducible content Never commit credentials, tokens, signing material, private URLs, local database contents, editor files, runtime downloads, package-manager output, frontend build output, staged packaging content, or installers. ### Handle secrets narrowly Read secrets only when the explicitly authorized operation requires them. Never print, log, paste, summarize, or persist a secret value. Do not reuse a credential for a different repository, registry, account, or environment. ### Keep real data out of the loop Do not access or mutate production data, user data, or an unrelated local database for build or diagnostic convenience. Use fixtures or a named local test datasource unless the user explicitly places another system in scope. ### Network exposure Keep desktop and host-published listeners on loopback unless remote exposure is explicitly requested and documented with its security impact. Do not change a container's required internal binding in order to enforce a host publication policy. ### Versioned against generated Know which packaging resources are versioned source and which are reproducible output. Do not remove a tracked resource merely because it shares a parent directory with generated files. Update the readme and workflow examples when a public command, port, artifact, environment variable, or release input changes. ## Pick tests and checks by which part of the app changed - Frontend logic, route, service, or state: the relevant focused test, the lint task, and the edition build. - Server domain, web, storage, or plugin code: focused tests with test execution explicitly enabled, any stale test-include pattern and failure-ignoring setting overridden, and a confirmed nonzero test count; then package the affected module and its dependencies. - Shared API or persistence contract: add compatibility coverage and inspect callers plus serialization and storage effects. - Runtime-mode, identity, isolation, AI, or network behavior: inspect both the registration path and the call path, and run an edition smoke test when feasible. - Native bridge code: focused bridge tests, a full compile or package, and matching renderer verification. - Desktop scripts and resources: syntax-check the touched shell scripts, validate platform metadata, run the preparation step, and review the cross-platform workflows. - Container work: script syntax, compose expansion, image build, and an HTTP or static-asset smoke test when the container runtime is available. - Workflow definitions: parse or inspect the resolved inputs and commands, and distinguish artifact upload from release publication and from content-delivery upload. - Documentation-only changes: verify commands, links, paths, ports, and names against current source and workflows. - Every change: a whitespace and conflict-marker diff check, a focused diff review, and a final status check. ## Don't call a build a test pass; report only tests that ran Build success is not test success. When a project skips tests by default, or carries a stale test-include pattern or a failure-ignoring setting, override those explicitly and confirm the test summary reports a nonzero test count with zero failures and zero errors. ### Do not overstate Do not claim a build ran tests when the build was invoked with tests skipped. Do not claim a native package works from shell syntax or a preparation step alone; claim installer success only for an installer actually built and run on its target platform. If running a broader test set surfaces stale compilation failures elsewhere in the module, report them instead of weakening test discovery. ### Name what was not run Separate out the checks that remain automation-only, platform-only, or otherwise unrun. If a required tool is unavailable, report the missing check or use an equivalent read-only fallback; never fabricate tool output and never silently broaden the environment. ## Use only the services and test databases the task needs - For an authorized change or build task, repository edits, generated build output, standard package-manager caches, and ordinary dependency downloads are allowed. Do not change global package-manager configuration or install system packages unless the task requires it and the impact is explicit. - Start a local service only when the requested smoke test needs it. Inspect the port first, bind to loopback, record the process, and stop only the process you started for this task. Never bounce an unrelated service. - Container builds and task-scoped test containers are allowed for a container build request. Do not prune the daemon, remove unrelated resources, or start composed services outside the task. - Use only named local or test databases for autonomous verification. Schema or data mutation in shared, staging, or production systems requires explicit scope, a recovery plan, and authorization. - Read-only network access for dependency resolution and public source checks is allowed when needed. Authenticated writes, uploads, workflow dispatches, messages, and publication remain external actions requiring explicit user authority. ## Keep the user's changes and ask before pushing or releasing ### Protect the user's working tree Preserve unrelated user changes, including changes in files you also need to edit. Never reset, check out, clean, or overwrite them to simplify the task. Do not use destructive version-control commands, and do not remove local data or generated caches outside the requested scope. ### Require an explicit request Do not stage, commit, push, tag, dispatch workflows, publish releases, upload packages, or push images unless the user explicitly requests that action. Treat workflow dispatch, release publication, image push, content-delivery upload, moving a rolling tag, and signing as external mutations behind an explicit approval boundary. ### When a commit or push is requested Stage only the intended semantic scope, inspect the staged diff, check it for credentials or generated output, run its checks, and verify the local and remote commit identifiers. ## Say what changed and which checks ran when handing off At handoff, state what behavior changed and which files own it; which commands were actually run and whether they passed; any verification that remains automation-only, platform-only, or otherwise unrun; the current version-control state, including unrelated modifications left untouched; and every attempted external action with its commit, remote branch, workflow run, image, release, or artifact identifier, including partial or failed attempts. ### Code review reports For a code review, report findings first in severity order, each with its file and line, the affected runtime surface, the behavioral risk, and the required fix or the missing evidence. If there are no findings, say so and list the residual test gaps. ## Decide when to stop and ask, and how to retry after a failure Continue autonomously for normal read, edit, build, and test work within the requested scope. Stop and ask only when one of these conditions materially changes the result: - applicable instructions conflict, or the desired behavior remains ambiguous after current source has established the existing behavior; - the task requires deleting user data, changing a public compatibility contract, exposing a listener, or crossing an edition boundary; - credentials, signing identity, release destination, or production authority are missing; - an irreversible or externally visible action was not explicitly requested; - unrelated user edits make the requested change unsafe to isolate; or - required verification still fails after one cycle of diagnosis and repair and no safe in-scope recovery remains. ### Retries and interruptions Retry a transient, idempotent operation at most twice. Never blindly repeat a push, workflow dispatch, release, upload, signing request, or other external mutation after an ambiguous result; inspect the remote or provider state first. After an interruption or a partial completion, recheck branch, worktree, remote, and workflow state before resuming. ### On failure Keep the worktree recoverable, record the exact command and error, avoid unsupported success claims, and hand off the current goal, the evidence, the actions already attempted, the identifiers, the open risks, and the next safe action.