pi-tandem 0.3.0 → 0.4.0

package/README.md

@@ -15,7 +15,7 @@ Modern coding agents lean toward autonomy: multi-file changes in one go, subagen
 ## What's inside
 
 - **Pair-work prompt patch** - collaboration style (lock-step, explicit go-aheads), terse communication rules, and a "lazy senior" coding discipline: no speculative abstractions, deletion over addition, root-cause fixes
-- **`subagent` skill** to run a task in a fresh agent session on request, with full visibility and control, instead of harness-managed subagents
+- **Interactive subagent workflow** to run a task in a fresh session on request (a new tmux window or a background paseo agent), with full visibility and control
 - **Tool-specific instructions** (`gh`, `aws`, `jira`, ...), added to the prompt only if the tool is actually installed
 
 ## Recommended tools
@@ -23,11 +23,14 @@ Modern coding agents lean toward autonomy: multi-file changes in one go, subagen
 The plugin notices which CLI tools are actually installed on your machine, and for each one it finds, adds a short note telling the model that the tool is available and recommended to use. Installing these gets you significantly more out of this package:
 
 - `gh` - GitHub CLI: repos, issues, PRs, releases, workflows
-- `pandoc` - read docx/odt/rtf/html (and fetched web pages) as text instead of raw markup
+- `html2text` (Python, e.g. via `pipx install html2text`) - read web pages as markdown instead of raw markup
+- `lynx` - plain-text fallback for web pages when the Python `html2text` is not installed
 - `pdftotext` (poppler) - extract text from PDFs
 - a Chromium-based browser (Brave, Chromium, Chrome, Edge) - headless-render fallback for JS-heavy or bot-blocked pages
+- `pandoc` - convert docx/odt/rtf to markdown
 - `osascript` (macOS only) - drive the user's real browser sessions via AppleScript
 - `jira`, `aws`, `saml2aws` - if your workflow includes them
+- `tmux` or `paseo` - run the main session inside one of these to get the interactive subagent workflow
 
 ## Attribution
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-tandem",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/skhoroshavin/tandem-skills.git"

package/prompt.md

@@ -46,14 +46,19 @@ A number of CLI tools are installed on this laptop and fully authenticated, you'
 <!--cli:pdftotext-->
 - Use `pdftotext` to extract text from PDFs: `pdftotext input.pdf output.txt`, or `pdftotext input.pdf -` to print to stdout
 <!--/cli-->
-<!--cli:pandoc-->
-- Use `pandoc` to read documents other than pdf as markdown or plain text: `pandoc input.docx -o output.md` (also works for odt, rtf, html, ...)
-- Unless your task requires seeing actual tags, always convert HTML fetched from the web to plain text or markdown, instead of reading it raw, for example when using `curl`: `curl -s <url> | pandoc -f html -t plain`.
+<!--cli:html2text-->
+- Unless your task requires seeing actual tags, always convert HTML fetched from the web to markdown instead of reading it raw, for example when using `curl`: `curl -s <url> | html2text --ignore-images --no-wrap-links`.
+<!--/cli-->
+<!--cli:lynx-->
+- Unless your task requires seeing actual tags, always convert HTML fetched from the web to plain text instead of reading it raw, for example when using `curl`: `curl -s <url> | lynx -stdin -dump` (link URLs are kept in a References list).
 <!--/cli-->
 <!--cli:browser-->
 - Use a real headless browser when you need to read a JS-rendered or bot-blocked page: `<browser-binary> --headless --disable-gpu --user-data-dir=$(mktemp -d) --dump-dom --virtual-time-budget=5000 <url>`
 - When in doubt, always try `curl` first before resorting to a headless browser
 <!--/cli-->
+<!--cli:pandoc-->
+- Use `pandoc` to convert documents (docx, odt, rtf, ...) to markdown: `pandoc input.docx -o output.md`
+<!--/cli-->
 <!--cli:osascript-->
 - Use `osascript` with `execute <tab> javascript "<js>"` to read pages and interact using the user's
   real logged-in sessions (analyzing dashboards, checking Google Calendar and Mail, etc)
