@plot-ai/darwin-arm64 0.0.3 → 0.0.4

package/bin/CHANGELOG.md

@@ -1,5 +1,5 @@
 # changelog
 
-## 0.0.3
+## 0.0.4
 
 - packaged plot-ai release

package/bin/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@plot-ai/darwin-arm64",
-  "version": "0.0.3",
+  "version": "0.0.4",
   "piConfig": {
     "name": "plot",
     "configDir": ".plot"

package/bin/tracker/beads/skills/plot-beads-tracker/SKILL.md

@@ -0,0 +1,241 @@
+---
+name: plot-beads-tracker
+description: "beads issue state management for plot orchestration. hybrid model: native beads status for primary lifecycle, labels for orchestrator sub-states (rework, merging). workpad comment lifecycle and bd queries. use when moving issues between states, creating/updating workpad comments, or querying issue status."
+---
+
+# plot-beads-tracker
+
+manages issue state and progress tracking for the plot orchestrator via beads status, labels, and comments.
+
+use `bd` for all tracker operations. the git/PR lifecycle uses `gh` separately.
+
+## state model
+
+beads uses a hybrid state model with two layers:
+
+- **status** (native beads lifecycle): `open`, `in_progress`, `blocked`, `deferred`, `closed`
+- **labels** (orchestrator sub-states): `plot:rework`, `plot:merging`
+
+the orchestrator checks labels first. if a configured label exists on the issue, it becomes the routing state. otherwise the native beads status is the state.
+
+```
+                  ┌─────────┐
+                  │  open    │  agent picks up, starts work
+                  └────┬────┘
+                       │ bd update <id> --status in_progress
+                       ▼
+                ┌─────────────┐
+                │ in_progress  │  agent implements, pushes PR
+                └──────┬──────┘
+                       │ bd update <id> --status blocked
+                       ▼
+                  ┌─────────┐
+                  │ blocked  │  human reviews PR
+                  └────┬────┘
+                       │
+            ┌──────────┼──────────┐
+            ▼          ▼          ▼
+     ┌────────────┐  ┌─────────────────┐  ┌────────┐
+     │plot:rework │  │  plot:merging    │  │closed  │
+     │(label)     │  │  (label)        │  │(reject)│
+     └─────┬──────┘  └───────┬─────────┘  └────────┘
+           │                 │
+           │ agent fixes,    │ agent merges PR,
+           │ removes label,  │ removes label,
+           │ → blocked       │ closes issue
+           │                 │
+           ▼                 ▼
+      ┌─────────┐      ┌────────┐
+      │ blocked  │      │ closed │
+      └─────────┘      └────────┘
+```
+
+## state transitions
+
+```bash
+# open → in_progress (starting work)
+bd update <id> --status in_progress
+
+# in_progress → blocked (PR ready for review)
+bd update <id> --status blocked
+
+# human approves → add merging label (human does this)
+bd label add <id> plot:merging
+
+# human requests changes → add rework label (human does this)
+bd label add <id> plot:rework
+
+# plot:rework → blocked (rework complete, remove label first)
+bd label remove <id> plot:rework
+bd update <id> --status blocked
+
+# plot:merging → closed (PR merged, remove label first)
+bd label remove <id> plot:merging
+bd close <id> -r "completed"
+
+# reopen closed → in_progress
+bd reopen <id> -r "needs rework"
+```
+
+## available states
+
+| source | state          | meaning                     | agent action                                          |
+| ------ | -------------- | --------------------------- | ----------------------------------------------------- |
+| status | `open`         | queued for work             | move to `in_progress`, start implementation           |
+| status | `in_progress`  | implementation underway     | continue implementation, push PR, move to `blocked`   |
+| status | `blocked`      | waiting on human review     | do nothing, wait                                      |
+| status | `deferred`     | intentionally postponed     | do nothing, wait                                      |
+| label  | `plot:rework`  | reviewer requested changes  | address feedback, remove label, move to `blocked`     |
+| label  | `plot:merging` | human approved PR           | merge PR, remove label, close issue                   |
+| status | `closed`       | terminal                    | stop                                                  |
+
+workflow routing:
+
+- dispatch_states: `open`, `in_progress`, `plot:rework`, `plot:merging`
+- parked_states: `blocked`, `deferred`
+- terminal_states: `closed`
+
+## workpad comment
+
+a persistent beads comment used as a living scratchpad across agent sessions.
+
+### find current workpad
+
+comments are append-only. there is no edit-in-place. the current workpad is the latest comment whose body starts with `## Plot Workpad`.
+
+```bash
+bd comments <id> --json
+```
+
+scan the returned comments and pick the latest one starting with `## Plot Workpad`.
+
+if none exists, create one.
+
+### create workpad
+
+write the full workpad body to a temp file, then add it as a comment:
+
+````bash
+cat > /tmp/workpad.md <<'WORKPAD'
+## Plot Workpad
+
+```text
+<workspace-id>@<short-sha>
+```
+
+### Plan
+- [ ] 1. <task>
+
+### Acceptance Criteria
+- [ ] <criterion>
+
+### Validation
+- [ ] targeted tests: `<command>`
+
+### Latest Attempt Summary
+- changed: <files or none>
+- validated: <commands + outcome>
+- failed: <remaining failure or none>
+- blocked: <blocker or none>
+
+### Notes
+- <durable context>
+WORKPAD
+
+bd comments add <id> -f /tmp/workpad.md
+````
+
+### update workpad
+
+do not try to edit an old comment. add a new full workpad comment with the complete updated body.
+
+````bash
+cat > /tmp/workpad.md <<'WORKPAD'
+...full updated workpad body...
+WORKPAD
+
+bd comments add <id> -f /tmp/workpad.md
+````
+
+### rules
+
+- treat the latest `## Plot Workpad` comment as canonical
+- never rely on older workpad comments once a newer one exists
+- update the workpad after every meaningful milestone
+- never leave completed items unchecked
+- include workspace id and short sha at top: `<workspace-id>@<short-sha>`
+- keep the full workpad body in each update so the latest comment is self-contained
+
+## workpad template
+
+````markdown
+## Plot Workpad
+
+```text
+<workspace-id>@<short-sha>
+```
+
+### Plan
+- [ ] 1. Parent task
+  - [ ] 1.1 Child task
+- [ ] 2. Parent task
+
+### Acceptance Criteria
+- [ ] Criterion 1
+- [ ] Criterion 2
+
+### Validation
+- [ ] targeted tests: `<command>`
+
+### Latest Attempt Summary
+- changed: <files or none>
+- validated: <commands + outcome>
+- failed: <remaining failure or none>
+- blocked: <blocker or none>
+
+### Notes
+- <short durable context>
+
+````
+
+## issue queries
+
+```bash
+# full issue details
+bd show <id> --json
+
+# all comments (for workpad lookup)
+bd comments <id> --json
+
+# list by status
+bd list --status open --json
+bd list --status in_progress --json
+bd list --status blocked --json
+
+# list by label
+bd list --label plot:rework --json
+bd list --label plot:merging --json
+
+# ready work: open + no blockers
+bd ready --json
+
+# complex filters
+bd query "status=open AND priority<=1" --json
+bd query "label=plot:rework" --json
+
+# text search
+bd search "keyword" --json
+
+# dependencies
+bd dep list <id>
+```
+
+## out-of-scope issue creation
+
+if you discover unrelated work, file a separate beads issue instead of expanding scope:
+
+```bash
+bd create "discovered: <title>" -t task -p 2 -d "<description>"
+```
+
+keep the new issue narrow and factual. reference the triggering issue in the description when useful.

package/bin/tracker/github/skills/plot-github-tracker/SKILL.md

@@ -0,0 +1,162 @@
+---
+name: plot-github-tracker
+description: "github issue state management for plot orchestration. state transitions via labels, workpad comment lifecycle, and issue/PR linkage. use when moving issues between states, creating/updating workpad comments, or linking PRs to issues."
+---
+
+# plot-github-tracker
+
+manages issue state and progress tracking for the plot orchestrator via GitHub labels and comments.
+
+use `gh` CLI for all GitHub operations. `$GITHUB_REPO` must be set to `owner/repo`.
+
+## state transitions
+
+issue state is determined by labels. plot only routes issues that have an explicit `plot:*` state label. unlabeled issues are ignored.
+
+transition by removing the previous `plot:*` label and adding the new one:
+
+```bash
+# todo -> in-progress
+gh issue edit <number>   --repo "$GITHUB_REPO"   --remove-label "plot:todo"   --add-label "plot:in-progress"
+
+# in-progress -> human-review
+gh issue edit <number>   --repo "$GITHUB_REPO"   --remove-label "plot:in-progress"   --add-label "plot:human-review"
+
+# rework -> human-review
+gh issue edit <number>   --repo "$GITHUB_REPO"   --remove-label "plot:rework"   --add-label "plot:human-review"
+
+# merging -> done, then close
+gh issue edit <number>   --repo "$GITHUB_REPO"   --remove-label "plot:merging"   --add-label "plot:done"
+gh issue close <number> --repo "$GITHUB_REPO"
+```
+
+if you need to move a terminal issue back into active work, reopen first, then swap labels:
+
+```bash
+gh issue reopen <number> --repo "$GITHUB_REPO"
+gh issue edit <number>   --repo "$GITHUB_REPO"   --remove-label "plot:done"   --add-label "plot:rework"
+```
+
+## available states
+
+| label             | meaning                    | agent action                                           |
+| ----------------- | -------------------------- | ------------------------------------------------------ |
+| plot:todo         | queued for work            | move to plot:in-progress, start execution              |
+| plot:in-progress  | implementation underway    | implement, verify, open PR, move to plot:human-review |
+| plot:human-review | PR open, waiting on human  | do nothing, wait                                       |
+| plot:rework       | reviewer requested changes | read feedback, fix, move to plot:human-review         |
+| plot:merging      | human approved             | merge PR, move to plot:done                           |
+| plot:done         | terminal                   | stop                                                   |
+
+## workpad comment
+
+a single persistent GitHub issue comment used as a living scratchpad across agent sessions.
+
+### find or create
+
+```bash
+# search for existing workpad
+gh api repos/$GITHUB_REPO/issues/<number>/comments --jq '.[] | select(.body | startswith("## Plot Workpad")) | .id' | head -1
+```
+
+if not found, create it:
+
+```bash
+gh api repos/$GITHUB_REPO/issues/<number>/comments   -X POST   -f body='## Plot Workpad
+
+### Plan
+
+- [ ] 1. <task>
+
+### Acceptance Criteria
+
+- [ ] <criterion>
+
+### Validation
+
+- [ ] <test command>
+
+### Latest Attempt Summary
+
+- changed: <files or none>
+- validated: <commands + outcome>
+- failed: <remaining failure or none>
+- blocked: <blocker or none>
+
+### Notes
+
+- <durable context>'
+```
+
+### update existing
+
+replace the full workpad body in place:
+
+```bash
+gh api repos/$GITHUB_REPO/issues/comments/<id>   -X PATCH   -f body='...full updated workpad body...'
+```
+
+### rules
+
+- exactly one workpad comment per issue, identified by `## Plot Workpad` header
+- reuse existing comment on continuation runs — do not create duplicates
+- update the workpad after every meaningful milestone
+- never leave completed items unchecked
+- include workspace id and short sha at top: `<workspace-id>@<short-sha>`
+
+## workpad template
+
+````markdown
+## Plot Workpad
+
+```text
+<workspace-id>@<short-sha>
+```
+
+### Plan
+
+- [ ] 1. Parent task
+  - [ ] 1.1 Child task
+- [ ] 2. Parent task
+
+### Acceptance Criteria
+
+- [ ] Criterion 1
+- [ ] Criterion 2
+
+### Validation
+
+- [ ] targeted tests: `<command>`
+
+### Latest Attempt Summary
+
+- changed: <files or none>
+- validated: <commands + outcome>
+- failed: <remaining failure or none>
+- blocked: <blocker or none>
+
+### Notes
+
+- <short durable context>
+
+````
+
+## issue queries
+
+```bash
+# view issue details
+gh issue view <number> --repo "$GITHUB_REPO" --json title,body,state,labels,comments
+
+# list open issues by label
+gh issue list --repo "$GITHUB_REPO" --label "plot:in-progress" --state open
+```
+
+## PR linkage
+
+after creating or updating a PR, ensure the PR body includes `Resolves #<number>`. that is the durable issue/PR link.
+
+if you need to post the PR URL back to the issue, add a normal issue comment:
+
+```bash
+gh api repos/$GITHUB_REPO/issues/<number>/comments   -X POST   -f body='linked PR: <pr-url>'
+```

package/bin/tui-worker.js

@@ -290968,7 +290968,64 @@ async function createBeadsOps(config2) {
     createdAt: bd.created_at || null,
     updatedAt: bd.updated_at || null
   });
