HtmlGraph Tracker Skill

Use this skill when HtmlGraph is tracking the session to ensure proper activity attribution and documentation. This skill should be activated at session start via the SessionStart hook.

📚 REQUIRED READING

→ READ ../../../AGENTS.md FOR COMPLETE SDK DOCUMENTATION

The root AGENTS.md file contains:

✅ Python SDK Quick Start - Installation, initialization, basic operations
✅ Deployment Instructions - Using deploy-all.sh script
✅ API & CLI Reference - Alternative interfaces
✅ Best Practices - Patterns for AI agents
✅ Complete Workflow Examples - End-to-end scenarios

This file (SKILL.md) contains Claude Code-specific instructions only.

For SDK usage, deployment, and general agent workflows → USE AGENTS.md

When to Activate This Skill

At the start of every session when HtmlGraph plugin is enabled
When the user asks about tracking, features, or session management
When drift detection warnings appear
When the user mentions htmlgraph, features, sessions, or activity tracking
When discussing work attribution or documentation

Trigger keywords: htmlgraph, feature tracking, session tracking, drift detection, activity log, work attribution, feature status, session management

Core Responsibilities

1. Use SDK, Not MCP Tools (CRITICAL)

IMPORTANT: For Claude Code, use the Python SDK directly instead of MCP tools.

Why SDK over MCP:

✅ No context bloat - MCP tool schemas consume precious tokens
✅ Runtime discovery - Explore all operations via Python introspection
✅ Type hints - See all available methods without schemas
✅ More powerful - Full programmatic access, not limited to 3 MCP tools
✅ Faster - Direct Python, no JSON-RPC overhead

The SDK provides access to ALL HtmlGraph operations without adding tool definitions to your context.

ABSOLUTE RULE: You must NEVER use Read, Write, or Edit tools on .htmlgraph/ HTML files.

AI agents MUST use the SDK (or API/CLI for special cases) to ensure all HTML is validated through Pydantic + justhtml.

❌ FORBIDDEN:

# NEVER DO THIS
Write('/path/to/.htmlgraph/features/feature-123.html', ...)
Edit('/path/to/.htmlgraph/sessions/session-456.html', ...)
with open('.htmlgraph/features/feature-123.html', 'w') as f:
    f.write('<html>...</html>')

✅ REQUIRED - Use SDK (BEST CHOICE FOR AI AGENTS):

from htmlgraph import SDK

sdk = SDK(agent="claude")

# Work with ANY collection (features, bugs, chores, spikes, epics, phases)
sdk.features    # Features with builder support
sdk.bugs        # Bug reports
sdk.chores      # Maintenance tasks
sdk.spikes      # Investigation spikes
sdk.epics       # Large bodies of work
sdk.phases      # Project phases

# Create features (fluent interface)
feature = sdk.features.create("Title") \
    .set_priority("high") \
    .add_steps(["Step 1", "Step 2"]) \
    .save()

# Edit ANY collection (auto-saves)
with sdk.features.edit("feature-123") as f:
    f.status = "done"

with sdk.bugs.edit("bug-001") as bug:
    bug.status = "in-progress"
    bug.priority = "critical"

# Vectorized batch updates (efficient!)
sdk.bugs.batch_update(
    ["bug-001", "bug-002", "bug-003"],
    {"status": "done", "resolution": "fixed"}
)

# Query across collections
high_priority = sdk.features.where(status="todo", priority="high")
in_progress_bugs = sdk.bugs.where(status="in-progress")

# All collections have same interface
sdk.chores.mark_done(["chore-1", "chore-2"])
sdk.spikes.assign(["spike-1"], agent="claude")

Why SDK is best:

✅ 3-16x faster than CLI (no process startup)
✅ Type-safe with auto-complete
✅ Context managers (auto-save)
✅ Vectorized batch operations
✅ Works offline (no server needed)
✅ Supports ALL collections (features, bugs, chores, spikes, epics, etc.)

✅ ALTERNATIVE - Use CLI (for one-off commands):

# CLI is slower (400ms startup per command) but convenient for one-off queries
uv run htmlgraph feature create/start/complete
uv run htmlgraph status

