@plot-ai/darwin-arm64 0.0.1

package/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "@plot-ai/darwin-arm64",
+  "version": "0.0.1",
+  "type": "module",
+  "license": "MIT",
+  "description": "orchestrate coding agents against an issue tracker",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/igorsheg/plot.git",
+    "directory": "packages/plot"
+  },
+  "homepage": "https://github.com/igorsheg/plot",
+  "bugs": {
+    "url": "https://github.com/igorsheg/plot/issues"
+  },
+  "os": [
+    "darwin"
+  ],
+  "cpu": [
+    "arm64"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "bin",
+    "web-dist",
+    "pi-resources",
+    "package.json"
+  ]
+}

package/pi-resources/skills/core/plot-commit/SKILL.md

@@ -0,0 +1,68 @@
+---
+name: plot-commit
+description: "session-aware conventional commits for plot. produces commits with summary, rationale, and validation evidence. use when committing implementation work during orchestrated issue execution."
+---
+
+# plot-commit
+
+## goals
+
+- produce commits that reflect the actual code changes and session context
+- follow conventional commit format with rationale
+- never stage unrelated changes
+
+## steps
+
+1. inspect working tree and staged changes:
+
+   ```bash
+   git status
+   git diff
+   git diff --staged
+   ```
+
+2. stage only your changes explicitly — never `git add -A` or `git add .`:
+
+   ```bash
+   git add <specific-files>
+   ```
+
+3. sanity-check staged files — flag build artifacts, logs, or temp files before committing.
+
+4. choose a conventional type that matches the change:
+   - `feat(scope):` — new feature
+   - `fix(scope):` — bug fix
+   - `refactor(scope):` — restructuring without behavior change
+   - `docs(scope):` — documentation only
+   - `test(scope):` — test additions/changes
+   - `chore(scope):` — tooling, deps, config
+
+5. write the commit message:
+
+   ```
+   <type>(<scope>): <short summary, imperative mood, ≤72 chars>
+
+   Summary:
+   - <what changed>
+
+   Rationale:
+   - <why it changed>
+
+   Validation:
+   - <what was verified, or "not run (reason)">
+   ```
+
+6. commit using a file to preserve formatting:
+   ```bash
+   cat > /tmp/commit-msg.md << 'EOF'
+   <message>
+   EOF
+   git commit -F /tmp/commit-msg.md
+   ```
+
+## rules
+
+- subject line: imperative mood, ≤72 chars, no trailing period
+- body lines: wrapped at 72 chars
+- staged diff must match the commit message — if they diverge, fix the index or revise the message
+- one logical change per commit when practical

package/pi-resources/skills/core/plot-debug/SKILL.md

