Skip to content

feat: add session management and parallel work spawning #26

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
marcusquinn merged 2 commits into from
Jan 10, 2026
Merged

feat: add session management and parallel work spawning #26

Show file tree
Hide file tree
Changes from 1 commit
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
cd8a2ee
feat: add session management and parallel work spawning
marcusquinn Jan 10, 2026
dedc10c
fix: address CodeRabbit review feedback
marcusquinn Jan 10, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
42 changes: 42 additions & 0 deletions .agent/AGENTS.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -214,6 +214,48 @@ opencode mcp list
~/.aidevops/agents/scripts/tool-version-check.sh
```

## Session Completion & Parallel Work

**Recognize session completion signals:**
- All session tasks marked `[x]` in TODO.md
- PR merged and release published
- User expresses gratitude ("thanks", "done", "that's all")
- Significant topic shift to unrelated work

**At natural completion points, suggest:**

```text
---
Session goals achieved:
- [x] {completed task 1}
- [x] {completed task 2}

Suggestions:
1. Run @agent-review to capture learnings
2. Start new session for clean context
3. For parallel work: worktree-helper.sh add {type}/{name}
---
```

**When to suggest new sessions:**
- After PR merge + release
- When switching to unrelated domain
- After 3+ hours of continuous work
- When user requests unrelated task

**Spawning parallel sessions** (for related but separate work):

```bash
# Create worktree + spawn new terminal (macOS)
~/.aidevops/agents/scripts/worktree-helper.sh add feature/parallel-task
osascript -e 'tell application "Terminal" to do script "cd ~/Git/{repo}-feature-parallel-task && opencode"'

# Or background session
opencode run "Continue with task X" --agent Build+ &
```

See `workflows/session-manager.md` for full session lifecycle guidance.
Comment on lines +217 to +257

@coderabbitai coderabbitai Bot Jan 10, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟡 Minor

🧩 Analysis chain

🏁 Script executed:

#!/bin/bash

echo "=== 1. Check referenced files exist ==="
[ -f .agent/workflows/session-manager.md ] && echo "✓ workflows/session-manager.md exists" || echo "✗ workflows/session-manager.md NOT FOUND"
find .agent -name "worktree-helper.sh" && echo "✓ worktree-helper.sh found" || echo "✗ worktree-helper.sh NOT FOUND"

echo -e "\n=== 2. Check AGENTS.md line count and structure ==="
wc -l .agent/AGENTS.md

echo -e "\n=== 3. Check for spawning patterns/duplication ==="
echo "Searching for 'Spawning' patterns across .agent:"
rg -n "Spawning|parallel.*session|new.*session" .agent --type markdown -i | head -20

echo -e "\n=== 4. Check AGENTS.md for other section with spawning/parallel work ==="
rg -n "worktree-helper\|opencode run" .agent/AGENTS.md

echo -e "\n=== 5. Check workflows/session-manager.md content (if exists) ==="
if [ -f .agent/workflows/session-manager.md ]; then
  echo "File exists. First 50 lines:"
  head -50 .agent/workflows/session-manager.md
fi

Repository: marcusquinn/aidevops

Length of output: 3729

Session spawning examples should relocate to subagent; consolidate with ralph-loop.md "Session Completion & Spawning" section.

The section appropriately uses progressive disclosure with a pointer to workflows/session-manager.md, aligning with prior learnings. However, two issues warrant refactoring:

  1. Duplication with workflows/ralph-loop.md: Lines 347-403 of ralph-loop.md contain "Session Completion & Spawning" with overlapping spawning patterns and new session logic. This duplicates AGENTS.md lines 246-255.

  2. Inline spawning examples: The code examples at lines 246-255 (worktree + terminal spawning) should move to a dedicated subagent with a brief pointer in AGENTS.md, strengthening the progressive disclosure pattern already established by the pointer to workflows/session-manager.md.

The content itself is universally applicable (session management touches >80% of tasks), so root-level guidance is warranted—but delivery should follow the pointer-first pattern consistently.


## Main Agents

| Agent | Purpose |
Expand Down
29 changes: 29 additions & 0 deletions .agent/tools/build-agent/agent-review.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -56,6 +56,35 @@ See `tools/opencode/opencode.md` for CLI testing patterns.
3. **Observable failure** - Commands fail, paths don't exist
4. **Periodic maintenance** - Scheduled review cycles

### When Agents Should Suggest @agent-review

All agents should suggest calling `@agent-review` at these points:

1. **After PR merge** - Capture what worked in the PR process
2. **After release** - Document release learnings
3. **After fixing multiple issues** - Pattern recognition opportunity
4. **After user correction** - Immediate improvement opportunity
5. **Before starting unrelated work** - Clean context boundary
6. **After long session** - Capture accumulated learnings

**Suggestion format:**

```text
---
Session complete. Consider running @agent-review to:
- Capture patterns from {specific accomplishment}
- Identify improvements to {agents used}
- Document {any corrections or failures}

