Claude Cursor GitHub Copilot Skill

workthreads

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

LLM Mart · 0 points · 20 views 234 listing impressions 0 install-command copies
Download specstoryai-getspecstory-workthreads-1e49496.zip · 37 KB

Install

skills CLI npx skills add https://github.com/specstoryai/getspecstory/tree/dev/workthreads
Claude Code claude plugin marketplace add https://llmmart.ai/marketplace.json && claude plugin install specstoryai-getspecstory@llmmart
Git git clone https://github.com/specstoryai/getspecstory.git

The skills CLI installs just this skill, for any of its supported agents. Claude Code installs the whole specstoryai/getspecstory collection as a plugin from our marketplace. Git is the plain clone.

README

Workthreads

A weekly work-thread rollup from your SpecStory coding histories.

Workthreads reads the .specstory/history transcripts your coding agents already write and answers, at a glance: what happened this week, what got finished, and what is still open and needs a next step. It groups the window's sessions into threads of work per project and labels each one:

  • new - first activity within the last 7 days
  • open - unresolved, still active (the "open loops")
  • closed - latest outcome was success and it has gone quiet (flagged reverted when a beat ran a rollback command)

A lead can use it for a weekly standup; an individual can use it to re-orient after time away ("what was I in the middle of?").

How it clusters (deterministic, no LLM in the engine)

The engine is robust against both failure modes of naive clustering:

  • A session is one line of work - a long multi-prompt session collapses into one thread, not one-thread-per-prompt.
  • Cross-session merge needs >= 2 shared rare keys (a distinct file or symbol; ubiquitous files like package.json and short abbreviations are ignored) - so a single shared utility file or a plain word never bridges unrelated work.
  • Bounded threads - a hard session cap stops a whole codebase from chaining into one mega-thread.

Output is deterministic (stable sort, no wall-clock in the body), so two runs on the same corpus are byte-identical.

Install

From a clone of this repo:

cd workthreads
./install.sh

That bundles the engine and the skill into ~/.agents/skills/workthreads and symlinks it into ~/.claude/skills/workthreads, so /workthreads is available from any Claude Code session in any project. It is self-contained - it does not read from any other skill's directory. Re-run ./install.sh any time to update.

Requirements: Node >= 22.5 (for node:sqlite), and the SpecStory CLI capturing histories into .specstory/history/.

Use

Start a new Claude Code session (skills load at session start), then:

/workthreads

or just ask in plain English: "give me the weekly rollup", "what's still open?", "what did we finish this week?". With no arguments it asks three short questions - Scope (which repos), Window (how many days, default 7), Goal (full rollup / just open loops / recently closed / status) - then runs.

The digest groups threads by project under New / Open / Recently closed, each with evidence refs (path:line), last-activity date, and a one-line rationale. It is also saved to a dated file (.specstory/workthreads/<YYYY>-W<week>.md) so rollups are durable and diffable week over week.

Sample shape:

workthreads digest - 31 thread(s) across 3 active project(s) (window: last 7 days)

## marketing
  New
    - run the first-cut skill on the maker video  [new]  · last 2026-06-19 · 1 session, 20 beats
  Open
    - resend contact-topic sync still failing  [open]  · last 2026-06-20 · 2 sessions, 7 beats
  Recently closed
    - extract survey emails for non-solo respondents  [closed]  · last 2026-06-18 · 1 session, 6 beats

Develop

The engine is plain Node (ESM, zero dependencies, node:sqlite). Run the tests:

cd workthreads
npm test

License

Apache-2.0.

Skill manifest

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:

    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>
    
  2. Run threads cross-project for the last 7 days and capture the evidence:

    node "${CLAUDE_SKILL_DIR}/scripts/workthreads.mjs" threads --db <db> --days 7            # human digest
    node "${CLAUDE_SKILL_DIR}/scripts/workthreads.mjs" threads --db <db> --days 7 --json     # machine-readable
    

    The digest prints, per project, three sections in order - New, Open, Recently closed - each thread with its evidence refs (path:line), last-activity date, status, and a reverted marker. --json emits an array of threads (project, status, reverted, the files touched, last-activity date).

  3. Write the rollup from that evidence, in the lead's shape:

    • (a) a high-level result: session count and active projects in the window;
    • (b) per-project highlights of completed work (the closed threads);
    • (c) open loops - the open threads, unresolved or needing verification, with a suggested next step each;
    • (d) notable rollbacks / abandoned efforts (the reverted threads);
    • (e) cite evidence refs (path:line) so each claim is checkable. Add a caveat that the week may still be in progress, so open and new threads are snapshots, not final outcomes.
  4. Save it to a dated file so the rollup is durable and diffable week over week:

    .specstory/workthreads/<YYYY>-W<week>.md
    

    (ISO week number, e.g. .specstory/workthreads/2026-W25.md). Also offer threads --out <file> to drop the raw digest beside your written summary.

