claudemesh/docs/tcs/TCS-QUICKSTART.md

TCS Quick Start

Build a compiler in hours, not weeks.

Prerequisites

• Node.js 18+
• pnpm
• Anthropic API key

1. Define Your Triangle (5 min)

Pick 3 representations of the same semantic content:

Example: Form Builder
├── Visual: Form UI mockup/description
├── Structured: JSON Schema
└── Compact: FormDSL

2. Write Initial Spec (15 min)

# FormDSL Spec v0.1

## Syntax
form "name"
  ? field_id "Label" type [validation]
  ! message "text"
  -> next_field
end

## Types
Tx = text, Em = email, Ph = phone, Nm = number

## Example
form "contact"
  ? name "Your name" Tx [required]
  ? email "Email" Em [required]
  ! thanks "Thank you!"
end

3. Create Sample Generator (10 min)

// tcs/generate.ts
import Anthropic from '@anthropic-ai/sdk';

const client = new Anthropic();

export async function generateTriangle(prompt: string) {
  const [visual, structured, dsl] = await Promise.all([
    client.messages.create({
      model: 'claude-sonnet-4-20250514',
      max_tokens: 2000,
      messages: [{ role: 'user', content: `Describe this form visually: ${prompt}` }]
    }),
    client.messages.create({
      model: 'claude-sonnet-4-20250514',
      max_tokens: 2000,
      messages: [{ role: 'user', content: `Generate JSON Schema for: ${prompt}` }]
    }),
    client.messages.create({
      model: 'claude-sonnet-4-20250514',
      max_tokens: 2000,
      system: `You write FormDSL. Spec: [paste spec here]`,
      messages: [{ role: 'user', content: prompt }]
    }),
  ]);

  return { visual, structured, dsl };
}

4. Create Triangulator (10 min)

// tcs/triangulate.ts
export async function triangulate(sample: Triangle) {
  const response = await client.messages.create({
    model: 'claude-sonnet-4-20250514',
    max_tokens: 2000,
    messages: [{
      role: 'user',
      content: `Compare these 3 representations. Are they semantically equivalent?

VISUAL:
${sample.visual}

JSON SCHEMA:
${JSON.stringify(sample.structured, null, 2)}

DSL:
${sample.dsl}

Return JSON: { equivalent: boolean, disagreements: string[], specGaps: string[] }`
    }]
  });

  return JSON.parse(response.content[0].text);
}

5. Run TCS Loop (iterate)

// tcs/iterate.ts
async function tcsIteration(spec: string, sampleCount = 10) {
  // Generate samples
  const prompts = await generatePrompts(sampleCount);
  const samples = await Promise.all(prompts.map(generateTriangle));

  // Triangulate
  const results = await Promise.all(samples.map(triangulate));

  // Collect findings
  const findings = results
    .filter(r => !r.equivalent)
    .flatMap(r => r.specGaps);

  // Evolve spec if needed
  if (findings.length > 0) {
    spec = await evolveSpec(spec, findings);
  }

  // Build/update compiler
  await buildCompiler(spec);

  // Test
  const testResults = await runTests(samples.filter((_, i) => results[i].equivalent));

  return { spec, passRate: testResults.passRate, findings };
}

// Main loop
let spec = readFileSync('spec.md', 'utf-8');
while (true) {
  const result = await tcsIteration(spec);
  spec = result.spec;

  if (result.passRate === 1 && result.findings.length === 0) {
    console.log('Converged!');
    break;
  }
}

6. Output

After convergence:

output/
├── spec-final.md      # Evolved specification
├── compiler/
│   ├── scanner.ts     # Tokenizer
│   ├── parser.ts      # AST builder
│   └── emitter.ts     # Code generator
└── tests/
    └── samples.json   # Validated test cases

Tips

1. Start small - 5-10 samples per iteration
2. Parallelize - Generate/triangulate concurrently
3. Trust disagreements - They reveal real spec gaps
4. Checkpoint often - Save state every iteration
5. Let it converge - Don't manually fix, let TCS find issues

Example Run

$ pnpm tcs:run --spec form-dsl.md --target 50

Iteration 1: 10 samples, 3 disagreements, 2 spec changes
Iteration 2: 10 samples, 1 disagreement, 1 spec change
Iteration 3: 10 samples, 0 disagreements, 0 spec changes
Iteration 4: 20 samples, 0 disagreements, 0 spec changes
✓ Converged at 50 samples, 4 iterations

Quality Rules (Non-Negotiable)

1. No bypassing - Errors reveal spec gaps, don't suppress them
2. No patches - Generalize fixes, don't add special cases
3. Production code - Strict TypeScript, no TODOs, no debug code
4. Redesign when stuck - Bad architecture can't be patched

// ❌ WRONG
try { parse(input) } catch { return null }  // Bypassing
if (sample === 'special') { ... }            // Isolated patch
const x: any = ...                            // Not production

// ✅ RIGHT
const result = parse(input)                   // Let it fail, fix root cause
handleAllCases(sample)                        // Generalized solution
const x: ParsedNode = ...                     // Strict types

Next Steps

• Read TCS-AI-METHODOLOGY.md for full theory
• Read TCS-CLAUDE-CODE.md for Claude Code execution
• Check TCS-ROADMAP.md for liquid package applications