@pixelfactoryio/theway 0.5.1 → 0.5.3
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
|
@@ -2363,25 +2363,114 @@ import {
|
|
|
2363
2363
|
chmodSync,
|
|
2364
2364
|
constants,
|
|
2365
2365
|
copyFileSync as copyFileSync2,
|
|
2366
|
-
cpSync
|
|
2366
|
+
cpSync,
|
|
2367
2367
|
existsSync as existsSync3,
|
|
2368
2368
|
lstatSync,
|
|
2369
2369
|
mkdirSync as mkdirSync3,
|
|
2370
|
-
readFileSync as
|
|
2370
|
+
readFileSync as readFileSync5,
|
|
2371
2371
|
readlinkSync,
|
|
2372
2372
|
realpathSync,
|
|
2373
|
-
renameSync as
|
|
2373
|
+
renameSync as renameSync3,
|
|
2374
2374
|
rmdirSync,
|
|
2375
|
-
rmSync,
|
|
2375
|
+
rmSync as rmSync2,
|
|
2376
2376
|
statSync as statSync2,
|
|
2377
|
-
writeFileSync
|
|
2377
|
+
writeFileSync as writeFileSync2
|
|
2378
2378
|
} from "node:fs";
|
|
2379
2379
|
import { homedir as homedir2 } from "node:os";
|
|
2380
2380
|
import { delimiter, dirname, join as join3, resolve as resolve3, sep } from "node:path";
|
|
2381
2381
|
import { fileURLToPath } from "node:url";
|
|
2382
2382
|
|
|
2383
2383
|
// src/core/init.ts
|
|
2384
|
-
import {
|
|
2384
|
+
import { createHash } from "node:crypto";
|
|
2385
|
+
import {
|
|
2386
|
+
copyFileSync,
|
|
2387
|
+
existsSync as existsSync2,
|
|
2388
|
+
mkdirSync as mkdirSync2,
|
|
2389
|
+
readdirSync as readdirSync2,
|
|
2390
|
+
readFileSync as readFileSync4,
|
|
2391
|
+
renameSync as renameSync2,
|
|
2392
|
+
rmSync,
|
|
2393
|
+
writeFileSync
|
|
2394
|
+
} from "node:fs";
|
|
2395
|
+
var SHIPPED_DIRS = ["data/standards", "templates"];
|
|
2396
|
+
var MANIFEST = ".shipped.json";
|
|
2397
|
+
var sha256 = (data) => createHash("sha256").update(data).digest("hex");
|
|
2398
|
+
function readManifest(home) {
|
|
2399
|
+
try {
|
|
2400
|
+
const parsed = JSON.parse(readFileSync4(`${home}/${MANIFEST}`, "utf-8"));
|
|
2401
|
+
if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed))
|
|
2402
|
+
return;
|
|
2403
|
+
return parsed;
|
|
2404
|
+
} catch {
|
|
2405
|
+
return;
|
|
2406
|
+
}
|
|
2407
|
+
}
|
|
2408
|
+
function writeAtomic(target, data) {
|
|
2409
|
+
const tmp = `${target}.tmp-${process.pid}`;
|
|
2410
|
+
try {
|
|
2411
|
+
writeFileSync(tmp, data);
|
|
2412
|
+
renameSync2(tmp, target);
|
|
2413
|
+
} finally {
|
|
2414
|
+
rmSync(tmp, { force: true });
|
|
2415
|
+
}
|
|
2416
|
+
}
|
|
2417
|
+
function writeManifest(home, manifest) {
|
|
2418
|
+
writeAtomic(`${home}/${MANIFEST}`, `${JSON.stringify(manifest, null, 2)}
|
|
2419
|
+
`);
|
|
2420
|
+
}
|
|
2421
|
+
function backupPath(home, rel, current) {
|
|
2422
|
+
const bak = `${rel}.bak`;
|
|
2423
|
+
if (!existsSync2(`${home}/${bak}`) || readFileSync4(`${home}/${bak}`).equals(current))
|
|
2424
|
+
return bak;
|
|
2425
|
+
for (let n = 1;; n++) {
|
|
2426
|
+
if (!existsSync2(`${home}/${bak}.${n}`))
|
|
2427
|
+
return `${bak}.${n}`;
|
|
2428
|
+
}
|
|
2429
|
+
}
|
|
2430
|
+
function copyShipped(src, home) {
|
|
2431
|
+
const previous = readManifest(home);
|
|
2432
|
+
const manifest = {};
|
|
2433
|
+
for (const dir of SHIPPED_DIRS) {
|
|
2434
|
+
mkdirSync2(`${home}/${dir}`, { recursive: true });
|
|
2435
|
+
const names = readdirSync2(`${src}/${dir}`, { withFileTypes: true }).filter((e) => e.isFile() && e.name.endsWith(".md")).map((e) => e.name).sort();
|
|
2436
|
+
for (const name of names) {
|
|
2437
|
+
const rel = `${dir}/${name}`;
|
|
2438
|
+
const dst = `${home}/${rel}`;
|
|
2439
|
+
const shipped = readFileSync4(`${src}/${rel}`);
|
|
2440
|
+
const old = previous?.[rel];
|
|
2441
|
+
const sibling = `${dir}/${name.slice(0, -".md".length)}.default.md`;
|
|
2442
|
+
let removeSibling = true;
|
|
2443
|
+
if (!existsSync2(dst)) {
|
|
2444
|
+
writeAtomic(dst, shipped);
|
|
2445
|
+
} else {
|
|
2446
|
+
const current = readFileSync4(dst);
|
|
2447
|
+
if (!current.equals(shipped)) {
|
|
2448
|
+
if (typeof old === "string") {
|
|
2449
|
+
if (sha256(current) === old) {
|
|
2450
|
+
writeAtomic(dst, shipped);
|
|
2451
|
+
} else {
|
|
2452
|
+
removeSibling = false;
|
|
2453
|
+
writeAtomic(`${home}/${sibling}`, shipped);
|
|
2454
|
+
process.stdout.write(`Kept your edited ${rel} (shipped version: ${sibling})
|
|
2455
|
+
`);
|
|
2456
|
+
}
|
|
2457
|
+
} else {
|
|
2458
|
+
removeSibling = false;
|
|
2459
|
+
const bak = backupPath(home, rel, current);
|
|
2460
|
+
copyFileSync(dst, `${home}/${bak}`);
|
|
2461
|
+
writeAtomic(dst, shipped);
|
|
2462
|
+
process.stdout.write(`Replaced ${rel}; your previous version is in ${bak}
|
|
2463
|
+
`);
|
|
2464
|
+
}
|
|
2465
|
+
}
|
|
2466
|
+
}
|
|
2467
|
+
if (removeSibling)
|
|
2468
|
+
rmSync(`${home}/${sibling}`, { force: true });
|
|
2469
|
+
manifest[rel] = sha256(shipped);
|
|
2470
|
+
}
|
|
2471
|
+
}
|
|
2472
|
+
writeManifest(home, manifest);
|
|
2473
|
+
}
|
|
2385
2474
|
function init(src, home) {
|
|
2386
2475
|
try {
|
|
2387
2476
|
mkdirSync2(home, { recursive: true });
|
|
@@ -2392,8 +2481,7 @@ function init(src, home) {
|
|
|
2392
2481
|
} else {
|
|
2393
2482
|
copyFileSync(`${src}/config.yaml`, `${home}/config.yaml`);
|
|
2394
2483
|
}
|
|
2395
|
-
|
|
2396
|
-
cpSync(`${src}/templates`, `${home}/templates`, { recursive: true });
|
|
2484
|
+
copyShipped(src, home);
|
|
2397
2485
|
} catch (e) {
|
|
2398
2486
|
process.stderr.write(`theway: ${e.message}
|
|
2399
2487
|
`);
|
|
@@ -2421,10 +2509,15 @@ function installDir() {
|
|
|
2421
2509
|
function shownHome(home) {
|
|
2422
2510
|
return resolve3(home) === resolve3(defaultHome()) ? "~/.theway" : resolve3(home);
|
|
2423
2511
|
}
|
|
2424
|
-
function
|
|
2512
|
+
function ruleRoot(home) {
|
|
2425
2513
|
const at = shownHome(home);
|
|
2426
|
-
|
|
2427
|
-
|
|
2514
|
+
return at.startsWith("~/") ? at : `/${at}`;
|
|
2515
|
+
}
|
|
2516
|
+
function homeRules(home) {
|
|
2517
|
+
return [`Read(${ruleRoot(home)}/**)`];
|
|
2518
|
+
}
|
|
2519
|
+
function editRule(home) {
|
|
2520
|
+
return `Edit(${ruleRoot(home)}/*/changes/**)`;
|
|
2428
2521
|
}
|
|
2429
2522
|
function rules(home) {
|
|
2430
2523
|
return ["Bash(theway:*)", ...homeRules(home)];
|
|
@@ -2449,7 +2542,7 @@ function readSettings(path2) {
|
|
|
2449
2542
|
return {};
|
|
2450
2543
|
let data;
|
|
2451
2544
|
try {
|
|
2452
|
-
data = JSON.parse(
|
|
2545
|
+
data = JSON.parse(readFileSync5(path2, "utf-8"));
|
|
2453
2546
|
} catch {
|
|
2454
2547
|
return null;
|
|
2455
2548
|
}
|
|
@@ -2499,12 +2592,12 @@ function writeSettings(target, settings) {
|
|
|
2499
2592
|
const mode = existsSync3(target) ? statSync2(target).mode & 511 : 384;
|
|
2500
2593
|
const tmp = `${target}.tmp-${process.pid}`;
|
|
2501
2594
|
try {
|
|
2502
|
-
|
|
2595
|
+
writeFileSync2(tmp, `${JSON.stringify(settings, null, 2)}
|
|
2503
2596
|
`, { mode });
|
|
2504
2597
|
chmodSync(tmp, mode);
|
|
2505
|
-
|
|
2598
|
+
renameSync3(tmp, target);
|
|
2506
2599
|
} finally {
|
|
2507
|
-
|
|
2600
|
+
rmSync2(tmp, { force: true });
|
|
2508
2601
|
}
|
|
2509
2602
|
}
|
|
2510
2603
|
function invalidSettings(path2) {
|
|
@@ -2514,19 +2607,19 @@ function copyPlugin(home) {
|
|
|
2514
2607
|
const tmp = join3(home, `.theway-install-${process.pid}`);
|
|
2515
2608
|
const old = join3(home, `.theway-old-${process.pid}`);
|
|
2516
2609
|
const dest = join3(home, "skills", "theway");
|
|
2517
|
-
|
|
2610
|
+
rmSync2(tmp, { recursive: true, force: true });
|
|
2518
2611
|
try {
|
|
2519
2612
|
for (const dir of PLUGIN_DIRS) {
|
|
2520
|
-
|
|
2613
|
+
cpSync(join3(plugin, dir), join3(tmp, dir), { recursive: true });
|
|
2521
2614
|
}
|
|
2522
2615
|
mkdirSync3(join3(home, "skills"), { recursive: true });
|
|
2523
2616
|
if (existsSync3(dest))
|
|
2524
|
-
|
|
2525
|
-
|
|
2617
|
+
renameSync3(dest, old);
|
|
2618
|
+
renameSync3(tmp, dest);
|
|
2526
2619
|
} finally {
|
|
2527
|
-
|
|
2620
|
+
rmSync2(tmp, { recursive: true, force: true });
|
|
2528
2621
|
}
|
|
2529
|
-
|
|
2622
|
+
rmSync2(old, { recursive: true, force: true });
|
|
2530
2623
|
return dest;
|
|
2531
2624
|
}
|
|
2532
2625
|
function removeIfEmpty(dir) {
|
|
@@ -2536,7 +2629,7 @@ function removeIfEmpty(dir) {
|
|
|
2536
2629
|
}
|
|
2537
2630
|
function legacyText(path2, match) {
|
|
2538
2631
|
try {
|
|
2539
|
-
return lstatSync(path2).isFile() && match(
|
|
2632
|
+
return lstatSync(path2).isFile() && match(readFileSync5(path2, "utf-8"));
|
|
2540
2633
|
} catch {
|
|
2541
2634
|
return false;
|
|
2542
2635
|
}
|
|
@@ -2547,11 +2640,11 @@ function removeLegacyBin(home) {
|
|
|
2547
2640
|
if (legacyText(join3(bin, "theway"), (t) => t.startsWith(`#!/bin/sh
|
|
2548
2641
|
exec node `) && t.endsWith(`theway.js' "$@"
|
|
2549
2642
|
`))) {
|
|
2550
|
-
|
|
2643
|
+
rmSync2(join3(bin, "theway"), { force: true });
|
|
2551
2644
|
}
|
|
2552
2645
|
if (legacyText(join3(bin, "theway.js"), (t) => t.startsWith(`#!/usr/bin/env node
|
|
2553
2646
|
`))) {
|
|
2554
|
-
|
|
2647
|
+
rmSync2(join3(bin, "theway.js"), { force: true });
|
|
2555
2648
|
}
|
|
2556
2649
|
removeIfEmpty(bin);
|
|
2557
2650
|
}
|
|
@@ -2563,9 +2656,9 @@ function writeBinary(dir) {
|
|
|
2563
2656
|
try {
|
|
2564
2657
|
copyFileSync2(self, tmp);
|
|
2565
2658
|
chmodSync(tmp, 493);
|
|
2566
|
-
|
|
2659
|
+
renameSync3(tmp, dest);
|
|
2567
2660
|
} finally {
|
|
2568
|
-
|
|
2661
|
+
rmSync2(tmp, { force: true });
|
|
2569
2662
|
}
|
|
2570
2663
|
return dest;
|
|
2571
2664
|
}
|
|
@@ -2581,7 +2674,7 @@ function isThewayBinary(path2) {
|
|
|
2581
2674
|
if (!isFile(path2))
|
|
2582
2675
|
return false;
|
|
2583
2676
|
try {
|
|
2584
|
-
const text =
|
|
2677
|
+
const text = readFileSync5(path2, "utf-8");
|
|
2585
2678
|
return text.startsWith("#!/usr/bin/env node") && text.includes(BINARY_MARKER);
|
|
2586
2679
|
} catch {
|
|
2587
2680
|
return false;
|
|
@@ -2591,10 +2684,10 @@ function writePointer(home, custom) {
|
|
|
2591
2684
|
const path2 = pointerPath();
|
|
2592
2685
|
if (custom) {
|
|
2593
2686
|
mkdirSync3(dirname(path2), { recursive: true });
|
|
2594
|
-
|
|
2687
|
+
writeFileSync2(path2, `${home}
|
|
2595
2688
|
`);
|
|
2596
2689
|
} else {
|
|
2597
|
-
|
|
2690
|
+
rmSync2(path2, { force: true });
|
|
2598
2691
|
}
|
|
2599
2692
|
}
|
|
2600
2693
|
function realpathOr(path2) {
|
|
@@ -2693,7 +2786,12 @@ function install() {
|
|
|
2693
2786
|
const perms = settings.permissions ?? {};
|
|
2694
2787
|
const allow = perms.allow ?? [];
|
|
2695
2788
|
const current = rules(tHome);
|
|
2696
|
-
const stale = [
|
|
2789
|
+
const stale = [
|
|
2790
|
+
...legacyRules(tHome),
|
|
2791
|
+
editRule(tHome),
|
|
2792
|
+
editRule(previous),
|
|
2793
|
+
...homeRules(previous).filter((r) => !current.includes(r))
|
|
2794
|
+
];
|
|
2697
2795
|
const kept = allow.filter((r) => !(typeof r === "string" && stale.includes(r)));
|
|
2698
2796
|
const missing = current.filter((r) => !kept.includes(r));
|
|
2699
2797
|
if (missing.length > 0 || kept.length !== allow.length) {
|
|
@@ -2702,7 +2800,7 @@ function install() {
|
|
|
2702
2800
|
writeSettings(resolved.target, settings);
|
|
2703
2801
|
}
|
|
2704
2802
|
checkPath(dir, binary);
|
|
2705
|
-
const version = JSON.parse(
|
|
2803
|
+
const version = JSON.parse(readFileSync5(join3(pkgRoot, "package.json"), "utf-8")).version;
|
|
2706
2804
|
process.stdout.write(`Installed theway ${version} to ${dest} (theway@skills-dir), ${binary} and ${tHome}. Start a new Claude Code session or run /reload-plugins.
|
|
2707
2805
|
`);
|
|
2708
2806
|
return 0;
|
|
@@ -2719,12 +2817,12 @@ function uninstall() {
|
|
|
2719
2817
|
return unwritableSettings(settingsPath, resolved.error);
|
|
2720
2818
|
settingsFile = resolved.target;
|
|
2721
2819
|
}
|
|
2722
|
-
|
|
2820
|
+
rmSync2(join3(cHome, "skills", "theway"), { recursive: true, force: true });
|
|
2723
2821
|
const binary = join3(installDir(), "theway");
|
|
2724
2822
|
const removed = isThewayBinary(binary);
|
|
2725
2823
|
if (removed)
|
|
2726
|
-
|
|
2727
|
-
|
|
2824
|
+
rmSync2(binary, { force: true });
|
|
2825
|
+
rmSync2(pointerPath(), { force: true });
|
|
2728
2826
|
removeIfEmpty(dirname(pointerPath()));
|
|
2729
2827
|
if (existsSync3(settingsPath)) {
|
|
2730
2828
|
const settings = readSettings(settingsFile);
|
|
@@ -2732,7 +2830,7 @@ function uninstall() {
|
|
|
2732
2830
|
return invalidSettings(settingsPath);
|
|
2733
2831
|
const allow = settings.permissions?.allow;
|
|
2734
2832
|
if (Array.isArray(allow)) {
|
|
2735
|
-
const drop = homes.flatMap((h) => [...rules(h), ...legacyRules(h)]);
|
|
2833
|
+
const drop = homes.flatMap((h) => [...rules(h), ...legacyRules(h), editRule(h)]);
|
|
2736
2834
|
const kept = allow.filter((r) => !(typeof r === "string" && drop.includes(r)));
|
|
2737
2835
|
if (kept.length !== allow.length) {
|
|
2738
2836
|
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.3",
|
|
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.3 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.3 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:
|