ClawDev: Instructions file for Codex

AGENTS.md - ClawDev Project Guidelines

Project Overview

This project (clawdev) is a Python framework that combines OpenClaw ACP (Agent Client Protocol) with a multi-agent collaboration system for automated code generation. It provides:

• ACP client for communicating with OpenClaw agents
• ChatChain orchestration for managing multi-agent dialog workflows
• Phase-based development process (demand analysis, coding, review, testing, etc.)

The main entry point is src/main.py and the core packages are src/openclaw_acp/ and src/clawdev/.

Build, Lint, and Test Commands

Running Tests and Linting in Docker Container

The project runs in Docker. Code directory is mounted at /app/ClawDev in the container. Always use docker exec to run tools from the project's virtual environment to avoid corrupting the local venv.

# Run all tests in docker container
docker exec -w /app/ClawDev clawdev-openclaw-gateway-1 /app/ClawDev/.venv/bin/pytest tests/ -v

# Run a single test file
docker exec -w /app/ClawDev clawdev-openclaw-gateway-1 /app/ClawDev/.venv/bin/pytest tests/test_agent.py -v

# Run linting in docker container
docker exec -w /app/ClawDev clawdev-openclaw-gateway-1 /app/ClawDev/.venv/bin/ruff check src/ tests/

Code Style Guidelines

General Principles

• Follow Python's PEP 8 style guide
• Use type hints for all function parameters and return values
• Write concise, readable code
• Keep functions focused and single-purpose

Naming Conventions

• Classes: PascalCase (e.g., OpenClawAgent)
• Functions/variables: snake_case (e.g., gateway_url, async_step)
• Constants: UPPER_SNAKE_CASE (e.g., MAX_RETRIES)
• Private methods: prefix with underscore (e.g., _initialize)

Import Organization

Order imports in the following groups (separate each group with a blank line):

1. Standard library imports
2. Third-party imports
3. Local application imports (relative imports)

import asyncio
import json
import os
from queue import Queue, Empty
from typing import AsyncGenerator, Callable, Optional

from .utils import require_api_key