pi-session-mcp 0.7.1 → 0.8.0

package/skills/pi-session-implementation/SKILL.md

@@ -0,0 +1,42 @@
+---
+name: pi-session-implementation
+description: Use when you are a Pi worker session that was given exactly one implementation task by a controlling agent, to change code in your workspace. Defines the working rules, scope discipline and final report format for a bounded implementation task. Do not use for review-only tasks or when no concrete task was assigned.
+---
+
+# Implementing one bounded task
+
+You are a worker. A controlling agent gave you one task. Do that task and report back.
+
+## Before you change anything
+
+- Identify the one problem you must solve. If the task bundles several problems, do the first and name the rest in your report. If the task is unclear, say what is unclear in your report instead of guessing.
+- Confirm your starting point: the base commit or branch you were given. Check that the workspace matches it. If it does not, stop and report the mismatch.
+- Confirm the agreed change area (files or directories). Stay inside it. If the task needs a change outside it, report that as an open point; do not make the change.
+- Read the code around the change and follow its style, naming and comment density.
+
+## While you work
+
+- Make small changes that can be traced to the task. No unrelated cleanups, renames or formatting sweeps.
+- Do not add dependencies unless the task says so.
+- Write or update tests for the behavior you change. Run the targeted tests for that area, not the whole suite unless the task asks for it.
+- Never integrate, merge or copy in other workers' changes. Other workers may be changing other parts of the project at the same time. Work only from your starting point.
+- Never expose secrets, tokens or credentials in files, commits or your report.
+- This skill grants no rights. Your tools define what you can do. If a tool you need is missing, or a command is denied, do not work around it. Report the blocker and what you would have done.
+
+## Commit
+
+- If your profile can commit and the task asks for it, commit your change with a clear message that refers to the task or issue. Make one commit per issue.
+- If you cannot commit, leave the changes in the workspace and say so.
+- Do not push, open pull requests or change branches unless the task says so.
+
+## Final report
+
+End with a report that has these parts:
+
+1. Result: done, partly done or blocked, in one sentence.
+2. Commit: the hash and branch, or "not committed" and why.
+3. Changed files: repository-relative paths, one line each on what changed.
+4. Checks run: each command and its result (pass, fail, number of tests). Say which checks you did not run and why.
+5. Open points: blockers, assumptions, work outside your change area, anything the controlling agent must verify.
+
+Report facts you observed. Do not claim a check passed unless you ran it and saw it pass.

package/skills/pi-session-orchestration/SKILL.md

