The Problem: AI Coding Without a Plan

Imagine hiring a builder who starts pouring concrete before looking at the blueprints. That's what happens when AI coding tools write code without a structured plan first.

SpecSafe solves this by enforcing a two-phase workflow: plan thoroughly first, then build with discipline.

Two Phases, One Principle: Think Before You Build

Like an architect who draws blueprints before any bricks are laid, SpecSafe splits every feature into a planning phase and a building phase.

Under the Hood: A CLI Tool

SpecSafe is a CLI tool you install from npm. It scaffolds your project, installs workflow “skills” for your AI tool, and keeps everything on track.

Your First Look at the Code

Here's the entry point — the very first file that runs when you type specsafe in your terminal.

const program = new Command();

program
  .name('specsafe')
  .description('SpecSafe — Skills-first TDD framework')
  .version(pkg.version);

Check Your Understanding

Six Characters, One Story

Think of SpecSafe like a film crew. Each person has one job, and they coordinate to produce the final product. Here are the main characters.

Where They Live

Here's how the project is organized on disk. Each actor lives in a specific file.

How the Router Dispatches Commands

When you type specsafe install cursor, the Router figures out you want the install command and sends “cursor” to the Installer. Here's exactly how.

program
  .command('install')
  .description('Install SpecSafe skills for a specific AI tool')
  .argument('<tool>', 'Tool name (claude-code, cursor, ...)')
  .action(async (tool: string) => {
    const { install } = await import('./install.js');
    await install(tool);
  });

Check Your Understanding

One Master Copy, Many Translations

Imagine a bestselling novel. The author writes one original manuscript. Then professional translators convert it into Spanish, Japanese, French, and more. The story is always the same — only the language changes.

SpecSafe works the same way. The canonical/ folder is the original manuscript. Adapters are the translators.

Anatomy of a Skill

Each skill is a Markdown file with a metadata header (called frontmatter) at the top. The metadata describes the skill; the body contains the instructions.

---
name: specsafe-new
description: 'Create a new spec with unique ID'
disable-model-invocation: true
---

# Create New Spec
When the user runs /specsafe-new...
1. Generate a unique SPEC ID
2. Copy the spec template
3. Open it for editing

The Install Flow: Step by Step

Here's exactly what happens when you run specsafe install claude-code. Click "Next Step" to follow the data.

How Skills Get Parsed

The Skill Loader reads each SKILL.md file and splits it into metadata and body. Here's the parser.

export function parseFrontmatter(content: string) {
  const normalized = content.replace(/\r\n/g, '\n');
  const match = normalized.match(
    /^---\n([\s\S]*?)\n---\n([\s\S]*)$/
  );
  if (!match) return { frontmatter: {}, body: content };
  // ... parse key: value pairs from match[1]
  return { frontmatter, body: match[2] };
}

Check Your Understanding

One Plug, Every Country

You know those universal power adapters for international travel? Your laptop charger is the same everywhere — but you need a different plug shape for each country. The electricity (the knowledge) doesn't change. Only the connector does.

That's exactly how SpecSafe's adapter pattern works. One interface, eight implementations.

export interface ToolAdapter {
  name: string;
  displayName: string;
  detect(projectRoot: string): Promise<boolean>;
  generate(
    skills: CanonicalSkill[],
    canonicalDir: string,
    projectRoot?: string,
  ): Promise<GeneratedFile[]>;
}

Watch the Adapters Coordinate

Here's how the Installer and Adapters talk to each other when you run specsafe install claude-code.

Inside the Claude Code Adapter

Here's the complete Claude Code adapter — it's one of the simplest. It takes canonical skills and outputs .claude/skills/ files.

async generate(skills: CanonicalSkill[], canonicalDir: string) {
  const files: GeneratedFile[] = [];

  for (const skill of skills) {
    files.push({
      path: `.claude/skills/${skill.directory}/SKILL.md`,
      content: reconstructSkillMd(skill),
    });
  }

  return files;
}

Eight Adapters, Eight Formats

Each adapter speaks its tool's language. Here's what they each produce.

Check Your Understanding

The Bouncer: Path Security

Imagine a nightclub bouncer who checks IDs at the door. No valid ID, no entry. SpecSafe's Installer has a similar guard — before writing any file, it checks that the file path doesn't escape your project folder.

This prevents a malicious or buggy skill from writing files to /etc/ or your home directory. It's called path traversal protection.

const resolvedCwd = resolve(cwd);
for (const file of files) {
  const fullPath = resolve(cwd, file.path);
  if (!fullPath.startsWith(`${resolvedCwd}/`)) {
    console.error(
      `Security error: path escapes project`
    );
    continue;
  }
  // Safe to write the file
}

The Pre-Flight Checklist: Doctor

Pilots run a checklist before every takeoff — engines, fuel, instruments. The specsafe doctor command does the same for your project. It checks everything and gives you a clear status report.

Smart Detection: Finding Your Tools

During specsafe init, the Initializer scans your project for known AI tools. It looks for specific marker files — like checking for a doorbell to know if someone lives there.

const TOOL_DETECT_MAP: Record<string, string> = {
  'claude-code': '.claude/',
  'cursor':      '.cursor/',
  'opencode':    '.opencode/',
  'gemini':      '.gemini/',
  'zed':         '.zed/',
  'aider':       '.aider.conf.yml',
};

Check Your Understanding

The Full Map

You've met every character. Now let's zoom out and see how they all connect. Click any component to learn more.

Why It's Built This Way

Every architectural decision in SpecSafe exists to solve a real problem. Here are the core design principles.

What You Can Do Now

After this course, you have the vocabulary and mental model to:

Final Challenge