Guided start

If the user just invokes the skill with no specifics, ask three short questions (use AskUserQuestion or plain chat), then run the default flow with the answers:

  • Scope - which repos / parent directory holds the team's .specstory/history corpus?
  • Window - how many days back? (default 7 for the weekly rollup; --days N to widen.)
  • Goal - the whole rollup, just the open loops, just recently closed, or a quick status line? Tailor which sections you emphasize to the answer.

Conventions

Node ESM only, zero dependencies, Node >= 22.5. No em dashes anywhere (use " - "). The engine path never calls an LLM or the network; all judgment (the written narrative, suggested next steps, emphasis) is yours.

Files (getspecstory)
  • docs
    • 2026-06-24-WORKTHREADS-AS-BUILT.md 5.5 KB
      Loading…
  • fixtures
    • threads-bar
      • .specstory
        • history
          • 2026-06-06_09-00-00Z-scaffold-search-index.md 282 B
            Loading…
          • 2026-06-20_11-00-00Z-fix-search-index.md 354 B
            Loading…
          • 2026-06-21_15-00-00Z-start-notif-badge.md 273 B
            Loading…
    • threads-foo
      • .specstory
        • history
          • 2026-06-02_09-00-00Z-begin-checkout-flow.md 503 B
            Loading…
          • 2026-06-09_10-00-00Z-finish-checkout-flow.md 550 B
            Loading…
          • 2026-06-12_14-00-00Z-payment-retry-rollback.md 905 B
            Loading…
  • scripts
    • lib
      • db.mjs 3.8 KB · in bundle
      • discover.mjs 3.3 KB · in bundle
      • indexer.mjs 7.4 KB · in bundle
      • parse.mjs 10.4 KB · in bundle
      • patterns.mjs 14.4 KB · in bundle
      • threads.mjs 12.4 KB · in bundle
    • workthreads.mjs 3.3 KB · in bundle
  • tests
    • threads.test.mjs 8.4 KB · in bundle
  • install.sh 1.1 KB
    Loading…
  • package.json 304 B
    Loading…
  • README.md 3.2 KB
    # Workthreads
    
    _A weekly work-thread rollup from your SpecStory coding histories._
    
    Workthreads reads the `.specstory/history` transcripts your coding agents already
    write and answers, at a glance: **what happened this week, what got finished, and
    what is still open and needs a next step.** It groups the window's sessions into
    **threads of work per project** and labels each one:
    
    - **new** - first activity within the last 7 days
    - **open** - unresolved, still active (the "open loops")
    - **closed** - latest outcome was success and it has gone quiet (flagged
      **reverted** when a beat ran a rollback command)
    
    A lead can use it for a weekly standup; an individual can use it to re-orient after
    time away ("what was I in the middle of?").
    
    ## How it clusters (deterministic, no LLM in the engine)
    
    The engine is robust against both failure modes of naive clustering:
    
    - **A session is one line of work** - a long multi-prompt session collapses into one
      thread, not one-thread-per-prompt.
    - **Cross-session merge needs >= 2 shared *rare* keys** (a distinct file or symbol;
      ubiquitous files like `package.json` and short abbreviations are ignored) - so a
      single shared utility file or a plain word never bridges unrelated work.
    - **Bounded threads** - a hard session cap stops a whole codebase from chaining into
      one mega-thread.
    
    Output is deterministic (stable sort, no wall-clock in the body), so two runs on the
    same corpus are byte-identical.
    
    ## Install
    
    From a clone of this repo:
    
    ```zsh
    cd workthreads
    ./install.sh
    ```
    
    That bundles the engine and the skill into `~/.agents/skills/workthreads` and
    symlinks it into `~/.claude/skills/workthreads`, so `/workthreads` is available from
    **any** Claude Code session in **any** project. It is self-contained - it does not
    read from any other skill's directory. Re-run `./install.sh` any time to update.
    
    Requirements: Node >= 22.5 (for `node:sqlite`), and the SpecStory CLI capturing
    histories into `.specstory/history/`.
    
    ## Use
    
    Start a new Claude Code session (skills load at session start), then:
    
    ```
    /workthreads
    ```
    
    or just ask in plain English: _"give me the weekly rollup"_, _"what's still open?"_,
    _"what did we finish this week?"_. With no arguments it asks three short questions -
    **Scope** (which repos), **Window** (how many days, default 7), **Goal** (full rollup
    / just open loops / recently closed / status) - then runs.
    
    The digest groups threads by project under **New / Open / Recently closed**, each
    with evidence refs (`path:line`), last-activity date, and a one-line rationale. It is
    also saved to a dated file (`.specstory/workthreads/<YYYY>-W<week>.md`) so rollups are
    durable and diffable week over week.
    
    Sample shape:
    
    ```
    workthreads digest - 31 thread(s) across 3 active project(s) (window: last 7 days)
    
    ## marketing
      New
        - run the first-cut skill on the maker video  [new]  · last 2026-06-19 · 1 session, 20 beats
      Open
        - resend contact-topic sync still failing  [open]  · last 2026-06-20 · 2 sessions, 7 beats
      Recently closed
        - extract survey emails for non-solo respondents  [closed]  · last 2026-06-18 · 1 session, 6 beats
    ```
    
    ## Develop
    
    The engine is plain Node (ESM, zero dependencies, `node:sqlite`). Run the tests:
    
    ```zsh
    cd workthreads
    npm test
    ```
    
    ## License
    
    Apache-2.0.
    
  • SKILL.md 4.9 KB
    ---
    name: workthreads
    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.
    argument-hint: "Enter = guided setup · or plain English, e.g. 'last 7 days, just the open loops'"
    allowed-tools: Bash, Read, Write, AskUserQuestion
    license: Apache-2.0
    metadata:
      author: Greg Ceccarelli
      version: "1.0.0"
    ---
    
    # 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>
       ```
    
    2. **Run `threads` cross-project for the last 7 days** and capture the evidence:
       ```bash
       node "${CLAUDE_SKILL_DIR}/scripts/workthreads.mjs" threads --db <db> --days 7            # human digest
       node "${CLAUDE_SKILL_DIR}/scripts/workthreads.mjs" threads --db <db> --days 7 --json     # machine-readable
       ```
       The digest prints, per project, three sections in order - **New**, **Open**, **Recently
       closed** - each thread with its evidence refs (`path:line`), last-activity date, status, and a
       `reverted` marker. `--json` emits an array of threads (`project`, `status`, `reverted`, the files
       touched, last-activity date).
    
    3. **Write the rollup** from that evidence, in the lead's shape:
       - (a) a high-level result: session count and active projects in the window;
       - (b) per-project **highlights** of completed work (the `closed` threads);
       - (c) **open loops** - the `open` threads, unresolved or needing verification, with a suggested
         next step each;
       - (d) notable **rollbacks / abandoned efforts** (the `reverted` threads);
       - (e) cite evidence refs (`path:line`) so each claim is checkable.
       Add a caveat that **the week may still be in progress**, so `open` and `new` threads are
       snapshots, not final outcomes.
    
    4. **Save it to a dated file** so the rollup is durable and diffable week over week:
       ```
       .specstory/workthreads/<YYYY>-W<week>.md
       ```
       (ISO week number, e.g. `.specstory/workthreads/2026-W25.md`). Also offer `threads --out <file>`
       to drop the raw digest beside your written summary.
    
    ## Guided start
    
    If the user just invokes the skill with no specifics, ask three short questions (use
    `AskUserQuestion` or plain chat), then run the default flow with the answers:
    
    - **Scope** - which repos / parent directory holds the team's `.specstory/history` corpus?
    - **Window** - how many days back? (default **7** for the weekly rollup; `--days N` to widen.)
    - **Goal** - the whole **rollup**, just the **open loops**, just **recently closed**, or a quick
      **status** line? Tailor which sections you emphasize to the answer.
    
    ## Conventions
    
    Node ESM only, zero dependencies, Node >= 22.5. No em dashes anywhere (use " - "). The engine path
    never calls an LLM or the network; all judgment (the written narrative, suggested next steps,
    emphasis) is yours.
    

Comments (0)

Sign in to join the conversation.

No comments yet.

Reviews (0)

No reviews yet.