Multi-Product, Multi-Level Spec Management

This proposal establishes a hierarchical specification management framework that enables organizations with multiple products to maintain consistent, traceable specifications across different abstraction levels. AI agents navigate this hierarchy to understand context, constraints, and dependencies when generating code.

Key Insight: Current AI development frameworks assume single product, single team environments. Multi-product organizations need a structured approach where specifications cascade from organization-wide principles to product-specific implementations while maintaining traceability and consistency.

Vision: Intent-to-Plan in Seconds

The ultimate goal of multi-level spec management is to enable instant, comprehensive planning from high-level intent - especially for end-to-end, cross-product features:

The Vision: For any end-to-end, cross-product feature, a human provides only a high-level intent. With full information transparency (all specs AI-visible across all products), the AI agent immediately produces a complete detailed plan covering all affected products and their integration points.

Example: Cross-Product Feature Intent

markdown

## High-Level Intent

"Enable unified device health monitoring across VSaaS, Vortex, and Cloud Portal
with real-time alerts and historical analytics."

AI-Generated Cross-Product Plan

Plan Component	AI Generates
VSaaS Changes	Device health data collection API, streaming endpoints
Vortex Changes	Health data aggregation service, alert rules engine
Cloud Portal Changes	Dashboard widgets, alert management UI, analytics views
Shared Domain Updates	`DeviceHealth` entity in shared domains
API Contracts	Inter-service communication specs, event schemas
Integration Specs	Message queue topics, data flow diagrams
UX Flows	Consistent health visualization across all products
Test Strategy	End-to-end tests spanning all three products
Migration Plan	Phased rollout, backward compatibility per product
Dependency Graph	Which changes block others, parallel work streams

Human Role: Review the comprehensive cross-product plan, approve or request adjustments, then let AI execute across all affected codebases.

Why This Requires Multi-Level Spec Management

Without Hierarchy	With Hierarchy
AI asks clarifying questions about standards	AI knows all standards from Level 0
AI guesses at product constraints	AI reads product specs from Level 1
AI creates inconsistent designs	AI follows inherited patterns
Human must specify every detail	Human only provides intent
Planning takes days of back-and-forth	Planning takes seconds

The Information Transparency Principle

For this vision to work, all context must be AI-visible:

markdown

## AI-Visible Context Checklist

- [x] Organization principles in version control
- [x] Product-specific constraints documented
- [x] Shared domains with clear ownership
- [x] API standards with examples
- [x] Design system components cataloged
- [x] Existing feature specs indexed
- [x] Cross-product dependencies mapped
- [x] Historical decisions recorded (ADRs)

When humans can state intent and AI can access complete context, the result is instant comprehensive planning ready for human review - not endless clarification cycles.

Problem Statement

Current State: Framework Mismatch

Evidence from AI Development Challenges

Challenge	Impact
No spec inheritance	AI agents lack context about organizational standards when implementing features
Product silos	Same capability implemented inconsistently across products
Level confusion	High-level business requirements mixed with technical specs
Cross-product blindness	AI cannot detect conflicting specs across product boundaries
Approval bottlenecks	Multi-level reviews delay spec approval without adding value

The Fundamental Problem

AI agents working with flat specification structures:

Cannot inherit organizational design principles
Miss product-specific constraints and conventions
Duplicate solutions that already exist in other products
Generate code inconsistent with cross-product standards

Proposed Solution: Hierarchical Spec Management

Target Architecture

Specification Levels

Level	Name	Scope	Owner	AI Usage
0	Organization Principles	All products	Architecture Guild	Context for all decisions
1	Product Specs	Single product	Product Manager	Product-specific constraints
2	Feature Specs	Single feature	Feature Lead	What to build
3	Platform Specs	Single platform	Platform Lead	How to build (platform)
4	Implementation Specs	Single module	Developer	Detailed design

Core Principles

Inheritance Over Duplication: Lower levels inherit from higher levels, not copy
Override With Justification: Lower levels may override higher-level specs with documented reasoning
Cross-Product Visibility: AI agents can query specs across product boundaries
Level-Appropriate Detail: Each level contains only details relevant to its scope
Traceable Changes: All spec changes link to parent specs and downstream impacts

