Session Start

Overview

Get your bearings before doing any work. Every session starts here.

Core principle: Understand the current state before taking action.

Announce at start: "I'm using session-start to get oriented before beginning work."

The Protocol

Execute these steps in order at the start of every session:

Step 1: Environment Check

Verify required tools and environment variables are available.

# Check GitHub CLI authentication
gh auth status

# Check git is available
git --version

# Verify GITHUB_PROJECT is set
echo $GITHUB_PROJECT

If any check fails: Report to user before proceeding.

Skill: environment-bootstrap

---

Step 1.5: Development Services

Check for available development services (docker-compose).

# Detect compose services
if [ -f "docker-compose.yml" ] || [ -f ".devcontainer/docker-compose.yml" ]; then
    docker-compose config --services
    docker-compose ps
fi

Key questions:

• What services are available (postgres, redis, etc.)?
• Which are currently running?
• Do any need to be started for this work?

If services are available but not running:

# Start all services
docker-compose up -d

# Or start specific service
docker-compose up -d postgres

Skill: local-service-testing

---

Step 2: Repository State

Understand the current state of the repository.

# Current branch
git branch --show-current

# Working directory status
git status

# Recent commits
git log --oneline -5

# Any stashed changes?
git stash list

Key questions:

• Am I on a feature branch or main?
• Are there uncommitted changes?
• Is there work in progress?

---

Step 3: GitHub Project State (Source of Truth)

Check the current state of work via the GitHub Project Board (the source of truth).

CRITICAL: Use github-api-cache to minimize API calls.

# === CACHE INITIALIZATION (3 API calls total) ===
# This replaces 20+ individual API calls

echo "Initializing GitHub API cache..."

# CALL 1: Cache all project fields
export GH_CACHE_FIELDS=$(gh project field-list "$GITHUB_PROJECT_NUM" --owner "$GH_PROJECT_OWNER" --format json)

# CALL 2: Cache all project items
export GH_CACHE_ITEMS=$(gh project item-list "$GITHUB_PROJECT_NUM" --owner "$GH_PROJECT_OWNER" --format json)

# CALL 3: Get project ID
export GH_PROJECT_ID=$(gh project list --owner "$GH_PROJECT_OWNER" --format json --limit 100 | \
  jq -r ".projects[] | select(.number == $GITHUB_PROJECT_NUM) | .id")

# Extract field IDs from cache (NO API CALLS)
export GH_STATUS_FIELD_ID=$(echo "$GH_CACHE_FIELDS" | jq -r '.fields[] | select(.name == "Status") | .id')
export GH_STATUS_IN_PROGRESS_ID=$(echo "$GH_CACHE_FIELDS" | jq -r '.fields[] | select(.name == "Status") | .options[] | select(.name == "In Progress") | .id')
export GH_STATUS_DONE_ID=$(echo "$GH_CACHE_FIELDS" | jq -r '.fields[] | select(.name == "Status") | .options[] | select(.name == "Done") | .id')

echo "Cached $(echo "$GH_CACHE_ITEMS" | jq '.items | length') project items"

Query from cache (NO API CALLS):

# Get all project items with their status (from cache)
echo "$GH_CACHE_ITEMS" | jq '.items[] | {number: .content.number, title: .content.title, status: .status.name}'

# Get Ready issues (from cache)
echo "$GH_CACHE_ITEMS" | jq -r '.items[] | select(.status.name == "Ready") | .content.number'

# Get In Progress issues (from cache)
echo "$GH_CACHE_ITEMS" | jq -r '.items[] | select(.status.name == "In Progress") | .content.number'

# Get Blocked issues (from cache)
echo "$GH_CACHE_ITEMS" | jq -r '.items[] | select(.status.name == "Blocked") | .content.number'

Key questions:

• What issues have Status = "In Progress"?
• What issues have Status = "Ready" (pending work)?
• Are there any Status = "Blocked" items?
• What's the highest priority Ready item?

Skill: github-api-cache

---

Step 3.5: Project Board Sync Verification

MANDATORY: Verify project board state matches actual work state.

Uses cached data from Step 3 - NO additional API calls for project queries.

# Check for sync issues between project board and reality
# ALL project queries use GH_CACHE_ITEMS (cached in Step 3)

echo "## Project Board Sync Check"
echo ""

# 1. Issues marked "In Progress" should have active branches (0 API calls)
echo "### Checking: In Progress issues have branches"
for issue in $(echo "$GH_CACHE_ITEMS" | jq -r '.items[] | select(.status.name == "In Progress") | .content.number'); do
  branch=$(git branch -r 2>/dev/null | grep -E "feature/$issue-" | head -1)
  if [ -z "$branch" ]; then
    echo "⚠️ Issue #$issue is 'In Progress' but has no branch"
  fi
done

# 2. Active branches should have issues marked "In Progress" (0 API calls)
echo ""
echo "### Checking: Active branches have In Progress issues"
for branch in $(git branch -r 2>/dev/null | grep -E 'origin/feature/[0-9]+' | sed 's/.*feature\///' | cut -d- -f1 | sort -u); do
  status=$(echo "$GH_CACHE_ITEMS" | jq -r ".items[] | select(.content.number == $branch) | .status.name")

  if [ "$status" != "In Progress" ] && [ "$status" != "In Review" ]; then
    echo "⚠️ Branch for #$branch exists but project Status='$status' (expected: In Progress or In Review)"
  fi
done

