@neriros/ralphy 2.7.1 → 2.7.2
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +52 -0
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -68,6 +68,47 @@ ralph list # Table of all tasks
|
|
|
68
68
|
ralph status --name fix-auth # Detailed view of one task
|
|
69
69
|
```
|
|
70
70
|
|
|
71
|
+
### Agent Mode (Linear integration)
|
|
72
|
+
|
|
73
|
+
`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.
|
|
74
|
+
|
|
75
|
+
```bash
|
|
76
|
+
export LINEAR_API_KEY=lin_api_xxx
|
|
77
|
+
ralph agent --linear-team ENG --linear-assignee me --concurrency 3 --poll-interval 60
|
|
78
|
+
```
|
|
79
|
+
|
|
80
|
+
What it does on each tick:
|
|
81
|
+
|
|
82
|
+
1. Polls Linear for open issues matching the filter (team / assignee / status / labels)
|
|
83
|
+
2. Dedupes against `.ralph/agent-state.json` (already processed) plus any in-flight workers
|
|
84
|
+
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
|
|
85
|
+
4. Posts a "🤖 started" comment on the Linear issue and (optionally) moves it to `inProgressStatus`
|
|
86
|
+
5. On worker exit, posts a success/failure comment and (on success) moves the issue to `doneStatus`
|
|
87
|
+
|
|
88
|
+
Defaults are written to `ralphy.config.json` on first run; CLI flags override config values per invocation.
|
|
89
|
+
|
|
90
|
+
```jsonc
|
|
91
|
+
{
|
|
92
|
+
"concurrency": 3,
|
|
93
|
+
"pollIntervalSeconds": 60,
|
|
94
|
+
"maxIterationsPerTask": 0,
|
|
95
|
+
"maxCostUsdPerTask": 0,
|
|
96
|
+
"engine": "claude",
|
|
97
|
+
"model": "opus",
|
|
98
|
+
"linear": {
|
|
99
|
+
"team": "ENG",
|
|
100
|
+
"assignee": "me",
|
|
101
|
+
"statuses": ["Todo", "In Progress"],
|
|
102
|
+
"labels": ["ralph", "automation"],
|
|
103
|
+
"inProgressStatus": "In Progress",
|
|
104
|
+
"doneStatus": "In Review",
|
|
105
|
+
"postComments": true,
|
|
106
|
+
},
|
|
107
|
+
}
|
|
108
|
+
```
|
|
109
|
+
|
|
110
|
+
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.
|
|
111
|
+
|
|
71
112
|
## CLI Options
|
|
72
113
|
|
|
73
114
|
| Option | Description |
|
|
@@ -87,6 +128,17 @@ ralph status --name fix-auth # Detailed view of one task
|
|
|
87
128
|
| `--log` | Log raw JSON stream output |
|
|
88
129
|
| `--verbose` | Verbose output |
|
|
89
130
|
|
|
131
|
+
### Agent mode flags
|
|
132
|
+
|
|
133
|
+
| Option | Description |
|
|
134
|
+
| ------------------------ | -------------------------------------------- |
|
|
135
|
+
| `--linear-team <key>` | Linear team key (e.g. `ENG`) |
|
|
136
|
+
| `--linear-assignee <id>` | Filter by assignee (user id, email, or `me`) |
|
|
137
|
+
| `--linear-status <name>` | Filter by status name (repeatable) |
|
|
138
|
+
| `--linear-label <name>` | Filter by label name (repeatable, any-of) |
|
|
139
|
+
| `--poll-interval <s>` | Seconds between Linear polls (default: 60) |
|
|
140
|
+
| `--concurrency <n>` | Max concurrent task loops (default: 1) |
|
|
141
|
+
|
|
90
142
|
## OpenSpec Flow
|
|
91
143
|
|
|
92
144
|
There are no phases. One loop, one prompt, one `tasks.md` checklist.
|