session-aware

Enforce session type transitions and track per-worktree state in .session-state/session.json.

Updated Aug 27, 2026
One-click install
npx skills add https://github.com/mcj-coder-org/claude-skills --skill session-aware
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: session-aware
Source: https://github.com/mcj-coder-org/claude-skills/tree/main/session-aware
Command: npx skills add https://github.com/mcj-coder-org/claude-skills --skill session-aware

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

This Skill coordinates multiple AI prompts by enforcing session types, tracking progress, and ensuring proper handoffs between skills during development work.

Core Features & Use Cases

  • Session type recognition and transitions across vision, guardrails, plan, brainstorm, whiteboard, and implement
  • Local, per-worktree session state stored in .session-state/session.json
  • Handoff and boundary enforcement to prevent skipped steps
  • Automatic announcements of mode switches and context

Quick Start

Start a session by choosing a mode, for example: vision for a new project, plan for a feature, or implement a task. The skill will announce ENTERING {MODE} mode, create the session state, and delegate to the appropriate sub-skill.

Frequently Asked Questions about session-aware

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I manage session state across multiple prompts in Claude Code?

Session state across multiple prompts is managed by tracking per-worktree progress in a local session.json file and enforcing explicit mode transitions. This prevents skipped steps and maintains context across different development activities.

What are session-aware workflows for AI-assisted development?

Session-aware workflows coordinate multiple AI prompts by enforcing structured session types like vision, plan, and implement. They track progress and ensure proper handoffs between skills to maintain context throughout development phases.

Can I use isolated worktrees to track per-worktree session state?

Yes, isolated worktrees are required to store local per-worktree session state at .session-state/session.json. This setup isolates session tracking data and prevents state conflicts across concurrent development activities.

Do I need YAML frontmatter to coordinate session types and skills?

Yes, a YAML SKILL.md frontmatter with name and description is required to coordinate session types and wrap other skills. This metadata allows the orchestrator to properly delegate prompts and enforce mode transitions.

What is the best way to structure development phases like vision and implement in Claude Code?

The best way to structure development phases is by using a session orchestrator that enforces transitions across vision, guardrails, plan, brainstorm, whiteboard, and implement modes, automatically announcing mode switches to maintain context.