⚠️ AVOID - API/curl (use only for remote access):

# Requires server + network overhead, only use for remote access
curl -X PATCH localhost:8080/api/features/feat-123 -d '{"status": "done"}'

Why this matters:

Direct file edits bypass Pydantic validation
Bypass justhtml HTML generation (can create invalid HTML)
Break the SQLite index sync
Skip event logging and activity tracking
Can corrupt graph structure and relationships

NO EXCEPTIONS: NEVER read, write, or edit .htmlgraph/ files directly.

Use the SDK for ALL operations including inspection:

# ✅ CORRECT - Inspect sessions/events via SDK
from htmlgraph import SDK
from htmlgraph.session_manager import SessionManager

sdk = SDK(agent="claude-code")
sm = SessionManager()

# Get current session
session = sm.get_active_session(agent="claude-code")

# Get recent events (last 10)
recent = session.get_events(limit=10, offset=session.event_count - 10)
for evt in recent:
    print(f"{evt['event_id']}: {evt['tool']} - {evt['summary']}")

# Query events by tool
bash_events = session.query_events(tool='Bash', limit=20)

# Query events by feature
feature_events = session.query_events(feature_id='feat-123')

# Get event statistics
stats = session.event_stats()
print(f"Total: {stats['total_events']}, Tools: {stats['tools_used']}")

❌ FORBIDDEN - Reading files directly:

# NEVER DO THIS
with open('.htmlgraph/events/session-123.jsonl') as f:
    events = [json.loads(line) for line in f]

# NEVER DO THIS
tail -10 .htmlgraph/events/session-123.jsonl

Documentation:

Complete SDK guide: docs/SDK_FOR_AI_AGENTS.md
Event inspection: docs/SDK_EVENT_INSPECTION.md
Agent best practices: docs/AGENTS.md

2. Feature Awareness (MANDATORY)

You MUST always know which feature(s) are currently in progress:

Check active features at session start (use uv run htmlgraph status)
Reference the current feature when discussing work
Alert immediately if work appears to drift from the assigned feature

3. Step Completion (CRITICAL)

Mark each step complete IMMEDIATELY after finishing it:

Use SDK to complete individual steps as you finish them
Step 0 = first step, step 1 = second step (0-based indexing)
Do NOT wait until all steps are done - mark each one as you finish
See "How to Mark Steps Complete" section below for exact commands

4. Continuous Tracking (CRITICAL)

ABSOLUTE REQUIREMENT: ALL work MUST be tracked in HtmlGraph.

Think of HtmlGraph tracking like Git commits - you wouldn't do work without committing it, and you shouldn't do work without tracking it.

Every time you complete work, update HtmlGraph immediately:

✅ Finished a step? → Mark it complete in SDK
✅ Fixed a bug? → Update bug status
✅ Discovered a decision? → Document it in the feature
✅ Changed approach? → Note it in activity log
✅ Completed a task? → Mark feature/bug/chore as done

Why this matters:

Attribution ensures work isn't lost across sessions
Links between sessions and features preserve context
Drift detection helps catch scope creep early
Analytics show real progress, not guesses

The hooks track tool usage automatically, but YOU must:

Start features before working (uv run htmlgraph feature start <id>)
Mark steps complete as you finish them (use SDK)
Complete features when done (uv run htmlgraph feature complete <id>)

5. Activity Attribution

HtmlGraph automatically tracks tool usage, but you should:

Use descriptive summaries in Bash description parameter
Reference feature IDs in commit messages
Mention the feature context when starting new tasks

6. Documentation Habits

For every significant piece of work:

Summarize what was done and why
Note any decisions made and alternatives considered
Record blockers or dependencies discovered

Working with Tracks, Specs, and Plans

What Are Tracks?

Tracks are high-level containers for multi-feature work (conductor-style planning):

Track = Overall initiative with multiple related features
Spec = Detailed specification with requirements and acceptance criteria
Plan = Implementation plan with phases and estimated tasks
Features = Individual work items linked to the track

When to create a track:

Work involves 3+ related features
Need high-level planning before implementation
Multi-phase implementation
Coordination across multiple sessions or agents

When to skip tracks:

Single feature work
Quick fixes or enhancements
Direct implementation without planning phase

Creating Tracks with TrackBuilder (PRIMARY METHOD)

IMPORTANT: Use the TrackBuilder for deterministic track creation with minimal effort.

The TrackBuilder provides a fluent API that auto-generates IDs, timestamps, file paths, and HTML files.

from htmlgraph import SDK

sdk = SDK(agent="claude")

# Create complete track with spec and plan in one command
track = sdk.tracks.builder() \
    .title("User Authentication System") \
    .description("Implement OAuth 2.0 authentication with JWT") \
    .priority("high") \
    .with_spec(
        overview="Add secure authentication with OAuth 2.0 support for Google and GitHub",
        context="Current system has no authentication. Users need secure login with session management.",
        requirements=[
            ("Implement OAuth 2.0 flow", "must-have"),
            ("Add JWT token management", "must-have"),
            ("Create user profile endpoint", "should-have"),
            "Add password reset functionality"  # Defaults to "must-have"
        ],
        acceptance_criteria=[
            ("Users can log in with Google/GitHub", "OAuth integration test passes"),
            "JWT tokens expire after 1 hour",
            "Password reset emails sent within 5 minutes"
        ]
    ) \
    .with_plan_phases([
        ("Phase 1: OAuth Setup", [
            "Configure OAuth providers (1h)",
            "Implement OAuth callback (2h)",
            "Add state verification (1h)"
        ]),
        ("Phase 2: JWT Integration", [
            "Create JWT signing logic (2h)",
            "Add token refresh endpoint (1.5h)",
            "Implement token validation middleware (2h)"
        ]),
        ("Phase 3: User Management", [
            "Create user profile endpoint (3h)",
            "Add password reset flow (4h)",
            "Write integration tests (3h)"
        ])
    ]) \
    .create()

# Output:
# ✓ Created track: track-20251221-220000
#   - Spec with 4 requirements
#   - Plan with 3 phases, 9 tasks

# Files created automatically:
# .htmlgraph/tracks/track-20251221-220000/index.html  (track metadata)
# .htmlgraph/tracks/track-20251221-220000/spec.html   (specification)
# .htmlgraph/tracks/track-20251221-220000/plan.html   (implementation plan)

TrackBuilder Features:

✅ Auto-generates track IDs with timestamps
✅ Creates index.html, spec.html, plan.html automatically
✅ Parses time estimates from task descriptions "Task (2h)"
✅ Validates requirements and acceptance criteria via Pydantic
✅ Fluent API with method chaining
✅ Single .create() call generates everything

Linking Features to Tracks

After creating a track, link features to it:

from htmlgraph import SDK

sdk = SDK(agent="claude")

# Get the track ID from the track you created
track_id = "track-20251221-220000"

# Create features and link to track
oauth_feature = sdk.features.create("OAuth Integration") \
    .set_track(track_id) \
    .set_priority("high") \
    .add_steps([
        "Configure OAuth providers",
        "Implement OAuth callback",
        "Add state verification"
    ]) \
    .save()

jwt_feature = sdk.features.create("JWT Token Management") \
    .set_track(track_id) \
    .set_priority("high") \
    .add_steps([
        "Create JWT signing logic",
        "Add token refresh endpoint",
        "Implement validation middleware"
    ]) \
    .save()

# Features are now linked to the track
# Query features by track:
track_features = sdk.features.where(track=track_id)
print(f"Track has {len(track_features)} features")

The track_id field:

Links features to their parent track
Enables track-level progress tracking
Used for querying related features
Automatically indexed for fast lookups

Track Workflow Example

Complete workflow from track creation to feature completion:

from htmlgraph import SDK

sdk = SDK(agent="claude")

