feat: session orchestration v2 with ISessionService #312
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Add /orchestrate command and supporting infrastructure for managing parallel worker sessions across separate worktrees. - /orchestrate: Session orchestrator for spawning and monitoring workers - /ralph-work: Spawn autonomous Ralph Wiggum session for an issue - ADR-0030: Documents session orchestration architecture - Worker templates for Task agents and Ralph terminals - PowerShell script for launching orchestration Learnings from initial test: - Task agents share working directory (can't parallelize branches) - Ralph terminals with worktrees required for true parallel work - Session files in ~/.ppds/sessions/ for cross-session state Co-Authored-By: Claude Opus 4.5 <[email protected]>
Implements V2 orchestration with isolated worktrees:
- Session service with spawn, list, get, update, cancel, forward
- WindowsTerminalWorkerSpawner for wt.exe integration
- RPC methods for ppds serve integration
- CLI commands: ppds session {list,spawn,get,cancel,cancel-all,update}
Session commands are internal dev tooling, hidden unless PPDS_INTERNAL=1.
Workers are spawned with PPDS_INTERNAL=1 set automatically.
Updates orchestrate.md with explicit first-step instructions and
worker templates to use ppds session update for status reporting.
Co-Authored-By: Claude Opus 4.5 <[email protected]>
The global ppds command may be outdated. Updated orchestrate.md to always use dotnet run from source with PPDS_INTERNAL=1, avoiding confusion about build vs install. Co-Authored-By: Claude Opus 4.5 <[email protected]>
Windows Bash tool may use PowerShell. Updated orchestrate.md to use $env:PPDS_INTERNAL syntax that works in both PowerShell and pwsh. Co-Authored-By: Claude Opus 4.5 <[email protected]>
Claude Code Bash tool on Windows uses Git Bash, not PowerShell. Updated to use standard bash export/prefix syntax. Co-Authored-By: Claude Opus 4.5 <[email protected]>
Added commands for reviewing/discussing issues before spawning workers: - list issues, show issue details - discuss priority and dependencies - analyze if issues can run in parallel - plan implementation approach Updated startup to offer plan vs spawn options instead of pushing users directly to spawn workers. Co-Authored-By: Claude Opus 4.5 <[email protected]>
List bugs first and recommend fixing them before other issues. Co-Authored-By: Claude Opus 4.5 <[email protected]>
Nested quotes through wt -> powershell -Command were getting mangled. Now writes a .ps1 launcher script and runs with pwsh -File instead. Co-Authored-By: Claude Opus 4.5 <[email protected]>
/ralph-loop doesn't exist. For now, just start claude in the worktree and show the prompt file path. Worker can read session-prompt.md. Co-Authored-By: Claude Opus 4.5 <[email protected]>
Workers are spawned in worktrees we create, so trust is implicit. Co-Authored-By: Claude Opus 4.5 <[email protected]>
ListCommand now shows [?] and "STALE (no heartbeat)" for sessions that haven't sent a heartbeat in over 90 seconds. Co-Authored-By: Claude Opus 4.5 <[email protected]>
- Added ppds session forward <id> <message> command - Added ppds session pause/resume commands - Worker now starts with initial prompt to read session-prompt.md Workers were starting claude with no instructions. Now they get an initial message pointing them to the session prompt file. Co-Authored-By: Claude Opus 4.5 <[email protected]>
- Fix permission mode: change dontAsk (auto-deny) to acceptEdits - Add Skill permissions for /ship, /test, /commit to settings.json - Add Planning and PlanningComplete session statuses - Update worker prompt with plan-first workflow and optional status updates - Add worker plan display to session get command - Write session state to worktree for forwarded messages - Fix git diff command that used bash-specific 2>/dev/null on Windows - Add CLAUDE.md rule: no bash-specific syntax in C# process commands Tested with issue #202 - worker completed autonomously with zero prompts. Co-Authored-By: Claude Opus 4.5 <[email protected]>
Workers check for session-state.json to read forwarded messages, but it was only created when forwarding. Now created on spawn so workers always have the file available. Co-Authored-By: Claude Opus 4.5 <[email protected]>
Worktrees now use the actual repo folder name (e.g., ppds-docs-issue-5) instead of hardcoded "ppds". This enables spawning workers from any repo in the ppds family - issues should be filed in their target repo. Co-Authored-By: Claude Opus 4.5 <[email protected]>
Replaced bash gh commands with native MCP GitHub tools. Co-Authored-By: Claude Opus 4.5 <[email protected]>
This reverts commit 8f3778a.
…ommands - Remove dead ralph-wiggum code (ralph-work.md, ralph-prompt-template.md, Start-PpdsOrchestration.ps1) - Rewrite ADR-0030 to match ISessionService implementation - Add planning phase and status values to workflow docs - Add /commit command for phase-aware intermediate commits - Add /create-worktree command for quick ad-hoc worktrees - Update /ship with explicit reviewer polling (Copilot, Gemini, CodeQL) - Update /orchestrate with plan review flow ([P] status) - Update CLAUDE.md commands table Co-Authored-By: Claude Opus 4.5 <[email protected]>
joshsmithxrm
had a problem deploying
to
test-dataverse
GitHub Actions
Failure
Summary of ChangesHello @joshsmithxrm, I'm Gemini Code Assist1! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed! This pull request introduces a robust and comprehensive session orchestration system designed to manage multiple parallel Claude Code worker sessions. The core idea is to enable a central Claude instance to act as an orchestrator, spawning and overseeing other Claude instances (workers) that each tackle a specific GitHub issue. This system streamlines the development workflow by automating the setup of isolated development environments (git worktrees), providing a structured lifecycle for issue resolution, and facilitating human intervention through natural language commands for monitoring, guidance, and status updates. The changes lay the groundwork for highly efficient, concurrent, and supervised autonomous development. Highlights
Using Gemini Code AssistThe full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips. Invoking Gemini You can request assistance from Gemini at any point by creating a comment using either
Customization To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a Limitations & Feedback Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for Github and other Google products, sign up here. You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension. Footnotes
|
![gemini-code-assist[bot]](https://avatars.githubusercontent.com/in/956858?s=60&v=4){kind=small}
There was a problem hiding this comment.
Code Review
This pull request introduces a comprehensive session orchestration feature, enabling parallel worker sessions for implementing GitHub issues. The changes include a new ISessionService layer, a suite of ppds session CLI commands, a Windows Terminal spawner, and extensive documentation including a new ADR. The implementation is thorough and well-documented. My review focuses on improving dependency injection usage in the new RPC handlers and CLI commands, ensuring consistent error handling with custom exceptions as per project guidelines, and fixing some minor inconsistencies in status reporting and command-line help messages.
Codecov Report❌ Patch coverage is 📢 Thoughts on this report? Let us know! |
There was a problem hiding this comment.
Pull request overview
This PR implements a comprehensive session orchestration system for managing parallel Claude Code worker sessions. The feature enables spawning multiple autonomous workers to implement GitHub issues simultaneously with human oversight through natural language interaction.
Key Changes:
- Full C# service layer with ISessionService and DI support for session management
- CLI command group with 9 session management commands (spawn, list, get, update, pause, resume, cancel, etc.)
- Windows Terminal worker spawner for creating isolated worker tabs with direct Claude invocation
- File-based coordination using JSON state files in
~/.ppds/sessions/
Reviewed changes
Copilot reviewed 31 out of 31 changed files in this pull request and generated 22 comments.
Show a summary per file
| File | Description |
|---|---|
src/PPDS.Cli/Services/Session/SessionService.cs |
Core service implementation with session lifecycle management, git worktree operations, and state persistence |
src/PPDS.Cli/Services/Session/SessionState.cs |
Session state models including SessionStatus enum and WorktreeStatus |
src/PPDS.Cli/Services/Session/ISessionService.cs |
Service interface defining session operations (spawn, list, get, update, pause, resume, cancel, forward, heartbeat) |
src/PPDS.Cli/Services/Session/WindowsTerminalWorkerSpawner.cs |
Windows Terminal-based worker spawner that creates PowerShell launcher scripts |
src/PPDS.Cli/Services/Session/IWorkerSpawner.cs |
Worker spawner abstraction with request/response models |
src/PPDS.Cli/Commands/Session/*.cs |
CLI commands for session operations (8 command files) |
src/PPDS.Cli/Services/ServiceRegistration.cs |
DI registration for IWorkerSpawner and ISessionService |
src/PPDS.Cli/Program.cs |
Session command group registration gated behind PPDS_INTERNAL=1 |
src/PPDS.Cli/Infrastructure/Progress/IProgressReporter.cs |
New UI-agnostic progress reporting interface per ADR-0025 |
src/PPDS.Cli/Infrastructure/Errors/ErrorCodes.cs |
Session-specific error codes |
src/PPDS.Cli/Commands/Serve/Handlers/RpcMethodHandler.cs |
9 new RPC methods for session management with DTOs |
docs/adr/0030_SESSION_ORCHESTRATION.md |
Comprehensive ADR documenting architecture, workflow, and design decisions |
.claude/workflows/*.md |
Updated workflow documentation with planning phase and commit strategy |
.claude/commands/orchestrate.md |
New orchestrator command documentation with natural language interface |
.claude/commands/commit.md |
Phase-aware intermediate commit command |
.claude/commands/ship.md |
Updated with explicit reviewer polling for Copilot/Gemini/CodeQL |
scripts/worker-task-template.md |
Worker prompt template with status reporting and domain gates |
scripts/ppds-dev.ps1 |
Local development wrapper for ppds CLI |
CLAUDE.md |
Updated with new commands and common mistakes |
- Use [P] icon for PlanningComplete status (was [~]) - Add Registered status icon [ ] - Update status lists in error messages to include all values - Replace KeyNotFoundException with PpdsException in SessionService - Replace InvalidOperationException with PpdsException for AlreadyExists - Centralize spawner availability check in SpawnAsync Co-Authored-By: Claude Opus 4.5 <[email protected]>
joshsmithxrm
had a problem deploying
to
test-dataverse
GitHub Actions
Failure
- Add ISessionService to RpcMethodHandler constructor - Update ServeCommand to create SessionService once for daemon lifetime - Replace all per-call SessionService instantiation with injected service - Update tests to pass mock ISessionService This fixes the performance issue where every RPC call was reloading all sessions from disk. The daemon now uses a singleton SessionService that caches sessions in memory across RPC calls. Co-Authored-By: Claude Opus 4.5 <[email protected]>
joshsmithxrm
had a problem deploying
to
test-dataverse
GitHub Actions
Failure
- Add step to enumerate all bot reviewers before addressing comments - Add checklist to ensure no reviewer is missed (Copilot, Gemini, etc.) - Reorder sections for clearer flow: CI first, then enumerate, then fix - Move CodeQL check earlier in the process Co-Authored-By: Claude Opus 4.5 <[email protected]>
joshsmithxrm
had a problem deploying
to
test-dataverse
GitHub Actions
Failure
Add intermediate session statuses to track the shipping workflow: - Shipping: PR created, waiting for required CI checks - ReviewsInProgress: CI passed, addressing bot review comments - PrReady: All bot comments addressed, ready for human review Also updates /ship docs to distinguish required vs optional CI checks and adds CI check classification table to CLAUDE.md. Co-Authored-By: Claude Opus 4.5 <[email protected]>
joshsmithxrm
had a problem deploying
to
test-dataverse
GitHub Actions
Failure
Address Gemini/Copilot review comment about incomplete status lists in error messages and option descriptions. Added shipping, reviews_in_progress, and pr_ready to the valid values. Co-Authored-By: Claude Opus 4.5 <[email protected]>
joshsmithxrm
had a problem deploying
to
test-dataverse
GitHub Actions
Failure
- Use atomic AddOrUpdate for ConcurrentDictionary to prevent race conditions - Use async File.WriteAllTextAsync with CancellationToken in spawner - Fix JSON serialization consistency (use typed record with JsonOptions) - Add logging for IsAvailable exceptions with ILogger injection - Properly dispose Process objects in spawner - Document heartbeat in-memory limitation in ISessionService Co-Authored-By: Claude Opus 4.5 <[email protected]>
joshsmithxrm
had a problem deploying
to
test-dataverse
GitHub Actions
Failure
3 tasks
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Summary
Complete implementation of session orchestration for parallel Claude Code worker sessions:
PPDS_INTERNAL=1)~/.ppds/sessions/work-{issue}.jsonstatus filesNew Commands
/orchestrate- Natural language orchestrator interface/commit- Phase-aware intermediate commits/create-worktree- Quick worktree + Claude session for ad-hoc workDocumentation
Test plan
ppds session spawn <issue>🤖 Generated with Claude Code