The Vibe-Clock Drift Problem

Tasks sprint. Specs evolve. Shadowbook keeps them aligned.

The Vibe-Clock Drift Problem

I work on multiple features in parallel. Each has a spec. Each spec evolves—often faster than I can tell the code.

AI generates specs faster than I can track them. Tasks implement requirements that have already changed. The spec says “OAuth with Google AND Apple” but the code is still building Google-only auth.

I call this spec drift. Tasks sprint while specs evolve. The clock is ticking on both, but they’re not synchronized.

---

The Solution: Shadowbook

Shadowbook is a fork of Beads (a git-backed issue tracker) that adds spec intelligence—keeping specifications and work items synchronized.

ToolQuestion it answersBeadsWhat work needs doing?ShadowbookIs the work still aligned with the spec?

---

How It Works

1. Hash-Based Drift Detection

Shadowbook stores specs as files and tracks their SHA256 hashes. When a file’s hash changes, linked issues get flagged.

bd spec scan

● SPEC CHANGED: specs/login.md
  ↳ bd-a1b2 "Implement login" — spec updated, issue unaware

Find drifted issues:

bd list --spec-changed

Acknowledge after reviewing:

bd update bd-a1b2 --ack-spec

Key insight: Specs are files. Files have hashes. When hashes change, linked issues know.

---

2. Automatic Spec-to-Issue Linking

Not every issue starts with a --spec-id. Shadowbook suggests matches using Jaccard similarity on tokenized titles.

bd spec suggest bd-c3d4

Suggested specs for "Implement OAuth login":
  specs/auth/oauth.md     (82% match)
  specs/auth/sso.md       (45% match)

The algorithm:

• Tokenize titles into words

• Filter stopwords (”implement”, “add”, “feature”)

• Calculate overlap: |A ∩ B| / |A ∪ B|

• 80% match means 80% of meaningful words overlap

Bulk-link above a confidence threshold:

bd spec link --auto --threshold 0.7

---

3. Volatility Tracking

Some specs change weekly. Others haven’t moved in months. Shadowbook tracks change frequency:

bd spec volatility

specs/trading/signals.md    12 changes (last: 2 days ago)  ← high churn
specs/auth/login.md          1 change  (last: 45 days ago) ← stable

High-churn specs with open issues? That’s where drift hides.

---

4. Multi-Factor Auto-Compaction

Completed specs waste tokens. A 2000-token spec that’s done should become a 20-token summary.

Shadowbook scores specs for auto-compaction:

FactorWeightAll linked issues closed+40%Spec unchanged 30+ days+20%Code unmodified 45+ days+20%Marked SUPERSEDED+20%

Score ≥ 0.7? Safe to compact.

bd spec candidates        # Show candidates with scores
bd spec auto-compact      # Compact specs above threshold

Token savings (real codebase):

57 specs, ~4,941 lines = ~14,823 tokens to load

20 completed specs × ~2,000 tokens = 40,000 tokens wasted
After compaction: 20 summaries × ~20 tokens = 400 tokens

Savings: 39,600 tokens per session
Monthly (weekly reviews): 118,800+ tokens
Yearly: 1.4M+ tokens

---

5. Skills Manifest: Agent Drift Detection

Specs aren’t the only things that drift. AI agents load skills from multiple sources—Claude plugins, Codex superpowers, local customizations. When a skill changes, every agent using it should know.

Shadowbook generates a manifest.json tracking every skill:

{
  "name": "superpowers:test-driven-development",
  "source": "codex",
  "tier": "must-have",
  "sha256": "7dee67b4af6bdccc...",
  "bytes": 9867
}

When a skill’s hash changes, the manifest diffs. Your agents notice. Same principle as spec drift—applied to agent behavior itself.

---

Try It

# Install
go install github.com/anupamchugh/shadowbook/cmd/bd@latest

# Initialize
bd init && mkdir -p specs

# Scan for drift
bd spec scan

Repository: github.com/anupamchugh/shadowbook

---

Tasks sprint. Specs evolve. Shadowbook catches the drift.