🧭 Way of Working: Spec‑Driven + TDD¶

Welcome, Visualli Crew. This document describes how we build using Spec‑Driven Development (SDD) and Test‑Driven Development (TDD).

Watch: Using Spec‑Kit with Visualli

Visual Overview¶

flowchart LR
    A[📋 Spec] --> B[📐 Plan]
    B --> C[🎯 Prime]
    C --> D[🔄 TDD Loop]
    D --> E[✅ Ship]

    style A fill:#202020,stroke:#12C7D3,stroke-width:2px,color:#fff
    style B fill:#202020,stroke:#325E8C,stroke-width:2px,color:#fff
    style C fill:#202020,stroke:#8A70A6,stroke-width:2px,color:#fff
    style D fill:#202020,stroke:#F54A57,stroke-width:2px,color:#fff
    style E fill:#202020,stroke:#F28C16,stroke-width:2px,color:#fff

Roles & Responsibilities¶

🧠 Product
Define the spec in .specify/specs/.
Run /speckit.specify <feature-name>.
Collaborate with UX and Engineering to refine.
🎨 UX / Design
Validate user stories and flows in the spec.
Provide visual review during the Green phase.
Review specs and share feedback.
⚙️ Engineering
Create the plan from the spec.
Prime the context by loading the constitution.
Execute the TDD loop: Red → Green → Refactor.
Use /speckit.plan, /speckit.implement, /speckit.checklist.

Repository Structure (Thinking vs Doing)¶

We separate "Thinking" (specs/plans) from "Doing" (src/tests) to help humans and AI align.

visualli-labs/
├── .github/
│   ├── agents/                   # Configuration files for AI agents (rules/settings)
│   └── prompts/                  # Reusable system prompts
│
├── .specify/                     # Root directory for Spec-Driven Development
│   ├── memory/
│   │   └── constitution.md       # Global technical constraints and style guides
│   ├── specs/                    # Functional requirements (The "What")
│   ├── plan.md                   # Current implementation checklist (The "How")
│   └── scripts/                  # Utilities for context packing
│
├── src/
│   ├── components/
│   │   └── [Feature]/
│   │       ├── [Component].tsx        # Component source code
│   │       └── [Component].spec.tsx   # Co-located unit tests
│   ├── hooks/
│   │   └── __tests__/                 # Tests for custom hooks
│   └── ...
│
├── tests/                        # Integration and Setup
│   ├── setup.ts                  # Global test environment configuration
│   └── e2e/                      # End-to-end testing scenarios
│
└── vitest.config.ts              # Test runner configuration

Phase 1: Define (The Spec)¶

Location: .specify/specs/
Output: <feature>.md (spec file)

flowchart LR
  A[Input: Feature request or user story] --> B[Output: <feature>.md]

  style A fill:#202020,stroke:#7F7F7F,stroke-width:2px,color:#fff
  style B fill:#202020,stroke:#12C7D3,stroke-width:2px,color:#fff

Steps: - Create the spec: add a new markdown file in .specify/specs/ (e.g., node-explorer.md). - Draft requirements: User Stories, Inputs, Outputs, Edge Cases. - Refine with AI:

/speckit.specify node-explorer
/speckit.clarify

Phase 2: Plan (The Checklist)¶

Location: .specify/plan.md
Output: step‑by‑step technical checklist

Steps: - Generate the plan:

/speckit.plan node-explorer

Review for small, testable tasks.
Validate coverage and consistency:

/speckit.analyze
/speckit.tasks

Phase 3: Prime (The Context)¶

Location: Terminal / Copilot Chat
Input: Plan + Constitution
Output: Aligned AI ready to code

Load the Constitution (our “Laws”: Tech Stack, Styling Rules, Forbidden Libraries):

/speckit.constitution

Phase 4: Execute (The TDD Loop)¶

We strictly follow Red‑Green‑Refactor. Do not write implementation code without a failing test.

stateDiagram-v2
  direction LR
  [*] --> RED
  RED: Write test, confirm it fails
  RED --> GREEN
  GREEN: Minimal code to pass
  GREEN --> REFACTOR
  REFACTOR: Clean up, keep tests green
  REFACTOR --> RED: Next feature

  classDef redState fill:#202020,stroke:#F54A57,stroke-width:2px,color:#fff
  classDef greenState fill:#202020,stroke:#12C7D3,stroke-width:2px,color:#fff
  classDef yellowState fill:#202020,stroke:#FFD347,stroke-width:2px,color:#fff

  class RED redState
  class GREEN greenState
  class REFACTOR yellowState

Red: Write a test for the specific functionality; run the suite and confirm failure.
Green: Write just enough code to make the test pass.
Refactor: Improve design while tests stay green.

Optional helpers during Execute:

/speckit.implement
/speckit.checklist

Spec‑Kit Commands Cheat Sheet¶

graph LR
  root((Spec‑Kit))

  %% Core Workflow Branch
  root --> CW[CORE WORKFLOW]
  CW --> S1(/speckit.specify)
  CW --> S2(/speckit.plan)
  CW --> S3(/speckit.tasks)
  CW --> S4(/speckit.implement)

  %% Quality Branch
  root --> Q[QUALITY]
  Q --> Q1(/speckit.constitution)
  Q --> Q2(/speckit.clarify)
  Q --> Q3(/speckit.analyze)
  Q --> Q4(/speckit.checklist)

  %% Brand Styling
  style root fill:#202020,stroke:#F28C16,color:#fff,stroke-width:2px
  style CW fill:#202020,stroke:#12C7D3,color:#fff,stroke-width:2px
  style Q fill:#202020,stroke:#12C7D3,color:#fff,stroke-width:2px

  %% Leaf Node Styling
  classDef command fill:#202020,stroke:#F28C16,stroke-width:1px,color:#fff;
  class S1,S2,S3,S4,Q1,Q2,Q3,Q4 command;

Tips for Devs¶

The Constitution is law: if a library is not allowed, point to .specify/memory/constitution.md.
Update the plan: mark completed items with [x] in .specify/plan.md.
Test isolation: mock external dependencies; use tests/setup.ts for global config.
Commit often: treat every checked box in plan.md as a commit.

git commit -m "feat: complete step 1 of node explorer plan"

Feature Development Checklist¶

✓ Product   → /speckit.specify <feature>     [ Define requirements ]
✓ Product   → /speckit.clarify               [ Clarify gaps ]
✓ Eng       → /speckit.plan <feature>        [ Create plan ]
✓ Eng       → /speckit.analyze               [ Check consistency ]
✓ Eng       → /speckit.constitution          [ Load guidelines ]
✓ Eng       → /speckit.tasks                 [ Generate tasks ]
✓ Eng       → /speckit.implement             [ Build & test ]
✓ Eng       → /speckit.checklist             [ Validate quality ]
✓ Team      → git commit + push              [ Ship it! 🚀 ]