From 1afdd0a4627ca909b4fba2205e3e606545528aa6 Mon Sep 17 00:00:00 2001
From: nitrix <me@nitrix.one>
Date: Fri, 6 Mar 2026 20:22:39 +0100
Subject: [PATCH] Add spec-kit workflow guide
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Human-readable reference for the clarify → plan → tasks → analyze → implement
loop and the file structure it produces.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
---
 WORKFLOW.md | 94 +++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 94 insertions(+)
 create mode 100644 WORKFLOW.md

diff --git a/WORKFLOW.md b/WORKFLOW.md
new file mode 100644
index 0000000..203784e
--- /dev/null
+++ b/WORKFLOW.md
@@ -0,0 +1,94 @@
+# Spec-Kit Workflow
+
+How to take a feature from spec to working code.
+
+## The Loop
+
+```
+clarify → plan → tasks → analyze → implement
+```
+
+Every step produces files in `specs/NNN-feature-name/`. Review after each step before moving on.
+
+## Steps
+
+### 1. Clarify the spec (optional)
+
+```
+/speckit.clarify
+```
+
+Asks up to 5 targeted questions about gaps or ambiguities in the spec. Answers get folded back into `spec.md`. Skip this if the spec is already solid.
+
+### 2. Create the implementation plan
+
+```
+/speckit.plan
+```
+
+Reads `spec.md`, checks it against the constitution, and produces:
+
+| File | Content |
+|------|---------|
+| `plan.md` | Technical design, architecture decisions, contracts |
+| `research.md` | Background research (if needed) |
+| `data-model.md` | Entity definitions (if new entities are involved) |
+| `contracts/` | API contracts (if applicable) |
+
+**Review this carefully.** The plan shapes everything downstream.
+
+### 3. Generate the task list
+
+```
+/speckit.tasks
+```
+
+Reads the plan and generates `tasks.md` — an ordered, dependency-aware task list. Tasks marked `[P]` can run in parallel.
+
+### 4. Check consistency (optional)
+
+```
+/speckit.analyze
+```
+
+Cross-checks spec, plan, and tasks for contradictions, gaps, or drift. Non-destructive — only reports, doesn't change files.
+
+### 5. Implement
+
+```
+/speckit.implement
+```
+
+Executes the tasks from `tasks.md` phase by phase. Follows TDD: writes tests first, then implementation. Stops at checkpoints so you can verify.
+
+## File structure
+
+Each feature lives in its own directory:
+
+```
+specs/
+  007-view-event/
+    spec.md              # What and why (from /speckit.specify or migration)
+    plan.md              # How (from /speckit.plan)
+    research.md          # Background research (from /speckit.plan)
+    data-model.md        # Entity definitions (from /speckit.plan)
+    contracts/           # API contracts (from /speckit.plan)
+    tasks.md             # Ordered task list (from /speckit.tasks)
+```
+
+## Starting a brand new feature
+
+If the feature doesn't have a spec yet:
+
+```
+/speckit.specify
+```
+
+Describe what you want in plain language. This creates the spec directory and `spec.md` from the template. Then continue with the loop above.
+
+## Tips
+
+- **Don't skip the review.** Each step builds on the previous one. Garbage in, garbage out.
+- **The spec is the source of truth.** If something in the plan contradicts the spec, fix the spec first.
+- **You can re-run steps.** Changed the spec after planning? Run `/speckit.plan` again.
+- **Constitution governs everything.** Principles in `.specify/memory/constitution.md` override ad-hoc decisions.