@difflab/difflab-cli 0.5.0 → 0.7.0

package/README.md

@@ -46,6 +46,17 @@ Clients are selected explicitly. Supported names: `pi`, `cursor`, `codex`, `clau
 
 MCP clients launch `npx -y @difflab/difflab-cli mcp serve` over stdio, so no daemon or port is needed. Bun must be on the client's PATH.
 
+## MCP todo tools
+
+`mcp setup` does **not** create a todo file. Use `todo_init` to create a list. Each todo call requires an absolute `cwd` pointing to an existing directory and a relative `path` to a JSON todo file inside it. For example:
+
+```text
+todo_init({"cwd":"/home/alex","path":"todos.json"})
+todo_add({"cwd":"/home/alex","path":"todos.json","text":"Review PR"})
+```
+
+`todo_list`, `todo_complete`, and `todo_remove` also require both fields; the latter two require a task `id` returned by `todo_list` or `todo_add`. Call `todo_init` before other operations on a new file. Parent traversal outside `cwd`, absolute `path` values, and symlinked paths are rejected. Keep personal todo files outside the repository or add their paths to `.gitignore`. Concurrent writes to the same file are not yet coordinated. Agents can load `skills/difflab-todo/SKILL.md` for usage instructions.
+
 ## Document templates
 
 List the available templates or scaffold a new document from one:
@@ -55,11 +66,19 @@ difflab-cli templates list
 difflab-cli templates scaffold spec-driven-plan docs/plans first-plan.md --cwd /absolute/project/path
 ```
 
