feat: add session-workflow skill and TODO.md for multi-session AI development

{{cookiecutter.project_slug}}/.opencode/agents/developer.md

@@ -15,6 +15,20 @@ tools:
 ---
 You are a specialized developer agent for the {{cookiecutter.project_name}} project.
 
+## Session Start Protocol
+
+**Always begin every session by:**
+1. Reading `TODO.md` to understand where the last session left off
+2. Reading `AGENTS.md` for current project context
+3. Identifying the first pending `[ ]` task and the "Notes for Next Session" section
+4. Picking a focused scope for this session (one phase at a time)
+
+Use `/skill session-workflow` for the complete session start and end protocol.
+
+**Always end every session by:**
+1. Updating `TODO.md` - mark completed tasks `[x]`, update Session Log, refresh Notes for Next Session
+2. Committing the updated `TODO.md`
+
 ## Project Context
 - **Package**: `{{cookiecutter.package_name}}`
 - **Module**: `{{cookiecutter.module_name}}`
@@ -29,6 +43,7 @@ You are a specialized developer agent for the {{cookiecutter.project_name}} proj
 ├── tests/                               # Test suite
 ├── docs/                                # Documentation
 ├── pyproject.toml                       # Project config
+├── TODO.md                              # Session state & development roadmap
 └── README.md                            # Project docs
 ```
 
@@ -92,6 +107,7 @@ You are a specialized developer agent for the {{cookiecutter.project_name}} proj
 5. Run property-based tests with Hypothesis
 
 ## Available Skills
+- **session-workflow**: Manage multi-session development - read TODO.md, continue from checkpoint, update progress
 - **feature-definition**: Define features with SOLID principles
 - **prototype-script**: Create validation scripts for real data
 - **tdd**: Write tests using descriptive naming with pytest

{{cookiecutter.project_slug}}/.opencode/skills/session-workflow/SKILL.md

@@ -0,0 +1,160 @@
+---
+name: session-workflow
+description: Manage multi-session AI development - read TODO.md, continue from last checkpoint, update progress, and hand off cleanly to the next session
+license: MIT
+compatibility: opencode
+metadata:
+  audience: developers
+  workflow: session-management
+---
+## What I do
+
+Enable complex projects to be developed across multiple AI sessions. Each session picks up exactly where the last one stopped, using `TODO.md` as the shared state between sessions.
+
+This solves the context-window problem for large projects: no single session needs to hold the entire project in mind. The `TODO.md` file acts as a living contract between sessions.
+
+## When to use me
+
+- At the **start** of every session: read `TODO.md` and orient yourself
+- At the **end** of every session: update `TODO.md` with progress and handoff notes
+- When a project is **too large** to complete in one session
+- When you want **any AI** (not just you) to be able to continue the work
+
+## Session Start Protocol
+
+When beginning a new session on a project:
+
+### 1. Read the project state
+```
+Read TODO.md
+Read AGENTS.md
+```
+
+### 2. Identify the current phase
+- Find the first `[ ]` (pending) item in `TODO.md`
+- Read the **Session Log** and **Notes for Next Session** sections
+- Understand what was done last and what comes next
+
+### 3. Confirm scope for this session
+- Pick ONE phase or a small, coherent set of tasks
+- Do not attempt to complete everything at once
+- Aim for a clean handoff point at the end of the session
+
+### 4. Mark tasks in progress
+- Update `TODO.md`: change `[ ]` to `[~]` for tasks you start
+- Only mark one task `[~]` at a time when possible
+
+## Session End Protocol
+
+When finishing a session:
+
+### 1. Mark completed tasks
+- Change `[~]` to `[x]` for everything finished this session
+- Leave `[ ]` for anything not yet started
+
+### 2. Update the Session Log
+Append a row to the Session Log table:
+```markdown
+| YYYY-MM-DD | Brief summary of what was done this session |
+```
+
+### 3. Update Notes for Next Session
+Replace the existing notes with fresh guidance:
+```markdown
+## Notes for Next Session
+- Start with Phase X, item: "..."
+- The tricky part is [explain any complexity or gotchas]
+- Run `task test` first to verify current state
+- [Any other context the next session needs]
+```
+
+### 4. Commit the updated TODO.md
+Always commit `TODO.md` changes so the history is preserved in git.
+
+## TODO.md Format
+
+Every project should have a `TODO.md` at the root with this structure:
+
+```markdown
+# <Project Name> - Development TODO
+
+This file tracks all development steps. Each AI session should read this file first,
+pick up from the last completed step, and update statuses before finishing.
+
+**Convention:** `[ ]` = pending, `[x]` = done, `[~]` = in progress
+
+---
+
+## Phase 1: <Phase Name>
+
+- [x] Completed task
+- [~] In-progress task
+- [ ] Pending task
+
+---
+
+## Phase N: <Phase Name>
+
+- [ ] Task
+
+---
+
+## Session Log
+
+| Date       | Session Summary                        |
+|------------|----------------------------------------|
+| YYYY-MM-DD | Initial scaffolding, TODO created      |
+
+---
+
+## Notes for Next Session
+
+- Start with Phase X: "task description"
+- <Any context or gotchas>
+```
+
+## Task Status Conventions
+
+| Symbol | Meaning |
+|--------|---------|
+| `[ ]`  | Pending - not started |
+| `[~]`  | In progress - current session is working on this |
+| `[x]`  | Done - completed and verified |
+| `[-]`  | Skipped - decided not to do this |
+
+## Example: Starting a session
+
+```
+I'm starting a new session on this project.
+
+Step 1: Read TODO.md to find where we are.
+Step 2: The last session completed Phase 2 (data models).
+        Notes say: "Start with Phase 3, federation_repo.py first"
+Step 3: I'll tackle Phase 3.1 (Federation Repository) this session.
+Step 4: Marking federation_repo tasks as [~] and starting work.
+```
+
+## Example: Ending a session
+
+```
+Session complete. I implemented Phase 3.1 and 3.2.
+
+Updating TODO.md:
+- [x] federation_repo.py - list, get, create, update
+- [x] agent_repo.py - list, get, create, federations query
+
+Session Log: 2026-03-13 | Implemented federation and agent repositories
+
+Notes for Next Session:
+- Start with Phase 3.3: membership_repo.py
+- Tests are in tests/test_repositories.py, run `task test` first
+- The DB schema uses TEXT for IDs (slugs), not integers
+```
+
+## Rules
+
+1. **Never skip reading TODO.md** at the start of a session
+2. **Never leave TODO.md stale** - always update before finishing
+3. **One phase per session** - resist the urge to do everything
+4. **Clean handoffs** - future sessions (and future AIs) should need zero context from you
+5. **Commit TODO.md** - it is source code, not a scratch pad

{{cookiecutter.project_slug}}/AGENTS.md

@@ -17,10 +17,30 @@
 | **Version** | {{cookiecutter.version}} |
 | **Minimum Coverage** | {{cookiecutter.minimum_coverage}}% |
 
+## Session-Based Development
+
+This project uses a **session workflow** that allows complex development to span multiple AI sessions. Any AI agent can continue work from where the last session stopped.
+
+### How it works
+
+1. **`TODO.md`** at the project root is the shared state between sessions
+2. Every session starts by reading `TODO.md` to find the current phase
+3. Every session ends by updating `TODO.md` with progress and handoff notes
+4. This makes the project AI-agnostic: any agent, any time can continue
+
+### Starting a new session
+```bash
+# The developer agent reads TODO.md automatically
+@developer /skill session-workflow
+```
+
 ## Available Skills
 
 This project includes custom skills for OpenCode:
 
+### Session Management
+- **session-workflow**: Manage multi-session development - read TODO.md, continue from last checkpoint, update progress and hand off cleanly
+
 ### Development Workflow
 - **feature-definition**: Define features with SOLID principles and clear requirements
 - **prototype-script**: Create quick validation scripts with real data capture  
@@ -122,6 +142,14 @@ opencode
 Then run `/init` to generate a fresh `AGENTS.md` based on your project's current state.
 
 ### Example Workflow
+
+#### Starting a session (always do this first)
+```bash
+# Read project state and orient for this session
+@developer /skill session-workflow
+```
+
+#### Full feature development workflow
 ```bash
 # 1. Define and implement a feature
 @developer /skill feature-definition
