shynlee04/hivemind-plugin/session-foundation

Session Foundation — Session Governance Core

1. Overview (30-second read)

Session governance is the practice of discovering what work is happening across the project, understanding how sessions relate to each other, and deciding what to resume or extend. This skill provides a structured workflow using operational tools — no aspirational capabilities, no undocumented behavior.

Core principle: This is a read-side skill. It discovers, reads, and aggregates session state. It does NOT mutate sessions or create delegations directly (that is the write-side, handled by other skills and tools).

What you can do with this skill:

• Discover all sessions that have ever run on the project
• Filter sessions by status, agent type, depth, or time range
• Search session content (including child .json files)
• Navigate the delegation hierarchy (parents, children, depth)
• Aggregate cross-session data by status or agent type
• Build a unified session view from multiple data roots
• Check delegation status and verify resumability
• Stack new work onto existing sessions

2. Core Workflow (2-minute read)

The session governance loop has four phases. Follow them in order when you need to understand the session landscape.

Phase 1: Discover — "What sessions exist?"

session-tracker({action: "list-sessions"})

Returns every session with status, depth, and timestamps. Start here to get the full picture.

To find active sessions specifically:

session-tracker({action: "filter-sessions", status: "active"})

Filters by status, agent type, depth range, or time range. Replace the old manual discovery approach — this is the correct discovery tool.

To search session content:

session-tracker({action: "search-sessions", query: "<term>", limit: 10})

Searches across session .md files AND child .json files including lastMessage, turn.content, and journey[].content. Use this when you need to find sessions by topic rather than metadata.

Phase 2: Navigate — "How are sessions related?"

session-hierarchy({action: "get-children", sessionId: "<id>"})
session-hierarchy({action: "get-manifest", sessionId: "<id>"})
session-hierarchy({action: "get-parent-chain", sessionId: "<id>"})
session-hierarchy({action: "get-delegation-depth", sessionId: "<id>"})

`get-manifest` is the preferred action for inspecting delegation trees. It reads a flattened child list — no recursive tree walking needed.

Use get-parent-chain to trace a session back to its root. Use get-delegation-depth for a quick depth check.

Phase 3: Aggregate — "What patterns exist?"

session-context({action: "aggregate", groupBy: "status"})
session-context({action: "aggregate", groupBy: "subagentType"})
session-context({action: "find-related", sessionId: "<id>"})
session-context({action: "cross-reference", term: "<tool-or-term>"})
session-context({action: "synthesize-context", sessionIds: ["<id1>", "<id2>"]})

Use aggregate to get counts — how many sessions per status, per agent type. Use find-related to discover sessions sharing tool usage patterns. Use synthesize-context to build a unified picture from multiple sessions.

Phase 4: Act — "What do I do next?"

Once you understand the session landscape:

1. For a unified view of a specific session:

`` hivemind-session-view({action: "get", sessionId: "<id>"}) ` Returns nested data: {session, delegations}`. Reads from session data, delegation records, and trajectory checkpoints in a single call.

1. To check if a delegation is still running:

`` delegation-status({action: "status", delegationId: "<id>"}) ``

1. To continue work or verify completeness:

• Resume a session: via task tool with task_id (PREFERRED — full control)
• Stack new work onto session: via task tool with task_id (PREFERRED) or delegate-task with context: '{"parentSessionId": "<id>"}' (async background only)
• Run a command: via execute-slash-command
• Discover available commands: via hivemind-command-engine

3. Tool Reference (quick lookup)

3.1 session-tracker — Session Discovery

Key distinction: filter-sessions is the discovery tool. search-sessions is the research tool. Neither performs resume — they provide metadata for you to decide.

3.2 session-hierarchy — Delegation Navigation

3.3 session-context — Cross-Session Intelligence

3.4 hivemind-session-view — Unified View

Use this when you need a unified view. For simple queries (just status, just depth), use the specific tool action instead to avoid over-fetching.

3.5 delegate-task — Session Stacking

Use the parentSessionId pattern to attach new work as a child of an existing session. This creates a proper delegation hierarchy without needing to resume the original session.

3.6 delegation-status — Delegation Health

4. Session Resume & Stacking Guidance

When to Resume vs Stack

Resume Mechanics

task({subagent_type: "<agentType>", task_id: "<sessionId>", prompt: "Continue"})

Critical: Resume depends on SDK support. If the SDK does not support full context restoration via task_id, the resume may start a fresh session instead of continuing the existing one.

Verify before resuming:

1. Check session status via session-tracker({action: "get-status", sessionId})
2. Verify delegation exists via delegation-status({action: "status", delegationId})
3. Attempt resume with a specific, bounded prompt — not just "Continue"

Stacking Mechanics

delegate-task({
  agent: "<specialist>",
  prompt: "<bounded task>",
  context: '{"parentSessionId": "<existing-session-id>"}'
})

The parentSessionId context parameter chains the new delegation as a child of the specified session. Do NOT inject the session ID into the prompt text — that creates an independent session without hierarchy tracking.

5. Anti-Patterns

6. Self-Correction — When Things Go Wrong

Mode 1: Tool Returns Empty Results

Symptom: filter-sessions or list-sessions returns zero sessions.

Diagnosis:

1. Check if session-tracker data exists on disk:

`` glob(".hivemind/session-tracker/*/") ``

1. If directories exist, the tool may need a different query — try

search-sessions with a broad query

1. If no directories exist, no sessions have been tracked on this project yet

Mode 2: Session Not Found

Symptom: get-status({sessionId}) returns not-found.

Diagnosis:

1. Verify session ID format — it usually starts with ses_ or is a UUID
2. Try list-sessions to get the exact session ID format used in this project
3. The session may have been cleaned up or never tracked

Mode 3: Resume Fails

Symptom: task(task_id=...) starts a new session instead of resuming.

Diagnosis:

1. Check SDK version in node_modules/@opencode-ai/sdk/package.json
2. If SDK version < 2.x, task_id resume may not preserve context
3. Fall back to stacking via delegate-task(parentSessionId=...)
4. If both fail, create a fresh delegation and reference the original session

in the prompt

Mode 4: Delegation Depth Too Deep

Symptom: Delegation chain exceeds reasonable depth (recommended max: 3).

Diagnosis:

1. Check depth: session-hierarchy({action: "get-delegation-depth", sessionId})
2. If depth >= 3, the chain is too deep for reliable operation
3. Escalate to the user: "This chain is too deep. Consider an architectural

split or restart from root with accumulated context."

1. Use get-manifest to show the full tree
2. Use synthesize-context to aggregate work across the chain

7. References — Progressive Disclosure

These reference files provide deeper detail. Load them on demand, not all at once.