@klaudworks/rmr 1.1.1 → 1.2.0

package/README.md

@@ -8,6 +8,14 @@
 
 Inspired by [snarktank/antfarm](https://github.com/snarktank/antfarm).
 
+## Why rmr?
+
+Coding agents produce slop. Not because they're bad, but because "go make it work" is a bad prompt, the same way it's a bad brief for a human developer. You wouldn't hand someone a one-liner and expect clean, well-structured code back. Yet that's how most people use coding agents today.
+
+The fix is simple: break the work into steps. Plan first, then implement, then review. Loop back if the review finds problems. This is how good teams already work. rmr just lets you encode that process in a YAML file and run it automatically.
+
+It doesn't care how you plan (markdown files, Beads, Linear, whatever) or which agent you use (Claude Code, Codex, OpenCode). You can mix and match harnesses within a single workflow too, like using Claude for planning and Codex for implementation. It just makes sure each step gets the right context, the output flows to the next step, and you can pause and pick up where you left off.
+
 ## Quick Start
 
 **Instructions for humans**
@@ -154,6 +162,25 @@ rmr install feature-dev
 rmr run .rmr/workflows/feature-dev/workflow.yaml
 ```
 
+<details>
+<summary><strong>beads</strong> (requires beads + toon)</summary>
+
+Autonomous issue loop powered by Beads: pick the next issue, plan, implement,
+review, then continue with the next issue.
+
+See docs: [docs/workflows/beads/](docs/workflows/beads/)
+
+Prerequisites:
+- [beads](https://github.com/steveyegge/beads)
+- [toon](https://github.com/toon-format/toon?tab=readme-ov-file)
+
+```bash
+rmr install beads
+rmr run .rmr/workflows/beads/workflow.yaml
+```
+
+</details>
+
 ## Supported Harnesses
 
 Specify a default harness (and optionally model) at the top level of your workflow file. Individual steps can override both, so you can mix providers within a single workflow.

package/dist/index.js

@@ -8041,6 +8041,15 @@ var isOptionSymbol = Symbol(`clipanion/isOption`);
 function makeCommandOption(spec) {
   return { ...spec, [isOptionSymbol]: true };
 }
+function rerouteArguments(a, b) {
+  if (typeof a === `undefined`)
+    return [a, b];
+  if (typeof a === `object` && a !== null && !Array.isArray(a)) {
+    return [undefined, a];
+  } else {
+    return [a, b];
+  }
+}
 function cleanValidationError(message, { mergeName = false } = {}) {
   const match = message.match(/^([^:]+): (.*)$/m);
   if (!match)
@@ -8060,6 +8069,23 @@ ${errors.map((error) => `
 - ${cleanValidationError(error)}`).join(``)}`);
   }
 }
