@wanbicoi/next-steps 0.1.0 → 0.1.2

package/docs/AGENTS.sample.md

@@ -0,0 +1,120 @@
+<!-- Template: copy this to AGENTS.md in a repo that uses next-steps on PATH. -->
+
+# Work the graph with next-steps
+
+This repo defines its work as one graph in `.next-steps/workflow.json`.
+`next-steps` walks that graph one node at a time: it tells you which nodes are
+legal now, and records the path you take.
+
+Pass `--json` to every command.
+
+## Walk
+
+1. **Open a session.**
+
+   ```sh
+   next-steps create --json
+   ```
+
+   The response holds `key` (your task id) and the first `next` list.
+
+   **Done when:** you have `key` in hand and a non-empty `next` list.
+
+2. **Choose one next node.**
+
+   Each entry has `node`, `edge`, `title`, `description`, `reviewRequired`, and
+   sometimes `condition`. The `condition` is prose telling you when that branch
+   applies; you judge it against the task, nothing checks it for you. `edge` is
+   derived from `from->to` and is what the log will record.
+
+   ```json
+   {
+     "current": { "node": "verify", "title": "Verify" },
+     "next": [
+       { "edge": "verify->implement", "node": "implement", "title": "Implement",
+         "description": "Loop back and fix the failure.",
+         "condition": "the build or the tests failed",
+         "reviewRequired": true },
+       { "edge": "verify->review", "node": "review", "title": "Peer review",
+         "description": "Hand the change to review.",
+         "condition": "the build and the tests pass",
+         "reviewRequired": false }
+     ],
+     "done": false
+   }
+   ```
+
+   **Done when:** exactly one entry is chosen.
+
+3. **If that entry has `reviewRequired: true`, stop and ask.**
+
+   Prepare everything the node needs — the plan, the diff, the command you are
+   about to run — show it to the user, and wait for an explicit yes. Then act.
+
+   **Done when:** the user said yes. The CLI only reports the flag — nothing
+   enforces it. A node without the flag: skip this step.
+
+4. **Do that node's work.**
+
+   **Done when:** the node's `description` is satisfied — not when you started
+   it.
+
+5. **Log the node.**
+
+   ```sh
+   next-steps log --key <key> --node <node> --json
+   ```
+
+   One log per visit, after the work. Log is the only call per node; the
+   response already carries the new `next` list, so continue straight from it.
+
+   **Done when:** exit `0` and the response contains the new `next` list.
+
+6. **Repeat 2–5 until the response says `done: true`.**
+
+   **Done when:** `done` is true. Stop there; a written summary is its own node
+   if the graph wants one.
+
+`next-steps next --key <key> --json` returns the same list on demand. Use it when
+you resume rather than during the walk.
+
+## Branches
+
+- **`END` is a legal target.** Log it like any node; the session becomes
+  `done`. The `next` list also labels it `finish`.
+- **A node whose only move is `END`** finishes the run as soon as you log it.
+  The response is already `done: true`; there is no extra step.
+- **Exit `4`** means the move is not legal. The error's `details.legal` is the
+  complete list of nodes you can move to; choose from it, or correct the work and
+  log the node the graph expects.
+- **Exit `3`** means the key is unknown or `.next-steps/workflow.json` is
+  missing — run `next-steps workflow new` if the graph has never been created. A
+  key belongs to one task: create a fresh session for a new task.
+
+## Resume
+
+A new agent, or the same one after a context reset, rebuilds the task from the
+tool:
+
+```sh
+next-steps steps --key <key> --json   # audit trail: seq, node, from, edge, at
+next-steps next  --key <key> --json   # legal moves now
+```
+
+The `steps` record is the source of truth for what already happened.
+
+## Housekeeping
+
+```sh
+next-steps keys --json                     # sessions on this machine
+next-steps reset --key <key> --json        # delete a finished or abandoned session
+```
+
+`.next-steps/state.db` is local state and is gitignored. The graph,
+`.next-steps/workflow.json`, is source code: commit it with the rest of the repo.
+
+## Exit codes
+
+`0` ok · `2` usage, duplicate key, or invalid key · `3` not found ·
+`4` invalid move or unknown node · `5` invalid workflow file. Errors go to
+stderr as `{ "error": { "code", "message", "details" } }`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wanbicoi/next-steps",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "Agent-facing workflow walker: log a step, list the next ones.",
   "license": "MIT",
   "type": "module",
