@specsafe/core

Core workflow engine, types, and utilities for the SpecSafe spec-driven development framework.

Installation

npm install @specsafe/core

What It Provides

• Workflow Engine - Manage spec lifecycle from creation to archive
• ProjectTracker - Track project state and spec metadata
• TypeScript Types - Full type definitions for specs, requirements, and reports
• Validation Utilities - Schema validation and ID validation

API Reference

Workflow Class

The main class for managing spec workflows.

import { Workflow } from '@specsafe/core';

const workflow = new Workflow({
  specsDir: './specs',
  projectName: 'My Project'
});

createSpec(specId: string, content: string): Promise<Spec>

Create a new specification.

const spec = await workflow.createSpec('user-auth', `# User Authentication

## Requirements

### REQ-001: Login
**Given** a registered user
**When** they enter valid credentials
**Then** they should be logged in
`);

moveToTest(specId: string): Promise<Spec>

Move a spec to the "test" phase.

const spec = await workflow.moveToTest('user-auth');

moveToCode(specId: string): Promise<Spec>

Move a spec to the "code" phase.

const spec = await workflow.moveToCode('user-auth');

moveToQA(specId: string, report?: QAReport): Promise<Spec>

Transition a spec into QA review or mark QA as complete. Optionally accepts a QAReport to record results.

const spec = await workflow.moveToQA('user-auth', {
  passed: true,
  notes: 'All tests passing'
});

complete(specId: string): Promise<Spec>

Mark a spec as complete.

const spec = await workflow.complete('user-auth');

archive(specId: string): Promise<Spec>

Archive a completed spec.

const spec = await workflow.archive('user-auth');

getSpec(specId: string): Promise<Spec | null>

Get a spec by ID.

const spec = await workflow.getSpec('user-auth');

listSpecs(phase?: Phase): Promise<Spec[]>

List all specs or filter by phase.

// All specs
const allSpecs = await workflow.listSpecs();

// Only active specs
const activeSpecs = await workflow.listSpecs('active');

ProjectTracker Class

Track project-level state and metadata.

import { ProjectTracker } from '@specsafe/core';

const tracker = new ProjectTracker('./specs');

getProjectState(): Promise<ProjectState>

Get the current project state.

const state = await tracker.getProjectState();
console.log(state.activeSpecs.length);
console.log(state.completedSpecs.length);

updateSpecStatus(specId: string, status: SpecStatus): Promise<void>

Update the status of a spec.

await tracker.updateSpecStatus('user-auth', 'in-progress');

Validation Utilities

validateSpecId(specId: string): boolean

Validate a spec ID format.

import { validateSpecId } from '@specsafe/core';

validateSpecId('user-auth');     // true
validateSpecId('user_auth');     // false (underscores not allowed)
validateSpecId('user-auth-123'); // true

TypeScript Types

Spec

interface Spec {
  id: string;
  title: string;
  description: string;
  phase: Phase;
  status: SpecStatus;
  requirements: Requirement[];
  acceptanceCriteria: string[];
  technicalNotes?: string;
  createdAt: Date;
  updatedAt: Date;
  completedAt?: Date;
  qaReport?: QAReport;
}

Requirement

interface Requirement {
  id: string;
  title: string;
  given: string;
  when: string;
  then: string;
}

QAReport

interface QAReport {
  passed: boolean;
  notes?: string;
  testedAt: Date;
  testedBy?: string;
}

Phase

type Phase = 'draft' | 'active' | 'test' | 'code' | 'qa' | 'completed' | 'archived';

SpecStatus

type SpecStatus = 'pending' | 'in-progress' | 'blocked' | 'completed';

Usage Examples

Basic Workflow

import { Workflow } from '@specsafe/core';

async function main() {
  const workflow = new Workflow({
    specsDir: './specs',
    projectName: 'My App'
  });

  // Create a spec
  await workflow.createSpec('email-validation', `
# Email Validation

## Requirements

### REQ-001: Valid Email Format
**Given** an email input field
**When** the user enters "[email protected]"
**Then** the email should be marked as valid

### REQ-002: Invalid Email Format
**Given** an email input field
**When** the user enters "invalid-email"
**Then** an error message should be shown
`);

  // Move through phases
  await workflow.moveToTest('email-validation');
  await workflow.moveToCode('email-validation');
  await workflow.moveToQA('email-validation', { passed: true });
  await workflow.complete('email-validation');
}

main();

Project Statistics

import { ProjectTracker } from '@specsafe/core';

async function printStats() {
  const tracker = new ProjectTracker('./specs');
  const state = await tracker.getProjectState();

  console.log(`Active specs: ${state.activeSpecs.length}`);
  console.log(`Completed: ${state.completedSpecs.length}`);
  console.log(`Archived: ${state.archivedSpecs.length}`);
}

License

MIT © Agentic Engineering