ido4

    Advanced Topics

    This guide covers advanced ido4 features for power users, automation, and customization.

    The Hydro Foundation

    ido4 is built on the Hydro methodology (Hybrid Development Resource Orchestration), a framework designed specifically for AI-human collaborative development.

    Core Hydro Principles ido4 Implements:

    • Possibility-Driven Development - focus on what becomes possible, not what fits in time boxes
    • Flow over Ceremonies - work moves when dependencies clear, not when meetings occur
    • AI Task Classification - systematic approach to human-AI work allocation
    • Epic Integrity - business capabilities delivered as complete units
    • Dependency-Driven Planning - waves organize around what blocks what, not calendar boundaries

    ido4 makes these theoretical concepts executable through practical CLI commands and GitHub integration. For teams wanting to understand the complete methodology, visit hydro-dev.gitbook.io or contribute to the framework at github.com/b-coman/hydro-methodology.

    AI Tool Compatibility and Testing

    ido4 has been specifically built and tested with certain AI coding assistants to ensure optimal integration with the Hydro methodology workflow.

    Supported AI Tools

    Claude Code (Primary Support)

    • Most mature integration and behavior
    • Extensive testing across all ido4 features
    • Optimal task classification accuracy
    • Recommended for production use

    Gemini CLI (Secondary Support)

    • Supported with ongoing compatibility improvements
    • Regular updates to enhance integration
    • Some features may have different behavior patterns

    Development Environment

    Recommended Configuration:

    • IDE: Visual Studio Code (though not required)
    • Primary AI: Claude Code extension
    • Setup: VSCode + Claude Code + ido4 CLI

    Alternative Configurations:

    • Other IDEs are supported - ido4 is not limited to VSCode
    • Integration quality may vary depending on AI tool choice
    • All core ido4 functionality works across environments

    Ongoing Development

    ido4 is under constant development with regular improvements to:

    • AI tool compatibility and integration
    • Task classification accuracy across different AI assistants
    • Workflow optimization for various AI-human collaboration patterns
    • Support for additional AI coding tools

    Integration Quality Considerations

    When choosing your AI tool setup, consider:

    • Task Classification Accuracy: How well the AI understands ido4 task specifications
    • Context Package Processing: AI's ability to work with provided code context
    • Workflow Integration: Seamless transitions between ido4 states and AI execution
    • Quality Consistency: Reliable output that meets ido4 quality gates

    Security and Data Privacy

    Enterprise teams rightly have concerns about tools that interact with their codebase. ido4 is designed with security and transparency as core principles.

    Data Handling and Privacy

    No External Data Transmission

    • ido4 CLI operates entirely locally on your machine
    • No repository code, project data, or sensitive information is transmitted to external servers
    • All code and project information remains within your local environment and your chosen GitHub repositories
    • The tool only interacts with GitHub's public APIs for project management (issues, projects, etc.)

    Local Operation

    • All wave planning, dependency analysis, and task management happens locally
    • Repository content never leaves your control
    • AI integrations work through your locally installed AI tools (Claude Code, Gemini CLI)
    • No cloud dependencies for core functionality

    Transparency and Auditability

    Open Git Operations

    • All git commands executed by ido4 are fully transparent and auditable
    • Every repository interaction can be inspected and verified
    • No hidden or obfuscated operations on your codebase
    • Complete audit trail of all actions taken by the CLI

    GitHub API Usage

    • Only uses standard GitHub REST APIs for project management
    • All API calls are for managing issues, projects, and metadata
    • No access to repository content through GitHub APIs
    • Standard OAuth authentication - you control permissions

    Enterprise Security Considerations

    Compliance-Friendly

    • No data sovereignty concerns - all data stays local
    • Audit-friendly with complete transparency of operations
    • No external dependencies that could compromise security posture
    • Compatible with air-gapped or restricted network environments (local GitHub Enterprise)

    Access Control

    • Respects existing GitHub repository permissions
    • Uses your personal access tokens and authentication
    • No elevated permissions required beyond standard development access
    • All operations performed under your authenticated identity

    1. Configuration Deep Dive

    ido4 uses a local configuration file to manage its connection to your GitHub Project. This file is essential for the tool's operation.

    The .ido4 Directory

    When you run ido4 project:init, a new directory named .ido4 is created in the root of your project. This directory contains all the configuration that ido4 needs.

    • Location: your-project/.ido4/
    • Recommendation: You should commit this directory to your version control system (git). This allows every team member to use ido4 with the same consistent configuration.

    The project-info.json File

    This is the most important file in the .ido4 directory. It contains the unique IDs for your GitHub Project and its custom fields.

    Example project-info.json:

    {
  "project_id": "PVT_kwHOA...",
  "project_number": 123,
  "repository": "your-org/your-repo",
  "fields": {
    "status_field_id": "PVTSSF_lAHOA...",
    "wave_field_id": "PVTSSF_lAHOA...",
    "epic_field_id": "PVTSSF_lAHOA...",
    // ... and other field IDs
  },
  "status_options": {
    "Backlog": "f75ad...",
    "In Refinement": "b9c3b...",
    // ... and other status option IDs
  }
}

    How ido4 uses it:

    • The project_id tells ido4 which GitHub Project to interact with.
    • The field_ids allow ido4 to read and write to your custom fields like Wave and Epic.
    • The status_options map the human-readable status names (e.g., "In Progress") to the internal IDs used by the GitHub API.

    Editing this file: In general, you should not need to edit this file manually. ido4 commands will manage it for you. However, understanding its structure can be helpful for troubleshooting.

    2. Automation with ido4

    One of the most powerful features of ido4 is its ability to be used in scripts and automated workflows, thanks to the --format json global flag.

    When you use this flag, ido4 commands output structured JSON data instead of human-readable text. This allows you to build custom tools and CI/CD integrations on top of ido4.

    Example: A Script to Check for Blocked Tasks

    Imagine you want to create a daily report of all tasks that are currently blocked. You could write a simple shell script like this:

    #!/bin/bash

