gtapps/session

Session

Start or resume a session with full context loading. This is the generic session workflow — hermits may provide specialized versions.

Workflow

1. Start or resume

Invoke /claude-code-hermit:session-start to check session state and load context.

2. If resuming an active session

• Call TaskList to see current plan steps
• Show: task, progress (completed/remaining tasks), and blockers
• If the session status is blocked: suggest running /debug to diagnose tool/hook failures before re-attempting
• Ask: "Continue this, or start something new?"

3. If starting a new session

• Ask: "What should I help with?"
• The session-start skill handles tags

4. Plan the work

Once I know what to work on:

• Propose an ordered plan to get it done
• Confirm the plan with the operator before starting work
• For multi-step work: create a native Task (TaskCreate) for each step
• For quick single-step tasks: skip TaskCreate

5. Execute

Work through tasks using whatever tools, skills, and agents are available:

• Use the tools best suited to each step
• Mark tasks in progress (TaskUpdate) when starting each step, completed when done
• Update .claude-code-hermit/sessions/SHELL.md Progress Log after each significant step
• If a step is blocked, document the blocker in SHELL.md and ask the operator how to proceed

6. Work done

When the work is done, or the operator decides to move on (even if partial or blocked):

Completion notification is the final step of this flow, not a substitute for it. Skipping the session-mgr idle transition (step 6 below) leaves the session in_progress, which triggers stale-session heartbeat alerts and delays report archival until the time-based backstops kick in.

1. Compile final session data in context — do NOT write to SHELL.md at this point. session-mgr owns the final write. Gather:
   • Status: one of completed | partial | blocked
   • Blockers: one line each, enough context for a cold start
   • Lessons: only genuinely useful ones
   • Changed: list of files modified
2. Verify quality in-context before passing to session-mgr:
   • Task status is one of completed | partial | blocked
   • Changed files are identified
   • Blockers have enough context for a cold start
   • Cost data recorded (if available)
3. Create proposals for any high-leverage improvements discovered during work
4. Reflect (with debounce). Read state/reflection-state.json for last_reflection. Only invoke the claude-code-hermit:reflect skill if last_reflection is null or older than 4 hours. For quick tasks (no tasks created, under 5 minutes), skip entirely — progress log is sufficient. 4b. Session-triggered scheduled checks. For each scheduled_checks entry (from config already loaded) with trigger: "session" and enabled: true, invoke the skill. If a skill is unavailable or errors, skip it and continue — never block session finalization on a scheduled check failure. For each check that completed successfully, read-modify-write state/reflection-state.json: update only scheduled_checks.<id>.last_run to today's ISO date, preserving all other keys. Do not update last_run for failed checks.
5. If native Tasks exist: call TaskList, format as a markdown table. Then TaskUpdate(status=deleted) for all tasks (idle = clean slate).
6. Use claude-code-hermit:session-mgr to perform an idle transition (finalize SHELL.md, archive report, reset task-scoped sections, set status to idle). session-mgr handles updating both SHELL.md (cosmetic) and state/runtime.json (lifecycle truth). Pass the following compact structured payload in the prompt — keep it brief, no freeform prose:

   Status: <completed|partial|blocked>
   Blockers: <one line each, or none>
   Lessons: <one line each, or none>
   Changed: <file list, or none>
   

   Also include the task table (if native Tasks were created).
7. If heartbeat.enabled is true in config and heartbeat is not already running: start it (/claude-code-hermit:heartbeat start)
8. After the session-mgr idle transition (step 6) succeeds: notify the operator: "Archived as S-NNN. Task: [summary]. Status: [outcome]. Ready for what's next."
9. Once the operator says what's next: go to step 4 (plan the work)

To close the session entirely, the operator runs /claude-code-hermit:session-close at any time.

Notes

• This skill does NOT prescribe a specific quality workflow (no tests, no /claude-code-hermit:simplify). Those belong to domain-specific session skills.
• If you discover something worth operationalizing during work, use /claude-code-hermit:proposal-create.
• For watching recurring checks during a session, use /claude-code-hermit:watch.
• Check session status anytime with /claude-code-hermit:pulse.