| name | todo |
| description | Full workflow for picking up and completing a TODO item from TODO.md — read the backlog, clarify, implement, install, browser-test, update docs, and move the item to Completed. |
| license | MIT |
| compatibility | opencode |
Overview
This skill governs the end-to-end process of working through items in TODO.md. Every step below is mandatory — none may be skipped.
Step-by-step workflow
1. Read the backlog
Open TODO.md and identify the first item listed under the # Backlog section. That is the item you will work on. Do not pick a different item.
2. Ask clarifying questions upfront
Before writing a single line of code:
- Re-read the TODO item carefully.
- Identify every ambiguity — implementation approach, scope, edge cases, UI placement, data shape, etc.
- Use the
question tool to ask all clarifying questions at once in a single message. Do not drip-feed questions across multiple rounds.
- Wait for the user's answers before proceeding to implementation.
If the item is completely unambiguous, state that explicitly and ask the user to confirm before proceeding.
3. Implement the TODO item
- Load the relevant skills (
go-backend, vue-frontend, db-migrations, add-service, install-package) as needed before writing code.
- Use
TodoWrite to plan and track sub-tasks for the implementation.
- Follow all project conventions described in
AGENTS.md and the loaded skills.
- Do not commit code unless the user explicitly asks.
4. Build and install
Run the following and fix any errors before continuing:
make install
sudo systemctl restart devctl
Check for startup errors:
sudo journalctl -u devctl -n 40 --no-pager
Do not proceed to testing until the service is running cleanly.
5. Write and run integration tests
If fixing a bug: write a failing test that reproduces the bug before touching implementation code. Confirm it fails, then fix the bug, then confirm the test passes. This is non-negotiable.
For all work:
- Load the
integration-testing skill for backend/API changes; load testing-dashboard for UI changes.
- Write end-to-end tests that cover every part of the feature or fix — not just the happy path.
- Run the tests inside the Incus container (never against the host). See
integration-testing skill for the full workflow.
- If anything is broken, fix it and repeat steps 4–5 until all tests pass.
- Do not consider the task done until automated tests exist and pass.
6. Update the README
Open README.md and make targeted updates:
- New feature → add a description under the relevant section (or create a new section).
- Changed feature → update the existing description.
- Removed feature → delete or strike the entry.
Only update sections that are actually affected. Do not rewrite unrelated content.
7. Update CHANGELOG.md
If CHANGELOG.md does not exist, create it with an # Unreleased section at the top.
Add one or more bullet points under # Unreleased (or today's date heading if the file uses date-based sections) that describe what was added, changed, or fixed. Keep entries concise and user-facing (e.g. - Added spx profile viewer with timeline and flamegraph).
8. Move the item to Completed
In TODO.md:
- Remove the bullet from the
# Backlog section.
- Append it to the
# Completed section with a date/time stamp in the format:
- <original item text> *(completed YYYY-MM-DD)*
Checklist
Use this as a final gate before declaring the task done:
