Internal Spec Platform

Problem Statement

Organizations managing multiple products face fragmented specification access:

Scattered specs - Specifications live in different repositories, wikis, and documents
No versioning - "What was the spec when we deployed last month?" is unanswerable
No cross-product visibility - Teams cannot discover related specs in other products
AI context inefficiency - Agents re-fetch and re-parse specs every session
No single entry point - Developers must know where each spec lives

Proposed Solution

Build an internal specification platform accessible via:

https://spec.{company.domain}/{date}/{product-id}/{spec-type}/specs/{spec-id}

URL Structure

Segment	Purpose	Examples
`spec.{company.domain}`	Dedicated subdomain	Separation of concerns
`{date}`	Point-in-time snapshot	`2024-12-04`, `latest`, `head`
`{product-id}`	Product boundary	`product-a`, `product-b`, `billing`
`{spec-type}`	OpenSpec spec type directory	`func`, `ux`, `api`, `infra`
`specs`	Fixed path segment	OpenSpec convention
`{spec-id}`	Capability identifier	`user-auth`, `order-create`

Supported Spec Types

Type	Path	Description
func	`/{product}/func/specs/{id}`	Functional/capability specifications
ux	`/{product}/ux/specs/{id}`	UX/UI specifications and wireframes
api	`/{product}/api/specs/{id}`	API contracts (OpenAPI, AsyncAPI)
infra	`/{product}/infra/specs/{id}`	Infrastructure specifications
changes	`/{product}/changes/{id}`	Active change proposals
archive	`/{product}/archive/{id}`	Completed/deployed changes

Example URLs

/latest/product-a/func/specs/user-auth     # Functional spec
/latest/product-a/ux/specs/user-auth       # UX spec
/latest/product-a/api/specs/user-auth      # API spec
/latest/product-a/changes/add-2fa          # Change proposal

Date-Based Versioning

Date versioning fits specification management better than semantic versioning:

Aspect	Semver (`v1.2.3`)	Date (`2024-12-04`)
Meaning	Breaking/feature/patch	Point-in-time snapshot
Decision	Subjective ("is this breaking?")	Objective (today's date)
Audit trail	"Which version was live in Q3?"	"Show me 2024-09-15"
Multi-product sync	Version alignment is painful	Same date = same snapshot

Version Aliases

/latest/...        → Current deployed state (alias to last deploy date)
/2024-12-04/...    → Immutable snapshot for that date
/head/...          → Bleeding edge (main branch, may include undeployed)

Capability Naming Convention

OpenSpec uses flat structure with prefix-based domain grouping:

specs/
├── user-auth/
├── user-profile/
├── user-preferences/
├── order-create/
├── order-fulfill/
├── order-cancel/
├── payment-capture/
├── payment-refund/
└── notification-email/

This is an OpenSpec convention, not a platform design choice. The platform respects and surfaces OpenSpec's existing structure.

Architecture

Git-Based Resolution

No storage duplication. Git is the source of truth:

/2024-12-04/...  → git show $(git rev-list -1 --before="2024-12-04" main):products/...
/latest/...      → main branch HEAD (or last deploy tag)
/head/...        → main branch HEAD

Directory Structure

spec-platform/
├── products/
│   ├── product-a/
│   │   ├── func/                       # Functional specs
│   │   │   └── specs/
│   │   │       ├── user-auth/
│   │   │       │   ├── spec.md
│   │   │       │   └── design.md
│   │   │       └── order-create/
│   │   │           └── spec.md
│   │   ├── ux/                         # UX specifications
│   │   │   └── specs/
│   │   │       ├── user-auth/
│   │   │       │   ├── spec.md
│   │   │       │   └── assets/
│   │   │       └── order-create/
│   │   │           └── spec.md
│   │   ├── api/                        # API contracts
│   │   │   └── specs/
│   │   │       ├── user-auth/
│   │   │       │   └── openapi.yaml
│   │   │       └── order-create/
│   │   │           └── openapi.yaml
│   │   └── changes/
│   │       └── add-2fa/
│   │           ├── proposal.md
│   │           ├── func/
│   │           │   └── specs/
│   │           │       └── user-auth/
│   │           │           └── spec.md
│   │           └── ux/
│   │               └── specs/
│   │                   └── user-auth/
│   │                       └── spec.md
│   └── billing/
│       └── func/
│           └── specs/
│               └── payment-capture/
│                   └── spec.md
├── shared/
│   ├── domains/
│   │   └── glossary.md
│   └── principles/
│       └── api-design.md
└── .vitepress/
    └── config.mjs

Spec Type Relationships

Specs reference related specs using absolute URIs with domain (specs may be spread across different repositories):

yaml

---
id: user-auth
spec-type: func
related:
  ux: https://spec.{company.domain}/product-a/ux/specs/user-auth
  api: https://spec.{company.domain}/product-a/api/specs/user-auth
  # Cross-product reference
  billing: https://spec.{company.domain}/billing/func/specs/payment-capture
---

Absolute URIs with domain ensure references work regardless of where specs are physically stored.

API Endpoints

# Core spec access (follows OpenSpec structure)
GET /{date}/{product}/func/specs/{spec-id}      # Functional spec
GET /{date}/{product}/ux/specs/{spec-id}        # UX spec
GET /{date}/{product}/api/specs/{spec-id}       # API spec
GET /{date}/{product}/{spec-type}/specs         # List all specs of type

# Change proposals
GET /{date}/{product}/changes                   # Active proposals
GET /{date}/{product}/changes/{change-id}       # Specific proposal
GET /{date}/{product}/changes/{change-id}/preview  # Merged preview

# Cross-type queries
GET /{date}/{product}/func/specs/{id}/related   # Related ux, api specs
GET /{date}/search?q=authentication             # Full-text search across all types
GET /{date}/search?q=login&type=ux              # Search specific spec type
GET /{date}/graph                               # Dependency visualization
GET /products                                   # List all products

Snapshot Strategy

Trigger	Creates Snapshot
Daily cron	Auto-snapshot if changes exist since last snapshot
Deployment	Tag with deploy date
Manual	`spec-platform snapshot 2024-12-04`

Cross-Product References

Use absolute URIs with domain for all references (specs may be spread across repositories):

markdown

# In product-a/func/specs/order-payment/spec.md

## Dependencies
- [payment-capture](https://spec.{company.domain}/billing/func/specs/payment-capture)
- [user-auth](https://spec.{company.domain}/product-a/func/specs/user-auth)
- [order-flow](https://spec.{company.domain}/product-a/ux/specs/order-create)

The platform resolves these URIs against the requested date:

Request to /latest/product-a/func/specs/order-payment
Reference https://spec.{company.domain}/billing/func/specs/payment-capture resolves to /latest/billing/func/specs/payment-capture

Requirement Pool Integration

Specs trace back to their source requirements in the Global Requirement Store:

yaml

---
id: user-auth
spec-type: func
# Link to source requirements
requirements:
  - https://req.{company.domain}/product-a/REQ-001  # Login feature
  - https://req.{company.domain}/product-a/REQ-002  # Session management
  - https://req.{company.domain}/shared/SEC-012    # Security baseline
---

Traceability Chain

Requirement Pool          Spec Platform              Implementation
─────────────────────────────────────────────────────────────────────
REQ-001 (Login)     →     func/specs/user-auth   →   src/auth/login.ts
                    →     ux/specs/user-auth     →   src/components/LoginForm.tsx
                    →     api/specs/user-auth    →   openapi.yaml

API Endpoints for Traceability

# From spec to requirements
GET /{date}/{product}/{type}/specs/{id}/requirements

# From requirement to specs (reverse lookup)
GET /{date}/specs?requirement=REQ-001

# Coverage report: which requirements have specs?
GET /{date}/{product}/coverage

Requirement Reference Schema

Field	Description	Example
`requirements`	Source requirements this spec implements	`https://req.{company.domain}/product-a/REQ-001`
`partial`	Requirements partially addressed	For specs covering subset of requirement
`derived_from`	Parent requirement if decomposed	Hierarchical requirement tracing

Implementation Roadmap

Phase 1: Static Site (Month 1-2)

Goal: Basic spec hosting with date versioning

[ ] VitePress/Docusaurus setup with product routing
[ ] Git-based date resolution for /latest and /head
[ ] Auto-deploy on merge to main
[ ] Basic search functionality

Deliverables:

spec.{company.domain}/latest/{product}/specs/{spec-id} working
CI/CD pipeline for spec updates

Phase 2: Snapshots (Month 2-3)

Goal: Immutable date-based access

[ ] Daily snapshot automation
[ ] Deployment tagging integration
[ ] Historical navigation UI
[ ] Diff between dates

Deliverables:

/{date}/... endpoints working
"Compare versions" UI feature

Phase 3: API Layer (Month 3-4)

Goal: Programmatic access for AI agents

[ ] REST API for spec queries
[ ] MCP resource provider
[ ] Webhook integration for change notifications
[ ] JSON/YAML export formats

Deliverables:

GET /api/v1/{product}/specs endpoint
MCP server for Claude Code integration

Phase 4: Platform Features (Month 4-6)

Goal: Full platform capabilities

[ ] Change proposal workflow UI
[ ] Cross-product dependency tracking
[ ] Semantic search with embeddings
[ ] Compliance/coverage dashboards
[ ] Spec diffing between versions

Deliverables:

Web UI for proposal management
Analytics dashboard

CLAUDE.md Integration

markdown

## Specification Platform

Access specifications at: https://spec.{company.domain}

### Quick Reference
- Latest specs: `/latest/{product}/specs/{spec-id}`
- Historical: `/{date}/{product}/specs/{spec-id}`
- Search: `/latest/search?q=query`

### Before Implementation
1. Check existing specs: `/latest/{product}/specs`
2. Review active changes: `/latest/{product}/changes`
3. Verify no conflicts with other products

### Cross-Product Dependencies
When implementing features that span products, check:
- `/latest/billing/specs/payment-*` for payment integration
- `/latest/product-a/specs/user-*` for user identity

### MCP Access
Use the spec-platform MCP server for programmatic access:
- `spec://product-a/user-auth` - Read spec content
- `spec://search?q=authentication` - Search across products

Success Metrics

Metric	Target	How to Measure
Spec discoverability	<30s to find any spec	User testing
Historical access	100% date queries successful	API monitoring
Cross-product visibility	All dependencies documented	Link validation
AI context efficiency	50% reduction in re-fetching	Agent session analysis
Audit compliance	Any date queryable within 5 years	Retention policy

Anti-Patterns to Avoid

Spec Duplication

Wrong: Copy specs between products Right: Reference shared specs via URI

Over-Nesting

Wrong: Deep hierarchies like /product/domain/subdomain/feature/specRight: Flat with naming convention: domain-feature

Version Sprawl

Wrong: Create snapshot for every commit Right: Meaningful snapshots (daily, deploy, manual milestone)

Platform Complexity

Wrong: Build full CMS before proving value Right: Start with static site, add features incrementally

G1: Single Source of Truth - Centralized specification hosting
G2: Version-Controlled Documentation - Date-based versioning for specs
G4: Unified Product Management - Multi-product spec visibility

Multi-Product Spec Management - Hierarchical spec framework this platform implements
Frontmatter Spec Coordination - Metadata schema for spec documents
Agent-Friendly Knowledge Base - Broader knowledge system this integrates with
Global Requirement Store - Requirements layer that feeds into specs

Workflow Framework

Guiding Principles

Governance

Culture

Execution

Internal Spec Platform

Problem Statement

Proposed Solution

URL Structure

Supported Spec Types

Example URLs

Date-Based Versioning

Version Aliases

Capability Naming Convention

Architecture

Git-Based Resolution

Directory Structure

Spec Type Relationships

API Endpoints

Snapshot Strategy

Cross-Product References

Requirement Pool Integration

Traceability Chain

API Endpoints for Traceability

Requirement Reference Schema

Implementation Roadmap

Phase 1: Static Site (Month 1-2)

Phase 2: Snapshots (Month 2-3)

Phase 3: API Layer (Month 3-4)

Phase 4: Platform Features (Month 4-6)

CLAUDE.md Integration

Success Metrics

Anti-Patterns to Avoid

Spec Duplication

Over-Nesting

Version Sprawl

Platform Complexity

Internal Spec Platform ​

Problem Statement ​

Proposed Solution ​

URL Structure ​

Supported Spec Types ​

Example URLs ​

Date-Based Versioning ​

Version Aliases ​

Capability Naming Convention ​

Architecture ​

Git-Based Resolution ​

Directory Structure ​

Spec Type Relationships ​

API Endpoints ​

Snapshot Strategy ​

Cross-Product References ​

Requirement Pool Integration ​

Traceability Chain ​

API Endpoints for Traceability ​

Requirement Reference Schema ​

Implementation Roadmap ​

Phase 1: Static Site (Month 1-2) ​

Phase 2: Snapshots (Month 2-3) ​

Phase 3: API Layer (Month 3-4) ​

Phase 4: Platform Features (Month 4-6) ​

CLAUDE.md Integration ​

Success Metrics ​

Anti-Patterns to Avoid ​

Spec Duplication ​

Over-Nesting ​

Version Sprawl ​

Platform Complexity ​

Related Principles ​

Related Proposals ​

Internal Spec Platform

Problem Statement

Proposed Solution

URL Structure

Supported Spec Types

Example URLs

Date-Based Versioning

Version Aliases

Capability Naming Convention

Architecture

Git-Based Resolution

Directory Structure

Spec Type Relationships

API Endpoints

Snapshot Strategy

Cross-Product References

Requirement Pool Integration

Traceability Chain

API Endpoints for Traceability

Requirement Reference Schema

Implementation Roadmap

Phase 1: Static Site (Month 1-2)

Phase 2: Snapshots (Month 2-3)

Phase 3: API Layer (Month 3-4)

Phase 4: Platform Features (Month 4-6)

CLAUDE.md Integration

Success Metrics

Anti-Patterns to Avoid

Spec Duplication

Over-Nesting

Version Sprawl

Platform Complexity

Related Principles

Related Proposals