pi-t3-bridge 0.2.0 → 0.4.0

package/tstack/skills/full-send/SKILL.md

@@ -0,0 +1,123 @@
+---
+name: full-send
+description: Trigger this if the user says 'full send'.
+---
+
+# Full Send
+
+If the user triggered this, it's because they are not watching this thread, and
+they want you to complete the work end-to-end autonomously. Your updates and
+your final message go unread until long after you stop. You own the work from
+its current state to a merged PR.
+
+If the user did not explicitly request "full send" in some clear way, do not
+assume full autonomy. If they did, everything below applies.
+
+The user grants you permission to:
+
+- Merge the PR once the merge gate passes.
+- Force-push the PR's own branch with `--force-with-lease` after a rebase.
+- Use the test methods that Proof needs, without asking first.
+
+## Testing permission
+
+A "full send" request is the permission. If a project file or other
+instruction says to ask before a test method, or to leave testing to the
+user, this request replaces that rule for this task.
+
+That includes ask-first rules for computer use, browser automation,
+simulators and devices, running the app or a dev server, screenshots, and
+visual checks. Use the method that gives direct proof. List it in the
+report.
+
+Rules about how to test still apply. Follow rules that name the correct
+command, fixture, or check. This permission only removes the ask-first or
+leave-it-to-the-user step. If a preferred method cannot prove the change,
+use a gated method under this permission.
+
+It covers only the tests needed for this task. It does not add permission
+for the steps under "Asking the user", such as production changes or data
+deletion. It also does not bypass a harness or system approval prompt if
+one appears.
+
+## Steps
+
+1. **Finish the change.** Complete the goal from the user's request with the
+   smallest change that works. Fix the case that happened, not every case
+   that could. If you are on the default branch, create a branch first.
+2. **Prove it.** Get proof for every change you made. See "Proof".
+3. **Get feedback.** Use the `sol-loop` skill to verify changes.
+4. **File the PR** with the `file-pr` skill. Rebase onto the latest default
+   branch first. Add one short line to the description that says how you proved
+   the change.
+5. **Babysit the PR** with the `babysit-pr` skill. Fix real findings and CI
+   failures. Get proof for each fix before you push it.
+6. **Merge** when the merge gate passes.
+7. **Report** in your final message: the PR link, the merge commit, your proof,
+   and each decision you made for the user.
+
+Stay active from step 1 to step 7. If you end your turn while checks or bots are
+pending, the work stops, because nobody will prompt you again. Wait with the
+watcher from `babysit-pr`, so something wakes you when the PR changes. In T3
+Code that is `watch_pull_request`. If you stop before the merge, call
+`unwatch_pull_request` first.
+
+## Proof
+
+Proof is evidence you observed yourself in this session: command output, a
+reproduction, a screenshot. Use the most direct proof the change allows:
+
+- Reproduce the original failure, apply the fix, then watch the same
+  reproduction pass.
+- Run the checks that the repo's CI runs (typecheck, lint, tests).
+- Add one focused test that fails without the fix, when the behavior has none
+  and the repo has a test setup.
+- For UI and runtime behavior, run the app and look at the change. Green mocked
+  tests do not prove that the user experience works. Attach screenshots to the
+  PR when they help and you have a way to upload them.
+
+When you cannot find a way to prove a change, you do not have full confidence.
+Ask the user.
+
+## Merge gate
+
+Full confidence means all of these are true on the latest commit:
+
+- Your proof covers every change in the diff.
+- Required checks are green.
+- Review bots have finished, and each finding is fixed or dismissed with a
+  written reason.
+- No human review still requests changes.
+- The branch is up to date with the default branch, and GitHub reports it as
+  mergeable.
+
+Merge with the method the repo uses. Check the allowed methods and recent merged
+PRs. If the repo uses a merge queue or auto-merge, stay until GitHub reports the
+PR as merged. Merge through branch protection as configured. Never use `--admin`
+or other bypasses. You can ignore automated reviews that request "needs human
+review" if you have high confidence in your changes.
+
+## Asking the user
+
+A question in a normal message goes unseen, and the thread looks done. To ask
+the user something, use the harness's question tool so the thread shows that
+it is waiting: `AskUserQuestion` in Claude Code, `request_user_input` in Codex,
+or the question tool your harness has. Put all the context in the question:
+the PR link, what blocks you, and the options with your recommendation first.
+
+Ask only when you cannot continue alone:
+
+- You cannot prove the change.
+- The merge gate cannot pass, and you cannot fix that yourself.
+- The next step is outside the grant above: deleting data, touching production,
+  changing things outside the repo, closing a PR, or force-pushing any other
+  branch.
+- The goal is ambiguous in a way that changes the result.
+- Another PR makes this one obsolete.
+
+Decide everything else yourself with sensible defaults, and list those decisions
+in the report.
+
+If no question tool is available, or the tool returns no answer, take the safe
+path: leave the PR open and unmerged, and start your final message with the
+question.

