MadAppGang

session-isolation

@MadAppGang/session-isolation
MadAppGang
196
19 forks
Updated 1/6/2026
View on GitHub

Session Isolation Pattern: Session-based artifact isolation for multi-artifact workflows. Use when orchestrating workflows that generate multiple files (designs, reviews, reports) to prevent file collisions across concurrent or sequential sessions.

Installation

$skills install @MadAppGang/session-isolation
Claude Code
Cursor
Copilot
Codex
Antigravity

Details

RepositoryMadAppGang/claude-code
Pathplugins/orchestration/skills/session-isolation/SKILL.md
Branchmain
Scoped Name@MadAppGang/session-isolation

Usage

After installing, this skill will be available to your AI coding assistant.

Verify installation:

skills list

Skill Instructions

Session Isolation Pattern

Session-based artifact isolation for multi-artifact workflows. Use when orchestrating workflows that generate multiple files (designs, reviews, reports) to prevent file collisions across concurrent or sequential sessions.

Problem

When multiple workflows run (even sequentially), artifacts with the same name collide:

Session 1 (SEO): writes ai-docs/plan-review-grok.md
Session 2 (API): writes ai-docs/plan-review-grok.md  <-- OVERWRITES!

Solution

Use unique session folders to isolate artifacts:

ai-docs/sessions/agentdev-seo-20260105-143022-a3f2/
├── session-meta.json      # Session tracking
├── design.md              # Primary artifact
├── reviews/
│   ├── plan-review/       # Plan review phase
│   │   ├── internal.md
│   │   ├── grok.md
│   │   └── consolidated.md
│   └── impl-review/       # Implementation review phase
│       ├── internal.md
│       └── consolidated.md
└── report.md              # Final report

Implementation Pattern

1. Session Initialization (Orchestrator)

Add to Phase 0 of your orchestrator command:

# Generate unique session path
TARGET_SLUG=$(echo "${TARGET_NAME:-workflow}" | tr '[:upper:] ' '[:lower:]-' | sed 's/[^a-z0-9-]//g' | head -c20)
SESSION_BASE="${WORKFLOW_TYPE}-${TARGET_SLUG}-$(date +%Y%m%d-%H%M%S)-$(head -c4 /dev/urandom | xxd -p | head -c4)"
SESSION_PATH="ai-docs/sessions/${SESSION_BASE}"

# Create directory structure
mkdir -p "${SESSION_PATH}/reviews/plan-review" \
         "${SESSION_PATH}/reviews/impl-review" || {
  echo "Warning: Cannot create session directory, using legacy mode"
  SESSION_PATH="ai-docs"
}

# Create session metadata (if not legacy mode)
if [[ "$SESSION_PATH" != "ai-docs" ]]; then
  cat > "${SESSION_PATH}/session-meta.json" << EOF
{
  "session_id": "${SESSION_BASE}",
  "type": "${WORKFLOW_TYPE}",
  "target": "${USER_REQUEST}",
  "started_at": "$(date -u +%Y-%m-%dT%H:%M:%SZ)",
  "status": "in_progress"
}
EOF
fi

2. Pass SESSION_PATH to Sub-Agents

Include in all agent prompts:

SESSION_PATH: ${SESSION_PATH}

{actual task description}

Save output to: ${SESSION_PATH}/{artifact_path}

3. Sub-Agent SESSION_PATH Detection

Add to agent <critical_constraints>:

<session_path_support>
  **Check for Session Path Directive**

  If prompt contains `SESSION_PATH: {path}`:
  1. Extract the session path
  2. Use it for all output file paths
  3. Primary artifact: `${SESSION_PATH}/{type}.md`
  4. Reviews: `${SESSION_PATH}/reviews/{phase}/{model}.md`

  **If NO SESSION_PATH**: Use legacy paths (ai-docs/)
</session_path_support>

4. Session Completion

Update metadata when workflow completes:

if [[ -f "${SESSION_PATH}/session-meta.json" ]]; then
  jq '.status = "completed" | .completed_at = (now | strftime("%Y-%m-%dT%H:%M:%SZ"))' \
    "${SESSION_PATH}/session-meta.json" > "${SESSION_PATH}/session-meta.json.tmp" && \
  mv "${SESSION_PATH}/session-meta.json.tmp" "${SESSION_PATH}/session-meta.json"
fi

Artifact Path Mapping

Artifact TypeSESSION_PATH FormatLegacy Format
Design/Context${SESSION_PATH}/design.mdai-docs/agent-design-{name}.md
Plan Review${SESSION_PATH}/reviews/plan-review/{model}.mdai-docs/plan-review-{model}.md
Impl Review${SESSION_PATH}/reviews/impl-review/{model}.mdai-docs/impl-review-{model}.md
Consolidated${SESSION_PATH}/reviews/{phase}/consolidated.mdai-docs/{phase}-consolidated.md
Final Report${SESSION_PATH}/report.mdai-docs/{workflow}-report-{name}.md

Backward Compatibility

Legacy Mode Triggers:

  1. SESSION_PATH not provided in prompt
  2. Directory creation fails (permissions)
  3. Explicit LEGACY_MODE: true in prompt

Behavior:

  • Fall back to flat ai-docs/ paths
  • Log warning about legacy mode
  • All features still work, just without isolation

Session Metadata Schema

{
  "session_id": "agentdev-seo-20260105-143022-a3f2",
  "type": "agentdev",
  "target": "SEO agent improvements",
  "started_at": "2026-01-05T14:30:22Z",
  "completed_at": "2026-01-05T15:45:30Z",
  "status": "completed",
  "phases_completed": ["init", "design", "plan-review", "implementation", "quality-review"],
  "models_used": ["claude-embedded", "x-ai/grok-code-fast-1", "google/gemini-3-pro"],
  "artifacts": {
    "design": "design.md",
    "plan_reviews": ["reviews/plan-review/internal.md", "reviews/plan-review/grok.md"],
    "impl_reviews": ["reviews/impl-review/internal.md", "reviews/impl-review/gemini.md"],
    "report": "report.md"
  }
}

Plugins Using Session Isolation

PluginCommandSession Pattern
agentdev/developagentdev-{target}-{timestamp}-{random}
frontend/review, /implementreview-{timestamp}-{random}
seo/review, /alternativesseo-review-{timestamp}-{random}

Best Practices

  1. Always initialize early: Session creation should happen in Phase 0
  2. Include SESSION_PATH in all prompts: Sub-agents need it for output paths
  3. Use descriptive slugs: Include workflow type and target in folder name
  4. Update metadata on completion: Track status changes
  5. Fallback gracefully: Never fail the workflow due to session creation issues

More by MadAppGang

View all
external-model-selection
1,265

Choose optimal external AI models for code analysis, bug investigation, and architectural decisions. Use when consulting multiple LLMs via claudish, comparing model perspectives, or investigating complex Go/LSP/transpiler issues. Provides empirically validated model rankings (91/100 for MiniMax M2, 83/100 for Grok Code Fast) and proven consultation strategies based on real-world testing.

claudish-usage
247

CRITICAL - Guide for using Claudish CLI ONLY through sub-agents to run Claude Code with OpenRouter models (Grok, GPT-5, Gemini, MiniMax). NEVER run Claudish directly in main context unless user explicitly requests it. Use when user mentions external AI models, Claudish, OpenRouter, or alternative models. Includes mandatory sub-agent delegation patterns, agent selection guide, file-based instructions, and strict rules to prevent context window pollution.

model-tracking-protocol
196

MANDATORY tracking protocol for multi-model validation. Creates structured tracking tables BEFORE launching models, tracks progress during execution, and ensures complete results presentation. Use when running 2+ external AI models in parallel. Trigger keywords - "multi-model", "parallel review", "external models", "consensus", "model tracking".

xml-standards
196

XML tag structure patterns for Claude Code agents and commands. Use when designing or implementing agents to ensure proper XML structure following Anthropic best practices.