Cliplin

Feature-centric Spec-Driven Development framework.

Specifications are the source of truth; code is the output of the system.

"Describe the problem clearly, and half of it is already solved." — Kidlin's Law

Install and get started →
>

What is Cliplin?

An operational framework that brings specification-driven development to real projects, with real teams and real constraints.

The problem: AI tools fail in enterprise environments not because models are weak, but because context is implicit, fragmented, or inconsistent. There is no single source of truth.
The solution: Specifications live versioned in the repository. AI only acts on well-defined specifications. Every change is traceable to a specification.

The four pillars of Cliplin

Four complementary specification types, each with a clear responsibility.

🎯

Business Features

.feature (Gherkin). Defines what the system must do and why. If the feature doesn't exist, the functionality doesn't exist.

⚙️

TDR

Markdown. Technical Decision Records. Defines how to implement: conventions, validation rules, technical contract.

📋

ADRs and business

Markdown. Preserves why technical decisions were made. Prevents reopening closed decisions.

🎨

UI Intent WIP

YAML. Defines how the system expresses intent to users: screens, components, roles. Intent, not pixels.

Shared knowledge, made simple

Share specs and know-how with anyone—your team, other teams, or the wider community. Cliplin’s knowledge system lets you add external packages (ADRs, TDRs, features, rules) and have them indexed like the rest of your project, so they become part of your project’s general knowledge.

Package content is indexed in the same context store as your own specs. The AI doesn’t see “your docs” vs “external docs”—it sees one body of knowledge. Shared knowledge is first-class.

Why use it?

  • Share with anyone: internal teams, other companies, or open-source—one simple add and it’s part of the project.
  • Version it: pin by branch, tag, or commit so upgrades are under your control.
  • One context: your specs and package specs are queried together; no copy-paste, no second-class context.

Add a package

cliplin knowledge add <name> github:org/repo main

For list, show, update, remove and full usage, see the README.

Installation and usage

Requirements: Python 3.10+, uv (recommended), and a compatible AI assistant (Cursor, Claude Desktop, etc.).

1. Install Cliplin

Recommended: install from GitHub with uv to always get the latest version.

uv tool install git+https://github.com/Rodrigonavarro23/cliplin.git

2. Initialize your project

Creates the directory structure and configures the AI host.

cliplin init --ai claude-desktop

Cliplin supports: Cursor, Claude Desktop, and more. See the README for options.

This creates cliplin.yaml, docs/features, docs/tdrs, docs/adrs, docs/ui-intent, and the framework package at .cliplin/knowledge/cliplin-framework/.

3. Write specs and index

Write features, TDRs, and ADRs. Then index so the Cliplin MCP (context store) can search them semantically.

cliplin reindex
cliplin reindex --dry-run   # preview
cliplin reindex --type tdr  # by type

4. Work with AI

With Cliplin configured, the AI loads context from the MCP, follows the feature-first flow, and applies TDRs and ADRs when generating code.

Spec-first flow