opencode-kolchoz-loop 1.0.0

package/README.md

@@ -0,0 +1,149 @@
+# opencode-kolchoz-loop
+
+Multi-agent Ralph Loop plugin for [OpenCode](https://opencode.ai).
+
+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:
+
+```json
+{
+  "$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. Copy agent definitions into `.opencode/agents/`
+3. Create `.opencode/state/` for runtime state files
+4. Add `.opencode/state/` to `.gitignore`
+
+### From a private npm registry (internal)
+
+```json
+{
+  "plugin": ["@your-company/opencode-kolchoz-loop"]
+}
+```
+
+### From a local folder (testing)
+
+Copy the full `src/` directory into `.opencode/plugins/` in your project:
+
+```bash
+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:
+
+```bash
+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`:
+
+```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:
+
+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
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+import type { Plugin } from "@opencode-ai/plugin";
+export declare const KolchozLoop: Plugin;
+export default KolchozLoop;

package/dist/index.js

@@ -0,0 +1,409 @@
+import { tool } from "@opencode-ai/plugin/tool";
+import { readFile, writeFile, mkdir, readdir, copyFile, stat } from "fs/promises";
+import { join, dirname } from "path";
+import { fileURLToPath } from "url";
+// ── Filesystem helpers ──
+async function ensureDir(dir) {
+    await mkdir(dir, { recursive: true });
+}
+async function exists(path) {
+    try {
+        await stat(path);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+async function readJson(dir, filename, fallback) {
+    try {
+        const raw = await readFile(join(dir, filename), "utf-8");
+        return JSON.parse(raw);
+    }
+    catch {
+        return fallback;
+    }
+}
+async function writeJson(dir, filename, data) {
+    await ensureDir(dir);
+    await writeFile(join(dir, filename), JSON.stringify(data, null, 2), "utf-8");
+}
+async function appendProgress(dir, message) {
+    await ensureDir(dir);
+    const file = join(dir, "progress.txt");
+    const timestamp = new Date().toISOString();
+    const line = `[${timestamp}] ${message}\n`;
+    try {
+        const existing = await readFile(file, "utf-8");
+        await writeFile(file, existing + line, "utf-8");
+    }
+    catch {
+        await writeFile(file, line, "utf-8");
+    }
+}
+// ── Agent provisioning ──
+// Copies bundled .md agent files to .opencode/agents/
+// so OpenCode discovers them as real agents.
+async function provisionAgents(projectRoot, log) {
+    const targetDir = join(projectRoot, ".opencode", "agents");
+    await ensureDir(targetDir);
+    // Resolve the agents directory bundled inside this package
+    const packageAgentsDir = join(dirname(fileURLToPath(import.meta.url)), "agents");
+    let agentFiles;
+    try {
+        agentFiles = (await readdir(packageAgentsDir)).filter((f) => f.endsWith(".md"));
+    }
+    catch {
+        log("WARN: Could not read bundled agents directory. Agents must be provisioned manually.");
+        return;
+    }
+    for (const file of agentFiles) {
+        const target = join(targetDir, file);
+        if (await exists(target)) {
+            // Don't overwrite — user may have customized
+            continue;
+        }
+        await copyFile(join(packageAgentsDir, file), target);
+        log(`Provisioned agent: ${file} → .opencode/agents/${file}`);
+    }
+}
+// ── Gitignore helper ──
+// Ensures .opencode/state/ is in .gitignore
+async function ensureGitignore(projectRoot) {
+    const gitignorePath = join(projectRoot, ".gitignore");
+    const entry = ".opencode/state/";
+    let content = "";
+    try {
+        content = await readFile(gitignorePath, "utf-8");
+    }
+    catch {
+        // No .gitignore — create one
+    }
+    if (!content.includes(entry)) {
+        const addition = content.length > 0 && !content.endsWith("\n")
+            ? `\n\n# Kolkhoz Loop state (ephemeral)\n${entry}\n`
+            : `\n# Kolkhoz Loop state (ephemeral)\n${entry}\n`;
+        await writeFile(gitignorePath, content + addition, "utf-8");
+    }
+}
+// ── Main Plugin Export ──
+export const KolchozLoop = async ({ project, client, $, directory, worktree }) => {
+    const projectRoot = worktree || directory;
+    const stateDir = join(projectRoot, ".opencode", "state");
+    // ── Auto-provision on first run ──
+    await ensureDir(stateDir);
+    await provisionAgents(projectRoot, (msg) => {
+        client.app.log({
+            body: { service: "kolchoz-loop", level: "info", message: msg },
+        });
+    });
+    await ensureGitignore(projectRoot);
+    await client.app.log({
+        body: {
+            service: "kolchoz-loop",
+            level: "info",
+            message: `Kolkhoz Loop initialized. Project: ${projectRoot}, State: ${stateDir}`,
+        },
+    });
+    return {
+        // ══════════════════════════════════
+        // Custom Tools
+        // ══════════════════════════════════
+        tool: {
+            // ── Grazynka: create/update PRD ──
+            kolchoz_create_prd: tool({
+                description: "[Grazynka] Create or update a structured PRD with user stories " +
+                    "and acceptance criteria. Writes to .opencode/state/prd.json.",
+                args: {
+                    title: tool.schema.string(),
+                    context: tool.schema.string(),
+                    constraints: tool.schema.string(),
+                    stories: tool.schema.string(), // JSON array
+                },
+                async execute(args) {
+                    const stories = JSON.parse(args.stories).map((s, i) => ({
+                        id: s.id || `story-${i + 1}`,
+                        title: s.title || `Story ${i + 1}`,
+                        description: s.description || "",
+                        acceptanceCriteria: s.acceptanceCriteria || [],
+                        priority: s.priority || "medium",
+                        status: "pending",
+                        assignedTo: "areczek",
+                        iteration: 0,
+                    }));
+                    const prd = {
+                        title: args.title,
+                        createdBy: "grazynka",
+                        createdAt: new Date().toISOString(),
+                        userStories: stories,
+                        context: args.context,
+                        constraints: args.constraints.split(",").map((c) => c.trim()),
+                    };
+                    await writeJson(stateDir, "prd.json", prd);
+                    await appendProgress(stateDir, `[Grazynka] PRD created: "${args.title}" with ${stories.length} stories`);
+                    return `PRD created with ${stories.length} stories. Saved to .opencode/state/prd.json`;
+                },
+            }),
+            // ── Areczek: get next task ──
+            kolchoz_next_task: tool({
+                description: "[Areczek] Get the next pending or failed story from the PRD. " +
+                    "Returns story details or signals completion.",
+                args: {},
+                async execute() {
+                    const prd = await readJson(stateDir, "prd.json", null);
+                    if (!prd)
+                        return "ERROR: No PRD found. Ask Januszek to start the process.";
+                    const next = prd.userStories.find((s) => s.status === "pending" || s.status === "failed");
+                    if (!next) {
+                        const allDone = prd.userStories.every((s) => s.status === "done");
+                        if (allDone)
+                            return "<promise>COMPLETE</promise> — All stories are done!";
+                        return "No actionable stories. Some may be in review.";
+                    }
+                    next.status = "in_progress";
+                    next.iteration += 1;
+                    await writeJson(stateDir, "prd.json", prd);
+                    const state = await readJson(stateDir, "loop-state.json", {
+                        currentIteration: 0,
+                        maxIterations: 10,
+                        currentStoryId: null,
+                        phase: "idle",
+                        startedAt: new Date().toISOString(),
+                        history: [],
+                    });
+                    state.phase = "building";
+                    state.currentStoryId = next.id;
+                    state.currentIteration += 1;
+                    await writeJson(stateDir, "loop-state.json", state);
+                    await appendProgress(stateDir, `[Areczek] Starting: ${next.id} "${next.title}" (iteration ${next.iteration})`);
+                    return JSON.stringify({
+                        storyId: next.id,
+                        title: next.title,
+                        description: next.description,
+                        acceptanceCriteria: next.acceptanceCriteria,
+                        priority: next.priority,
+                        iteration: next.iteration,
+                        feedback: next.feedback || null,
+                    }, null, 2);
+                },
+            }),
+            // ── Areczek: submit for review ──
+            kolchoz_submit_for_review: tool({
+                description: "[Areczek] Submit current story for review by Anetka.",
+                args: {
+                    storyId: tool.schema.string(),
+                    summary: tool.schema.string(),
+                    filesChanged: tool.schema.string(),
+                },
+                async execute(args) {
+                    const prd = await readJson(stateDir, "prd.json", null);
+                    if (!prd)
+                        return "ERROR: No PRD found.";
+                    const story = prd.userStories.find((s) => s.id === args.storyId);
+                    if (!story)
+                        return `ERROR: Story ${args.storyId} not found.`;
+                    story.status = "review";
+                    await writeJson(stateDir, "prd.json", prd);
+                    const state = await readJson(stateDir, "loop-state.json", {
+                        currentIteration: 0, maxIterations: 10, currentStoryId: null,
+                        phase: "idle", startedAt: new Date().toISOString(), history: [],
+                    });
+                    state.phase = "reviewing";
+                    await writeJson(stateDir, "loop-state.json", state);
+                    await appendProgress(stateDir, `[Areczek → Anetka] Story ${args.storyId} submitted. Files: ${args.filesChanged}`);
+                    return `Story ${args.storyId} submitted for review. @anetka will verify.`;
+                },
+            }),
+            // ── Anetka: review verdict ──
+            kolchoz_review_verdict: tool({
+                description: "[Anetka] Submit review verdict. Pass = done. Fail = back to Areczek.",
+                args: {
+                    storyId: tool.schema.string(),
+                    verdict: tool.schema.enum(["pass", "fail"]),
+                    feedback: tool.schema.string(),
+                    testsRun: tool.schema.string(),
+                    issuesFound: tool.schema.string(),
+                },
+                async execute(args) {
+                    const prd = await readJson(stateDir, "prd.json", null);
+                    if (!prd)
+                        return "ERROR: No PRD found.";
+                    const story = prd.userStories.find((s) => s.id === args.storyId);
+                    if (!story)
+                        return `ERROR: Story ${args.storyId} not found.`;
+                    const state = await readJson(stateDir, "loop-state.json", {
+                        currentIteration: 0, maxIterations: 10, currentStoryId: null,
+                        phase: "idle", startedAt: new Date().toISOString(), history: [],
+                    });
+                    if (args.verdict === "pass") {
+                        story.status = "done";
+                        story.feedback = undefined;
+                        state.phase = "idle";
+                        await appendProgress(stateDir, `[Anetka ✅] Story ${args.storyId} PASSED. ${args.feedback}`);
+                    }
+                    else {
+                        story.status = "failed";
+                        story.feedback = args.feedback;
+                        state.phase = "building";
+                        await appendProgress(stateDir, `[Anetka ❌] Story ${args.storyId} FAILED. ${args.feedback}`);
+                    }
+                    state.history.push({
+                        iteration: state.currentIteration,
+                        storyId: args.storyId,
+                        phase: "review",
+                        result: args.verdict,
+                        timestamp: new Date().toISOString(),
+                        summary: `${args.verdict.toUpperCase()}: ${args.feedback}`,
+                    });
+                    await writeJson(stateDir, "prd.json", prd);
+                    await writeJson(stateDir, "loop-state.json", state);
+                    const allDone = prd.userStories.every((s) => s.status === "done");
+                    if (allDone)
+                        return "<promise>COMPLETE</promise> — All stories verified!";
+                    if (args.verdict === "fail") {
+                        if (story.iteration >= state.maxIterations) {
+                            return `BLOCKED: Story ${args.storyId} failed ${story.iteration} times. Escalating to Januszek.`;
+                        }
+                        return `Story ${args.storyId} needs rework. Feedback sent to Areczek.`;
+                    }
+                    return `Story ${args.storyId} done. Next task available.`;
+                },
+            }),
+            // ── Status ──
+            kolchoz_status: tool({
+                description: "Get Kolkhoz Loop status — PRD progress, phase, iteration count.",
+                args: {},
+                async execute() {
+                    const prd = await readJson(stateDir, "prd.json", null);
+                    const state = await readJson(stateDir, "loop-state.json", null);
+                    if (!prd)
+                        return "No active PRD. Describe your requirements to Januszek to start.";
+                    const byStatus = (s) => prd.userStories.filter((st) => st.status === s).length;
+                    return JSON.stringify({
+                        prdTitle: prd.title,
+                        totalStories: prd.userStories.length,
+                        done: byStatus("done"),
+                        pending: byStatus("pending"),
+                        inProgress: byStatus("in_progress"),
+                        inReview: byStatus("review"),
+                        failed: byStatus("failed"),
+                        currentPhase: state?.phase || "idle",
+                        currentIteration: state?.currentIteration || 0,
+                        currentStory: state?.currentStoryId || null,
+                    }, null, 2);
+                },
+            }),
+            // ── Learning (AGENTS.md in project root) ──
+            kolchoz_learn: tool({
+                description: "Append a learning/pattern/gotcha to AGENTS.md (project root). " +
+                    "Persists knowledge across Ralph Loop iterations. Committed to git.",
+                args: {
+                    category: tool.schema.enum(["pattern", "gotcha", "convention", "dependency"]),
+                    learning: tool.schema.string(),
+                    discoveredBy: tool.schema.enum(["januszek", "grazynka", "areczek", "anetka"]),
+                },
+                async execute(args) {
+                    const agentsMd = join(projectRoot, "AGENTS.md");
+                    let content;
+                    try {
+                        content = await readFile(agentsMd, "utf-8");
+                    }
+                    catch {
+                        content = "# Project Knowledge Base\n\nAuto-generated by Kolkhoz Loop.\n";
+                    }
+                    const header = `## ${args.category.toUpperCase()}`;
+                    if (content.includes(header)) {
+                        content = content.replace(new RegExp(`(${header}[^#]*)`), `$1- ${args.learning} _(${args.discoveredBy})_\n`);
+                    }
+                    else {
+                        content += `\n${header}\n- ${args.learning} _(${args.discoveredBy})_\n`;
+                    }
+                    await writeFile(agentsMd, content, "utf-8");
+                    await appendProgress(stateDir, `[${args.discoveredBy}] Learning: [${args.category}] ${args.learning}`);
+                    return `Recorded in AGENTS.md: [${args.category}] ${args.learning}`;
+                },
+            }),
+            // ── Reset (clean state for new task) ──
+            kolchoz_reset: tool({
+                description: "Reset Kolkhoz Loop state. Clears PRD, progress and loop state. " +
+                    "AGENTS.md (learnings) are preserved. Use between separate tasks.",
+                args: {
+                    confirm: tool.schema.enum(["yes"]),
+                },
+                async execute(args) {
+                    const files = ["prd.json", "loop-state.json", "progress.txt"];
+                    for (const f of files) {
+                        try {
+                            const { unlink } = await import("fs/promises");
+                            await unlink(join(stateDir, f));
+                        }
+                        catch { /* ignore */ }
+                    }
+                    return "Kolkhoz Loop state reset. AGENTS.md preserved. Ready for a new task.";
+                },
+            }),
+        },
+        // ══════════════════════════════════
+        // Event hooks
+        // ══════════════════════════════════
+        event: async ({ event }) => {
+            if (event.type === "session.idle") {
+                const state = await readJson(stateDir, "loop-state.json", null);
+                if (state?.phase === "building" || state?.phase === "reviewing") {
+                    await client.app.log({
+                        body: {
+                            service: "kolchoz-loop",
+                            level: "warn",
+                            message: `Session idle during active phase: ${state.phase}`,
+                        },
+                    });
+                }
+            }
+        },
+        // ══════════════════════════════════
+        // Tool execution hooks
+        // ══════════════════════════════════
+        "tool.execute.before": async (input, output) => {
+            if (input.tool === "write" || input.tool === "edit") {
+                const state = await readJson(stateDir, "loop-state.json", null);
+                if (state?.phase === "building") {
+                    await client.app.log({
+                        body: {
+                            service: "kolchoz-loop",
+                            level: "debug",
+                            message: `[Areczek] File modification: ${JSON.stringify(output.args)}`,
+                        },
+                    });
+                }
+            }
+        },
+        "tool.execute.after": async (input) => {
+            if (input.tool === "bash") {
+                const state = await readJson(stateDir, "loop-state.json", null);
+                if (state?.phase === "reviewing") {
+                    await appendProgress(stateDir, `[Anetka] Verification command executed`);
+                }
+            }
+        },
+        // ══════════════════════════════════
+        // Compaction hook
+        // ══════════════════════════════════
+        "experimental.session.compacting": async (_input, output) => {
+            const prd = await readJson(stateDir, "prd.json", null);
+            const state = await readJson(stateDir, "loop-state.json", null);
+            if (prd || state) {
+                const done = prd?.userStories.filter((s) => s.status === "done").length ?? 0;
+                const total = prd?.userStories.length ?? 0;
+                const active = prd?.userStories
+                    .filter((s) => s.status !== "done")
+                    .map((s) => `${s.id}: ${s.title} [${s.status}]`)
+                    .join(", ") || "none";
+                output.context.push(`## Kolkhoz Loop State\n` +
+                    `Phase: ${state?.phase ?? "idle"}, Iteration: ${state?.currentIteration ?? 0}\n` +
+                    `PRD: "${prd?.title ?? "none"}" — ${done}/${total} stories done.\n` +
+                    `Active: ${active}`);
+            }
+        },
+    };
+};
+export default KolchozLoop;

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "opencode-kolchoz-loop",
+  "version": "1.0.0",
+  "description": "Multi-agent Ralph Loop plugin for OpenCode - Januszek, Grazynka, Areczek, Anetka",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "opencode",
+    "opencode-plugin",
+    "multi-agent",
+    "ralph-loop"
+  ],
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@opencode-ai/plugin": "latest"
+  },
+  "devDependencies": {
+    "@types/node": "latest",
+    "typescript": "latest"
+  },
+  "files": [
+    "dist/**/*",
+    "src/agents/**/*.md",
+    "README.md"
+  ]
+}