Specification Level Details

Level 0: Organization Principles

The foundational layer defining organization-wide standards that all products MUST follow.

markdown

# org-specs/
├── CLAUDE.md                      # AI agent master instructions
├── README.md                      # Human overview
│
├── principles/
│   ├── api-design.md              # API design principles (RFC 2119)
│   ├── security.md                # Security requirements
│   ├── accessibility.md           # A11y standards
│   ├── performance.md             # Performance budgets
│   └── data-privacy.md            # Data handling requirements
│
├── standards/
│   ├── naming-conventions.md      # Ubiquitous language
│   ├── error-handling.md          # Error response standards
│   ├── logging.md                 # Logging requirements
│   └── testing.md                 # Testing standards
│
├── governance/
│   ├── review-process.md          # Spec review requirements
│   ├── change-management.md       # Breaking change process
│   └── escalation.md              # Decision escalation paths
│
└── shared/
    ├── domains/                   # Cross-product domain concepts
    ├── integrations/              # Shared integration patterns
    └── components/                # Shared component registry

Example Organization Principle:

markdown

id: principle-api-design
level: 0
scope: organization
status: approved
version: 1.0.0
# API Design Principles

## Core Requirements

### REQ-API-001: RESTful Resource Naming
All HTTP APIs MUST use RESTful resource naming with plural nouns.

#### Scenario: Resource endpoint naming
- **WHEN** defining a new API endpoint
- **THEN** use plural nouns (e.g., `/devices`, `/users`, `/sites`)
- **AND** use kebab-case for multi-word resources (e.g., `/device-groups`)

### REQ-API-002: Cursor-Based Pagination
All list endpoints MUST implement cursor-based pagination.

#### Scenario: List endpoint pagination
- **WHEN** returning a collection of resources
- **THEN** support `cursor` and `limit` query parameters
- **AND** return `nextCursor` and `hasMore` in response

## AI Implementation Notes

@ai-hint Always check this document before designing any API endpoint.
@ai-hint These principles apply to ALL products without exception.
@ai-hint Violations require Architecture Guild approval and documented justification.

Level 1: Product Specs

Product-specific specifications that extend organization principles.

markdown

# products/vsaas/
├── _product.md                    # Product overview and context
├── CLAUDE.md                      # Product-specific AI instructions
│
├── principles/
│   ├── device-handling.md         # How VSaaS handles devices
│   ├── video-streaming.md         # Video-specific constraints
│   └── real-time.md               # Real-time requirements
│
├── domains/
│   ├── device.md                  # Device domain model
│   ├── site.md                    # Site/location model
│   └── video.md                   # Video/stream model
│
├── features/                      # Level 2 specs
│   └── ...
│
└── overrides/
    └── api-design.md              # Product-specific API variations

Example Product-Level Override:

markdown

id: vsaas-api-override
level: 1
scope: product
inherits: org-specs/principles/api-design
overrides:
  - REQ-API-001  # Partial override
status: approved
justification: Video streaming requires specialized endpoint patterns
approved_by: architecture-guild@company.com
# VSaaS API Design Overrides

## Inherited Principles

This document inherits from `org-specs/principles/api-design.md`.
All principles apply unless explicitly overridden below.

## Overrides

### REQ-API-001: RESTful Resource Naming (MODIFIED)

Original requirement: Use plural nouns for all endpoints.

**VSaaS Override:** Video streaming endpoints MAY use action-based paths.

#### Scenario: Streaming action endpoints
- **WHEN** defining video streaming control endpoints
- **THEN** MAY use action paths (e.g., `/devices/{id}/stream/start`)
- **BECAUSE** WebRTC signaling requires action-oriented semantics

#### Scenario: Non-streaming endpoints
- **WHEN** defining non-streaming endpoints
- **THEN** MUST follow original REQ-API-001 (plural nouns)

## AI Implementation Notes

