Global Requirement Store

This proposal establishes a centralized, product-oriented requirement repository that serves as the single source of truth for all product requirements across platforms (Web, iOS, Android, Backend). AI agents access this store to understand feature specifications before implementation, ensuring cross-platform consistency and reducing requirement fragmentation.

Key Insight: Requirements fragmented across platform-specific documents create divergent implementations. A single, AI-accessible requirement store enables agents to generate consistent code across all endpoints from the same source of truth.

Problem Statement

Current State: Fragmented Requirements

Evidence from Team Feedback

Pain Point	Impact
Platform-specific PRDs	Each team maintains own interpretation of requirements
Requirement versioning	No correlation between PRD changes and code changes
Cross-platform inconsistency	Same feature behaves differently across platforms
AI context fragmentation	Agents see only local requirements, miss global picture
Duplicate specifications	Same requirement documented 4+ times with variations

The Fundamental Problem

Each AI agent sees only its platform's interpretation, leading to:

Inconsistent feature implementations
Missing edge cases on some platforms
Conflicting API contracts
Redundant specification effort

Proposed Solution: Global Requirement Store

Target Architecture

Core Principles

Product-Centric Organization: Requirements grouped by product, not platform
Single Source of Truth: One canonical requirement, platform-specific supplements
API-First Contracts: Backend API defined alongside requirements
AI-Native Format: Structured Markdown with machine-readable metadata
Version Correlation: Requirement changes linked to implementation PRs
Cross-Product References: Shared concepts and dependencies across product boundaries

Repository Structure

Directory Layout

requirement-store/
├── CLAUDE.md                       # AI agent instructions
├── README.md                       # Human overview
├── .schema/
│   ├── requirement.schema.json    # Requirement document schema
│   ├── api-contract.schema.json   # API contract schema
│   └── ux-spec.schema.json        # UX specification schema
│
├── products/
│   ├── vsaas/
│   │   ├── _product.md            # Product overview
│   │   ├── features/
│   │   │   ├── device-management/
│   │   │   │   ├── requirement.md      # Core requirement (all platforms)
│   │   │   │   ├── api-contract.md     # Backend API specification
│   │   │   │   ├── ux-spec.md          # UX/UI specification
│   │   │   │   ├── test-cases.md       # Acceptance criteria
│   │   │   │   └── platforms/
│   │   │   │       ├── web.md          # Web-specific notes
│   │   │   │       ├── ios.md          # iOS-specific notes
│   │   │   │       └── android.md      # Android-specific notes
│   │   │   │
│   │   │   ├── video-playback/
│   │   │   │   ├── requirement.md
│   │   │   │   ├── api-contract.md
│   │   │   │   └── ...
│   │   │   │
│   │   │   └── analytics-dashboard/
│   │   │       └── ...
│   │   │
│   │   └── shared/
│   │       ├── device-identity.md     # Cross-feature domain concepts
│   │       ├── authentication.md
│   │       └── error-handling.md
│   │
│   └── vortex/
│       ├── _product.md
│       └── features/
│           └── ...
│
├── shared/                           # Cross-product shared concepts
│   ├── domains/
│   │   ├── user-identity.md         # User/account concepts across products
│   │   ├── organization.md          # Organization/tenant hierarchy
│   │   ├── permissions.md           # RBAC/permission model
│   │   └── notifications.md         # Notification patterns
│   │
│   ├── integrations/
│   │   ├── sso.md                   # SSO integration requirements
│   │   ├── billing.md               # Billing/subscription handling
│   │   └── analytics.md             # Cross-product analytics
│   │
│   └── ux-patterns/
│       ├── navigation.md            # Cross-product navigation
│       ├── branding.md              # Brand consistency requirements
│       └── accessibility.md         # A11y requirements
│
├── contracts/
│   ├── api-standards.md           # API design standards
│   ├── error-codes.md             # Global error code registry
│   └── data-models.md             # Shared data model definitions
│
└── templates/
    ├── requirement.template.md
    ├── api-contract.template.md
    └── platform-notes.template.md

Requirement Document Structure

markdown

id: req-device-management
title: Device Management
product: vsaas
version: 2.3.0
status: approved
priority: high
created: 2025-01-15
updated: 2025-11-28
authors:
  - pm@company.com
reviewers:
  - tech-lead@company.com
  - ux@company.com
platforms:
  - web
  - ios
  - android
api_version: v2
related_features:
  - device-provisioning
  - device-monitoring
cross_product_refs:
  - shared/domains/user-identity        # User context from shared
  - shared/domains/permissions          # Permission model
  - vortex/features/device-sync         # Related feature in another product
depends_on:
  - vsaas/features/authentication       # Same product dependency
  - shared/integrations/sso             # Cross-product dependency
tags:
  - device
  - crud
  - core-feature
# Device Management

## Overview

Brief description of the feature and its business value.

## User Stories

