@pixelfactoryio/theway 0.15.0 → 0.17.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/dist/theway.js CHANGED
@@ -10339,7 +10339,7 @@ function cmdNextId(seriesId, count, override) {
10339
10339
  import { basename as basename2, join as join9, relative } from "node:path";
10340
10340
  var WORKFLOW_VERSION = "theway.workflow/v1";
10341
10341
  var STEP_VERSION = "theway.step/v1";
10342
- var WORKFLOW_KEYS = ["version", "input", "default", "agents", "steps"];
10342
+ var WORKFLOW_KEYS = ["version", "description", "input", "default", "agents", "steps"];
10343
10343
  var STEP_KEYS = ["version", "description", "params", "do"];
10344
10344
  var TYPES = ["work", "findings", "verdicts", "resolutions", "pr", "ci", "diagnosis", "scaffold", "edits"];
10345
10345
  var CONDITIONS = [
@@ -10986,6 +10986,13 @@ function validateOrThrow(d, path2) {
10986
10986
  const idOf = uniqueNames(literalIds);
10987
10987
  const cache = new Map;
10988
10988
  for (const key of root.keys()) {
10989
+ if (key === "description") {
10990
+ const v = root.get(key);
10991
+ if (typeof v !== "string" || v.trim() === "")
10992
+ fail2("description must be a non-empty string");
10993
+ if (v.includes("${"))
10994
+ fail2("description does not take a reference");
10995
+ }
10989
10996
  if (key === "default" && typeof root.get(key) !== "boolean")
10990
10997
  fail2("default must be true or false");
10991
10998
  if (key === "default" && root.get(key) === true && input === "request")
@@ -11060,7 +11067,8 @@ function validateOrThrow(d, path2) {
11060
11067
  fail2(`steps[${pushing[0]}]: a pushing step must be the last step`);
11061
11068
  if ("gate" in steps[steps.length - 1])
11062
11069
  fail2(`steps[${steps.length - 1}]: a gate cannot be the last step`);
11063
- return { workflow: { name: basename2(path2, ".yaml"), file: path2, input, steps }, isDefault: root.get("default") === true };
11070
+ const description = root.has("description") ? root.get("description") : null;
11071
+ return { workflow: { name: basename2(path2, ".yaml"), description, file: path2, input, steps }, isDefault: root.get("default") === true };
11064
11072
  }
11065
11073
  function scan(d, dir) {
11066
11074
  const names = namesIn(dir, "workflows", (path2) => warnLoud(rel(d, path2), "not a valid workflow name"));
@@ -11147,10 +11155,11 @@ function cmdWorkflow(wanted, override) {
11147
11155
  const own = join9(projectDir(home, key), "standards", file2);
11148
11156
  conventions.push(isFile(own) ? own : global);
11149
11157
  }
11150
- const { name: workflowName, file, input, steps } = result.workflow;
11158
+ const { name: workflowName, description, file, input, steps } = result.workflow;
11151
11159
  const changes = input === "changes";
11152
11160
  const doc = {
11153
11161
  name: workflowName,
11162
+ description,
11154
11163
  file,
11155
11164
  input,
11156
11165
  commits: conventions[0],
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@pixelfactoryio/theway",
3
- "version": "0.15.0",
3
+ "version": "0.17.0",
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.15.0",
3
+ "version": "0.17.0",
4
4
  "description": "theway writes a spec and a numbered task list before any code, then implements the tasks in your session or through agents that open a reviewed, CI-green pull request.",
5
5
  "author": {
6
6
  "name": "Amine",
@@ -33,7 +33,7 @@ Run `theway path` and use the folder it prints as `<home>`, never a path from el
33
33
  - **One change ID:** run the change and stop when its PR is ready for validation (when `pushes` is `false`, when its local branch is ready; for a working-tree workflow, when the change is done, uncommitted in the working tree). Never merge it.
34
34
  - **Multiple change IDs (series):** run each change strictly in the given order. When `pushes` is `true`, each change's PR must be merged before the next change starts, since later changes build on earlier ones; the user confirms each merge (Step 5). When `pushes` is `false`, nothing is merged: each change's branch is created from the previous change's branch (Step 2). A working-tree workflow commits nothing, so it cannot run a series (Step 1).
35
35
 
36
- **Authorization boundary:** invoking this command authorizes editing the repository, inline or through agents, committing only on each change's own feature branch (nothing for a working-tree workflow), the Workflow tool, and, when `theway workflow` prints `pushes: true`, pushing each change's own feature branch (never force-push, never the default branch) and opening its PR — nothing more. When `pushes` is `false`, it pushes nothing and opens no PR. Merging needs the user's explicit yes, asked at Step 5, and merges as `git-host.md` says: never bypass required reviews or checks. Do not ask for permission mid-run for the pushes and PRs it grants; do not perform outward actions it doesn't.
36
+ **Authorization boundary:** invoking this command authorizes editing the repository, inline or through agents, committing only on each change's own feature branch (nothing for a working-tree workflow), the Workflow tool, and, when `theway workflow` prints `pushes: true`, pushing each change's own feature branch (never force-push, never the default branch) and opening its PR — nothing more. When `pushes` is `false`, it pushes nothing and opens no PR. Merging needs the user's explicit yes, asked at Step 5, and merges as `git-host.md` says: never bypass required reviews or checks. Do not ask for permission mid-run for the pushes and PRs it grants; do not perform outward actions it doesn't. Never create or edit workflow, step or prompt files, or initialize a repository, to work around a missing remote or another failed step: stop and report.
37
37
 
38
38
  **Authorization of a request run** (`input: request`): invoking this command authorizes writing the change folders the scaffold creates, and throwaway probes in a directory created with `mktemp -d`, inline or through agents, and the Workflow tool — nothing more. It authorizes no repository edit, no branch, no commit, no push and no PR.
39
39
 
@@ -47,7 +47,7 @@ Run Step 1's first part once per run, then Steps 1-5 once per change ID, in orde
47
47
 
48
48
  Once per run:
49
49
 
50
- - Run `theway workflow`, or `theway workflow <name>` with `--workflow <name>`. It prints the resolved workflow as JSON: its `name`, its `file`, `commits` and `git_host`, `pushes` (whether a step pushes), `working_tree` (one inline step that commits nothing) and its `steps`. Each step entry has its `id`, `step`, effective `agents` (`agents: false` runs it inline), `params` and its `do` tree of `agent`, `parallel`, `loop` and `when` nodes, every agent with its `label`, `prompt` paths, `returns` type, `access` and `model`; a gate entry has its `id` and `gate` question. On exit 1, quote its error line and stop: no change starts.
50
+ - Run `theway workflow`, or `theway workflow <name>` with `--workflow <name>`. It prints the resolved workflow as JSON: its `name`, its `description`, its `file`, `commits` and `git_host`, `pushes` (whether a step pushes), `working_tree` (one inline step that commits nothing) and its `steps`. Each step entry has its `id`, `step`, effective `agents` (`agents: false` runs it inline), `params` and its `do` tree of `agent`, `parallel`, `loop` and `when` nodes, every agent with its `label`, `prompt` paths, `returns` type, `access` and `model`; a gate entry has its `id` and `gate` question. On exit 1, quote its error line and stop: no change starts.
51
51
  - When `working_tree` is `true`, say "working tree: no branch, nothing committed" in your first report line.
52
52
  - Read the files at its `commits` and `git_host` paths, `commits.md` and `git-host.md` (your project's own copy when it has one): `commits.md` says how the feature branch, the commits and the PR are named, `git-host.md` gives the command of each git host operation by its heading. Pass both paths to every Workflow call (Step 3) and follow both in every step you do yourself.
53
53
  - When `working_tree` is `true` and more than one change ID was given, stop before any work and say: `a series needs a workflow that commits; pass --workflow agents or a workflow with more steps`.
@@ -67,7 +67,15 @@ Then read every file its `standards` lists: these are the standards, the shipped
67
67
 
68
68
  ### Step 2: Branch
69
69
 
70
- Find the default branch and sync it, as `git-host.md` says ("Default branch", "Sync the default branch"), then create (or check out) the change's feature branch from it, named as `commits.md` says. When `pushes` is `false`, create each later change's branch of a series from the previous change's branch instead, so the changes stack locally. The branch the feature branch is created from, the default branch or that previous branch, is the change's `<base>`.
70
+ Before any branch, check the repository in this order. Case 1 also runs for a working-tree workflow, before its skip below; a request run skips all three.
71
+
72
+ 1. **No commit.** When `git rev-parse --verify HEAD` fails (not a git repository, or no commit yet), stop before any work with: `the repository has no commit: run git init and commit once, then run /theway:workflow again`.
73
+ 2. **No remote, and the workflow pushes.** When `git remote` prints nothing and `pushes` is `true`, stop before any work with: `this workflow pushes and the repository has no git remote: add one, or run the default develop workflow (no branch, nothing pushed)`.
74
+ 3. **No remote, and the workflow does not push.** When `git remote` prints nothing and `pushes` is `false`, the base is the current branch (`git branch --show-current`), with no sync. When that prints nothing (detached HEAD), stop with `HEAD is detached: check out a branch, then run /theway:workflow again`; otherwise create the feature branch from it as usual. Case 3 replaces finding and syncing the default branch below; only its series rule still applies.
75
+
76
+ When a `git-host.md` operation of this step fails (for example when the default branch cannot be found), quote its error and stop, before any work.
77
+
78
+ Find the default branch and sync it, as `git-host.md` says ("Default branch", "Sync the default branch"), then create (or check out) the change's feature branch from it, named as `commits.md` says. When `pushes` is `false`, create each later change's branch of a series from the previous change's branch instead, so the changes stack locally. The branch the feature branch is created from, the default branch, the current branch of case 3 or that previous branch, is the change's `<base>`.
71
79
 
72
80
  Skip this step for a working-tree workflow: it creates no branch and commits nothing, the change stays uncommitted in the working tree, and its base commit is `HEAD`.
73
81
 
@@ -14,6 +14,11 @@
14
14
  "const": "theway.workflow/v1",
15
15
  "description": "The format of this file: theway.workflow/v1."
16
16
  },
17
+ "description": {
18
+ "type": "string",
19
+ "minLength": 1,
20
+ "description": "One line on what the workflow does; theway workflow prints it."
21
+ },
17
22
  "input": {
18
23
  "type": "string",
19
24
  "enum": [
@@ -1,7 +1,8 @@
1
1
  # yaml-language-server: $schema=https://pixelfactoryio.github.io/theway/schemas/workflow.v1.json
2
- # Implement, review and open the PR through agents. A param an entry leaves out comes from workflow.defaults in
3
- # config.yaml, else from the step file: theway steps lists them.
2
+ # A param an entry leaves out comes from workflow.defaults in config.yaml, else from the step file: theway steps
3
+ # lists them.
4
4
  version: theway.workflow/v1
5
+ description: Implement, review and open the PR through agents
5
6
  steps:
6
7
  - implement:
7
8
  - review:
@@ -1,7 +1,7 @@
1
1
  # yaml-language-server: $schema=https://pixelfactoryio.github.io/theway/schemas/workflow.v1.json
2
- # The workflow /theway:workflow runs when no file sets default: true: the tasks done inline in your session, on the
3
- # working tree, nothing committed.
2
+ # The workflow /theway:workflow runs when no file sets default: true.
4
3
  version: theway.workflow/v1
4
+ description: The tasks done inline in your session, on the working tree, nothing committed
5
5
  agents: false
6
6
  steps:
7
7
  - implement:
@@ -1,6 +1,7 @@
1
1
  # yaml-language-server: $schema=https://pixelfactoryio.github.io/theway/schemas/workflow.v1.json
2
- # The light path of /theway:engineering --light: a short spec and 1 to 3 tasks, reviewed by one grounding critic.
2
+ # The light path of /theway:engineering --light.
3
3
  version: theway.workflow/v1
4
+ description: A short spec and 1 to 3 tasks, reviewed by one grounding critic
4
5
  input: request
5
6
  steps:
6
7
  - scaffold-light: {agents: false}
@@ -1,6 +1,7 @@
1
1
  # yaml-language-server: $schema=https://pixelfactoryio.github.io/theway/schemas/workflow.v1.json
2
- # Investigate a request and write its spec and tasks, then review them. /theway:engineering runs it.
2
+ # /theway:engineering runs it.
3
3
  version: theway.workflow/v1
4
+ description: Investigate a request and write its spec and tasks, then review them
4
5
  input: request
5
6
  steps:
6
7
  - scaffold: {agents: false}