agent-worktree skill — portable package

A drop-in /agent-worktree Cursor IDE skill + supporting pipeline for running an autonomous multi-agent PR pipeline against any git/GitHub repo.

The pipeline runs N cursor-agent workers in parallel inside git worktrees, plans ⌈target_commits × 1.3⌉ tasks at startup, opens PRs with auto-merge SQUASH, re-fills the queue with LLM helpers when it runs low, and writes 20-min progress reports to a ledger.

Originally built and battle-tested in unitree_sdk_jt (a SLAM C++ fork). This package strips out the project-specific bits and makes everything configurable.

---

Contents

agent-worktree-skill-pkg/
├── install.sh                          # one-command installer
├── README.md                           # this file
└── skill/
    ├── .cursor/
    │   ├── commands/agent-worktree.md  # slash command entry
    │   └── skills/agent-worktree/
    │       ├── SKILL.md                # main skill prompt
    │       ├── parse_requirement.md    # natural-language → config.json
    │       ├── decompose_tasks.md      # decomposition prompt
    │       └── role_addons/
    │           └── _template.md        # copy + fill per role
    └── pipeline/
        ├── bin/                        # supervisor + helpers + user-facing CLI
        ├── prompts/                    # supervisor + worker + helper prompts
        ├── examples/                   # config.example.json, queue.example.json
        ├── state/                      # gitignored runtime state (status.json,
        │                               # plan-ledger.md, inflight/*, completed/*, ...)
        ├── logs/                       # gitignored
        └── systemd/                    # optional user unit (linger setup)

---

Requirements

• Linux or macOS (uses bash, setsid, nohup, GNU coreutils-ish tools)
• Cursor IDE with cursor-agent CLI on PATH (verified: cursor-agent --version)
• gh CLI logged in (gh auth status shows your GitHub login)
• git with the target repo cloned and remote pointing at the GitHub repo
• jq (the supervisor uses it heavily)
• The target GitHub repo must allow:
  • Pull requests via REST API (you must have push access)
  • Auto-merge SQUASH (gh api repos/$repo --jq .allow_auto_merge returns true)
  • Branch protection on the base branch with at least one required status check

---

Install

cd /path/to/agent-worktree-skill-pkg
bash install.sh --target /path/to/your-repo
# or pass everything explicitly:
bash install.sh \
    --target /path/to/your-repo \
    --repo-slug owner/name \
    --committer-name your-gh-login \
    --committer-email '12345+your-gh-login@users.noreply.github.com' \
    --verify-cmd 'make test' \
    --base-branch main \
    --worktree-name your-repo-dir-name

install.sh reads the values it can infer from gh api user / gh repo view / standard build files, and asks for confirmation before writing.

After install:

your-repo/
├── .cursor/skills/agent-worktree/       (NEW)
├── .cursor/commands/agent-worktree.md   (NEW)
├── .gitignore                           (appended)
└── pipeline/                            (NEW; pipeline/state and pipeline/logs gitignored)

