Product Requirements Documents

• 1: PRD: IR JSON Schema Verification
• 2: BDD Test Scenarios: IR JSON Schema Verification
• 3: PRD: Product Manager Skill for Morphir Ecosystem
• 4: PRD: Deployment Architecture Refactor
• 5: PRD: Layered Configuration
• 6: Vulnerability Resolver Skill Requirements

1 - PRD: IR JSON Schema Verification

Product Requirements Document: IR JSON Schema Verification

Status: ✅ Phase 1 Complete | ⏳ Phase 2 Ready Created: 2025-12-13 Last Updated: 2025-12-15 Phase 1 Completion Date: 2025-12-15 Current Phase: Phase 1 Complete - Ready for Phase 2 Author: Morphir .NET Team

Overview

This PRD defines the requirements for adding JSON schema verification capabilities to the Morphir .NET CLI and tooling. This feature will enable developers to validate Morphir IR JSON files against the official schema specifications for all supported format versions (v1, v2, v3).

The implementation will introduce WolverineFx as a messaging layer between the CLI and core tooling services, using Vertical Slice Architecture to organize features by use case rather than technical layers.

Problem Statement

Currently, developers working with Morphir IR JSON files have no built-in way to:

1. Validate IR correctness: Verify that generated or hand-written IR files conform to the expected schema
2. Debug format issues: Quickly identify structural problems in IR files
3. Ensure version compatibility: Confirm which schema version an IR file uses and whether it’s valid
4. Catch errors early: Detect malformed IR before it causes runtime failures in downstream tools

Current Pain Points

• Manual validation: Developers must use external tools (Python jsonschema, Node.js ajv-cli) to validate IR
• Version confusion: No automated way to detect which schema version an IR file uses
• Poor error messages: External validators provide generic JSON schema errors without Morphir-specific context
• Workflow friction: Validation requires switching between tools and languages

Goals

Primary Goals

1. Enable IR validation via CLI command for all supported schema versions (v1, v2, v3)
2. Establish WolverineFx integration with Vertical Slice Architecture as the foundation for future tooling commands
3. Provide excellent developer experience with clear, actionable error messages and multiple output formats
4. Support flexible input starting with file paths, with extensibility for stdin and multiple files
5. Auto-detect schema versions while allowing manual override when needed

Secondary Goals

6. Create reusable validation services in Morphir.Tooling that can be leveraged by other tools
7. Establish testing patterns using BDD scenarios for validation use cases
8. Document architectural decisions for Vertical Slice Architecture adoption

Non-Goals

Explicitly Out of Scope

• IR migration/upgrade tooling: Will be addressed in a separate PRD (tracked below)
• Schema generation: Creating schemas from .NET types
• Real-time validation: IDE plugins or language servers
• IR parsing/deserialization: This already exists in Morphir.Core
• Schema authoring: Schemas are maintained in the upstream Morphir repository

User Stories

Story 1: Validate IR File

As a Morphir developer I want to validate my IR JSON file against the official schema So that I can catch structural errors before using the IR in other tools

Acceptance Criteria:

• User runs morphir ir verify path/to/morphir-ir.json
• Tool auto-detects schema version from JSON
• Tool validates against appropriate schema
• Tool returns clear success or detailed error messages
• Exit code is 0 for valid, non-zero for invalid

Story 2: Validate Specific Schema Version

As a Morphir tooling developer I want to validate IR against a specific schema version So that I can test version-specific compatibility

Acceptance Criteria:

• User runs morphir ir verify --schema-version 3 path/to/morphir-ir.json
• Tool validates against specified schema version regardless of file content
• Tool reports validation results for the specified version

Story 3: Machine-Readable Output

As a CI/CD pipeline I want to get validation results in JSON format So that I can parse and process errors programmatically

Acceptance Criteria:

• User runs morphir ir verify --json path/to/morphir-ir.json
• Tool outputs structured JSON with validation results
• JSON includes error locations, messages, and metadata

Story 4: Quick Status Check

As a developer in a CI pipeline I want to validate IR without verbose output So that I can keep build logs clean

Acceptance Criteria:

• User runs morphir ir verify --quiet path/to/morphir-ir.json
• Tool only outputs errors (if any)
• Exit code indicates success/failure

Story 5: Detect IR Version

As a Morphir developer I want to identify which schema version my IR file uses So that I know which tools and features are compatible

Acceptance Criteria:

• User runs morphir ir detect-version path/to/morphir-ir.json
• Tool analyzes IR structure and reports detected version
• Tool provides confidence level or rationale for detection

Detailed Requirements

Functional Requirements

FR-1: Command Interface

Command Structure:

morphir ir verify <file-path> [options]

Required Arguments:

• <file-path>: Path to the Morphir IR JSON file to validate

Options:

• --schema-version <version>: Explicitly specify schema version (1, 2, or 3)
• --json: Output results in JSON format
• --quiet: Suppress output except errors
• -v, --verbose: Show detailed validation information

Exit Codes:

• 0: Validation successful
• 1: Validation failed (schema errors)
• 2: Operational error (file not found, invalid JSON, etc.)

FR-2: Input Format Support

Phase 1 (Initial Release):

• ✅ File paths (absolute and relative)

Phase 2 (Future):

• ⏳ Stdin support: cat morphir-ir.json | morphir ir verify -
• ⏳ Multiple files: morphir ir verify file1.json file2.json file3.json
• ⏳ Directory validation: morphir ir verify --recursive ./ir-files/

FR-3: Schema Version Handling

Auto-Detection Logic (default behavior):

1. Look for formatVersion field in JSON
2. Analyze tag capitalization patterns:
   • All lowercase tags → v1
   • Mixed capitalization → v2
   • All capitalized tags → v3
3. If ambiguous, report detection failure with suggestions

Manual Override:

• --schema-version option forces validation against specified version
• Useful for testing migration scenarios
• Bypasses auto-detection

FR-4: Output Formats

Human-Readable Format (default):

✓ Validation successful
  File: morphir-ir.json
  Schema: v3 (auto-detected)
  Validated: 2025-12-13 10:30:45

Or on error:

✗ Validation failed against schema v3

Error 1: Invalid type tag
  Path: $.modules[0].types["MyType"].value[0]
  Expected: "Public" or "Private"
  Found: "public"
  Line: 42, Column: 12

Error 2: Missing required field
  Path: $.package.modules
  Message: Required property 'name' is missing

2 errors found. Fix these issues and try again.

JSON Format (--json flag):

{
  "valid": false,
  "schemaVersion": "3",
  "detectionMethod": "auto",
  "file": "morphir-ir.json",
  "timestamp": "2025-12-13T10:30:45Z",
  "errors": [
    {
      "path": "$.modules[0].types[\"MyType\"].value[0]",
      "message": "Invalid type tag",
      "expected": ["Public", "Private"],
      "found": "public",
      "line": 42,
      "column": 12
    }
  ],
  "errorCount": 2
}

Quiet Format (--quiet flag):

• Only output errors
• No success messages
• Minimal formatting

FR-5: Schema Validation

Supported Versions:

• ✅ v1: morphir-ir-v1.yaml (all lowercase tags)
• ✅ v2: morphir-ir-v2.yaml (mixed capitalization)
• ✅ v3: morphir-ir-v3.yaml (all capitalized tags)

Validation Requirements:

• Use json-everything library
• Validate against JSON Schema Draft 07 specification
• Provide detailed error locations using JSON Path notation
• Include contextual information in error messages

FR-6: Version Detection Helper

Command:

morphir ir detect-version <file-path>

Output Example:

Detected schema version: v3
Confidence: High
Rationale:
  - All tags are capitalized ("Library", "Public", "Apply", etc.)
  - Contains formatVersion: 3

Implementation Status: ⏳ Planned for Phase 2

FR-7: Error Reporting Quality

Error Messages Must Include:

• JSON Path to the error location
• Expected value/format
• Actual value found
• Line and column numbers (when possible)
• Suggested fixes (when applicable)

Example Error:

Error: Invalid access control tag
  Location: $.modules[0].types["Account"].accessControlled[0]
  Expected: One of ["Public", "Private"]
  Found: "public"
  Suggestion: Change "public" to "Public" (capitalize first letter)

Non-Functional Requirements

NFR-1: Performance

Targets:

• Small files (<100KB): Validation completes in <100ms
• Typical files (<1MB): Validation completes in <500ms
• Large files (>1MB): Validation completes in <2 seconds

Benchmarking:

• Use BenchmarkDotNet for performance testing
• Test with representative IR files of varying sizes
• Profile schema loading and validation separately

NFR-2: Reliability

Error Handling:

• Gracefully handle malformed JSON with clear error messages
• Catch and report file I/O errors (file not found, permission denied, etc.)
• Handle edge cases: empty files, extremely large files, invalid UTF-8
• Never crash; always return meaningful error messages

Validation Accuracy:

• 100% compliance with JSON Schema Draft 07 specification
• Zero false positives (valid IR rejected)
• Zero false negatives (invalid IR accepted)

NFR-3: Usability

CLI Experience:

• Clear, consistent command naming following morphir <noun> <verb> pattern
• Colored output for terminal readability (green=success, red=errors, yellow=warnings)
• Progress indicators for large files
• Helpful error messages with actionable suggestions

Documentation:

• CLI help text: morphir ir verify --help
• User guide in main docs: /docs/guides/validating-ir.md
• API documentation for Morphir.Tooling services

NFR-4: Maintainability

Code Organization (Vertical Slice Architecture):

src/Morphir.Tooling/
├── Features/
│   ├── VerifyIR/
│   │   ├── VerifyIR.cs              # Command, handler, validation
│   │   ├── VerifyIRResult.cs        # Result types
│   │   └── VerifyIRValidator.cs     # FluentValidation rules
│   └── DetectVersion/
│       ├── DetectVersion.cs         # Command & handler
│       └── VersionDetector.cs       # Detection logic
├── Infrastructure/
│   ├── JsonSchema/
│   │   ├── SchemaLoader.cs          # Load & cache schemas
│   │   └── SchemaValidator.cs       # Wrapper around json-everything
│   └── Schemas/                     # Embedded YAML schemas
│       ├── morphir-ir-v1.yaml
│       ├── morphir-ir-v2.yaml
│       └── morphir-ir-v3.yaml
└── Program.cs                        # Host configuration

Testing Coverage:

• >90% code coverage target
• Unit tests for all validation logic
• BDD scenarios using Reqnroll for user-facing features
• Integration tests for CLI commands

NFR-5: Extensibility

Architecture Flexibility:

• WolverineFx messaging enables reuse across different frontends (CLI, API, desktop app)
• Schema validation services usable independently of CLI
• Plugin-friendly design for future enhancements

Future Enhancements Supported:

• Additional input formats (URLs, streams)
• Custom validation rules beyond schema
• Watch mode for continuous validation
• Integration with VS Code extension

Technical Design

Architecture: Vertical Slice Architecture with WolverineFx

We will adopt Vertical Slice Architecture as recommended by WolverineFx, organizing code by feature/use case rather than horizontal technical layers.

Key Architectural Principles

1. Organize by Feature: Each slice (e.g., VerifyIR) contains all code needed for that feature
2. Pure Function Handlers: Handlers return side effects rather than directly coupling to infrastructure
3. No Repository Abstractions: Direct use of persistence/infrastructure tools when needed
4. Single File Per Feature: Command, handler, and validation in one file when possible
5. Minimal Ceremony: Avoid unnecessary abstraction layers

A-Frame Architecture

┌─────────────────────────────┐
│  CLI / Coordination Layer   │  ← System.CommandLine delegates to handlers
├─────────────────────────────┤
│   Business Logic (Handlers) │  ← Pure functions, validation, decision-making
├─────────────────────────────┤
│  Infrastructure (Services)  │  ← JSON schema validation, file I/O
└─────────────────────────────┘

Component Design

1. CLI Layer (Morphir Project)

File: src/Morphir/Program.cs

// Add new IR subcommand
var irCommand = new Command("ir", "Morphir IR operations");