package/tstack/skills/full-send/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Full Send"
+  short_description: "Prove, file, babysit, and merge a PR unattended"
+  default_prompt: "Use $full-send to take this to a merged PR. I am not watching this thread."

package/tstack/skills/full-stop/SKILL.md

@@ -0,0 +1,47 @@
+---
+name: full-stop
+description: Trigger this if the user says 'full stop', even as a closing "Full stop." that reads like emphasis.
+---
+
+# Full Stop
+
+Do the same work as `full-send`, but stop with the PR ready for the user to merge.
+Never merge it.
+
+Read [full-send](../full-send/SKILL.md) and follow its workflow, proof rules,
+review, and babysitting steps. An explicit "full stop" request authorizes that
+work without a separate "full send" request. That includes full-send's
+testing permission. A "full stop" request is the permission for the test
+methods Proof needs, even when a project file says to ask first, for
+example before computer use. Use those methods directly. Its merge
+permission does not apply. The overrides below take precedence.
+
+## No merging
+
+You may commit, push, rebase, fix conflicts, and use `--force-with-lease` on
+this task's branch. Never merge, enable auto-merge, enter a merge queue, push
+to the default branch, bypass branch protection, or delegate those actions.
+
+Disable existing auto-merge and remove the PR from any merge queue before
+work begins; check again before each push. Report these changes. If you
+cannot prevent automatic merging, report the blocker before proceeding.
+
+## Stop at the gate
+
+Use full-send's merge gate as the readiness check. Replace its merge and
+final report steps with a handoff. Proof and review must cover the final diff;
+recheck behavior changes and meaningful conflict fixes before handoff.
+
+Fetch the target branch and check the live PR's head, base, checks, reviews,
+and mergeability. Confirm it is open, not a draft, and not set to merge
+without the user. If someone else merged it, report that instead.
+
+- **Ready to merge:** the merge gate passes. Leave the PR open and unmerged.
+- **Waiting for required approval:** only human approval remains. Confirm
+  that this is the actual blocker.
+- **Blocked:** explain what prevents readiness, what you tried, and what is
+  needed. Follow full-send's rules for asking the user.
+
+In T3 Code, call `unwatch_pull_request` before the handoff or a question.
+Report the PR link, final head, verdict, proof, reviewer outcome, and remaining
+risks. State whether the PR is still open and unmerged.

package/tstack/skills/full-stop/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Full Stop"
+  short_description: "Prove, review, and prepare a PR without merging"
+  default_prompt: "Use $full-stop to make this PR ready for me to merge."

package/tstack/skills/leaving-pr-comments/SKILL.md

@@ -0,0 +1,44 @@
+---
+name: leaving-pr-comments
+description: Use whenever leaving comments on GitHub.
+---
+
+# Leaving PR Comments
+
+Prefix every agent-authored comment left on the user's behalf with this GitHub
+note callout:
+
+```md
+> [!NOTE]
+> 🤖 **<model> responding on behalf of <user>**
+
+Actual comment starts here.
+```
+
+Use the verified public name of the model that wrote the comment, and the
+user's name or GitHub login.
+
+If the harness does not expose a model name, use the harness name. Do not guess.
+
+Before posting, check the entire comment, including quoted text and
+attachments, for secrets and private details.
+
+Keep the attribution inside the note and the actual reply outside it. The
+context line must start with the robot emoji. Do not add a horizontal rule,
+Setext underline, heading, signature footer, or a second attribution.
+
+Apply this format to top-level PR comments, inline review comments, replies to
+bots or reviewers, and written explanations used before resolving or
+dismissing feedback. Do not add it to PR descriptions, commit messages, or text
+the user explicitly asked to post verbatim without attribution.
+
+Write the comment itself in a direct style:
+
+- Lead with the conclusion.
+- Cite the relevant code, behavior, check, or reproduction.
+- Keep it concise and avoid filler, canned thanks, or status narration.
+- Distinguish verified facts from judgment.
+
+Preview the final Markdown before posting so quoting and blank lines render as
+shown. After posting, verify that GitHub returned the comment or review URL.
+Resolve a review thread only after its response was posted successfully.