### US-001: View Device List
As a **site administrator**, I want to **view all devices in my site**
so that I can **monitor device status at a glance**.

**Acceptance Criteria:**
- [ ] Display device name, status, and last seen time
- [ ] Support pagination for sites with >100 devices
- [ ] Show online/offline indicator
- [ ] Allow sorting by name, status, or last seen

### US-002: Add New Device
As a **site administrator**, I want to **add a new device to my site**
so that I can **expand my surveillance coverage**.

**Acceptance Criteria:**
- [ ] Validate device credentials before adding
- [ ] Support QR code scanning for device ID
- [ ] Show progress during device discovery
- [ ] Handle duplicate device gracefully

## Functional Requirements

### FR-001: Device List Retrieval
- System SHALL retrieve devices for the authenticated user's accessible sites
- System SHALL return device status within 5 seconds
- System SHALL support filtering by site, status, and device type

### FR-002: Device Registration
- System SHALL validate device connectivity before registration
- System SHALL reject devices already registered to another account
- System SHALL assign unique DeviceKey upon successful registration

## Non-Functional Requirements

### NFR-001: Performance
- Device list SHALL load within 2 seconds for up to 500 devices
- Search results SHALL appear within 500ms

### NFR-002: Availability
- Device management operations SHALL be available 99.9% of the time

## Business Rules

### BR-001: Device Limit
- Free tier: Maximum 5 devices per site
- Pro tier: Maximum 50 devices per site
- Enterprise: Unlimited devices

### BR-002: Device Naming
- Device names MUST be unique within a site
- Device names MUST be 1-64 characters
- Device names MAY contain alphanumeric, spaces, hyphens, underscores

## Out of Scope

- Device firmware updates (see device-firmware feature)
- Device analytics configuration (see analytics-dashboard feature)

## AI Implementation Notes

@ai-hint When implementing device list, use pagination with cursor-based approach.
@ai-hint Device status should use the DeviceStatus enum from shared/device-identity.md.
@ai-hint All device operations require site-level authorization check.
@see api-contract.md for API endpoints
@see platforms/web.md for Web-specific component usage

API Contract Document

markdown

id: api-device-management
feature: device-management
version: 2.3.0
base_path: /api/v2/devices
auth: bearer
# Device Management API Contract

## Endpoints

### GET /api/v2/sites/{siteId}/devices

List all devices in a site.

**Parameters:**
| Name | In | Type | Required | Description |
|------|-----|------|----------|-------------|
| siteId | path | string | yes | Site identifier |
| cursor | query | string | no | Pagination cursor |
| limit | query | integer | no | Items per page (default: 20, max: 100) |
| status | query | string | no | Filter by status: online, offline, error |

**Response 200:**
```json
{
  "devices": [
    {
      "deviceKey": "dk_abc123",
      "name": "Front Entrance Camera",
      "status": "online",
      "lastSeen": "2025-11-28T10:30:00Z",
      "model": "IB9365-EHT",
      "firmware": "2.3.1"
    }
  ],
  "pagination": {
    "nextCursor": "eyJsYXN0SWQiOiJkZXYxMjMifQ==",
    "hasMore": true
  }
}

Error Responses:

Code	Type	Description
401	AUTH_REQUIRED	Missing or invalid bearer token
403	SITE_ACCESS_DENIED	User lacks access to site
404	SITE_NOT_FOUND	Site does not exist

POST /api/v2/sites/{siteId}/devices

Request Body:

json

{
  "deviceId": "00:11:22:33:44:55",
  "name": "Lobby Camera",
  "credentials": {
    "username": "admin",
    "password": "encrypted_password"
  }
}

Response 201:

json

{
  "deviceKey": "dk_new123",
  "name": "Lobby Camera",
  "status": "connecting",
  "registeredAt": "2025-11-28T10:35:00Z"
}

Data Models

Device

typescript

interface Device {
  deviceKey: string;      // Unique identifier (dk_*)
  name: string;           // User-defined name
  status: DeviceStatus;   // online | offline | connecting | error
  lastSeen: string;       // ISO 8601 timestamp
  model: string;          // Device model number
  firmware: string;       // Firmware version
  siteId: string;         // Parent site
}

type DeviceStatus = 'online' | 'offline' | 'connecting' | 'error';

AI Implementation Notes

@ai-hint Use deviceKey (not deviceId/MAC) for all internal references. @ai-hint Implement optimistic UI updates for status changes. @ai-hint Cache device list with 30-second TTL.


### Platform-Specific Notes

```markdown
feature: device-management
platform: web
# Device Management - Web Platform Notes

## Component Usage

Use these design system components:
- `DeviceCard` for individual device display
- `DeviceList` for paginated list with virtual scrolling
- `DeviceStatusBadge` for status indicators

## State Management