var verifyCommand = new Command("verify", "Verify IR against JSON schema")
{
    filePathArgument,
    schemaVersionOption,
    jsonFormatOption,
    quietOption
};

verifyCommand.SetHandler(async (string filePath, int? version, bool json, bool quiet) =>
{
    // Dispatch to WolverineFx handler via message bus
    var command = new VerifyIR(filePath, version, json, quiet);
    var result = await messageBus.InvokeAsync<VerifyIRResult>(command);

    // Format and display result
    DisplayResult(result, json, quiet);
});

irCommand.AddCommand(verifyCommand);
rootCommand.AddCommand(irCommand);

Responsibilities:

• Parse CLI arguments
• Dispatch commands to WolverineFx message bus
• Format and display results
• Handle exit codes

2. Feature Slice: VerifyIR

File: src/Morphir.Tooling/Features/VerifyIR/VerifyIR.cs

namespace Morphir.Tooling.Features.VerifyIR;

// Command message
public record VerifyIR(
    string FilePath,
    int? SchemaVersion = null,
    bool JsonOutput = false,
    bool Quiet = false
);

// Result type
public record VerifyIRResult(
    bool IsValid,
    string SchemaVersion,
    string DetectionMethod,
    string FilePath,
    List<ValidationError> Errors,
    DateTime Timestamp
);

public record ValidationError(
    string Path,
    string Message,
    object? Expected = null,
    object? Found = null,
    int? Line = null,
    int? Column = null
);

// Handler (pure function)
public static class VerifyIRHandler
{
    public static async Task<VerifyIRResult> Handle(
        VerifyIR command,
        SchemaValidator validator,
        VersionDetector detector,
        CancellationToken ct)
    {
        // 1. Load and parse JSON
        var jsonContent = await File.ReadAllTextAsync(command.FilePath, ct);

        // 2. Detect or use specified version
        var version = command.SchemaVersion?.ToString()
            ?? detector.DetectVersion(jsonContent);

        // 3. Validate against schema
        var validationResult = await validator.ValidateAsync(
            jsonContent,
            version,
            ct);

        // 4. Return pure result (no side effects)
        return new VerifyIRResult(
            IsValid: validationResult.IsValid,
            SchemaVersion: version,
            DetectionMethod: command.SchemaVersion.HasValue ? "manual" : "auto",
            FilePath: command.FilePath,
            Errors: validationResult.Errors,
            Timestamp: DateTime.UtcNow
        );
    }
}

// FluentValidation rules
public class VerifyIRValidator : AbstractValidator<VerifyIR>
{
    public VerifyIRValidator()
    {
        RuleFor(x => x.FilePath)
            .NotEmpty()
            .Must(File.Exists).WithMessage("File does not exist: {PropertyValue}");

        RuleFor(x => x.SchemaVersion)
            .InclusiveBetween(1, 3)
            .When(x => x.SchemaVersion.HasValue)
            .WithMessage("Schema version must be 1, 2, or 3");
    }
}

Responsibilities:

• Define command and result types
• Implement handler as pure function
• Validate command inputs
• Coordinate validation logic

3. Infrastructure: Schema Validation

File: src/Morphir.Tooling/Infrastructure/JsonSchema/SchemaValidator.cs

namespace Morphir.Tooling.Infrastructure.JsonSchema;

using Json.Schema;
using Json.More;

public class SchemaValidator
{
    private readonly SchemaLoader _schemaLoader;

    public async Task<SchemaValidationResult> ValidateAsync(
        string jsonContent,
        string schemaVersion,
        CancellationToken ct)
    {
        // Load schema (cached)
        var schema = await _schemaLoader.LoadSchemaAsync(schemaVersion, ct);

        // Parse JSON
        var jsonDocument = JsonDocument.Parse(jsonContent);

        // Validate using json-everything
        var validationResults = schema.Evaluate(jsonDocument.RootElement);

        // Convert to our error format
        var errors = ConvertToValidationErrors(validationResults);

        return new SchemaValidationResult(
            IsValid: validationResults.IsValid,
            Errors: errors
        );
    }

    private List<ValidationError> ConvertToValidationErrors(
        EvaluationResults results)
    {
        // Transform json-everything errors to our format
        // Include JSON paths, line numbers, etc.
    }
}

File: src/Morphir.Tooling/Infrastructure/JsonSchema/SchemaLoader.cs

public class SchemaLoader
{
    private readonly ConcurrentDictionary<string, JsonSchema> _cache = new();

    public async Task<JsonSchema> LoadSchemaAsync(
        string version,
        CancellationToken ct)
    {
        return _cache.GetOrAdd(version, v =>
        {
            // Load embedded YAML schema
            var resourceName = $"Morphir.Tooling.Infrastructure.Schemas.morphir-ir-v{v}.yaml";
            using var stream = Assembly.GetExecutingAssembly()
                .GetManifestResourceStream(resourceName);

            // Convert YAML to JSON Schema
            var yaml = new StreamReader(stream).ReadToEnd();
            var json = YamlToJson(yaml);
            return JsonSchema.FromText(json);
        });
    }
}

4. Infrastructure: Version Detection

File: src/Morphir.Tooling/Features/DetectVersion/VersionDetector.cs

public class VersionDetector
{
    public string DetectVersion(string jsonContent)
    {
        var doc = JsonDocument.Parse(jsonContent);

        // 1. Check formatVersion field
        if (doc.RootElement.TryGetProperty("formatVersion", out var versionProp))
        {
            return versionProp.GetInt32().ToString();
        }

        // 2. Analyze tag capitalization
        var tags = ExtractTags(doc.RootElement);
        return AnalyzeTagPattern(tags);
    }

    private string AnalyzeTagPattern(List<string> tags)
    {
        var allLowercase = tags.All(t => t == t.ToLowerInvariant());
        var allCapitalized = tags.All(t => char.IsUpper(t[0]));

        if (allLowercase) return "1";
        if (allCapitalized) return "3";
        return "2"; // Mixed
    }
}

WolverineFx Integration

Host Configuration

File: src/Morphir.Tooling/Program.cs

var builder = Host.CreateApplicationBuilder(args);

builder.Services.AddWolverine(opts =>
{
    // Enable in-memory messaging (no external broker needed)
    opts.UseInMemoryTransport();

    // Auto-discover handlers in Features/ directory
    opts.Discovery.IncludeAssembly(typeof(Program).Assembly);
});

// Register infrastructure services
builder.Services.AddSingleton<SchemaLoader>();
builder.Services.AddSingleton<SchemaValidator>();
builder.Services.AddSingleton<VersionDetector>();

var host = builder.Build();
await host.RunAsync();

Message Bus Usage in CLI

// In CLI Program.cs
var host = CreateToolingHost();
var messageBus = host.Services.GetRequiredService<IMessageBus>();

// Dispatch command
var result = await messageBus.InvokeAsync<VerifyIRResult>(
    new VerifyIR(filePath, schemaVersion, jsonOutput, quiet)
);

Dependencies

NuGet Packages:

<!-- Morphir.Tooling.csproj -->
<ItemGroup>
  <!-- WolverineFx -->
  <PackageReference Include="WolverineFx" Version="3.x" />

  <!-- JSON Schema Validation -->
  <PackageReference Include="JsonSchema.Net" Version="7.x" />
  <PackageReference Include="Json.More.Net" Version="4.x" />

  <!-- YAML Support -->
  <PackageReference Include="YamlDotNet" Version="16.x" />

  <!-- Validation -->
  <PackageReference Include="FluentValidation" Version="11.x" />

  <!-- Testing -->
  <PackageReference Include="TUnit" Version="0.x" />
  <PackageReference Include="Reqnroll" Version="2.x" />
  <PackageReference Include="Verify.TUnit" Version="x.x" />
  <PackageReference Include="BenchmarkDotNet" Version="0.x" />
</ItemGroup>

<!-- Embedded Schemas -->
<ItemGroup>
  <EmbeddedResource Include="Infrastructure\Schemas\*.yaml" />
</ItemGroup>

Schema Files:

• Copy from docs/content/docs/spec/schemas/ to src/Morphir.Tooling/Infrastructure/Schemas/
• Embed as resources in assembly

Feature Status Tracking

This table tracks implementation status of all features defined in this PRD:

Status Legend:

• ⏳ Planned: Defined in this PRD, not yet implemented
• 🚧 In Progress: Currently being developed
• ✅ Implemented: Complete and merged
• 📋 Future: Deferred to future work, separate PRD needed

Implementation Phases

Phase 1: Core Verification (MVP)

Goal: Basic validation functionality with excellent UX

Deliverables:

• ✅ WolverineFx host setup in Morphir.Tooling
• ✅ morphir ir verify <file> command
• ✅ Auto-detection of schema versions
• ✅ Manual version override (--schema-version)
• ✅ All three schema versions supported (v1, v2, v3)
• ✅ Human-readable, JSON, and quiet output formats
• ✅ Comprehensive error messages with JSON paths
• ✅ BDD test scenarios (unit + integration)
• ✅ User Documentation:
  • CLI command reference (morphir ir verify)
  • Getting started guide with examples
  • Error message reference
  • JSON output format specification
  • Troubleshooting common issues

Success Criteria:

• All user stories satisfied
• Performance targets met

• 90% code coverage

• Documentation complete and published to docs site
• User can successfully validate IR without external help

Estimated Duration: 2-3 sprints

Phase 2: Extended Input & Detection

Goal: Flexible input options and standalone version detection

Deliverables:

• ⏳ Stdin support for piped input
• ⏳ Multiple file validation
• ⏳ morphir ir detect-version command
• ⏳ Confidence reporting for version detection
• ⏳ Performance optimizations for batch processing
• ⏳ User Documentation Updates:
  • Batch validation guide
  • Stdin/pipe usage examples
  • Version detection command reference
  • Performance best practices
  • CI/CD integration examples

Success Criteria:

• Batch validation performs efficiently
• Version detection accuracy >95%
• Documentation updated with Phase 2 features
• Users can integrate into CI/CD pipelines

Estimated Duration: 1-2 sprints

Phase 3: Advanced Features (Future)

Goal: Directory validation, watch mode, migration tooling

Deliverables:

• 📋 Recursive directory validation
• 📋 Watch mode for continuous validation
• 📋 Migration/upgrade commands (separate PRD)
• 📋 Custom validation rules beyond schema
• 📋 User Documentation Updates:
  • Directory validation workflows
  • Watch mode usage guide
  • Migration command reference
  • Custom validation rules guide
  • Advanced troubleshooting

Success Criteria:

• TBD in future PRD
• Comprehensive documentation for all advanced features

Testing Strategy

Unit Tests

Coverage: All business logic and infrastructure services

Key Test Cases:

• Schema loading and caching
• Version detection algorithm
• JSON path error location
• Command validation rules
• Result formatting

Framework: TUnit with Verify for snapshot testing

BDD Scenarios (Reqnroll)

Feature Files Location: tests/Morphir.Core.Tests/Features/

Comprehensive BDD scenarios are defined in Gherkin syntax in a companion document. See BDD Test Scenarios for the complete specification.

Summary of Feature Files:

• IrSchemaVerification.feature: Core validation scenarios for all schema versions
• IrVersionDetection.feature: Auto-detection and manual version specification
• IrMultiFileVerification.feature: Multiple file and stdin support (Phase 2)
• IrDirectoryVerification.feature: Recursive directory validation (Phase 3)
• IrValidationErrorReporting.feature: Error message quality and actionability

Integration Tests

Test Cases:

• End-to-end CLI command execution
• WolverineFx message bus integration
• Schema file loading from embedded resources
• Error handling for missing files, malformed JSON, etc.

Performance Tests

Benchmarks (using BenchmarkDotNet):

• Schema loading time
• Validation speed by file size
• Memory usage for large files
• Batch processing throughput

Target Metrics:

• Small files (<100KB): <100ms
• Typical files (<1MB): <500ms
• Large files (>1MB): <2s

Success Criteria

Correctness

• ✅ 100% schema compliance detection: No false positives or negatives
• ✅ Accurate version detection: >95% accuracy on real-world IR files
• ✅ Precise error locations: All errors include JSON path and line/column when possible

