Build out a very simple, auditable, and local example of how to orchestrate a workflow to help me generate new blog post ideas from my Joplin markdown notes. I want to keep the workflow tightly designed so that I can audit and understand each step of the workflow. I also want this to be a local tool that does not require outside access. Eventually, I will want to start adding tools that my tool can use, but I want to limit the blast radius for any unintended consequences.

I want to keep the model grounded in the retrieved notes and will provide some simple sterring prompts like suggested topic areas or known “blog series” that I want to produce. This prompt should return ranked suggestions for blog titles, outlines and what notes where found to support content for those posts.

Starting with the basics

At a high level, an agent orchestration is just a program that decides:

1. what the model should see,
2. what tools it is allowed to use,
3. when to call those tools,
4. how to store memory or state,
5. and when to stop.

A workflow follows a known sequence: classify → retrieve documents → summarize → save result. An agent is more dynamic

The mental model

Think of a local agent as five layers stacked on top of each other.

Layer 1: the model

This is the brain-shaped text engine, but not the whole system. Locally, that might be Ollama serving a model on your machine. Ollama now supports both tool calling and structured outputs, which matters because it lets the model either request a tool or produce JSON that your code can trust more than free-form prose.

Layer 2: the tools

A tool is just a function the model is allowed to invoke. It could read a file, search your notes, create a calendar event, run a shell command, or query a SQLite database. The model itself does not “have access” to anything unless you explicitly give it a tool.

Layer 3: the orchestrator

This is the traffic cop. It decides what prompt goes to the model, whether tool calls are allowed, how results are fed back, how many retries are allowed, and when the process ends. LangGraph, for example, models this as a graph with shared state and nodes that read from and write to that state.

Layer 4: memory/state

This is where prior messages, tool outputs, task variables, or scratch data live. In LangGraph, short-term memory is treated as part of graph state and can be persisted with checkpoints.

Layer 5: the data boundary

This is the part that I care about most. Which files can be read? Which folders are exposed? Which tools can write? Which logs are saved? Since I distrust cloud models (especially for security and privacy), this boundary matters more than the cleverness of the prompts.

At this point, you might be thinking “why not just use OpenClaw if you want an assistant or LangChain to build your own tools?”

Simply put, I do not trust OpenClaw and I would rather start super small and deepen my own understanding of how these things work. I am an engineer after all.

Code vs Models

Writing my own orchestration will also let me dig in and let code do what code is good at and the model to what models are good at.

Code is good at:

• validation
• branching
• permissions
• retries
• schemas
• persistence
• deterministic transforms

Models are good at:

• interpretation
• summarization
• classification
• drafting
• ranking fuzzy options
• extracting meaning from messy text

The Project Structure

local_blog_agent/
├── data/
│   ├── joplin_export/
│   ├── processed/
│   │   ├── notes.jsonl
│   │   ├── chunks.jsonl
│   │   └── tfidf_index.pkl
│   └── outputs/
│       ├── blog_ideas.json
│       └── blog_ideas.md
├── src/
│   ├── config.py
│   ├── ingest.py
│   ├── chunking.py
│   ├── retrieve.py
│   ├── prompts.py
│   ├── llm.py
│   ├── schemas.py
│   ├── pipeline.py
│   └── cli.py
├── requirements.txt
└── README.md

All of my notes are written in markdown and while not all of them include frontmater some of them will which makes my output structure remaining consistent so much more important.

A simple schema like:

from pydantic import BaseModel, Field
from typing import List


class BlogIdea(BaseModel):
    rank: int
    title: str
    angle: str
    why_this_fits: str
    target_audience: str
    suggested_outline: List[str]
    source_chunks: List[str]
    confidence: float = Field(ge=0.0, le=1.0)


class BlogIdeasResponse(BaseModel):
    ideas: List[BlogIdea]

Will force my response into a known shape and can validate against this shape to fail loudly if the output is junk.

Where to go next

Once I have validated that this tool is useful and generating predictable suggestions for blog ideas with a given steering prompt, I would like to generate multiple search queries from a giving steering topic.

What do I want to say here, and how do I say it honestly?