```typescript
// Use Pinia store
import { useDeviceStore } from '@/stores/device'

const deviceStore = useDeviceStore()
await deviceStore.fetchDevices(siteId)

Web-Specific Behaviors

Implement keyboard navigation for device list
Support drag-and-drop for device reordering
Show browser notifications for device status changes

Accessibility

Device cards must have aria-label with device name and status
Status changes must be announced to screen readers



## Cross-Platform Consistency

### Shared Domain Concepts

Create shared definitions that all platforms reference:

```markdown
# products/vsaas/shared/device-identity.md

id: domain-device-identity
type: domain-concept
# Device Identity

## Terminology

| Term | Definition | Usage |
|------|------------|-------|
| **DeviceKey** | Unique identifier assigned by system (dk_*) | All internal references, API calls |
| **DeviceId** | Hardware identifier (MAC address) | Device discovery only |
| **DeviceName** | User-defined display name | UI display, user-facing |

## Status States

```mermaid
stateDiagram-v2
    [*] --> Connecting: Register
    Connecting --> Online: Connected
    Connecting --> Error: Failed
    Online --> Offline: Timeout
    Offline --> Online: Reconnect
    Online --> Error: Fatal
    Error --> Connecting: Retry

AI Guidelines

@ai-hint NEVER use MAC address as identifier after registration. @ai-hint DeviceKey is immutable once assigned. @ai-hint Status transitions must follow the state diagram.


### Cross-Product References

When requirements span multiple products, use explicit cross-product references:

```markdown
# shared/domains/user-identity.md

id: domain-user-identity
type: cross-product-domain
scope: global
products:
  - vsaas
  - vortex
  - cloud-portal
# User Identity

## Overview

Defines the unified user identity model shared across all products.
Products MUST reference this document rather than defining their own user model.

## Core Concepts

| Concept | Definition | Products |
|---------|------------|----------|
| **UserId** | Global unique identifier (usr_*) | All products |
| **AccountId** | Organization identifier (acc_*) | All products |
| **TenantId** | Multi-tenant isolation key | VSaaS, Vortex |

## Cross-Product Behaviors

### Single Sign-On
- User authenticated in Product A is automatically authenticated in Product B
- Session tokens are valid across product boundaries
- @see shared/integrations/sso.md

### Unified Permissions
- Permissions follow a hierarchical model across products
- Product-specific roles inherit from global roles
- @see shared/domains/permissions.md

## AI Implementation Notes

@ai-hint User identity is ALWAYS fetched from shared auth service, never product-specific.
@ai-hint When implementing user-related features, first check shared/domains/user-identity.md.
@ai-hint Cross-product features MUST use the shared domain concepts.

Reference Types

Reference Type	Syntax	Use Case
Same Product	`related_features: [device-provisioning]`	Features in same product
Cross Product	`cross_product_refs: [vortex/features/device-sync]`	Features in different products
Shared Domain	`cross_product_refs: [shared/domains/user-identity]`	Global domain concepts
Dependency	`depends_on: [shared/integrations/sso]`	Required before implementation

Dependency Graph

Cross-Product Scenarios

This section details common cross-product scenarios and how the Global Requirement Store addresses them.

Scenario 1: Shared Feature Implementation

When multiple products need the same feature (e.g., device sharing between VSaaS and Vortex):

Directory Structure for Shared Features:

requirement-store/
├── shared/
│   └── features/
│       └── device-sharing/
│           ├── requirement.md       # Shared business logic
│           ├── api-contract.md      # Inter-product API
│           └── integration-spec.md  # How products integrate
│
├── products/
│   ├── vsaas/features/device-management/
│   │   └── requirement.md
│   │       # cross_product_refs: [shared/features/device-sharing]
│   │
│   └── vortex/features/device-sync/
│       └── requirement.md
│           # cross_product_refs: [shared/features/device-sharing]

Scenario 2: Cross-Product Data Flow

When data flows between products (e.g., analytics aggregation):

markdown

# shared/integrations/analytics.md

id: integration-analytics
type: cross-product-integration
scope: global
products:
  - vsaas
  - vortex
  - cloud-portal
data_flow:
  - source: vsaas
    sink: cloud-portal
    events: [device_added, device_removed, stream_started]
  - source: vortex
    sink: cloud-portal
    events: [sync_completed, sync_failed]
# Cross-Product Analytics Integration

## Overview

Defines how analytics events flow between products to the central Cloud Portal dashboard.

## Event Contract

All products MUST emit events following this schema:

```typescript
interface AnalyticsEvent {
  eventId: string;           // Unique event ID (evt_*)
  productId: string;         // Source product: vsaas | vortex | cloud-portal
  eventType: string;         // Event type from product's event catalog
  timestamp: string;         // ISO 8601 UTC
  userId: string;            // User from shared/domains/user-identity
  accountId: string;         // Account from shared/domains/organization
  payload: Record<string, unknown>;  // Event-specific data
}

AI Implementation Notes

@ai-hint When implementing analytics, ALWAYS check this document for event schema. @ai-hint Events MUST include userId and accountId from shared domain concepts. @ai-hint Never create product-specific event schemas without updating this contract.


### Scenario 3: Cross-Product User Journey

When a user journey spans multiple products:

```markdown
# shared/journeys/device-onboarding.md

