Product-Tracking Skill

Defines methods for calculating feature completion, tracking progress, and managing development state.

What It Provides

Progress Calculation Methods

How to calculate feature completion percentage
Subtask weighting strategies
Overall progress formulas

State Tracking Structures

Completion data format
Quality gate status format
Feature status transitions

Priority Weighting

How to weight CRITICAL vs HIGH vs MEDIUM vs LOW
Priority-based task selection logic

Progress Formulas

Feature Progress

feature_progress = (completed_subtasks / total_subtasks) × 100

Overall Progress

overall_progress = weighted_average(all_feature_progress)
 
where weights:
  CRITICAL = 4x
  HIGH = 3x
  MEDIUM = 2x
  LOW = 1x

Quality Gate Factor

if any_critical_gate_failing:
  overall_progress = max(overall_progress - 10, 0)

State Structure

Completion Tracking

Stored in .agentful/completion.json:

{
  "features": {
    "User Authentication": {
      "status": "complete",
      "progress": 100,
      "priority": "CRITICAL",
      "subtasks": {
        "registration": "complete",
        "login": "complete",
        "password_reset": "complete"
      }
    },
    "User Profiles": {
      "status": "in_progress",
      "progress": 45,
      "priority": "HIGH",
      "subtasks": {
        "profile_page": "complete",
        "avatar_upload": "in_progress",
        "settings": "pending"
      }
    }
  },
  "gates": {
    "tests_passing": true,
    "no_type_errors": false,
    "no_dead_code": true,
    "coverage_80": false,
    "security_clean": true
  },
  "overall": 67
}

Status Values

pending - Not started
in_progress - Actively working
complete - All subtasks done, quality gates passed
blocked - Waiting on decision or external dependency

How Agents Use This

Orchestrator Agent:

Reads this skill for progress calculation methods
Calculates next task based on priority weighting
Updates completion.json after each task
Uses progress to determine if more work needed

Status Command:

Reads completion.json
Formats progress report using display patterns from skill
Shows quality gate status

Product Structure Support

Product Specification (.claude/product/)

.claude/product/
├── index.md           # Features for simple projects
└── domains/           # Domains for complex projects
    ├── authentication/
    │   └── index.md
    └── profiles/
        └── index.md

Parsing:

Read index.md for features or domain list
If domains exist, parse each domain/index.md
Calculate progress per feature/domain
Aggregate using priority weights

Feature Format:

## Features
 
### User Authentication - CRITICAL
- [x] Registration
- [x] Login
- [ ] Password Reset
 
### User Profiles - HIGH
- [ ] Profile Page
- [ ] Avatar Upload

Calculation:

Find heading with priority tag
Count checkboxes (total)
Count checked boxes (complete)
Calculate: (checked / total) × 100

Priority-Based Selection

When selecting next task:

1. Find all pending/in_progress features
2. Sort by priority (CRITICAL → HIGH → MEDIUM → LOW)
3. Within same priority, sort by dependencies
4. Select highest priority unblocked feature

Example:

Available tasks:
- API Integration (HIGH, 0%, pending)
- User Profiles (HIGH, 45%, in_progress)
- Dashboard (MEDIUM, 0%, pending)
 
Selection: User Profiles (same HIGH priority, but in_progress = continue)

Quality Gate Tracking

Quality gates from validation skill:

{
  "tests_passing": true,      // All tests pass
  "no_type_errors": false,    // Type checker clean
  "no_lint_errors": true,     // Linter clean
  "no_dead_code": true,       // No unused code
  "coverage_80": false,       // ≥80% coverage
  "security_clean": true      // No vulnerabilities
}

Impact on completion:

Feature at 100% but gates failing → Status remains "in_progress"
All features at 100% and gates passing → Product "complete"

Progress Display Patterns

Terminal Output

Progress:
  ████████░░░░░░░░░░░ 67%
 
Features:
✅ User Authentication  100%  CRITICAL
🔄 User Profiles         45%  HIGH
⏸  API Integration       0%  MEDIUM

Status Symbols

✅ Complete
🔄 In Progress
⏸ Pending
⛔ Blocked

Quality Gates Display

Quality Gates:
  ✅ Tests Passing
  ❌ Type Errors (3 errors)
  ⚠️  Coverage (76% - target: 80%)
  ✅ Linting
  ✅ Dead Code
  ✅ Security

Implementation Details

Location: .claude/skills/product-tracking/SKILL.md

Model: Sonnet

Tools Used:

Read (completion state, product spec)
Write (update completion.json)
Edit (modify feature status)
Glob (find domain files)
Grep (search for features)

Files:

.agentful/completion.json - Progress data
.agentful/state.json - Current work state
.claude/product/ - Product specification

Update Procedures

After Subtask Completion

1. Update subtask status to "complete"
2. Recalculate feature progress
3. If all subtasks complete AND gates pass:
   - Set feature status to "complete"
4. Recalculate overall progress
5. Write to completion.json

After Quality Gate Check

1. Read validation results
2. Update gates object in completion.json
3. If gates failing:
   - Keep features in "in_progress" even if subtasks done
4. Recalculate overall progress with gate factor

Examples

Initial State

{
  "features": {},
  "gates": {
    "tests_passing": false,
    "no_type_errors": false,
    "no_dead_code": false,
    "coverage_80": false,
    "security_clean": false
  },
  "overall": 0
}

After First Feature

{
  "features": {
    "User Authentication": {
      "status": "complete",
      "progress": 100,
      "priority": "CRITICAL"
    }
  },
  "gates": {
    "tests_passing": true,
    "no_type_errors": true,
    "no_dead_code": true,
    "coverage_80": true,
    "security_clean": true
  },
  "overall": 100
}

Partial Completion with Gate Failures

{
  "features": {
    "Authentication": {"status": "complete", "progress": 100, "priority": "CRITICAL"},
    "Profiles": {"status": "in_progress", "progress": 100, "priority": "HIGH"}
  },
  "gates": {
    "tests_passing": true,
    "no_type_errors": false,  // ← Failing
    "no_dead_code": true,
    "coverage_80": false,     // ← Failing
    "security_clean": true
  },
  "overall": 90  // Would be 100, but gates reduce it
}

Note: Profiles shows 100% subtasks but status is "in_progress" because gates failing.

Usage by Commands

/agentful-status

Primary consumer for display
Reads completion.json
Formats using display patterns from this skill

/agentful-start

Updates completion.json as work progresses
Uses priority selection logic

Orchestrator Agent

Uses priority weighting to select next task
Updates progress after each task completion

Extending the Skill

Add custom progress metrics by editing .claude/skills/product-tracking/SKILL.md:

## Custom Metric: Documentation Coverage
 
Formula:
\`\`\`
doc_coverage = (documented_features / total_features) × 100
\`\`\`
 
Storage:
\`\`\`json
{
  "custom_metrics": {
    "documentation_coverage": 85
  }
}
\`\`\`
 
Display:
\`\`\`
Custom Metrics:
  📚 Documentation: 85%
\`\`\`