1. The Temptation

When you’ve got AI helping out, it’s so easy to slip into things like:

• Overstating experience
• Inflating scope
• Smoothing rough edges into fiction

Especially when it comes to AI.

2. The Constraint I Chose

My official title is Principal Software Engineer.

But titles aren’t what matters to me. They don’t capture the impact or the real work I put in.

Target:

• Staff / Senior+ IC roles
• Developer productivity teams
• AI enablement spaces
• Possibly education-focused AI

Constraint:

Everything I include has to be true, defensible, and based on actual, shipped work.

3. From Hype to Systems Thinking

This shift wasn’t about lowering my ambitions.

It meant thinking differently about impact:

• Systems over features
• Leverage over activity
• Direction over claims

💬 Not:

“Built AI systems”

But:

“Improved systems where AI is becoming a multiplier”

4. Instead of One Resume… Two

I stopped chasing that one perfect version.

So I built two:

Conservative

• Tight edits
• Minimal expansion
• Lower narrative risk

Aggressive

• Stronger AI-forward framing
• Clearer directional intent
• Still grounded in the real work I’ve done

5. Why This Works

Because hiring isn’t binary.

Different companies optimize for different signals:

• Some reward precision
• Some reward trajectory
• Some reward narrative clarity

So instead of guessing what would resonate…

I started testing positioning.

6. The Mission Section

I added a new section:

AI in education as augmentation, not replacement.

This does two things:

1. Signals a commitment to long-term direction
2. Anchors my AI work in responsibility

7. Working With AI Without Losing the Plot

The most helpful thing AI did wasn’t write for me.

It was:

• Surfacing inconsistencies
• Stress-testing claims
• Generating structured alternatives

💡 AI is best used as a reviewer and amplifier
not a narrator of your experience

8. What Changed for Me

Before:

• Resume = static artifact
• Edit = one-shot decision

After:

• Resume = system with variants
• Edit = exploration space

Lessons Learned

1. How you frame your story is just as important as the metrics you’ve achieved.
2. Honesty outlasts hype, and real impact speaks for itself.
3. Exploring multiple variants is more useful than chasing a single ‘perfect’ resume.
4. AI works best as a collaborator, not a replacement.
5. Where you’re headed matters as much as what you’ve done.

What I’d Do Next

1. Add diff tooling between variants
2. Build a lightweight “resume lint” system
3. Create targeted versions for:
   • Dev productivity teams
   • Education AI companies
4. Start publishing small, real AI projects

Closing Thought

The hardest part wasn’t fixing the pipeline.

It was figuring out what story to tell once it actually worked.

And making sure that story stayed true to what I’d actually accomplished.

One bullet point included a percentage sign. In the PDF, however, the sentence just stopped.

It wasn’t truncated or wrapped—just gone.

That’s usually a smell.

1. The “It’s Just a Percent Sign” Bug

My first instinct was correct:

LaTeX treats % as a comment.

So, I escaped it, moved on, and thought I was done.

Except, I wasn’t done.

Escaping the percent sign kind of worked, but then the output started looking weird in other places.

That’s when it stopped being a simple formatting issue and revealed itself as a pipeline problem.

2. Follow the Pipeline, Not the Symptom

The resume wasn’t just a LaTeX file; it was the product of a pipeline:

3. The Real Bug: Escaping in the Wrong Order

The problem wasn’t whether the % symbol was escaped.

It was when backslashes were processed before percent signs, which meant:

• Already escaped sequences got escaped again
• Output became corrupted in subtle ways

Broken (old order)

escape_backslashes()
escape_percent()

Fixed (new order)

preserve_existing_escapes()
escape_percent()
escape_remaining_sequences()

Once I corrected the order:

• Percentages rendered correctly
• Text stopped disappearing
• Output stabilized

💡 If a formatting bug behaves inconsistently, it’s probably a transformation-order bug.

4. Then the Colors Broke

The output was technically correct, but visually wrong.

It was flatter, with less contrast—not the same resume.

5. Version Drift Is a Silent Killer

Same template (moderncv). Different result.