# 1. Create track with spec and plan
track = sdk.tracks.builder() \
    .title("API Rate Limiting") \
    .description("Protect API endpoints from abuse") \
    .priority("critical") \
    .with_spec(
        overview="Implement rate limiting to prevent API abuse",
        context="Current API has no limits, vulnerable to DoS attacks",
        requirements=[
            ("Implement token bucket algorithm", "must-have"),
            ("Add Redis for distributed limiting", "must-have"),
            ("Create rate limit middleware", "must-have")
        ],
        acceptance_criteria=[
            ("100 requests/minute per API key", "Load test passes"),
            "429 status code when limit exceeded"
        ]
    ) \
    .with_plan_phases([
        ("Phase 1: Core", ["Token bucket (3h)", "Redis client (1h)"]),
        ("Phase 2: Integration", ["Middleware (2h)", "Error handling (1h)"]),
        ("Phase 3: Testing", ["Unit tests (2h)", "Load tests (3h)"])
    ]) \
    .create()

# 2. Create features from plan phases
for phase_idx, (phase_name, tasks) in enumerate([
    ("Core Implementation", ["Implement token bucket", "Add Redis client"]),
    ("API Integration", ["Create middleware", "Add error handling"]),
    ("Testing & Validation", ["Write unit tests", "Run load tests"])
]):
    feature = sdk.features.create(phase_name) \
        .set_track(track.id) \
        .set_priority("critical") \
        .add_steps(tasks) \
        .save()
    print(f"✓ Created feature {feature.id} for track {track.id}")

# 3. Work on features
# Start first feature
first_feature = sdk.features.where(track=track.id, status="todo")[0]
with sdk.features.edit(first_feature.id) as f:
    f.status = "in-progress"

# ... do the work ...

# Mark steps complete as you finish them
with sdk.features.edit(first_feature.id) as f:
    f.steps[0].completed = True

# Complete feature when done
with sdk.features.edit(first_feature.id) as f:
    f.status = "done"

# 4. Track progress
track_features = sdk.features.where(track=track.id)
completed = len([f for f in track_features if f.status == "done"])
print(f"Track progress: {completed}/{len(track_features)} features complete")

TrackBuilder API Reference

Methods:

.title(str) - Set track title (REQUIRED)
.description(str) - Set description (optional)
.priority(str) - Set priority: "low", "medium", "high", "critical" (default: "medium")
.with_spec(...) - Add specification (optional)
- overview - High-level summary
- context - Background and current state
- requirements - List of (description, priority) tuples or strings
  - Priorities: "must-have", "should-have", "nice-to-have"
- acceptance_criteria - List of (description, test_case) tuples or strings
.with_plan_phases(list) - Add plan phases (optional)
- Format: [(phase_name, [task_descriptions]), ...]
- Task estimates: Include (Xh) in description, e.g., "Implement auth (3h)"
.create() - Execute build and create all files (returns Track object)

Documentation:

Quick start: docs/TRACK_BUILDER_QUICK_START.md
Complete workflow: docs/TRACK_WORKFLOW.md
Full proposal: docs/AGENT_FRIENDLY_SDK.md

Working with HtmlGraph

RECOMMENDED: Use the Python SDK for AI agents (cleanest, fastest, most powerful)

Python SDK (PRIMARY INTERFACE - Use This!)

The SDK supports ALL collections with a unified interface. Use it for maximum performance and type safety.

from htmlgraph import SDK

# Initialize (auto-discovers .htmlgraph)
sdk = SDK(agent="claude")

# ===== ALL COLLECTIONS SUPPORTED =====
# Features (with builder support)
feature = sdk.features.create("User Authentication") \
    .set_priority("high") \
    .add_steps([
        "Create login endpoint",
        "Add JWT middleware",
        "Write tests"
    ]) \
    .save()

# Bugs
with sdk.bugs.edit("bug-001") as bug:
    bug.status = "in-progress"
    bug.priority = "critical"

# Chores, Spikes, Epics - all work the same way
chore = sdk.chores.where(status="todo")[0]
spike_results = sdk.spikes.all()
epic_steps = sdk.epics.get("epic-001").steps

# ===== EFFICIENT BATCH OPERATIONS =====
# Mark multiple items done (vectorized!)
sdk.bugs.mark_done(["bug-001", "bug-002", "bug-003"])

# Assign multiple items to agent
sdk.features.assign(["feat-001", "feat-002"], agent="claude")

# Custom batch updates (any attributes)
sdk.chores.batch_update(
    ["chore-001", "chore-002"],
    {"status": "done", "agent_assigned": "claude"}
)

