@klaudworks/rmr 0.4.0

package/examples/workflows/feature-dev/planner-agent.md

@@ -0,0 +1,65 @@
+# Planner
+
+You are a combined research + planning agent. Your job is to validate an issue,
+gather implementation context, and produce a concrete plan -- all in one pass.
+
+## Phase 1: Research
+
+Validate that the task is real and worth doing before investing in a plan.
+
+1. Read the task description carefully. Understand what is being asked.
+2. Explore the codebase to validate the problem:
+   - Is the issue real? Can you reproduce or confirm it in code?
+   - Is it worth doing? Does it improve correctness, maintainability, or UX?
+3. If the issue is invalid or not worth pursuing, reject it -- set
+   `<next_state>done</next_state>` with a `<reason>` explaining why.
+   This terminates the workflow immediately.
+4. For valid issues, gather implementation context:
+   - Identify affected files, functions, and modules.
+   - Note relevant patterns already used in the codebase.
+   - Identify edge cases and risks.
+   - Note what tests exist and what coverage is needed.
+
+## Phase 2: Plan
+
+Design a clean solution. Focus on the approach, not line-by-line diffs.
+
+1. **Check scope.** Confirm exactly what the task asks for. If requirements
+   are ambiguous, note the ambiguity explicitly in the plan.
+2. **Design the approach.** Consider:
+   - What is the right abstraction?
+   - What patterns does the codebase already use for similar things?
+   - Is there a way to solve this that makes the code simpler, not just different?
+   - Would a deeper refactor address the root cause rather than a symptom?
+
+## What a Good Plan Contains
+
+- **Why this matters**: concrete benefit -- fewer bugs, better UX, etc.
+- **The approach**: how to solve it, what pattern or structural change to use.
+- **Scope**: which files/modules are affected.
+- **Risks**: what could go wrong, behavioral changes, breaking changes.
+- **Verification**: how to confirm correctness -- which tests to run, what to check.
+
+A good plan does NOT contain line-by-line diffs. The implementing agent
+decides the code-level details.
+
+## Output
+
+Emit `<rmr:*>` tags at the end of your response. rmr parses these automatically.
+
+For valid issues (proceeds to implementation):
+
+```
+<rmr:status>done</rmr:status>
+<rmr:summary>One-line summary of the plan</rmr:summary>
+<rmr:plan>The full implementation plan</rmr:plan>
+```
+
+For rejected issues (terminates the workflow):
+
+```
+<rmr:status>done</rmr:status>
+<rmr:next_state>done</rmr:next_state>
+<rmr:summary>Why this issue was rejected</rmr:summary>
+<rmr:plan>N/A</rmr:plan>
+```

package/examples/workflows/feature-dev/review-agent.md

@@ -0,0 +1,63 @@
+# Review
+
+You are reviewing a change made by the tackle agent. Your job is to verify
+correctness, catch regressions, and ensure code quality.
+
+## Workflow
+
+1. Read the tackle agent's output to understand what was changed and why.
+2. Read the commit diff to see the actual changes.
+3. If the diff isn't enough to understand the change (large refactors,
+   structural moves), read the affected files in their final state.
+4. Evaluate:
+   - **Correctness**: Does the change achieve what the plan intended?
+   - **No regressions**: Could it break existing behavior?
+   - **Code quality**: Clean, idiomatic code? Is the result elegant?
+   - **Behavioral preservation**: For refactors, does the code still do
+     exactly the same thing?
+   - **Net improvement**: Is the codebase clearly better after this change?
+5. Verify the build passes and all tests are green.
+6. Make your decision.
+
+## What to Look For
+
+- Semantic changes: refactors that subtly change behavior
+- Missing error handling
+- Test validity: new tests that don't actually test what they claim
+- Unrelated changes sneaking in (but touching many files for a consistent
+  refactor is fine)
+
+## Decisions
+
+Use `<rmr:next_state>` to route the workflow.
+
+**Approve** -- the change is correct and improves the codebase:
+
+```
+<rmr:status>done</rmr:status>
+<rmr:next_state>done</rmr:next_state>
+<rmr:summary>Why this change is good</rmr:summary>
+```
+
+**Request changes** -- issues that need fixing (sends back to implement):
+
+```
+<rmr:status>done</rmr:status>
+<rmr:next_state>implement</rmr:next_state>
+<rmr:issues>What needs to be fixed and why</rmr:issues>
+```
+
+**Escalate** -- needs human judgment:
+
+```
+<rmr:status>human_intervention_required</rmr:status>
+<rmr:reason>Why human input is needed</rmr:reason>
+```
+
+## Do NOT
+
+- Make improvements -- review only
+- Refactor code touched by the commit
+- Add unrelated tests
+- Approve changes that fail build or tests
+- Skip or weaken tests to make the suite pass

