mattbrailsford-speckl

∴ SPECKL

Human-First. AI-Empowered. Spec-Bound.

SPECKL is a lightweight framework for building software with AI assistance — not AI automation.
It uses specks (minimalist specification documents) to give structure and context to how humans and AIs collaborate inside real development workflows.

This repo contains the official SPECKL Manifesto, starter templates, and example commands for Claude, GPT, and other AI tools.

---

💡 What Is SPECKL?

SPECKL sits between vibe coding and Spec-Driven Development (SDD):

Approach	Description
Vibe Coding	“Let’s see what the AI writes.” Fast but unstructured, context easily drifts.
SPECKL	Humans write specs and code; AI assists within clear, human-defined boundaries.
Spec-Driven Development (SDD)	AI generates entire systems from detailed specs; humans review and refine outputs.

SPECKL is the middle path — a step up from vibe coding (structure and accountability), yet lighter and more human-centric than full SDD automation.

---

📘 What’s Inside

Path	Description
MANIFESTO.md	The SPECKL Manifesto — philosophy & principles
README.md	You’re here!

---

🧩 Core Concepts

📃 Specks

Short, structured definitions of a feature or function that describe:

• Goal — the intent or outcome
• Inputs / Outputs — data flow boundaries
• Constraints — limits on stack, performance, or design
• Done — measurable success condition

They act as context contracts for humans and AIs — small enough to iterate quickly, strong enough to prevent drift.

---

⚙️ Using SPECKL with Claude Code

This repository includes custom slash commands for Claude Code to streamline the SPECKL workflow:

/spkl:init <feature-description>

Initializes a new specification directory with a feature description.

What it does:

• Extracts a short kebab-case name from your description
• Creates a new numbered directory: spec/001-feature-name/, spec/002-feature-name/, etc.
• Creates README.md with your full feature description to guide research
• Updates spec/.current to track the active specification

Example:

/spkl:init "Add JWT-based authentication with email/password login and refresh token support"

Tip: Provide context in your description (where, why, what-for) to better guide research before spec creation.

/spkl:spec <description or refinement>

Creates or reviews a specification following SPECKL methodology.

For new specifications:

1. Researches the topic (existing patterns, best practices, security, performance)
2. Creates a minimal spec.md in the current spec directory with:
   • Goal — user/system outcome
   • Inputs — data, params, triggers
   • Outputs — UI state, API, files
   • Constraints — stack, performance, compliance
   • Dependencies — existing systems to study before implementing
   • Requirements — what needs to be built
   • Out of Scope — explicit non-goals
   • Done — observable outcomes that prove success

For existing specifications:

• Reviews the current spec content
• Applies refinements based on your instructions
• Suggests improvements as a unified diff
• Focuses on removing ambiguity without expanding scope

Examples:

/spkl:spec Add JWT-based authentication with refresh tokens
/spkl:spec Make constraints more specific around token expiry

/spkl:tasks

Breaks down the current spec into actionable implementation tasks.

What it does:

1. Validates that spec/<current-spec>/spec.md exists
2. Translates the spec into concrete, human-actionable tasks
3. Organizes tasks into logical categories (Core Models, API Layer, UI, etc.)
4. Creates spec/<current-spec>/tasks.md with numbered, checkable tasks

Key principles:

• Tasks describe what to build, not how to build it
• Validation tasks are consolidated into broad areas (3-5 items, not 7+)
• Tasks remain focused on implementation, leaving test strategy to developer judgment
• Each task maps clearly back to the spec's Requirements section

Example:

/spkl:tasks

Generates a task list like:

**1. Core Models**
- [ ] 1.1 Create RefundReason enum in transaction domain
- [ ] 1.2 Add refund_reason field to Refund model

**2. Validation**
- [ ] 2.1 Verify refund flows work correctly (full and partial)
- [ ] 2.2 Verify UI validation and display (dropdown, history)

/spkl:collab <request or question> [--task N.N]

Collaborate on implementation with spec context.

What it does:

1. Loads the current spec and task context
2. Enters spec-aware collaboration mode as a pair developer
3. Helps with implementation, questions, refactoring, or any work within spec boundaries