@klaudworks/rmr 1.1.2 → 1.2.1

package/README.md

@@ -162,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

@@ -10838,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",
     "}",
@@ -10869,7 +10869,7 @@ function zshScript() {
     "  fi",
     "",
     "  if [[ ${words[2]} == install && $CURRENT -eq 3 ]]; then",
-    "    compadd -- feature-dev",
+    "    compadd -- feature-dev beads",
     "    return",
     "  fi",
     "}",
@@ -10891,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(`
 `);
 }
@@ -12028,8 +12028,18 @@ class ContinueCommand extends BaseCommand {
 // src/commands/install.ts
 import { cp, readdir as readdir2 } from "node:fs/promises";
 import { existsSync } from "node:fs";
-import { dirname as dirname3, resolve as resolve7 } from "node:path";
+import { basename as basename2, dirname as dirname3, resolve as resolve7 } from "node:path";
 import { fileURLToPath as fileURLToPath2 } from "node:url";
+
+// src/lib/workflow-utils.ts
+function workflowRequiresTask(workflow) {
+  return workflow.steps.some((step) => step.requires.inputs.includes("task"));
+}
+function getWorkflowDefaultHarness(workflow) {
+  return workflow.harness ?? "(none - step-level harnesses only)";
+}
+
+// src/commands/install.ts
 function getExamplesWorkflowsDir() {
   const thisDir = dirname3(fileURLToPath2(import.meta.url));
   const fromDist = resolve7(thisDir, "..", "examples", "workflows");
@@ -12040,6 +12050,17 @@ function getExamplesWorkflowsDir() {
     return fromSrc;
   return fromSrc;
 }
+function resolveWorkflowFilePath(workflowDir) {
+  const yamlPath = resolve7(workflowDir, "workflow.yaml");
+  if (existsSync(yamlPath)) {
+    return yamlPath;
+  }
+  const ymlPath = resolve7(workflowDir, "workflow.yml");
+  if (existsSync(ymlPath)) {
+    return ymlPath;
+  }
+  throw new UserInputError(`Workflow directory does not contain workflow.yaml or workflow.yml: ${workflowDir}`);
+}
 
 class InstallCommand extends BaseCommand {
   static paths = [["install"]];
@@ -12065,14 +12086,28 @@ class InstallCommand extends BaseCommand {
       const hint = available.length > 0 ? ` Available: ${available.join(", ")}.` : " No bundled workflows found.";
       throw new UserInputError(`Unknown workflow "${this.workflowName}".${hint}`);
     }
+    const sourceWorkflowPath = resolveWorkflowFilePath(sourceDir);
+    const sourceWorkflow = await loadWorkflowDefinition(sourceWorkflowPath).catch((error) => {
+      const message = error instanceof Error ? error.message : String(error);
+      throw new UserInputError(`Bundled workflow "${this.workflowName}" is invalid: ${message}`);
+    });
+    const workflowFileName = basename2(sourceWorkflowPath);
+    const installedWorkflowPath = `.rmr/workflows/${this.workflowName}/${workflowFileName}`;
+    const runHint = workflowRequiresTask(sourceWorkflow) ? `${binaryName} run ${installedWorkflowPath} --task "Describe your task"` : `${binaryName} run ${installedWorkflowPath}`;
+    const defaultHarness = getWorkflowDefaultHarness(sourceWorkflow);
+    const harnessHint = `To use codex or opencode, edit ${installedWorkflowPath} and change "harness:"` + ` (optionally "model:").`;
     if (existsSync(destinationDir)) {
       ui.info(`Workflow already installed at .rmr/workflows/${this.workflowName}/`);
-      ui.info(`Run it with: ${binaryName} run .rmr/workflows/${this.workflowName}/workflow.yaml --task "Describe your task"`);
+      ui.info(`Run it with: ${runHint}`);
+      ui.info(`Default harness: ${defaultHarness}`);
+      ui.info(harnessHint);
       return 0;
     }
     await cp(sourceDir, destinationDir, { recursive: true, force: false, errorOnExist: true });
     ui.success(`installed .rmr/workflows/${this.workflowName}/`);
-    ui.info(`Run it with: ${binaryName} run .rmr/workflows/${this.workflowName}/workflow.yaml --task "Describe your task"`);
+    ui.info(`Run it with: ${runHint}`);
+    ui.info(`Default harness: ${defaultHarness}`);
+    ui.info(harnessHint);
     return 0;
   }
 }
@@ -12193,13 +12228,13 @@ class ListCommand extends BaseCommand {
 }
 
 // src/commands/root.ts
-import { basename as basename2 } from "node:path";
+import { basename as basename3 } from "node:path";
 function detectShell() {
   const raw = process.env.SHELL;
   if (!raw) {
     return null;
   }
-  const shell = basename2(raw);
+  const shell = basename3(raw);
   if (shell === "bash" || shell === "zsh" || shell === "fish") {
     return shell;
   }
@@ -12319,9 +12354,6 @@ async function resolveWorkflowPath(inputPath) {
     throw new UserInputError(`Failed to access workflow path "${absolutePath}": ${getErrorMessage(error)}`);
   }
 }
-function workflowRequiresTask(workflow) {
-  return workflow.steps.some((step) => step.requires.inputs.includes("task"));
-}
 
 class RunCommand extends BaseCommand {
   static paths = [["run"]];

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,28 @@
+# 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 # Default harness for all steps; set codex or opencode to switch.
+# model: <provider/model> # Optional: uncomment to pin a default model.
+
+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/examples/workflows/feature-dev/workflow.yaml

@@ -1,6 +1,7 @@
 id: feature-dev
 name: Feature Development
-harness: claude
+harness: claude # Default harness for all steps; set codex or opencode to switch.
+# model: <provider/model> # Optional: uncomment to pin a default model.
 
 steps:
   - id: plan

package/npm-shrinkwrap.json

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

package/package.json

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