package/examples/workflows/feature-dev/tackle-agent.md

@@ -0,0 +1,53 @@
+# Tackle
+
+You are implementing a change based on a plan from the planner agent. The plan
+describes the approach and rationale -- you decide the code-level details.
+Aim for the most elegant implementation that fulfills the plan's intent.
+
+## Workflow
+
+1. Read the plan carefully. Understand the approach, scope, and risks.
+2. Read the relevant source files. Understand the full picture -- the plan
+   frames the approach, but you need to understand the code deeply to
+   implement it well. Read broadly, not just the files the plan mentions.
+3. Confirm the project builds and tests pass before making changes.
+4. Implement the change. Follow the plan's intent but use your judgment on
+   code-level decisions. If the cleanest implementation touches more files
+   than the plan anticipated, that's fine.
+5. Verify:
+   - Build passes
+   - All tests pass -- not just the ones related to your change.
+     If a pre-existing test fails, investigate and fix it.
+     Do not skip, disable, or weaken tests to work around breakage.
+   - Any additional verification from the plan.
+6. Commit with a clear message describing what changed and why.
+
+## Principles
+
+- One atomic commit per task. The review agent expects a single coherent
+  change to evaluate.
+- Do NOT fix unrelated issues you happen to notice -- note them in your
+  output so they can be filed separately.
+- Do NOT gold-plate. Implement what the plan asks for, elegantly, then stop.
+- Do NOT skip verification. Every change must leave the project in a
+  working state.
+
+## Output
+
+Emit `<rmr:*>` tags at the end of your response. rmr parses these automatically.
+
+On success:
+
+```
+<rmr:status>done</rmr:status>
+<rmr:summary>What was implemented and why</rmr:summary>
+<rmr:commit>The commit hash</rmr:commit>
+<rmr:tests>Test results summary</rmr:tests>
+```
+
+If blocked after 3 attempts:
+
+```
+<rmr:status>human_intervention_required</rmr:status>
+<rmr:reason>What is blocking and what was tried</rmr:reason>
+```

package/examples/workflows/feature-dev/workflow.yaml

@@ -0,0 +1,61 @@
+# Feature development workflow for rmr.
+# Three agents: planner (research + plan), tackle (implement), review (verify).
+# The review step can loop back to implement or escalate to human intervention.
+#
+# Agent prompts are co-located with this workflow in the same folder.
+# Step inputs only pass dynamic context (variables from prior steps).
+# Variables reference step IDs: {{step_id.key}}
+#
+# Routing is controlled by <next_state> in agent output.
+# The planner can reject a task by setting next_state=done.
+# The reviewer can request changes by setting next_state=implement.
+
+id: feature-dev
+name: Feature Development
+
+agents:
+  - id: planner
+    harness: claude
+    prompt: planner-agent.md
+
+  - id: developer
+    harness: claude
+    prompt: tackle-agent.md
+
+  - id: reviewer
+    harness: claude
+    prompt: review-agent.md
+
+steps:
+  - id: plan
+    agent: planner
+    default_next: implement
+    input_required: [task]
+    outputs:
+      required: []
+    input: |
+      Task: {{task}}
+
+  - id: implement
+    agent: developer
+    default_next: verify
+    input_required: [task, plan.plan]
+    outputs:
+      required: [summary]
+    input: |
+      Task: {{task}}
+      Plan: {{plan.plan}}
+      Reviewer feedback: {{verify.issues}}
+
+  - id: verify
+    agent: reviewer
+    default_next: done
+    input_required: [implement.summary]
+    outputs:
+      required: []
+    input: |
+      Task: {{task}}
+      Plan: {{plan.plan}}
+      Developer summary: {{implement.summary}}
+      Commit: {{implement.commit}}
+      Tests: {{implement.tests}}

