Relevant source files

The following files were used as context for generating this wiki page: - [AGENTS.md](https://github.com/recoupable/tasks/blob/main/AGENTS.md) - [CLAUDE.md](https://github.com/recoupable/tasks/blob/main/CLAUDE.md) - [src/tasks/codingAgentTask.ts](https://github.com/recoupable/tasks/blob/main/src/tasks/codingAgentTask.ts) - [src/sandboxes/pushAndCreatePRsViaAgent.ts](https://github.com/recoupable/tasks/blob/main/src/sandboxes/pushAndCreatePRsViaAgent.ts) - [src/sandboxes/git/syncMonorepoSubmodules.ts](https://github.com/recoupable/tasks/blob/main/src/sandboxes/git/syncMonorepoSubmodules.ts) - [src/sandboxes/runClaudeCodeAgent.ts](https://github.com/recoupable/tasks/blob/main/src/sandboxes/runClaudeCodeAgent.ts) - [src/tasks/updatePRTask.ts](https://github.com/recoupable/tasks/blob/main/src/tasks/updatePRTask.ts)

# Coding Agent Guidelines ## Introduction The Coding Agent system is designed to automate software development tasks within the Recoup monorepo using AI agents like Claude Code. These agents operate within isolated Vercel Sandbox environments to perform code modifications, synchronize submodules, and manage the Git workflow from branch creation to Pull Request (PR) submission. The guidelines ensure that agents follow a structured, test-driven development (TDD) process and adhere to strict architectural principles such as the Single Responsibility Principle (SRP) and DRY (Don't Repeat Yourself). This system integrates with Trigger.dev v4 for background task processing and relies on specialized sandbox utilities for secure execution and state persistence via snapshots. Sources: [AGENTS.md](), [src/tasks/codingAgentTask.ts:16-25]() ## Core Development Principles Coding agents must adhere to the following technical and architectural standards: * **Test-Driven Development (TDD)**: Agents must follow the Red-Green-Refactor cycle. For bug fixes, a failing test must be written based on exact error messages before applying the fix. * **Architectural Cleanliness**: Every exported function must follow SRP (one per file). Shared logic should be extracted into reusable utilities. * **Validation and Logging**: All task inputs must be validated using Zod schemas. Agents must use the `@trigger.dev/sdk/v3` logger for all execution details. * **Git Integrity**: Agents are prohibited from pushing directly to the `main` branch. All changes must be pushed to feature branches and submitted via PRs. Sources: [AGENTS.md](), [CLAUDE.md]() ## Agent Execution Workflow The lifecycle of a coding agent task involves setting up an isolated environment, preparing the source code, executing the AI agent, and processing the results. ### Orchestration Flow The following diagram illustrates the sequence of steps taken by the `codingAgentTask` to process a development prompt. ```mermaid flowchart TD Start[Start Task] --> Sandbox[Get/Create Sandbox] Sandbox --> Auth[Configure Git Auth] Auth --> Clone[Clone Monorepo] Clone --> Sync[Sync Submodules] Sync --> AgentRun[Run Claude Code Agent] AgentRun --> PR[Push & Create PRs] PR --> Snapshot[Take Sandbox Snapshot] Snapshot --> Notify[Notify Callback] Notify --> Stop[Stop Sandbox] ``` The workflow ensures that submodules are synced to the latest base branches (main or test) before the agent makes changes to prevent merge conflicts. Sources: [src/tasks/codingAgentTask.ts:31-77](), [src/sandboxes/git/syncMonorepoSubmodules.ts:21-41]() ### Functional Components | Component | Responsibility | Relevant Files | | :--- | :--- | :--- | | **Sandbox** | Provides an isolated Linux microVM for code execution. | `src/sandboxes/getOrCreateSandbox.ts` | | **Claude Agent** | Executes `claude -p` with dangerously-skip-permissions to apply changes. | `src/sandboxes/runClaudeCodeAgent.ts` | | **Git Sync** | Fetches and resets submodules to latest remote base branches. | `src/sandboxes/git/syncMonorepoSubmodules.ts` | | **PR Manager** | Instructs the agent to commit, push, and use `gh pr create`. | `src/sandboxes/pushAndCreatePRsViaAgent.ts` | ## Git Workflow Guidelines Agents are required to follow a specific branch and commit strategy. ### Submodule and Root Management Changes are handled in two steps: 1. **Mono Repo Root**: Changes to files like `progress.md` are committed and pushed directly to `main`. 2. **Submodules**: Changes require a new branch (prefixed with `agent/`), a commit with an automated message, and a PR created via the GitHub CLI (`gh`). ```bash # Branch Naming Convention agent/- # PR Creation Command Instruction gh pr create --repo --base --head --title "agent: " --body "Automated PR from coding agent." ``` Sources: [src/sandboxes/pushAndCreatePRsViaAgent.ts:47-81](), [src/tasks/codingAgentTask.ts:54-56]() ### PR Update Cycle When human feedback is provided, the `updatePRTask` resumes the environment from a previous snapshot to apply revisions. ```mermaid sequenceDiagram participant T as UpdatePR Task participant S as Vercel Sandbox participant A as Claude Agent T->>S: Create Sandbox from Snapshot T->>S: Configure Git Auth T->>A: Run Agent with Feedback Prompt A->>S: Apply Code Changes T->>A: Run Agent (git push) A->>T: Return Stdout/Stderr T->>S: Snapshot & Stop ``` Sources: [src/tasks/updatePRTask.ts:38-75]() ## Build and Environment Configuration ### Required Commands Agents use `pnpm` for dependency management and deployment. | Command | Purpose | | :--- | :--- | | `pnpm install` | Install project dependencies | | `pnpm dev` | Start Trigger.dev development mode | | `pnpm test` | Run vitest suite | | `pnpm run deploy:trigger-prod` | Deploy workers to production | Sources: [AGENTS.md](), [CLAUDE.md]() ### Environment Variables The agent environment requires specific tokens for operation: * `CLAUDE_CODE_OAUTH_TOKEN`: For agent authentication. * `GITHUB_TOKEN`: For repository access and PR creation. * `CODING_AGENT_CALLBACK_URL`: To notify the system of task completion. Sources: [src/sandboxes/runClaudeCodeAgent.ts:25-30](), [src/tasks/updatePRTask.ts:70-75]() ## Conclusion The Coding Agent Guidelines provide a robust framework for automated development. By leveraging isolated sandboxes, strict Git protocols, and TDD principles, the system ensures that AI-generated contributions remain high-quality and consistent with the project's monorepo architecture. The use of snapshots and background tasks allows for an iterative feedback loop between human developers and AI agents.