Dev Knowledge System (Hermes)

English | 繁體中文

A three-part toolkit for AI-assisted development: pitfall logging, progress tracking, and multi-agent coordination. Design principle in one line: models fill in content, scripts own the structure, the filesystem is the memory hierarchy — every deterministic operation (numbering, indexing, locking, validation) is done by scripts, so behavior is identical across Fable / Sonnet / Haiku.

Full design and 16 Architecture Decision Records: docs/design/2026-07-05-knowledge-system-design.md (zh-TW)

Three-layer memory hierarchy

~/pitfalls-kb/                cross-project long-term memory — env/SDK/toolchain pitfalls
                              (its own git repo; follows YOU)
<project>/docs/               project long-term memory — committed, merge-safe (follows the project)
  ├── pitfalls/               one pitfall per file
  ├── progress/tasks/         one task per file; status is an append-only event log
  └── rules/PROMOTED.md       standing rules (referenced by the last line of CLAUDE.md)
.git/agent-coord/             live working memory — shared across worktrees, never committed

INDEX.md and ROADMAP.md are derived artifacts: gitignored, never hand-edited, regenerated any time via reindex / report.

---

What each skill does

pitfall-log — record & recall pitfalls

Solves "stepping into the same hole twice." Each entry has six sections: raw symptom (the grep entry point), environment versions, root cause, solution, dead ends (approaches that did NOT work — the most valuable part), and a one-line prevention rule.

Key mechanics:

• Two-phase capture: at solve time you spend 5 seconds on a one-line draft; the dream pass fills in the rest. Capture friction is the #1 killer of knowledge systems.
• Two storage tiers: root cause in project code → docs/pitfalls/; in runtime/SDK/OS → ~/pitfalls-kb/ (cross-project).
• Version lifecycle: a pitfall is a claim with a validity range (affects_versions / fixed_in), lazily re-verified at recall time against your current versions. Fixed entries change status but are never deleted — older projects still need them.
• Recurrence tracking: each re-hit appends a timestamped line; salience = frequency × recency decay (derived, never stored); the 🔥 section at the top of INDEX ranks repeat offenders.
• Dream pass (consolidate): a script scan produces a worklist (drafts to complete, stale entries to re-verify, archive candidates, promotion candidates, duplicate candidates, capture gaps); the model executes it item by item. Sleep-time memory consolidation, engineered.
• Institutionalization (promote / demote): pitfalls with hits ≥ 3 get proposed for the standing-rules file (human approval required, budget of 15, demotion proposed once the source is fixed). The rules file is @ref'd by the last line of CLAUDE.md, so the frozen constitution body stays prompt-cache-friendly.
• Secret scanning: validate blocks API-key/token patterns so credentials never enter the KB.

progress-track — task tracking

Solves "new session / different model / another worktree — where was I?" One file per task (script-assigned IDs T-00N), four statuses only (todo/doing/done/blocked).

Key mechanics:

• Append-only event log: every status change appends one line — time old→new (worktree) — reason — and never rewrites old lines. The reason is mandatory: it is where the chain of thought lands, so any model can reconstruct context by reading the log.
• Derived status: frontmatter is never overwritten; current status is computed from the latest log line — the merge-conflict surface across worktrees drops to zero.
• Generated ROADMAP: report regroups everything by status; neither humans nor models edit it by hand.

agent-coord — multi-agent coordination (blackboard + mailboxes)

Solves "multiple AI agents in different worktrees can't see each other before merge." Data lives in .git/agent-coord/ — all worktrees share the same .git, so it is visible to everyone and never touches a merge.

Key mechanics:

• Six-verb protocol: register (automatic via hook) / status (the global blackboard) / claim (atomic task lock via mkdir) / post (broadcast progress + heartbeat) / send + inbox (directed messages) / done (release + flush summary back to the task file).
• Heartbeat anti-deadlock: 15 minutes without a heartbeat marks an agent stale and its claims become takeable — a crashed agent can't lock a task forever.
• Concurrency safety: one-writer-per-file, O_APPEND single lines, mkdir atomicity; covered by a two-process race test.
• Solo, single-worktree work can ignore this skill entirely.

---

How to invoke (three coexisting ways)

1. Implicit triggering (the main path) — just work normally

Each SKILL.md states decidable trigger conditions, so the model activates them on its own:

You do	What happens automatically
Hand the model a bug	It recalls from both INDEX tiers / search before debugging
A bug takes more than two rounds to solve	A draft entry is recorded after the fix
"Start working on X"	Task created; status enters the event log
"How's progress?"	report, then answers from ROADMAP
Parallel worktrees	Hook auto-registers; tasks are claimed before work

2. Explicit invocation (guaranteed)

• Keywords: "記錄這個坑" (log this pitfall), "跑夢遊" (run the dream pass), "進度如何" (progress?)
• Slash commands: /pitfall-log, /progress-track, /agent-coord

3. Direct CLI (no model involved)

# Pitfalls
.claude/skills/pitfall-log/scripts/pitfall.sh draft "one line: symptom + fix"   # 5-second capture
.claude/skills/pitfall-log/scripts/pitfall.sh draft --global "…"                # env-tier pitfall
.claude/skills/pitfall-log/scripts/pitfall.sh search "error keywords"           # two-tier recall
.claude/skills/pitfall-log/scripts/pitfall.sh hit <id> "context of the re-hit"  # record recurrence
.claude/skills/pitfall-log/scripts/pitfall.sh consolidate                       # dream pass, Phase A
.claude/skills/pitfall-log/scripts/pitfall.sh promote <id>                      # promote to standing rule (after approval)
.claude/skills/pitfall-log/scripts/pitfall.sh rules                             # rule budget status

# Progress
.claude/skills/progress-track/scripts/track.sh add "task title"
.claude/skills/progress-track/scripts/track.sh update T-001 doing "starting OAuth callback"
.claude/skills/progress-track/scripts/track.sh report

# Coordination
.claude/skills/agent-coord/scripts/coord.sh status
.claude/skills/agent-coord/scripts/coord.sh claim T-001

# Tests
bash tests/run-tests.sh

---

Suggested daily rhythm

1. Develop normally; remember two phrases: "log this pitfall" after a nasty bug, and "run the dream pass" once a week.
2. You approve the promotion/demotion proposals in the dream worklist; scripts do the writing.
3. After two weeks of dogfooding, recalibrate the magic numbers with real data (hit threshold 3, stale 15 min, archive 180 days, rule budget 15 — all initial guesses; see design doc §9).

Want this in other projects?

Half the value of pitfall-log is cross-project (the global KB). Copy the skill to your personal tier to make it available everywhere:

cp -R .claude/skills/pitfall-log ~/.claude/skills/