@pixelfactoryio/theway 0.5.0 → 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
|
@@ -2094,6 +2094,72 @@ function isFile(path2) {
|
|
|
2094
2094
|
|
|
2095
2095
|
// src/core/list.ts
|
|
2096
2096
|
import { readdirSync, readFileSync as readFileSync2 } from "node:fs";
|
|
2097
|
+
|
|
2098
|
+
// src/core/path.ts
|
|
2099
|
+
import { join as join2, resolve as resolve2 } from "node:path";
|
|
2100
|
+
var CHANGE_ID = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
|
|
2101
|
+
var PROJECT = /^[A-Za-z0-9_][A-Za-z0-9._-]*$/;
|
|
2102
|
+
function changeIdReason(v) {
|
|
2103
|
+
if (v === "")
|
|
2104
|
+
return "must not be empty";
|
|
2105
|
+
if (v.length > 200)
|
|
2106
|
+
return "must be at most 200 characters";
|
|
2107
|
+
if (!CHANGE_ID.test(v))
|
|
2108
|
+
return "must be lowercase letters and digits in words separated by single hyphens";
|
|
2109
|
+
return "";
|
|
2110
|
+
}
|
|
2111
|
+
function projectReason(v) {
|
|
2112
|
+
if (v === "")
|
|
2113
|
+
return "must not be empty";
|
|
2114
|
+
if (v.length > 200)
|
|
2115
|
+
return "must be at most 200 characters";
|
|
2116
|
+
if (!PROJECT.test(v))
|
|
2117
|
+
return 'must be letters, digits, ".", "_" or "-", not starting with "." or "-"';
|
|
2118
|
+
return "";
|
|
2119
|
+
}
|
|
2120
|
+
function invalidSegments(segments) {
|
|
2121
|
+
for (const [label, value] of segments) {
|
|
2122
|
+
if (value === undefined)
|
|
2123
|
+
continue;
|
|
2124
|
+
const reason = label === "project" ? projectReason(value) : changeIdReason(value);
|
|
2125
|
+
if (reason !== "") {
|
|
2126
|
+
const shown = value.replaceAll(`
|
|
2127
|
+
`, "\\n").replaceAll("\r", "\\r");
|
|
2128
|
+
process.stderr.write(`theway: invalid ${label} '${shown}': ${reason}
|
|
2129
|
+
`);
|
|
2130
|
+
return true;
|
|
2131
|
+
}
|
|
2132
|
+
}
|
|
2133
|
+
return false;
|
|
2134
|
+
}
|
|
2135
|
+
function cmdPath(project, changeId, verbose) {
|
|
2136
|
+
if (invalidSegments([
|
|
2137
|
+
["project", project],
|
|
2138
|
+
["change id", changeId]
|
|
2139
|
+
]))
|
|
2140
|
+
return 1;
|
|
2141
|
+
const { home, source } = resolveHome();
|
|
2142
|
+
if (verbose)
|
|
2143
|
+
process.stderr.write(`theway: home ${home} (from ${source})
|
|
2144
|
+
`);
|
|
2145
|
+
if (source === "env") {
|
|
2146
|
+
const pointer = readPointer();
|
|
2147
|
+
if (pointer !== "" && resolve2(pointer) !== home) {
|
|
2148
|
+
process.stderr.write(`theway: warning: THEWAY_HOME is ${home} (from env) but ${pointerPath()} holds ${resolve2(pointer)} (from pointer); using ${home}
|
|
2149
|
+
`);
|
|
2150
|
+
}
|
|
2151
|
+
}
|
|
2152
|
+
let out = home;
|
|
2153
|
+
if (project !== undefined)
|
|
2154
|
+
out = join2(home, project);
|
|
2155
|
+
if (project !== undefined && changeId !== undefined)
|
|
2156
|
+
out = join2(home, project, "changes", changeId);
|
|
2157
|
+
process.stdout.write(`${out}
|
|
2158
|
+
`);
|
|
2159
|
+
return 0;
|
|
2160
|
+
}
|
|
2161
|
+
|
|
2162
|
+
// src/core/list.ts
|
|
2097
2163
|
var CHECKED = /^\s*-\s*\[x\]\s+[0-9]+[a-z]?\./;
|
|
2098
2164
|
var UNCHECKED = /^\s*-\s*\[ \]\s+[0-9]+[a-z]?\./;
|
|
2099
2165
|
function visibleNames(dir) {
|
|
@@ -2132,6 +2198,8 @@ function taskCounts(dir) {
|
|
|
2132
2198
|
return [checked, total];
|
|
2133
2199
|
}
|
|
2134
2200
|
function cmdList(project) {
|
|
2201
|
+
if (invalidSegments([["project", project]]))
|
|
2202
|
+
return 1;
|
|
2135
2203
|
const home = thewayHome();
|
|
2136
2204
|
const base = `${home}/${project}/changes`;
|
|
2137
2205
|
let text = `theway changes — ${project}
|
|
@@ -2182,6 +2250,11 @@ function uncheckedLines(path2) {
|
|
|
2182
2250
|
`).flatMap((line, i) => UNCHECKED.test(line) ? [`${i + 1}:${line}`] : []);
|
|
2183
2251
|
}
|
|
2184
2252
|
function cmdArchive(project, changeId, force) {
|
|
2253
|
+
if (invalidSegments([
|
|
2254
|
+
["project", project],
|
|
2255
|
+
["change id", changeId]
|
|
2256
|
+
]))
|
|
2257
|
+
return 1;
|
|
2185
2258
|
const home = thewayHome();
|
|
2186
2259
|
const src = `${home}/${project}/changes/${changeId}`;
|
|
2187
2260
|
const dst = `${home}/${project}/changes/archive/${localDate()}-${changeId}`;
|
|
@@ -2226,55 +2299,6 @@ ${list}`);
|
|
|
2226
2299
|
return 0;
|
|
2227
2300
|
}
|
|
2228
2301
|
|
|
2229
|
-
// src/core/path.ts
|
|
2230
|
-
import { join as join2, resolve as resolve2 } from "node:path";
|
|
2231
|
-
function segmentReason(name) {
|
|
2232
|
-
if (name === "")
|
|
2233
|
-
return "must not be empty";
|
|
2234
|
-
if (name.includes("/"))
|
|
2235
|
-
return "must not contain /";
|
|
2236
|
-
if (name === "." || name === "..")
|
|
2237
|
-
return `must not be ${name}`;
|
|
2238
|
-
return "";
|
|
2239
|
-
}
|
|
2240
|
-
function cmdPath(project, changeId, verbose) {
|
|
2241
|
-
const segments = [
|
|
2242
|
-
["project", project],
|
|
2243
|
-
["change id", changeId]
|
|
2244
|
-
];
|
|
2245
|
-
for (const [label, value] of segments) {
|
|
2246
|
-
if (value === undefined)
|
|
2247
|
-
continue;
|
|
2248
|
-
const reason = segmentReason(value);
|
|
2249
|
-
if (reason !== "") {
|
|
2250
|
-
const shown = value.replaceAll(`
|
|
2251
|
-
`, "\\n").replaceAll("\r", "\\r");
|
|
2252
|
-
process.stderr.write(`theway: invalid ${label} '${shown}': ${reason}
|
|
2253
|
-
`);
|
|
2254
|
-
return 1;
|
|
2255
|
-
}
|
|
2256
|
-
}
|
|
2257
|
-
const { home, source } = resolveHome();
|
|
2258
|
-
if (verbose)
|
|
2259
|
-
process.stderr.write(`theway: home ${home} (from ${source})
|
|
2260
|
-
`);
|
|
2261
|
-
if (source === "env") {
|
|
2262
|
-
const pointer = readPointer();
|
|
2263
|
-
if (pointer !== "" && resolve2(pointer) !== home) {
|
|
2264
|
-
process.stderr.write(`theway: warning: THEWAY_HOME is ${home} (from env) but ${pointerPath()} holds ${resolve2(pointer)} (from pointer); using ${home}
|
|
2265
|
-
`);
|
|
2266
|
-
}
|
|
2267
|
-
}
|
|
2268
|
-
let out = home;
|
|
2269
|
-
if (project !== undefined)
|
|
2270
|
-
out = join2(home, project);
|
|
2271
|
-
if (project !== undefined && changeId !== undefined)
|
|
2272
|
-
out = join2(home, project, "changes", changeId);
|
|
2273
|
-
process.stdout.write(`${out}
|
|
2274
|
-
`);
|
|
2275
|
-
return 0;
|
|
2276
|
-
}
|
|
2277
|
-
|
|
2278
2302
|
// src/core/validate-id.ts
|
|
2279
2303
|
var VERB = /^(add|update|refactor|remove)-/;
|
|
2280
2304
|
var KEBAB = /^(add|update|refactor|remove)-[a-z0-9]+(-[a-z0-9]+)*$/;
|
|
@@ -2344,14 +2368,16 @@ import {
|
|
|
2344
2368
|
lstatSync,
|
|
2345
2369
|
mkdirSync as mkdirSync3,
|
|
2346
2370
|
readFileSync as readFileSync4,
|
|
2371
|
+
readlinkSync,
|
|
2347
2372
|
realpathSync,
|
|
2348
2373
|
renameSync as renameSync2,
|
|
2349
2374
|
rmdirSync,
|
|
2350
2375
|
rmSync,
|
|
2376
|
+
statSync as statSync2,
|
|
2351
2377
|
writeFileSync
|
|
2352
2378
|
} from "node:fs";
|
|
2353
2379
|
import { homedir as homedir2 } from "node:os";
|
|
2354
|
-
import { delimiter, dirname, join as join3, resolve as resolve3 } from "node:path";
|
|
2380
|
+
import { delimiter, dirname, join as join3, resolve as resolve3, sep } from "node:path";
|
|
2355
2381
|
import { fileURLToPath } from "node:url";
|
|
2356
2382
|
|
|
2357
2383
|
// src/core/init.ts
|
|
@@ -2395,10 +2421,15 @@ function installDir() {
|
|
|
2395
2421
|
function shownHome(home) {
|
|
2396
2422
|
return resolve3(home) === resolve3(defaultHome()) ? "~/.theway" : resolve3(home);
|
|
2397
2423
|
}
|
|
2398
|
-
function
|
|
2424
|
+
function ruleRoot(home) {
|
|
2399
2425
|
const at = shownHome(home);
|
|
2400
|
-
|
|
2401
|
-
|
|
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/**)`;
|
|
2402
2433
|
}
|
|
2403
2434
|
function rules(home) {
|
|
2404
2435
|
return ["Bash(theway:*)", ...homeRules(home)];
|
|
@@ -2438,11 +2469,48 @@ function readSettings(path2) {
|
|
|
2438
2469
|
}
|
|
2439
2470
|
return data;
|
|
2440
2471
|
}
|
|
2441
|
-
function
|
|
2442
|
-
|
|
2443
|
-
|
|
2444
|
-
|
|
2445
|
-
|
|
2472
|
+
function settingsTarget(path2) {
|
|
2473
|
+
let target = path2;
|
|
2474
|
+
const seen = new Set;
|
|
2475
|
+
for (;; ) {
|
|
2476
|
+
let link;
|
|
2477
|
+
try {
|
|
2478
|
+
link = lstatSync(target).isSymbolicLink();
|
|
2479
|
+
} catch {
|
|
2480
|
+
break;
|
|
2481
|
+
}
|
|
2482
|
+
if (!link)
|
|
2483
|
+
break;
|
|
2484
|
+
if (seen.has(target) || seen.size >= 40)
|
|
2485
|
+
return { error: "it is a symlink loop" };
|
|
2486
|
+
seen.add(target);
|
|
2487
|
+
target = resolve3(dirname(target), readlinkSync(target));
|
|
2488
|
+
}
|
|
2489
|
+
let dir = dirname(target);
|
|
2490
|
+
while (!existsSync3(dir) && dirname(dir) !== dir)
|
|
2491
|
+
dir = dirname(dir);
|
|
2492
|
+
try {
|
|
2493
|
+
accessSync(dir, constants.W_OK);
|
|
2494
|
+
} catch {
|
|
2495
|
+
return { error: `${dir} is not writable` };
|
|
2496
|
+
}
|
|
2497
|
+
return { target };
|
|
2498
|
+
}
|
|
2499
|
+
function unwritableSettings(path2, reason) {
|
|
2500
|
+
return fail(`theway: cannot write ${path2}: ${reason}; nothing was changed`);
|
|
2501
|
+
}
|
|
2502
|
+
function writeSettings(target, settings) {
|
|
2503
|
+
mkdirSync3(dirname(target), { recursive: true });
|
|
2504
|
+
const mode = existsSync3(target) ? statSync2(target).mode & 511 : 384;
|
|
2505
|
+
const tmp = `${target}.tmp-${process.pid}`;
|
|
2506
|
+
try {
|
|
2507
|
+
writeFileSync(tmp, `${JSON.stringify(settings, null, 2)}
|
|
2508
|
+
`, { mode });
|
|
2509
|
+
chmodSync(tmp, mode);
|
|
2510
|
+
renameSync2(tmp, target);
|
|
2511
|
+
} finally {
|
|
2512
|
+
rmSync(tmp, { force: true });
|
|
2513
|
+
}
|
|
2446
2514
|
}
|
|
2447
2515
|
function invalidSettings(path2) {
|
|
2448
2516
|
return fail(`theway: ${path2} is not valid settings JSON; nothing was changed`);
|
|
@@ -2471,11 +2539,25 @@ function removeIfEmpty(dir) {
|
|
|
2471
2539
|
rmdirSync(dir);
|
|
2472
2540
|
} catch {}
|
|
2473
2541
|
}
|
|
2542
|
+
function legacyText(path2, match) {
|
|
2543
|
+
try {
|
|
2544
|
+
return lstatSync(path2).isFile() && match(readFileSync4(path2, "utf-8"));
|
|
2545
|
+
} catch {
|
|
2546
|
+
return false;
|
|
2547
|
+
}
|
|
2548
|
+
}
|
|
2474
2549
|
function removeLegacyBin(home) {
|
|
2475
2550
|
for (const h of new Set([defaultHome(), resolve3(home)])) {
|
|
2476
2551
|
const bin = join3(h, "bin");
|
|
2477
|
-
|
|
2478
|
-
|
|
2552
|
+
if (legacyText(join3(bin, "theway"), (t) => t.startsWith(`#!/bin/sh
|
|
2553
|
+
exec node `) && t.endsWith(`theway.js' "$@"
|
|
2554
|
+
`))) {
|
|
2555
|
+
rmSync(join3(bin, "theway"), { force: true });
|
|
2556
|
+
}
|
|
2557
|
+
if (legacyText(join3(bin, "theway.js"), (t) => t.startsWith(`#!/usr/bin/env node
|
|
2558
|
+
`))) {
|
|
2559
|
+
rmSync(join3(bin, "theway.js"), { force: true });
|
|
2560
|
+
}
|
|
2479
2561
|
removeIfEmpty(bin);
|
|
2480
2562
|
}
|
|
2481
2563
|
}
|
|
@@ -2527,6 +2609,17 @@ function realpathOr(path2) {
|
|
|
2527
2609
|
return resolve3(path2);
|
|
2528
2610
|
}
|
|
2529
2611
|
}
|
|
2612
|
+
function unsafeHomeReason(tHome, custom) {
|
|
2613
|
+
const home = resolve3(tHome);
|
|
2614
|
+
const real = realpathOr(home);
|
|
2615
|
+
const user = realpathOr(homedir2());
|
|
2616
|
+
if (real === user || user.startsWith(real + sep) || real === "/") {
|
|
2617
|
+
return "it is your home folder or one of its parents";
|
|
2618
|
+
}
|
|
2619
|
+
if (custom && /[*?[\]{}\n\r]/.test(home))
|
|
2620
|
+
return "it contains a glob character or a line break";
|
|
2621
|
+
return "";
|
|
2622
|
+
}
|
|
2530
2623
|
function copiesOnPath() {
|
|
2531
2624
|
const running = realpathOr(self);
|
|
2532
2625
|
const seen = new Set;
|
|
@@ -2572,7 +2665,14 @@ function install() {
|
|
|
2572
2665
|
const custom = tHome !== resolve3(defaultHome());
|
|
2573
2666
|
const dir = installDir();
|
|
2574
2667
|
const settingsPath = join3(cHome, "settings.json");
|
|
2575
|
-
const
|
|
2668
|
+
const unsafe = unsafeHomeReason(tHome, custom);
|
|
2669
|
+
if (unsafe !== "") {
|
|
2670
|
+
return fail(`theway: refusing data home ${resolve3(tHome)}: ${unsafe}; set THEWAY_HOME to a dedicated folder`);
|
|
2671
|
+
}
|
|
2672
|
+
const resolved = settingsTarget(settingsPath);
|
|
2673
|
+
if ("error" in resolved)
|
|
2674
|
+
return unwritableSettings(settingsPath, resolved.error);
|
|
2675
|
+
const settings = readSettings(resolved.target);
|
|
2576
2676
|
if (settings === null)
|
|
2577
2677
|
return invalidSettings(settingsPath);
|
|
2578
2678
|
const target = join3(dir, "theway");
|
|
@@ -2598,13 +2698,18 @@ function install() {
|
|
|
2598
2698
|
const perms = settings.permissions ?? {};
|
|
2599
2699
|
const allow = perms.allow ?? [];
|
|
2600
2700
|
const current = rules(tHome);
|
|
2601
|
-
const stale = [
|
|
2701
|
+
const stale = [
|
|
2702
|
+
...legacyRules(tHome),
|
|
2703
|
+
editRule(tHome),
|
|
2704
|
+
editRule(previous),
|
|
2705
|
+
...homeRules(previous).filter((r) => !current.includes(r))
|
|
2706
|
+
];
|
|
2602
2707
|
const kept = allow.filter((r) => !(typeof r === "string" && stale.includes(r)));
|
|
2603
2708
|
const missing = current.filter((r) => !kept.includes(r));
|
|
2604
2709
|
if (missing.length > 0 || kept.length !== allow.length) {
|
|
2605
2710
|
settings.permissions = { ...perms, allow: [...kept, ...missing] };
|
|
2606
2711
|
mkdirSync3(cHome, { recursive: true });
|
|
2607
|
-
writeSettings(
|
|
2712
|
+
writeSettings(resolved.target, settings);
|
|
2608
2713
|
}
|
|
2609
2714
|
checkPath(dir, binary);
|
|
2610
2715
|
const version = JSON.parse(readFileSync4(join3(pkgRoot, "package.json"), "utf-8")).version;
|
|
@@ -2617,6 +2722,13 @@ function uninstall() {
|
|
|
2617
2722
|
const tHome = resolveHome().home;
|
|
2618
2723
|
const homes = [...new Set([tHome, recordedHome(), defaultHome()])];
|
|
2619
2724
|
const settingsPath = join3(cHome, "settings.json");
|
|
2725
|
+
let settingsFile = settingsPath;
|
|
2726
|
+
if (occupied(settingsPath)) {
|
|
2727
|
+
const resolved = settingsTarget(settingsPath);
|
|
2728
|
+
if ("error" in resolved)
|
|
2729
|
+
return unwritableSettings(settingsPath, resolved.error);
|
|
2730
|
+
settingsFile = resolved.target;
|
|
2731
|
+
}
|
|
2620
2732
|
rmSync(join3(cHome, "skills", "theway"), { recursive: true, force: true });
|
|
2621
2733
|
const binary = join3(installDir(), "theway");
|
|
2622
2734
|
const removed = isThewayBinary(binary);
|
|
@@ -2625,16 +2737,16 @@ function uninstall() {
|
|
|
2625
2737
|
rmSync(pointerPath(), { force: true });
|
|
2626
2738
|
removeIfEmpty(dirname(pointerPath()));
|
|
2627
2739
|
if (existsSync3(settingsPath)) {
|
|
2628
|
-
const settings = readSettings(
|
|
2740
|
+
const settings = readSettings(settingsFile);
|
|
2629
2741
|
if (settings === null)
|
|
2630
2742
|
return invalidSettings(settingsPath);
|
|
2631
2743
|
const allow = settings.permissions?.allow;
|
|
2632
2744
|
if (Array.isArray(allow)) {
|
|
2633
|
-
const drop = homes.flatMap((h) => [...rules(h), ...legacyRules(h)]);
|
|
2745
|
+
const drop = homes.flatMap((h) => [...rules(h), ...legacyRules(h), editRule(h)]);
|
|
2634
2746
|
const kept = allow.filter((r) => !(typeof r === "string" && drop.includes(r)));
|
|
2635
2747
|
if (kept.length !== allow.length) {
|
|
2636
2748
|
settings.permissions = { ...settings.permissions, allow: kept };
|
|
2637
|
-
writeSettings(
|
|
2749
|
+
writeSettings(settingsFile, settings);
|
|
2638
2750
|
}
|
|
2639
2751
|
}
|
|
2640
2752
|
}
|
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:
|