Build and Maintain a Research AI Agent Tool That Runs on Your Own Computer

## Run the Research Tool on the User's Computer and Decide What It Won't Do Build a local-first research environment that runs on the user's machine by default, installs through a documented public path, stores durable state in files plus version control, and supports the full research loop inside one project workspace. Keep one implementation runtime authoritative even when a thin launcher or multiple interfaces expose it. Use prompts and specialized skills to guide research work while a small service persists, restores, and routes state. Optimize for a focused core rather than an expanding platform, and state non-goals whenever a proposal would broaden the runtime, public tools, or deployment surface. ## Trust Current Files and Behavior over Memory and Old Plans Begin with the files that exist in the current checkout, not memory or an older plan. Read the product overview, documentation index, maintainer architecture, development guide, the smallest subsystem-specific references, the implementation, and the relevant tests. When sources disagree, prefer current runtime behavior and passing contract tests, then the repository-wide guide, then canonical maintainer documentation, then supplementary contributor notes. Update inaccurate documentation in the same change instead of preserving a stale path, feature claim, or workflow. Treat planned behavior and implemented behavior as different claims. Do not describe a component as available until its implementation, configuration, integration, documentation, and tests all support that claim. ## Keep Rules for Code Contributors Apart from Rules for the AI Inside the Tool Distinguish instructions for repository contributors from prompts and skills that govern an agent running inside the product. A runtime contract may require a particular public tool or constrained execution path without imposing the same restriction on maintainers editing the repository. Preserve this boundary whenever prompt, skill, command, or tool behavior changes. Do not reinterpret an in-product safety contract as a repository contribution rule, and do not weaken the runtime contract merely because maintainers have broader local development tools. ## Keep Each Research Project in One Folder with Version History Treat each research project as one version-controlled repository with one absolute project root. Keep all durable research content inside that root, and use branches or isolated worktrees to represent divergent approaches without splitting the project's history across unrelated locations. Maintain an explicit workspace contract for the brief, plan, status, summary, artifacts, baselines, experiments, literature, handoffs, manuscript, memory, and private runtime state. Runtime caches and logs may live outside the project, but they must not become the only copy of research evidence. When the project layout changes, update the layout model, persistence services, snapshots, API consumers, user interfaces, tests, and documentation together. Do not migrate one consumer while leaving the others on an obsolete structure. ## Keep the Startup Program Simple and Check What Is Actually Running Before Restarting Keep the authoritative research runtime in one implementation layer and make package-manager launchers thin adapters over that runtime and any prebuilt interface bundles. Public installation packages should contain the files and built clients required to start; do not depend on an end user's post-install build to make the supported path functional. Before debugging or restarting a live installation, inspect the running process, effective configuration, existing supervisor or launcher, actual runtime executable, and the home path reported by a health endpoint. Never infer the active home, configuration, or process owner from a default directory alone. Align package manifests, project metadata, public documentation, and bundle expectations. A package preview or dry run must confirm the shipped file set before packaging is treated as complete. ## Keep the AI's Public Tools Few and Justify Any New One Limit the built-in public tool surface to a few stable responsibilities: durable memory, versioned artifacts, and durable command execution. Keep version-control behavior behind the artifact boundary and shell execution behind the execution boundary rather than adding a new public namespace for every subsystem. Let prompts define workflow expectations and filesystem contracts, and let skills provide specialized execution behavior. The state service should remain thin; avoid hard-coding a large central stage scheduler when prompt and skill contracts can express the workflow clearly. Any proposal for a new public tool must show that an existing responsibility cannot contain it, define its persistence and permission model, update every client, and add contract tests. Convenience alone is not sufficient. ## Add New Connections Through Small Lists and Call Them Done Only When Every Piece Is Ready Use small registries for research runners, communication channels, connector bridges, skill discovery, managed local tools, and optional adapters. Prefer consistent registration, lookup, and listing interfaces over large dispatch branches or subsystem-specific conditionals. Do not call an integration implemented until its runtime adapter, registry metadata, configuration defaults, validation, service and command-line wiring, user-visible documentation, and tests are all present. Missing one layer means the integration is partial. Keep optional adapters outside the core path and make their absence explicit. A registry entry should expose capabilities and compatibility without silently installing dependencies, reaching an external service, or changing local configuration. ## Make the Browser and Terminal Screens Use the Same Project State and Service Connection (API) Require browser and terminal interfaces to consume the same service API, state snapshots, and event model. When an API route or event changes, update the service, every client, navigation assumptions, and contract tests in the same change. Preserve stable project-oriented routes and identifiers across interfaces. User interfaces may present different layouts, but they must not invent separate state semantics or hide a transition that another supported interface needs to observe. Treat a first-class communication channel as an implementation of the generic channel and bridge model. Do not let one important connector become a separate runtime with unique persistence, error handling, or lifecycle rules. ## Set Research Steps from Discovery to Writing Without Forcing One Straight Line Define a small canonical progression such as discovery, baseline, idea formation, experimentation, analysis, writing, and finalization. Keep decision-making cross-cutting rather than pretending that every important activity is a single linear stage. Intake audits, figure preparation, review, and rebuttal may exist as specialized activities, but do not place them in the default chain unless current code and prompt contracts actually do so. Named stages must match the system's active anchors, state transitions, and user documentation. Keep stage behavior in the system prompt, focused prompt contracts, prompt assembly, and stage skills. Avoid scattering stage semantics across service handlers, interface code, and ad hoc conditionals. ## Separate Guides for Users from Documents for Developers Keep user-facing guides separate from maintainer architecture and development references. Public documentation should explain current behavior; maintainer documents should explain contracts, extension points, and coordinated change requirements. Do not place temporary plans, scratch checklists, private paths, or internal-only notes in the public documentation tree. Keep linked document names stable, remove references to deleted files, and update every maintained translation when a user-visible behavior changes. When a change affects only internal maintenance, update the canonical maintainer references without manufacturing a user-facing announcement. Documentation scope should follow behavior scope. ## Keep Passwords and Personal Paths Out of Shared Files and Preserve Research Records Do not commit workstation-specific absolute paths, credentials, tokens, local caches, dependency directories, transient build output, or test caches. Generated interface bundles belong in a public package only when the packaging contract explicitly requires them. Keep durable experiment records, literature notes, baselines, artifacts, and manuscripts inside the project boundary and under version control. Preserve the original evidence before summarizing it, and never replace a reproducible result with an interface-only status message. Review public files for leaked secrets, obsolete document names, private references, and generated-file drift before release. A clean test run does not excuse publishing sensitive or non-reproducible content. ## Look at the Current Code First and Make Small Changes Inspect the existing implementation before proposing a new abstraction. Prefer small, coherent changes over broad mixed refactors, use the smallest relevant documentation set first, and verify the proposal against code and tests. When code and documentation diverge, fix both in one scoped change. Do not preserve stale references because they once existed, and do not restart a live research service until the effective runtime, process, configuration, and home are identified. Separate diagnosis from mutation. Record the observed signal, expected behavior, affected consumers, and smallest correction before changing shared state. ## Update Tests and Docs Along with the Code You Change, and Leave Unrelated Areas Alone Update every directly affected layer for the subsystem being changed: - project layout or durable state: layout model, persistence service, snapshots, API consumers, and state tests; - prompts or stage skills: prompt sources, assembly, skill definitions, mirrored installers, behavior tests, and user guides; - memory, artifacts, or command execution: implementations, public boundaries, service tests, and contract documentation; - research runners: adapter, registry, configuration defaults, validation, service and command-line wiring, guides, and tests; - channels or connector bridges: defaults, validation, channel and bridge code, connector guides, and integration tests; - managed local tools: registry, concrete adapter, status and resolution behavior, maintainer guides, and tests; - shared API surface: router, handlers, browser client, terminal client, navigation, and contract tests; - packaging: manifests, project metadata, public overview, required bundles, and package-content verification. Do not expand this matrix to unrelated subsystems. The purpose is coordinated completeness within the direct impact boundary, not a repository-wide rewrite. ## Test the Documented Install Path Before Calling the Work Done Run the relevant unit, integration, contract, compilation, interface-build, and packaging checks for the changed surface. Start through the documented public path when launcher or packaging behavior changes, and verify direct service startup only as a diagnostic path. Review the final difference for unrelated edits, stale generated files, missing translated documentation, unsupported feature claims, and incomplete client updates. Distinguish a locally successful component test from proof that the supported installation and interface path works. Use the actual checkout as the final source of truth. If a referenced file or behavior no longer exists, correct the reference and its consumers rather than preserving the mistake.