Performance

• ✅ Fast validation: Meets performance targets (<100ms for small, <500ms for typical)
• ✅ Efficient caching: Schema loading happens once per process
• ✅ Scales to large files: Handles multi-MB IR files without crashing

Usability

• ✅ Clear error messages: Users can fix errors without reading schema docs
• ✅ Flexible output: Supports human, JSON, and quiet formats
• ✅ Good defaults: Auto-detection works for 95%+ of use cases
• ✅ Helpful documentation: CLI help and user guide are comprehensive

Reliability

• ✅ Graceful error handling: Never crashes, always returns actionable error
• ✅ Edge case coverage: Handles empty files, huge files, malformed JSON, etc.
• ✅ Consistent behavior: Same IR file always produces same validation result

Integration

• ✅ Seamless WolverineFx: Messaging layer works transparently
• ✅ Reusable services: Validation logic usable outside CLI
• ✅ Extensible design: Easy to add new features and commands

Testing

• ✅ High coverage: >90% code coverage across unit and integration tests
• ✅ BDD scenarios: All user stories have corresponding feature files
• ✅ Performance benchmarks: Baseline established and tracked over time

Architectural Decisions

ADR-1: Adopt Vertical Slice Architecture

Decision: Organize code by feature/use case rather than technical layers

Rationale:

• Recommended pattern for WolverineFx applications
• Easier to reason about features in isolation
• Better testability with pure function handlers
• Simpler iteration without navigating multiple layers
• Reduced ceremony and abstraction overhead

Alternatives Considered:

• Traditional layered architecture (controllers, services, repositories)
  • Rejected: Too much boilerplate, harder to maintain
• DDD with ports/adapters
  • Rejected: Overkill for CLI tooling, excessive abstraction

Implications:

• New pattern for the codebase (existing code uses layered approach)
• Document pattern for future contributors
• May need to refactor existing features over time

ADR-2: Use json-everything for Schema Validation

Decision: Use the json-everything library suite

Rationale:

• Modern, actively maintained .NET library
• Full JSON Schema Draft 07 support (our schemas use Draft 07)
• Excellent performance and low allocations
• Rich error reporting with JSON Path support
• Already using Json.More.Net in the project

Alternatives Considered:

• NJsonSchema
  • Rejected: Older API, less active development
• Manual validation
  • Rejected: Reinventing the wheel, error-prone

ADR-3: Embed Schema Files as Resources

Decision: Copy YAML schemas from docs and embed in Morphir.Tooling assembly

Rationale:

• Self-contained: No external file dependencies
• Versioned: Schemas ship with the tool
• Fast loading: No file I/O at runtime
• Cacheable: Load once, use many times

Alternatives Considered:

• Read from file system
  • Rejected: Requires deployment of schema files, path resolution issues
• Download from URL
  • Rejected: Network dependency, slower, requires internet access

Implications:

• Schemas must be synced manually from docs when updated
• Assembly size increases slightly (~90KB for 3 YAML files)

ADR-4: Introduce WolverineFx for Messaging

Decision: Use WolverineFx as a message bus between CLI and tooling services

Rationale:

• Decouples CLI UI from business logic
• Enables reuse of handlers in other frontends (API, desktop app, etc.)
• Provides a consistent pattern for future commands
• Built-in support for validation, middleware, side effects

Alternatives Considered:

• Direct method calls from CLI to services
  • Rejected: Tight coupling, harder to test, no reusability
• MediatR
  • Rejected: WolverineFx is more feature-rich and performant

Implications:

• New dependency on WolverineFx
• Requires learning Wolverine patterns
• Sets precedent for all future CLI commands

Dependencies

External Dependencies

NuGet Packages:

• WolverineFx (3.x): Messaging and handler infrastructure
• JsonSchema.Net (7.x): JSON Schema Draft 07 validation
• Json.More.Net (4.x): JSON utilities
• YamlDotNet (16.x): YAML parsing for schema files
• FluentValidation (11.x): Command input validation

Schema Files:

• morphir-ir-v1.yaml (from upstream Morphir repository)
• morphir-ir-v2.yaml (from upstream Morphir repository)
• morphir-ir-v3.yaml (from upstream Morphir repository)

Internal Dependencies

Existing Projects:

• Morphir.Core: May use IR types for deserialization (optional)
• Morphir (CLI): Hosts the ir verify command

New Projects:

• Morphir.Tooling: New project for reusable tooling services

Open Questions

Question 1: Schema Update Process

Q: How do we keep embedded schemas in sync with upstream Morphir repository?

Options:

1. Manual copy-paste when schemas change (low-tech, simple)
2. CI job to auto-fetch latest schemas (automated, more complex)
3. Git submodule to Morphir repo (keeps in sync, adds complexity)

Decision: ✅ Use CI job to auto-fetch latest schemas

Rationale:

• Automated synchronization reduces manual maintenance burden
• CI job can validate schema compatibility before merging
• Can detect upstream schema changes and create PRs automatically
• More maintainable than git submodules for this use case
• Provides audit trail of schema updates through PR history

Implementation Plan:

• Create GitHub Actions workflow to periodically check upstream schemas
• Compare with embedded schemas in src/Morphir.Tooling/Infrastructure/Schemas/
• If changes detected, create a PR with updated schemas
• Include changelog/diff in PR description
• Run validation tests against new schemas before merge

Question 2: Migration Tooling Priority

Q: Should we prioritize migration tooling (v1→v2→v3) alongside verification, or defer it?

Current Plan: Defer to Phase 3+ with separate PRD

Revisit If: Users report high demand for migration during Phase 1 rollout

Question 3: Custom Validation Rules

Q: Should we support custom validation rules beyond JSON schema (e.g., business rules and semantic validation)?

Examples:

• “All public types must have documentation”
• “Module names must follow naming convention”
• “No circular dependencies between modules”
• Type coherence validation
• Dead code detection
• Semantic consistency checks

Decision: ✅ Defer to future PRD, but design for extensibility

Rationale:

• Business rules and semantic validation are valuable but complex
• Schema validation is the foundation that must be solid first
• Custom rules require different validation architecture (AST traversal, semantic analysis)
• Separate concern from structural JSON schema validation

Extensibility Requirements (must be addressed in Phase 1 design):

1. Pluggable Validation Pipeline:

   • Design SchemaValidator with extensibility in mind
   • Allow chaining multiple validators (schema → business rules → semantic)
   • Result aggregation from multiple validation sources

2. Common Validation Result Format:

   • ValidationError type should support both schema and custom rule errors
   • Include error categorization (structural, business, semantic)
   • Support for different severity levels (error, warning, info)

3. IR Deserialization Support:

   • Custom validators will need access to typed IR objects, not just JSON
   • Leverage existing Morphir.Core IR types
   • Support both JSON-level and IR-level validation

4. Vertical Slice for Custom Rules:

   • Future feature slice: Features/ValidateBusinessRules/
   • Can reuse VerifyIR command or introduce new command
   • Follow same VSA pattern for consistency

Future PRD Will Cover:

• Custom validation rule DSL or API
• Semantic validation framework
• Integration with Morphir.Core IR traversal
• Performance considerations for complex validations
• Configuration for enabling/disabling specific rules

Question 4: Watch Mode

Q: Should we implement a watch mode that continuously validates IR files on change?

Use Case: Development workflow where IR is frequently regenerated

Decision: ✅ Include as low-priority feature, design for reusability

Rationale:

• Watch mode is valuable for developer experience during active development
• Not critical for initial release—validation on-demand covers core use cases
• Other future commands will likely benefit from watch mode (e.g., codegen, migration)
• Should be implemented as reusable infrastructure, not command-specific

Priority: Low (Phase 3+, after core validation, multi-file, and directory support)

Design Considerations for Reusability:

1. Shared Watch Infrastructure:

   • Create Infrastructure/FileWatcher/ with reusable file system watching
   • Support glob patterns, ignore patterns, debouncing, and file filters
   • Not tied to any specific command

2. Command-Agnostic Design:

   • Watch mode should be a general CLI capability: morphir <command> --watch
   • Any command can opt-in to watch mode support
   • Example: morphir ir verify --watch src/**/*.json

3. Event-Driven Architecture:

   • Leverage WolverineFx messaging for file change events
   • File watcher publishes FileChanged events to message bus
   • Commands subscribe and handle events asynchronously

4. Graceful Degradation:

   • Watch mode failures shouldn’t crash the CLI
   • Clear status reporting (watching X files, Y changes detected)
   • Ctrl+C handling for clean shutdown

Future Commands That Will Benefit:

• morphir ir verify --watch (validation)
• morphir codegen --watch (code generation on IR changes)
• morphir ir migrate --watch (auto-migrate on changes)
• morphir format --watch (auto-formatting)

Implementation in This PRD:

• Phase 3+ or separate enhancement PRD
• Focus on reusable infrastructure first, then integrate with verify
• Consider FileSystemWatcher (.NET) or libraries like DotNet.Glob + polling

Implementation Notes

This section captures design decisions, deviations, and insights discovered during implementation. Updated in real-time as work progresses.

Phase 1: Core Verification (Current - Started 2025-12-15)

Initial Setup (2025-12-15)

• Task: Created PRD and set up project structure
• Status: ✅ Complete
• Notes:
  • PRD created with comprehensive requirements and BDD scenarios
  • Added PRD management guidance to AGENTS.md for cross-agent collaboration
  • Created PRD index for quick status lookup
  • Ready to begin implementation

Next Steps

• Create Morphir.Tooling project
• Set up WolverineFx host configuration
• Implement VerifyIR feature slice

References

Documentation

• Morphir IR Specification
• Morphir IR JSON Schemas
• Schema v1 Details
• Schema v2 Details
• Schema v3 Details

Libraries

• json-everything GitHub
• JsonSchema.Net Documentation
• WolverineFx Documentation
• Vertical Slice Architecture with Wolverine
• YamlDotNet
• FluentValidation

Related Resources

• Morphir Project
• Morphir Repository
• JSON Schema Specification
• System.CommandLine

Phase 1 Completion Summary

✅ All Deliverables Complete

Implementation (100% Complete):

• ✅ WolverineFx host setup in Morphir.Tooling
• ✅ Vertical Slice Architecture established
• ✅ morphir ir verify <file> command fully functional
• ✅ Auto-detection of schema versions (v1, v2, v3)
• ✅ Manual version override (--schema-version)
• ✅ All three schema versions supported
• ✅ Human-readable output format
• ✅ JSON output format (--json)
• ✅ Quiet mode (--quiet)
• ✅ Comprehensive error messages with JSON paths
• ✅ Enhanced error details (Expected/Found values)
• ✅ Malformed JSON error handling

Testing (100% Complete):

• ✅ 49 unit tests covering all business logic
• ✅ 13 BDD integration tests (end-to-end CLI)
• ✅ 62 tests total, all passing
• ✅ >90% code coverage achieved
• ✅ All error scenarios tested

Documentation (100% Complete):

• ✅ CLI reference documentation (docs/content/docs/cli/)
• ✅ morphir ir verify command reference with examples
• ✅ Getting started guide for validating IR
• ✅ Troubleshooting guide with common issues
• ✅ CI/CD integration examples
• ✅ Error message reference
• ✅ JSON output format specification

Architecture Documentation:

• ✅ Phase 1 patterns documented in AGENTS.md
• ✅ Vertical Slice Architecture patterns
• ✅ WolverineFx integration patterns
• ✅ Testing layer conventions
• ✅ Error handling patterns

📊 Final Metrics

🎯 Success Criteria Achievement

✅ All user stories satisfied

• Story 1: Validate IR File ✅
• Story 2: Validate Specific Schema Version ✅
• Story 3: Machine-Readable Output ✅
• Story 4: Quick Status Check ✅
• Story 5: Detect IR Version (auto-detection implemented) ✅

✅ Performance targets met

• Small files (<100KB): <100ms ✅
• Typical files (<1MB): <500ms ✅
• Large files (>1MB): <2s ✅

