@neriros/ralphy 2.7.1 → 2.7.3

package/README.md

@@ -68,6 +68,50 @@ ralph list                    # Table of all tasks
 ralph status --name fix-auth  # Detailed view of one task
 ```
 
+### Agent Mode (Linear integration)
+
+`ralph agent` polls Linear for open issues and runs up to N concurrent task loops, scaffolding an OpenSpec change per new issue. Requires `LINEAR_API_KEY` in the environment.
+
+```bash
+export LINEAR_API_KEY=lin_api_xxx
+ralph agent --linear-team ENG --linear-assignee me --concurrency 3 --poll-interval 60
+```
+
+What it does on each tick:
+
+1. Polls Linear for open issues matching the filter (team / assignee / status / labels)
+2. Dedupes against `.ralph/agent-state.json` (already processed) plus any in-flight workers
+3. For each new issue: fetches existing comments, scaffolds `openspec/changes/<id-slug>/{proposal.md,tasks.md,design.md}` (with the comments embedded so the worker sees prior discussion), then spawns `ralph task --name <id-slug>` up to the concurrency cap
+4. Posts a "🤖 started" comment on the Linear issue and (optionally) moves it to `inProgressStatus`
+5. On worker exit, posts a success/failure comment and (on success) moves the issue to `doneStatus` and/or applies `doneLabel`
+
+Defaults are written to `ralphy.config.json` on first run; CLI flags override config values per invocation.
+
+```jsonc
+{
+  "concurrency": 3,
+  "pollIntervalSeconds": 60,
+  "maxIterationsPerTask": 0,
+  "maxCostUsdPerTask": 0,
+  "engine": "claude",
+  "model": "opus",
+  "linear": {
+    "team": "ENG",
+    "assignee": "me",
+    "statuses": ["Todo", "In Progress"],
+    "labels": ["ralph", "automation"],
+    "inProgressStatus": "In Progress",
+    "doneStatus": "In Review",
+    "doneLabel": "ralphy-done",
+    "postComments": true,
+  },
+}
+```
+
+`doneStatus` and `doneLabel` are independent — set either, both, or neither. Use `doneLabel` if your team marks completion via a label rather than a workflow state.
+
+Failed workers (non-zero exit) are not marked processed, so they'll be retried on the next poll. SIGINT/SIGTERM cleanly stops polling and kills active workers. All Linear side effects are best-effort — failures log a warning but never block the task loop.
+
 ## CLI Options
 
 | Option                 | Description                                              |
@@ -87,6 +131,17 @@ ralph status --name fix-auth  # Detailed view of one task
 | `--log`                | Log raw JSON stream output                               |
 | `--verbose`            | Verbose output                                           |
 
+### Agent mode flags
+
+| Option                   | Description                                  |
+| ------------------------ | -------------------------------------------- |
+| `--linear-team <key>`    | Linear team key (e.g. `ENG`)                 |
+| `--linear-assignee <id>` | Filter by assignee (user id, email, or `me`) |
+| `--linear-status <name>` | Filter by status name (repeatable)           |
+| `--linear-label <name>`  | Filter by label name (repeatable, any-of)    |
+| `--poll-interval <s>`    | Seconds between Linear polls (default: 60)   |
+| `--concurrency <n>`      | Max concurrent task loops (default: 1)       |
+
 ## OpenSpec Flow
 
 There are no phases. One loop, one prompt, one `tasks.md` checklist.

package/dist/cli/index.js

@@ -69685,6 +69685,26 @@ async function updateIssueState(apiKey, issueId, stateId) {
     stateId
   });
 }
+async function fetchIssueLabels(apiKey, teamKey) {
+  const query = `query Labels($team: String!) {
+    issueLabels(filter: { team: { key: { eq: $team } } }, first: 250) {
+      nodes { id name }
+    }
+  }`;
+  const data = await linearRequest(apiKey, query, {
+    team: teamKey
+  });
+  return data.issueLabels.nodes;
+}
+async function addLabelToIssue(apiKey, issueId, labelId) {
+  const mutation = `mutation AddLabel($id: String!, $labelId: String!) {
+    issueAddLabel(id: $id, labelId: $labelId) { success }
+  }`;
+  await linearRequest(apiKey, mutation, {
+    id: issueId,
+    labelId
+  });
+}
 
 // apps/cli/src/agent/state.ts
 import { join as join10 } from "path";
@@ -69790,6 +69810,7 @@ var RalphyConfigSchema = exports_external.object({
     labels: exports_external.union([exports_external.array(exports_external.string()), exports_external.string()]).transform((v) => typeof v === "string" ? [v] : v).default([]),
     inProgressStatus: exports_external.string().optional(),
     doneStatus: exports_external.string().optional(),
+    doneLabel: exports_external.string().optional(),
     postComments: exports_external.boolean().default(true)
   }).default({ statuses: [], labels: [], postComments: true })
 }).default({
@@ -69959,6 +69980,27 @@ class AgentCoordinator {
     if (ok && this.opts.doneStatus) {
       await this.moveIssue(issue, this.opts.doneStatus);
     }
+    if (ok && this.opts.doneLabel) {
+      await this.tagIssue(issue, this.opts.doneLabel);
+    }
+  }
+  async tagIssue(issue, labelName) {
+    const updater = this.deps.updater;
+    if (!updater.resolveLabelId || !updater.addLabel) {
+      this.deps.onLog(`! Linear updater does not support labels (cannot tag ${issue.identifier} with '${labelName}')`, "yellow");
+      return;
+    }
+    try {
+      const labelId = await updater.resolveLabelId(issue, labelName);
+      if (!labelId) {
+        this.deps.onLog(`! Linear label '${labelName}' not found for ${issue.identifier}`, "yellow");
+        return;
+      }
+      await updater.addLabel(issue, labelId);
+      this.deps.onLog(`  \u2192 ${issue.identifier} tagged with '${labelName}'`, "gray");
+    } catch (err) {
+      this.deps.onLog(`! Linear label add failed for ${issue.identifier}: ${err.message}`, "red");
+    }
   }
   async moveIssue(issue, stateName) {
     const updater = this.deps.updater;
@@ -70022,6 +70064,7 @@ function AgentMode({ args, projectRoot, statesDir, tasksDir }) {
         labels: args.linearLabel.length ? args.linearLabel : cfg.linear.labels
       };
       const stateCache = new Map;
+      const labelCache = new Map;
       const teamKeyOf = (issue) => issue.identifier.split("-")[0];
       const coord2 = new AgentCoordinator({
         fetchIssues: (f2) => fetchOpenIssues(apiKey, f2),
@@ -70075,6 +70118,17 @@ function AgentMode({ args, projectRoot, statesDir, tasksDir }) {
               stateCache.set(team, map2);
             }
             return map2.get(stateName.toLowerCase()) ?? null;
+          },
+          addLabel: (issue, labelId) => addLabelToIssue(apiKey, issue.id, labelId),
+          resolveLabelId: async (issue, labelName) => {
+            const team = teamKeyOf(issue);
+            let map2 = labelCache.get(team);
+            if (!map2) {
+              const labels = await fetchIssueLabels(apiKey, team);
+              map2 = new Map(labels.map((l) => [l.name.toLowerCase(), l.id]));
+              labelCache.set(team, map2);
+            }
+            return map2.get(labelName.toLowerCase()) ?? null;
           }
         }
       }, {
@@ -70082,6 +70136,7 @@ function AgentMode({ args, projectRoot, statesDir, tasksDir }) {
         filter: filter2,
         inProgressStatus: cfg.linear.inProgressStatus,
         doneStatus: cfg.linear.doneStatus,
+        doneLabel: cfg.linear.doneLabel,
         postComments: cfg.linear.postComments
       });
       coordRef.current = coord2;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@neriros/ralphy",
-  "version": "2.7.1",
+  "version": "2.7.3",
   "description": "An iterative AI task execution framework. Orchestrates multi-phase autonomous work using Claude or Codex engines.",
   "keywords": [
     "agent",