-  const fetchRunContext = async (issueId, _state) => {
+  const runGh = async (args2) => {
+    return await execFileAsync2("gh", args2, {
+      maxBuffer: 50 * 1024 * 1024,
+      cwd: workspaceRoot
+    });
+  };
+  const fetchPrReviews = async (issueId) => {
+    const repoArgs = config2.githubRepo ? ["--repo", config2.githubRepo] : [];
+    try {
+      const prSearchResult = await runGh([
+        "pr",
+        "list",
+        ...repoArgs,
+        "--state",
+        "open",
+        "--json",
+        "number,headRefName,body",
+        "--limit",
+        "50"
+      ]);
+      const prs = JSON.parse(prSearchResult.stdout);
+      const linkedPr = prs.find((pr) => pr.body?.includes(issueId));
+      if (!linkedPr)
+        return null;
+      const reviewResult = await runGh([
+        "pr",
+        "view",
+        String(linkedPr.number),
+        ...repoArgs,
+        "--json",
+        "reviews,comments"
+      ]);
+      const prData = JSON.parse(reviewResult.stdout);
+      const parts2 = [];
+      if (prData.reviews?.length) {
+        for (const r of prData.reviews) {
+          if (r.body)
+            parts2.push(`**${r.author.login}** (${r.state}):
+${r.body}`);
+        }
+      }
+      if (prData.comments?.length) {
+        for (const c of prData.comments) {
+          if (c.body)
+            parts2.push(`**${c.author.login}**:
+${c.body}`);
+        }
+      }
+      return parts2.length > 0 ? parts2.join(`
+
+---
+
+`) : null;
+    } catch {
+      return null;
+    }
+  };
+  const fetchRunContext = async (issueId, state) => {
     let comments = [];
     try {
       const issue2 = await viewIssue(issueId);
@@ -290980,7 +291037,12 @@ async function createBeadsOps(config2) {
     const workpadComment = comments.find((c) => c.text.startsWith("## Plot Workpad"));
     if (workpadComment)
       workpad = workpadComment.text;
-    return buildRunContext({ workpad, reviewFeedback: null });
+    let reviews = null;
+    const normalizedDispatch = config2.dispatchStates.map(normalizeState2);
+    if (normalizedDispatch.includes(normalizeState2(state))) {
+      reviews = await fetchPrReviews(issueId);
+    }
+    return buildRunContext({ workpad, reviewFeedback: reviews });
   };
   return {
     runBd,
@@ -290999,6 +291061,7 @@ var plugin2 = {
     return {
       kind: String(raw2.kind),
       beadsDir: typeof raw2["beadsDir"] === "string" ? raw2["beadsDir"] : undefined,
+      githubRepo: typeof raw2["githubRepo"] === "string" ? raw2["githubRepo"] : undefined,
       dispatchStates: Array.isArray(raw2["dispatchStates"]) ? raw2["dispatchStates"] : undefined,
       parkedStates: Array.isArray(raw2["parkedStates"]) ? raw2["parkedStates"] : undefined,
       terminalStates: Array.isArray(raw2["terminalStates"]) ? raw2["terminalStates"] : undefined
@@ -291012,11 +291075,13 @@ var plugin2 = {
     ].filter((s, i, arr) => arr.indexOf(s) === i);
     const ops = await createBeadsOps({
       beadsDir: config2.beadsDir,
+      githubRepo: config2.githubRepo,
+      dispatchStates: config2.dispatchStates ?? [],
       allStates
     });
     return {
       async fetchCandidateIssues(dispatchStates) {
-        const bdIssues = await ops.listOpenIssues();
+        const bdIssues = await ops.listAllIssues();
         const issues = bdIssues.map(ops.mapIssue);
         const normalized = new Set(dispatchStates.map(normalizeState2));
         return issues.filter((i) => normalized.has(normalizeState2(i.state)));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@plot-ai/darwin-arm64",
-  "version": "0.0.3",
+  "version": "0.0.4",
   "type": "module",
   "license": "MIT",
   "description": "orchestrate coding agents against an issue tracker",