@wanbicoi/next-steps 0.1.0 → 0.1.2

package/README.md

@@ -1,11 +1,11 @@
 # next-steps
 
-A small CLI that keeps an agent on a predefined workflow. The graph lives in
-`workflows/*.json`; the tool records one session per task and always answers the
-same question: **what can I do next?**
+A small CLI that keeps an agent on a predefined workflow. The graph is one file,
+`.next-steps/workflow.json`; the tool records one session per task and always
+answers the same question: **what can I do next?**
 
 ```
-$ next-steps create --workflow feature-work
+$ next-steps create
 session: 4f1c9b3e-9a02-4d1c-8e11-7c6b1f0a2d33
 workflow: feature-work  Implement a feature end to end
 status: running
@@ -16,16 +16,18 @@ next:
 
 $ next-steps log --key 4f1c... --node read-issue
 logged: #1 read-issue  (entry)
-scope: feature-work   status: running
+status: running
 
 next:
-  1. e1 -> implement  Implement
+  1. implement  Implement  [review]
      Criteria are understood.
 ```
 
 The point is not to constrain what the agent can think — it is to make the path
 it took readable afterwards, and to stop it from skipping work or losing its
-place.
+place. A node marked `[review]` means the agent shows the plan and waits for an
+explicit yes before doing the work; the flag is advisory, so nothing blocks a
+scripted run.
 
 ## Run it
 
@@ -57,44 +59,44 @@ bun src/cli.ts help
 You can also use the package script: `bun run next-steps -- help`.
 
 State is created on first use at `./.next-steps/state.db` (SQLite, gitignored).
-There are no path flags: the tool uses the directory it is run from, so run it
-from the project root. Workflow definitions are read from `./workflows/`.
+The graph is read from `./.next-steps/workflow.json`; commit that file, and run
+the tool from the project root. There are no path flags.
 
-This repo keeps its sample graphs under `test/fixtures/workflows/`. To try the
+This repo keeps sample graphs under `test/fixtures/<id>/.next-steps/`. To try the
 commands from the repo root:
 
 ```sh
-mkdir -p workflows && cp test/fixtures/workflows/*.json workflows/
+mkdir -p .next-steps && cp test/fixtures/feature-work/.next-steps/workflow.json .next-steps/
 ```
 
-## Visualize workflows
+## Visualize the graph
 
-`next-steps viz` serves an interactive Cytoscape viewer for the workflows in
-`./workflows/`:
+`next-steps viz` serves an interactive Cytoscape viewer for
+`.next-steps/workflow.json`:
 
 ```sh
 next-steps viz                # http://127.0.0.1:3000
 next-steps viz --port 8080
 ```
 
-From this repo, `bun src/cli.ts viz`. Press Ctrl+C to stop. The viewer shows
-every graph with node/edge labels, conditions, and subgraph drill-down; edit
-`viz/template.html` to change the styles.
+From this repo, `bun src/cli.ts viz`. Press Ctrl+C to stop. Groups are drawn as
+labelled boxes, review nodes are marked, and every move shows its description and
+condition. Edit `viz/template.html` to change the styles.
 
 ## Commands
 
 ```
-next-steps create  --workflow <id> [--key <key>] [--json]
+next-steps create  [--key <key>] [--json]
 next-steps log     --key <key> --node <node> [--json]
 next-steps next    --key <key> [--json]
 next-steps steps   --key <key> [--limit <n>] [--after <seq>] [--json]
-next-steps keys    [--workflow <id>] [--json]
+next-steps keys    [--json]
 next-steps reset   --key <key> [--json]
+next-steps agents  [--json]
 
-next-steps workflow new <id> [--json]
-next-steps workflow list [--json]
-next-steps workflow show <id> [--json]
-next-steps workflow check [id] [--json]
+next-steps workflow new [--json]
+next-steps workflow show [--json]
+next-steps workflow check [--json]
 
 next-steps viz [--port <n>] [--json]
 ```
@@ -103,7 +105,69 @@ Pretty output is the default; `--json` is the stable, machine-readable form
 documented in `docs/AGENTS.sample.md`.
 
 `create` only opens a session (the key is the task id; a UUID is generated when
-omitted). It does not author a workflow — use `workflow new` for that.
+omitted). It does not author the graph — use `workflow new` for that.
+
+`agents` prints `docs/AGENTS.sample.md`, the playbook an agent reads to drive
+this CLI from another repo. Copy the output into that repo's `AGENTS.md`:
+
+```sh
+next-steps agents > /tmp/agents.md
+```
+
+## Hooks
+
+If `.next-steps/hook` exists and is executable (`chmod +x`), every successful
+`log` runs it after the state is written. Use it to mirror progress into a
+status bar, window title, or agent sidebar. Any language works; a Python hook:
+
+```python
+#!/usr/bin/env python3
+# .next-steps/hook — mirror the state into a status file
+import json
+import sys
+
+payload = json.load(sys.stdin)
+
+if payload["status"] == "done":
+    label = "done"
+elif payload["status"] == "review":
+    label = ", ".join(n["title"] for n in payload["next"] if n["reviewRequired"])
+else:
+    label = " | ".join(n["title"] for n in payload["next"]) or payload["last"]["title"]
+
+with open("/tmp/next-steps-status", "w") as out:
+    out.write(f'{payload["key"]}  {payload["status"]}  {label}\n')
+```
+
+Replace the file write with a call to your status tool (a tmux status line, a
+Herdr sidebar, a file watcher). The hook runs from the project root and inherits
+the normal environment; its stdout and stderr are discarded, so report through
+the tool it drives.
+
+The payload on stdin is a status snapshot, not the full event:
+
+```json
+{
+  "event": "log",
+  "key": "4f1c...",
+  "status": "review",
+  "last": { "id": "read-issue", "title": "Read the issue" },
+  "next": [{ "id": "implement", "title": "Implement", "reviewRequired": true }]
+}
+```
+
+`status` is derived: `done` when the run finished, `review` when any legal next
+node has `reviewRequired`, otherwise `running`. `last` is the node just logged;
+`next` is what the agent may do now. For anything richer (edges, descriptions,
+conditions, history), call `next-steps next --key <key> --json` — the payload
+carries the `key`.
+
+Hooks run synchronously with a five-second timeout. A missing hook is silent; a
+hook that fails, times out, or lacks the execute bit prints a warning to stderr
+and never changes the log's exit code. Only `log` triggers the hook, so a fresh
+session stays quiet until its first node is finished. Commit `.next-steps/hook`
+when the whole team should share the behaviour; leave it untracked for a local
+adapter.
 
 ## Workflow format
 
