skill-rails 0.2.0
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/.claude-plugin/marketplace.json +16 -0
- package/.claude-plugin/plugin.json +16 -0
- package/.mcp.json +8 -0
- package/LICENSE +21 -0
- package/README.md +255 -0
- package/bin/skill-rails.js +4 -0
- package/dist/api.d.ts +38 -0
- package/dist/api.js +73 -0
- package/dist/api.js.map +1 -0
- package/dist/cli.d.ts +2 -0
- package/dist/cli.js +112 -0
- package/dist/cli.js.map +1 -0
- package/dist/engine.d.ts +18 -0
- package/dist/engine.js +312 -0
- package/dist/engine.js.map +1 -0
- package/dist/expressions.d.ts +12 -0
- package/dist/expressions.js +44 -0
- package/dist/expressions.js.map +1 -0
- package/dist/flow.d.ts +11 -0
- package/dist/flow.js +137 -0
- package/dist/flow.js.map +1 -0
- package/dist/mcp.d.ts +5 -0
- package/dist/mcp.js +37 -0
- package/dist/mcp.js.map +1 -0
- package/dist/run.d.ts +6 -0
- package/dist/run.js +67 -0
- package/dist/run.js.map +1 -0
- package/dist/schema.d.ts +10 -0
- package/dist/schema.js +15 -0
- package/dist/schema.js.map +1 -0
- package/dist/state.d.ts +6 -0
- package/dist/state.js +24 -0
- package/dist/state.js.map +1 -0
- package/dist/testing.d.ts +50 -0
- package/dist/testing.js +233 -0
- package/dist/testing.js.map +1 -0
- package/dist/types.d.ts +200 -0
- package/dist/types.js +2 -0
- package/dist/types.js.map +1 -0
- package/docs/format.md +256 -0
- package/docs/testing.md +100 -0
- package/examples/hello/flow.yaml +32 -0
- package/examples/hello/tests/hello.test.yaml +22 -0
- package/examples/open-pr/flow.yaml +87 -0
- package/examples/open-pr/prompts/text.md +26 -0
- package/examples/open-pr/scripts/body-file.sh +10 -0
- package/examples/open-pr/scripts/context.sh +21 -0
- package/examples/open-pr/scripts/create.sh +6 -0
- package/examples/open-pr/scripts/push.sh +8 -0
- package/examples/open-pr/tests/open-pr.test.yaml +42 -0
- package/examples/open-pr/tests/stubs/gh +9 -0
- package/package.json +72 -0
- package/schema/flow.schema.json +440 -0
- package/skills/create-skill-rails/SKILL.md +72 -0
- package/skills/create-skill-rails/template/SKILL.md +24 -0
- package/skills/migrate-to-skill-rails/SKILL.md +78 -0
- package/skills/run-skill-rails/SKILL.md +63 -0
package/docs/format.md
ADDED
|
@@ -0,0 +1,256 @@
|
|
|
1
|
+
# The flow format
|
|
2
|
+
|
|
3
|
+
A flow is a YAML file, checked against [`schema/flow.schema.json`](../schema/flow.schema.json).
|
|
4
|
+
The runner goes through its steps in order.
|
|
5
|
+
It runs the `run` and `stop` steps itself, and it gives the `skill`, `prompt` and `ask` steps to the agent, one at a time.
|
|
6
|
+
|
|
7
|
+
```yaml
|
|
8
|
+
name: open-pr # kebab-case; the state file and the done command use it
|
|
9
|
+
description: Open the PR of the current branch.
|
|
10
|
+
inputs:
|
|
11
|
+
auto:
|
|
12
|
+
type: boolean # string (default), boolean or number
|
|
13
|
+
default: false
|
|
14
|
+
description: Run with no questions.
|
|
15
|
+
steps:
|
|
16
|
+
- id: context
|
|
17
|
+
run: context.sh
|
|
18
|
+
- if: ${{ !steps.context.outputs.commits }}
|
|
19
|
+
stop: Nothing to merge.
|
|
20
|
+
outcome: failure
|
|
21
|
+
- id: text
|
|
22
|
+
prompt-file: prompts/text.md
|
|
23
|
+
output:
|
|
24
|
+
type: object
|
|
25
|
+
required: [title]
|
|
26
|
+
properties:
|
|
27
|
+
title: { type: string }
|
|
28
|
+
- id: create
|
|
29
|
+
run: create.sh
|
|
30
|
+
env:
|
|
31
|
+
TITLE: ${{ steps.text.outputs.title }}
|
|
32
|
+
```
|
|
33
|
+
|
|
34
|
+
## Folder layout
|
|
35
|
+
|
|
36
|
+
```text
|
|
37
|
+
my-skill/
|
|
38
|
+
SKILL.md # the short loop: start the flow, do each step, report it
|
|
39
|
+
flow.yaml # the order, the conditions and the inputs of the steps
|
|
40
|
+
scripts/ # the code of the run steps; this folder is in PATH
|
|
41
|
+
prompts/ # the instructions of the agent steps
|
|
42
|
+
```
|
|
43
|
+
|
|
44
|
+
## Steps
|
|
45
|
+
|
|
46
|
+
Every step can have an `id` (kebab-case, unique) and an `if`.
|
|
47
|
+
Agent steps need an `id`.
|
|
48
|
+
When `if` is false, the step is skipped, and `steps.<id>.outcome` is `skipped`.
|
|
49
|
+
|
|
50
|
+
### `run`
|
|
51
|
+
|
|
52
|
+
The runner runs the command with `bash -eo pipefail`, in the working directory of the flow.
|
|
53
|
+
|
|
54
|
+
```yaml
|
|
55
|
+
- id: build
|
|
56
|
+
run: build.sh
|
|
57
|
+
env:
|
|
58
|
+
TARGET: ${{ inputs.target }}
|
|
59
|
+
continue-on-error: true
|
|
60
|
+
```
|
|
61
|
+
|
|
62
|
+
- `scripts/` next to `flow.yaml` is first in `PATH`, so `run: build.sh` runs `scripts/build.sh`.
|
|
63
|
+
- `$FLOW_DIR` is the folder of `flow.yaml`.
|
|
64
|
+
- The command writes its outputs to the file `$FLOW_OUTPUT`, as in GitHub Actions: `key=value` lines, or `key<<EOF`, several lines, then `EOF`.
|
|
65
|
+
Later steps read them as `steps.<id>.outputs.<key>`.
|
|
66
|
+
- A `::warning::<text>` line on stdout becomes a note that the agent shows to the user.
|
|
67
|
+
- A command that fails ends the flow with its last 20 lines of stderr, unless the step has `continue-on-error: true`.
|
|
68
|
+
`steps.<id>.outcome` is `success` or `failure`.
|
|
69
|
+
- `env` values can be `${{ }}` expressions.
|
|
70
|
+
A list becomes one line per item, and an object becomes JSON.
|
|
71
|
+
- A `run` command must not hold `${{ }}`: the check refuses it.
|
|
72
|
+
A value can hold shell code (a commit message, a title), so pass every value with `env`.
|
|
73
|
+
|
|
74
|
+
#### Polling
|
|
75
|
+
|
|
76
|
+
A `run` step with `until` runs its command again until the condition is true: for example, wait for CI or a deploy.
|
|
77
|
+
|
|
78
|
+
```yaml
|
|
79
|
+
- id: ci
|
|
80
|
+
run: ci-state.sh # writes state=pending, success or failure
|
|
81
|
+
until: ${{ steps.ci.outputs.state != 'pending' }}
|
|
82
|
+
interval-seconds: 30 # default 30
|
|
83
|
+
timeout-minutes: 30 # default 30; the step fails after it
|
|
84
|
+
```
|
|
85
|
+
|
|
86
|
+
- In `until`, `steps.<id>` holds the result of the last run.
|
|
87
|
+
- A run that fails (exit code not 0) ends the polling as a failure: report "not ready yet" in an output, not with the exit code.
|
|
88
|
+
- The runner gives control back to the agent after 9 minutes (`SKILL_RAILS_WAIT_SLICE_SECONDS`), so that one command stays under the tool timeout of the agent.
|
|
89
|
+
The agent then gets a `wait` step: it reports it as done, with no output, and the polling goes on.
|
|
90
|
+
|
|
91
|
+
### `prompt`
|
|
92
|
+
|
|
93
|
+
The agent follows the instructions, then reports an output.
|
|
94
|
+
|
|
95
|
+
```yaml
|
|
96
|
+
- id: summary
|
|
97
|
+
prompt-file: prompts/summary.md
|
|
98
|
+
output:
|
|
99
|
+
type: object
|
|
100
|
+
required: [summary]
|
|
101
|
+
properties:
|
|
102
|
+
summary: { type: string, maxLength: 300 }
|
|
103
|
+
```
|
|
104
|
+
|
|
105
|
+
- `prompt` holds the instructions inline, and `prompt-file` names a Markdown file relative to `flow.yaml`.
|
|
106
|
+
Both can hold `${{ }}` expressions.
|
|
107
|
+
- `output` is a JSON Schema.
|
|
108
|
+
The runner validates the reported output and refuses it with the errors when it does not match.
|
|
109
|
+
With no `output`, the agent reports nothing, or any JSON object.
|
|
110
|
+
|
|
111
|
+
### `skill`
|
|
112
|
+
|
|
113
|
+
The agent invokes another skill with `with` as its arguments, then follows the optional `prompt` or `prompt-file`.
|
|
114
|
+
|
|
115
|
+
```yaml
|
|
116
|
+
- id: review
|
|
117
|
+
skill: code-review
|
|
118
|
+
with: the current branch
|
|
119
|
+
prompt: Report the number of findings.
|
|
120
|
+
output: { type: object, required: [findings], properties: { findings: { type: integer } } }
|
|
121
|
+
```
|
|
122
|
+
|
|
123
|
+
When the other skill only runs a script, call the script in a `run` step: it costs no model turn.
|
|
124
|
+
|
|
125
|
+
### `ask`
|
|
126
|
+
|
|
127
|
+
The agent asks the user one or more multiple-choice questions.
|
|
128
|
+
|
|
129
|
+
```yaml
|
|
130
|
+
- id: confirm
|
|
131
|
+
ask:
|
|
132
|
+
- id: answer
|
|
133
|
+
header: Confirm # 12 characters at most
|
|
134
|
+
question: Push the branch now?
|
|
135
|
+
options:
|
|
136
|
+
- { label: Push, description: Push and open the PR. }
|
|
137
|
+
- { label: Stop, description: Stop with no change. }
|
|
138
|
+
- id: checks
|
|
139
|
+
if: ${{ steps.list.outputs.commands[0] }}
|
|
140
|
+
header: Checks
|
|
141
|
+
question: Which checks do you want to run?
|
|
142
|
+
multiSelect: true
|
|
143
|
+
options:
|
|
144
|
+
- ${{ steps.list.outputs.commands }} # a list of { label, description }
|
|
145
|
+
- { label: None, description: Run no check. }
|
|
146
|
+
```
|
|
147
|
+
|
|
148
|
+
- Every option needs a `label` and a `description`.
|
|
149
|
+
An option can also have a `preview`: text that the question tool shows next to it, for example a draft to approve.
|
|
150
|
+
- An option can be an expression that gives a list of options.
|
|
151
|
+
- A question with a false `if` is left out.
|
|
152
|
+
When all the questions are left out, the step is skipped.
|
|
153
|
+
- The output has one property per question `id`: the label, or a list of labels for `multiSelect`.
|
|
154
|
+
The runner validates the labels.
|
|
155
|
+
|
|
156
|
+
- A question with `free: true` takes free text: the agent asks it in a normal message and reports the reply.
|
|
157
|
+
Its options are optional suggestions, and the output is a non-empty string.
|
|
158
|
+
|
|
159
|
+
### `foreach`
|
|
160
|
+
|
|
161
|
+
The runner runs the steps once for each item of a list.
|
|
162
|
+
|
|
163
|
+
```yaml
|
|
164
|
+
- id: comments
|
|
165
|
+
foreach: ${{ fromJSON(steps.fetch.outputs.comments) }}
|
|
166
|
+
steps:
|
|
167
|
+
- id: propose
|
|
168
|
+
prompt: 'Propose a fix for: ${{ item.body }} (comment ${{ loop.index }} of ${{ loop.count }})'
|
|
169
|
+
output: { type: object, required: [fix], properties: { fix: { type: string } } }
|
|
170
|
+
- id: decide
|
|
171
|
+
ask:
|
|
172
|
+
- { id: answer, header: Fix, question: 'Apply the fix?', options: [ { label: Apply, description: Apply it. }, { label: Skip, description: Skip it. } ] }
|
|
173
|
+
- if: ${{ steps.decide.outputs.answer == 'Apply' }}
|
|
174
|
+
run: reply.sh
|
|
175
|
+
env: { ID: '${{ item.id }}' }
|
|
176
|
+
- stop: '${{ steps.comments.outputs.count }} comments handled'
|
|
177
|
+
```
|
|
178
|
+
|
|
179
|
+
- `foreach` is an expression that gives a list, or a YAML list.
|
|
180
|
+
An empty list skips the steps.
|
|
181
|
+
- Inside, `item` is the current item, and `loop.index` (from 0) and `loop.count` give its place.
|
|
182
|
+
- The steps of an iteration see the steps before the `foreach`, and the steps of the same iteration.
|
|
183
|
+
Each iteration starts with no results.
|
|
184
|
+
- After the loop, `steps.<id>.outputs.count` is the number of items, and `steps.<id>.outputs.results` is the list of the iterations: `{ item, steps }`.
|
|
185
|
+
- A `stop` inside the loop ends the flow.
|
|
186
|
+
- A `break` step (`break: true`, often with an `if`) ends the loop, and the flow goes on after it.
|
|
187
|
+
`steps.<id>.outputs.done` is then the number of iterations that ran, and `broken` is true.
|
|
188
|
+
|
|
189
|
+
### `uses`
|
|
190
|
+
|
|
191
|
+
The runner runs another flow as one step.
|
|
192
|
+
|
|
193
|
+
```yaml
|
|
194
|
+
- id: ci
|
|
195
|
+
uses: ../diagnose-ci/flow.yaml # relative to this flow file
|
|
196
|
+
with:
|
|
197
|
+
pr: ${{ steps.context.outputs.pr_number }}
|
|
198
|
+
continue-on-error: true
|
|
199
|
+
```
|
|
200
|
+
|
|
201
|
+
- The other flow has its own inputs (from `with`), its own steps and its own folder (`flow.dir`, `scripts/`).
|
|
202
|
+
- Its end becomes the outputs of the step: `status` (`done` or `failed`), `message` (its stop message), and `steps` (its step results).
|
|
203
|
+
- When it fails, the flow fails, unless the step has `continue-on-error: true`.
|
|
204
|
+
- `check` loads the other flows too, and refuses flows that use each other.
|
|
205
|
+
|
|
206
|
+
### `stop`
|
|
207
|
+
|
|
208
|
+
The runner ends the flow with a message.
|
|
209
|
+
|
|
210
|
+
```yaml
|
|
211
|
+
- if: ${{ !steps.context.outputs.branch }}
|
|
212
|
+
stop: The current commit is a detached HEAD.
|
|
213
|
+
outcome: failure # success (default) or failure
|
|
214
|
+
```
|
|
215
|
+
|
|
216
|
+
The last step of a flow is usually a `stop` with the result.
|
|
217
|
+
A flow with no more steps ends with `done` and no message.
|
|
218
|
+
|
|
219
|
+
## Expressions
|
|
220
|
+
|
|
221
|
+
`${{ }}` expressions use the GitHub Actions syntax and rules, evaluated by [`@actions/expressions`](https://github.com/actions/languageservices/tree/main/expressions).
|
|
222
|
+
|
|
223
|
+
| Context | Value |
|
|
224
|
+
|---------|-------|
|
|
225
|
+
| `inputs.<name>` | A flow input. |
|
|
226
|
+
| `steps.<id>.outcome` | `success`, `failure` or `skipped`. |
|
|
227
|
+
| `steps.<id>.outputs.<key>` | An output of a `run` step, or a property of the output of an agent step. |
|
|
228
|
+
| `item`, `loop.index`, `loop.count` | Inside a `foreach`: the current item and its place. |
|
|
229
|
+
| `env.<NAME>` | An environment variable of the runner. |
|
|
230
|
+
| `flow.dir`, `flow.name` | The folder and the name of the flow. |
|
|
231
|
+
|
|
232
|
+
- The functions are the GitHub ones: `contains`, `startsWith`, `endsWith`, `format`, `join`, `toJSON`, `fromJSON`.
|
|
233
|
+
- `==` compares strings with no case.
|
|
234
|
+
- A value that is one expression keeps the type of its result (a list, a boolean).
|
|
235
|
+
Text with expressions becomes a string.
|
|
236
|
+
- `if:` can be a bare expression, with no `${{ }}`.
|
|
237
|
+
- A step that did not run has no outputs, so `steps.<id>.outputs.<key>` is `null`.
|
|
238
|
+
A step that depends on a skipped step is often skipped too.
|
|
239
|
+
|
|
240
|
+
## The protocol
|
|
241
|
+
|
|
242
|
+
Each command prints one JSON object.
|
|
243
|
+
|
|
244
|
+
| `status` | Meaning | The agent |
|
|
245
|
+
|----------|---------|-----------|
|
|
246
|
+
| `step` | A step waits for the agent: `id`, `type`, and `instructions`, `skill` and `args`, or `questions`, with `output`. | Does the step, then reports it with `done`. |
|
|
247
|
+
| `step` with `type: wait` | A polling step needs more time. | Reports it with `done` and no output, to keep waiting. |
|
|
248
|
+
| `invalid` | The output does not match: `errors`. | Corrects the output and reports it again. |
|
|
249
|
+
| `done` | The flow ended: `message`. | Tells the user the message. |
|
|
250
|
+
| `failed` | A step failed, a `stop` with `outcome: failure`, or a `--fail`: `message`. | Tells the user the message. |
|
|
251
|
+
| `error` | The flow file or a command is not valid: `errors`. | Tells the user the errors. |
|
|
252
|
+
|
|
253
|
+
A result can also have `notes`: the warnings of the run steps, which the agent shows to the user.
|
|
254
|
+
|
|
255
|
+
The state is a JSON file per flow name and working directory, in `$SKILL_RAILS_STATE_DIR` (default: the system temp folder).
|
|
256
|
+
`start` resets it.
|
package/docs/testing.md
ADDED
|
@@ -0,0 +1,100 @@
|
|
|
1
|
+
# Testing flows
|
|
2
|
+
|
|
3
|
+
`skill-rails test` runs a flow for real, with fixed answers in place of the agent.
|
|
4
|
+
It needs no model, no network and no API key, so a test takes milliseconds and gives the same result every time.
|
|
5
|
+
|
|
6
|
+
```bash
|
|
7
|
+
skill-rails test # every *.test.yaml under the current folder
|
|
8
|
+
skill-rails test skills/open-pr # one skill
|
|
9
|
+
skill-rails test --json # the results as JSON, for CI
|
|
10
|
+
```
|
|
11
|
+
|
|
12
|
+
## A test file
|
|
13
|
+
|
|
14
|
+
Put the tests of a flow in `tests/<name>.test.yaml`, next to `flow.yaml`.
|
|
15
|
+
A file has one test, or a `tests:` list whose items share the keys at the top.
|
|
16
|
+
In a test, `env` and `path` add to the shared ones, and the other keys replace them.
|
|
17
|
+
|
|
18
|
+
```yaml
|
|
19
|
+
flow: ../flow.yaml # the flow to test, relative to this file
|
|
20
|
+
fixture: fixtures/repo # copied into a new temp working directory
|
|
21
|
+
git: true # git init and commit the fixture (default: true)
|
|
22
|
+
setup: | # bash, run in the working directory before the flow
|
|
23
|
+
git checkout -q -b feat/x
|
|
24
|
+
path: [stubs] # folders put first in PATH, for stub commands
|
|
25
|
+
env: # environment variables of the run steps
|
|
26
|
+
GH_SCENARIO: failing
|
|
27
|
+
TMPDIR: '{{cwd}}/'
|
|
28
|
+
|
|
29
|
+
tests:
|
|
30
|
+
- name: failing checks go to the agent
|
|
31
|
+
inputs: { pr: '42' }
|
|
32
|
+
answers: # the agent output of each step, by step id
|
|
33
|
+
diagnose: { applied: 1, skipped: 0, files: [src/a.ts] }
|
|
34
|
+
expect:
|
|
35
|
+
status: done
|
|
36
|
+
message: '/Applied fixes: 1/'
|
|
37
|
+
steps: { gather: success, fix: skipped }
|
|
38
|
+
outputs: { gather.failing: '2' }
|
|
39
|
+
files: { diagnose-ci-42.log: '/Run: 123/' }
|
|
40
|
+
```
|
|
41
|
+
|
|
42
|
+
## Answers
|
|
43
|
+
|
|
44
|
+
`answers` maps each agent step id (`prompt`, `skill` and `ask` steps) to the output that the agent would report.
|
|
45
|
+
|
|
46
|
+
- An `ask` answer has one property per question id: `{ answer: Write it }`.
|
|
47
|
+
- A list gives one answer per occurrence of the step, in order: a step in a `foreach` comes back once per item.
|
|
48
|
+
`decide: [{ answer: Fix }, { answer: Skip }]`.
|
|
49
|
+
A single answer is used for every occurrence.
|
|
50
|
+
- `$files` writes files in the working directory before the answer, for an agent step that changes files: `{ ok: true, $files: { notes.md: hello } }`.
|
|
51
|
+
- `$fail` fails the step, as `done --fail` does: `{ $fail: The user stopped. }`.
|
|
52
|
+
- `{{cwd}}` is the temp working directory, and `{{dir}}` is the folder of the test file.
|
|
53
|
+
They work in `answers`, `env` and `inputs`.
|
|
54
|
+
|
|
55
|
+
The runner validates each answer against the output schema of its step, as it does for a real agent.
|
|
56
|
+
|
|
57
|
+
## Expectations
|
|
58
|
+
|
|
59
|
+
| Key | Checks |
|
|
60
|
+
|-----|--------|
|
|
61
|
+
| `status` | `done`, `failed` or `error`. |
|
|
62
|
+
| `message` | The final message. |
|
|
63
|
+
| `steps` | The outcome of each step: `success`, `failure` or `skipped`. A step that the flow never reached is `not reached`. |
|
|
64
|
+
| `outputs` | `<step id>.<key>`: an output of a run step, or a property of an agent output. |
|
|
65
|
+
| `files` | A file of the working directory: `exists`, `absent`, an exact content, or a regular expression. |
|
|
66
|
+
| `notes` | The `::warning::` notes of the run steps. |
|
|
67
|
+
|
|
68
|
+
A value that starts and ends with `/` is a regular expression.
|
|
69
|
+
Quote it in YAML when it holds `: ` or ` #`.
|
|
70
|
+
|
|
71
|
+
## Why a test fails
|
|
72
|
+
|
|
73
|
+
- The flow asks for a step that has no answer: the path of the flow changed.
|
|
74
|
+
- An answer is never used: the flow skipped a step that the test expects.
|
|
75
|
+
- An answer does not match the output schema of its step.
|
|
76
|
+
- An expectation does not match.
|
|
77
|
+
|
|
78
|
+
## Stub commands
|
|
79
|
+
|
|
80
|
+
A stub is a script in a folder of `path`, with the name of the command that it replaces.
|
|
81
|
+
It answers the calls of the flow, and refuses the others so that a new call is visible:
|
|
82
|
+
|
|
83
|
+
```bash
|
|
84
|
+
#!/usr/bin/env bash
|
|
85
|
+
# stubs/gh
|
|
86
|
+
case "$*" in
|
|
87
|
+
"repo view"*) echo main ;;
|
|
88
|
+
"pr view"*) exit 1 ;; # no open PR
|
|
89
|
+
"pr create"*) echo "https://github.com/acme/app/pull/7" ;;
|
|
90
|
+
*) echo "unexpected gh call: $*" >&2; exit 1 ;;
|
|
91
|
+
esac
|
|
92
|
+
```
|
|
93
|
+
|
|
94
|
+
Use an environment variable to choose a scenario, for example `GH_SCENARIO: failing`.
|
|
95
|
+
|
|
96
|
+
## What a test does not check
|
|
97
|
+
|
|
98
|
+
A test checks what the flow does with the agent's answers: the order, the conditions, the scripts, the outputs and the files.
|
|
99
|
+
It does not check the quality of the agent's work (a diagnosis, a draft, a title).
|
|
100
|
+
Check that with model evals, separately.
|
|
@@ -0,0 +1,32 @@
|
|
|
1
|
+
# The smallest useful flow: a shell step, a question, a prompt with a checked output, and an end.
|
|
2
|
+
name: hello
|
|
3
|
+
inputs:
|
|
4
|
+
who:
|
|
5
|
+
type: string
|
|
6
|
+
default: world
|
|
7
|
+
|
|
8
|
+
steps:
|
|
9
|
+
- id: greet
|
|
10
|
+
run: echo "greeting=Hello, $WHO" >> "$FLOW_OUTPUT"
|
|
11
|
+
env:
|
|
12
|
+
WHO: ${{ inputs.who }}
|
|
13
|
+
|
|
14
|
+
- id: mood
|
|
15
|
+
ask:
|
|
16
|
+
- id: answer
|
|
17
|
+
header: Mood
|
|
18
|
+
question: ${{ steps.greet.outputs.greeting }}! How is your day?
|
|
19
|
+
options:
|
|
20
|
+
- { label: Good, description: The day goes well. }
|
|
21
|
+
- { label: Bad, description: The day does not go well. }
|
|
22
|
+
|
|
23
|
+
- id: poem
|
|
24
|
+
if: ${{ steps.mood.outputs.answer == 'Good' }}
|
|
25
|
+
prompt: Write a two-line poem about a good day.
|
|
26
|
+
output:
|
|
27
|
+
type: object
|
|
28
|
+
required: [poem]
|
|
29
|
+
properties:
|
|
30
|
+
poem: { type: string }
|
|
31
|
+
|
|
32
|
+
- stop: ${{ steps.poem.outputs.poem || 'Tomorrow will be better.' }}
|
|
@@ -0,0 +1,22 @@
|
|
|
1
|
+
flow: ../flow.yaml
|
|
2
|
+
git: false
|
|
3
|
+
|
|
4
|
+
tests:
|
|
5
|
+
- name: a good day gets a poem
|
|
6
|
+
inputs: { who: team }
|
|
7
|
+
answers:
|
|
8
|
+
mood: { answer: Good }
|
|
9
|
+
poem: { poem: Sun on the desk. }
|
|
10
|
+
expect:
|
|
11
|
+
status: done
|
|
12
|
+
message: Sun on the desk.
|
|
13
|
+
outputs:
|
|
14
|
+
greet.greeting: Hello, team
|
|
15
|
+
|
|
16
|
+
- name: a bad day skips the poem
|
|
17
|
+
answers:
|
|
18
|
+
mood: { answer: Bad }
|
|
19
|
+
expect:
|
|
20
|
+
status: done
|
|
21
|
+
message: /better/
|
|
22
|
+
steps: { poem: skipped }
|
|
@@ -0,0 +1,87 @@
|
|
|
1
|
+
# Open or update the GitHub pull request of the current branch.
|
|
2
|
+
# The runner gathers the git context, pushes, and calls gh; the agent writes the title and the body.
|
|
3
|
+
name: open-pr
|
|
4
|
+
description: Create or update the GitHub pull request of the current branch.
|
|
5
|
+
|
|
6
|
+
inputs:
|
|
7
|
+
auto:
|
|
8
|
+
type: boolean
|
|
9
|
+
default: false
|
|
10
|
+
description: Run unattended, with no questions. A new PR is always a draft.
|
|
11
|
+
|
|
12
|
+
steps:
|
|
13
|
+
- id: context
|
|
14
|
+
run: context.sh
|
|
15
|
+
|
|
16
|
+
- if: ${{ !steps.context.outputs.branch }}
|
|
17
|
+
stop: The current commit is a detached HEAD. Create a branch first.
|
|
18
|
+
outcome: failure
|
|
19
|
+
|
|
20
|
+
- if: ${{ steps.context.outputs.branch == steps.context.outputs.base }}
|
|
21
|
+
stop: The current branch is the base branch. Use a separate branch.
|
|
22
|
+
outcome: failure
|
|
23
|
+
|
|
24
|
+
- if: ${{ !steps.context.outputs.commits }}
|
|
25
|
+
stop: The branch has no commits ahead of its base branch, so there is nothing to merge.
|
|
26
|
+
outcome: failure
|
|
27
|
+
|
|
28
|
+
- if: ${{ inputs.auto && steps.context.outputs.pr_number }}
|
|
29
|
+
stop: 'A PR already exists: ${{ steps.context.outputs.pr_url }}'
|
|
30
|
+
|
|
31
|
+
- id: existing
|
|
32
|
+
if: ${{ !inputs.auto && steps.context.outputs.pr_number }}
|
|
33
|
+
ask:
|
|
34
|
+
- id: answer
|
|
35
|
+
header: Existing PR
|
|
36
|
+
question: 'A PR already exists: ${{ steps.context.outputs.pr_url }}. Rewrite its title and description?'
|
|
37
|
+
options:
|
|
38
|
+
- { label: Rewrite, description: Rebuild the title and the body. Manual edits are lost. }
|
|
39
|
+
- { label: Keep, description: Push the new commits only. }
|
|
40
|
+
|
|
41
|
+
- id: draft
|
|
42
|
+
if: ${{ !inputs.auto && !steps.context.outputs.pr_number }}
|
|
43
|
+
ask:
|
|
44
|
+
- id: answer
|
|
45
|
+
header: Draft
|
|
46
|
+
question: Open the PR as a draft or ready for review?
|
|
47
|
+
options:
|
|
48
|
+
- { label: Draft, description: Open the PR as a draft. }
|
|
49
|
+
- { label: Ready, description: Open the PR ready for review. }
|
|
50
|
+
|
|
51
|
+
- id: push
|
|
52
|
+
run: push.sh
|
|
53
|
+
|
|
54
|
+
- if: ${{ steps.existing.outputs.answer == 'Keep' }}
|
|
55
|
+
stop: 'Pushed. The PR is unchanged: ${{ steps.context.outputs.pr_url }}'
|
|
56
|
+
|
|
57
|
+
- id: body-file
|
|
58
|
+
run: body-file.sh
|
|
59
|
+
env:
|
|
60
|
+
TEMPLATE: ${{ steps.context.outputs.template }}
|
|
61
|
+
|
|
62
|
+
- id: text
|
|
63
|
+
prompt-file: prompts/text.md
|
|
64
|
+
output:
|
|
65
|
+
type: object
|
|
66
|
+
required: [title]
|
|
67
|
+
properties:
|
|
68
|
+
title: { type: string, maxLength: 72 }
|
|
69
|
+
|
|
70
|
+
- id: create
|
|
71
|
+
if: ${{ !steps.context.outputs.pr_number }}
|
|
72
|
+
run: create.sh
|
|
73
|
+
env:
|
|
74
|
+
TITLE: ${{ steps.text.outputs.title }}
|
|
75
|
+
BASE: ${{ steps.context.outputs.base }}
|
|
76
|
+
BODY: ${{ steps.body-file.outputs.file }}
|
|
77
|
+
DRAFT: ${{ inputs.auto || steps.draft.outputs.answer == 'Draft' }}
|
|
78
|
+
|
|
79
|
+
- id: update
|
|
80
|
+
if: ${{ steps.context.outputs.pr_number }}
|
|
81
|
+
run: gh pr edit "$PR" --title "$TITLE" --body-file "$BODY"
|
|
82
|
+
env:
|
|
83
|
+
PR: ${{ steps.context.outputs.pr_number }}
|
|
84
|
+
TITLE: ${{ steps.text.outputs.title }}
|
|
85
|
+
BODY: ${{ steps.body-file.outputs.file }}
|
|
86
|
+
|
|
87
|
+
- stop: '${{ steps.update.outcome == ''success'' && ''PR updated'' || ''PR created'' }}: ${{ steps.create.outputs.url || steps.context.outputs.pr_url }}'
|
|
@@ -0,0 +1,26 @@
|
|
|
1
|
+
Write the pull request title and body.
|
|
2
|
+
|
|
3
|
+
1. Read `${{ steps.body-file.outputs.file }}` and fill it in place with the Edit tool.
|
|
4
|
+
${{ steps.context.outputs.template && 'It is the PR template: keep every line that you do not fill, and every HTML comment.' || '' }}
|
|
5
|
+
- Start with one sentence on the goal of the PR, then 2–4 short bullet points on what it does and why.
|
|
6
|
+
- Do not describe how: no function names and no file-by-file lists.
|
|
7
|
+
- Fill the testing section with 1–3 manual steps, or "No manual testing required".
|
|
8
|
+
2. Write the title: under 72 characters, in the imperative mood, in the format of the recent commits of the base branch.
|
|
9
|
+
|
|
10
|
+
Commits of the branch:
|
|
11
|
+
|
|
12
|
+
```text
|
|
13
|
+
${{ steps.context.outputs.commits }}
|
|
14
|
+
```
|
|
15
|
+
|
|
16
|
+
Changed files:
|
|
17
|
+
|
|
18
|
+
```text
|
|
19
|
+
${{ steps.context.outputs.files }}
|
|
20
|
+
```
|
|
21
|
+
|
|
22
|
+
Recent commits of the base branch:
|
|
23
|
+
|
|
24
|
+
```text
|
|
25
|
+
${{ steps.context.outputs.recent }}
|
|
26
|
+
```
|
|
@@ -0,0 +1,10 @@
|
|
|
1
|
+
#!/usr/bin/env bash
|
|
2
|
+
# Starts the PR body from the template, or from a short default.
|
|
3
|
+
set -eo pipefail
|
|
4
|
+
file="$(mktemp "${TMPDIR:-/tmp}/skill-rails-pr-body.XXXXXX")"
|
|
5
|
+
if [ -n "$TEMPLATE" ]; then
|
|
6
|
+
cp "$TEMPLATE" "$file"
|
|
7
|
+
else
|
|
8
|
+
printf '## Summary\n\n[1 sentence on the goal, then 2-4 bullet points]\n\n## Testing\n\n[How to test, or "No manual testing required"]\n' > "$file"
|
|
9
|
+
fi
|
|
10
|
+
echo "file=$file" >> "$FLOW_OUTPUT"
|
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
#!/usr/bin/env bash
|
|
2
|
+
# The branch, its base, its open PR, the commits, the changed files and the PR template.
|
|
3
|
+
set -eo pipefail
|
|
4
|
+
branch="$(git branch --show-current)"
|
|
5
|
+
default="$(gh repo view --json defaultBranchRef --jq .defaultBranchRef.name)"
|
|
6
|
+
pr="$(gh pr view --json number,url,baseRefName,state --jq 'select(.state == "OPEN") | [.number, .url, .baseRefName] | @tsv' 2>/dev/null || true)"
|
|
7
|
+
IFS=$'\t' read -r number url pr_base <<<"$pr"
|
|
8
|
+
base="${pr_base:-$default}"
|
|
9
|
+
git fetch --quiet origin "$base" || echo "::warning::Could not fetch origin/$base: the base may be stale."
|
|
10
|
+
merge_base="$(git merge-base "origin/$base" HEAD 2>/dev/null || git merge-base "$base" HEAD)"
|
|
11
|
+
template=""
|
|
12
|
+
for f in .github/PULL_REQUEST_TEMPLATE.md .github/pull_request_template.md PULL_REQUEST_TEMPLATE.md docs/PULL_REQUEST_TEMPLATE.md; do
|
|
13
|
+
if [ -f "$f" ]; then template="$f"; break; fi
|
|
14
|
+
done
|
|
15
|
+
{
|
|
16
|
+
printf '%s\n' "branch=$branch" "base=$base" "pr_number=$number" "pr_url=$url" "template=$template"
|
|
17
|
+
echo 'commits<<EOF'; git log "$merge_base..HEAD" --oneline; echo EOF
|
|
18
|
+
echo 'files<<EOF'; git diff "$merge_base..HEAD" --name-only; echo EOF
|
|
19
|
+
echo 'recent<<EOF'; git log "origin/$base" --oneline -10 2>/dev/null || true; echo EOF
|
|
20
|
+
} >> "$FLOW_OUTPUT"
|
|
21
|
+
if [ -n "$(git status --short)" ]; then echo "::warning::The uncommitted changes are not part of the PR."; fi
|
|
@@ -0,0 +1,6 @@
|
|
|
1
|
+
#!/usr/bin/env bash
|
|
2
|
+
# Creates the PR with the body that the agent wrote.
|
|
3
|
+
set -eo pipefail
|
|
4
|
+
args=(--title "$TITLE" --base "$BASE" --body-file "$BODY")
|
|
5
|
+
if [ "$DRAFT" = true ]; then args+=(--draft); fi
|
|
6
|
+
echo "url=$(gh pr create "${args[@]}" | tail -n 1)" >> "$FLOW_OUTPUT"
|
|
@@ -0,0 +1,42 @@
|
|
|
1
|
+
flow: ../flow.yaml
|
|
2
|
+
path: [stubs]
|
|
3
|
+
env:
|
|
4
|
+
GIT_AUTHOR_NAME: test
|
|
5
|
+
GIT_AUTHOR_EMAIL: test@example.com
|
|
6
|
+
GIT_COMMITTER_NAME: test
|
|
7
|
+
GIT_COMMITTER_EMAIL: test@example.com
|
|
8
|
+
# A local bare remote, and a branch with one commit ahead of main.
|
|
9
|
+
setup: |
|
|
10
|
+
remote="$(mktemp -d)/origin.git"
|
|
11
|
+
git init -q --bare "$remote"
|
|
12
|
+
git remote add origin "$remote"
|
|
13
|
+
git push -q origin main
|
|
14
|
+
git checkout -q -b feat/add-a
|
|
15
|
+
echo a > a.txt
|
|
16
|
+
git add a.txt
|
|
17
|
+
git commit -q -m "feat: add a"
|
|
18
|
+
|
|
19
|
+
tests:
|
|
20
|
+
- name: interactive, new draft PR
|
|
21
|
+
answers:
|
|
22
|
+
draft: { answer: Draft }
|
|
23
|
+
text: { title: 'feat: add a' }
|
|
24
|
+
expect:
|
|
25
|
+
status: done
|
|
26
|
+
message: 'PR created: https://github.com/acme/app/pull/7'
|
|
27
|
+
steps: { existing: skipped, push: success, update: skipped }
|
|
28
|
+
|
|
29
|
+
- name: unattended, no questions
|
|
30
|
+
inputs: { auto: true }
|
|
31
|
+
answers:
|
|
32
|
+
text: { title: 'feat: add a' }
|
|
33
|
+
expect:
|
|
34
|
+
status: done
|
|
35
|
+
steps: { draft: skipped, create: success }
|
|
36
|
+
|
|
37
|
+
- name: stops on the base branch
|
|
38
|
+
setup: 'true'
|
|
39
|
+
answers: {}
|
|
40
|
+
expect:
|
|
41
|
+
status: failed
|
|
42
|
+
message: /base branch/
|
|
@@ -0,0 +1,9 @@
|
|
|
1
|
+
#!/usr/bin/env bash
|
|
2
|
+
# A stub of gh: no open PR, the default branch is main, and pr create prints a URL.
|
|
3
|
+
case "$*" in
|
|
4
|
+
"repo view"*) echo main ;;
|
|
5
|
+
"pr view"*) exit 1 ;;
|
|
6
|
+
"pr create"*) echo "https://github.com/acme/app/pull/7" ;;
|
|
7
|
+
"pr edit"*) exit 0 ;;
|
|
8
|
+
*) echo "unexpected gh call: $*" >&2; exit 1 ;;
|
|
9
|
+
esac
|