Tagging System

Validated, trackable metadata for powerful filtering and organization.

The tagging system provides a registry-based approach to categorizing work units and features. Unlike ad-hoc tags, fspec's tags are validated, documented, and tracked—giving you powerful filtering capabilities while preventing tag sprawl and inconsistency.

The Problem: Tag Chaos

Without a tag registry, tags become unmanageable:

Developer 1: @frontend @ui @react
Developer 2: @front-end @UI @React
Developer 3: @client-side @interface

Same concept, three different tag variations.
Result: Filters don't work, reports are incomplete, search is broken.

The result: Tag sprawl, inconsistency, lost discoverability, broken queries.

How Tagging Works

The tagging system enforces validation, tracks usage, and maintains documentation:

Key Features:

Registry-based: All tags must be registered before use
Validated: Format and category enforcement
Categorized: Organized by purpose (component, priority, platform, etc.)
Tracked: Usage statistics across features and work units
Documented: TAGS.md auto-generated from registry

Tag Registry Structure

Tags are stored in spec/tags.json:

{
  "tags": [
    {
      "name": "@authentication",
      "category": "Component",
      "description": "Authentication and identity management features",
      "usageCount": 12
    },
    {
      "name": "@high-priority",
      "category": "Priority",
      "description": "Critical work that must be completed first",
      "usageCount": 8
    },
    {
      "name": "@backend",
      "category": "Technical",
      "description": "Server-side code and API implementation",
      "usageCount": 25
    }
  ]
}

Registry fields:

name: Tag identifier (must start with @, lowercase-with-hyphens)
category: Tag classification (Component, Priority, etc.)
description: What this tag means and when to use it
usageCount: Number of features/work units using this tag (tracked automatically)

Tag Validation Rules

Format Rules

Valid format: @lowercase-with-hyphens

Examples:

✅ @authentication
✅ @high-priority
✅ @frontend-ui
✅ @test-coverage
❌ @Authentication (uppercase not allowed)
❌ @high_priority (underscores not allowed)
❌ @High-Priority (mixed case not allowed)
❌ authentication (missing @ prefix)

Why these rules?

Consistent formatting prevents duplicates
Lowercase ensures case-insensitive matching
Hyphens are readable and URL-safe
@ prefix visually distinguishes tags from regular text

Category Rules

Valid categories:

Component: System components (authentication, payment, dashboard)
Feature Group: Related features (user-management, reporting)
Technical: Technical areas (backend, frontend, database)
Platform: Platform-specific (ios, android, web)
Priority: Priority levels (high-priority, low-priority)
Status: Status indicators (deprecated, experimental)
Testing: Testing-related (needs-testing, test-coverage)

Why categories matter?

Organize tags by purpose
Enable category-based filtering
Improve TAGS.md readability
Prevent category confusion

Description Rules

Required: Every tag must have a description

Good descriptions:

✅ "Authentication and identity management features"
✅ "Critical work that must be completed first"
✅ "Server-side code and API implementation"

Bad descriptions:

❌ "Auth stuff" (too vague)
❌ "Backend" (redundant with tag name)
❌ "" (empty)

Why descriptions matter?

Document when to use the tag
Onboard new team members
Prevent misuse
Improve searchability

Tag Categories Explained

Component Category

Purpose: Identify system components and domains

Examples:

@authentication - Auth and identity features
@payment - Payment processing
@notification - Notification system
@dashboard - Dashboard UI

Use case: "Show me all authentication work"

Feature Group Category

Purpose: Group related features together

Examples:

@user-management - User CRUD, profiles, settings
@reporting - Analytics, reports, dashboards
@api-integration - Third-party API integrations

Use case: "Show me all user management features"

Technical Category

Purpose: Technical architecture and stack

Examples:

@backend - Server-side code
@frontend - Client-side code
@database - Database schemas and queries
@infrastructure - DevOps, CI/CD

Use case: "Show me all backend work"

Platform Category

Purpose: Platform-specific work

Examples:

@ios - iOS app
@android - Android app
@web - Web app
@mobile - Cross-platform mobile

Use case: "Show me all iOS work"

Priority Category

Purpose: Prioritize work

Examples:

@high-priority - Must do first
@medium-priority - Do soon
@low-priority - Do eventually
@critical - Urgent, blocking

Use case: "Show me high-priority work"

Status Category

Purpose: Mark special statuses

Examples:

@deprecated - Being phased out
@experimental - Experimental feature
@legacy - Legacy code
@blocked - Blocked by external dependency

Use case: "Show me deprecated features"

Testing Category

Purpose: Testing-related metadata

Examples:

@needs-testing - Tests not written yet
@test-coverage - Full test coverage
@integration-test - Integration tests required
@manual-test - Manual QA needed

Use case: "Show me work needing tests"

Natural Language Workflows

