KARIMO

██╗  ██╗   █████╗   ██████╗   ██╗  ███╗   ███╗   ██████╗
██║ ██╔╝  ██╔══██╗  ██╔══██╗  ██║  ████╗ ████║  ██╔═══██╗
█████╔╝   ███████║  ██████╔╝  ██║  ██╔████╔██║  ██║   ██║
██╔═██╗   ██╔══██║  ██╔══██╗  ██║  ██║╚██╔╝██║  ██║   ██║
██║  ██╗  ██║  ██║  ██║  ██║  ██║  ██║ ╚═╝ ██║  ╚██████╔╝
╚═╝  ╚═╝  ╚═╝  ╚═╝  ╚═╝  ╚═╝  ╚═╝  ╚═╝     ╚═╝   ╚═════╝

What is KARIMO?

KARIMO is a framework and Claude Code plugin for PRD-driven autonomous development. Think of it as plan mode on steroids — leveraging native worktree isolation, sub-agents, and model routing.

Philosophy: You are the architect, agents are the builders, automated review is the optional inspector.

How It Works

┌──────────┐   ┌──────┐   ┌─────┐   ┌───────┐   ┌─────────────┐   ┌─────────────┐   ┌─────────┐   ┌───────┐
│ RESEARCH │──▸│ PLAN │──▸│ RUN │──▸│ TASKS │──▸│ AUTO-REVIEW │──▸│ ORCHESTRATE │──▸│ INSPECT │──▸│ MERGE │
└──────────┘   └──────┘   └─────┘   └───────┘   └─────────────┘   └─────────────┘   └─────────┘   └───────┘
      │            │                    │              │                 │              │
      └────────────┘                    └──────────────┘                 └──────────────┘
          Loop 1                             Loop 2                           Loop 3
          Human                              Claude                        Configurable

Strategic Looping

KARIMO has three strategic loops with increasing automation:

Loop 1 — Human-Driven: /karimo:research ↔ /karimo:plan — You iterate until PRD is ready

Loop 2 — Claude Built-In: /karimo:run generates briefs → auto-review validates → you approve

Loop 3 — Review Automation: Each wave creates PRs → inspect (your choice of tooling) → merge

After all waves complete → /karimo:merge creates final PR to main.

Orchestration

Tasks execute in waves with automatic parallelization:

Wave 1: [task-1a, task-1b] ─── parallel, PRs to main
              ↓ (wait for merge)
Wave 2: [task-2a, task-2b] ─── parallel, PRs to main
              ↓ (wait for merge)
Wave 3: [task-3a] ─────────── final task

Getting Started

Prerequisites

Install

curl -sL https://raw.githubusercontent.com/opensesh/KARIMO/main/.karimo/remote-install.sh | bash

Update

.karimo/update.sh

What's Preserved Across Updates

Full walkthrough: Getting Started

Core Commands

Full reference: COMMANDS.md

Adoption Phases

Details: PHASES.md

Context Architecture

KARIMO uses layered context management for efficient token usage:

Key files:

• .claude/agents.overview.md — All agents at a glance
• .claude/agents/karimo/*.md — Full agent definitions
• .claude/skills.overview.md — All skills with agent mapping
• .karimo/learnings/ — Categorized project learnings
• .karimo/findings/ — Cross-PRD pattern index

Details: Context Architecture

Compound Learning

KARIMO has a two-tier knowledge system that makes agents smarter over time:

Findings are task-to-task communication during a single PRD execution:

.karimo/prds/{slug}/
├── findings.md          # Aggregated discoveries from all tasks
└── briefs/
    └── {task}/findings.md  # Per-task discoveries (in worktree)

When a worker discovers something downstream tasks need (new API, gotcha, pattern), it writes to findings.md. The PM Agent propagates these to dependent task briefs. Findings are ephemeral — they exist for one PRD cycle.

Learnings are permanent project wisdom captured via /karimo:feedback:

.karimo/learnings/
├── index.md             # Navigation + stats
├── patterns/            # Positive practices to replicate
├── anti-patterns/       # Mistakes to avoid
├── project-notes/       # Project-specific context
└── execution-rules/     # Mandatory guidelines

Learnings are read by all agents before task execution. They prevent the same mistake from happening twice.

Promotion path: Findings that appear in 3+ PRDs can be promoted to learnings via /karimo:feedback --from-metrics.

Details: Compound Learning

Documentation

Configuration lives in .karimo/config.yaml — run /karimo:configure after install.

FAQ

Can I run without automated review?
Yes. Review is optional (Phase 2). PRD interviews, execution, and PRs all work out of the box.

Having issues?
Run /karimo:doctor to diagnose. Still stuck? [email protected]

Contributing

See CONTRIBUTING.md

License

Apache 2.0

Built with Claude Code by Open Session