autopilot-code 0.0.4

package/.autopilot/autopilot.json

@@ -0,0 +1,15 @@
+{
+  "enabled": true,
+  "repo": "bakkensoftware/autopilot",
+  "agent": "opencode",
+  "issueLabels": {
+    "queue": ["autopilot:todo"],
+    "blocked": "autopilot:blocked",
+    "inProgress": "autopilot:in-progress",
+    "done": "autopilot:done"
+  },
+  "priorityLabels": ["p0", "p1", "p2"],
+  "maxParallel": 1,
+  "branchPrefix": "autopilot/",
+  "allowedBaseBranch": "main"
+}

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Bakken Software
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,119 @@
+# autopilot
+
+Repo-issue–driven autopilot runner.
+
+## What it is
+Autopilot is a **GitHub-issue–driven** automation loop:
+
+- repos **opt in** by committing `.autopilot/autopilot.json`
+- work lives in **GitHub Issues**
+- the runner advances issues through a **label-based workflow**
+- the runner is designed to determine “is work still happening?” using **durable artifacts** (GitHub + repo files), **not process inspection** (`ps`, PID checks, etc.)
+
+## Repo opt-in
+A repo is considered autopilot-enabled when it contains:
+
+- `.autopilot/autopilot.json` with `enabled: true`
+
+Example:
+
+```json
+{
+  "enabled": true,
+  "repo": "bakkensoftware/autopilot",
+  "agent": "opencode",
+  "issueLabels": {
+    "queue": ["autopilot:todo"],
+    "blocked": "autopilot:blocked",
+    "inProgress": "autopilot:in-progress",
+    "done": "autopilot:done"
+  },
+  "priorityLabels": ["p0", "p1", "p2"],
+  "maxParallel": 1,
+  "heartbeatMaxAgeSecs": 3600,
+  "branchPrefix": "autopilot/",
+  "allowedBaseBranch": "main"
+}
+```
+
+Notes:
+- `repo` must be the GitHub `owner/name`.
+- `agent` (optional, default `"none"`): set to `"opencode"` to enable OpenCode integration after claiming issues.
+- `heartbeatMaxAgeSecs` controls how long an in-progress issue can go without a heartbeat before it's considered stale.
+
+## Workflow (labels)
+Autopilot uses labels as a kanban state machine:
+
+- `autopilot:backlog` — captured, not ready
+- `autopilot:todo` — ready to be picked up by the runner
+- `autopilot:in-progress` — claimed by autopilot
+- `autopilot:blocked` — needs human input or missing/stale heartbeat
+- `autopilot:done` — completed
+
+Optional priority labels:
+- `p0`, `p1`, `p2` (lower number = higher priority)
+
+## How claiming works
+When the runner finds a candidate issue (typically `autopilot:todo`):
+
+1. It applies `autopilot:in-progress`
+2. It removes the queue label(s) (e.g. `autopilot:todo`)
+3. It leaves a comment indicating the claim time and next step
+
+## Durable tracking (no process inspection)
+This runner intentionally **does not** check local processes to decide if work is ongoing.
+
+Instead it uses durable artifacts:
+
+- **GitHub:** issue labels + issue comments + (future) PR presence/status
+- **Repo file heartbeat:** `.autopilot/state.json`
+
+The runner writes/updates `.autopilot/state.json` like:
+
+```json
+{
+  "activeIssue": {
+    "number": 2,
+    "repo": "bakkensoftware/autopilot",
+    "updatedAt": 1738000000
+  }
+}
+```
+
+On each loop:
+- if an issue is `autopilot:in-progress` but the heartbeat is stale/missing, autopilot comments and moves it to `autopilot:blocked`.
+
+## Running locally
+### Python runner
+```bash
+python3 scripts/run_autopilot.py --root /mnt/f/Source
+```
+
+### Node CLI wrapper
+From the repo root:
+
+```bash
+npm install
+npm run build
+
+# sanity checks
+node dist/cli.js doctor
+
+# scan enabled repos without claiming
+node dist/cli.js scan --root /mnt/f/Source
+
+# claim exactly one issue + comment
+node dist/cli.js run-once --root /mnt/f/Source
+```
+
+## Roadmap
+- Spawn a coding agent (Claude Code / OpenCode) in a worktree per issue
+- Create PRs linked to issues; wait for checks to go green
+- Merge PRs automatically when mergeable + checks pass
+- Close issues + apply `autopilot:done`
+- Richer durable state:
+  - PR number / branch name / last heartbeat comment
+  - “blocked reason” codified
+
+## Config template
+See `templates/autopilot.json`.