@ai-hint For streaming endpoints, action paths are acceptable.
@ai-hint For all other VSaaS endpoints, follow org-level API principles.
@ai-hint When in doubt, default to org-level principles.

Level 2: Feature Specs

Feature-level specifications defining what to build.

markdown

# products/vsaas/features/device-management/
├── requirement.md                 # Business requirements
├── api-contract.md               # API specification
├── ux-spec.md                    # UX requirements
├── test-cases.md                 # Acceptance criteria
│
├── platforms/                     # Level 3 specs
│   ├── web.md
│   ├── ios.md
│   └── android.md
│
└── modules/                       # Level 4 specs
    ├── device-list.md
    └── device-add.md

Example Feature Spec Header:

markdown

id: feature-device-management
level: 2
scope: feature
product: vsaas

inherits:
  - org-specs/principles/api-design
  - org-specs/standards/error-handling
  - products/vsaas/principles/device-handling
  - products/vsaas/domains/device

cross_product_refs:
  - shared/domains/user-identity
  - vortex/features/device-sync

status: approved
version: 2.3.0

Level 3: Platform Specs

Platform-specific implementation details.

markdown

id: platform-web-device-management
level: 3
scope: platform
feature: device-management
platform: web

inherits:
  - products/vsaas/features/device-management/requirement
  - org-specs/shared/components/design-system

technology_stack:
  framework: vue3
  state: pinia
  components: shadcn-vue

status: approved
# Device Management - Web Platform

## Component Mapping

| Feature Element | Design System Component |
|-----------------|------------------------|
| Device list | `DataTable` |
| Device card | `Card` with `Badge` |
| Add device form | `Dialog` with `Form` |
| Status indicator | `StatusBadge` |

## State Management

Use Pinia store pattern:
```typescript
// stores/device.ts
export const useDeviceStore = defineStore('device', () => {
  // Implementation follows org-specs/standards/state-management
})

AI Implementation Notes

@ai-hint Use Vue 3 Composition API exclusively. @ai-hint Import components from @/components/ui (shadcn-vue). @ai-hint Follow Pinia store patterns from org-specs.


### Level 4: Implementation Specs

Detailed module-level design specifications.

```markdown
id: impl-device-list-component
level: 4
scope: implementation
platform: web
feature: device-management
module: device-list

inherits:
  - products/vsaas/features/device-management/platforms/web
  - org-specs/standards/testing

files:
  - src/components/device/DeviceList.vue
  - src/components/device/DeviceListItem.vue
  - src/stores/device.ts
  - src/composables/useDeviceList.ts

status: approved
# Device List Component Implementation

## Component Structure

DeviceList/ ├── DeviceList.vue # Container component ├── DeviceListItem.vue # Item renderer ├── DeviceListHeader.vue # Table header with sort controls └── tests/ └── DeviceList.spec.ts


## Props Interface

```typescript
interface DeviceListProps {
  siteId: string;
  initialFilters?: DeviceFilters;
  onDeviceSelect?: (device: Device) => void;
}

AI Implementation Notes

@ai-hint This component uses virtual scrolling for large lists. @ai-hint Sorting is handled by DeviceListHeader emitting sort events. @ai-hint Tests should cover: loading, empty, error, pagination states.



## Cross-Level Relationships

### Inheritance Chain

```mermaid
graph TD
    subgraph "Inheritance Example"
        ORG[org-specs/principles/api-design]
        PROD[products/vsaas/overrides/api-design]
        FEAT[features/device-management/api-contract]
        PLAT[platforms/web.md]
        IMPL[modules/device-list.md]

        ORG -->|inherits| PROD
        PROD -->|inherits| FEAT
        FEAT -->|inherits| PLAT
        PLAT -->|inherits| IMPL
    end

    style ORG fill:#e8f5e9
    style PROD fill:#e3f2fd
    style FEAT fill:#fff3e0
    style PLAT fill:#fce4ec
    style IMPL fill:#f3e5f5

Override Tracking

markdown

# Override Chain Example

## REQ-API-001: Resource Naming

