pi-do-always 0.8.0 → 0.10.0

package/README.md

@@ -11,26 +11,23 @@ type to filter, scroll or click, or navigate with arrows + Enter → the task's
 ```text
   do-always — pick a task
 
+   #  TASK                      DESCRIPTION                                                    ORDER
   PLAN
-▸ 1. ⚡ Review changes       Review the current code changes (Plan)
-  2. ⚡ Review code          Review the whole project's code quality (Plan)
-  3. ⚡ Cleanup              Clean up dead code and duplicates (Plan)
-  4. ⚡ Security             Security audit (Plan)
-  5. ⚡ Performance          Performance review (Plan)
-  6. ⚡ Propose features     Propose new features (Plan)
+   1  ⚡ Review changes         Review the current code changes (Plan)                           ·  
+   2  ⚡ Review code            Review the whole project's code quality (Plan)                  [1] 
+   3  ⚡ Cleanup                Clean up dead code and duplicates (Plan)                        [2] 
+   4  ⚡ Security               Security audit (Plan)                                            ·  
+   5  ⚡ Performance            Performance review (Plan)                                      ►[3] 
+   6  ⚡ Propose features       Propose new features (Plan)                                      ·  
   DO
-  7. Build                  Test build is ok and fix issues
-  8. Tests                  Run tests and fix failures
+   7  Build                     Test build is ok and fix issues                                  ·  
+   8  Tests                     Run tests and fix failures                                       ·  
   DOCS
-  9. Readme                 Update the README.md
-  OPS
- 10. Release               Prepare a release (version, changelog, tag)
- 11. Commit                Prepare a clean commit
+   9  Readme                    Update the README.md                                             ·  
 
-  Review changes — prompt:
-  Review the changes on branch fix/login-null (3 changed files: auth.ts, login.ts,
-  test/auth.test.ts). Last commit: Fix null check in login. Check `git status` and
-  `git diff` to see what changed, then double-check the changes for bugs, edge …
+  ──────────────────────────────────────────────────────────────────────────────────────────────────
+  Run the chain (3)
+  ← tasks  •  ⏎ remove  •  esc  •  ctrl+u clear
 
   1-9 pick by number  •  type to filter  •  ↑↓ navigate  •  enter select  •  esc cancel  •  ⚡ auto-runs
 ```
@@ -59,6 +56,82 @@ not filled): the `Plan` category does this by default, and any task can opt in o
 In non-interactive modes (no TUI) there is no editor to fill, so the selected prompt is sent
 as a user message instead.
 
