From cfcde4c8a4637371c23d221c0d98f4aa5046fcf5 Mon Sep 17 00:00:00 2001 From: Shane Neuville Date: Mon, 30 Mar 2026 16:48:20 -0500 Subject: [PATCH 1/4] feat: add release-notes skill for curated changelogs and README updates Adds a new skill at .claude/skills/release-notes/SKILL.md that guides agents through generating polished, highlight-driven release notes instead of the default GitHub auto-generated PR lists. The skill covers: - Gathering changes between tags via git log and gh CLI - Categorizing commits (features, fixes, perf, mobile, multi-agent) - Writing curated highlights with user-focused language - Publishing via gh release edit - README update strategy (when and what to change) - Quick reference commands for common release tasks Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- .claude/skills/release-notes/SKILL.md | 298 ++++++++++++++++++++++++++ 1 file changed, 298 insertions(+) create mode 100644 .claude/skills/release-notes/SKILL.md diff --git a/.claude/skills/release-notes/SKILL.md b/.claude/skills/release-notes/SKILL.md new file mode 100644 index 0000000000..c3b2bd3ea2 --- /dev/null +++ b/.claude/skills/release-notes/SKILL.md @@ -0,0 +1,298 @@ +--- +name: release-notes +description: > + Generate polished release notes and update the README for PolyPilot releases. + Use when: (1) A new version tag has been pushed and needs release notes, + (2) The user asks to prepare release notes for a version, + (3) The README needs updating with new features or a "What's New" section, + (4) Preparing a release announcement or changelog entry. + Covers: commit categorization, highlight extraction, README update strategy, + GitHub Release body formatting, and the release workflow integration. +--- + +# Release Notes & README Update Skill + +## Overview + +PolyPilot releases follow semantic versioning (`v1.0.x`) with tags pushed to `main`. +The GitHub Actions workflow (`.github/workflows/build.yml`) creates releases via +`softprops/action-gh-release@v1` with `generate_release_notes: false` โ€” meaning +the release body must be explicitly provided or updated after creation. + +Currently, release notes default to GitHub's auto-generated "What's Changed" PR list, +which is noisy and hard to scan. This skill produces **curated, highlight-driven +release notes** and keeps the README current. + +--- + +## Step 1: Gather Changes Since Last Release + +```bash +# Find the previous tag +PREV_TAG=$(git tag --sort=-v:refname | head -2 | tail -1) +CURR_TAG=$(git tag --sort=-v:refname | head -1) + +# List commits between tags +git --no-pager log ${PREV_TAG}..${CURR_TAG} --oneline + +# Get full commit messages (for PR numbers and descriptions) +git --no-pager log ${PREV_TAG}..${CURR_TAG} --pretty=format:"%h %s" + +# For PRs with more detail +gh pr list --state merged --search "merged:>=$(git log -1 --format=%ci $PREV_TAG | cut -d' ' -f1)" --limit 50 --json number,title,labels,body +``` + +If preparing notes for a release that hasn't been tagged yet, compare against `HEAD`: +```bash +git --no-pager log ${PREV_TAG}..HEAD --oneline +``` + +--- + +## Step 2: Categorize Changes + +Group commits by type using conventional commit prefixes and PR content: + +### Categories (in display order) + +| Emoji | Category | Commit Prefixes | Description | +|-------|----------|----------------|-------------| +| ๐Ÿš€ | **Highlights** | (manually curated) | Top 1-3 most impactful changes โ€” the "headline" | +| โœจ | **New Features** | `feat:` | New capabilities, commands, UI elements | +| ๐Ÿ› | **Bug Fixes** | `fix:` | Corrections to existing behavior | +| โšก | **Performance** | `perf:`, `fix:` (perf-related) | Speed, memory, render improvements | +| ๐Ÿ“ฑ | **Mobile** | any mobile/bridge-related | Remote mode, bridge, mobile UI | +| ๐Ÿค– | **Multi-Agent** | orchestrat*, squad, worker | Orchestration, presets, squad teams | +| ๐Ÿ”ง | **Infrastructure** | `chore:`, `ci:`, `build:` | CI/CD, deps, tooling | +| ๐Ÿ“ | **Documentation** | `docs:` | README, docs/, skill updates | + +### Rules for Highlights + +Highlights are the **most user-visible, exciting changes**. Pick 1-3 from the full list. +Good highlights: +- New features users will immediately notice (new UI, new command, new integration) +- Major reliability improvements that fix frequent pain points +- New platform support or significant UX redesign + +Bad highlights: +- Internal refactors (even big ones) +- Test fixes +- CI/CD changes +- Minor bug fixes + +### Writing Style + +- **Active voice, present tense**: "Adds Fiesta mode for multi-machine orchestration" +- **User-focused**: Describe what users can do, not what code changed +- **Concise**: One line per item, 10-15 words max +- **Include PR numbers**: `(#123)` at end for traceability +- **Group related PRs**: If 3 PRs fix mobile streaming, combine into one line + +--- + +## Step 3: Write the Release Notes + +### Template + +```markdown +## ๐Ÿš€ Highlights + +- **[Headline feature]** โ€” one-sentence description of the most exciting change (#PR) +- **[Second highlight]** โ€” another major improvement (#PR) + +## โœจ New Features + +- Feature description in active voice (#PR) +- Another feature (#PR) + +## ๐Ÿ› Bug Fixes + +- Fix description โ€” what was broken and what works now (#PR) +- Another fix (#PR) + +## โšก Performance + +- What got faster and by how much (#PR) + +## ๐Ÿ”ง Infrastructure + +- CI/CD, build, or tooling change (#PR) + +--- + +**Full Changelog**: https://github.com/PureWeen/PolyPilot/compare/vPREV...vCURR + +**Install/Update:** +- **macOS (Homebrew):** `brew upgrade polypilot` or `brew install --cask polypilot` +- **Direct download:** See assets below +``` + +### Example (real v1.0.15 notes, rewritten) + +```markdown +## ๐Ÿš€ Highlights + +- **Fiesta Mode** โ€” Discover and orchestrate across multiple PolyPilot instances on your LAN with push-to-pair (#322) +- **Mixed-Model PR Review Squad** โ€” New preset combining Opus, Sonnet, and Codex for comprehensive code review (#451) + +## โœจ New Features + +- Surface CLI subagent and skill events directly in chat + `/agent` command (#445) +- Add sync button for mobile with diagnostic logging (#438) +- Surface auth errors with actionable guidance messages (#446) + +## ๐Ÿ› Bug Fixes + +- Fix mobile streaming: bypass render throttle, debounce broadcasts, fix stale IsProcessing (#447, #449) +- Fix cleared input fields re-filling with stale draft text on re-render (#435) +- Fix orchestrator over-dispatching workers for single-task prompts (#429) +- Forward full system environment to CLI child process (#439) +- Recover restored session model and expose gpt-5.4 (#448) +- Use `.git/info/exclude` instead of `.gitignore` for worktree exclusions (#434) +- Never abort sessions on resume โ€” removes RESUME-ABORT behavior (#452) + +## ๐Ÿ”ง Infrastructure + +- Fix structural tests to find call sites instead of method definitions (#453) +- Fix flaky ProcessHelper test catching leaked exceptions (#454) + +--- + +**Full Changelog**: https://github.com/PureWeen/PolyPilot/compare/v1.0.14...v1.0.15 +``` + +--- + +## Step 4: Publish the Release Notes + +### Option A: Update an existing GitHub Release + +```bash +# Update the release body for an existing tag +gh release edit v1.0.16 --notes-file /tmp/release-notes.md +``` + +### Option B: Create a new release (if not auto-created by CI) + +```bash +gh release create v1.0.17 \ + --title "v1.0.17" \ + --notes-file /tmp/release-notes.md \ + --draft +``` + +### Workflow + +1. Write the notes to a temp file (never commit temp files) +2. Use `gh release edit` to update the existing release +3. Verify: `gh release view v1.0.16` + +--- + +## Step 5: Update the README + +### What to Update + +The README (`README.md` at repo root) should be updated when: + +1. **New major features** are added โ€” add to the "Key Features" section +2. **Platform support changes** โ€” update the platform table +3. **Installation method changes** โ€” update Getting Started +4. **New slash commands** โ€” update the slash commands list + +### README Update Strategy + +The README is a **living document** that describes the current state of the app, +not a changelog. Don't add version-specific notes to the README body. + +**Feature section updates:** +- Add new feature subsections under "โœจ Key Features" following the existing pattern: + ```markdown + ### ๐ŸŽ‰ Feature Name + One-paragraph description of what it does and why it matters. + ``` +- Remove or update features that have been significantly reworked +- Keep the order: most impressive/visible features first + +**What NOT to put in README:** +- Version-specific changelog (that goes in GitHub Releases) +- "What's New in v1.0.x" sections (gets stale quickly) +- Dates or timestamps + +### Current README Structure (preserve this) + +``` +1. Logo + title + tagline +2. "What is PolyPilot?" โ€” overview paragraph +3. "Why PolyPilot?" โ€” bullet list of value props +4. "Key Features" โ€” detailed feature descriptions (this is where new features go) +5. "Iterating on PolyPilot" โ€” self-building workflow +6. "Supported Platforms" โ€” platform table +7. "Getting Started" โ€” install + build instructions +8. "Testing" โ€” test overview +9. "Remote Access via DevTunnel" โ€” mobile setup +10. Footer +``` + +--- + +## Step 6: Verify + +After updating: + +```bash +# Verify release notes look right +gh release view $CURR_TAG + +# Verify README renders correctly (check for broken markdown) +# Look for: unclosed code blocks, broken links, missing images +cat README.md | head -5 # should start with

