You run multi-day scoping or discovery workshops. The transcripts pile up, and by day 3 nobody can say with confidence what's agreed, what's still open, and what moved since yesterday. Thread Weaver keeps track of all of that for you.
It's a Claude Code skill that analyzes workshop transcripts to track a team's progress on a fixed set of functional threads across multiple workshop days. Its core discipline is record fidelity: every captured statement traces to something a participant explicitly said. If a facet wasn't discussed, it scores low and is flagged as open — it is never filled in with a plausible guess.
You give it each day's transcripts. It gives you, per day:
- Digests — a faithful per-transcript capture of what was explicitly said (never inferred), thread by thread, facet by facet;
- an Integral Analysis — the accumulated substance of every thread across all days so far, reconciled and scored (per-facet maturity on a 1–5 scale, scope stability, word-count coverage);
- an Integral Feedback — the actionable read of the Integral Analysis: what regressed, what firmed up, what's ready for sprint, and what tomorrow's session should focus on.
Why "Integral": the word is used in its mathematical sense — an accumulation. Each day's digests are that day's increment; the Integral is every day so far, added together and reconciled into one current picture. So you never read yesterday's file beside today's to work out where things stand — today's Integral already contains everything.
The four facets: every functional thread is read through the same four dimensions — 🪪 User's Name (who the user is: their role, in their words), 👷♀️ User's Goal (what that person must achieve to do their job), 🤕 Pain Points (what hurts them today), and ✋ Use Case (how they will use the solution — a sequence of actions, not a feature list). Each has to pass one test: does this sentence describe a person, or a piece of software? The facets are the atoms of the whole analysis — every score, readiness verdict and trend is built from them — which is also why maturity can't be faked by talking a lot about the product: if nobody said who it's for, 🪪 stays low no matter how rich the feature discussion was.
The three capture questions: for every facet, the analysis answers exactly three questions about what the room said. Agreed — what does the team explicitly share? Disagreement — what do members explicitly clash on? (This needs two asserted, incompatible positions — a hedged "maybe X… I don't know, actually" is not a position, it's ambiguity.) Still ambiguous — what stated substance is still vague? The distinction matters because each state calls for a different move from you the next morning: settled → validate and anchor it; contested → arbitrate it; vague → clarify it. In practice, the last two columns are your next session's agenda.
The skill has two modes, declared once per workshop cycle in a config file:
basic— the supported getting-started path, documented below. Daily cycle: Digests → Integral Analysis → Integral Feedback. Minimal setup (one config file you author yourself).advanced— adds a Day-0 baseline session, seven registers (five append-only capture logs — decisions, open questions, risks, action items, stakeholders — plus a scope-facets setup register and a per-day word-count register), and the cumulative Curve view. It ships in this repository and is fully specified inSKILL.mdandreference/, but it expects pre-workshop input files and more ceremony — start with basic.
A mode is fixed for the whole cycle; switching means starting a new cycle folder.
The rest of this guide — and the files the skill writes — use a handful of terms as settled vocabulary. Here they are in plain language, so you don't have to guess on first read:
| Term | Means |
|---|---|
| Session | One conversation with Claude Code, started fresh. Thread Weaver deliberately splits its work into several short sessions (see step 4) rather than one long one — you literally close the chat and open a new one between steps. |
| CONFIG file | The one file you write by hand (step 2 below) — just a markdown file listing your workshop's threads. |
| Digest | A faithful, per-transcript summary of what was explicitly said that day — nothing inferred. One per transcript. |
| Integral Analysis (IA) | The accumulated, scored picture of every thread across all days so far — reconciled from all the digests. "Integral" as in math: an accumulation, not a personality trait. |
| Integral Feedback (IF) | The actionable read of the IA: what regressed, what's ready, what to focus on next — read this one first. |
| Functional thread | One of the 3–6 topics your workshop tracks (you name these in the CONFIG file), e.g. "Maintenance Scheduling." |
| Facet | One of four fixed lenses every thread is scored on: 🪪 who the user is, 👷♀️ their goal, 🤕 their pain points, ✋ how they'd use the solution. |
| Maturity score | A 1–5 rating per facet, shown as a colored square: 🟫 1 · 🟥 2 · 🟨 3 · 🟩 4 · 🟦 5 — how well-understood that facet is so far. |
Colored-square and emoji meanings beyond this table (there are more, used across the output files) are all defined in docs/glyph-legend.md — open it any time a symbol in an output file is unclear.
New to Claude Code? It's Anthropic's command-line AI assistant — you type requests in plain English in a terminal, and it reads/writes files for you. Thread Weaver is a skill: a set of instructions that teaches Claude Code this specific workflow. You don't write any code yourself.
Before installing anything, open examples/fleetcare-demo/sample-output/ in this repo — it's a finished, real run of the whole basic-mode cycle (a fictional two-day workshop) that you can read right now:
Integral-Feedback-day0-to-day2.md— start here, it's the "what do I do next" fileIntegral-Analysis-day0-to-day2.md— the evidence behind it_digests/— the raw per-transcript captures both of those are built from
That's what you'll get from your own transcripts. If it looks useful, install below and run the same demo yourself with examples/fleetcare-demo/README.md.
- Copy this repository to
~/.claude/skills/thread-weaver(or your project's.claude/skills/thread-weaver). If you're not comfortable withgit clone, downloading the repo as a ZIP from GitHub and unzipping it into that folder works the same. - Copy
agents/thread-weaver-integral.mdto~/.claude/agents/(or your project's.claude/agents/) — it registers the analysis agent the Integral Analysis session uses by default. (A plain Finder/File Explorer copy is enough — this step doesn't need the terminal.) - Requirements: Claude Code with Bash available (the skill's output gates are shell scripts, run automatically at the end of each session — you don't run them yourself). If you don't have Claude Code installed yet, follow claude.com/claude-code first, then come back here. The skill declares
model: sonnetin its frontmatter (the metadata block between---lines at the top of a markdown file) — the analysis was tuned and validated on Sonnet.
What a run costs (measured on the demo above, on Sonnet): each session takes a few minutes, and a full workshop day — two transcripts through all three sessions — lands around 350–400k tokens, i.e. a dollar or two of API usage or a modest slice of a subscription.
One folder per workshop cycle. All outputs land inside it. Run Claude Code from this folder.
my-workshop/
├── CONFIG_list-of-functional-threads.md ← you author this (step 2)
├── day1/ ← this day's transcripts (step 3)
└── day2/
The one file you write by hand: the 3–6 functional threads the workshop is about, each with a short code. Create CONFIG_list-of-functional-threads.md at the cycle root — copy the block below and just edit the project: line and the table rows (leave everything else as-is):
---
skill: thread-weaver
mode: basic
format-version: v5.34
project: My Workshop
file-kind: functional-threads
---
# Functional Threads — My Workshop
| # | Code | Thread | One-line description |
|---|---|---|---|
| 1 | MNT | Maintenance Scheduling | Plan and assign maintenance work |
| 2 | ALT | Smart Alerts | Detect and route anomaly alerts |
| 3 | RPT | Fleet Reporting | Fleet-level status reporting |(format-version: v5.34 is current as of this README. If the skill ever tells you it's stale, the current value always lives in reference/format-rules.md under "Format Version" — but you shouldn't need to look that up for a first run.)
Rules the first run will validate (violations stop and ask — your codes are never silently changed):
- 3–6 threads, fixed for the whole cycle — every day is analyzed against the same set, so progress is directly comparable;
- each code 3–4 letters, unique, and not one of the reserved codes
SCP·PRD·DSG·TEC·ALL(taken by the built-in threads: Scope · Product · Design · Tech · plusALLfor cycle-wide items); mode: basicin the frontmatter is required — there is no default.
(Three cross-functional threads — 🧭 Product, 🎨 Design, 🛠️ Tech — plus the 🔭 Scope boundary are always analyzed on top of your functional threads; you don't configure them.)
Put each transcript as a .md file in a day folder (day1/, day2/, …). A transcript is positively identified by a frontmatter marker:
---
transcript: true
---
(transcript text…)Expect to add this yourself. Files exported from a meeting-capture tool usually arrive with the tool's own frontmatter and no transcript: key, so add the marker to each file before the first run. (If your capture tool stamps a distinctive key of its own — granola_id, say — you can instead list that key in an optional transcript-markers.local file at the skill root, one key per line, and skip the per-file marker.)
A file with no recognized marker isn't silently ingested or dropped — the skill asks you about it in chat.
Each step is deliberately its own session — keeping each session short and focused is what keeps the analysis reliable. Finish a step, open a new session, ask for the next.
Session 1: "Digests for day 1. Transcripts: <path>/day1"
Session 2: "Analysis for day 1"
Session 3: "Feedback for day 1"
- Session 1 — Digests. On the very first run, the skill validates your config and shows you the threads + codes to confirm in chat before anything runs. Then one sub-agent per transcript writes
_digests/day1/digest-<name>.mdand stops. - Session 2 — Integral Analysis. One analysis agent — the one you installed in Install step 2 — reads your config + all digests so far (day 1..N) and writes
Integral-Analysis-day0-to-day<N>.md: reconciled substance and scores for every thread. It's deliberately a single agent scoring everything, so scores stay comparable across threads and days. Ends by running its output gate (runtime/check-ia.sh). - Session 3 — Integral Feedback. Derives
Integral-Feedback-day0-to-day<N>.mdfrom that day's Integral Analysis: regressions since yesterday, take-aways, sprint readiness, next-session focus, session craft. Ends with its gate (runtime/check-if.sh).
Repeat for day 2, 3, … Each day writes new files; earlier days' files are never overwritten — together they are the narrative of how the team moved from confusion to clarity on each thread.
On demand, in any session: "diff day 1 vs day 3" — an ad-hoc comparison of two days' recorded readings, answered in chat, writing nothing.
| File | What it answers |
|---|---|
_digests/day<N>/digest-*.md |
What was said that day — per transcript, explicit statements only |
Integral-Analysis-day0-to-day<N>.md |
What's true now — accumulated substance + scores per thread and facet |
Integral-Feedback-day0-to-day<N>.md |
What to do about it — regressions, readiness, tomorrow's focus |
Start with the Integral Feedback; drill into the Integral Analysis when you want the evidence behind a score.
(day0-to- in those filenames is a fixed naming convention, not a claim that you had a day 0 — in basic mode there isn't one, and your first run produces Integral-Analysis-day0-to-day1.md. Day 0 is the empty origin the accumulation counts from; every day's file keeps the same name shape so the range it covers is readable at a glance.)
Basic mode keeps no cross-day logbook: no decision log, no risk register, no stakeholder tracking, no open-question IDs, and no Day-0 baseline — open items stay visible per facet inside the Integral Analysis (Still ambiguous), and readiness gaps are enumerated in the Integral Feedback. It also assesses no problem–solution fit and infers no acceptance criteria — those are advanced-only. That last cut buys a property worth naming: acceptance criteria are the record's one sanctioned inference, so without them every line of a basic-mode output traces to something a participant explicitly said — the record is inference-free. These are stated limitations of the mode, not bugs: a basic cycle cannot answer "what did we ever decide about X, and when?" — that trail is what the advanced mode's registers exist for. The cumulative Curve (the scores arc across the whole cycle) is also advanced-only, since it reads those registers and the Day-0 file.
If you outgrow basic mode: start a new cycle folder with mode: advanced and read SKILL.md — the full workflow is specified there.
| Path | Contents |
|---|---|
SKILL.md |
The skill itself — routing, sessions, principles (both modes) |
reference/ |
The format specifications: digest, Integral Analysis, Integral Feedback, Curve, registers, scoring rubrics, and the shared format rules (the version home) — each format file carries its own section-registry table |
runtime/ |
The output gates (check-digest.sh, check-ia.sh, check-if.sh) — run automatically, deterministic, no LLM |
agents/ |
The thread-weaver-integral analysis agent (install to .claude/agents/) |
examples/ |
The FleetCare demo — a runnable two-day basic-mode cycle, with reference outputs |
docs/ |
Reader aids: images this README embeds + glyph-legend.md (the emoji/symbol lookup) — no specification lives here |
The reference files are the source of truth for every output's structure; the gates verify each artifact against them mechanically at the end of its session.
I don't have Claude Code installed — where do I start? Follow the install instructions at claude.com/claude-code first (it's a one-time setup), then come back to the Install section above.
A session ended with a 🔴 and mentions check-digest.sh / check-ia.sh / check-if.sh — what do I do? These are the skill's automatic quality gates — small scripts that run themselves at the end of a session to check the file it just wrote. 🔴 means something's off (e.g. a required section is missing) and it will tell you what, in plain language, in the chat. Read that message and reply in the same session; it will fix and re-check. You never run these scripts yourself.
What's a "sub-agent"? A helper Claude Code spins up for a sub-task and closes when done — you'll see this mentioned for the Digests session, which starts one per transcript so they can work in parallel. It's internal machinery; you don't do anything differently because of it.
My transcripts don't come from a "meeting-capture tool" — can I still use this? Yes. Any .md (markdown — plain text) file works, as long as it has the transcript: true marker described in step 3. If you're pasting text from Zoom, Teams, or your own notes, just save it as a .md file and add that marker at the top.
The skill asked me to confirm my threads/codes in chat — is that normal? Yes, on the very first run only. It's a safety check so a typo in your CONFIG file doesn't silently propagate through the whole workshop. Just review what it shows and confirm.
Do I need to know markdown or YAML? Only enough to copy-paste the CONFIG template in step 2 and change the project name and table rows — you don't need to learn the format beyond that. The ----delimited block at the top of that file is called "frontmatter" — it's metadata the skill reads; leave its structure as-is and only edit the values.
Open an issue — whether it's a setup problem, a confusing step in this guide, or "would this work for my kind of workshop?". I'm happy to help you get your first cycle running, and every question about an unclear step is also a bug report against this README.