# CALF File Format Specification

Complete specification for the `.calf` file format used by Cleave.

## Table of Contents

1. [What is CALF?](#what-is-calf)
2. [File Extension](#file-extension)
3. [Syntax and Structure](#syntax-and-structure)
4. [Best Practices](#best-practices)
5. [Examples](#examples)
6. [Validation](#validation)
7. [Common Mistakes](#common-mistakes)

## What is CALF?

**CALF** stands for **Cleave Application Level Format**. It's a plain text format for writing software development directives that will be processed by Cleave.

CALF files are:
- **Plain text** (UTF-8 encoded)
- **Free-form** (no strict schema, natural language)
- **Context-aware** (interpreted by LLM with project context)
- **Version-controlled** (commit to git like any source file)

## File Extension

Use `.calf` extension:
```
auth-migration.calf
api-refactor.calf
database-schema-update.calf
```

## Syntax and Structure

### Basic Structure

A CALF file contains a single directive in natural language:

```
Add user authentication with JWT tokens. Support both access
and refresh token flows. Include token blacklist for logout.
```

That's it. No special syntax required.

### Multi-Paragraph Directives

For complex directives, use paragraphs to organize:

```
Implement real-time collaboration features with WebSocket support.

Users should see live cursors, text edits, and presence indicators
for other collaborators. Support conflict resolution for simultaneous
edits using operational transforms.

Add offline mode with local storage. Sync changes when reconnecting.
Include comprehensive integration tests for multi-user scenarios.
```

### Inline Metadata (Optional)

You can include special keywords to control Cleave behavior:

#### Robust Mode
```
cleave-robust

Implement blockchain smart contract with ERC-20 token standard...
```

Triggers verbose reasoning and complete context in child directives.

#### Skip Interrogation
```
iamverysmart

Add JWT authentication with HS256, 15min access token expiry,
7day refresh token expiry, database-backed token blacklist...
```

Skips clarifying questions (assumes directive is complete).

#### No TDD
```
no-tdd

Refactor API layer to use async/await throughout...
```

Disables TDD workflow instructions in task files.

### Structured Sections (Optional)

For very complex directives, you can use markdown-style sections:

```
# Goal
Migrate authentication from sessions to JWT tokens

# Requirements
- Maintain backwards compatibility for 30 days
- Support both auth methods simultaneously
- No downtime during migration

# Out of Scope
- OAuth integration (future work)
- Multi-factor authentication (separate PR)

# Success Criteria
- /auth/token endpoint returns valid JWT
- Protected routes accept both JWT and session
- Existing clients continue working unchanged

# Context
Current session implementation uses Redis with 1-hour TTL.
API consumers include web app, mobile app, and CLI tool.
```

Cleave will parse these sections into the `manifest.yaml` intent structure.

## Best Practices

### 1. Be Specific

**Bad**:
```
Add authentication
```

**Good**:
```
Add JWT-based authentication with refresh tokens. Support token
blacklist for logout. Maintain backwards compatibility with existing
session-based auth for 30-day migration window.
```

### 2. Define Success Criteria

**Bad**:
```
Improve API performance
```

**Good**:
```
Reduce API response time from 500ms to <100ms for /users endpoint.
Add caching layer with Redis. Profile slow queries and add indexes.
Verify with load test (1000 req/s).
```

### 3. Specify Constraints

**Bad**:
```
Add payment processing
```

**Good**:
```
Integrate Stripe for payment processing. Use Checkout Sessions (no
card data on our servers). Support subscription billing (monthly/annual).
Handle webhook events for payment success/failure. Include retry logic
for failed payments.
```

### 4. Exclude Out-of-Scope Items

**Bad**:
```
Build user dashboard with analytics and reports
```

**Good**:
```
Build user dashboard with activity timeline and basic stats (login
count, last active). Analytics and custom reports are out of scope
for this phase. Focus on core dashboard UI and data fetching.
```

### 5. Provide Context (When Needed)

**Bad**:
```
Fix the bug in the auth middleware
```

**Good**:
```
Fix JWT validation bug in auth middleware. Currently, expired tokens
are accepted if refresh token is valid. Middleware should reject
requests with expired access tokens, forcing clients to use the
refresh endpoint. Located in src/middleware/auth.py:45-60.
```

## Examples

### Example 1: Simple Feature
```
Add user profile page with avatar upload. Users should be able to
update display name, bio, and upload a profile picture. Store images
in existing uploads/ directory, resize to 200x200px.
```

**Why it's good**:
- Clear scope (profile page only)
- Specific fields (display name, bio, avatar)
- Technical details (directory, size)

### Example 2: Complex Integration
```
Integrate Stripe payment processing for subscription billing.

Requirements:
- Support monthly ($10) and annual ($100) plans
- Use Stripe Checkout Sessions (hosted payment page)
- Handle webhooks for payment_intent.succeeded and customer.subscription.deleted
- Store subscription metadata in database (user_id, plan, status, expires_at)
- Add admin dashboard for viewing subscription status

Technical Constraints:
- Use Stripe SDK v11+
- Verify webhook signatures
- Implement idempotency for webhook handlers

Success Criteria:
- Users can subscribe via /checkout endpoint
- Successful payment updates database
- Webhook events are processed reliably
- Admin can view active subscriptions
```

**Why it's good**:
- Multiple sections for clarity
- Specific pricing and plans
- Technical constraints listed
- Clear success criteria

### Example 3: Migration Task
```
Migrate user table from SQLite to PostgreSQL.

Migration Strategy:
1. Add PostgreSQL connection alongside SQLite
2. Dual-write to both databases (sync mode)
3. Backfill historical data from SQLite to PostgreSQL
4. Verify data consistency
5. Switch reads to PostgreSQL
6. Remove SQLite dependencies

Constraints:
- Zero downtime required
- Data loss not acceptable (verify with checksums)
- Rollback plan: switch reads back to SQLite if issues

Success Criteria:
- All user data in PostgreSQL matches SQLite
- Application reads from PostgreSQL successfully
- Performance equivalent or better than SQLite
- SQLite can be safely removed
```

**Why it's good**:
- Step-by-step migration strategy
- Risk mitigation (zero downtime, no data loss)
- Rollback plan included
- Verification steps specified

## Validation

### What Makes a Good CALF File?

A good CALF file:
- ✓ Has a clear goal (single-sentence summary)
- ✓ Defines success criteria (how to verify it works)
- ✓ Lists constraints (what must be preserved/respected)
- ✓ Excludes out-of-scope items (what NOT to do)
- ✓ Provides context (when needed for understanding)

### Linting Rules

While CALF is free-form, these guidelines help:

1. **Length**: 50-500 words (too short lacks detail, too long is unfocused)
2. **Clarity**: Should be understandable by someone unfamiliar with the project
3. **Actionability**: Contains verbs (add, implement, refactor, migrate)
4. **Specificity**: Includes technical details (not just vague goals)
5. **Testability**: Includes verification steps or success criteria

### Validation Command (Future)

```bash
# Check CALF file quality
cleave lint directive.calf

# Output
✓ Goal is clear
✓ Success criteria defined
✓ Constraints specified
⚠ Consider adding out-of-scope section
⚠ Missing verification steps

Score: 8/10
```

## Common Mistakes

### 1. Too Vague

**Bad**:
```
Improve the API
```

**Why**: No specific goal, no success criteria, no constraints.

**Fix**:
```
Reduce /users endpoint latency from 500ms to <100ms. Add Redis
caching for frequently accessed users. Add database indexes on
email and username columns. Verify with load test (1000 req/s).
```

### 2. Scope Creep

**Bad**:
```
Add authentication with JWT, OAuth, SAML, and LDAP support.
Include multi-factor authentication, passwordless login, social
login, and biometric authentication. Build admin panel for user
management, audit logging, and security analytics.
```

**Why**: Too many features, should be split into multiple directives.

**Fix**: Split into focused directives:
- `auth-jwt.calf` - JWT authentication
- `auth-oauth.calf` - OAuth integration
- `auth-mfa.calf` - Multi-factor authentication
- `admin-users.calf` - Admin panel

### 3. Missing Context

**Bad**:
```
Fix the bug
```

**Why**: No information about what bug, where, or expected behavior.

**Fix**:
```
Fix JWT validation bug in auth middleware (src/middleware/auth.py:45).
Currently accepts expired access tokens if refresh token is valid.
Should reject expired access tokens and return 401 Unauthorized.
```

### 4. No Success Criteria

**Bad**:
```
Add caching to improve performance
```

**Why**: No way to verify improvement or know when done.

**Fix**:
```
Add Redis caching for /users endpoint. Cache user objects for 5min.
Verify response time improves from 500ms to <100ms with load test
(1000 req/s). Include cache invalidation on user updates.
```

### 5. Ambiguous Requirements

**Bad**:
```
Add authentication system
```

**Why**: Many interpretations (JWT? Sessions? OAuth? Magic links?).

**Fix**:
```
Add JWT authentication with HS256. Access tokens expire in 15min,
refresh tokens in 7 days. Store refresh tokens in database for
revocation. Add /auth/token and /auth/refresh endpoints.
```

## Working with CALF Files

### Creating CALF Files

```bash
# Create new CALF file
touch feature-name.calf

# Edit with your preferred editor
vim feature-name.calf
code feature-name.calf
```

### Loading into Cleave

**Option 1: Claude Code skill**
```bash
/cleave
$(cat feature-name.calf)
```

**Option 2: TUI**
```bash
cleave tui
# Then in TUI:
/load feature-name.calf
```

**Option 3: CLI**
```bash
cleave assess --directive "$(cat feature-name.calf)"
```

### Version Control

Commit CALF files to git:
```bash
git add feature-name.calf
git commit -m "feat: add directive for feature X"
```

### Organizing CALF Files

```
project/
├── directives/
│   ├── features/
│   │   ├── auth-migration.calf
│   │   ├── api-refactor.calf
│   │   └── payment-integration.calf
│   ├── bugs/
│   │   ├── fix-jwt-validation.calf
│   │   └── fix-cache-invalidation.calf
│   └── migrations/
│       ├── sqlite-to-postgres.calf
│       └── redis-to-valkey.calf
└── .cleave/  # Generated workspaces
```

## CALF vs Other Formats

### CALF vs User Stories

**User Story**:
```
As a user
I want to upload a profile picture
So that I can personalize my account
```

**CALF**:
```
Add profile picture upload to user settings page. Allow JPG/PNG up
to 5MB. Resize to 200x200px. Store in uploads/ directory. Display
on profile page and navigation bar.
```

CALF is more technical and implementation-focused.

### CALF vs GitHub Issue

**GitHub Issue**:
```
Title: Add profile picture upload
Labels: feature, enhancement

Description:
Users should be able to upload profile pictures.

Acceptance Criteria:
- [ ] Upload form on settings page
- [ ] Image validation
- [ ] Display on profile
```

**CALF**:
```
Add profile picture upload to user settings page. Support JPG/PNG
up to 5MB. Resize to 200x200px on upload. Store in uploads/ with
filename pattern: {user_id}-avatar.{ext}. Display on profile page
and navigation bar. Return 400 if invalid format or size exceeded.
```

CALF includes more implementation details.

### CALF vs PRD

**PRD** (Product Requirements Document):
- Multi-page document
- Stakeholder alignment
- Business justification
- Long-term roadmap

**CALF**:
- Single-page directive
- Technical implementation
- Immediate execution
- Specific deliverable

Use PRDs for planning, CALF for execution.

## Future Extensions

Planned enhancements to CALF format:

### 1. YAML Frontmatter (Optional)
```yaml
---
priority: high
assignee: backend-team
estimated_complexity: 6.0
pattern: authentication
---

Add JWT authentication with refresh tokens...
```

### 2. Inline References
```
Add JWT authentication (see: docs/auth-spec.md, examples/jwt-example.py)
with refresh token flow (ref: RFC 6749 section 1.5).
```

### 3. Dependency Links
```
depends_on: [auth-migration.calf, database-schema.calf]

Add authorization layer using JWT claims from auth-migration...
```

### 4. Validation Annotations
```
verify_with: pytest tests/test_auth.py
benchmark_with: locust load-test.py --target-rps 1000
```

These are under consideration for future versions.

## Summary

CALF files are:
- Plain text directives for software development tasks
- Free-form, natural language (interpreted by LLM)
- Focused on clarity, specificity, and actionability
- Version-controlled alongside source code
- The input format for Cleave task decomposition

For working examples, see [examples/](../examples/).