+ +# Ensure no temp files are left +git status --short +``` + +--- + +## Automation Integration + +The release workflow in `.github/workflows/build.yml` (line ~717) uses: +```yaml +- name: Create Release + uses: softprops/action-gh-release@v1 + with: + generate_release_notes: false + draft: false +``` + +To integrate automated release notes, the workflow could be updated to: +1. Add a step before `Create Release` that generates the notes body +2. Pass the body to the `softprops/action-gh-release` action via the `body` or `body_path` input +3. This could use a script that calls `gh api` to get merged PRs and formats them + +However, the **recommended approach** is to run this skill manually before or after +tagging a release. Curated notes are always better than fully automated ones. + +--- + +## Quick Reference Commands + +```bash +# List recent tags +git tag --sort=-v:refname | head -5 + +# Commits since last tag +git --no-pager log $(git tag --sort=-v:refname | head -1)..HEAD --oneline + +# Merged PRs since a date +gh pr list --state merged --search "merged:>=2026-03-25" --limit 30 + +# Update release notes +gh release edit v1.0.16 --notes-file /tmp/release-notes.md + +# View current release notes +gh release view v1.0.16 + +# README preview (if you have grip installed) +# grip README.md +``` From 6ecf7e866c5d1f90f42c5458321b5c7b5f7ebcc2 Mon Sep 17 00:00:00 2001 From: Shane Neuville Date: Mon, 30 Mar 2026 16:52:49 -0500 Subject: [PATCH 2/4] docs: update README with recent feature additions - Update PR Review Squad description to reflect mixed-model architecture (Opus workers dispatching Opus + Sonnet + Codex sub-agents) - Update Fiesta Mode to mention pairing string and push-to-pair - Add /agent to slash commands list - Add new 'CLI Agent & Skill Visibility' feature section Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- README.md | 9 ++++++--- 1 file changed, 6 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index bf1338a9cc..fcfda8c325 100644 --- a/README.md +++ b/README.md @@ -60,7 +60,7 @@ Point each agent at a different repo or directory. Native folder pickers on macO Clone repositories, create branches and worktrees, and launch sessions โ€” all from the sidebar. **Quick Branch + Session** creates a new branch and session in one click. **Named Branch + Session** lets you specify a branch name or PR number (`#123`). Worktrees are tracked, linked to sessions, and cleaned up automatically when sessions close. ### ๐Ÿค– Multi-Agent Presets & Squad Teams -Launch pre-configured teams with one click. Built-in presets like **PR Review Squad** spin up an orchestrator plus multiple workers, each with their own model and role. Auto-discovers `.squad` and `.ai-team` directories in your repos for custom team definitions with agent charters and routing configs. +Launch pre-configured teams with one click. Built-in presets like **PR Review Squad** spin up an orchestrator plus specialized workers โ€” each internally dispatching parallel sub-agent reviews across multiple models (Opus, Sonnet, Codex) and synthesizing consensus reports. Auto-discovers `.squad` and `.ai-team` directories in your repos for custom team definitions with agent charters and routing configs. ### ๐Ÿ”€ Worktree Strategies Control how multi-agent teams share code: @@ -72,10 +72,13 @@ Control how multi-agent teams share code: Groups, pinning, and multiple sort modes (Last Active, Created, Aโ€“Z, Manual) let you manage large fleets of agents without losing track. Collapsible groups keep things tidy. ### ๐ŸŽ‰ Fiesta Mode โ€” Multi-Machine Orchestration -Discover and link other PolyPilot instances on your LAN. Start a "Fiesta" to fan out work to linked worker machines via `@mention` routing. Workers are discovered automatically and linked in Settings. Use `@worker-name` in your prompts to dispatch tasks to specific machines. +Discover and link other PolyPilot instances on your LAN. Start a "Fiesta" to fan out work to linked worker machines via `@mention` routing. Workers are discovered automatically, or pair instantly with a compact pairing string or push-to-pair button in Settings. Use `@worker-name` in your prompts to dispatch tasks to specific machines. ### โŒจ๏ธ Slash Commands -Built-in slash commands give you quick control without leaving the chat: `/help`, `/clear`, `/version`, `/compact`, `/new`, `/sessions`, `/rename`, `/diff`, `/status`, `/mcp`, `/plugin`. +Built-in slash commands give you quick control without leaving the chat: `/help`, `/clear`, `/version`, `/compact`, `/new`, `/sessions`, `/rename`, `/diff`, `/status`, `/mcp`, `/plugin`, `/agent`. + +### ๐Ÿค– CLI Agent & Skill Visibility +When the Copilot CLI invokes a specialized agent (code-review, security-review) or a skill plugin, PolyPilot surfaces it in the chat โ€” see which agent is running, when it starts and finishes, and any errors. Use `/agent` to list, select, or deselect agents manually. ### ๐Ÿ”” Smart Notifications Get notified when agents finish tasks, encounter errors, or need your attention โ€” even when the app is in the background. From 6cbf04f5ae095b82f751d3dbb276808fad24c0ba Mon Sep 17 00:00:00 2001 From: Shane Neuville Date: Mon, 30 Mar 2026 17:13:52 -0500 Subject: [PATCH 3/4] docs: rewrite README as a landing page + refine release-notes skill README overhaul: - Add version/download/platform badges - Add dashboard and chat screenshots inline - Replace wall-of-subsections with consolidated, scannable feature blocks - Lead with a quick-scan value prop table instead of bullet list - Merge related features (agent visibility + model selection = one section) - Add platform install links directly in the supported platforms table - Remove implementation details (watchdog tiers, connection modes, etc.) - Update test count to 2,900+ Skill refinements: - Make reading PR bodies a primary step (not optional) - Add README philosophy section: 'The README Sells, It Doesn't Document' - Add good/bad voice examples for README writing - Add per-platform asset download links to release note template - Add trigger table for when to update which README section Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- .claude/skills/release-notes/SKILL.md | 113 +++++++++----- README.md | 216 +++++++++----------------- 2 files changed, 149 insertions(+), 180 deletions(-) diff --git a/.claude/skills/release-notes/SKILL.md b/.claude/skills/release-notes/SKILL.md index c3b2bd3ea2..82484f321f 100644 --- a/.claude/skills/release-notes/SKILL.md +++ b/.claude/skills/release-notes/SKILL.md @@ -27,18 +27,22 @@ release notes** and keeps the README current. ## Step 1: Gather Changes Since Last Release +**Start with commits, then ALWAYS read PR bodies for the headline features.** +The commit subject line is never enough โ€” the PR body has the "why", the architecture +decisions, and the user-facing description you need for highlights. + ```bash # Find the previous tag PREV_TAG=$(git tag --sort=-v:refname | head -2 | tail -1) CURR_TAG=$(git tag --sort=-v:refname | head -1) -# List commits between tags +# List commits between tags (overview) git --no-pager log ${PREV_TAG}..${CURR_TAG} --oneline -# Get full commit messages (for PR numbers and descriptions) -git --no-pager log ${PREV_TAG}..${CURR_TAG} --pretty=format:"%h %s" +# CRITICAL: Read PR bodies for any feat: commits โ€” this is where the good stuff is +gh pr view --json body -q '.body' -# For PRs with more detail +# Batch: get all merged PRs with titles and bodies gh pr list --state merged --search "merged:>=$(git log -1 --format=%ci $PREV_TAG | cut -d' ' -f1)" --limit 50 --json number,title,labels,body ``` @@ -47,6 +51,10 @@ If preparing notes for a release that hasn't been tagged yet, compare against `H git --no-pager log ${PREV_TAG}..HEAD --oneline ``` +**Do not skip reading PR bodies.** A commit that says `feat: mixed-model PR Review Squad` +tells you nothing. The PR body explains that 5 Opus workers each dispatch 3 sub-agents +across Opus/Sonnet/Codex and synthesize 2-of-3 consensus reports. That's the highlight. + --- ## Step 2: Categorize Changes @@ -122,11 +130,16 @@ Bad highlights: **Full Changelog**: https://github.com/PureWeen/PolyPilot/compare/vPREV...vCURR -**Install/Update:** -- **macOS (Homebrew):** `brew upgrade polypilot` or `brew install --cask polypilot` -- **Direct download:** See assets below +**Install / Update:** +- **macOS:** `brew upgrade polypilot` โ€” or download [PolyPilot.zip](https://github.com/PureWeen/PolyPilot/releases/download/vCURR/PolyPilot.zip) +- **Windows:** [PolyPilot-Windows.zip](https://github.com/PureWeen/PolyPilot/releases/download/vCURR/PolyPilot-Windows.zip) +- **Android:** [PolyPilot-Android.apk](https://github.com/PureWeen/PolyPilot/releases/download/vCURR/PolyPilot-Android.apk) +- **Linux:** [.deb](https://github.com/PureWeen/PolyPilot/releases/download/vCURR/polypilot_CURR_amd64.deb) ยท [.AppImage](https://github.com/PureWeen/PolyPilot/releases/download/vCURR/PolyPilot-CURR-x86_64.AppImage) ยท [.flatpak](https://github.com/PureWeen/PolyPilot/releases/download/vCURR/com.microsoft.PolyPilot.flatpak) ``` +Replace `vCURR` and `vPREV` with actual tag names. The asset filenames match what +`.github/workflows/build.yml` uploads (lines 719-727). + ### Example (real v1.0.15 notes, rewritten) ```markdown @@ -191,49 +204,71 @@ gh release create v1.0.17 \ ## Step 5: Update the README -### What to Update +### Philosophy: The README Sells, It Doesn't Document -The README (`README.md` at repo root) should be updated when: +The README is a **landing page**, not a technical spec. It should make someone excited +to try PolyPilot in 30 seconds of scrolling. Every sentence should answer "what can I do?" +not "how is it implemented?" -1. **New major features** are added โ€” add to the "Key Features" section -2. **Platform support changes** โ€” update the platform table -3. **Installation method changes** โ€” update Getting Started -4. **New slash commands** โ€” update the slash commands list +**Good README voice:** +- "Launch pre-built agent teams with one click โ€” 5 workers dispatch sub-agents across models and synthesize consensus reviews" +- "Scan a QR code, control your agent fleet from your pocket" +- "Set a goal and let the agent loop: execute โ†’ evaluate โ†’ refine โ†’ repeat" -### README Update Strategy +**Bad README voice (too implementation-focused):** +- "Uses ConcurrentDictionary for thread-safe session management" +- "Events from the SDK arrive on background threads and are marshaled via SynchronizationContext.Post" +- "The 3-tier timeout system handles quiescent sessions (30s), active tool execution (10min), and general inactivity (2min)" -The README is a **living document** that describes the current state of the app, -not a changelog. Don't add version-specific notes to the README body. +### What to Update (and when) -**Feature section updates:** -- Add new feature subsections under "โœจ Key Features" following the existing pattern: - ```markdown - ### ๐ŸŽ‰ Feature Name - One-paragraph description of what it does and why it matters. - ``` -- Remove or update features that have been significantly reworked -- Keep the order: most impressive/visible features first +| Trigger | README Section | Action | +|---------|---------------|--------| +| New major feature | Key Features | Add or update a feature block | +| Feature significantly reworked | Key Features | Rewrite the block with new capabilities | +| New platform supported | Supported Platforms | Update the table | +| New install method | Getting Started | Add install instructions | +| New slash command | Slash Commands | Add to the list | +| Test count milestone | Testing | Update the number | -**What NOT to put in README:** -- Version-specific changelog (that goes in GitHub Releases) -- "What's New in v1.0.x" sections (gets stale quickly) -- Dates or timestamps +### Structure -### Current README Structure (preserve this) +The README follows this flow (preserve it): ``` -1. Logo + title + tagline -2. "What is PolyPilot?" โ€” overview paragraph -3. "Why PolyPilot?" โ€” bullet list of value props -4. "Key Features" โ€” detailed feature descriptions (this is where new features go) -5. "Iterating on PolyPilot" โ€” self-building workflow -6. "Supported Platforms" โ€” platform table -7. "Getting Started" โ€” install + build instructions -8. "Testing" โ€” test overview -9. "Remote Access via DevTunnel" โ€” mobile setup -10. Footer +1. Logo + badges + tagline +2. Screenshot +3. "What is PolyPilot?" โ€” one paragraph + quick-scan table +4. "Key Features" โ€” the showcase (biggest section, most visual) +5. "Supported Platforms" โ€” table with install links +6. "Getting Started" โ€” Homebrew + build from source +7. "Self-Building Workflow" โ€” the meta story +8. "Testing" โ€” brief +9. Footer ``` +### Adding a New Feature to Key Features + +Follow this pattern โ€” short heading, 1-3 sentences max, focus on what the user gets: + +```markdown +### ๐ŸŽ‰ Feature Name +What it lets you do in one sentence. Maybe a second sentence with a concrete example +or the "wow" detail. Never mention implementation classes or internal architecture. +``` + +Consolidate related capabilities. Don't add a separate section for every PR โ€” group +"CLI Agent Visibility" and "/agent command" into one "Any Model, Any Task" section +rather than three separate entries. + +### What NOT to Put in the README + +- Version-specific changelog (goes in GitHub Releases) +- "What's New in v1.0.x" sections (gets stale instantly) +- Internal architecture (ConcurrentDictionary, SynchronizationContext, event marshaling) +- Timeout values, watchdog tiers, or other implementation constants +- Dates or timestamps + --- ## Step 6: Verify diff --git a/README.md b/README.md index fcfda8c325..a46a70adbb 100644 --- a/README.md +++ b/README.md @@ -9,204 +9,138 @@

