start-session_skill

Overview

This skill starts a work session by reading project context, checking git state, and giving a concise orientation so you can get started quickly. It prioritizes CLAUDE.md and local agent files, detects repo type (code, research, mixed), and surfaces recent commits, remote-only branches, roadmap progress, and session history. It also highlights missing project tracking sections and suggests setup actions.

How this skill works

It syncs files from a paired machine, then reads CLAUDE.md, agents.md, and local settings to extract project context, actions, roadmap, and session logs. It inspects the git workspace (status, current branch, recent commits) and queries the remote for branches that exist only on origin. Finally, it compiles a structured orientation summary tailored to the repo type and flags missing tracking sections with actionable suggestions.

When to use it

• At the start of a coding, research, or mixed session (user says “let’s get started” or “where are we”).
• When returning to a project after working on another machine to catch remote branches and changes.
• Before making new commits or switching tasks to confirm current focus and roadmap status.
• When you want a quick recap of recent work, pending items, and candidate actions to run next.

Best practices

• Run the initial sync (Unison) if you work across machines to surface remote-only branches and avoid surprises.
• Keep CLAUDE.md and agents.md updated with a Current Focus, Roadmap, and Project Actions for reliable session orientation.
• Regularly push branches from other machines so remote-only branches are discoverable during sessions.
• Use concise action headers under ## Project Actions so the skill can parse and list runnable workflows.
• If prompted about missing sections, accept the template to enable consistent session logging and wrap-up integration.

Example use cases

• Start a session on a repo to see current branch, uncommitted changes, and recent commits before coding.
• Return to a writing project to learn where the draft left off and which sections are next on the roadmap.
• Detect work pushed from another machine by listing remote-only branches and their latest commits.
• Extract scripted project actions (e.g., new-experiment) so you can run them without searching files.
• Identify missing project tracking and automatically add roadmap/session templates to standardize progress tracking.