package/tstack/skills/leaving-pr-comments/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Leaving PR Comments"
+  short_description: "Format agent-authored GitHub PR comments"
+  default_prompt: "Use $leaving-pr-comments when posting this comment on my behalf."

package/tstack/skills/modernize/SKILL.md

@@ -0,0 +1,102 @@
+---
+name: modernize
+description: >-
+  For getting old prs up to date. Use when asked to rebase a pr or
+  "modernize".
+---
+
+# Modernize
+
+Modernize the idea, not just the branch. A clean rebase does not prove that the
+PR still belongs in the product.
+
+## Guardrails
+
+- Always check to make sure you have pulled latest origin for your branch, main
+  branch, and any other branch related to your work before starting.
+- Treat existing worktree changes as user-owned. Use a disposable worktree when
+  the active worktree is dirty or is being used for other work.
+- Modernizing authorizes rebasing and updating the PR branch. It does not
+  authorize merging, closing, changing the base branch, or expanding scope.
+- Never use an unqualified force push. Update a rebased branch with
+  `--force-with-lease` against the head SHA observed before the rebase.
+- Do not post a PR comment unless the user asked for one. Use the
+  `leaving-pr-comments` skill for every comment posted on the user's behalf.
+
+## Establish the PR's intent
+
+Resolve the PR and record its URL, state, base, head repository and branch,
+current head SHA, author, checks, and review state. Read the title, body, linked
+issues, commits, review threads, and complete diff. State the smallest coherent
+goal the PR was trying to accomplish before judging its implementation.
+
+Fetch the latest remote base and PR head. Use the PR's actual base branch,
+usually `main`, rather than assuming the local branch is current. Record the
+merge base so the original PR and subsequent base-branch changes can be
+compared separately.
+
+## Check what changed around it
+
+Inspect commits and diffs added to the base branch since the PR diverged. Search
+merged and open PRs when titles, code paths, or behavior suggest a replacement
+or competing implementation.
+
+Look beyond overlapping lines:
+
+- Has the same user-facing problem already been solved?
+- Did APIs, types, schemas, dependencies, or architectural boundaries change?
+- Do both sides now claim ownership of the same behavior or invariant?
+- Was the code being changed deleted, moved, or intentionally simplified?
+- Would landing the PR restore an old behavior or create two ways to do the
+  same thing?
+- Is the original benefit still large enough to justify the maintenance cost?
+
+Do not describe a PR as current merely because Git reports no conflicts.
+
+## Choose a disposition before pushing
+
+Use one of these recommendations:
+
+- **MODERNIZE**: the goal is still useful and the implementation remains the
+  right shape. Rebase, resolve conflicts, test, and update the branch.
+- **REWORK**: the goal is still useful, but a mechanical rebase would preserve
+  the wrong implementation. Explain the smallest credible rewrite and stop
+  before pushing unless the user also asked for that rework.
+- **CLOSE**: the PR is superseded, obsolete, directionally wrong, or no longer
+  worth its cost. Cite concrete evidence and stop. Do not spend time rebasing an
+  obsolete branch, and do not close it without explicit permission.
+
+Be willing to recommend `CLOSE`. Age alone is not evidence, and sunk effort is
+not a reason to keep a PR alive.
+
+## Rebase without losing intent
+
+For a `MODERNIZE` disposition:
+
+1. Create a safe local branch or disposable worktree at the recorded PR head.
+2. Rebase its commits onto the freshly fetched base branch.
+3. Resolve each conflict according to the PR's current intent and the base
+   branch's newer invariants. If a conflict reveals a product or architecture
+   disagreement, stop and reconsider the disposition instead of guessing.
+4. Compare the pre-rebase and post-rebase commit series with `git range-diff`
+   and inspect the final diff. Confirm that no intentional behavior disappeared
+   and no already-landed behavior was reintroduced.
+5. Run the repository's focused checks for the touched area. Distinguish real
+   failures from pre-existing or infrastructure failures.
+6. Push with `--force-with-lease` tied to the previously observed remote head.
+   If the lease fails, fetch and reassess rather than overwriting new work.
+
+Do not merge the PR.
+
+## Report
+
+Lead with `MODERNIZE`, `REWORK`, or `CLOSE` and the reason. Then summarize:
+
+- meaningful changes on the base branch;
+- conceptual conflicts or confirmation that none were found;
+- the rebase and push result, if performed;
+- checks run and their results;
+- the remaining decision or work, with a link to the PR.
+
+Separate observed facts from judgment. Say what could not be verified instead
+of manufacturing confidence.

