# Idumb Governance

> Complete iDumb governance protocols - hierarchical delegation, validation patterns, context anchoring, and expert-skeptic mode guidelines Use when this capability is needed.

- Skill: `tomevault-io/idumb-governance` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add tomevault-io/idumb-governance`
- Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/idumb-governance/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: tomevault-io (https://skillmd.com/u/tomevault-io)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/tomevault-io/idumb-governance

---


# iDumb Governance Skill

Complete protocols for operating within the iDumb hierarchical governance system.

## Governance Philosophy

### Expert-Skeptic Mode

**NEVER assume. ALWAYS verify.**

- Don't trust file contents are current - check timestamps
- Don't trust state is consistent - validate structure
- Don't trust context survives compaction - anchor critical decisions
- Don't trust previous agent conclusions - verify with evidence

### Context-First

Before ANY action:

1. Read `.idumb/brain/state.json`
2. Check current phase
3. Identify stale context (>48h old)
4. Anchor decisions that must survive compaction

### Evidence-Based Results

Every validation must return:

```yaml
result:
  status: pass | fail | warning
  evidence: [what was checked]
  proof: [how it was verified]
  timestamp: [when checked]
```

---

## Agent Categories

### META Agents

**Purpose:** Manage iDumb framework itself

**Scope:** Restricted to `.idumb/` and `.opencode/` directories

**Agents:**
- `@idumb-supreme-coordinator` - Entry-point coordinator (delegation only)
- `@idumb-high-governance` - Mid-level coordinator (delegation only)
- `@idumb-meta-builder` - ONLY META agent that can write/edit framework files
- `@idumb-meta-validator` - Validates framework state (read-only)

**Rules:**
- Coordinators: NEVER execute directly, ALWAYS delegate
- `idumb-meta-builder`: ONLY agent that can write framework files
- `idumb-meta-validator`: Read-only validation
- Scope restricted to framework directories

**Delegation pattern:**
```
@idumb-high-governance
Task: [what needs doing]
Context: [relevant state]
Requirements: [constraints]
Report: [expected format]
```

### PROJECT Agents

**Purpose:** Work on user's actual project code

**Scope:** User project directory (excluding `.idumb/`, `.opencode/`)

**Agents:**
- `@idumb-project-executor` - Executes project code tasks (can write user code)
- `@idumb-project-coordinator` - Coordinates project workflows
- `@idumb-project-validator` - Validates project code quality
- `@idumb-project-explorer` - Explores project codebase

**Capabilities:**
- Can read project files (grep, glob, read across entire codebase)
- `@idumb-project-executor` can write/edit user code
- Can further delegate via `task()` tool
- NO depth restrictions on delegation

**Key Principle:** The distinction is about **scope** (framework vs user code), not capability or depth. Any agent can delegate to any other agent.

**Return format (for validation work):**
```yaml
validation:
  check: [what was checked]
  status: pass | fail
  evidence: [proof]
  details: [explanation]
```

**Return format (for execution work):**
```yaml
execution:
  action: [what was done]
  files: [modified paths]
  status: success | partial | failed
  changes: [summary]
```

---

## Validation Protocols

### Structure Validation

Check `.idumb/` directory integrity:

```
.idumb/
├── brain/
│   └── state.json      # REQUIRED
├── governance/         # Optional
│   └── plugin.log      # Created by plugin
└── anchors/            # Optional
```

### Schema Validation

Required fields in `state.json`:

```json
{
  "version": "string",
  "initialized": "ISO date string",
  "framework": "idumb | bmad | planning | custom | none",
  "phase": "string",
  "lastValidation": "ISO date string | null",
  "validationCount": "number",
  "anchors": "array",
  "history": "array"
}
```

### Freshness Validation

- Files older than 48 hours are "stale"
- Stale context must be refreshed before use
- Anchors older than 48h should be reviewed

### Planning Alignment Validation

If planning framework detected:

1. Check `.planning/` exists
2. Check `ROADMAP.md` exists
3. Check `PROJECT.md` exists
4. Verify iDumb phase matches planning phase
5. Report any misalignment

---

## Context Anchoring

### When to Anchor

Create anchors for:

- **Critical decisions** that change project direction
- **Discovered constraints** that affect future work
- **Phase transitions** marking completion of major work
- **Error resolutions** documenting how issues were fixed

### Anchor Types

| Type | Use | Priority |
|------|-----|----------|
| `decision` | Strategic choices | critical/high |
| `context` | Background information | normal/high |
| `checkpoint` | Phase completion markers | high |

### Anchor Format

```yaml
anchor:
  type: decision | context | checkpoint
  content: "Brief description of what to remember"
  priority: critical | high | normal