✅ >90% code coverage - Achieved ~95%

✅ Documentation complete and published

• CLI reference complete
• Getting started guide complete
• Troubleshooting guide complete
• All examples with CI/CD integration

✅ User can successfully validate IR without external help

• Comprehensive documentation
• Clear error messages
• Multiple output formats

🚀 Key Architectural Decisions

ADR-1: Vertical Slice Architecture

• Implemented successfully
• Features organized by use case
• Handlers are pure functions
• Infrastructure services injected

ADR-2: WolverineFx for Messaging

• Clean separation of CLI and business logic
• Message bus pattern enables testability
• Foundation for future commands

ADR-3: Three-Layer Testing

• Unit tests (isolated components)
• BDD feature tests (business logic)
• Integration tests (end-to-end CLI)
• All layers working harmoniously

📦 Deliverables

Code:

• src/Morphir/ - CLI with System.CommandLine
• src/Morphir.Tooling/ - WolverineFx host and features
• src/Morphir.Tooling/Features/VerifyIR/ - Complete feature slice
• src/Morphir.Tooling/Infrastructure/JsonSchema/ - Schema services
• tests/Morphir.Tooling.Tests/ - Complete test suite

Documentation:

• docs/content/docs/cli/ - CLI reference section
• docs/content/docs/getting-started/validating-ir.md - Quick start
• AGENTS.md - Phase 1 patterns documented
• PRD updated with completion status

Phase 2 Handoff Notes

🎯 Phase 2 Objectives

Primary Goals:

1. Stdin support for piped input
2. Multiple file validation (batch processing)
3. morphir ir detect-version standalone command
4. Confidence reporting for version detection
5. Performance optimizations for batch processing

Documentation:

• Batch validation guide
• Stdin/pipe usage examples
• Version detection command reference
• Performance best practices
• CI/CD integration examples (expanded)

🏗️ Architecture Foundation

Already Established:

• ✅ WolverineFx messaging infrastructure
• ✅ Vertical Slice Architecture pattern
• ✅ Infrastructure services (SchemaLoader, SchemaValidator)
• ✅ Testing infrastructure (unit, BDD, integration)
• ✅ CLI integration pattern with System.CommandLine
• ✅ Documentation structure and patterns

Reusable Components:

• SchemaLoader - Already caches schemas efficiently
• SchemaValidator - Accepts string content (works with stdin)
• VersionDetector - Can be exposed as standalone command
• CliTestHelper - Ready for batch validation tests
• Error handling patterns - Established in Phase 1

📋 Implementation Checklist for Phase 2

1. Stdin Support:

// Extend VerifyIR command
public record VerifyIR(
    string? FilePath = null,  // Make optional
    bool UseStdin = false,    // Add flag
    ...
);

// In CLI Program.cs
if (filePath == "-" || useStdin)
{
    var jsonContent = await Console.In.ReadToEndAsync();
    // Pass to handler
}

2. Multiple File Validation:

// New command
public record VerifyMultipleIR(
    List<string> FilePaths,
    bool StopOnFirstError = false,
    bool Parallel = true,
    ...
);

// Handler returns aggregated results
public record MultipleVerifyIRResult(
    List<VerifyIRResult> Results,
    int TotalFiles,
    int ValidFiles,
    int InvalidFiles
);

3. Standalone detect-version Command:

// New feature slice
// src/Morphir.Tooling/Features/DetectVersion/DetectVersion.cs
public record DetectVersion(string FilePath);

public record DetectVersionResult(
    string DetectedVersion,
    string ConfidenceLevel,  // High, Medium, Low
    string Rationale,
    List<string> Indicators
);

4. Performance Optimizations:

• Schema caching (already implemented) ✅
• Parallel file processing (new)
• Streaming for large files (new)
• Progress reporting for batch operations (new)

🧪 Testing Strategy for Phase 2

Unit Tests to Add:

• Stdin parsing and validation
• Multiple file aggregation logic
• Version detection with confidence levels
• Parallel processing safety

BDD Scenarios to Add:

# Features/VerifyMultipleIR.feature
Scenario: Validate multiple files in batch
  Given I have 10 valid IR files
  When I run "morphir ir verify file1.json file2.json ... file10.json"
  Then all 10 files should be validated
  And the summary should show "10 valid, 0 invalid"

# Features/DetectVersion.feature
Scenario: Detect version with high confidence
  Given a valid IR v3 file with formatVersion field
  When I run "morphir ir detect-version file.json"
  Then the detected version should be "3"
  And the confidence level should be "High"

Integration Tests to Add:

• CLI with stdin input (pipe)
• CLI with multiple file arguments
• CLI with glob patterns
• Parallel processing performance

📚 Documentation Updates for Phase 2

New Documentation:

• docs/content/docs/cli/ir-detect-version.md - New command reference
• docs/content/docs/guides/batch-validation.md - Batch processing guide
• docs/content/docs/guides/ci-cd-integration.md - Expanded CI/CD patterns

Updates to Existing:

• docs/content/docs/cli/ir-verify.md - Add stdin and multiple file examples
• docs/content/docs/cli/troubleshooting.md - Add batch processing issues
• docs/content/docs/getting-started/validating-ir.md - Add advanced scenarios

🔗 Related Work

Dependencies:

• No new package dependencies expected
• All infrastructure already in place

Breaking Changes:

• None anticipated
• Phase 2 is purely additive

Migration Notes:

• No migration needed
• All Phase 1 functionality remains unchanged

📞 Questions for Phase 2

1. Stdin Format: Should stdin accept single file or array of files?
2. Batch Error Handling: Continue on error or stop immediately (configurable)?
3. Progress Reporting: Real-time progress for batch operations?
4. Output Format: How to format multiple file results in JSON/human-readable?
5. Glob Support: Support glob patterns like *.json or use explicit file lists?

🎬 Getting Started with Phase 2

Step 1: Review Phase 1 code

# Familiarize with existing patterns
tree src/Morphir.Tooling/Features/VerifyIR/
cat AGENTS.md  # Section 14: Phase 1 Patterns

Step 2: Create Phase 2 feature branch

git checkout main
git pull origin main
git checkout -b feature/ir-verify-phase2

Step 3: Start with Stdin Support (smallest increment)

# 1. Write failing BDD scenario
# 2. Implement minimal code
# 3. Refactor
# 4. Document

Step 4: Follow TDD cycle strictly (see AGENTS.md Section 9.1)

✅ Phase 1 Handoff Complete

All Phase 1 work is complete, documented, and ready for the next phase or agent to continue.

Changelog:

• 2025-12-13: Initial draft created
• 2025-12-15: Phase 1 completed, Phase 2 handoff notes added

2 - BDD Test Scenarios: IR JSON Schema Verification

BDD Test Scenarios: IR JSON Schema Verification

This document defines comprehensive BDD scenarios using Gherkin syntax for the IR JSON Schema Verification feature. These scenarios will be implemented as Reqnroll feature files in tests/Morphir.Core.Tests/Features/.

Related: IR JSON Schema Verification PRD

Feature 1: IR Schema Verification

Feature File: IrSchemaVerification.feature

Feature: IR Schema Verification
  As a Morphir developer
  I want to validate IR JSON files against schemas
  So that I can catch structural errors early

  Background:
    Given the Morphir CLI is installed
    And the schema files v1, v2, and v3 are available

  Rule: Valid IR files pass validation

    Scenario: Validate a valid v3 IR file
      Given a valid Morphir IR v3 JSON file "valid-v3.json"
      When I run "morphir ir verify valid-v3.json"
      Then the exit code should be 0
      And the output should contain "✓ Validation successful"
      And the output should contain "Schema: v3 (auto-detected)"
      And the output should contain "File: valid-v3.json"

    Scenario: Validate a valid v2 IR file
      Given a valid Morphir IR v2 JSON file "valid-v2.json"
      When I run "morphir ir verify valid-v2.json"
      Then the exit code should be 0
      And the output should contain "✓ Validation successful"
      And the output should contain "Schema: v2 (auto-detected)"

    Scenario: Validate a valid v1 IR file
      Given a valid Morphir IR v1 JSON file "valid-v1.json"
      When I run "morphir ir verify valid-v1.json"
      Then the exit code should be 0
      And the output should contain "✓ Validation successful"
      And the output should contain "Schema: v1 (auto-detected)"

    Scenario Outline: Validate various valid IR files across versions
      Given a valid Morphir IR <version> JSON file "<filename>"
      When I run "morphir ir verify <filename>"
      Then the exit code should be 0
      And the output should contain "✓ Validation successful"
      And the output should contain "Schema: <version> (auto-detected)"

      Examples:
        | version | filename              |
        | v1      | library-v1.json       |
        | v1      | complex-types-v1.json |
        | v2      | library-v2.json       |
        | v2      | complex-types-v2.json |
        | v3      | library-v3.json       |
        | v3      | complex-types-v3.json |

  Rule: Invalid IR files fail validation with clear errors

    Scenario: Validate an IR file with incorrect tag capitalization
      Given an invalid Morphir IR v3 JSON file "invalid-tags.json" with lowercase tags
      When I run "morphir ir verify invalid-tags.json"
      Then the exit code should be 1
      And the output should contain "✗ Validation failed"
      And the output should contain "Invalid type tag"
      And the output should contain "Expected: \"Public\" or \"Private\""
      And the output should contain "Found: \"public\""

    Scenario: Validate an IR file with missing required fields
      Given an invalid Morphir IR v3 JSON file "missing-fields.json" missing the "name" field
      When I run "morphir ir verify missing-fields.json"
      Then the exit code should be 1
      And the output should contain "✗ Validation failed"
      And the output should contain "Missing required field"
      And the output should contain "Path: $.package.modules"
      And the output should contain "Required property 'name' is missing"

    Scenario: Validate an IR file with invalid type structure
      Given an invalid Morphir IR v3 JSON file "invalid-structure.json" with malformed type definitions
      When I run "morphir ir verify invalid-structure.json"
      Then the exit code should be 1
      And the output should contain "✗ Validation failed"
      And the error count should be greater than 0

    Scenario: Validate an IR file with multiple errors
      Given an invalid Morphir IR v3 JSON file "multiple-errors.json" with 5 validation errors
      When I run "morphir ir verify multiple-errors.json"
      Then the exit code should be 1
      And the output should contain "5 errors found"
      And the output should list all 5 errors with JSON paths

  Rule: Schema version can be manually specified

    Scenario: Force validation against specific schema version
      Given a Morphir IR JSON file "mixed-version.json"
      When I run "morphir ir verify --schema-version 2 mixed-version.json"
      Then the validation should use schema v2
      And the output should contain "Schema: v2 (manual)"

    Scenario: Override auto-detection with explicit version
      Given a valid Morphir IR v3 JSON file "valid-v3.json"
      When I run "morphir ir verify --schema-version 3 valid-v3.json"
      Then the exit code should be 0
      And the output should contain "Schema: v3 (manual)"

    Scenario: Validate v2 file against v3 schema (should fail)
      Given a valid Morphir IR v2 JSON file "valid-v2.json"
      When I run "morphir ir verify --schema-version 3 valid-v2.json"
      Then the exit code should be 1
      And the output should contain "✗ Validation failed against schema v3"

    Scenario Outline: Validate with explicit version specification
      Given a valid Morphir IR <actual-version> JSON file "<filename>"
      When I run "morphir ir verify --schema-version <specified-version> <filename>"
      Then the exit code should be <exit-code>
      And the output should contain "Schema: <specified-version> (manual)"

      Examples:
        | filename        | actual-version | specified-version | exit-code |
        | valid-v1.json   | v1             | 1                 | 0         |
        | valid-v2.json   | v2             | 2                 | 0         |
        | valid-v3.json   | v3             | 3                 | 0         |
        | valid-v1.json   | v1             | 3                 | 1         |
        | valid-v2.json   | v2             | 1                 | 1         |

  Rule: Multiple output formats are supported

    Scenario: Output validation results as JSON
      Given an invalid Morphir IR JSON file "errors.json"
      When I run "morphir ir verify --json errors.json"
      Then the output should be valid JSON
      And the JSON should have field "valid" with value false
      And the JSON should have field "errors" as an array
      And each error should include "path", "message", "expected", and "found"

    Scenario: Output successful validation as JSON
      Given a valid Morphir IR v3 JSON file "valid-v3.json"
      When I run "morphir ir verify --json valid-v3.json"
      Then the output should be valid JSON
      And the JSON should have field "valid" with value true
      And the JSON should have field "schemaVersion" with value "3"
      And the JSON should have field "detectionMethod" with value "auto"
      And the JSON should have field "errorCount" with value 0

    Scenario: Quiet mode suppresses success messages
      Given a valid Morphir IR v3 JSON file "valid-v3.json"
      When I run "morphir ir verify --quiet valid-v3.json"
      Then the exit code should be 0
      And the output should be empty

    Scenario: Quiet mode shows only errors
      Given an invalid Morphir IR v3 JSON file "invalid-tags.json"
      When I run "morphir ir verify --quiet invalid-tags.json"
      Then the exit code should be 1
      And the output should contain error messages
      And the output should not contain "✗ Validation failed"
      And the output should not contain headers or decorations

    Scenario: Verbose mode shows detailed information
      Given a valid Morphir IR v3 JSON file "valid-v3.json"
      When I run "morphir ir verify --verbose valid-v3.json"
      Then the exit code should be 0
      And the output should contain "✓ Validation successful"
      And the output should contain "Schema: v3 (auto-detected)"
      And the output should contain "File: valid-v3.json"
      And the output should contain validation timestamp
      And the output should contain schema file path

  Rule: Error messages are clear and actionable

    Scenario: Error message includes JSON path
      Given an invalid Morphir IR v3 JSON file "bad-path.json" with error at "$.modules[0].types.MyType"
      When I run "morphir ir verify bad-path.json"
      Then the exit code should be 1
      And the output should contain "Path: $.modules[0].types.MyType"

    Scenario: Error message includes line and column numbers
      Given an invalid Morphir IR v3 JSON file "line-col-error.json" with error at line 42, column 12
      When I run "morphir ir verify line-col-error.json"
      Then the exit code should be 1
      And the output should contain "Line: 42, Column: 12"

    Scenario: Error message suggests fixes
      Given an invalid Morphir IR v3 JSON file "lowercase-tag.json" with lowercase "public" tag
      When I run "morphir ir verify lowercase-tag.json"
      Then the exit code should be 1
      And the output should contain 'Suggestion: Change "public" to "Public"'

  Rule: Edge cases and error handling

    Scenario: File not found
      When I run "morphir ir verify non-existent-file.json"
      Then the exit code should be 2
      And the output should contain "File not found: non-existent-file.json"

    Scenario: Malformed JSON
      Given a file "malformed.json" with invalid JSON syntax
      When I run "morphir ir verify malformed.json"
      Then the exit code should be 2
      And the output should contain "Invalid JSON"
      And the output should contain the JSON parsing error location

    Scenario: Empty file
      Given an empty file "empty.json"
      When I run "morphir ir verify empty.json"
      Then the exit code should be 2
      And the output should contain "File is empty"

    Scenario: Very large file
      Given a valid Morphir IR v3 JSON file "large-10mb.json" of size 10MB
      When I run "morphir ir verify large-10mb.json"
      Then the validation should complete within 2 seconds
      And the exit code should be 0

    Scenario: Invalid schema version specified
      Given a valid Morphir IR v3 JSON file "valid-v3.json"
      When I run "morphir ir verify --schema-version 5 valid-v3.json"
      Then the exit code should be 2
      And the output should contain "Schema version must be 1, 2, or 3"

    Scenario: File with invalid UTF-8 encoding
      Given a file "invalid-utf8.json" with invalid UTF-8 bytes
      When I run "morphir ir verify invalid-utf8.json"
      Then the exit code should be 2
      And the output should contain "Invalid file encoding"

