Design: PM Feature Management with @spec Tags

[deepracticexs]

Overview

Design and implement a Product Manager (PM) role in NodeSpec CLI for managing Gherkin feature files with a structured tagging system and query capabilities.

Motivation

Currently, there's no standardized way to:

• Uniquely identify features, rules, and scenarios
• Query and filter features across packages
• Track feature metadata for PM workflows
• Manage feature lifecycle independently of file paths

Design Proposal

Tag System: @spec: Namespace

Use @spec: prefixed tags to avoid collision with native Gherkin tags:

Required Tags:

• @spec:id={unique-id} - Globally unique identifier (auto-generated)
• @spec:path={package/path/to/feature} - Relative path from package to feature (Feature level only)

Future Extensions:

• @spec:priority={low|medium|high|critical}
• @spec:status={draft|implemented|pending|deprecated}
• @spec:owner={username}
• @spec:issue={number}

Example Feature File

Feature: Initialize Monorepo in Current Directory
  @spec:id=cli-infra-monorepo-init
  @spec:path=cli/infra/monorepo/init
  As a developer using NodeSpec
  I want to initialize a monorepo project

  Rule: Initialize creates complete structure
    @spec:id=cli-infra-monorepo-init-r1
    
    Scenario: Initialize in current directory
      @spec:id=cli-infra-monorepo-init-r1-s1
      Given I am in an empty directory
      When I run "nodespec infra monorepo init"
      Then the command should succeed

ID Generation Rules

Feature ID:   {path-with-dashes}
              cli/infra/monorepo/init → cli-infra-monorepo-init

Rule ID:      {feature-id}-r{index}
              cli-infra-monorepo-init-r1

Scenario ID:  {rule-id}-s{index}
              cli-infra-monorepo-init-r1-s1

CLI Commands

# Management commands
nodespec pm feature init <path>        # Initialize @spec tags for a feature
nodespec pm feature init --all         # Batch initialize all features
nodespec pm feature validate           # Validate @spec tags completeness and uniqueness

# Query commands
nodespec pm feature list [package]     # List features (optional: filter by package)
nodespec pm feature show --id <id>     # Show feature by ID
nodespec pm feature show --path <path> # Show feature by path

# Creation commands
nodespec pm feature create <path>      # Create new feature (auto-init @spec tags)

Data Model

interface FeatureMetadata {
  id: string;              // @spec:id
  path: string;            // @spec:path
  filePath: string;        // Actual file path
  
  title: string;
  rules: RuleMetadata[];
  scenarios: ScenarioMetadata[];
}

interface RuleMetadata {
  id: string;              // @spec:id
  title: string;
  scenarios: ScenarioMetadata[];
}

interface ScenarioMetadata {
  id: string;              // @spec:id
  title: string;
}

Implementation Plan

1. Gherkin Parser Enhancement

   • Parse @spec: tags from feature files
   • Extract metadata into structured format
   • Support tag validation

2. PM Feature Commands

   • nodespec pm feature init - Generate and inject @SPEC tags
   • nodespec pm feature list - Query features with filters
   • nodespec pm feature show - Display feature details
   • nodespec pm feature validate - Validate tag integrity

3. ID Generator

   • Auto-generate unique IDs based on path
   • Handle Rule and Scenario numbering
   • Ensure uniqueness across workspace

4. Feature Index

   • Build queryable index of all features
   • Support filtering by package, ID, path
   • Cache for performance

Benefits

• Fast Lookup: Find features by ID without knowing file path
• PM-Friendly: Manage features without understanding directory structure
• Extensible: Easy to add new @SPEC tags for additional metadata
• Compatible: Doesn't break existing Gherkin tooling
• Automated: ID generation removes manual maintenance burden

Related Issues

• CLI Design Principles: Four-Layer Semantic Structure for AI-First Development #12 - Four-layer CLI semantic structure

Technical Considerations

• Tag parsing: Use existing Gherkin parser, extract @SPEC: tags
• ID collision: Validate uniqueness on init and validate
• File modification: Preserve formatting when injecting tags
• Backward compatibility: Features without @SPEC tags still work (fallback to path-based queries)

Open Questions

• Should init be idempotent (skip if tags exist) or update existing tags?
• Should we support manual ID override or always auto-generate?
• How to handle ID conflicts if features are moved/renamed?