Divio type: Tutorial
This tutorial walks you through the entire Spec Kitty workflow from specification to merge.
Time: ~2 hours Prerequisites: Completed Getting Started
Note: This tutorial works with both git and jujutsu (jj) backends. Spec Kitty abstracts the VCS operations, so the workflow is the same. For jj-specific features like auto-rebase and non-blocking conflicts, see Jujutsu Workflow Tutorial.
Workflow path:
/spec-kitty.specify → /spec-kitty.plan → /spec-kitty.tasks → /spec-kitty.implement → /spec-kitty.review → /spec-kitty.accept → /spec-kitty.merge
You will build a tiny “task list” feature as the concrete example.
From the project root, in your agent:
/spec-kitty.specify Build a task list app with add, complete, and delete actions.
Answer the discovery interview until it completes.
Expected results:
kitty-specs/###-task-list/spec.mdmain with the new specStay in the main repository (planning happens in main in v0.11.0+).
In your agent:
/spec-kitty.plan Use Python 3.11, SQLite, and a minimal CLI interface.
Answer the planning questions and confirm the Engineering Alignment summary.
Expected results:
kitty-specs/###-task-list/plan.mdmain with the planIn your agent:
/spec-kitty.tasks
This generates tasks.md and individual work package files under:
kitty-specs/###-task-list/tasks/
Each WP file includes frontmatter with its lane and dependencies.
Start with the first planned package (example uses WP01).
In your agent:
/spec-kitty.implement
This moves the WP to doing and prints the implementation prompt. Then create the workspace from your terminal:
spec-kitty implement WP01
Expected output (abridged):
OK Created workspace: .worktrees/###-task-list-WP01
Move into the new worktree and implement the required changes:
cd .worktrees/###-task-list-WP01
When finished, return to the main repo and run the review step.
From the main repo, ask your agent to review the work package.
In your agent:
/spec-kitty.review
Or via CLI:
spec-kitty agent workflow review WP01
Follow the review instructions and address any feedback.
Once review passes, validate and accept.
In your agent:
/spec-kitty.accept
Or via CLI:
spec-kitty accept
Then merge the feature branches.
In your agent:
/spec-kitty.merge
Or via CLI:
spec-kitty merge
You should see the feature merged into main and the worktrees cleaned up.
main. If you see a feature worktree, upgrade with spec-kitty upgrade.spec-kitty implement WP02 --base WP01 as suggested.spec-kitty validate-tasks --fix and re-run /spec-kitty.review.Continue with Multi-Agent Workflow to learn parallel development with multiple agents.