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 all commits
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
Copy link
Contributor

@coderabbitai coderabbitai bot Jan 10, 2026

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
27 changes: 27 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,33 @@ 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.

### Quick Reference

```bash
# Non-interactive execution
opencode run "Task description" --agent Build+ --title "Task Name"

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

# Persistent server (reuses MCP connections)
opencode serve --port 4097
opencode run --attach http://localhost:4097 "Task" --agent Build+

# With worktree (recommended for parallel branches)
~/.aidevops/agents/scripts/worktree-helper.sh add feature/parallel-task
```

See `workflows/session-manager.md` for full session lifecycle guidance including:
- Terminal tab spawning (macOS, Linux)
- Session handoff patterns
- Worktree integration
- Loop completion detection

## References

- [OpenCode Agents Documentation](https://opencode.ai/docs/agents)
Expand Down
44 changes: 44 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,50 @@ 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. See `workflows/session-manager.md` for full spawning patterns (background sessions, terminal tabs, worktrees).

**Quick reference:**

```bash
# Background session
opencode run "Continue with next task" --agent Build+ &

# With worktree (recommended for parallel branches)
~/.aidevops/agents/scripts/worktree-helper.sh add feature/parallel-task
```

### 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
```

## Learn More

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