+function applyValidator(name, value, validator) {
+  if (typeof validator === `undefined`)
+    return value;
+  const errors = [];
+  const coercions = [];
+  const coercion = (v) => {
+    const orig = value;
+    value = v;
+    return coercion.bind(null, orig);
+  };
+  const check = validator(value, { errors, coercions, coercion });
+  if (!check)
+    throw formatError(`Invalid value for ${name}`, errors);
+  for (const [, op] of coercions)
+    op();
+  return value;
+}
 
 // node_modules/clipanion/lib/advanced/Command.mjs
 class Command {
@@ -9388,19 +9414,208 @@ VersionCommand.paths = [[`-v`], [`--version`]];
 var exports_options = {};
 __export(exports_options, {
   rerouteArguments: () => rerouteArguments,
-  makeCommandOption: () => makeCommandOption2,
-  isOptionSymbol: () => isOptionSymbol2,
-  formatError: () => formatError2,
-  cleanValidationError: () => cleanValidationError2,
+  makeCommandOption: () => makeCommandOption,
+  isOptionSymbol: () => isOptionSymbol,
+  formatError: () => formatError,
+  cleanValidationError: () => cleanValidationError,
   applyValidator: () => applyValidator,
   String: () => String2,
   Rest: () => Rest,
-  Proxy: () => Proxy2,
+  Proxy: () => Proxy,
   Counter: () => Counter,
   Boolean: () => Boolean2,
   Array: () => Array2
 });
 
+// node_modules/clipanion/lib/advanced/options/Array.mjs
+function Array2(descriptor, initialValueBase, optsBase) {
+  const [initialValue, opts] = rerouteArguments(initialValueBase, optsBase !== null && optsBase !== undefined ? optsBase : {});
+  const { arity = 1 } = opts;
+  const optNames = descriptor.split(`,`);
+  const nameSet = new Set(optNames);
+  return makeCommandOption({
+    definition(builder) {
+      builder.addOption({
+        names: optNames,
+        arity,
+        hidden: opts === null || opts === undefined ? undefined : opts.hidden,
+        description: opts === null || opts === undefined ? undefined : opts.description,
+        required: opts.required
+      });
+    },
+    transformer(builder, key, state) {
+      let usedName;
+      let currentValue = typeof initialValue !== `undefined` ? [...initialValue] : undefined;
+      for (const { name, value } of state.options) {
+        if (!nameSet.has(name))
+          continue;
+        usedName = name;
+        currentValue = currentValue !== null && currentValue !== undefined ? currentValue : [];
+        currentValue.push(value);
+      }
+      if (typeof currentValue !== `undefined`) {
+        return applyValidator(usedName !== null && usedName !== undefined ? usedName : key, currentValue, opts.validator);
+      } else {
+        return currentValue;
+      }
+    }
+  });
+}
+// node_modules/clipanion/lib/advanced/options/Boolean.mjs
+function Boolean2(descriptor, initialValueBase, optsBase) {
+  const [initialValue, opts] = rerouteArguments(initialValueBase, optsBase !== null && optsBase !== undefined ? optsBase : {});
+  const optNames = descriptor.split(`,`);
+  const nameSet = new Set(optNames);
+  return makeCommandOption({
+    definition(builder) {
+      builder.addOption({
+        names: optNames,
+        allowBinding: false,
+        arity: 0,
+        hidden: opts.hidden,
+        description: opts.description,
+        required: opts.required
+      });
+    },
+    transformer(builer, key, state) {
+      let currentValue = initialValue;
+      for (const { name, value } of state.options) {
+        if (!nameSet.has(name))
+          continue;
+        currentValue = value;
+      }
+      return currentValue;
+    }
+  });
+}
+// node_modules/clipanion/lib/advanced/options/Counter.mjs
+function Counter(descriptor, initialValueBase, optsBase) {
+  const [initialValue, opts] = rerouteArguments(initialValueBase, optsBase !== null && optsBase !== undefined ? optsBase : {});
+  const optNames = descriptor.split(`,`);
+  const nameSet = new Set(optNames);
+  return makeCommandOption({
+    definition(builder) {
+      builder.addOption({
+        names: optNames,
+        allowBinding: false,
+        arity: 0,
+        hidden: opts.hidden,
+        description: opts.description,
+        required: opts.required
+      });
+    },
+    transformer(builder, key, state) {
+      let currentValue = initialValue;
+      for (const { name, value } of state.options) {
+        if (!nameSet.has(name))
+          continue;
+        currentValue !== null && currentValue !== undefined || (currentValue = 0);
+        if (!value) {
+          currentValue = 0;
+        } else {
+          currentValue += 1;
+        }
+      }
+      return currentValue;
+    }
+  });
+}
+// node_modules/clipanion/lib/advanced/options/Rest.mjs
+function Rest(opts = {}) {
+  return makeCommandOption({
+    definition(builder, key) {
+      var _a;
+      builder.addRest({
+        name: (_a = opts.name) !== null && _a !== undefined ? _a : key,
+        required: opts.required
+      });
+    },
+    transformer(builder, key, state) {
+      const isRestPositional = (index) => {
+        const positional = state.positionals[index];
+        if (positional.extra === NoLimits)
+          return true;
+        if (positional.extra === false && index < builder.arity.leading.length)
+          return true;
+        return false;
+      };
+      let count = 0;
+      while (count < state.positionals.length && isRestPositional(count))
+        count += 1;
+      return state.positionals.splice(0, count).map(({ value }) => value);
+    }
+  });
+}
+// node_modules/clipanion/lib/advanced/options/String.mjs
+function StringOption(descriptor, initialValueBase, optsBase) {
+  const [initialValue, opts] = rerouteArguments(initialValueBase, optsBase !== null && optsBase !== undefined ? optsBase : {});
+  const { arity = 1 } = opts;
+  const optNames = descriptor.split(`,`);
+  const nameSet = new Set(optNames);
+  return makeCommandOption({
+    definition(builder) {
+      builder.addOption({
+        names: optNames,
+        arity: opts.tolerateBoolean ? 0 : arity,
+        hidden: opts.hidden,
+        description: opts.description,
+        required: opts.required
+      });
+    },
+    transformer(builder, key, state, context) {
+      let usedName;
+      let currentValue = initialValue;
+      if (typeof opts.env !== `undefined` && context.env[opts.env]) {
+        usedName = opts.env;
+        currentValue = context.env[opts.env];
+      }
+      for (const { name, value } of state.options) {
+        if (!nameSet.has(name))
+          continue;
+        usedName = name;
+        currentValue = value;
+      }
+      if (typeof currentValue === `string`) {
+        return applyValidator(usedName !== null && usedName !== undefined ? usedName : key, currentValue, opts.validator);
+      } else {
+        return currentValue;
+      }
+    }
+  });
+}
+function StringPositional(opts = {}) {
+  const { required = true } = opts;
+  return makeCommandOption({
+    definition(builder, key) {
+      var _a;
+      builder.addPositional({
+        name: (_a = opts.name) !== null && _a !== undefined ? _a : key,
+        required: opts.required
+      });
+    },
+    transformer(builder, key, state) {
+      var _a;
+      for (let i = 0;i < state.positionals.length; ++i) {
+        if (state.positionals[i].extra === NoLimits)
+          continue;
+        if (required && state.positionals[i].extra === true)
+          continue;
+        if (!required && state.positionals[i].extra === false)
+          continue;
+        const [positional] = state.positionals.splice(i, 1);
+        return applyValidator((_a = opts.name) !== null && _a !== undefined ? _a : key, positional.value, opts.validator);
+      }
+      return;
+    }
+  });
+}
+function String2(descriptor, ...args) {
+  if (typeof descriptor === `string`) {
+    return StringOption(descriptor, ...args);
+  } else {
+    return StringPositional(descriptor);
+  }
+}
 // src/lib/errors.ts
 class RmrError extends Error {
   code;
@@ -10623,7 +10838,7 @@ function bashScript() {
     "  fi",
     "",
     '  if [[ "${prev}" == "install" ]]; then',
-    '    COMPREPLY=( $(compgen -W "feature-dev" -- "${cur}") )',
+    '    COMPREPLY=( $(compgen -W "feature-dev beads" -- "${cur}") )',
     "    return 0",
     "  fi",
     "}",
@@ -10654,7 +10869,7 @@ function zshScript() {
     "  fi",
     "",
     "  if [[ ${words[2]} == install && $CURRENT -eq 3 ]]; then",
-    "    compadd -- feature-dev",
+    "    compadd -- feature-dev beads",
     "    return",
     "  fi",
     "}",
@@ -10676,7 +10891,7 @@ function fishScript() {
     `complete -c ${binaryName} -n '__fish_use_subcommand' -a 'install run continue complete completion'`,
     `complete -c ${binaryName} -n '__fish_seen_subcommand_from continue' -a '(__rex_complete_run_id)'`,
     `complete -c ${binaryName} -n '__fish_seen_subcommand_from run' -a '(__rex_complete_workflow)'`,
-    `complete -c ${binaryName} -n '__fish_seen_subcommand_from install' -a 'feature-dev'`
+    `complete -c ${binaryName} -n '__fish_seen_subcommand_from install' -a 'feature-dev beads'`
   ].join(`
 `);
 }
@@ -11040,7 +11255,8 @@ var adapters = {
       return { binary: "copilot", args: withModelArgs(options.model, args) };
     },
     buildResumeCommand(_sessionId, prompt, options) {
-      const args = ["-p", prompt];
+      const auto = options.allowAll ? ["--allow-all", "--no-ask-user"] : [];
+      const args = [...auto, "-p", prompt];
       return { binary: "copilot", args: withModelArgs(options.model, args) };
     },
     createStreamParser: createPassthroughParser,

package/examples/workflows/beads/implement-agent.md

@@ -0,0 +1,79 @@
+# Implement
+
+You are implementing one beads issue selected by the planner.
+Use issue comments as the source of truth for research context and plan.
+
+## Subagent Use
+
+- Do not use subagents for basic code exploration.
+- Read files and grep directly for general repo understanding.
+- Use subagents sparingly, only when a focused deep lookup is needed.
+
+## Workflow
+
+1. Determine issue id:
+   - Use `{{verify.issue_id}}` if present (loop-back from review).
+   - Otherwise use `{{plan.issue_id}}`.
+2. If needed, claim issue:
+   `bd update <issue-id> --status in_progress --json | toon`
+3. Read issue comments once:
+   `bd comments <issue-id> --json -q | toon`
+   - Find latest planning comment and any review feedback.
+4. Read relevant source files broadly.
+5. Confirm project checks pass before changes:
+   - `go build ./...`
+   - `go vet ./...`
+6. Implement the planned change.
+7. 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 issue plan comment.
+8. Commit with a clear message describing what changed and why.
+9. Add implementation handoff comment with:
+   - commit hash
+   - what changed
+   - verification results
+   Example:
+   `bd comments add <issue-id> "Review target commit: <hash>\n\nImplementation summary: ...\n\nVerification: ..." --json | toon`
+10. Keep the issue open and `in_progress` for review:
+    - `bd update <issue-id> --status in_progress --json | toon`
+
+## 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:issue_id><issue-id></rmr:issue_id>
+<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:issue_id><issue-id></rmr:issue_id>
+<rmr:reason>What is blocking and what was tried</rmr:reason>
+```
+
+## Context
+
+Reviewer feedback: {{verify.issues}}
+Planned issue: {{plan.issue_id}}
+Loop issue: {{verify.issue_id}}

package/examples/workflows/beads/planner-agent.md

@@ -0,0 +1,69 @@
+# Planner
+
+You are the combined research + planning step for a beads issue loop.
+Pick one issue, validate it, research it, write the implementation plan to
+issue comments, and hand off by issue id.
+
+## Command Rules
+
+- Use `--json | toon` for beads commands.
+- Prefer narrow issue-scoped reads after selection.
+- Do not run `bd prime` in this loop.
+
+## Subagent Use
+
+- Do not use subagents for basic code exploration.
+- Read files and grep directly for general repo understanding.
+- Use subagents sparingly, only when a focused deep lookup is needed.
+
+## Workflow
+
+1. Select next work (highest priority):
+   - `bd list --status in_progress --sort priority --limit 1 --json -q | toon`
+   - If an in-progress issue exists, use it.
+   - Otherwise: `bd ready --sort priority --limit 1 --json -q | toon`
+2. If no issue is available, stop the loop for this run:
+   ```
+   <rmr:status>done</rmr:status>
+   <rmr:next_state>done</rmr:next_state>
+   <rmr:summary>No ready beads issues.</rmr:summary>
+   <rmr:issue_id>N/A</rmr:issue_id>
+   ```
+3. If selected issue is not `in_progress`, claim it:
+   `bd update <issue-id> --status in_progress --json | toon`
+4. Read issue comments once:
+   `bd comments <issue-id> --json -q | toon`
+5. Validate problem and value. If invalid/low-value:
+   - Add concise evidence comment.
+   - Close the issue with reason.
+   - Emit `<rmr:next_state>plan</rmr:next_state>` to continue loop.
+6. For valid issues, research and plan in one pass:
+   - Local code touchpoints (paths + symbols)
+   - Relevant spec anchors under `spec/`
+   - `.cache/repos/` references when useful
+   - Risks, edge cases, and test guidance
+7. Write one structured comment that contains both research and plan.
+8. Keep the issue `in_progress` and hand off by `<rmr:issue_id>`.
+
+## Output
+
+Valid issue handoff:
+
+```
+<rmr:status>done</rmr:status>
+<rmr:issue_id><issue-id></rmr:issue_id>
+<rmr:summary>Planned issue <issue-id></rmr:summary>
+```
+
+Invalid/low-value issue (continue loop):
+
+```
+<rmr:status>done</rmr:status>
+<rmr:next_state>plan</rmr:next_state>
+<rmr:summary>Closed issue <issue-id>: <reason></rmr:summary>
+<rmr:issue_id><issue-id></rmr:issue_id>
+```
+
+## Context
+
+No external task input is required. Select work from beads only.

package/examples/workflows/beads/review-agent.md

@@ -0,0 +1,91 @@
+# Review
+
+You are reviewing a change made by the implement agent.
+Use the beads issue comments as the source of truth for plan, implementation
+notes, and review history.
+
+## Subagent Use
+
+- Do not use subagents for basic code exploration.
+- Read files and grep directly for general repo understanding.
+- Use subagents sparingly, only when a focused deep lookup is needed.
+
+## Workflow
+
+1. Use `{{implement.issue_id}}` as the active issue id.
+2. Read issue comments once:
+   `bd comments <issue-id> --json -q | toon`
+   - Find latest `Review target commit: <hash>` marker.
+3. Read the commit diff to see the actual changes.
+4. If the diff is not enough to understand the change (large refactors,
+   structural moves), read the affected files in their final state.
+5. 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?
+6. Verify the build passes and all tests are green.
+7. Make your decision.
+
+## Routing Actions
+
+- **Approve**:
+  - `bd comments add <issue-id> "Review: approved" --json | toon`
+  - `bd close <issue-id> --reason "Approved" --json | toon`
+- **Request changes**:
+  - `bd comments add <issue-id> "Review issues: <what to fix and why>" --json | toon`
+  - `bd update <issue-id> --status in_progress --json | toon`
+- **Escalate**:
+  - `bd comments add <issue-id> "Review blocked: <reason>" --json | toon`
+
+## What to Look For
+
+- Semantic changes: refactors that subtly change behavior
+- Missing error handling
+- Test validity: new tests that do not 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:issue_id><issue-id></rmr:issue_id>
+<rmr:next_state>plan</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:issue_id><issue-id></rmr:issue_id>
+<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:issue_id><issue-id></rmr:issue_id>
+<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
+
+## Context
+
+Issue: {{implement.issue_id}}

package/examples/workflows/beads/workflow.yaml

@@ -0,0 +1,27 @@
+# Beads autonomous loop for rmr.
+# Three steps: plan (select + research + plan), implement, verify (review).
+# verify routes back to plan after approval to continue processing issues.
+
+id: beads
+name: Beads Development Workflow
+harness: claude
+
+steps:
+  - id: plan
+    prompt_file: planner-agent.md
+    next_step: implement
+    requires:
+      outputs: [issue_id]
+
+  - id: implement
+    prompt_file: implement-agent.md
+    next_step: verify
+    requires:
+      inputs: [plan.issue_id]
+      outputs: [issue_id]
+
+  - id: verify
+    prompt_file: review-agent.md
+    next_step: plan
+    requires:
+      inputs: [implement.issue_id]

package/npm-shrinkwrap.json

@@ -1,12 +1,12 @@
 {
   "name": "@klaudworks/rex",
-  "version": "1.1.1",
+  "version": "1.2.0",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "@klaudworks/rex",
-      "version": "1.1.1",
+      "version": "1.2.0",
       "dependencies": {
         "clipanion": "^4.0.0-rc.4",
         "yaml": "^2.8.2"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@klaudworks/rmr",
-  "version": "1.1.1",
+  "version": "1.2.0",
   "description": "Define multi-step coding workflows for AI agents",
   "license": "MIT",
   "repository": {