tins

---
name: tins
description: creating TINS-compliant README files, generating implementations from TINS READMEs, and validating TINS documentation. Use when users want to build TINS README files from scratch, generate working code from an existing TINS README, validate or improve a TINS README for completeness, or learn the TINS distribution paradigm. Triggers on phrases like "TINS README", "there is no source", "create a README for LLM generation", "generate code from this README", "validate my TINS doc", or when a user wants to describe software so an AI can build it.
license: Apache-2.0
---

# TINS (There Is No Source) — Claude Skill

## What is TINS?

TINS is a software distribution paradigm where **only README files are distributed** — no source code. AI models generate the implementation on demand from the README. The same README produces better code as models improve over time.

Key benefits: tiny distribution size, automatic improvements, no executable code = fewer attack vectors, platform independence.

**Official resources:** [thereisnosource.com](https://thereisnosource.com) · [TINS-MCP server](https://github.com/ScuffedEpoch/TINS-MCP) · [Discord](https://discord.com/invite/uubQXhwzkj)

---

## Your Four Core Modes

### 1. Generate a TINS README
When a user describes a project, produce a complete TINS-compliant README. Ask clarifying questions first if needed — features, target users, platform, rough UI shape, any hard technical constraints.

### 2. Generate Code from a TINS README
When given a TINS README, produce a complete, functional implementation. No TODOs, no placeholders. Read the full README before writing a line of code. Choose appropriate modern tech unless specified.

### 3. Validate a TINS README
Review against the checklist below. Report specifically what is missing, ambiguous, or contradictory.

### 4. Enhance a TINS README
Identify gaps, ambiguities, and weak sections. Produce an improved version with better detail, concrete examples, and clearer structure.

---

## Required README Sections

Every valid TINS README must contain all four:

| # | Section | What to include |
|---|---------|-----------------|
| 1 | **Project Title** (H1) | App name only |
| 2 | **Description** | 1–3 paragraphs: purpose, audience, key differentiators |
| 3 | **Functionality** | Core features, UI layout (ASCII/Mermaid), behavior specs, user flows, edge cases |
| 4 | **Technical Implementation** | Architecture, data models with typed fields, key algorithms |

### Recommended Optional Sections
- Style Guide (colors, typography, animations)
- Testing Scenarios
- Accessibility Requirements
- Performance Goals
- Extended Features (optional enhancements)

### Metadata Tags (optional LLM hints)
```markdown
<!-- TINS Specification v1.0 -->
<!-- ZS:COMPLEXITY:MEDIUM -->
<!-- ZS:PRIORITY:HIGH -->
<!-- ZS:PLATFORM:WEB -->
<!-- ZS:LANGUAGE:JAVASCRIPT -->
```

---

## Validation Checklist

Use this when validating or reviewing a README:

- [ ] Clear project title (H1) and description
- [ ] All core features listed comprehensively
- [ ] User interface described with layout diagram
- [ ] Technical architecture specified
- [ ] Data models defined with field names and types
- [ ] User flows and interactions described
- [ ] Edge cases and error states addressed
- [ ] Examples provided for complex behaviors
- [ ] Consistent terminology throughout (no "cart" vs "basket" drift)
- [ ] No contradictions between sections
- [ ] No external references required to understand the spec
- [ ] Accessibility requirements noted
- [ ] Performance expectations defined

---

## Writing Quality Guide

### Be Explicit, Not Implicit

✅ **Good:** "The email field must validate format as `user@domain.tld` before submission. Invalid formats display the message: *'Please enter a valid email address.'*"

❌ **Avoid:** "The application should check if emails are valid."

### Provide Concrete Examples

✅ **Good:** Search supports `search("name:John")`, `search("name:John role:admin")`, `search("age:30-40")`

❌ **Avoid:** "Search supports filtering by properties and ranges."

### Use Consistent Terminology

Pick one term per concept and use it everywhere. Decide up front: cart or basket, user or account, post or article.

### Structure Hierarchically

```markdown
## User Management
### User Registration
#### Form Fields
#### Validation Rules
#### Success / Error Flows
```

### Specify Without Overconstraining

✅ **Good:** "Use a client-server architecture with a RESTful API. Handle state on the client side."

❌ **Avoid:** "Must use React + Redux + Express.js + MongoDB." (locks out better alternatives)

### Include UI Layouts

Use ASCII art or Mermaid for layouts:

```
+-------------------------------------------+
| ✏️ My Todo List              🌙 [Search]  |
+-------------------------------------------+
| ➕ Add New Task                            |
+-------------------------------------------+
| Filters: All | Active | Completed          |
+-------------------------------------------+
| ☐ High | Buy groceries    | Today  | 🗑️  |
| ☑ Med  | Call dentist     | Yest.  | 🗑️  |
+-------------------------------------------+
```

### Define Data Models Precisely

```javascript
{
  id: string,                        // Unique identifier (UUID)
  title: string,                     // 1–200 characters, required
  completed: boolean,                // Default: false
  priority: "low" | "medium" | "high",
  dueDate: Date | null,              // ISO 8601, optional
  createdAt: Date                    // Set on creation, immutable
}
```

---

## Common Pitfalls

| Pitfall | Fix |
|---------|-----|
| Vague requirements ("fast and friendly") | Specify: "respond within 100ms, use consistent nav patterns" |
| Contradictory specs | Check: offline + no local storage = contradiction |
| Underspecified edge cases | Add: empty states, error states, limits, invalid inputs |
| Excessive flexibility | Narrow down: specify auth approach, storage mechanism |
| Missing user flows | Add step-by-step flows for critical paths |

---

## Code Generation Guidelines

When generating an implementation from a TINS README:

1. **Read comprehensively** — understand all sections before writing code
2. **Match specs exactly** — implement what's described, no more, no less
3. **Choose modern tech** — unless the README specifies otherwise
4. **Implement completely** — no TODOs, stubs, or placeholders
5. **Handle all edge cases** — every error state mentioned in the README
6. **Write clean, documented code** — comments for non-obvious logic
7. **Verify it actually works** — trace through the primary user flows mentally

---

## Reference Files

For deeper detail, read these when needed:

- `references/specification.md` — Full formal TINS specification with schema details, diagram syntax, and extension guidelines
- `references/best-practices.md` — Comprehensive best practices with examples, platform-specific guidance, and the full template
- `references/developer-guide.md` — End-to-end developer workflow: planning → writing → testing → publishing

---

## Example Interaction Patterns

**"I want to create a TINS README for a weather app"**
→ Ask: What features? What platform (web/mobile)? Any design preferences? Then generate the full README.

**"Generate code from this TINS README: [content]"**
→ Read all sections, then produce a complete working implementation in an artifact.

**"Is this TINS README complete? [content]"**
→ Run through the validation checklist, report specific gaps with suggested fixes.

**"Improve this TINS README: [content]"**
→ Identify weak sections, then output an enhanced version with better detail and examples.

---

Remember: the goal is READMEs so complete and unambiguous that any capable AI can generate a quality implementation from them. Prioritize **clarity**, **completeness**, and **consistency**.