package/dist/cli.js

@@ -0,0 +1,58 @@
+#!/usr/bin/env node
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const commander_1 = require("commander");
+const node_child_process_1 = require("node:child_process");
+const node_path_1 = __importDefault(require("node:path"));
+function run(cmd, args) {
+    const res = (0, node_child_process_1.spawnSync)(cmd, args, { stdio: "inherit" });
+    if (res.error)
+        throw res.error;
+    if (typeof res.status === "number" && res.status !== 0)
+        process.exit(res.status);
+}
+function check(cmd, args, label) {
+    const res = (0, node_child_process_1.spawnSync)(cmd, args, { stdio: "inherit" });
+    if (res.error) {
+        console.error(`\n${label}: failed to run: ${res.error.message}`);
+        process.exit(1);
+    }
+    if (typeof res.status === "number" && res.status !== 0) {
+        console.error(`\n${label}: returned exit code ${res.status}`);
+        process.exit(res.status);
+    }
+}
+const repoRoot = node_path_1.default.resolve(__dirname, "..");
+const runnerPath = node_path_1.default.join(repoRoot, "scripts", "run_autopilot.py");
+const program = new commander_1.Command();
+program
+    .name("autopilot")
+    .description("Repo-issue–driven autopilot runner (CLI wrapper)")
+    .version("0.0.0");
+program
+    .command("doctor")
+    .description("Check local prerequisites (gh auth, python3)")
+    .action(() => {
+    check("gh", ["--version"], "gh");
+    check("gh", ["auth", "status"], "gh auth");
+    check("python3", ["--version"], "python3");
+    console.log("\nOK");
+});
+program
+    .command("scan")
+    .description("Discover autopilot-enabled repos + show next issue candidate (dry-run)")
+    .requiredOption("--root <path>", "Root folder that contains git repos")
+    .action((opts) => {
+    run("python3", [runnerPath, "--root", opts.root, "--dry-run"]);
+});
+program
+    .command("run-once")
+    .description("Claim exactly one issue and post a progress comment")
+    .requiredOption("--root <path>", "Root folder that contains git repos")
+    .action((opts) => {
+    run("python3", [runnerPath, "--root", opts.root]);
+});
+program.parse();

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "autopilot-code",
+  "version": "0.0.4",
+  "private": false,
+  "description": "Repo-issue–driven autopilot runner",
+  "license": "MIT",
+  "bin": {
+    "autopilot": "dist/cli.js"
+  },
+  "main": "dist/cli.js",
+  "files": [
+    "dist/",
+    "scripts/",
+    "templates/",
+    ".autopilot/"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "lint": "node -e \"console.log('lint: (not configured)')\"",
+    "test": "node -e \"console.log('test: (not configured)')\"",
+    "release": "changeset publish",
+    "version-packages": "changeset version"
+  },
+  "dependencies": {
+    "commander": "^12.1.0"
+  },
+  "devDependencies": {
+    "@changesets/cli": "^2.29.8",
+    "@types/node": "^22.10.2",
+    "typescript": "^5.7.2"
+  }
+}

package/scripts/run_autopilot.py