Scenario 1: Registering Tags for New Project

YOU: "Let's set up tags for our authentication project."

AI: I'll register tags for authentication work...

    fspec register-tag @authentication \
      --category Component \
      --description "Authentication and identity management features"

    ✓ Registered tag: @authentication

    fspec register-tag @security \
      --category Technical \
      --description "Security-sensitive code requiring extra review"

    ✓ Registered tag: @security

    fspec register-tag @high-priority \
      --category Priority \
      --description "Critical work that must be completed first"

    ✓ Registered tag: @high-priority

    Now these tags can be used on features and work units.

YOU: "Add backend and frontend tags too."

AI: fspec register-tag @backend \
      --category Technical \
      --description "Server-side code and API implementation"

    fspec register-tag @frontend \
      --category Technical \
      --description "Client-side code and UI implementation"

    ✓ Registered 2 tags

    You now have a complete tag set for your project.

Scenario 2: Using Registered Tags

YOU: "Create a story for user login and tag it appropriately."

AI: fspec create-story "User login with email/password" \
      --prefix AUTH \
      --tags @authentication @backend @high-priority @security

    ✓ Created AUTH-001

    All tags validated against registry.
    Tags applied:
    - @authentication (Component)
    - @backend (Technical)
    - @high-priority (Priority)
    - @security (Technical)

YOU: "Tag the feature file too."

AI: fspec tag-feature user-authentication \
      @authentication @backend @security

    ✓ Tagged feature: user-authentication

    This feature now shares tags with its work units.

Scenario 3: Tag Validation Catches Typo

YOU: "Create a story and tag it @Authenication."

AI: fspec create-story "Password reset" \
      --tags @Authenication @backend

    ❌ Error: Invalid tag format: @Authenication
       Reason: Contains uppercase letters
       Valid format: @lowercase-with-hyphens

    Did you mean: @authentication?

YOU: "Yes, use @authentication."

AI: fspec create-story "Password reset" \
      --tags @authentication @backend

    ✓ Created AUTH-002 with validated tags

Scenario 4: Viewing Tag Statistics

YOU: "Which tags are most used in our project?"

AI: fspec tag-stats

# Tag Usage Statistics

## By Category

### Component (3 tags, 45 usages)
- @authentication: 12 usages (5 features, 7 work units)
- @payment: 18 usages (3 features, 15 work units)
- @dashboard: 15 usages (4 features, 11 work units)

### Technical (2 tags, 50 usages)
- @backend: 25 usages
- @frontend: 25 usages

### Priority (3 tags, 20 usages)
- @high-priority: 8 usages
- @medium-priority: 7 usages
- @low-priority: 5 usages

## Top 5 Most Used Tags
1. @backend (25 usages)
2. @frontend (25 usages)
3. @payment (18 usages)
4. @dashboard (15 usages)
5. @authentication (12 usages)

## Unused Tags (2)
- @legacy (0 usages)
- @deprecated (0 usages)

The @backend and @frontend tags are most heavily used.
Consider breaking down into more specific tags if needed.

Scenario 5: Auto-Generating Tag Documentation

YOU: "Generate documentation for all our tags."

AI: fspec generate-tags-doc

    ✓ Generated TAGS.md from registry

    TAGS.md created with:
    - All registered tags organized by category
    - Usage statistics for each tag
    - Descriptions and guidelines
    - Auto-updated on every tag change

YOU: "Show me what it looks like."

AI: [Reading TAGS.md]

# Project Tags

This file is auto-generated from `spec/tags.json`. Do not edit manually.
Last updated: 2025-11-09

## Component (3 tags)

### @authentication (12 usages)
Authentication and identity management features

**Used by**:
- Features: user-authentication, oauth-integration, session-management
- Work Units: AUTH-001, AUTH-002, AUTH-003, ...

### @payment (18 usages)
Payment processing and billing features

**Used by**:
- Features: payment-processing, refunds, invoicing
- Work Units: PAY-001, PAY-002, ...

## Technical (2 tags)

### @backend (25 usages)
Server-side code and API implementation

### @frontend (25 usages)
Client-side code and UI implementation

[... more categories ...]

Scenario 6: Cleaning Up Unused Tags

YOU: "We have some tags that aren't being used. Clean them up."

AI: Checking for unused tags...
    fspec tag-stats

    Found 3 unused tags:
    - @legacy (0 usages)
    - @deprecated (0 usages)
    - @experimental (0 usages)

    Should I delete these tags?

YOU: "Keep @experimental, delete the others."

AI: fspec delete-tag @legacy
    fspec delete-tag @deprecated

    ✓ Deleted 2 tags
    ✓ Kept @experimental for future use

    Tag registry is now cleaner.

Tag Operations

Registering Tags

Basic registration:

fspec register-tag @authentication \
  --category Component \
  --description "Authentication and identity management features"