@@ -136,3 +164,10 @@ Then run `/init` to generate a fresh `AGENTS.md` based on your project's current
 @repo-manager /skill pr-management
 @repo-manager /skill git-release
 ```
+
+#### Ending a session (always do this last)
+```bash
+# Update TODO.md with progress and handoff notes, then commit
+@developer /skill session-workflow
+# Follow the "Session End Protocol" in the skill
+```

{{cookiecutter.project_slug}}/README.md

@@ -35,7 +35,21 @@ task test && task lint && task static-check
 
 ## 🤖 AI-Powered Development
 
-This project includes built-in AI agents to accelerate your development:
+This project includes built-in AI agents to accelerate your development.
+
+### Multi-Session Development
+
+Complex projects are developed across multiple AI sessions. `TODO.md` at the root acts as the shared state — any AI agent can pick up exactly where the last session stopped.
+
+```bash
+# Start any session: read state, orient, continue
+@developer /skill session-workflow
+
+# End any session: update TODO.md, commit progress, hand off
+@developer /skill session-workflow
+```
+
+### Feature Development Workflow
 
 ```bash
 # Define new features with SOLID principles
@@ -91,19 +105,21 @@ docker build --target prod -t {{cookiecutter.package_name}}:prod
 {{cookiecutter.project_slug}}/
 ├── {{cookiecutter.package_name}}/        # Main application package
 │   ├── __init__.py                       # Package initialization