id: journey-device-onboarding
type: cross-product-journey
scope: global
products:
  - cloud-portal    # Entry point
  - vsaas           # Device registration
  - vortex          # Initial sync
touchpoints:
  - product: cloud-portal
    feature: account-setup
    step: 1
  - product: vsaas
    feature: device-management
    step: 2
  - product: vortex
    feature: device-sync
    step: 3
# Device Onboarding Journey

## Journey Overview

```mermaid
journey
    title Device Onboarding
    section Cloud Portal
      Sign up: 5: User
      Create organization: 4: User
    section VSaaS
      Add first device: 3: User, System
      Configure device: 4: User
    section Vortex
      Initial sync: 5: System
      Verify sync: 4: User

Cross-Product Handoffs

From	To	Handoff Data	Contract
Cloud Portal	VSaaS	userId, accountId, orgId	shared/domains/user-identity
VSaaS	Vortex	deviceKey, userId	vsaas/shared/device-identity
Vortex	Cloud Portal	syncStatus, deviceKeys	shared/integrations/analytics

AI Implementation Notes

@ai-hint Each handoff MUST preserve context defined in the contract column. @ai-hint User should NOT re-authenticate between products (use shared/integrations/sso). @ai-hint Journey abandonment events should be tracked in shared/integrations/analytics.



## Cross-Product Governance

### Ownership Model

```mermaid
graph TD
    subgraph "Governance Structure"
        ARCH[Architecture Guild] --> SHARED[shared/]
        ARCH --> CONTRACTS[contracts/]

        VSAAS_PM[VSaaS PM] --> VP[products/vsaas/]
        VORTEX_PM[Vortex PM] --> VXP[products/vortex/]
        CP_PM[Cloud Portal PM] --> CPP[products/cloud-portal/]

        SHARED --> |reviews| VSAAS_PM
        SHARED --> |reviews| VORTEX_PM
        SHARED --> |reviews| CP_PM
    end

    style ARCH fill:#e8f5e9
    style SHARED fill:#e1f5fe
    style CONTRACTS fill:#e1f5fe

Change Management Rules

Change Type	Owner	Reviewers	Approval
Product feature	Product PM	Tech Lead	Product PM
Cross-product ref addition	Product PM	Architecture Guild	Both
Shared domain change	Architecture Guild	All affected PMs	Architecture Guild + All PMs
Contract change	Architecture Guild	All product teams	Architecture Guild
Integration change	Owning product PM	All consuming PMs	All parties

Conflict Resolution

When products have conflicting requirements:

Detection: CI validates cross_product_refs for conflicts
Escalation: Architecture Guild notified via PR label
Resolution: Joint session with affected PMs
Documentation: Decision recorded in contracts/decisions/

markdown

# contracts/decisions/DEC-001-device-status-naming.md

id: DEC-001
date: 2025-11-15
participants:
  - vsaas-pm@company.com
  - vortex-pm@company.com
  - architect@company.com
status: resolved
# Decision: Device Status Naming Convention

## Conflict

- VSaaS used: `online`, `offline`, `error`
- Vortex used: `connected`, `disconnected`, `failed`

## Resolution

Standardize on VSaaS naming (`online`, `offline`, `error`) across all products.

## Migration

- Vortex to migrate by v3.0 release
- Backward compatibility layer for 2 releases

## AI Implementation Notes

@ai-hint Use `online`, `offline`, `error` for all device status.
@ai-hint Legacy `connected`/`disconnected`/`failed` are deprecated.

Cross-Product Validation

Automated Consistency Checks

typescript

// CI validation script
interface CrossProductValidator {
  // Validate all cross_product_refs resolve to existing documents
  validateReferences(): ValidationResult[];

  // Check shared domain concepts are used consistently
  validateTerminology(): TerminologyReport[];

  // Ensure API contracts don't conflict
  validateApiContracts(): ApiConflict[];

  // Verify journey touchpoints are implemented
  validateJourneys(): JourneyGap[];
}

// Example CI output
const validationResults = {
  references: {
    total: 45,
    valid: 43,
    broken: [
      'vsaas/features/alerts -> shared/domains/notifications (not found)',
      'vortex/features/backup -> shared/integrations/storage (deprecated)'
    ]
  },
  terminology: {
    conflicts: [
      {
        term: 'device status',
        usages: [
          { product: 'vsaas', values: ['online', 'offline'] },
          { product: 'vortex', values: ['connected', 'disconnected'] }
        ],
        recommendation: 'See contracts/decisions/DEC-001'
      }
    ]
  }
};

MCP Validation Tools

typescript

