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
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.
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.
The sandbox creates a real GitHub project from a demo codebase, 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 →
# 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:onboardnpm install @ido4/mcpAdd to your MCP client configuration:
{
"mcpServers": {
"ido4": {
"command": "npx",
"args": ["@ido4/mcp"],
"env": {
"GITHUB_TOKEN": "your-token"
}
}
}
}# 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/ configEvery 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.
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.
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:
{
"transitions": {
"start": {
"steps": ["StatusTransition", "Dependency", "ContainerAssignment", "ContainerIntegrity"]
},
"approve": {
"steps": ["StatusTransition", "PRReview:minApprovals=2", "SecurityScan", "TestCoverage:threshold=80"]
}
}
}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.
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
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
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 |
A 6-check merge readiness gate that catches what CI alone can't:
- Workflow Compliance — Did the task follow the full governance workflow?
- PR Review — Does the PR have the required number of approving reviews?
- Dependency Completion — Are all upstream dependencies satisfied?
- Container Integrity — Is the grouping container cohesive within its execution container?
- Security Gates — Are there vulnerability alerts?
- 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.
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.
┌──────────────────────────────────────────────────────────────┐
│ 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 │
└──────────────────────────────────────────────────────────────┘
| Package | npm | Description |
|---|---|---|
@ido4/core |
npm i @ido4/core |
Domain logic — BRE (34 steps), profile-driven services, repositories. Zero CLI dependencies. |
@ido4/mcp |
npm i @ido4/mcp |
MCP server — STDIO transport, 58 tools (Hydro), 9 resources, 8 prompts. |
ido4dev |
— | Claude Code plugin — 21 skills, 4 agents, governance hooks. Distributed via marketplace. |
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
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.
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.
We welcome contributions. See CONTRIBUTING.md for development setup, architecture guide, and testing conventions.
# Development
npm install
npm run build
npm run test # 1,759 tests
# Run with plugin (local development)
claude --plugin-dir ../ido4devido4 — The platform that makes AI-hybrid software development work. At scale. For real.