feature-tracking

# Feature Tracking Skill Track feature implementation status against requirements documents using hierarchical FR codes. ## When to Use This Skill | Use this skill when... | Use blueprint-feature-tracker-sync instead when... | |---|---| | You need to read or update feature implementation status by FR code | You want to reconcile TODO.md checkboxes with the tracker | | You're recalculating completion percentages mid-development | You want to drain WO entries from a taskwarrior sidecar | | You manage hierarchical FR codes (FR1, FR1.2, FR1.2.1) | You want a markdown progress summary via `--summary` | | You add features or phases to feature-tracker.json | Use blueprint-feature-tracker-status to view stats without modifying | ## 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 ```bash jq '.statistics' docs/blueprint/feature-tracker.json ``` ### List incomplete features ```bash jq -r '.. | objects | select(.status == "not_started") | .name' docs/blueprint/feature-tracker.json ``` ### Show PRD completion ```bash jq '.prds | to_entries | .[] | "\(.key): \(.value.status)"' docs/blueprint/feature-tracker.json ``` ### List features by phase ```bash jq -r '.. | objects | select(.phase == "phase-1") | .name' docs/blueprint/feature-tracker.json ``` ### Count features by status ```bash 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`: ```bash 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: ```json { "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: ```json { "name": "Terrain Visual Enhancement", "status": "complete", "prd": "PRD_TERRAIN_VISUAL_ENHANCEMENT" } ``` PRDs track which features they implement: ```json { "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: ```bash /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`: ```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: ```json { "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.