package/src/agents/anetka.md

@@ -0,0 +1,89 @@
+---
+description: "Code reviewer and quality gate. Reviews Areczek's work: tests, linting, typecheck, and diff review. Decides pass/fail."
+mode: subagent
+model: anthropic/claude-sonnet-4-20250514
+temperature: 0.1
+color: "#f43f5e"
+tools:
+  write: false
+  edit: false
+  bash: true
+  read: true
+  glob: true
+  grep: true
+---
+
+# Anetka - Reviewer and Quality Gate
+
+You are Anetka, the code reviewer in the Kolkhoz Loop system. Your role is the quality gate - nothing passes without your approval.
+
+## Your role
+
+After Areczek submits a story for review, you:
+
+1. **Verify** - run tests, lint, and typecheck
+2. **Inspect** - review diffs (`git diff`, `git log`)
+3. **Evaluate** - issue a PASS or FAIL verdict
+4. **Comment** - if FAIL, provide concrete feedback on what to fix
+
+## Review checklist
+
+For every story, check:
+
+### Tests (blocking)
+```bash
+# Run tests
+npm test / bun test / pytest / go test ./...
+```
+If tests fail -> FAIL with a precise description of what failed.
+
+### Type check (blocking)
+```bash
+# TypeScript
+tsc --noEmit
+# Python
+mypy .
+```
+If there are type errors -> FAIL.
+
+### Linting (blocking)
+```bash
+# JS/TS
+npm run lint
+# Python
+ruff check .
+```
+If linting fails -> FAIL.
+
+### Diff review (advisory)
+```bash
+git diff HEAD~1
+git log --oneline -5
+```
+Check:
+- Are the changes aligned with the user story?
+- Were files outside scope modified?
+- Is the commit message meaningful?
+- Are there hardcoded secrets, contextless TODOs, or debug prints?
+
+### Acceptance criteria (blocking)
+- Read criteria from PRD (`.opencode/state/prd.json`)
+- Verify each criterion by running commands when needed
+- If a criterion requires a browser and cannot be verified, note it and continue
+
+## Verdict
+
+Use `kolchoz_review_verdict` with:
+- **verdict**: "pass" or "fail"
+- **feedback**: what is good, what is wrong, what to fix (specific)
+- **testsRun**: which test commands you executed
+- **issuesFound**: list of found issues (empty if pass)
+
+## Rules
+
+- Be strict but fair - do not approve low-quality work
+- Never edit code directly - only report findings
+- Feedback must be detailed enough for Areczek to fix without guessing
+- If you discover a new pattern or gotcha, record it via `kolchoz_learn`
+- Check `.opencode/state/progress.txt` to understand prior iterations
+- Do not fail for pure cosmetics - focus on correctness, security, and tests

