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.
Files changed (57) hide show
  1. package/.claude-plugin/marketplace.json +16 -0
  2. package/.claude-plugin/plugin.json +16 -0
  3. package/.mcp.json +8 -0
  4. package/LICENSE +21 -0
  5. package/README.md +255 -0
  6. package/bin/skill-rails.js +4 -0
  7. package/dist/api.d.ts +38 -0
  8. package/dist/api.js +73 -0
  9. package/dist/api.js.map +1 -0
  10. package/dist/cli.d.ts +2 -0
  11. package/dist/cli.js +112 -0
  12. package/dist/cli.js.map +1 -0
  13. package/dist/engine.d.ts +18 -0
  14. package/dist/engine.js +312 -0
  15. package/dist/engine.js.map +1 -0
  16. package/dist/expressions.d.ts +12 -0
  17. package/dist/expressions.js +44 -0
  18. package/dist/expressions.js.map +1 -0
  19. package/dist/flow.d.ts +11 -0
  20. package/dist/flow.js +137 -0
  21. package/dist/flow.js.map +1 -0
  22. package/dist/mcp.d.ts +5 -0
  23. package/dist/mcp.js +37 -0
  24. package/dist/mcp.js.map +1 -0
  25. package/dist/run.d.ts +6 -0
  26. package/dist/run.js +67 -0
  27. package/dist/run.js.map +1 -0
  28. package/dist/schema.d.ts +10 -0
  29. package/dist/schema.js +15 -0
  30. package/dist/schema.js.map +1 -0
  31. package/dist/state.d.ts +6 -0
  32. package/dist/state.js +24 -0
  33. package/dist/state.js.map +1 -0
  34. package/dist/testing.d.ts +50 -0
  35. package/dist/testing.js +233 -0
  36. package/dist/testing.js.map +1 -0
  37. package/dist/types.d.ts +200 -0
  38. package/dist/types.js +2 -0
  39. package/dist/types.js.map +1 -0
  40. package/docs/format.md +256 -0
  41. package/docs/testing.md +100 -0
  42. package/examples/hello/flow.yaml +32 -0
  43. package/examples/hello/tests/hello.test.yaml +22 -0
  44. package/examples/open-pr/flow.yaml +87 -0
  45. package/examples/open-pr/prompts/text.md +26 -0
  46. package/examples/open-pr/scripts/body-file.sh +10 -0
  47. package/examples/open-pr/scripts/context.sh +21 -0
  48. package/examples/open-pr/scripts/create.sh +6 -0
  49. package/examples/open-pr/scripts/push.sh +8 -0
  50. package/examples/open-pr/tests/open-pr.test.yaml +42 -0
  51. package/examples/open-pr/tests/stubs/gh +9 -0
  52. package/package.json +72 -0
  53. package/schema/flow.schema.json +440 -0
  54. package/skills/create-skill-rails/SKILL.md +72 -0
  55. package/skills/create-skill-rails/template/SKILL.md +24 -0
  56. package/skills/migrate-to-skill-rails/SKILL.md +78 -0
  57. 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.
@@ -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,8 @@
1
+ #!/usr/bin/env bash
2
+ # Pushes the current branch. It never force-pushes.
3
+ set -eo pipefail
4
+ if git rev-parse --abbrev-ref --symbolic-full-name '@{u}' >/dev/null 2>&1; then
5
+ git push --quiet
6
+ else
7
+ git push --quiet -u origin HEAD
8
+ fi
@@ -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