package/npm-shrinkwrap.json

@@ -0,0 +1,97 @@
+{
+  "name": "@klaudworks/rex",
+  "version": "0.3.1",
+  "lockfileVersion": 3,
+  "requires": true,
+  "packages": {
+    "": {
+      "name": "@klaudworks/rex",
+      "version": "0.3.1",
+      "dependencies": {
+        "clipanion": "^4.0.0-rc.4",
+        "yaml": "^2.8.2"
+      },
+      "bin": {
+        "rex": "dist/index.js"
+      },
+      "devDependencies": {
+        "@types/bun": "^1.3.10",
+        "typescript": "^5.9.3"
+      }
+    },
+    "node_modules/@types/bun": {
+      "version": "1.3.10",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "bun-types": "1.3.10"
+      }
+    },
+    "node_modules/@types/node": {
+      "version": "25.5.0",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "undici-types": "~7.18.0"
+      }
+    },
+    "node_modules/bun-types": {
+      "version": "1.3.10",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@types/node": "*"
+      }
+    },
+    "node_modules/clipanion": {
+      "version": "4.0.0-rc.4",
+      "license": "MIT",
+      "workspaces": [
+        "website"
+      ],
+      "dependencies": {
+        "typanion": "^3.8.0"
+      },
+      "peerDependencies": {
+        "typanion": "*"
+      }
+    },
+    "node_modules/typanion": {
+      "version": "3.14.0",
+      "license": "MIT",
+      "workspaces": [
+        "website"
+      ]
+    },
+    "node_modules/typescript": {
+      "version": "5.9.3",
+      "dev": true,
+      "license": "Apache-2.0",
+      "bin": {
+        "tsc": "bin/tsc",
+        "tsserver": "bin/tsserver"
+      },
+      "engines": {
+        "node": ">=14.17"
+      }
+    },
+    "node_modules/undici-types": {
+      "version": "7.18.2",
+      "dev": true,
+      "license": "MIT"
+    },
+    "node_modules/yaml": {
+      "version": "2.8.2",
+      "license": "ISC",
+      "bin": {
+        "yaml": "bin.mjs"
+      },
+      "engines": {
+        "node": ">= 14.6"
+      },
+      "funding": {
+        "url": "https://github.com/sponsors/eemeli"
+      }
+    }
+  }
+}

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "@klaudworks/rmr",
+  "version": "0.4.0",
+  "description": "Define multi-step coding workflows for AI agents",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/klaudworks/ralph-meets-rex"
+  },
+  "type": "module",
+  "files": [
+    "dist",
+    "examples",
+    "npm-shrinkwrap.json",
+    "README.md"
+  ],
+  "bin": {
+    "rmr": "dist/index.js"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "dev": "bun run src/index.ts",
+    "build": "bun build src/index.ts --outfile dist/index.js --target node",
+    "start": "bun run dist/index.js",
+    "test": "bun test"
+  },
+  "dependencies": {
+    "chalk": "^5.6.2",
+    "clipanion": "^4.0.0-rc.4",
+    "yaml": "^2.8.2"
+  },
+  "devDependencies": {
+    "@types/bun": "^1.3.10",
+    "typescript": "^5.9.3"
+  }
+}