Cause:

• Dependency drift
• Theme defaults changed
• Color aliases resolved differently

The Fix: Pin Everything

\definecolor{color1}{HTML}{3873B3}
\definecolor{color2}{HTML}{737373}

6. One More Bug (Because Of Course)

The mission bullets no longer aligned with the rest of the layout.

Cause:

• Used \itemize
• which bypassed the moderncv layout system.

Fix:

\cvlistitem{...}

Alignment was instantly restored.

7. What This Actually Was

This entire process started as:

Why is one sentence broken?

But it became:

• Pipeline debugging
• Transformation correctness
• Dependency control
• Layout system alignment

Lessons Learned

1. Small bugs often point to system-level issues.
2. The order of transformations matters more than the transformations themselves.
3. Defaults are not stable contracts; they can change unexpectedly.
4. Layout systems demand semantic consistency.

Closing Thought

This wasn’t really about LaTeX.

The pipeline is a product. Treat it like one.

Up Next

In the next post, I’ll walk through what happened after the pipeline was fixed:

• Rewriting the resume for Staff-level roles
• Working with AI without over-claiming experience
• Creating multiple narrative variants intentionally

• define constraints
• stay disciplined
• iterate in small, testable steps

That all sounds nice.

But what did it actually look like?

This is the visual version of that process—the messy middle included.

Each screenshot maps to a specific rule change, not just a visual tweak.

1. The Starting Point (Systems Fighting Each Other)

At a glance, nothing looks obviously broken.

But everything is slightly off.

What was actually happening:

• content is left-aligned instead of centered
• no consistent container width
• multiple style systems competing

It looks fine… until you try to change anything.

2. The “Centered” Illusion (Debugging with a Centerline)

I added a simple centerline overlay to verify alignment.

That’s when the illusion broke.

What this revealed:

• the layout was not actually centered
• elements were visually “close enough,” but structurally wrong
• spacing drifted across sections

If you can’t prove it’s centered, it probably isn’t.

3. Mid-Refactor Reality (Progress… and New Problems)

At this stage:

• content was finally centered
• layout rules were starting to stabilize

…but the navigation was clearly off.

The breakage was useful: it proved the new layout model was actually taking control, and exposed the assumptions that had been hidden in older styles.

What changed:

• a real container model emerged
• spacing became more predictable

What broke:

• nav alignment
• header consistency

This is where most refactors fall apart.

4. The System Locks In (Everything Becomes Predictable)

Once the layout model was fully defined:

• max-width was consistent
• margins were intentional
• components aligned naturally

No more fighting the system.

The layout stopped being a collection of fixes and became a set of rules.

5. What Made This Work

These screenshots show the output.

They don’t show the most important part:

• constraints defined before changes
• small, surgical patches
• constant validation against real output

Validation happened at three levels: rendered output, spacing behavior by breakpoint, and contrast/accessibility checks.

Without that, this would have turned into:

“It looked better… until it didn’t.”

If you want to copy this process: define non-negotiables first, then only accept patches that preserve them.

Closing Thought

The goal wasn’t to make it look right.

The goal was to make it stay right.

And that only happened once the system was clear—both to me, and to the AI helping me implement it.

Clear constraints turned AI from a suggestion engine into a reliable implementation layer.

Refactoring a system with AI in the loop?

That can either be a superpower… or a fast track to chaos.

After working through a full layout and styling refactor on this blog, I started to notice a pattern—not just in what worked, but in what kept me from completely losing the thread halfway through.

This isn’t a post about “AI made this easy.”

It didn’t.

This is about how to work with AI deliberately so you don’t create something your future self hates.

1. The Trap: Letting AI Lead the Architecture

The easiest mistake to make is also the most tempting:

“Here’s my code. Improve it.”

AI will happily:

• rename things
• restructure files
• introduce new abstractions
• suggest patterns that look cleaner

And suddenly…

You’re no longer refactoring.

You’re rewriting—without a clear mental model of what changed.

That’s where things break down:

• styles drift
• layout assumptions conflict
• debugging becomes guesswork
• your “simple change” becomes a multi-hour spiral

