Skip to content

Commit 2f7053e

Browse files
author
AI Developer
committed
feat: add session-workflow skill and TODO.md for multi-session AI development
Introduces a session-based development pattern that allows complex projects to be built across multiple AI sessions, with any AI able to continue from where the last session stopped. - Add .opencode/skills/session-workflow/SKILL.md: full session start/end protocol, TODO.md format spec, status conventions and examples - Add TODO.md template: phased roadmap with Session Log and handoff notes - Update developer.md: session start/end protocol at top of agent instructions - Update AGENTS.md: session-based development section, session-workflow skill listed - Update README.md: multi-session development section, TODO.md in project structure
1 parent 7b72222 commit 2f7053e

File tree

5 files changed

+320
-3
lines changed

5 files changed

+320
-3
lines changed

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

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -15,6 +15,20 @@ tools:
1515
---
1616
You are a specialized developer agent for the {{cookiecutter.project_name}} project.
1717

18+
## Session Start Protocol
19+
20+
**Always begin every session by:**
21+
1. Reading `TODO.md` to understand where the last session left off
22+
2. Reading `AGENTS.md` for current project context
23+
3. Identifying the first pending `[ ]` task and the "Notes for Next Session" section
24+
4. Picking a focused scope for this session (one phase at a time)
25+
26+
Use `/skill session-workflow` for the complete session start and end protocol.
27+
28+
**Always end every session by:**
29+
1. Updating `TODO.md` - mark completed tasks `[x]`, update Session Log, refresh Notes for Next Session
30+
2. Committing the updated `TODO.md`
31+
1832
## Project Context
1933
- **Package**: `{{cookiecutter.package_name}}`
2034
- **Module**: `{{cookiecutter.module_name}}`
@@ -29,6 +43,7 @@ You are a specialized developer agent for the {{cookiecutter.project_name}} proj
2943
├── tests/ # Test suite
3044
├── docs/ # Documentation
3145
├── pyproject.toml # Project config
46+
├── TODO.md # Session state & development roadmap
3247
└── README.md # Project docs
3348
```
3449

@@ -92,6 +107,7 @@ You are a specialized developer agent for the {{cookiecutter.project_name}} proj
92107
5. Run property-based tests with Hypothesis
93108

94109
## Available Skills
110+
- **session-workflow**: Manage multi-session development - read TODO.md, continue from checkpoint, update progress
95111
- **feature-definition**: Define features with SOLID principles
96112
- **prototype-script**: Create validation scripts for real data
97113
- **tdd**: Write tests using descriptive naming with pytest

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

Lines changed: 160 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,160 @@
1+
---
2+
name: session-workflow
3+
description: Manage multi-session AI development - read TODO.md, continue from last checkpoint, update progress, and hand off cleanly to the next session
4+
license: MIT
5+
compatibility: opencode
6+
metadata:
7+
audience: developers
8+
workflow: session-management
9+
---
10+
## What I do
11+
12+
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.
13+
14+
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.
15+
16+
## When to use me
17+
18+
- At the **start** of every session: read `TODO.md` and orient yourself
19+
- At the **end** of every session: update `TODO.md` with progress and handoff notes
20+
- When a project is **too large** to complete in one session
21+
- When you want **any AI** (not just you) to be able to continue the work
22+
23+
## Session Start Protocol
24+
25+
When beginning a new session on a project:
26+
27+
### 1. Read the project state
28+
```
29+
Read TODO.md
30+
Read AGENTS.md
31+
```
32+
33+
### 2. Identify the current phase
34+
- Find the first `[ ]` (pending) item in `TODO.md`
35+
- Read the **Session Log** and **Notes for Next Session** sections
36+
- Understand what was done last and what comes next
37+
38+
### 3. Confirm scope for this session
39+
- Pick ONE phase or a small, coherent set of tasks
40+
- Do not attempt to complete everything at once
41+
- Aim for a clean handoff point at the end of the session
42+
43+
### 4. Mark tasks in progress
44+
- Update `TODO.md`: change `[ ]` to `[~]` for tasks you start
45+
- Only mark one task `[~]` at a time when possible
46+
47+
## Session End Protocol
48+
49+
When finishing a session:
50+
51+
### 1. Mark completed tasks
52+
- Change `[~]` to `[x]` for everything finished this session
53+
- Leave `[ ]` for anything not yet started
54+
55+
### 2. Update the Session Log
56+
Append a row to the Session Log table:
57+
```markdown
58+
| YYYY-MM-DD | Brief summary of what was done this session |
59+
```
60+
61+
### 3. Update Notes for Next Session
62+
Replace the existing notes with fresh guidance:
63+
```markdown
64+
## Notes for Next Session
65+
- Start with Phase X, item: "..."
66+
- The tricky part is [explain any complexity or gotchas]
67+
- Run `task test` first to verify current state
68+
- [Any other context the next session needs]
69+
```
70+
71+
### 4. Commit the updated TODO.md
72+
Always commit `TODO.md` changes so the history is preserved in git.
73+
74+
## TODO.md Format
75+
76+
Every project should have a `TODO.md` at the root with this structure:
77+
78+
```markdown
79+
# <Project Name> - Development TODO
80+
81+
This file tracks all development steps. Each AI session should read this file first,
82+
pick up from the last completed step, and update statuses before finishing.
83+
84+
**Convention:** `[ ]` = pending, `[x]` = done, `[~]` = in progress
85+
86+
---
87+
88+
## Phase 1: <Phase Name>
89+
90+
- [x] Completed task
91+
- [~] In-progress task
92+
- [ ] Pending task
93+
94+
---
95+
96+
## Phase N: <Phase Name>
97+
98+
- [ ] Task
99+
100+
---
101+
102+
## Session Log
103+
104+
| Date | Session Summary |
105+
|------------|----------------------------------------|
106+
| YYYY-MM-DD | Initial scaffolding, TODO created |
107+
108+
---
109+
110+
## Notes for Next Session
111+
112+
- Start with Phase X: "task description"
113+
- <Any context or gotchas>
114+
```
115+
116+
## Task Status Conventions
117+
118+
| Symbol | Meaning |
119+
|--------|---------|
120+
| `[ ]` | Pending - not started |
121+
| `[~]` | In progress - current session is working on this |
122+
| `[x]` | Done - completed and verified |
123+
| `[-]` | Skipped - decided not to do this |
124+
125+
## Example: Starting a session
126+
127+
```
128+
I'm starting a new session on this project.
129+
130+
Step 1: Read TODO.md to find where we are.
131+
Step 2: The last session completed Phase 2 (data models).
132+
Notes say: "Start with Phase 3, federation_repo.py first"
133+
Step 3: I'll tackle Phase 3.1 (Federation Repository) this session.
134+
Step 4: Marking federation_repo tasks as [~] and starting work.
135+
```
136+
137+
## Example: Ending a session
138+
139+
```
140+
Session complete. I implemented Phase 3.1 and 3.2.
141+
142+
Updating TODO.md:
143+
- [x] federation_repo.py - list, get, create, update
144+
- [x] agent_repo.py - list, get, create, federations query
145+
146+
Session Log: 2026-03-13 | Implemented federation and agent repositories
147+
148+
Notes for Next Session:
149+
- Start with Phase 3.3: membership_repo.py
150+
- Tests are in tests/test_repositories.py, run `task test` first
151+
- The DB schema uses TEXT for IDs (slugs), not integers
152+
```
153+
154+
## Rules
155+
156+
1. **Never skip reading TODO.md** at the start of a session
157+
2. **Never leave TODO.md stale** - always update before finishing
158+
3. **One phase per session** - resist the urge to do everything
159+
4. **Clean handoffs** - future sessions (and future AIs) should need zero context from you
160+
5. **Commit TODO.md** - it is source code, not a scratch pad

‎{{cookiecutter.project_slug}}/AGENTS.md‎

Lines changed: 35 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -17,10 +17,30 @@
1717
| **Version** | {{cookiecutter.version}} |
1818
| **Minimum Coverage** | {{cookiecutter.minimum_coverage}}% |
1919

20+
## Session-Based Development
21+
22+
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.
23+
24+
### How it works
25+
26+
1. **`TODO.md`** at the project root is the shared state between sessions
27+
2. Every session starts by reading `TODO.md` to find the current phase
28+
3. Every session ends by updating `TODO.md` with progress and handoff notes
29+
4. This makes the project AI-agnostic: any agent, any time can continue
30+
31+
### Starting a new session
32+
```bash
33+
# The developer agent reads TODO.md automatically
34+
@developer /skill session-workflow
35+
```
36+
2037
## Available Skills
2138

2239
This project includes custom skills for OpenCode:
2340

41+
### Session Management
42+
- **session-workflow**: Manage multi-session development - read TODO.md, continue from last checkpoint, update progress and hand off cleanly
43+
2444
### Development Workflow
2545
- **feature-definition**: Define features with SOLID principles and clear requirements
2646
- **prototype-script**: Create quick validation scripts with real data capture
@@ -122,6 +142,14 @@ opencode
122142
Then run `/init` to generate a fresh `AGENTS.md` based on your project's current state.
123143

124144
### Example Workflow
145+
146+
#### Starting a session (always do this first)
147+
```bash
148+
# Read project state and orient for this session
149+
@developer /skill session-workflow
150+
```
151+
152+
#### Full feature development workflow
125153
```bash
126154
# 1. Define and implement a feature
127155
@developer /skill feature-definition
@@ -136,3 +164,10 @@ Then run `/init` to generate a fresh `AGENTS.md` based on your project's current
136164
@repo-manager /skill pr-management
137165
@repo-manager /skill git-release
138166
```
167+
168+
#### Ending a session (always do this last)
169+
```bash
170+
# Update TODO.md with progress and handoff notes, then commit
171+
@developer /skill session-workflow
172+
# Follow the "Session End Protocol" in the skill
173+
```

‎{{cookiecutter.project_slug}}/README.md‎

Lines changed: 19 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -35,7 +35,21 @@ task test && task lint && task static-check
3535

3636
## 🤖 AI-Powered Development
3737

38-
This project includes built-in AI agents to accelerate your development:
38+
This project includes built-in AI agents to accelerate your development.
39+
40+
### Multi-Session Development
41+
42+
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.
43+
44+
```bash
45+
# Start any session: read state, orient, continue
46+
@developer /skill session-workflow
47+
48+
# End any session: update TODO.md, commit progress, hand off
49+
@developer /skill session-workflow
50+
```
51+
52+
### Feature Development Workflow
3953

4054
```bash
4155
# Define new features with SOLID principles
@@ -91,19 +105,21 @@ docker build --target prod -t {{cookiecutter.package_name}}:prod
91105
{{cookiecutter.project_slug}}/
92106
├── {{cookiecutter.package_name}}/ # Main application package
93107
│ ├── __init__.py # Package initialization
94-
│ └── {{cookiecutter.module_name}}.py # Core module
108+
│ └── {{cookiecutter.module_name}}.py # Core module
95109
├── .opencode/ # AI development agents
96110
│ ├── agents/ # Specialized AI agents
97111
│ │ ├── developer.md # 7-phase development workflow
98112
│ │ ├── architect.md # SOLID architecture review
99113
│ │ └── repo-manager.md # Release and PR management
100114
│ └── skills/ # Development skills
115+
│ ├── session-workflow/ # Multi-session development state
101116
│ ├── feature-definition/ # Requirements planning
102-
│ ├── tdd/ # Test-driven development
117+
│ ├── tdd/ # Test-driven development
103118
│ ├── implementation/ # Guided implementation
104119
│ └── code-quality/ # Quality enforcement
105120
├── tests/ # Comprehensive test suite
106121
├── docs/ # Documentation
122+
├── TODO.md # Development roadmap & session state
107123
├── Dockerfile # Multi-stage container build
108124
└── pyproject.toml # Project configuration
109125
```

‎{{cookiecutter.project_slug}}/TODO.md‎

Lines changed: 90 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,90 @@
1+
# {{cookiecutter.project_name}} - Development TODO
2+
3+
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.
4+
5+
**Convention:** `[ ]` = pending, `[x]` = done, `[~]` = in progress, `[-]` = skipped
6+
7+
> **For AI agents:** Use `/skill session-workflow` for the full session start/end protocol.
8+
9+
---
10+
11+
## Phase 1: Project Foundation
12+
13+
- [x] Project created via cookiecutter template
14+
- [ ] Review and update `README.md` with project-specific description
15+
- [ ] Install dependencies: `uv venv && uv pip install -e '.[dev]'`
16+
- [ ] Verify base tests pass: `task test`
17+
18+
---
19+
20+
## Phase 2: Feature Definition
21+
22+
- [ ] Define core features using `/skill feature-definition`
23+
- [ ] Document requirements and acceptance criteria
24+
- [ ] Review SOLID principles compliance in design
25+
26+
---
27+
28+
## Phase 3: Prototype & Validation
29+
30+
- [ ] Create prototype scripts using `/skill prototype-script`
31+
- [ ] Validate core concepts with real data
32+
- [ ] Document prototype outputs for implementation reference
33+
34+
---
35+
36+
## Phase 4: Test-Driven Development
37+
38+
- [ ] Write comprehensive test suite using `/skill tdd`
39+
- [ ] Ensure all tests fail initially (RED phase)
40+
- [ ] Cover unit, integration, and property-based tests
41+
42+
---
43+
44+
## Phase 5: Architecture Review
45+
46+
- [ ] Design interfaces using `/skill signature-design`
47+
- [ ] Request architecture review from `@architect`
48+
- [ ] Address any architectural concerns
49+
50+
---
51+
52+
## Phase 6: Implementation
53+
54+
- [ ] Implement features using `/skill implementation`
55+
- [ ] Make tests pass one at a time (GREEN phase)
56+
- [ ] Refactor for quality (REFACTOR phase)
57+
58+
---
59+
60+
## Phase 7: Quality Assurance
61+
62+
- [ ] Run linting: `task lint`
63+
- [ ] Run type checking: `task static-check`
64+
- [ ] Verify coverage ≥ {{cookiecutter.minimum_coverage}}%: `task test`
65+
- [ ] Run property-based tests with Hypothesis
66+
67+
---
68+
69+
## Phase 8: Release
70+
71+
- [ ] Create release using `@repo-manager /skill git-release`
72+
- [ ] Update documentation
73+
- [ ] Deploy if applicable
74+
75+
---
76+
77+
## Session Log
78+
79+
| Date | Session Summary |
80+
|------------|----------------------------------------------------|
81+
| (date) | Project scaffolded via cookiecutter, TODO created |
82+
83+
---
84+
85+
## Notes for Next Session
86+
87+
- Start with **Phase 1**: update `README.md` with project-specific content
88+
- Then proceed to **Phase 2**: define the core features
89+
- Run `task test` to verify the base template tests pass before making changes
90+
- See `AGENTS.md` for project details and available commands

0 commit comments

Comments
 (0)