@@ -10,6 +10,7 @@
   "files": [
     "dist",
     "viz/template.html",
+    "docs/AGENTS.sample.md",
     "README.md",
     "LICENSE"
   ],

package/viz/template.html

@@ -14,6 +14,10 @@
         --accent: #2563eb;
         --accent-soft: #eff6ff;
         --code: #f1f5f9;
+        --font-ui: system-ui, -apple-system, "Segoe UI", Roboto, "Noto Sans", "DejaVu Sans",
+          sans-serif;
+        --font-mono: ui-monospace, "SF Mono", "Cascadia Code", Menlo, Consolas, "DejaVu Sans Mono",
+          monospace;
       }
       * {
         box-sizing: border-box;
@@ -24,7 +28,7 @@
       }
       body {
         margin: 0;
-        font: 13px/1.45 ui-sans-serif, system-ui, -apple-system, "Segoe UI", sans-serif;
+        font: 13px/1.5 var(--font-ui);
         color: var(--text);
         background: var(--bg);
       }
@@ -67,54 +71,6 @@
         color: var(--muted);
         font-size: 12px;
       }
-      #search {
-        width: 100%;
-        padding: 7px 9px;
-        border: 1px solid var(--border);
-        border-radius: 7px;
-        font: inherit;
-        background: var(--bg);
-        color: var(--text);
-        outline: none;
-      }
-      #search:focus {
-        border-color: var(--accent);
-        box-shadow: 0 0 0 2px var(--accent-soft);
-      }
-      #workflow-list {
-        flex: 1;
-        overflow: auto;
-        padding: 8px;
-      }
-      .wf {
-        display: block;
-        width: 100%;
-        padding: 8px 10px;
-        margin: 2px 0;
-        border: 1px solid transparent;
-        border-radius: 7px;
-        background: transparent;
-        text-align: left;
-        font: inherit;
-        color: var(--text);
-        cursor: pointer;
-      }
-      .wf:hover {
-        background: var(--bg);
-      }
-      .wf.active {
-        background: var(--accent-soft);
-        border-color: #bfdbfe;
-      }
-      .wf strong {
-        display: block;
-        font-weight: 600;
-      }
-      .wf small {
-        color: var(--muted);
-        font-family: ui-monospace, SFMono-Regular, Menlo, monospace;
-        font-size: 11px;
-      }
       #legend {
         border-top: 1px solid var(--border);
         padding: 12px 16px 16px;
@@ -155,7 +111,7 @@
       #subtitle {
         color: var(--muted);
         font-size: 12px;
-        font-family: ui-monospace, SFMono-Regular, Menlo, monospace;
+        font-family: var(--font-mono);
       }
       #controls {
         display: flex;
@@ -186,12 +142,6 @@
         background: var(--accent);
         border-color: var(--accent);
       }
-      #back {
-        display: none;
-      }
-      #back.visible {
-        display: inline-block;
-      }
       #cy {
         flex: 1;
         min-height: 0;
@@ -226,6 +176,7 @@
         background: var(--code);
         padding: 1px 4px;
         border-radius: 4px;
+        font-family: var(--font-mono);
         font-size: 11px;
       }
       #details .hint {
@@ -263,25 +214,23 @@
         <header>
           <h1>next-steps <span>viewer</span></h1>
           <p id="count"></p>
-          <input id="search" type="search" placeholder="Filter workflows" autocomplete="off" />
         </header>
-        <nav id="workflow-list"></nav>
         <section id="legend">
           <strong>Legend</strong>
           <div><span class="swatch" style="background:#fff;border-color:#94a3b8"></span> Node</div>
-          <div><span class="swatch" style="background:#f5f3ff;border-color:#7c3aed"></span> Subgraph</div>
+          <div><span class="swatch" style="background:#f5f3ff;border-color:#7c3aed"></span> Group</div>
           <div><span class="swatch" style="background:#f0fdf4;border-color:#16a34a"></span> Start</div>
+          <div><span class="swatch" style="background:#fff;border-color:#f59e0b"></span> Needs review</div>
           <div><span class="swatch" style="background:#0f172a;border-color:#0f172a;border-radius:50%"></span> END</div>
           <div>
             <span class="swatch" style="background:#f59e0b;border-color:#f59e0b;height:3px;border-radius:2px"></span>