# ===== CROSS-COLLECTION QUERIES =====
# Find all in-progress work
in_progress = []
for coll_name in ['features', 'bugs', 'chores', 'spikes', 'epics']:
    coll = getattr(sdk, coll_name)
    in_progress.extend(coll.where(status='in-progress'))

# Find low-lift tasks
for item in in_progress:
    if hasattr(item, 'steps'):
        for step in item.steps:
            if not step.completed and 'document' in step.description.lower():
                print(f"📝 {item.id}: {step.description}")

SDK Performance (vs CLI):

Single query: 3x faster
5 queries: 9x faster
10 batch updates: 16x faster

CLI (For One-Off Commands Only)

IMPORTANT: Always use uv run when running htmlgraph commands to ensure the correct environment.

⚠️ CLI is slower than SDK (400ms startup per command). Use for quick one-off queries only.

# Check Current Status
uv run htmlgraph status
uv run htmlgraph feature list

# Start Working on a Feature
uv run htmlgraph feature start <feature-id>

# Set Primary Feature (when multiple are active)
uv run htmlgraph feature primary <feature-id>

# Complete a Feature
uv run htmlgraph feature complete <feature-id>

When to use CLI vs SDK:

CLI: Quick one-off shell command
SDK: Everything else (faster, more powerful, better for scripts)

Strategic Planning & Dependency Analytics

NEW: HtmlGraph now provides intelligent analytics to help you make smart decisions about what to work on next.

Quick Start: Get Recommendations

from htmlgraph import SDK

sdk = SDK(agent="claude")

# Get smart recommendations on what to work on
recs = sdk.recommend_next_work(agent_count=1)
if recs:
    best = recs[0]
    print(f"💡 Work on: {best['title']}")
    print(f"   Score: {best['score']:.1f}")
    print(f"   Why: {', '.join(best['reasons'])}")

Available Strategic Planning Features

1. Find Bottlenecks 🚧

Identify tasks blocking the most downstream work:

bottlenecks = sdk.find_bottlenecks(top_n=5)

for bn in bottlenecks:
    print(f"{bn['title']} blocks {bn['blocks_count']} tasks")
    print(f"Impact score: {bn['impact_score']}")

Returns: List of dicts with id, title, status, priority, blocks_count, impact_score, blocked_tasks

2. Get Parallel Work ⚡

Find tasks that can be worked on simultaneously:

parallel = sdk.get_parallel_work(max_agents=5)

print(f"Can work on {parallel['max_parallelism']} tasks at once")
print(f"Ready now: {parallel['ready_now']}")

Returns: Dict with max_parallelism, ready_now, total_ready, level_count, next_level

3. Recommend Next Work 💡

Get smart recommendations considering priority, dependencies, and impact:

recs = sdk.recommend_next_work(agent_count=3)

for rec in recs:
    print(f"{rec['title']} (score: {rec['score']})")
    print(f"Reasons: {rec['reasons']}")
    print(f"Unlocks: {rec['unlocks_count']} tasks")

Returns: List of dicts with id, title, priority, score, reasons, estimated_hours, unlocks_count, unlocks

4. Assess Risks ⚠️

Check for dependency-related risks:

risks = sdk.assess_risks()

if risks['high_risk_count'] > 0:
    print(f"Warning: {risks['high_risk_count']} high-risk tasks")
    for task in risks['high_risk_tasks']:
        print(f"  {task['title']}: {task['risk_factors']}")

if risks['circular_dependencies']:
    print("Circular dependencies detected!")

Returns: Dict with high_risk_count, high_risk_tasks, circular_dependencies, orphaned_count, recommendations

5. Analyze Impact 📊

See what completing a task will unlock:

impact = sdk.analyze_impact("feature-001")

print(f"Unlocks {impact['completion_impact']:.1f}% of remaining work")
print(f"Affects {impact['total_impact']} downstream tasks")

Returns: Dict with node_id, direct_dependents, total_impact, completion_impact, unlocks_count, affected_tasks

Recommended Decision Flow

At the start of each work session:

from htmlgraph import SDK

sdk = SDK(agent="claude")

