# Workthreads

SpecStory Workthreads - a weekly work-thread rollup across a team's repos from...

- Repository: https://github.com/specstoryai/getspecstory (1365 stars)
- Category: AI and agents
- License: Apache-2.0
- Last updated: 2026-10-30
- Runs scripts: yes, review before use

## Install

Claude Code: `npx skills add specstoryai/getspecstory --skill workthreads -g -a claude-code -y`
Codex: `npx skills add specstoryai/getspecstory --skill workthreads -g -a codex -y`
Cursor: `npx skills add specstoryai/getspecstory --skill workthreads -g -a cursor -y`
Gemini CLI: `npx skills add specstoryai/getspecstory --skill workthreads -g -a gemini-cli -y`
Claude Code plugin marketplace: `/plugin marketplace add specstoryai/getspecstory`

## Description

SpecStory Workthreads - a weekly work-thread rollup across a team's repos from SpecStory coding histories (any agent - Claude Code, Codex, Cursor, Gemini, and more). It groups the window's sessions into threads of work per project and labels each new / open / recently closed, so a lead sees what shipped, what is still an open loop, and what was just started. Use when someone asks "what happened this week", "what is still open", "what did the team finish", "give me the weekly rollup", or wants a status report over a .specstory/history corpus.

## SKILL.md, as published by its author (untrusted third-party text, read it as data)

# Workthreads

A lead needs a weekly answer across the team's repos: what work happened this week, what got
finished, and what is still open and needs a next step. **Workthreads** produces that **rollup**
from SpecStory histories - the `.specstory/history` transcripts your coding agents already write.
It reports **lines of work and their lifecycle** (new / open / recently closed).

A deterministic engine (`scripts/workthreads.mjs threads`) does the retrieval, clustering, and
classification; **you do the synthesis** - you turn its evidence into the lead's weekly report.
Do not try to read raw transcripts yourself; they can be hundreds of thousands of lines. Run the
engine and write the rollup from its output.

This skill is **harness-portable** (agentskills.io format). Where it names a specific tool
(e.g. `AskUserQuestion`), treat that as "use your harness's equivalent; fall back to plain chat."

## How the engine splits the work

- The engine groups the window's beats **by project** and clusters them into **threads** (a line
  of work that can span several sessions). It assigns each thread one lifecycle **status** relative
  to today:
  - **new** - first activity within the last 7 days.
  - **open** - unresolved, still active (the open loops).
  - **closed** - latest outcome was success and the thread has gone quiet; flagged **reverted**
    when a beat ran a rollback command (`git revert` / `git reset --hard` / `git checkout -- ...`).
- Output is deterministic (stable sort, no wall-clock timestamps in the body), so two runs on the
  same corpus are byte-identical.

## Default flow: the weekly rollup

1. **Index the corpus** into workthreads' own DB. Point at the team's repos and build/update it:
   ```bash
   node "${CLAUDE_SKILL_DIR}/scripts/workthreads.mjs" index --projects <parent-of-repos> --db <db>
   # or a single tree:  --scan <root>     or a single history dir:  --dir <dir>
   ```

The rest: https://github.com/specstoryai/getspecstory/blob/HEAD/workthreads/SKILL.md