-│   └── {{cookiecutter.module_name}}.py  # Core module
+│   └── {{cookiecutter.module_name}}.py   # Core module
 ├── .opencode/                            # AI development agents
 │   ├── agents/                           # Specialized AI agents
 │   │   ├── developer.md                  # 7-phase development workflow
 │   │   ├── architect.md                  # SOLID architecture review
 │   │   └── repo-manager.md               # Release and PR management
 │   └── skills/                           # Development skills
+│       ├── session-workflow/             # Multi-session development state
 │       ├── feature-definition/           # Requirements planning
-│       ├── tdd/                      # Test-driven development
+│       ├── tdd/                          # Test-driven development
 │       ├── implementation/               # Guided implementation
 │       └── code-quality/                 # Quality enforcement
 ├── tests/                                # Comprehensive test suite
 ├── docs/                                 # Documentation
+├── TODO.md                               # Development roadmap & session state
 ├── Dockerfile                            # Multi-stage container build
 └── pyproject.toml                        # Project configuration
 ```

{{cookiecutter.project_slug}}/TODO.md

@@ -0,0 +1,90 @@
+# {{cookiecutter.project_name}} - Development TODO
+
+This file tracks all development steps across AI sessions. Each session should read this file first, pick up from the last completed step, and update statuses before finishing.
+
+**Convention:** `[ ]` = pending, `[x]` = done, `[~]` = in progress, `[-]` = skipped
+
+> **For AI agents:** Use `/skill session-workflow` for the full session start/end protocol.
+
+---
+
+## Phase 1: Project Foundation
+
+- [x] Project created via cookiecutter template
+- [ ] Review and update `README.md` with project-specific description
+- [ ] Install dependencies: `uv venv && uv pip install -e '.[dev]'`
+- [ ] Verify base tests pass: `task test`
+
+---
+
+## Phase 2: Feature Definition
+
+- [ ] Define core features using `/skill feature-definition`
+- [ ] Document requirements and acceptance criteria
+- [ ] Review SOLID principles compliance in design
+
+---
+
+## Phase 3: Prototype & Validation
+
+- [ ] Create prototype scripts using `/skill prototype-script`
+- [ ] Validate core concepts with real data
+- [ ] Document prototype outputs for implementation reference
+
+---
+
+## Phase 4: Test-Driven Development
+
+- [ ] Write comprehensive test suite using `/skill tdd`
+- [ ] Ensure all tests fail initially (RED phase)
+- [ ] Cover unit, integration, and property-based tests
+
+---
+
+## Phase 5: Architecture Review
+
+- [ ] Design interfaces using `/skill signature-design`
+- [ ] Request architecture review from `@architect`
+- [ ] Address any architectural concerns
+
+---
+
+## Phase 6: Implementation
+
+- [ ] Implement features using `/skill implementation`
+- [ ] Make tests pass one at a time (GREEN phase)
+- [ ] Refactor for quality (REFACTOR phase)
+
+---
+
+## Phase 7: Quality Assurance
+
+- [ ] Run linting: `task lint`
+- [ ] Run type checking: `task static-check`
+- [ ] Verify coverage ≥ {{cookiecutter.minimum_coverage}}%: `task test`
+- [ ] Run property-based tests with Hypothesis
+
+---
+
+## Phase 8: Release
+
+- [ ] Create release using `@repo-manager /skill git-release`
+- [ ] Update documentation
+- [ ] Deploy if applicable
+
+---
+
+## Session Log
+
+| Date       | Session Summary                                    |
+|------------|----------------------------------------------------|
+| (date)     | Project scaffolded via cookiecutter, TODO created  |
+
+---
+
+## Notes for Next Session
+
+- Start with **Phase 1**: update `README.md` with project-specific content
+- Then proceed to **Phase 2**: define the core features
+- Run `task test` to verify the base template tests pass before making changes
+- See `AGENTS.md` for project details and available commands