- Multi-agent orchestration โ€ข Real-time streaming โ€ข Cross-platform โ€ข Remote access from your phone + Latest Release + Downloads + Platforms

--- -## What is PolyPilot? - -PolyPilot is a **multi-agent control plane for GitHub Copilot**. It's a cross-platform native app (macOS, Windows, Android, iOS) built with .NET MAUI and Blazor that lets you spin up, orchestrate, and monitor **dozens of parallel Copilot coding agents** โ€” each with its own model, working directory, and conversation โ€” all from one dashboard. - -Think of it as **mission control for AI-powered development**: you launch agents, assign them tasks across different repos, watch them work in real time, and manage everything from a single pane of glass โ€” or from your phone while you're away from your desk. +

+ PolyPilot Dashboard +

-### Why PolyPilot? +## What is PolyPilot? -The Copilot CLI is powerful, but it's one agent in one terminal. What if you could: +**Mission control for AI-powered development.** Launch dozens of GitHub Copilot agents, assign them to different repos, watch them work in real time, and manage everything from one dashboard โ€” or from your phone. -- ๐Ÿš€ **Run 10+ Copilot agents simultaneously**, each working on a different task or repo -- ๐Ÿ”„ **Resume any session** across app restarts โ€” your agents never lose context -- ๐Ÿ“ฑ **Monitor and control everything from your phone** via secure WebSocket bridge and DevTunnel -- ๐Ÿง  **Mix and match models** โ€” Claude, GPT, Gemini โ€” in the same workspace -- ๐Ÿ—๏ธ **Organize agents into groups**, pin favorites, and sort by activity -- ๐ŸŒฟ **Manage repos and worktrees** โ€” clone repos, create branches, spin up isolated worktrees per agent +| | | +|---|---| +| ๐Ÿš€ **Run 10+ agents simultaneously** | Each with its own model, repo, and conversation | +| ๐Ÿง  **Mix models freely** | Claude Opus + GPT-5 + Sonnet in the same workspace | +| ๐Ÿค– **One-click team presets** | PR Review Squad, multi-agent orchestration, custom squads | +| ๐Ÿ“ฑ **Control from your phone** | Scan a QR code, manage your fleet from anywhere | +| ๐ŸŽ‰ **Fiesta Mode** | Spread work across multiple machines on your LAN | +| ๐Ÿ”„ **Sessions never die** | Persistent across restarts, auto-reconnect, auto-resume | -That's PolyPilot. +--- ## โœจ Key Features -### ๐ŸŽ›๏ธ Multi-Session Orchestrator Dashboard -A real-time grid view of all active agents. Each card shows streaming output, tool execution status, token usage, and queue depth. Send targeted prompts to individual agents from a single dashboard. - -### ๐Ÿ’ฌ Rich Chat Interface -Full-featured chat UI with streaming responses, Markdown rendering (code blocks, inline code, bold), real-time activity indicators, and auto-scrolling. See exactly what each agent is thinking and doing โ€” including tool calls, reasoning blocks, and intent changes. - -### ๐Ÿ”ง Live Agent Activity Feed -Watch your agents work in real time: `๐Ÿ’ญ Thinking...` โ†’ `๐Ÿ”ง Running bash...` โ†’ `โœ… Tool completed`. Full visibility into multi-step agentic workflows with tool execution tracking and reasoning transparency. - -### ๐Ÿ’พ Session Persistence & Resume -Sessions survive app restarts. Active sessions are automatically saved and restored. Conversation history is reconstructed from event logs. Browse and resume any previously saved session from the sidebar โ€” agents never lose their place. - -### ๐Ÿ“ฑ Remote Access from Your Phone -Run agents on your desktop, monitor from your phone. PolyPilot's WebSocket bridge + Azure DevTunnel integration creates a secure tunnel so you can watch agents work, send prompts, and manage sessions from anywhere. Just scan a QR code to connect. - -### ๐Ÿง  Multi-Model Support -Create sessions with different AI models and compare results side by side. Assign Claude to one task, GPT to another, and Gemini to a third โ€” all running in parallel in the same workspace. +### ๐ŸŽ›๏ธ Fleet Dashboard +A real-time grid of all active agents. Streaming output, tool execution, token usage โ€” everything at a glance. Send prompts to any agent without switching windows. -### ๐Ÿ“‚ Per-Session Working Directories -Point each agent at a different repo or directory. Native folder pickers on macOS and Windows. Manage worktrees for parallel git operations across agents. - -### ๐ŸŒฟ Repository & Worktree Management -Clone repositories, create branches and worktrees, and launch sessions โ€” all from the sidebar. **Quick Branch + Session** creates a new branch and session in one click. **Named Branch + Session** lets you specify a branch name or PR number (`#123`). Worktrees are tracked, linked to sessions, and cleaned up automatically when sessions close. +

