Session Isolation

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/plugin-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

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": "plugin-seo-20260105-143022-a3f2",
  "type": "plugin",
  "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", "grok", "gemini"],
  "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

Team Session Example

The /team command creates a session for multi-model blind voting:

ai-docs/sessions/team-stats-validation-20260209-143022-a3f2/
├── input.md                # The task/vote prompt every model receives
├── manifest.json           # anonymous id → model (the de-anonymiser) + shuffleOrder
├── status.json             # per-slot state, updated as the run proceeds
├── work/01/ .. work/NN/    # one scratch dir per slot, by anonymous id
├── response-01.md          # one response per model, named by ANONYMOUS id
├── response-02.md
├── response-03.md
├── errors/01.log           # stderr, written only for a slot that failed
├── judging/                # judge prompts and votes (run-and-judge mode)
└── verdict.md              # aggregated verdict with vote breakdown

The team tool owns this layout — do not invent filenames for it.

Responses are named by anonymous id, never by model. That is the mechanism of the blind vote, not a cosmetic choice: response-03.md reveals nothing about who wrote it, and only manifest.json can map it back. A layout like grok-result.md / gemini-result.md — which earlier versions of this document showed — de-anonymises the panel before the verdict and must not be reintroduced.

Native Claude is one of these slots. internal goes in the models array and gets a response-NN.md like everyone else. A separate internal-result.md written by a background Agent is the OLD split, and it sits outside the anonymised set and outside require_pattern — an unvalidated reviewer beside validated ones.

Key difference from other plugins: Team sessions contain results from multiple AI models investigating the same task independently. Each model writes to its own result file to prevent conflicts during parallel execution.

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