# 3. Open PRs should have issues marked "In Review" (1 API call for PR list - REST API)
echo ""
echo "### Checking: Open PRs have In Review issues"
for pr in $(gh pr list --json number,body --jq '.[] | select(.body | contains("Closes #")) | .body' 2>/dev/null | grep -oE 'Closes #[0-9]+' | grep -oE '[0-9]+'); do
  # Use cached items, not API call
  status=$(echo "$GH_CACHE_ITEMS" | jq -r ".items[] | select(.content.number == $pr) | .status.name")

  if [ "$status" != "In Review" ]; then
    echo "⚠️ Issue #$pr has open PR but project Status='$status' (expected: In Review)"
  fi
done

echo ""
echo "Sync check complete."

If sync issues found:

1. Report discrepancies to user before proceeding
2. Fix critical discrepancies (In Progress with no branch = stale state)
3. Document any unresolved sync issues

Skill: project-board-enforcement

---

Step 3.6: Active Orchestration Detection

CRITICAL: Check if autonomous orchestration was running and needs to resume.

# Check MCP Memory for active orchestration marker
ACTIVE_ORCH=$(mcp__memory__open_nodes({"names": ["ActiveOrchestration"]}))

If ActiveOrchestration entity exists:

## ⚠️ ACTIVE ORCHESTRATION DETECTED

**Status:** [from entity]
**Scope:** [from entity]
**Tracking Issue:** #[from entity]
**Last Loop:** [from entity]
**Repository:** [from entity]

### Action Required

Context was compacted mid-orchestration. Resuming now.

1. Verify tracking issue still exists
2. Resume orchestration via `autonomous-orchestration` skill
3. Continue from current phase (BOOTSTRAP or MAIN_LOOP)

Resume orchestration immediately - do not wait for user input. The original request for autonomous operation is still the active consent.

If no ActiveOrchestration entity: Continue to Step 4.

---

Step 4: Memory Recall

Search for relevant context from previous sessions.

Episodic Memory:

• Search for current issue number
• Search for feature/project name
• Search for recent work in this repository

Knowledge Graph (mcp__memory):

• Check for entities related to this project
• Look for documented decisions or patterns

Skill: memory-integration

---

Step 5: Active Work Detection

Determine if there's work in progress to resume.

Indicators of active work:

• Branch is not main
• Uncommitted changes exist
• Issue marked "In Progress" in project
• Previous session notes reference ongoing work

If active work detected:

1. Read the associated issue
2. Check last commit message for context
3. Review any verification reports
4. Determine current step in issue-driven-development process

---

Step 6: Environment Bootstrap

If starting fresh or environment needs setup:

# Run init script if it exists
if [ -f scripts/init.sh ]; then
    ./scripts/init.sh
fi

# Or common alternatives
pnpm install --frozen-lockfile  # Node projects
pip install                     # Python projects

Verify basic functionality works before starting new work.

Skill: environment-bootstrap

---

Step 7: Orient and Report

Summarize current state to user:

## Session State

**Repository:** [owner/repo]
**Branch:** [current branch]
**Working Directory:** [clean/dirty]

**Active Work:**
- Issue: #[number] - [title]
- Status: [project status]
- Progress: [what's been done]

**Environment:**
- [tool versions]
- [any issues detected]

**Development Services:**
- postgres: [running/stopped] @ localhost:5432
- redis: [running/stopped] @ localhost:6379
- [other services from docker-compose]

**Ready to:** [resume work on X / start new issue / await instructions]

---

Decision Tree

Start Session
     │
     ▼
┌─────────────────┐
│ Environment OK? │──No──► Report issues, await fix
└────────┬────────┘
         │ Yes
         ▼
┌─────────────────┐
│ On main branch? │──Yes──► Ready for new work
└────────┬────────┘
         │ No
         ▼
┌─────────────────┐
│ Uncommitted     │──Yes──► Resume in-progress work
│ changes exist?  │
└────────┬────────┘
         │ No
         ▼
┌─────────────────┐
│ Issue marked    │──Yes──► Resume in-progress work
│ In Progress?    │
└────────┬────────┘
         │ No
         ▼
Ready for new work

Resuming In-Progress Work

If resuming work from a previous session:

1. Read the issue - Full description and all comments
2. Check last commit - What was the last completed step?
3. Run tests - Is the codebase in a working state?
4. Review verification - What criteria are already met?
5. Determine next step - Map to issue-driven-development steps

Then continue from the appropriate step in issue-driven-development.

Starting New Work

If no work in progress:

1. Check GitHub Project for highest priority "Ready" item
2. Or await user instructions for which issue to work on
3. Begin issue-driven-development from Step 1

Common Issues

| Issue | Resolution | |-------|------------| | GITHUB_PROJECT not set | Ask user for project URL | | Not authenticated to gh | Run gh auth login | | Dirty working directory on main | Stash or discard before proceeding | | Issue "In Progress" but branch deleted | Reset issue status, start fresh |

Checklist

Before proceeding to work:

• [ ] Environment verified (gh, git, env vars)
• [ ] GITHUB_PROJECT_NUM and GH_PROJECT_OWNER set
• [ ] GitHub API cache initialized (GH_CACHE_ITEMS, GH_CACHE_FIELDS set)
• [ ] Development services detected and status reported
• [ ] Repository state understood
• [ ] GitHub Project state checked (via cached data, not repeated API calls)
• [ ] Project board sync verified (Step 3.5) using cached data
• [ ] Sync discrepancies reported/fixed
• [ ] Active orchestration checked (Step 3.6) - Resume if found
• [ ] Memory searched for context
• [ ] Active work detected or new work identified
• [ ] Environment bootstrapped if needed
• [ ] Required services started (if applicable)
• [ ] State reported to user

Skills: github-api-cache, project-board-enforcement

Integration

After session-start completes, proceed to either:

• Resume: Continue from current step in issue-driven-development
• New work: Begin issue-driven-development from Step 1

Always operate under autonomous-operation mode.