package/src/agents/areczek.md

@@ -0,0 +1,78 @@
+---
+description: "Lead implementer. Writes code, runs tests, commits changes. Has full access to tools, browser MCP, and Git. Executes PRD user stories."
+mode: subagent
+model: anthropic/claude-sonnet-4-20250514
+temperature: 0.1
+color: "#22d3ee"
+steps: 50
+tools:
+  write: true
+  edit: true
+  bash: true
+  read: true
+  glob: true
+  grep: true
+  todo: true
+---
+
+# Areczek - Lead Implementer
+
+You are Areczek, the lead implementer in the Kolkhoz Loop system.
+
+## Your role
+
+You execute user stories from the PRD. You receive concrete, clarified tasks from Grazynka (via Januszek) and implement them end-to-end.
+
+## Workflow
+
+1. Use `kolchoz_next_task` to fetch the next task
+2. Read the description, acceptance criteria, and any feedback from previous iterations
+3. Read AGENTS.md (project root) and `.opencode/state/progress.txt` for context
+4. Implement step by step
+5. After implementation, run tests, lint, and typecheck
+6. If checks pass, create a meaningful git commit
+7. Use `kolchoz_submit_for_review` to submit work to Anetka
+
+## Tools and skills
+
+Use these capabilities consistently:
+
+### Git
+- Commit per meaningful unit of work (not every line)
+- Commit format: `feat(story-id): short description`
+- Always inspect `git diff` before committing
+- If something goes wrong: `git stash` or `git reset`
+
+### Tests
+- Run existing tests after changes: `npm test` / `bun test` / equivalent
+- If the story requires new tests, add them
+- Tests must pass before submitting
+
+### Linting and types
+- `npm run lint` / `bun run lint`
+- `npm run typecheck` / `tsc --noEmit`
+- Zero errors before submit
+
+### Browser (MCP)
+- If the story is UI-related, use browser MCP for visual verification
+- Capture screenshots when possible
+
+### LSP
+- Use LSP diagnostics to catch issues during implementation
+
+## Rules
+
+- If there is feedback from Anetka, read it first and address it
+- Do not modify files unrelated to the current story
+- Each commit should be atomic and reversible
+- If you discover a problem, record it with `kolchoz_learn` category "gotcha"
+- If you discover a pattern, record it with `kolchoz_learn` category "pattern"
+- Do not ask the user questions - act autonomously based on the PRD
+- If information is missing, read code, tests, and docs - do not pause execution
+
+## Submit format
+
+When submitting via `kolchoz_submit_for_review`, provide:
+- storyId - ID from the PRD
+- summary - what you changed (2-3 sentences)
+- filesChanged - list of changed files

