Data

Tools

Indexes

Applications

Experiments

Awesome

An open API service indexing awesome lists of open source software.

https://github.com/ido4-dev/ido4

Development Governance Platform — deterministic methodology enforcement for AI-augmented teams
https://github.com/ido4-dev/ido4

ai-agents audit-trail business-rules claude-code compliance developer-tools governance mcp mcp-server multi-agent typescript wave-methodology

Last synced: 3 months ago
JSON representation

Development Governance Platform — deterministic methodology enforcement for AI-augmented teams

Awesome Lists containing this project

README 

          


  
ido4


  
AI-Hybrid Software Development at Scale


  
The platform that gives AI agents shared understanding, institutional memory, and quality enforcement





  See It In Action ·

  Quick Start ·

  Features ·

  Documentation ·

  Architecture






  MCP Compatible

  58 MCP Tools

  1731 Tests

  MIT License




---



AI agents can write code. But can they understand the full project? Know what was built before them? Pick the highest-leverage task? Build on decisions from previous sessions? Coordinate with other agents without conflicts?



**ido4** is the platform that makes AI-hybrid software development actually work. It runs inside Claude Code (and any MCP-compatible AI environment), giving every AI session full project context — what to build, what's already built, who depends on your output — with deterministic governance ensuring quality at every step.



The system carries the knowledge, not the agent. Every session starts with accumulated project understanding. Every action is validated through **34 real validation steps** — not LLM instructions that can be hallucinated. Every outcome is recorded so the next session is smarter than the last.



```

> What should I work on?



get_next_task { agentId: "agent-alpha" }

  Recommended: #42 Auth token rotation (score: 72)

  cascade:15 | momentum:25 | capability:20 | freshness:12

  Unblocks 3 downstream tasks. Epic is 60% complete — finish it.



> Load the full context



get_task_execution_data { issueNumber: 42 }

  ✓ Task spec + acceptance criteria loaded

  ✓ Upstream: #38 built JWT refresh endpoint (RSA-256, 30min TTL)

  ✓ Upstream: #41 created user schema with bcrypt hashing

  ✓ Siblings: #39, #40 established error handling pattern

  ✓ Downstream: #45, #47, #51 waiting on this task

  Risk: critical path — 3 of 5 remaining epic tasks depend on #42



> Start the task



start_task { issueNumber: 42 }

  ✓ BRE Validation: 6/6 steps passed

  Task #42 → In Progress. Lock acquired.

```



The agent didn't start from scratch. It knew what to work on, why it matters, what was built upstream, and who depends on its output. That's ido4.



## The Problem



AI coding agents can execute. But AI-hybrid development at scale needs more than execution:



- **No shared understanding.** Every AI session starts from scratch. No knowledge of what was built yesterday, what decisions were made, what patterns were established. Context is lost between sessions.

- **No task intelligence.** Agents pick whatever task seems obvious, not the one that unblocks the most downstream work. No scoring, no cascade analysis, no epic momentum.

- **No institutional memory.** When Agent A builds an auth service and Agent B needs to consume it next week, there's no structured knowledge transfer. B searches the codebase blind.

- **No quality enforcement.** Dependencies get violated. Epics ship incomplete. Quality gates get skipped. Nobody can trace what happened when something breaks.

- **No coordination.** Multiple agents on the same codebase with no awareness of each other — duplicate work, conflicting changes, cascade failures.



Traditional project management tools (Linear, Jira, Notion) track work after the fact. They don't **empower agents** to build effectively. ido4 is the platform that makes AI-hybrid development work — from context delivery through quality enforcement.



## See It In Action



