SDD 06 - Spec Kit: Lab Route
SDD Learning · Previous: Spec Kit starter guide · Next: OpenSpec starter guide
Levels 2 to 6 with Spec Kit. Walk a requirement through specification, plan, tasks and convergence, and review each artifact on the way. Read the Spec Kit starter guide first: it explains the tool, and this page applies it to the shared lab.
Walk the Matt Pocock Skills lab route first if you have not: it is the baseline this route is compared with.
/speckit.specify. Use the names your agent exposes. Invoke each command separately and read its output before continuing.
Colors mean the same thing in every diagram of this Learning: see the color key.
The route at a glance
| Level | What you use | What it leaves behind |
|---|---|---|
| 2 · Specify | speckit-constitution, speckit-specify, speckit-clarify | Constitution and feature spec.md |
| 3 · Plan | speckit-plan, speckit-tasks, speckit-analyze | plan.md and tasks.md that agree with the spec |
| 4 · Implement | speckit-implement | The change and its tests |
| 5 · Verify | Your own run, then speckit-converge | Observed results and convergence findings |
| 6 · Review | Human review of the findings and the diff | A decision and a handoff |
The contract, the acceptance criteria AC1 to AC7 and the level checks are the same on every route and are described in the lab. Only the steps differ.
Set up once
Download the starter lab, unpack it and run the baseline from a fresh copy of its doc-index-starter directory:
$ python3 -m unittest discover -v $ python3 doc_index.py sample-docs
The four baseline tests pass and the CLI prints two filename/title rows. Install the specify CLI as the starter guide describes. Then initialize Spec Kit inside the lab directory, not in an unrelated empty project:
$ specify version $ specify init --here --integration copilot
Review the initialization changes. If the CLI asks to merge into a non-empty directory, confirm only after preserving your work; --force should be a deliberate choice.
Record the installed version, the agent and the model in training/WORKSHEET.md.
Level 2 · Specify
Establish the project rules, in agent chat:
/speckit-constitution Keep the project small. Preserve documented behavior. Test observable behavior. Avoid unnecessary dependencies. Require actual verification evidence before calling a change complete.
Describe the behavior:
/speckit-specify Add an optional --format json mode to the existing Markdown indexing CLI. Keep default text output byte-for-byte unchanged (AC1). JSON is an array of objects (AC2) with exactly the string fields file and title, sorted by filename (AC3). An empty directory returns [] (AC4). Unknown formats and missing directories fail with a nonzero exit status, a useful stderr message and empty stdout (AC5). Quotes and non-ASCII characters in titles survive JSON encoding and decoding (AC6). Keep the top-level-only scan and the title fallback (AC7). Use the Python standard library only. Do not add recursion, network access, a database or a web interface.
Resolve anything the agent cannot infer from the current code:
/speckit-clarify Focus on compatibility, deterministic ordering, JSON encoding and error behavior. Read the baseline before proposing changes. Keep the acceptance IDs AC1 to AC7.
Level 2 check: a partner can explain the promised behavior and the exclusions from the artifact alone.
Level 2 complete. You turned “add JSON” into a contract someone else can check. Good work: this is the step most people skip.
Level 3 · Plan
Provide the implementation constraints:
/speckit-plan Use Python 3.11+ standard library, argparse, pathlib and json. Preserve the existing collect function's behavior. Exercise the command through subprocess-based unittest tests. JSON whitespace is not part of the contract; parsed values are. Do not add dependencies or change unrelated files.
Generate the tasks:
/speckit-tasks
Inspect their consistency:
/speckit-analyze
Read the artifacts. A task that changes the default output without a compatibility test is a planning defect. Fix that before implementation.
Complete at least three rows of the worksheet's requirement-to-evidence table, one for compatibility and one for an error case.
Level 3 check: the plan identifies how AC1 will be preserved and checked.
Level 3 complete. Every criterion you care about now points to a task and a check. From here on you build what you have already decided.
Level 4 · Implement
/speckit-implement
Inspect the diff for unrelated changes. Ask for one observable behavior at a time, with a relevant failing test before the change.
Level 4 check: JSON output works, the original tests still pass, and there are new tests for the feature.
Level 4 complete. The feature exists and the old behavior is still there. Run it once more, just to see your JSON come out.
Level 5 · Verify
Run the commands yourself in the lab directory:
$ python3 -m unittest discover -v $ python3 doc_index.py sample-docs $ python3 doc_index.py sample-docs --format json
The default output should still be the original two tab-separated rows. The JSON should parse to this value; spacing is unimportant:
[{"file":"alpha.md","title":"Alpha"},{"file":"beta.md","title":"beta"}]The new tests should also cover an empty directory, an invalid format, a missing directory and a title containing quotes or non-ASCII text. Record the commands, the results and the revision in the worksheet. The independent checker in the trainer kit can be run against your directory.
Then ask whether implementation and artifacts agree:
/speckit-converge
Convergence can identify remaining work. A model-generated verdict still needs the actual test results behind it.
Level 5 check: the evidence is from the final code and every unmet criterion is visible.
Level 5 complete. You can show what ran and what it returned. Enjoy the passing run.
Level 6 · Review
Review the convergence findings and the diff against spec.md. Implement the justified corrections and repeat the assessment. Then have a second participant answer the handoff questions from the artifacts alone.
| Handoff question | Evidence to point to |
|---|---|
| What did we agree? | Accepted behavior and exclusions |
| What changed? | The implementation diff and the bounded task |
| How was it checked? | Test command, result and checked revision |
| What remains? | A precise gap or next task |
If the next participant must reconstruct the entire chat to answer these questions, improve the durable record.
Level 6 check: the worksheet states accepted, incomplete or needs revision, says why, and points to what the next session must read.
Level 6 complete. You have walked the whole loop on this route. Take a moment to enjoy that before you go on.
Track checkpoint
Pick AC1. Point to the specification, the implementation task and the test that preserve default text output. Explain what would make that test fail.
Spec Kit lab route complete. You can now walk a requirement through specification, plan, tasks and convergence, and show the evidence at the end.
Compare with your baseline
Put this worksheet beside the one from the Matt Pocock Skills lab route. Which corrections did each route need, which artifacts would you keep, and what would a fresh session find first? The comparison says what to observe. The routes differ in emphasis, and one run is not a ranking.