Agent & Workflow Guidelines
Relevant source files
The following files were used as context for generating this wiki page:
Introduction
The Agent & Workflow Guidelines define the operational framework for AI agents and human developers contributing to the ProductCompare repository. This project follows a modular monolith architecture using Elixir/Phoenix for the backend and React with Relay for the frontend. These guidelines ensure consistency across parallel workstreams, maintain strict architectural boundaries, and enforce non-negotiable implementation conventions.
The system relies on a central planning directory (docs/work/) to coordinate "lanes" of execution, primarily divided into frontend and backend workflows. By adhering to these protocols, agents can operate independently while maintaining the integrity of the unified codebase.
Sources: ARCHITECTURE.md:1-12, AGENTS.md:1-15
Execution Framework
Work Discovery and Entry Points
Agents must follow a specific hierarchy of documentation to determine the current state of the project and the next required tasks. The source of truth for active execution is managed through the docs/work/ directory.
- Primary Entry Point:
docs/work/index.mdcontains the priority list and active blockers. - Queue Management:
docs/plans/INDEX.mdserves as the repo-level queue for implementation plans. - Current Batch:
docs/plans/NOW.mdrecords the immediate next steps for active lanes. - Historical Context: Dated documents in
docs/plans/provide design checkpoints but are superseded by the work index.
Sources: AGENTS.md:3-10, ARCHITECTURE.md:3-6
Parallel Subagent Dispatch
To scale development, the project utilizes a subagent dispatch plan that categorizes work into functional slices (A-F). This allows multiple workstreams to proceed with defined integration rules.
| Lane | Focus Area | Description |
|---|---|---|
| Subagent-A | Repo/Architecture | Bootstrapping, nix environments, and core boundary setup. |
| Subagent-B | DB/Migrations | Schema design, indexing strategy, and Ecto migrations. |
| Subagent-C | Core Workflows | Service API implementation and transaction invariants. |
| Subagent-D | Seeds | Deterministic dataset creation and idempotent seed flows. |
| Subagent-E | Testing | Unit, context integration, and E2E test matrix execution. |
| Subagent-F | Deliverables | Documentation and framing of deferred scope. |
Sources: 2026-03-03-product-compare-backend-mvp-plan.md:44-55
Coordination Workflow
When working in parallel mode, agents are restricted to specific "Owned paths" associated with their lane.
The diagram shows the sequence an agent must follow to ensure work does not conflict across parallel lanes.
Sources: AGENTS.md:3-15
Backend Implementation Conventions
Architectural Boundaries
The backend is structured as a modular monolith. All business logic must reside within specific context modules, while Ecto schemas remain "schema-only" under the ProductCompareSchemas namespace.
- Accounts: Users, reputation, and authentication.
- Taxonomy: Tree structures, closures, and product tagging.
- Catalog: Brands and product anchors.
- Specs: Attributes, units, claims, and filtering logic.
- Pricing: Merchants, listings, and price history.
- Affiliate: Networks, programs, and coupons.
- Discussions: Threads, posts, and reviews.
Sources: README.md:24-32, backend_starting_guide.md:37-65
Database and Schema Rules
The following technical constraints are non-negotiable for all database migrations and schema definitions:
- Timestamps: Use
:utc_datetime_usecfor all schema fields and migrations. - Primary Keys: Relational tables must use
bigintfor internal IDs. - Entropy IDs: Every relational table must include an
entropy_idusinguuidv7()generated by PostgreSQL 18. - Token Security: Raw secrets must never be persisted; use SHA3-256 hashes (
:sha3_256).
Sources: backend_starting_guide.md:7-13, backend_starting_guide.md:89-98
Authentication Contract
Frontend-Backend Integration
The project is migrating from legacy REST endpoints to a unified GraphQL authentication flow.
- Transport: Browser auth must use GraphQL via
/api/graphql. - Authority: Phoenix remains the cookie-backed session authority.
- Mechanism: GraphQL mutations (login, register, logout) set or clear Phoenix session cookies rather than returning bearer tokens.
Sources: AGENTS.md:17-23, ARCHITECTURE.md:8-12
Auth Workflow Sequence
The sequence below illustrates the interaction between the React frontend and the Phoenix backend during a login operation.
The diagram shows that the GraphQL mutation is the trigger for session management handled by Phoenix.
Sources: assets/src/routes/auth/actions.ts:74-87, AGENTS.md:19-21
Development and Verification Gates
CI and Pre-commit Requirements
Before code is considered deliverable, it must pass a series of static analysis and testing gates. Agents are required to run the mix precommit alias as a hard gate.
| Command | Purpose |
|---|---|
mix compile | Ensures code compiles without warnings. |
mix test | Runs the full test suite (Unit, Integration, E2E). |
mix typecheck | Executes dialyzer and check.typespecs --strict. |
mix format | Enforces consistent code style. |
Sources: backend_starting_guide.md:148-158, README.md:34-39
Agent Checklist
Agents must verify the following items before opening a Pull Request:
- Relational tables use
bigint id+entropy_id uuidv7. - Public functions have
@specdefinitions. - GraphQL IDs are Relay global IDs.
- Mutations return typed payloads and structured errors.
- New schemas define
@type t.
Sources: backend_starting_guide.md:164-184
Summary
The "Agent & Workflow Guidelines" ensure that all contributions to the ProductCompare project adhere to a strict modular monolith architecture and a unified communication contract. By centralizing work discovery in docs/work/ and enforcing specific technology choices like UUIDv7 and Relay-first GraphQL, the project maintains high velocity without compromising system stability. Agents are expected to be self-verifying, utilizing the provided mix tasks and checklists to guarantee technical accuracy.
Sources: backend_starting_guide.md:1-5, ARCHITECTURE.md:25-30