@@ -0,0 +1,293 @@
+#!/usr/bin/env python3
+"""Issue-driven autopilot runner.
+
+MVP: discovery + issue queue + claim + notify + durable state tracking.
+Later: spawn coding agent, open PR, merge, close issue.
+
+Design constraint: the runner must NOT rely on local process inspection (ps, pid files).
+It should infer progress using durable artifacts:
+- GitHub (labels/comments/PRs)
+- repo files under .autopilot/ (local state)
+
+Designed to run from a cron/loop.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import subprocess
+import sys
+import time
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+STATE_DIR = ".autopilot"
+STATE_FILE = "state.json"
+DEFAULT_HEARTBEAT_MAX_AGE_SECS = 60 * 60  # 1h
+
+
+def sh(cmd: list[str], cwd: Path | None = None, check: bool = True) -> str:
+    p = subprocess.run(cmd, cwd=str(cwd) if cwd else None, text=True, stdout=subprocess.PIPE, stderr=subprocess.STDOUT)
+    if check and p.returncode != 0:
+        raise RuntimeError(f"command failed ({p.returncode}): {' '.join(cmd)}\n{p.stdout}")
+    return p.stdout
+
+
+@dataclass
+class RepoConfig:
+    root: Path
+    repo: str
+    enabled: bool
+    queue_labels: list[str]
+    label_in_progress: str
+    label_blocked: str
+    label_done: str
+    priority_labels: list[str]
+    max_parallel: int
+    heartbeat_max_age_secs: int
+    agent: str
+
+
+def load_config(repo_root: Path) -> RepoConfig | None:
+    cfg_path = repo_root / ".autopilot" / "autopilot.json"
+    if not cfg_path.exists():
+        return None
+    data = json.loads(cfg_path.read_text(encoding="utf-8"))
+    if not data.get("enabled", False):
+        return None
+
+    labels = data.get("issueLabels", {})
+    queue = labels.get("queue", ["autopilot:todo"])
+
+    return RepoConfig(
+        root=repo_root,
+        repo=data["repo"],
+        enabled=True,
+        queue_labels=queue,
+        label_in_progress=labels.get("inProgress", "autopilot:in-progress"),
+        label_blocked=labels.get("blocked", "autopilot:blocked"),
+        label_done=labels.get("done", "autopilot:done"),
+        priority_labels=data.get("priorityLabels", ["p0", "p1", "p2"]),
+        max_parallel=int(data.get("maxParallel", 2)),
+        heartbeat_max_age_secs=int(data.get("heartbeatMaxAgeSecs", DEFAULT_HEARTBEAT_MAX_AGE_SECS)),
+        agent=data.get("agent", "none"),
+    )
+
+
+def discover_repos(root: Path) -> list[RepoConfig]:
+    out: list[RepoConfig] = []
+    for child in root.iterdir():
+        if not child.is_dir():
+            continue
+        if (child / ".git").exists() and (child / ".autopilot" / "autopilot.json").exists():
+            cfg = load_config(child)
+            if cfg:
+                out.append(cfg)
+    return out
+
+
+def list_candidate_issues(cfg: RepoConfig, limit: int = 10) -> list[dict[str, Any]]:
+    # Sort by created date asc; prioritize p0/p1/p2 by label presence.
+    q = " ".join([f"label:{l}" for l in cfg.queue_labels])
+    cmd = [
+        "gh",
+        "issue",
+        "list",
+        "--repo",
+        cfg.repo,
+        "--limit",
+        str(limit),
+        "--search",
+        f"is:open {q}",
+        "--json",
+        "number,title,labels,updatedAt,createdAt,url",
+    ]
+    raw = sh(cmd)
+    issues = json.loads(raw)
+
+    def pri_rank(it: dict[str, Any]) -> int:
+        labs = {l["name"] for l in it.get("labels", [])}
+        for i, p in enumerate(cfg.priority_labels):
+            if p in labs:
+                return i
+        return 999
+
+    issues.sort(key=lambda x: (pri_rank(x), x.get("createdAt", "")))
+    return issues
+
+
+def _state_path(repo_root: Path) -> Path:
+    return repo_root / STATE_DIR / STATE_FILE
+
+
+def load_state(repo_root: Path) -> dict[str, Any]:
+    p = _state_path(repo_root)
+    if not p.exists():
+        return {}
+    try:
+        return json.loads(p.read_text(encoding="utf-8"))
+    except Exception:
+        return {}
+
+
+def write_state(repo_root: Path, state: dict[str, Any]) -> None:
+    d = repo_root / STATE_DIR
+    d.mkdir(parents=True, exist_ok=True)
+    p = d / STATE_FILE
+    p.write_text(json.dumps(state, indent=2, sort_keys=True) + "\n", encoding="utf-8")
+
+
+def touch_heartbeat(cfg: RepoConfig, issue_number: int) -> None:
+    """Update durable local heartbeat state for the repo.
+
+    This is the mechanism we use to infer liveness WITHOUT process inspection.
+    """
+    state = load_state(cfg.root)
+    now = int(time.time())
+    state["activeIssue"] = {
+        "number": issue_number,
+        "updatedAt": now,
+        "repo": cfg.repo,
+    }
+    write_state(cfg.root, state)
+
+
+def is_heartbeat_fresh(cfg: RepoConfig, issue_number: int) -> bool:
+    state = load_state(cfg.root)
+    active = state.get("activeIssue")
+    if not isinstance(active, dict):
+        return False
+    if int(active.get("number", -1)) != int(issue_number):
+        return False
+    updated = int(active.get("updatedAt", 0))
+    age = int(time.time()) - updated
+    return age <= cfg.heartbeat_max_age_secs
+
+
+def claim_issue(cfg: RepoConfig, issue: dict[str, Any], note: str) -> None:
+    num = int(issue["number"])
+    sh(
+        [
+            "gh",
+            "issue",
+            "edit",
+            str(num),
+            "--repo",
+            cfg.repo,
+            "--add-label",
+            cfg.label_in_progress,
+            "--remove-label",
+            ",".join(cfg.queue_labels),
+        ]
+    )
+    sh(["gh", "issue", "comment", str(num), "--repo", cfg.repo, "--body", note])
+    touch_heartbeat(cfg, num)
+
+
+def list_in_progress_issues(cfg: RepoConfig, limit: int = 20) -> list[dict[str, Any]]:
+    cmd = [
+        "gh",
+        "issue",
+        "list",
+        "--repo",
+        cfg.repo,
+        "--limit",
+        str(limit),
+        "--search",
+        f"is:open label:{cfg.label_in_progress}",
+        "--json",
+        "number,title,labels,updatedAt,createdAt,url",
+    ]
+    raw = sh(cmd)
+    return json.loads(raw)
+
+
+def maybe_mark_blocked(cfg: RepoConfig, issue: dict[str, Any]) -> None:
+    num = int(issue["number"])
+    if is_heartbeat_fresh(cfg, num):
+        return
+
+    note = (
+        "Autopilot marking this issue **blocked** because no durable heartbeat was updated "
+        f"in the last {cfg.heartbeat_max_age_secs} seconds.\n\n"
+        "This runner intentionally does **not** inspect local processes, so a fresh heartbeat "
+        "is how we infer work is ongoing.\n\n"
+        "Reply here if work is still in progress (or re-label as `autopilot:todo` to re-queue)."
+    )
+    sh(["gh", "issue", "comment", str(num), "--repo", cfg.repo, "--body", note])
+    sh(
+        [
+            "gh",
+            "issue",
+            "edit",
+            str(num),
+            "--repo",
+            cfg.repo,
+            "--add-label",
+            cfg.label_blocked,
+            "--remove-label",
+            cfg.label_in_progress,
+        ]
+    )
+
+
+def main() -> int:
+    ap = argparse.ArgumentParser()
+    ap.add_argument("--root", default="/mnt/f/Source")
+    ap.add_argument("--max-parallel", type=int, default=2)
+    ap.add_argument("--dry-run", action="store_true")
+    args = ap.parse_args()
+
+    root = Path(args.root)
+    configs = discover_repos(root)
+    if not configs:
+        print("No autopilot-enabled repos found.")
+        return 0
+
+    for cfg in configs:
+        # 1) First, check any in-progress issues and mark blocked if stale.
+        inprog = list_in_progress_issues(cfg)
+        for it in inprog:
+            # This is conservative: only mark blocked if we have no fresh local heartbeat.
+            if not args.dry_run:
+                maybe_mark_blocked(cfg, it)
+
+        # 2) If nothing is currently in progress, claim one from the queue.
+        # (We only support one active issue per repo in this MVP.)
+        if inprog:
+            continue
+
+        issues = list_candidate_issues(cfg)
+        if not issues:
+            continue
+
+        issue = issues[0]
+        msg = (
+            f"Autopilot claimed this issue at {time.strftime('%Y-%m-%d %H:%M:%S %Z')}.\n\n"
+            "Next: implement fix and open PR.\n\n"
+            "(Durable tracking: this repo will maintain `.autopilot/state.json` as a heartbeat; "
+            "the runner does not inspect processes.)"
+        )
+        print(f"[{cfg.repo}] next issue: #{issue['number']} {issue['title']}")
+        if args.dry_run:
+            continue
+        claim_issue(cfg, issue, msg)
+
+        # If agent==opencode, delegate to bash script
+        if cfg.agent == "opencode":
+            sh(
+                [
+                    "/home/kellye/clawd/repos/autopilot/scripts/run_opencode_issue.sh",
+                    str(cfg.root),
+                    str(issue["number"]),
+                ]
+            )
+
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/scripts/run_opencode_issue.sh

@@ -0,0 +1,86 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+REPO_DIR="$1"
+ISSUE_NUMBER="$2"
+
+if [[ -z "$REPO_DIR" || -z "$ISSUE_NUMBER" ]]; then
+  echo "Usage: $0 <repoDir> <issueNumber>" >&2
+  exit 1
+fi
+
+cd "$REPO_DIR"
+
+# Read repo name from config (prefer jq, fallback to python3)
+if command -v jq >/dev/null 2>&1; then
+  REPO=$(jq -r '.repo' < .autopilot/autopilot.json)
+else
+  REPO=$(python3 -c 'import json; print(json.load(open(".autopilot/autopilot.json"))["repo"])')
+fi
+
+WORKTREE="/tmp/autopilot-issue-$ISSUE_NUMBER"
+BRANCH="autopilot/issue-$ISSUE_NUMBER"
+
+echo "[run_opencode_issue.sh] repo=$REPO issue=$ISSUE_NUMBER worktree=$WORKTREE"
+
+# 1. Create or reuse git worktree from main
+if [[ -d "$WORKTREE" ]]; then
+  echo "[run_opencode_issue.sh] Reusing existing worktree: $WORKTREE"
+else
+  # If branch exists already, add worktree from that branch; otherwise create from main.
+  if git show-ref --verify --quiet "refs/heads/$BRANCH"; then
+    git worktree add "$WORKTREE" "$BRANCH"
+  else
+    git worktree add "$WORKTREE" -b "$BRANCH" main
+  fi
+fi
+
+# 2. Fetch issue title/body
+ISSUE_JSON=$(gh issue view "$ISSUE_NUMBER" --repo "$REPO" --json title,body)
+if command -v jq >/dev/null 2>&1; then
+  ISSUE_TITLE=$(echo "$ISSUE_JSON" | jq -r '.title')
+  ISSUE_BODY=$(echo "$ISSUE_JSON" | jq -r '.body')
+else
+  ISSUE_TITLE=$(python3 -c 'import json,sys; d=json.load(sys.stdin); print(d["title"])' <<<"$ISSUE_JSON")
+  ISSUE_BODY=$(python3 -c 'import json,sys; d=json.load(sys.stdin); print(d.get("body") or "")' <<<"$ISSUE_JSON")
+fi
+
+# 3. Build prompt
+PROMPT="Please implement the following GitHub issue.
+
+Issue #$ISSUE_NUMBER: $ISSUE_TITLE
+
+$ISSUE_BODY
+
+Work rules:
+- Make the necessary code changes.
+- Commit with message: \"autopilot: work for issue #$ISSUE_NUMBER\".
+- Push your changes to the remote branch $BRANCH.
+- If the issue is a simple file-addition, just do it directly (no extra refactors)."
+# 4. Run opencode inside worktree
+cd "$WORKTREE"
+opencode run "$PROMPT"
+
+# 5. Commit any changes OpenCode made
+if [[ -n "$(git status --porcelain)" ]]; then
+  git add -A
+  git commit -m "autopilot: work for issue #$ISSUE_NUMBER"
+fi
+
+# 6. Ensure branch is pushed (no-op if already up to date)
+git push -u origin "$BRANCH" || true
+
+# 7. Create PR if one doesn't already exist
+PR_URL=""
+if gh pr view --repo "$REPO" --head "$BRANCH" --json url --jq .url >/dev/null 2>&1; then
+  PR_URL=$(gh pr view --repo "$REPO" --head "$BRANCH" --json url --jq .url)
+else
+  PR_URL=$(gh pr create --repo "$REPO" --title "Autopilot: Issue #$ISSUE_NUMBER" --body "Closes #$ISSUE_NUMBER" --base main --head "$BRANCH")
+fi
+
+# 8. Comment on issue with PR URL (best-effort)
+if [[ -n "$PR_URL" ]]; then
+  gh issue comment "$ISSUE_NUMBER" --repo "$REPO" --body "Autopilot opened PR: $PR_URL" || true
+fi
+
+echo "[run_opencode_issue.sh] Done: $PR_URL"

package/templates/autopilot.json

@@ -0,0 +1,14 @@
+{
+  "enabled": true,
+  "repo": "bakkensoftware/TicketToolbox",
+  "issueLabels": {
+    "queue": ["autopilot:todo"],
+    "blocked": "autopilot:blocked",
+    "inProgress": "autopilot:in-progress",
+    "done": "autopilot:done"
+  },
+  "priorityLabels": ["p0", "p1", "p2"],
+  "maxParallel": 2,
+  "branchPrefix": "autopilot/",
+  "allowedBaseBranch": "main"
+}