Options:
1. Run @agent-review now
2. Start new session (clean context)
3. Continue in current session
---
```

See `workflows/session-manager.md` for full session lifecycle guidance.

### Review Checklist

For each agent file under review:
Expand Down
76 changes: 76 additions & 0 deletions .agent/tools/opencode/opencode.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -617,6 +617,82 @@ After fixing violations from SonarCloud, Codacy, ShellCheck, etc.:

Example: Finding 15 SC2162 violations (read without -r) leads to adding clear examples in AGENTS.md's shell best practices section.

## Spawning Parallel Sessions

OpenCode supports multiple session patterns for parallel work.

### Non-Interactive Execution

```bash
# Run a task without TUI
opencode run "Task description" --agent Build+ --title "Task Name"

# Background execution
opencode run "Long running task" --agent Build+ &
```

### Persistent Server Mode

For multiple sessions sharing MCP connections:

```bash
# Terminal 1: Start headless server
opencode serve --port 4097

# Terminal 2+: Run against server (fast, reuses MCPs)
opencode run --attach http://localhost:4097 "Task 1" --agent Build+
opencode run --attach http://localhost:4097 "Task 2" --agent SEO
```

### Terminal Tab Spawning

```bash
# macOS Terminal.app
osascript -e 'tell application "Terminal" to do script "cd ~/Git/project && opencode"'

@gemini-code-assist gemini-code-assist Bot Jan 10, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

medium

The example commands use a hardcoded project path ~/Git/project. This is repeated in other examples and files. For better clarity and reusability, consider using a placeholder like {project_path}. The file .agent/AGENTS.md already uses a {repo} placeholder, and adopting a consistent placeholder strategy across all documentation would be beneficial.


# iTerm2
osascript -e 'tell application "iTerm2" to tell current window to create tab with default profile command "cd ~/Git/project && opencode"'

# Linux GNOME Terminal
gnome-terminal --tab -- bash -c "cd ~/Git/project && opencode; exec bash"

# Kitty
kitty @ launch --type=tab --cwd=~/Git/project opencode
```

### Worktree + New Session (Recommended)

Best pattern for parallel branch work:

```bash
# Create worktree for parallel branch
~/.aidevops/agents/scripts/worktree-helper.sh add feature/parallel-task
# Output: ~/Git/project-feature-parallel-task/

# Spawn session in worktree (macOS)
osascript -e 'tell application "Terminal" to do script "cd ~/Git/project-feature-parallel-task && opencode"'
```

### Session Handoff

When spawning a continuation session:

```bash
# Export context for new session
cat > .session-handoff.md << EOF
# Session Handoff
**Branch**: $(git branch --show-current)
**Last commit**: $(git log -1 --oneline)
## Continue With
- {next task description}
EOF

# Spawn with handoff
opencode run "Read .session-handoff.md and continue" --agent Build+
```

See `workflows/session-manager.md` for full session lifecycle guidance.

## References

- [OpenCode Agents Documentation](https://opencode.ai/docs/agents)
Expand Down
65 changes: 65 additions & 0 deletions .agent/workflows/ralph-loop.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -344,6 +344,71 @@ This compares our implementation against the Claude plugin and reports any signi

The check runs automatically when starting an OpenCode session in the aidevops repository.

## Session Completion & Spawning

Loop agents should detect completion and suggest next steps.

### Loop Completion Detection

When a loop completes successfully (promise fulfilled), suggest:

```text
<promise>PR_MERGED</promise>

---
Loop complete. PR #123 merged successfully.

Suggestions:
1. Run @agent-review to capture learnings
2. Start new session for next task
3. Spawn parallel session for related work
---
```

### Spawning New Sessions from Loops

Loops can spawn new OpenCode sessions for parallel work:

**Background Session (Same Terminal):**

```bash
# Start new session in background
opencode run "Continue with next task" --agent Build+ &

# Or use serve mode for persistent background
opencode serve --port 4097 &
opencode run --attach http://localhost:4097 "Task X" --agent Build+
```

**New Terminal Tab (macOS):**

```bash
# Spawn in new tab
osascript -e 'tell application "Terminal" to do script "cd ~/Git/project && opencode"'
```

**With Worktrees (Recommended for Parallel Branches):**

```bash
# Create worktree for parallel work
~/.aidevops/agents/scripts/worktree-helper.sh add feature/parallel-task
# Output: ~/Git/project-feature-parallel-task/

# Spawn session in new worktree
osascript -e 'tell application "Terminal" to do script "cd ~/Git/project-feature-parallel-task && opencode"'
```

### Integration with quality-loop-helper.sh

The `quality-loop-helper.sh` script can spawn new sessions on loop completion:

```bash
# After successful loop, offer to spawn next task
~/.aidevops/agents/scripts/quality-loop-helper.sh preflight --on-complete spawn
```

See `workflows/session-manager.md` for full session lifecycle guidance.
Comment thread
coderabbitai[bot] marked this conversation as resolved.
Outdated

## Learn More

- Original technique: <https://ghuntley.com/ralph/>
Expand Down
Loading
Loading