The sandbox creates a real GitHub project from a [demo codebase](https://github.com/ido4-dev/ido4-demo), embeds governance violations, and discovers them live — using the same tools that govern real projects:



```

> /ido4dev:onboard



Demo project cloned. Creating governed sandbox...

✓ Tasks ingested via pipeline, violations embedded, agents registered



══════════════════════════════════════════════

  LIVE GOVERNANCE ANALYSIS

══════════════════════════════════════════════



CASCADE BLOCKER: Delivery Engine Core blocking 11 downstream tasks

  Working in src/notifications/delivery-engine.ts.

  Channel providers, template renderer, and API endpoint all waiting.



FALSE STATUS: Delivery Status Tracking shows "In Review" — no PR

  Status updated during sync meeting. Implementation not started.



REVIEW BOTTLENECK: Retry Policy PR open 3 days, 0 reviews

  Changes in src/notifications/retry-policy.ts. Code ready, idle.



INTEGRITY VIOLATION: Idempotency Guard in wrong wave

  Part of Notification Core capability but assigned to wave-003

  instead of wave-002. Delivery pipeline can't ship atomically.



══════════════════════════════════════════════

  INTELLIGENT WORK DISTRIBUTION

══════════════════════════════════════════════



agent-alpha (notification core — locked on Delivery Engine):

  → Email Provider       score:47  cascade:15 epic:12 cap:10 fresh:10

  → Webhook Provider     score:35  cascade:8  epic:12 cap:10 fresh:5



agent-beta (channel providers — available):

  → Email Provider       score:44  cascade:15 epic:12 cap:7  fresh:10

  → SMS Provider         score:30  cascade:8  epic:12 cap:7  fresh:3



Every score is deterministic — computed from dependency graphs,

capability completion ratios, agent capabilities, and audit timestamps.

```



The sandbox works identically for all three methodologies — Hydro (waves/epics), Scrum (sprints), and Shape Up (cycles/bets). The governance adapts to your methodology; the engine stays the same. [Try the sandbox demo →](https://docs.ido4.dev/getting-started/sandbox/)



## Quick Start



### As a Claude Code Plugin (Recommended)



```bash

# Set your GitHub token

export GITHUB_TOKEN=$(gh auth token)



# Install from the marketplace (no clone, no build)

/plugin marketplace add ido4-dev/ido4-plugins

/plugin install ido4dev@ido4-plugins



# Try the interactive sandbox demo

> /ido4dev:onboard

```



### As a Standalone MCP Server



```bash

npm install @ido4/mcp

```



Add to your MCP client configuration:



```json

{

  "mcpServers": {

    "ido4": {

      "command": "npx",

      "args": ["@ido4/mcp"],

      "env": {

        "GITHUB_TOKEN": "your-token"

      }

    }

  }

}

```



### Initialize a Project



```bash

# Inside Claude Code with the plugin loaded:

> Initialize ido4 governance for my-org/my-project

# The AI calls init_project, creates the GitHub Project V2,

# sets up custom fields, and writes .ido4/ config

```



## Features



### Context Assembly & Task Intelligence



Every AI session starts with full project understanding — not a blank slate:



- **`get_task_execution_data`** — One call assembles: task spec, upstream dependency context (what was actually built, not just "done"), sibling patterns, downstream consumers, epic progress, and quantified risk flags.

- **`get_next_task`** — 4-dimension scoring recommends the highest-leverage task: cascade value (what unblocks the most), epic momentum (finish what's started), capability match, dependency freshness.

- **`get_standup_data`** — Full project briefing: blocked tasks, compliance score, recent audit events, agent status, analytics — everything a session needs to orient.

- **Structured context comments** — Agents write what they built; next agent reads accumulated knowledge. Institutional memory that compounds across sessions.



### The Read-Execute-Write Loop



This is how institutional memory grows even though individual agents are stateless:



```

Agent reads context    →  upstream #38 built /auth/refresh (RSA-256, 30min TTL)

                          upstream #41 created user schema (bcrypt, 3 tables)

                          sibling #39 established error handling pattern



Agent executes work    →  builds /auth/rotate with sliding window + circuit breaker



Agent writes context   →  "Created POST /auth/rotate. Used sliding window

                           (not fixed TTL) for active sessions. Circuit breaker

                           shared with refresh — single failure domain."



Next agent reads       →  gets ALL accumulated context automatically

```



Every completed task enriches the system. The 10th agent working on a project has access to everything the first 9 built, decided, and documented — without any of them being "specialized" or persistent.



### Deterministic Business Rule Engine



Every task transition runs through a composable validation pipeline — 34 built-in steps across 5 categories, configurable per methodology:



| Category | What It Validates |

|---|---|

| **Workflow** | Status transitions, state machine paths, required fields |

| **Dependencies** | Completion checks, circular detection, cascade analysis |

| **Governance** | Container assignment, integrity rules, singularity constraints |

| **Quality Gates** | PR reviews, test coverage, security scans, task locks |

| **Risk** | AI suitability assessment, risk level enforcement |



The BRE is **configurable** — methodology profiles define which steps run for which transitions:



```json

{

  "transitions": {

    "start": {

      "steps": ["StatusTransition", "Dependency", "ContainerAssignment", "ContainerIntegrity"]

    },

    "approve": {

      "steps": ["StatusTransition", "PRReview:minApprovals=2", "SecurityScan", "TestCoverage:threshold=80"]

    }

  }

}

```



### Multi-Agent Coordination



Built for teams deploying multiple AI agents on the same codebase:



- **Task locking** — Agents acquire exclusive locks. No duplicate effort.

- **Work distribution** — 4-dimension scoring (cascade value, epic momentum, capability match, dependency freshness) recommends the highest-leverage task for each agent.

- **Coordination state** — Every agent sees who's working on what, recent events, and handoff opportunities.

- **Complete-and-handoff** — Atomic operation: approve work, release lock, identify unblocked tasks, recommend next work.



### Audit Trail & Compliance



Every governance action creates an immutable audit entry:



- **Event-sourced** — Append-only JSONL with in-memory ring buffer for fast queries

- **Compliance scoring** — Deterministic 0-100 score across 5 weighted categories: BRE pass rate (40%), quality gates (20%), process adherence (20%), container integrity (10%), flow efficiency (10%)

- **Real analytics** — Cycle time, lead time, throughput, blocking time — computed from actual events, not estimates

- **Queryable** — Filter by time range, actor, transition type, issue number, session



### Decomposition Pipeline



The two-artifact pipeline bridges stakeholder understanding and implementation:



```

ido4shape (conversation) → strategic spec → ido4 MCP (codebase analysis) → technical spec → GitHub issues

      The WHAT                                    The HOW

```



- **ido4shape** captures multi-stakeholder requirements through conversation — produces a strategic spec with capabilities, success conditions, and functional dependencies

- **ido4 MCP** decomposes the strategic spec against the actual codebase — a code analysis agent explores the repo, then a technical spec writer produces implementation tasks with effort, risk, AI suitability, and code-level dependencies

- The **ingestion pipeline** creates GitHub issues: capabilities become epics/bets, tasks become sub-issues — every task traceable to a strategic requirement



### 21 Intelligence Skills



Skills are intelligent workflows that compose multiple tools into project intelligence. Core skills work across all methodologies; methodology-specific variants speak your methodology's language:



| Skill | What It Does |

|---|---|

| `/ido4dev:onboard` | Zero-friction onboarding — auto-clones demo, creates sandbox, guided governance discovery |

| `/ido4dev:guided-demo` | Four-act governance walkthrough — project, discovery, enforcement, pipeline |

| `/ido4dev:sandbox-explore` | Interactive exploration — 13 structured paths across governance capabilities |

| `/ido4dev:standup` | Morning briefing — risks, leverage points, highest-impact action |

| `/ido4dev:board` | Flow intelligence — blockers, cascade risks, false statuses, capability cohesion |

| `/ido4dev:compliance` | Three-part assessment: quantitative score + structural audit + synthesis |

| `/ido4dev:health` | 5-second governance verdict: RED / YELLOW / GREEN |

| `/ido4dev:plan-wave` | Principle-aware wave composition. Also: `/plan-sprint` (Scrum), `/plan-cycle` (Shape Up) |

| `/ido4dev:retro-wave` | Data-backed retrospective. Also: `/retro-sprint` (Scrum), `/retro-cycle` (Shape Up) |

| `/ido4dev:decompose` | Decompose a strategic spec into a technical spec via codebase analysis |

| `/ido4dev:sandbox` | Sandbox lifecycle — create, reset, destroy |

| `/ido4dev:pilot-test` | End-to-end verification of the entire governance stack |



### CI/CD Quality Gate



A 6-check merge readiness gate that catches what CI alone can't:



1. **Workflow Compliance** — Did the task follow the full governance workflow?

2. **PR Review** — Does the PR have the required number of approving reviews?

3. **Dependency Completion** — Are all upstream dependencies satisfied?

4. **Container Integrity** — Is the grouping container cohesive within its execution container?

5. **Security Gates** — Are there vulnerability alerts?

6. **Compliance Threshold** — Does the project meet its compliance score minimum?



Emergency overrides are available — but they're audited and impact the compliance score. Governance doesn't prevent action; it ensures accountability.



## Governance Principles



Each methodology defines its own principles — deterministic rules enforced by the BRE that cannot be bypassed:



| Methodology | Key Principles |

|---|---|

| **Hydro** | Epic Integrity (all tasks in an epic must be in the same wave), Active Wave Singularity, Dependency Coherence, Self-Contained Execution, Atomic Completion |

| **Scrum** | Sprint Singularity, Dependency Coherence, Atomic Sprint Completion. Epics span sprints (no epic-sprint integrity). Type-scoped pipelines enforce different quality gates per work item type. |

| **Shape Up** | Cycle Singularity, Bet-Cycle Integrity, Circuit Breaker (unfinished at cycle end = killed), Fixed Appetite (time fixed, scope variable) |



Principles aren't suggestions — they're compiled into the BRE pipeline. An agent can't start a task that violates dependency coherence. A wave can't close with incomplete tasks. A bet that exceeds its cycle gets killed. The profile defines it. The engine enforces it.



## Architecture



```

┌──────────────────────────────────────────────────────────────┐

│  Claude Code Plugin (ido4dev — separate repo)                 │

│  21 Skills · 4 Agents · 2 Governance Hooks                   │

├──────────────────────────────────────────────────────────────┤

│  MCP Server (@ido4/mcp)                                      │

│  58 Tools · 9 Resources · 8 Prompts · STDIO Transport        │

├──────────────────────────────────────────────────────────────┤

│  Core Domain Layer (@ido4/core)                               │

│                                                               │

│  ┌──────────┐ ┌──────────┐ ┌────────────┐ ┌──────────────┐  │

│  │ Tasks    │ │Containers│ │ Agents     │ │ Compliance   │  │

│  │ BRE (34  │ │Integrity │ │ Work       │ │ Analytics    │  │

│  │  steps)  │ │ Deps     │ │ Distrib.   │ │ Audit Trail  │  │

│  └──────────┘ └──────────┘ │ Merge Gate │ └──────────────┘  │

│                             └────────────┘                    │

│  ┌──────────────────────────────────────────────────────────┐│

│  │ Infrastructure: GraphQL (retry · pagination · rate       ││

│  │ limiting) · GitHub Repositories · Config · Sandbox       ││

│  └──────────────────────────────────────────────────────────┘│

├──────────────────────────────────────────────────────────────┤

│  GitHub Projects V2 · Issues · Pull Requests                  │

└──────────────────────────────────────────────────────────────┘

```



### Monorepo Structure



| Package | npm | Description |

|---|---|---|

| [`@ido4/core`](packages/core/) | `npm i @ido4/core` | Domain logic — BRE (34 steps), profile-driven services, repositories. Zero CLI dependencies. |

| [`@ido4/mcp`](packages/mcp/) | `npm i @ido4/mcp` | MCP server — STDIO transport, 58 tools (Hydro), 9 resources, 8 prompts. |

| [`ido4dev`](https://github.com/ido4-dev/ido4dev) | — | Claude Code plugin — 21 skills, 4 agents, governance hooks. Distributed via [marketplace](https://github.com/ido4-dev/ido4-plugins). |



### 58 MCP Tools (Hydro)



Tool counts vary by methodology — Hydro: 58, Scrum: 56, Shape Up: 54 — because container and transition tools are generated dynamically from the methodology profile.



Task Governance (18 tools)



`start_task` · `review_task` · `approve_task` · `block_task` · `unblock_task` · `return_task` · `refine_task` · `ready_task` · `get_task` · `get_task_field` · `list_tasks` · `create_task` · `validate_transition` · `validate_all_transitions` · `find_task_pr` · `get_pr_reviews` · `add_task_comment` · `get_sub_issues`



Wave & Epic Management (9 tools)



`list_waves` · `get_wave_status` · `create_wave` · `assign_task_to_wave` · `validate_wave_completion` · `search_epics` · `get_epic_tasks` · `get_epic_timeline` · `validate_epic_integrity`



Multi-Agent Coordination (7 tools)



`register_agent` · `list_agents` · `lock_task` · `release_task` · `get_next_task` · `complete_and_handoff` · `get_coordination_state`



Audit, Analytics & Compliance (5 tools)



`query_audit_trail` · `get_audit_summary` · `get_analytics` · `get_task_cycle_time` · `compute_compliance_score`



Quality Gate & Dependencies (3 tools)



`check_merge_readiness` · `analyze_dependencies` · `validate_dependencies`



Project & Sandbox (5 tools)



`init_project` · `get_project_status` · `create_sandbox` · `destroy_sandbox` · `reset_sandbox`



Composite Intelligence (4 tools)



`get_standup_data` · `get_board_data` · `get_compliance_data` · `get_health_data`



## For Enterprise



ido4 provides the infrastructure that enterprise AI-hybrid development requires:



**Context at scale.** Every AI session starts with full project understanding — accumulated knowledge from every prior session, dependency context, risk signals, and institutional memory. No agent starts from scratch.



**Compliance documentation.** Every decision is auditable. Every rule enforcement is traceable. The audit trail provides the evidence that enterprise clients demand — who did what, when, and whether the rules were followed.



**Multi-methodology support.** Three built-in profiles: Hydro (wave-based), Scrum (sprint-based), Shape Up (cycle-based). The engine is methodology-agnostic — profiles define states, transitions, containers, integrity rules, and pipelines. Adopt ido4 with your existing methodology while getting deterministic enforcement.



**Quality gates.** Configure minimum PR reviews, test coverage thresholds, and security scan requirements per transition. Gates are enforced deterministically — not as suggestions.



**Multi-agent coordination at scale.** Deploy multiple AI agents on the same codebase with confidence. Each agent has a unique identity, capability profile, and audit trail. Task intelligence recommends the highest-leverage work. Task locking prevents duplicate effort. Handoff chains keep work flowing continuously.



## The New Way of Working



ido4 enables a new operating model for software delivery — AI-hybrid development at enterprise scale:



**2 senior humans + AI agents + ido4 = the output of a 10-person team.**



| Role | Provides |

|---|---|

| **PM** | Product vision, stakeholder management, strategic decisions |

| **Tech Architect** | System design, code quality oversight, technical judgment |

| **AI Agents** | Execution capacity — coding, testing, documentation |

| **ido4** | **The platform** — context intelligence, institutional memory, task distribution, and deterministic quality enforcement |



This isn't a better project management tool. It's the infrastructure that makes AI-hybrid software development actually work — where AI agents understand the full project, build on each other's work, and deliver with the quality and coherence that enterprise clients demand.



## Contributing



We welcome contributions. See [CONTRIBUTING.md](CONTRIBUTING.md) for development setup, architecture guide, and testing conventions.



```bash

# Development

npm install

npm run build

npm run test          # 1,731 tests



# Run with plugin (local development)

claude --plugin-dir ../ido4dev

```



## License



[MIT](LICENSE)



---





  ido4 — The platform that makes AI-hybrid software development work. At scale. For real.