Product Specification Verification System

A prototype system for managing product specifications with structured JSON schemas, TypeScript-based verification, and agentic workflow support.

Overview

This system enables:

• Structured product specifications with both prose and machine-readable metadata
• Automated verification using TypeScript modules
• Agent-friendly tooling for reading, writing, and validating specs
• Traceability between requirements, tests, and features

Quick Start

Prerequisites

# Install Node.js (18+ recommended)
# Then install project dependencies
npm install

Note: All tools are written in TypeScript and executed via tsx. No external CLI tools required.

Verify All Features

npm run verify all

Query Features

# Find circular dependencies
npm run query find-circular-deps

# List features by facet
npm run query list-features-by-facet

# Find orphaned features
npm run query find-orphaned-features

Edit a Feature

# Set a value
npm run write set FEAT-CHECKOUT-UX-001 "metadata.status" '"approved"'

# Verify the change
npm run verify FEAT-CHECKOUT-UX-001

Generate Markdown Documentation

# Convert all features to markdown with clickable links
npm run to-markdown

# Output will be in docs/ directory

Directory Structure

verifier/
├── specs/                    # Feature specifications
│   ├── manifest.json        # Feature discovery manifest
│   └── checkout/            # Checkout feature specs
├── schemas/                 # JSON Schema definitions
├── verifiers/              # TypeScript verification modules
│   ├── verify-dependencies.ts
│   ├── verify-constraints.ts
│   ├── verify-requirements.ts
│   └── verify-prose-schema.ts
├── queries/                 # TypeScript query modules
│   ├── find-circular-deps.ts
│   ├── find-orphaned-features.ts
│   └── list-features-by-facet.ts
├── tools/                   # TypeScript command-line tools
│   ├── types.ts            # Shared TypeScript types
│   ├── verify.ts           # Verification script
│   ├── query.ts            # Query execution
│   ├── write.ts            # Structured edits
│   └── to-markdown.ts      # Markdown conversion
├── docs/                   # Generated markdown docs (optional)
├── package.json            # npm scripts and dependencies
├── tsconfig.json           # TypeScript configuration
└── AGENTS.md               # Agent configuration guide

Features

The prototype includes 4 facets of the checkout flow:

1. FEAT-CHECKOUT-UX-001: User Experience Flow
2. FEAT-PAY-001: Payment Processing (Technical)
3. FEAT-FRAUD-001: Fraud Detection (Business Constraints)
4. FEAT-REQ-CHECKOUT-001: Requirements & Tests

Verification

The system includes 4 verification modules (TypeScript):

1. verify-dependencies: Circular deps, orphaned refs, bidirectional consistency
2. verify-constraints: Constraint feasibility and propagation
3. verify-requirements: Requirements-test traceability
4. verify-prose-schema: Prose-schema alignment

Available npm Scripts

• npm run verify - Run verification on features
• npm run query - Execute queries
• npm run write - Make structured edits to feature files
• npm run to-markdown - Generate markdown documentation

Agent Workflow

See AGENTS.md for detailed agent configuration and workflow.

License

Prototype - Internal Use