Skip to content

Developer Documentation

Project: ADW (AI Developer Workflow) Version: 2.1.0 Last Updated: 2025-11-15

Welcome to the ADW developer documentation hub. This section contains comprehensive guides, architecture documentation, and standards for developers working with or extending the ADW system.

Quick Navigation

Core Guides

Essential guides for ADW development:

Architecture

Understanding ADW's design and structure:

Documentation Standards

Writing consistent, high-quality documentation:

Process & Conventions

Development workflows and standards:

Templates

Standardized templates for consistent documentation:

Getting Started

For New Developers

  1. Read the Code Style Guide - Understand coding standards
  2. Review the Testing Guide - Learn testing patterns and commands
  3. Explore the Architecture Outline - Understand system structure
  4. Study the Code Culture - Learn team values and practices

For Contributors

  1. Follow Commit Conventions - Write semantic commit messages
  2. Use PR Conventions - Create well-structured pull requests
  3. Apply Review Guide - Conduct thorough code reviews
  4. Maintain Documentation Standards - Keep docs up-to-date

For Architects

  1. Review Architecture Guide - Understand design patterns
  2. Study Decision Records - Learn from past decisions
  3. Follow Architecture Reference - Apply architectural conventions
  4. Create ADRs - Document significant architectural decisions

Development Quick Reference

Setup

# Create virtual environment
uv venv .venv

# Install in editable mode with dev dependencies
uv pip install -e ".[dev]"

# Activate environment
source .venv/bin/activate  # Linux/macOS

Testing

# Run all tests
python -m pytest

# Run specific test file
python -m pytest adw/tests/cli_test.py

# Run with coverage
python -m pytest --cov=adw --cov-report=term-missing

Test Framework: pytest Test Pattern: *_test.py Coverage Target: 50%+ Test Location: adw/tests/, adw/*/tests/

See Testing Guide for complete documentation.

Linting

# Run linter
ruff check adw

# Run linter with auto-fix
ruff check adw --fix

# Run formatter
ruff format adw

Linter: ruff Line Length: 100 characters Rules: E, F, W, I, N (errors, warnings, imports, naming)

See Linting Guide for complete documentation.

Common Development Tasks

Adding a New Workflow

  1. Create or copy a JSON definition in .opencode/workflow/<name>.json.
  2. Describe phases, steps, and conditions using the workflow JSON schema and workflow engine guide.
  3. Run adw workflow list (or adw workflow help <name>) to confirm the definition was auto-registered, then exercise it with adw workflow <name> <issue-number>.
  4. Add or update tests for the agents/workflow steps referenced by the new definition.
  5. Update documentation (README, docs/index.md, and relevant guides) so users know how to invoke the new workflow.

See the Architecture Outline and Architecture Guide for engine internals and extension patterns.

Adding a Slash Command

  1. Create markdown file in .opencode/command/command_name.md
  2. Update adw/core/models.py SlashCommand type
  3. Add to SLASH_COMMAND_MODEL_MAP for model selection
  4. Test command execution

Fixing a Bug

  1. Write failing test that reproduces the bug
  2. Identify affected module(s) from Architecture Outline
  3. Implement fix following Code Style Guide
  4. Verify test passes
  5. Run full test suite
  6. Update documentation if behavior changed

Refactoring Code

  1. Ensure existing tests pass
  2. Make incremental changes
  3. Run tests after each change
  4. Follow patterns from Architecture Guide
  5. Update architecture docs if structure changed

Documentation Types

Type Purpose Location Format
README Project overview Root, module roots Markdown
Architecture Docs System design docs/Agent/architecture/ Markdown
API Docs Module/function reference Generated from docstrings Google-style
Decision Records Design decisions docs/Agent/architecture/decisions/ ADR format
Guides Development guides docs/Agent/ Markdown
Examples Practical tutorials docs/Examples/ Markdown + Code
Theory Concepts and principles docs/Theory/ Markdown

Code Quality Standards

Naming Conventions

  • Functions/variables: snake_case
  • Classes: PascalCase
  • Constants: UPPER_SNAKE_CASE
  • Private: _leading_underscore

Documentation Requirements

  • Type Hints: Required for public APIs
  • Docstrings: Required for public modules, classes, functions
  • Imports: Organized (stdlib, third-party, local)

Linting Rules

  • E/F/W: PEP 8 errors, warnings, and style issues
  • I: Import sorting and organization
  • N: Naming conventions
  • Line Length: 100 characters maximum
  • Auto-fix: Enabled for most rules

Architecture Principles

ADW is built on four core architectural principles:

  1. Isolated Execution - Each workflow runs in an isolated git worktree
  2. State-Driven Architecture - Workflow state persists to JSON files
  3. Declarative Phase Orchestration - .opencode/workflow/*.json definitions describe each phase and are executed via adw workflow <name>
  4. AI-Augmented Automation - Claude Code agents handle complex tasks

See Architecture Guide for detailed explanations.

Contributing

Pull Request Process

  1. Create Feature Branch: git checkout -b feature-description
  2. Make Changes: Follow Code Style Guide
  3. Run Tests: Ensure all tests pass (python -m pytest)
  4. Run Linter: Ensure no linting errors (ruff check adw)
  5. Commit: Follow Commit Conventions
  6. Push: git push origin feature-description
  7. Create PR: Follow PR Conventions
  8. Code Review: Address review comments using Review Guide
  9. Merge: After approval and passing CI

Commit Message Format

<type>: <description>

<optional body>

<optional footer>

Types: feat, fix, docs, style, refactor, test, chore

See Commit Conventions for complete specification.

Additional Resources

External Documentation

Internal Documentation

Support

Last Updated: 2025-11-15 Maintainers: ADW Development Team