File Formats
Three lossless representations of the same schema. Choose the format that fits your workflow.
.sf.json
Machine-first
100%
Baseline tokens
.sf.yaml
Human-first
~85%
vs JSON tokens
.sf.toon
LLM-optimized
60.1%
vs JSON tokens
example.sf.jsonProgrammatic generation · CI · Storage
{
"specforgeVersion": "1.0",
"project": {
"id": "a1b2c3d4-0000-0000-0000-000000000001",
"name": "SaaS Platform",
"description": "Full-stack SaaS with Stripe billing"
},
"specifications": [
{
"id": "b2c3d4e5-0000-0000-0000-000000000002",
"title": "Stripe Webhook Handler",
"status": "ready",
"goals": [
"Process all Stripe webhook events",
"Idempotent event handling"
],
"epics": [
{
"id": "c3d4e5f6-0000-0000-0000-000000000003",
"epicNumber": 1,
"title": "Core Webhook Infrastructure",
"status": "todo",
"tickets": [
{
"id": "d4e5f6a7-0000-0000-0000-000000000004",
"ticketNumber": 1,
"title": "Webhook signature verification",
"status": "ready",
"complexity": "small",
"priority": "critical",
"implementation": {
"steps": [
"Create verifySignature middleware",
"Add Stripe webhook secret to env"
],
"filesToCreate": [
"src/webhooks/verify.ts"
]
}
}
]
}
]
}
]
}
When to use each format
.sf.json
Programmatic generation, CI pipelines, database storage, API responses..sf.yaml
Hand-authored specs, version control with readable diffs, config files..sf.toon
Injecting specs into LLM agent context windows. 39.9% fewer tokens.