opencode-kolchoz-loop

Multi-agent Ralph Loop plugin for OpenCode.

Four agents work in a Ralph Loop workflow and autonomously execute tasks from requirements analysis to code review.

Agents

Agent	Role	Mode	Color
Januszek 👔	Orchestrator - talks to the user, delegates work	primary	orange
Grazynka 📋	Requirements analyst - creates PRDs with user stories	subagent	purple
Areczek 🔧	Builder - implements code, tests, commits	subagent	cyan
Anetka 🔍	Reviewer - quality gate: tests, lint, typecheck, diff	subagent	pink

Installation

Add the package to opencode.json in your project:

{
  "$schema": "https://opencode.ai/config.json",
  "plugin": ["opencode-kolchoz-loop"]
}

On the next OpenCode start it will automatically:

Install the package via Bun
Copy agent definitions into .opencode/agents/
Create .opencode/state/ for runtime state files
Add .opencode/state/ to .gitignore

From a private npm registry (internal)

{
  "plugin": ["@your-company/opencode-kolchoz-loop"]
}

From a local folder (testing)

Copy the full src/ directory into .opencode/plugins/ in your project:

cp -r src/ /path/to/project/.opencode/plugins/kolchoz-loop/

Usage

Interactive mode

After OpenCode starts, Januszek is the default agent. Describe the task:

Implement an authentication system with OAuth2 and 2FA

Januszek then:

Delegates requirement clarification to @grazynka
Grazynka creates a PRD with user stories
Januszek delegates implementation to @areczek
Areczek codes, tests, and commits
@anetka performs code review
If FAIL -> Areczek fixes. If PASS -> next story.
After PRD completion -> Januszek reports back.

Manual agent calls

@grazynka Analyze requirements for the payments module
@areczek Fetch the next task and implement it
@anetka Review the latest changes

Check status

Januszek uses kolchoz_status, but you can also inspect state manually:

cat .opencode/state/prd.json | jq '.userStories[] | {id, title, status}'
tail -20 .opencode/state/progress.txt

Reset (new task)

kolchoz_reset clears loop state while preserving accumulated knowledge in AGENTS.md.

File structure

After installation this appears in your project:

your-project/
├── .opencode/
│   ├── agents/               ← copied automatically from the package
│   │   ├── januszek.md
│   │   ├── grazynka.md
│   │   ├── areczek.md
│   │   └── anetka.md
│   └── state/                ← gitignored, ephemeral
│       ├── prd.json
│       ├── progress.txt
│       └── loop-state.json
├── AGENTS.md                 ← accumulated knowledge, COMMITTED
└── .gitignore                ← auto-updated: .opencode/state/

Tools (custom tools)

The plugin registers 7 tools:

Tool	Used by	Description
`kolchoz_create_prd`	Grazynka	Creates PRD with user stories
`kolchoz_next_task`	Areczek	Fetches next task
`kolchoz_submit_for_review`	Areczek	Submits work for review
`kolchoz_review_verdict`	Anetka	Pass/fail verdict
`kolchoz_status`	Everyone	Loop status
`kolchoz_learn`	Everyone	Writes knowledge to AGENTS.md
`kolchoz_reset`	Januszek	Clears state, keeps knowledge

Model configuration

Agents use claude-sonnet-4 by default. Override in opencode.json:

{
  "agent": {
    "januszek": { "model": "anthropic/claude-opus-4-20250514" },
    "areczek": { "model": "openai/gpt-4.1" },
    "anetka": { "model": "google/gemini-2.5-pro" }
  }
}

Recommendation: Anetka and Areczek should use different models. Cross-model review reduces shared blind spots.

Compound engineering

The system builds knowledge in AGENTS.md automatically:

Areczek discovers a pattern -> kolchoz_learn("pattern", "...")
Anetka discovers a gotcha -> kolchoz_learn("gotcha", "...")
Future sessions read AGENTS.md -> better context -> better outcomes

License

MIT