@pixelfactoryio/theway 0.14.0 → 0.15.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/README.md +2 -0
- package/dist/theway.js +1156 -291
- package/package.json +5 -2
- package/plugin/.claude-plugin/plugin.json +1 -1
- package/plugin/commands/archive.md +3 -2
- package/plugin/commands/document.md +4 -2
- package/plugin/commands/engineering.md +2 -130
- package/plugin/commands/list.md +3 -2
- package/plugin/commands/workflow.md +87 -37
- package/plugin/home/config.yaml +7 -36
- package/plugin/home/prompts/ci-diagnose.md +15 -0
- package/plugin/home/prompts/ci-fix.md +7 -0
- package/plugin/home/prompts/ci-wait.md +5 -0
- package/plugin/home/prompts/fix-check.md +7 -0
- package/plugin/home/{templates → prompts}/fix-spec-template.md +7 -1
- package/plugin/home/prompts/fix.md +9 -0
- package/plugin/home/prompts/grounding.md +7 -0
- package/plugin/home/prompts/implement.md +9 -0
- package/plugin/home/prompts/implementability.md +12 -0
- package/plugin/home/{templates → prompts}/light-spec-template.md +3 -1
- package/plugin/home/prompts/open-pr.md +5 -0
- package/plugin/home/prompts/reviewer.md +7 -0
- package/plugin/home/prompts/scaffold-light.md +38 -0
- package/plugin/home/prompts/scaffold-rules.md +22 -0
- package/plugin/home/prompts/scaffold.md +55 -0
- package/plugin/home/prompts/spec-fix.md +5 -0
- package/plugin/home/{standards → prompts}/spec-investigation.md +6 -5
- package/plugin/home/prompts/spec-reviewer.md +16 -0
- package/plugin/home/{templates → prompts}/spec-template.md +10 -1
- package/plugin/home/prompts/spec-triage.md +5 -0
- package/plugin/home/{standards → prompts}/tamm-framework.md +8 -0
- package/plugin/home/{templates → prompts}/tasks-template.md +3 -0
- package/plugin/home/prompts/triage.md +3 -0
- package/plugin/home/prompts/verdicts.md +11 -0
- package/plugin/home/schemas/step.v1.json +449 -0
- package/plugin/home/schemas/workflow.v1.json +110 -0
- package/plugin/home/standards/commits.md +2 -2
- package/plugin/home/standards/develop.md +3 -3
- package/plugin/home/standards/git-host.md +1 -1
- package/plugin/home/standards/interaction.md +4 -4
- package/plugin/home/standards/sre.md +2 -2
- package/plugin/home/standards/web-development.md +3 -0
- package/plugin/home/steps/implement.yaml +7 -0
- package/plugin/home/steps/pr.yaml +21 -0
- package/plugin/home/steps/review.yaml +25 -0
- package/plugin/home/steps/scaffold-light.yaml +7 -0
- package/plugin/home/steps/scaffold.yaml +7 -0
- package/plugin/home/steps/spec-review.yaml +26 -0
- package/plugin/home/templates/source-tree-template.md +5 -0
- package/plugin/home/templates/tech-stack-template.md +7 -0
- package/plugin/home/workflows/agents.yaml +4 -1
- package/plugin/home/workflows/develop.yaml +4 -1
- package/plugin/home/workflows/engineering-light.yaml +7 -0
- package/plugin/home/workflows/engineering.yaml +7 -0
- package/plugin/workflows/run-pipeline.js +466 -464
- package/plugin/home/standards/spec-review.md +0 -61
- /package/plugin/home/{lenses → prompts}/conformance.md +0 -0
- /package/plugin/home/{lenses → prompts}/correctness.md +0 -0
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@pixelfactoryio/theway",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.15.0",
|
|
4
4
|
"description": "A spec-first workflow for Claude Code",
|
|
5
5
|
"license": "MIT",
|
|
6
6
|
"repository": {
|
|
@@ -25,12 +25,15 @@
|
|
|
25
25
|
"scripts": {
|
|
26
26
|
"build": "bun build src/cli.ts --target=node --outfile dist/theway.js",
|
|
27
27
|
"typecheck": "tsc --noEmit -p .",
|
|
28
|
-
"test": "bun test"
|
|
28
|
+
"test": "bun test",
|
|
29
|
+
"lint:md": "git ls-files -z '*.md' ':!:CHANGELOG.md' | xargs -0 markdownlint-cli2"
|
|
29
30
|
},
|
|
30
31
|
"devDependencies": {
|
|
31
32
|
"@clack/prompts": "1.8.1",
|
|
32
33
|
"@types/node": "^22",
|
|
34
|
+
"ajv": "8.20.0",
|
|
33
35
|
"commander": "15.0.0",
|
|
36
|
+
"markdownlint-cli2": "0.24.0",
|
|
34
37
|
"typescript": "^5",
|
|
35
38
|
"yaml": "2.9.1"
|
|
36
39
|
}
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "theway",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.15.0",
|
|
4
4
|
"description": "theway writes a spec and a numbered task list before any code, then implements the tasks in your session or through agents that open a reviewed, CI-green pull request.",
|
|
5
5
|
"author": {
|
|
6
6
|
"name": "Amine",
|
|
@@ -4,13 +4,14 @@ author: Amine
|
|
|
4
4
|
allowed-tools: Bash(theway:*)
|
|
5
5
|
---
|
|
6
6
|
|
|
7
|
-
#
|
|
7
|
+
# theway: Archive Spec
|
|
8
8
|
|
|
9
9
|
Archive a completed spec by moving it to the archive folder with a timestamp.
|
|
10
10
|
|
|
11
11
|
## Locate the home
|
|
12
12
|
|
|
13
|
-
Run `theway path` and use the folder it prints as `<home>`, never a path from elsewhere:
|
|
13
|
+
Run `theway path` and use the folder it prints as `<home>`, never a path from elsewhere: theway files of the current project are stored in `<home>/projects/<key>/`: run `theway project` for its key and folder; never compute the key yourself.
|
|
14
|
+
|
|
14
15
|
- If `theway` is not found, tell the user to add the folder theway is installed in (`~/.local/bin` by default) to their `PATH`, or to run `npx --yes @pixelfactoryio/theway@latest install` then `/reload-plugins`, and stop.
|
|
15
16
|
- If any `theway` subcommand fails with `error: unknown command '<name>'`, the installed `theway` is older than these commands: tell the user to run `npx --yes @pixelfactoryio/theway@latest install` then `/reload-plugins` and stop.
|
|
16
17
|
- If a `theway` subcommand exits 1 otherwise, quote the error line it wrote to stderr and stop, unless the step that runs it says what to do instead. The steps that do are `validate-id` (fix the ID), `next-id` (fix the series ID) and `archive` (open tasks, `--force` on explicit acceptance). Not every error line starts with `theway:`: `validate-id` and `next-id` write `invalid change id '…'` and `archive` writes `Error: …`.
|
|
@@ -4,13 +4,14 @@ author: Amine
|
|
|
4
4
|
allowed-tools: Bash(theway:*)
|
|
5
5
|
---
|
|
6
6
|
|
|
7
|
-
#
|
|
7
|
+
# theway: Document Mode
|
|
8
8
|
|
|
9
9
|
**IMPORTANT:** Keep documentation practical and actionable, not verbose. Use code examples over explanations.
|
|
10
10
|
|
|
11
11
|
## Locate the home
|
|
12
12
|
|
|
13
|
-
Run `theway path` and use the folder it prints as `<home>`, never a path from elsewhere:
|
|
13
|
+
Run `theway path` and use the folder it prints as `<home>`, never a path from elsewhere: theway files of the current project are stored in `<home>/projects/<key>/`: run `theway project` for its key and folder; never compute the key yourself.
|
|
14
|
+
|
|
14
15
|
- If `theway` is not found, tell the user to add the folder theway is installed in (`~/.local/bin` by default) to their `PATH`, or to run `npx --yes @pixelfactoryio/theway@latest install` then `/reload-plugins`, and stop.
|
|
15
16
|
- If any `theway` subcommand fails with `error: unknown command '<name>'`, the installed `theway` is older than these commands: tell the user to run `npx --yes @pixelfactoryio/theway@latest install` then `/reload-plugins` and stop.
|
|
16
17
|
- If a `theway` subcommand exits 1 otherwise, quote the error line it wrote to stderr and stop, unless the step that runs it says what to do instead. The steps that do are `validate-id` (fix the ID), `next-id` (fix the series ID) and `archive` (open tasks, `--force` on explicit acceptance). Not every error line starts with `theway:`: `validate-id` and `next-id` write `invalid change id '…'` and `archive` writes `Error: …`.
|
|
@@ -47,6 +48,7 @@ Then, for each template below, read the template file, follow its frontmatter in
|
|
|
47
48
|
### Step 2: Additional Documentation
|
|
48
49
|
|
|
49
50
|
Create other documentation as needed:
|
|
51
|
+
|
|
50
52
|
- System architecture overviews
|
|
51
53
|
- Backend design and API contracts
|
|
52
54
|
- Frontend architecture and patterns
|
|
@@ -4,134 +4,6 @@ author: Amine
|
|
|
4
4
|
allowed-tools: Bash(theway:*)
|
|
5
5
|
---
|
|
6
6
|
|
|
7
|
-
#
|
|
7
|
+
# theway: Engineering
|
|
8
8
|
|
|
9
|
-
|
|
10
|
-
>
|
|
11
|
-
> Write only under `<change-dir>`, the change folder `theway path <change-id>` prints (Step 2). Throwaway probes, yours and the review critics' (Step 6), may also write to a temporary directory created with `mktemp -d`; the change files still go only under `<change-dir>`. Action words in the request ("rename X", "try the fix") describe what the spec should plan, not something to do now.
|
|
12
|
-
>
|
|
13
|
-
> Do **not** suggest entering plan mode — its approval step is a "start coding" trigger that collapses scaffolding into implementation.
|
|
14
|
-
|
|
15
|
-
## Locate the home
|
|
16
|
-
|
|
17
|
-
Run `theway path` and use the folder it prints as `<home>`, never a path from elsewhere: TheWay files of the current project are stored in `<home>/projects/<key>/`: run `theway project` for its key and folder; never compute the key yourself.
|
|
18
|
-
- If `theway` is not found, tell the user to add the folder theway is installed in (`~/.local/bin` by default) to their `PATH`, or to run `npx --yes @pixelfactoryio/theway@latest install` then `/reload-plugins`, and stop.
|
|
19
|
-
- If any `theway` subcommand fails with `error: unknown command '<name>'`, the installed `theway` is older than these commands: tell the user to run `npx --yes @pixelfactoryio/theway@latest install` then `/reload-plugins` and stop.
|
|
20
|
-
- If a `theway` subcommand exits 1 otherwise, quote the error line it wrote to stderr and stop, unless the step that runs it says what to do instead. The steps that do are `validate-id` (fix the ID), `next-id` (fix the series ID) and `archive` (open tasks, `--force` on explicit acceptance). Not every error line starts with `theway:`: `validate-id` and `next-id` write `invalid change id '…'` and `archive` writes `Error: …`.
|
|
21
|
-
- Quote every `theway: warning:` line in your report.
|
|
22
|
-
- Do not check for files under `<home>` before reading them. If a file under `<home>/standards/` or `<home>/templates/` does not exist, theway is not set up: tell the user to run `npx --yes @pixelfactoryio/theway@latest install` then `/reload-plugins` and stop.
|
|
23
|
-
|
|
24
|
-
## Invocation
|
|
25
|
-
|
|
26
|
-
```
|
|
27
|
-
/theway:engineering [--light] <request>
|
|
28
|
-
```
|
|
29
|
-
|
|
30
|
-
`--light` may stand anywhere in the arguments; given more than once, it counts once. The rest is the request, and the change ID when the request names one.
|
|
31
|
-
|
|
32
|
-
`--light` is the light path, for a small change with nothing to decide: a known cause, a local change, no public contract change. A change that needs decisions goes through `/theway:engineering` without `--light`: the light path escalates to it and never writes a full spec itself.
|
|
33
|
-
|
|
34
|
-
**Series with `--light`:** when the request asks for a series, for multiple sequential changes or to split into N changes, or the named change ID ends in `-NN`, stop before Step 1 and write nothing: report `a series is not a light change; run /theway:engineering without --light`, and the standards read: none.
|
|
35
|
-
|
|
36
|
-
Every step below states the full rule; a **With `--light`:** paragraph replaces it where the light path differs.
|
|
37
|
-
|
|
38
|
-
## Workflow
|
|
39
|
-
|
|
40
|
-
> Follow the conventions in `<home>/standards/interaction.md` (exploration, reporting and authority).
|
|
41
|
-
|
|
42
|
-
### Step 1: Load Config and Standards
|
|
43
|
-
|
|
44
|
-
Run `theway context engineering`. Read these files from `<home>`:
|
|
45
|
-
- `<home>/standards/tamm-framework.md` - TAMM framework
|
|
46
|
-
|
|
47
|
-
Then read every file its `standards` lists: these are the standards, the shipped opt-in ones that are enabled and yours, and the spec follows them.
|
|
48
|
-
|
|
49
|
-
From its `config`, where every value is already valid, take `engineering.review.rounds` (maximum review rounds in Step 6) and `engineering.review.model`.
|
|
50
|
-
|
|
51
|
-
### Step 2: Create Change Folder
|
|
52
|
-
|
|
53
|
-
Use naming convention: `add-*`, `update-*`, `refactor-*`, `remove-*`, `fix-*`
|
|
54
|
-
|
|
55
|
-
Example change IDs: `add-user-authentication`, `update-payment-api`, `fix-login-crash`
|
|
56
|
-
|
|
57
|
-
A `fix-` change fixes a bug: Steps 3, 4 and 6 (with `--light`: Steps 3 and 4) have rules of their own for it.
|
|
58
|
-
|
|
59
|
-
**Series naming**
|
|
60
|
-
|
|
61
|
-
- **Trigger:** the request is a series when the user asks for a series, for multiple sequential changes, or to "split into N changes", or when the argument passed already ends in `-NN`. In series mode the `<series-id>` is the argument without a trailing `-NN`, not a change ID.
|
|
62
|
-
- **Pattern:** every member is `<series-id>-NN` — a shared verb-prefixed kebab-case `<series-id>` (same `add-`/`update-`/`refactor-`/`remove-`/`fix-` rule) plus a zero-padded two-digit ordinal. The member IDs are exactly the ones `theway next-id` prints: from `01` for a new series, after the highest existing ordinal otherwise.
|
|
63
|
-
- **Member IDs:** run `theway next-id <series-id> --count <N>`, with `<N>` the number of members, and assign the IDs it prints in dependency order; never rename or renumber existing folders. On `invalid change id '…'`, fix the series ID from the reason and run it again; on `would go past -99`, stop and report it.
|
|
64
|
-
- **Forbidden:** topic-word suffixes (`add-user-auth-login`), and mixing standalone and series IDs in one series.
|
|
65
|
-
- **Example:** `add-user-auth-01`, `add-user-auth-02`, `add-user-auth-03`.
|
|
66
|
-
|
|
67
|
-
**Validate the ID before writing:** run `theway validate-id <change-id>` for a standalone change (`next-id` already validated a series' IDs), and fix the ID from the reason it prints until it exits 0, before writing any change folder.
|
|
68
|
-
|
|
69
|
-
**Locate the change folder:** once an ID is valid, run `theway path <change-id>` and use the folder it prints as `<change-dir>` for that change (one per member in a series). Every file of the change is written there.
|
|
70
|
-
|
|
71
|
-
**With `--light`:** When the request names a change ID, use it. There is no series naming. **Validate the ID before writing:** run `theway validate-id <change-id>`, never with `--series` (a light change is never a series member), and fix the ID from the reason it prints until it exits 0, before writing any change folder. **Locate the change folder:** once the ID is valid, run `theway path <change-id>` and use the folder it prints as `<change-dir>`. Every file of the change is written there.
|
|
72
|
-
|
|
73
|
-
### Step 3: Investigate
|
|
74
|
-
|
|
75
|
-
Investigate as `<home>/standards/spec-investigation.md` sets out. A question you cannot settle there becomes a question for the user, or an open point recorded in the spec. A request that contradicts a standard is an open question for the user.
|
|
76
|
-
|
|
77
|
-
For a `fix-` change, the recorded reproduction goes into the spec's Reproduction. When none of the three stop outcomes applies, continue to Step 4.
|
|
78
|
-
|
|
79
|
-
**With `--light`:** Investigate as `<home>/standards/spec-investigation.md` sets out. A question you cannot settle there is a decision: it escalates (below). The findings, and for a `fix-` change the recorded reproduction, go into the spec's Evidence, quoted. When none of the three stop outcomes applies, run the escalation check.
|
|
80
|
-
|
|
81
|
-
**Escalation check**, for every change, at the end of the investigation and before any change file is written. Escalate when the investigation finds a decision to make, a public contract change, a TAMM risk at Medium or High, or a request for a series. A request that contradicts a standard is a decision to make. A decision is a choice the code, the docs and the request do not settle; a public contract change is a change to a command, CLI, API, config key or file format that others rely on. Escalating writes no change file: report what was found, and tell the user to run `/theway:engineering` with the original request, without `--light`. Otherwise continue to Step 4.
|
|
82
|
-
|
|
83
|
-
### Step 4: Generate Documents from Templates
|
|
84
|
-
|
|
85
|
-
For each template below, read the template file, follow its frontmatter instructions (required_context, agent_role, workflow_steps, quality_standards, best_practices), and create the output file in `<change-dir>`:
|
|
86
|
-
|
|
87
|
-
| Template | Output |
|
|
88
|
-
|----------|--------|
|
|
89
|
-
| `<home>/templates/spec-template.md`, or `<home>/templates/fix-spec-template.md` for a `fix-` ID | `spec.md` |
|
|
90
|
-
| `<home>/templates/tasks-template.md` | `tasks.md` |
|
|
91
|
-
|
|
92
|
-
A `fix-` ID uses `fix-spec-template.md`; every other verb uses `spec-template.md`. In a `fix-` change, task 1 writes the regression test; re-running the reproduction is not a task, as it is part of Verify.
|
|
93
|
-
|
|
94
|
-
For a series, each member's `spec.md` carries one line directly under its H1 title:
|
|
95
|
-
`**Series:** <series-id> — NN of TOTAL, depends on <series-id>-(NN-1)` — `NN` is the member's ordinal from `next-id`, `TOTAL` the last ordinal it printed; the `01` member states no dependency.
|
|
96
|
-
|
|
97
|
-
**With `--light`:** The table is:
|
|
98
|
-
|
|
99
|
-
| Template | Output |
|
|
100
|
-
|----------|--------|
|
|
101
|
-
| `<home>/templates/light-spec-template.md` | `spec.md` |
|
|
102
|
-
| `<home>/templates/tasks-template.md` | `tasks.md` |
|
|
103
|
-
|
|
104
|
-
`spec.md` keeps the `**Mode:** light` line directly under its H1 title: `/theway:workflow` reads it. For a `fix-` change, Problem states the cause with file:line evidence, and Evidence holds the reproduction. `tasks.md` follows `tasks-template.md`'s rule for a light change. In a `fix-` change, task 1 writes the regression test; re-running the reproduction is not a task, as it is part of Verify. There is no series line and no `fix-spec-template.md`.
|
|
105
|
-
|
|
106
|
-
### Step 5: Optional Technical Design
|
|
107
|
-
|
|
108
|
-
If needed, create `<change-dir>/design.md` for:
|
|
109
|
-
- API contracts and data models
|
|
110
|
-
- Architecture decisions
|
|
111
|
-
- Technical diagrams and specs
|
|
112
|
-
|
|
113
|
-
**With `--light`:** Skip this step: a light change has no `design.md`.
|
|
114
|
-
|
|
115
|
-
### Step 6: Review
|
|
116
|
-
|
|
117
|
-
Check that the change can be implemented without guessing, before it is reported ready. Run this step only when Steps 3-5 left no open question; an open point recorded in the spec counts as one. Otherwise do not run it: the spec is not ready, and the Exit report says the review was not run. With `rounds: 0`, skip this step.
|
|
118
|
-
|
|
119
|
-
Review the change as `<home>/standards/spec-review.md` sets out, for up to `engineering.review.rounds` rounds, with both lenses. Each round spawns the grounding and the implementability critic in parallel, in a single message, with the Agent tool and `model` set to `engineering.review.model`. In a series, each round covers every member together.
|
|
120
|
-
|
|
121
|
-
After a round's fixes, a confirmed `decision` finding ends the step: each one is an open question, and the spec is not ready.
|
|
122
|
-
|
|
123
|
-
**With `--light`:** Run up to `engineering.review.rounds` review rounds with one grounding critic. With `rounds: 0`, skip this step. An open question would have escalated in Step 3, so there is none to wait for. Review the change as `<home>/standards/spec-review.md` sets out, with the grounding lens only, which then also reports a spec or task that contradicts a standard. Spawn the critic with the Agent tool and `model` set to `engineering.review.model`. A confirmed `decision` finding is an escalation, not an open question. Escalating after the review keeps the light files: tell the user to run `/theway:engineering <change-id>: <original request>`, without `--light`, which writes over them.
|
|
124
|
-
|
|
125
|
-
## Exit
|
|
126
|
-
|
|
127
|
-
Report the change folder, the findings that shaped the spec, the review outcome, and any question still open. A confirmed `decision` finding of Step 6 is an open question. If a question is open, stop after this report; the spec is not ready until it is answered. Every report, including a stop or an escalation, names the standards read in Step 1, by file name, or "none".
|
|
128
|
-
|
|
129
|
-
Report the review outcome as `<home>/standards/spec-review.md` sets it out. It can also read "not run because a question was already open". For a confirmed `decision`, its `Fix` column reads `open question:` followed by the question.
|
|
130
|
-
|
|
131
|
-
When a `fix-` change stopped in Step 3, report the stop as `<home>/standards/spec-investigation.md` sets it out: the user re-runs `/theway:engineering` with the new information.
|
|
132
|
-
|
|
133
|
-
**With `--light`:** Report the change folder, the findings that shaped the spec, and the review outcome. When a `fix-` change stopped in Step 3, report the stop as `<home>/standards/spec-investigation.md` sets it out: the user re-runs `/theway:engineering --light` with the new information. When the change escalated, report what was found and the command to run instead:
|
|
134
|
-
- from Step 3: no change folder was written; the user runs `/theway:engineering` with the original request, without `--light`;
|
|
135
|
-
- from Step 6: the confirmed `decision` findings, and `/theway:engineering <change-id>: <original request>`, which writes over the light files.
|
|
136
|
-
|
|
137
|
-
Report the review outcome as `<home>/standards/spec-review.md` sets it out. For a confirmed `decision`, its `Fix` column reads `escalated`. This paragraph replaces the full Exit's open-question sentences and its `open question:` `Fix` rule for a light run.
|
|
9
|
+
`/theway:engineering [--light] <request>` is `/theway:workflow --workflow engineering <request>`, or `--workflow engineering-light <request>` when `--light` is given (anywhere in the arguments, counted once). Invoke the `theway:workflow` skill with the Skill tool and those arguments, then follow it.
|
package/plugin/commands/list.md
CHANGED
|
@@ -4,11 +4,12 @@ author: Amine
|
|
|
4
4
|
allowed-tools: Bash(theway:*)
|
|
5
5
|
---
|
|
6
6
|
|
|
7
|
-
#
|
|
7
|
+
# theway: List Changes
|
|
8
8
|
|
|
9
9
|
## Locate the home
|
|
10
10
|
|
|
11
|
-
Run `theway path` and use the folder it prints as `<home>`, never a path from elsewhere:
|
|
11
|
+
Run `theway path` and use the folder it prints as `<home>`, never a path from elsewhere: theway files of the current project are stored in `<home>/projects/<key>/`: run `theway project` for its key and folder; never compute the key yourself.
|
|
12
|
+
|
|
12
13
|
- If `theway` is not found, tell the user to add the folder theway is installed in (`~/.local/bin` by default) to their `PATH`, or to run `npx --yes @pixelfactoryio/theway@latest install` then `/reload-plugins`, and stop.
|
|
13
14
|
- If any `theway` subcommand fails with `error: unknown command '<name>'`, the installed `theway` is older than these commands: tell the user to run `npx --yes @pixelfactoryio/theway@latest install` then `/reload-plugins` and stop.
|
|
14
15
|
- If a `theway` subcommand exits 1 otherwise, quote the error line it wrote to stderr and stop, unless the step that runs it says what to do instead. The steps that do are `validate-id` (fix the ID), `next-id` (fix the series ID) and `archive` (open tasks, `--force` on explicit acceptance). Not every error line starts with `theway:`: `validate-id` and `next-id` write `invalid change id '…'` and `archive` writes `Error: …`.
|
|
@@ -1,16 +1,19 @@
|
|
|
1
1
|
---
|
|
2
|
-
description: "Run changes through a YAML workflow
|
|
2
|
+
description: "Run changes, or a request, through a YAML workflow of steps, inline or through agents, and open a PR when the workflow pushes"
|
|
3
3
|
author: Amine
|
|
4
4
|
allowed-tools: Bash(theway:*)
|
|
5
5
|
---
|
|
6
6
|
|
|
7
|
-
#
|
|
7
|
+
# theway: Workflow
|
|
8
8
|
|
|
9
|
-
Run each change through one workflow: an ordered list of
|
|
9
|
+
Run each change through one workflow: an ordered list of entries, each a step or a gate, that `theway workflow` resolves from `<home>/projects/<key>/workflows/` or `<home>/workflows/`. A step is a step file (`steps/<name>.yaml`) whose tree of agents reads prompt files (`prompts/<name>.md`); `theway workflow` prints every step resolved into that tree. Steps with `agents: true` run through agents in the plugin workflow `theway:run-pipeline`; steps with `agents: false` and gates run inline, in this session. The default workflow, the shipped `develop`, runs one inline step that works on the working tree and commits nothing.
|
|
10
|
+
|
|
11
|
+
A workflow's `input`, which `theway workflow` prints, says what it takes. An `input: changes` workflow (`develop`, `agents`) takes change IDs and works on each change's feature branch. An `input: request` workflow (`engineering`, `engineering-light`, which `/theway:engineering` runs) takes a free-text request and writes only the change folders it creates: no branch, no commit, no push.
|
|
10
12
|
|
|
11
13
|
## Locate the home
|
|
12
14
|
|
|
13
|
-
Run `theway path` and use the folder it prints as `<home>`, never a path from elsewhere:
|
|
15
|
+
Run `theway path` and use the folder it prints as `<home>`, never a path from elsewhere: theway files of the current project are stored in `<home>/projects/<key>/`: run `theway project` for its key and folder; never compute the key yourself.
|
|
16
|
+
|
|
14
17
|
- If `theway` is not found, tell the user to add the folder theway is installed in (`~/.local/bin` by default) to their `PATH`, or to run `npx --yes @pixelfactoryio/theway@latest install` then `/reload-plugins`, and stop.
|
|
15
18
|
- If any `theway` subcommand fails with `error: unknown command '<name>'`, the installed `theway` is older than these commands: tell the user to run `npx --yes @pixelfactoryio/theway@latest install` then `/reload-plugins` and stop.
|
|
16
19
|
- If a `theway` subcommand exits 1 otherwise, quote the error line it wrote to stderr and stop, unless the step that runs it says what to do instead. The steps that do are `validate-id` (fix the ID), `next-id` (fix the series ID) and `archive` (open tasks, `--force` on explicit acceptance). Not every error line starts with `theway:`: `validate-id` and `next-id` write `invalid change id '…'` and `archive` writes `Error: …`.
|
|
@@ -20,33 +23,39 @@ Run `theway path` and use the folder it prints as `<home>`, never a path from el
|
|
|
20
23
|
## Invocation
|
|
21
24
|
|
|
22
25
|
```
|
|
23
|
-
/theway:workflow [--workflow <name>] <change-id> [<change-id> ...]
|
|
26
|
+
/theway:workflow [--workflow <name>] <change-id> [<change-id> ...] # input: changes
|
|
27
|
+
/theway:workflow --workflow <name> <request> # input: request
|
|
24
28
|
```
|
|
25
29
|
|
|
26
|
-
- `--workflow <name>` or `--workflow=<name>` may stand anywhere in the arguments and picks the workflow `<name>`; without it, the run uses the default workflow (the file that sets `default: true`, else `develop`).
|
|
27
|
-
- `--workflow` with no name after it, or given twice: stop and say so.
|
|
28
|
-
-
|
|
29
|
-
- **
|
|
30
|
+
- `--workflow <name>` or `--workflow=<name>` may stand anywhere in the arguments and picks the workflow `<name>`; without it, the run uses the default workflow (the file that sets `default: true`, else `develop`).
|
|
31
|
+
- `--workflow` with no name after it, or given twice: stop and say so.
|
|
32
|
+
- `theway workflow <name>` is resolved first (Step 1). With `input: changes`, every other argument is a change ID; no change ID: stop and ask for one. With `input: request`, every argument other than `--workflow <name>` forms the request, joined with spaces; an empty request: stop and ask for one.
|
|
33
|
+
- **One change ID:** run the change and stop when its PR is ready for validation (when `pushes` is `false`, when its local branch is ready; for a working-tree workflow, when the change is done, uncommitted in the working tree). Never merge it.
|
|
34
|
+
- **Multiple change IDs (series):** run each change strictly in the given order. When `pushes` is `true`, each change's PR must be merged before the next change starts, since later changes build on earlier ones; the user confirms each merge (Step 5). When `pushes` is `false`, nothing is merged: each change's branch is created from the previous change's branch (Step 2). A working-tree workflow commits nothing, so it cannot run a series (Step 1).
|
|
30
35
|
|
|
31
|
-
**Authorization boundary:** invoking this command authorizes editing the repository, inline or through agents, committing only on each change's own feature branch (nothing for a workflow
|
|
36
|
+
**Authorization boundary:** invoking this command authorizes editing the repository, inline or through agents, committing only on each change's own feature branch (nothing for a working-tree workflow), the Workflow tool, and, when `theway workflow` prints `pushes: true`, pushing each change's own feature branch (never force-push, never the default branch) and opening its PR — nothing more. When `pushes` is `false`, it pushes nothing and opens no PR. Merging needs the user's explicit yes, asked at Step 5, and merges as `git-host.md` says: never bypass required reviews or checks. Do not ask for permission mid-run for the pushes and PRs it grants; do not perform outward actions it doesn't.
|
|
37
|
+
|
|
38
|
+
**Authorization of a request run** (`input: request`): invoking this command authorizes writing the change folders the scaffold creates, and throwaway probes in a directory created with `mktemp -d`, inline or through agents, and the Workflow tool — nothing more. It authorizes no repository edit, no branch, no commit, no push and no PR.
|
|
32
39
|
|
|
33
40
|
## Workflow Steps
|
|
34
41
|
|
|
35
42
|
> Follow the conventions in `<home>/standards/interaction.md` (exploration, reporting and authority).
|
|
36
43
|
|
|
37
|
-
Run Step 1's first part once per run, then Steps 1-5 once per change ID, in order.
|
|
44
|
+
Run Step 1's first part once per run, then Steps 1-5 once per change ID, in order. A request run (`input: request`) runs Steps 1-5 once, for its request, with Steps 2 and 4 skipped.
|
|
38
45
|
|
|
39
46
|
### Step 1: Load Context
|
|
40
47
|
|
|
41
48
|
Once per run:
|
|
42
|
-
|
|
49
|
+
|
|
50
|
+
- Run `theway workflow`, or `theway workflow <name>` with `--workflow <name>`. It prints the resolved workflow as JSON: its `name`, its `file`, `commits` and `git_host`, `pushes` (whether a step pushes), `working_tree` (one inline step that commits nothing) and its `steps`. Each step entry has its `id`, `step`, effective `agents` (`agents: false` runs it inline), `params` and its `do` tree of `agent`, `parallel`, `loop` and `when` nodes, every agent with its `label`, `prompt` paths, `returns` type, `access` and `model`; a gate entry has its `id` and `gate` question. On exit 1, quote its error line and stop: no change starts.
|
|
51
|
+
- When `working_tree` is `true`, say "working tree: no branch, nothing committed" in your first report line.
|
|
43
52
|
- Read the files at its `commits` and `git_host` paths, `commits.md` and `git-host.md` (your project's own copy when it has one): `commits.md` says how the feature branch, the commits and the PR are named, `git-host.md` gives the command of each git host operation by its heading. Pass both paths to every Workflow call (Step 3) and follow both in every step you do yourself.
|
|
44
|
-
- When
|
|
53
|
+
- When `working_tree` is `true` and more than one change ID was given, stop before any work and say: `a series needs a workflow that commits; pass --workflow agents or a workflow with more steps`.
|
|
45
54
|
- Run `theway authority`: its output is the `## Authority` section of `<home>/standards/interaction.md`, which every agent of the run gets verbatim.
|
|
46
55
|
|
|
47
56
|
Run `theway context develop <change-id>` for each change and use its `change_dir` as `<change-dir>`. Then read these exact paths directly — do not search the filesystem to locate them:
|
|
48
|
-
|
|
49
|
-
- `<home>/standards/
|
|
57
|
+
|
|
58
|
+
- `<home>/standards/develop.md` - How a change is implemented and verified (you follow it for an inline `work` agent; the agents get it otherwise)
|
|
50
59
|
- `<change-dir>/spec.md` - Why, what, risks and Success Criteria
|
|
51
60
|
- `<change-dir>/tasks.md` - The work, as numbered tasks
|
|
52
61
|
- `<change-dir>/design.md` - Technical specs (if present)
|
|
@@ -54,15 +63,19 @@ Run `theway context develop <change-id>` for each change and use its `change_dir
|
|
|
54
63
|
|
|
55
64
|
Then read every file its `standards` lists: these are the standards, the shipped opt-in ones that are enabled and yours.
|
|
56
65
|
|
|
66
|
+
**A request run** (`input: request`): run `theway workflow` and `theway authority` as above, then run `theway context engineering` for the standards (the `engineering` phase) and read every file its `standards` lists. Do not read `develop.md` or any change file.
|
|
67
|
+
|
|
57
68
|
### Step 2: Branch
|
|
58
69
|
|
|
59
|
-
Find the default branch and sync it, as `git-host.md` says ("Default branch", "Sync the default branch"), then create (or check out) the change's feature branch from it, named as `commits.md` says. When
|
|
70
|
+
Find the default branch and sync it, as `git-host.md` says ("Default branch", "Sync the default branch"), then create (or check out) the change's feature branch from it, named as `commits.md` says. When `pushes` is `false`, create each later change's branch of a series from the previous change's branch instead, so the changes stack locally. The branch the feature branch is created from, the default branch or that previous branch, is the change's `<base>`.
|
|
60
71
|
|
|
61
|
-
Skip this step
|
|
72
|
+
Skip this step for a working-tree workflow: it creates no branch and commits nothing, the change stays uncommitted in the working tree, and its base commit is `HEAD`.
|
|
73
|
+
|
|
74
|
+
Skip this step for a request run: there is no branch and no commit.
|
|
62
75
|
|
|
63
76
|
### Step 3: Run
|
|
64
77
|
|
|
65
|
-
Run the workflow's
|
|
78
|
+
Run the workflow's entries in order, in segments: each run of consecutive step entries with `agents: true` is one agent segment, one Workflow call; each step entry with `agents: false` and each gate is inline, done by you in this session.
|
|
66
79
|
|
|
67
80
|
**Agent segment.** Call the Workflow tool once, with `name: "theway:run-pipeline"` and these `args`, as a JSON object (not a string):
|
|
68
81
|
|
|
@@ -72,41 +85,78 @@ Run the workflow's steps in order, in segments: each run of consecutive steps wi
|
|
|
72
85
|
| `branch`, `base`, `changeId` | the feature branch, `<base>` (Step 2), the change ID |
|
|
73
86
|
| `changeDir` | `<change-dir>`, absolute |
|
|
74
87
|
| `light` | `true` when `spec.md` has `**Mode:** light` under its H1, else `false` |
|
|
75
|
-
| `develop
|
|
88
|
+
| `develop` | the absolute path of `<home>/standards/develop.md` |
|
|
76
89
|
| `commits`, `gitHost` | the `commits` and `git_host` paths `theway workflow` printed |
|
|
77
90
|
| `standards` | the absolute paths `theway context` lists in `standards`, possibly `[]` |
|
|
78
91
|
| `authority` | the output of `theway authority`, verbatim |
|
|
79
92
|
| `workflow` | the object `theway workflow` printed, parsed (not the string) |
|
|
80
|
-
| `steps` | the segment's
|
|
81
|
-
| `head` |
|
|
93
|
+
| `steps` | the segment's entry indices (0-based, ascending and consecutive) |
|
|
94
|
+
| `head` | the output of `git rev-parse HEAD` after Step 2 and any inline entries before the segment |
|
|
95
|
+
|
|
96
|
+
**A request run** passes only `repo`, `request` (the request, as a string), `changes`, `standards`, `authority`, `workflow` and `steps`; `branch`, `base`, `head`, `changeId`, `changeDir`, `light`, `develop`, `commits` and `gitHost` are rejected. `changes` is `[]` when the segment starts at the scaffold step; otherwise it is the scaffold result's `changes`, each `{ id, dir, light, fix }`, with `light` set from the spec (`**Mode:** light` under its H1) and `fix` from the ID (it starts with `fix-`). Pass it to every segment after the scaffold.
|
|
82
97
|
|
|
83
|
-
The script runs the segment's
|
|
98
|
+
The script runs the segment's entries and returns `{ status, error, steps, pr, changes, authorityReports }`, with `status` `succeeded`, `blocked` or `failed`. `steps` holds one record per entry run, `{ id, step, results }`, and each result is `{ label, returns, iteration, result }`: the agent's label, its result type, its loop iteration (`null` outside a loop) and its typed result. `pr` is `{ url, number }` or `null`; `changes` is a request run's change folders, else `[]`. It fails with `run-pipeline is started by /theway:workflow with its args` when a key is missing, or when `steps` and `head` do not match these rules.
|
|
84
99
|
|
|
85
|
-
- **When the Workflow tool is not available in this session:** read `${CLAUDE_PLUGIN_ROOT}/workflows/run-pipeline.js` and run the segment's
|
|
100
|
+
- **When the Workflow tool is not available in this session:** read `${CLAUDE_PLUGIN_ROOT}/workflows/run-pipeline.js` and run the segment's tree with the Agent tool, one agent per `agent` node, with the same prompts, models, order and type rules. Each agent's prompt asks it to end its reply with a JSON object of its type's fields, and you build the same result. This fallback is for agent segments only.
|
|
101
|
+
- **When neither the Workflow tool nor the Agent tool is available:** run the agent segment's nodes yourself, as an inline step, and say "inline" for it in the report.
|
|
102
|
+
- **Agent steps always go through agents:** an entry with `agents: true` runs through the Workflow tool, or through the Agent tool fallback above when the Workflow tool is missing. It runs inline only when both tools are missing, as the previous item says. Never run it inline otherwise, even for a short step.
|
|
86
103
|
- **When the Workflow call returns an error and no result:** the change is `failed`, with that error quoted. There is no fallback then, since agents may already have committed.
|
|
87
104
|
|
|
88
|
-
**Inline step.**
|
|
89
|
-
- **`implement`:** follow `<home>/standards/develop.md`, including its update of `spec.md` (the decision and why) and `tasks.md` once a decision you brought back is taken; agent steps keep the change files read-only. When steps follow it, commit on the feature branch as `commits.md` says. When it is the only step, commit nothing (Step 2 was skipped). On a spec that does not fit the code, the change is `blocked`, with the blocker and its options.
|
|
90
|
-
- **`review`:** up to `rounds` rounds. Per round, review `git diff <base>...<branch>` yourself through each lens, one after the other (read its `path` and follow it, and check the diff against every standard), then give each finding one of the five verdicts of `<home>/standards/spec-review.md`'s Triage step 1 (`confirmed`, `false_positive`, `duplicate`, `nit`, `out_of_scope`). No confirmed finding ends the step. Otherwise fix the confirmed findings and commit as `commits.md` says (for a `fix-` change whose fixes touch the regression test or the fix, re-run the regression check of `develop.md`), then check your fixes from the round's start head: a confirmed finding not resolved makes the change `failed`. The report says "review ran inline": an inline review is the session checking its own work.
|
|
91
|
-
- **`agent`:** carry out the step's `prompt` under the rules above; you may commit on the feature branch, as `commits.md` says; you do not push. When you cannot carry it out under those rules, the change is `failed`.
|
|
92
|
-
- **`pr`:** push the feature branch once, open the PR and drive CI with the rules of the script's `pr` step: the PR title and body as `commits.md` says, each git host operation as `git-host.md` says, the CI attempts up to `ci_attempts`, the failed check's log, its classification and what each one does; its outcomes are the script's.
|
|
105
|
+
**Inline step.** Walk the step's printed `do` tree yourself, in order: for each `agent` node, read its prompt files and follow them under the same rules the script gives its agents, except as the list below says: the fixed rules (`fixed()` in `${CLAUDE_PLUGIN_ROOT}/workflows/run-pipeline.js`, its request-run branch in a request run), the permission line of its `access` (`PERMISSION` there), its Input and its type's engine line. Apply the type rules of the script to what you produce, run a `parallel` group's agents one after the other, evaluate `loop` and `when` conditions as the script does, and build the same typed results for Steps 4 and 5.
|
|
93
106
|
|
|
94
|
-
|
|
107
|
+
- During an inline `work` agent, you may update `spec.md` (the decision and why) and `tasks.md` as `develop.md` asks, once a decision you brought back is taken; agents keep the change files read-only.
|
|
108
|
+
- In a working-tree workflow, commit nothing, whatever the permission line says (Step 2 was skipped).
|
|
109
|
+
- A blocker of an inline `work` agent makes the change `blocked`, with the blocker and its options.
|
|
110
|
+
- A step with a `findings` agent run inline is the session checking its own work: the report says "ran inline: the session checked its own work".
|
|
111
|
+
- In a request run, an inline `scaffold` agent is the scaffold done in this session: it writes only the change folders it validated or got from `theway next-id`, and its result's `changes`, with `light` and `fix` added, is passed to every later segment.
|
|
112
|
+
|
|
113
|
+
**Gate.** Ask the user the gate's question with AskUserQuestion, with the options "Continue" and "Stop". "Continue" goes on with the next entry; any other answer makes the change `blocked`, with `gate: <question>`. There is no resume from a gate.
|
|
114
|
+
|
|
115
|
+
The first `blocked` or `failed` segment, inline step or gate stops the change: the later entries do not run.
|
|
95
116
|
|
|
96
117
|
### Step 4: Record
|
|
97
118
|
|
|
98
|
-
|
|
119
|
+
Skip this step for a request run: the change files are its output.
|
|
120
|
+
|
|
121
|
+
Otherwise, whatever the status, record what the typed results hold in `<change-dir>/tasks.md`, the results of agent segments and of inline steps alike:
|
|
122
|
+
|
|
123
|
+
- tick the union of `tasksDone` of every `work` result (`- [x] N.`);
|
|
124
|
+
- add to its Notes every `work` result's `discoveries` and `choices`, and its `regression` outputs for a `fix-` change;
|
|
125
|
+
- add every `verdicts` result to the Notes, each finding with its verdict and reason;
|
|
126
|
+
- add every finding that got no verdict to the Notes, as "not triaged".
|
|
99
127
|
|
|
100
128
|
### Step 5: Gate
|
|
101
129
|
|
|
102
|
-
-
|
|
103
|
-
- **`succeeded`,
|
|
104
|
-
- **`succeeded`, a series
|
|
105
|
-
- **`
|
|
106
|
-
- **`
|
|
130
|
+
- **A request run:** whatever the status, report as the Exit says; a `blocked` run's `error` is the open question, the stop or escalation report, or the confirmed decisions, and the spec is not ready. Nothing is merged.
|
|
131
|
+
- **`succeeded`, one change:** report the PR ready for validation, the local branch when `pushes` is `false`, or the uncommitted change for a working-tree workflow. Never merge.
|
|
132
|
+
- **`succeeded`, a series, `pushes` true:** report the PR URL, its diffstat ("Diffstat" in `git-host.md`) and CI status, and ask the user whether to merge it. On an explicit yes, merge as "Merge" in `git-host.md` says (never bypass required reviews or checks), sync the default branch ("Sync the default branch"), then continue with the next change ID. Any other answer stops the run; report where the series stopped.
|
|
133
|
+
- **`succeeded`, a series, `pushes` false:** nothing is merged; continue with the next change ID, whose branch Step 2 creates from this change's branch.
|
|
134
|
+
- **`blocked`:** stop the run and bring `error` (a `work` agent's blocker, an agent that returned no result, or the gate question) to the user with its options. In a series, no later change starts.
|
|
135
|
+
- **`failed`:** never merge; stop the run and report `error`: a finding not resolved with its reason, a loop that ended without its condition, or the quoted CI error. In a series, no later change starts.
|
|
107
136
|
|
|
108
137
|
## Exit
|
|
109
138
|
|
|
110
|
-
|
|
139
|
+
**A request run** reports, in this order:
|
|
140
|
+
|
|
141
|
+
1. each change folder the scaffold wrote;
|
|
142
|
+
2. one line per entry, in workflow order: its `id` and "through agents" or "inline";
|
|
143
|
+
3. the scaffold's `shaping`: the findings that shaped the spec;
|
|
144
|
+
4. the review outcome: how it ran (the rounds used; "not run because a question was already open" when the scaffold returned `open`; "not run: the scaffold stopped" when it returned `stopped` or `escalated`; "inline" when the step ran inline), then every finding of every round in one Markdown table with the columns `#`, `Finding`, `Verdict` and `Fix`, one row per finding. `#` is `R<iteration>-<index>`, for example `R1-0`; `Finding` is one line saying what is wrong; `Verdict` is the triage verdict, or `confirmed, settled` for a verdict with `settled: true`; `Fix` comes from the `edits` result's `fixes`, reads `open question: <question>` for a confirmed `decision` (`escalated` in a light run, whose changes are `light`), names the earlier `#` for a `duplicate`, and gives the one-line reason for the other verdicts;
|
|
145
|
+
5. under the table, each `confirmed, settled` finding again, with the choice made, so the user can overturn it;
|
|
146
|
+
6. any open question or stop report (the `error` of a `blocked` run), verbatim, and that the spec is not ready until it is answered;
|
|
147
|
+
7. the standards given, by file name, or "none";
|
|
148
|
+
8. every `theway: warning:` line and every `authorityReports` entry.
|
|
149
|
+
|
|
150
|
+
For a working-tree workflow, report the tasks done, each Success Criterion with how it was verified, any deviation from the spec and what was decided about it, anything still open, and that the change is uncommitted in the working tree; also name the standards followed, by file name, or "none", and quote every `theway: warning:` line.
|
|
151
|
+
|
|
152
|
+
Otherwise, report per change: the workflow's name and file, the branch, and the PR URL (or the local branch when nothing was pushed). Then, per entry in workflow order whichever segment ran it:
|
|
153
|
+
|
|
154
|
+
- its `id`, marked "through agents" for an entry run through agents and "inline" for an inline entry, and "ran inline: the session checked its own work" for an inline step with a `findings` agent;
|
|
155
|
+
- the loop iterations it used;
|
|
156
|
+
- each agent's `summary`;
|
|
157
|
+
- every finding, with its verdict or "not triaged";
|
|
158
|
+
- each `resolutions` result;
|
|
159
|
+
- the PR and its CI iterations, or "not run" when the run stopped before it;
|
|
160
|
+
- for a gate, the answer.
|
|
111
161
|
|
|
112
|
-
|
|
162
|
+
Then say whether the PR was merged or awaits validation, and any blocker waiting on the user. In a series, also state where it stopped and why if it did not complete. Quote every `authorityReports` entry of every segment. Also name the standards given to the agents, by file name, or "none", and quote every `theway: warning:` line.
|
package/plugin/home/config.yaml
CHANGED
|
@@ -16,40 +16,11 @@ standards:
|
|
|
16
16
|
quality:
|
|
17
17
|
enabled: false
|
|
18
18
|
|
|
19
|
-
#
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
review:
|
|
23
|
-
# Maximum review rounds per scaffold; 0 skips the review
|
|
24
|
-
rounds: 1
|
|
25
|
-
# The critic agents (two in /theway:engineering, one with --light): opus, sonnet or haiku; lower cost: sonnet
|
|
26
|
-
model: opus
|
|
27
|
-
|
|
28
|
-
# Workflow - defaults for /theway:workflow: a field a step of a workflow file leaves out takes its value here (absent or invalid key means the default)
|
|
29
|
-
# Models: opus, sonnet or haiku
|
|
19
|
+
# Workflow - defaults for /theway:workflow: workflow.defaults.<step>.<param> sets a param of a step for every
|
|
20
|
+
# workflow entry of that step that leaves it out (a value in the entry wins); the step files hold the defaults, and
|
|
21
|
+
# theway steps lists every step with its params
|
|
30
22
|
workflow:
|
|
31
|
-
defaults:
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
# The local review before anything is pushed
|
|
36
|
-
review:
|
|
37
|
-
# Maximum review rounds; leave the review step out of a workflow to skip the review
|
|
38
|
-
rounds: 1
|
|
39
|
-
# One reviewer per lens, from <home>/projects/<key>/lenses/<name>.md or <home>/lenses/<name>.md
|
|
40
|
-
lenses: [conformance, correctness]
|
|
41
|
-
# The reviewers, the triage agent and the fix check
|
|
42
|
-
model: opus
|
|
43
|
-
# The fix agent of each round
|
|
44
|
-
fix_model: opus
|
|
45
|
-
# The push, the PR and CI; leave the pr step out of a workflow to push nothing
|
|
46
|
-
pr:
|
|
47
|
-
# CI attempts to reach green, re-runs included
|
|
48
|
-
ci_attempts: 2
|
|
49
|
-
# The push/PR agent, CI polling and log fetching
|
|
50
|
-
model: sonnet
|
|
51
|
-
# The CI fix agent
|
|
52
|
-
fix_model: opus
|
|
53
|
-
# A custom agent step
|
|
54
|
-
agent:
|
|
55
|
-
model: sonnet
|
|
23
|
+
defaults: {}
|
|
24
|
+
# For example, two spec review rounds for /theway:engineering:
|
|
25
|
+
# defaults:
|
|
26
|
+
# spec-review: {rounds: 2}
|
|
@@ -0,0 +1,15 @@
|
|
|
1
|
+
# Diagnose CI
|
|
2
|
+
|
|
3
|
+
CI failed on the PR Input `pr.number`. For each run of Input `ci.failedRunIds`, fetch its log as "Read a failed check's log" in the git host standard (`git-host.md`) says and quote the real error line in `errors`; never diagnose from memory. The checks of Input `ci.failedOther` have no run ID: theway adds each one's name and link to `errors` and classifies the failure `this_pr`.
|
|
4
|
+
|
|
5
|
+
Classify the failure: `this_pr` (this PR causes it), `base_red` (Input `base` fails the same way) or `flaky` (infrastructure). For `base_red`, give `baseFix`: the sha of a commit on Input `base` that fixes it, or null when there is none; null for the others.
|
|
6
|
+
|
|
7
|
+
Re-run the failed jobs only when all of these hold:
|
|
8
|
+
|
|
9
|
+
- Input `loop.iteration` is below Input `loop.max`, so an attempt is left;
|
|
10
|
+
- Input `ci.failedOther` is empty;
|
|
11
|
+
- the failure is not fixable: you classify it `flaky`, or `base_red` with `baseFix` null.
|
|
12
|
+
|
|
13
|
+
Then re-run the failed jobs of each run of Input `ci.failedRunIds` once, as "Re-run failed jobs" says, and return `rerun`: the run IDs re-run. Otherwise re-run nothing and return `rerun` as `[]`.
|
|
14
|
+
|
|
15
|
+
Do not push or edit anything.
|
|
@@ -0,0 +1,7 @@
|
|
|
1
|
+
# Fix CI
|
|
2
|
+
|
|
3
|
+
Input `diagnosis` holds the CI failure of the PR Input `pr.number`. When its `classification` is `this_pr`, fix the failure its `errors` quote. When it is `base_red`, port its `baseFix`, the commit of Input `base` that fixes the failure, onto Input `branch`.
|
|
4
|
+
|
|
5
|
+
Commit on Input `branch` and push it once, as "Push the feature branch" in the git host standard (`git-host.md`) says (never force).
|
|
6
|
+
|
|
7
|
+
When the failure cannot be fixed without a decision the spec does not make, stop and return a blocker (what you found, the options); `blocker` is null otherwise.
|
|
@@ -0,0 +1,5 @@
|
|
|
1
|
+
# Wait for CI
|
|
2
|
+
|
|
3
|
+
Wait for the checks of the PR Input `pr.number` on Input `head` to finish, as "Wait for the checks" in the git host standard (`git-host.md`) says. Do not push, edit or re-run anything.
|
|
4
|
+
|
|
5
|
+
Return `ci`: `red` when at least one check failed, as that standard defines a failed check; `green` otherwise. Return `failedRunIds`: the run ID of each failed check that has one; and `failedOther`: the name and link of each failed check that has no run ID. Both are `[]` when `ci` is `green`.
|
|
@@ -0,0 +1,7 @@
|
|
|
1
|
+
# Fix check
|
|
2
|
+
|
|
3
|
+
You check the fixes of the confirmed findings of Input `confirmed`: read `git log <Input work.from>..<Input work.head>` and `git diff <Input work.from>..<Input work.head>`.
|
|
4
|
+
|
|
5
|
+
For each finding, answer resolved or not resolved with a one-line reason. This check does not look for new problems, except that a fix that breaks a standard your fixed rules list is not resolved.
|
|
6
|
+
|
|
7
|
+
When Input `change.fix` is true (a `fix-` change): a finding whose fix touched the regression test or the fix is resolved only when the regression outputs of the fix agent, Input `work.regression`, pass the regression check of `develop.md`.
|