---
description: "Aut-O session lifecycle — start protocol, GitHub sync, crash recovery, continuous sync"
alwaysApply: true
---

# Session Protocol

## Session Start Sequence

Execute this sequence at the start of every session or when context is unclear:

### Phase 1: Sync from GitHub (Source of Truth)

Run these terminal commands to understand current project state:

```bash
# Active work items
gh issue list --state open

# In-progress pull requests
gh pr list --state open

# CI/CD status
gh run list --limit 5

# Recent commits
git log --oneline -10

# Optional: project board (if using GitHub Projects V2)
# gh project item-list <project-number> --owner <owner> --limit 20
```

### Phase 2: Load Grounding

1. Read `AGENTS.md` at project root (universal project context)
2. Review any other `.cursor/rules/*.mdc` files for domain rules
3. Check `git status` and `git diff --stat` for uncommitted work
4. **Deferred work:** If project has a `deferred/` directory, read `deferred/README.md` and check each item's unblock trigger before planning work; if newly unblocked, propose executing the integration steps first

### Phase 3: Orient

Determine:
- What was last worked on? (git log, open PRs)
- What needs attention? (open issues, failing CI, review requests)
- What is highest priority? (issue labels, milestones)

### Phase 4: Execute

Begin working on the highest-priority task. Follow T-01: full autonomy.

## GitHub SSOT Commands

Use these commands throughout the session to stay synchronized:

```bash
# Check what needs doing
gh issue list --state open --label "priority:high"

# View specific issue details
gh issue view <number>

# Create branch for work
git checkout -b feat/<issue-number>-<short-description>

# Link PR to issue when done
gh pr create --title "..." --body "Closes #<number>"

# Update issue with progress
gh issue comment <number> --body "Status: ..."

# Check CI after push
gh run list --limit 3
```

## Crash Recovery Steps

When resuming after an interruption:

1. **Check git state**: `git status` — is there uncommitted work?
2. **Check stash**: `git stash list` — was work stashed before crash?
3. **Check GitHub**: `gh issue list --state open` — what was being worked on?
4. **Check PRs**: `gh pr list --state open` — any draft PRs in progress?
5. **Check CI**: `gh run list --limit 5` — did last push succeed?
6. **Read AGENTS.md**: Confirm project context is current
7. **Resume**: Pick up the highest-priority incomplete task

## Continuous Sync Triggers

Update project state when:

| Event | Action |
|-------|--------|
| Architecture change | Update AGENTS.md architecture section |
| Feature complete | Close GitHub issue, merge PR |
| Convention added | Update AGENTS.md conventions section |
| Bug found | Create GitHub issue |
| CI fails | Fix immediately (T-03: Zero Technical Debt) |
| Session ending | Commit all work, push, update issues |

## Merge and Docker

- **Merge:** Prefer squash merge to main; use PR title as the final commit message. Linear history.
- **Docker-only dev:** When the project runs all tooling in Docker, run `gh` and `git` inside the dev container (e.g. `docker compose run --rm dev bash` or equivalent); never assume host has `gh`/`git` configured.

## Branch Naming Convention

```
feat/<issue>-<description>     # New feature
fix/<issue>-<description>      # Bug fix
refactor/<issue>-<description> # Refactoring
docs/<issue>-<description>     # Documentation
test/<issue>-<description>     # Test additions
```

## Commit Message Format

```
<type>(<scope>): <description>

[optional body]

Closes #<issue-number>
```

Types: feat, fix, refactor, docs, test, chore, ci, perf
