lite-sdd-overview

Entry point for the lite-sdd methodology. It orients the agent and routes to the task skills. This is the only skill that owns the repository layout and the global principles — task skills link back here rather than repeating them.

Spec-Driven Development keeps the specification and the code in lockstep: the spec is the functional source of truth, and the code is its image. The goal is to minimise the gap between the two so the spec is always current, never a stale artifact.

Repository layout

A lite-sdd project keeps its specifications under a top-level specs/ directory, one folder per feature. Each feature folder holds a functional spec.md and, once built, a technical implementation.md:

<project-root>/
├── specs/
│   ├── README.md                      # Index of the apps and features
│   ├── 001-roles/
│   │   ├── spec.md                    # Functional source of truth (what)
│   │   └── implementation.md          # Technical image of the code (how it is built)
│   ├── 002-budget-calculation/
│   │   ├── spec.md
│   │   └── implementation.md
│   ├── 100-manage-organization/
│   │   ├── spec.md
│   │   └── implementation.md
│   ├── 200-access-app/
│   │   ├── spec.md
│   │   └── implementation.md
│   └── 201-list-records/
│       ├── spec.md
│       └── implementation.md
└── <application code>

spec.md is written before the code (by lite-sdd-specify); implementation.md is written/updated after the code (by lite-sdd-implement) and stays the living image of what is actually built.

Numbering by hundreds — one block per application

Features are numbered in blocks of one hundred. Each hundred-block groups all the features of a single application or major epic, leaving room for up to 99 features per block:

Block	Scope
000–099	Backend / shared foundation — server-side logic, APIs, and data-layer extensions consumed by the apps above
100–199	First application (for example a back-office / admin app)
200–299	Second application (for example an end-user / front-office app)
300+	Further applications — one hundred-block each

The block boundary is functional, not technical: bump to the next hundred when you start a distinct application or a distinct major epic. The hundreds scheme keeps a multi-app project organised and makes every feature individually addressable.

Feature folder naming

Each folder is NNN-concise-feature-name:

• NNN — the three-digit number. Prefixing with the number lets you reference a feature unambiguously in a prompt ("update 201", "implement 206").
• concise name — lowercase, hyphen-separated, short and functional.

Splitting work into features is the user's call — the methodology does not auto-decompose the work for them.

The specs/README.md index

specs/README.md is the table of contents for the whole project — the entry point a human or agent reads to navigate the specs. It is a nested tree, three levels deep, every line a link:

• Level 0 — the *00 block node (000-…, 100-…, 200-…): the application or shared-foundation spec. Links to its spec.md.
• Level 2 — each feature (N01, N02, …) nested under its block. Links to the feature's spec.md.
• Level 3 — each user story (US-NNN-01, …) nested under its feature. Links to the ## US-NNN-01 — … heading anchor inside that spec.md.

A *00 block node lists no user stories of its own (it has none — see below); its features hang directly under it.

# Specifications

Table of contents for every app, feature, and user story in this project.

## 000 — Backend / shared foundation

- [`000-dataverse-backend`](./000-dataverse-backend/spec.md)
  - [`001-recalculation-auto`](./001-recalculation-auto/spec.md)
    - [US-001-01 — Creation](./001-recalculation-auto/spec.md#us-001-01--creation)
    - [US-001-02 — Modification](./001-recalculation-auto/spec.md#us-001-02--modification)

## 100 — Agenda app

- [`100-agenda-app`](./100-agenda-app/spec.md)
  - [`101-grid-view`](./101-grid-view/spec.md)
    - [US-101-01 — Grid structure](./101-grid-view/spec.md#us-101-01--grid-structure)

lite-sdd-init creates this index; lite-sdd-specify keeps it in sync whenever a feature folder or a user story is added, renamed, or removed.

The *00 application-level spec

The first feature of each block (100, 200, 300, …) is the application-level spec. It describes the overall structure of that app and the rules that apply across all its features (global layout, shared header, cross-cutting constraints). Because it has to state which platform or runtime the app targets, this is the one spec allowed to carry technical vocabulary; every other spec in the block stays functional and refers back to it.

Skill routing

Skill	Use it to
lite-sdd-init	Bootstrap a new SDD project — agent instruction file, README, and the specs/ layout
lite-sdd-specify	Write or update a spec.md — the functional source of truth — before code
lite-sdd-implement	Plan the implementation and keep the technical documentation reflecting the actual code

Global principles

1. Functional altitude. Specs describe what the product does, not how it is built. Keep implementation detail out — the only exception is the *00 application-level spec, which may name the target platform because it must.
2. Concise and precise. Go straight to the essential. No filler, no blabla. A spec is short and exhaustive: it states every business rule, acceptance criterion, and edge case. Prefer tables and diagrams over prose.
3. Two audiences. Every spec serves humans (who validate it) and agents (who build from it). It must read clearly for both.
4. The user owns decomposition. Feature boundaries and the hundreds numbering are decided by the user, not inferred.
5. Single-source. State a shared rule once — here — and route to it, rather than repeating it across skills.

Anti-patterns (DO NOT DO)

Anti-pattern	Correct approach
Leaking implementation detail into a feature spec	Keep it functional; put platform/runtime context only in the *00 spec
Verbose prose that buries the rules	Tighten to the essential; use tables and diagrams
A spec that lists happy-path behaviour only	State the business rules, acceptance criteria and edge cases
Auto-splitting the work into features	Let the user define feature boundaries and numbers
Re-deciding the numbering per feature	Keep one hundred-block per application, ≤ 99 features each

Skill boundaries

This skill covers methodology orientation and routing only. It does not cover:

• New project setup → lite-sdd-init
• Writing a specification → lite-sdd-specify
• Planning and syncing the implementation → lite-sdd-implement