@pixelfactoryio/theway 0.5.1 → 0.5.2
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/dist/theway.js
CHANGED
|
@@ -2421,10 +2421,15 @@ function installDir() {
|
|
|
2421
2421
|
function shownHome(home) {
|
|
2422
2422
|
return resolve3(home) === resolve3(defaultHome()) ? "~/.theway" : resolve3(home);
|
|
2423
2423
|
}
|
|
2424
|
-
function
|
|
2424
|
+
function ruleRoot(home) {
|
|
2425
2425
|
const at = shownHome(home);
|
|
2426
|
-
|
|
2427
|
-
|
|
2426
|
+
return at.startsWith("~/") ? at : `/${at}`;
|
|
2427
|
+
}
|
|
2428
|
+
function homeRules(home) {
|
|
2429
|
+
return [`Read(${ruleRoot(home)}/**)`];
|
|
2430
|
+
}
|
|
2431
|
+
function editRule(home) {
|
|
2432
|
+
return `Edit(${ruleRoot(home)}/*/changes/**)`;
|
|
2428
2433
|
}
|
|
2429
2434
|
function rules(home) {
|
|
2430
2435
|
return ["Bash(theway:*)", ...homeRules(home)];
|
|
@@ -2693,7 +2698,12 @@ function install() {
|
|
|
2693
2698
|
const perms = settings.permissions ?? {};
|
|
2694
2699
|
const allow = perms.allow ?? [];
|
|
2695
2700
|
const current = rules(tHome);
|
|
2696
|
-
const stale = [
|
|
2701
|
+
const stale = [
|
|
2702
|
+
...legacyRules(tHome),
|
|
2703
|
+
editRule(tHome),
|
|
2704
|
+
editRule(previous),
|
|
2705
|
+
...homeRules(previous).filter((r) => !current.includes(r))
|
|
2706
|
+
];
|
|
2697
2707
|
const kept = allow.filter((r) => !(typeof r === "string" && stale.includes(r)));
|
|
2698
2708
|
const missing = current.filter((r) => !kept.includes(r));
|
|
2699
2709
|
if (missing.length > 0 || kept.length !== allow.length) {
|
|
@@ -2732,7 +2742,7 @@ function uninstall() {
|
|
|
2732
2742
|
return invalidSettings(settingsPath);
|
|
2733
2743
|
const allow = settings.permissions?.allow;
|
|
2734
2744
|
if (Array.isArray(allow)) {
|
|
2735
|
-
const drop = homes.flatMap((h) => [...rules(h), ...legacyRules(h)]);
|
|
2745
|
+
const drop = homes.flatMap((h) => [...rules(h), ...legacyRules(h), editRule(h)]);
|
|
2736
2746
|
const kept = allow.filter((r) => !(typeof r === "string" && drop.includes(r)));
|
|
2737
2747
|
if (kept.length !== allow.length) {
|
|
2738
2748
|
settings.permissions = { ...settings.permissions, allow: kept };
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "theway",
|
|
3
|
-
"version": "0.5.
|
|
3
|
+
"version": "0.5.2",
|
|
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",
|
|
@@ -1,5 +1,5 @@
|
|
|
1
1
|
---
|
|
2
|
-
description: Implement changes through agents
|
|
2
|
+
description: Implement changes through agents, review them locally, then open a PR and drive CI to green
|
|
3
3
|
author: Amine
|
|
4
4
|
allowed-tools: Bash(theway:*)
|
|
5
5
|
---
|
|
@@ -21,10 +21,10 @@ Run `theway path` and use the folder it prints as `<home>`: TheWay files are sto
|
|
|
21
21
|
/theway:develop-workflow <change-id> [<change-id> ...]
|
|
22
22
|
```
|
|
23
23
|
|
|
24
|
-
- **One change ID:** develop the change and stop when its PR is ready for validation. Never merge it.
|
|
25
|
-
- **Multiple change IDs (series):** develop each change strictly in the given order.
|
|
24
|
+
- **One change ID:** develop the change and stop when its PR is ready for validation (with `workflow.open_pr: false`, when its local branch is ready). Never merge it.
|
|
25
|
+
- **Multiple change IDs (series):** develop each change strictly in the given order. With `workflow.open_pr` 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 6). With `workflow.open_pr: false`, nothing is merged: each change's branch is created from the previous change's branch (Step 2).
|
|
26
26
|
|
|
27
|
-
**Authorization boundary:** invoking this command authorizes
|
|
27
|
+
**Authorization boundary:** invoking this command authorizes, when `workflow.open_pr` is true (the default), pushing each change's own feature branch (never force-push, never the default branch) once its local review is done, and opening its PR — nothing more. With `workflow.open_pr: false` it pushes nothing and opens no PR. Merging always needs the user's explicit yes, asked at Step 6, and uses `gh pr merge <number> --squash`, never `--admin`. This invocation is also the explicit opt-in for the Workflow tool. Do not ask for permission mid-run for the pushes and PRs it grants; do not perform outward actions it doesn't.
|
|
28
28
|
|
|
29
29
|
## Workflow Steps
|
|
30
30
|
|
|
@@ -44,11 +44,13 @@ Run `theway path <project> <change-id>` and use the folder it prints as `<change
|
|
|
44
44
|
|
|
45
45
|
From `<home>/config.yaml`, take `workflow.review_rounds` (review rounds per change, default 1) and `workflow.ci_attempts` (CI attempts per change, default 2). A key that is absent or not a non-negative integer (`ci_attempts`: a positive integer) takes its default.
|
|
46
46
|
|
|
47
|
+
Also take `workflow.open_pr` (default `true`): when it is `false`, Step 5 is skipped and nothing is pushed. A value that is not a boolean takes the default.
|
|
48
|
+
|
|
47
49
|
Also take the agent models from `workflow.models`: `implementer` (default `opus`), `reviewer` (default `opus`), `fix` (default `opus`) and `ci` (default `sonnet`). Each must be `opus` or `sonnet`; a key that is absent or holds any other value takes its default.
|
|
48
50
|
|
|
49
51
|
### Step 2: Branch
|
|
50
52
|
|
|
51
|
-
Sync the main branch, then create (or check out) the change's feature branch from it.
|
|
53
|
+
Sync the main branch, then create (or check out) the change's feature branch from it. In a series with `workflow.open_pr: false`, create each later change's branch from the previous change's branch instead, so the changes stack locally.
|
|
52
54
|
|
|
53
55
|
### Step 3: Implement via Orchestrated Agents
|
|
54
56
|
|
|
@@ -61,39 +63,47 @@ Orchestrate with the **Workflow tool**. If it is unavailable in this session, fa
|
|
|
61
63
|
- CI polling and log-fetch agents: `workflow.models.ci`.
|
|
62
64
|
- Never `haiku`. Always set `model` explicitly — do not rely on inheriting the session model.
|
|
63
65
|
|
|
64
|
-
**Implementers.** One implementer per change by default: the tasks of a change usually build on each other and touch the same files, so splitting them adds handoffs and merges without saving time. Split into parallel agents, each in its own worktree, only for large parts that are independent and touch different files; chain dependent parts, never run them in parallel. Each implementer gets `<home>/data/standards/develop.md`, the change's `<change-dir>/spec.md`, `<change-dir>/tasks.md` and `<change-dir>/design.md`, and its part of the work. When the spec does not fit the code, it stops and returns a blocker (what it found, the options) instead of redesigning. It commits locally on the feature branch with Conventional Commits (`type(scope): description`, imperative, lowercase), verifies its work as the standard says (including the CI's commands that can run locally),
|
|
65
|
-
|
|
66
|
-
### Step 4: Open PR
|
|
67
|
-
|
|
68
|
-
The implementer opens the PR with `gh pr create`; the orchestrator only collects its URL.
|
|
69
|
-
|
|
70
|
-
- Commit and PR text describe only what the change does — never the process or tooling that produced it.
|
|
71
|
-
- Keep the PR body minimal: one-line subject, bullets only when the change isn't self-evident.
|
|
66
|
+
**Implementers.** One implementer per change by default: the tasks of a change usually build on each other and touch the same files, so splitting them adds handoffs and merges without saving time. Split into parallel agents, each in its own worktree, only for large parts that are independent and touch different files; chain dependent parts, never run them in parallel. Each implementer gets `<home>/data/standards/develop.md`, the change's `<change-dir>/spec.md`, `<change-dir>/tasks.md` and `<change-dir>/design.md`, and its part of the work. When the spec does not fit the code, it stops and returns a blocker (what it found, the options) instead of redesigning. It commits locally on the feature branch with Conventional Commits (`type(scope): description`, imperative, lowercase), verifies its work as the standard says (including the CI's commands that can run locally), and returns its verification and any blocker. It does not push. The orchestrator — not the agents — checks off completed tasks in `<change-dir>/tasks.md` and records discoveries in its Notes section.
|
|
72
67
|
|
|
73
|
-
### Step
|
|
68
|
+
### Step 4: Local Review
|
|
74
69
|
|
|
75
|
-
|
|
70
|
+
Run up to `review_rounds` review rounds on the local branch, before anything is pushed. With `review_rounds: 0`, skip this step.
|
|
76
71
|
|
|
77
72
|
Each round:
|
|
78
73
|
|
|
79
|
-
1. **Review
|
|
80
|
-
- Spawn independent reviewer agents prompted to refute or break the PR diff: against `spec.md` (each Success Criterion met, nothing outside Scope, nothing it lists as Out of Scope), and for correctness, edge cases and convention violations. A correct diff that does something the spec did not ask for is a finding. Each finding's `file` is a path relative to the repository root, without a leading `./`.
|
|
81
|
-
- Poll the PR checks.
|
|
74
|
+
1. **Review.** Spawn independent reviewer agents prompted to refute or break the branch diff (`git diff <base>...<branch>` on the round's head, where `<base>` is the main branch, or, in a series with `workflow.open_pr: false`, the previous change's branch): against `spec.md` (each Success Criterion met, nothing outside Scope, nothing it lists as Out of Scope), and for correctness, edge cases and convention violations. A correct diff that does something the spec did not ask for is a finding. Each finding's `file` is a path relative to the repository root, without a leading `./`.
|
|
82
75
|
2. **Triage findings**, once per round:
|
|
83
|
-
1. Number the round's findings `0..N-1` in the order reported and verify each one. Each gets one verdict: `confirmed` (real), `false_positive` (refuted), `duplicate` (the same problem as an earlier finding of the round, which it names), `nit` (real, cosmetic) or `out_of_scope` (not this
|
|
76
|
+
1. Number the round's findings `0..N-1` in the order reported and verify each one. Each gets one verdict: `confirmed` (real), `false_positive` (refuted), `duplicate` (the same problem as an earlier finding of the round, which it names), `nit` (real, cosmetic) or `out_of_scope` (not this change's).
|
|
84
77
|
2. Only `confirmed` findings go to the fix agent. List the `false_positive`, `nit` and `out_of_scope` findings (index, verdict, title) in the Exit report.
|
|
85
|
-
3. **
|
|
78
|
+
3. **Fix once.** When the round has confirmed findings, spawn one fix agent with them. It commits the fixes locally on the branch and re-runs the CI's commands that can run locally. It does not push.
|
|
79
|
+
4. **Fix check:** spawn one agent that reads the fix commits (`git log` / `git diff` from the round's reviewed head to the new head) and the round's confirmed findings, and answers, per finding, `resolved` or `not resolved` with a one-line reason. It does not look for new problems. Any `not resolved` finding fails the change (Step 6).
|
|
80
|
+
|
|
81
|
+
A round with no confirmed findings ends the step. Otherwise start the next round only while rounds remain under `review_rounds`; the next round reviews the new head.
|
|
82
|
+
|
|
83
|
+
### Step 5: Open PR and CI
|
|
84
|
+
|
|
85
|
+
Skipped with `workflow.open_pr: false`.
|
|
86
|
+
|
|
87
|
+
Push the branch once and open the PR with `gh pr create`.
|
|
88
|
+
|
|
89
|
+
- Commit and PR text describe only what the change does — never the process or tooling that produced it.
|
|
90
|
+
- Keep the PR body minimal: one-line subject, bullets only when the change isn't self-evident.
|
|
91
|
+
|
|
92
|
+
Then drive CI on the PR:
|
|
93
|
+
|
|
94
|
+
1. **Poll the PR checks** on its current head.
|
|
95
|
+
2. **Triage CI.** On a failed run, fetch the log (`gh run view <run-id> --log-failed`, then the full `--log` if that is empty) and quote the real error line before attempting any fix; never diagnose from memory or plausibility. Classify the failure as `code_bug`, `test_failure`, `lint_format`, `typecheck`, `dependency_install`, `flaky_infra`, `base_branch_red` or `unknown`. A failure of this PR (any class but `flaky_infra` and `base_branch_red`) goes to the fix agent; `flaky_infra` and `base_branch_red` follow the not-this-PR path below.
|
|
86
96
|
- **Not this PR's failure** (base branch red or flaky infra): when the base branch is red, port its fix onto the branch if one exists there, otherwise report it; then re-run the failed jobs once (`gh run rerun <run-id> --failed`).
|
|
87
|
-
|
|
88
|
-
5. **Fix check** (skipped with `review_rounds: 0`), on that push while CI reruns: spawn one agent that reads the fix commits (`git log` / `git diff` from the round's reviewed head to the new head) and the round's confirmed findings, and answers, per finding, `resolved` or `not resolved` with a one-line reason. It does not look for new problems. Any `not resolved` finding fails the change (Step 6).
|
|
97
|
+
3. **Fix.** For a failure of this PR, spawn one fix agent with the quoted CI error. It commits the fix on the branch and pushes once.
|
|
89
98
|
|
|
90
|
-
**Caps.** Each CI run of the PR (the first one, every run after a fix push and every re-run) counts as one CI attempt.
|
|
99
|
+
**Caps.** Each CI run of the PR (the first one, every run after a fix push and every re-run) counts as one CI attempt. Drive CI until it is green or `ci_attempts` attempts are used. If CI is still red after attempt `ci_attempts`, the change failed (Step 6).
|
|
91
100
|
|
|
92
101
|
### Step 6: Gate
|
|
93
102
|
|
|
94
|
-
**Change succeeded** (every confirmed finding resolved by the fix check, and CI green):
|
|
95
|
-
- Single change: stop and report the PR ready for validation.
|
|
96
|
-
- Series:
|
|
103
|
+
**Change succeeded** (every confirmed finding resolved by the fix check, and, with `workflow.open_pr` true, CI green):
|
|
104
|
+
- Single change: stop and report the PR ready for validation (with `workflow.open_pr: false`: the local branch, not pushed, reviewed unless `review_rounds: 0`).
|
|
105
|
+
- Series with `workflow.open_pr` true: report the PR URL, its diffstat (`gh pr diff <number> --stat`) and CI status, and ask the user whether to merge it. On an explicit yes, merge with `gh pr merge <number> --squash` (never `--admin`), sync main, then continue with the next change ID. On any other answer, stop the run and report where the series stopped.
|
|
106
|
+
- Series with `workflow.open_pr: false`: nothing is merged; continue with the next change ID, whose branch Step 2 creates from this change's branch.
|
|
97
107
|
|
|
98
108
|
**Change blocked** (the implementer returned a blocker): never merge; stop the run, and bring the blocker to the user with its options. In series mode, do not start later changes.
|
|
99
109
|
|
|
@@ -103,4 +113,4 @@ Each round:
|
|
|
103
113
|
|
|
104
114
|
## Exit
|
|
105
115
|
|
|
106
|
-
Report per change: branch, PR URL, review outcome (review rounds used, the findings not fixed with their verdicts, and the fix-check result per confirmed finding), CI status (CI attempts used), whether it was merged or awaits validation, and any blocker waiting on the user. In series mode, also state where the series stopped and why if it did not complete.
|
|
116
|
+
Report per change: branch, PR URL (or the local branch when nothing was pushed), review outcome (review rounds used, the findings not fixed with their verdicts, and the fix-check result per confirmed finding), CI status (CI attempts used; "not run" when nothing was pushed: with `workflow.open_pr: false`, or when the change failed or was blocked before Step 5), whether it was merged or awaits validation (with `workflow.open_pr: false`, the local branch), and any blocker waiting on the user. In series mode, also state where the series stopped and why if it did not complete.
|
package/plugin/commands/setup.md
CHANGED
|
@@ -1,7 +1,9 @@
|
|
|
1
1
|
---
|
|
2
2
|
description: Install or update theway from a Claude Code session
|
|
3
3
|
author: Amine
|
|
4
|
-
|
|
4
|
+
# x-release-please-start-version
|
|
5
|
+
allowed-tools: Bash(npx --yes @pixelfactoryio/theway@0.5.2 install)
|
|
6
|
+
# x-release-please-end
|
|
5
7
|
---
|
|
6
8
|
|
|
7
9
|
# TheWay: Setup
|
|
@@ -12,9 +14,11 @@ One-time setup: installs the `theway` CLI on your `PATH` and initializes the the
|
|
|
12
14
|
|
|
13
15
|
### Step 1: Run the Installer
|
|
14
16
|
|
|
17
|
+
<!-- x-release-please-start-version -->
|
|
15
18
|
```bash
|
|
16
|
-
npx --yes @pixelfactoryio/theway@
|
|
19
|
+
npx --yes @pixelfactoryio/theway@0.5.2 install
|
|
17
20
|
```
|
|
21
|
+
<!-- x-release-please-end -->
|
|
18
22
|
|
|
19
23
|
### Step 2: Check the Result
|
|
20
24
|
|
|
@@ -50,6 +50,8 @@ workflow:
|
|
|
50
50
|
review_rounds: 1
|
|
51
51
|
# CI attempts per change to reach green, re-runs included
|
|
52
52
|
ci_attempts: 2
|
|
53
|
+
# Push the branch, open the PR and drive CI after the local review; false stops at the reviewed local branch
|
|
54
|
+
open_pr: true
|
|
53
55
|
# Model per agent role: opus or sonnet (absent or invalid means the default)
|
|
54
56
|
# Lower cost: implementer, fix and ci on sonnet, reviewer on opus
|
|
55
57
|
models:
|