Change a Full-Stack Repository Using Its Own Commands and Tests

## Read the Repo's Docs First and Work on a Branch with a Pull Request Read the repository-level guidance, subsystem documentation, package manifests, and nearby implementations before planning a change. Identify every affected surface, including the frontend, API, SDK, CLI, database, containers, and documentation. Treat the protected default branch as read-only for direct development. Create a descriptively named branch, make meaningful commits, and open a pull request for review. Do not rewrite shared history with an amended commit, and do not merge your own pull request when the workflow assigns that decision to a reviewer. Keep the branch focused on the requested behavior. Separate unrelated cleanup and preserve established patterns unless the task requires a deliberate change. ## Use the Repo's Own Commands and Pinned Runtime Versions Discover the documented development, formatting, linting, test, migration, and startup commands before running them. Use the command owned by the affected package instead of substituting a root-wide tool. Honor pinned runtime versions and existing environments; a newer major runtime is not automatically supported. Install dependencies only when they are missing. Do not start the complete application stack, containers, or long-running servers unless the task or relevant verification requires them. Run formatters and linters on changed files with their documented modes. Start with a supported single-test selector, then expand only to the directly affected suite. When a subsystem imports an installed SDK package rather than its source tree, reinstall that SDK after editing it and restart the consuming process. Check required ports and prerequisites before starting combined development processes. ## Keep the Jobs of UI, API, Services, and Migrations Separate Map responsibilities before editing: - the user interface owns presentation and client state; - the API owns request validation and transport concerns; - service modules own business logic; - SDK and CLI packages own their public contracts; - migrations own database evolution. Read the documentation for the subsystem being changed and inspect similar existing files before introducing a new pattern. When a change crosses layers, proceed in small steps: define types or schemas, implement service logic, expose the API contract, update the client, then build the interface. Install a dependency in the package that uses it. When adding a workspace package, update every production and local container-build manifest that copies package metadata before dependency installation. ## Follow the TypeScript, Python, and Database Rules Use strict TypeScript types, avoid unbounded types, define component and API contracts clearly, and follow the repository's established component and state-management patterns. Prefer functional components and explicit state actions over deep property threading. For Python code, provide type hints for every function boundary, use validation models for serialization, and keep business logic in services rather than transport routers. Routers should validate requests, call services, and shape responses. Follow existing table and migration rules, including any prohibition on foreign keys. Keep database operations portable across every supported engine. Use the repository's UTC helper for timestamp fields instead of local time, deprecated APIs, or hand-built conversions. Respect the repository's decision about filesystem versus database storage. Do not move synchronized cluster data into a database merely for convenience. ## Test Each Change in the Layer and Test Suite It Belongs To Use the test system actually configured for each subsystem. If the frontend has no unit-test framework, cover its behavior with the designated end-to-end suite rather than introducing an unsupported runner. Put backend unit and service tests in their established tree, and run the CLI suite after changing CLI source. Mock external storage, compute providers, and filesystem interactions so tests remain fast and deterministic. Prefer direct service tests for business rules that do not require the full API stack. Run one focused test first, then the relevant subsystem suite. Make repeated runs safe against existing data, use stable selectors, and allow realistic timeouts for queued work or state transitions. Do not claim success from a command name alone. Confirm that the intended test files were discovered and that the result exercises the changed behavior. ## Check Changed Pages in a Browser and Test Logged-In API Calls Use the repository's approved interactive browser tool for visual inspection. Reserve automated end-to-end scripts for the maintained test suite or an explicit request. Start only the required test application, navigate to the changed and directly related pages, capture evidence, and correct visible regressions. Prefer role, exact-text, and placeholder selectors. Handle repeated test data without assuming a clean database. Content rendered by a terminal emulator may not exist in the DOM; verify it through the backing API when required. For authenticated API checks, use the documented test identity and authentication flow. Supply required account or tenant scope headers, distinguish protected from unprotected endpoints, and never place reusable credentials in source, logs, or the resulting documentation. ## Add Dependencies Carefully and Keep Passwords Out of Logs Check package manifests before adding dependencies and use the repository's installation workflow. Keep pre-commit formatting and linting hooks active when the project relies on them. Treat dependency overrides as temporary security controls, not permanent decoration. When upgrading a parent package, test whether the override can be removed, run the relevant vulnerability scan, and retain the override if the resolved dependency is still unsafe. Do not broaden credential exposure while testing integrations. Mock external providers when their real behavior is not the subject of the test, and keep logs free of tokens, passwords, and personal identifiers. ## Check the Diff and Report the Evidence Before Finishing Read before planning, make the smallest coherent implementation, and verify each affected boundary before expanding scope. For larger changes, keep the sequence explicit and reviewable rather than mixing backend, API, client, and interface work in one opaque step. Before reporting completion, inspect the diff and run the relevant formatter, linter, type check, tests, migration checks, and visual verification that the changed surfaces require. Do not add a full build or unrelated suite merely for appearance. Report what changed, which checks ran, what broader checks remained out of scope, and any residual risk. Completion requires evidence from the behavior that changed, not only a successful edit.