feat: add session management and parallel work spawning#26
Conversation
Add session completion detection and parallel session spawning across all agents to improve context management and enable focused parallel work. New file: - workflows/session-manager.md - Full session lifecycle guidance (252 lines) Updated files: - AGENTS.md - Session completion detection section with signals and suggestions - agent-review.md - When agents should suggest @agent-review - opencode.md - Spawning parallel sessions (CLI, terminal tabs, worktrees) - ralph-loop.md - Loop completion detection and spawn capability Key features: - Detect session completion (tasks done, PR merged, release published) - Suggest @agent-review at natural completion points - Spawn parallel sessions via opencode run, serve mode, or terminal tabs - Integrate worktrees for parallel branch development - Cross-platform terminal spawning (macOS, Linux) This enables cleaner context management and efficient parallel work across multiple branches and tasks.
WalkthroughAdds comprehensive documentation for session lifecycle management and patterns for spawning parallel work across the agent framework, including a new session-manager guide, duplicated guidance in several workflow/tool docs, and suggestions for when agents should propose Changes
Sequence Diagram(s)sequenceDiagram
actor User
participant Agent
participant Repo as Git/PR
participant Terminal
participant SessionMgr as Session Manager
User->>Agent: finish current task / check status
Agent->>Repo: inspect TODO.md, PRs, tags
Repo-->>Agent: status (open PR, merged, tag)
Agent->>SessionMgr: evaluate completion signals
SessionMgr-->>Agent: session_complete? (yes/no)
alt complete
Agent->>User: suggest next steps (merge, release, handoff)
Agent->>Terminal: suggest spawn commands (tab, background, worktree)
else incomplete
Agent->>User: list remaining tasks and warnings (context limit)
end
Estimated code review effort🎯 3 (Moderate) | ⏱️ ~20 minutes Poem
🚥 Pre-merge checks | ✅ 3✅ Passed checks (3 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
Summary of ChangesHello @marcusquinn, 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 significantly upgrades the system's session management capabilities by enabling agents to automatically recognize session completion and facilitate the initiation of new or parallel work streams. This enhancement aims to improve context handling, reduce manual overhead, and provide structured guidance for managing complex, multi-task workflows, ultimately leading to more efficient and focused agent operations. 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
|
🔍 Code Quality Report�[0;35m[MONITOR]�[0m Code Review Monitoring Report �[0;34m[INFO]�[0m Latest Quality Status: �[0;34m[INFO]�[0m Recent monitoring activity: 📈 Current Quality Metrics
Generated on: Sat Jan 10 23:36:17 UTC 2026 Generated by AI DevOps Framework Code Review Monitoring |
![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 comprehensive documentation for session management and parallel work spawning. The changes are well-structured across several new and updated markdown files, providing clear guidance for agents on detecting session completion and creating new work sessions. I've identified a few areas for improvement to enhance the clarity and correctness of the provided examples and scripts. My main suggestions focus on making the example script in session-manager.md more robust, ensuring consistency in shell command examples, and improving placeholder usage for project paths.
| if [[ "$incomplete" == "0" && "$pr_state" == "MERGED" ]]; then | ||
| echo "" | ||
| echo "Session appears complete. Consider:" | ||
| echo " 1. Run @agent-review" | ||
| echo " 2. Start new session" | ||
| fi |
There was a problem hiding this comment.
The logic in this script to detect session completion is quite specific, only checking for completed tasks and a merged PR. It doesn't use the version and latest_tag variables it collects, nor does it consider other completion signals mentioned in the documentation (e.g., release published, or tasks completed without a PR). To make this a more robust example for agents to follow, consider expanding the conditional logic to cover more scenarios described in the "Automatic Signals" table.
.agent/tools/opencode/opencode.md
Outdated
| # macOS Terminal.app | ||
| osascript -e 'tell application "Terminal" to do script "cd ~/Git/project && opencode"' |
There was a problem hiding this comment.
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.
| gnome-terminal --tab -- bash -c "cd ~/Git/project && opencode; exec bash" | ||
|
|
||
| # Konsole | ||
| konsole --new-tab -e bash -c "cd ~/Git/project && opencode" |
There was a problem hiding this comment.
The provided konsole command will cause the new tab to close as soon as the opencode process finishes. This is inconsistent with the gnome-terminal example, which uses exec bash to keep the tab open for further interaction. For a consistent user experience across terminals, you should add exec bash to this command as well.
| konsole --new-tab -e bash -c "cd ~/Git/project && opencode" | |
| konsole --new-tab -e bash -c "cd ~/Git/project && opencode; exec bash" |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 5
🤖 Fix all issues with AI agents
In @.agent/workflows/ralph-loop.md:
- Around line 347-410: Duplicate session-spawning patterns appear across
ralph-loop.md, session-manager.md, tools/opencode/opencode.md, and AGENTS.md;
consolidate by keeping session-manager.md as the single canonical reference for
spawning patterns (background exec, macOS Terminal/osascript, worktrees, Linux
variants), remove the duplicated boilerplate from ralph-loop.md and
tools/opencode/opencode.md and replace it with a short pointer to
session-manager.md, move the workflow-specific quality-loop-helper.sh
integration snippet from ralph-loop.md into session-manager.md (preserve its
exact commands and context) and add brief cross-reference lines in ralph-loop.md
and AGENTS.md that link to session-manager.md for details while retaining
ralph-loop.md’s unique guidance about quality-loop-helper.sh usage.
In @.agent/workflows/session-manager.md:
- Around line 138-142: The AppleScript target in spawn_iterm_tab currently uses
the incorrect application name "iTerm2"; update the osascript command inside the
spawn_iterm_tab function to target "iTerm" instead so AppleScript will find the
app. Keep the same variables (dir, cmd) and the rest of the command structure
but replace the application string from "iTerm2" to "iTerm" in the osascript -e
call.
- Around line 246-252: The Related section lists several docs but doesn't state
hierarchy; update the Related block so it clearly marks AGENTS.md as the
authoritative source and that this session-manager workflow is supplementary,
and add a line stating that if guidance conflicts, AGENTS.md takes precedence
over entries like workflows/worktree.md, workflows/ralph-loop.md,
tools/build-agent/agent-review.md, and tools/opencode/opencode.md; keep the
existing list but prepend a short sentence like "AGENTS.md is the single source
of truth for agent behavior; this document is supplementary and defers to
AGENTS.md where they differ."
- Around line 1-11: Update the osascript example that opens a new iTerm tab:
replace the application name "iTerm2" with "iTerm" in the osascript command
string used to create a tab (the line containing osascript -e "tell application
\"iTerm2\" ..."). Ensure the command now uses "tell application \"iTerm\"" so
macOS resolves the correct bundle identifier.
🧹 Nitpick comments (1)
.agent/workflows/session-manager.md (1)
212-222: Refine language for formal consistency in @agent-review suggestion list.Per static analysis feedback, line 218 could use more formal wording. Currently "Document release learnings" uses a slightly informal tone in a formal list context.
💬 Proposed refinement
1. **After PR merge** - Capture what worked in the PR process - 2. **After release** - Document release learnings + 2. **After release** - Capture release learnings 3. **After fixing multiple issues** - Pattern recognition opportunityAlternatives: "Record release learnings" or "Synthesize release learnings" also work, but "Capture" maintains consistency with line 216.
📜 Review details
Configuration used: Path: .coderabbit.yaml
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (5)
.agent/AGENTS.md.agent/tools/build-agent/agent-review.md.agent/tools/opencode/opencode.md.agent/workflows/ralph-loop.md.agent/workflows/session-manager.md
🧰 Additional context used
🧠 Learnings (9)
📓 Common learnings
Learnt from: CR
Repo: marcusquinn/aidevops PR: 0
File: CLAUDE.md:0-0
Timestamp: 2025-11-29T04:34:27.158Z
Learning: All instructions, documentation, and operational guidance should be maintained in AGENTS.md as the single source of truth
Learnt from: CR
Repo: marcusquinn/aidevops PR: 0
File: GEMINI.md:0-0
Timestamp: 2025-11-29T04:34:30.742Z
Learning: Maintain all instructions, documentation, and operational guidance in AGENTS.md as the single source of truth
📚 Learning: 2025-12-22T01:24:53.937Z
Learnt from: CR
Repo: marcusquinn/aidevops PR: 0
File: templates/home/AGENTS.md:0-0
Timestamp: 2025-12-22T01:24:53.937Z
Learning: Follow all security protocols and working directory specifications defined in ~/Git/aidevops/AGENTS.md
Applied to files:
.agent/tools/opencode/opencode.md.agent/workflows/session-manager.md.agent/AGENTS.md
📚 Learning: 2026-01-06T15:57:56.008Z
Learnt from: CR
Repo: marcusquinn/aidevops PR: 0
File: AGENTS.md:0-0
Timestamp: 2026-01-06T15:57:56.008Z
Learning: Applies to **/AGENTS.md : Limit root AGENTS.md to ~50-100 max instructions with universal applicability to >80% of tasks
Applied to files:
.agent/tools/opencode/opencode.md.agent/workflows/session-manager.md.agent/tools/build-agent/agent-review.md.agent/AGENTS.md
📚 Learning: 2025-11-29T04:34:27.158Z
Learnt from: CR
Repo: marcusquinn/aidevops PR: 0
File: CLAUDE.md:0-0
Timestamp: 2025-11-29T04:34:27.158Z
Learning: All instructions, documentation, and operational guidance should be maintained in AGENTS.md as the single source of truth
Applied to files:
.agent/workflows/session-manager.md.agent/tools/build-agent/agent-review.md.agent/AGENTS.md
📚 Learning: 2025-11-29T04:34:42.033Z
Learnt from: CR
Repo: marcusquinn/aidevops PR: 0
File: AGENT.md:0-0
Timestamp: 2025-11-29T04:34:42.033Z
Learning: Reference AGENTS.md (authoritative) instead of AGENT.md for AI assistant guidance
Applied to files:
.agent/tools/build-agent/agent-review.md.agent/AGENTS.md
📚 Learning: 2025-11-29T04:34:30.742Z
Learnt from: CR
Repo: marcusquinn/aidevops PR: 0
File: GEMINI.md:0-0
Timestamp: 2025-11-29T04:34:30.742Z
Learning: Reference AGENTS.md for authoritative AI assistant guidance instead of GEMINI.md
Applied to files:
.agent/tools/build-agent/agent-review.md.agent/AGENTS.md
📚 Learning: 2025-11-29T04:34:30.742Z
Learnt from: CR
Repo: marcusquinn/aidevops PR: 0
File: GEMINI.md:0-0
Timestamp: 2025-11-29T04:34:30.742Z
Learning: Maintain all instructions, documentation, and operational guidance in AGENTS.md as the single source of truth
Applied to files:
.agent/tools/build-agent/agent-review.md.agent/AGENTS.md
📚 Learning: 2026-01-06T15:57:56.007Z
Learnt from: CR
Repo: marcusquinn/aidevops PR: 0
File: AGENTS.md:0-0
Timestamp: 2026-01-06T15:57:56.007Z
Learning: Applies to **/.agent/scripts/linters-local.sh : Run quality checks before committing using .agent/scripts/linters-local.sh
Applied to files:
.agent/tools/build-agent/agent-review.md
📚 Learning: 2026-01-06T15:57:56.008Z
Learnt from: CR
Repo: marcusquinn/aidevops PR: 0
File: AGENTS.md:0-0
Timestamp: 2026-01-06T15:57:56.008Z
Learning: Applies to **/AGENTS.md : Use progressive disclosure in AGENTS.md with pointers to subagents rather than inline content
Applied to files:
.agent/AGENTS.md
🪛 LanguageTool
.agent/workflows/session-manager.md
[style] ~218-~218: Consider using a different verb for a more formal wording.
Context: ...- Document release learnings 3. After fixing multiple issues - Pattern recognition...
(FIX_RESOLVE)
⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (1)
- GitHub Check: Codacy Static Code Analysis
🔇 Additional comments (4)
.agent/AGENTS.md (1)
246-255: Intentional cross-reference with opencode.md (not duplication).The worktree spawning example here serves as quick reference in root AGENTS.md. The comprehensive "Spawning Parallel Sessions" section in
tools/opencode/opencode.md(lines 620-694) provides the detailed patterns for OpenCode users. This is appropriate scope separation—no consolidation needed..agent/tools/build-agent/agent-review.md (1)
59-86: Well-structured agent-review trigger guidance with clear suggestion format.The section provides concrete signals and a consistent template for end-of-session suggestions. The reference to
workflows/session-manager.mdappropriately delegates comprehensive session lifecycle details including completion detection, suggestion templates, and session spawning patterns..agent/tools/opencode/opencode.md (1)
620-694: Comprehensive parallel session patterns with well-documented examples for each terminal/workflow type.The section covers multiple spawning strategies appropriately scoped for an OpenCode subagent. Terminal automation syntax is correct for macOS Terminal.app, iTerm2, GNOME Terminal, and Kitty. All referenced scripts and workflows exist at the correct distributed paths and are consistent with codebase standards.
.agent/workflows/session-manager.md (1)
223-244: Loop agent integration examples are correct; no placeholder syntax issue exists.The promise format
<promise>PR_MERGED</promise>aligns correctly with the implementations inquality-loop-helper.sh(lines 776, 782) and documented patterns inralph-loop-helper.sh. All referenced helper scripts (worktree-helper.sh,quality-loop-helper.sh,ralph-loop-helper.sh) are present and executable.Note: The example command
worktree-helper.sh add feature/next-featureuses literal values, not placeholder syntax. The worktree-helper accepts branch names directly (e.g.,feature/auth,bugfix/login-timeout). The loop agent references (/preflight-loop,/pr-loop,/postflight-loop) are command references, with actual implementations provided as helper functions in the quality and ralph loop scripts.
| ## 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. |
There was a problem hiding this comment.
🧩 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
fiRepository: 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:
-
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. -
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.
- Fix iTerm application name (iTerm2 → iTerm) in osascript commands - Consolidate spawning patterns to session-manager.md as canonical source - Add AGENTS.md as authoritative source in Related section - Use consistent formal tone (Document → Capture) - Remove duplicate boilerplate from ralph-loop.md and opencode.md Net reduction: -68 lines (consolidation)
|
🔍 Code Quality Report�[0;35m[MONITOR]�[0m Code Review Monitoring Report �[0;34m[INFO]�[0m Latest Quality Status: �[0;34m[INFO]�[0m Recent monitoring activity: 📈 Current Quality Metrics
Generated on: Sat Jan 10 23:45:54 UTC 2026 Generated by AI DevOps Framework Code Review Monitoring |
🤖 Augment PR SummarySummary: This PR adds structured documentation for managing AI “session” lifecycles, including how agents detect natural completion points and how to spin up new/parallel sessions to keep context focused. Changes:
Technical Notes: Documentation-only change; relies on Git worktrees for isolated parallel branch work and 🤖 Was this summary useful? React with 👍 or 👎 |
![augmentcode[bot]](https://avatars.githubusercontent.com/in/1027498?s=60&v=4){kind=small}
|
|
||
| # Check incomplete tasks | ||
| local incomplete | ||
| incomplete=$(grep -c '^\s*- \[ \]' TODO.md 2>/dev/null || echo "0") |
There was a problem hiding this comment.
grep’s default regex doesn’t treat \s as whitespace, and grep -c exits non-zero when there are 0 matches, so || echo "0" can yield 0\n0 and make the [[ "$incomplete" == "0" ]] check fail (also affects the command shown in the “Automatic Signals” table).
🤖 Was this useful? React with 👍 or 👎
There was a problem hiding this comment.
Actionable comments posted: 1
🤖 Fix all issues with AI agents
In @.agent/workflows/session-manager.md:
- Around line 138-146: The AppleScript call in spawn_iterm_tab uses the legacy
application name "iTerm"; change the app identifier to "iTerm2" inside the
osascript string so the command targets the official iTerm2 application (update
the string in the osascript invocation within function spawn_iterm_tab to use
"tell application \"iTerm2\""). Ensure the rest of the AppleScript command
(current window / create tab with default profile command ...) remains
unchanged.
🧹 Nitpick comments (1)
.agent/workflows/session-manager.md (1)
212-221: Minor style suggestion on line 218.LanguageTool suggests considering a different verb for more formal wording in the "Pattern recognition opportunity" line. Consider replacing "Capture" with a more formal alternative like "Document" or "Record" if tighter tone is desired. This is optional.
📜 Review details
Configuration used: Path: .coderabbit.yaml
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (3)
.agent/tools/opencode/opencode.md.agent/workflows/ralph-loop.md.agent/workflows/session-manager.md
🚧 Files skipped from review as they are similar to previous changes (1)
- .agent/tools/opencode/opencode.md
🧰 Additional context used
🧠 Learnings (11)
📓 Common learnings
Learnt from: CR
Repo: marcusquinn/aidevops PR: 0
File: CLAUDE.md:0-0
Timestamp: 2025-11-29T04:34:27.158Z
Learning: All instructions, documentation, and operational guidance should be maintained in AGENTS.md as the single source of truth
Learnt from: CR
Repo: marcusquinn/aidevops PR: 0
File: GEMINI.md:0-0
Timestamp: 2025-11-29T04:34:30.742Z
Learning: Maintain all instructions, documentation, and operational guidance in AGENTS.md as the single source of truth
📚 Learning: 2026-01-06T15:57:56.008Z
Learnt from: CR
Repo: marcusquinn/aidevops PR: 0
File: AGENTS.md:0-0
Timestamp: 2026-01-06T15:57:56.008Z
Learning: Applies to **/AGENTS.md : Limit root AGENTS.md to ~50-100 max instructions with universal applicability to >80% of tasks
Applied to files:
.agent/workflows/ralph-loop.md.agent/workflows/session-manager.md
📚 Learning: 2025-11-29T04:34:27.158Z
Learnt from: CR
Repo: marcusquinn/aidevops PR: 0
File: CLAUDE.md:0-0
Timestamp: 2025-11-29T04:34:27.158Z
Learning: All instructions, documentation, and operational guidance should be maintained in AGENTS.md as the single source of truth
Applied to files:
.agent/workflows/ralph-loop.md.agent/workflows/session-manager.md
📚 Learning: 2025-11-29T04:34:30.742Z
Learnt from: CR
Repo: marcusquinn/aidevops PR: 0
File: GEMINI.md:0-0
Timestamp: 2025-11-29T04:34:30.742Z
Learning: Maintain all instructions, documentation, and operational guidance in AGENTS.md as the single source of truth
Applied to files:
.agent/workflows/ralph-loop.md.agent/workflows/session-manager.md
📚 Learning: 2026-01-06T15:57:56.008Z
Learnt from: CR
Repo: marcusquinn/aidevops PR: 0
File: AGENTS.md:0-0
Timestamp: 2026-01-06T15:57:56.008Z
Learning: Applies to **/AGENTS.md : Use progressive disclosure in AGENTS.md with pointers to subagents rather than inline content
Applied to files:
.agent/workflows/ralph-loop.md.agent/workflows/session-manager.md
📚 Learning: 2025-11-29T04:34:42.033Z
Learnt from: CR
Repo: marcusquinn/aidevops PR: 0
File: AGENT.md:0-0
Timestamp: 2025-11-29T04:34:42.033Z
Learning: Reference AGENTS.md (authoritative) instead of AGENT.md for AI assistant guidance
Applied to files:
.agent/workflows/ralph-loop.md.agent/workflows/session-manager.md
📚 Learning: 2026-01-06T15:57:56.009Z
Learnt from: CR
Repo: marcusquinn/aidevops PR: 0
File: AGENTS.md:0-0
Timestamp: 2026-01-06T15:57:56.009Z
Learning: Search with rg "pattern" .agent/ before adding new instructions to avoid duplicates
Applied to files:
.agent/workflows/ralph-loop.md
📚 Learning: 2025-11-29T04:34:42.033Z
Learnt from: CR
Repo: marcusquinn/aidevops PR: 0
File: AGENT.md:0-0
Timestamp: 2025-11-29T04:34:42.033Z
Learning: Maintain all AI assistant instructions, documentation, and operational guidance in AGENTS.md as the single source of truth
Applied to files:
.agent/workflows/ralph-loop.md.agent/workflows/session-manager.md
📚 Learning: 2026-01-06T15:57:56.008Z
Learnt from: CR
Repo: marcusquinn/aidevops PR: 0
File: AGENTS.md:0-0
Timestamp: 2026-01-06T15:57:56.008Z
Learning: Applies to **/AGENTS.md : Include code examples in AGENTS.md only when authoritative, otherwise use file:line references
Applied to files:
.agent/workflows/session-manager.md
📚 Learning: 2025-11-29T04:34:30.742Z
Learnt from: CR
Repo: marcusquinn/aidevops PR: 0
File: GEMINI.md:0-0
Timestamp: 2025-11-29T04:34:30.742Z
Learning: Reference AGENTS.md for authoritative AI assistant guidance instead of GEMINI.md
Applied to files:
.agent/workflows/session-manager.md
📚 Learning: 2025-12-22T01:24:53.937Z
Learnt from: CR
Repo: marcusquinn/aidevops PR: 0
File: templates/home/AGENTS.md:0-0
Timestamp: 2025-12-22T01:24:53.937Z
Learning: Follow all security protocols and working directory specifications defined in ~/Git/aidevops/AGENTS.md
Applied to files:
.agent/workflows/session-manager.md
🪛 LanguageTool
.agent/workflows/session-manager.md
[style] ~218-~218: Consider using a different verb for a more formal wording.
Context: ... - Capture release learnings 3. After fixing multiple issues - Pattern recognition...
(FIX_RESOLVE)
⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (1)
- GitHub Check: Codacy Static Code Analysis
🔇 Additional comments (5)
.agent/workflows/session-manager.md (3)
1-76: ✓ Well-structured session detection guidance.The quick reference, signals table, and check script form a clear, actionable foundation. The
write: false, edit: falsetooling config appropriately restricts this to a guidance document.
185-244: ✓ Practical handoff and integration patterns.The session handoff pattern and loop agent integration are well-executed. The explicit deference to AGENTS.md (line 248) is excellent for maintaining single-source-of-truth discipline.
246-253: Consolidate session completion and spawn guidance to eliminate duplication across workflow files.The audit confirms "duplicated guidance in several workflow/tool docs": Session Completion references appear in both
ralph-loop.mdandsession-manager.md, while spawn session patterns are duplicated acrossopencode.md,ralph-loop.md, andsession-manager.md. Additionally,AGENTS.mdcontains its own "Session Completion & Parallel Work" section.Per the learnings,
AGENTS.mdshould be the single source of truth with brief, progressive disclosure (~50-100 instructions). Consolidate by:
- Keeping
AGENTS.mdwith minimal overview + pointer to authoritative reference- Making
session-manager.mdthe canonical source for detailed session patterns- Removing duplicate session completion and spawning guidance from
ralph-loop.mdandopencode.md(replace with references to session-manager.md)This eliminates redundancy while maintaining the SSoT architecture.
⛔ Skipped due to learnings
Learnt from: CR Repo: marcusquinn/aidevops PR: 0 File: CLAUDE.md:0-0 Timestamp: 2025-11-29T04:34:27.158Z Learning: All instructions, documentation, and operational guidance should be maintained in AGENTS.md as the single source of truthLearnt from: CR Repo: marcusquinn/aidevops PR: 0 File: GEMINI.md:0-0 Timestamp: 2025-11-29T04:34:30.742Z Learning: Maintain all instructions, documentation, and operational guidance in AGENTS.md as the single source of truthLearnt from: CR Repo: marcusquinn/aidevops PR: 0 File: AGENTS.md:0-0 Timestamp: 2026-01-06T15:57:56.008Z Learning: Applies to **/AGENTS.md : Limit root AGENTS.md to ~50-100 max instructions with universal applicability to >80% of tasksLearnt from: CR Repo: marcusquinn/aidevops PR: 0 File: AGENT.md:0-0 Timestamp: 2025-11-29T04:34:42.033Z Learning: Maintain all AI assistant instructions, documentation, and operational guidance in AGENTS.md as the single source of truthLearnt from: CR Repo: marcusquinn/aidevops PR: 0 File: AGENT.md:0-0 Timestamp: 2025-11-29T04:34:42.033Z Learning: Reference AGENTS.md (authoritative) instead of AGENT.md for AI assistant guidanceLearnt from: CR Repo: marcusquinn/aidevops PR: 0 File: templates/home/AGENTS.md:0-0 Timestamp: 2025-12-22T01:24:53.937Z Learning: Follow all security protocols and working directory specifications defined in ~/Git/aidevops/AGENTS.mdLearnt from: CR Repo: marcusquinn/aidevops PR: 0 File: AGENTS.md:0-0 Timestamp: 2026-01-06T15:57:56.008Z Learning: Applies to **/AGENTS.md : Include code examples in AGENTS.md only when authoritative, otherwise use file:line referencesLearnt from: CR Repo: marcusquinn/aidevops PR: 0 File: GEMINI.md:0-0 Timestamp: 2025-11-29T04:34:30.742Z Learning: Reference AGENTS.md for authoritative AI assistant guidance instead of GEMINI.mdLearnt from: CR Repo: marcusquinn/aidevops PR: 0 File: AGENTS.md:0-0 Timestamp: 2026-01-06T15:57:56.008Z Learning: Applies to **/AGENTS.md : Use progressive disclosure in AGENTS.md with pointers to subagents rather than inline contentLearnt from: CR Repo: marcusquinn/aidevops PR: 0 File: AGENTS.md:0-0 Timestamp: 2026-01-06T15:57:56.007Z Learning: Applies to **/setup.sh : Deploy agents locally using ./setup.sh script.agent/workflows/ralph-loop.md (2)
347-389: No action needed. The "Session Completion & Spawning" section (lines 347–389) appears only once in the file. Grep verification confirms a single occurrence of this heading, with no duplicated content elsewhere in.agent/workflows/ralph-loop.md.Likely an incorrect or invalid review comment.
368-380: No action required—session management guidance is architecturally correct.The reference to
workflows/session-manager.mdin ralph-loop.md follows the progressive disclosure pattern already established in./.agent/AGENTS.md(line 257), where high-level session guidance points to session-manager.md for detailed spawning patterns. The architecture complies with learnings: AGENTS.md is the authoritative source with concise directives, and session-manager.md is a properly structured subagent workflow with operational details—not parallel guidance.
| spawn_iterm_tab() { | ||
| local dir="${1:-$(pwd)}" | ||
| local cmd="${2:-opencode}" | ||
| osascript -e "tell application \"iTerm\" to tell current window to create tab with default profile command \"cd '$dir' && $cmd\"" | ||
| } | ||
|
|
||
| # Usage | ||
| spawn_terminal_tab ~/Git/project-feature-auth | ||
| ``` |
There was a problem hiding this comment.
🧩 Analysis chain
🌐 Web query:
iTerm2 AppleScript application name "tell application"
💡 Result:
Use "iTerm2" in your tell block (official iTerm2 docs use tell application "iTerm2"). If that doesn't work (older installs/scripts), try "iTerm" as a fallback — some examples and community scripts still reference "iTerm". [1][2][6]
Sources:
- iTerm2 scripting docs (examples using "iTerm2"). [1]
- iTerm2 reference/docs. [2]
- Stack Overflow example showing some scripts use "iTerm" (fallback). [6]
Use official iTerm2 application identifier in AppleScript.
Line 141 should use tell application "iTerm2" instead of "iTerm". Official iTerm2 documentation specifies "iTerm2" as the correct application name in AppleScript; "iTerm" is only a fallback for legacy installations and may fail on current versions.
Code update
- osascript -e "tell application \"iTerm\" to tell current window to create tab with default profile command \"cd '$dir' && $cmd\""
+ osascript -e "tell application \"iTerm2\" to tell current window to create tab with default profile command \"cd '$dir' && $cmd\""📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| spawn_iterm_tab() { | |
| local dir="${1:-$(pwd)}" | |
| local cmd="${2:-opencode}" | |
| osascript -e "tell application \"iTerm\" to tell current window to create tab with default profile command \"cd '$dir' && $cmd\"" | |
| } | |
| # Usage | |
| spawn_terminal_tab ~/Git/project-feature-auth | |
| ``` | |
| spawn_iterm_tab() { | |
| local dir="${1:-$(pwd)}" | |
| local cmd="${2:-opencode}" | |
| osascript -e "tell application \"iTerm2\" to tell current window to create tab with default profile command \"cd '$dir' && $cmd\"" | |
| } | |
| # Usage | |
| spawn_terminal_tab ~/Git/project-feature-auth |
🤖 Prompt for AI Agents
In @.agent/workflows/session-manager.md around lines 138 - 146, The AppleScript
call in spawn_iterm_tab uses the legacy application name "iTerm"; change the app
identifier to "iTerm2" inside the osascript string so the command targets the
official iTerm2 application (update the string in the osascript invocation
within function spawn_iterm_tab to use "tell application \"iTerm2\""). Ensure
the rest of the AppleScript command (current window / create tab with default
profile command ...) remains unchanged.
marcusquinn
left a comment
marcusquinn
left a comment
There was a problem hiding this comment.
Regarding the iTerm/iTerm2 naming: Both work in AppleScript. The app bundle is /Applications/iTerm.app but responds to both tell application "iTerm" and tell application "iTerm2". The current code uses "iTerm" which matches the bundle name and works correctly. No change needed.
1 participant
Summary
Add session completion detection and parallel session spawning across all agents to improve context management and enable focused parallel work.
Changes
New File
workflows/session-manager.md(252 lines) - Full session lifecycle guidanceUpdated Files
AGENTS.mdagent-review.mdopencode.mdralph-loop.mdFeatures
Session Completion Detection
Agents now recognize completion signals:
[x]in TODO.mdSuggestion Format
Parallel Session Spawning
Multiple methods supported:
Testing
Related
Implements feature requested in conversation - agents should suggest @agent-review and new sessions at natural completion points.
Summary by CodeRabbit
✏️ Tip: You can customize this high-level summary in your review settings.