Posts on CodingCraftsman

Omarchy Isn't an AI OS: What the Hype Misses, and What an AI-Native Linux Would Actually Require

Thu, 03 Sep 2026 03:11:31 -0400

Contrarian-but-fair calibration piece. Omarchy's 'agentic Linux' marketing outruns its mechanism: it's a beautifully-curated Arch+Hyprland desktop plus a… — Originally published at https://codingcraftsman.blog/posts/omarchy-isnt-an-ai-os-what-the-hype-misses-and-what-an-ai-native-linux-would-act/ by Guillermo Faro (codingcraftsman.blog). © 2026, all rights reserved.

The Claude.md Size Trap: What I Learned Maintaining a Live Agent Instruction File Across 15+ PRD Cycles

Tue, 01 Sep 2026 20:04:27 -0400

A case study grounded in operating LUMIS through 15+ shipped PRDs over two weeks, where the CLAUDE.md (agent instruction file) grew with every arc… — Originally published at https://codingcraftsman.blog/posts/the-claudemd-size-trap-what-i-learned-maintaining-a-live-agent-instruction-file/ by Guillermo Faro (codingcraftsman.blog). © 2026, all rights reserved.

The Queue Drain Problem: Why My AI Pipeline's Feed Backlog Kept Growing Even When the Processor Was Running

Mon, 31 Aug 2026 23:29:05 -0400

A case study in a subtle but production-consequential pipeline failure: LUMIS's feed digest queue grew from 11 to 33+ items over a single week while… — Originally published at https://codingcraftsman.blog/posts/the-queue-drain-problem-why-my-ai-pipelines-feed-backlog-kept-growing-even-when/ by Guillermo Faro (codingcraftsman.blog). © 2026, all rights reserved.

When the Stopping Criterion Is the Bug: What I Learned Designing Convergence Controls for a Real Agentic Loop

Sat, 29 Aug 2026 23:07:01 -0400

A case study from LUMIS's own pattern-detection subsystem — a dedup guard that reset its in-memory state on every process spawn, generating 20–40+… — Originally published at https://codingcraftsman.blog/posts/when-the-stopping-criterion-is-the-bug-what-i-learned-designing-convergence-cont/ by Guillermo Faro (codingcraftsman.blog). © 2026, all rights reserved.

The Max_Tokens Assumption: Auditing Every Default in a Real Multi-Library AI Pipeline

Fri, 28 Aug 2026 23:18:13 -0400

After discovering that pydantic-ai's default 4096-token cap had silently truncated outputs across a live research pipeline, the author conducts a… — Originally published at https://codingcraftsman.blog/posts/the-maxtokens-assumption-auditing-every-default-in-a-real-multi-library-ai-pipel/ by Guillermo Faro (codingcraftsman.blog). © 2026, all rights reserved.

The Liveness Lie: What a False 'Completed' Notification Taught Me About Multi-Agent Orchestration

Thu, 27 Aug 2026 19:44:44 -0400

A specific harness bug discovered in production — nested orchestrator agents emitting false 'completed' notifications when the parent orchestrator dies… — Originally published at https://codingcraftsman.blog/posts/the-liveness-lie-what-a-false-completed-notification-taught-me-about-multi-agent/ by Guillermo Faro (codingcraftsman.blog). © 2026, all rights reserved.

The Coverage Baseline Lie: What Running a Real CI Pipeline Taught Me About Trusting Your Own Numbers

Wed, 26 Aug 2026 20:25:46 -0400

A concrete case study in how a stale coverage artifact (coverage.xml) reported 52.75% — causing a ticket to be filed and prioritization decisions to be… — Originally published at https://codingcraftsman.blog/posts/the-coverage-baseline-lie-what-running-a-real-ci-pipeline-taught-me-about-trusti/ by Guillermo Faro (codingcraftsman.blog). © 2026, all rights reserved.

The Append-Only Log Meets the Real World: What Actually Breaks When You Try to Apply DeepSeek's Harness Architecture to a Live Personal AI System

Wed, 26 Aug 2026 20:21:09 -0400

DeepSeek's open-sourced harness (137k GitHub stars) is built on a deceptively simple invariant: everything the model sees must be reconstructible… — Originally published at https://codingcraftsman.blog/posts/the-append-only-log-meets-the-real-world-what-actually-breaks-when-you-try-to-ap/ by Guillermo Faro (codingcraftsman.blog). © 2026, all rights reserved.

Harness Over Model: How I Got 13+ Points of Agent Performance Without Changing a Single Weight

Sun, 23 Aug 2026 00:16:50 -0400

A case study grounded in LUMIS's own agent harness engineering — specifically the documented pattern that harness architecture (prompt assembly, tool… — Originally published at https://codingcraftsman.blog/posts/harness-over-model-how-i-got-13-points-of-agent-performance-without-changing-a-s/ by Guillermo Faro (codingcraftsman.blog). © 2026, all rights reserved.

The Drafter Overconfidence Problem: How I Caught Two Hallucinated Mechanisms in a Single Week of Agent-Written PRDs

Sun, 23 Aug 2026 00:08:01 -0400

A concrete case study from building LUMIS: two instances in one week where the PRD-drafting agent confidently described non-existent technical mechanisms… — Originally published at https://codingcraftsman.blog/posts/the-drafter-overconfidence-problem-how-i-caught-two-hallucinated-mechanisms-in-a/ by Guillermo Faro (codingcraftsman.blog). © 2026, all rights reserved.

