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:

1. Install the package via Bun
2. Register Kolchoz tools and agents
3. Ensure trekker-dashboard is available (npm install -g @obsfx/trekker-dashboard when missing)
4. Start trekker-dashboard on port 7312 by default
5. Inject bundled agent definitions into runtime config.agent
   • agents are available in the same OpenCode startup (no second launch required)
   • package updates apply automatically on next OpenCode startup
6. Disable default build and plan agents in runtime config
7. Ensure AGENTS.md contains a REQUIRED SKILLS baseline section

trekker quickstart and trekker init run lazily when the Kolchoz loop actually starts (for example on kolchoz_start_prd / kolchoz_add_story / kolchoz_next_task).

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 pauses for plan review (kolchoz_status) so you can inspect/edit tickets in Trekker
4. After your approval, Januszek calls kolchoz_approve_plan
5. Januszek delegates implementation to @areczek
6. Areczek codes, tests, and commits
7. @anetka performs code review
8. If FAIL -> Areczek fixes. If PASS -> next story.
9. After PRD completion -> Januszek reports back.

Manual agent calls

@grazynka Analyze requirements for the payments module
@grazynka Update TREK-12 acceptance criteria before approval
@januszek Approve the plan and start implementation
@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:

trekker quickstart
trekker epic list --status in_progress
trekker task list --epic <epicId>

Dashboard (ticket preview)

Kolchoz starts trekker-dashboard automatically on http://127.0.0.1:7312. Use it to review or tweak stories before Januszek calls kolchoz_approve_plan.

To override the default port:

export OPENCODE_KOLCHOZ_DASHBOARD_PORT=7400

Reset (new task)

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

File structure

After installation this appears in your project:

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

Scaffolding safety

When the repo starts empty, Kolchoz may create .trekker/ and AGENTS.md before app scaffolding.

• Do not delete .trekker/ or AGENTS.md to satisfy framework CLI "empty directory" checks.
• If a CLI (for example create-next-app .) requires an empty directory, scaffold in a temporary sibling directory and copy generated files into the current project.
• Kolchoz now blocks destructive shell commands targeting .trekker/ and AGENTS.md.

Tools (custom tools)

The plugin registers 10 tools:

| Tool | Used by | Description | |------|---------|-------------| | kolchoz_start_prd | Grazynka | Starts a PRD session | | kolchoz_add_story | Grazynka | Adds one user story to the session | | kolchoz_update_story | Grazynka | Updates an existing story during plan review | | kolchoz_approve_plan | Januszek | Approves PRD backlog and unlocks Areczek execution | | kolchoz_next_task | Areczek | Fetches next task; if a story is already active, returns that story instead of claiming another | | 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 | Closes active session, keeps knowledge |

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 .trekker/**)
• 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 .trekker updates to keep trekker 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