Developer Guide¶

Thank you for your interest in contributing to WireFlow!

Ways to Contribute¶

Report bugs: File issues with clear reproduction steps
Suggest features: Propose enhancements or new capabilities
Improve documentation: Fix typos, clarify explanations, add examples
Submit code: Fix bugs or implement features

Getting Started¶

Understanding the Codebase¶

Before contributing code, review the technical documentation:

Architecture: High-level system design and layer overview
Implementation: Module reference and technical gotchas
Configuration: Config cascade and settings
Content & I/O: Input processing, aggregation, output handling
Execution: Run/task/batch modes, streaming, tokens
API Layer: Anthropic API interaction

These provide comprehensive context for understanding how WireFlow is built and how components interact.

Development Setup¶

# Clone repository
git clone https://github.com/jdmonaco/wireflow.git
cd wireflow

# Install for local development
ln -s "$(pwd)/wireflow.sh" ~/bin/workflow

# Install test framework
git submodule update --init --recursive

Running Tests¶

# Using test runner (RECOMMENDED)
./tests/run-tests.sh unit              # Run all unit tests
./tests/run-tests.sh integration       # Run all integration tests
./tests/run-tests.sh all               # Run all tests (~137 tests)
./tests/run-tests.sh unit config.bats  # Run specific test file

# Direct bats invocation
bats tests/unit/config.bats            # Specific unit test
bats tests/integration/run.bats        # Specific integration test
bats -t tests/unit/utils.bats          # Verbose output

Project Structure¶

workflow/
├── wireflow.sh           # Main script
├── lib/                  # Library modules
│   ├── core.sh          # Core subcommands
│   ├── config.sh        # Configuration management
│   ├── help.sh          # Help system
│   ├── task.sh          # Task mode
│   ├── execute.sh       # Shared execution logic
│   ├── utils.sh         # Utility functions
│   └── api.sh           # API interaction
├── tests/               # Test suite
│   ├── unit/            # Function-level unit tests
│   ├── integration/     # End-to-end command tests
│   ├── test_helper/     # Test helpers (submodules)
│   └── run-tests.sh     # Test runner script
├── docs/                # Documentation (MkDocs)
└── mkdocs.yml           # Documentation configuration

Development Workflow¶

Commit Guidelines¶

Format:

<type>: <subject>

<body>

<footer>

Types:

feat: New feature
fix: Bug fix
docs: Documentation changes
test: Test additions or fixes
refactor: Code refactoring
style: Code style changes (formatting)
chore: Maintenance tasks

Examples:

feat: Add task mode for lightweight execution

Implements workflow task subcommand for one-off queries without
creating workflow directories. Supports inline and named tasks.

Closes #42

fix: Correct path resolution for nested projects

Config file paths are now correctly resolved relative to project
root when run from subdirectories.

Fixes #56

Code Style¶

Bash Style:

Use #!/usr/bin/env bash shebang
4-space indentation
Use [[ ]] for conditionals
Quote variables: "$var" not $var
Use local for function variables
Add comments for complex logic

Example:

# Good
process_file() {
    local file_path="$1"

    if [[ ! -f "$file_path" ]]; then
        echo "Error: File not found: $file_path" >&2
        return 1
    fi

    # Process file content
    cat "$file_path"
}