-            Conditional edge
+            Conditional move
           </div>
         </section>
       </aside>
       <main>
         <header id="toolbar">
           <div>
-            <button id="back" type="button">← Back</button>
             <h2 id="title">Loading…</h2>
             <div id="subtitle"></div>
           </div>
@@ -303,10 +252,11 @@
       </main>
       <aside id="details">
         <h3>Workflow viewer</h3>
-        <p class="muted">Click a node or an edge. Double-click a subgraph node to open it.</p>
+        <p class="muted">Click a node or an edge. Each box is a group; nodes marked
+        <strong>[review]</strong> need an explicit yes before the work starts.</p>
         <div class="hint">
-          The data is generated from <code>test/fixtures/workflows/</code>. Run
-          <code>bun run viz</code> after editing a graph.
+          The data is generated from <code>.next-steps/workflow.json</code>. Run
+          <code>bun run viz</code> after editing the graph.
         </div>
       </aside>
     </div>
@@ -328,14 +278,22 @@
 
       const $ = (selector) => document.querySelector(selector);
 
+      // Cytoscape draws labels on canvas, so it cannot inherit the page font.
+      // Read the same token the CSS uses to keep one source of truth.
+      const FONT_UI = getComputedStyle(document.documentElement)
+        .getPropertyValue("--font-ui")
+        .replace(/\s+/g, " ")
+        .trim();
+
       const COLORS = {
         nodeBg: "#ffffff",
         nodeBorder: "#94a3b8",
         nodeText: "#0f172a",
-        subgraphBg: "#f5f3ff",
-        subgraphBorder: "#7c3aed",
+        groupBg: "#f5f3ff",
+        groupBorder: "#7c3aed",
         startBg: "#f0fdf4",
         startBorder: "#16a34a",
+        reviewBorder: "#f59e0b",
         endBg: "#0f172a",
         endText: "#ffffff",
         edge: "#94a3b8",
@@ -344,7 +302,7 @@
       };
 
       // Customise the graph here. Cytoscape selectors support classes,
-      // data attributes (`node[type = "subgraph"]`), and states (`:selected`).
+      // data attributes, and states (`:selected`).
       const STYLE = [
         {
           selector: "node",
@@ -357,8 +315,9 @@
             height: "label",
             padding: 10,
             label: "data(label)",
+            "font-family": FONT_UI,
             color: COLORS.nodeText,
-            "font-size": 10,
+            "font-size": 12,
             "text-wrap": "wrap",
             "text-max-width": "150px",
             "text-valign": "center",
@@ -366,11 +325,22 @@
           },
         },
         {
-          selector: "node.subgraph",
+          selector: "node.group",
           style: {
-            "background-color": COLORS.subgraphBg,
-            "border-color": COLORS.subgraphBorder,
-            shape: "round-hexagon",
+            "background-color": COLORS.groupBg,
+            "background-opacity": 0.7,
+            "border-color": COLORS.groupBorder,
+            "border-width": 1,
+            "border-style": "dashed",
+            shape: "round-rectangle",
+            label: "data(label)",
+            "font-family": FONT_UI,
+            "font-size": 13,
+            "font-weight": "bold",
+            color: COLORS.groupBorder,
+            "text-valign": "top",
+            "text-halign": "center",
+            padding: 26,
           },
         },
         {
@@ -381,6 +351,13 @@
             "border-width": 3,
           },
         },
+        {
+          selector: "node.review",
+          style: {
+            "border-color": COLORS.reviewBorder,
+            "border-width": 3,
+          },
+        },
         {
           selector: "node.end",
           style: {
@@ -390,7 +367,8 @@
             shape: "ellipse",
             width: 52,
             height: 52,
-            "font-size": 11,
+            "font-family": FONT_UI,
+            "font-size": 12,
             "font-weight": "bold",
           },
         },
@@ -410,7 +388,8 @@
             "target-arrow-shape": "triangle",
             "curve-style": "bezier",
             label: "data(label)",
-            "font-size": 8,
+            "font-family": FONT_UI,
+            "font-size": 10,
             color: "#475569",
             "text-wrap": "wrap",
             "text-max-width": "140px",
@@ -437,10 +416,7 @@
           },
         },
       ];
-
       const state = {
-        current: null,
-        history: [],
         labels: true,
         conditions: true,
       };
@@ -454,106 +430,81 @@
         );
       }
 