package/tstack/skills/modernize/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Modernize PR"
+  short_description: "Rebase and reassess an aging pull request"
+  default_prompt: "Use $modernize to rebase this PR on its current base, check for conceptual conflicts, and tell me honestly whether it should stay open."

package/tstack/skills/sol-loop/SKILL.md

@@ -0,0 +1,119 @@
+---
+name: sol-loop
+description: Use when the user says "sol loop".
+---
+
+# sol-loop
+
+This is a workflow for making your code changes more correct before (or
+sometimes after) filing a pull request. tl;dr - use OpenAI's GPT Sol to review
+your code in a loop.
+
+Make the most minimal possible changes to appease the Sol reviewers. Be careful
+of scope creep and don't be scared to push back.
+
+## Budget
+
+- Default: 3 rounds total. Round 1 is full. Later rounds check only
+  changed code and open findings.
+- Extend to 5 only for security, permissions, auth, data loss, or
+  state/concurrency, while a blocker or should stays open with evidence. Or when
+  the user asks.
+- Stop early if a round returns only nits. Declined nits and comment,
+  doc, or format-only fixes need no new round.
+- One reviewer only. Sol must not start subagents or reviewers.
+- Keep a ledger: id, severity, outcome, usage if returned. Never guess it.
+
+## 1. Scope
+
+Run `git status --short`. Do not stash, discard, or include unrelated
+changes. Limit review to the change paths if they separate cleanly.
+Otherwise stop and ask.
+
+Find the base after `git fetch origin`:
+
+- PR: `gh pr view <n> --json baseRefName,headRefOid`. Check out the branch
+  only if clean. Confirm `HEAD` is the PR head, or ahead only by this
+  change. Base: `git merge-base HEAD origin/<baseRefName>`.
+- Local: `git merge-base HEAD origin/<default-branch>`. No remote: a base
+  the user names, or `HEAD` for uncommitted changes only.
+
+The change is base to working tree in those paths, with untracked files.
+Use one diff command all rounds. State intent and out-of-scope in 1-2
+sentences. Run covering checks. Do not send code this change breaks. Note
+missing or pre-failing checks in the brief.
+
+## 2. Start Sol
+
+In T3, call `orchestrator_capabilities`. Pick the latest Sol unless the user
+named a version. Do not hardcode an ID. Record provider, model, and effort
+only if exposed. Use `delegate_task` every round (`role: "review"`,
+`mode: "async"`). Save `taskId`. New `clientRequestId` per round.
+`childThreadId` is storage, not the next target. Do not use
+`t3_thread_send`, `create_threads`, or `t3_thread_launch` for review.
+
+If T3 tools are not listed, try one direct capability call. Outside T3, use
+a native Sol subagent and keep its ID. In Claude Code, use a custom subagent
+only if it is set up to run Sol. If no route runs Sol, report the blocker. Do
+not substitute a model.
+
+Do not edit scoped files while review runs. Wait for the notice. Do not
+poll or start a second reviewer. Timeout, error, or no reply is not
+approval. On failure, cancel, verify stop, restart with the ledger.
+
+Round 1 brief (T3 children get no history):
+
+```
+Review only. Do not edit, commit, push, comment on PRs, or start subagents.
+Repo: <abs path> Base: <sha> Intent: <intent> Out of scope: <scope> Checks: <results>
+See: git diff <base> [-- <paths>]; git status --short (read untracked).
+Read surrounding code. Find bugs, broken callers, mismatch with intent.
+Skip style unless it hides a bug. Hold to the smallest change. Flag code,
+tests, or guards the intent does not need. Other paths, rare cases, small
+perf, extra compat: nits.
+blocker = intended case wrong. should = real bug callers will hit, in intent. nit = rest.
+Reply:
+VERDICT: APPROVE or CHANGES
+S1 [blocker|should|nit] <file>:<line> <claim>. Fix: <suggestion> (stable ids)
+```
+
+## 3. Answer findings
+
+Check each finding and severity yourself. Another path, rare case, or
+small cost is a nit, whatever label it came with.
+
+- Agree: smallest fix. Prefer delete or narrow over new lock, cache,
+  helper, or option. Fix the case that happened. Add one focused test
+  that fails without the fix, if intent needs it.
+- Disagree: say why, with evidence (file:line, test, output).
+- Out of scope or nit: decline in one line. List as follow-up.
+
+Update the ledger. Re-run checks and `git diff --shortstat <base>`. If
+review grew the diff, cut first. Do not agree just to end the loop.
+
+## 4. Next round
+
+Start one only if budget remains and a blocker or should is open, behavior code
+changed, or approval does not cover the current behavior diff. Use a fresh
+`delegate_task` in T3, or follow up the saved native ID. Send the round 1 brief,
+the ledger (`fixed:` / `disagree:` / `declined:` + evidence), the same base
+diff, and the change since last round. Tell Sol: open ids and changed code only.
+Mark each old id `resolved` or `still open: <reason>`.
+
+## 5. Stop and ship
+
+Agreed: APPROVE on the current behavior diff, no blocker or should open,
+no concern of your own. Stuck: an item stays disputed after two replies,
+or budget ends. Show both sides in 2-3 lines each. The user decides.
+Budget end is not approval.
+
+Do not push during the loop. Push after agreement only if the user asked
+to push, ship, or update the PR. If you push to a PR, add above the model
+blurb:
+
+`Reviewed with sol-loop: <N> rounds with <model>. Sol verdict: approved`.
+
+Add `on <effort>` only if verified.
+
+Report: rounds, model, what Sol changed, diff size before/after, fixed and
+declined findings with reasons, usage if exposed (else say not), pushed or not.