Output:

✓ Registered tag: @authentication
  Category: Component
  Description: Authentication and identity management features
  Usage: 0 (newly registered)

Batch registration:

fspec register-tag @backend --category Technical --description "Server-side code"
fspec register-tag @frontend --category Technical --description "Client-side code"
fspec register-tag @database --category Technical --description "Database code"

Listing Tags

All tags:

fspec list-tags

Output:

# Registered Tags

## Component (3)
- @authentication (12 usages)
- @payment (18 usages)
- @dashboard (15 usages)

## Technical (3)
- @backend (25 usages)
- @frontend (25 usages)
- @database (10 usages)

## Priority (3)
- @high-priority (8 usages)
- @medium-priority (7 usages)
- @low-priority (5 usages)

Total: 9 tags, 100 total usages

Filter by category:

fspec list-tags --category Technical

Output:

# Technical Tags

- @backend (25 usages)
- @frontend (25 usages)
- @database (10 usages)

Viewing Tag Statistics

Project-wide statistics:

fspec tag-stats

Output:

# Tag Usage Statistics

## Summary
- Total Tags: 12
- Total Usages: 150
- Average Usage: 12.5 per tag
- Most Used: @backend (25)
- Least Used: @experimental (0)

## By Category
- Component: 45 usages across 3 tags
- Technical: 60 usages across 3 tags
- Priority: 20 usages across 3 tags
- Testing: 10 usages across 2 tags
- Status: 0 usages across 1 tag

## Unused Tags (1)
- @experimental

Single tag statistics:

fspec tag-stats @authentication

Output:

# Tag: @authentication

**Category**: Component
**Description**: Authentication and identity management features
**Usage Count**: 12

## Used By Features (5)
- user-authentication
- oauth-integration
- session-management
- password-reset
- two-factor-auth

## Used By Work Units (7)
- AUTH-001: User login
- AUTH-002: Password reset
- AUTH-003: Session management
- AUTH-004: OAuth integration
- AUTH-005: Two-factor auth
- AUTH-006: Remember me
- AUTH-007: Logout

Validating Tags

Validate all tags in project:

fspec validate-tags

Output (success):

✓ All tags valid

Validation Results:
- Features validated: 25
- Work units validated: 150
- Tags found: 12
- All tags registered: Yes
- Format violations: 0

Output (failures):

❌ Tag validation failed

Errors Found:

1. Unregistered tag used
   Tag: @auth
   Used by: AUTH-001
   Fix: Register tag or change to @authentication

2. Invalid format
   Tag: @High-Priority
   Used by: PAY-005
   Fix: Change to @high-priority (lowercase)

3. Unregistered tag used
   Tag: @frontend-ui
   Used by: DASH-002
   Fix: Register tag with category Component

Summary:
- 3 violations found
- 2 unregistered tags
- 1 format error

Run fixes:
1. fspec register-tag @auth --category Component
2. fspec update-work-unit PAY-005 --remove-tag @High-Priority --add-tag @high-priority
3. fspec register-tag @frontend-ui --category Component

Deleting Tags

Delete unused tag:

fspec delete-tag @experimental

Output:

✓ Deleted tag: @experimental
  Was used by: 0 features, 0 work units
  Registry updated

Prevent deletion of used tag:

fspec delete-tag @authentication

Output:

❌ Cannot delete tag: @authentication
   Reason: Tag is in use

   Used by:
   - 5 features
   - 7 work units

   To force delete (will remove from all features/work units):
   fspec delete-tag @authentication --force

Force delete with cleanup:

fspec delete-tag @authentication --force

Output:

⚠️  Force deleting tag: @authentication

Removing from:
- user-authentication (feature)
- oauth-integration (feature)
- AUTH-001 (work unit)
- AUTH-002 (work unit)
- ... (10 more)

✓ Deleted tag: @authentication
  Removed from: 5 features, 7 work units
  Registry updated

TAGS.md Auto-Generation

The TAGS.md file is auto-generated from tags.json and serves as living documentation:

When TAGS.md Updates

Auto-generated on:

Tag registration
Tag deletion
Tag usage changes
Manual generation: fspec generate-tags-doc

TAGS.md Structure

# Project Tags
 
This file is auto-generated from `spec/tags.json`. Do not edit manually.
Last updated: 2025-11-09
 
## Component (3 tags, 45 usages)
 
### @authentication (12 usages)
Authentication and identity management features
 
**Used by Features**:
- user-authentication
- oauth-integration
- session-management
 
**Used by Work Units**:
- AUTH-001, AUTH-002, AUTH-003, ...
 
### @payment (18 usages)
Payment processing and billing features
 
## Technical (2 tags, 60 usages)
 
### @backend (25 usages)
Server-side code and API implementation
 
### @frontend (25 usages)
Client-side code and UI implementation
 
