AGENTS.md

autoforge — Agent Instructions

This file provides instructions for AI coding agents (Codex CLI, Claude Code, etc.) working on this repository.

Overview

autoforge is an autonomous SDLC framework. You have access to harness tools via bash commands.

Available Tools

# Search codebase for patterns
PYTHONPATH=. python3 -m autoforge.harness.tools search "pattern" --dir autoforge/

# View file with line numbers
PYTHONPATH=. python3 -m autoforge.harness.tools view path/to/file.py --start 1 --end 50

# Edit file (with Python syntax validation)
PYTHONPATH=. python3 -m autoforge.harness.tools edit path/to/file.py --old "old code" --new "new code"

# Run shell command
PYTHONPATH=. python3 -m autoforge.harness.tools run-cmd "pytest tests/ -v"

# List directory
PYTHONPATH=. python3 -m autoforge.harness.tools list-dir autoforge/agents

# Extract search patterns from issue text
PYTHONPATH=. python3 -m autoforge.harness.tools localize --issue "bug description"

# Analyze a repository and propose goals
PYTHONPATH=. python3 -m autoforge.harness.init --dir /path/to/repo

Issue Resolution Workflow

1. Read the issue description
2. localize --issue "..." to extract search patterns
3. search "pattern" to find relevant files
4. view path/to/file.py to read the code
5. edit path/to/file.py --old "..." --new "..." to fix the bug
6. run-cmd "pytest tests/" to verify the fix

Development Rules

• Python 3.11+, Pydantic v2, httpx
• Immutable data (frozen dataclass / Pydantic model)
• Files under 400 lines
• Run tests: PYTHONPATH=. python3 -m pytest tests/ -v

Project Structure

autoforge/
├── agents/      # 7 SDLC agents + resolver stack
├── core/        # PipelineRunner, LLMClient, Config, Memory, Hooks
├── schemas/     # Pydantic schemas for structured artifact passing
├── tools/       # ACI toolkit, arXiv/GitHub API clients
├── harness/     # Agent harness mode (init, tools, solve)
└── bench/       # SWE-bench evaluation pipeline