| Level | Document | Status | Justification |
|-------|----------|--------|---------------|
| 0 | org-specs/principles/api-design | Original | - |
| 1 | products/vsaas/overrides/api-design | Modified | Streaming endpoints need action paths |
| 2 | features/device-management/api-contract | Inherited | Uses VSaaS override |

Impact Analysis

Multi-Product Coordination

Cross-Product Spec Visibility

markdown

# Scenario: Implementing feature that exists in another product

## AI Agent Workflow

1. Agent reads feature requirement
2. Detects similar feature exists in another product:

cross_product_refs: - vortex/features/device-sync # Similar feature

3. Agent queries vortex spec for patterns
4. Applies consistent patterns while respecting product differences
5. Notes any divergence in implementation spec

Shared Domain Management

Cross-Product Change Protocol

Change Type	Process	Reviewers
Level 0 change	RFC + All product review	Architecture Guild + All Product Leads
Level 1 change	Product RFC	Product Lead + Architecture Guild
Shared domain change	Cross-product RFC	All consuming product leads
Feature with cross-product refs	Impact notification	Referenced product leads

AI Agent Integration

markdown

# Multi-Level Spec Navigation - AI Instructions

## Understanding the Hierarchy

Specifications are organized in 5 levels:
- **Level 0**: Organization principles (always apply)
- **Level 1**: Product specs (apply within product)
- **Level 2**: Feature specs (what to build)
- **Level 3**: Platform specs (how to build)
- **Level 4**: Implementation specs (detailed design)

## Before Any Implementation

Identify the feature: products/{product}/features/{feature}/
Read Level 2 spec (requirement.md)
Trace inheritance chain upward:
- Check feature inherits from
- Check product overrides
- Check org-level principles
Check cross_product_refs for related work
Read platform spec (Level 3) for your target platform
Read implementation spec (Level 4) if exists


## Resolving Conflicts

When specs at different levels seem to conflict:
1. Lower levels override higher levels ONLY if explicitly documented
2. Look for `overrides:` in frontmatter
3. If no explicit override, higher level wins
4. When uncertain, note the conflict and ask for clarification

## Cross-Product Awareness

When implementing features:
1. Always check cross_product_refs
2. Query similar features in other products for patterns
3. Use shared domains from org-specs/shared/
4. Do not create product-specific solutions for cross-product concepts

## Level-Appropriate Output

Match your output to the spec level:
- Level 2 prompts → Feature-level design decisions
- Level 3 prompts → Platform-specific implementation
- Level 4 prompts → Detailed code generation

typescript

const multiLevelSpecServer = {
  tools: {
    // Trace full inheritance chain for a spec
    traceInheritance: async ({ specPath }) => {
      const spec = await readSpec(specPath);
      const chain = [];
      let current = spec;

      while (current.inherits) {
        for (const parent of current.inherits) {
          const parentSpec = await readSpec(parent);
          chain.push({
            path: parent,
            level: parentSpec.level,
            overrides: parentSpec.overrides || []
          });
        }
        current = await readSpec(current.inherits[0]);
      }

      return chain;
    },

    // Find all specs affected by a change
    impactAnalysis: async ({ specPath, changeType }) => {
      const spec = await readSpec(specPath);
      const level = spec.level;

      // Find all specs that inherit from this one
      const affected = await findInheritingSpecs(specPath);

      return {
        directlyAffected: affected.filter(s => s.level === level + 1),
        transitivelyAffected: affected.filter(s => s.level > level + 1),
        crossProductRefs: await findCrossProductRefs(specPath)
      };
    },

    // Resolve effective spec considering all inheritance
    resolveEffectiveSpec: async ({ specPath }) => {
      const chain = await this.traceInheritance({ specPath });
      const merged = {};

      // Apply from highest level to lowest (overrides win)
      for (const ancestor of chain.reverse()) {
        const ancestorSpec = await readSpec(ancestor.path);
        Object.assign(merged, ancestorSpec.requirements);
      }

      const currentSpec = await readSpec(specPath);
      Object.assign(merged, currentSpec.requirements);

      return {
        effectiveRequirements: merged,
        overrideChain: chain.filter(c => c.overrides.length > 0)
      };
    },

    // Check cross-product consistency
    validateCrossProduct: async ({ product, feature }) => {
      const spec = await readSpec(`products/${product}/features/${feature}/requirement.md`);
      const refs = spec.cross_product_refs || [];

      const validation = {
        terminology: await validateTerminologyConsistency(spec, refs),
        apiCompatibility: await validateApiCompatibility(spec, refs),
        domainAlignment: await validateDomainUsage(spec)
      };

      return validation;
    }
  }
};

