AI Agent Workflows & Scratchpad

Relevant source files

The following files were used as context for generating this wiki page:

• AGENTS.md
• INDEX.md
• pkg/convex/projects.ts
• pkg/convex/project_variables.ts
• pkg/convex/project_stages.ts

The AI Agent Workflows and the Developer Scratchpad constitute the operational framework for automated agents and human developers contributing to the Barekey project. These systems define the protocols for autonomous contributions, the use of visual verification tools, and the maintainance of a persistent "thinking" space to ensure continuity across sessions.

Sources: AGENTS.md, INDEX.md

Agent Operational Framework

AI agents in Barekey are expected to operate with high autonomy, handling the full lifecycle of a feature from branch creation to merging. This includes interacting with the backend (Convex), frontend (React), and the GitHub CLI.

Autonomous Git Lifecycle

Agents follow a standardized Git workflow to ensure progress is visible and code quality is maintained through automated reviews.

The flow prioritizes non-blocking progress; agents do not wait for human review on every push but instead check for Codex feedback intermittently.

Sources: AGENTS.md:128-144, INDEX.md:46-62

Visual Verification with agent-browser

For UI tasks, agents use agent-browser to perform visual regression testing and verify component behavior against a baseline.

Action	Command	Purpose
Baseline	agent-browser open / screenshot baseline.png	Set the starting visual state before changes.
Verification	agent-browser snapshot -i	Read the DOM structure to verify element IDs and accessibility.
Annotation	agent-browser screenshot --annotate	Visually confirm UI changes and interactive states.
Diffing	agent-browser diff screenshot --baseline	Detect unintended pixel changes.

Sources: AGENTS.md:92-111

Scratchpad & Communication Protocols

The INDEX.md file serves as a persistent, shared scratchpad. It is specifically designed to prevent context loss between sessions, which is critical for AI agents.

Inter-Agent Communication via Comments

Agents use JSDoc and inline comments as a primary means of passing intent to the next agent or session.

• JSDoc: Mandatory for all exported functions to allow cross-codebase readability without opening files.
• Encryption Context: Explicit comments are required for any logic touching the DEK (Data Encryption Key) or KEK (Key Encryption Key) lifecycles due to the high risk involved.
• Logic Justification: Decisions regarding non-obvious algorithms, such as ab_roll probability logic or specific Convex index ordering, must be documented.

Sources: INDEX.md:118-154, AGENTS.md:65-80

The Scratchpad (INDEX.md)

Unlike standard documentation, the scratchpad is a "live" area for drafting plans and flagging weird behaviors.

• Format: Entries are prefixed with YYYY-MM-DD.
• Flags: Urgent items use [URGENT], [REVISIT], or [WEIRD] tags.
• History: Old entries are archived at the bottom rather than deleted to preserve project history.

Sources: INDEX.md:1-35

Development Environment & Tooling

Agents interact with the core project stack using specific CLI tools to manage the backend and verify the environment.

Convex Backend Operations

Convex is the BaaS (Backend as a Service) used for the project. Agents must manage deployments and verify data integrity using the Convex CLI.

Core Project Standards

Agents must adhere to strict TypeScript and file naming rules to maintain codebase consistency:

• Strings: Use double quotes "" for all strings and JSX props.
• Enums: Use as const objects instead of TypeScript enum keywords.
• Naming: Filenames use kebab-case; Types and Components use PascalCase.
• Convex Indices: Index names must list all fields (e.g., by_orgId_and_name) and queries must follow the definition order.

Sources: AGENTS.md:148-175, pkg/convex/projects.ts:32-35, pkg/convex/project_variables.ts:143-145

Governance & Safety Limits

To protect critical infrastructure, specific limits are placed on autonomous merging.

Scenario	Autonomous Merge Allowed?
UI Changes / Bug Fixes	Yes (after fixing valid Codex issues)
Encryption / DEK Lifecycle	No (requires human review)
Dependency on Unbuilt Features	No (hold and leave note in INDEX.md)
Unresolved Codex Concerns	No (hold for human clarification)

Sources: INDEX.md:64-74, AGENTS.md:52-60

Summary

The AI Agent Workflow and Scratchpad system provides a rigorous yet flexible environment for autonomous development. By combining the agent-browser for visual audits, the Convex CLI for backend management, and the INDEX.md scratchpad for persistent context, the project enables agents to contribute safely to complex areas like secret management and encrypted variable storage.