Feature 2: Version Detection

Feature File: IrVersionDetection.feature

Feature: IR Version Detection
  As a Morphir developer
  I want to automatically detect which schema version my IR uses
  So that I can validate against the correct schema

  Background:
    Given the Morphir CLI is installed
    And the schema files v1, v2, and v3 are available

  Rule: Auto-detection works for files with formatVersion field

    Scenario: Detect version from formatVersion field (v3)
      Given a Morphir IR JSON file "with-format-v3.json" containing "formatVersion": 3
      When I run "morphir ir verify with-format-v3.json"
      Then the validation should use schema v3
      And the output should contain "Schema: v3 (auto-detected)"

    Scenario Outline: Detect version from formatVersion field
      Given a Morphir IR JSON file "<filename>" containing "formatVersion": <version>
      When I run "morphir ir verify <filename>"
      Then the validation should use schema v<version>
      And the output should contain "Schema: v<version> (auto-detected)"

      Examples:
        | filename        | version |
        | format-v1.json  | 1       |
        | format-v2.json  | 2       |
        | format-v3.json  | 3       |

  Rule: Auto-detection uses tag capitalization when formatVersion is absent

    Scenario: Detect v1 from lowercase tags
      Given a Morphir IR JSON file "no-format-v1.json" without formatVersion
      And the file uses all lowercase tags like "library", "public", "apply"
      When I run "morphir ir verify no-format-v1.json"
      Then the validation should use schema v1
      And the output should contain "Schema: v1 (auto-detected)"

    Scenario: Detect v3 from capitalized tags
      Given a Morphir IR JSON file "no-format-v3.json" without formatVersion
      And the file uses all capitalized tags like "Library", "Public", "Apply"
      When I run "morphir ir verify no-format-v3.json"
      Then the validation should use schema v3
      And the output should contain "Schema: v3 (auto-detected)"

    Scenario: Detect v2 from mixed capitalization
      Given a Morphir IR JSON file "no-format-v2.json" without formatVersion
      And the file uses mixed case tags
      When I run "morphir ir verify no-format-v2.json"
      Then the validation should use schema v2
      And the output should contain "Schema: v2 (auto-detected)"

  Rule: Standalone version detection command

    Scenario: Detect version with dedicated command
      Given a Morphir IR JSON file "detect-me.json" with v3 structure
      When I run "morphir ir detect-version detect-me.json"
      Then the exit code should be 0
      And the output should contain "Detected schema version: v3"
      And the output should contain "Confidence: High"
      And the output should contain "Rationale:"

    Scenario: Version detection shows rationale
      Given a Morphir IR JSON file "v3-with-format.json" containing "formatVersion": 3
      When I run "morphir ir detect-version v3-with-format.json"
      Then the output should contain "Contains formatVersion: 3"

    Scenario: Version detection analyzes tag patterns
      Given a Morphir IR JSON file "v3-no-format.json" without formatVersion but with capitalized tags
      When I run "morphir ir detect-version v3-no-format.json"
      Then the output should contain 'All tags are capitalized ("Library", "Public", "Apply")'

    Scenario Outline: Detect version with varying confidence levels
      Given a Morphir IR JSON file "<filename>" with <indicators>
      When I run "morphir ir detect-version <filename>"
      Then the output should contain "Confidence: <confidence>"

      Examples:
        | filename            | indicators                    | confidence |
        | clear-v3.json       | formatVersion and cap tags    | High       |
        | likely-v1.json      | lowercase tags only           | Medium     |
        | ambiguous.json      | minimal structure             | Low        |

Feature 3: Multiple File Support (Phase 2)

Feature File: IrMultiFileVerification.feature

Feature: Multiple File Verification
  As a Morphir developer working with multiple IR files
  I want to validate several files at once
  So that I can efficiently verify my entire project

  Background:
    Given the Morphir CLI is installed with Phase 2 features

  Rule: Multiple files can be validated in one command

    Scenario: Validate two valid files
      Given valid IR files "file1.json" and "file2.json"
      When I run "morphir ir verify file1.json file2.json"
      Then the exit code should be 0
      And the output should show results for "file1.json"
      And the output should show results for "file2.json"
      And both files should pass validation

    Scenario: Validate mix of valid and invalid files
      Given a valid IR file "valid.json"
      And an invalid IR file "invalid.json"
      When I run "morphir ir verify valid.json invalid.json"
      Then the exit code should be 1
      And the output should show "valid.json" passed
      And the output should show "invalid.json" failed with errors

    Scenario: Validate multiple files with summary
      Given 10 valid IR files
      And 3 invalid IR files
      When I run "morphir ir verify *.json"
      Then the exit code should be 1
      And the output should contain "Summary: 10 passed, 3 failed"

  Rule: Stdin support for piped input

    Scenario: Validate IR from stdin
      Given a valid Morphir IR v3 JSON file "valid-v3.json"
      When I run "cat valid-v3.json | morphir ir verify -"
      Then the exit code should be 0
      And the output should contain "✓ Validation successful"
      And the output should contain "Source: stdin"

    Scenario: Validate invalid IR from stdin
      Given an invalid Morphir IR JSON file "invalid.json"
      When I run "cat invalid.json | morphir ir verify -"
      Then the exit code should be 1
      And the output should contain "✗ Validation failed"

    Scenario: Combine file and stdin (stdin represented as -)
      Given a valid IR file "file.json"
      And valid IR JSON content in stdin
      When I run "cat stdin.json | morphir ir verify file.json -"
      Then the exit code should be 0
      And the output should show results for "file.json"
      And the output should show results for "stdin"

  Rule: Batch processing is efficient

    Scenario: Validate 100 files efficiently
      Given 100 valid IR files in "batch/" directory
      When I run "morphir ir verify batch/*.json"
      Then the validation should complete within 10 seconds
      And the exit code should be 0
      And the output should contain "Summary: 100 passed, 0 failed"

    Scenario: Stop on first error (--fail-fast option)
      Given 5 valid IR files and 1 invalid IR file
      When I run "morphir ir verify --fail-fast *.json"
      Then the validation should stop at the first error
      And the exit code should be 1
      And not all files should be processed

Feature 4: Directory Validation (Phase 3)

Feature File: IrDirectoryVerification.feature

Feature: Directory Verification
  As a Morphir developer with many IR files
  I want to validate entire directories
  So that I can ensure all my IR files are correct

  Background:
    Given the Morphir CLI is installed with Phase 3 features

  Rule: Directories can be validated recursively

    Scenario: Validate all JSON files in directory
      Given a directory "ir-files/" with 5 valid IR JSON files
      When I run "morphir ir verify --recursive ir-files/"
      Then the exit code should be 0
      And all 5 files should be validated
      And the output should contain "5 files validated, 5 passed"

    Scenario: Validate directory with mixed results
      Given a directory "mixed/" with 3 valid and 2 invalid IR files
      When I run "morphir ir verify --recursive mixed/"
      Then the exit code should be 1
      And the output should contain "5 files validated, 3 passed, 2 failed"

    Scenario: Skip non-JSON files in directory
      Given a directory "mixed-types/" with JSON and non-JSON files
      When I run "morphir ir verify --recursive mixed-types/"
      Then only JSON files should be validated
      And the output should list which files were skipped

    Scenario: Validate nested directory structure
      Given a nested directory structure:
        """
        project/
        ├── src/
        │   ├── module1/
        │   │   └── ir.json
        │   └── module2/
        │       └── ir.json
        └── tests/
            └── fixtures/
                └── ir.json
        """
      When I run "morphir ir verify --recursive project/"
      Then all 3 IR files should be validated
      And the output should show the relative paths of all files

  Rule: Directory validation supports filtering

    Scenario: Validate only specific file patterns
      Given a directory with various JSON files
      When I run "morphir ir verify --recursive --pattern 'morphir-*.json' dir/"
      Then only files matching "morphir-*.json" should be validated

    Scenario: Exclude specific directories
      Given a directory structure with "node_modules/" and "src/"
      When I run "morphir ir verify --recursive --exclude 'node_modules' ."
      Then files in "node_modules/" should be skipped
      And files in "src/" should be validated

Feature 5: Error Reporting Quality

Feature File: IrValidationErrorReporting.feature

