buildlog 0.1.0__py3-none-any.whl → 0.3.0__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (27) hide show
  1. buildlog/cli.py +46 -23
  2. buildlog/confidence.py +311 -0
  3. buildlog/core/operations.py +11 -15
  4. buildlog/distill.py +3 -3
  5. buildlog/embeddings.py +108 -16
  6. buildlog/mcp/tools.py +4 -4
  7. buildlog/render/__init__.py +34 -11
  8. buildlog/render/claude_md.py +3 -24
  9. buildlog/render/settings_json.py +3 -23
  10. buildlog/render/skill.py +175 -0
  11. buildlog/render/tracking.py +43 -0
  12. buildlog/skills.py +229 -47
  13. buildlog/stats.py +7 -5
  14. {buildlog-0.1.0.data → buildlog-0.3.0.data}/data/share/buildlog/post_gen.py +11 -7
  15. buildlog-0.3.0.dist-info/METADATA +763 -0
  16. buildlog-0.3.0.dist-info/RECORD +30 -0
  17. buildlog-0.1.0.dist-info/METADATA +0 -664
  18. buildlog-0.1.0.dist-info/RECORD +0 -27
  19. {buildlog-0.1.0.data → buildlog-0.3.0.data}/data/share/buildlog/copier.yml +0 -0
  20. {buildlog-0.1.0.data → buildlog-0.3.0.data}/data/share/buildlog/template/buildlog/.gitkeep +0 -0
  21. {buildlog-0.1.0.data → buildlog-0.3.0.data}/data/share/buildlog/template/buildlog/2026-01-01-example.md +0 -0
  22. {buildlog-0.1.0.data → buildlog-0.3.0.data}/data/share/buildlog/template/buildlog/BUILDLOG_SYSTEM.md +0 -0
  23. {buildlog-0.1.0.data → buildlog-0.3.0.data}/data/share/buildlog/template/buildlog/_TEMPLATE.md +0 -0
  24. {buildlog-0.1.0.data → buildlog-0.3.0.data}/data/share/buildlog/template/buildlog/assets/.gitkeep +0 -0
  25. {buildlog-0.1.0.dist-info → buildlog-0.3.0.dist-info}/WHEEL +0 -0
  26. {buildlog-0.1.0.dist-info → buildlog-0.3.0.dist-info}/entry_points.txt +0 -0
  27. {buildlog-0.1.0.dist-info → buildlog-0.3.0.dist-info}/licenses/LICENSE +0 -0