// Extended MCP server with validation tools
const requirementStoreServer = {
  // ... existing tools ...

  tools: {
    // Validate cross-product consistency for a feature
    validateCrossProduct: async ({ product, feature }) => {
      const requirement = await readRequirement(product, feature);
      const refs = requirement.frontmatter.cross_product_refs || [];

      const validation = {
        referencesValid: await validateRefs(refs),
        terminologyConsistent: await checkTerminology(requirement),
        apiCompatible: await checkApiCompatibility(product, feature),
        journeyCovered: await checkJourneyImplementation(product, feature)
      };

      return validation;
    },

    // Find all products affected by a shared change
    impactAnalysis: async ({ sharedPath }) => {
      const affectedProducts = await findReferencingProducts(sharedPath);
      const impactedFeatures = await findReferencingFeatures(sharedPath);

      return {
        products: affectedProducts,
        features: impactedFeatures,
        estimatedImpact: calculateImpact(impactedFeatures)
      };
    },

    // Suggest cross-product refs based on content similarity
    suggestReferences: async ({ product, feature }) => {
      const requirement = await readRequirement(product, feature);
      const suggestions = await findSimilarConcepts(requirement);

      return suggestions.map(s => ({
        suggestedRef: s.path,
        reason: s.similarity,
        confidence: s.score
      }));
    }
  }
};

Pre-Commit Hooks

yaml

# .pre-commit-config.yaml
repos:
  - repo: local
    hooks:
      - id: validate-cross-product-refs
        name: Validate Cross-Product References
        entry: scripts/validate-refs.js
        language: node
        files: 'products/.*/features/.*/requirement\.md$'

      - id: check-shared-terminology
        name: Check Shared Terminology
        entry: scripts/check-terminology.js
        language: node
        files: '\.md$'

      - id: api-contract-compatibility
        name: API Contract Compatibility
        entry: scripts/check-api-compat.js
        language: node
        files: 'api-contract\.md$'

API Standards

markdown

# contracts/api-standards.md

## Naming Conventions

| Concept | API Format | Example |
|---------|------------|---------|
| Resource ID | camelCase with prefix | deviceKey: "dk_abc123" |
| Timestamps | ISO 8601 UTC | "2025-11-28T10:30:00Z" |
| Pagination | Cursor-based | cursor: "eyJsYXN0..." |
| Errors | RFC 9457 Problem Details | type, title, detail, status |

## Standard Query Parameters

| Parameter | Type | Description |
|-----------|------|-------------|
| cursor | string | Pagination cursor |
| limit | integer | Items per page (max 100) |
| sort | string | Sort field and direction (name:asc) |
| filter | string | Filter expression |

## AI Implementation Notes

@ai-hint All list endpoints MUST support cursor pagination.
@ai-hint All mutations MUST return the created/updated resource.
@ai-hint All errors MUST follow RFC 9457 format.

AI Agent Integration

CLAUDE.md for Requirement Store

markdown

# Requirement Store - AI Instructions

## Purpose

This repository is the single source of truth for all product requirements.
Before implementing any feature, consult the relevant requirement documents.

## Finding Requirements

1. Navigate to `products/{product}/features/{feature}/`
2. Read `requirement.md` for business requirements
3. Read `api-contract.md` for API specifications
4. Read `platforms/{platform}.md` for platform-specific notes

## Before Implementation

Search for feature: products/{product}/features/{feature-name}/
Read requirement.md completely
Check related features in frontmatter
Review shared concepts in products/{product}/shared/
Verify API contract matches your implementation


## Cross-Platform Consistency