Feature: Validation Error Reporting
  As a Morphir developer fixing validation errors
  I want detailed, actionable error messages
  So that I can quickly identify and fix issues

  Background:
    Given the Morphir CLI is installed

  Rule: Errors include precise location information

    Scenario: Error with JSON path
      Given an IR file "error.json" with invalid value at "$.modules[0].types.MyType.accessControlled[0]"
      When I run "morphir ir verify error.json"
      Then the output should contain the exact JSON path
      And the path should be formatted as "$.modules[0].types.MyType.accessControlled[0]"

    Scenario: Error with line and column numbers
      Given an IR file "error.json" with syntax error at line 42, column 12
      When I run "morphir ir verify error.json"
      Then the output should contain "Line: 42, Column: 12"

    Scenario: Error shows context snippet
      Given an IR file with error at line 42
      When I run "morphir ir verify --verbose error.json"
      Then the output should include a code snippet around line 42
      And the error line should be highlighted

  Rule: Errors explain what was expected vs found

    Scenario: Type mismatch error
      Given an IR file with string where number is expected
      When I run "morphir ir verify error.json"
      Then the output should contain "Expected: number"
      And the output should contain 'Found: "some string"'

    Scenario: Enum value error
      Given an IR file with invalid access control tag
      When I run "morphir ir verify error.json"
      Then the output should contain 'Expected: One of ["Public", "Private"]'
      And the output should contain 'Found: "public"'

    Scenario: Array length constraint error
      Given an IR file with array that violates length constraints
      When I run "morphir ir verify error.json"
      Then the output should contain "Expected: Array with 2 elements"
      And the output should contain "Found: Array with 3 elements"

  Rule: Errors provide helpful suggestions

    Scenario: Suggest capitalization fix
      Given an IR file with lowercase tag in v3 IR
      When I run "morphir ir verify error.json"
      Then the output should contain 'Suggestion: Change "public" to "Public"'

    Scenario: Suggest adding missing field
      Given an IR file missing required "name" field
      When I run "morphir ir verify error.json"
      Then the output should contain 'Suggestion: Add required field "name"'

    Scenario: Suggest similar field names for typos
      Given an IR file with "nmae" instead of "name"
      When I run "morphir ir verify error.json"
      Then the output should contain 'Did you mean "name"?'

  Rule: Multiple errors are clearly enumerated

    Scenario: List multiple errors with numbering
      Given an IR file with 3 validation errors
      When I run "morphir ir verify error.json"
      Then the output should contain "Error 1:"
      And the output should contain "Error 2:"
      And the output should contain "Error 3:"
      And the output should contain "3 errors found"

    Scenario: Group errors by category
      Given an IR file with type errors and missing field errors
      When I run "morphir ir verify error.json"
      Then errors should be grouped by type
      And the output should show "Type Errors (2)" and "Missing Fields (3)"

    Scenario: Limit error display with --max-errors option
      Given an IR file with 50 validation errors
      When I run "morphir ir verify --max-errors 10 error.json"
      Then only the first 10 errors should be displayed
      And the output should contain "... and 40 more errors"

  Rule: Error output is machine-readable in JSON mode

    Scenario: JSON error format includes all details
      Given an IR file with validation errors
      When I run "morphir ir verify --json error.json"
      Then the JSON output should include:
        | field           | description                    |
        | valid           | false                          |
        | errors          | Array of error objects         |
        | errors[].path   | JSON path to error             |
        | errors[].line   | Line number                    |
        | errors[].column | Column number                  |
        | errors[].message| Human-readable error message   |
        | errors[].code   | Machine-readable error code    |

    Scenario: Error codes are consistent and documented
      Given an IR file with a missing required field
      When I run "morphir ir verify --json error.json"
      Then the error should have code "MISSING_REQUIRED_FIELD"
      And the error code should be documented

Feature 6: Performance and Scalability

Feature File: IrValidationPerformance.feature

Feature: Validation Performance
  As a developer integrating validation in CI/CD
  I want fast validation even for large files
  So that builds remain efficient

  Background:
    Given the Morphir CLI is installed

  Rule: Validation meets performance targets

    Scenario Outline: Validate files of varying sizes
      Given a valid Morphir IR v3 JSON file of size <size>
      When I run "morphir ir verify <filename>"
      Then the validation should complete within <max-time>
      And the exit code should be 0

      Examples:
        | size   | filename        | max-time |
        | 10KB   | small.json      | 100ms    |
        | 100KB  | medium.json     | 100ms    |
        | 1MB    | large.json      | 500ms    |
        | 10MB   | very-large.json | 2000ms   |

    Scenario: Schema caching improves performance
      Given 10 valid IR files
      When I run "morphir ir verify file1.json ... file10.json"
      Then schemas should only be loaded once
      And subsequent validations should be faster

    Scenario: Memory usage remains bounded
      Given a 50MB IR file
      When I run "morphir ir verify huge.json"
      Then memory usage should not exceed 500MB
      And validation should complete successfully

  Rule: Validation supports progress reporting

    Scenario: Show progress for multiple files
      Given 100 IR files to validate
      When I run "morphir ir verify --progress *.json"
      Then the output should show a progress indicator
      And the progress should update as files are validated

    Scenario: Show progress for large single file
      Given a 10MB IR file
      When I run "morphir ir verify --progress large.json"
      Then the output should show validation progress

Implementation Notes

Step Definition Organization

Step definitions should be organized in the following files within tests/Morphir.Core.Tests/StepDefinitions/:

• IrVerificationSteps.cs: Common steps for file setup, CLI execution, output assertions
• IrSchemaSteps.cs: Steps specific to schema validation
• IrVersionDetectionSteps.cs: Steps for version detection scenarios
• IrFileManagementSteps.cs: Steps for file and directory operations

Test Data Strategy

Test IR JSON files should be stored in tests/Morphir.Core.Tests/TestData/IrFiles/:

TestData/
└── IrFiles/
    ├── v1/
    │   ├── valid/
    │   │   ├── library-v1.json
    │   │   └── complex-types-v1.json
    │   └── invalid/
    │       ├── invalid-tags-v1.json
    │       └── missing-fields-v1.json
    ├── v2/
    │   ├── valid/
    │   └── invalid/
    └── v3/
        ├── valid/
        └── invalid/

Continuous Integration

These BDD scenarios should run:

• On every pull request
• On merge to main branch
• As part of the release validation process

Target: All scenarios pass with >95% reliability.

Last Updated: 2025-12-13

3 - PRD: Product Manager Skill for Morphir Ecosystem

Product Requirements Document: Product Manager Skill for Morphir Ecosystem

Status: 📋 Draft Created: 2025-12-18 Last Updated: 2025-12-18 Current Phase: Phase 1 - Planning and Design Author: Morphir .NET Team Related Issue: #228

Overview

This PRD defines requirements for creating a specialized Product Manager skill for AI coding agents. This skill will provide comprehensive product management capabilities tailored to the Morphir ecosystem across all FINOS Morphir repositories, helping users create better PRDs, craft meaningful issues, understand the ecosystem, and make product decisions aligned with Morphir’s philosophy.

Problem Statement

Currently, contributors working across the Morphir ecosystem face several challenges:

1. Fragmented Knowledge: Morphir spans multiple repositories (morphir-elm, morphir-jvm, morphir-scala, morphir-dotnet, etc.) with varying maturity levels, features, and conventions
2. Inconsistent Issue Quality: Issues and PRs often lack context, proper categorization, or alignment with project goals
3. PRD Gaps: Not all features have comprehensive PRDs, and creating high-quality PRDs requires deep Morphir knowledge
4. Cross-Repo Blind Spots: Contributors may duplicate work or miss opportunities for cross-repository synergies
5. UX/DX Debt: User experience and developer experience improvements need dedicated advocacy
6. Manual Ecosystem Tracking: No automated way to track trends, backlogs, or health metrics across the ecosystem

Current Pain Points

• New contributors struggle to understand where to contribute and how to write good issues
• Maintainers spend time triaging poorly-written issues and PRs
• Product decisions lack ecosystem-wide context and may not align with Morphir’s functional modeling philosophy
• Documentation gaps make it hard to understand feature status across implementations
• Backlog management is manual and repository-siloed

Goals

Primary Goals

1. Expert PRD Guidance: Help users create comprehensive, well-structured PRDs aligned with Morphir principles
2. Issue Quality Improvement: Assist in crafting high-quality issues (bugs, features, enhancements) with proper context
3. Ecosystem Intelligence: Provide real-time awareness of backlogs, trends, and status across all Morphir repositories
4. UX/DX Advocacy: Champion user and developer experience improvements
5. Intelligent Questioning: Push back constructively on features that don’t align with Morphir’s ethos
6. GitHub Automation: Provide F# scripts for querying, analyzing, and reporting across the ecosystem

Secondary Goals

7. Cross-Skill Integration: Coordinate effectively with qa-tester and release-manager skills
8. Knowledge Management: Maintain and share institutional knowledge about Morphir
9. Template Library: Provide reusable templates for common product management tasks
10. Metrics & Analytics: Track and report ecosystem health metrics

Non-Goals

Explicitly Out of Scope

• Code Implementation: Development agents handle implementation
• Test Execution: qa-tester skill handles testing
• Release Management: release-manager skill handles releases
• Direct Repository Modifications: Should create PRs/issues instead of direct changes
• Automated Merging: Requires human review and approval
• External Product Management: Focus is on Morphir ecosystem only

User Stories

Story 1: Create a Comprehensive PRD

As a feature owner I want to create a comprehensive PRD with AI assistance So that my feature is well-specified and aligns with Morphir principles

Acceptance Criteria:

• User requests help creating a PRD for a feature
• Product Manager asks clarifying questions about goals, scope, users
• Product Manager generates PRD using template with all sections filled
• PRD references existing Morphir patterns and architecture
• PRD includes feature tracking table and implementation phases
• Product Manager validates alignment with Morphir philosophy

Story 2: Craft a High-Quality Issue

As a contributor I want to create a well-structured issue So that maintainers can quickly understand and prioritize it

Acceptance Criteria:

• User describes a bug, feature, or enhancement idea
• Product Manager asks clarifying questions
• Product Manager helps categorize and label appropriately
• Product Manager suggests related issues across repositories
• Product Manager generates issue description with proper formatting
• Issue includes references to relevant documentation and code

Story 3: Ecosystem Trend Analysis

As a maintainer I want to understand what’s trending across the Morphir ecosystem So that I can align my repository’s priorities with ecosystem needs

Acceptance Criteria:

• User requests ecosystem analysis
• Product Manager runs trend-analysis.fsx script
• Product Manager reports most active labels, common themes
• Product Manager identifies cross-repository patterns
• Product Manager suggests areas needing attention
• Report includes links to relevant issues and discussions

Story 4: Backlog Health Check

As a project lead I want to assess the health of my backlog So that I can prioritize triage and cleanup efforts

Acceptance Criteria:

• User requests backlog analysis
• Product Manager runs analyze-backlog.fsx script
• Product Manager reports backlog metrics (age, staleness, priority distribution)
• Product Manager identifies stale issues needing attention
• Product Manager suggests triage priorities
• Product Manager compares against ecosystem averages

Story 5: Cross-Repository Issue Search

As a developer I want to find related issues across all Morphir repositories So that I don’t duplicate work and can learn from other implementations

Acceptance Criteria:

• User describes a feature or issue
• Product Manager runs query-issues.fsx across all finos/morphir-* repos
• Product Manager presents related issues with context
• Product Manager highlights implementation differences
• Product Manager suggests collaboration opportunities
• Results link to original issues

Story 6: Feature Alignment Validation

As a contributor I want to validate that my feature idea aligns with Morphir’s philosophy So that I don’t waste effort on something that won’t be accepted

Acceptance Criteria:

• User proposes a feature idea
• Product Manager asks probing questions about motivation, alternatives
• Product Manager evaluates alignment with Morphir principles (functional, type-driven, domain modeling)
• Product Manager provides constructive feedback
• Product Manager suggests modifications or alternatives if misaligned
• Product Manager references similar features in other repos

Detailed Requirements

