docs+skills: add main UI/UX visual-truth PRD and skill links

2026-02-18 12:50:53 -08:00 · 2026-02-18 12:50:53 -08:00 · 14a50ad4ae
commit 14a50ad4ae
parent 1c36223e7f
289 changed files with 54463 additions and 0 deletions
--- a/.agents/skills/create-beads-orchestration/docs/memory-architecture.md
+++ b/.agents/skills/create-beads-orchestration/docs/memory-architecture.md
@ -0,0 +1,114 @@
+# Memory Architecture
+
+## Overview
+
+Beads orchestration includes a passive knowledge capture system. As agents work, their insights can be voluntarily recorded into a persistent knowledge base that grows across sessions.
+
+## How It Works
+
+```
+Agent runs bd comment BD-001 "LEARNED: ..."
+       |
+       v
+PostToolUse hook (memory-capture.sh) detects LEARNED: prefix
+       |
+       v
+Extracts structured entry into .beads/memory/knowledge.jsonl
+       |
+       v
+Next session: session-start.sh surfaces recent knowledge
+              Agents search when investigating unfamiliar code
+```
+
+## Write Path
+
+Agents write knowledge through the existing `bd comment` interface:
+
+| Prefix | Who writes | Purpose |
+|--------|-----------|---------|
+| `LEARNED:` | Any agent (voluntary) | Conventions, gotchas, patterns discovered during implementation |
+
+Example:
+```bash
+bd comment BD-001 "LEARNED: TaskGroup requires @Sendable closures in strict concurrency mode."
+```
+
+An async `PostToolUse` hook on the Bash tool intercepts these commands and extracts a structured JSONL entry. No changes to the beads CLI are required.
+
+## Storage Format
+
+`.beads/memory/knowledge.jsonl` -- one JSON object per line:
+
+```json
+{"key":"learned-taskgroup-requires-sendable-closures","type":"learned","content":"TaskGroup requires @Sendable closures in strict concurrency mode.","source":"supervisor","tags":["learned","async","concurrency"],"ts":1706360000,"bead":"BD-001"}
+```
+
+| Field | Description |
+|-------|-------------|
+| `key` | Auto-generated slug from type + first 60 chars of content |
+| `type` | `learned` |
+| `content` | The raw insight text |
+| `source` | `orchestrator` or `supervisor` (detected from CWD) |
+| `tags` | Auto-detected from content via keyword scan |
+| `ts` | Unix timestamp |
+| `bead` | The bead ID that produced this knowledge |
+
+Same key = latest entry wins (deduplication on read).
+
+## Read Path
+
+### Automatic (session start)
+
+`session-start.sh` displays the 5 most recent deduplicated entries when a new session begins:
+
+```
+## Recent Knowledge (12 entries)
+
+  [LEARN] MenuBarExtra popup closes on NSWindow activate. Use activates:false.  (supervisor)
+
+  Search: .beads/memory/recall.sh "keyword"
+```
+
+### On-demand (recall script)
+
+```bash
+.beads/memory/recall.sh "keyword"                  # Search by keyword
+.beads/memory/recall.sh "keyword" --type learned   # Filter by type
+.beads/memory/recall.sh --recent 10                # Show latest entries
+.beads/memory/recall.sh --stats                    # Entry counts
+.beads/memory/recall.sh "keyword" --all            # Include archived entries
+```
+
+## Voluntary Contribution
+
+Knowledge capture is opt-in. Agents are encouraged to log insights when they discover something worth remembering, but it is not enforced. The `SubagentStop` hook verifies worktree state, push status, and bead status — not knowledge contributions.
+
+Exempt: `worker-supervisor` (low-level tasks that don't produce architectural insight).
+
+## Rotation
+
+When `knowledge.jsonl` exceeds 1,000 lines, the oldest 500 are moved to `knowledge.archive.jsonl`. The archive is searchable via `recall.sh --all`.
+
+## File Layout
+
+```
+.beads/
+  memory/
+    knowledge.jsonl          # Active knowledge store
+    knowledge.archive.jsonl  # Rotated older entries
+    recall.sh                # On-demand search script
+.claude/
+  hooks/
+    memory-capture.sh        # PostToolUse async hook (captures entries)
+    validate-completion.sh   # SubagentStop hook (verifies work completion)
+    log-dispatch-prompt.sh   # PostToolUse async hook (logs dispatch prompts)
+    session-start.sh         # SessionStart hook (surfaces knowledge)
+```
+
+## Design Decisions
+
+- **JSONL over SQLite**: Simpler, append-only, human-readable, git-trackable
+- **grep + jq over embeddings**: Sufficient for project-scoped knowledge; no external dependencies
+- **Passive capture via hooks**: Zero friction -- agents use `bd comment` as they already do
+- **Voluntary contribution**: Knowledge base grows organically from genuine insights, not forced boilerplate
+- **Same key = latest wins**: No explicit update/close lifecycle; knowledge self-corrects over time