2. The Shift: You Own the Model, AI Executes

The turning point for me was simple:

Stop asking AI what to do. Start telling it what you’ve already decided.

Before touching code, I had to answer:

• What is my layout model?
• Where is the source of truth for spacing and width?
• What is mobile-first actually enforcing here?
• What must not change?

Only after that did AI become useful.

Instead of:

“Fix my layout”

I moved to:

“Act as a CSS/layout debugger. Identify the current model, then propose the minimum changes required to center the reading canvas.”

That one constraint changed everything.

3. The Real Superpower: Constraint-Driven Iteration

AI is incredible at operating within constraints.

But you have to give it constraints.

The most effective loop I found looked like this:

Step 1: Snapshot Reality

• Current source files
• Generated output (in my case, Jekyll build)
• Screenshots of actual rendering

Step 2: Force Reconciliation

Ask AI to:

• reconcile HTML + CSS + output
• identify the actual layout system in play

Not what we think is happening.

What is happening.

Step 3: Demand Surgical Changes

Not:

“Refactor this”

But:

“Propose the minimum patch set required to achieve X”

Step 4: Apply Incrementally

• Patch 1–3 files
• Rebuild
• Validate visually
• Repeat

This prevented the classic AI failure mode:

Warning “Everything changed, and I don’t know why.”

What This Looked Like In Practice

In this blog refactor, constraints were not abstract. They were specific:

• keep semantic HTML
• go mobile-first
• move to a token-first theme model
• hit WCAG AA contrast in both light and dark modes

A few moments made the value of this process obvious:

• Theme drift prevention: We added a repeatable contrast check workflow instead of relying on visual guesses.

• UI regression recovery: Mobile nav looked better after a pass, but accidentally occluded page content when opened. Fixing it was straightforward because scope stayed tight: remove the global overlay, keep panel-level separation, re-test.

• Scope discipline: We intentionally deferred connect page changes to a separate pass instead of folding it into every other layout change. That kept the main refactor understandable and reviewable.

• Layout sanity over cleverness: We removed overlapping style assumptions, normalized spacing rules, and made behavior explicit by breakpoint.

None of that is flashy, but that is exactly the point. The trust in AI went up as the constraints got tighter, not looser.

3.5. The Execution Layer: Working Directly in the Code with Copilot

Everything above describes the thinking model.

But the execution layer matters just as much. This is where the feedback loop lives.

One of the biggest accelerators in this process was shifting into a workflow where AI could operate directly on the codebase, not just through chat.

Using Copilot with GPT-5.3 in VS Code changed the feedback loop in two important ways:

Planning Mode → Agent Mode

The flow became:

1. Planning Mode
   • Define constraints
   • Clarify intent
   • Break work into scoped changes
2. Agent Mode
   • Apply changes directly to the code
   • Navigate files automatically
   • Execute multi-step edits without losing context

This removed a major source of friction:

Warning Copy → paste → modify → re-run → repeat

Instead, iteration became:

Pro Tip Think → constrain → apply → validate

Why This Worked

The key difference wasn’t just speed.

It was context continuity.

Because the AI could:

• see the actual file structure
• follow imports and dependencies
• modify multiple files in one pass

…it stopped behaving like a suggestion engine and started behaving like a constrained executor.

The Important Caveat

This only worked because the constraints were already defined.

Without that, agent mode becomes dangerous very quickly:

• large, unfocused changes
• unintended side effects across files
• loss of architectural clarity

In other words:

Warning Agent mode amplifies your system.

If your thinking is clear, it accelerates you. If your thinking is fuzzy, it magnifies the chaos.

The Net Effect

This shift dramatically shortened the feedback cycle:

• faster iteration
• fewer context resets
• tighter alignment between intent and implementation

But it didn’t replace the core loop.

It just made it faster to execute the same disciplined loop.

The discipline still came first.

4. Maintainability Is the Only Metric That Matters

It’s easy to get something that looks right.

That’s not the goal.

The goal is:

Can I come back in 3 months and understand this in 30 seconds?

That forced a few principles:

• No overlapping layout systems (Water.css + Pico + custom overrides = pain)

• Semantic HTML first, styling second

• Single source of truth for layout width

• Kill cleverness early

If something felt “kind of magical,” it was probably a future bug.

5. AI Is a Force Multiplier for Discipline (Not a Replacement)

AI didn’t remove the need to think.

It made lack of thinking more dangerous.

When used well, it becomes:

• a second set of eyes
• a fast iteration engine
• a way to validate assumptions

When used poorly, it becomes:

• a chaos generator
• a source of silent complexity
• a confidence trap

6. What I’d Do Again (and What I Wouldn’t)

I would:

• Start with constraints before code
• Treat AI as a debugger, not a designer
• Work in small, validated patches
• Continuously compare source vs output

I would not:

• Accept large, multi-file rewrites blindly
• Mix design systems without a clear boundary
• Assume AI understands my intent without explicitly stating it

7. The Meta Takeaway

The most valuable shift wasn’t technical.

It was mental:

I stopped collaborating with AI like a peer, and started directing it like a system.

That’s when it became reliable.

What’s Next

I’m planning to document this process more visually:

• before/after layout diagrams
• CSS cascade breakdowns
• “what changed vs what I thought changed”

Because the real lesson here isn’t about CSS.

It’s about how to think clearly while moving fast with AI— whether that AI is in a chat window or directly modifying your code.

And that’s a skill that’s only going to matter more.

The early version was intentionally simple. I added Water.css, got a basic layout in place, and had pages rendering quickly. It worked. It was readable. It was also generic in exactly the way a first pass usually is.

Then the real work started.

The shift from “site exists” to “site has structure”

The first meaningful improvement was URL and content structure.

I wanted posts to live under a dedicated namespace instead of hanging off root-level routes, so I moved to a /posts/:title/ pattern. It seems small, but this is one of those decisions that quietly pays off later. Your URLs become more predictable, your content model is clearer, and your site starts to feel like an actual publication instead of a pile of pages.

From there, discovery became the next concern. I didn’t just want writing to exist, I wanted it to be browsable. Categories became the primary organizing system, and I initially explored manual category pages before switching to plugin-based generation for scale. Manual pages are fine at first; they become friction as soon as you stop having “just a few posts.”

That pivot was one of the bigger themes of this build: moving from “works now” to “still works after I publish 50 more posts.”

Homepage semantics, not just styling

Once structure was solid, I reworked the homepage to show a real post feed: latest entries, short summaries, semantic markup, and cleaner separation of concerns between content and layout.

I learned (again) that presentation logic dumped into markdown gets messy fast. Moving feed rendering into the layout gave me cleaner templates, better semantics, and fewer weird rendering edge cases.

This site stopped feeling like a static landing page and started behaving more like a blog.

Developer experience matters on a solo blog too

I spend enough time in code blocks that syntax highlighting quality was non-negotiable. So I integrated Rouge styles with both light and dark variants, and then documented lexer/language support so future me doesn’t have to rediscover what’s already available.

I also added styled markdown callouts for notes, warnings, and tips. This was one of those tiny quality-of-life upgrades that disproportionately improved readability. The first version looked too much like default blockquotes, so it got refined until callouts were visually distinct without feeling loud.

There’s a pattern here: almost nothing was “one and done.” Most things got better on the second or third pass.

Visual identity: the site finally got a face

The masthead was where the blog started to feel personal.

I added a home-only hero section with a gradient treatment and profile image, then refactored it to be config-driven instead of hardcoded. That gave me flexibility to adjust tone and messaging without touching layout code every time.

Navigation went through multiple iterations too. Fixed versus sticky behavior, mobile dropdown readability, spacing, contrast, active-state clarity. These weren’t dramatic redesigns. They were small, cumulative improvements that made the interface feel intentional.

The part no one posts screenshots of: production debugging

The hardest part wasn’t writing templates. It was making local and production behave the same.

At one point, the site looked right locally but wrong after deploy. The only way through was to stop guessing and compare generated artifacts directly: built HTML, compiled CSS, live output, and asset URLs.

That surfaced real issues:

• stale CSS from caching
• mobile viewport quirks caused by 100vw breakout techniques
• layout regressions introduced while fixing another responsive issue
• route-specific wrapper differences that affected spacing on posts vs home

Each fix was straightforward in isolation. Together, they were a good reminder that frontend systems fail at the seams, not usually in the obvious center of a component.

What this process actually changed

By the end, I didn’t just have a prettier theme. I had a blog foundation that is:

• structurally cleaner (URL and archive model)
• easier to extend (config-driven sections and plugin-backed archives)
• more readable (semantic feed, callouts, code styling)
• more stable across breakpoints and routes
• less fragile in production (cache strategy and artifact-level validation)

In other words: less “demo,” more “system.”

Final thought

I started with an empty Jekyll site and a CSS framework. I ended up with something that feels authored, not assembled.

Most of the value came from iteration, not from any single big feature. Small choices around structure, semantics, and debugging discipline compounded into a site I actually want to keep publishing on.

And honestly, that was the goal the whole time.

Bold move, I know.

There are already thousands (millions?) of engineers writing about code, architecture, and (most recently) AI. So why add another voice to the noise?

Because I think we’re missing the point.

1. Not Another “Look What I Built in 5 Minutes” Post

If you’ve been anywhere near tech content lately, you’ve seen it:

I vibe-coded this app in 20 minutes with AI.

Or

Look at this startup I built over a weekend.

Cool. Honestly, the tooling is incredible, but most of that content stops at the novelty.

What I’m interested in is something deeper:

What happens when AI is in the hands of an experienced engineer?

Not just someone prompting their way to a demo, but someone who understands systems, tradeoffs, debugging, performance, and long-term maintainability.

Someone who knows what should be built, not just what can be built.

That’s where things actually get interesting.

That’s what this blog is about.

2. Why Jekyll (Again)

Yes, I’m using Jekyll again.

Not because it’s trendy (it’s not), but because it’s comfortable. I work in Ruby every day, and there’s something nice about a tool that gets out of your way and lets you write.

#!/bin/bash
bundle exec jekyll serve

That’s it. No platform lock-in. No algorithm deciding if this post is worth showing to people.

Just files, version control, and a system I fully understand.

And importantly, it gives me flexibility.

Since I can completely control the layout, styles, and have been writing using markdown for years. I can quickly and easily generate code blocks with syntax highlighting (using Rogue) and also easily add callouts like this:

Note This is an informational note.

Pro Tip Share helpful advice here.

Warning Call out a potential issue.

Danger Use for critical alerts.

This isn’t just a place for code snippets or quick takes. It’s a space where I can:

• Write longer-form thoughts
• Explore ideas over time
• Revisit and refine older posts
• Actually own what I publish

3. Bringing the Past Forward

I’ve written a lot over the years—scattered across notes, repos, half-finished drafts, and probably a few places I’ve forgotten about.

Part of this reboot is pulling all of that forward.

Not as-is, but refined. Updated. Recontextualized.

Think of this as a living archive, not just a stream of new posts.

4. A Real Writing Cadence (Finally)

I’m not going to promise “one post a week” or anything rigid like that.

But I am committing to writing consistently.

Not just when something is shiny or new, but when something is worth thinking through.

Not noise. Signal. (I promise to limit these clichés)

5. What You Can Expect

This blog will focus on:

• The intersection of AI and experienced engineering
• Practical insights, not just demos
• Systems thinking in an AI-accelerated world
• The stuff that doesn’t fit into a tweet or a quick post

Sometimes that might include code:

def print_hi(name)
puts "Hi, #{name}"
end

print_hi('Tom')
#=> prints 'Hi, Tom' to STDOUT.

But more often, it’ll be about why the code matters, and what changes when the tools evolve.

Final Thought

The barrier to building has dropped dramatically.

That’s a good thing.

But the gap between building something and building something that lasts?

That gap might actually be getting wider.

Anyone can build faster now.

Fewer people are thinking deeper.

That’s the gap I want to explore.

If you’ve made it this far—thanks for reading.

Let’s see where this goes and build things that last.