From 2f7053ecf39b9a956add0095253425dcd264fb99 Mon Sep 17 00:00:00 2001 From: AI Developer Date: Fri, 13 Mar 2026 02:40:12 -0400 Subject: [PATCH] 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 --- .../.opencode/agents/developer.md | 16 ++ .../skills/session-workflow/SKILL.md | 160 ++++++++++++++++++ {{cookiecutter.project_slug}}/AGENTS.md | 35 ++++ {{cookiecutter.project_slug}}/README.md | 22 ++- {{cookiecutter.project_slug}}/TODO.md | 90 ++++++++++ 5 files changed, 320 insertions(+), 3 deletions(-) create mode 100644 {{cookiecutter.project_slug}}/.opencode/skills/session-workflow/SKILL.md create mode 100644 {{cookiecutter.project_slug}}/TODO.md diff --git a/{{cookiecutter.project_slug}}/.opencode/agents/developer.md b/{{cookiecutter.project_slug}}/.opencode/agents/developer.md index 5fd8e26..a139584 100644 --- a/{{cookiecutter.project_slug}}/.opencode/agents/developer.md +++ b/{{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 diff --git a/{{cookiecutter.project_slug}}/.opencode/skills/session-workflow/SKILL.md b/{{cookiecutter.project_slug}}/.opencode/skills/session-workflow/SKILL.md new file mode 100644 index 0000000..c3356cf --- /dev/null +++ b/{{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 +# - 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: + +- [x] Completed task +- [~] In-progress task +- [ ] Pending task + +--- + +## Phase N: + +- [ ] Task + +--- + +## Session Log + +| Date | Session Summary | +|------------|----------------------------------------| +| YYYY-MM-DD | Initial scaffolding, TODO created | + +--- + +## Notes for Next Session + +- Start with Phase X: "task description" +- +``` + +## 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 diff --git a/{{cookiecutter.project_slug}}/AGENTS.md b/{{cookiecutter.project_slug}}/AGENTS.md index 7210522..5ba3bd3 100644 --- a/{{cookiecutter.project_slug}}/AGENTS.md +++ b/{{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 +``` diff --git a/{{cookiecutter.project_slug}}/README.md b/{{cookiecutter.project_slug}}/README.md index cb57b53..e1fc64a 100644 --- a/{{cookiecutter.project_slug}}/README.md +++ b/{{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 ``` diff --git a/{{cookiecutter.project_slug}}/TODO.md b/{{cookiecutter.project_slug}}/TODO.md new file mode 100644 index 0000000..017a166 --- /dev/null +++ b/{{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