```

### Anchor Limits

- Maximum 20 anchors stored
- Old normal-priority anchors pruned first
- Critical anchors always preserved

---

## Planning Integration

### Principle: Wrap, Don't Break

- Planning commands work normally
- iDumb intercepts via plugin hooks
- Validation happens post-execution
- State tracked separately in `.idumb/`

### Planning File Locations

| File | Purpose | iDumb Access |
|------|---------|--------------|
| `.planning/` | Planning artifacts | READ ONLY |
| `ROADMAP.md` | Project roadmap | READ ONLY |
| `PROJECT.md` | Project description | READ ONLY |
| `phases/` | Phase-specific plans | READ ONLY |

### Sync Protocol

After planning operations:

1. Read `PROJECT.md` for current phase
2. Update `.idumb/brain/state.json` phase
3. Log sync in governance history

---

## Compaction Survival

### What Gets Injected

During compaction, the plugin injects:

1. Current phase and framework
2. Critical and high-priority anchors
3. Recent action history (last 5)

### What Gets Lost

- Normal-priority anchors (unless recent)
- Full history beyond last 5 entries
- Detailed validation reports

### Pre-Compaction Checklist

Before context window fills:

1. Anchor all critical decisions
2. Summarize current state
3. Document next steps
4. Ensure state.json is current

---

## Error Handling

### Validation Failures

When validation fails:

1. Report specific failure reason
2. Provide evidence of failure
3. Suggest remediation
4. Do NOT auto-fix without delegation

### State Corruption

If `state.json` is corrupted:

1. Report corruption detected
2. Attempt to read what's salvageable
3. Recommend re-initialization
4. Preserve anchors if possible

### Missing Dependencies

If `.idumb/` doesn't exist:

1. Inform user to run `/idumb:init`
2. Do NOT auto-create structure
3. Operate in degraded mode if needed

---

## Command Reference

| Command | Purpose | Agent |
|---------|---------|-------|
| `/idumb:init` | Initialize governance | supreme-coordinator |
| `/idumb:status` | Show current state | supreme-coordinator |
| `/idumb:validate` | Run validation | supreme-coordinator |
| `/idumb:help` | Show help | supreme-coordinator |

---

## Tool Reference

| Tool | Purpose | Exports |
|------|---------|---------|
| `idumb-state` | State management | read, write, anchor, history, getAnchors |
| `idumb-validate` | Validation runner | structure, schema, freshness, planningAlignment, default (full) |
| `idumb-context` | Context detection | default (classify), summary, patterns |

---

## Best Practices

### For Coordinators (META agents)

1. Always check state before delegating
2. Provide full context in delegation
3. Synthesize results before reporting
4. Anchor significant outcomes
5. Stay within framework scope (.idumb/, .opencode/)

### For META Workers (meta-builder, meta-validator)

1. meta-builder: ONLY agent that writes framework files
2. meta-validator: Read-only validation of framework state
3. Never operate outside framework directories
4. Report all framework changes

### For PROJECT Agents (project-executor, project-validator, etc.)

1. Work within user project scope
2. project-executor: ONLY agent that can write user code
3. project-validator: Validates user code quality
4. Can read anywhere (grep, glob, read across codebase)
5. Include timestamps in reports

### For All Agents

1. Context first, action second
2. Evidence-based conclusions only
3. Anchor critical discoveries
4. Log actions taken

**Remember:** The distinction is META (framework) vs PROJECT (user code), not "levels" or "subagents."

---
> Converted and distributed by [TomeVault](https://tomevault.io/claim/shynlee04) — claim your Tome and manage your conversions.
<!-- tomevault:4.0:skill_md:2026-04-15 -->