zigcc/skills

Overview

This skill provides documentation-driven development (Doc-Driven-Dev) workflow guidance to keep stories, ROADMAP status, and docs synchronized with code and tests. It enforces a strict cycle: prepare docs and Story files first, implement and test, then finalize documentation and release. The skill helps prevent common mistakes like marking a Story complete with unchecked items or committing code without updating documentation.

How this skill works

The skill inspects story files, ROADMAP.md markers, documentation files, changelog entries, and source code notes to validate consistency. It provides concrete checks and shell commands to find unchecked tasks, mismatched status markers, TODO/FIXME/XXX comments, and test-run requirements. It also prescribes the documentation-first development cycle and rules for refactoring, completion, and release.

When to use it

• Starting a new feature or version — create a Story file and list acceptance criteria first
• Implementing code — ensure Story checkboxes track progress and add code comments where needed
• Before committing or releasing — verify tests pass, changelog entries exist, and Story+ROADMAP agree
• During refactors — follow the phased process and do not add new features until tests pass
• Performing repo audits — scan for TODO/FIXME/XXX and uncompleted Story tasks

Best practices

• Create or update the Story file at feature start and enumerate all acceptance criteria
• Only mark a Story or ROADMAP version ✅ when every acceptance checkbox is checked
• Run full test suite (zig build test) and fix failures before committing
• Sync user-facing docs and CHANGELOG during the coding phase, not after release
• Keep refactoring and new feature commits separate and verify tests between phases

Example use cases

• Add a new API feature: create stories/vX.Y.Z-*.md, update ROADMAP.md, implement code, run tests, update docs and CHANGELOG
• Complete a bugfix session: update the Story tasks, implement tests, ensure tests pass, then mark session entry in CHANGELOG
• Refactor module layout: follow phased refactor rules, run full tests after reorg, then proceed to add features only after verification
• Release a version: ensure all Story checkboxes are [x], run verification commands, update ROADMAP and CHANGELOG entries