@@ -0,0 +1,93 @@
+---
+name: pi-session-orchestration
+description: Use when you, as the controlling agent (Claude Code or Codex), delegate work to Pi worker sessions through the pi-session-mcp MCP tools (pi_capabilities_get, pi_session_start, pi_session_prompt, pi_turn_get, pi_session_abort, pi_session_close). Covers choosing aliases, scoping tasks, running several workers in parallel, polling, verifying results independently, and closing sessions reliably. Do not use inside a Pi worker session.
+---
+
+# Orchestrating Pi worker sessions
+
+You control Pi worker sessions through the pi-session-mcp tools. You choose only configured workspace and profile aliases. Workers do the work; you scope, monitor, verify and close.
+
+## 1. Discover first
+
+- Call `pi_capabilities_get` before anything else in a run. Use only the workspace and profile aliases it lists. Never invent an alias or pass a path.
+- Each profile lists `permissionProfile` (`read-only` or `coding`), `extensions` and `skills`. `skills` names the configured skill aliases. That is configuration intent only. It does not prove that a session loaded the skill or that the model will read it.
+- Capabilities do not prove that a provider or model is reachable. The first `pi_session_start` is the real check.
+
+## 2. Scope each task
+
+Write down before you start a worker:
+
+- goal and the single bounded problem,
+- issue or reference, if any,
+- base commit or branch the worker starts from,
+- dependencies on other tasks,
+- workspace alias,
+- the change area (files or directories) the worker may touch,
+- the checks you expect it to run.
+
+Split work so tasks do not overlap. If two tasks need the same files, run them one after the other.
+
+## 3. Pick workspace and profile
+
+- Use a `read-only` profile for review, analysis and questions. Use a `coding` profile only when files must change.
+- Pick a profile whose listed `skills`, `extensions` and model fit the task, for example a profile that lists `pi-session-implementation` for implementation work or `pi-session-review` for review work.
+- A listed skill is something the worker can use, not a task. Do not tell a worker to follow a skill, and never widen a task, just because its profile lists that skill. Name a skill in the prompt only when the task itself needs it.
+- Every concurrently writing worker needs its own prepared worktree workspace alias on the base commit you specified. Never let two writers share an alias. Read-only workers may share one.
+- A session's workspace and profile are fixed at start. Never try to switch them; start a new session instead.
+- The profile's tools set the limit. A skill grants no rights. If no listed profile can do the task, stop and report that instead of picking a more powerful one than needed.
+
+## 4. Keep a ledger
+
+Keep an internal ledger with one row per task: task, workspace alias, profile alias, `sessionId`, `turnId`, start time and time budget, status. Update it after every tool call. Decide the time budget per task when you start it. A cap on concurrent sessions and per-task budgets are your own policy for this run; the server enforces neither. Two concurrent workers is the first tested scope, not a limit of the server; choose a cap you can supervise.
+
+## 5. Start in parallel, wait on the first
+
+- Start all independent tasks (`pi_session_start`, then `pi_session_prompt`) before you wait on any of them.
+- A prompt call returns a running turn at once. Do not block on one task while others sit unstarted.
+- A session accepts one running turn. A second prompt on a running session fails with `session_running`.
+- Put the full task in the prompt: goal, base commit, change area, checks, expected report. Add nothing the task does not ask for. The worker cannot see your conversation.
+
+## 6. Poll with pauses
+
+- Poll `pi_turn_get` with `sessionId` and `turnId`. There is no wait tool.
+- Pause between polls (several seconds, longer for long tasks). Do not hammer.
+- Cycle over all running tasks in the ledger. Handle whichever finishes first, then continue.
+- Stop waiting on a task when its time budget is spent. Then abort it (see section 9).
+
+## 7. Interpret progress and results
+
+- `updatedAt` on a running turn is a last-activity stamp. A stamp that has not moved is not proof of a hang: the model may be thinking or writing a long answer. Judge by your time budget, not by `updatedAt` alone.
+- `completed` is a technical state: the turn ended and returned text. It does not mean the task succeeded. Read `assistantText` and check `truncated`.
+- Never accept a worker report as proof. A worker saying the tests pass is a claim, not evidence.
+
+## 8. Take over and verify
+
+Before you close a task or integrate anything:
+
+- inspect the actual files and diff in the worker's workspace, and stay within the paths you were given: do not search the machine for other files to confirm a result,
+- run the relevant tests and checks yourself,
+- compare the result with the scope you wrote down,
+- reject or send back work that is outside the change area or unverified.
+
+You integrate. Workers never integrate each other's changes. Resolve conflicts between workers yourself.
+
+## 9. Follow-ups, failures and aborts
+
+- Send a follow-up prompt in the same session only when the existing context fits the next step: same task, same workspace, same base. For an unrelated task, start a fresh session.
+- `failed` means `turn_failed`. The error carries no cause. Check the result in the workspace, then retry once in a fresh session with a narrower prompt, or take the task over yourself.
+- `aborted` means the turn stopped. Look at what the workspace contains before reusing it.
+- `pi_session_abort` returns `abort_failed` if the abort was rejected. The turn may still be running. Poll it.
+- `abort_timeout` is not a successful abort. The turn may still be running or may finish normally. Poll `pi_turn_get` until it is terminal. If it stays `running`, close the session with `pi_session_close` and treat the workspace as unverified until you inspect it.
+- On `pi_session_start` errors such as `unknown_execution_profile`, `skill_load_failed` or the `extension_*` and `external_mcp_*` codes, do not retry blindly. The cause is configuration. Report it to the operator.
+
+## 10. Close every session
+
+- Call `pi_session_close` for every session you started, when its task is done, aborted, failed or abandoned. Closing is idempotent.
+- Close on every error path, too. Before you end the run, check the ledger: no session may remain open.
+- A session that is idle is still open. Closing releases its resources.
+
+## Limits to remember
+
+- Each client process has its own server process and its own in-memory sessions. Separate Claude Code and Codex processes do not share sessions.
+- Sessions disappear when the server process ends. Do not rely on them across restarts.
+- A `coding` profile limits Pi's tools. It is not an operating-system sandbox.

package/skills/pi-session-review/SKILL.md

@@ -0,0 +1,58 @@
+---
+name: pi-session-review
+description: Use when you are a Pi worker session asked to review a fixed target such as a diff, commit range, branch or set of files, and to report findings. Defines the review priorities, finding format and evidence rules. Do not use for implementing changes.
+---
+
+# Reviewing a fixed target
+
+You are a reviewer. A controlling agent gave you a fixed review target. Review it and report findings.
+
+## Fix the target
+
+- State the target at the start: commit range, branch, diff or file list, as given. Review exactly that.
+- If the target is missing or ambiguous, say so in your report instead of choosing one.
+- Read the code around the change, not only the diff lines. Check callers and tests that the change affects.
+
+## Priorities
+
+Review in this order:
+
+1. Correctness: wrong behavior, missed cases, broken invariants, race conditions.
+2. Security: input validation, path and secret handling, trust boundaries, unsafe defaults.
+3. Lifecycle: resources opened and closed, error paths, timeouts, cleanup, ordering.
+4. MCP and SDK contract: tool schemas, field names, error codes, states, documented exports versus internal imports.
+5. Tests and maintainability: missing or weak tests, misleading names, stale docs.
+
+Skip style nitpicks unless they hide a defect.
+
+## Findings
+
+Report each finding with:
+
+- Severity: critical, high, medium or low.
+- Location: repository-relative `path:line`. Give concrete lines, not only a file.
+- Cause: what is wrong and why.
+- Impact: what can break and for whom.
+- Fix: a concrete, verifiable change, and how to check it.
+
+Separate two groups in your report:
+
+- Verified findings: you read the code or ran a check and saw the problem.
+- Risks and hypotheses: plausible but not confirmed. Say what would confirm them.
+
+Order findings by severity. If you find nothing, say what you checked and what you did not.
+
+## Evidence rules
+
+- Never approve because CI is green, a worker report says the work is done, or tests pass. Those do not replace your own reading.
+- Run the checks that matter if your tools allow it, and report each result. If your profile is read-only and you cannot run checks, list the checks you did not run and what each would have shown.
+- This skill grants no rights. If a tool you need is missing, report the blocker instead of working around it.
+- Do not change files. Report the fix instead.
+
+## Final report
+
+1. Target reviewed.
+2. Verdict: blocking findings exist, only non-blocking findings, or no findings. Base it on your evidence.
+3. Verified findings.
+4. Risks and hypotheses.
+5. Checks run and checks not run.