-      function edgeLabel(edge) {
+      function edgeLabel(move) {
         if (!state.labels) return "";
-        const parts = [edge.description || ""];
-        if (state.conditions && edge.condition) parts.push(`when: ${edge.condition}`);
+        const parts = [move.description || ""];
+        if (state.conditions && move.condition) parts.push(`when: ${move.condition}`);
         return parts.filter(Boolean).join("\n");
       }
 
-      function renderList() {
-        const list = $("#workflow-list");
-        const query = $("#search").value.trim().toLowerCase();
-        list.innerHTML = "";
-
-        for (const id of DATA.order) {
-          const workflow = DATA.workflows[id];
-          const haystack = `${id} ${workflow.title}`.toLowerCase();
-          if (query && !haystack.includes(query)) continue;
-
-          const button = document.createElement("button");
-          button.type = "button";
-          button.className = `wf${id === state.current ? " active" : ""}`;
-          button.innerHTML = `<strong>${esc(workflow.title)}</strong><small>${esc(id)}</small>`;
-          button.addEventListener("click", () => openWorkflow(id));
-          list.appendChild(button);
-        }
-
-        $("#count").textContent = `${DATA.order.length} workflows`;
-      }
-
-      function openWorkflow(id, push = true) {
-        if (!DATA.workflows[id]) return;
-        if (push && state.current && state.current !== id) state.history.push(state.current);
-        state.current = id;
-        render();
-      }
-
-      function goBack() {
-        const previous = state.history.pop();
-        if (!previous) return;
-        state.current = previous;
-        render();
-      }
-
       function render() {
-        const workflow = DATA.workflows[state.current];
-        if (!workflow) return;
-
+        const workflow = DATA.workflow;
         $("#title").textContent = workflow.title;
         $("#subtitle").textContent = `${workflow.id} · start: ${workflow.start}`;
-        $("#back").classList.toggle("visible", state.history.length > 0);
+        $("#count").textContent = `${workflow.nodes.length} nodes`;
         document.title = `${workflow.title} · next-steps`;
-
-        renderList();
         renderGraph(workflow);
       }
 
       function renderGraph(workflow) {
         const elements = [];
+        const groups = new Map();
+        for (const node of workflow.nodes) {
+          if (!node.group || groups.has(node.group)) continue;
+          groups.set(node.group, `group-${groups.size}`);
+        }
+
+        for (const [label, id] of groups) {
+          elements.push({ data: { id, label }, classes: "group" });
+        }
 
         for (const node of workflow.nodes) {
-          const classes = [node.type === "subgraph" ? "subgraph" : "node"];
+          const classes = ["node"];
           if (node.id === workflow.start) classes.push("start");
+          if (node.reviewRequired) classes.push("review");
           elements.push({
             data: {
               id: node.id,
-              label: node.title,
+              label: node.reviewRequired ? `${node.title} [review]` : node.title,
               title: node.title,
-              type: node.type,
               description: node.description,
-              workflow: node.workflow || "",
+              group: node.group || "",
+              reviewRequired: Boolean(node.reviewRequired),
+              ...(node.group ? { parent: groups.get(node.group) } : {}),
             },
             classes: classes.join(" "),
           });
         }
 
-        if (workflow.edges.some((edge) => edge.to === "END")) {
+        const moves = workflow.nodes.flatMap((node) =>
+          node.next.map((move) => ({ from: node.id, ...move })),
+        );
+
+        if (moves.some((move) => move.to === "END")) {
           elements.push({
             data: {
               id: "END",
               label: "END",
               title: "END",
-              type: "end",
-              description: "This scope is finished.",
+              description: "The run is finished.",
             },
             classes: "end",
           });
         }
 
-        for (const edge of workflow.edges) {
+        for (const move of moves) {
           elements.push({
             data: {
-              id: edge.id,
-              source: edge.from,
-              target: edge.to,
-              label: edgeLabel(edge),
-              from: edge.from,
-              to: edge.to,
-              description: edge.description,
-              condition: edge.condition || "",
+              id: `${move.from}->${move.to}`,
+              source: move.from,
+              target: move.to,
+              label: edgeLabel(move),
+              from: move.from,
+              to: move.to,
+              description: move.description,
+              condition: move.condition || "",
             },
-            classes: edge.condition ? "conditional" : "edge",
+            classes: move.condition ? "conditional" : "edge",
           });
         }
 
@@ -571,15 +522,12 @@
           maxZoom: 2.5,
         });
 
-        cy.on("tap", "node", (event) => showNode(event.target));
+        cy.on("tap", "node.node", (event) => showNode(event.target));
+        cy.on("tap", "node.end", (event) => showNode(event.target));
         cy.on("tap", "edge", (event) => showEdge(event.target));
         cy.on("tap", (event) => {
           if (event.target === cy) showIntro();
         });
-        cy.on("dblclick", "node", (event) => {
-          const workflowId = event.target.data("workflow");
-          if (workflowId) openWorkflow(workflowId);
-        });
 
         cy.ready(() => runLayout());
         showIntro();
@@ -624,36 +572,33 @@
       function showIntro() {
         $("#details").innerHTML = `
           <h3>Workflow viewer</h3>
-          <p class="muted">Click a node or an edge. Double-click a subgraph node to open it.</p>
+          <p class="muted">Click a node or an edge. Each box is a group; nodes marked
+          <strong>[review]</strong> need an explicit yes before the work starts.</p>
           <div class="hint">
-            The data is generated from <code>test/fixtures/workflows/</code>. Run
-            <code>bun run viz</code> after editing a graph.
+            The data is generated from <code>.next-steps/workflow.json</code>. Run
+            <code>bun run viz</code> after editing the graph.
           </div>
         `;
       }
 
       function showNode(node) {
         const data = node.data();
-        const kind = data.type === "subgraph" ? "subgraph" : data.type === "end" ? "END" : "node";
+        const group = data.group ? `<dt>Group</dt><dd>${esc(data.group)}</dd>` : "";
+        const review = data.reviewRequired
+          ? "<dt>Review</dt><dd>Show the plan, wait for an explicit yes, then act.</dd>"
+          : "";
 
         $("#details").innerHTML = `
           <h3>${esc(data.title)}</h3>
-          <div class="muted"><code>${esc(data.id)}</code> · ${esc(kind)}</div>
+          <div class="muted"><code>${esc(data.id)}</code>${data.id === "END" ? " · END" : ""}</div>
           <dl>
             <dt>Description</dt><dd>${esc(data.description || "—")}</dd>
+            ${group}
+            ${review}
           </dl>
         `;
 
-        if (data.type === "subgraph" && data.workflow) {
-          const button = document.createElement("button");
-          button.type = "button";
-          button.className = "primary";
-          button.textContent = `Open ${data.workflow} →`;
-          button.addEventListener("click", () => openWorkflow(data.workflow));
-          $("#details").appendChild(button);
-        }
-
-        if (data.type !== "end") {
+        if (data.id !== "END") {
           const hint = document.createElement("div");
           hint.className = "hint";
           hint.innerHTML = `Log this step with <code>next-steps log --key &lt;key&gt; --node ${esc(
@@ -666,14 +611,13 @@
       function showEdge(edge) {
         const data = edge.data();
         $("#details").innerHTML = `
-          <h3>Transition ${esc(data.id)}</h3>
-          <div class="muted"><code>${esc(data.from)}</code> → <code>${esc(data.to)}</code></div>
+          <h3>${esc(data.from)} → ${esc(data.to)}</h3>
           <dl>
             <dt>Description</dt><dd>${esc(data.description || "—")}</dd>
             <dt>Condition</dt><dd>${esc(data.condition || "—")}</dd>
           </dl>
           <div class="hint">
-            Conditions are prose. The agent decides; the logged edge is the audit trail.
+            Conditions are prose. The agent decides; the logged move is the audit trail.
           </div>
         `;
       }
@@ -682,12 +626,10 @@
         if (!cy) return;
         const link = document.createElement("a");
         link.href = cy.png({ full: true, scale: 2, bg: "#ffffff" });
-        link.download = `${state.current}.png`;
+        link.download = `${DATA.workflow.id}.png`;
         link.click();
       }
 
-      $("#search").addEventListener("input", renderList);
-      $("#back").addEventListener("click", goBack);
       $("#fit").addEventListener("click", () => cy?.fit(undefined, 30));
       $("#relayout").addEventListener("click", runLayout);
       $("#png").addEventListener("click", exportPng);
@@ -700,7 +642,6 @@
         refreshEdgeLabels();
       });
 
-      state.current = DATA.workflows["support-ticket"] ? "support-ticket" : DATA.order[0];
       render();
     </script>
   </body>