@@ -0,0 +1,116 @@
+---
+name: plot-debug
+description: "investigate stuck runs, retry loops, and execution failures in the plot orchestrator. correlates logs by issue id, workspace path, and session state. use when runs stall, retry repeatedly, or fail unexpectedly."
+---
+
+# plot-debug
+
+## goals
+
+- find why a run is stuck, retrying, or failing
+- correlate issue identity to agent session and workspace
+- read the right logs in the right order to isolate root cause
+
+## log sources
+
+plot logs to stdout as structured key-value pairs. relevant log messages include:
+
+| message                 | meaning                              |
+| ----------------------- | ------------------------------------ |
+| `dispatch`              | agent dispatched for issue           |
+| `agent_session_created` | pi session started in workspace      |
+| `retry_scheduled`       | retry queued (continuation or error) |
+| `retry_issue_gone`      | issue disappeared during retry       |
+| `reconcile`             | active run state check               |
+| `tick`                  | poll cycle summary                   |
+| `workspace_ready`       | workspace created/reused             |
+| `agent_failed`          | agent exited with error              |
+| `worker_interrupted`    | agent was stopped by reconciliation  |
+
+## correlation keys
+
+- `issue_id` — numeric github issue number
+- `identifier` — human-readable `#N`
+- `state` — issue state at dispatch time
+- `workspace` — absolute workspace path
+- `attempt` — retry attempt number
+- `error` — failure reason (or `continuation` for normal re-check)
+
+## quick triage
+
+### issue not being picked up
+
+```bash
+# check if issue has correct label
+gh issue view <number> --repo $GITHUB_REPO --json labels
+
+# check server logs for candidate detection
+# look for tick logs showing candidates > 0
+```
+
+possible causes:
+
+- missing or wrong `plot:*` state label (unlabeled issues are ignored)
+- issue already claimed (check `running` or `retrying` counts)
+- no available slots (`max_concurrent_agents` reached)
+- issue has non-terminal blockers (`plot:todo` state only)
+
+### agent stuck / not progressing
+
+```bash
+# check if session is still running
+# look for recent reconcile logs with stopped: 0
+
+# check stall timeout config
+# default: 120000ms (2 min) — if no events for this long, agent is killed
+```
+
+possible causes:
+
+- agent waiting for user input (hard fail in pi)
+- stall timeout too short for complex tasks
+- workspace has broken state (missing deps, corrupt git)
+
+### retry loop
+
+```bash
+# look for repeated retry_scheduled logs for same issue_id
+# check error field — if "continuation", agent completed normally
+# if actual error, check the error message
+```
+
+possible causes:
+
+- `continuation` retries are normal (agent finished, orchestrator re-checks if issue still active)
+- `retry_issue_gone` means issue was closed/moved to terminal state during retry
+- real errors trigger exponential backoff: 10s, 20s, 40s... up to max_retry_backoff_ms
+
+### workspace issues
+
+```bash
+# check workspace exists and is valid
+ls -la workspaces/<workspace-key>/
+
+# check git worktree state
+cd workspaces/<workspace-key> && git status
+
+# check if hooks failed (after_create, before_run)
+# look for hook timeout/failure in logs
+```
+
+## investigation flow
+
+1. identify the issue: `identifier` or `issue_id`
+2. find dispatch logs: look for `dispatch` with matching identifier
+3. find session logs: look for `agent_session_created` with matching issue_id
+4. check outcome: `retry_scheduled` (error field tells you why)
+5. if stuck: check `reconcile` logs — is `stopped` incrementing?
+6. if retry loop: check retry `attempt` numbers — are they climbing?
+
+## orchestrator state
+
+the server exposes runtime state at `http://localhost:3000/rpc` via RPC. the dashboard at `http://localhost:3000` shows:
+
+- running sessions with turn counts and token usage
+- retry queue with attempt numbers and due times
+- aggregate token totals and runtime

package/pi-resources/skills/core/plot-land/SKILL.md

