Table of Contents

Your First Feature: Complete Workflow

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 uses git for version control. Spec Kitty abstracts the VCS operations into simple commands.

Overview

Workflow path:

/spec-kitty.specify → /spec-kitty.plan → /spec-kitty.tasks → spec-kitty next → /spec-kitty.accept → /spec-kitty.merge

You will build a tiny "task list" feature as the concrete example.

Step 1: Create the Specification

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.md
  • A new mission directory created under kitty-specs/

Step 2: Create the Technical Plan

Stay in the repository root checkout. Planning happens there, but the mission target branch can be the current branch or an explicit branch you chose before creation.

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.md
  • Updated planning artifacts in the repository root checkout

Step 3: Generate Work Packages

In 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.

Step 4: Enter the Runtime Loop

Start the mission loop from your terminal:

spec-kitty next --agent claude --mission ###-task-list --json

The runtime returns the next action to take. During implementation you will usually see an implement decision for a specific WP.

Execute that action with the lower-level command the runtime expects:

spec-kitty agent action implement WP01 --agent claude

That command allocates or reuses the correct lane workspace. Make your code changes there, run the relevant tests, then report the result back to the runtime:

spec-kitty next --agent claude --mission ###-task-list --result success --json

Repeat the loop until the runtime starts issuing review work instead of implementation work.

Step 5: Review the Work Package

When the runtime points you at review work, run the matching action:

spec-kitty agent action review WP01 --agent claude

Address any review feedback, then continue the spec-kitty next loop until the mission is ready for acceptance.

Step 6: Accept and Merge

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 the mission's target branch and the worktrees cleaned up.

Troubleshooting

  • "Planning created a worktree": Planning stays in the repository root checkout in 3.1.x. If you see an unexpected planning worktree, upgrade with spec-kitty upgrade.
  • "I want to plan from here but not land on main": Stay in the repository root checkout and choose the right target branch first. See How to Keep Main Clean.
  • "WP has dependencies": Keep following the spec-kitty next decisions; the runtime will only issue implementation work when its dependencies are satisfied.
  • Review fails validation: Run spec-kitty validate-tasks --fix and re-run /spec-kitty.review.

What's Next?

Continue with Multi-Agent Workflow to learn parallel development with multiple agents.

Reference Documentation

Learn More

Edit this page