package/src/agents/grazynka.md

@@ -0,0 +1,50 @@
+---
+description: "Requirements analyst. Clarifies requests from Januszek, analyzes the codebase, and creates a structured PRD with user stories and acceptance criteria."
+mode: subagent
+model: anthropic/claude-sonnet-4-20250514
+temperature: 0.2
+color: "#a855f7"
+tools:
+  write: false
+  edit: false
+  bash: false
+  read: true
+  glob: true
+  grep: true
+---
+
+# Grazynka - Requirements Analyst
+
+You are Grazynka, the requirements analyst in the Kolkhoz Loop system.
+
+## Your role
+
+Januszek delegates ambiguous or high-level requests to you. Your job is to:
+
+1. **Analyze context** - read AGENTS.md, inspect project structure, review existing code
+2. **Clarify scope** - break general requirements into concrete, implementable user stories
+3. **Define acceptance criteria** - for each story, define measurable completion conditions
+4. **Create PRD** - use `kolchoz_create_prd` to persist the output
+
+## User story format
+
+Each story should include:
+- **id**: unique, e.g. "story-1", "story-2"
+- **title**: short summary (max 10 words)
+- **description**: complete description of what must be implemented
+- **acceptanceCriteria**: list of concrete, verifiable conditions
+- **priority**: "critical" | "high" | "medium" | "low"
+
+## Rules
+
+- Each story should be small enough for Areczek to implement in one iteration
+- Acceptance criteria must be machine-verifiable (tests, typecheck, lint)
+- Account for dependencies between stories and order them logically
+- If a story requires UI changes, include the criterion "Verify in browser"
+- Read `.opencode/state/progress.txt` to avoid duplicating previous work
+- Use `kolchoz_learn` when you discover important project knowledge
+
+## Communication
+
+Be precise and methodical. Your PRDs should be concise but complete.
+Do not implement code - only analyze and specify.

package/src/agents/januszek.md

@@ -0,0 +1,53 @@
+---
+description: "Main Kolkhoz Loop orchestrator. Talks with the user, translates requirements into tasks, delegates to Grazynka and Areczek, and controls Ralph Loop flow."
+mode: primary
+model: anthropic/claude-sonnet-4-20250514
+temperature: 0.3
+color: "#ff6b35"
+tools:
+  write: false
+  edit: false
+  bash: true
+  read: true
+  glob: true
+  todo: true
+---
+
+# Januszek - Lead Orchestrator
+
+You are Januszek, the main orchestrator in the Kolkhoz Loop multi-agent system.
+
+## Your role
+
+You are responsible for:
+1. **User interaction** - understand what the user needs and ask clarifying questions
+2. **Delegation** - pass unclear requirements to `@grazynka` for clarification
+3. **Flow control** - monitor progress with `kolchoz_status`
+4. **Iteration closure** - decide when work is complete
+
+## Workflow (Ralph Loop)
+
+When a user submits a task:
+
+1. Analyze the request - is it specific enough?
+2. If not, delegate to `@grazynka` with what needs clarification
+3. Once Grazynka returns a PRD (`.opencode/state/prd.json`), instruct `@areczek` to fetch a task (`kolchoz_next_task`)
+4. After Areczek implements, `@anetka` performs review
+5. If Anetka gives PASS -> next story. If FAIL -> back to Areczek.
+6. When all stories are marked "done", report results to the user
+
+## Rules
+
+- Never implement code yourself - that is Areczek's job
+- Never create PRD yourself - that is Grazynka's job
+- Never review code yourself - that is Anetka's job
+- Always check `kolchoz_status` before making decisions
+- Loop state lives in `.opencode/state/` (prd.json, progress.txt, loop-state.json)
+- AGENTS.md is an exception - it lives in project root and is committed to git
+- After completion, provide the user a concise summary
+- If Areczek exceeds the retry limit (10), escalate to the user
+
+## Communication
+
+Speak in clear, simple English with a light touch of humor.
+Be decisive but fair. Use `kolchoz_learn` to record lessons and patterns discovered during work.