@@ -0,0 +1,122 @@
+---
+name: plot-land
+description: "merge an approved PR for plot. monitors CI, resolves conflicts, handles review feedback, squash-merges, and transitions issue to plot:done. use when issue enters plot:merging state."
+---
+
+# plot-land
+
+## goals
+
+- ensure PR is conflict-free with main
+- address any outstanding review feedback
+- squash-merge the PR when checks pass
+- transition issue to plot:done and close it
+
+## preconditions
+
+- `gh` CLI is authenticated
+- issue is in `plot:merging` state (label)
+- a PR exists for the current branch
+
+## steps
+
+1. locate the PR:
+
+   ```bash
+   branch=$(git branch --show-current)
+   pr_number=$(gh pr view --json number -q .number --repo "$GITHUB_REPO")
+   ```
+
+2. run the review feedback sweep before merging:
+
+   ```bash
+   # top-level PR comments
+   gh pr view "$pr_number" --repo "$GITHUB_REPO" --comments
+
+   # inline review comments (line-level)
+   gh api repos/$GITHUB_REPO/pulls/$pr_number/comments
+
+   # review summaries
+   gh pr view "$pr_number" --repo "$GITHUB_REPO" --json reviews
+   ```
+
+   for each actionable comment:
+   - **accept**: implement fix, commit, push
+   - **push back**: reply with justification
+   - **clarify**: ask for specifics
+
+   do not merge while review comments are outstanding.
+
+3. check mergeability:
+
+   ```bash
+   mergeable=$(gh pr view --json mergeable -q .mergeable --repo "$GITHUB_REPO")
+   ```
+
+   if `CONFLICTING`:
+   - use the `plot-pull-main` skill to merge origin/main and resolve conflicts
+   - use the `plot-push-pr` skill to push the updated branch
+
+   if `UNKNOWN`:
+   - wait and re-check
+
+4. run local verification:
+
+   ```bash
+   bun run typecheck
+   bun run lint
+   ```
+
+5. watch CI checks:
+
+   ```bash
+   gh pr checks "$pr_number" --repo "$GITHUB_REPO" --watch
+   ```
+
+   if checks fail:
+   - inspect logs: `gh run view <run-id> --log`
+   - fix locally, commit with `plot-commit`, push with `plot-push-pr`
+   - re-run check watch
+
+   use judgment for flaky failures (timeouts on one platform) — may proceed.
+
+6. squash-merge:
+
+   ```bash
+   pr_title=$(gh pr view --json title -q .title --repo "$GITHUB_REPO")
+   gh pr merge "$pr_number" --squash --subject "$pr_title" --repo "$GITHUB_REPO"
+   ```
+
+7. transition issue to `plot:done`:
+   ```bash
+   # extract issue number from PR body (Resolves #N)
+   issue_number=$(gh pr view "$pr_number" --repo "$GITHUB_REPO" --json body -q '.body | capture("Resolves #(\d+)").["1"]')
+
+   gh issue edit "$issue_number"      --repo "$GITHUB_REPO"      --remove-label "plot:merging"      --add-label "plot:done"
+
+   gh issue close "$issue_number" --repo "$GITHUB_REPO"
+   ```
+
+## review response format
+
+when responding to feedback on the PR:
+
+```
+[plot] <response — what you're doing about this comment>
+```
+
+prefix all agent-generated PR comments with `[plot]`.
+
+## rules
+
+- never call `gh pr merge` without completing the review sweep first
+- only use `--force-with-lease` if history was rewritten; prefer normal push
+- do not enable auto-merge — run the full watch loop
+- address correctness feedback with concrete validation before closing it
+- after pushing fixes, post a summary comment:
+  ```
+  [plot] Changes since last review:
+  - <bullets>
+  Commits: <sha>
+  Validation: <commands run>
+  ```

package/pi-resources/skills/core/plot-pull-main/SKILL.md

@@ -0,0 +1,99 @@
+---
+name: plot-pull-main
+description: "sync current branch with origin/main using merge and zdiff3 conflict resolution. use before implementation starts and before pushing to ensure branch is up to date."
+---
+
+# plot-pull-main
+
+## goals
+
+- keep feature branch current with `origin/main`
+- resolve merge conflicts with intent-preserving edits
+- verify project health after merge
+
+## steps
+
+1. ensure working tree is clean:
+
+   ```bash
+   git status
+   ```
+
+   if dirty, commit or stash changes first.
+
+2. enable rerere for learned conflict resolution:
+
+   ```bash
+   git config rerere.enabled true
+   git config rerere.autoupdate true
+   ```
+
+3. fetch latest refs:
+
+   ```bash
+   git fetch origin
+   ```
+
+4. sync remote feature branch first (catches remote auto-commits):
+
+   ```bash
+   git pull --ff-only origin $(git branch --show-current) || true
+   ```
+
+5. merge origin/main with zdiff3 for clearer conflict context:
+
+   ```bash
+   git -c merge.conflictstyle=zdiff3 merge origin/main
+   ```
+
+6. if conflicts appear, resolve them following the protocol below, then:
+
+   ```bash
+   git add <resolved-files>
+   git merge --continue
+   ```
+
+7. verify project health:
+   ```bash
+   bun run typecheck
+   bun run lint
+   ```
+
+## conflict resolution protocol
+
+- inspect before editing:
+
+  ```bash
+  git status                                    # list conflicted files
+  git diff                                      # see conflict hunks
+  git diff :1:<file> :2:<file>                  # base vs ours
+  git diff :1:<file> :3:<file>                  # base vs theirs
+  ```
+
+- with zdiff3, conflict markers include `|||||||` (base) between ours and theirs — use it to understand both sides' intent
+
+- resolve strategy:
+  1. state what each side is trying to achieve
+  2. identify the shared goal
+  3. decide the final behavior first, then write the code
+  4. prefer preserving API contracts and user-visible behavior
+
+- resolve one file at a time, run verification after each logical batch
+
+- for generated files: resolve source files first, then regenerate
+
+- for import conflicts: accept both sides temporarily, then run lint to remove unused imports
+
+- confirm no conflict markers remain:
+  ```bash
+  git diff --check
+  ```
+
+## rules
+
+- always merge, never rebase (preserves history for orchestrator tracking)
+- use `--ff-only` for same-branch pulls only
+- document merge result in workpad Notes section:
+  - merge source(s)
+  - result: `clean` or `conflicts resolved`
+  - resulting HEAD short SHA