@@ -113,36 +177,44 @@ omitted). It does not author a workflow — use `workflow new` for that.
   "title": "Deploy a change",
   "start": "build",
   "nodes": [
-    { "id": "build", "type": "node", "title": "Build", "description": "Run the build." },
+    {
+      "id": "build",
+      "title": "Build",
+      "description": "Run the build.",
+      "group": "Prepare",
+      "next": [{ "to": "review", "description": "The build is green." }]
+    },
     {
       "id": "review",
-      "type": "subgraph",
-      "workflow": "code-review",
       "title": "Review",
-      "description": "Run the review workflow."
+      "description": "Read the change before it ships.",
+      "group": "Prepare",
+      "reviewRequired": true,
+      "next": [
+        { "to": "build", "description": "Fix the review notes." },
+        { "to": "END", "description": "Approved." }
+      ]
     }
-  ],
-  "edges": [
-    { "id": "e1", "from": "build", "to": "review", "description": "Build is green." },
-    { "id": "e2", "from": "review", "to": "END", "description": "Review done." }
   ]
 }
 ```
 
-- `start` names the first step.
-- `END` is a reserved target, not a node. It means "this scope is finished".
-- A conditional edge adds `"condition": "the tests failed"`. Conditions are prose
-  for the agent; nothing evaluates them. The edge the agent actually logged is
-  the audit trail.
-- A `subgraph` node references another workflow by id. Entering it pushes a
-  scope; reaching `END` inside it pops back and continues at the node after the
-  subgraph.
-- Every node needs an outgoing edge, every workflow needs an edge to `END`, and
-  a node whose only edge is `END` finishes its scope with no extra step.
-- Duplicate `from -> to` pairs are rejected so edge inference is unambiguous.
+- `start` names the first step. Every node needs at least one move.
+- `next` holds the ways out of the node. `to` is a node id or `END`; a
+  `condition` adds prose the agent reads but nothing evaluates. The move the
+  agent actually logs is the audit trail, recorded as `from->to`.
+- `END` is a reserved target, not a node. A node whose only move is `END`
+  finishes the run as soon as it is logged, with no extra step.
+- `group` labels a region of the graph. It is rendering metadata: the viewer
+  draws it as a box, and the rest of the tool ignores it.
+- `reviewRequired` marks a node that needs an explicit yes before the work
+  starts. It is reported in `next` and `workflow show`, and never enforced.
+- Duplicate moves out of one node are rejected so the log is unambiguous, and at
+  least one move to `END` is required.
+- The graph is flat: there are no subgraphs and no cross-file references.
 
 Run `next-steps workflow check` after editing. It fails with exit 5 on structural
-problems and warns about unreachable nodes.
+problems and warns about unreachable nodes or nodes that cannot reach `END`.
 
 ## Exit codes
 
@@ -151,7 +223,7 @@ problems and warns about unreachable nodes.
 
 Errors go to stderr. With `--json` they are
 `{ "error": { "code", "message", "details" } }`, and `details.legal` lists the
-steps the graph allows.
+moves the graph allows.
 
 ## Publish
 
@@ -193,12 +265,14 @@ src/commands/            one function per command
 src/workflow/            load, validate, pure graph logic
 src/runs/                session service, store, Bun/Node SQLite driver
 scripts/build.ts         Node bundle + shebang for dist/cli.js
-test/fixtures/workflows/ sample graphs (test fixtures)
+test/fixtures/<id>/      sample graphs, each in its own .next-steps/ directory
 test/                    pure, validation, end-to-end
 ```
 
-`src/workflow/graph.ts` is pure: no I/O, no database, so the tricky scope logic
-is testable in milliseconds. `RunStore` is an interface over `src/runs/driver.ts`,
-which loads `bun:sqlite` under Bun and `node:sqlite` under Node.
+`src/workflow/graph.ts` is pure: no I/O, no database, so the next computation is
+testable in milliseconds. `RunStore` is an interface over `src/runs/driver.ts`,
+which loads `bun:sqlite` under Bun and `node:sqlite` under Node. A state file from
+0.1.0 or earlier is replaced on first use, since those sessions name graphs that
+no longer exist.
 
-`docs/initial-plan.md` records the design and the decisions behind it.
+`docs/initial-plan.md` records the original design and the decisions behind it.