When implementing a feature:
- Follow the SAME requirement.md across all platforms
- Platform differences go in platforms/{platform}.md ONLY
- API calls must match api-contract.md exactly
- Use shared domain terminology from shared/*.md

## Updating Requirements

If implementation requires requirement changes:
1. Do NOT modify requirements unilaterally
2. Create a PR to requirement-store with proposed changes
3. Tag PM and tech lead for review
4. Implementation PR should reference requirement PR

## Document Relationships

- `requirement.md` - WHAT to build (all platforms)
- `api-contract.md` - HOW backend exposes it
- `ux-spec.md` - HOW it looks and feels
- `platforms/*.md` - Platform-specific deviations
- `test-cases.md` - HOW to verify it works

## Cross-Product References

When implementing features that span multiple products:

1. Always check `cross_product_refs` in frontmatter
2. Read ALL referenced documents before implementation
3. Use shared domain concepts from `shared/domains/`
4. Respect `depends_on` - implement dependencies first
5. When in doubt, consult `shared/` before creating product-specific solutions

Example workflow:

Feature: vsaas/features/device-management ├── cross_product_refs: │ ├── shared/domains/user-identity → Read first │ ├── shared/domains/permissions → Check permission model │ └── vortex/features/device-sync → Ensure compatibility └── depends_on: └── shared/integrations/sso → Must be working first

MCP Resource Provider

typescript

// requirement-store MCP server
const requirementStoreServer = {
  resources: {
    list: async ({ product, feature }) => {
      // List all requirements for a product/feature
      return requirements.map(req => ({
        uri: `req://${product}/${feature}/${req.id}`,
        name: req.title,
        mimeType: 'text/markdown',
        metadata: {
          version: req.version,
          status: req.status,
          platforms: req.platforms
        }
      }))
    }
  },
  tools: {
    getRequirement: async ({ product, feature }) => {
      // Return complete requirement with all related docs
      return {
        requirement: await readFile(`products/${product}/features/${feature}/requirement.md`),
        apiContract: await readFile(`products/${product}/features/${feature}/api-contract.md`),
        platforms: await readPlatformDocs(product, feature)
      }
    },
    checkConsistency: async ({ product, feature }) => {
      // Validate requirement is consistently implemented
      return validateCrossplatformConsistency(product, feature)
    }
  }
}

Implementation Workflow

Feature Development Flow

Requirement-Code Correlation

markdown

# In code PR description

## Requirement Reference

- Requirement: [req-device-management v2.3.0](../requirement-store/products/vsaas/features/device-management/requirement.md)
- API Contract: [api-device-management v2.3.0](../requirement-store/products/vsaas/features/device-management/api-contract.md)

## User Stories Implemented

- [x] US-001: View Device List
- [x] US-002: Add New Device
- [ ] US-003: Edit Device (next PR)

## Deviation Notes

None - implementation follows requirement exactly.

Migration Strategy

Phase 1: Template & Pilot (Month 1)

[ ] Create requirement document templates
[ ] Set up requirement-store repository
[ ] Migrate 1 feature (device-management) as pilot
[ ] Document AI agent integration pattern

Phase 2: New Features (Month 2-3)

[ ] All new features start in requirement-store
[ ] Require requirement reference in all PRs
[ ] Train PMs on requirement format
[ ] Implement MCP resource provider

Phase 3: Migration (Month 4-6)

[ ] Prioritize active features for migration
[ ] Convert existing Confluence PRDs
[ ] Deprecate platform-specific requirement docs
[ ] Full AI agent integration

Success Metrics

Metric	Target	How to Measure
Cross-platform consistency	>95%	Feature parity audit
Requirement coverage	100% active features	Store vs codebase diff
AI requirement access	<1s	MCP tool latency
PR-requirement linkage	100%	PR template compliance
Requirement freshness	<30 days	Updated date monitoring

Relationship to Multi-Level Spec Systems

The Reality: Specs Exist at Multiple Levels

Organizations that practice spec-driven development already maintain multi-level specification systems. The Global Requirement Store doesn't replace these systems - it feeds into them. Understanding this relationship is critical for successful adoption.

Using OpenSpec as Reference Model

OpenSpec exemplifies a three-stage spec lifecycle that many organizations adopt:

openspec/
├── specs/              # Current truth - what IS built
│   └── [capability]/
│       ├── spec.md     # Requirements and scenarios
│       └── design.md   # Technical patterns
├── changes/            # Proposals - what SHOULD change
│   └── [change-name]/
│       ├── proposal.md # Why, what, impact
│       ├── tasks.md    # Implementation checklist
│       ├── design.md   # Technical decisions
│       └── specs/      # Delta changes (ADDED/MODIFIED/REMOVED)
└── archive/            # Completed - what WAS changed
    └── YYYY-MM-DD-[name]/

How Global Requirements Feed Spec Systems

The Global Requirement Store operates at the "What" level - defining product requirements, user stories, and acceptance criteria. Spec systems like OpenSpec operate at the "How" level - tracking implementation proposals, current state, and history.

Mapping Requirement Store to Spec Levels

Requirement Store	Spec System Role	Lifecycle Stage
`requirement.md`	Triggers `changes/[name]/proposal.md`	Input to "Why"
`api-contract.md`	Informs `changes/[name]/specs/api/spec.md`	Input to "What Changes"
`ux-spec.md`	Informs `changes/[name]/specs/ui/spec.md`	Input to "What Changes"
User stories	Becomes scenarios in `spec.md`	Validated behaviors
Acceptance criteria	Becomes requirements in `spec.md`	Testable outcomes

Three-Tier Spec Flow

Tier 1: Global Requirements (Product-Level)

Location: requirement-store/products/{product}/features/{feature}/

Purpose: Define WHAT the product should do from a business perspective.

Owned by: Product Managers

Format:

yaml

id: req-device-management
title: Device Management
product: vsaas
version: 2.3.0
status: approved

Content: User stories, acceptance criteria, business rules, non-functional requirements.

Tier 2: Implementation Specs (System-Level)

Location: {repo}/openspec/specs/{capability}/

Purpose: Define HOW the system implements the requirements.

Owned by: Engineering teams

Format:

yaml

id: spec-device-crud
capability: device-management
status: active
version: 2.3.0

Content: Requirements with SHALL/MUST statements, scenarios (WHEN/THEN), technical constraints, error handling.

Tier 3: Change Proposals (Delta-Level)

Location: {repo}/openspec/changes/{change-id}/

Purpose: Track WHAT IS CHANGING and WHY.

Owned by: Feature developers (human or AI)

Format:

markdown

## Why
[Link to Global Requirement Store]
- req: requirement-store/products/vsaas/features/device-management v2.4.0

## What Changes
- ADDED: Bulk device registration
- MODIFIED: Device list pagination

## Impact
- Affected specs: device-management, device-provisioning

Integration Pattern: Requirement-to-Spec Pipeline

Frontmatter Linking

To maintain traceability, use explicit frontmatter references between tiers:

In Requirement Store (requirement.md):

yaml

id: req-device-management
implementations:
  - repo: vsaas-backend
    spec: openspec/specs/device-management
  - repo: vsaas-web
    spec: openspec/specs/device-ui

In Spec System (changes/add-bulk-device/proposal.md):

yaml

change_id: add-bulk-device
requirement_ref: requirement-store/products/vsaas/features/device-management
requirement_version: 2.4.0

In Spec System (specs/device-management/spec.md):

yaml

id: spec-device-management
capability: device-management
requirement_source: requirement-store/products/vsaas/features/device-management
last_requirement_version: 2.4.0

AI Agent Workflow with Multi-Level Specs

When AI agents implement features, they navigate multiple spec levels:

AI Agent Implementation Workflow:

1. READ Global Requirement
   └── requirement-store/products/vsaas/features/device-management/
       ├── requirement.md    → Understand WHAT to build
       ├── api-contract.md   → Understand API shape
       └── ux-spec.md        → Understand UI expectations

2. CHECK Existing Specs
   └── openspec/specs/device-management/
       ├── spec.md           → Current implementation truth
       └── design.md         → Technical patterns in use

3. CREATE Change Proposal
   └── openspec/changes/add-bulk-device/
       ├── proposal.md       → Reference requirement, explain why
       ├── tasks.md          → Implementation checklist
       └── specs/device-management/spec.md  → ADDED/MODIFIED deltas

4. IMPLEMENT Tasks
   └── Follow tasks.md, validate against requirement

5. ARCHIVE After Deployment
   └── Move to openspec/archive/YYYY-MM-DD-add-bulk-device/
       └── Update specs/device-management/spec.md with merged changes

Benefits of Multi-Level Integration

Benefit	Without Integration	With Integration
Traceability	Requirements disconnected from implementation	Clear path: requirement -> proposal -> spec -> code
Version correlation	Code changes without requirement reference	Every spec change links to requirement version
AI context	Agents see only local specs	Agents navigate full hierarchy for complete context
Change impact	Unknown downstream effects	Automated impact analysis across levels
Audit trail	Scattered documentation	Complete history in archive with requirement refs

Validation Across Levels

Implement CI validation to ensure consistency across specification levels:

yaml

# .github/workflows/spec-validation.yml
name: Multi-Level Spec Validation

on:
  pull_request:
    paths:
      - 'openspec/**'
      - 'requirement-store/**'

jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
      - name: Validate requirement references
        run: |
          # Check all proposals reference valid requirements
          openspec validate --check-requirement-refs

      - name: Check spec-requirement alignment
        run: |
          # Verify specs are not ahead of approved requirements
          scripts/check-spec-requirement-alignment.sh

      - name: Cross-repo consistency
        run: |
          # Ensure shared concepts match across repos
          scripts/validate-cross-repo-consistency.sh

Migration: Adding Multi-Level Awareness

For organizations adopting both Global Requirement Store and spec systems:

Phase 1: Establish Links

Add requirement_source to existing specs
Add implementations to existing requirements
Create tooling to validate references

Phase 2: Enforce Flow

Require requirement reference in all change proposals
Block spec changes without corresponding requirement
Automate requirement version bumping

Phase 3: AI Integration

Train agents to navigate full hierarchy
Implement MCP tools for cross-level queries
Enable automated traceability reports

Anti-Patterns to Avoid

1. Platform-First Requirements

Problem: Writing requirements from one platform's perspective.

Why It Fails: Other platforms retrofit requirements, causing inconsistency.

Instead: Write platform-agnostic requirements, add platform notes separately.

2. API-Last Design

Problem: Defining API after frontend implementation starts.

Why It Fails: Frontend makes assumptions, backend differs, integration breaks.

Instead: API contract defined alongside requirement, before implementation.

3. Stale Requirements

Problem: Requirements not updated when implementation changes.

Why It Fails: AI agents generate code against outdated specs.

Instead: Require requirement PR for any spec-changing code PR.

4. Duplicate Definitions

Problem: Same concept defined differently in multiple features.

Why It Fails: AI gets conflicting context, generates inconsistent code.

Instead: Extract to shared/*.md, reference from features.

G1: Single Source of Truth - Central repository as source of truth
G3: Centralized Requirements Management - Requirement centralization
E3: Contract-First Development - API contracts alongside requirements

Related: Agent-Friendly Knowledge Base | Back: Proposals Overview

References

Model Context Protocol (MCP) - Anthropic's protocol for AI-tool integration
RFC 9457 - Problem Details for HTTP APIs
Claude Code Documentation - Official documentation for CLAUDE.md AI guidance files
API-First Design - Swagger's guide to API-first development
OpenSpec - Specification-driven development framework demonstrating multi-level spec lifecycle (changes -> specs -> archive)

Global Requirement Store ​

Problem Statement ​

Current State: Fragmented Requirements ​

Evidence from Team Feedback ​

The Fundamental Problem ​

Proposed Solution: Global Requirement Store ​

Target Architecture ​

Core Principles ​

Repository Structure ​

Directory Layout ​

Requirement Document Structure ​

API Contract Document ​

POST /api/v2/sites/{siteId}/devices ​

Data Models ​

Device ​

AI Implementation Notes ​

Web-Specific Behaviors ​

Accessibility ​

AI Guidelines ​

Reference Types ​

Dependency Graph ​

Cross-Product Scenarios ​

Scenario 1: Shared Feature Implementation ​

Scenario 2: Cross-Product Data Flow ​

AI Implementation Notes ​

Cross-Product Handoffs ​

AI Implementation Notes ​

Change Management Rules ​

Conflict Resolution ​

Cross-Product Validation ​

Automated Consistency Checks ​

MCP Validation Tools ​

Pre-Commit Hooks ​

API Standards ​

AI Agent Integration ​

CLAUDE.md for Requirement Store ​

MCP Resource Provider ​

Implementation Workflow ​

Feature Development Flow ​

Requirement-Code Correlation ​

Migration Strategy ​

Phase 1: Template & Pilot (Month 1) ​

Phase 2: New Features (Month 2-3) ​

Phase 3: Migration (Month 4-6) ​

Success Metrics ​

Relationship to Multi-Level Spec Systems ​

The Reality: Specs Exist at Multiple Levels ​

Using OpenSpec as Reference Model ​

How Global Requirements Feed Spec Systems ​

Mapping Requirement Store to Spec Levels ​

Three-Tier Spec Flow ​

Tier 1: Global Requirements (Product-Level) ​

Tier 2: Implementation Specs (System-Level) ​

Tier 3: Change Proposals (Delta-Level) ​

Integration Pattern: Requirement-to-Spec Pipeline ​

Frontmatter Linking ​

AI Agent Workflow with Multi-Level Specs ​

Benefits of Multi-Level Integration ​

Validation Across Levels ​

Migration: Adding Multi-Level Awareness ​

Anti-Patterns to Avoid ​

1. Platform-First Requirements ​

2. API-Last Design ​

3. Stale Requirements ​

4. Duplicate Definitions ​

Related Principles ​

References ​

Global Requirement Store

Problem Statement

Current State: Fragmented Requirements

Evidence from Team Feedback

The Fundamental Problem

Proposed Solution: Global Requirement Store

Target Architecture

Core Principles

Repository Structure

Directory Layout

Requirement Document Structure

API Contract Document

POST /api/v2/sites/{siteId}/devices

Data Models

Device

AI Implementation Notes

Web-Specific Behaviors

Accessibility

AI Guidelines

Reference Types

Dependency Graph

Cross-Product Scenarios

Scenario 1: Shared Feature Implementation

Scenario 2: Cross-Product Data Flow

AI Implementation Notes

Cross-Product Handoffs

AI Implementation Notes

Change Management Rules

Conflict Resolution

Cross-Product Validation

Automated Consistency Checks

MCP Validation Tools

Pre-Commit Hooks

API Standards

AI Agent Integration

CLAUDE.md for Requirement Store

MCP Resource Provider

Implementation Workflow

Feature Development Flow

Requirement-Code Correlation

Migration Strategy

Phase 1: Template & Pilot (Month 1)

Phase 2: New Features (Month 2-3)

Phase 3: Migration (Month 4-6)

Success Metrics

Relationship to Multi-Level Spec Systems

The Reality: Specs Exist at Multiple Levels

Using OpenSpec as Reference Model

How Global Requirements Feed Spec Systems

Mapping Requirement Store to Spec Levels

Three-Tier Spec Flow

Tier 1: Global Requirements (Product-Level)

Tier 2: Implementation Specs (System-Level)

Tier 3: Change Proposals (Delta-Level)

Integration Pattern: Requirement-to-Spec Pipeline

Frontmatter Linking

AI Agent Workflow with Multi-Level Specs

Benefits of Multi-Level Integration

Validation Across Levels

Migration: Adding Multi-Level Awareness

Anti-Patterns to Avoid

1. Platform-First Requirements

2. API-Last Design

3. Stale Requirements

4. Duplicate Definitions

Related Principles

References