Feature Tracking

Feature Tracking Skill

Track feature implementation status against requirements documents using hierarchical FR codes.

When to Use This Skill

Overview

The feature tracker maintains a JSON file that maps requirements from a source document (e.g., REQUIREMENTS.md) to implementation status. It supports:

• Hierarchical FR codes: FR1, FR2.1, FR2.1.1, etc.
• Phase-based development: Group features by development phase
• PRD integration: Link features to Product Requirements Documents
• Task tracking: Track in-progress and pending tasks (replaces work-overview.md)
• Sync targets: Keep TODO.md in sync

When to Run

Run feature tracking operations when:

• Feature implementation status changes
• New PRD is added or completed
• After major development milestones
• Before generating status reports
• Starting a new development phase

Core Concepts

Feature Status

Each feature has one of five statuses:

• complete: Implementation files exist, tests pass, TODO item checked
• partial: Some implementation exists, not all sub-features done
• in_progress: Active work, files modified recently
• not_started: No implementation files, TODO unchecked
• blocked: Missing dependencies or explicitly marked

Hierarchical Structure

Features are organized hierarchically:

FR1 (Game Setup & Configuration)
├── FR1.1 (Window Configuration)
├── FR1.2 (Game Mode Selection)
│   ├── FR1.2.1 (Versus Mode)
│   └── FR1.2.2 (Cooperative Mode)
└── FR1.3 (Scenario Setup)

Phase Organization

Features are grouped by development phase:

• phase-0: Foundation
• phase-1: Core gameplay
• phase-2: Advanced features
• etc.

File Structure

docs/blueprint/
├── feature-tracker.json       # Main tracker file (source of truth)
└── schemas/                   # Optional: local schema copy
    └── feature-tracker.schema.json

The project's TODO.md is a sync target for checkbox states.

Note: As of v1.1.0, feature-tracker.json includes a tasks section that tracks in-progress and pending tasks, replacing the separate work-overview.md file.

Quick Commands

View completion stats

jq '.statistics' docs/blueprint/feature-tracker.json

List incomplete features

jq -r '.. | objects | select(.status == "not_started") | .name' docs/blueprint/feature-tracker.json

Show PRD completion

jq '.prds | to_entries | .[] | "\(.key): \(.value.status)"' docs/blueprint/feature-tracker.json

List features by phase

jq -r '.. | objects | select(.phase == "phase-1") | .name' docs/blueprint/feature-tracker.json

Count features by status

jq '[.. | objects | select(.status?) | .status] | group_by(.) | map({(.[0]): length}) | add' docs/blueprint/feature-tracker.json

Schema

The feature tracker uses a JSON Schema for validation. The schema is bundled with the blueprint-plugin at:

schemas/feature-tracker.schema.json

Key schema features:

• Strict FR code validation: ^FR\d+(\.\d+)*$
• Phase pattern validation: ^phase-\d+$
• Recursive feature definitions for nesting
• PRD naming pattern: ^PRD_[A-Z_]+$

Validate tracker

scripts/check-schema.py is the bundled validator — the same engine the ADR/PRD/PRP hooks use. It needs no globally-installed ajv, resolves its own dependencies through uv, and emits the STATUS=/ISSUE_COUNT= contract from .claude/rules/structured-script-output.md:

uv run --quiet --script "${CLAUDE_PLUGIN_ROOT}/scripts/check-schema.py" --schema "${CLAUDE_PLUGIN_ROOT}/schemas/feature-tracker.schema.json" --json-file docs/blueprint/feature-tracker.json

Exit 0 on OK/WARN, 1 on ERROR. A missing tracker is STATUS=OK — most repos have none, and a validator that errors on an absent optional file gets disabled. blueprint-tracker-check.sh covers the invariants a schema cannot express (the statistics cache agreeing with the features collection, tasks.*[] membership, FR ids cited in docs but never minted).

Integration Points

Manifest Integration

The manifest.json references the feature tracker:

{
  "structure": {
    "has_feature_tracker": true
  },
  "feature_tracker": {
    "file": "feature-tracker.json",
    "source_document": "REQUIREMENTS.md",
    "sync_targets": ["TODO.md"]
  }
}

PRD Mapping

Features link to PRDs via the prd field:

{
  "name": "Terrain Visual Enhancement",
  "status": "complete",
  "prd": "PRD_TERRAIN_VISUAL_ENHANCEMENT"
}

PRDs track which features they implement:

{
  "PRD_TERRAIN_VISUAL_ENHANCEMENT": {
    "name": "Terrain Visual Enhancement",
    "status": "complete",
    "features_implemented": ["FR2.8.1", "FR2.8.2", "FR2.8.3"],
    "tests_passing": 107
  }
}

Work Order Integration

Work orders can reference specific FR codes. When a work order is completed, update the corresponding feature status in the tracker.

Sync Process

The sync process ensures consistency between:

1. feature-tracker.json (source of truth for features AND tasks)
2. TODO.md (checkbox-based task list)

Sync Steps

1. Load current state from feature-tracker.json (features and tasks)
2. Compare with TODO.md checkbox states
3. Verify implementation status for each feature
4. Recalculate statistics
5. Update TODO.md with changes
6. Report what was synchronized

Human-Readable Summary

Use --summary flag to generate a markdown overview:

/blueprint:feature-tracker-sync --summary

Status Verification

For each feature, verify:

• complete: Files exist, tests pass (if applicable), TODO checked
• partial: Some files exist, not all sub-features complete
• in_progress: Recent commits touch feature files
• not_started: No implementation evidence
• blocked: Documented dependency issues

Commands

Related blueprint commands:

• /blueprint:feature-tracker-status: Display statistics and completion summary
• /blueprint:feature-tracker-sync: Synchronize tracker with sync targets

Example: Updating Feature Status

When completing a feature:

1. Update feature status in feature-tracker.json:

   {
     "name": "Unit Selection",
     "status": "complete",
     "phase": "phase-2",
     "implementation": {
       "files": ["src/systems/selection.rs"],
       "notes": "Box selection and click selection",
       "tests": ["tests/selection_tests.rs"]
     }
   }
   

2. Run /blueprint:feature-tracker-sync to update:

   • Move task from tasks.in_progress to tasks.completed
   • TODO.md checkboxes
   • Statistics recalculation

3. Commit all changes together for consistency

Statistics

The tracker maintains aggregate statistics:

{
  "statistics": {
    "total_features": 42,
    "complete": 22,
    "partial": 4,
    "in_progress": 2,
    "not_started": 14,
    "blocked": 0,
    "completion_percentage": 52.4
  }
}

These are recalculated during sync operations.