# 1. Check for bottlenecks
bottlenecks = sdk.find_bottlenecks(top_n=3)
if bottlenecks:
    print(f"⚠️  {len(bottlenecks)} bottlenecks found")

# 2. Get recommendations
recs = sdk.recommend_next_work(agent_count=1)
if recs:
    best = recs[0]
    print(f"\n💡 RECOMMENDED: {best['title']}")
    print(f"   Score: {best['score']:.1f}")
    print(f"   Reasons: {', '.join(best['reasons'][:2])}")

    # 3. Analyze impact
    impact = sdk.analyze_impact(best['id'])
    print(f"   Impact: Unlocks {impact['unlocks_count']} tasks")

# 4. Check for parallel work (if coordinating)
parallel = sdk.get_parallel_work(max_agents=3)
if parallel['total_ready'] > 1:
    print(f"\n⚡ {parallel['total_ready']} tasks available in parallel")

When to Use Each Feature

find_bottlenecks(): At session start, during sprint planning
recommend_next_work(): When deciding what task to pick up
get_parallel_work(): When coordinating multiple agents
assess_risks(): During project health checks, before milestones
analyze_impact(): When choosing between high-effort tasks

Advanced: Direct Analytics Access

For advanced use cases, access the full analytics engine:

# Access Pydantic models with all fields
analytics = sdk.dep_analytics

bottlenecks = analytics.find_bottlenecks(top_n=5, min_impact=1.0)
parallel = analytics.find_parallelizable_work(status="todo")
recs = analytics.recommend_next_tasks(agent_count=3, lookahead=5)
risk = analytics.assess_dependency_risk(spof_threshold=2)
impact = analytics.impact_analysis("feature-001")

See also: docs/AGENT_STRATEGIC_PLANNING.md for complete guide

Work Type Classification (Phase 1)

NEW: HtmlGraph now automatically categorizes all work by type to differentiate exploratory work from implementation.

Work Type Categories

All events are automatically tagged with a work type based on the active feature:

feature-implementation - Building new functionality (feat-*)
spike-investigation - Research and exploration (spike-*)
bug-fix - Correcting defects (bug-*)
maintenance - Refactoring and tech debt (chore-*)
documentation - Writing docs (doc-*)
planning - Design decisions (plan-*)
review - Code review
admin - Administrative tasks

Creating Spikes (Investigation Work)

Use Spike model for timeboxed investigation:

from htmlgraph import SDK, SpikeType

sdk = SDK(agent="claude")

# Create a spike with classification
spike = sdk.spikes.create("Investigate OAuth providers") \
    .set_spike_type(SpikeType.TECHNICAL) \
    .set_timebox_hours(4) \
    .add_steps([
        "Research OAuth 2.0 flow",
        "Compare Google vs GitHub providers",
        "Document security considerations"
    ]) \
    .save()

# Update findings after investigation
with sdk.spikes.edit(spike.id) as s:
    s.findings = "Google OAuth has better docs but GitHub has simpler integration"
    s.decision = "Use GitHub OAuth for MVP, migrate to Google later if needed"
    s.status = "done"

Spike Types:

TECHNICAL - Investigate technical implementation options
ARCHITECTURAL - Research system design decisions
RISK - Identify and assess project risks
GENERAL - Uncategorized investigation

Creating Chores (Maintenance Work)

Use Chore model for maintenance tasks:

from htmlgraph import SDK, MaintenanceType

sdk = SDK(agent="claude")

# Create a chore with classification
chore = sdk.chores.create("Refactor authentication module") \
    .set_maintenance_type(MaintenanceType.PREVENTIVE) \
    .set_technical_debt_score(7) \
    .add_steps([
        "Extract auth logic to separate module",
        "Add unit tests for auth flows",
        "Update documentation"
    ]) \
    .save()

Maintenance Types:

CORRECTIVE - Fix defects and errors
ADAPTIVE - Adapt to environment changes (OS, dependencies)
PERFECTIVE - Improve performance, usability, maintainability
PREVENTIVE - Prevent future problems (refactoring, tech debt)

Session Work Type Analytics

Query work type distribution for any session:

from htmlgraph import SDK