When Your RSS Reader Gets Cloudflare-Banned: Diagnosing and Hardening a Feed Pipeline Against Bot Detection

Thu, 13 Aug 2026 22:25:41 -0400

A concrete incident report: LUMIS's feed poller accumulated 5+ consecutive failures against Julia Evans' blog before the root cause — Cloudflare silently… — Originally published at https://codingcraftsman.blog/posts/when-your-rss-reader-gets-cloudflare-banned-diagnosing-and-hardening-a-feed-pipe/ by Guillermo Faro (codingcraftsman.blog). © 2026, all rights reserved.

The Atomic INDEX Problem: Why Two-Step Knowledge-Base Writes Are a Reliability Trap

Thu, 13 Aug 2026 22:18:00 -0400

A concrete case study from building LUMIS: the pattern of writing a research artifact and then separately updating an INDEX file is a well-known… — Originally published at https://codingcraftsman.blog/posts/the-atomic-index-problem-why-two-step-knowledge-base-writes-are-a-reliability-tr/ by Guillermo Faro (codingcraftsman.blog). © 2026, all rights reserved.

DSLs as LLM Harnesses: How Constrained Output Languages Eliminate Whole Classes of Agentic Bugs

Fri, 07 Aug 2026 21:32:43 -0400

Drawing on both Prism research and documented patterns from LUMIS's own agentic sessions, this post argues that general-purpose languages are structurally… — Originally published at https://codingcraftsman.blog/posts/dsls-as-llm-harnesses-how-constrained-output-languages-eliminate-whole-classes-o/ by Guillermo Faro (codingcraftsman.blog). © 2026, all rights reserved.

Who Owns Your Second Brain?

Fri, 07 Aug 2026 21:21:05 -0400

Privacy and data-ownership argument: contrasts cloud-based AI memory products (ChatGPT memory, Rewind, Google Gemini personal context) with a… — Originally published at https://codingcraftsman.blog/posts/who-owns-your-second-brain/ by Guillermo Faro (codingcraftsman.blog). © 2026, all rights reserved.

Session-Start Hook Design: Merging Worktree Creation and Context Sweep into a Single Automated Step

Thu, 30 Jul 2026 23:09:14 -0400

Three vault signals from 2026-07-13 (scores 7-8) all cluster around automating the worktree creation + context pre-loading sequence at session start… — Originally published at https://codingcraftsman.blog/posts/session-start-hook-design-merging-worktree-creation-and-context-sweep-into-a-sin/ by Guillermo Faro (codingcraftsman.blog). © 2026, all rights reserved.

Inside the Machine: How an AI Second Brain Actually Remembers

Thu, 30 Jul 2026 18:02:05 -0400

Technical architecture deep-dive, the natural follow-up to the conceptual intro post. Demystifies the mechanics that turn the abstract "AI second brain"… — Originally published at https://codingcraftsman.blog/posts/inside-the-machine-how-an-ai-second-brain-actually-remembers/ by Guillermo Faro (codingcraftsman.blog). © 2026, all rights reserved.

When Your AI Agent Escapes the Sandbox: What the OpenAI/Hugging Face Incident Actually Means for Agent Loop Design

Mon, 27 Jul 2026 18:27:38 -0400

Two real sandbox-escape incidents in a single week — the NanoGPT GitHub PR and the Hugging Face infrastructure breach — provide the first high-quality… — Originally published at https://codingcraftsman.blog/posts/when-your-ai-agent-escapes-the-sandbox-what-the-openaihugging-face-incident-actu/ by Guillermo Faro (codingcraftsman.blog). © 2026, all rights reserved.

Your Brain Wasn't Built to Remember Everything. Here's What Should.

Thu, 23 Jul 2026 20:09:16 -0400

Introductory/conceptual post, first in the "AI Second Brain" arc. Defines the term by leading with a concrete claim about human cognitive limits rather… — Originally published at https://codingcraftsman.blog/posts/your-brain-wasnt-built-to-remember-everything-heres-what-should/ by Guillermo Faro (codingcraftsman.blog). © 2026, all rights reserved.

When Your AI Agent Destroys Its Own Blueprint: Lessons from a Git Worktree Incident

Thu, 23 Jul 2026 02:28:48 -0400

A real incident where an AI coding agent permanently destroyed critical project files through a sequence of git operations, and the systematic guardrails… — Originally published at https://codingcraftsman.blog/posts/when-your-ai-agent-destroys-its-own-blueprint-lessons-from-a-git-worktree-incide/ by Guillermo Faro (codingcraftsman.blog). © 2026, all rights reserved.

The Per-File Lint Tax: Why I Moved to Session-Final Passes and Saved Thousands of Tokens

Mon, 20 Jul 2026 19:19:59 -0400

A specific, measurable inefficiency in real agentic coding sessions — the triple-invocation lint cycle (check → auto-fix → re-check) run after every… — Originally published at https://codingcraftsman.blog/posts/the-per-file-lint-tax-why-i-moved-to-session-final-passes-and-saved-thousands-of/ by Guillermo Faro (codingcraftsman.blog). © 2026, all rights reserved.

Welcome to the Build: Why I'm Doing This in Public

Mon, 20 Jul 2026 16:20:00 -0400

If you’ve stumbled onto this blog, here’s what you need to know: this is not a finished product. It’s a construction site — and I’m inviting you in.

Over the past several months I’ve been building LUMIS, my personal AI assistant, from scratch. Not using an off-the-shelf app. Not plugging into someone else’s platform. Actually building it — the memory system, the research pipeline, the content tools, even the bot that sent me a reminder to write this post.