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

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:

1. Install the package via Bun
2. Initialize beads (bd init) if needed
3. Synchronize bundled markdown agents into the global OpenCode directory:
   • ~/.config/opencode/agents/ (or $XDG_CONFIG_HOME/opencode/agents/)
   • existing files are updated when package content changes
4. Ensure AGENTS.md contains a REQUIRED SKILLS baseline section

The plugin does not copy agents into the current project's .opencode/agents/. If agents are not visible immediately in the current UI session, restart OpenCode once.

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:

1. Delegates requirement clarification to @grazynka
2. Grazynka creates a PRD with user stories
3. Januszek delegates implementation to @areczek
4. Areczek codes, tests, and commits
5. @anetka performs code review
6. If FAIL -> Areczek fixes. If PASS -> next story.
7. 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:

bd list --type epic --label kolchoz:session --label kolchoz:active --json
bd list --parent <epicId> --json

Reset (new task)

kolchoz_reset closes the active beads session while preserving accumulated knowledge in AGENTS.md.

File structure

After installation this appears in your project:

your-project/
├── .beads/                   ← beads data (tasks, epic, history)
└── AGENTS.md                 ← accumulated knowledge, COMMITTED

Global agent files are managed here:

~/.config/opencode/agents/

Tools (custom tools)

The plugin registers 8 tools:

Model configuration

You can override agent models in opencode.json:

{
  "agent": {
    "januszek": { "model": "<provider>/<model-name>" },
    "areczek": { "model": "<provider>/<model-name>" },
    "anetka": { "model": "<provider>/<model-name>" }
  }
}

Commit gate

Before Areczek can submit a story for review, kolchoz_submit_for_review validates Git:

• no uncommitted changes in the working tree (excluding .beads/**)
• latest commit message starts with feat(<storyId>):

If either check fails, submission is blocked until Areczek creates the correct commit. After finishing a full PRD/session, commit .beads updates to keep beads history in the repository.

Required skills baseline

During setup, the plugin ensures AGENTS.md contains baseline skills:

• vercel-labs/skills@find-skills
• github/awesome-copilot@git-commit

Grazynka also adds project-specific skill: ... entries to PRD constraints when needed.

Compound engineering

The system builds knowledge in AGENTS.md automatically:

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

Release automation

This repository includes GitHub Actions workflows for a release cycle:

1. Run Prepare Release Draft manually from GitHub Actions on main or master.
2. Choose RELEASE_TYPE: major, minor, or patch.
3. Workflow bumps package.json version, commits it, creates a tag, and opens a draft release.
4. Publish the draft release in GitHub Releases.
5. Publishing the release triggers npm publishing from the release tag.

Workflow files:

• .github/workflows/prepare-release.yml
• .github/workflows/publish-on-release.yml

Required npm setup:

• Configure npm Trusted Publisher for this GitHub repository and workflow file publish-on-release.yml.
• Trusted publishing uses GitHub OIDC, so NPM_TOKEN is not required for package publishing.

Important:

• Prepare Release Draft guarantees matching tag and package.json version.
• If branch protection blocks direct pushes by Actions, allow GITHUB_TOKEN pushes for this workflow.

License

MIT