+## Chains
+
+Run several tasks in a row as a **chain**. The selector shows an `ORDER` column; tasks in
+the chain get a `[n]` marker in execution order, and a pinned row at the bottom of the
+list runs the chain.
+
+Building a chain in the selector:
+
+- **Enter on a task row** runs just that task (the classic pick — the cursor starts in
+  the task column).
+- **→** moves the cursor to the ORDER column on the same row, where **Enter** toggles
+  that task's chain membership (`·` → `[n]` → `·`). **←** goes back to the task column.
+- **↑ / ↓** move the cursor in either column. The cursor is a **►** marker in the
+  theme's accent color: in the left gutter in the task column, in the ORDER cell in
+  the order column (plus a row highlight where your theme makes it visible). From the
+  last task row, **↓** lands on the pinned Run row (and **↑** back).
+- **Enter on the `Run the chain (n)` row** — or a mouse click on it — runs the chain.
+  The row is dimmed while the chain is empty. The ► marker appears on it only
+  while the cursor is on the row (as on task rows).
+- **Backspace** (with no filter typed) undoes the last add; **ctrl+u** clears the whole
+  chain; **Esc** cancels and discards it.
+- Clicking an ORDER cell toggles the task's chain membership.
+- The classic fast paths are unchanged: **1-9** runs a task immediately, and clicking a
+  task row runs it — both close the selector and discard the chain.
+
+Chains are capped at 8 tasks. Reordering is done by removing a task and re-adding it
+(mouse drag reordering is planned for a future release). On narrow terminals the ORDER
+column is dropped and the chain is shown on its own line below the list (keyboard
+chaining still works).
+
+Running a chain sends each step as its own turn, strictly one after another — the next
+step starts only after the previous run has fully finished. Each step's guards are
+re-evaluated at its turn against the current state; a step whose guards no longer hold
+stops the chain there (with a warning), as do an aborted step (Esc) or a step that
+errors. Steps already run are kept.
+
+If the first task of a chain is a fill task (no `⚡`) in the TUI, step 1 is put in the
+editor and the rest of the chain starts automatically once you press Enter and that run
+finishes.
+
+While a chain is running, a **status widget** is shown below the prompt: the chain's
+tasks with a marker per step and a `(n/N)` progress count — the step the chain is
+currently at.
+
+```
+  ⛓ do-always (2/4)
+  ✓ Review changes
+  ▶ Build
+  ○ Test
+  ○ Deploy
+```
+
+Markers: `✓` completed, `▶` running (or waiting for your Enter on a fill-first step 1),
+`○` pending, `✗` errored / failed to start, `⊘` aborted, `–` skipped because its guards
+no longer hold. The widget is removed when the chain completes; if the chain stops early
+it stays below the prompt as a trace of where it stopped (until your next prompt or a new
+session). Starting a second chain while
+one is running is refused — wait for it to finish or abort the current step with Esc.
+
+Every chain run also writes a **report file** in the project root —
+`do-always-report-tasks-YYYY-MM-DD-HHMM.md` (e.g. `do-always-report-tasks-2025-01-15-1432.md`) —
+so earlier steps' results are not lost when later steps' output scrolls them off screen.
+Each step appends a section as it finishes (the step's final assistant message, with its
+outcome and run time), so the file is complete even if the session dies mid-chain; a
+footer with the overall summary is appended when the chain ends, and the completion
+notification carries the file's path. A run that produces nothing worth keeping (no
+completed step and no step result text — e.g. step 1 errors before any output) leaves no
+file behind. Set `"report": false` in the config to disable
+it (the project file's value wins over the global one). See [Report file](#report-file).
+
+**Inline report in the chat.** When a chain completes fully (all steps done), the full
+Markdown report is sent as a message in the chat so you can read the results without
+opening the file. The message is automatically removed when you start the next
+prompt or session. A run that stops early (aborted, errored, or skipped steps) does
+not show the inline report — only the status trace widget below the prompt.
+
 ## Install
 
 Install it from npm as a Pi package, which loads the bundled `index.ts` (and its `tasks.ts`) without
@@ -117,6 +190,7 @@ In the object form you can also configure the selector shortcut:
 
 - `shortcut` (optional) — key that opens the selector, e.g. `"f4"`. Set to `null` to disable the shortcut. Defaults to `F4`. The project file's value wins over the global one.
 - `merge` (optional) — how project tasks combine with the global tasks: `"override"` (default) replaces a global task with the same `name`; `"append"` keeps the global tasks and only adds new project task names (a cascade, like CSS). The project file's value wins over the global one; when neither sets it, the default is `override` (the historical behavior).
+- `report` (optional) — whether chain runs write a Markdown report file in the project root (one per run, appended as each step finishes). Default `true`; set `false` to disable. The project file's value wins over the global one. See [Chains](#chains).
 
 Example project file that only *adds* tasks without overriding the global set:
 
@@ -147,6 +221,10 @@ injects “Review the changes on branch `fix/login-null` (3 changed files:
 |`{{files_changed}}`|Changed files from `git status` — comma-separated, capped at 20 entries (`none` when clean or not a git repo)|
 |`{{files_changed_count}}`|Number of changed files (`0` when clean or not a git repo)|
 |`{{user}}`|`git config user.name` (`unknown` when unset)|
+|`{{diff_stat}}`|`git diff --shortstat` output, e.g. `3 files changed, 41 insertions(+), 7 deletions(-)` (`none` when unavailable)|
+|`{{repo}}`|Basename of the git remote (or of the working directory when there is no remote) — disambiguates monorepo work|
+|`{{staged_files}}`|Files staged for commit, one per line (`none` when empty)|
+|`{{unstaged_files}}`|Modified-but-unstaged files, one per line (`none` when empty)|
 
 Unknown placeholders are left as-is, and a prompt without placeholders is
 injected unchanged, so existing configs keep working. The selector preview and
@@ -198,7 +276,7 @@ The `guards` array accepts these guard objects (all must pass):
 
 | `type` | `value` | Blocks when… |
 |---|---|---|
-| `requireDirty` | none | the working tree is clean (`files_changed_count === 0`) |
+| `requireDirty` | none | the working tree is clean (no changed files) |
 | `requireBranch` | branch name | the current branch is not the given name |
 | `requireRepo` | repo name | the git-remote basename context value is not the given name |
 | `requireFilePattern` | glob | no changed file matches the glob |

package/extensions/pi-do-always/do-always.json

@@ -4,9 +4,9 @@
 		{
 			"name": "Review changes",
 			"category": "Plan",
-			"requireDirty": true,
 			"description": "Review the current code changes (Plan)",
-			"prompt": "Review the changes on branch {{branch}} ({{files_changed_count}} changed files: {{files_changed}}). Last commit: {{last_commit}}. Check `git status` and `git diff` to see what changed, then double-check the changes for bugs, edge cases, security issues, and consistency with the rest of the codebase. Do a plan proposal for the fixes if needed. Do a summary of your findings"
+			"requireDirty": true,
+			"prompt": "Review the changes on branch {{branch}} ({{files_changed_count}} changed files: {{files_changed}}). Change summary: {{diff_stat}}. Last commit: {{last_commit}}. Check `git status` and `git diff` to see what changed, then double-check the changes for bugs, edge cases, security issues, and consistency with the rest of the codebase. Do a plan proposal for the fixes if needed. Do a summary of your findings"
 		},
 		{
 			"name": "Review code",
@@ -17,7 +17,6 @@
 		{
 			"name": "Cleanup",
 			"category": "Plan",
-			"autoRun": false,
 			"description": "Clean up dead code and duplicates (Plan)",
 			"prompt": "Scan the project for dead code, unused imports, commented-out blocks, and duplicated logic. Do a plan proposal for the removals and consolidations, keeping behavior unchanged. Do not make any changes yet."
 		},
@@ -61,13 +60,16 @@
 			"name": "Release",
 			"category": "Ops",
 			"description": "Prepare a release (version, changelog, tag)",
+			"when": "git",
 			"prompt": "Prepare a release for this project (branch {{branch}}): check `git log` since the last tag, update the version in package.json (or the equivalent location), add a changelog entry summarizing the changes, and create a git tag if git present. Do not push."
 		},
 		{
 			"name": "Commit",
 			"category": "Ops",
 			"description": "Prepare a clean commit",
-			"prompt": "Prepare the working tree on branch {{branch}} ({{files_changed_count}} changed files: {{files_changed}}) for a clean commit: review `git status` and `git diff`, stage the relevant changes, and write a clear commit message describing what changed and why. Do not push."
+			"requireDirty": true,
+			"when": "git",
+			"prompt": "Prepare the working tree on branch {{branch}} ({{files_changed_count}} changed files: {{files_changed}}) for a clean commit: stage the relevant changes, and write a clear commit message describing what changed and why. Do not push."
 		}
 	]
 }