Governance Model

Approval Matrix

Spec Level	Author	Reviewer	Approver
Level 0	Architecture Guild	All Product Leads	Architecture Guild
Level 1	Product Lead	Architecture Guild	Product Lead
Level 2	Feature Lead	Product Lead	Feature Lead
Level 3	Platform Lead	Feature Lead	Platform Lead
Level 4	Developer	Platform Lead	Developer

Change Propagation

Flattened Approval for AI Workflows

Spec approvals should:

Eliminate redundant reviews - If Level 2 inherits unchanged from Level 1, no Level 1 re-review needed
Parallel reviews - Cross-product refs reviewed in parallel, not sequentially
Automated validation - CI validates inheritance chain correctness
Owner autonomy - Each level owner has full authority within their scope

Implementation Roadmap

Phase 1: Foundation (Month 1)

[ ] Define Level 0 organization principles
[ ] Create spec hierarchy directory structure
[ ] Implement inheritance tracking in frontmatter
[ ] Build inheritance chain validator (CI)

Phase 2: Product Migration (Month 2-3)

[ ] Migrate one product to new hierarchy
[ ] Create product-level override documentation
[ ] Implement MCP tools for spec navigation
[ ] Train AI agents on multi-level navigation

Phase 3: Cross-Product (Month 4-5)

[ ] Establish shared domain specs
[ ] Implement cross-product consistency validation
[ ] Create impact analysis tooling
[ ] Document governance model

Phase 4: Full Rollout (Month 6)

[ ] Migrate remaining products
[ ] Integrate with CI/CD pipeline
[ ] Measure and optimize AI navigation efficiency
[ ] Refine governance based on experience

Success Metrics

Metric	Target	Measurement
Spec inheritance coverage	>90%	Features inheriting from org principles
Cross-product consistency	>95%	Shared concept usage audit
Override documentation	100%	All overrides have justification
AI navigation accuracy	>85%	Correct level identification
Change impact accuracy	>95%	Predicted vs actual affected specs
Review cycle time	<24h L4, <48h L3, <72h L2	Time from submission to approval

Anti-Patterns to Avoid

1. Copy-Paste Instead of Inherit

Problem: Copying Level 0 content into Level 2 specs.

Why It Fails: Changes to Level 0 don't propagate; specs drift apart.

Instead: Use inherits: frontmatter; reference, don't copy.

2. Over-Deep Hierarchy

Problem: Creating 8+ levels of specification.

Why It Fails: Navigation becomes complex; inheritance chains break.

Instead: Stick to 5 levels; flatten unnecessary intermediate specs.

3. Cross-Level Shortcuts

Problem: Level 4 spec directly referencing Level 0, skipping Level 1-3.

Why It Fails: Misses product/feature-specific constraints.

Instead: Always inherit through the chain; use cross_product_refs for lateral references.

4. Undocumented Overrides

Problem: Lower level contradicts higher level without overrides: declaration.

Why It Fails: AI agents can't detect conflicts; generates inconsistent code.

Instead: All overrides MUST be declared in frontmatter with justification.

CLAUDE.md Integration Example

markdown

# Product: VSaaS - AI Instructions

## Spec Hierarchy Context

This product follows multi-level spec management:

org-specs/ # Level 0 - Always check first └── principles/ └── api-design.md # Your API designs must follow this

products/vsaas/ # Level 1 - Product constraints ├── _product.md # Read for product context ├── overrides/ # Check for org-level overrides └── domains/ # Product domain models

