Sessions & Entries

Workflow MCP organizes work into sessions that contain entries.

Sessions

A session is a focused work period on a specific topic within a workflow phase.

Session Lifecycle

Start - Create session with start_session
Work - Log entries with log_entry
End - Complete or pause with end_session

Session Files

Sessions are persisted to markdown files:

projects/
  research/
    RESEARCH_AUTH-SYSTEM_2026-01-12.md
    RESEARCH_AUTH-SYSTEM_2026-01-12_2.md  # Second session same day (iteration 2)
  plans/
    PLAN_AUTH-SYSTEM_2026-01-12.md
  implementations/
    IMPL_AUTH-SYSTEM_2026-01-12.md

Session State

The current session state is stored in .claude/workflow/.session-state.json:

{
  "context": {
    "command": "/implement",
    "topic": "AUTH-SYSTEM",
    "extraContext": "Focus on OAuth2 integration",
    "dps": 1,
    "logPath": "./projects/implementations/IMPL_AUTH-SYSTEM_2026-01-12.md",
    "inputFiles": {
      "research": "./projects/research/RESEARCH_AUTH-SYSTEM_2026-01-12.md",
      "plan": "./projects/plans/PLAN_AUTH-SYSTEM_2026-01-12.md"
    },
    "iteration": 1
  },
  "entryCounters": {
    "IMP": 5,
    "UFB": 2
  },
  "blockers": [],
  "startTime": "2026-01-12 10:30",
  "status": "In Progress"
}

Extra Context

You can provide additional context when starting a session:

/workflow:implement AUTH-SYSTEM focus on the login flow first

This context is stored in the session and included in the log file header.

Iteration Tracking

When you start multiple sessions for the same topic on the same day, the system tracks this:

Iteration 1: First session of the day - normal start
Iteration 2+: System prompts for reflection

When iteration > 1, you’ll see a reflection prompt:

## ⚠️ Multiple Sessions Detected (Iteration 2)

This is session **#2** for `/workflow:research AUTH-SYSTEM` today. Before proceeding, please reflect:

| Possible Reason | If Yes, Consider... |
|-----------------|---------------------|
| **Query misunderstood?** | Clarify the goal before starting |
| **Scope too broad?** | Break into smaller topics |
| **Scope too narrow?** | Expand the topic |
| **Previous session incomplete?** | Consider resuming instead |

This helps identify process issues and encourages better scoping.

Entries

Entries are structured log items within a session.

Entry-IDs

Every entry gets a unique ID in the format: PREFIX-TOPIC-NNN

Examples:

RES-AUTH-SYSTEM-001 - First research finding
PLN-AUTH-SYSTEM-003 - Third planning decision
IMP-AUTH-SYSTEM-012 - Twelfth implementation task

Entry Types

Tag	Prefix	Purpose
`finding`	RES	Research discoveries
`requirement`	REQ	User requirements (verbatim)
`decision`	PLN	Planning decisions
`task-complete`	IMP	Completed implementation tasks
`user-feedback`	UFB	User input during work
`issue`	IMP	Problems encountered
`blocker`	BLK	Blocking issues
`gap`	GAP-RP	Gaps found in review
`fix`	FIX	Applied fixes
`fault`	DBG	Debug fault reports
`investigation`	DBG	Debug investigations

Cross-Referencing

Use Entry-IDs to connect related items:

// In a decision
fields: {
  ref: "RES-AUTH-SYSTEM-005",
  decision: "Use JWT with refresh tokens",
  rationale: "Based on security requirements from RES-AUTH-SYSTEM-005"
}

Session Resumption

If a session is interrupted:

mcp__workflow__start_session({
  command: "/implement",
  topic: "AUTH-SYSTEM",
  mode: "resume"
})

The session resumes with:

Previous entry counters preserved
Session file updated with resume timestamp
Status changed back to “In Progress”