package/tstack/skills/takeover/SKILL.md

@@ -0,0 +1,42 @@
+---
+name: takeover
+description: Take over existing work. Use when the user asks to take over a PR, branch, or agent thread, or requests a takeover.
+---
+
+# Takeover
+
+Take responsibility for finishing the original goal while preserving the
+original contributors' credit. Do not defend an implementation just because
+another agent already built it.
+
+Read the source PR, branch, or thread, including review findings and the user's
+later corrections. Resolve the handoff to the actual code and current head,
+and account for uncommitted work. Treat the handoff as context, not proof.
+
+For a replacement PR, import the original commits onto a new branch and add
+your fixes separately. Honor an explicitly requested in-place or stacked
+continuation instead. Do not overwrite unrelated work or change the original
+PR without authorization.
+
+Preserve Git authorship and existing co-author trailers. Credit the original
+contributors in the PR description and link the original PR when there is one.
+If the work will be squashed, preserve human author/co-author credit in the
+merge commit too, using verified identities rather than guessed emails. Model
+attribution is not a substitute for contributor credit.
+
+Use `modernize` to update the continuation against its intended base and
+current architecture. Rework what is necessary to finish the same goal, not
+unrelated features. Simplify the implementation without dropping intended
+behavior or surfaces. Recheck the source PR too: it may have improved while
+you were working.
+
+Independently verify the original failure and realistic workflows, following
+repository guidance and permissions. Green mocked tests do not prove the user
+experience works. State what remains unverified.
+
+When the requested finish includes a PR, use `file-pr` to file or update it,
+then `babysit-pr` rather than stopping at creation. Use `leaving-pr-comments`
+for replies. Merge or close the original PR only when authorized.
+
+Report what you inherited, what you changed, how you verified it, how credit
+was preserved, and any remaining decision.

package/tstack.ts

@@ -0,0 +1,21 @@
+import { existsSync } from "node:fs";
+import path from "node:path";
+
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+
+// Theo Browne's tstack skills, vendored under tstack/. This extension only
+// serves their skill directory. It imports nothing from src/bridge or
+// src/pstack, so the skills stay available when either extension is off.
+const tstackExtension = (pi: ExtensionAPI): void => {
+  const skillsDir = path.join(
+    path.resolve(import.meta.dirname),
+    "tstack",
+    "skills"
+  );
+
+  pi.on("resources_discover", () => ({
+    skillPaths: existsSync(skillsDir) ? [skillsDir] : [],
+  }));
+};
+
+export default tstackExtension;