+ PolyPilot Chat +

-### ๐Ÿค– Multi-Agent Presets & Squad Teams -Launch pre-configured teams with one click. Built-in presets like **PR Review Squad** spin up an orchestrator plus specialized workers โ€” each internally dispatching parallel sub-agent reviews across multiple models (Opus, Sonnet, Codex) and synthesizing consensus reports. Auto-discovers `.squad` and `.ai-team` directories in your repos for custom team definitions with agent charters and routing configs. +### ๐Ÿค– Multi-Agent Teams +Launch pre-built or custom agent teams with one click: -### ๐Ÿ”€ Worktree Strategies -Control how multi-agent teams share code: -- **Shared** โ€” all agents work in the same directory -- **Orchestrator Isolated** โ€” orchestrator gets its own branch, workers share one -- **Fully Isolated** โ€” every agent gets a unique worktree and branch for zero-conflict parallel work +- **PR Review Squad** โ€” 5 Opus workers each dispatch 3 sub-agents (Opus, Sonnet, Codex) and synthesize consensus reviews +- **Custom Squads** โ€” Drop a `.squad/` directory in your repo with agent charters, routing rules, and shared context +- **Worktree Strategies** โ€” Shared, orchestrator-isolated, or fully-isolated branches per agent -### ๐Ÿ—๏ธ Session Organization -Groups, pinning, and multiple sort modes (Last Active, Created, Aโ€“Z, Manual) let you manage large fleets of agents without losing track. Collapsible groups keep things tidy. +### ๐ŸŽ‰ Fiesta Mode +Turn your LAN into a compute cluster. Discover other PolyPilot instances, pair with a string or push-to-pair, then dispatch tasks to any machine with `@worker-name`. One PolyPilot to rule them all. -### ๐ŸŽ‰ Fiesta Mode โ€” Multi-Machine Orchestration -Discover and link other PolyPilot instances on your LAN. Start a "Fiesta" to fan out work to linked worker machines via `@mention` routing. Workers are discovered automatically, or pair instantly with a compact pairing string or push-to-pair button in Settings. Use `@worker-name` in your prompts to dispatch tasks to specific machines. +### ๐Ÿ“ฑ Remote Access +Your agents run on your desktop. You control them from your pocket. -### โŒจ๏ธ Slash Commands -Built-in slash commands give you quick control without leaving the chat: `/help`, `/clear`, `/version`, `/compact`, `/new`, `/sessions`, `/rename`, `/diff`, `/status`, `/mcp`, `/plugin`, `/agent`. +1. Start a tunnel in Settings (powered by [Azure DevTunnels](https://learn.microsoft.com/en-us/azure/developer/dev-tunnels/)) +2. Scan the QR code on your phone +3. Full control: send prompts, watch streaming output, manage sessions -### ๐Ÿค– CLI Agent & Skill Visibility -When the Copilot CLI invokes a specialized agent (code-review, security-review) or a skill plugin, PolyPilot surfaces it in the chat โ€” see which agent is running, when it starts and finishes, and any errors. Use `/agent` to list, select, or deselect agents manually. +### ๐Ÿ’ฌ Rich Chat +Streaming Markdown, code blocks, reasoning traces, tool call visualization, and real-time activity indicators (`๐Ÿ’ญ Thinking...` โ†’ `๐Ÿ”ง Running bash...` โ†’ `โœ… Done`). You see everything the agent sees. -### ๐Ÿ”” Smart Notifications -Get notified when agents finish tasks, encounter errors, or need your attention โ€” even when the app is in the background. +### ๐Ÿง  Any Model, Any Task +Create sessions with different models and compare results side by side. Claude for architecture, GPT for code generation, Gemini for review โ€” all in parallel. Models are assigned per-session, and the `/agent` command lets you select specialized CLI agents (code-review, security-review) on the fly. -### ๐Ÿ›ก๏ธ Processing Watchdog -Automatically detects agents stuck in a "Thinking..." state and recovers them. A 3-tier timeout system handles quiescent sessions (30s), active tool execution (10min), and general inactivity (2min) โ€” no more zombie sessions. +### ๐ŸŒฟ Git-Native Workflow +- **Quick Branch + Session** โ€” one click to create a branch and start coding +- **Named Branch + Session** โ€” specify a name or PR number (`#123`) +- **Worktree management** โ€” clone, branch, isolate โ€” all from the sidebar +- **Auto-cleanup** โ€” worktrees are tracked and removed when sessions close ### ๐Ÿ” Reflection Cycles -Goal-based iterative refinement for agents. Set a goal, and the agent will loop โ€” executing, evaluating, and refining โ€” until it meets the completion criteria or hits a max iteration count. Great for test-driven workflows and multi-step tasks. - -### ๐Ÿ“Š Usage Stats -Track session metrics: messages sent, tokens used, session duration, and lines suggested. Visible in the bottom bar for quick reference. - -### ๐ŸŽฎ Demo Mode -Test the UI without a Copilot connection. The built-in demo service simulates streaming responses, tool calls, and activity indicators with realistic timing. - -### ๐Ÿ”Œ Flexible Connection Modes -From embedded stdio for quick single-machine use, to a persistent server that survives app restarts, to remote mode for mobile access โ€” pick the transport that fits your workflow. - -### ๐Ÿ›ก๏ธ Auto-Reconnect -If an agent's underlying process dies mid-conversation, PolyPilot automatically resumes the session and retries โ€” transparent to you. - -### ๐Ÿ”„ Git Auto-Update -When running from a git checkout, PolyPilot can automatically detect and pull updates from the main branch โ€” keeping your instance up to date without manual intervention. - -### ๐ŸŒ Tailscale Integration -Detects your Tailscale VPN status and IP automatically, making it easy to share your agent fleet across your Tailscale network. - -## ๐Ÿ” Iterating on PolyPilot โ€” Self-Building Workflow +Set a goal and let the agent loop: execute โ†’ evaluate โ†’ refine โ†’ repeat. Configurable iteration limits and completion criteria. Perfect for TDD and multi-step tasks. -PolyPilot is designed to be developed **from within itself**. You can open a Copilot session pointed at the PolyPilot repo, make changes, and use the included `relaunch.sh` script to seamlessly rebuild and relaunch โ€” all without leaving the app. +### ๐Ÿ’พ Bulletproof Persistence +Sessions survive everything โ€” app restarts, machine reboots, CLI crashes. History is reconstructed from event logs. A 3-tier watchdog recovers stuck agents automatically. No zombie sessions, no lost work. -### How it works - -```bash -# macOS -./relaunch.sh - -# Windows -powershell -ExecutionPolicy Bypass -File relaunch.ps1 -``` - -On macOS, the script: -1. **Builds** the project (`dotnet build -f net10.0-maccatalyst`) -2. **Copies** the built app to a staging directory -3. **Launches** the new instance -4. **Verifies** the new instance is stable (waits a few seconds) -5. **Kills** the old instance โ€” seamless handoff, no downtime - -On Windows, `relaunch.ps1` follows the same pattern for the WinUI target. - -If the build fails, the old instance keeps running and you see clear error output. No stale binaries are ever launched. - -This means an agent working inside PolyPilot can edit code, run `./relaunch.sh`, and immediately test its own changes in the freshly-built app โ€” a tight feedback loop for AI-driven development. +### โŒจ๏ธ Slash Commands +Quick control without leaving the chat: `/help` `/clear` `/compact` `/new` `/sessions` `/rename` `/diff` `/status` `/mcp` `/plugin` `/agent` -> **Most of PolyPilot's features were built by GitHub Copilot coding agents โ€” orchestrated from within PolyPilot itself.** +--- -## Supported Platforms +## ๐Ÿ–ฅ๏ธ Supported Platforms -| Platform | Status | -|----------|--------| -| **macOS** (Mac Catalyst) | โœ… Primary development target | -| **Windows** | โœ… Supported | -| **Android** | โœ… Supported (Remote mode) | -| **iOS** | โœ… Supported (Remote mode) | -| **Linux** (GTK head) | ๐Ÿงช Experimental (`PolyPilot.Gtk`) | +| Platform | Status | Install | +|----------|--------|---------| +| **macOS** | โœ… Primary | `brew install --cask polypilot` | +| **Windows** | โœ… Supported | [Download .zip](https://github.com/PureWeen/PolyPilot/releases/latest) | +| **Android** | โœ… Supported | [Download .apk](https://github.com/PureWeen/PolyPilot/releases/latest) | +| **iOS** | โœ… Supported | TestFlight | +| **Linux** | ๐Ÿงช Experimental | [.deb / .AppImage / .flatpak](https://github.com/PureWeen/PolyPilot/releases/latest) | -Mobile devices connect to a desktop instance via WebSocket bridge โ€” run your agent fleet on your workstation, control it from your pocket. +Mobile connects to a desktop instance via WebSocket bridge โ€” your fleet runs on the workstation, your phone is the remote control. -## Getting Started +## ๐Ÿš€ Getting Started -### Install with Homebrew (macOS) +### Homebrew (macOS โ€” recommended) ```bash brew tap PureWeen/tap brew install --cask polypilot ``` -This installs the notarized PolyPilot.app and the GitHub Copilot CLI automatically. - -### Prerequisites (build from source) +### Build from Source -- **.NET 10 SDK** (Preview) -- **.NET MAUI workload** โ€” `dotnet workload install maui` -- **GitHub Copilot CLI** โ€” `brew install copilot-cli` or `npm install -g @github/copilot` -- **GitHub Copilot subscription** - -### Build & Run +**Prerequisites:** [.NET 10 SDK](https://dotnet.microsoft.com/download/dotnet/10.0) + `dotnet workload install maui` + [GitHub Copilot CLI](https://docs.github.com/en/copilot) + Copilot subscription ```bash cd PolyPilot # macOS -dotnet build -f net10.0-maccatalyst -open bin/Debug/net10.0-maccatalyst/maccatalyst-arm64/PolyPilot.app - -# Or use the hot-relaunch script for iterative development -./relaunch.sh +./relaunch.sh # Build + hot-relaunch # Windows dotnet build -f net10.0-windows10.0.19041.0 -# Android (deploy to connected device) +# Android dotnet build -f net10.0-android -t:Install -# Linux (GTK head) -dotnet build PolyPilot.Gtk/PolyPilot.Gtk.csproj +# Linux dotnet run --project PolyPilot.Gtk/PolyPilot.Gtk.csproj ``` -## ๐Ÿงช Testing +## ๐Ÿ” Self-Building Workflow -PolyPilot has two layers of testing: +PolyPilot builds itself. Open a Copilot session pointed at the PolyPilot repo, make changes, run `./relaunch.sh`, and the app seamlessly rebuilds and relaunches โ€” no downtime, no stale binaries, no leaving the app. -- **1,200+ unit tests** (xUnit, .NET 10) โ€” deterministic tests covering models, services, multi-agent orchestration, persistence, and parsing. Run with `cd PolyPilot.Tests && dotnet test`. -- **Executable UI scenarios** (JSON + MauiDevFlow CDP) โ€” end-to-end flows validated against a running app instance. 25+ multi-agent scenarios (reflection loops, Squad discovery, group lifecycle) and 10+ mode-switch scenarios. - -The test project shares source files with the main MAUI project via `` links, so tests run on any machine without platform SDKs. `ScenarioReferenceTests.cs` cross-references every CDP scenario with its deterministic unit-test equivalent. +> **Most of PolyPilot's features were built by GitHub Copilot coding agents โ€” orchestrated from within PolyPilot itself.** -See [`docs/testing.md`](docs/testing.md) for the full testing guide, scenario format, and how to add new tests. +## ๐Ÿงช Testing -## ๐Ÿ“ฑ Remote Access via DevTunnel +- **2,900+ unit tests** โ€” models, services, orchestration, persistence, parsing +- **Executable UI scenarios** โ€” end-to-end CDP flows validated against a running instance -Mobile devices connect to your desktop over [Azure DevTunnels](https://learn.microsoft.com/en-us/azure/developer/dev-tunnels/) โ€” a secure tunnel to control your agent fleet from anywhere. +```bash +cd PolyPilot.Tests && dotnet test +``` -1. Install the DevTunnel CLI (`brew install --cask devtunnel` on macOS, `winget install Microsoft.devtunnel` on Windows) -2. In PolyPilot Settings, click **Login with GitHub** then **Start Tunnel** -3. Scan the **QR code** from your phone to connect instantly +See [`docs/testing.md`](docs/testing.md) for the full guide. --- From 41dba1d8fe376092533d5b82962ddb1b2002525d Mon Sep 17 00:00:00 2001 From: Shane Neuville Date: Mon, 30 Mar 2026 18:02:38 -0500 Subject: [PATCH 4/4] docs: address PR review feedback MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Fix test count: 2,900+ โ†’ 3,000+ (actual: 3,061) - Fix iOS install: TestFlight โ†’ Build from source (no public link) - Restore dropped features: Notifications, Tailscale, Demo Mode - Clarify Linux asset naming in skill template with actual examples Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- .claude/skills/release-notes/SKILL.md | 7 +++++-- README.md | 10 ++++++++-- 2 files changed, 13 insertions(+), 4 deletions(-) diff --git a/.claude/skills/release-notes/SKILL.md b/.claude/skills/release-notes/SKILL.md index 82484f321f..e313db398e 100644 --- a/.claude/skills/release-notes/SKILL.md +++ b/.claude/skills/release-notes/SKILL.md @@ -137,8 +137,11 @@ Bad highlights: - **Linux:** [.deb](https://github.com/PureWeen/PolyPilot/releases/download/vCURR/polypilot_CURR_amd64.deb) ยท [.AppImage](https://github.com/PureWeen/PolyPilot/releases/download/vCURR/PolyPilot-CURR-x86_64.AppImage) ยท [.flatpak](https://github.com/PureWeen/PolyPilot/releases/download/vCURR/com.microsoft.PolyPilot.flatpak) ``` -Replace `vCURR` and `vPREV` with actual tag names. The asset filenames match what -`.github/workflows/build.yml` uploads (lines 719-727). +Replace `vCURR`/`vPREV` with actual tag names (e.g., `v1.0.17`) and `CURR` with the +bare version (e.g., `1.0.17`). The asset filenames match what `.github/workflows/build.yml` +uploads (lines 719-727). Actual assets per release: `PolyPilot.zip` (macOS), +`PolyPilot-Windows.zip`, `PolyPilot-Android.apk`, `polypilot_{ver}_amd64.deb`, +`PolyPilot-{ver}-x86_64.AppImage`, `com.microsoft.PolyPilot.flatpak`. ### Example (real v1.0.15 notes, rewritten) diff --git a/README.md b/README.md index a46a70adbb..ce62e38e7b 100644 --- a/README.md +++ b/README.md @@ -82,6 +82,12 @@ Sessions survive everything โ€” app restarts, machine reboots, CLI crashes. Hist ### โŒจ๏ธ Slash Commands Quick control without leaving the chat: `/help` `/clear` `/compact` `/new` `/sessions` `/rename` `/diff` `/status` `/mcp` `/plugin` `/agent` +### ๐Ÿ”” Notifications & Tailscale +Get notified when agents finish or hit errors โ€” even in the background. Tailscale VPN is detected automatically for easy fleet sharing across your network. + +### ๐ŸŽฎ Demo Mode +Try the full UI without a Copilot connection โ€” simulated streaming, tool calls, and activity indicators with realistic timing. + --- ## ๐Ÿ–ฅ๏ธ Supported Platforms @@ -91,7 +97,7 @@ Quick control without leaving the chat: `/help` `/clear` `/compact` `/new` `/ses | **macOS** | โœ… Primary | `brew install --cask polypilot` | | **Windows** | โœ… Supported | [Download .zip](https://github.com/PureWeen/PolyPilot/releases/latest) | | **Android** | โœ… Supported | [Download .apk](https://github.com/PureWeen/PolyPilot/releases/latest) | -| **iOS** | โœ… Supported | TestFlight | +| **iOS** | โœ… Supported | [Build from source](https://github.com/PureWeen/PolyPilot#build-from-source) | | **Linux** | ๐Ÿงช Experimental | [.deb / .AppImage / .flatpak](https://github.com/PureWeen/PolyPilot/releases/latest) | Mobile connects to a desktop instance via WebSocket bridge โ€” your fleet runs on the workstation, your phone is the remote control. @@ -133,7 +139,7 @@ PolyPilot builds itself. Open a Copilot session pointed at the PolyPilot repo, m ## ๐Ÿงช Testing -- **2,900+ unit tests** โ€” models, services, orchestration, persistence, parsing +- **3,000+ unit tests** โ€” models, services, orchestration, persistence, parsing - **Executable UI scenarios** โ€” end-to-end CDP flows validated against a running instance ```bash