@@ -64,6 +69,33 @@ Important:
 - Read-only commands, like checking state of GHA workflow or reading web page content, are fine without asking
 - Commands with side effects, like push, create/modify/delete of repos, issues, PRs, releases, triggering workflows, submitting forms, posting or purchasing require an explicit go-ahead, like any other side-effect, as stated in the collaboration style section
 
+<!--cli:tmux-->
+When explicitly instructed to run a task in a separate or fresh agent session ("do it in a fresh session", "use a subagent"), spawn a worker in a new tmux window with the bundled script. Pass the full task on stdin, self-contained - the worker never sees this session's history:
+
+```bash
+<spawn-script> <task-name> <<'EOF'
+<full task>
+EOF
+```
+
+- If asked for a specific model, pass it after the task name: `<spawn-script> <task-name> <model>`
+- The script opens a tmux window named `<task-name>` running `pi --no-session`, sends the task to it together with instructions for reporting back after user approval, and prints how to terminate the worker
+- After spawning, stop and wait: do not poll the worker pane and do not read the result file early. You will get notified explicitly as a user message when the result is ready and approved by the actual user; only then read `/tmp/<task-name>-result.md` and clean up the window
+<!--/cli-->
+<!--cli:paseo-->
+When explicitly instructed to run a task in a separate or fresh agent session ("do it in a fresh session", "use a subagent"), spawn a background paseo worker with the bundled script. Pass the full task on stdin, self-contained - the worker never sees this session's history:
+
+```bash
+<spawn-script> <task-name> <<'EOF'
+<full task>
+EOF
+```
+
+- If asked for a specific model, pass it after the task name: `<spawn-script> <task-name> <model>`
+- The script starts a background paseo agent titled `<task-name>`, sends the task to it together with instructions for reporting back after user approval, and prints how to terminate the worker
+- After spawning, stop and wait: do not poll the worker and do not read the result file early. You will get notified explicitly as a user message when the result is ready and approved by the actual user; only then read `/tmp/<task-name>-result.md` and clean up (`paseo archive --force <agent-id>`)
+<!--/cli-->
+
 ## Coding tasks
 
 When working on coding tasks, you are a lazy senior developer. Lazy means efficient, not careless. The best code is the code never written. Stop at the first rung that holds:

package/runtime/cli-tools.mjs

@@ -1,8 +1,15 @@
 // Shared runtime helpers, copied verbatim into every package's runtime/ dir.
 // Files filtered by this module must contain <!--cli:tool-->...<!--/cli--> blocks.
 
+import { spawnSync } from "node:child_process";
 import { statSync } from "node:fs";
-import { delimiter, join } from "node:path";
+import { delimiter, dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const spawnScript = join(
+  dirname(fileURLToPath(import.meta.url)),
+  process.env.PASEO_AGENT_ID ? "spawn-paseo.sh" : "spawn-tmux.sh",
+);
 
 // windows executables are found via fixed suffixes (.exe etc)
 const extensions = process.platform === "win32" ? [".EXE", ".BAT", ".CMD"] : [""];
@@ -33,26 +40,46 @@ function findBrowserBinary() {
   }
 }
 
+// brew/apt ship a different C++-based html2text with an incompatible CLI;
+// only the Python one supports the --ignore-images flag used in the prompt
+function isPythonHtml2text() {
+  if (!isOnPath("html2text")) return false;
+  try {
+    const res = spawnSync("html2text", ["--help"], { encoding: "utf8", timeout: 5000 });
+    return res.status === 0 && (res.stdout || "").includes("--ignore-images");
+  } catch {
+    return false;
+  }
+}
+
 // drop <!--cli:tool--> blocks for absent tools, and the whole section when none remain
-function toolAvailable(tool, browser) {
-  if (tool === "browser") return browser !== undefined;
+function toolAvailable(tool, ctx) {
+  if (tool === "browser") return ctx.browser !== undefined;
+  if (tool === "html2text") return ctx.html2text;
+  if (tool === "lynx") return !ctx.html2text && isOnPath(tool);
   if (tool === "osascript") return process.platform === "darwin" && isOnPath(tool);
+  if (tool === "paseo") return !!process.env.PASEO_AGENT_ID;
+  if (tool === "tmux") return !process.env.PASEO_AGENT_ID && !!process.env.TMUX;
   return isOnPath(tool);
 }
 
 export function filterCliTools(raw) {
   let hasTools = false;
-  const browser = findBrowserBinary();
+  const ctx = {
+    browser: findBrowserBinary(),
+    html2text: isPythonHtml2text(),
+  };
   const filtered = raw
     .replace(
       /<!--cli:([a-z0-9]+)-->\r?\n?([\s\S]*?)<!--\/cli-->\r?\n?/g,
       (_marker, tool, body) => {
-        if (!toolAvailable(tool, browser)) return "";
+        if (!toolAvailable(tool, ctx)) return "";
         hasTools = true;
         return body;
       },
     )
-    .replace(/<browser-binary>/g, () => (browser ? JSON.stringify(browser) : "<browser-binary>"))
+    .replace(/<browser-binary>/g, () => (ctx.browser ? JSON.stringify(ctx.browser) : "<browser-binary>"))
+    .replace(/<spawn-script>/g, () => JSON.stringify(spawnScript))
     .replace(/\n{3,}/g, "\n\n");
   return hasTools ? filtered : filtered.replace(/\n## CLI tools[\s\S]*?(?=\n## )/, "");
 }

package/runtime/spawn-paseo.sh

@@ -0,0 +1,39 @@
+#!/usr/bin/env bash
+# Spawn a fresh worker agent session in the background via the local paseo daemon.
+# Usage: spawn-paseo.sh <task-name> [<model>]   (full task on stdin)
+set -euo pipefail
+
+name="${1:?usage: spawn-paseo.sh <task-name> [<model>] (full task on stdin)}"
+model="${2:-}"
+[[ $# -le 2 ]] || { echo "error: unexpected args: $*" >&2; exit 2; }
+[[ "$name" =~ ^[a-z0-9][a-z0-9-]{0,30}$ ]] || { echo "error: bad name" >&2; exit 2; }
+[[ -n "${PASEO_AGENT_ID:-}" ]] || { echo "error: not inside a paseo agent session" >&2; exit 2; }
+
+task="$(cat)"
+[[ -n "$task" ]] || { echo "error: empty task on stdin" >&2; exit 2; }
+
+# the name keys the result file: keep it unique among live workers
+result="/tmp/${name}-result.md"
+
+prompt="$task
+
+# Rules
+
+Check whether you have some skills applicable to this task, and load
+them before starting working. When done, write the full result to
+$result, tell the user it is ready for review and wait for further
+instructions. Only after the user explicitly approves, notify the
+parent with a one-line pointer (never result content):
+
+    paseo send --no-wait '$PASEO_AGENT_ID' 'Result ready: $result'"
+
+# a crashed run may have left a stale result for this name
+rm -f "$result"
+if [[ -n "$model" ]]; then
+  id="$(paseo run -q --background --title "$name" --provider pi --model "$model" "$prompt")"
+else
+  id="$(paseo run -q --background --title "$name" --provider pi "$prompt")"
+fi
+[[ -n "$id" ]] || { echo "error: paseo run did not return an agent id" >&2; exit 1; }
+
+echo "Worker spawned as paseo agent \"$id\". Terminate with: paseo archive --force \"$id\""

package/{skills/subagent/spawn-subagent.sh → runtime/spawn-tmux.sh}

@@ -1,19 +1,11 @@
 #!/usr/bin/env bash
 # Spawn a fresh worker agent session in a new tmux window.
-# Usage: spawn-subagent.sh <task-name> [--model <model>]   (full task on stdin)
+# Usage: spawn-tmux.sh <task-name> [<model>]   (full task on stdin)
 set -euo pipefail
 
-name="${1:?usage: spawn-subagent.sh <task-name> [--model <model>] (full task on stdin)}"
-shift
-model_flag=""
-if [[ "${1:-}" == "--model" ]]; then
-  [[ $# -ge 2 ]] || { echo "error: --model needs a value" >&2; exit 2; }
-  # plain model ids only: the flag is embedded in a tmux command string
-  [[ "$2" =~ ^[A-Za-z0-9._:/-]+$ ]] || { echo "error: bad model" >&2; exit 2; }
-  model_flag=" --model $2"
-  shift 2
-fi
-[[ $# -eq 0 ]] || { echo "error: unexpected args: $*" >&2; exit 2; }
+name="${1:?usage: spawn-tmux.sh <task-name> [<model>] (full task on stdin)}"
+model="${2:-}"
+[[ $# -le 2 ]] || { echo "error: unexpected args: $*" >&2; exit 2; }
 [[ "$name" =~ ^[a-z0-9][a-z0-9-]{0,30}$ ]] || { echo "error: bad name" >&2; exit 2; }
 [[ -n "${TMUX:-}" ]] || { echo "error: not inside tmux" >&2; exit 2; }
 
@@ -45,8 +37,11 @@ prompt=${prompt//\'/\'\\\'\'}
 
 # a crashed run may have left a stale result for this name
 rm -f "$result"
-tmux new-window -c "$PWD" -n "$name" \
-  "pi --no-session$model_flag '$prompt'"
+if [[ -n "$model" ]]; then
+  tmux new-window -c "$PWD" -n "$name" "pi --no-session --model $model '$prompt'"
+else
+  tmux new-window -c "$PWD" -n "$name" "pi --no-session '$prompt'"
+fi
 tmux set-option -w -t "$name" automatic-rename off
 
 echo "Worker spawned in tmux window \"$name\". Terminate with: tmux kill-window -t $name"

package/skills/code-review/SKILL.md

@@ -3,19 +3,13 @@ name: code-review
 description: Use when asked to do a code review.
 ---
 
-Read the full diff and everything it touches before judging; the worst review
-mistakes come from reviewing the diff only.
+Read the full diff and everything it touches before judging; the worst review mistakes come from reviewing the diff only. The review is read-only: never modify tracked files, the index, HEAD, or branch state; running builds and tests to verify the change is fine.
+
+Review as a lazy senior engineer: besides bugs, flag NIH syndrome, overengineering, unnecessary dependencies, obvious copy paste and other similar code bloats. Give accompanying tests the same, if not higher, level of attention: unreadable, overcomplicated tests explain nothing, and a test that would also pass without the change proves nothing.
 
 Report rules:
 
-- Actionable findings only, ordered by severity: ones requiring changes, or
-  at least explicit decisions; "checked and fine" does not qualify.
-- Each finding: what is wrong and why it matters in 1-3 lines, then the
-  smallest fix - as a diff if it fits within 50 LoC, otherwise described
-  generally, asking for a decision.
-- No praise, no diff summary, no restating the request, no advice beyond
-  findings.
+- Actionable findings only, ordered by severity: ones requiring changes, or at least explicit decisions; "checked and fine" does not qualify.
+- Each finding: what is wrong and why it matters in 1-3 lines, then the smallest fix as a concrete diff, or set of diffs; if not diffable, describe generally and ask for a decision.
+- No praise, no diff summary, no restating the request, no advice beyond findings.
 - If nothing actionable: say exactly that, plus one line on what was checked.
-- Before writing, verify: grep for references to removed or renamed
-  identifiers; where the repo has rendered build output, check it is in sync;
-  diff the commit message claims against the actual change.

package/skills/subagent/SKILL.md

@@ -1,29 +0,0 @@
----
-name: subagent
-description: Use when explicitly instructed to run a task in a separate or fresh agent session - e.g. "do it in a fresh session", "use a subagent".
----
-
-Spawn a subagent in a new tmux window using the script bundled next to this
-file. Pass the full task on stdin, self-contained - the subagent never sees
-this session's history:
-
-```bash
-<this-skill-dir>/spawn-subagent.sh <task-name> <<'EOF'
-<full task>
-EOF
-```
-
-After spawning, stop and wait: do not poll the worker pane and do not read
-the result file early. You will get notified explicitly as a user message
-when the result is ready and approved by the actual user; only then read
-the file and clean up the window.
-
-If asked to use a specific model, pass it with `--model <model>`:
-
-```bash
-<this-skill-dir>/spawn-subagent.sh <task-name> --model <model> <<'EOF'
-<full task>
-EOF
-```
-
-Workers run `pi --no-session`.