products/vsaas/features/ # Level 2 - Feature specs └── {feature}/ └── requirement.md # What you're building


## Implementation Workflow

1. Read Level 0 principles (always applicable)
2. Check Level 1 overrides (product-specific)
3. Read Level 2 feature spec (your task)
4. Follow Level 3 platform spec (your platform)
5. Generate Level 4 implementation spec if complex

## Inheritance Rules

- Higher levels apply unless explicitly overridden
- Check `overrides:` in frontmatter for exceptions
- When uncertain, default to higher level spec
- Document any ambiguity for human review

G1: Single Source of Truth - Hierarchical spec management as canonical source
G4: Unified Product Management - Multi-product coordination

References

Workflow Framework - Multi-level specification overview
OpenSpec - Specification-driven development framework
RFC 2119 - Key words for requirement levels
Global Requirement Store - Product-oriented requirement management

Multi-Product, Multi-Level Spec Management ​

Vision: Intent-to-Plan in Seconds ​

Example: Cross-Product Feature Intent ​

AI-Generated Cross-Product Plan ​

Why This Requires Multi-Level Spec Management ​

The Information Transparency Principle ​

Problem Statement ​

Current State: Framework Mismatch ​

Evidence from AI Development Challenges ​

The Fundamental Problem ​

Proposed Solution: Hierarchical Spec Management ​

Target Architecture ​

Specification Levels ​

Core Principles ​

Specification Level Details ​

Level 0: Organization Principles ​

Level 1: Product Specs ​

Level 2: Feature Specs ​

Level 3: Platform Specs ​

AI Implementation Notes ​

AI Implementation Notes ​

Override Tracking ​

Impact Analysis ​

Multi-Product Coordination ​

Cross-Product Spec Visibility ​

Shared Domain Management ​

Cross-Product Change Protocol ​

AI Agent Integration ​

CLAUDE.md for Multi-Level Navigation ​

MCP Tools for Spec Navigation ​

Governance Model ​

Approval Matrix ​

Change Propagation ​

Flattened Approval for AI Workflows ​

Implementation Roadmap ​

Phase 1: Foundation (Month 1) ​

Phase 2: Product Migration (Month 2-3) ​

Phase 3: Cross-Product (Month 4-5) ​

Phase 4: Full Rollout (Month 6) ​

Success Metrics ​

Anti-Patterns to Avoid ​

1. Copy-Paste Instead of Inherit ​

2. Over-Deep Hierarchy ​

3. Cross-Level Shortcuts ​

4. Undocumented Overrides ​

CLAUDE.md Integration Example ​

Related Principles ​

References ​

Multi-Product, Multi-Level Spec Management

Vision: Intent-to-Plan in Seconds

Example: Cross-Product Feature Intent

AI-Generated Cross-Product Plan

Why This Requires Multi-Level Spec Management

The Information Transparency Principle

Problem Statement

Current State: Framework Mismatch

Evidence from AI Development Challenges

The Fundamental Problem

Proposed Solution: Hierarchical Spec Management

Target Architecture

Specification Levels

Core Principles

Specification Level Details

Level 0: Organization Principles

Level 1: Product Specs

Level 2: Feature Specs

Level 3: Platform Specs

AI Implementation Notes

AI Implementation Notes

Override Tracking

Impact Analysis

Multi-Product Coordination

Cross-Product Spec Visibility

Shared Domain Management

Cross-Product Change Protocol

AI Agent Integration

CLAUDE.md for Multi-Level Navigation

MCP Tools for Spec Navigation

Governance Model

Approval Matrix

Change Propagation

Flattened Approval for AI Workflows

Implementation Roadmap

Phase 1: Foundation (Month 1)

Phase 2: Product Migration (Month 2-3)

Phase 3: Cross-Product (Month 4-5)

Phase 4: Full Rollout (Month 6)

Success Metrics

Anti-Patterns to Avoid

1. Copy-Paste Instead of Inherit

2. Over-Deep Hierarchy

3. Cross-Level Shortcuts

4. Undocumented Overrides

CLAUDE.md Integration Example

Related Principles

References