You should git add and commit the skill files (NOT pipeline/state/* or pipeline/logs/* — they're runtime state).

---

Quick start

1. Make sure the verify command actually passes on a clean checkout:

   <whatever you passed as --verify-cmd>

   If it doesn't, the workers will be stuck in retry loops.

2. (Optional) Edit pipeline/state/config.json (you can copy pipeline/examples/config.example.json as a starting point) to set forbidden_files, project_hard_noedit_fields, project_lang_constraints, project_layout_hint for your repo.

3. (Optional) Copy .cursor/skills/agent-worktree/role_addons/_template.md to <role-name>.md for each role you plan to use in requirements (e.g. frontend.md, backend.md, db.md). Fill the four sections. If you don't, roles still work, just without the per-role guidance addon.

4. Open Cursor IDE in the repo and type:

   /agent-worktree your one-line requirement
   

   Examples:

   /agent-worktree add unit-test coverage for src/cli, target 50 commits
   

   /agent-worktree split the payments module, 3 agents: api, db, tests
   

   The skill parses worker_count / worker_roles / stop_condition from the requirement, writes pipeline/state/config.json, asks for confirmation, then spawns the supervisor in the background via nohup setsid.

5. Monitor:

   /agent-worktree status                                # one-shot summary
   /agent-worktree progress                              # trigger fresh LLM summary
   bash pipeline/bin/pipeline-tail                       # tail -f orchestrator log
   open file://$(pwd)/pipeline/state/status.html         # browser dashboard
   cat pipeline/state/progress-latest.txt                # last 20-min report

6. Stop:

   /agent-worktree stop
   

   Or directly: bash pipeline/bin/pipeline-stop (graceful, waits 5min for drain) bash pipeline/bin/pipeline-stop --force (immediate kill).

---

What it automates (v4 supervisor)

Trigger	Auto-action
pipeline-start invoked, no queue.json	_helper-decompose.sh plans ⌈target × 1.3⌉ tasks in batches
fresh start	seeds pipeline/state/plan-ledger.md
any worker state transition	ledger_append writes a timestamped line
20 min elapsed OR ping.flag touched	stage 6 LLM progress summary
queue + inflight + in_pr < 5	stage 4 LLM refill with full history context
_supervisor.sh mtime changed on disk	exec re-launch with same config
PR is BEHIND main	auto gh api .../update-branch (90s throttle)
worker heartbeat stale > 600s	SIGKILL + re-queue with retry++
stop_condition met + inflight+in_pr drained	clean exit

What still needs a human:

• git push --force (never)
• Editing ~/.gitconfig / ~/.ssh/config (never)
• GitHub repo Settings (auto-merge / branch protection / Codex App / secrets)
• Hardware / production / external-service smoke
• Brand-new failure modes not in the supervisor's stage-1-to-6

---

Limitations + caveats

• Token cost: each refill or progress report is one cursor-agent invocation (~3K-10K tokens). 24h with default config: roughly $5-25 in API costs on top of Cursor Pro / Pro+ subscription.

• GitHub auto-merge race: with default settings, CI sometimes finishes faster than Codex review. The codex-review-then-merge guarantee is on a best-effort basis. To make it stricter, add sleep 90 between gh api .../pulls -X POST and gh api graphql ... enablePullRequestAutoMerge in pipeline/prompts/task_template.md.

• Long-running ledger: at 100+ tasks the ledger grows to ~1000 lines. Refill caps plan_ledger_tail at 400 lines by default (configurable). Progress report sees last 200 lines.

• Cursor-agent model list changes: this package defaults to claude-4.6-sonnet-medium-thinking (worker + helper). If your cursor-agent version drops that model, edit worker_model and helper_model in config.json. List available with cursor-agent --list-models.

• Single-node only: all workers run on the same machine, sharing the same ~/.cursor/worktrees/<repo>/ and one cursor-agent Pro/Pro+ subscription.

• Branch protection sensitivity: if the base branch has many required checks, PRs will spend most of their time waiting on CI rather than worker turnaround. Tune worker_count accordingly.

---

How it differs from the upstream unitree_sdk_jt source

• All hardcoded references to the unitree SDK (unitree_slam/, keyDemo3.cpp, climb_control, etc.) have been stripped or generalized
• 5 project-specific role_addons (mapping / navigation / perception / slam / view) replaced by one _template.md
• forbidden_files and other project-specific behavior moved from hardcoded shell logic to pipeline/state/config.json reads
• install.sh substitutes 7 placeholders at install time, the rest (4 project hints) are read at supervisor runtime

---

Troubleshooting

Symptom	First check
cursor-agent: command not found	install / log in Cursor first
gh: command not found or gh auth status failing	install + gh auth login
jq: command not found	install via package manager (apt install jq / brew install jq)
pipeline-start exits 4 (no queue.json)	decompose helper returned empty; check pipeline/logs/decompose-*.log
Supervisor PID exists but status.json is stale > 5min	LLM helper call hung — pkill -f cursor-agent.*--print will unblock
bash pipeline/bin/pipeline-stop takes 5min	normal graceful drain; use --force to skip
Workers all fail with same error	run the --verify-cmd manually to confirm baseline is green

For deeper issues, the original repo's playbook (this package's ancestor) has 12 documented failure-mode classes with fixes: search GitHub for agent-worktree-playbook.md.

---

License

MIT (same as the upstream unitree_sdk_jt fork). See LICENSE in the source repo.