Functional Requirements

FR-1: PRD Creation and Guidance

Capabilities:

• Generate PRDs from template with all required sections
• Ask clarifying questions to fill in gaps
• Validate PRD completeness and quality
• Reference existing PRDs for consistency
• Ensure alignment with Morphir architecture
• Include feature status tracking tables
• Suggest implementation phases

Templates:

• Standard feature PRD
• Architecture change PRD
• Breaking change PRD
• Cross-repository PRD

Validation Checklist:

• Problem statement clearly defined
• Goals and non-goals explicit
• User stories with acceptance criteria
• Technical design outlined
• Testing strategy included
• Success criteria measurable
• References to Morphir docs/architecture
• Feature tracking table included

FR-2: Issue Creation and Enhancement

Capabilities:

• Help craft feature requests
• Help write bug reports
• Help create enhancement proposals
• Suggest appropriate labels and milestones
• Cross-reference related issues
• Validate issue completeness

Issue Templates:

• Feature request
• Bug report
• Enhancement proposal
• Documentation improvement
• Performance issue

Quality Checklist:

• Clear, descriptive title
• Problem/motivation explained
• Expected vs actual behavior (for bugs)
• Steps to reproduce (for bugs)
• Proposed solution or alternatives
• Impact assessment
• Links to related issues/docs
• Appropriate labels

FR-3: Ecosystem Intelligence

Data Sources:

• finos/morphir (core specs and schemas)
• finos/morphir-elm (reference implementation)
• finos/morphir-jvm (JVM implementation)
• finos/morphir-scala (Scala implementation)
• finos/morphir-dotnet (this repository)
• finos/morphir-examples (examples and docs)

Intelligence Capabilities:

• Query issues across all repositories
• Track trending topics and labels
• Identify common pain points
• Monitor release cadences
• Compare feature parity
• Detect cross-repository dependencies

Metrics Tracked:

• Issue velocity (opened, closed, avg time to close)
• Backlog health (age distribution, staleness)
• Label distribution and trends
• Contributor activity
• Documentation coverage
• Test coverage trends