sdk = SDK(agent="claude")

# Get current session
from htmlgraph.session_manager import SessionManager
sm = SessionManager()
session = sm.get_active_session(agent="claude")

# Calculate work breakdown
breakdown = session.calculate_work_breakdown()
# Returns: {"feature-implementation": 120, "spike-investigation": 45, "maintenance": 30}

# Get primary work type
primary = session.calculate_primary_work_type()
# Returns: "feature-implementation" (most common type)

# Query events by work type
spike_events = [e for e in session.get_events() if e.get("work_type") == "spike-investigation"]

Automatic Work Type Inference

Work type is automatically inferred from feature_id prefix:

# When you start a spike:
sdk.spikes.start("spike-123")
# → All events auto-tagged with work_type="spike-investigation"

# When you start a feature:
sdk.features.start("feat-456")
# → All events auto-tagged with work_type="feature-implementation"

# When you start a chore:
sdk.chores.start("chore-789")
# → All events auto-tagged with work_type="maintenance"

No manual tagging required! The system automatically categorizes your work based on what you're working on.

Why This Matters

Work type classification enables you to:

Differentiate exploration from implementation - "How much time was spent researching vs building?"
Track technical debt - "What % of work is maintenance vs new features?"
Measure innovation - "What's our spike-to-feature ratio?"
Session context - "Was this primarily an exploratory session or implementation?"

Example Session Analysis:

# After a long session, analyze what you did:
session = sm.get_active_session(agent="claude")
breakdown = session.calculate_work_breakdown()

print(f"Primary work type: {session.calculate_primary_work_type()}")
print(f"Work breakdown: {breakdown}")

# Output:
# Primary work type: spike-investigation
# Work breakdown: {
#   "spike-investigation": 65,
#   "feature-implementation": 30,
#   "documentation": 10
# }
# → This was primarily an exploratory/research session

Feature Creation Decision Framework

CRITICAL: Use this framework to decide when to create a feature vs implementing directly.

Quick Decision Rule

Create a FEATURE if ANY apply:

Estimated >30 minutes of work
Involves 3+ files
Requires new automated tests
Affects multiple components
Hard to revert (schema, API changes)
Needs user/API documentation

Implement DIRECTLY if ALL apply:

Single file, obvious change
<30 minutes work
No cross-system impact
Easy to revert
No tests needed
Internal/trivial change

Decision Tree (Quick Reference)

User request received
  ├─ Bug in existing feature? → See Bug Fix Workflow in WORKFLOW.md
  ├─ >30 minutes? → CREATE FEATURE
  ├─ 3+ files? → CREATE FEATURE
  ├─ New tests needed? → CREATE FEATURE
  ├─ Multi-component impact? → CREATE FEATURE
  ├─ Hard to revert? → CREATE FEATURE
  └─ Otherwise → IMPLEMENT DIRECTLY

Examples

✅ CREATE FEATURE:

"Add user authentication" (multi-file, tests, docs)
"Implement session comparison view" (new UI, Playwright tests)
"Fix attribution drift algorithm" (complex, backend tests)

❌ IMPLEMENT DIRECTLY:

"Fix typo in README" (single file, trivial)
"Update CSS color" (single file, quick, reversible)
"Add missing import" (obvious fix, no impact)

Default Rule

When in doubt, CREATE A FEATURE. Over-tracking is better than losing attribution.

See docs/WORKFLOW.md for the complete decision framework with detailed criteria, thresholds, and edge cases.

Session Workflow Checklist

MANDATORY: Follow this checklist for EVERY session. No exceptions.

Session Start (DO THESE FIRST)

✅ Activate this skill (done automatically)
✅ RUN: uv run htmlgraph status - Check what's active
✅ Review active features and decide if you need to create a new one
✅ Greet user with brief status update
✅ DECIDE: Create feature or implement directly? (use decision framework below)
✅ If creating feature: Use SDK or run uv run htmlgraph feature start <id>

During Work (DO CONTINUOUSLY)

✅ Feature MUST be marked "in-progress" before you write any code
✅ CRITICAL: Mark each step complete IMMEDIATELY after finishing it (use SDK)
✅ Document ALL decisions as you make them
✅ Test incrementally - don't wait until the end
✅ Watch for drift warnings and act on them immediately