@@ -0,0 +1,763 @@
1
+ Metadata-Version: 2.4
2
+ Name: buildlog
3
+ Version: 0.3.0
4
+ Summary: Engineering notebook for AI-assisted development
5
+ Project-URL: Homepage, https://github.com/Peleke/buildlog-template
6
+ Project-URL: Repository, https://github.com/Peleke/buildlog-template
7
+ Author: Peleke Sengstacke
8
+ License-Expression: MIT
9
+ License-File: LICENSE
10
+ Keywords: ai,buildlog,development,documentation,journal
11
+ Classifier: Development Status :: 4 - Beta
12
+ Classifier: Environment :: Console
13
+ Classifier: Intended Audience :: Developers
14
+ Classifier: License :: OSI Approved :: MIT License
15
+ Classifier: Programming Language :: Python :: 3
16
+ Classifier: Programming Language :: Python :: 3.10
17
+ Classifier: Programming Language :: Python :: 3.11
18
+ Classifier: Programming Language :: Python :: 3.12
19
+ Classifier: Programming Language :: Python :: 3.13
20
+ Classifier: Topic :: Documentation
21
+ Classifier: Topic :: Software Development :: Documentation
22
+ Requires-Python: >=3.10
23
+ Requires-Dist: click>=8.0.0
24
+ Requires-Dist: copier>=9.0.0
25
+ Requires-Dist: numpy>=1.21.0
26
+ Requires-Dist: pyyaml>=6.0.0
27
+ Provides-Extra: all
28
+ Requires-Dist: mcp>=1.0.0; extra == 'all'
29
+ Requires-Dist: openai>=1.0.0; extra == 'all'
30
+ Requires-Dist: sentence-transformers>=2.2.0; extra == 'all'
31
+ Provides-Extra: dev
32
+ Requires-Dist: black>=24.0.0; extra == 'dev'
33
+ Requires-Dist: flake8>=7.0.0; extra == 'dev'
34
+ Requires-Dist: isort>=5.13.0; extra == 'dev'
35
+ Requires-Dist: mypy>=1.8.0; extra == 'dev'
36
+ Requires-Dist: pre-commit>=3.6.0; extra == 'dev'
37
+ Requires-Dist: pytest-asyncio>=0.21.0; extra == 'dev'
38
+ Requires-Dist: pytest-cov>=4.0.0; extra == 'dev'
39
+ Requires-Dist: pytest>=7.0.0; extra == 'dev'
40
+ Requires-Dist: types-pyyaml>=6.0.0; extra == 'dev'
41
+ Provides-Extra: embeddings
42
+ Requires-Dist: sentence-transformers>=2.2.0; extra == 'embeddings'
43
+ Provides-Extra: mcp
44
+ Requires-Dist: mcp>=1.0.0; extra == 'mcp'
45
+ Provides-Extra: openai
46
+ Requires-Dist: openai>=1.0.0; extra == 'openai'
47
+ Description-Content-Type: text/markdown
48
+
49
+ <div align="center">
50
+
51
+ # buildlog
52
+
53
+ ### Engineering Notebook for AI-Assisted Development
54
+
55
+ [![PyPI](https://img.shields.io/pypi/v/buildlog?style=for-the-badge&logo=pypi&logoColor=white)](https://pypi.org/project/buildlog/)
56
+ [![Python](https://img.shields.io/pypi/pyversions/buildlog?style=for-the-badge&logo=python&logoColor=white)](https://python.org/)
57
+ [![CI](https://img.shields.io/github/actions/workflow/status/Peleke/buildlog-template/ci.yml?branch=main&style=for-the-badge&logo=github&label=CI)](https://github.com/Peleke/buildlog-template/actions/workflows/ci.yml)
58
+ [![Coverage](https://img.shields.io/codecov/c/github/Peleke/buildlog-template?style=for-the-badge&logo=codecov&logoColor=white)](https://codecov.io/gh/Peleke/buildlog-template)
59
+ [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg?style=for-the-badge)](https://opensource.org/licenses/MIT)
60
+
61
+ **Capture your work as publishable content. Include the fuckups.**
62
+
63
+ <img src="assets/hero-notebook.png" alt="buildlog - Engineering Notebook for AI-Assisted Development" width="800"/>
64
+
65
+ [Quick Start](#-quick-start) · [The Pipeline](#-the-pipeline) · [Commands](#-commands) · [Philosophy](#-philosophy)
66
+
67
+ ---
68
+
69
+ </div>
70
+
71
+ ## The Problem
72
+
73
+ You're pairing with AI on real work. Hours of debugging, wrong turns, "oh shit" moments, and hard-won insights—all vanishing into chat history the moment you close the tab.
74
+
75
+ Meanwhile, your AI agent makes the same mistakes on similar problems because it has no memory of what you learned together.
76
+
77
+ ## The Solution
78
+
79
+ **buildlog** captures the signal from AI-assisted development sessions and transforms it into:
80
+
81
+ 1. **Publishable content** - Each entry is a $500+ tutorial draft
82
+ 2. **Structured insights** - Categorized learnings ready for analysis
83
+ 3. **Agent rules** - Deduplicated, confidence-scored rules that improve AI behavior
84
+
85
+ ```mermaid
86
+ flowchart LR
87
+ A["Raw Sessions<br/>(ephemeral)"] --> B["Buildlog Entries<br/>(structured markdown)"]
88
+ B --> C["Distilled Insights<br/>(categorized patterns)"]
89
+ C --> D["Agent Rules<br/>(deduplicated + scored)"]
90
+ D --> E["CLAUDE.md<br/>settings.json<br/>Agent Skills"]
91
+
92
+ style A fill:#ff6b6b,color:#fff
93
+ style B fill:#4ecdc4,color:#fff
94
+ style C fill:#45b7d1,color:#fff
95
+ style D fill:#96ceb4,color:#fff
96
+ style E fill:#dda0dd,color:#fff
97
+ ```
98
+
99
+ ---
100
+
101
+ ## Key Concepts
102
+
103
+ | Term | What it means |
104
+ |------|---------------|
105
+ | **Entry** | A structured markdown file documenting one work session |
106
+ | **Insight** | A single learning extracted from an entry's Improvements section |
107
+ | **Pattern** | Raw insights grouped by category (architectural, workflow, etc.) |
108
+ | **Rule** | Deduplicated insight with stable ID, confidence score, and source tracking |
109
+ | **Agent Skill** | Rules promoted to `.claude/skills/` for on-demand loading by Claude |
110
+
111
+ ---
112
+
113
+ ## Features
114
+
115
+ ### Structured Capture
116
+ Templates with six required sections ensure you never forget to document the mistakes that teach the most.
117
+
118
+ ### Pattern Distillation
119
+ Extract categorized insights from all your entries into structured JSON/YAML for analysis.
120
+
121
+ ### Semantic Deduplication
122
+ "Run tests before commit" and "Always execute the test suite prior to committing" are the same insight. buildlog merges them.
123
+
124
+ ### Confidence Scoring
125
+ Rules are scored based on frequency and recency. High-confidence rules have been reinforced multiple times recently.
126
+
127
+ ### Multiple Promotion Targets
128
+ Promote rules to CLAUDE.md, settings.json, or **Anthropic Agent Skills** (`.claude/skills/`) for on-demand loading.
129
+
130
+ ### Pluggable Embeddings
131
+ Token-based similarity by default. Upgrade to sentence-transformers or OpenAI for semantic understanding.
132
+
133
+ ---
134
+
135
+ ## Quick Start
136
+
137
+ ```bash
138
+ # Install
139
+ pip install buildlog
140
+
141
+ # Initialize in your project
142
+ buildlog init
143
+
144
+ # Create an entry for today's work
145
+ buildlog new auth-api
146
+
147
+ # After a few entries, extract patterns
148
+ buildlog distill
149
+
150
+ # Generate deduplicated rules
151
+ buildlog skills
152
+ ```
153
+
154
+ ---
155
+
156
+ ## The Pipeline
157
+
158
+ buildlog is a three-stage pipeline that transforms ephemeral work into durable knowledge:
159
+
160
+ ```mermaid
161
+ flowchart TB
162
+ subgraph Stage1["Stage 1: Capture"]
163
+ A1["buildlog new slug"] --> A2["Edit markdown entry"]
164
+ A2 --> A3["Document: Goal, Journey,<br/>Tests, Code, Improvements"]
165
+ end
166
+
167
+ subgraph Stage2["Stage 2: Distill"]
168
+ B1["buildlog distill"] --> B2["Parse all entries"]
169
+ B2 --> B3["Extract Improvements sections"]
170
+ B3 --> B4["Group by category"]
171
+ end
172
+
173
+ subgraph Stage3["Stage 3: Promote"]
174
+ C1["buildlog skills"] --> C2["Deduplicate similar insights"]
175
+ C2 --> C3["Calculate confidence scores"]
176
+ C3 --> C4["Generate stable IDs"]
177
+ C4 --> C5["Promote to target"]
178
+ end
179
+
180
+ Stage1 --> Stage2 --> Stage3
181
+
182
+ C5 --> D1["CLAUDE.md"]
183
+ C5 --> D2["settings.json"]
184
+ C5 --> D3[".claude/skills/"]
185
+ ```
186
+
187
+ ### Stage 1: Capture (`buildlog new`)
188
+
189
+ Create structured entries as you work. Each entry has six sections:
190
+
191
+ | Section | Purpose |
192
+ |---------|---------|
193
+ | **The Goal** | What you're building and why |
194
+ | **What We Built** | Architecture diagram, components |
195
+ | **The Journey** | Chronological narrative *including mistakes* |
196
+ | **Test Results** | Actual commands, actual outputs |
197
+ | **Code Samples** | Key snippets with context |
198
+ | **Improvements** | Categorized learnings for next time |
199
+
200
+ The **Improvements** section is structured for machine extraction:
201
+
202
+ ```markdown
203
+ ### Architectural
204
+ - Always validate inputs at the boundary, not conditionally
205
+ - Use frozen dataclasses for immutable data containers
206
+
207
+ ### Workflow
208
+ - Run the test suite after EVERY code change, not just at the end
209
+ - Write the integration test first to clarify the API contract
210
+
211
+ ### Tool Usage
212
+ - The `patch` context manager for date mocking is cleaner than fixtures
213
+ - Use `jwt.io` to decode tokens instead of console.log
214
+
215
+ ### Domain Knowledge
216
+ - `datetime.utcnow()` is deprecated in Python 3.12+
217
+ - Supabase storage returns 400, not 404, for missing files
218
+ ```
219
+
220
+ ### Stage 2: Distill (`buildlog distill`)
221
+
222
+ Extract all insights across entries into structured data:
223
+
224
+ ```bash
225
+ buildlog distill # JSON to stdout
226
+ buildlog distill -o patterns.yaml # Write to file
227
+ buildlog distill --since 2026-01-01 # Filter by date
228
+ buildlog distill --category workflow # Filter by category
229
+ ```
230
+
231
+ Output:
232
+ ```json
233
+ {
234
+ "patterns": {
235
+ "architectural": [
236
+ {"insight": "Always validate inputs at boundary...", "source": "2026-01-16-auth.md"}
237
+ ],
238
+ "workflow": [...],
239
+ "tool_usage": [...],
240
+ "domain_knowledge": [...]
241
+ },
242
+ "statistics": {
243
+ "total_patterns": 47,
244
+ "by_category": {"architectural": 12, "workflow": 15, ...}
245
+ }
246
+ }
247
+ ```
248
+
249
+ ### Stage 3: Generate Rules (`buildlog skills`)
250
+
251
+ Transform raw patterns into deduplicated, scored rules:
252
+
253
+ ```bash
254
+ buildlog skills # YAML to stdout
255
+ buildlog skills -o rules.yml # Write to file
256
+ buildlog skills --format markdown # For CLAUDE.md injection
257
+ buildlog skills --min-frequency 2 # Only repeated patterns
258
+ buildlog skills --embeddings openai # Semantic deduplication
259
+ ```
260
+
261
+ Output:
262
+ ```yaml
263
+ generated_at: '2026-01-16T12:00:00Z'
264
+ source_entries: 23
265
+ total_skills: 31
266
+ skills:
267
+ architectural:
268
+ - id: arch-b0fcb62a1e
269
+ rule: Always validate inputs at the boundary, not conditionally
270
+ frequency: 4
271
+ confidence: high
272
+ sources: [auth.md, api.md, validation.md, forms.md]
273
+ tags: [api, error]
274
+ - id: arch-0cda924aeb
275
+ rule: Frozen dataclasses should be the default for data containers
276
+ frequency: 2
277
+ confidence: medium
278
+ sources: [models.md, dto.md]
279
+ tags: [python]
280
+ ```
281
+
282
+ ---
283
+
284
+ ## Patterns vs Rules
285
+
286
+ **Patterns** are raw extractions—every insight from every entry, exactly as written.
287
+
288
+ **Rules** are processed patterns with:
289
+
290
+ | Property | Description |
291
+ |----------|-------------|
292
+ | **Stable ID** | Same rule always gets same ID (SHA-256 based) |
293
+ | **Deduplication** | Similar insights merged, frequency tracked |
294
+ | **Confidence** | high/medium/low based on frequency + recency |
295
+ | **Sources** | Which entries contributed to this rule |
296
+ | **Tags** | Auto-extracted technology/concept keywords |
297
+
298
+ ### Deduplication in Action
299
+
300
+ Raw patterns from different entries:
301
+ ```
302
+ - "Run tests before committing"
303
+ - "Always run the test suite before commit"
304
+ - "Execute tests prior to committing code"
305
+ ```
306
+
307
+ After deduplication → **1 rule** with `frequency: 3`:
308
+ ```yaml
309
+ - id: wf-96f12966f1
310
+ rule: Run tests before committing
311
+ frequency: 3
312
+ confidence: high
313
+ ```
314
+
315
+ ---
316
+
317
+ ## Promotion Targets
318
+
319
+ Rules can be promoted to different targets for agent consumption:
320
+
321
+ ```mermaid
322
+ flowchart LR
323
+ R["Rules<br/>(buildlog_status)"] --> T1["CLAUDE.md<br/>(append)"]
324
+ R --> T2["settings.json<br/>(merge)"]
325
+ R --> T3[".claude/skills/<br/>(Agent Skill)"]
326
+
327
+ T1 --> A1["Always loaded<br/>in context"]
328
+ T2 --> A2["Project settings<br/>for Claude Code"]
329
+ T3 --> A3["On-demand loading<br/>saves context"]
330
+
331
+ style T3 fill:#96ceb4,color:#fff
332
+ ```
333
+
334
+ | Target | File | When to Use |
335
+ |--------|------|-------------|
336
+ | `claude_md` | `CLAUDE.md` | Rules always in context (default) |
337
+ | `settings_json` | `.claude/settings.json` | Project-level Claude Code settings |
338
+ | `skill` | `.claude/skills/buildlog-learned/SKILL.md` | **On-demand loading** - rules load only when relevant |
339
+
340
+ ### Anthropic Agent Skills (New!)
341
+
342
+ The `skill` target creates an [Anthropic Agent Skill](https://docs.anthropic.com/en/docs/claude-code/skills) that Claude loads on-demand:
343
+
344
+ ```bash
345
+ # Via MCP tool
346
+ buildlog_promote(skill_ids=["arch-123", "wf-456"], target="skill")
347
+ ```
348
+
349
+ Creates `.claude/skills/buildlog-learned/SKILL.md`:
350
+
351
+ ```markdown
352
+ ---
353
+ name: buildlog-learned
354
+ description: Project-specific patterns learned from development history.
355
+ Use when writing code, making architectural decisions, reviewing PRs,
356
+ or ensuring consistency. Contains 12 rules across Architectural, Workflow.
357
+ ---
358
+
359
+ # Learned Patterns
360
+
361
+ *12 rules extracted from buildlog entries on 2026-01-16*
362
+
363
+ ## Must Follow (High Confidence)
364
+
365
+ These patterns have been reinforced multiple times.
366
+
367
+ ### Architectural
368
+ - Always validate inputs at the boundary
369
+ - Use dependency injection for testability
370
+
371
+ ### Workflow
372
+ - Run tests after EVERY code change
373
+
374
+ ## Should Consider (Medium Confidence)
375
+
376
+ These patterns appear frequently but may have exceptions.
377
+
378
+ ### Tool Usage
379
+ - Prefer `patch` context manager for date mocking
380
+ ```
381
+
382
+ **Why Agent Skills?**
383
+ - **On-demand loading** - Rules only load when Claude determines they're relevant
384
+ - **Saves context** - Not always in context like CLAUDE.md
385
+ - **Progressive disclosure** - Claude asks before loading the full skill
386
+
387
+ ### Live Usage Scenario
388
+
389
+ Here's how your learned rules actually get used:
390
+
391
+ ```
392
+ ┌─────────────────────────────────────────────────────────────────┐
393
+ │ You: "Review this authentication endpoint I wrote" │
394
+ └─────────────────────────────────────────────────────────────────┘
395
+
396
+
397
+ ┌─────────────────────────────────────────────────────────────────┐
398
+ │ Claude sees: "authentication" + "review" + "endpoint" │
399
+ │ │
400
+ │ Checks skill description: │
401
+ │ "Use when writing code, making architectural decisions, │
402
+ │ reviewing PRs, or ensuring consistency..." │
403
+ │ │
404
+ │ Match! Loads .claude/skills/buildlog-learned/SKILL.md │
405
+ └─────────────────────────────────────────────────────────────────┘
406
+
407
+
408
+ ┌─────────────────────────────────────────────────────────────────┐
409
+ │ Claude now has access to YOUR learned rules: │
410
+ │ │
411
+ │ Must Follow: │
412
+ │ - Password hashing belongs in User model, not route handler │
413
+ │ - Always validate inputs at the boundary │
414
+ │ │
415
+ │ Worth Knowing: │
416
+ │ - bcrypt.compare() arg order is (plaintext, hash) │
417
+ │ - JWT expiry is in seconds, not milliseconds │
418
+ └─────────────────────────────────────────────────────────────────┘
419
+
420
+
421
+ ┌─────────────────────────────────────────────────────────────────┐
422
+ │ Claude: "I notice the password hashing is in your route │
423
+ │ handler. Based on patterns from your buildlog, this should │
424
+ │ be a pre-save hook in the User model instead. │
425
+ │ │
426
+ │ Also, I see bcrypt.compare(hash, password) - the argument │
427
+ │ order should be (plaintext, hash). This has tripped you up │
428
+ │ before." │
429
+ └─────────────────────────────────────────────────────────────────┘
430
+ ```
431
+
432
+ Your past mistakes now prevent future ones—automatically.
433
+
434
+ ---
435
+
436
+ ## Embedding Backends
437
+
438
+ Deduplication uses text similarity. Choose your backend:
439
+
440
+ | Backend | Install | Use Case |
441
+ |---------|---------|----------|
442
+ | `token` (default) | Built-in | Fast, free, good for obvious duplicates |
443
+ | `sentence-transformers` | `pip install buildlog[embeddings]` | Local semantic similarity, no API calls |
444
+ | `openai` | `pip install buildlog[openai]` | Best quality, requires API key |
445
+
446
+ ```bash
447
+ # Token-based (default) - catches "run tests" ≈ "run testing"
448
+ buildlog skills
449
+
450
+ # Semantic - catches "use Redis for caching" ≈ "cache data in Redis"
451
+ buildlog skills --embeddings sentence-transformers
452
+
453
+ # OpenAI - best quality semantic matching
454
+ export OPENAI_API_KEY=...
455
+ buildlog skills --embeddings openai
456
+ ```
457
+
458
+ ### Comparison
459
+
460
+ | Input | Token | OpenAI |
461
+ |-------|:-----:|:------:|
462
+ | "Run tests before commit" ≈ "Run testing before committing" | Merged | Merged |
463
+ | "Use Redis for caching" ≈ "Cache data in Redis" | Separate | Merged |
464
+
465
+ ---
466
+
467
+ ## Practical Usage
468
+
469
+ ### 1. Inject Rules into CLAUDE.md
470
+
471
+ ```bash
472
+ buildlog skills --format markdown >> CLAUDE.md
473
+ ```
474
+
475
+ Your AI agent now has access to every lesson you've learned:
476
+
477
+ ```markdown
478
+ ## Learned Rules
479
+
480
+ Based on 23 buildlog entries, 31 actionable rules have emerged:
481
+
482
+ ### Architectural (8 rules)
483
+ - Always validate inputs at the boundary (seen 4x)
484
+ - Use frozen dataclasses for data containers (seen 2x)
485
+
486
+ ### Workflow (12 rules)
487
+ - Run tests after EVERY code change (seen 5x)
488
+ ...
489
+ ```
490
+
491
+ ### 2. Create an Agent Skill
492
+
493
+ For on-demand loading instead of always-in-context:
494
+
495
+ ```bash
496
+ # Via CLI (coming soon)
497
+ buildlog promote --target skill
498
+
499
+ # Via MCP
500
+ buildlog_promote(skill_ids=["arch-123"], target="skill")
501
+ ```
502
+
503
+ ### 3. Track Rule Evolution
504
+
505
+ Rules have stable IDs. Track which are reinforced over time:
506
+
507
+ ```bash
508
+ # This week's new rules
509
+ buildlog skills --since 2026-01-10 -o this-week.yml
510
+
511
+ # Compare to baseline
512
+ diff baseline.yml this-week.yml
513
+ ```
514
+
515
+ ### 4. Find Your Blind Spots
516
+
517
+ ```bash
518
+ buildlog stats --detailed
519
+ ```
520
+
521
+ ```
522
+ Buildlog Statistics
523
+
524
+ Entries: 23 total
525
+ Coverage: 87% with improvements
526
+
527
+ Category Breakdown:
528
+ architectural: 12 insights (26%)
529
+ workflow: 15 insights (33%)
530
+ tool_usage: 8 insights (17%)
531
+ domain_knowledge: 11 insights (24%)
532
+
533
+ Warnings:
534
+ - 3 entries have empty Improvements sections
535
+ ```
536
+
537
+ ---
538
+
539
+ ## Commands
540
+
541
+ | Command | Description |
542
+ |---------|-------------|
543
+ | `buildlog init` | Initialize in current directory |
544
+ | `buildlog new <slug>` | Create entry for today |
545
+ | `buildlog new <slug> --date 2026-01-15` | Create entry for specific date |
546
+ | `buildlog list` | List all entries |
547
+ | `buildlog distill` | Extract patterns from all entries |
548
+ | `buildlog stats` | Show statistics and analytics |
549
+ | `buildlog skills` | Generate deduplicated rules |
550
+ | `buildlog update` | Update templates to latest |
551
+
552
+ ### Skills Options
553
+
554
+ ```bash
555
+ --output, -o PATH # Write to file instead of stdout
556
+ --format [yaml|json|markdown] # Output format (default: yaml)
557
+ --min-frequency N # Only rules seen N+ times
558
+ --since YYYY-MM-DD # Only entries from this date
559
+ --embeddings [token|sentence-transformers|openai] # Similarity backend
560
+ ```
561
+
562
+ ---
563
+
564
+ ## Architecture
565
+
566
+ ```mermaid
567
+ flowchart TB
568
+ subgraph CLI["CLI Layer"]
569
+ cli["cli.py"]
570
+ end
571
+
572
+ subgraph Core["Core Logic"]
573
+ distill["distill.py<br/>Pattern extraction"]
574
+ skills["skills.py<br/>Deduplication + scoring"]
575
+ stats["stats.py<br/>Analytics"]
576
+ embeddings["embeddings.py<br/>Similarity backends"]
577
+ ops["core/operations.py<br/>status, promote, reject"]
578
+ end
579
+
580
+ subgraph Render["Render Adapters"]
581
+ claude_md["claude_md.py"]
582
+ settings_json["settings_json.py"]
583
+ skill_render["skill.py"]
584
+ end
585
+
586
+ subgraph MCP["MCP Server"]
587
+ server["server.py"]
588
+ tools["tools.py"]
589
+ end
590
+
591
+ cli --> distill
592
+ cli --> skills
593
+ cli --> stats
594
+
595
+ skills --> embeddings
596
+ skills --> distill
597
+
598
+ ops --> skills
599
+ ops --> Render
600
+
601
+ tools --> ops
602
+ server --> tools
603
+ ```
604
+
605
+ ### Data Flow
606
+
607
+ ```mermaid
608
+ flowchart LR
609
+ MD["buildlog/*.md"] --> Parse["Parse markdown"]
610
+ Parse --> Extract["Extract Improvements"]
611
+ Extract --> Distill["distill_all()"]
612
+ Distill --> Patterns["Patterns by category"]
613
+ Patterns --> Dedup["Deduplicate"]
614
+ Dedup --> Score["Calculate confidence"]
615
+ Score --> Rules["Rules with IDs"]
616
+ Rules --> Format["Format output"]
617
+ Format --> Out["YAML / JSON / Markdown / Agent Skill"]
618
+ ```
619
+
620
+ ---
621
+
622
+ ## Installation Options
623
+
624
+ ```bash
625
+ # Basic install
626
+ pip install buildlog
627
+
628
+ # With local semantic embeddings (offline)
629
+ pip install buildlog[embeddings]
630
+
631
+ # With OpenAI embeddings
632
+ pip install buildlog[openai]
633
+
634
+ # Everything
635
+ pip install buildlog[all]
636
+
637
+ # Development
638
+ pip install buildlog[dev]
639
+
640
+ # With MCP server for Claude Code integration
641
+ pip install buildlog[mcp]
642
+ ```
643
+
644
+ ---
645
+
646
+ ## MCP Server (Claude Code Integration)
647
+
648
+ The MCP server lets Claude Code interact with your buildlog rules directly. Your agent can review learned patterns, promote them to rules, or reject false positives—all through natural conversation.
649
+
650
+ ### Setup for Claude Code CLI
651
+
652
+ 1. Install with MCP support:
653
+ ```bash
654
+ pip install buildlog[mcp]
655
+ # or with uv
656
+ uv pip install buildlog[mcp]
657
+ ```
658
+
659
+ 2. Add to your Claude Code settings (`~/.claude/settings.json`):
660
+ ```json
661
+ {
662
+ "mcpServers": {
663
+ "buildlog": {
664
+ "command": "buildlog-mcp",
665
+ "args": []
666
+ }
667
+ }
668
+ }
669
+ ```
670
+
671
+ 3. Start a new Claude Code session. The buildlog tools will be available.
672
+
673
+ ### Available Tools
674
+
675
+ | Tool | Description |
676
+ |------|-------------|
677
+ | `buildlog_status` | Get rules grouped by category with confidence scores |
678
+ | `buildlog_promote` | Write rules to CLAUDE.md, settings.json, or **Agent Skills** |
679
+ | `buildlog_reject` | Mark rules to exclude from future suggestions |
680
+ | `buildlog_diff` | Show rules pending review (not yet promoted/rejected) |
681
+
682
+ ### Promotion Targets via MCP
683
+
684
+ ```python
685
+ # Append to CLAUDE.md (default)
686
+ buildlog_promote(skill_ids=["arch-123"], target="claude_md")
687
+
688
+ # Merge into settings.json
689
+ buildlog_promote(skill_ids=["arch-123"], target="settings_json")
690
+
691
+ # Create Anthropic Agent Skill (NEW!)
692
+ buildlog_promote(skill_ids=["arch-123"], target="skill")
693
+ ```
694
+
695
+ ### Example Conversation
696
+
697
+ ```
698
+ You: What patterns have I learned?
699
+
700
+ Claude: [calls buildlog_status]
701
+ Based on 23 buildlog entries, you have 31 rules:
702
+
703
+ High confidence (ready to promote):
704
+ - arch-b0fcb62a1e: "Always validate inputs at the boundary"
705
+ - wf-96f12966f1: "Run tests before committing"
706
+
707
+ Would you like me to add these to your CLAUDE.md or create an Agent Skill?
708
+
709
+ You: Create an Agent Skill so they load on-demand.
710
+
711
+ Claude: [calls buildlog_promote with target="skill"]
712
+ Created skill at .claude/skills/buildlog-learned/SKILL.md
713
+
714
+ This skill will load on-demand when relevant to your work,
715
+ saving context for when you need it most.
716
+ ```
717
+
718
+ ---
719
+
720
+ ## Philosophy
721
+
722
+ ### 1. Write Fast, Not Pretty
723
+ Refrigerator to-do list energy. Get it down before you forget.
724
+
725
+ ### 2. Never Delete Mistakes
726
+ Wrong turns are the most valuable content. They're what makes tutorials actually useful.
727
+
728
+ ### 3. Include the Journey
729
+ "We tried X, it failed because Y, so we did Z" > "We did Z"
730
+
731
+ ### 4. Capture Improvements
732
+ Concrete learnings, not vague observations. "Always validate at boundary" > "validation is important"
733
+
734
+ ### 5. Quality Bar
735
+ Each entry should be publishable as a **$500+ tutorial**. Real error messages. Honest about what didn't work. Code that runs.
736
+
737
+ ---
738
+
739
+ ## Contributing
740
+
741
+ 1. Fork the repository
742
+ 2. Create a feature branch (`git checkout -b feature/amazing`)
743
+ 3. Commit your changes (`git commit -m 'Add amazing feature'`)
744
+ 4. Push to the branch (`git push origin feature/amazing`)
745
+ 5. Open a Pull Request
746
+
747
+ ---
748
+
749
+ ## License
750
+
751
+ MIT License — see [LICENSE](./LICENSE) for details.
752
+
753
+ ---
754
+
755
+ <div align="center">
756
+
757
+ **Your AI pair programmer should learn from your mistakes.**
758
+
759
+ **buildlog makes that possible.**
760
+
761
+ [Back to top](#buildlog)
762
+
763
+ </div>