# Get the project status in JSON format
project_data=$(ido4 project:status --format json)

# Use the 'jq' tool to parse the JSON and find blocked tasks
blocked_tasks=$(echo "$project_data" | jq -r '[.tasks[] | select(.status == "Blocked")] | .[] | "- #\(.number): \(.title)" ')

if [ -n "$blocked_tasks" ]; then
  echo "🚨 The following tasks are currently blocked:"
  echo "$blocked_tasks"
else
  echo "✅ No tasks are currently blocked."
fi

    This script leverages ido4's JSON output to create a custom report, demonstrating how you can integrate the tool into your own automated processes.

    3. CI/CD Integration

    You can use ido4 within your GitHub Actions workflows to automate project management tasks based on development events.

    Example: Automatically Check Dependencies on a Pull Request

    This GitHub Actions workflow will automatically run ido4 task:check-dependencies on an issue when a pull request is opened for it.

    # .github/workflows/ido4-pr-check.yml

name: 'ido4 PR Dependency Check'

on:
  pull_request:
    types: [opened]

jobs:
  check_dependencies:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout code
        uses: actions/checkout@v3

      - name: Setup Node.js
        uses: actions/setup-node@v3
        with:
          node-version: '18'

      - name: Install ido4
        run: npm install -g ido4

      - name: Get Issue Number from PR Body
        id: get_issue
        run: |
          # This is a simplified example; a real script would be more robust
          issue_number=$(echo "${{ github.event.pull_request.body }}" | grep -oE '#([0-9]+)' | sed 's/#//')
          echo "::set-output name=issue_number::$issue_number"

      - name: Run ido4 Dependency Check
        if: steps.get_issue.outputs.issue_number
        run: |
          ido4 task:check-dependencies ${{ steps.get_issue.outputs.issue_number }}
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

    This example shows how you can start to build a powerful, automated project management system by integrating ido4 into your existing CI/CD pipelines.