specstory-project-stats

name	specstory-project-stats
description	Fetch project statistics from SpecStory Cloud. Run when user says "get project stats", "show SpecStory stats", "project statistics", "how many sessions", or "SpecStory metrics".
license	Apache-2.0
metadata	{"author":"SpecStory, Inc.","version":"1.0.0"}
allowed-tools	Bash(node *)

SpecStory Project Stats

Fetches project statistics from SpecStory's cloud platform, showing contributor counts, session activity, and other project metrics.

How It Works

1. Identifies the project via .specstory/.project.json, git remote, or folder name
2. Calls the SpecStory Cloud API
3. Returns project statistics in JSON format
4. Presents the data in a readable summary

Prerequisites

• Project must be synced to SpecStory Cloud
• Node.js must be available to run the script

Usage

Slash Command

User says	Action
/specstory-project-stats	Fetch stats for current project
/specstory-project-stats	Same as above (no arguments needed)

Direct Script Usage

# Fetch stats for current project
node skills/specstory-project-stats/scripts/get-stats.js

# With custom API endpoint (for development)
SPECSTORY_API_URL=http://localhost:5173 node skills/specstory-project-stats/scripts/get-stats.js

Output

The script outputs JSON with project statistics:

{
  "project_id": "specstoryai/agent-skills",
  "sessions": {
    "total": 156,
    "last_30_days": 47,
    "last_7_days": 12
  },
  "contributors": {
    "total": 5,
    "active_last_30_days": 3
  },
  "activity": {
    "first_session": "2025-10-15",
    "last_session": "2026-01-28",
    "avg_sessions_per_week": 8.2
  }
}

Project ID Resolution

The script determines project ID in this order:

1. .specstory/.project.json - Uses git_id or workspace_id field
2. Git remote - Extracts repo name from origin remote URL
3. Folder name - Falls back to current directory name

Error Handling

Error	Meaning	Action
404	Project not found	Project needs to sync to SpecStory Cloud first
401	Unauthorized	API endpoint may require authentication
Network error	Can't reach API	Check internet connection

Present Results to User

After fetching stats, present them in a friendly format:

Example Response (success)

Here are the stats for **specstoryai/agent-skills**:

**Sessions**
- Total: 156 sessions captured
- Last 30 days: 47 sessions
- Last 7 days: 12 sessions

**Contributors**
- Total: 5 contributors
- Active recently: 3

**Activity**
- First session: October 15, 2025
- Most recent: January 28, 2026
- Average: ~8 sessions per week

Your project has been actively using AI-assisted coding!

Example Response (404 error)

This project doesn't exist on SpecStory Cloud yet.

To get started:
1. Make sure you have SpecStory installed
2. Run `specstory sync` to push your local sessions to the cloud
3. Try this command again

Need help? Check the docs at https://docs.specstory.com

Environment Variables

Variable	Default	Description
SPECSTORY_API_URL	https://cloud.specstory.com	API endpoint

Notes

• Statistics are fetched from SpecStory Cloud, not local history
• Project must have synced sessions to show meaningful stats
• The API is public and doesn't require authentication for basic stats