@cristochang/spec-core

Spec data structures and validation library for OpenCode.

Installation

npm install @cristochang/spec-core

Overview

This package provides the core data structures and validation logic for OpenCode's Spec workflow. It includes:

• Spec Schema - Zod schemas for Spec data structures
• Validator - Business-level validation logic
• Spec API - Utility functions for creating and manipulating specs

Usage

Creating a Spec

import { Spec } from '@cristochang/spec-core'

const spec = Spec.create({
  objective: "Add user authentication feature",
  scope: {
    inclusions: ["login page", "auth service"],
    exclusions: ["social login"]
  },
  successCriteria: ["Users can log in with email/password", "Session management works"]
})

console.log(spec.id)        // ULID
console.log(spec.status)     // "pending"
console.log(spec.created)    // ISO 8601 timestamp

Validating a Spec

import { Spec } from '@cristochang/spec-core'

const result = Spec.validate(spec)

if (!result.valid) {
  console.log("Missing fields:", result.missing)
  console.log("Errors:", result.errors)
}

Status Transitions

import { Spec } from '@cristochang/spec-core'

// Pending -> Approved
const approved = Spec.approve(spec)

// Approved -> Implemented
const implemented = Spec.markImplemented(approved, "All tests passing")

// Any status -> Cancelled
const cancelled = Spec.cancel(spec)

Checking Execution Readiness

import { Spec } from '@cristochang/spec-core'

if (Spec.canExecute(spec)) {
  console.log("Spec is ready for execution")
}

Data Structure

interface SpecInfo {
  // Meta (required)
  id: string                      // ULID
  created: string                 // ISO 8601 datetime
  status: "pending" | "approved" | "implemented" | "cancelled"

  // Core (required)
  objective: string               // Clear one-sentence objective
  scope: {
    inclusions: string[]          // Items in scope
    exclusions: string[]          // Items out of scope
  }
  successCriteria: string[]       // Verifiable success criteria

  // Optional
  constraints?: string[]          // Technical/architectural constraints
  implementationNotes?: string    // Non-binding guidance

  // Auto-filled
  changes?: string[]              // Files modified
  verification?: string           // Verification result
}

License

MIT