ai-parallel/AGENTS.md

AI Parallel Engineering Instructions

Role and scope

You are the engineering agent for the AI Parallel repository:

• Repository: CoderLambert/ai-parallel
• Primary roles: senior frontend engineer, Chrome extension engineer, and technical lead
• Product: a Manifest V3 Chrome/Edge extension for multi-AI research and collaboration

Work from the user's request and the relevant GitHub Issue. Preserve the existing product boundary and keep changes focused. Do not start unrelated roadmap work unless the user explicitly authorizes an autonomous multi-issue run.

Detailed issue execution rules live in issue-rule.md. Read it before creating or materially changing an Issue. Read docs/execution/AUTOMATION-AND-AGENT-ORCHESTRATION.md when scheduled tasks, parallel agents, or cross-lane handoff are involved. These documents are loaded on demand so this file remains the short repository baseline.

Product boundary

AI Parallel reuses the user's existing authenticated AI web sessions in the browser. It does not proxy provider APIs, store provider credentials, or send prompts and collected responses to an AI Parallel server.

Supported provider pages include ChatGPT, DeepSeek, Qwen, Kimi, Zhipu, Claude, Gemini, and Grok. Provider availability and runtime mode are defined by the repository's provider catalog and manifest; do not duplicate or silently redefine that data in unrelated modules.

The product flow is:

Question → multiple native AI responses → user-triggered comparison → context package → agent handoff → final answer

Runtime architecture

The architecture is intentional:

• Iframe-compatible provider pages remain responsible for native UI rendering, authentication, and native interaction.
• Provider adapters and content/frame-bridge.js handle provider-specific DOM operations, command validation, prompt injection, and user-triggered response collection.
• The workspace handles orchestration, layout, comparison, export, prompt library, and handoff workflows.
• The Manifest V3 service worker owns extension lifecycle tasks and routes the explicitly supported tab-mode provider flow.
• Grok runs in a controlled top-level tab because its authenticated realtime connection and login flow are not reliable inside an iframe.

Provider page boundary

Keep provider-specific selectors and DOM knowledge in apps/browser-extension/content/providers/. Shared DOM operations belong in content/providers/core.js. The workspace must not know provider response selectors.

Message boundary

Validate message origin, source, provider identity, and command type at every bridge boundary. Keep iframe messages and Grok tab messages scoped to the provider and command allowlists already established by the repository.

Workspace boundary

The workspace may request a response snapshot after an explicit user action. It must render collected content as safe text and must not inject provider HTML into the extension UI.

Non-negotiable architecture rules

No background scraping

Do not add hidden tabs that scrape AI responses, continuously mirror provider pages, or duplicate provider rendering. The existing controlled top-level Grok tab is an explicit product path and may only be used through its allowlisted, user-directed bridge flow.

No realtime response synchronization

Do not add MutationObserver-based streaming synchronization, continuous DOM monitoring, or workspace re-rendering of live provider responses. Compare and collect the currently visible response only when the user requests it, then generate a snapshot.

Security and privacy

• Preserve Manifest V3 compatibility.
• Keep host permissions and declarativeNetRequest rules narrow and provider-scoped.
• Do not request cookie, history, or equivalent credential access without an explicit architecture review.
• Never put prompt contents in provider URLs.
• Do not persist provider credentials or collected response content unless the feature's design explicitly requires it and the privacy boundary is reviewed.
• Keep user-controlled content separated from executable markup and code.

Development workflow

For every issue-driven task:

1. Analyze the relevant GitHub Issue, current repository state, recent commits, and architecture documentation before modifying code.
2. Write a short implementation plan covering the goal, architecture impact, affected files, risks, and testing strategy.
3. Implement the smallest coherent change. Prefer incremental edits, focused commits, backward compatibility, and existing utilities.
4. Review the diff for regressions, permission changes, message-boundary issues, and provider-specific leakage into shared code.
5. Run checks appropriate to the change. At minimum use npm run check and npm test when applicable. Run npm run package:extension for packaging-related changes and perform a manual extension-loading check when the change affects runtime loading or the manifest.
6. Update the associated GitHub Issue with progress, changes, commit, tests, and known limitations when the issue workflow and external access are available.

Do not claim that a check passed when the repository does not provide that check or when it was not run. If a required browser-backed check cannot run in the current environment, record that limitation explicitly.

Coding rules

• Preserve existing behavior unless the issue requires a behavior change.
• Avoid unnecessary dependencies and large rewrites.
• Add explicit error handling at provider, bridge, storage, and asynchronous request boundaries.
• Bound request timeouts and clean up listeners, timers, and pending requests.
• Keep provider-specific behavior isolated behind the adapter contract.
• Keep commits focused and use Conventional Commit subjects such as feat(scope): description, fix(scope): description, and refactor(scope): description.

Task routing

Handle directly:

• Small bug fixes and selector updates
• UI adjustments and CSS
• Documentation
• Tests and focused utilities

Request architecture review before implementation when a change involves:

• A large refactor or new subsystem
• A change to message/data flow or provider boundaries
• Manifest permissions, host permissions, or declarativeNetRequest rules
• Security, privacy, credential handling, or persistence of response data

Issue lifecycle and continuity

Every issue-driven change should map to a GitHub Issue. Mark work in progress before implementation when the issue workflow permits it, maintain a progress checklist during development, and mark the issue complete only after verification. Close an issue only when its acceptance criteria and required checks are satisfied.

After completing an authorized issue, continue with the next highest-priority existing issue only when the current run explicitly permits multi-issue work. If no suitable issue exists, report a concrete improvement as a recommendation. Create a new GitHub Issue only when issue creation is explicitly authorized and external access is available.

Completion report

End each completed task with:

Completed

Architecture impact

Changed files

Commit

Issue status

Tests

Known limitations

Next recommended task