---
 
## Tag Usage Guidelines
 
1. Always use registered tags
2. Follow @lowercase-with-hyphens format
3. Choose appropriate category
4. Add descriptions when registering
5. Run `fspec validate-tags` before committing

Integration with ACDD Workflow

Tags enhance every phase of ACDD:

Specifying Phase: Tag Features

fspec create-feature "User Authentication" \
  --tags @authentication @backend @high-priority

Testing Phase: Tag Work Units

fspec create-story "User login" \
  --tags @authentication @backend @needs-testing

Implementing Phase: Filter by Tags

fspec list-work-units --tag @backend --status implementing

Validating Phase: Quality Gates

# Ensure all high-priority work has test coverage
fspec list-work-units --tag @high-priority --tag @needs-testing

Done Phase: Analytics

# Track what was delivered
fspec tag-stats --status done

Best Practices

✅ DO

Register tags before using - Prevent ad-hoc tags
Use descriptive names - @authentication not @auth
Choose correct category - Improves organization
Write clear descriptions - Helps team understand usage
Validate regularly - Run fspec validate-tags before commits
Generate TAGS.md - Keep documentation current
Clean up unused tags - Prevent registry bloat
Use multiple tags - Combine for rich filtering (@backend @high-priority)

❌ DON'T

Skip registration - Defeats the purpose
Use uppercase or underscores - Breaks validation
Create duplicate concepts - @auth and @authentication
Over-tag - 10 tags per work unit is too many
Manually edit TAGS.md - It's auto-generated
Delete tags in use - Unless using --force with care
Use generic descriptions - "Backend stuff" is useless

Common Patterns

Pattern 1: Standard Tag Set

Every project starts with these core tags:

# Technical
fspec register-tag @backend --category Technical --description "Server-side code"
fspec register-tag @frontend --category Technical --description "Client-side code"
 
# Priority
fspec register-tag @high-priority --category Priority --description "Critical work"
fspec register-tag @low-priority --category Priority --description "Nice to have"
 
# Testing
fspec register-tag @needs-testing --category Testing --description "Tests not written"
fspec register-tag @test-coverage --category Testing --description "Full coverage"

Pattern 2: Domain-Specific Tags

Add tags for your specific domain:

# E-commerce
fspec register-tag @checkout --category Component
fspec register-tag @cart --category Component
fspec register-tag @inventory --category Component

Pattern 3: Platform Tags

Multi-platform projects:

fspec register-tag @ios --category Platform
fspec register-tag @android --category Platform
fspec register-tag @web --category Platform
fspec register-tag @shared --category Platform --description "Cross-platform code"

Pattern 4: Status Tracking

Special statuses:

fspec register-tag @blocked --category Status --description "Blocked by dependency"
fspec register-tag @experimental --category Status --description "Experimental feature"
fspec register-tag @deprecated --category Status --description "Being phased out"

Troubleshooting

Issue: Tag validation fails

Error: Tag @Authentication is invalid

Solution: Use lowercase format

# Change to:
@authentication

Issue: Tag not found

Error: Tag @auth is not registered

Solution: Register the tag first

fspec register-tag @auth --category Component --description "Authentication features"

Or use existing similar tag:

@authentication

Issue: TAGS.md out of date

Problem: TAGS.md doesn't reflect current tags

Solution: Regenerate

fspec generate-tags-doc

Issue: Too many tags, hard to manage

Problem: Tag registry has 100+ tags

Solution: Delete unused tags

fspec tag-stats
# Identify tags with 0 usages
fspec delete-tag @unused-tag

Summary

The tagging system provides validated, trackable metadata:

Before Tagging System:

Ad-hoc tags with typos
Duplicate tag concepts
No consistency
Broken filtering
Lost discoverability

With Tagging System:

✅ Registry-based validation
✅ Consistent formatting
✅ Category organization
✅ Usage tracking
✅ Auto-generated docs
✅ Powerful filtering
✅ Team alignment

Key Concepts:

Registry: tags.json stores all valid tags
Validation: Format and category enforcement
Categories: Component, Technical, Priority, Platform, Status, Testing, Feature Group
Statistics: Usage tracking across features and work units
Documentation: TAGS.md auto-generated

Core Commands:

fspec register-tag @name --category Cat --description "Desc"
fspec list-tags                    # View all tags
fspec tag-stats                    # Usage statistics
fspec validate-tags                # Check consistency
fspec delete-tag @name             # Remove tag
fspec generate-tags-doc            # Update TAGS.md

Validation Format:

@lowercase-with-hyphens

Tag Categories:

Component: System components
Feature Group: Related features
Technical: Tech stack
Platform: Platform-specific
Priority: Prioritization
Status: Special statuses
Testing: Test-related

Tags transform chaotic metadata into structured, validated, trackable categorization.

Review Command Dependency Management