How to Mark Steps Complete

IMPORTANT: After finishing each step, mark it complete using the SDK:

from htmlgraph import SDK

sdk = SDK(agent="claude")

# Mark step 0 (first step) as complete
with sdk.features.edit("feature-id") as f:
    f.steps[0].completed = True

# Mark step 1 (second step) as complete
with sdk.features.edit("feature-id") as f:
    f.steps[1].completed = True

# Or mark multiple steps at once
with sdk.features.edit("feature-id") as f:
    f.steps[0].completed = True
    f.steps[1].completed = True
    f.steps[2].completed = True

Step numbering is 0-based (first step = 0, second step = 1, etc.)

When to mark complete:

✅ IMMEDIATELY after finishing a step
✅ Even if you continue working on the feature
✅ Before moving to the next step
❌ NOT at the end when all steps are done (too late!)

Example workflow:

Start feature: uv run htmlgraph feature start feature-123
Work on step 0 (e.g., "Design models")
MARK STEP 0 COMPLETE → Use SDK: with sdk.features.edit("feature-123") as f: f.steps[0].completed = True
Work on step 1 (e.g., "Create templates")
MARK STEP 1 COMPLETE → Use SDK: with sdk.features.edit("feature-123") as f: f.steps[1].completed = True
Continue until all steps done
Complete feature: uv run htmlgraph feature complete feature-123

Session End (MUST DO BEFORE MARKING COMPLETE)

✅ RUN TESTS: uv run pytest - All tests MUST pass
✅ VERIFY ATTRIBUTION: Check that activities are linked to correct feature
✅ CHECK STEPS: ALL feature steps MUST be marked complete
✅ CLEAN CODE: Remove all debug code, console.logs, TODOs
✅ COMMIT WORK: Git commit your changes IMMEDIATELY (allows user rollback)
- Do this BEFORE marking the feature complete
- Include the feature ID in the commit message
✅ COMPLETE FEATURE: Use SDK or run uv run htmlgraph feature complete <id>
✅ UPDATE EPIC: If part of epic, mark epic step complete

REMINDER: Completing a feature without doing all of the above means incomplete work. Don't skip steps.

Handling Drift Warnings

When you see a drift warning like:

Drift detected (0.74): Activity may not align with feature-self-tracking

Consider:

Is this expected? Sometimes work naturally spans multiple features
Should you switch features? Use uv run htmlgraph feature primary <id> to change attribution
Is the feature scope wrong? The feature's file patterns or keywords may need updating

Session Continuity

At the start of each session:

Review previous session summary (if provided)
Note current feature progress
Identify what remains to be done
Ask the user what they'd like to work on

At the end of each session:

The SessionEnd hook will generate a summary
All activities are preserved in .htmlgraph/sessions/
Feature progress is updated automatically

Best Practices

Commit Messages

Include feature context:

feat(feature-id): Description of the change

- Details about what was done
- Why this approach was chosen

🤖 Generated with Claude Code

Task Descriptions

When using Bash tool, always provide a description:

# Good - descriptive
Bash(description="Install dependencies for auth feature")

# Bad - no context
Bash(command="npm install")

Decision Documentation

When making architectural decisions:

Track with uv run htmlgraph track "Decision" "Chose X over Y because Z"
Or note in the feature's HTML file under activity log

Dashboard Access

View progress visually:

uv run htmlgraph serve
# Open http://localhost:8080

The dashboard shows:

Kanban board with feature status
Session history with activity logs
Graph visualization of dependencies

Key Files

.htmlgraph/features/ - Feature HTML files (the graph nodes)
.htmlgraph/sessions/ - Session HTML files with activity logs
index.html - Dashboard (open in browser)

Integration Points

HtmlGraph hooks track:

SessionStart: Creates session, provides feature context
PostToolUse: Logs every tool call with attribution
UserPromptSubmit: Logs user queries
SessionEnd: Finalizes session with summary

All data is stored as HTML files - human-readable, git-friendly, browser-viewable.

htmlgraph-tracker