@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 as cpSync2,
2366
+ cpSync,
2367
2367
  existsSync as existsSync3,
2368
2368
  lstatSync,
2369
2369
  mkdirSync as mkdirSync3,
2370
- readFileSync as readFileSync4,
2370
+ readFileSync as readFileSync5,
2371
2371
  readlinkSync,
2372
2372
  realpathSync,
2373
- renameSync as renameSync2,
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 { copyFileSync, cpSync, existsSync as existsSync2, mkdirSync as mkdirSync2 } from "node:fs";
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
- cpSync(`${src}/data/standards`, `${home}/data/standards`, { recursive: true });
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 homeRules(home) {
2512
+ function ruleRoot(home) {
2425
2513
  const at = shownHome(home);
2426
- const root = at.startsWith("~/") ? at : `/${at}`;
2427
- return [`Read(${root}/**)`, `Edit(${root}/*/changes/**)`];
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(readFileSync4(path2, "utf-8"));
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
- writeFileSync(tmp, `${JSON.stringify(settings, null, 2)}
2595
+ writeFileSync2(tmp, `${JSON.stringify(settings, null, 2)}
2503
2596
  `, { mode });
2504
2597
  chmodSync(tmp, mode);
2505
- renameSync2(tmp, target);
2598
+ renameSync3(tmp, target);
2506
2599
  } finally {
2507
- rmSync(tmp, { force: true });
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
- rmSync(tmp, { recursive: true, force: true });
2610
+ rmSync2(tmp, { recursive: true, force: true });
2518
2611
  try {
2519
2612
  for (const dir of PLUGIN_DIRS) {
2520
- cpSync2(join3(plugin, dir), join3(tmp, dir), { recursive: true });
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
- renameSync2(dest, old);
2525
- renameSync2(tmp, dest);
2617
+ renameSync3(dest, old);
2618
+ renameSync3(tmp, dest);
2526
2619
  } finally {
2527
- rmSync(tmp, { recursive: true, force: true });
2620
+ rmSync2(tmp, { recursive: true, force: true });
2528
2621
  }
2529
- rmSync(old, { recursive: true, force: true });
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(readFileSync4(path2, "utf-8"));
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
- rmSync(join3(bin, "theway"), { force: true });
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
- rmSync(join3(bin, "theway.js"), { force: true });
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
- renameSync2(tmp, dest);
2659
+ renameSync3(tmp, dest);
2567
2660
  } finally {
2568
- rmSync(tmp, { force: true });
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 = readFileSync4(path2, "utf-8");
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
- writeFileSync(path2, `${home}
2687
+ writeFileSync2(path2, `${home}
2595
2688
  `);
2596
2689
  } else {
2597
- rmSync(path2, { force: true });
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 = [...legacyRules(tHome), ...homeRules(previous).filter((r) => !current.includes(r))];
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(readFileSync4(join3(pkgRoot, "package.json"), "utf-8")).version;
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
- rmSync(join3(cHome, "skills", "theway"), { recursive: true, force: true });
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
- rmSync(binary, { force: true });
2727
- rmSync(pointerPath(), { force: true });
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": "@pixelfactoryio/theway",
3
- "version": "0.5.1",
3
+ "version": "0.5.3",
4
4
  "description": "A spec-first workflow for Claude Code",
5
5
  "license": "MIT",
6
6
  "repository": {
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "theway",
3
- "version": "0.5.1",
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 that open a PR, then review it and drive CI to green
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. Merging is implied: each change's PR must be merged before the next change starts, since later changes build on earlier ones.
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 pushing branches, opening PRs, and merging exactly as the syntax above grants — nothing more. This invocation is also the explicit opt-in for the Workflow tool. Do not ask for permission mid-run for actions the syntax already grants; do not perform outward actions it doesn't.
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), then pushes the branch and opens the PR (Step 4) and returns the PR URL, its verification and any blocker. The orchestrator — not the agents — checks off completed tasks in `<change-dir>/tasks.md` and records discoveries in its Notes section.
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 5: Review and CI
68
+ ### Step 4: Local Review
74
69
 
75
- Once the PR is open, run up to `review_rounds` review rounds while CI runs. With `review_rounds: 0`, skip the reviewers, the triage and the fix check: only CI runs, and the round below reduces to its CI part.
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 while CI runs.** Start the reviewers and the CI polling together, on the PR's current head.
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 PR's).
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. **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.
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
- 4. **Fix once.** When the round has confirmed findings or CI failed for this PR, spawn one fix agent with both: the confirmed findings and the quoted CI error. It commits the fixes on the branch and pushes once.
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. A round with no confirmed findings and CI green ends the step. Otherwise start the next round only while rounds remain under `review_rounds`; the next round reviews the new head. After the last round, keep driving CI alone (triage, fix agent with the CI failure only, re-runs) until it is green or `ci_attempts` attempts are used. If CI is still red after attempt `ci_attempts`, the change failed (Step 6).
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: squash-merge the PR, sync main, then continue with the next change ID.
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.
@@ -1,7 +1,9 @@
1
1
  ---
2
2
  description: Install or update theway from a Claude Code session
3
3
  author: Amine
4
- allowed-tools: Bash(npx --yes @pixelfactoryio/theway@latest install)
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@latest install
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: