pi-tandem 0.4.2 → 0.4.3

package/README.md

@@ -16,13 +16,25 @@ Modern coding agents lean toward autonomy: multi-file changes in one go, subagen
 
 - **Pair-work prompt patch** - collaboration style (lock-step, explicit go-aheads) and terse communication rules
 - **Skills**, loaded on demand:
-  - **Brainstorming** - interviews you about the idea one question at a time, or rubber ducks while you think out loud, until you and the model get on the same page
+  - **Research** - pairs with you digging through data, documents and code to get a verified answer to a question
+  - **Brainstorm** - interviews you about the idea one question at a time, or rubber ducks while you think out loud, until you and the model get on the same page
   - **Coding** - "lazy senior" discipline for code changes: no speculative abstractions, deletion over addition, root-cause fixes
   - **Review** - interactively checks code and documents for errors and bloat, actionable findings only
   - **Pull requests** - branch, title and description rules, calibrated to the repo's merged PRs
-- **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
+- **Interactive subagents** - fresh-context workers you can steer and must approve; details in the [Interactive subagents](#interactive-subagents) section
 - **Tool-specific instructions** (`gh`, `aws`, `jira`, ...), added to the prompt only if the tool is actually installed
 
+## Interactive subagents
+
+In most harnesses a subagent is fire-and-forget: a one-shot call - prompt in, result out, no interaction while it runs - and the full result lands in the parent's context. Tandem keeps the point of the idea - a task runs in a fresh context and reports back, sparing the parent's context the intermediate steps - but drops the fire-and-forget part:
+
+- the worker is a normal agent session with the same skills: you can watch it work and talk to it mid-task
+- nothing flows back until you check and approve the result in the worker's chat; only the result - usually far smaller than the worker's full transcript - is loaded into the parent's context
+
+The workflow needs the main session to run inside tmux or paseo. To start a worker, tell the current agent "use a subagent" or "do it in a fresh session": it spawns a new session using the available mechanism - a tmux window, or a parallel paseo agent - and hands it a fully self-contained task; the worker never sees the parent session's history. Workers can spawn subagents of their own, so the delegation nests.
+
+The idea first shipped in [pi-supergsd](https://github.com/skhoroshavin/pi-supergsd), Pi-only, with tasks running as branches in the Pi session tree instead of separate sessions.
+
 ## Recommended tools
 
 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:
@@ -35,13 +47,13 @@ The plugin notices which CLI tools are actually installed on your machine, and f
 - `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
+- `tmux` or `paseo` - run the main session inside one of these to enable [interactive subagents](#interactive-subagents)
 
 ## Attribution
 
 The "lazy senior" part of the coding skill is adapted from [ponytail](https://github.com/DietrichGebert/ponytail) by DietrichGebert (MIT).
 
-The brainstorming skill's interview method (facts vs. decisions, one question at a time, throwaway probes) is inspired by ideas from the brainstorming skill in [superpowers](https://github.com/obra/superpowers) by obra and the grilling skill in [skills](https://github.com/mattpocock/skills) by mattpocock (both MIT).
+The brainstorm skill's interview method (facts vs. decisions, one question at a time, throwaway probes) is inspired by ideas from the brainstorming skill in [superpowers](https://github.com/obra/superpowers) by obra and the grilling skill in [skills](https://github.com/mattpocock/skills) by mattpocock (both MIT).
 
 ## License
 

package/package.json

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

package/prompt.md

@@ -59,8 +59,7 @@ A number of CLI tools are installed on this laptop and fully authenticated, you'
 - 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)
+- 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)
 - If a needed site is not open, opening a new tab for it is acceptable on request.
 <!--/cli-->
 

package/skills/{brainstorming → brainstorm}/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: brainstorming
+name: brainstorm
 description: Use when asked to discuss or brainstorm something - an idea, design, plan.
 ---
 

package/skills/coding/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: coding
-description: Always use when working with code, including researching, planning changes, implementing, debugging, reviewing and refactoring
+description: Always use when working with code, including planning changes, implementing, debugging, reviewing and refactoring
 ---
 
 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/skills/pr/SKILL.md

@@ -3,19 +3,13 @@ name: pr
 description: Use when asked to create or update a pull request, including branch, title and description.
 ---
 
-Before writing anything, check a few recently merged PRs in this repo and
-match their tone, length and structure.
+Before writing anything, check a few recently merged PRs in this repo and match their tone, length and structure.
 
 Title: one terse imperative line, commit-message style.
 
-Description: what changes for the user of the code, in a few short bullets or
-lines. No process narrative (test runs, review iterations), no history or
-commit archaeology - the "why" only when it changes a user decision.
+Description: what changes for the user of the code, in a few short bullets or lines. No process narrative (test runs, review iterations), no history or commit archaeology - the "why" only when it changes a user decision.
 
 Workflow:
-- Continue on the current branch; if it is main, move the commits to a
-  descriptively named branch first.
-- Before proposing, run `git log --oneline <base>..HEAD` and confirm the PR
-  would contain exactly this task's commits.
-- Propose the exact title and description to the user; create the PR only
-  after their explicit go-ahead.
+- Continue on the current branch; if it is main, move the commits to a descriptively named branch first.
+- Before proposing, run `git log --oneline <base>..HEAD` and confirm the PR would contain exactly this task's commits.
+- Propose the exact title and description to the user; create the PR only after their explicit go-ahead.

package/skills/research/SKILL.md

@@ -0,0 +1,31 @@
+---
+name: research
+description: Use when asked to investigate or find something out - in data, documents or code.
+---
+
+Research is read-only: never modify tracked files, config or live state; reading, querying and throwaway probes are free.
+
+Terms:
+
+- **unverified claim** - a single statement the answer could rest on, not yet verified, so it cannot be relied upon. Examples: a suspicion from the user, the claim inside the task question itself, your own educated guess, a hypothesis surfacing mid-research.
+- **verified claim** - a claim confirmed by checked evidence, or stated by the user from their own knowledge. Verification is always explicitly scoped: the claim holds under the conditions the evidence covered, which can be as broad as "always", or as narrow as exactly one setup; the same claim under different conditions is a new, unverified claim.
+
+Workflow:
+
+1. Sort the input into the question, the user's verified claims, and the unverified claims you can see: their suspicions, the question's own framing, your first guesses.
+2. Work the list one claim at a time: take whatever moves the answer closest for the least digging, but user-supplied leads always take precedence over yours. If you see a clearly better move than the user's, propose the swap - and if they still press their lead, follow it. Re-sort whenever the list changes. Try the claim:
+   - verified: move it over; queue the new claims it suggests;
+   - refuted: its opposite is verified; queue what that opens up;
+   - not directly checkable: swap it for intermediate claims that would settle it.
+3. Verify by tracing the real thing end to end; a plausible story is not verification. "No such thing" counts only when you looked everywhere it could be - and when the answer hangs on a "no", check it again from another angle. When a probe would settle a claim more cheaply or more reliably than reading - a throwaway script, a query, a client call - probe; keep probes in a scratch directory, never the repo.
+4. Report once every part of the question is answered by verified claims.
+5. Interrupt for user input when:
+   - a new verification contradicts a verified claim: lay both out; resolving contradictions is their call, not yours;
+   - the next best claim is expensive to verify - deep digging, data crunching, a real bite of session context - and the user may know or point somewhere cheaper;
+   - the list is empty and the question is still open: ask what else to check.
+
+Report rules, whether it lands in chat or a file:
+
+- Lead with the answer, then the evidence. Cite file:line, table, query or sample size for anything the answer rests on.
+- Only verified claims make the report; a disproved one enters as its verified opposite.
+- No process narrative: what you found, not the order you found it in.