FR-4: GitHub Automation Scripts (F#)

Script: query-issues.fsx

// Query issues across Morphir repositories
// Usage: dotnet fsi query-issues.fsx --label "enhancement" --state "open" --repos "all"
// Output: JSON, Markdown, or formatted table

Features:

• Multi-repository queries (all finos/morphir-* repos)
• Filter by label, state, milestone, assignee, author
• Sort by created, updated, comments, reactions
• Format output as JSON, Markdown, or table
• Cache results for performance

Script: analyze-backlog.fsx

// Analyze backlog health metrics
// Usage: dotnet fsi analyze-backlog.fsx --repo "finos/morphir-dotnet"
// Output: Health report with metrics and recommendations

Features:

• Calculate backlog age distribution
• Identify stale issues (no activity in 90+ days)
• Analyze priority distribution
• Compare against ecosystem averages
• Generate recommendations for triage

Script: trend-analysis.fsx

// Identify trending topics across ecosystem
// Usage: dotnet fsi trend-analysis.fsx --since "30 days ago"
// Output: Trend report with top labels, themes, activity

Features:

• Most active labels in time period
• Emerging themes from issue titles/descriptions
• Spike detection (unusual activity)
• Cross-repository correlation
• Sentiment analysis (positive/negative)

Script: check-ecosystem.fsx

// Check status across all Morphir repositories
// Usage: dotnet fsi check-ecosystem.fsx
// Output: Ecosystem health dashboard

Features:

• Latest release versions
• CI/CD status
• Open PR counts
• Recent activity summary
• Documentation status
• Test coverage (if available)

Script: generate-prd.fsx

// Generate PRD from template with interactive prompts
// Usage: dotnet fsi generate-prd.fsx --template "standard"
// Output: PRD markdown file

Features:

• Interactive questionnaire for PRD sections
• Pre-fill from existing issues or discussions
• Validate completeness
• Preview before saving
• Save to docs/content/contributing/design/prds/

FR-5: Integration with Other Skills

With qa-tester:

• Coordinate on acceptance criteria definition
• Align test plans with PRD requirements
• Validate feature completeness against PRD
• Review test coverage for PRD features

With release-manager:

• Align features with release roadmap
• Coordinate changelog entries
• Review “What’s New” documentation
• Prioritize features for releases

With development agents:

• Provide clear requirements and context
• Answer questions during implementation
• Validate implementation against PRD
• Document design decisions in PRD

FR-6: Knowledge Management

Morphir Core Concepts:

• Functional modeling approach
• Type-driven development
• Business domain modeling
• Distribution and intermediate representation
• Cross-language support strategy

Architecture Patterns:

• Vertical Slice Architecture
• Railway-oriented programming
• ADT-first design
• Immutability and pure functions
• Effect management at boundaries

Decision-Making Framework:

• IR fidelity over convenience
• Minimize dependencies
• Performance requires benchmarks
• Keep effects at edges
• Prefer explicit ADTs

Non-Functional Requirements

NFR-1: Response Time

• Script execution < 30 seconds for single-repo queries
• Script execution < 2 minutes for ecosystem-wide queries
• PRD generation interactive (responds to each question in < 5 seconds)

NFR-2: Accuracy

• Cross-repository queries return 100% accurate results
• Trend analysis validated against manual review (>95% agreement)
• Issue recommendations relevant (>80% user acceptance)

NFR-3: Maintainability

• Scripts use GitHub CLI (gh) for authentication
• Scripts use standard F# libraries (no exotic dependencies)
• Scripts include help text and examples
• Scripts handle rate limiting gracefully

NFR-4: Usability

• Clear, conversational interaction style
• Asks clarifying questions before making assumptions
• Provides rationale for recommendations
• Offers alternatives when pushing back
• Links to relevant documentation

NFR-5: Documentation

• Comprehensive skill.md with all capabilities
• README with quick start guide
• Script documentation with usage examples
• Template documentation with instructions
• Integration guide for other skills

Technical Design

Skill Structure

.claude/skills/product-manager/
├── skill.md                          # Main skill definition and playbooks
├── README.md                         # Quick start and overview
├── scripts/                          # F# automation scripts
│   ├── query-issues.fsx              # Multi-repo issue queries
│   ├── analyze-backlog.fsx           # Backlog health analysis
│   ├── trend-analysis.fsx            # Trend detection and reporting
│   ├── check-ecosystem.fsx           # Ecosystem status dashboard
│   ├── generate-prd.fsx              # Interactive PRD generation
│   ├── update-knowledge.fsx          # Update knowledgebase from live sources
│   └── common/                       # Shared utilities
│       ├── github-api.fsx            # GitHub API helpers
│       ├── formatting.fsx            # Output formatting
│       └── cache.fsx                 # Result caching
├── templates/                        # Document templates
│   ├── prd-standard.md               # Standard feature PRD
│   ├── prd-architecture.md           # Architecture change PRD
│   ├── prd-breaking.md               # Breaking change PRD
│   ├── issue-feature.md              # Feature request template
│   ├── issue-bug.md                  # Bug report template
│   └── issue-enhancement.md          # Enhancement proposal template
├── knowledge/                        # Curated knowledgebase (markdown)
│   ├── README.md                     # Knowledgebase overview and index
│   ├── morphir-principles.md         # Core Morphir philosophy and principles
│   ├── ecosystem-map.md              # Repository overview and relationships
│   ├── architecture/                 # Architecture patterns and decisions
│   │   ├── ir-design.md              # IR architecture and versioning
│   │   ├── vertical-slices.md        # Vertical Slice Architecture
│   │   ├── type-system.md            # Morphir type system
│   │   └── distribution-model.md     # Cross-language distribution
│   ├── repositories/                 # Per-repository knowledge
│   │   ├── morphir-core.md           # finos/morphir (specs)
│   │   ├── morphir-elm.md            # finos/morphir-elm (reference)
│   │   ├── morphir-jvm.md            # finos/morphir-jvm
│   │   ├── morphir-scala.md          # finos/morphir-scala
│   │   ├── morphir-dotnet.md         # finos/morphir-dotnet (this repo)
│   │   └── morphir-examples.md       # finos/morphir-examples
│   ├── features/                     # Feature status across repos
│   │   ├── cli-tools.md              # CLI feature parity
│   │   ├── ir-versions.md            # IR version support matrix
│   │   ├── backends.md               # Backend/codegen support
│   │   └── testing-tools.md          # Testing capabilities
│   ├── conventions/                  # Standards and conventions
│   │   ├── naming.md                 # Naming conventions
│   │   ├── code-style.md             # Code style per language
│   │   ├── commit-messages.md        # Commit message format
│   │   └── issue-labels.md           # Standard labels across repos
│   ├── workflows/                    # Common workflows and processes
│   │   ├── contributing.md           # Contribution workflow
│   │   ├── prd-process.md            # PRD creation and review
│   │   ├── release-process.md        # Release workflow
│   │   └── issue-triage.md           # Issue triage guidelines
│   └── faq/                          # Frequently asked questions
│       ├── product-decisions.md      # Common product decision rationales
│       ├── technical-choices.md      # Technical architecture FAQs
│       └── cross-repo-alignment.md   # How to align features across repos
└── docs/                             # Skill-specific documentation
    └── integration-guide.md          # Integration with other skills

Morphir Ecosystem Model

Repository Categories:

1. Core Specification (finos/morphir)

   • Language specification
   • IR schema definitions (v1, v2, v3)
   • Authoritative documentation

2. Reference Implementation (finos/morphir-elm)

   • Elm frontend compiler
   • CLI tools
   • Example models
   • Most mature implementation

3. Platform Implementations:

   • finos/morphir-jvm: Java/Kotlin support
   • finos/morphir-scala: Scala support
   • finos/morphir-dotnet: C#/F# support

4. Resources:

   • finos/morphir-examples: Example models and documentation

Cross-Repository Queries:

// Example: Find all IR-related issues across ecosystem
let irIssues =
    MorphirRepos.All
    |> Seq.collect (fun repo -> GitHub.queryIssues repo "label:IR")
    |> Seq.sortByDescending (_.UpdatedAt)

GitHub API Integration

Authentication:

• Use GitHub CLI (gh) for authenticated requests
• Leverage existing user credentials
• No API tokens to manage

Rate Limiting:

• Implement exponential backoff
• Cache results for 15 minutes
• Use GraphQL for complex queries (fewer requests)
• Batch queries when possible

Query Patterns:

REST API (simple queries):

gh api repos/finos/morphir-dotnet/issues \
  --field state=open \
  --field labels=enhancement \
  --jq '.[] | {title, number, url}'

GraphQL API (complex queries):

query EcosystemIssues {
  search(query: "org:finos morphir in:name is:issue label:enhancement", type: ISSUE, first: 100) {
    nodes {
      ... on Issue {
        title
        number
        repository { name }
        labels(first: 10) { nodes { name } }
      }
    }
  }
}

Knowledgebase Management

Purpose: The Product Manager skill maintains a curated knowledgebase of Morphir ecosystem knowledge as markdown files within the skill directory. This enables offline access, version control, and structured knowledge organization.

Knowledge Categories:

1. Core Principles (knowledge/morphir-principles.md)

   • Functional modeling philosophy
   • Type-driven development
   • Business domain modeling
   • Distribution strategy
   • Cross-language approach

2. Ecosystem Map (knowledge/ecosystem-map.md)

   • Repository overview and purposes
   • Maturity levels and feature parity
   • Release cadences
   • Maintainer information
   • Dependency relationships

3. Architecture (knowledge/architecture/)

   • IR design and versioning strategy
   • Vertical Slice Architecture patterns
   • Type system design
   • Distribution model
   • Backend architecture patterns

4. Repository-Specific Knowledge (knowledge/repositories/)

   • Per-repo feature status
   • Technology stacks
   • Conventions and patterns
   • Common issues and solutions
   • Roadmap highlights

5. Feature Parity (knowledge/features/)

   • CLI tools comparison matrix
   • IR version support across implementations
   • Backend/codegen capabilities
   • Testing tool availability
   • Documentation status

6. Conventions (knowledge/conventions/)

   • Naming conventions (modules, types, functions)
   • Code style guides per language
   • Commit message standards
   • Issue/PR label taxonomy
   • Documentation standards

7. Workflows (knowledge/workflows/)

   • Contribution process
   • PRD creation and review
   • Release management
   • Issue triage guidelines
   • Cross-repo coordination

8. FAQs (knowledge/faq/)

   • Common product decision rationales
   • Technical architecture questions
   • Cross-repo alignment strategies
   • Migration and compatibility

Knowledge Update Workflow:

// update-knowledge.fsx: Fetch latest info from live sources
// Usage: dotnet fsi update-knowledge.fsx --category repositories

// Fetch latest README from each repo
let updateRepositoryDocs repos =
    repos
    |> Seq.iter (fun repo ->
        let readme = GitHub.fetchFile repo "README.md"
        let repoDoc = Knowledge.parseRepositoryInfo readme
        Knowledge.save $"knowledge/repositories/{repo.name}.md" repoDoc
    )

// Fetch latest feature status
let updateFeatureMatrix () =
    let cliFeatures =
        MorphirRepos.All
        |> Seq.collect (fun repo ->
            GitHub.searchCode repo "CLI commands"
        )
    Knowledge.generateFeatureMatrix cliFeatures
    |> Knowledge.save "knowledge/features/cli-tools.md"

// Validate knowledgebase consistency
let validateKnowledge () =
    Knowledge.checkBrokenLinks ()
    Knowledge.validateMarkdown ()
    Knowledge.checkOutdatedInfo ()

Knowledge Access Patterns:

When asked about Morphir principles:
1. Read knowledge/morphir-principles.md
2. Cite specific sections with links
3. Provide examples from knowledge/faq/

When comparing repos:
1. Read knowledge/ecosystem-map.md for overview
2. Read specific knowledge/repositories/{repo}.md
3. Consult knowledge/features/ for capability matrix

When validating feature alignment:
1. Reference knowledge/morphir-principles.md
2. Check knowledge/architecture/ for design patterns
3. Review knowledge/faq/product-decisions.md for precedents

Knowledge Maintenance:

• Manual Curation: Maintainers update knowledge files as authoritative sources
• Periodic Updates: Run update-knowledge.fsx quarterly to refresh from live sources
• Version Control: Knowledge evolves with the skill, tracked in git
• Validation: CI validates markdown formatting and internal links
• Review Process: Knowledge changes reviewed like code changes

Knowledge vs. Live Data:

• Knowledgebase: Stable, curated, architectural, and philosophical knowledge
• Live Queries: Real-time issue data, PR status, recent activity
• Hybrid Approach: Use knowledge for context, live queries for current state

PRD Template Engine

Interactive Generation:

// Prompt user for each section
let prd = PRD.Interactive [
    Section.Overview [
        Question "What feature are you proposing?"
        Question "Why is this feature needed?"
    ]
    Section.Goals [
        Question "What are the primary goals? (one per line)"
        Question "What is explicitly out of scope?"
    ]
    // ... more sections
]

// Validate completeness
let validation = PRD.validate prd

// Save to file
PRD.save "docs/content/contributing/design/prds/my-feature.md" prd

Skill Activation Triggers

Keywords:

• “PRD”, “product requirements”, “feature spec”
• “create issue”, “file bug”, “report enhancement”
• “ecosystem”, “cross-repo”, “morphir repos”
• “backlog”, “triage”, “issue health”
• “trend”, “popular”, “common issues”
• “align with morphir”, “morphir philosophy”

Scenarios:

• User asks for help creating a PRD
• User wants to file an issue
• User asks “what should I work on?”
• User asks about feature status across repos
• User proposes a feature that may not align
• User asks about Morphir architecture or principles

Feature Status Tracking

Status Legend:

• ⏳ Planned: Specification complete, ready to implement
• 🚧 In Progress: Currently being implemented
• ✅ Implemented: Feature complete and tested
• 🔄 Iterating: Implemented but needs refinement
• ⏸️ Deferred: Postponed to later phase

Priority Legend:

• P0: Must-have for initial release
• P1: Should-have for initial release
• P2: Nice-to-have, can be added later

Implementation Phases

Phase 1: Core Infrastructure and Knowledgebase Foundation (Weeks 1-2)

Goal: Establish skill structure, foundational scripts, and core knowledgebase

Deliverables:

• PRD created and reviewed (this document)
• skill.md with core playbooks
• README with quick start
• Knowledgebase structure and README
• knowledge/morphir-principles.md (P0)
• knowledge/ecosystem-map.md (P0)
• knowledge/architecture/ - 4 core docs (P0)
  • ir-design.md
  • vertical-slices.md
  • type-system.md
  • distribution-model.md
• Basic GitHub API utilities (scripts/common/)
• query-issues.fsx (basic functionality)

Success Criteria:

• Skill can be invoked and responds appropriately
• Knowledgebase has core Morphir principles documented
• query-issues.fsx can query issues from single repository
• Documentation explains skill purpose and capabilities
• Skill can reference knowledgebase when answering questions

Phase 2: Templates, Playbooks, and Extended Knowledgebase (Weeks 2-3)

Goal: Provide templates, guided workflows, and expand knowledgebase

Deliverables:

• All PRD templates (standard, architecture, breaking)
• All issue templates (feature, bug, enhancement)
• PRD creation playbook
• Issue crafting playbook
• Enhanced query-issues.fsx (multi-repo, filtering)
• knowledge/repositories/ - 6 repo docs (P1)
• knowledge/conventions/ - 4 convention docs (P1)
• knowledge/workflows/ - 4 workflow docs (P1)

Success Criteria:

• User can generate PRD using template
• User can create well-structured issue with guidance
• Multi-repository queries work across all finos/morphir-* repos
• Knowledgebase covers all major Morphir repositories
• Skill can compare features across repositories using knowledgebase

Phase 3: Analytics, Intelligence, and Feature Matrices (Weeks 3-4)

Goal: Add ecosystem intelligence capabilities and feature comparison matrices

Deliverables:

• analyze-backlog.fsx
• trend-analysis.fsx
• check-ecosystem.fsx
• Feature validation playbook
• Ecosystem analysis playbook
• Caching infrastructure
• knowledge/features/ - 4 feature matrices (P1)
• knowledge/faq/ - 3 FAQ docs (P2)

Success Criteria:

• Backlog health metrics accurate and actionable
• Trend analysis identifies real patterns (validated manually)
• Ecosystem dashboard provides useful overview
• Feature matrices enable cross-repo capability comparisons
• FAQs capture common product decision rationales

Phase 4: Integration, Polish, and Knowledge Automation (Week 4-5)

Goal: Integrate with other skills, refine, and add knowledge automation

Deliverables:

• Integration guide (qa-tester, release-manager)
• generate-prd.fsx (interactive PRD generation)
• update-knowledge.fsx (knowledgebase automation)
• Knowledge management playbook
• Comprehensive testing
• Documentation review and updates
• Example walkthroughs
• Knowledgebase validation (CI integration)

Success Criteria:

• Skill integrates smoothly with qa-tester and release-manager
• generate-prd.fsx creates complete, high-quality PRDs
• update-knowledge.fsx can refresh knowledgebase from live sources
• Documentation is comprehensive and clear
• Examples demonstrate all major workflows
• Knowledgebase passes automated validation checks

Testing Strategy

Manual Testing

PRD Creation:

1. Request PRD for fictional feature
2. Validate all sections populated
3. Check alignment with existing PRDs
4. Verify feature tracking table included

Issue Creation:

1. Request help creating feature, bug, enhancement
2. Validate templates used correctly
3. Check cross-references to related issues
4. Verify appropriate labels suggested

Ecosystem Queries:

1. Run query-issues.fsx across all repos
2. Validate results accuracy (spot check 20 issues)
3. Test filtering, sorting, formatting
4. Verify performance < 2 minutes

Backlog Analysis:

1. Run analyze-backlog.fsx on known repo
2. Manually validate metrics (age, staleness)
3. Check recommendations are actionable
4. Compare against ecosystem averages

Trend Analysis:

1. Run trend-analysis.fsx for 30-day window
2. Manually review top trending labels
3. Validate emerging themes make sense
4. Check for false positives

Integration Testing

With qa-tester:

1. Create PRD, then ask qa-tester for test plan
2. Verify test plan aligns with PRD acceptance criteria
3. Check cross-references work

With release-manager:

1. Ask about feature priority for release
2. Verify release-manager can access PRD context
3. Check coordination on changelog entries

Acceptance Testing

User Scenarios:

• New contributor creates first issue with PM help
• Maintainer generates PRD for complex feature
• Developer checks ecosystem for related work
• Project lead analyzes backlog health
• Contributor validates feature alignment

Quality Checks:

• PRDs follow template structure
• Issues have appropriate labels
• Cross-repo queries are accurate
• Metrics are validated against manual checks
• Recommendations are helpful (user survey)

Success Criteria

Quantitative Metrics

• Adoption: 80% of PRDs created using Product Manager skill
• Issue Quality: 90% of issues created with PM help are well-structured (manual review)
• Query Accuracy: 95% precision on cross-repo issue searches
• Performance: All scripts complete within SLA (30s single-repo, 2min ecosystem)
• Coverage: All 6 Morphir repos covered by ecosystem queries

Qualitative Metrics

• User Satisfaction: Positive feedback from 4+ contributors
• Maintainer Impact: Reduced time spent triaging issues
• Knowledge Transfer: New contributors feel confident creating issues/PRDs
• Alignment: Features better aligned with Morphir philosophy (maintainer assessment)
• Integration: Smooth coordination with qa-tester and release-manager

Completion Criteria

• All P0 features implemented and tested
• All P1 features implemented and tested
• Documentation complete and reviewed
• Integration tested with other skills
• At least 3 real PRDs created using the skill
• At least 10 real issues created with PM assistance
• Ecosystem queries validated across all repos
• Maintainer sign-off

Implementation Notes

2025-12-18: Initial PRD Creation

• Decision: Start with comprehensive PRD before implementation
• Rationale: Complex skill requiring careful design and alignment with existing patterns
• Impact: Clear roadmap for phased implementation
• Files: This PRD (product-manager-skill.md)

Open Questions

Q1: Should the Product Manager skill fetch live documentation from morphir.finos.org?

Status: Open Options:

1. Fetch live docs via WebFetch tool
2. Maintain local cache of key documentation
3. Reference docs via links only

Decision Needed By: Phase 1 (Week 1) Impact: Affects skill.md design and response accuracy

Q2: How should the skill handle conflicting guidance across repos?

Status: Open Example: morphir-elm uses one convention, morphir-dotnet uses another Options:

1. Always favor reference implementation (morphir-elm)
2. Favor current repo context
3. Present both and explain tradeoffs

Decision Needed By: Phase 1 (Week 1) Impact: Affects ecosystem map and playbook design

Q3: Should F# scripts use GitHub CLI or direct API calls?

Status: Open Options:

1. GitHub CLI (gh) for simplicity and auth
2. Direct API calls via HTTP client for flexibility
3. Hybrid approach

Recommendation: GitHub CLI for Phase 1, evaluate direct API if needed Decision Needed By: Phase 1 (Week 1) Impact: Affects script architecture and dependencies

Q4: How deep should trend analysis go?

Status: Open Options:

1. Label frequency and time-series only
2. Add NLP for theme extraction from titles/descriptions
3. Add sentiment analysis

Recommendation: Start with label frequency, add NLP in Phase 3 if valuable Decision Needed By: Phase 3 (Week 3) Impact: Affects trend-analysis.fsx complexity and dependencies

References

Project Documentation

• AGENTS.md - Primary agent guidance
• CLAUDE.md - Claude Code-specific guidance
• QA Tester Skill
• Release Manager Skill
• Existing PRDs

Morphir Resources

• Morphir Homepage
• morphir (core spec)
• morphir-elm (reference)
• morphir-jvm
• morphir-scala
• morphir-dotnet (this repo)
• morphir-examples