package/pi-resources/skills/core/plot-push-pr/SKILL.md

@@ -0,0 +1,109 @@
+---
+name: plot-push-pr
+description: "push branch and create/update pull request for plot. handles PR creation, template compliance, title/body maintenance, and closed PR detection. use when publishing changes and opening or updating a PR."
+---
+
+# plot-push-pr
+
+## goals
+
+- push current branch to origin safely
+- create or update a PR with template-compliant body
+- detect and handle closed/merged PR branches
+
+## steps
+
+1. identify current branch and confirm it's not `main`:
+
+   ```bash
+   branch=$(git branch --show-current)
+   if [ "$branch" = "main" ]; then echo "ERROR: do not push directly to main"; exit 1; fi
+   ```
+
+2. run validation before pushing:
+
+   ```bash
+   bun run typecheck
+   bun run lint
+   ```
+
+3. push branch to origin:
+
+   ```bash
+   git push -u origin HEAD
+   ```
+
+   if push is rejected (non-fast-forward), sync first:
+
+   ```bash
+   git fetch origin
+   git merge origin/main
+   git push -u origin HEAD
+   ```
+
+4. check if a PR already exists for this branch:
+
+   ```bash
+   pr_state=$(gh pr view --json state -q .state --repo "$GITHUB_REPO" 2>/dev/null || echo "NONE")
+   ```
+
+5. handle PR state:
+   - `NONE` → create new PR
+   - `OPEN` → update existing PR
+   - `MERGED` or `CLOSED` → branch is stale; create a new branch and PR
+
+6. create PR with template compliance:
+
+   ```bash
+   gh pr create      --title "#<number>: <clear description of change>"      --body-file /tmp/pr-body.md      --repo "$GITHUB_REPO"
+   ```
+
+   after creation:
+   - ensure the PR body includes `Resolves #<number>` so GitHub links and closes the issue on merge
+   - move the issue into review by swapping labels:
+
+   ```bash
+   gh issue edit <number>      --repo "$GITHUB_REPO"      --remove-label "plot:in-progress"      --add-label "plot:human-review"
+   ```
+
+7. update existing PR if scope changed:
+   ```bash
+   gh pr edit --title "#<number>: <updated title>" --body-file /tmp/pr-body.md --repo "$GITHUB_REPO"
+   ```
+
+   after update:
+   - keep `Resolves #<number>` in the PR body so linkage stays intact
+
+## PR body template
+
+the PR body must follow `.github/pull_request_template.md`. fill every section:
+
+```markdown
+## Summary
+
+<what this PR does — 1-2 sentences>
+
+## Changes
+
+- <key change 1>
+- <key change 2>
+
+## Verification
+
+- [x] Typecheck passes (`bun run typecheck`)
+- [x] Lint passes (`bun run lint`)
+- <additional verification done>
+
+## Issue
+
+Resolves #<number>
+```
+
+## rules
+
+- never force push (`--force` or `-f`)
+- `--force-with-lease` only when history was rewritten (rebase)
+- PR title format: `#<number>: <short description>`
+- PR body must have all template sections filled — no placeholder comments
+- on branch updates, reconsider whether PR title still matches scope
+- return PR URL after creation/update