-The CLI defaults `--cwd` to its current directory. The MCP server exposes `template_list({})` and `scaffold({"name":"spec-driven-plan","cwd":"/absolute/project/path","path":"docs/plans","filename":"first-plan.md"})`. Both interfaces take a hyphenated template name, a relative destination **directory** (`path`, or `.` for `cwd`), and a separate **filename**. MCP always requires an absolute existing `cwd`. Missing destination directories are created. Available names: `spec-driven-plan`, `software-architecture-design`, `architecture-decision-record`, `product-requirements-document`, `code-review`, `planning-intent`, `ui-component-architecture`, and `pull-request-description` (adapted from Diffpi's PR template).
+The CLI defaults `--cwd` to its current directory. The MCP server exposes `template_list({})` and `scaffold({"name":"spec-driven-plan","cwd":"/absolute/project/path","path":"docs/plans","filename":"first-plan.md"})`. Both interfaces take a hyphenated template name, a relative destination **directory** (`path`, or `.` for `cwd`), and a separate **filename**. MCP always requires an absolute existing `cwd`. Missing destination directories are created. Available names: `spec-driven-plan`, `software-architecture-design`, `architecture-decision-record`, `product-requirements-document`, `code-review`, `planning-intent`, `ui-component-architecture`, `pull-request-description` (adapted from Diffpi's PR template), `flow-definition`, and `flow-instance`.
 
 On first use, missing bundled templates and filled examples are copied to `~/.difflab/templates` and `~/.difflab/templates/examples`. Edit the installed templates to customize future documents. Later runs add missing files but never replace existing ones, even after an upgrade. Examples are for reference, not selectable templates. Copying is literal: prompts and placeholders are not substituted. An unknown name, missing or invalid source, unsafe path, symlink, or existing destination causes an error; destination files are never overwritten. The target directory must remain inside `cwd` and the filename must be a single file name without separators. The one symlink exception is an initialized repository's `.difflab` link to its own user project store: `templates scaffold spec-driven-plan .difflab/plans/YYMMDD-name PLAN.md --cwd /absolute/repo` works in Git worktrees as well. To restore a bundled default, move your installed copy aside before listing again.
 
-The portable `skills/difflab-plan` and `skills/difflab-review` directories contain natural-language agent workflows for these templates. Install each skill in your client's Agent Skills directory. The MCP-only `log_append({"path":"/absolute/physical/project-store/plans/YYMMDD-name/logs.txt","message":"Phase started"})` tool creates an append-only progress log on first use; pass the physical path, not the `.difflab` symlink. There is no log CLI command.
+The portable `skills/difflab-plan`, `skills/difflab-review`, and `skills/difflab-flow` directories contain natural-language agent workflows for these templates. Install each skill in your client's Agent Skills directory. The MCP-only `log_append({"path":"/absolute/physical/project-store/plans/YYMMDD-name/logs.txt","message":"Phase started"})` tool creates an append-only progress log on first use; pass the physical path, not the `.difflab` symlink. There is no log CLI command.
+
+## Flow definitions and runs
+
+`flow new <name>` and `flow go <name>` are Agent Skill requests, not CLI subcommands. The agent creates a definition once at `~/.difflab/flows/<name>.md`. It calls MCP `scaffold` with `cwd=<absolute home>/.difflab`, `path="flows"`, and `filename="<name>.md"`. Do not use `cwd=<home>,path=".difflab/flows"`: that route is for a repository project store. You can edit a definition before another run. A new run uses a fresh snapshot and does not alter old runs.
+
+From an initialized repository, ask “flow go autospec with input 'Export monthly sales' --local”. The agent selects one branch and creates `.difflab/flows/YYMMDD-autospec/FLOW.md`. It keeps inputs, selected permissions, step checkboxes, and verified outputs for later steps in that file. A same-day path requires an explicit resume choice or a distinct run ID. The first unchecked step is the resume point. The physical project-store path to the sibling `logs.txt` receives timestamped entries through MCP `log_append` only. The definition remains unchanged.
+
+`--local` removes remote steps before creating the run. `--commit` permits only an explicitly declared local commit step when passed, and never permits a push. Remote review needs separate permission and the review skill's forge checks. Plan and review skills still control their own operations; a flow cannot override them. Merge is not supported as a flow step. Example definitions live in `skills/difflab-flow/examples/`.
 
 ## Develop
 

package/dist/index.js

@@ -48712,6 +48712,97 @@ var pull_request_description_default = `## Intent
 `;
 var init_pull_request_description = () => {};
 
+// templates/flow-definition.md
+var flow_definition_default = `# {{name}}
+
+## Intent
+
+{{intent}}
+
+## Inputs
+
+| Name  | Required | Default | Description                                |
+| ----- | -------- | ------- | ------------------------------------------ |
+| input | yes      | \u2014       | Free-form user request; bind as one value. |
+
+## Flags
+
+| Flag            | Default | Capability    | Effect                                                                             |
+| --------------- | ------- | ------------- | ---------------------------------------------------------------------------------- |
+| --local         | false   | local         | Omit steps with \`unless: --local\`; never forward to every skill.                   |
+| --commit        | false   | local-commit  | Permit only explicitly commit-capable selected steps to make scoped local commits. |
+| --remote-review | false   | remote-review | Opt in to remote review with independent forge authorization.                      |
+
+## Steps
+
+### 1. {{step-id}}
+
+- Handler: \`plan new\`
+- When: always
+- Unless: never
+- Requires: local
+- Receives: \`{{input}}\`
+- Produces: \`plan_path\` (verified path to the created plan)
+- Instructions: {{step-instructions}}
+
+### 2. {{next-step-id}}
+
+- Handler: \`review new\`
+- When: \`--remote-review\`
+- Unless: \`--local\`
+- Requires: remote-review
+- Receives: \`{{steps.step-id.plan_path}}\`
+- Produces: \`review_path\` (verified review artifact)
+- Instructions: {{step-instructions}}
+
+## Contract
+
+Replace example rows and steps when creating a definition. Use stable unique lower-case hyphenated input and step IDs; output names may also contain underscores (\`^[a-z][a-z0-9]*(?:[-_][a-z0-9]+)*$\`). Declare every input, flag, capability, output and condition. \`When\` and \`Unless\` accept only \`always\`, \`never\`, or one declared flag; no expressions, shell interpolation or implicit flags. The only tokens are \`{{input-name}}\` and \`{{steps.step-id.output-name}}\`. A later step can consume only an earlier declared output, verified when that step finishes. Define any remote or commit capability explicitly and require its independent opt-in flag. This file is reusable and has no run state; editing it affects future runs only.
+`;
+var init_flow_definition = () => {};
+
+// templates/flow-instance.md
+var flow_instance_default = `# Flow run: {{name}}
+
+- **Status:** in progress
+- **Definition:** {{absolute-definition-path}}
+- **Definition SHA-256:** {{definition-sha256}}
+- **Repository:** {{absolute-repository-root}}
+- **Run ID:** {{run-id}}
+
+## Resolved inputs
+
+| Input | Value     |
+| ----- | --------- |
+| input | {{input}} |
+
+## Selected flags and permissions
+
+{{flags-and-capabilities}}
+
+## Selection provenance
+
+{{omitted-step-ids-and-reasons-only-no-instructions}}
+
+## Steps
+
+- [ ] 1. {{selected-step-id}} \u2014 {{resolved-handler}}
+  - Requires: {{authorized-capability}}
+  - Instructions: {{resolved-instructions}}
+  - Receives: {{concrete-input-or-prior-step-handoff}}
+  - Expected output: {{declared-output-name}}
+  - Result/handoff: pending
+
+## Blocker
+
+None.
+
+## Contract
+
+This is the frozen execution snapshot. Include only selected executable steps; never copy unselected instructions here. Resolve all declared inputs before creating this file. References to earlier step outputs are typed handoff slots, filled only from verified results when those steps complete. Check a step only after success; on failure leave it unchecked, record the blocker and stop. Resume this exact instance at its first unchecked step without rereading the global definition.
+`;
+var init_flow_instance = () => {};
+
 // templates/examples/plan-feature.md
 var plan_feature_default = `# Invite teammates to a project
 
@@ -49227,6 +49318,8 @@ var init_source = __esm(() => {
   init_planning_intent();
   init_ui_component_architecture();
   init_pull_request_description();
+  init_flow_definition();
+  init_flow_instance();
   init_plan_feature();
   init_plan_migration();
   init_design_service();
@@ -49245,7 +49338,9 @@ var init_source = __esm(() => {
     { name: "code-review", description: "Thorough code review" },
     { name: "planning-intent", description: "Planning intent for a user to fill in" },
     { name: "ui-component-architecture", description: "UI component design and implementation" },
-    { name: "pull-request-description", description: "Draft pull request description" }
+    { name: "pull-request-description", description: "Draft pull request description" },
+    { name: "flow-definition", description: "Reusable global Agent Skill flow definition" },
+    { name: "flow-instance", description: "Frozen repository-local flow run" }
   ];
   contents = {
     "spec-driven-plan.md": spec_driven_plan_default,
@@ -49256,6 +49351,8 @@ var init_source = __esm(() => {
     "planning-intent.md": planning_intent_default,
     "ui-component-architecture.md": ui_component_architecture_default,
     "pull-request-description.md": pull_request_description_default,
+    "flow-definition.md": flow_definition_default,
+    "flow-instance.md": flow_instance_default,
     "examples/plan-feature.md": plan_feature_default,
     "examples/plan-migration.md": plan_migration_default,
     "examples/design-service.md": design_service_default,
@@ -49438,7 +49535,7 @@ var init_tools4 = __esm(() => {
   });
   templateTools = [
     defineTool("template_list", {
-      description: "List eight document templates; install any missing defaults and examples in the user templates directory without overwriting local edits.",
+      description: "List document templates, including flow definitions and instances; install any missing defaults and examples in the user templates directory without overwriting local edits.",
       inputSchema: strictObject({}),
       outputSchema: templateListOutput,
       annotations: { openWorldHint: false }
@@ -51816,7 +51913,7 @@ function createProgram(write = console.log, version = "0.1.0", options = {}) {
 
 // src/index.ts
 init_errors3();
-var version2 = "0.5.0";
+var version2 = "0.7.0";
 try {
   await createProgram(console.log, version2).parseAsync(process.argv);
 } catch (error) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@difflab/difflab-cli",
-  "version": "0.5.0",
+  "version": "0.7.0",
   "private": false,
   "description": "A minimal Bun CLI starter built with Commander",
   "license": "Apache-2.0",